From 9f0793774317ce3f1c06673e3066637136a2372b Mon Sep 17 00:00:00 2001 From: Sebastien Taggart Date: Wed, 25 Mar 2026 09:23:16 -0400 Subject: [PATCH] Add greenfield GitHub baseline guide for PM/BA setup Document label and milestone expectations for /start and /qa in README and setup skill; add template comments. Regenerate Claude commands. Require git pull before /version step. Made-with: Cursor --- .claude/commands/qa.md | 4 ++-- .claude/commands/release.md | 22 ++++++++--------- .claude/commands/setup.md | 48 ++++++++++++++++++++++++++++++++++++- .claude/commands/ship.md | 14 +++++------ .claude/commands/version.md | 13 ++++++---- README.md | 16 +++++++++++++ skills/setup.md | 46 +++++++++++++++++++++++++++++++++++ skills/version.md | 5 ++++ templates/codecannon.yaml | 7 ++++++ 9 files changed, 150 insertions(+), 25 deletions(-) diff --git a/.claude/commands/qa.md b/.claude/commands/qa.md index a5b76af..374cbf1 100644 --- a/.claude/commands/qa.md +++ b/.claude/commands/qa.md @@ -1,10 +1,10 @@ - + You are executing the `/qa` skill. Your argument is: $ARGUMENTS --- diff --git a/.claude/commands/release.md b/.claude/commands/release.md index 58c4a53..ac670af 100644 --- a/.claude/commands/release.md +++ b/.claude/commands/release.md @@ -1,4 +1,4 @@ - + You are executing the `/release` skill. Your argument is: $ARGUMENTS --- @@ -17,9 +17,9 @@ git branch --show-current ``` **Determine mode:** -- If `` is empty → **Trunk Mode**. Follow the Trunk Mode section below. -- If `` is set but `` is empty → **Two-Branch Mode**. Follow the Two-Branch Mode section below. -- If both `` and `` are set → **Three-Branch Mode**. Follow the Three-Branch Mode section below. +- If `dev` is empty → **Trunk Mode**. Follow the Trunk Mode section below. +- If `dev` is set but `` is empty → **Two-Branch Mode**. Follow the Two-Branch Mode section below. +- If both `dev` and `` are set → **Three-Branch Mode**. Follow the Three-Branch Mode section below. --- @@ -116,9 +116,9 @@ Tell the user: ### Step 1 — Verify state -If not on ``, switch to it: +If not on `dev`, switch to it: ```bash -git checkout && git pull +git checkout dev && git pull ``` Verify a version tag exists on HEAD: @@ -130,9 +130,9 @@ If no tag is found, warn: "No version tag found on HEAD. Run `/version` first to ### Step 2 — Compute what's being promoted -Find all merge commits in `` not yet in `main`: +Find all merge commits in `dev` not yet in `main`: ```bash -git log main.. --merges --pretty=format:"%s" +git log main..dev --merges --pretty=format:"%s" ``` Parse PR numbers from the merge commit subjects. GitHub's format is: @@ -169,10 +169,10 @@ Have you tested all of the above on preview? Type 'release' to confirm. Wait for the user to type "release" or an explicit confirmation. Any other response → stop and ask what they'd like to change. -### Step 4 — Create PR: `` → `main` +### Step 4 — Create PR: `dev` → `main` ```bash -gh pr create --base main --head \ +gh pr create --base main --head dev \ --title "Release vX.Y.Z" \ --body "$(cat <<'EOF' Release vX.Y.Z @@ -260,7 +260,7 @@ Find all merge commits in `` not yet in `main`: git log main.. --merges --pretty=format:"%s" ``` -Parse PR numbers from the merge commit subjects. Note: some merge commits here may be promotion merges from `` — these are identifiable by subjects matching "Merge ... from ``". Include them in the list but note they are promotion merges; extract the original feature PRs from their PR bodies when possible. +Parse PR numbers from the merge commit subjects. Note: some merge commits here may be promotion merges from `dev` — these are identifiable by subjects matching "Merge ... from `dev`". Include them in the list but note they are promotion merges; extract the original feature PRs from their PR bodies when possible. For each PR number found, retrieve the PR body: ```bash diff --git a/.claude/commands/setup.md b/.claude/commands/setup.md index 0fed24b..385a988 100644 --- a/.claude/commands/setup.md +++ b/.claude/commands/setup.md @@ -1,4 +1,4 @@ - + You are executing the `/setup` skill. Your argument is: $ARGUMENTS --- @@ -281,6 +281,30 @@ Run: gh label list --limit 100 --json name,color,description ``` +If zero labels are found, treat this as a greenfield repository and offer a starter label baseline before asking about `TICKET_LABELS`. + +Show this recommendation: + +``` +No labels were found. For new projects, a practical baseline is: + - bug + - enhancement + - chore + - documentation + - ready-for-qa + - qa-passed + - qa-failed +``` + +Ask: **"Create any missing labels from this baseline now? (yes/no)"** + +Wait for response. + +- **yes** → create missing labels only (do not recreate existing labels). Use sensible colors and short descriptions. +- **no / skip / anything else** → continue without creating labels. + +After this step (or if labels were non-zero initially), run `gh label list --limit 100 --json name,color,description` again and continue with the numbered list flow below. + Display the results as a numbered list: ``` @@ -328,6 +352,28 @@ The walkthrough adapts based on profile. Walk through each applicable unset opti --- +### Greenfield GitHub baseline guidance (for PM/BA setup) + +Before the value walkthrough, provide this mini guide when either condition is true: +- `TICKET_LABELS` is unset, or +- fewer than 5 labels exist in the repository. + +Keep it short and practical: + +1. Explain that `/start` works best with a clear issue-label pool (`TICKET_LABELS`) and `/qa` needs explicit QA lifecycle labels. +2. Recommend this baseline label set for new projects: + - Work intake: `bug`, `enhancement`, `chore`, `documentation` + - QA lifecycle: `ready-for-qa`, `qa-passed`, `qa-failed` + - Optional planning: one lightweight priority scheme (for example `priority:high`, `priority:medium`, `priority:low`) +3. Explain milestone guidance: + - If the team runs planned iterations, set `DEFAULT_MILESTONE` (example: `Sprint 12` or `Release 2026.04`). + - If not, leave it unset so `/start` auto-detects open milestones and prompts only when needed. +4. End with: "Want me to help apply this baseline now during setup? (yes/no)" + +If user says no, continue immediately with the normal walkthrough. + +--- + **DEFAULT_MILESTONE** (Governed and Custom only) "Sets the default milestone applied to every issue `/start` creates — skip if you're not using milestones or prefer auto-detect." diff --git a/.claude/commands/ship.md b/.claude/commands/ship.md index 249eb63..67a58c2 100644 --- a/.claude/commands/ship.md +++ b/.claude/commands/ship.md @@ -1,4 +1,4 @@ - + You are executing the `/ship` skill. Your argument is: $ARGUMENTS --- @@ -24,7 +24,7 @@ git branch --show-current Determine which branches are protected (i.e., not a feature branch): - Always: `main` -- If `` is non-empty: also `` +- If `dev` is non-empty: also `dev` - If `` is non-empty: also `` If the current branch matches any of the above, **abort immediately** and say: @@ -89,7 +89,7 @@ git ls-files CODEOWNERS .github/CODEOWNERS docs/CODEOWNERS 2>/dev/null If the output is non-empty, inform the user: "CODEOWNERS file detected — GitHub will automatically request reviews from code owners." Determine the PR target branch: -- If `` is non-empty, target `` (two-branch or three-branch mode). +- If `dev` is non-empty, target `dev` (two-branch or three-branch mode). - Otherwise, target `main` (trunk mode). Determine the issue reference format: @@ -132,7 +132,7 @@ Wait for the review agent to complete and report its verdict. ## Step 7 — Act on verdict Determine merge command (used by all paths below): -- If in **trunk mode** (`` is empty): use `gh pr merge --merge` directly — `make merge` may refuse merges targeting `main`. +- If in **trunk mode** (`dev` is empty): use `gh pr merge --merge` directly — `make merge` may refuse merges targeting `main`. - Otherwise: use `make merge`. --- @@ -169,7 +169,7 @@ Return to the coding loop. When fixed, run `/ship` again from Step 1. ### After merge — QA label and success report -Apply the QA label only in **two-branch mode** (`` is set AND `` is empty): +Apply the QA label only in **two-branch mode** (`dev` is set AND `` is empty): - If `` is non-empty AND a linked issue number was identified in Step 3: ``` gh issue edit --add-label "" @@ -180,7 +180,7 @@ Apply the QA label only in **two-branch mode** (`` is set AND `` is empty): Report success based on mode: - **Trunk mode**: "PR merged. Issue #N closed automatically. Run `make deploy-prod` when ready to deploy to production." - **Two-branch mode**: "PR merged. Issues stay open until testing confirms the fix. Run `make deploy-preview` when ready to deploy to preview." -- **Three-branch mode**: "PR merged to ``. Promote to `` when ready for staging." +- **Three-branch mode**: "PR merged to `dev`. Promote to `` when ready for staging." --- @@ -190,5 +190,5 @@ Report success based on mode: - When `ai` is `"ai"`, never merge if the review verdict is REQUEST CHANGES. - When `ai` is `"advisory"`, always merge after review completes, regardless of verdict. - When `ai` is `"off"`, skip the review agent entirely — merge immediately after checks pass. -- In trunk mode, merges target `main`. Otherwise, `/ship` merges only to `` — never directly to `` or `main`. +- In trunk mode, merges target `main`. Otherwise, `/ship` merges only to `dev` — never directly to `` or `main`. - If `make merge` fails for any reason, report it and stop — do not attempt workarounds. diff --git a/.claude/commands/version.md b/.claude/commands/version.md index cbb3322..0816511 100644 --- a/.claude/commands/version.md +++ b/.claude/commands/version.md @@ -1,4 +1,4 @@ - + You are executing the `/version` skill. Your argument is: $ARGUMENTS --- @@ -12,11 +12,16 @@ git branch --show-current Determine the required branch: - If `` is non-empty → required branch is `` (three-branch mode). -- Else if `` is non-empty → required branch is `` (two-branch mode). +- Else if `dev` is non-empty → required branch is `dev` (two-branch mode). - Else → required branch is `main` (trunk mode). If not on the required branch, abort and say: "Switch to `` before running `/version`." +Pull the latest changes before proceeding: +```bash +git pull +``` + --- ## Step 2 — Read current version @@ -72,6 +77,6 @@ Both the version bump commit and the tag must be pushed. Tell the user the new version and tag: Report based on mode: -- **Trunk mode** (`` empty): "Tagged vX.Y.Z. Run `/release` to create the GitHub Release." -- **Two-branch mode** (`` set, `` empty): "Tagged vX.Y.Z. Run `make deploy-preview` to deploy to preview for testing. When testing is complete, run `/release`." +- **Trunk mode** (`dev` empty): "Tagged vX.Y.Z. Run `/release` to create the GitHub Release." +- **Two-branch mode** (`dev` set, `` empty): "Tagged vX.Y.Z. Run `make deploy-preview` to deploy to preview for testing. When testing is complete, run `/release`." - **Three-branch mode** (both set): "Tagged vX.Y.Z. Run `make deploy-preview` to deploy to staging. When testing is complete, run `/release`." diff --git a/README.md b/README.md index cc2ea86..abca813 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,22 @@ These aren't rigid modes — they're starting points. Every setting is independe **Milestone assignment is automatic.** When `/start` creates an issue it resolves the active milestone in order: per-invocation `--milestone` flag → `DEFAULT_MILESTONE` config → open milestones queried from GitHub. If one open milestone exists it's used silently; if multiple exist you're prompted once; if none exist the issue is created without one. Set `DEFAULT_MILESTONE` only if you want to pin a value and skip detection. +## GitHub baseline for PM/BA setup + +If your repo is new and you want predictable behavior from `/start` and `/qa`, configure a minimal GitHub baseline before day-to-day usage: + +- **Starter labels for issue intake:** `bug`, `enhancement`, `chore`, `documentation` +- **QA lifecycle labels:** `ready-for-qa`, `qa-passed`, `qa-failed` +- **Optional planning labels:** a single priority scheme (for example `priority:high`, `priority:medium`, `priority:low`) + +How this maps to Code Cannon behavior: + +- `/start` uses `TICKET_LABELS` as its allowed label pool when creating issues. +- `/qa` depends on `QA_READY_LABEL` to build the QA queue and applies `QA_PASSED_LABEL` or `QA_FAILED_LABEL` as verdicts. +- Milestones can stay dynamic (auto-detected from GitHub open milestones) or be pinned using `DEFAULT_MILESTONE` when your team runs fixed iterations (for example `Sprint 12` or `Release 2026.04`). + +For first-time setup, run `/setup`; it can populate labels and walk through these options interactively. + **Reviewer selection is never automatic.** `/ship` adds reviewers only from two sources: a detected `CODEOWNERS` file (checked in `CODEOWNERS`, `.github/CODEOWNERS`, and `docs/CODEOWNERS`) and the `DEFAULT_REVIEWERS` config key. The agent never infers reviewers from git history, blame, or team membership. **The agent commits; you test.** `/start` writes code but does not commit — it hands off to you with "run `DEV_CMD` and test locally." Committing happens in `/ship`. This is intentional: the human approval loop before shipping is where you catch things the agent missed. diff --git a/skills/setup.md b/skills/setup.md index 0caf79c..18f8938 100644 --- a/skills/setup.md +++ b/skills/setup.md @@ -283,6 +283,30 @@ Run: gh label list --limit 100 --json name,color,description ``` +If zero labels are found, treat this as a greenfield repository and offer a starter label baseline before asking about `TICKET_LABELS`. + +Show this recommendation: + +``` +No labels were found. For new projects, a practical baseline is: + - bug + - enhancement + - chore + - documentation + - ready-for-qa + - qa-passed + - qa-failed +``` + +Ask: **"Create any missing labels from this baseline now? (yes/no)"** + +Wait for response. + +- **yes** → create missing labels only (do not recreate existing labels). Use sensible colors and short descriptions. +- **no / skip / anything else** → continue without creating labels. + +After this step (or if labels were non-zero initially), run `gh label list --limit 100 --json name,color,description` again and continue with the numbered list flow below. + Display the results as a numbered list: ``` @@ -330,6 +354,28 @@ The walkthrough adapts based on profile. Walk through each applicable unset opti --- +### Greenfield GitHub baseline guidance (for PM/BA setup) + +Before the value walkthrough, provide this mini guide when either condition is true: +- `TICKET_LABELS` is unset, or +- fewer than 5 labels exist in the repository. + +Keep it short and practical: + +1. Explain that `/start` works best with a clear issue-label pool (`TICKET_LABELS`) and `/qa` needs explicit QA lifecycle labels. +2. Recommend this baseline label set for new projects: + - Work intake: `bug`, `enhancement`, `chore`, `documentation` + - QA lifecycle: `ready-for-qa`, `qa-passed`, `qa-failed` + - Optional planning: one lightweight priority scheme (for example `priority:high`, `priority:medium`, `priority:low`) +3. Explain milestone guidance: + - If the team runs planned iterations, set `DEFAULT_MILESTONE` (example: `Sprint 12` or `Release 2026.04`). + - If not, leave it unset so `/start` auto-detects open milestones and prompts only when needed. +4. End with: "Want me to help apply this baseline now during setup? (yes/no)" + +If user says no, continue immediately with the normal walkthrough. + +--- + **DEFAULT_MILESTONE** (Governed and Custom only) "Sets the default milestone applied to every issue `/start` creates — skip if you're not using milestones or prefer auto-detect." diff --git a/skills/version.md b/skills/version.md index 8eff018..35a372f 100644 --- a/skills/version.md +++ b/skills/version.md @@ -19,6 +19,11 @@ Determine the required branch: If not on the required branch, abort and say: "Switch to `` before running `/version`." +Pull the latest changes before proceeding: +```bash +git pull +``` + --- ## Step 2 — Read current version diff --git a/templates/codecannon.yaml b/templates/codecannon.yaml index 1b73214..820ef1d 100644 --- a/templates/codecannon.yaml +++ b/templates/codecannon.yaml @@ -55,6 +55,13 @@ config: REVIEW_AGENT_PROMPT: .claude/review-agent-prompt.md # ── GitHub / PR settings ───────────────────────────────────────────────────── + # Greenfield quick baseline (PM/BA friendly): + # 1) Labels: bug, enhancement, chore, documentation, ready-for-qa, qa-passed, qa-failed + # 2) Put work-intake labels in TICKET_LABELS so /start can triage new issues consistently. + # 3) Set QA_READY_LABEL / QA_PASSED_LABEL / QA_FAILED_LABEL if you want /qa status labeling. + # 4) Set DEFAULT_MILESTONE only when you want all /start tickets pinned by default + # (for example "Sprint 12" or "Release 2026.04"); otherwise leave it unset for auto-detect. + # # Comma-separated GitHub handles or team slugs assigned as PR reviewers by /ship. # Accepts usernames (@alice), team slugs (org/team-name), or combinations. # Leave empty (or omit) to rely solely on CODEOWNERS or manual assignment.