diff --git a/.github/assets/readme-inline-agents-working-with-humans.png b/.github/assets/readme-inline-agents-working-with-humans.png new file mode 100644 index 0000000..fb39478 Binary files /dev/null and b/.github/assets/readme-inline-agents-working-with-humans.png differ diff --git a/README.md b/README.md index cc2ea86..f728b04 100644 --- a/README.md +++ b/README.md @@ -4,217 +4,88 @@ A portable agent workflow skill library. Write your team's development workflow once — start, ship, review, version, release — and sync it to Claude Code, Cursor, and other AI coding agents across all your projects. -Repository: [github.com/LightbridgeLab/CodeCanon](https://github.com/LightbridgeLab/CodeCanon) +Repository: [github.com/LightbridgeLab/CodeCannon](https://github.com/LightbridgeLab/CodeCannon) -## How it works +## The problem -1. Skills live in `skills/` as plain markdown with `{{PLACEHOLDER}}` tokens for project-specific values. -2. `sync.sh` reads your project config, substitutes values, wraps each skill in an agent-specific invocation header, and writes the generated files to the right place (`.claude/commands/`, `.cursor/rules/`, etc.). -3. Generated files carry a hash so sync.sh can detect manual edits and warn before overwriting. +AI coding agents are powerful, but every project reinvents the same workflows: how to create issues, open PRs, run reviews, bump versions, cut releases. These instructions live in scattered prompt files, maintained per-project, per-agent, with no consistency and no reuse. -## Workflow model +## The solution -Before configuring anything, understand the assumptions these skills encode. - -**GitHub only.** Every skill uses the `gh` CLI. GitLab, Gitea, and Bitbucket are not supported (yet). - -**Every session has a ticket.** `/start` either creates a new GitHub issue or resumes an existing one by number. There is no path for committing code without an issue. The issue is the unit of work — the branch, PR, and commit history all link back to it. - -**Branching model.** Three models are supported — set `BRANCH_DEV` and `BRANCH_TEST` in `.codecannon.yaml` to match your workflow: +Code Cannon is a shared skill library that lives as a git submodule. Skills are written once as portable markdown with placeholder tokens. A sync script reads your project config, substitutes values, and generates agent-specific command files for each AI tool your team uses. ``` -# Trunk-based (BRANCH_DEV and BRANCH_TEST empty): -feature/ → BRANCH_PROD (default: main) - /start /ship merges here; /version and /release run here - -# Two-branch (BRANCH_DEV set): -feature/ → BRANCH_DEV → BRANCH_PROD - /start /ship /release - -# Three-branch (BRANCH_DEV and BRANCH_TEST set): -feature/ → BRANCH_DEV → BRANCH_TEST → BRANCH_PROD - /start /ship manual/future /release - /promote +skills/*.md → sync.sh + .codecannon.yaml → .claude/commands/*.md + → .cursor/rules/*.mdc ``` -**All three models are supported.** Set `BRANCH_DEV` and `BRANCH_TEST` in `.codecannon.yaml` to match your workflow. Leave both empty for trunk-based development. Trunk mode is the default when no dev branch is configured. - -In two-branch mode, feature PRs target `BRANCH_DEV`. Issues deliberately stay open through this merge — `Closes #N` is not used on feature PRs because they don't land in the default branch. Issues only auto-close when `/release` promotes to `BRANCH_PROD`. This supports a QA gate between merging code and shipping to production. - -In trunk mode, feature PRs target `BRANCH_PROD` directly and use `Closes #N` — issues auto-close on merge. - -## Choose your workflow - -Code Cannon adapts to your process, not your team size. Run `/setup` for a guided walkthrough, or configure `.codecannon.yaml` manually. Common profiles: - -| Profile | Branch model | AI review | QA flow | Reviewers | Good for | -|---|---|---|---|---|---| -| **Lightweight** | Trunk | Advisory (posts but doesn't block) | Off | None | Fast iteration, low ceremony | -| **Standard** | Two-branch | Blocks merge | Optional | Optional | Review-gated development | -| **Governed** | Two or three-branch | Blocks merge | On | Assigned | Full traceability and QA handoff | +One source of truth. Every project. Every agent. -These aren't rigid modes — they're starting points. Every setting is independently configurable. +## What you get -**The intended sequence for a complete change:** +**A complete development workflow in six commands:** ``` -/start → [code + local test] → /ship → [QA on preview] → /version → /release +/start → [code + test] → /ship → [QA] → /version → /release ``` -- `/start` — reads code, proposes an approach, **waits for human approval**, then creates the issue, branch, and writes code -- `/ship` — runs `CHECK_CMD`, commits everything, pushes, opens the PR, spawns an agent review, merges if approved; runs from a feature branch -- `/version` — bumps semver, tags, pushes; runs from the pre-production branch (determined by mode) after features are merged -- `/release` — in two/three-branch mode, opens a promotion PR to `BRANCH_PROD`, **waits for human to type "release"**, merges, creates a GitHub Release, closes issues; in trunk mode, creates the GitHub Release directly from `BRANCH_PROD` -- `/review` — standalone review on any PR; also called internally by `/ship` -- `/status` — read-only snapshot: open PRs, recently merged PRs, and open issues for a user (defaults to `@me`, scoped to the current repo) +- `/start` — creates a GitHub issue, feature branch, and writes code (with human approval before any work begins) +- `/ship` — checks, commits, opens PR, runs AI review, merges +- `/review` — standalone code review on any PR +- `/version` — bumps semver, tags, pushes +- `/release` — promotes to production, creates a GitHub Release +- `/status` — standup-ready snapshot of PRs, issues, and progress -**Human gates.** `/start` pauses before creating the issue to confirm the implementation approach. `/release` requires an explicit "release" confirmation. Everything else runs unattended. +Plus `/qa` for structured QA workflows and `/setup` for guided onboarding. -**Branch discipline is enforced.** `/ship` aborts if run from any protected branch (`BRANCH_PROD`, `BRANCH_DEV`, or `BRANCH_TEST` when set). `/version` aborts if not on the required pre-production branch (determined by mode). The agent will not proceed past these checks. +## Philosophy -**Milestone assignment is automatic.** When `/start` creates an issue it resolves the active milestone in order: per-invocation `--milestone` flag → `DEFAULT_MILESTONE` config → open milestones queried from GitHub. If one open milestone exists it's used silently; if multiple exist you're prompted once; if none exist the issue is created without one. Set `DEFAULT_MILESTONE` only if you want to pin a value and skip detection. +**Humans stay in the loop.** The agent proposes; you approve. `/start` waits for your sign-off before creating anything. `/release` requires explicit confirmation. The agent commits; you test. -**Reviewer selection is never automatic.** `/ship` adds reviewers only from two sources: a detected `CODEOWNERS` file (checked in `CODEOWNERS`, `.github/CODEOWNERS`, and `docs/CODEOWNERS`) and the `DEFAULT_REVIEWERS` config key. The agent never infers reviewers from git history, blame, or team membership. +**Every change has a ticket.** There is no path for code without an issue. The issue is the unit of work — branch, PR, and release all link back to it. -**The agent commits; you test.** `/start` writes code but does not commit — it hands off to you with "run `DEV_CMD` and test locally." Committing happens in `/ship`. This is intentional: the human approval loop before shipping is where you catch things the agent missed. +**Configure, don't fork.** Skills use `{{PLACEHOLDER}}` tokens for project-specific values. Your `.codecannon.yaml` fills them in. When upstream skills improve, pull the submodule and re-sync. -## Quickstart +**Agent-agnostic.** Skills are written once. Adapters handle the translation to Claude Code, Cursor, or any future agent. -### 1. Add Code Cannon as a submodule +![Code Cannon Agents Working With Humans](.github/assets/readme-inline-agents-working-with-humans.png) + +## Quick start ```bash +# Add Code Cannon to your project git submodule add https://github.com/LightbridgeLab/CodeCanon.git CodeCanon git submodule update --init -``` -### 2. Create your project config - -```bash +# Create and edit your config cp CodeCanon/templates/codecannon.yaml .codecannon.yaml -``` - -Edit `.codecannon.yaml` — set your branch names, check command, deploy commands, and which adapters to generate. - -### 3. Run sync -```bash +# Generate skill files CodeCanon/sync.sh ``` -This generates skill files for each adapter listed in your config. For Claude Code, that's `.claude/commands/*.md`. For Cursor, `.cursor/rules/*.mdc`. - -### 4. Copy AGENTS.md template (optional) - -```bash -cp CodeCanon/templates/AGENTS.md.template AGENTS.md -``` - -Edit the project-specific section at the bottom. - -### 5. Add Makefile targets (optional) - -```makefile -# In your Makefile -include CodeCanon/Makefile.agents.mk -``` - -Or copy the targets from `Makefile.agents.mk` directly. - -### 6. Commit and share - -Commit `.codecannon.yaml`, `AGENTS.md`, and the generated `.claude/` directory. Every teammate gets a working installation on `git clone` + `git submodule update --init` — no further setup needed. - -`.codecannon.yaml` is a team contract, not personal config. Changes to it should be reviewed like any other config change. - -## Keeping skills up to date - -```bash -git submodule update --remote CodeCanon # pull latest skills -CodeCanon/sync.sh # regenerate skill files -``` - -If any generated files have been manually customized, sync.sh will warn and skip them. Use `--force` to overwrite. - -## Migrating from the old `agentgate` submodule - -If your project still uses the previous repo URL or folder name: - -1. Point `.gitmodules` at `https://github.com/LightbridgeLab/CodeCanon.git` and use submodule path `CodeCanon/` (or rename your existing checkout to match). -2. Rename `.agentgate.yaml` → `.codecannon.yaml`. -3. Run `CodeCanon/sync.sh --force` once if needed so generated file headers match the new provenance marker. - -## Customizing the review agent - -The review agent prompt is generated to the path in `REVIEW_AGENT_PROMPT`. Two config keys make it project-aware — set them in `.codecannon.yaml` and re-run sync: - -`**PLATFORM_COMPLIANCE_NOTES**` — infrastructure and framework rules that are easy to get wrong and hard to catch in tests. Examples: - -- `Postgres: use parameterized queries via the ORM; never raw string interpolation` -- `Redis: TTLs required on all keys written in request handlers` -- `Next.js: server components must not import client-only modules` - -`**CONVENTIONS_NOTES**` — non-obvious team rules that differ from common defaults. Examples: - -- `API logic in services/, UI in app/ — no business logic in components` -- `Use the design system tokens — no hardcoded hex values` -- `Feature flags via the flags/ module only; no ad-hoc env var checks` - -These are the primary way Code Cannon becomes project-aware rather than a generic tool. Until set, both sections default to an HTML comment (invisible to agents, visible to you as a nudge). Use YAML block scalars for multi-line content: - -```yaml -CONVENTIONS_NOTES: | - - Rule one - - Rule two -``` - -## sync.sh reference - -``` -./CodeCanon/sync.sh [options] - -Options: - --config path Project config file (default: .codecannon.yaml) - --force Overwrite customized files without prompting - --dry-run Preview what would be written, no changes made - --skill name,... Sync only specific skill(s), comma-separated -``` - -## Included skills - - -| Skill | Description | -| -------------- | -------------------------------------------------------------------------------------------------------------------- | -| `start` | Start a new feature: create a GitHub issue, branch, and write code | -| `ship` | Type-check, commit, open PR, spawn review agent, merge | -| `review` | Standalone code review on a PR | -| `version` | Bump version, tag, push — run before deploying to preview environment | -| `release` | Create GitHub Release; in two-branch and three-branch mode, also promotes the pre-production branch to `BRANCH_PROD` | -| `status` | Snapshot of open PRs, recently merged work, and open issues | -| `qa` | View the QA queue or record findings and apply a verdict label to a specific issue | -| `setup` | First-run onboarding: check config, labels, and milestone setup | -| `review-agent` | Code review agent system prompt (used by `ship` and `review`) | - - -## Supported adapters - - -| Adapter | Output | Notes | -| -------- | ----------------------- | ------------------------------------------------------- | -| `claude` | `.claude/commands/*.md` | Full feature support including sub-agent spawning | -| `cursor` | `.cursor/rules/*.mdc` | Agent-requested rules; sub-agent spawning not supported | - - -## Config reference - -See `config.schema.yaml` for all available `{{PLACEHOLDERS}}` with descriptions and defaults. +Or run `/setup` for a guided walkthrough that detects your project state and configures everything interactively. -## Adding your project's conventions +## Documentation -After running sync, add project-specific sections to `AGENTS.md` (below the separator line) — architecture notes, coding conventions, platform gotchas. These are not managed by Code Cannon sync and won't be overwritten. +- **[Getting started](docs/index.md)** — detailed overview, full quickstart, migration guide +- **[Branching models](docs/branching.md)** — trunk, two-branch, and three-branch workflows +- **[Customization](docs/customization.md)** — tailoring skills to your project, sync.sh reference +- **[Config reference](docs/config-reference.md)** — every `.codecannon.yaml` setting documented +- **[Adapters](docs/adapters.md)** — supported agents and how to add new ones -## Legacy: template-repo usage +### Skill reference -The original copy-based workflow (AGENTS.md + `.agents/config.yaml` + `Makefile.agents.mk`) still works for projects that prefer to copy files rather than use a submodule. See `.agents/` for those files. +| Skill | Docs | Description | +|---|---|---| +| `/start` | [docs](docs/skills/start.md) | Create a GitHub issue, branch, and write code | +| `/ship` | [docs](docs/skills/ship.md) | Check, commit, open PR, review, merge | +| `/review` | [docs](docs/skills/review.md) | Standalone code review on a PR | +| `/version` | [docs](docs/skills/version.md) | Bump version, tag, push | +| `/release` | [docs](docs/skills/release.md) | Promote to production, create GitHub Release | +| `/qa` | [docs](docs/skills/qa.md) | QA queue and structured review workflow | +| `/status` | [docs](docs/skills/status.md) | Snapshot of PRs, issues, and progress | +| `/setup` | [docs](docs/skills/setup.md) | Guided onboarding and configuration | ## License diff --git a/docs/adapters.md b/docs/adapters.md new file mode 100644 index 0000000..84f5d21 --- /dev/null +++ b/docs/adapters.md @@ -0,0 +1,61 @@ +# Adapters + +Adapters translate Code Cannon's generic skill format into agent-specific file formats. Each adapter defines an output directory, file extension, and invocation header. + +## Supported adapters + +| Adapter | Output | Notes | +|---|---|---| +| `claude` | `.claude/commands/*.md` | Full feature support including sub-agent spawning | +| `cursor` | `.cursor/rules/*.mdc` | Agent-requested rules; sub-agent spawning not supported | + +### Claude Code + +The Claude adapter generates slash commands in `.claude/commands/`. Users invoke skills with `/skill-name` in Claude Code. The `/ship` skill can spawn a review sub-agent natively. + +### Cursor + +The Cursor adapter generates agent-requested rules in `.cursor/rules/`. Users trigger rules via `@rulename` in Agent mode, or the agent requests them by description. + +**Limitation:** Cursor does not support sub-agent spawning. The review step in `/ship` (which spawns a separate review agent) must be performed manually by pasting the review-agent prompt into a new chat. + +## Enabling adapters + +List the adapters you want in `.codecannon.yaml`: + +```yaml +adapters: + - claude + - cursor +``` + +Run `sync.sh` to generate files for all listed adapters. You can enable both simultaneously — they write to different directories and don't conflict. + +## How adapters work + +Each adapter lives in `adapters//` and contains: + +- **`config.yaml`** — defines `output_directory` and `output_extension` +- **`header.md`** — the invocation header template prepended to each generated skill file + +The header template uses `{skill}` and `{description}` as placeholders (distinct from the `{{CONFIG}}` placeholders used in skill bodies). + +## Adding a new adapter + +To support a new AI coding agent: + +1. Create `adapters//config.yaml`: + ```yaml + agent: + description: + output_directory: + output_extension: + ``` + +2. Create `adapters//header.md` — the invocation header that tells the agent how to interpret the skill. Use `{skill}` and `{description}` as placeholders for the skill name and description. + +3. Test with `sync.sh --skill start` against a test project. + +4. Document any adapter limitations in `config.yaml` under `notes`. + +5. Add the adapter name to `adapters:` in `.codecannon.yaml` for any project that should use it. diff --git a/docs/branching.md b/docs/branching.md new file mode 100644 index 0000000..25d18b8 --- /dev/null +++ b/docs/branching.md @@ -0,0 +1,84 @@ +# Branching Models + +Code Cannon supports three branching models. Set `BRANCH_DEV` and `BRANCH_TEST` in `.codecannon.yaml` to match your workflow. + +## Trunk-based development + +**Config:** Leave `BRANCH_DEV` and `BRANCH_TEST` empty (or unset). + +``` +feature/ → main + /start /ship merges here + /version and /release run here +``` + +The simplest model. Feature branches are created from and merged directly into `BRANCH_PROD` (default: `main`). `/ship` opens a PR targeting `main` with `Closes #N` — issues auto-close on merge. + +**When to use:** Solo developers, small teams, projects where every merge is production-ready. Fast iteration with low ceremony. + +**Skill behavior in trunk mode:** +- `/ship` targets `BRANCH_PROD` directly +- `/version` runs from `BRANCH_PROD` +- `/release` creates a GitHub Release from `BRANCH_PROD` (no promotion PR needed) +- QA labels are not applied automatically + +## Two-branch development + +**Config:** Set `BRANCH_DEV` to your integration branch (e.g. `dev`, `development`, `staging`). + +``` +feature/ → BRANCH_DEV → BRANCH_PROD + /start /ship /release +``` + +Feature PRs target `BRANCH_DEV`. Issues deliberately stay open through the feature merge — `Closes #N` is not used on feature PRs because they don't land in the default branch. Issues only auto-close when `/release` promotes `BRANCH_DEV` to `BRANCH_PROD`. + +This supports a QA gate between merging code and shipping to production. After `/ship` merges a feature, you deploy the integration branch to a preview environment, test it, then run `/release` when satisfied. + +**When to use:** Teams that want a review/QA gate before production. The most common model for teams with a staging or preview environment. + +**Skill behavior in two-branch mode:** +- `/ship` targets `BRANCH_DEV` and uses `Issue #N` (not `Closes`) +- `/ship` applies `QA_READY_LABEL` to the linked issue (if configured) +- `/version` runs from `BRANCH_DEV` +- `/release` opens a promotion PR from `BRANCH_DEV` to `BRANCH_PROD` with `Closes #N` to auto-close issues + +## Three-branch development + +**Config:** Set both `BRANCH_DEV` and `BRANCH_TEST`. + +``` +feature/ → BRANCH_DEV → BRANCH_TEST → BRANCH_PROD + /start /ship manual/future /release + /promote +``` + +Adds a dedicated test/staging branch between integration and production. Feature PRs still target `BRANCH_DEV`. The promotion from `BRANCH_DEV` to `BRANCH_TEST` is a manual PR or a future `/promote` skill. + +**When to use:** Teams with a formal QA or staging environment that is separate from the integration environment. Common in regulated industries or teams with dedicated QA staff. + +**Skill behavior in three-branch mode:** +- `/ship` targets `BRANCH_DEV` (same as two-branch) +- `/version` runs from `BRANCH_TEST` +- `/release` promotes `BRANCH_TEST` to `BRANCH_PROD` +- The `BRANCH_DEV` to `BRANCH_TEST` step is outside Code Cannon's current scope + +## Choosing your model + +| Profile | Branch model | AI review | QA flow | Good for | +|---|---|---|---|---| +| **Lightweight** | Trunk | Advisory (posts but doesn't block) | Off | Fast iteration, low ceremony | +| **Standard** | Two-branch | Blocks merge | Optional | Review-gated development | +| **Governed** | Two or three-branch | Blocks merge | On | Full traceability and QA handoff | + +These aren't rigid modes — they're starting points. Every setting is independently configurable. Run `/setup` for a guided walkthrough that helps you pick the right profile and configure it. + +## Branch discipline + +Code Cannon enforces branch rules at the skill level: + +- `/ship` aborts if run from any protected branch (`BRANCH_PROD`, `BRANCH_DEV`, or `BRANCH_TEST` when set). It must be run from a `feature/*` branch. +- `/version` aborts if not on the required pre-production branch (determined by mode). +- `/start` always creates `feature/*` branches via `gh issue develop`, ensuring every branch is linked to an issue. + +The agent will not proceed past these checks. There is no override flag — if you're on the wrong branch, switch first. diff --git a/docs/config-reference.md b/docs/config-reference.md new file mode 100644 index 0000000..a10cc3e --- /dev/null +++ b/docs/config-reference.md @@ -0,0 +1,76 @@ +# Config Reference + +All placeholders available in `.codecannon.yaml`. Each is substituted into skill files by `sync.sh`. + +For the canonical source, see [`config.schema.yaml`](../config.schema.yaml). + +## Branch names + +| Key | Default | Used in | Description | +|---|---|---|---| +| `BRANCH_PROD` | `main` | ship, release, version | Production branch. All release promotion targets this branch. | +| `BRANCH_DEV` | *(empty)* | ship, release, version, qa, review-agent | Development/integration branch. Leave empty for trunk-based development. Set to enable two-branch mode. | +| `BRANCH_TEST` | *(empty)* | version, release | Test/staging branch for three-branch workflows. Requires `BRANCH_DEV` to be set. | + +See [branching models](branching.md) for how these values change skill behavior. + +## Workflow commands + +| Key | Default | Used in | Description | +|---|---|---|---| +| `CHECK_CMD` | `make check` | ship | Type-check / lint gate that must pass before shipping. | +| `DEV_CMD` | `make dev` | start | Start the local development server. Suggested to user after `/start` writes code. | +| `ABANDON_CMD` | `make abandon` | start | Discard all changes and delete the current feature branch. | +| `MERGE_CMD` | `make merge` | ship, release | Merge the current feature PR into the integration branch. | +| `DEPLOY_PREVIEW_CMD` | `make deploy-preview` | version | Deploy to the pre-production environment. | +| `DEPLOY_PROD_CMD` | `make deploy-prod` | release | Deploy to production. | +| `REVIEW_GATE` | `ai` | ship, review | Controls AI review in `/ship`. Values: `ai` (blocks on critical findings), `advisory` (posts but doesn't block), `off` (no review). | + +## Version bumping + +| Key | Default | Used in | Description | +|---|---|---|---| +| `VERSION_READ_CMD` | `node -p "require('./package.json').version"` | version | Command that prints the current version string. | +| `BUMP_PATCH_CMD` | `make bump-patch` | version | Bump patch version, commit, and tag. | +| `BUMP_MINOR_CMD` | `make bump-minor` | version | Bump minor version, commit, and tag. | +| `BUMP_MAJOR_CMD` | `make bump-major` | version | Bump major version, commit, and tag. | +| `SET_VERSION_CMD` | `make set-version V=` | version | Set an arbitrary version (value appended as argument). | + +## Paths + +| Key | Default | Used in | Description | +|---|---|---|---| +| `REVIEW_AGENT_PROMPT` | `.claude/review-agent-prompt.md` | ship, review, review-agent | Path to the review agent prompt file. | + +## GitHub / PR settings + +| Key | Default | Used in | Description | +|---|---|---|---| +| `DEFAULT_REVIEWERS` | *(empty)* | ship | Comma-separated GitHub handles or team slugs to add as PR reviewers. | +| `TICKET_LABELS` | *(empty)* | start | Comma-separated label pool the agent may apply to new issues. The agent selects 1-3 fitting labels, not all of them. | +| `TICKET_LABEL_CREATION_ALLOWED` | `false` | start | Whether the agent may create new GitHub labels when no pool label fits. | +| `DEFAULT_MILESTONE` | *(empty)* | start | Milestone applied to every new issue. Overrides auto-detection from GitHub. | +| `QA_READY_LABEL` | `ready-for-qa` | ship, qa | Label applied by `/ship` in two-branch mode when a feature merges to `BRANCH_DEV`. | +| `QA_PASSED_LABEL` | `qa-passed` | qa | Label applied by `/qa` when a feature passes QA. | +| `QA_FAILED_LABEL` | `qa-failed` | qa | Label applied by `/qa` when a feature fails QA. | + +## Review agent content + +| Key | Default | Used in | Description | +|---|---|---|---| +| `PLATFORM_COMPLIANCE_NOTES` | *(HTML comment placeholder)* | review-agent | Platform-specific compliance rules injected into the review agent prompt. Use a YAML block scalar for multi-line content. | +| `CONVENTIONS_NOTES` | *(HTML comment placeholder)* | review-agent | Project-specific conventions injected into the review agent prompt. Use a YAML block scalar for multi-line content. | + +See the [customization guide](customization.md) for examples of setting these values. + +## Top-level config + +In addition to the `config:` block, `.codecannon.yaml` has a top-level `adapters:` key: + +```yaml +adapters: + - claude + - cursor +``` + +This controls which agent adapters `sync.sh` generates files for. See [adapters](adapters.md) for details on each. diff --git a/docs/customization.md b/docs/customization.md new file mode 100644 index 0000000..65dde08 --- /dev/null +++ b/docs/customization.md @@ -0,0 +1,166 @@ +# Customization Guide + +Code Cannon is designed to be configured, not forked. All project-specific behavior is controlled through `.codecannon.yaml` and a few optional extension points. + +## How placeholders work + +Skills in `skills/` use `{{PLACEHOLDER}}` tokens wherever behavior needs to vary between projects. When you run `sync.sh`, it reads your `.codecannon.yaml`, substitutes each placeholder with your project's value, and writes the generated skill files. + +For example, the `/ship` skill contains: + +```markdown +Run: +{{CHECK_CMD}} +``` + +If your `.codecannon.yaml` has `CHECK_CMD: npm run lint && npm test`, the generated file will contain `npm run lint && npm test` in place of the token. + +See the full list of available placeholders in the [config reference](config-reference.md). + +## Common customization examples + +### Changing your branch model + +```yaml +# Trunk-based (simplest) +BRANCH_PROD: main +BRANCH_DEV: "" +BRANCH_TEST: "" + +# Two-branch with QA gate +BRANCH_PROD: main +BRANCH_DEV: development + +# Three-branch with staging +BRANCH_PROD: main +BRANCH_DEV: development +BRANCH_TEST: staging +``` + +See [branching models](branching.md) for a full explanation of each mode. + +### Setting your check and deploy commands + +```yaml +CHECK_CMD: make check # must pass before /ship proceeds +DEV_CMD: make dev # suggested to user after /start writes code +DEPLOY_PREVIEW_CMD: make deploy-preview +DEPLOY_PROD_CMD: make deploy-prod +``` + +These can be any shell command. If your project uses npm scripts: + +```yaml +CHECK_CMD: npm run lint && npm test +DEV_CMD: npm run dev +DEPLOY_PREVIEW_CMD: npm run deploy:staging +DEPLOY_PROD_CMD: npm run deploy:production +``` + +### Controlling AI review behavior + +```yaml +# AI review blocks merge on critical findings (default) +REVIEW_GATE: "ai" + +# AI review posts findings but never blocks merge +REVIEW_GATE: "advisory" + +# No AI review at all — /ship merges immediately after checks pass +REVIEW_GATE: "off" +``` + +### Configuring labels and milestones + +```yaml +# Labels the agent can choose from when creating issues +TICKET_LABELS: "bug,enhancement,documentation,good first issue" + +# Allow the agent to create new labels on the fly +TICKET_LABEL_CREATION_ALLOWED: "true" + +# Pin all new issues to a specific milestone +DEFAULT_MILESTONE: "Sprint 4" +``` + +### Setting up QA labels (two-branch mode) + +```yaml +QA_READY_LABEL: "ready-for-qa" +QA_PASSED_LABEL: "qa-passed" +QA_FAILED_LABEL: "qa-failed" +``` + +## Customizing the review agent + +The review agent prompt is generated to the path in `REVIEW_AGENT_PROMPT`. Two config keys make it project-aware: + +### `PLATFORM_COMPLIANCE_NOTES` + +Infrastructure and framework rules that are easy to get wrong and hard to catch in tests. These are injected into the review agent's "Platform Compliance" section. + +```yaml +PLATFORM_COMPLIANCE_NOTES: | + - Postgres: use parameterized queries via the ORM; never raw string interpolation + - Redis: TTLs required on all keys written in request handlers + - Next.js: server components must not import client-only modules +``` + +### `CONVENTIONS_NOTES` + +Non-obvious team rules that differ from common defaults. Injected into the review agent's "Conventions" section. + +```yaml +CONVENTIONS_NOTES: | + - API logic in services/, UI in app/ — no business logic in components + - Use the design system tokens — no hardcoded hex values + - Feature flags via the flags/ module only; no ad-hoc env var checks +``` + +These are the primary way Code Cannon becomes project-aware rather than a generic tool. Until set, both sections default to an HTML comment (invisible to agents, visible to you as a nudge). + +## Adding project conventions to AGENTS.md + +After running sync, add project-specific sections to `AGENTS.md` below the separator line — architecture notes, coding conventions, platform gotchas. These are not managed by Code Cannon sync and won't be overwritten. + +The `AGENTS.md` template provides the structure. Your additions live alongside the generated content and give agents broader context about your project beyond what the skill placeholders cover. + +## sync.sh and manual edits + +Every generated file includes a hash comment in its header: + +``` + +``` + +When you run `sync.sh`, it computes the expected hash for each file. If the file on disk has a different hash (because you edited it manually), sync.sh warns and skips that file. This protects intentional customizations. + +To overwrite anyway: `sync.sh --force`. + +To regenerate only specific skills: `sync.sh --skill start,ship`. + +### sync.sh reference + +``` +./CodeCanon/sync.sh [options] + +Options: + --config path Project config file (default: .codecannon.yaml) + --force Overwrite customized files without prompting + --dry-run Preview what would be written, no changes made + --skill name,... Sync only specific skill(s), comma-separated +``` + +## Version commands + +The version-related placeholders control how `/version` reads and bumps versions: + +```yaml +VERSION_READ_CMD: "cat VERSION" # prints current version +BUMP_PATCH_CMD: make bump-patch # bump + commit + tag +BUMP_MINOR_CMD: make bump-minor +BUMP_MAJOR_CMD: make bump-major +SET_VERSION_CMD: "make set-version V=" # arbitrary version (value appended) +``` + +These commands are expected to handle the commit and tag creation themselves. `/version` calls them and then pushes. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..bb048b0 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,112 @@ +# Code Cannon Documentation + +Code Cannon is a portable agent workflow skill library. Write your team's development workflow once — start, ship, review, version, release — and sync it to Claude Code, Cursor, and other AI coding agents across all your projects. + +## How it works + +1. **Skills** live in `skills/` as plain markdown with `{{PLACEHOLDER}}` tokens for project-specific values. +2. **`sync.sh`** reads your project config (`.codecannon.yaml`), substitutes values, wraps each skill in an agent-specific invocation header, and writes the generated files to the right place (`.claude/commands/`, `.cursor/rules/`, etc.). +3. **Generated files** carry a hash so sync.sh can detect manual edits and warn before overwriting. + +## The workflow + +The intended sequence for a complete change: + +``` +/start → [code + local test] → /ship → [QA on preview] → /version → /release +``` + +- [`/start`](skills/start.md) — reads code, proposes an approach, **waits for human approval**, then creates the issue, branch, and writes code +- [`/ship`](skills/ship.md) — runs checks, commits everything, pushes, opens the PR, spawns an agent review, merges if approved +- [`/review`](skills/review.md) — standalone review on any PR; also called internally by `/ship` +- [`/version`](skills/version.md) — bumps semver, tags, pushes +- [`/release`](skills/release.md) — promotes to production, creates a GitHub Release, closes issues +- [`/status`](skills/status.md) — read-only snapshot of open PRs, merged work, and open issues +- [`/qa`](skills/qa.md) — view the QA queue or record findings on a specific issue +- [`/setup`](skills/setup.md) — first-run onboarding: check config, labels, and milestone setup + +## Human gates + +Code Cannon is opinionated about where humans stay in the loop: + +- `/start` pauses before creating the issue to confirm the implementation approach. +- `/release` requires an explicit "release" confirmation before promoting to production. +- `/qa` shows the review comment and waits for approval before posting. +- Everything else runs unattended. + +The agent commits; you test. `/start` writes code but does not commit — it hands off to you with "run your dev command and test locally." Committing happens in `/ship`. The human approval loop before shipping is where you catch things the agent missed. + +## Quickstart + +### 1. Add Code Cannon as a submodule + +```bash +git submodule add https://github.com/LightbridgeLab/CodeCanon.git CodeCanon +git submodule update --init +``` + +### 2. Create your project config + +```bash +cp CodeCanon/templates/codecannon.yaml .codecannon.yaml +``` + +Edit `.codecannon.yaml` — set your branch names, check command, deploy commands, and which adapters to generate. See the [config reference](config-reference.md) for all available settings. + +### 3. Run sync + +```bash +CodeCanon/sync.sh +``` + +This generates skill files for each adapter listed in your config. For Claude Code, that's `.claude/commands/*.md`. For Cursor, `.cursor/rules/*.mdc`. + +### 4. Copy AGENTS.md template (optional) + +```bash +cp CodeCanon/templates/AGENTS.md.template AGENTS.md +``` + +Edit the project-specific section at the bottom. + +### 5. Add Makefile targets (optional) + +```makefile +# In your Makefile +include CodeCanon/Makefile.agents.mk +``` + +Or copy the targets from `Makefile.agents.mk` directly. + +### 6. Commit and share + +Commit `.codecannon.yaml`, `AGENTS.md`, and the generated `.claude/` directory. Every teammate gets a working installation on `git clone` + `git submodule update --init` — no further setup needed. + +`.codecannon.yaml` is a team contract, not personal config. Changes to it should be reviewed like any other config change. + +Or skip all of this and run `/setup` for a guided walkthrough. + +## Keeping skills up to date + +```bash +git submodule update --remote CodeCanon # pull latest skills +CodeCanon/sync.sh # regenerate skill files +``` + +If any generated files have been manually customized, sync.sh will warn and skip them. Use `--force` to overwrite. + +## Migrating from the old `agentgate` submodule + +If your project still uses the previous repo URL or folder name: + +1. Point `.gitmodules` at `https://github.com/LightbridgeLab/CodeCanon.git` and use submodule path `CodeCanon/` (or rename your existing checkout to match). +2. Rename `.agentgate.yaml` to `.codecannon.yaml`. +3. Run `CodeCanon/sync.sh --force` once if needed so generated file headers match the new provenance marker. + +## Further reading + +- [Branching models](branching.md) — trunk, two-branch, and three-branch workflows explained +- [Customization guide](customization.md) — how to tailor skills to your project +- [Config reference](config-reference.md) — every `.codecannon.yaml` placeholder documented +- [Adapters](adapters.md) — supported agents and how to add new ones +- Individual skill documentation — see links in the workflow section above diff --git a/docs/skills/qa.md b/docs/skills/qa.md new file mode 100644 index 0000000..44ef854 --- /dev/null +++ b/docs/skills/qa.md @@ -0,0 +1,56 @@ +# /qa + +View the QA queue or record findings on a specific issue. + +**Source prompt:** [`../../skills/qa.md`](../../skills/qa.md) + +## What it does + +`/qa` provides a structured QA workflow for teams using two-branch development. It has two modes: + +- **No argument** — lists all issues with the `QA_READY_LABEL`, showing the current QA queue. +- **Issue number** — walks through a QA review for a specific issue: prompts for testing findings, posts a structured comment, and applies a verdict label. + +## Usage + +``` +/qa # show all issues awaiting QA +/qa 42 # review issue #42 +``` + +## Pre-flight + +`/qa` requires `QA_READY_LABEL` to be set in `.codecannon.yaml`. Without it, the skill can't identify which issues are waiting for QA. If unset, it explains how to enable the label workflow. + +The QA label workflow is primarily used in two-branch mode, where `/ship` automatically applies `QA_READY_LABEL` after merging a feature to `BRANCH_DEV`. In trunk or three-branch mode, the label must be applied manually. + +## Queue view (no argument) + +Queries GitHub for all open issues with the `QA_READY_LABEL` and displays them as a numbered list with issue number, title, milestone, and URL. Takes no other action. + +## Issue review (numeric argument) + +1. **Load context** — reads the issue body and comments. Warns if the issue doesn't have the `QA_READY_LABEL` (it may not be deployed yet). + +2. **Review prompt** — asks you to test the feature on the preview environment and report your findings and verdict (pass or fail). + +3. **Post findings** — builds a structured QA review comment with verdict, what was tested, findings, and screenshots. Shows the comment and asks for confirmation before posting to GitHub. + +4. **Apply verdict label** — on pass, adds `QA_PASSED_LABEL` and removes `QA_READY_LABEL`. On fail, adds `QA_FAILED_LABEL`, removes `QA_READY_LABEL`, and CCs the issue's assignees in the comment. + +## Why it's built this way + +**Structured QA comments.** QA findings are posted as structured comments with a consistent format. This makes it easy to scan an issue's history and find the QA verdict, what was tested, and what was found. + +**Label-driven workflow.** Using labels to track QA state means the queue is visible in GitHub's issue list without any external tools. `/qa` (no argument) simply queries for issues with the ready label. + +**Human gate on posting.** The comment is shown to the QA person before posting. This prevents accidental verdicts and gives a chance to edit findings. + +**Never closes issues.** `/qa` records the verdict but never closes the issue. Closure happens when `/release` promotes to production and the `Closes #N` reference triggers GitHub's auto-close. QA verdict and issue closure are separate concerns. + +## Config keys used + +- `QA_READY_LABEL` — label that identifies issues waiting for QA (required) +- `QA_PASSED_LABEL` — label applied on pass verdict +- `QA_FAILED_LABEL` — label applied on fail verdict +- `BRANCH_DEV` — relevant because QA labels are primarily used in two-branch mode diff --git a/docs/skills/release.md b/docs/skills/release.md new file mode 100644 index 0000000..0364903 --- /dev/null +++ b/docs/skills/release.md @@ -0,0 +1,53 @@ +# /release + +Create a GitHub Release and promote to production. + +**Source prompt:** [`../../skills/release.md`](../../skills/release.md) + +## What it does + +`/release` is the final step in the workflow. Its behavior varies by branching model: + +- **Trunk mode:** Creates a GitHub Release from `BRANCH_PROD` using the latest version tag. No promotion PR needed since features already merged to `BRANCH_PROD`. +- **Two-branch mode:** Opens a promotion PR from `BRANCH_DEV` to `BRANCH_PROD`, merges it (which auto-closes linked issues), and creates a GitHub Release. +- **Three-branch mode:** Same as two-branch but promotes from `BRANCH_TEST` to `BRANCH_PROD`. + +## Usage + +``` +/release +``` + +No arguments. Run after `/version` has tagged the release. + +## Step-by-step (trunk mode) + +1. **Verify state** — switches to `BRANCH_PROD` if needed, verifies a version tag exists on HEAD. +2. **Compute release contents** — finds merge commits since the previous tag, extracts linked PRs and issues. +3. **Human gate** — shows a release summary and waits for you to type "release". +4. **Create GitHub Release** — creates a release with a changelog listing all included PRs and issues. + +## Step-by-step (two-branch and three-branch mode) + +1. **Verify state** — switches to the pre-production branch, verifies a version tag exists on HEAD. +2. **Compute what's being promoted** — finds merge commits in the pre-production branch not yet in `BRANCH_PROD`, extracts linked PRs and issues. +3. **Human gate** — shows a release summary with all included PRs and issues that will close. Waits for you to type "release". +4. **Create promotion PR** — opens a PR from the pre-production branch to `BRANCH_PROD` with `Closes #N` references so issues auto-close on merge. +5. **Merge** — merges the promotion PR directly (does not use `MERGE_CMD`, which may refuse `BRANCH_PROD` targets). +6. **Create GitHub Release** — creates a release with a changelog and full comparison link. + +## Why it's built this way + +**Human gate is mandatory.** The "type release to confirm" gate exists because promoting to production is irreversible in practice. The summary gives you one last chance to verify that the right changes are going out. + +**Issues close on release, not on feature merge.** In multi-branch modes, feature PRs use `Issue #N` instead of `Closes #N`. Issues only auto-close when the promotion PR merges to `BRANCH_PROD`. This means issues stay open through the QA/staging phase, giving you visibility into what's deployed where. + +**Promotion PR bypasses MERGE_CMD.** `MERGE_CMD` typically includes safeguards that prevent direct merges to `BRANCH_PROD`. `/release` uses `gh pr merge` directly because this is the one intentional case where merging to production is correct. + +**Changelog is computed from git history.** The release notes are built from merge commits and their linked PRs/issues, not from manual input. This ensures the changelog matches what actually shipped. + +## Config keys used + +- `BRANCH_PROD`, `BRANCH_DEV`, `BRANCH_TEST` — determine mode and promotion path +- `MERGE_CMD` — NOT used for promotion merges (uses `gh pr merge` directly) +- `DEPLOY_PROD_CMD` — suggested after release for deploying to production diff --git a/docs/skills/review.md b/docs/skills/review.md new file mode 100644 index 0000000..fa199e9 --- /dev/null +++ b/docs/skills/review.md @@ -0,0 +1,59 @@ +# /review + +Run a standalone code review on a pull request. + +**Source prompt:** [`../../skills/review.md`](../../skills/review.md) + +## What it does + +`/review` runs a code review on any PR using the project's review agent prompt. It reads the PR diff, examines files for context, and posts structured findings as a PR comment. + +This is the same review that `/ship` runs automatically — `/review` just lets you trigger it independently at any time. + +## Usage + +``` +/review # review the current branch's open PR +/review 42 # review PR #42 +``` + +## Step-by-step + +1. **Pre-flight** — if `REVIEW_GATE` is `off`, the skill aborts with a message explaining how to enable reviews. + +2. **Identify the PR** — uses the argument as a PR number, or detects the current branch's open PR if no argument is given. + +3. **Spawn review agent** — loads `REVIEW_AGENT_PROMPT` and invokes the review agent. The agent reads the diff, reads files for context, and posts findings as a PR comment. + +4. **Report verdict** — relays the review agent's verdict: + - **APPROVE** — no critical findings + - **REQUEST CHANGES** — at least one critical finding; suggests fixing and re-running + +## What the review agent checks + +In priority order: + +1. **Correctness** — logic errors, edge cases, regressions +2. **Security** — SQL injection, XSS, secrets in code, unsafe redirects +3. **Platform compliance** — project-specific rules from `PLATFORM_COMPLIANCE_NOTES` +4. **Conventions** — project-specific rules from `CONVENTIONS_NOTES`, plus commit message format +5. **Code quality** (light touch) — obvious duplication, misleading names, dead code + +The review agent does NOT flag style preferences, documentation completeness, or future improvement suggestions. + +## Why it's built this way + +**Standalone and composable.** `/review` exists separately from `/ship` so you can review any PR at any time — not just as part of the shipping pipeline. It's useful for reviewing PRs from other contributors or re-reviewing after changes. + +**Same prompt, same standards.** Both `/ship` and `/review` use the same `REVIEW_AGENT_PROMPT`, so reviews are consistent regardless of how they're triggered. + +**Read-only.** `/review` never commits, pushes, or merges. It only reads and comments. This makes it safe to run at any point in the workflow. + +**Customizable via config.** The review agent's knowledge of your project comes from `PLATFORM_COMPLIANCE_NOTES` and `CONVENTIONS_NOTES` in `.codecannon.yaml`. Without these, it runs generic checks. With them, it catches project-specific issues. + +## Config keys used + +- `REVIEW_GATE` — must not be `off` for `/review` to run +- `REVIEW_AGENT_PROMPT` — path to the review agent system prompt +- `PLATFORM_COMPLIANCE_NOTES` — platform-specific rules (via review-agent prompt) +- `CONVENTIONS_NOTES` — project conventions (via review-agent prompt) diff --git a/docs/skills/setup.md b/docs/skills/setup.md new file mode 100644 index 0000000..4c82f7a --- /dev/null +++ b/docs/skills/setup.md @@ -0,0 +1,80 @@ +# /setup + +First-run onboarding and configuration walkthrough. + +**Source prompt:** [`../../skills/setup.md`](../../skills/setup.md) + +## What it does + +`/setup` detects the current state of Code Cannon in your project and guides you through configuration. It handles three scenarios: + +1. **You're in the Code Cannon repo itself** — explains how Code Cannon works and offers to help you add it to your project. +2. **Partial setup** — the submodule exists but something is missing (sync.sh not initialized, `gh` not installed, config file missing, etc.). Walks through fixes one at a time. +3. **Fully configured** — runs a health check, offers to populate labels from your GitHub repo, and walks through optional config values. + +## Usage + +``` +/setup +``` + +No arguments. Run it in any project where Code Cannon is (or should be) installed. + +## What it checks + +When the submodule is present, `/setup` runs these checks in order, stopping at the first failure: + +1. **`CodeCanon/sync.sh` present** — submodule initialized? +2. **`gh` installed** — GitHub CLI available? +3. **`gh` authenticated** — logged in to GitHub? +4. **Inside a GitHub repo** — remote configured? +5. **`.codecannon.yaml` present** — project config exists? +6. **Config values valid** — do branch names and commands point to real things? +7. **`.claude/commands/` populated** — has sync been run? + +Each check explains the problem and shows the fix command. + +## Profile selection + +When creating `.codecannon.yaml` for the first time, `/setup` asks you to pick a workflow profile: + +| Profile | Branch model | AI review | QA | What it configures | +|---|---|---|---|---| +| **Lightweight** | Trunk | Advisory | Off | `BRANCH_PROD`, `REVIEW_GATE: advisory` | +| **Standard** | Two-branch | AI-gated | Optional | `BRANCH_PROD`, `BRANCH_DEV`, `REVIEW_GATE: ai` | +| **Governed** | Two/three-branch | AI-gated | On | All branch/QA settings | +| **Custom** | Manual | Manual | Manual | Opens config for manual editing | + +Profiles are starting points — every setting is independently configurable afterward. + +## Label population + +Once fully configured, `/setup` fetches your repo's existing GitHub labels and offers to write them to `TICKET_LABELS` in `.codecannon.yaml`. This populates the label pool that `/start` uses when creating issues. + +You can select all labels or pick specific ones from the list. + +## Optional config walkthrough + +After label population, `/setup` walks through unset optional config values appropriate for your profile: + +- **Lightweight:** `PLATFORM_COMPLIANCE_NOTES`, `CONVENTIONS_NOTES` +- **Standard:** adds `DEFAULT_REVIEWERS`, `TICKET_LABEL_CREATION_ALLOWED` +- **Governed/Custom:** adds `DEFAULT_MILESTONE`, plus all Standard values + +For `PLATFORM_COMPLIANCE_NOTES`, it asks about your tech stack and drafts rules based on common violations for those technologies. For `CONVENTIONS_NOTES`, it asks about non-obvious team rules and shapes them into checkable review rules. + +Every write requires explicit confirmation. + +## Why it's built this way + +**Progressive disclosure.** `/setup` only shows you what's relevant to your current state. A new project sees the profile picker. A configured project sees the health check and optional settings. You never have to wade through the full config schema. + +**Stop-at-first-failure.** Each check builds on the previous one. There's no point checking config values if `gh` isn't installed. Stopping early keeps the fix list actionable. + +**Profile-aware walkthrough.** The optional config walkthrough skips settings that don't apply to your profile. A Lightweight setup doesn't need QA labels or milestone config. + +**Draft assistance for review rules.** Rather than asking you to write compliance and convention rules from scratch, `/setup` asks about your stack and drafts rules based on common patterns. You review and edit before anything is written. + +## Config keys used + +`/setup` can read and write all config keys. It's the only skill that modifies `.codecannon.yaml`. diff --git a/docs/skills/ship.md b/docs/skills/ship.md new file mode 100644 index 0000000..1aa56c3 --- /dev/null +++ b/docs/skills/ship.md @@ -0,0 +1,79 @@ +# /ship + +Type-check, commit, open PR, spawn review agent, and merge. + +**Source prompt:** [`../../skills/ship.md`](../../skills/ship.md) + +## What it does + +`/ship` is Phase 3 of the workflow — it takes code that has been written and tested locally, and moves it through the full shipping pipeline: check, commit, push, PR, review, merge. + +It must be run from a `feature/*` branch. Running it from any protected branch (`BRANCH_PROD`, `BRANCH_DEV`, `BRANCH_TEST`) causes an immediate abort. + +## Usage + +``` +/ship +``` + +No arguments. `/ship` operates on the current branch. + +## Step-by-step + +1. **Verify branch** — confirms you're on a `feature/*` branch, not a protected branch. + +2. **Type-check gate** — runs `CHECK_CMD`. If it fails, `/ship` stops and reports the errors. This is a hard gate — no bypass. + +3. **Identify linked issue** — looks for the issue number linked to this branch (from `gh issue develop` or the PR body). + +4. **Commit** — stages all changes and creates a single commit with an imperative-mood message. Excludes `.env` files, build artifacts, and secrets. + +5. **Push and open PR** — pushes the branch and creates a PR targeting the correct branch based on your branching model: + - **Trunk mode:** targets `BRANCH_PROD`, uses `Closes #N` + - **Two/three-branch mode:** targets `BRANCH_DEV`, uses `Issue #N` (issue stays open until `/release`) + +6. **Review** (conditional) — behavior depends on `REVIEW_GATE`: + - `ai` (default): spawns a review agent, waits for verdict + - `advisory`: spawns a review agent, posts findings, merges regardless + - `off`: skips review entirely + +7. **Act on verdict** — if `REVIEW_GATE` is `ai` and the review finds CRITICAL issues, `/ship` stops and asks you to fix them. Otherwise, it merges the PR. + +8. **Post-merge** — in two-branch mode, applies `QA_READY_LABEL` to the linked issue if configured. Reports next steps based on your branching model. + +## Reviewer selection + +`/ship` adds reviewers from exactly two sources: + +- **CODEOWNERS file** — checked in `CODEOWNERS`, `.github/CODEOWNERS`, and `docs/CODEOWNERS`. GitHub automatically requests reviews from code owners. +- **`DEFAULT_REVIEWERS` config** — comma-separated handles or team slugs added to the PR. + +The agent never infers reviewers from git history, blame, or team membership. + +## Review gate modes + +| Mode | Review happens? | Blocks merge? | Use case | +|---|---|---|---| +| `ai` | Yes | Yes, on CRITICAL findings | Default. Full review-gated development. | +| `advisory` | Yes | No | Review posts findings but merges anyway. Good for fast iteration with visibility. | +| `off` | No | N/A | No review. Merges immediately after checks pass. | + +## Why it's built this way + +**Single command for the full pipeline.** The check-commit-push-PR-review-merge sequence is mechanical and error-prone when done manually. `/ship` automates the entire chain while keeping a human gate (the review) in the middle. + +**Mandatory check gate.** `CHECK_CMD` must pass before anything is committed or pushed. This prevents known-broken code from ever reaching a PR. + +**Issue linking varies by mode.** In trunk mode, `Closes #N` auto-closes issues on merge because the PR targets the default branch. In multi-branch mode, `Issue #N` keeps issues open until `/release` promotes to production — this supports QA workflows where you want to track issues through the staging environment. + +**QA label automation.** In two-branch mode, `/ship` applies `QA_READY_LABEL` to signal that a feature is ready for testing on the preview environment. This feeds into the `/qa` skill's queue view. + +## Config keys used + +- `CHECK_CMD` — lint/type-check gate +- `MERGE_CMD` — merge command for feature PRs +- `REVIEW_GATE` — controls review behavior (`ai`, `advisory`, `off`) +- `REVIEW_AGENT_PROMPT` — path to the review agent system prompt +- `DEFAULT_REVIEWERS` — auto-assigned PR reviewers +- `QA_READY_LABEL` — label applied in two-branch mode after merge +- `BRANCH_PROD`, `BRANCH_DEV`, `BRANCH_TEST` — determine PR target and issue reference format diff --git a/docs/skills/start.md b/docs/skills/start.md new file mode 100644 index 0000000..0fa9b2c --- /dev/null +++ b/docs/skills/start.md @@ -0,0 +1,93 @@ +# /start + +Start a new feature or resume an existing issue. + +**Source prompt:** [`../../skills/start.md`](../../skills/start.md) + +## What it does + +`/start` is the entry point for all work in Code Cannon. It has two modes: + +- **New work** (text description) — reads the codebase, proposes an implementation approach, waits for human approval, creates a GitHub issue and linked feature branch, then writes the code. +- **Resume** (issue number) — loads an existing issue's context and comments, summarizes what was done and what remains, then picks up where work left off. + +There is no path for committing code without an issue. The issue is the unit of work — the branch, PR, and commit history all link back to it. + +## Usage + +``` +/start Add dark mode toggle to settings page +/start Fix the 404 on the Contact Us footer link +/start 42 +``` + +### Inline flags + +You can append flags after the description to override label and milestone selection: + +``` +/start Add dark mode --label enhancement +/start Add dark mode --label enhancement,ux --milestone "Sprint 4" +/start Fix login bug --milestone sprint-4 +``` + +- `--label ` / `-l ` — use these labels verbatim instead of auto-selecting from the configured pool +- `--milestone ` / `-m ` — use this milestone instead of the configured default or auto-detection + +Flags replace auto-selection entirely; they do not append. + +## Step-by-step: new work + +1. **Investigate** — the agent reads relevant code and proposes a concrete implementation approach, specifying which files change and how. + +2. **Human gate** — the agent asks: *"Does this approach sound right? I'll create a GitHub issue and branch before writing any code."* Nothing happens until you confirm. + +3. **Create GitHub issue** — runs `gh issue create` with a descriptive title, human-readable body, and resolved labels/milestone. Posts a technical implementation plan as an issue comment. + +4. **Create feature branch** — runs `gh issue develop` to create a `feature/*` branch linked to the issue in GitHub. Verifies the branch before proceeding. + +5. **Write the code** — implements the approach. Does NOT commit. Hands off to you: *"The code is ready for review. Please run your dev command and test locally."* + +## Step-by-step: resume existing issue + +1. **Load context** — reads the issue body, all comments, and any prior agent implementation notes. + +2. **Summarize and gate** — tells you what the issue is about, what was done, and what remains. Asks if this matches your understanding. + +3. **Check out branch** — finds or creates the linked feature branch. + +4. **Write the code** — continues from where work left off. Does NOT commit. + +## Label resolution + +Labels are resolved in a three-tier order: + +1. **Per-invocation flag** — `--label` value used verbatim +2. **Pool selection** — agent picks 1-3 fitting labels from `TICKET_LABELS` config +3. **No label** — if the pool is empty or nothing fits, the label is omitted (or a new one is created if `TICKET_LABEL_CREATION_ALLOWED` is `true`) + +## Milestone resolution + +Milestones are resolved in a three-tier order: + +1. **Per-invocation flag** — `--milestone` value used verbatim +2. **Config default** — `DEFAULT_MILESTONE` from `.codecannon.yaml` +3. **Auto-detect** — queries GitHub for open milestones: uses a single milestone silently, prompts when multiple exist, omits when none exist + +## Why it's built this way + +**Issue-first workflow.** Every piece of work starts with an issue. This creates traceability from idea through branch, PR, and release. It also means `/start` can be used to create well-formed tickets without writing any code — useful for non-developers or planning sessions. + +**Human gate before creation.** The agent proposes an approach and waits. This prevents wasted work on the wrong approach and gives you a chance to redirect before any GitHub artifacts are created. + +**No commits during /start.** Code is written but not committed. This is intentional — the human testing loop between `/start` and `/ship` is where you catch things the agent missed. Committing happens in `/ship` after you've verified the code locally. + +**Branch linking via `gh issue develop`.** Instead of `git checkout -b`, Code Cannon uses `gh issue develop` so the branch is linked to the issue in GitHub's UI. This makes it easy to find the branch from the issue and vice versa. + +## Config keys used + +- `DEV_CMD` — suggested to the user for local testing after code is written +- `ABANDON_CMD` — suggested if the user wants to scrap the work +- `TICKET_LABELS` — label pool for auto-selection +- `TICKET_LABEL_CREATION_ALLOWED` — whether new labels can be created on the fly +- `DEFAULT_MILESTONE` — default milestone for new issues diff --git a/docs/skills/status.md b/docs/skills/status.md new file mode 100644 index 0000000..1a846ef --- /dev/null +++ b/docs/skills/status.md @@ -0,0 +1,60 @@ +# /status + +Read-only snapshot of open PRs, recently merged work, and open issues. + +**Source prompt:** [`../../skills/status.md`](../../skills/status.md) + +## What it does + +`/status` generates a standup-style summary from GitHub data. It classifies work into three buckets — in progress, done, and up next — by cross-referencing open PRs, merged PRs, and open issues. + +It also supports a milestone mode for sprint-level views. + +## Usage + +``` +/status # your work, last 7 days +/status 14 # your work, last 14 days +/status @alice # alice's work, last 7 days +/status @alice 14 # alice's work, last 14 days +/status --milestone "Sprint 4" # all issues in Sprint 4 +/status --sprint "Sprint 4" # same (alias) +``` + +## Personal mode (default) + +Fetches three things in parallel: + +- **Open PRs** authored by the subject +- **Recently merged PRs** within the lookback window +- **Open issues** assigned to the subject + +Then classifies items: + +- **In progress** — open PRs, with linked issues identified from PR bodies +- **Done** — merged PRs within the lookback window +- **Up next** — open issues with no associated open PR + +Open issues that are linked from an open PR appear under "In progress", not "Up next". + +## Milestone mode + +When `--milestone` or `--sprint` is passed, `/status` fetches all issues in that milestone and classifies them by cross-referencing with open PRs: + +- **Done** — closed issues +- **In progress** — open issues referenced in an open PR body +- **Not started** — open issues with no associated open PR + +Shows a progress summary: "X of Y issues closed, Z in progress, W not started." + +## Why it's built this way + +**Read-only, always.** `/status` never writes to GitHub — no comments, labels, or issue updates. It's safe to run at any time without side effects. + +**Cross-referenced classification.** Rather than relying on labels or project board columns, `/status` infers work state from the relationship between PRs and issues. An open issue with a linked open PR is "in progress" — no manual status tracking needed. + +**Useful outside development.** `/status` generates standup summaries from GitHub data. It's valuable for project managers, team leads, or anyone who wants to see what's happening without reading code. + +## Config keys used + +None. `/status` uses only `gh` CLI commands and git log. It works with any Code Cannon configuration. diff --git a/docs/skills/version.md b/docs/skills/version.md new file mode 100644 index 0000000..eb570fd --- /dev/null +++ b/docs/skills/version.md @@ -0,0 +1,56 @@ +# /version + +Bump the project version, tag, and push. + +**Source prompt:** [`../../skills/version.md`](../../skills/version.md) + +## What it does + +`/version` reads the current version, asks what kind of bump you want, runs the appropriate bump command, and pushes both the commit and the tag. Run it after features are merged and before deploying. + +## Usage + +``` +/version +``` + +No arguments. Must be run from the correct branch (determined by your branching model). + +## Step-by-step + +1. **Verify branch** — checks that you're on the required pre-production branch: + - **Trunk mode:** `BRANCH_PROD` + - **Two-branch mode:** `BRANCH_DEV` + - **Three-branch mode:** `BRANCH_TEST` + + Aborts if on the wrong branch. + +2. **Read current version** — runs `VERSION_READ_CMD` to display the current version. + +3. **Ask the user** — presents bump options with computed values: + - **major** (e.g. 1.2.3 -> 2.0.0) + - **minor** (e.g. 1.2.3 -> 1.3.0) + - **patch** (e.g. 1.2.3 -> 1.2.4) + - or set a specific version + +4. **Run bump command** — maps your choice to the appropriate command (`BUMP_PATCH_CMD`, `BUMP_MINOR_CMD`, `BUMP_MAJOR_CMD`, or `SET_VERSION_CMD`). These commands are expected to update the version file, create a commit, and create a tag. + +5. **Push** — pushes the commit and the tag to the remote. + +6. **Report** — tells you the new version and next steps based on your branching model. + +## Why it's built this way + +**Separate from /release.** Version bumping and release promotion are distinct steps. You might bump the version and deploy to a preview environment for testing before deciding to promote to production. Keeping them separate supports this QA workflow. + +**Branch enforcement.** `/version` runs from the pre-production branch, not from a feature branch. This ensures the version bump happens after features are merged and the integration branch is stable. + +**Bump commands are external.** Code Cannon doesn't implement version bumping itself — it delegates to your project's Makefile or scripts. This keeps the skill generic across different version file formats (package.json, VERSION file, setup.py, etc.). + +## Config keys used + +- `VERSION_READ_CMD` — prints the current version +- `BUMP_PATCH_CMD`, `BUMP_MINOR_CMD`, `BUMP_MAJOR_CMD` — semver bump commands +- `SET_VERSION_CMD` — set an arbitrary version +- `DEPLOY_PREVIEW_CMD` — suggested for deploying to preview after version bump +- `BRANCH_PROD`, `BRANCH_DEV`, `BRANCH_TEST` — determine which branch `/version` must run from