From 22c61f7f9145cb7dba5fa7c1587f1ce701ef55ac Mon Sep 17 00:00:00 2001 From: Sebastien Taggart Date: Sat, 11 Apr 2026 10:14:28 -0400 Subject: [PATCH] Update docs for recent features and simplify README into a marketing page --- README.md | 92 ++++++++------------------------ docs/index.md | 2 +- docs/skills/start.md | 17 ++++-- docs/skills/submit-for-review.md | 4 +- 4 files changed, 39 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index 0177c8c..7535f6f 100644 --- a/README.md +++ b/README.md @@ -2,123 +2,75 @@ # Code Cannon -A portable agent workflow skill library. Write your team's development workflow once — start, submit-for-review, review, deploy — and sync it to Claude Code, Cursor, and other AI coding agents across all your projects. - -Repository: [github.com/LightbridgeLab/CodeCannon](https://github.com/LightbridgeLab/CodeCannon) +Write your team's AI agent workflow once — start, submit-for-review, review, deploy — and sync it to Claude Code, Cursor, Gemini, and Codex across all your projects. ## The problem -AI coding agents are powerful, but every project reinvents the same workflows: how to create issues, open PRs, run reviews, bump versions, deploy releases. These instructions live in scattered prompt files, maintained per-project, per-agent, with no consistency and no reuse. +AI coding agents are powerful, but every project reinvents the same workflows: how to create issues, open PRs, run reviews, deploy releases. These instructions live in scattered prompt files, maintained per-project, per-agent, with no consistency and no reuse. ## The solution -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. +Code Cannon is a shared skill library that lives as a git submodule. Skills are written once as portable markdown. A sync script reads your project config and generates agent-specific command files: ``` skills/*.md → sync.sh + .codecannon.yaml → .claude/commands/*.md → .cursor/rules/*.mdc ``` -One source of truth. Every project. Every agent. +One source of truth for every project and every agent. ## What you get -**A complete development workflow in five commands:** +A complete development workflow in five commands: ``` /start → [code + test] → /submit-for-review → [QA] → /deploy ``` -- `/start` — creates a GitHub issue, feature branch, and writes code (with human approval before any work begins) -- `/submit-for-review` — checks, commits, opens PR, runs AI review, merges -- `/review` — standalone code review on any PR -- `/deploy` — bumps version, creates a GitHub Release, promotes to production -- `/status` — standup-ready snapshot of PRs, issues, and progress +| Command | What it does | +|---|---| +| `/start` | Create a GitHub issue, feature branch, and write code | +| `/submit-for-review` | Check, commit, open PR, run AI review, merge | +| `/review` | Standalone code review on any PR | +| `/deploy` | Bump version, create a GitHub Release, promote to production | +| `/status` | Standup-ready snapshot of PRs, issues, and progress | Plus `/qa` for structured QA workflows and `/setup` for guided onboarding. +![Code Cannon Agents Working With Humans](.github/assets/readme-inline-agents-working-with-humans.png) + ## Philosophy -**Humans stay in the loop.** The agent proposes; you approve. `/start` waits for your sign-off before creating anything. `/deploy` requires explicit confirmation. The agent commits; you test. +**Humans stay in the loop.** The agent proposes; you approve. `/start` waits for your sign-off before creating anything. `/deploy` requires explicit confirmation. **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. -## GitHub baseline for PM/BA setup - -If your repo is new and you want predictable behavior from `/start` and `/qa`, configure a minimal GitHub baseline before day-to-day usage: - -- **Starter labels for issue intake:** `bug`, `enhancement`, `chore`, `documentation` -- **QA lifecycle labels:** `ready-for-qa`, `qa-passed`, `qa-failed` -- **Optional planning labels:** a single priority scheme (for example `priority:high`, `priority:medium`, `priority:low`) - -How this maps to Code Cannon behavior: - -- `/start` uses `TICKET_LABELS` as its allowed label pool when creating issues. -- `/qa` depends on `QA_READY_LABEL` to build the QA queue and applies `QA_PASSED_LABEL` or `QA_FAILED_LABEL` as verdicts. -- Milestones can stay dynamic (auto-detected from GitHub open milestones) or be pinned using `DEFAULT_MILESTONE` when your team runs fixed iterations (for example `Sprint 12` or `Release 2026.04`). - -For first-time setup, run `/setup`; it can populate labels and walk through these options interactively. - -**Reviewer selection is never automatic.** `/submit-for-review` 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. - -**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. - -**Agent-agnostic.** Skills are written once. Adapters handle the translation to Claude Code, Cursor, or any future agent. - -![Code Cannon Agents Working With Humans](.github/assets/readme-inline-agents-working-with-humans.png) +**Configure, don't fork.** Skills use `{{PLACEHOLDER}}` tokens. Your `.codecannon.yaml` fills them in. When upstream improves, pull the submodule and re-sync. ## Quick start ```bash -# Add Code Cannon to your project git submodule add https://github.com/LightbridgeLab/CodeCannon.git CodeCannon -git submodule update --init - -# Create and edit your config cp CodeCannon/templates/codecannon.yaml .codecannon.yaml - -# Generate skill files CodeCannon/sync.sh ``` -To update Code Cannon to the latest version, run from your project root: - -```bash -CodeCannon/sync.sh --update -``` - -This pulls the latest `main` in the CodeCannon checkout and regenerates your project's skill files in one step. If the CodeCannon checkout is on a branch other than `main`, `--update` stops with a message — update it manually and re-run `sync.sh` without `--update`. +Then optionally run `/setup` for a guided walkthrough. -If you installed Code Cannon as a git submodule, you can instead pin to the new commit: +To update to the latest version: ```bash -git submodule update --remote CodeCannon -git add CodeCannon -git commit -m "Update CodeCannon submodule to latest" -CodeCannon/sync.sh +CodeCannon/sync.sh --update ``` -Or run `/setup` for a guided walkthrough that detects your project state and configures everything interactively. - ## Documentation -- **[Getting started](docs/index.md)** — detailed overview, full quickstart, migration guide +- **[Getting started](docs/index.md)** — full quickstart, migration guide, and workflow details - **[Branching models](docs/branching.md)** — trunk, two-branch, and three-branch workflows -- **[Customization](docs/customization.md)** — tailoring skills to your project, sync.sh reference +- **[Customization](docs/customization.md)** — tailoring skills, 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 - -### Skill reference - -| Skill | Docs | Description | -|---|---|---| -| `/start` | [docs](docs/skills/start.md) | Create a GitHub issue, branch, and write code | -| `/submit-for-review` | [docs](docs/skills/submit-for-review.md) | Check, commit, open PR, review, merge | -| `/review` | [docs](docs/skills/review.md) | Standalone code review on a PR | -| `/deploy` | [docs](docs/skills/deploy.md) | Bump version, create GitHub Release, promote to production | -| `/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 | +- **Skill reference:** [/start](docs/skills/start.md) · [/submit-for-review](docs/skills/submit-for-review.md) · [/review](docs/skills/review.md) · [/deploy](docs/skills/deploy.md) · [/qa](docs/skills/qa.md) · [/status](docs/skills/status.md) · [/setup](docs/skills/setup.md) ## License diff --git a/docs/index.md b/docs/index.md index 9d92188..6202157 100644 --- a/docs/index.md +++ b/docs/index.md @@ -29,9 +29,9 @@ The intended sequence for a complete change: Code Cannon is opinionated about where humans stay in the loop: - `/start` pauses before creating the issue to confirm the implementation approach. +- `/submit-for-review` pauses after review if there are non-blocking findings, letting you choose to address them or merge now. - `/deploy` 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 `/submit-for-review`. The human approval loop before shipping is where you catch things the agent missed. diff --git a/docs/skills/start.md b/docs/skills/start.md index db2c2db..2fbab94 100644 --- a/docs/skills/start.md +++ b/docs/skills/start.md @@ -40,9 +40,20 @@ Flags replace auto-selection entirely; they do not append. 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. +2. **Human gate** — the agent asks: *"Does this approach sound right? Type `go` to create a GitHub issue and branch, or share any questions/adjustments first."* The agent uses intent classification (not keyword matching) to interpret your response: + - **Affirmative with no conditions** ("go", "yes", "looks good") → proceeds + - **Affirmative with conditions** ("go, but first change X") → treats as discussion, addresses conditions, re-asks + - **Questions or pushback** ("what about...", "I'm not sure") → discusses, revises, re-asks + - **Abandonment** ("never mind", "stop") → stops with nothing to clean up -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. +3. **Create GitHub issue** — runs `gh issue create` with a descriptive title, structured body, and resolved labels/milestone. The issue body contains five required sections: + - **Problem to Fix** — what is broken or missing, in plain language + - **Why it Matters** — the impact or motivation + - **General Approach** — high-level direction for the fix + - **Complexity** — verification/QA effort rating (trivial, moderate, significant, or extensive) with a one-line justification + - **Acceptance Criteria** — specific, verifiable outcomes + + After the issue is created, a technical implementation plan is posted 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. @@ -52,7 +63,7 @@ Flags replace auto-selection entirely; they do not append. 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. +2. **Summarize and gate** — tells you what the issue is about, what was done, and what remains. Uses the same intent classification as new work to interpret your response. 3. **Check out branch** — finds or creates the linked feature branch. diff --git a/docs/skills/submit-for-review.md b/docs/skills/submit-for-review.md index 1d2c1f7..73dc060 100644 --- a/docs/skills/submit-for-review.md +++ b/docs/skills/submit-for-review.md @@ -37,9 +37,9 @@ No arguments. `/submit-for-review` operates on the current branch. - `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, `/submit-for-review` stops and asks you to fix them. Otherwise, it merges the PR. +7. **Act on verdict** — if `REVIEW_GATE` is `ai` and the review finds CRITICAL issues, `/submit-for-review` stops and asks you to fix them. If the review approves but includes non-blocking findings (warnings or notes), a human gate asks whether you want to address them first or merge now. -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. +8. **Post-merge** — in two-branch mode, applies `QA_READY_LABEL` to the linked issue if configured. Posts a resolution comment to the linked issue summarizing what was done in plain language (written for non-technical audiences like PMs or QA). Reports next steps based on your branching model. ## Reviewer selection