LightbridgeLab · sebastientaggart · Mar 27, 2026 · Mar 27, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,74 +1,225 @@
-# AGENTS.md — Code Cannon
+# AGENTS.md — CodeCannon
 
-Instructions for AI coding agents working on the Code Cannon project itself.
+Instructions for AI coding agents working on the CodeCannon project itself.
 
-Code Cannon is a skill distribution system. It stores generic agent workflow skills in `skills/`, adapter configs in `adapters/`, and a `sync.sh` script that generates agent-specific skill files for downstream projects.
+CodeCannon is a skill distribution system. It stores generic agent workflow skills in `skills/`, adapter configs in `adapters/`, and a `sync.sh` script that generates agent-specific skill files for downstream projects. One source of truth, synced to every project and every AI agent.
 
-## Branch Strategy
+## Branch strategy
 
 ```
-feature/* → development → main
+feature/* → dev → main
 ```
 
 - `main` — published releases. Never push directly.
-- `development` — integration. Never push directly.
-- `feature/*` — short-lived. Branch from `development`, PR back.
+- `dev` — integration branch. Never push directly.
+- `feature/*` — short-lived. Branch from `dev`, PR back to `dev`.
 
-## Working on Code Cannon
+## Where things live
 
-### Editing skills
+Use this section to orient yourself. Do not search for files when the answer is here.
 
-Skills live in `skills/*.md`. Each file has YAML frontmatter followed by the skill body. Placeholder tokens use `{{UPPERCASE_NAME}}` syntax and are documented in `config.schema.yaml`.
+### Source skills (edit here)
 
-When editing a skill:
-1. Edit the `.md` file in `skills/`.
-2. Test locally by running sync against the APrimeforYou project (a known consumer): `cd ../APrimeforYou && CodeCannon/sync.sh --dry-run`
-3. Verify generated output looks correct before committing.
+```
+skills/*.md              Skill source files — YAML frontmatter + markdown body
+```
 
-### Adding a new adapter
+These are the single source of truth for all generated output. Every edit to agent workflows starts here.
 
-1. Create `adapters/{name}/config.yaml` — set `output_directory` and `output_extension`.
-2. Create `adapters/{name}/header.md` — the invocation header template. Use `{skill}` and `{description}` as placeholders.
-3. Test with `sync.sh --skill start` against a test project.
-4. Document any adapter limitations in `config.yaml` under `notes`.
+### Generated output (never edit)
+
+```
+.claude/commands/*.md    Claude Code slash commands
+.cursor/rules/*.mdc      Cursor agent rules
+.agents/skills/          Codex / legacy agent skills
+.gemini/skills/          Gemini agent skills
+```
+
+These are regenerated by `./sync.sh`. Each file contains a hash marker for change detection. If you need to change agent output, edit the source skill in `skills/` and re-run sync.
+
+### Adapters
+
+```
+adapters/claude/         config.yaml + header.md — Claude Code adapter
+adapters/cursor/         config.yaml + header.md — Cursor adapter
+adapters/codex/          config.yaml + header.md — Codex adapter
+adapters/gemini/         config.yaml + header.md — Gemini adapter
+```
+
+Each adapter has a `config.yaml` (output directory, file extension, agent name, notes) and a `header.md` (invocation header template using `{skill}` and `{description}` placeholders).
+
+### Configuration
+
+```
+.codecannon.yaml         This project's own config (adapters list + placeholder values)
+config.schema.yaml       Canonical documentation for every placeholder
+templates/codecannon.yaml  Template config for consumer projects to copy
+```
+
+### Documentation
+
+```
+docs/index.md            Getting started and overview
+docs/branching.md        Trunk, two-branch, and three-branch workflow docs
+docs/customization.md    Tailoring skills to a project
+docs/config-reference.md Every .codecannon.yaml setting explained
+docs/adapters.md         Supported agents and how to add new ones
+docs/skills/*.md         Per-skill documentation (start, deploy, qa, etc.)
+README.md                User-facing overview and quick start
+```
+
+When asked to update documentation, check `docs/` first — most detailed docs live there, not in README.md.
+
+### Build and workflow
+
+```
+Makefile                 CodeCannon-specific targets (sync, versioning, deployment)
+Makefile.agents.mk       Generic git workflow targets (branch, pr, abandon, merge, promote)
+sync.sh                  The core sync engine (Python 3)
+VERSION                  Current version number (plain text, e.g. 0.3.3)
+```
+
+### Project meta
+
+```
+AGENTS.md                This file — instructions for agents working on CodeCannon
+ROADMAP.md               Future ideas and planned work
+.codecannon.yaml         Project config (also listed under Configuration)
+```
+
+## Skill anatomy
+
+Each skill in `skills/` follows this structure:
+
+```yaml
+---
+skill: start                    # Identifier (becomes the filename)
+type: skill                     # "skill" (slash command) or "prompt" (non-invocable)
+description: "Start a feature"  # Human-readable, used in adapter headers
+args: "description text"        # What arguments the skill accepts
+# Optional:
+# output_path_override: path    # Override default output location
+# no_invocation_header: true    # Skip the auto-generated header
+---
 
-### Adding a new placeholder
+Markdown body with instructions...
+```
+
+### Placeholders
 
+Use `{{UPPERCASE_NAME}}` syntax. All placeholders are documented in `config.schema.yaml` with descriptions, defaults, and which skills use them.
+
+To add a new placeholder:
 1. Add it to `config.schema.yaml` with description, default, and `used_in` list.
 2. Add it with its default value to `templates/codecannon.yaml`.
 3. Use `{{PLACEHOLDER_NAME}}` in the relevant skill files.
 
-### Testing sync.sh
+### Conditional blocks
+
+Skills support conditional rendering:
 
-```bash
-cd /path/to/a/consumer/project
-../CodeCannon/sync.sh --dry-run       # verify output paths and content
-../CodeCannon/sync.sh                 # generate for real
 ```
+{{#if BRANCH_TEST}}
+  Content shown only when BRANCH_TEST has a value
+{{/if}}
+
+{{#if !BRANCH_TEST}}
+  Content shown only when BRANCH_TEST is empty
+{{/if}}
+```
+
+### Change detection
+
+`sync.sh` embeds an MD5 hash in a marker comment at the end of each generated file:
+
+```
+<!-- generated by CodeCannon/sync.sh | skill: start | adapter: claude | hash: a1b2c3d4 | DO NOT EDIT -->
+```
+
+If someone manually edits a generated file, the hash won't match and `sync.sh` will refuse to overwrite it (unless run with `--force`).
+
+## Working on CodeCannon
+
+### Make targets
+
+The primary commands for working on this project:
+
+| Command | What it does |
+|---------|-------------|
+| `make check` | Validate that all skill placeholders resolve against config |
+| `make dev` | Preview what sync would generate (dry run, no file writes) |
+| `make sync` | Regenerate all adapter output from `skills/` |
+| `make branch name=X` | Create `feature/X` from `dev` |
+| `make pr` | Push current branch and open PR to `dev` |
+| `make merge` | Merge current PR into `dev` |
+| `make abandon` | Discard changes and delete current feature branch |
+| `make bump-patch` | Bump version patch segment, commit, and tag |
+
+### Editing a skill
+
+1. Edit the source file in `skills/`.
+2. Run `make check` to validate placeholders.
+3. Run `make dev` to preview generated output.
+4. Run `make sync` to regenerate all adapter output.
+5. Commit the skill source **and** the regenerated files together in the same PR.
+
+### Adding a new adapter
+
+1. Create `adapters/{name}/config.yaml` — set `agent`, `output_directory`, and `output_extension`.
+2. Create `adapters/{name}/header.md` — invocation header template using `{skill}` and `{description}`.
+3. Test with `./sync.sh --skill start`.
+4. Document any adapter limitations in `config.yaml` under `notes`.
+5. Update `docs/adapters.md`.
+
+### Adding a new skill
+
+1. Create `skills/{name}.md` with frontmatter (`skill`, `type`, `description`, `args`).
+2. Add any new placeholders to `config.schema.yaml` and `templates/codecannon.yaml`.
+3. Run `make check` and `make dev` to verify.
+4. Run `make sync` to generate output for all adapters.
+5. Create `docs/skills/{name}.md` with user-facing documentation.
+
+## Self-hosting: using CodeCannon to develop CodeCannon
 
-## Self-hosting: using Code Cannon to develop Code Cannon
+This repo is the only project that runs sync as `./sync.sh` instead of `CodeCannon/sync.sh`. Every consumer project uses the submodule path — this is the exception.
 
-- **Sync path exception**: agents working on this repo run `./sync.sh`, not `CodeCannon/sync.sh`. Every consumer project uses `CodeCannon/sync.sh` via the submodule path — this repo is the only exception.
-- **Edit-test loop**: edit a skill in `skills/` → `make check` to validate placeholders → `make dev` to preview generated output → commit and `/submit-for-review`.
-- **Re-run sync after skill edits**: after changing any file in `skills/`, run `./sync.sh` to regenerate `.claude/commands/`. Commit the updated generated files in the same PR as the skill source change.
-- **Never edit `.claude/commands/` directly** — those files are generated. Edit the source skill in `skills/` and re-run sync.
+- **Edit-test loop**: edit a skill in `skills/` → `make check` → `make dev` → `make sync` → commit source + generated files together.
+- **All adapter outputs are generated**: after editing a skill, `make sync` regenerates `.claude/commands/`, `.cursor/rules/`, `.agents/skills/`, and `.gemini/skills/`. Commit all of them.
+- **Never edit generated files directly** — edit the source skill in `skills/` and re-run `make sync`.
 
-## What Agents Must Never Do
+## What agents must never do
 
-- Push directly to `main` or `development`
-- Edit generated files in consumer projects — edit the source skill instead
-- Add project-specific content to `skills/` — skills must remain generic (use placeholders)
+- Push directly to `main` or `dev`.
+- Edit generated files (`.claude/commands/`, `.cursor/rules/`, `.agents/skills/`, `.gemini/skills/`) — edit the source skill in `skills/` instead.
+- Add project-specific content to `skills/` — skills must remain generic. Use `{{PLACEHOLDER}}` tokens for anything project-specific.
+- Commit skill source changes without also committing the regenerated output (`make sync`).
+- Invent placeholder names — check `config.schema.yaml` for the canonical list.
 
-## Project Layout
+## Project layout
 
 ```
-skills/           source skill files (edit here)
-adapters/         per-agent adapter configs and header templates
-templates/        files for downstream projects to copy
-config.schema.yaml  placeholder documentation
-sync.sh           the installer / generator
-Makefile.agents.mk  generic git workflow Makefile targets
-AGENTS.md         this file
-README.md         human-facing docs
-.agents/          legacy workflow files (still functional for template-repo usage)
+skills/                  source skill files (edit here)
+adapters/                per-agent adapter configs and header templates
+  claude/                  Claude Code (.claude/commands/*.md)
+  cursor/                  Cursor (.cursor/rules/*.mdc)
+  codex/                   Codex (.agents/skills/)
+  gemini/                  Gemini (.gemini/skills/)
+templates/               files for downstream projects to copy
+  codecannon.yaml          template config
+docs/                    user-facing documentation
+  index.md                 getting started
+  branching.md             branch workflow strategies
+  customization.md         tailoring skills
+  config-reference.md      config setting reference
+  adapters.md              adapter documentation
+  skills/                  per-skill documentation
+config.schema.yaml       placeholder documentation (canonical)
+.codecannon.yaml         this project's config
+sync.sh                  the sync engine
+Makefile                 project-specific targets
+Makefile.agents.mk       generic git workflow targets
+VERSION                  current version
+AGENTS.md                this file
+README.md                user-facing overview
+ROADMAP.md               future ideas
 ```
diff --git a/README.md b/README.md
@@ -81,6 +81,14 @@ cp CodeCannon/templates/codecannon.yaml .codecannon.yaml
 CodeCannon/sync.sh
 ```
 
+To update Code Cannon to the latest version:
+
+```bash
+git submodule update --remote CodeCannon
+git add CodeCannon
+git commit -m "Update CodeCannon submodule to latest"
+```
+
 Or run `/setup` for a guided walkthrough that detects your project state and configures everything interactively.
 
 ## Documentation