AGENTS.md — CodeCannon

Instructions for AI coding agents working on the CodeCannon project itself.

CodeCannon is a skill distribution system. It stores generic agent workflow skills in skills/, adapter configs in adapters/, and a sync.py script that generates agent-specific skill files for downstream projects. One source of truth, synced to every project and every AI agent.

Branch strategy

feature/* → dev → main

• main — published releases. Never push directly.
• dev — integration branch. Never push directly.
• feature/* — short-lived. Branch from dev, PR back to dev.

Where things live

Use this section to orient yourself. Do not search for files when the answer is here.

Source skills (edit here)

skills/<group>/<name>/SKILL.md   Skill source folders — YAML frontmatter + markdown body
                         Each <group> is a domain-specific bundle (e.g. github-agile)
                         A project enables exactly one group via skill_group: in .codecannon.yaml

These are the single source of truth for all generated output. Every edit to agent workflows starts here.

Generated output (never edit)

.claude/skills/<name>/SKILL.md   Claude Code project skills
.agents/skills/<name>/SKILL.md   Shared Agent Skills output (Codex CLI, Cursor, Gemini CLI)

These are regenerated by ./sync.py. Each file contains a hash marker for change detection. If you need to change agent output, edit the source skill under skills/<group>/ and re-run sync.

Adapters

adapters/claude/         config.yaml — Claude Code adapter (.claude/skills/)
adapters/agents/         config.yaml — shared adapter (.agents/skills/) for Codex CLI, Cursor, Gemini CLI
adapters/codex/          config.yaml — legacy alias → agents
adapters/cursor/         config.yaml — legacy alias → agents
adapters/gemini/         config.yaml — legacy alias → agents

Each adapter has a config.yaml (output directory, agent name, argument_hint flag, optional permissions_file, notes). Output follows the Agent Skills standard, so no per-tool headers or format translation exist anymore; a config may instead declare alias: <adapter> to resolve to another adapter.

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.py                  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 design philosophy

CodeCannon's skills were first written for a generation of models that needed to be told not just what outcome to produce but how to produce it — how to parse an argument string, what date format to use, which emoji maps to which CI state. Capable agents do all of that well unaided. Procedural over-specification no longer buys reliability; it burns context, crowds out the instructions that matter, and blocks a capable agent from doing something smarter than the author imagined.

Every instruction in a skill must pass one test:

Prune where model variance produces a different-but-fine result. Keep where model variance produces a wrong result.

• Prune side — report formatting, argument tokenizing, investigation method, output templates, badge-to-emoji mappings. A differently-shaped-but-correct result is harmless, so hand the agent the intent and the inputs, not the procedure.
• Keep side — ordering guarantees, human approval gates (and their exact wording), platform behaviour the model cannot derive, review policy, and the prompt-avoidance instructions (--body-file / no-heredoc / no-$(cat)). Variance in any of these is a defect, not a style difference.

Two categories look like removable noise when read quickly but are load-bearing — never weaken them:

• Prompt-avoidance guidance. The --body-file and no-heredoc blocks exist because embedding markdown in a shell command triggers permission prompts that cannot be permanently allowed. State the rule once here and point at it; do not restate it per skill and do not soften it.
• Platform-behaviour notes. Facts like "unqualified #N populates closingIssuesReferences", "Closes is inert on non-default-branch merges", and "gh issue develop --base reads from the API, not local working state" are knowledge a model has no way to derive. Keep them verbatim.

Calibrate the prune against the weakest supported harness and model size, not the strongest. Skills ship to several adapters and a range of model sizes; trusting the agent as far as the best available model would under-serve everyone else. The cost of variance decides where the line sits — not the capability of the strongest model.

story.md is the reference shape: overwhelmingly what rather than how, with business rules collected under a ## Hard rules section at the end and procedure written only where sequencing genuinely matters. Converge older skills toward it.

Backend capability claims

Never commit a statement about what a specific agent backend can or cannot do — in skills, adapter configs, or docs. "Tool X does not support sub-agents" is true the day it is written and wrong within months; nothing fails when it goes stale, so it stays wrong until someone happens to notice.

• Phrase capability-conditionally. Ask the running agent about itself: "If sub-agent spawning is supported: … If it is not: …" (/review Step 2 is the reference). No "(e.g. Tool X)" parentheticals naming which backend falls on which side.
• Mechanics vs availability. Adapter notes: and docs/adapters.md describe invocation mechanics — where files land, how a skill is triggered, which config file a tool reads. Those are slow-moving facts about the integration. Feature availability is a fast-moving fact about the vendor; leave it out.
• No capability matrix, in any form. A corrected table is the same liability with a later expiry date.

Skill anatomy

Each skill in skills/ is an Agent Skills folder — skills/<group>/<name>/SKILL.md:

---
name: start                     # Spec-required; must match the directory name
type: skill                     # "skill" (invocable) or "prompt" (non-invocable)
description: "Start a feature"  # Spec-required; rendered into the output frontmatter
args: "description text"        # What arguments the skill accepts (emitted as
                                # argument-hint for adapters that support it)
# Optional:
# output_path_override: path    # Render as a bare file (no frontmatter) at this path
---

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.

Conditional blocks

Skills support conditional rendering:

{{#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.py embeds an MD5 hash in a marker comment at the end of each generated file:

<!-- generated by CodeCannon/sync.py | skill: start | adapter: claude | hash: a1b2c3d4 | DO NOT EDIT -->

If someone manually edits a generated file, the hash won't match and sync.py will refuse to overwrite it (unless run with --force).

Working on CodeCannon

Make targets

The primary commands for working on this project:

Editing a skill

1. Edit the source file under skills/<group>/ (this repo currently uses skills/github-agile/).
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

Most tools that support Agent Skills read .agents/skills/ already — check whether the agents adapter covers the tool before adding one.

1. Create adapters/{name}/config.yaml — set agent and output_directory (the tool's project skills directory).
2. Test with ./sync.py --skill start.
3. Document invocation mechanics in config.yaml under notes — never feature availability (see Backend capability claims).
4. Update docs/adapters.md.

Adding a new skill

1. Create skills/<group>/{name}/SKILL.md with frontmatter (name, type, description, args). Use the group that matches the skill's domain.
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

This repo is the only project that runs sync as ./sync.py instead of CodeCannon/sync.py. Every consumer project uses the submodule path — this is the exception.

• Edit-test loop: edit a skill under skills/<group>/ → make check → make dev → make sync → commit source + generated files together.
• All adapter outputs are generated: after editing a skill, make sync regenerates .claude/skills/ and .agents/skills/. Commit both.
• Never edit generated files directly — edit the source skill under skills/<group>/ and re-run make sync.

What agents must never do

• Push directly to main or dev.
• Edit generated files (.claude/skills/, .agents/skills/) — edit the source skill under skills/<group>/ instead.
• Add project-specific content to skills/<group>/ — 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

skills/                  source skill folders (edit here) — <group>/<name>/SKILL.md
adapters/                per-agent adapter configs
  claude/                  Claude Code (.claude/skills/)
  agents/                  Codex CLI, Cursor, Gemini CLI (.agents/skills/)
  codex/ cursor/ gemini/   legacy aliases → agents
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.py                  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