Skip to content

index.md

Latest commit

 

History

History
161 lines (110 loc) · 6.66 KB

index.md

File metadata and controls

161 lines (110 loc) · 6.66 KB
Raw

Code Cannon Documentation

Code Cannon is 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.

How it works

  1. Skills live in skills/ as plain markdown with {{PLACEHOLDER}} tokens for project-specific values.
  2. sync.py 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.py can detect manual edits and warn before overwriting.

The workflow

The intended sequence for a complete change:

/start  →  [code + local test]  →  /submit-for-review  →  [QA on preview]  →  /deploy
  • /start — reads code, proposes an approach, waits for human approval, then creates the issue, branch, and writes code
  • /submit-for-review — runs checks, commits everything, pushes, opens the PR, spawns an agent review, merges if approved
  • /review — standalone review on any PR; also called internally by /submit-for-review
  • /deploy — bumps version, creates a GitHub Release, promotes to production
  • /status — read-only snapshot of open PRs, merged work, and open issues
  • /qa — view the QA queue or record findings on a specific issue
  • /setup — 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.
  • /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.

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.

Quickstart

Requires Python 3.8+ (stdlib only — no pip install needed).

1. Add Code Cannon as a submodule

git submodule add https://github.com/LightbridgeLab/CodeCannon.git CodeCannon
git submodule update --init

2. Create your project config

cp CodeCannon/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 for all available settings.

3. Run sync

CodeCannon/sync.py

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)

cp CodeCannon/templates/AGENTS.md.template AGENTS.md

Edit the project-specific section at the bottom.

5. Add Makefile targets (optional)

# In your Makefile
include CodeCannon/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

git submodule update --remote CodeCannon   # pull latest skills
CodeCannon/sync.py                         # regenerate skill files

If any generated files have been manually customized, sync.py 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/CodeCannon.git and use submodule path CodeCannon/ (or rename your existing checkout to match).
  2. Rename .agentgate.yaml to .codecannon.yaml.
  3. Run CodeCannon/sync.py --force once if needed so generated file headers match the new provenance marker.

Agent tips and tweaks

Code Cannon skills are agent-agnostic, but each agent has its own quirks. This section collects per-agent configuration tips that smooth out the experience.

Claude Code

Reduce approval prompts. Claude Code prompts for permission on unfamiliar shell commands. Pre-approve the commands Code Cannon uses by adding a permissions block to .claude/settings.json (project-level, committed) or .claude/settings.local.json (personal, git-ignored):

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(cd:*)",
      "Bash(git:*)",
      "Bash(gh:*)",
      "Bash(make:*)",
      "Bash(python3:*)",
      "Bash(./sync.py:*)",
      "Bash(mkdir:*)",
      "Bash(mktemp:*)"
    ],
    "deny": [
      "Bash(git push --force)",
      "Bash(git push --force:*)",
      "Bash(git reset --hard)",
      "Bash(git reset --hard:*)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ]
  }
}

defaultMode: "acceptEdits" auto-approves file edits and common filesystem ops. allow rules pre-approve matching bash commands (wildcards supported). deny rules always win — dangerous operations still prompt. Adjust the allow list to match your project's tooling.

Cursor

Cursor does not prompt for shell commands by default, so no permission configuration is needed. Skills work out of the box.

Codex

Configure via the codex CLI's --full-auto flag or sandbox settings. Codex runs in a sandboxed environment, so approval prompts are less common but network access may need to be explicitly enabled for gh commands.

Gemini CLI

Configure via .gemini/settings.json or the --auto-approve flag. Consult Gemini CLI documentation for the latest permission options.

Further reading

  • Branching models — trunk, two-branch, and three-branch workflows explained
  • Customization guide — how to tailor skills to your project
  • Config reference — every .codecannon.yaml placeholder documented
  • Adapters — supported agents and how to add new ones
  • Individual skill documentation — see links in the workflow section above