Imported from rogerchappel/branchbrief (AGENTS.md). Install upstream with npx skills add rogerchappel/branchbrief. Copyright stays with the author.

Repository Agent Guide

Version: 2026-04-28

Purpose

This repository exists to build branchbrief: a local-first CLI and GitHub Action that turns branch state into a reviewable, auditable brief for humans and AI reviewers.

Repository Type

Current type:

community OSS

Default Mode

Work on a branch unless explicitly told otherwise.

Use atomic commits.

Keep PRs reviewable.

Verify before completion.

Return a review pack.

Do not merge without explicit human approval.

Repo Layout

• README.md - project overview
• docs/PRD.md - product requirements and roadmap
• branchbrief/ - future CLI implementation package
• .github/workflows/ - future CI and GitHub Action workflows
• tests/ - future automated tests
• examples/ - future example outputs and fixtures

Commands

Install:

# No package install command exists yet.

Test:

# No automated test command exists yet.

Lint:

# No lint command exists yet.

Typecheck:

# No typecheck command exists yet.

Build:

# No build command exists yet.

Smoke test:

git diff --check

Work Policy

Before editing, report:

1. objective
2. expected blast radius
3. files likely to change
4. commit plan
5. verification plan
6. risk level

Then:

1. branch from latest default branch
2. make the smallest coherent change
3. review git status
4. review git diff
5. stage only intended files
6. run the smallest relevant verification
7. commit atomically
8. rebase on latest default branch before PR
9. open a focused PR
10. return a review pack

Commit Policy

Use Conventional Commits.

One commit equals one reviewable intent.

No commit may change more than 3 files unless a maintainer explicitly approves before the commit.

If a task touches more than 3 files, split the work before committing.

Do not spread many file changes across a few broad commits.

Scaffold, generated output, lockfile-only changes, and mechanical renames are still over-3-file exceptions only with explicit maintainer approval.

Split commits when the work introduces independently reviewable parts, such as:

• public contracts or types
• implementation
• tests
• examples or fixtures
• documentation
• generated artifacts
• CI/config changes

Keep them together only when splitting would create artificial commits that cannot be understood or verified independently.

Tests are separate reviewable intents. Use one test intent per commit, and separate unrelated unit, regression, fixture, and smoke tests into separate commits.

Allowed commit types:

• feat: user-visible capability
• fix: bug fix
• test: tests only
• docs: documentation only
• refactor: internal change with no behaviour change
• ci: CI/build/release workflow
• chore: repo hygiene
• perf: performance improvement
• types: type-only change

Do not mix:

• implementation and unrelated docs
• tests for one feature with implementation of another
• dependency bumps and behaviour changes
• formatting-only changes and logic changes
• generated files and unrelated hand-written code
• CI changes and application behaviour changes

Prefer 3 clean commits over 1 mixed commit.

Prefer 1 clean commit over 5 artificial commits.

PR Policy

Rebase on latest main or the repository default branch before opening a PR.

One PR equals one reviewable intent.

Every delegated agent or workstream owns one branch and submits one PR. This is a hard line.

Do not put several agents' work on one shared branch unless explicitly requested.

Final integration PRs contain only integration glue, conflict resolution, connecting docs, and end-to-end verification updates.

Good PRs:

• can be reviewed in under 15 minutes
• have a clear summary
• have focused commits
• include verification
• explain risk
• include follow-up tasks if incomplete

Bad PRs:

• broad rewrites
• unrelated formatting churn
• mixed behaviour/config/dependency changes
• no tests or verification
• vague summary
• risky workflow changes without approval

Do not merge without explicit human approval.

Stacked PRs

For stacked PRs:

• base each PR on the previous PR head
• keep each head branch limited to that workstream's commits
• do not merge lower stack branches into higher stack branches
• prefer rebase or cherry-pick to move commits through the stack
• never force-push shared or maintainer branches without approval

Dependabot Policy

Dependabot is allowed for dependency hygiene, but PR noise must be controlled.

Rules:

• Use grouped dependency updates.
• Use weekly schedules by default.
• Keep open PR limits low.
• Do not auto-merge major updates.
• Do not auto-merge production dependency updates without tests.
• Use branchbrief on Dependabot PRs before merge.
• Treat major updates as medium or high risk.
• Treat auth, payment, crypto, database, build, and deployment dependency updates as high risk.

Release Cycle Tasks

Agents may perform release-cycle maintenance as atomic commits.

Allowed release-cycle commits:

• docs(changelog): add unreleased section
• chore(version): start next development cycle
• docs(roadmap): update next milestone
• docs(release): update release process
• ci(release): add release smoke check

Rules:

• Do not create release-cycle commits unless there is a real release or milestone transition.
• Do not bump versions randomly.
• Do not tag or publish releases without explicit approval.
• Do not modify npm publishing settings without approval.
• Keep changelog, roadmap, and version changes separate when they represent separate intents.

Stop Before Touching

Ask before changing:

• network access
• LLM/provider calls
• GitHub write actions
• PR commenting behaviour
• release publishing
• telemetry/privacy behaviour
• auth or token handling
• secrets
• environment variables
• config formats
• public CLI commands
• GitHub Action inputs or outputs
• generated output schema
• destructive commands
• major dependency upgrades
• licensing

branchbrief-Specific Policy

branchbrief must stay local-first by default.

Default behaviour must not require:

• API keys
• network access
• LLM calls
• GitHub tokens
• hidden credential use

Facts must come from deterministic sources before any optional AI enhancement.

Do not silently call:

• OpenAI
• Anthropic
• OpenRouter
• Copilot
• Ollama
• any local or remote model provider

Optional AI use must be explicit in command names, flags, docs, and review notes.

For risk detection work, keep rules auditable and path/config driven where possible.

For GitHub Action work, preserve safe defaults and document required permissions.

For output formats, treat Markdown and JSON shape as public interfaces once released.

Verification

Every task must include verification.

Use the smallest relevant check first:

• targeted unit test
• targeted integration test
• typecheck
• lint
• build
• smoke command
• manual QA checklist

If verification cannot be run, explain why and provide the exact command that should be run.

Do not claim success without either running verification or clearly stating that verification was not run.

Review Pack Required

At the end of every task, return:

## Review Pack
Repo:
Branch:
PR:
Task:
Status:
Summary:
Commits:
Files changed:
Verification:
Risk level:
Rollback plan:
Human decision needed:
Next recommended task: