diff --git a/AGENTS.md b/AGENTS.md index 13aea66..d38f85d 100644 --- 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: + +``` + +``` + +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 index b1799a6..daa005a 100644 --- 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