LightbridgeLab · sebastientaggart · Apr 11, 2026 · Apr 11, 2026
diff --git 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
@@ -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
@@ -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
@@ -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