setup

Detect state

Before taking any action, determine which state the project is in. Run these checks in order.

Check A — Is this the Code Cannon skill library repo itself?

test -f sync.py
test -d skills

If both exist at the working directory root → go to State 1.

Check B — Is there any Code Cannon submodule presence?

test -d CodeCannon

grep -q CodeCannon .gitmodules

(A successful match means .gitmodules exists and references CodeCannon.) If either check is true → go to State 2.

Check C — State 1 fallback

If .codecannon.yaml is absent AND neither CodeCannon/ nor .gitmodules exist → go to State 1.

Otherwise → go to State 2.

State 1 — Just checking it out

Do not configure anything. Do not touch any file.

Tell the user warmly that Code Cannon is designed to live as a submodule inside another project — running /setup here in the Code Cannon repo itself isn't the intended path.

Offer two forward paths and ask which they want:

Path A — "I want to understand how Code Cannon works"

Explain the three-layer model:

• Skills (skills/<group>/<name>/SKILL.md) — portable workflow instructions in the Agent Skills folder format, with main-style tokens for project-specific values (see config.schema.yaml)
• Config (.codecannon.yaml) — a project's values that fill those tokens at sync time
• Sync (sync.py) — reads the config, substitutes values, and writes generated Agent Skills folders for each adapter (Claude Code → .claude/skills/, Codex CLI / Cursor / Gemini CLI → .agents/skills/)

Point to README.md for the full skill list and documentation. Do not touch any file.

Path B — "I want to add Code Cannon to my project"

Show the exact command sequence:

cd /path/to/your-project
git submodule add https://github.com/LightbridgeLab/CodeCannon.git CodeCannon
git submodule update --init
cp CodeCannon/templates/codecannon.yaml .codecannon.yaml
# Edit .codecannon.yaml — set branch names, commands, adapters
CodeCannon/sync.py

Do not touch any file. The user runs these commands in their project directory.

State 2 — Partial or broken setup

Run checks 1–7 in order. Stop at the first failing check and address it. After describing the fix, tell the user to run /setup again once they've resolved it. Do not continue past a failing check.

Check 1 — CodeCannon/sync.py present

test -f CodeCannon/sync.py

If missing: the submodule was added to .gitmodules or CodeCannon/ exists as an empty directory, but it hasn't been initialized. Show:

git submodule update --init --recursive

Offer to run it. If the user agrees, run it. If they decline, tell them to run it manually before continuing. Stop.

Check 2 — gh installed

which gh

If not found: "gh is required by all Code Cannon skills. Install it with brew install gh (macOS) or from https://cli.github.com." Cannot proceed without it. Stop.

Check 3 — gh authenticated

gh auth status

If exit code is non-zero: "You're not authenticated with GitHub." Show:

gh auth login

Cannot proceed without it. Stop.

Check 4 — Inside a GitHub repository

gh repo view --json name

If exit code is non-zero: warn that most skills require a GitHub remote. Skills can be read and configured, but /start, /submit-for-review, /review, /deploy, and /status will fail without one. This is not a hard stop — ask if the user wants to continue configuring anyway.

Check 5 — .codecannon.yaml present

test -f .codecannon.yaml

If missing: "I'll create .codecannon.yaml from the template — you'll want to review the branch names and commands before running sync."

Show:

cp CodeCannon/templates/codecannon.yaml .codecannon.yaml

Ask permission to run it. If the user agrees, run it. If they decline, tell them to run it manually.

After creating the file, proceed immediately to Check 5b.

Check 5b — Profile selection (only on first setup)

This check runs only when Check 5 just created .codecannon.yaml from the template. If .codecannon.yaml already existed before this /setup invocation, skip to Check 6.

Ask the user:

"What level of process does this project need?"

1. Lightweight — Fast iteration. AI review is advisory, features merge to main, no QA workflow, and /start skips its approval gate and mandated issue structure.

2. Standard — Integration branch with AI-gated review. QA and milestones available but not required.

3. Governed — Full traceability. QA handoff, assigned reviewers, milestones, structured labels.

4. Custom — Configure each setting individually.

Pick a number, or describe your workflow and I'll recommend one.

Wait for response. If the user describes their situation instead of picking a number, recommend the best-fit profile and confirm before applying.

Apply profile values to .codecannon.yaml:

After the user selects a profile, ask the applicable follow-up questions from this list:

• "What's your production branch name?" (default: main) — ask for all profiles except Custom
• "What's your integration branch name?" (default: development) — ask for Standard and Governed only
• "Do you need a separate test/staging branch?" (default: staging) — ask for Governed only; if yes, ask for the branch name

Show every change before writing and ask "Apply these values to .codecannon.yaml? (yes/no)". Write only on yes.

All profiles leave REVIEW_EFFORT at its default (medium). It only tunes review depth on harnesses with a native review engine (a /code-review skill); raise it to high for higher-assurance projects or lower it to low to cut cost on low-stakes ones. It never changes the sensitive-area gate or the merge verdict.

After writing, say: "<Profile> profile applied. Check the workflow commands and run /setup again to finish configuration." Stop.

Check 6 — .codecannon.yaml stale values

Read .codecannon.yaml. Apply the following checks conservatively — only flag a value if you are confident it points to something that does not exist:

• If VERSION_READ_CMD references package.json and no package.json exists at the project root → flag it
• If BRANCH_DEV is set to a non-empty value and that branch does not appear in git branch -a → flag it
• If BRANCH_TEST is set to a non-empty value and that branch does not appear in git branch -a → flag it

If nothing is confidently broken, do not flag anything. When in doubt, do not flag.

If anything is flagged: show the specific key names and what they should likely be changed to. Do not modify the file. Tell the user to update these values and run /setup again. Stop.

Check 7 — Generated skill output present

Check whether sync.py has been run by looking for any of the adapter output directories configured in .codecannon.yaml:

test -d .claude/skills
test -d .agents/skills

If none exist: "sync.py hasn't been run yet — the skill commands don't exist."

Show:

CodeCannon/sync.py

Ask permission to run it. If the user agrees, run it. If they decline, tell them to run it manually before continuing. Stop.

State 3 — Everything configured

All checks pass. Run phases 1–4 in order.

Phase 1 — Health summary

Print one sentence confirming the setup looks healthy. Read .codecannon.yaml and infer the workflow profile for display:

• REVIEW_GATE is "advisory" or "off" AND BRANCH_DEV is empty → Lightweight
• REVIEW_GATE is "ai" AND BRANCH_DEV is set AND QA_READY_LABEL is empty → Standard
• REVIEW_GATE is "ai" AND QA_READY_LABEL is set → Governed
• Anything else → Custom

Check whether the configured dev/test branches exist in the remote (skip checks for empty values):

git show-ref --quiet --verify refs/remotes/origin/<BRANCH_DEV value>
git show-ref --quiet --verify refs/remotes/origin/<BRANCH_TEST value>

Confirm the setup is healthy and show a scannable summary — lay it out however reads clearly. Include the inferred profile, the core workflow values (BRANCH_PROD; BRANCH_DEV and BRANCH_TEST, each with whether it exists in the remote; REVIEW_GATE; START_APPROVAL_GATE ("true" default / "false"); ISSUE_FULL_STRUCTURE ("true" default / "false"); CHECK_CMD; MERGE_CMD; and the configured adapters), and then each optional config value reported as set or unset: DEFAULT_MILESTONE, DEFAULT_REVIEWERS, TICKET_LABELS (with label count when set), TICKET_LABEL_CREATION_ALLOWED, the QA labels, PLATFORM_COMPLIANCE_NOTES, CONVENTIONS_NOTES, SENSITIVE_AREAS_GATE ("true" default / "false"), and SENSITIVE_AREAS_CATEGORIES (custom list / default 5-category list).

A value counts as "set" if it is present, uncommented, and non-empty in .codecannon.yaml.

Phase 2 — Permission audit

Check whether the agent's permission configuration covers the shell commands Code Cannon skills use. Read the commands: list in CodeCannon/permissions.yaml for the required command prefixes. Use only the commands: key — commands under validate_only: (e.g. cd) are deliberately never emitted as allow rules, so they must not be reported as missing.

If the harness you are running in reads its permission allowlist from .claude/settings.json: Decide this from what you know about your own harness — the file existing in the project is not evidence, because sync commits it for the claude adapter regardless of which agent is running. Read .claude/settings.local.json (if it exists) and .claude/settings.json (if it exists). Collect all Bash(...) entries from the permissions.allow arrays in both files. For each prefix in commands:, check whether an allow rule covers it (e.g. Bash(git:*) or Bash(git *) covers git).

If all prefixes are covered, display Agent permissions: all skill commands pre-approved and continue to Phase 3.

If any are missing, report them as Bash(<cmd>:*) allow rules the user can optionally add to .claude/settings.local.json (git-ignored) or .claude/settings.json (shared with team) — pointing at docs/index.md for a full example — and note that commands can also be approved individually when prompted. Do not modify any settings file. This is advisory only.

Otherwise: Skip this phase silently — permission systems vary by harness.

Phase 3 — Commit signing

Check whether commit signing is already configured at any level (local or global):

git config --get commit.gpgsign

If the output is true, display Commit signing: enabled in the health summary area and skip to Phase 4.

If not true, ask: "Does this project require signed commits? (yes/no)"

Wait for response.

• no / skip → continue to Phase 4.
• yes → proceed with signing setup.

Verify a signing key exists:

git config --get user.signingkey

If a signing key is found, show the proposed change — enabling commit.gpgsign and tag.gpgsign for this repo, and naming the signing key — then ask "Proceed? (yes/no)". Wait for confirmation. Write only on yes. If no, skip to Phase 4. Otherwise continue to Phase 4.

If no signing key is found, detect the signing format:

git config --get gpg.format

• If ssh → suggest: git config user.signingkey ~/.ssh/id_ed25519.pub (adjust path to the user's key). Ask the user for their SSH public key path.
• If gpg or unset → suggest: run gpg --list-secret-keys --keyid-format=long to find a key ID. Ask the user for their GPG key ID.

Once the user provides a key value, show the proposed changes — setting user.signingkey to the provided key and enabling commit.gpgsign and tag.gpgsign — then ask "Proceed? (yes/no)". Wait for confirmation. Write only on yes. If no, skip to Phase 4.

If the user has no signing key and doesn't know how to create one, point them to GitHub's signing key documentation and stop: "Set up a signing key first, then run /setup again to enable commit signing."

Phase 4 — Label population

Run:

gh label list --limit 100 --json name,color,description

If zero labels are found, treat this as a greenfield repository. Present the starter baseline — bug, enhancement, chore, documentation, ready-for-qa, qa-passed, qa-failed — and ask: "Create any missing labels from this baseline now? (yes/no)"

• yes → run the label-create script with exactly those seven names:

  python3 CodeCannon/skills/github-agile/scripts/label-create.py bug enhancement chore documentation ready-for-qa qa-passed qa-failed

  The script applies sensible color/description defaults from a baked-in table and warns-and-continues on any name that already exists.
• no / skip / anything else → continue without creating labels.

Configured-label audit

Whether or not the greenfield baseline ran, audit the labels that configured skills will try to apply at runtime against what actually exists in the repo:

python3 CodeCannon/skills/github-agile/scripts/label-audit.py

The script reads .codecannon.yaml, collects the names referenced by TICKET_LABELS plus QA_READY_LABEL / QA_PASSED_LABEL / QA_FAILED_LABEL (skipping any that are unset), diffs against gh label list, and prints missing names — one per line — on stdout. A one-line diagnostic goes to stderr.

• No stdout output → all configured labels exist. Continue silently to the "Display the results" step below.
• One or more names on stdout → show them as a combined list and ask once: "These labels are referenced by your configured skills but don't exist in the repo: <list>. Create them now? (yes/no)"
  • yes → run python3 CodeCannon/skills/github-agile/scripts/label-create.py <name1> <name2> ... with the missing names from the audit output.
  • no / skip → continue, but at the end of Phase 4 print a one-line summary: "Skipped creating: <list>. /submit-for-review will warn and continue if it needs to apply a missing label; /qa and /start may degrade similarly."

After this step (or if labels were non-zero initially), re-run the same gh label list fetch to pick up any labels just created.

If TICKET_LABELS is unset or fewer than 5 labels exist, add a note: "/start works best with a clear issue-label pool (TICKET_LABELS), and /qa needs explicit QA lifecycle labels (ready-for-qa, qa-passed, qa-failed). Consider a lightweight priority scheme (e.g. priority:high, priority:medium, priority:low) if the team needs triage support. If the team runs planned iterations, set DEFAULT_MILESTONE in Phase 5; otherwise leave it unset so /start auto-detects."

Display the available labels as a numbered list (name — description, with the count found) so the user can pick by number, then ask: "Write these label names to .codecannon.yaml as TICKET_LABELS? (yes / no / list specific numbers)"

Wait for the user's response.

• yes → use all labels
• numbers (e.g. 1,3,5) → use only those labels
• no / skip / anything else → skip this phase, continue to Phase 5

Show the exact change before writing — the TICKET_LABELS line as it will appear in .codecannon.yaml — and ask "Proceed? (yes/no)". Wait for confirmation. Write only on yes.

Phase 5 — Optional config walkthrough (profile-aware)

First, infer the current profile using the same rules as Phase 1.

The walkthrough adapts based on profile. Walk through each applicable unset value in the order shown. Skip any value already set. If the user says "skip", move on without modifying the file and do not ask again.

Common pattern for simple values (DEFAULT_MILESTONE, DEFAULT_REVIEWERS, TICKET_LABEL_CREATION_ALLOWED): explain in one sentence, show the example value, ask. If the user provides a value, show the exact YAML change and ask "Write this to .codecannon.yaml? (yes/no)". Write only on yes.

Common pattern for drafted values (PLATFORM_COMPLIANCE_NOTES, CONVENTIONS_NOTES): ask what technologies/conventions apply, draft 2–4 concise checkable rules, show the draft, iterate until the user approves or skips. On approval, show the exact YAML change, confirm, write only on yes.

Lightweight skips DEFAULT_MILESTONE, DEFAULT_REVIEWERS, and TICKET_LABEL_CREATION_ALLOWED — those are intentionally unset.

Phase 6 — Team sharing

After completing or skipping the config walkthrough, say:

"To share this setup with your team, commit these files. Anyone who clones the project and runs git submodule update --init will have all skills ready — no further setup needed."

Show the exact command:

git add .codecannon.yaml .claude/ CodeCannon AGENTS.md

Add a note: /start can be used to create well-formed GitHub issues without writing any code — useful for non-developers tracking work. /status generates standup summaries from open issues and PRs — both are valuable outside of a development workflow.

Hard rules

• Only modify .codecannon.yaml and local git config (Phase 3 signing setup). Do not touch any other file (except running CodeCannon/sync.py, which modifies the generated skills directories — permitted only with explicit user approval).
• Do not run sync.py without explicit user permission.
• Do not create .codecannon.yaml without explicit user permission.
• Do not report a configuration problem unless confident the condition is genuinely broken. Prefer false negatives over false positives on all diagnostic checks.
• Never fetch more than 100 labels in a single command. gh label list --limit 100 is the ceiling.
• Do not skip any human gate in Phase 3, Phase 4, or Phase 5 — each write requires confirmation.
• If the user skips a config value, do not ask again. Move on.