From d52c2440d56c60a642b91bf35da3c984b0afa09f Mon Sep 17 00:00:00 2001 From: Sebastien Taggart Date: Thu, 26 Mar 2026 16:22:11 -0400 Subject: [PATCH 1/6] Add branch checkout before pull in deploy targets Co-Authored-By: Claude Opus 4.6 (1M context) --- Makefile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Makefile b/Makefile index 2995897..d1e56e2 100644 --- a/Makefile +++ b/Makefile @@ -90,10 +90,12 @@ endif # Push the integration branch for preview/testing. deploy-preview: + git checkout $(INTEGRATION_BRANCH) git pull --rebase origin $(INTEGRATION_BRANCH) git push origin $(INTEGRATION_BRANCH) # Publish a tagged release to production. deploy-prod: + git checkout $(PRODUCTION_BRANCH) git pull --rebase origin $(PRODUCTION_BRANCH) --tags git push origin $(PRODUCTION_BRANCH) --tags From 5eb24a300a52a8f0fd92ed7d57e30c65e9d2d19e Mon Sep 17 00:00:00 2001 From: Sebastien Taggart Date: Thu, 26 Mar 2026 17:06:10 -0400 Subject: [PATCH 2/6] Combine version and release skills into a single deploy skill Co-Authored-By: Claude Opus 4.6 (1M context) --- .agents/skills/deploy/SKILL.md | 238 ++++++++++++++++++++++ .agents/skills/release/SKILL.md | 155 --------------- .agents/skills/setup/SKILL.md | 7 +- .agents/skills/ship/SKILL.md | 4 +- .agents/skills/version/SKILL.md | 81 -------- .claude/commands/deploy.md | 233 ++++++++++++++++++++++ .claude/commands/release.md | 150 -------------- .claude/commands/setup.md | 7 +- .claude/commands/ship.md | 4 +- .claude/commands/version.md | 76 ------- .cursor/rules/deploy.mdc | 239 ++++++++++++++++++++++ .cursor/rules/release.mdc | 156 --------------- .cursor/rules/setup.mdc | 7 +- .cursor/rules/ship.mdc | 4 +- .cursor/rules/version.mdc | 82 -------- .gemini/skills/deploy/SKILL.md | 238 ++++++++++++++++++++++ .gemini/skills/release/SKILL.md | 155 --------------- .gemini/skills/setup/SKILL.md | 7 +- .gemini/skills/ship/SKILL.md | 4 +- .gemini/skills/version/SKILL.md | 81 -------- README.md | 16 +- config.schema.yaml | 26 +-- docs/branching.md | 21 +- docs/config-reference.md | 22 +-- docs/customization.md | 4 +- docs/index.md | 9 +- docs/skills/deploy.md | 69 +++++++ docs/skills/qa.md | 2 +- docs/skills/release.md | 53 ----- docs/skills/ship.md | 4 +- docs/skills/version.md | 56 ------ skills/{release.md => deploy.md} | 326 +++++++++++++++++-------------- skills/setup.md | 5 +- skills/ship.md | 2 +- skills/version.md | 98 ---------- templates/AGENTS.md.template | 11 +- 36 files changed, 1268 insertions(+), 1384 deletions(-) create mode 100644 .agents/skills/deploy/SKILL.md delete mode 100644 .agents/skills/release/SKILL.md delete mode 100644 .agents/skills/version/SKILL.md create mode 100644 .claude/commands/deploy.md delete mode 100644 .claude/commands/release.md delete mode 100644 .claude/commands/version.md create mode 100644 .cursor/rules/deploy.mdc delete mode 100644 .cursor/rules/release.mdc delete mode 100644 .cursor/rules/version.mdc create mode 100644 .gemini/skills/deploy/SKILL.md delete mode 100644 .gemini/skills/release/SKILL.md delete mode 100644 .gemini/skills/version/SKILL.md create mode 100644 docs/skills/deploy.md delete mode 100644 docs/skills/release.md delete mode 100644 docs/skills/version.md rename skills/{release.md => deploy.md} (56%) delete mode 100644 skills/version.md diff --git a/.agents/skills/deploy/SKILL.md b/.agents/skills/deploy/SKILL.md new file mode 100644 index 0000000..c1887ed --- /dev/null +++ b/.agents/skills/deploy/SKILL.md @@ -0,0 +1,238 @@ +--- +name: deploy +description: Bump the project version, create a GitHub Release, and promote to production — handles both versioning and releasing in one step +--- + +> **Codex CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — perform any review steps inline. + +--- + +## What `/deploy` does + +`/deploy` is the final step in the workflow. It combines version bumping and release creation into a single command: check state, optionally bump the version, then create a GitHub Release (and in multi-branch mode, promote to production). + +--- + +## Step 1 — Verify branch + +Run: +```bash +git branch --show-current +``` + +Required branch: `dev` (two-branch mode). + +If not on the required branch, abort and say: "Switch to `` before running `/deploy`." + +Pull the latest changes before proceeding: +```bash +git pull +``` + +--- + +## Step 2 — Check current state + +### Find the latest version tag + +```bash +git describe --tags --abbrev=0 2>/dev/null +``` + +If no tag exists, note this is the first release. + +### Read current version + +```bash +cat VERSION +``` + +### Show commits since last tag + +If a previous tag exists, show what's on the branch since that tag: + +```bash +git log main..dev --merges --pretty=format:"%s" +``` + +Parse PR numbers from merge commit subjects (format: `Merge pull request #N from branch/name`). + +For each PR number found, retrieve the PR body: +```bash +gh pr view --json number,title,body +``` + +Extract `Issue #N` and `Closes #N` references from PR bodies. Compile: +- List of PRs included (number + title) +- List of issues linked to those PRs + +### Check for open unmerged PRs + +```bash +gh pr list --state open --json number,title,headRefName --jq '.[] | "#\(.number) \(.title) (\(.headRefName))"' +``` + +### Present the summary + +Tell the user: + +``` +Current version: X.Y.Z +Latest tag: vX.Y.Z + +Commits/PRs since last tag: + #17 — Add /docs directory + #18 — Fix checkout runtime error + +Open PRs not yet merged: + #19 — Add dark mode (feature/dark-mode) + +Would you like to bump the version before deploying? + - **patch** → X.Y.C + - **minor** → X.B.0 + - **major** → A.0.0 + - **specific** → enter a version number + - **skip** → proceed to release with the current tag +``` + +Wait for their response. + +--- + +## Step 3 — Version bump (if requested) + +If the user chose to skip, verify a version tag exists on HEAD: +```bash +git describe --exact-match --tags HEAD 2>/dev/null +``` + +If no tag is found when skipping, warn: "No version tag found on HEAD. You must bump the version before deploying." Return to the version bump prompt. + +If the user chose a bump level, map their response to a command: + +| User says | Run | +|---|---| +| "patch" / anything mentioning patch | `make bump-patch` | +| "minor" | `make bump-minor` | +| "major" | `make bump-major` | +| A specific version e.g. "2.4.5" | `make set-version V= 2.4.5` | + +These commands update the version manifest, create a git commit, and create a git tag. Do not create commits or tags manually. + +Push the version bump: +```bash +git push +git push --tags +``` + +Both the version bump commit and the tag must be pushed. + +--- + +## Step 4 — Compute release contents + +Determine the version tag (either from the bump just performed, or from the existing HEAD tag if the user skipped bumping). + +Find the previous tag to determine the range: +```bash +git describe --abbrev=0 ^ 2>/dev/null +``` + +Use the PR/issue list already computed in Step 2. If the version bump added new commits, re-fetch if needed. + +--- + +## Step 5 — HUMAN GATE + +Show the user the release summary. Example format: + +``` +Ready to release vX.Y.Z to production. + +PRs included: + #17 — Add /docs directory + #18 — Fix checkout runtime error + +Issues that will close: + #14 — Add /docs directory + #15 — Fix checkout runtime error + +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 6 — Create PR: `dev` → `main` + +```bash +gh pr create --base main --head dev \ + --title "Release vX.Y.Z" \ + --body "$(cat <<'EOF' +Release vX.Y.Z + +PRs included: +- #17 — Add /docs directory +- #18 — Fix checkout runtime error + +Closes #14 +Closes #15 +EOF +)" +``` + +Note the PR number from the output. + +The `Closes #N` lines will auto-close the linked issues because this PR merges into `main` (the default branch). + +--- + +## Step 7 — Merge + +Do NOT use `make merge` — it refuses PRs targeting `main`. Use `gh pr merge` directly: + +```bash +gh pr merge --merge +``` + +--- + +## Step 8 — Create GitHub Release + +The version tag (from Step 3) and the PR/issue list (from Step 4) are already known. Find the previous tag to build the changelog link: + +```bash +git describe --abbrev=0 ^ 2>/dev/null +``` + +If no previous tag exists, omit the "Full changelog" line. + +Create the release: + +```bash +gh release create \ + --title "" \ + --notes "$(cat <<'EOF' +## Changes + +- # — (PR #) +[... one line per PR included in this release ...] + +**Full changelog:** https://github.com///compare/... +EOF +)" +``` + +Format each PR line as `- # — (PR #)`. If a PR had no linked issue, omit the `#` prefix and use just the PR title. + +After the command runs, note the release URL from the output. + +--- + +## Step 9 — Report + +Tell the user: + +> "Released vX.Y.Z. Issues #N, #M closed automatically. GitHub Release vX.Y.Z created at ``. Run `make deploy-prod` to ship to production." + diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md deleted file mode 100644 index 9f484f3..0000000 --- a/.agents/skills/release/SKILL.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -name: release -description: Create a GitHub Release; in multi-branch mode, also promotes the pre-production branch to `main` ---- - -> **Codex CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — perform any review steps inline. - ---- - -## What `/release` does - -Creates a GitHub Release and promotes `dev` to `main`. Run this after preview testing is confirmed. - ---- - -## Step 1 — Verify state - -Check the current branch: -```bash -git branch --show-current -``` - -### Verify on `dev` with tag - -If not on `dev`, switch to it: -```bash -git checkout dev && git pull -``` - -Verify a version tag exists on HEAD: -```bash -git describe --exact-match --tags HEAD 2>/dev/null -``` - -If no tag is found, warn: "No version tag found on HEAD. Run `/version` first to tag this release before promoting it." Stop unless the user explicitly says to proceed anyway. - ---- - -## Step 2 — Compute what's being promoted - -Find all merge commits in `dev` not yet in `main`: -```bash -git log main..dev --merges --pretty=format:"%s" -``` - -Parse PR numbers from the merge commit subjects. GitHub's format is: -`Merge pull request #N from branch/name` - -For each PR number found, retrieve the PR body: -```bash -gh pr view --json number,title,body -``` - -Extract `Issue #N` references from PR bodies (look for the pattern `Issue #\d+`). - -Compile: -- List of PRs being promoted (number + title) -- List of open issues linked to those PRs - ---- - -## Step 3 — HUMAN GATE - -Show the user the release summary. Example format: - -``` -Ready to release vX.Y.Z to production. - -PRs included: - #17 — Add /docs directory - #18 — Fix checkout runtime error - -Issues that will close: - #14 — Add /docs directory - #15 — Fix checkout runtime error - -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: `dev` → `main` - -```bash -gh pr create --base main --head dev \ - --title "Release vX.Y.Z" \ - --body "$(cat <<'EOF' -Release vX.Y.Z - -PRs included: -- #17 — Add /docs directory -- #18 — Fix checkout runtime error - -Closes #14 -Closes #15 -EOF -)" -``` - -Note the PR number from the output. - -The `Closes #N` lines will auto-close the linked issues because this PR merges into `main` (the default branch). - ---- - -## Step 5 — Merge - -Do NOT use `make merge` — it refuses PRs targeting `main`. Use `gh pr merge` directly: - -```bash -gh pr merge --merge -``` - ---- - -## Step 6 — Create GitHub Release - -The version tag (from Step 1) and the PR/issue list (from Step 2) are already known. Find the previous tag to build the changelog link: - -```bash -git describe --abbrev=0 ^ 2>/dev/null -``` - -If no previous tag exists, omit the "Full changelog" line. - -Create the release: - -```bash -gh release create \ - --title "" \ - --notes "$(cat <<'EOF' -## Changes - -- # — (PR #) -[... one line per PR included in this release ...] - -**Full changelog:** https://github.com///compare/... -EOF -)" -``` - -Format each PR line as `- # — (PR #)`. If a PR had no linked issue, omit the `#` prefix and use just the PR title. - -After the command runs, note the release URL from the output. - ---- - -## Step 7 — Report - -Tell the user: - -> "Released vX.Y.Z. Issues #N, #M closed automatically. GitHub Release vX.Y.Z created at ``. Run `make deploy-prod` to ship to production." - diff --git a/.agents/skills/setup/SKILL.md b/.agents/skills/setup/SKILL.md index 00daa2c..92f45c7 100644 --- a/.agents/skills/setup/SKILL.md +++ b/.agents/skills/setup/SKILL.md @@ -61,8 +61,7 @@ List the available skills: | `/start` | Creates a GitHub issue, feature branch, and writes code | | `/ship` | Checks, commits, opens PR, spawns review agent, merges | | `/review` | Standalone code review on any PR | -| `/version` | Bumps semver, tags, pushes | -| `/release` | Promotes integration branch to main, closes issues | +| `/deploy` | Bumps version, creates GitHub Release, promotes to production | | `/status` | Snapshot of open PRs and issues for the team | | `/setup` | This skill — configures Code Cannon in a project | @@ -131,7 +130,7 @@ Cannot proceed without it. Stop. 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`, `/ship`, `/review`, `/release`, and `/status` will fail without one. This is not a hard stop — ask if the user wants to continue configuring anyway. +If exit code is non-zero: warn that most skills require a GitHub remote. Skills can be read and configured, but `/start`, `/ship`, `/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 @@ -476,4 +475,4 @@ Add a note: `/start` can be used to create well-formed GitHub issues without wri - 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 2 or Phase 3 — each write requires confirmation. - If the user skips a config value, do not ask again. Move on. - + diff --git a/.agents/skills/ship/SKILL.md b/.agents/skills/ship/SKILL.md index d91120f..98026de 100644 --- a/.agents/skills/ship/SKILL.md +++ b/.agents/skills/ship/SKILL.md @@ -105,7 +105,7 @@ If the output is non-empty, inform the user: "CODEOWNERS file detected — GitHu PR target branch: `dev` -Use `Issue #` as the issue reference — the issue stays open until `/release` promotes to `main`. +Use `Issue #` as the issue reference — the issue stays open until `/deploy` promotes to `main`. Then create the PR with explicit title and body (never use an interactive editor): ``` @@ -203,4 +203,4 @@ Report success based on mode: - When `ai` is `"off"`, skip the review agent entirely — merge immediately after checks pass. - `/ship` merges only to `dev` — never directly to `main`. - If `make merge` fails for any reason, report it and stop — do not attempt workarounds. - + diff --git a/.agents/skills/version/SKILL.md b/.agents/skills/version/SKILL.md deleted file mode 100644 index e77f712..0000000 --- a/.agents/skills/version/SKILL.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -name: version -description: Bump the project version, tag, and push — run before deploying to preview ---- - -> **Codex CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — perform any review steps inline. - ---- - -## Step 1 — Verify branch - -Run: -```bash -git branch --show-current -``` - -Required branch: `dev` (two-branch 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 - -```bash -cat VERSION -``` - ---- - -## Step 3 — Ask the user - -Tell the user (filling in the actual computed values): - -> "You are on version X.Y.Z. Do you want to bump: -> - **major** → A.0.0 -> - **minor** → X.B.0 -> - **patch** → X.Y.C -> - or set a specific version?" - -Wait for their response. - ---- - -## Step 4 — Interpret and run - -Map the user's natural language response to a command: - -| User says | Run | -|---|---| -| "patch" / anything mentioning patch | `make bump-patch` | -| "minor" | `make bump-minor` | -| "major" | `make bump-major` | -| A specific version e.g. "2.4.5" | `make set-version V= 2.4.5` | - -These targets update the version manifest, create a git commit, and create a git tag. Do not create commits or tags manually. - ---- - -## Step 5 — Push - -```bash -git push -git push --tags -``` - -Both the version bump commit and the tag must be pushed. - ---- - -## Step 6 — Report - -Tell the user the new version and tag: - -"Tagged vX.Y.Z. Run `make deploy-preview` to deploy to preview for testing. When testing is complete, run `/release`." - diff --git a/.claude/commands/deploy.md b/.claude/commands/deploy.md new file mode 100644 index 0000000..f53cac1 --- /dev/null +++ b/.claude/commands/deploy.md @@ -0,0 +1,233 @@ +Bump the project version, create a GitHub Release, and promote to production — handles both versioning and releasing in one step + +--- + +## What `/deploy` does + +`/deploy` is the final step in the workflow. It combines version bumping and release creation into a single command: check state, optionally bump the version, then create a GitHub Release (and in multi-branch mode, promote to production). + +--- + +## Step 1 — Verify branch + +Run: +```bash +git branch --show-current +``` + +Required branch: `dev` (two-branch mode). + +If not on the required branch, abort and say: "Switch to `` before running `/deploy`." + +Pull the latest changes before proceeding: +```bash +git pull +``` + +--- + +## Step 2 — Check current state + +### Find the latest version tag + +```bash +git describe --tags --abbrev=0 2>/dev/null +``` + +If no tag exists, note this is the first release. + +### Read current version + +```bash +cat VERSION +``` + +### Show commits since last tag + +If a previous tag exists, show what's on the branch since that tag: + +```bash +git log main..dev --merges --pretty=format:"%s" +``` + +Parse PR numbers from merge commit subjects (format: `Merge pull request #N from branch/name`). + +For each PR number found, retrieve the PR body: +```bash +gh pr view --json number,title,body +``` + +Extract `Issue #N` and `Closes #N` references from PR bodies. Compile: +- List of PRs included (number + title) +- List of issues linked to those PRs + +### Check for open unmerged PRs + +```bash +gh pr list --state open --json number,title,headRefName --jq '.[] | "#\(.number) \(.title) (\(.headRefName))"' +``` + +### Present the summary + +Tell the user: + +``` +Current version: X.Y.Z +Latest tag: vX.Y.Z + +Commits/PRs since last tag: + #17 — Add /docs directory + #18 — Fix checkout runtime error + +Open PRs not yet merged: + #19 — Add dark mode (feature/dark-mode) + +Would you like to bump the version before deploying? + - **patch** → X.Y.C + - **minor** → X.B.0 + - **major** → A.0.0 + - **specific** → enter a version number + - **skip** → proceed to release with the current tag +``` + +Wait for their response. + +--- + +## Step 3 — Version bump (if requested) + +If the user chose to skip, verify a version tag exists on HEAD: +```bash +git describe --exact-match --tags HEAD 2>/dev/null +``` + +If no tag is found when skipping, warn: "No version tag found on HEAD. You must bump the version before deploying." Return to the version bump prompt. + +If the user chose a bump level, map their response to a command: + +| User says | Run | +|---|---| +| "patch" / anything mentioning patch | `make bump-patch` | +| "minor" | `make bump-minor` | +| "major" | `make bump-major` | +| A specific version e.g. "2.4.5" | `make set-version V= 2.4.5` | + +These commands update the version manifest, create a git commit, and create a git tag. Do not create commits or tags manually. + +Push the version bump: +```bash +git push +git push --tags +``` + +Both the version bump commit and the tag must be pushed. + +--- + +## Step 4 — Compute release contents + +Determine the version tag (either from the bump just performed, or from the existing HEAD tag if the user skipped bumping). + +Find the previous tag to determine the range: +```bash +git describe --abbrev=0 ^ 2>/dev/null +``` + +Use the PR/issue list already computed in Step 2. If the version bump added new commits, re-fetch if needed. + +--- + +## Step 5 — HUMAN GATE + +Show the user the release summary. Example format: + +``` +Ready to release vX.Y.Z to production. + +PRs included: + #17 — Add /docs directory + #18 — Fix checkout runtime error + +Issues that will close: + #14 — Add /docs directory + #15 — Fix checkout runtime error + +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 6 — Create PR: `dev` → `main` + +```bash +gh pr create --base main --head dev \ + --title "Release vX.Y.Z" \ + --body "$(cat <<'EOF' +Release vX.Y.Z + +PRs included: +- #17 — Add /docs directory +- #18 — Fix checkout runtime error + +Closes #14 +Closes #15 +EOF +)" +``` + +Note the PR number from the output. + +The `Closes #N` lines will auto-close the linked issues because this PR merges into `main` (the default branch). + +--- + +## Step 7 — Merge + +Do NOT use `make merge` — it refuses PRs targeting `main`. Use `gh pr merge` directly: + +```bash +gh pr merge --merge +``` + +--- + +## Step 8 — Create GitHub Release + +The version tag (from Step 3) and the PR/issue list (from Step 4) are already known. Find the previous tag to build the changelog link: + +```bash +git describe --abbrev=0 ^ 2>/dev/null +``` + +If no previous tag exists, omit the "Full changelog" line. + +Create the release: + +```bash +gh release create \ + --title "" \ + --notes "$(cat <<'EOF' +## Changes + +- # — (PR #) +[... one line per PR included in this release ...] + +**Full changelog:** https://github.com///compare/... +EOF +)" +``` + +Format each PR line as `- # — (PR #)`. If a PR had no linked issue, omit the `#` prefix and use just the PR title. + +After the command runs, note the release URL from the output. + +--- + +## Step 9 — Report + +Tell the user: + +> "Released vX.Y.Z. Issues #N, #M closed automatically. GitHub Release vX.Y.Z created at ``. Run `make deploy-prod` to ship to production." + diff --git a/.claude/commands/release.md b/.claude/commands/release.md deleted file mode 100644 index a637ec0..0000000 --- a/.claude/commands/release.md +++ /dev/null @@ -1,150 +0,0 @@ -Create a GitHub Release; in multi-branch mode, also promotes the pre-production branch to `main` - ---- - -## What `/release` does - -Creates a GitHub Release and promotes `dev` to `main`. Run this after preview testing is confirmed. - ---- - -## Step 1 — Verify state - -Check the current branch: -```bash -git branch --show-current -``` - -### Verify on `dev` with tag - -If not on `dev`, switch to it: -```bash -git checkout dev && git pull -``` - -Verify a version tag exists on HEAD: -```bash -git describe --exact-match --tags HEAD 2>/dev/null -``` - -If no tag is found, warn: "No version tag found on HEAD. Run `/version` first to tag this release before promoting it." Stop unless the user explicitly says to proceed anyway. - ---- - -## Step 2 — Compute what's being promoted - -Find all merge commits in `dev` not yet in `main`: -```bash -git log main..dev --merges --pretty=format:"%s" -``` - -Parse PR numbers from the merge commit subjects. GitHub's format is: -`Merge pull request #N from branch/name` - -For each PR number found, retrieve the PR body: -```bash -gh pr view --json number,title,body -``` - -Extract `Issue #N` references from PR bodies (look for the pattern `Issue #\d+`). - -Compile: -- List of PRs being promoted (number + title) -- List of open issues linked to those PRs - ---- - -## Step 3 — HUMAN GATE - -Show the user the release summary. Example format: - -``` -Ready to release vX.Y.Z to production. - -PRs included: - #17 — Add /docs directory - #18 — Fix checkout runtime error - -Issues that will close: - #14 — Add /docs directory - #15 — Fix checkout runtime error - -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: `dev` → `main` - -```bash -gh pr create --base main --head dev \ - --title "Release vX.Y.Z" \ - --body "$(cat <<'EOF' -Release vX.Y.Z - -PRs included: -- #17 — Add /docs directory -- #18 — Fix checkout runtime error - -Closes #14 -Closes #15 -EOF -)" -``` - -Note the PR number from the output. - -The `Closes #N` lines will auto-close the linked issues because this PR merges into `main` (the default branch). - ---- - -## Step 5 — Merge - -Do NOT use `make merge` — it refuses PRs targeting `main`. Use `gh pr merge` directly: - -```bash -gh pr merge --merge -``` - ---- - -## Step 6 — Create GitHub Release - -The version tag (from Step 1) and the PR/issue list (from Step 2) are already known. Find the previous tag to build the changelog link: - -```bash -git describe --abbrev=0 ^ 2>/dev/null -``` - -If no previous tag exists, omit the "Full changelog" line. - -Create the release: - -```bash -gh release create \ - --title "" \ - --notes "$(cat <<'EOF' -## Changes - -- # — (PR #) -[... one line per PR included in this release ...] - -**Full changelog:** https://github.com///compare/... -EOF -)" -``` - -Format each PR line as `- # — (PR #)`. If a PR had no linked issue, omit the `#` prefix and use just the PR title. - -After the command runs, note the release URL from the output. - ---- - -## Step 7 — Report - -Tell the user: - -> "Released vX.Y.Z. Issues #N, #M closed automatically. GitHub Release vX.Y.Z created at ``. Run `make deploy-prod` to ship to production." - diff --git a/.claude/commands/setup.md b/.claude/commands/setup.md index 1f0b664..ba2edf7 100644 --- a/.claude/commands/setup.md +++ b/.claude/commands/setup.md @@ -56,8 +56,7 @@ List the available skills: | `/start` | Creates a GitHub issue, feature branch, and writes code | | `/ship` | Checks, commits, opens PR, spawns review agent, merges | | `/review` | Standalone code review on any PR | -| `/version` | Bumps semver, tags, pushes | -| `/release` | Promotes integration branch to main, closes issues | +| `/deploy` | Bumps version, creates GitHub Release, promotes to production | | `/status` | Snapshot of open PRs and issues for the team | | `/setup` | This skill — configures Code Cannon in a project | @@ -126,7 +125,7 @@ Cannot proceed without it. Stop. 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`, `/ship`, `/review`, `/release`, and `/status` will fail without one. This is not a hard stop — ask if the user wants to continue configuring anyway. +If exit code is non-zero: warn that most skills require a GitHub remote. Skills can be read and configured, but `/start`, `/ship`, `/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 @@ -471,4 +470,4 @@ Add a note: `/start` can be used to create well-formed GitHub issues without wri - 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 2 or Phase 3 — each write requires confirmation. - If the user skips a config value, do not ask again. Move on. - + diff --git a/.claude/commands/ship.md b/.claude/commands/ship.md index 8e4de3a..2be406e 100644 --- a/.claude/commands/ship.md +++ b/.claude/commands/ship.md @@ -100,7 +100,7 @@ If the output is non-empty, inform the user: "CODEOWNERS file detected — GitHu PR target branch: `dev` -Use `Issue #` as the issue reference — the issue stays open until `/release` promotes to `main`. +Use `Issue #` as the issue reference — the issue stays open until `/deploy` promotes to `main`. Then create the PR with explicit title and body (never use an interactive editor): ``` @@ -198,4 +198,4 @@ Report success based on mode: - When `ai` is `"off"`, skip the review agent entirely — merge immediately after checks pass. - `/ship` merges only to `dev` — never directly to `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 deleted file mode 100644 index ccd65f4..0000000 --- a/.claude/commands/version.md +++ /dev/null @@ -1,76 +0,0 @@ -Bump the project version, tag, and push — run before deploying to preview - ---- - -## Step 1 — Verify branch - -Run: -```bash -git branch --show-current -``` - -Required branch: `dev` (two-branch 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 - -```bash -cat VERSION -``` - ---- - -## Step 3 — Ask the user - -Tell the user (filling in the actual computed values): - -> "You are on version X.Y.Z. Do you want to bump: -> - **major** → A.0.0 -> - **minor** → X.B.0 -> - **patch** → X.Y.C -> - or set a specific version?" - -Wait for their response. - ---- - -## Step 4 — Interpret and run - -Map the user's natural language response to a command: - -| User says | Run | -|---|---| -| "patch" / anything mentioning patch | `make bump-patch` | -| "minor" | `make bump-minor` | -| "major" | `make bump-major` | -| A specific version e.g. "2.4.5" | `make set-version V= 2.4.5` | - -These targets update the version manifest, create a git commit, and create a git tag. Do not create commits or tags manually. - ---- - -## Step 5 — Push - -```bash -git push -git push --tags -``` - -Both the version bump commit and the tag must be pushed. - ---- - -## Step 6 — Report - -Tell the user the new version and tag: - -"Tagged vX.Y.Z. Run `make deploy-preview` to deploy to preview for testing. When testing is complete, run `/release`." - diff --git a/.cursor/rules/deploy.mdc b/.cursor/rules/deploy.mdc new file mode 100644 index 0000000..973a1a1 --- /dev/null +++ b/.cursor/rules/deploy.mdc @@ -0,0 +1,239 @@ +--- +description: Bump the project version, create a GitHub Release, and promote to production — handles both versioning and releasing in one step +globs: +alwaysApply: false +--- + +> **Cursor:** Trigger this skill via `@deploy` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt. + +--- + +## What `/deploy` does + +`/deploy` is the final step in the workflow. It combines version bumping and release creation into a single command: check state, optionally bump the version, then create a GitHub Release (and in multi-branch mode, promote to production). + +--- + +## Step 1 — Verify branch + +Run: +```bash +git branch --show-current +``` + +Required branch: `dev` (two-branch mode). + +If not on the required branch, abort and say: "Switch to `` before running `/deploy`." + +Pull the latest changes before proceeding: +```bash +git pull +``` + +--- + +## Step 2 — Check current state + +### Find the latest version tag + +```bash +git describe --tags --abbrev=0 2>/dev/null +``` + +If no tag exists, note this is the first release. + +### Read current version + +```bash +cat VERSION +``` + +### Show commits since last tag + +If a previous tag exists, show what's on the branch since that tag: + +```bash +git log main..dev --merges --pretty=format:"%s" +``` + +Parse PR numbers from merge commit subjects (format: `Merge pull request #N from branch/name`). + +For each PR number found, retrieve the PR body: +```bash +gh pr view --json number,title,body +``` + +Extract `Issue #N` and `Closes #N` references from PR bodies. Compile: +- List of PRs included (number + title) +- List of issues linked to those PRs + +### Check for open unmerged PRs + +```bash +gh pr list --state open --json number,title,headRefName --jq '.[] | "#\(.number) \(.title) (\(.headRefName))"' +``` + +### Present the summary + +Tell the user: + +``` +Current version: X.Y.Z +Latest tag: vX.Y.Z + +Commits/PRs since last tag: + #17 — Add /docs directory + #18 — Fix checkout runtime error + +Open PRs not yet merged: + #19 — Add dark mode (feature/dark-mode) + +Would you like to bump the version before deploying? + - **patch** → X.Y.C + - **minor** → X.B.0 + - **major** → A.0.0 + - **specific** → enter a version number + - **skip** → proceed to release with the current tag +``` + +Wait for their response. + +--- + +## Step 3 — Version bump (if requested) + +If the user chose to skip, verify a version tag exists on HEAD: +```bash +git describe --exact-match --tags HEAD 2>/dev/null +``` + +If no tag is found when skipping, warn: "No version tag found on HEAD. You must bump the version before deploying." Return to the version bump prompt. + +If the user chose a bump level, map their response to a command: + +| User says | Run | +|---|---| +| "patch" / anything mentioning patch | `make bump-patch` | +| "minor" | `make bump-minor` | +| "major" | `make bump-major` | +| A specific version e.g. "2.4.5" | `make set-version V= 2.4.5` | + +These commands update the version manifest, create a git commit, and create a git tag. Do not create commits or tags manually. + +Push the version bump: +```bash +git push +git push --tags +``` + +Both the version bump commit and the tag must be pushed. + +--- + +## Step 4 — Compute release contents + +Determine the version tag (either from the bump just performed, or from the existing HEAD tag if the user skipped bumping). + +Find the previous tag to determine the range: +```bash +git describe --abbrev=0 ^ 2>/dev/null +``` + +Use the PR/issue list already computed in Step 2. If the version bump added new commits, re-fetch if needed. + +--- + +## Step 5 — HUMAN GATE + +Show the user the release summary. Example format: + +``` +Ready to release vX.Y.Z to production. + +PRs included: + #17 — Add /docs directory + #18 — Fix checkout runtime error + +Issues that will close: + #14 — Add /docs directory + #15 — Fix checkout runtime error + +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 6 — Create PR: `dev` → `main` + +```bash +gh pr create --base main --head dev \ + --title "Release vX.Y.Z" \ + --body "$(cat <<'EOF' +Release vX.Y.Z + +PRs included: +- #17 — Add /docs directory +- #18 — Fix checkout runtime error + +Closes #14 +Closes #15 +EOF +)" +``` + +Note the PR number from the output. + +The `Closes #N` lines will auto-close the linked issues because this PR merges into `main` (the default branch). + +--- + +## Step 7 — Merge + +Do NOT use `make merge` — it refuses PRs targeting `main`. Use `gh pr merge` directly: + +```bash +gh pr merge --merge +``` + +--- + +## Step 8 — Create GitHub Release + +The version tag (from Step 3) and the PR/issue list (from Step 4) are already known. Find the previous tag to build the changelog link: + +```bash +git describe --abbrev=0 ^ 2>/dev/null +``` + +If no previous tag exists, omit the "Full changelog" line. + +Create the release: + +```bash +gh release create \ + --title "" \ + --notes "$(cat <<'EOF' +## Changes + +- # — (PR #) +[... one line per PR included in this release ...] + +**Full changelog:** https://github.com///compare/... +EOF +)" +``` + +Format each PR line as `- # — (PR #)`. If a PR had no linked issue, omit the `#` prefix and use just the PR title. + +After the command runs, note the release URL from the output. + +--- + +## Step 9 — Report + +Tell the user: + +> "Released vX.Y.Z. Issues #N, #M closed automatically. GitHub Release vX.Y.Z created at ``. Run `make deploy-prod` to ship to production." + diff --git a/.cursor/rules/release.mdc b/.cursor/rules/release.mdc deleted file mode 100644 index 850fbc9..0000000 --- a/.cursor/rules/release.mdc +++ /dev/null @@ -1,156 +0,0 @@ ---- -description: Create a GitHub Release; in multi-branch mode, also promotes the pre-production branch to `main` -globs: -alwaysApply: false ---- - -> **Cursor:** Trigger this skill via `@release` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt. - ---- - -## What `/release` does - -Creates a GitHub Release and promotes `dev` to `main`. Run this after preview testing is confirmed. - ---- - -## Step 1 — Verify state - -Check the current branch: -```bash -git branch --show-current -``` - -### Verify on `dev` with tag - -If not on `dev`, switch to it: -```bash -git checkout dev && git pull -``` - -Verify a version tag exists on HEAD: -```bash -git describe --exact-match --tags HEAD 2>/dev/null -``` - -If no tag is found, warn: "No version tag found on HEAD. Run `/version` first to tag this release before promoting it." Stop unless the user explicitly says to proceed anyway. - ---- - -## Step 2 — Compute what's being promoted - -Find all merge commits in `dev` not yet in `main`: -```bash -git log main..dev --merges --pretty=format:"%s" -``` - -Parse PR numbers from the merge commit subjects. GitHub's format is: -`Merge pull request #N from branch/name` - -For each PR number found, retrieve the PR body: -```bash -gh pr view --json number,title,body -``` - -Extract `Issue #N` references from PR bodies (look for the pattern `Issue #\d+`). - -Compile: -- List of PRs being promoted (number + title) -- List of open issues linked to those PRs - ---- - -## Step 3 — HUMAN GATE - -Show the user the release summary. Example format: - -``` -Ready to release vX.Y.Z to production. - -PRs included: - #17 — Add /docs directory - #18 — Fix checkout runtime error - -Issues that will close: - #14 — Add /docs directory - #15 — Fix checkout runtime error - -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: `dev` → `main` - -```bash -gh pr create --base main --head dev \ - --title "Release vX.Y.Z" \ - --body "$(cat <<'EOF' -Release vX.Y.Z - -PRs included: -- #17 — Add /docs directory -- #18 — Fix checkout runtime error - -Closes #14 -Closes #15 -EOF -)" -``` - -Note the PR number from the output. - -The `Closes #N` lines will auto-close the linked issues because this PR merges into `main` (the default branch). - ---- - -## Step 5 — Merge - -Do NOT use `make merge` — it refuses PRs targeting `main`. Use `gh pr merge` directly: - -```bash -gh pr merge --merge -``` - ---- - -## Step 6 — Create GitHub Release - -The version tag (from Step 1) and the PR/issue list (from Step 2) are already known. Find the previous tag to build the changelog link: - -```bash -git describe --abbrev=0 ^ 2>/dev/null -``` - -If no previous tag exists, omit the "Full changelog" line. - -Create the release: - -```bash -gh release create \ - --title "" \ - --notes "$(cat <<'EOF' -## Changes - -- # — (PR #) -[... one line per PR included in this release ...] - -**Full changelog:** https://github.com///compare/... -EOF -)" -``` - -Format each PR line as `- # — (PR #)`. If a PR had no linked issue, omit the `#` prefix and use just the PR title. - -After the command runs, note the release URL from the output. - ---- - -## Step 7 — Report - -Tell the user: - -> "Released vX.Y.Z. Issues #N, #M closed automatically. GitHub Release vX.Y.Z created at ``. Run `make deploy-prod` to ship to production." - diff --git a/.cursor/rules/setup.mdc b/.cursor/rules/setup.mdc index 7ad5739..6251a67 100644 --- a/.cursor/rules/setup.mdc +++ b/.cursor/rules/setup.mdc @@ -62,8 +62,7 @@ List the available skills: | `/start` | Creates a GitHub issue, feature branch, and writes code | | `/ship` | Checks, commits, opens PR, spawns review agent, merges | | `/review` | Standalone code review on any PR | -| `/version` | Bumps semver, tags, pushes | -| `/release` | Promotes integration branch to main, closes issues | +| `/deploy` | Bumps version, creates GitHub Release, promotes to production | | `/status` | Snapshot of open PRs and issues for the team | | `/setup` | This skill — configures Code Cannon in a project | @@ -132,7 +131,7 @@ Cannot proceed without it. Stop. 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`, `/ship`, `/review`, `/release`, and `/status` will fail without one. This is not a hard stop — ask if the user wants to continue configuring anyway. +If exit code is non-zero: warn that most skills require a GitHub remote. Skills can be read and configured, but `/start`, `/ship`, `/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 @@ -477,4 +476,4 @@ Add a note: `/start` can be used to create well-formed GitHub issues without wri - 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 2 or Phase 3 — each write requires confirmation. - If the user skips a config value, do not ask again. Move on. - + diff --git a/.cursor/rules/ship.mdc b/.cursor/rules/ship.mdc index c8264fd..86d0b9d 100644 --- a/.cursor/rules/ship.mdc +++ b/.cursor/rules/ship.mdc @@ -106,7 +106,7 @@ If the output is non-empty, inform the user: "CODEOWNERS file detected — GitHu PR target branch: `dev` -Use `Issue #` as the issue reference — the issue stays open until `/release` promotes to `main`. +Use `Issue #` as the issue reference — the issue stays open until `/deploy` promotes to `main`. Then create the PR with explicit title and body (never use an interactive editor): ``` @@ -204,4 +204,4 @@ Report success based on mode: - When `ai` is `"off"`, skip the review agent entirely — merge immediately after checks pass. - `/ship` merges only to `dev` — never directly to `main`. - If `make merge` fails for any reason, report it and stop — do not attempt workarounds. - + diff --git a/.cursor/rules/version.mdc b/.cursor/rules/version.mdc deleted file mode 100644 index 290af5d..0000000 --- a/.cursor/rules/version.mdc +++ /dev/null @@ -1,82 +0,0 @@ ---- -description: Bump the project version, tag, and push — run before deploying to preview -globs: -alwaysApply: false ---- - -> **Cursor:** Trigger this skill via `@version` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt. - ---- - -## Step 1 — Verify branch - -Run: -```bash -git branch --show-current -``` - -Required branch: `dev` (two-branch 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 - -```bash -cat VERSION -``` - ---- - -## Step 3 — Ask the user - -Tell the user (filling in the actual computed values): - -> "You are on version X.Y.Z. Do you want to bump: -> - **major** → A.0.0 -> - **minor** → X.B.0 -> - **patch** → X.Y.C -> - or set a specific version?" - -Wait for their response. - ---- - -## Step 4 — Interpret and run - -Map the user's natural language response to a command: - -| User says | Run | -|---|---| -| "patch" / anything mentioning patch | `make bump-patch` | -| "minor" | `make bump-minor` | -| "major" | `make bump-major` | -| A specific version e.g. "2.4.5" | `make set-version V= 2.4.5` | - -These targets update the version manifest, create a git commit, and create a git tag. Do not create commits or tags manually. - ---- - -## Step 5 — Push - -```bash -git push -git push --tags -``` - -Both the version bump commit and the tag must be pushed. - ---- - -## Step 6 — Report - -Tell the user the new version and tag: - -"Tagged vX.Y.Z. Run `make deploy-preview` to deploy to preview for testing. When testing is complete, run `/release`." - diff --git a/.gemini/skills/deploy/SKILL.md b/.gemini/skills/deploy/SKILL.md new file mode 100644 index 0000000..fe44e6f --- /dev/null +++ b/.gemini/skills/deploy/SKILL.md @@ -0,0 +1,238 @@ +--- +name: deploy +description: Bump the project version, create a GitHub Release, and promote to production — handles both versioning and releasing in one step +--- + +> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt in a separate session. + +--- + +## What `/deploy` does + +`/deploy` is the final step in the workflow. It combines version bumping and release creation into a single command: check state, optionally bump the version, then create a GitHub Release (and in multi-branch mode, promote to production). + +--- + +## Step 1 — Verify branch + +Run: +```bash +git branch --show-current +``` + +Required branch: `dev` (two-branch mode). + +If not on the required branch, abort and say: "Switch to `` before running `/deploy`." + +Pull the latest changes before proceeding: +```bash +git pull +``` + +--- + +## Step 2 — Check current state + +### Find the latest version tag + +```bash +git describe --tags --abbrev=0 2>/dev/null +``` + +If no tag exists, note this is the first release. + +### Read current version + +```bash +cat VERSION +``` + +### Show commits since last tag + +If a previous tag exists, show what's on the branch since that tag: + +```bash +git log main..dev --merges --pretty=format:"%s" +``` + +Parse PR numbers from merge commit subjects (format: `Merge pull request #N from branch/name`). + +For each PR number found, retrieve the PR body: +```bash +gh pr view --json number,title,body +``` + +Extract `Issue #N` and `Closes #N` references from PR bodies. Compile: +- List of PRs included (number + title) +- List of issues linked to those PRs + +### Check for open unmerged PRs + +```bash +gh pr list --state open --json number,title,headRefName --jq '.[] | "#\(.number) \(.title) (\(.headRefName))"' +``` + +### Present the summary + +Tell the user: + +``` +Current version: X.Y.Z +Latest tag: vX.Y.Z + +Commits/PRs since last tag: + #17 — Add /docs directory + #18 — Fix checkout runtime error + +Open PRs not yet merged: + #19 — Add dark mode (feature/dark-mode) + +Would you like to bump the version before deploying? + - **patch** → X.Y.C + - **minor** → X.B.0 + - **major** → A.0.0 + - **specific** → enter a version number + - **skip** → proceed to release with the current tag +``` + +Wait for their response. + +--- + +## Step 3 — Version bump (if requested) + +If the user chose to skip, verify a version tag exists on HEAD: +```bash +git describe --exact-match --tags HEAD 2>/dev/null +``` + +If no tag is found when skipping, warn: "No version tag found on HEAD. You must bump the version before deploying." Return to the version bump prompt. + +If the user chose a bump level, map their response to a command: + +| User says | Run | +|---|---| +| "patch" / anything mentioning patch | `make bump-patch` | +| "minor" | `make bump-minor` | +| "major" | `make bump-major` | +| A specific version e.g. "2.4.5" | `make set-version V= 2.4.5` | + +These commands update the version manifest, create a git commit, and create a git tag. Do not create commits or tags manually. + +Push the version bump: +```bash +git push +git push --tags +``` + +Both the version bump commit and the tag must be pushed. + +--- + +## Step 4 — Compute release contents + +Determine the version tag (either from the bump just performed, or from the existing HEAD tag if the user skipped bumping). + +Find the previous tag to determine the range: +```bash +git describe --abbrev=0 ^ 2>/dev/null +``` + +Use the PR/issue list already computed in Step 2. If the version bump added new commits, re-fetch if needed. + +--- + +## Step 5 — HUMAN GATE + +Show the user the release summary. Example format: + +``` +Ready to release vX.Y.Z to production. + +PRs included: + #17 — Add /docs directory + #18 — Fix checkout runtime error + +Issues that will close: + #14 — Add /docs directory + #15 — Fix checkout runtime error + +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 6 — Create PR: `dev` → `main` + +```bash +gh pr create --base main --head dev \ + --title "Release vX.Y.Z" \ + --body "$(cat <<'EOF' +Release vX.Y.Z + +PRs included: +- #17 — Add /docs directory +- #18 — Fix checkout runtime error + +Closes #14 +Closes #15 +EOF +)" +``` + +Note the PR number from the output. + +The `Closes #N` lines will auto-close the linked issues because this PR merges into `main` (the default branch). + +--- + +## Step 7 — Merge + +Do NOT use `make merge` — it refuses PRs targeting `main`. Use `gh pr merge` directly: + +```bash +gh pr merge --merge +``` + +--- + +## Step 8 — Create GitHub Release + +The version tag (from Step 3) and the PR/issue list (from Step 4) are already known. Find the previous tag to build the changelog link: + +```bash +git describe --abbrev=0 ^ 2>/dev/null +``` + +If no previous tag exists, omit the "Full changelog" line. + +Create the release: + +```bash +gh release create \ + --title "" \ + --notes "$(cat <<'EOF' +## Changes + +- # — (PR #) +[... one line per PR included in this release ...] + +**Full changelog:** https://github.com///compare/... +EOF +)" +``` + +Format each PR line as `- # — (PR #)`. If a PR had no linked issue, omit the `#` prefix and use just the PR title. + +After the command runs, note the release URL from the output. + +--- + +## Step 9 — Report + +Tell the user: + +> "Released vX.Y.Z. Issues #N, #M closed automatically. GitHub Release vX.Y.Z created at ``. Run `make deploy-prod` to ship to production." + diff --git a/.gemini/skills/release/SKILL.md b/.gemini/skills/release/SKILL.md deleted file mode 100644 index e35a255..0000000 --- a/.gemini/skills/release/SKILL.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -name: release -description: Create a GitHub Release; in multi-branch mode, also promotes the pre-production branch to `main` ---- - -> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt in a separate session. - ---- - -## What `/release` does - -Creates a GitHub Release and promotes `dev` to `main`. Run this after preview testing is confirmed. - ---- - -## Step 1 — Verify state - -Check the current branch: -```bash -git branch --show-current -``` - -### Verify on `dev` with tag - -If not on `dev`, switch to it: -```bash -git checkout dev && git pull -``` - -Verify a version tag exists on HEAD: -```bash -git describe --exact-match --tags HEAD 2>/dev/null -``` - -If no tag is found, warn: "No version tag found on HEAD. Run `/version` first to tag this release before promoting it." Stop unless the user explicitly says to proceed anyway. - ---- - -## Step 2 — Compute what's being promoted - -Find all merge commits in `dev` not yet in `main`: -```bash -git log main..dev --merges --pretty=format:"%s" -``` - -Parse PR numbers from the merge commit subjects. GitHub's format is: -`Merge pull request #N from branch/name` - -For each PR number found, retrieve the PR body: -```bash -gh pr view --json number,title,body -``` - -Extract `Issue #N` references from PR bodies (look for the pattern `Issue #\d+`). - -Compile: -- List of PRs being promoted (number + title) -- List of open issues linked to those PRs - ---- - -## Step 3 — HUMAN GATE - -Show the user the release summary. Example format: - -``` -Ready to release vX.Y.Z to production. - -PRs included: - #17 — Add /docs directory - #18 — Fix checkout runtime error - -Issues that will close: - #14 — Add /docs directory - #15 — Fix checkout runtime error - -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: `dev` → `main` - -```bash -gh pr create --base main --head dev \ - --title "Release vX.Y.Z" \ - --body "$(cat <<'EOF' -Release vX.Y.Z - -PRs included: -- #17 — Add /docs directory -- #18 — Fix checkout runtime error - -Closes #14 -Closes #15 -EOF -)" -``` - -Note the PR number from the output. - -The `Closes #N` lines will auto-close the linked issues because this PR merges into `main` (the default branch). - ---- - -## Step 5 — Merge - -Do NOT use `make merge` — it refuses PRs targeting `main`. Use `gh pr merge` directly: - -```bash -gh pr merge --merge -``` - ---- - -## Step 6 — Create GitHub Release - -The version tag (from Step 1) and the PR/issue list (from Step 2) are already known. Find the previous tag to build the changelog link: - -```bash -git describe --abbrev=0 ^ 2>/dev/null -``` - -If no previous tag exists, omit the "Full changelog" line. - -Create the release: - -```bash -gh release create \ - --title "" \ - --notes "$(cat <<'EOF' -## Changes - -- # — (PR #) -[... one line per PR included in this release ...] - -**Full changelog:** https://github.com///compare/... -EOF -)" -``` - -Format each PR line as `- # — (PR #)`. If a PR had no linked issue, omit the `#` prefix and use just the PR title. - -After the command runs, note the release URL from the output. - ---- - -## Step 7 — Report - -Tell the user: - -> "Released vX.Y.Z. Issues #N, #M closed automatically. GitHub Release vX.Y.Z created at ``. Run `make deploy-prod` to ship to production." - diff --git a/.gemini/skills/setup/SKILL.md b/.gemini/skills/setup/SKILL.md index 16ee702..0b7a0cc 100644 --- a/.gemini/skills/setup/SKILL.md +++ b/.gemini/skills/setup/SKILL.md @@ -61,8 +61,7 @@ List the available skills: | `/start` | Creates a GitHub issue, feature branch, and writes code | | `/ship` | Checks, commits, opens PR, spawns review agent, merges | | `/review` | Standalone code review on any PR | -| `/version` | Bumps semver, tags, pushes | -| `/release` | Promotes integration branch to main, closes issues | +| `/deploy` | Bumps version, creates GitHub Release, promotes to production | | `/status` | Snapshot of open PRs and issues for the team | | `/setup` | This skill — configures Code Cannon in a project | @@ -131,7 +130,7 @@ Cannot proceed without it. Stop. 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`, `/ship`, `/review`, `/release`, and `/status` will fail without one. This is not a hard stop — ask if the user wants to continue configuring anyway. +If exit code is non-zero: warn that most skills require a GitHub remote. Skills can be read and configured, but `/start`, `/ship`, `/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 @@ -476,4 +475,4 @@ Add a note: `/start` can be used to create well-formed GitHub issues without wri - 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 2 or Phase 3 — each write requires confirmation. - If the user skips a config value, do not ask again. Move on. - + diff --git a/.gemini/skills/ship/SKILL.md b/.gemini/skills/ship/SKILL.md index 8a257e2..37882a2 100644 --- a/.gemini/skills/ship/SKILL.md +++ b/.gemini/skills/ship/SKILL.md @@ -105,7 +105,7 @@ If the output is non-empty, inform the user: "CODEOWNERS file detected — GitHu PR target branch: `dev` -Use `Issue #` as the issue reference — the issue stays open until `/release` promotes to `main`. +Use `Issue #` as the issue reference — the issue stays open until `/deploy` promotes to `main`. Then create the PR with explicit title and body (never use an interactive editor): ``` @@ -203,4 +203,4 @@ Report success based on mode: - When `ai` is `"off"`, skip the review agent entirely — merge immediately after checks pass. - `/ship` merges only to `dev` — never directly to `main`. - If `make merge` fails for any reason, report it and stop — do not attempt workarounds. - + diff --git a/.gemini/skills/version/SKILL.md b/.gemini/skills/version/SKILL.md deleted file mode 100644 index 102b7a9..0000000 --- a/.gemini/skills/version/SKILL.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -name: version -description: Bump the project version, tag, and push — run before deploying to preview ---- - -> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt in a separate session. - ---- - -## Step 1 — Verify branch - -Run: -```bash -git branch --show-current -``` - -Required branch: `dev` (two-branch 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 - -```bash -cat VERSION -``` - ---- - -## Step 3 — Ask the user - -Tell the user (filling in the actual computed values): - -> "You are on version X.Y.Z. Do you want to bump: -> - **major** → A.0.0 -> - **minor** → X.B.0 -> - **patch** → X.Y.C -> - or set a specific version?" - -Wait for their response. - ---- - -## Step 4 — Interpret and run - -Map the user's natural language response to a command: - -| User says | Run | -|---|---| -| "patch" / anything mentioning patch | `make bump-patch` | -| "minor" | `make bump-minor` | -| "major" | `make bump-major` | -| A specific version e.g. "2.4.5" | `make set-version V= 2.4.5` | - -These targets update the version manifest, create a git commit, and create a git tag. Do not create commits or tags manually. - ---- - -## Step 5 — Push - -```bash -git push -git push --tags -``` - -Both the version bump commit and the tag must be pushed. - ---- - -## Step 6 — Report - -Tell the user the new version and tag: - -"Tagged vX.Y.Z. Run `make deploy-preview` to deploy to preview for testing. When testing is complete, run `/release`." - diff --git a/README.md b/README.md index 177d684..c9d5121 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,13 @@ # Code Cannon -A portable agent workflow skill library. Write your team's development workflow once — start, ship, review, version, release — and sync it to Claude Code, Cursor, and other AI coding agents across all your projects. +A portable agent workflow skill library. Write your team's development workflow once — start, ship, review, deploy — and sync it to Claude Code, Cursor, and other AI coding agents across all your projects. Repository: [github.com/LightbridgeLab/CodeCannon](https://github.com/LightbridgeLab/CodeCannon) ## The problem -AI coding agents are powerful, but every project reinvents the same workflows: how to create issues, open PRs, run reviews, bump versions, cut releases. These instructions live in scattered prompt files, maintained per-project, per-agent, with no consistency and no reuse. +AI coding agents are powerful, but every project reinvents the same workflows: how to create issues, open PRs, run reviews, bump versions, deploy releases. These instructions live in scattered prompt files, maintained per-project, per-agent, with no consistency and no reuse. ## The solution @@ -23,24 +23,23 @@ One source of truth. Every project. Every agent. ## What you get -**A complete development workflow in six commands:** +**A complete development workflow in five commands:** ``` -/start → [code + test] → /ship → [QA] → /version → /release +/start → [code + test] → /ship → [QA] → /deploy ``` - `/start` — creates a GitHub issue, feature branch, and writes code (with human approval before any work begins) - `/ship` — checks, commits, opens PR, runs AI review, merges - `/review` — standalone code review on any PR -- `/version` — bumps semver, tags, pushes -- `/release` — promotes to production, creates a GitHub Release +- `/deploy` — bumps version, creates a GitHub Release, promotes to production - `/status` — standup-ready snapshot of PRs, issues, and progress Plus `/qa` for structured QA workflows and `/setup` for guided onboarding. ## Philosophy -**Humans stay in the loop.** The agent proposes; you approve. `/start` waits for your sign-off before creating anything. `/release` requires explicit confirmation. The agent commits; you test. +**Humans stay in the loop.** The agent proposes; you approve. `/start` waits for your sign-off before creating anything. `/deploy` requires explicit confirmation. The agent commits; you test. **Every change has a ticket.** There is no path for code without an issue. The issue is the unit of work — branch, PR, and release all link back to it. @@ -99,8 +98,7 @@ Or run `/setup` for a guided walkthrough that detects your project state and con | `/start` | [docs](docs/skills/start.md) | Create a GitHub issue, branch, and write code | | `/ship` | [docs](docs/skills/ship.md) | Check, commit, open PR, review, merge | | `/review` | [docs](docs/skills/review.md) | Standalone code review on a PR | -| `/version` | [docs](docs/skills/version.md) | Bump version, tag, push | -| `/release` | [docs](docs/skills/release.md) | Promote to production, create GitHub Release | +| `/deploy` | [docs](docs/skills/deploy.md) | Bump version, create GitHub Release, promote to production | | `/qa` | [docs](docs/skills/qa.md) | QA queue and structured review workflow | | `/status` | [docs](docs/skills/status.md) | Snapshot of PRs, issues, and progress | | `/setup` | [docs](docs/skills/setup.md) | Guided onboarding and configuration | diff --git a/config.schema.yaml b/config.schema.yaml index c8d3677..d52fbab 100644 --- a/config.schema.yaml +++ b/config.schema.yaml @@ -21,7 +21,7 @@ placeholders: a different name (e.g. "master", "prod"). All release promotion targets this branch. default: "main" category: branches - used_in: [ship, release, version] + used_in: [ship, deploy] BRANCH_DEV: description: > @@ -29,18 +29,18 @@ placeholders: Set to enable two-branch mode (feature → BRANCH_DEV → BRANCH_PROD). Common values: "development", "dev", "staging". default: "" category: branches - used_in: [ship, release, version, qa, review-agent] + used_in: [ship, deploy, qa, review-agent] BRANCH_TEST: description: > Test/staging branch for three-branch workflows (feature → BRANCH_DEV → BRANCH_TEST → BRANCH_PROD). Leave empty unless your team has a distinct test environment between dev and production. - Requires BRANCH_DEV to be set. When set, /version runs from this branch and /release promotes - this branch to BRANCH_PROD. The BRANCH_DEV → BRANCH_TEST promotion step is a manual PR + Requires BRANCH_DEV to be set. When set, /deploy runs from this branch and promotes + it to BRANCH_PROD. The BRANCH_DEV → BRANCH_TEST promotion step is a manual PR or future /promote skill. default: "" category: branches - used_in: [version, release] + used_in: [deploy] # ── Workflow commands ────────────────────────────────────────────────────── @@ -76,19 +76,19 @@ placeholders: description: "Merge the current feature PR into the integration branch" default: "make merge" category: workflow - used_in: [ship, release] + used_in: [ship, deploy] DEPLOY_PREVIEW_CMD: description: "Deploy to the pre-production environment (BRANCH_DEV in two-branch mode, BRANCH_TEST in three-branch mode). Not used by /ship in trunk mode." default: "make deploy-preview" category: workflow - used_in: [version] + used_in: [deploy] DEPLOY_PROD_CMD: description: "Build and deploy to production environment" default: "make deploy-prod" category: workflow - used_in: [release] + used_in: [deploy] # ── Version bumping ──────────────────────────────────────────────────────── @@ -96,31 +96,31 @@ placeholders: description: "Command that prints the current version string" default: "node -p \"require('./package.json').version\"" category: version - used_in: [version] + used_in: [deploy] BUMP_PATCH_CMD: description: "Bump patch version, commit, and tag" default: "make bump-patch" category: version - used_in: [version] + used_in: [deploy] BUMP_MINOR_CMD: description: "Bump minor version, commit, and tag" default: "make bump-minor" category: version - used_in: [version] + used_in: [deploy] BUMP_MAJOR_CMD: description: "Bump major version, commit, and tag" default: "make bump-major" category: version - used_in: [version] + used_in: [deploy] SET_VERSION_CMD: description: "Set an arbitrary version (value appended as argument by the skill)" default: "make set-version V=" category: version - used_in: [version] + used_in: [deploy] # ── Paths ────────────────────────────────────────────────────────────────── diff --git a/docs/branching.md b/docs/branching.md index 25d18b8..db86f8d 100644 --- a/docs/branching.md +++ b/docs/branching.md @@ -9,7 +9,7 @@ Code Cannon supports three branching models. Set `BRANCH_DEV` and `BRANCH_TEST` ``` feature/ → main /start /ship merges here - /version and /release run here + /deploy runs here ``` The simplest model. Feature branches are created from and merged directly into `BRANCH_PROD` (default: `main`). `/ship` opens a PR targeting `main` with `Closes #N` — issues auto-close on merge. @@ -18,8 +18,7 @@ The simplest model. Feature branches are created from and merged directly into ` **Skill behavior in trunk mode:** - `/ship` targets `BRANCH_PROD` directly -- `/version` runs from `BRANCH_PROD` -- `/release` creates a GitHub Release from `BRANCH_PROD` (no promotion PR needed) +- `/deploy` runs from `BRANCH_PROD` — bumps version and creates a GitHub Release (no promotion PR needed) - QA labels are not applied automatically ## Two-branch development @@ -28,20 +27,19 @@ The simplest model. Feature branches are created from and merged directly into ` ``` feature/ → BRANCH_DEV → BRANCH_PROD - /start /ship /release + /start /ship /deploy ``` -Feature PRs target `BRANCH_DEV`. Issues deliberately stay open through the feature merge — `Closes #N` is not used on feature PRs because they don't land in the default branch. Issues only auto-close when `/release` promotes `BRANCH_DEV` to `BRANCH_PROD`. +Feature PRs target `BRANCH_DEV`. Issues deliberately stay open through the feature merge — `Closes #N` is not used on feature PRs because they don't land in the default branch. Issues only auto-close when `/deploy` promotes `BRANCH_DEV` to `BRANCH_PROD`. -This supports a QA gate between merging code and shipping to production. After `/ship` merges a feature, you deploy the integration branch to a preview environment, test it, then run `/release` when satisfied. +This supports a QA gate between merging code and shipping to production. After `/ship` merges a feature, you deploy the integration branch to a preview environment, test it, then run `/deploy` when satisfied. **When to use:** Teams that want a review/QA gate before production. The most common model for teams with a staging or preview environment. **Skill behavior in two-branch mode:** - `/ship` targets `BRANCH_DEV` and uses `Issue #N` (not `Closes`) - `/ship` applies `QA_READY_LABEL` to the linked issue (if configured) -- `/version` runs from `BRANCH_DEV` -- `/release` opens a promotion PR from `BRANCH_DEV` to `BRANCH_PROD` with `Closes #N` to auto-close issues +- `/deploy` runs from `BRANCH_DEV` — bumps version, opens a promotion PR from `BRANCH_DEV` to `BRANCH_PROD` with `Closes #N` to auto-close issues ## Three-branch development @@ -49,7 +47,7 @@ This supports a QA gate between merging code and shipping to production. After ` ``` feature/ → BRANCH_DEV → BRANCH_TEST → BRANCH_PROD - /start /ship manual/future /release + /start /ship manual/future /deploy /promote ``` @@ -59,8 +57,7 @@ Adds a dedicated test/staging branch between integration and production. Feature **Skill behavior in three-branch mode:** - `/ship` targets `BRANCH_DEV` (same as two-branch) -- `/version` runs from `BRANCH_TEST` -- `/release` promotes `BRANCH_TEST` to `BRANCH_PROD` +- `/deploy` runs from `BRANCH_TEST` — bumps version and promotes `BRANCH_TEST` to `BRANCH_PROD` - The `BRANCH_DEV` to `BRANCH_TEST` step is outside Code Cannon's current scope ## Choosing your model @@ -78,7 +75,7 @@ These aren't rigid modes — they're starting points. Every setting is independe Code Cannon enforces branch rules at the skill level: - `/ship` aborts if run from any protected branch (`BRANCH_PROD`, `BRANCH_DEV`, or `BRANCH_TEST` when set). It must be run from a `feature/*` branch. -- `/version` aborts if not on the required pre-production branch (determined by mode). +- `/deploy` aborts if not on the required pre-production branch (determined by mode). - `/start` always creates `feature/*` branches via `gh issue develop`, ensuring every branch is linked to an issue. The agent will not proceed past these checks. There is no override flag — if you're on the wrong branch, switch first. diff --git a/docs/config-reference.md b/docs/config-reference.md index a10cc3e..1a1c74f 100644 --- a/docs/config-reference.md +++ b/docs/config-reference.md @@ -8,9 +8,9 @@ For the canonical source, see [`config.schema.yaml`](../config.schema.yaml). | Key | Default | Used in | Description | |---|---|---|---| -| `BRANCH_PROD` | `main` | ship, release, version | Production branch. All release promotion targets this branch. | -| `BRANCH_DEV` | *(empty)* | ship, release, version, qa, review-agent | Development/integration branch. Leave empty for trunk-based development. Set to enable two-branch mode. | -| `BRANCH_TEST` | *(empty)* | version, release | Test/staging branch for three-branch workflows. Requires `BRANCH_DEV` to be set. | +| `BRANCH_PROD` | `main` | ship, deploy | Production branch. All release promotion targets this branch. | +| `BRANCH_DEV` | *(empty)* | ship, deploy, qa, review-agent | Development/integration branch. Leave empty for trunk-based development. Set to enable two-branch mode. | +| `BRANCH_TEST` | *(empty)* | deploy | Test/staging branch for three-branch workflows. Requires `BRANCH_DEV` to be set. | See [branching models](branching.md) for how these values change skill behavior. @@ -21,20 +21,20 @@ See [branching models](branching.md) for how these values change skill behavior. | `CHECK_CMD` | `make check` | ship | Type-check / lint gate that must pass before shipping. | | `DEV_CMD` | `make dev` | start | Start the local development server. Suggested to user after `/start` writes code. | | `ABANDON_CMD` | `make abandon` | start | Discard all changes and delete the current feature branch. | -| `MERGE_CMD` | `make merge` | ship, release | Merge the current feature PR into the integration branch. | -| `DEPLOY_PREVIEW_CMD` | `make deploy-preview` | version | Deploy to the pre-production environment. | -| `DEPLOY_PROD_CMD` | `make deploy-prod` | release | Deploy to production. | +| `MERGE_CMD` | `make merge` | ship, deploy | Merge the current feature PR into the integration branch. | +| `DEPLOY_PREVIEW_CMD` | `make deploy-preview` | deploy | Deploy to the pre-production environment. | +| `DEPLOY_PROD_CMD` | `make deploy-prod` | deploy | Deploy to production. | | `REVIEW_GATE` | `ai` | ship, review | Controls AI review in `/ship`. Values: `ai` (blocks on critical findings), `advisory` (posts but doesn't block), `off` (no review). | ## Version bumping | Key | Default | Used in | Description | |---|---|---|---| -| `VERSION_READ_CMD` | `node -p "require('./package.json').version"` | version | Command that prints the current version string. | -| `BUMP_PATCH_CMD` | `make bump-patch` | version | Bump patch version, commit, and tag. | -| `BUMP_MINOR_CMD` | `make bump-minor` | version | Bump minor version, commit, and tag. | -| `BUMP_MAJOR_CMD` | `make bump-major` | version | Bump major version, commit, and tag. | -| `SET_VERSION_CMD` | `make set-version V=` | version | Set an arbitrary version (value appended as argument). | +| `VERSION_READ_CMD` | `node -p "require('./package.json').version"` | deploy | Command that prints the current version string. | +| `BUMP_PATCH_CMD` | `make bump-patch` | deploy | Bump patch version, commit, and tag. | +| `BUMP_MINOR_CMD` | `make bump-minor` | deploy | Bump minor version, commit, and tag. | +| `BUMP_MAJOR_CMD` | `make bump-major` | deploy | Bump major version, commit, and tag. | +| `SET_VERSION_CMD` | `make set-version V=` | deploy | Set an arbitrary version (value appended as argument). | ## Paths diff --git a/docs/customization.md b/docs/customization.md index 8b5bf2c..aa27fa8 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -153,7 +153,7 @@ Options: ## Version commands -The version-related placeholders control how `/version` reads and bumps versions: +The version-related placeholders control how `/deploy` reads and bumps versions: ```yaml VERSION_READ_CMD: "cat VERSION" # prints current version @@ -163,4 +163,4 @@ BUMP_MAJOR_CMD: make bump-major SET_VERSION_CMD: "make set-version V=" # arbitrary version (value appended) ``` -These commands are expected to handle the commit and tag creation themselves. `/version` calls them and then pushes. +These commands are expected to handle the commit and tag creation themselves. `/deploy` calls them and then pushes. diff --git a/docs/index.md b/docs/index.md index f508987..cea7281 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # Code Cannon Documentation -Code Cannon is a portable agent workflow skill library. Write your team's development workflow once — start, ship, review, version, release — and sync it to Claude Code, Cursor, and other AI coding agents across all your projects. +Code Cannon is a portable agent workflow skill library. Write your team's development workflow once — start, ship, review, deploy — and sync it to Claude Code, Cursor, and other AI coding agents across all your projects. ## How it works @@ -13,14 +13,13 @@ Code Cannon is a portable agent workflow skill library. Write your team's develo The intended sequence for a complete change: ``` -/start → [code + local test] → /ship → [QA on preview] → /version → /release +/start → [code + local test] → /ship → [QA on preview] → /deploy ``` - [`/start`](skills/start.md) — reads code, proposes an approach, **waits for human approval**, then creates the issue, branch, and writes code - [`/ship`](skills/ship.md) — runs checks, commits everything, pushes, opens the PR, spawns an agent review, merges if approved - [`/review`](skills/review.md) — standalone review on any PR; also called internally by `/ship` -- [`/version`](skills/version.md) — bumps semver, tags, pushes -- [`/release`](skills/release.md) — promotes to production, creates a GitHub Release, closes issues +- [`/deploy`](skills/deploy.md) — bumps version, creates a GitHub Release, promotes to production - [`/status`](skills/status.md) — read-only snapshot of open PRs, merged work, and open issues - [`/qa`](skills/qa.md) — view the QA queue or record findings on a specific issue - [`/setup`](skills/setup.md) — first-run onboarding: check config, labels, and milestone setup @@ -30,7 +29,7 @@ The intended sequence for a complete change: Code Cannon is opinionated about where humans stay in the loop: - `/start` pauses before creating the issue to confirm the implementation approach. -- `/release` requires an explicit "release" confirmation before promoting to production. +- `/deploy` requires an explicit "release" confirmation before promoting to production. - `/qa` shows the review comment and waits for approval before posting. - Everything else runs unattended. diff --git a/docs/skills/deploy.md b/docs/skills/deploy.md new file mode 100644 index 0000000..a4fae68 --- /dev/null +++ b/docs/skills/deploy.md @@ -0,0 +1,69 @@ +# /deploy + +Bump the project version, create a GitHub Release, and promote to production. + +**Source prompt:** [`../../skills/deploy.md`](../../skills/deploy.md) + +## What it does + +`/deploy` is the final step in the workflow. It combines version bumping and release creation into a single command. Its behavior varies by branching model: + +- **Trunk mode:** Optionally bumps the version, then creates a GitHub Release from `BRANCH_PROD` using the version tag. +- **Two-branch mode:** Optionally bumps the version, opens a promotion PR from `BRANCH_DEV` to `BRANCH_PROD`, merges it (which auto-closes linked issues), and creates a GitHub Release. +- **Three-branch mode:** Same as two-branch but promotes from `BRANCH_TEST` to `BRANCH_PROD`. + +## Usage + +``` +/deploy +``` + +No arguments. Must be run from the correct branch (determined by your branching model). + +## Step-by-step + +1. **Verify branch** — checks that you're on the required pre-production branch: + - **Trunk mode:** `BRANCH_PROD` + - **Two-branch mode:** `BRANCH_DEV` + - **Three-branch mode:** `BRANCH_TEST` + + Aborts if on the wrong branch. + +2. **Check current state** — finds the latest version tag, reads the current version, shows commits/PRs since the last tag, and lists any open unmerged PRs. + +3. **Ask about version bump** — presents bump options with computed values: + - **major** (e.g. 1.2.3 -> 2.0.0) + - **minor** (e.g. 1.2.3 -> 1.3.0) + - **patch** (e.g. 1.2.3 -> 1.2.4) + - set a specific version + - or skip (proceed with existing tag) + +4. **Version bump** (if requested) — runs the appropriate bump command (`BUMP_PATCH_CMD`, `BUMP_MINOR_CMD`, `BUMP_MAJOR_CMD`, or `SET_VERSION_CMD`), then pushes the commit and tag. + +5. **Compute release contents** — finds merge commits since the previous tag, extracts linked PRs and issues. + +6. **Human gate** — shows a release summary and waits for you to type "release". + +7. **Create GitHub Release** (trunk mode) or **Create promotion PR, merge, then create GitHub Release** (multi-branch modes). + +## Why it's built this way + +**Version bump and release in one flow.** Previously these were separate `/version` and `/release` commands. Combining them reduces the workflow from six commands to five and eliminates the possibility of bumping a version but forgetting to release, or vice versa. The version bump step is optional — if you've already tagged, you can skip straight to release. + +**Human gate is mandatory.** The "type release to confirm" gate exists because promoting to production is irreversible in practice. The summary gives you one last chance to verify that the right changes are going out. + +**Issues close on release, not on feature merge.** In multi-branch modes, feature PRs use `Issue #N` instead of `Closes #N`. Issues only auto-close when the promotion PR merges to `BRANCH_PROD`. This means issues stay open through the QA/staging phase, giving you visibility into what's deployed where. + +**State check surfaces surprises early.** Showing open unmerged PRs at the start prevents accidental releases that miss in-flight work. + +**Bump commands are external.** Code Cannon doesn't implement version bumping itself — it delegates to your project's Makefile or scripts. This keeps the skill generic across different version file formats (package.json, VERSION file, setup.py, etc.). + +## Config keys used + +- `VERSION_READ_CMD` — prints the current version +- `BUMP_PATCH_CMD`, `BUMP_MINOR_CMD`, `BUMP_MAJOR_CMD` — semver bump commands +- `SET_VERSION_CMD` — set an arbitrary version +- `DEPLOY_PREVIEW_CMD` — suggested for deploying to preview after version bump +- `DEPLOY_PROD_CMD` — suggested after release for deploying to production +- `BRANCH_PROD`, `BRANCH_DEV`, `BRANCH_TEST` — determine mode and promotion path +- `MERGE_CMD` — NOT used for promotion merges (uses `gh pr merge` directly) diff --git a/docs/skills/qa.md b/docs/skills/qa.md index 44ef854..611a8b5 100644 --- a/docs/skills/qa.md +++ b/docs/skills/qa.md @@ -46,7 +46,7 @@ Queries GitHub for all open issues with the `QA_READY_LABEL` and displays them a **Human gate on posting.** The comment is shown to the QA person before posting. This prevents accidental verdicts and gives a chance to edit findings. -**Never closes issues.** `/qa` records the verdict but never closes the issue. Closure happens when `/release` promotes to production and the `Closes #N` reference triggers GitHub's auto-close. QA verdict and issue closure are separate concerns. +**Never closes issues.** `/qa` records the verdict but never closes the issue. Closure happens when `/deploy` promotes to production and the `Closes #N` reference triggers GitHub's auto-close. QA verdict and issue closure are separate concerns. ## Config keys used diff --git a/docs/skills/release.md b/docs/skills/release.md deleted file mode 100644 index 0364903..0000000 --- a/docs/skills/release.md +++ /dev/null @@ -1,53 +0,0 @@ -# /release - -Create a GitHub Release and promote to production. - -**Source prompt:** [`../../skills/release.md`](../../skills/release.md) - -## What it does - -`/release` is the final step in the workflow. Its behavior varies by branching model: - -- **Trunk mode:** Creates a GitHub Release from `BRANCH_PROD` using the latest version tag. No promotion PR needed since features already merged to `BRANCH_PROD`. -- **Two-branch mode:** Opens a promotion PR from `BRANCH_DEV` to `BRANCH_PROD`, merges it (which auto-closes linked issues), and creates a GitHub Release. -- **Three-branch mode:** Same as two-branch but promotes from `BRANCH_TEST` to `BRANCH_PROD`. - -## Usage - -``` -/release -``` - -No arguments. Run after `/version` has tagged the release. - -## Step-by-step (trunk mode) - -1. **Verify state** — switches to `BRANCH_PROD` if needed, verifies a version tag exists on HEAD. -2. **Compute release contents** — finds merge commits since the previous tag, extracts linked PRs and issues. -3. **Human gate** — shows a release summary and waits for you to type "release". -4. **Create GitHub Release** — creates a release with a changelog listing all included PRs and issues. - -## Step-by-step (two-branch and three-branch mode) - -1. **Verify state** — switches to the pre-production branch, verifies a version tag exists on HEAD. -2. **Compute what's being promoted** — finds merge commits in the pre-production branch not yet in `BRANCH_PROD`, extracts linked PRs and issues. -3. **Human gate** — shows a release summary with all included PRs and issues that will close. Waits for you to type "release". -4. **Create promotion PR** — opens a PR from the pre-production branch to `BRANCH_PROD` with `Closes #N` references so issues auto-close on merge. -5. **Merge** — merges the promotion PR directly (does not use `MERGE_CMD`, which may refuse `BRANCH_PROD` targets). -6. **Create GitHub Release** — creates a release with a changelog and full comparison link. - -## Why it's built this way - -**Human gate is mandatory.** The "type release to confirm" gate exists because promoting to production is irreversible in practice. The summary gives you one last chance to verify that the right changes are going out. - -**Issues close on release, not on feature merge.** In multi-branch modes, feature PRs use `Issue #N` instead of `Closes #N`. Issues only auto-close when the promotion PR merges to `BRANCH_PROD`. This means issues stay open through the QA/staging phase, giving you visibility into what's deployed where. - -**Promotion PR bypasses MERGE_CMD.** `MERGE_CMD` typically includes safeguards that prevent direct merges to `BRANCH_PROD`. `/release` uses `gh pr merge` directly because this is the one intentional case where merging to production is correct. - -**Changelog is computed from git history.** The release notes are built from merge commits and their linked PRs/issues, not from manual input. This ensures the changelog matches what actually shipped. - -## Config keys used - -- `BRANCH_PROD`, `BRANCH_DEV`, `BRANCH_TEST` — determine mode and promotion path -- `MERGE_CMD` — NOT used for promotion merges (uses `gh pr merge` directly) -- `DEPLOY_PROD_CMD` — suggested after release for deploying to production diff --git a/docs/skills/ship.md b/docs/skills/ship.md index 1aa56c3..a2834d9 100644 --- a/docs/skills/ship.md +++ b/docs/skills/ship.md @@ -30,7 +30,7 @@ No arguments. `/ship` operates on the current branch. 5. **Push and open PR** — pushes the branch and creates a PR targeting the correct branch based on your branching model: - **Trunk mode:** targets `BRANCH_PROD`, uses `Closes #N` - - **Two/three-branch mode:** targets `BRANCH_DEV`, uses `Issue #N` (issue stays open until `/release`) + - **Two/three-branch mode:** targets `BRANCH_DEV`, uses `Issue #N` (issue stays open until `/deploy`) 6. **Review** (conditional) — behavior depends on `REVIEW_GATE`: - `ai` (default): spawns a review agent, waits for verdict @@ -64,7 +64,7 @@ The agent never infers reviewers from git history, blame, or team membership. **Mandatory check gate.** `CHECK_CMD` must pass before anything is committed or pushed. This prevents known-broken code from ever reaching a PR. -**Issue linking varies by mode.** In trunk mode, `Closes #N` auto-closes issues on merge because the PR targets the default branch. In multi-branch mode, `Issue #N` keeps issues open until `/release` promotes to production — this supports QA workflows where you want to track issues through the staging environment. +**Issue linking varies by mode.** In trunk mode, `Closes #N` auto-closes issues on merge because the PR targets the default branch. In multi-branch mode, `Issue #N` keeps issues open until `/deploy` promotes to production — this supports QA workflows where you want to track issues through the staging environment. **QA label automation.** In two-branch mode, `/ship` applies `QA_READY_LABEL` to signal that a feature is ready for testing on the preview environment. This feeds into the `/qa` skill's queue view. diff --git a/docs/skills/version.md b/docs/skills/version.md deleted file mode 100644 index eb570fd..0000000 --- a/docs/skills/version.md +++ /dev/null @@ -1,56 +0,0 @@ -# /version - -Bump the project version, tag, and push. - -**Source prompt:** [`../../skills/version.md`](../../skills/version.md) - -## What it does - -`/version` reads the current version, asks what kind of bump you want, runs the appropriate bump command, and pushes both the commit and the tag. Run it after features are merged and before deploying. - -## Usage - -``` -/version -``` - -No arguments. Must be run from the correct branch (determined by your branching model). - -## Step-by-step - -1. **Verify branch** — checks that you're on the required pre-production branch: - - **Trunk mode:** `BRANCH_PROD` - - **Two-branch mode:** `BRANCH_DEV` - - **Three-branch mode:** `BRANCH_TEST` - - Aborts if on the wrong branch. - -2. **Read current version** — runs `VERSION_READ_CMD` to display the current version. - -3. **Ask the user** — presents bump options with computed values: - - **major** (e.g. 1.2.3 -> 2.0.0) - - **minor** (e.g. 1.2.3 -> 1.3.0) - - **patch** (e.g. 1.2.3 -> 1.2.4) - - or set a specific version - -4. **Run bump command** — maps your choice to the appropriate command (`BUMP_PATCH_CMD`, `BUMP_MINOR_CMD`, `BUMP_MAJOR_CMD`, or `SET_VERSION_CMD`). These commands are expected to update the version file, create a commit, and create a tag. - -5. **Push** — pushes the commit and the tag to the remote. - -6. **Report** — tells you the new version and next steps based on your branching model. - -## Why it's built this way - -**Separate from /release.** Version bumping and release promotion are distinct steps. You might bump the version and deploy to a preview environment for testing before deciding to promote to production. Keeping them separate supports this QA workflow. - -**Branch enforcement.** `/version` runs from the pre-production branch, not from a feature branch. This ensures the version bump happens after features are merged and the integration branch is stable. - -**Bump commands are external.** Code Cannon doesn't implement version bumping itself — it delegates to your project's Makefile or scripts. This keeps the skill generic across different version file formats (package.json, VERSION file, setup.py, etc.). - -## Config keys used - -- `VERSION_READ_CMD` — prints the current version -- `BUMP_PATCH_CMD`, `BUMP_MINOR_CMD`, `BUMP_MAJOR_CMD` — semver bump commands -- `SET_VERSION_CMD` — set an arbitrary version -- `DEPLOY_PREVIEW_CMD` — suggested for deploying to preview after version bump -- `BRANCH_PROD`, `BRANCH_DEV`, `BRANCH_TEST` — determine which branch `/version` must run from diff --git a/skills/release.md b/skills/deploy.md similarity index 56% rename from skills/release.md rename to skills/deploy.md index d20526a..33dfb51 100644 --- a/skills/release.md +++ b/skills/deploy.md @@ -1,57 +1,175 @@ --- -skill: release +skill: deploy type: skill -description: "Create a GitHub Release; in multi-branch mode, also promotes the pre-production branch to `{{BRANCH_PROD}}`" +description: "Bump the project version, create a GitHub Release, and promote to production — handles both versioning and releasing in one step" args: none --- -## What `/release` does +## What `/deploy` does -{{#if !BRANCH_DEV}} -Creates a GitHub Release from `{{BRANCH_PROD}}`. Run this after `/version` has tagged the release. +`/deploy` is the final step in the workflow. It combines version bumping and release creation into a single command: check state, optionally bump the version, then create a GitHub Release (and in multi-branch mode, promote to production). + +--- + +## Step 1 — Verify branch + +Run: +```bash +git branch --show-current +``` + +{{#if BRANCH_TEST}} +Required branch: `{{BRANCH_TEST}}` (three-branch mode). {{/if}} -{{#if BRANCH_DEV}} {{#if !BRANCH_TEST}} -Creates a GitHub Release and promotes `{{BRANCH_DEV}}` to `{{BRANCH_PROD}}`. Run this after preview testing is confirmed. +{{#if BRANCH_DEV}} +Required branch: `{{BRANCH_DEV}}` (two-branch mode). {{/if}} -{{#if BRANCH_TEST}} -Creates a GitHub Release and promotes `{{BRANCH_TEST}}` to `{{BRANCH_PROD}}`. Run this after staging testing is confirmed. +{{#if !BRANCH_DEV}} +Required branch: `{{BRANCH_PROD}}` (trunk mode). {{/if}} {{/if}} +If not on the required branch, abort and say: "Switch to `` before running `/deploy`." + +Pull the latest changes before proceeding: +```bash +git pull +``` + --- -## Step 1 — Verify state +## Step 2 — Check current state + +### Find the latest version tag -Check the current branch: ```bash -git branch --show-current +git describe --tags --abbrev=0 2>/dev/null ``` +If no tag exists, note this is the first release. + +### Read current version + +```bash +{{VERSION_READ_CMD}} +``` + +### Show commits since last tag + +If a previous tag exists, show what's on the branch since that tag: + {{#if !BRANCH_DEV}} -### Verify on `{{BRANCH_PROD}}` with tag +```bash +git log ..HEAD --merges --pretty=format:"%s" +``` -If not on `{{BRANCH_PROD}}`, switch to it: +Parse PR numbers from merge commit subjects (format: `Merge pull request #N from branch/name`). +{{/if}} +{{#if BRANCH_DEV}} +{{#if !BRANCH_TEST}} +```bash +git log {{BRANCH_PROD}}..{{BRANCH_DEV}} --merges --pretty=format:"%s" +``` + +Parse PR numbers from merge commit subjects (format: `Merge pull request #N from branch/name`). +{{/if}} +{{#if BRANCH_TEST}} ```bash -git checkout {{BRANCH_PROD}} && git pull +git log {{BRANCH_PROD}}..{{BRANCH_TEST}} --merges --pretty=format:"%s" ``` -Verify a version tag exists on HEAD (i.e., `/version` was run before this): +Parse PR numbers from merge commit subjects. Note: some merge commits here may be promotion merges from `{{BRANCH_DEV}}` — these are identifiable by subjects matching "Merge ... from `{{BRANCH_DEV}}`". Include them in the list but note they are promotion merges; extract the original feature PRs from their PR bodies when possible. +{{/if}} +{{/if}} + +For each PR number found, retrieve the PR body: +```bash +gh pr view --json number,title,body +``` + +{{#if !BRANCH_DEV}} +Extract `Closes #N` references from PR bodies. Compile: +{{/if}} +{{#if BRANCH_DEV}} +Extract `Issue #N` and `Closes #N` references from PR bodies. Compile: +{{/if}} +- List of PRs included (number + title) +- List of issues linked to those PRs + +### Check for open unmerged PRs + +```bash +gh pr list --state open --json number,title,headRefName --jq '.[] | "#\(.number) \(.title) (\(.headRefName))"' +``` + +### Present the summary + +Tell the user: + +``` +Current version: X.Y.Z +Latest tag: vX.Y.Z + +Commits/PRs since last tag: + #17 — Add /docs directory + #18 — Fix checkout runtime error + +Open PRs not yet merged: + #19 — Add dark mode (feature/dark-mode) + +Would you like to bump the version before deploying? + - **patch** → X.Y.C + - **minor** → X.B.0 + - **major** → A.0.0 + - **specific** → enter a version number + - **skip** → proceed to release with the current tag +``` + +Wait for their response. + +--- + +## Step 3 — Version bump (if requested) + +If the user chose to skip, verify a version tag exists on HEAD: ```bash git describe --exact-match --tags HEAD 2>/dev/null ``` -If no tag is found, warn: "No version tag found on HEAD. Run `/version` first to tag this release before running `/release`." Stop unless the user explicitly says to proceed anyway. +If no tag is found when skipping, warn: "No version tag found on HEAD. You must bump the version before deploying." Return to the version bump prompt. + +If the user chose a bump level, map their response to a command: + +| User says | Run | +|---|---| +| "patch" / anything mentioning patch | `{{BUMP_PATCH_CMD}}` | +| "minor" | `{{BUMP_MINOR_CMD}}` | +| "major" | `{{BUMP_MAJOR_CMD}}` | +| A specific version e.g. "2.4.5" | `{{SET_VERSION_CMD}} 2.4.5` | + +These commands update the version manifest, create a git commit, and create a git tag. Do not create commits or tags manually. + +Push the version bump: +```bash +git push +git push --tags +``` + +Both the version bump commit and the tag must be pushed. --- -## Step 2 — Compute release contents +## Step 4 — Compute release contents + +Determine the version tag (either from the bump just performed, or from the existing HEAD tag if the user skipped bumping). Find the previous tag to determine the range: ```bash git describe --abbrev=0 ^ 2>/dev/null ``` +{{#if !BRANCH_DEV}} Find all merge commits since the previous tag: ```bash git log ..HEAD --merges --pretty=format:"%s" @@ -67,10 +185,19 @@ gh pr view --json number,title,body Extract `Closes #N` references from PR bodies (trunk PRs use `Closes #N`). Compile: - List of PRs included (number + title) - List of issues linked via `Closes #N` +{{/if}} +{{#if BRANCH_DEV}} +{{#if !BRANCH_TEST}} +Use the PR/issue list already computed in Step 2. If the version bump added new commits, re-fetch if needed. +{{/if}} +{{#if BRANCH_TEST}} +Use the PR/issue list already computed in Step 2. If the version bump added new commits, re-fetch if needed. +{{/if}} +{{/if}} --- -## Step 3 — HUMAN GATE +## Step 5 — HUMAN GATE Show the user the release summary. Example format: @@ -81,18 +208,34 @@ PRs included: #17 — Add /docs directory #18 — Fix checkout runtime error +{{#if !BRANCH_DEV}} Issues that will be referenced: +{{/if}} +{{#if BRANCH_DEV}} +Issues that will close: +{{/if}} #14 — Add /docs directory #15 — Fix checkout runtime error +{{#if !BRANCH_DEV}} Have you confirmed everything above is ready for production? Type 'release' to confirm. +{{/if}} +{{#if BRANCH_DEV}} +{{#if !BRANCH_TEST}} +Have you tested all of the above on preview? Type 'release' to confirm. +{{/if}} +{{#if BRANCH_TEST}} +Have you tested all of the above on the {{BRANCH_TEST}} environment? Type 'release' to confirm. +{{/if}} +{{/if}} ``` 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 GitHub Release +{{#if !BRANCH_DEV}} +## Step 6 — Create GitHub Release The version tag and PR/issue list are already known. If no previous tag exists, omit the "Full changelog" line. @@ -116,7 +259,7 @@ After the command runs, note the release URL from the output. --- -## Step 5 — Report +## Step 7 — Report Tell the user: @@ -124,68 +267,7 @@ Tell the user: {{/if}} {{#if BRANCH_DEV}} {{#if !BRANCH_TEST}} -### Verify on `{{BRANCH_DEV}}` with tag - -If not on `{{BRANCH_DEV}}`, switch to it: -```bash -git checkout {{BRANCH_DEV}} && git pull -``` - -Verify a version tag exists on HEAD: -```bash -git describe --exact-match --tags HEAD 2>/dev/null -``` - -If no tag is found, warn: "No version tag found on HEAD. Run `/version` first to tag this release before promoting it." Stop unless the user explicitly says to proceed anyway. - ---- - -## Step 2 — Compute what's being promoted - -Find all merge commits in `{{BRANCH_DEV}}` not yet in `{{BRANCH_PROD}}`: -```bash -git log {{BRANCH_PROD}}..{{BRANCH_DEV}} --merges --pretty=format:"%s" -``` - -Parse PR numbers from the merge commit subjects. GitHub's format is: -`Merge pull request #N from branch/name` - -For each PR number found, retrieve the PR body: -```bash -gh pr view --json number,title,body -``` - -Extract `Issue #N` references from PR bodies (look for the pattern `Issue #\d+`). - -Compile: -- List of PRs being promoted (number + title) -- List of open issues linked to those PRs - ---- - -## Step 3 — HUMAN GATE - -Show the user the release summary. Example format: - -``` -Ready to release vX.Y.Z to production. - -PRs included: - #17 — Add /docs directory - #18 — Fix checkout runtime error - -Issues that will close: - #14 — Add /docs directory - #15 — Fix checkout runtime error - -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: `{{BRANCH_DEV}}` → `{{BRANCH_PROD}}` +## Step 6 — Create PR: `{{BRANCH_DEV}}` → `{{BRANCH_PROD}}` ```bash gh pr create --base {{BRANCH_PROD}} --head {{BRANCH_DEV}} \ @@ -209,7 +291,7 @@ The `Closes #N` lines will auto-close the linked issues because this PR merges i --- -## Step 5 — Merge +## Step 7 — Merge Do NOT use `{{MERGE_CMD}}` — it refuses PRs targeting `{{BRANCH_PROD}}`. Use `gh pr merge` directly: @@ -219,9 +301,9 @@ gh pr merge --merge --- -## Step 6 — Create GitHub Release +## Step 8 — Create GitHub Release -The version tag (from Step 1) and the PR/issue list (from Step 2) are already known. Find the previous tag to build the changelog link: +The version tag (from Step 3) and the PR/issue list (from Step 4) are already known. Find the previous tag to build the changelog link: ```bash git describe --abbrev=0 ^ 2>/dev/null @@ -251,74 +333,14 @@ After the command runs, note the release URL from the output. --- -## Step 7 — Report +## Step 9 — Report Tell the user: > "Released vX.Y.Z. Issues #N, #M closed automatically. GitHub Release vX.Y.Z created at ``. Run `{{DEPLOY_PROD_CMD}}` to ship to production." {{/if}} {{#if BRANCH_TEST}} -### Verify on `{{BRANCH_TEST}}` with tag - -If not on `{{BRANCH_TEST}}`, switch to it: -```bash -git checkout {{BRANCH_TEST}} && git pull -``` - -Verify a version tag exists on HEAD: -```bash -git describe --exact-match --tags HEAD 2>/dev/null -``` - -If no tag is found, warn: "No version tag found on HEAD. Run `/version` first to tag this release before promoting it." Stop unless the user explicitly says to proceed anyway. - ---- - -## Step 2 — Compute what's being promoted - -Find all merge commits in `{{BRANCH_TEST}}` not yet in `{{BRANCH_PROD}}`: -```bash -git log {{BRANCH_PROD}}..{{BRANCH_TEST}} --merges --pretty=format:"%s" -``` - -Parse PR numbers from the merge commit subjects. Note: some merge commits here may be promotion merges from `{{BRANCH_DEV}}` — these are identifiable by subjects matching "Merge ... from `{{BRANCH_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 -gh pr view --json number,title,body -``` - -Extract `Issue #N` and `Closes #N` references from PR bodies. - -Compile (best-effort): -- List of PRs being promoted (number + title) -- List of open issues linked to those PRs - ---- - -## Step 3 — HUMAN GATE - -Show the user the release summary. Example format: - -``` -Ready to release vX.Y.Z to production. - -PRs included: - #17 — Add /docs directory - #18 — Fix checkout runtime error - -Issues that will close: - #14 — Add /docs directory - #15 — Fix checkout runtime error - -Have you tested all of the above on the {{BRANCH_TEST}} environment? 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: `{{BRANCH_TEST}}` → `{{BRANCH_PROD}}` +## Step 6 — Create PR: `{{BRANCH_TEST}}` → `{{BRANCH_PROD}}` ```bash gh pr create --base {{BRANCH_PROD}} --head {{BRANCH_TEST}} \ @@ -342,7 +364,7 @@ The `Closes #N` lines will auto-close the linked issues because this PR merges i --- -## Step 5 — Merge +## Step 7 — Merge Do NOT use `{{MERGE_CMD}}` — it refuses PRs targeting `{{BRANCH_PROD}}`. Use `gh pr merge` directly: @@ -352,9 +374,9 @@ gh pr merge --merge --- -## Step 6 — Create GitHub Release +## Step 8 — Create GitHub Release -The version tag (from Step 1) and the PR/issue list (from Step 2) are already known. Find the previous tag to build the changelog link: +The version tag (from Step 3) and the PR/issue list (from Step 4) are already known. Find the previous tag to build the changelog link: ```bash git describe --abbrev=0 ^ 2>/dev/null @@ -384,7 +406,7 @@ After the command runs, note the release URL from the output. --- -## Step 7 — Report +## Step 9 — Report Tell the user: diff --git a/skills/setup.md b/skills/setup.md index 72204af..f4f282b 100644 --- a/skills/setup.md +++ b/skills/setup.md @@ -59,8 +59,7 @@ List the available skills: | `/start` | Creates a GitHub issue, feature branch, and writes code | | `/ship` | Checks, commits, opens PR, spawns review agent, merges | | `/review` | Standalone code review on any PR | -| `/version` | Bumps semver, tags, pushes | -| `/release` | Promotes integration branch to main, closes issues | +| `/deploy` | Bumps version, creates GitHub Release, promotes to production | | `/status` | Snapshot of open PRs and issues for the team | | `/setup` | This skill — configures Code Cannon in a project | @@ -129,7 +128,7 @@ Cannot proceed without it. Stop. 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`, `/ship`, `/review`, `/release`, and `/status` will fail without one. This is not a hard stop — ask if the user wants to continue configuring anyway. +If exit code is non-zero: warn that most skills require a GitHub remote. Skills can be read and configured, but `/start`, `/ship`, `/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 diff --git a/skills/ship.md b/skills/ship.md index f638aad..e1b15c6 100644 --- a/skills/ship.md +++ b/skills/ship.md @@ -116,7 +116,7 @@ If the output is non-empty, inform the user: "CODEOWNERS file detected — GitHu {{#if BRANCH_DEV}} PR target branch: `{{BRANCH_DEV}}` -Use `Issue #` as the issue reference — the issue stays open until `/release` promotes to `{{BRANCH_PROD}}`. +Use `Issue #` as the issue reference — the issue stays open until `/deploy` promotes to `{{BRANCH_PROD}}`. {{/if}} {{#if !BRANCH_DEV}} PR target branch: `{{BRANCH_PROD}}` (trunk mode) diff --git a/skills/version.md b/skills/version.md deleted file mode 100644 index 7446fc4..0000000 --- a/skills/version.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -skill: version -type: skill -description: Bump the project version, tag, and push — run before deploying to preview -args: none ---- - -## Step 1 — Verify branch - -Run: -```bash -git branch --show-current -``` - -{{#if BRANCH_TEST}} -Required branch: `{{BRANCH_TEST}}` (three-branch mode). -{{/if}} -{{#if !BRANCH_TEST}} -{{#if BRANCH_DEV}} -Required branch: `{{BRANCH_DEV}}` (two-branch mode). -{{/if}} -{{#if !BRANCH_DEV}} -Required branch: `{{BRANCH_PROD}}` (trunk mode). -{{/if}} -{{/if}} - -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 - -```bash -{{VERSION_READ_CMD}} -``` - ---- - -## Step 3 — Ask the user - -Tell the user (filling in the actual computed values): - -> "You are on version X.Y.Z. Do you want to bump: -> - **major** → A.0.0 -> - **minor** → X.B.0 -> - **patch** → X.Y.C -> - or set a specific version?" - -Wait for their response. - ---- - -## Step 4 — Interpret and run - -Map the user's natural language response to a command: - -| User says | Run | -|---|---| -| "patch" / anything mentioning patch | `{{BUMP_PATCH_CMD}}` | -| "minor" | `{{BUMP_MINOR_CMD}}` | -| "major" | `{{BUMP_MAJOR_CMD}}` | -| A specific version e.g. "2.4.5" | `{{SET_VERSION_CMD}} 2.4.5` | - -These targets update the version manifest, create a git commit, and create a git tag. Do not create commits or tags manually. - ---- - -## Step 5 — Push - -```bash -git push -git push --tags -``` - -Both the version bump commit and the tag must be pushed. - ---- - -## Step 6 — Report - -Tell the user the new version and tag: - -{{#if !BRANCH_DEV}} -"Tagged vX.Y.Z. Run `/release` to create the GitHub Release." -{{/if}} -{{#if BRANCH_DEV}} -{{#if !BRANCH_TEST}} -"Tagged vX.Y.Z. Run `{{DEPLOY_PREVIEW_CMD}}` to deploy to preview for testing. When testing is complete, run `/release`." -{{/if}} -{{#if BRANCH_TEST}} -"Tagged vX.Y.Z. Run `{{DEPLOY_PREVIEW_CMD}}` to deploy to staging. When testing is complete, run `/release`." -{{/if}} -{{/if}} diff --git a/templates/AGENTS.md.template b/templates/AGENTS.md.template index 140cd3a..7a274f4 100644 --- a/templates/AGENTS.md.template +++ b/templates/AGENTS.md.template @@ -12,7 +12,7 @@ feature/* → main --> + diff --git a/.agents/skills/setup/SKILL.md b/.agents/skills/setup/SKILL.md index 92f45c7..7c0c4dc 100644 --- a/.agents/skills/setup/SKILL.md +++ b/.agents/skills/setup/SKILL.md @@ -59,7 +59,7 @@ List the available skills: | Skill | What it does | |---|---| | `/start` | Creates a GitHub issue, feature branch, and writes code | -| `/ship` | Checks, commits, opens PR, spawns review agent, merges | +| `/submit-for-review` | Checks, commits, opens PR, spawns review agent, merges | | `/review` | Standalone code review on any PR | | `/deploy` | Bumps version, creates GitHub Release, promotes to production | | `/status` | Snapshot of open PRs and issues for the team | @@ -130,7 +130,7 @@ Cannot proceed without it. Stop. 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`, `/ship`, `/review`, `/deploy`, and `/status` will fail without one. This is not a hard stop — ask if the user wants to continue configuring anyway. +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 @@ -389,7 +389,7 @@ Ask: "Which milestone should new issues go under, if any? (name, number, or 'ski **DEFAULT_REVIEWERS** (Standard, Governed, and Custom) -"Comma-separated GitHub handles or team slugs that `/ship` adds as PR reviewers — leave unset to rely on CODEOWNERS or manual assignment." +"Comma-separated GitHub handles or team slugs that `/submit-for-review` adds as PR reviewers — leave unset to rely on CODEOWNERS or manual assignment." Example: `DEFAULT_REVIEWERS: "@alice,@bob"` @@ -475,4 +475,4 @@ Add a note: `/start` can be used to create well-formed GitHub issues without wri - 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 2 or Phase 3 — each write requires confirmation. - If the user skips a config value, do not ask again. Move on. - + diff --git a/.agents/skills/start/SKILL.md b/.agents/skills/start/SKILL.md index 3a96868..924bf34 100644 --- a/.agents/skills/start/SKILL.md +++ b/.agents/skills/start/SKILL.md @@ -150,9 +150,9 @@ Show the user: `On branch feature/` Now write the code. Do NOT commit anything. -When done, say: **"The code is ready for review. Please run `make dev` and test locally. Let me know if it looks good, needs changes, or should be scrapped. When you're happy, run `/ship` to commit, push, and open a PR."** +When done, say: **"The code is ready for review. Please run `make dev` and test locally. Let me know if it looks good, needs changes, or should be scrapped. When you're happy, run `/submit-for-review` to commit, push, and open a PR."** -- User says looks good → run `/ship` +- User says looks good → run `/submit-for-review` - User requests changes → iterate, repeat this message - User says scrap it → run `make abandon` @@ -210,7 +210,7 @@ gh issue comment --body "Resuming work. --remove-assignee @me`. - Apply resolved labels and milestone to every new issue. Label resolution order: per-invocation flag → pool selection from `bug, documentation, enhancement, chore` → omit (or create if `false` is `true`). Never apply a label not in `bug, documentation, enhancement, chore` unless `false` is `true`. - Milestone resolution order: per-invocation flag → auto-detected from GitHub open milestones. Never prompt for a milestone more than once per invocation. - + diff --git a/.agents/skills/ship/SKILL.md b/.agents/skills/submit-for-review/SKILL.md similarity index 89% rename from .agents/skills/ship/SKILL.md rename to .agents/skills/submit-for-review/SKILL.md index 98026de..7286455 100644 --- a/.agents/skills/ship/SKILL.md +++ b/.agents/skills/submit-for-review/SKILL.md @@ -1,5 +1,5 @@ --- -name: ship +name: submit-for-review description: Type-check, commit, open PR, review, and merge to the integration branch --- @@ -7,9 +7,9 @@ description: Type-check, commit, open PR, review, and merge to the integration b --- -## What `/ship` does +## What `/submit-for-review` does -`/ship` is Phase 3 of the workflow: type-check, commit, open PR, spawn review agent, act on verdict. +`/submit-for-review` is Phase 3 of the workflow: type-check, commit, open PR, spawn review agent, act on verdict. --- @@ -26,7 +26,7 @@ Protected branches (not a feature branch): If the current branch matches any of the above, **abort immediately** and say: -> "You are on ``. `/ship` must be run from a feature branch. Switch to your feature branch first." +> "You are on ``. `/submit-for-review` must be run from a feature branch. Switch to your feature branch first." --- @@ -176,9 +176,9 @@ Apply QA label and report success (see below). **If REQUEST CHANGES (at least one CRITICAL finding):** Report the findings to the user. Do NOT merge. Say: -> "The review found blocking issues (see above). Fix them and run `/ship` again." +> "The review found blocking issues (see above). Fix them and run `/submit-for-review` again." -Return to the coding loop. When fixed, run `/ship` again from Step 1. +Return to the coding loop. When fixed, run `/submit-for-review` again from Step 1. --- @@ -201,6 +201,6 @@ 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. -- `/ship` merges only to `dev` — never directly to `main`. +- `/submit-for-review` merges only to `dev` — never directly to `main`. - If `make merge` fails for any reason, report it and stop — do not attempt workarounds. - + diff --git a/.claude/commands/review.md b/.claude/commands/review.md index d83f263..1e44882 100644 --- a/.claude/commands/review.md +++ b/.claude/commands/review.md @@ -50,7 +50,7 @@ The review must: After the review agent completes, relay its verdict to the user: -- **APPROVE** → "Review passed. Run `/ship` to merge (or it may already be merged if called from `/ship`)." +- **APPROVE** → "Review passed. Run `/submit-for-review` to merge (or it may already be merged if called from `/submit-for-review`)." - **REQUEST CHANGES** → Surface the CRITICAL findings. Say: "Fix the issues above and run `/review` again before merging." --- @@ -58,6 +58,6 @@ After the review agent completes, relay its verdict to the user: ## Important - This command does not commit, push, or merge anything. It only reviews. -- It may be called manually at any time, not just from `/ship`. +- It may be called manually at any time, not just from `/submit-for-review`. - The review comment is posted to GitHub for the audit trail. - + diff --git a/.claude/commands/setup.md b/.claude/commands/setup.md index ba2edf7..884406f 100644 --- a/.claude/commands/setup.md +++ b/.claude/commands/setup.md @@ -54,7 +54,7 @@ List the available skills: | Skill | What it does | |---|---| | `/start` | Creates a GitHub issue, feature branch, and writes code | -| `/ship` | Checks, commits, opens PR, spawns review agent, merges | +| `/submit-for-review` | Checks, commits, opens PR, spawns review agent, merges | | `/review` | Standalone code review on any PR | | `/deploy` | Bumps version, creates GitHub Release, promotes to production | | `/status` | Snapshot of open PRs and issues for the team | @@ -125,7 +125,7 @@ Cannot proceed without it. Stop. 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`, `/ship`, `/review`, `/deploy`, and `/status` will fail without one. This is not a hard stop — ask if the user wants to continue configuring anyway. +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 @@ -384,7 +384,7 @@ Ask: "Which milestone should new issues go under, if any? (name, number, or 'ski **DEFAULT_REVIEWERS** (Standard, Governed, and Custom) -"Comma-separated GitHub handles or team slugs that `/ship` adds as PR reviewers — leave unset to rely on CODEOWNERS or manual assignment." +"Comma-separated GitHub handles or team slugs that `/submit-for-review` adds as PR reviewers — leave unset to rely on CODEOWNERS or manual assignment." Example: `DEFAULT_REVIEWERS: "@alice,@bob"` @@ -470,4 +470,4 @@ Add a note: `/start` can be used to create well-formed GitHub issues without wri - 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 2 or Phase 3 — each write requires confirmation. - If the user skips a config value, do not ask again. Move on. - + diff --git a/.claude/commands/start.md b/.claude/commands/start.md index f9bf938..67b188f 100644 --- a/.claude/commands/start.md +++ b/.claude/commands/start.md @@ -145,9 +145,9 @@ Show the user: `On branch feature/` Now write the code. Do NOT commit anything. -When done, say: **"The code is ready for review. Please run `make dev` and test locally. Let me know if it looks good, needs changes, or should be scrapped. When you're happy, run `/ship` to commit, push, and open a PR."** +When done, say: **"The code is ready for review. Please run `make dev` and test locally. Let me know if it looks good, needs changes, or should be scrapped. When you're happy, run `/submit-for-review` to commit, push, and open a PR."** -- User says looks good → run `/ship` +- User says looks good → run `/submit-for-review` - User requests changes → iterate, repeat this message - User says scrap it → run `make abandon` @@ -205,7 +205,7 @@ gh issue comment --body "Resuming work. --remove-assignee @me`. - Apply resolved labels and milestone to every new issue. Label resolution order: per-invocation flag → pool selection from `bug, documentation, enhancement, chore` → omit (or create if `false` is `true`). Never apply a label not in `bug, documentation, enhancement, chore` unless `false` is `true`. - Milestone resolution order: per-invocation flag → auto-detected from GitHub open milestones. Never prompt for a milestone more than once per invocation. - + diff --git a/.claude/commands/ship.md b/.claude/commands/submit-for-review.md similarity index 89% rename from .claude/commands/ship.md rename to .claude/commands/submit-for-review.md index 2be406e..ed0d6da 100644 --- a/.claude/commands/ship.md +++ b/.claude/commands/submit-for-review.md @@ -2,9 +2,9 @@ Type-check, commit, open PR, review, and merge to the integration branch --- -## What `/ship` does +## What `/submit-for-review` does -`/ship` is Phase 3 of the workflow: type-check, commit, open PR, spawn review agent, act on verdict. +`/submit-for-review` is Phase 3 of the workflow: type-check, commit, open PR, spawn review agent, act on verdict. --- @@ -21,7 +21,7 @@ Protected branches (not a feature branch): If the current branch matches any of the above, **abort immediately** and say: -> "You are on ``. `/ship` must be run from a feature branch. Switch to your feature branch first." +> "You are on ``. `/submit-for-review` must be run from a feature branch. Switch to your feature branch first." --- @@ -171,9 +171,9 @@ Apply QA label and report success (see below). **If REQUEST CHANGES (at least one CRITICAL finding):** Report the findings to the user. Do NOT merge. Say: -> "The review found blocking issues (see above). Fix them and run `/ship` again." +> "The review found blocking issues (see above). Fix them and run `/submit-for-review` again." -Return to the coding loop. When fixed, run `/ship` again from Step 1. +Return to the coding loop. When fixed, run `/submit-for-review` again from Step 1. --- @@ -196,6 +196,6 @@ 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. -- `/ship` merges only to `dev` — never directly to `main`. +- `/submit-for-review` merges only to `dev` — never directly to `main`. - If `make merge` fails for any reason, report it and stop — do not attempt workarounds. - + diff --git a/.cursor/rules/deploy.mdc b/.cursor/rules/deploy.mdc index 973a1a1..096256f 100644 --- a/.cursor/rules/deploy.mdc +++ b/.cursor/rules/deploy.mdc @@ -4,7 +4,7 @@ globs: alwaysApply: false --- -> **Cursor:** Trigger this skill via `@deploy` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt. +> **Cursor:** Trigger this skill via `@deploy` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt. --- @@ -236,4 +236,4 @@ After the command runs, note the release URL from the output. Tell the user: > "Released vX.Y.Z. Issues #N, #M closed automatically. GitHub Release vX.Y.Z created at ``. Run `make deploy-prod` to ship to production." - + diff --git a/.cursor/rules/qa.mdc b/.cursor/rules/qa.mdc index caa66c7..778a80f 100644 --- a/.cursor/rules/qa.mdc +++ b/.cursor/rules/qa.mdc @@ -4,7 +4,7 @@ globs: alwaysApply: false --- -> **Cursor:** Trigger this skill via `@qa` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt. +> **Cursor:** Trigger this skill via `@qa` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt. --- @@ -142,4 +142,4 @@ After applying labels, tell the user what was done: - Never post the comment without showing it to the user first. - Never apply labels without user confirmation (the confirmation in Step 3 is the single gate for both posting the comment and applying labels). - Never merge, deploy, or take any action beyond labeling and commenting. - + diff --git a/.cursor/rules/review.mdc b/.cursor/rules/review.mdc index 2614955..3834fc8 100644 --- a/.cursor/rules/review.mdc +++ b/.cursor/rules/review.mdc @@ -4,7 +4,7 @@ globs: alwaysApply: false --- -> **Cursor:** Trigger this skill via `@review` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt. +> **Cursor:** Trigger this skill via `@review` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt. --- @@ -56,7 +56,7 @@ The review must: After the review agent completes, relay its verdict to the user: -- **APPROVE** → "Review passed. Run `/ship` to merge (or it may already be merged if called from `/ship`)." +- **APPROVE** → "Review passed. Run `/submit-for-review` to merge (or it may already be merged if called from `/submit-for-review`)." - **REQUEST CHANGES** → Surface the CRITICAL findings. Say: "Fix the issues above and run `/review` again before merging." --- @@ -64,6 +64,6 @@ After the review agent completes, relay its verdict to the user: ## Important - This command does not commit, push, or merge anything. It only reviews. -- It may be called manually at any time, not just from `/ship`. +- It may be called manually at any time, not just from `/submit-for-review`. - The review comment is posted to GitHub for the audit trail. - + diff --git a/.cursor/rules/setup.mdc b/.cursor/rules/setup.mdc index 6251a67..3809a98 100644 --- a/.cursor/rules/setup.mdc +++ b/.cursor/rules/setup.mdc @@ -4,7 +4,7 @@ globs: alwaysApply: false --- -> **Cursor:** Trigger this skill via `@setup` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt. +> **Cursor:** Trigger this skill via `@setup` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt. --- @@ -60,7 +60,7 @@ List the available skills: | Skill | What it does | |---|---| | `/start` | Creates a GitHub issue, feature branch, and writes code | -| `/ship` | Checks, commits, opens PR, spawns review agent, merges | +| `/submit-for-review` | Checks, commits, opens PR, spawns review agent, merges | | `/review` | Standalone code review on any PR | | `/deploy` | Bumps version, creates GitHub Release, promotes to production | | `/status` | Snapshot of open PRs and issues for the team | @@ -131,7 +131,7 @@ Cannot proceed without it. Stop. 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`, `/ship`, `/review`, `/deploy`, and `/status` will fail without one. This is not a hard stop — ask if the user wants to continue configuring anyway. +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 @@ -390,7 +390,7 @@ Ask: "Which milestone should new issues go under, if any? (name, number, or 'ski **DEFAULT_REVIEWERS** (Standard, Governed, and Custom) -"Comma-separated GitHub handles or team slugs that `/ship` adds as PR reviewers — leave unset to rely on CODEOWNERS or manual assignment." +"Comma-separated GitHub handles or team slugs that `/submit-for-review` adds as PR reviewers — leave unset to rely on CODEOWNERS or manual assignment." Example: `DEFAULT_REVIEWERS: "@alice,@bob"` @@ -476,4 +476,4 @@ Add a note: `/start` can be used to create well-formed GitHub issues without wri - 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 2 or Phase 3 — each write requires confirmation. - If the user skips a config value, do not ask again. Move on. - + diff --git a/.cursor/rules/start.mdc b/.cursor/rules/start.mdc index 8ae7b78..302a88e 100644 --- a/.cursor/rules/start.mdc +++ b/.cursor/rules/start.mdc @@ -4,7 +4,7 @@ globs: alwaysApply: false --- -> **Cursor:** Trigger this skill via `@start` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt. +> **Cursor:** Trigger this skill via `@start` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt. --- @@ -151,9 +151,9 @@ Show the user: `On branch feature/` Now write the code. Do NOT commit anything. -When done, say: **"The code is ready for review. Please run `make dev` and test locally. Let me know if it looks good, needs changes, or should be scrapped. When you're happy, run `/ship` to commit, push, and open a PR."** +When done, say: **"The code is ready for review. Please run `make dev` and test locally. Let me know if it looks good, needs changes, or should be scrapped. When you're happy, run `/submit-for-review` to commit, push, and open a PR."** -- User says looks good → run `/ship` +- User says looks good → run `/submit-for-review` - User requests changes → iterate, repeat this message - User says scrap it → run `make abandon` @@ -211,7 +211,7 @@ gh issue comment --body "Resuming work. --remove-assignee @me`. - Apply resolved labels and milestone to every new issue. Label resolution order: per-invocation flag → pool selection from `bug, documentation, enhancement, chore` → omit (or create if `false` is `true`). Never apply a label not in `bug, documentation, enhancement, chore` unless `false` is `true`. - Milestone resolution order: per-invocation flag → auto-detected from GitHub open milestones. Never prompt for a milestone more than once per invocation. - + diff --git a/.cursor/rules/status.mdc b/.cursor/rules/status.mdc index f0b5c8e..8c4d88d 100644 --- a/.cursor/rules/status.mdc +++ b/.cursor/rules/status.mdc @@ -4,7 +4,7 @@ globs: alwaysApply: false --- -> **Cursor:** Trigger this skill via `@status` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt. +> **Cursor:** Trigger this skill via `@status` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt. --- @@ -181,4 +181,4 @@ Do not post, comment, write files, or take any action. Output only. - If `gh` is unauthenticated or any fetch fails, report the error and stop immediately. - Do not retry failed commands. - Strip the leading `@` from the subject when passing to `gh` flags that do not accept it. - + diff --git a/.cursor/rules/ship.mdc b/.cursor/rules/submit-for-review.mdc similarity index 86% rename from .cursor/rules/ship.mdc rename to .cursor/rules/submit-for-review.mdc index 86d0b9d..d1aabc4 100644 --- a/.cursor/rules/ship.mdc +++ b/.cursor/rules/submit-for-review.mdc @@ -4,13 +4,13 @@ globs: alwaysApply: false --- -> **Cursor:** Trigger this skill via `@ship` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt. +> **Cursor:** Trigger this skill via `@submit-for-review` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt. --- -## What `/ship` does +## What `/submit-for-review` does -`/ship` is Phase 3 of the workflow: type-check, commit, open PR, spawn review agent, act on verdict. +`/submit-for-review` is Phase 3 of the workflow: type-check, commit, open PR, spawn review agent, act on verdict. --- @@ -27,7 +27,7 @@ Protected branches (not a feature branch): If the current branch matches any of the above, **abort immediately** and say: -> "You are on ``. `/ship` must be run from a feature branch. Switch to your feature branch first." +> "You are on ``. `/submit-for-review` must be run from a feature branch. Switch to your feature branch first." --- @@ -177,9 +177,9 @@ Apply QA label and report success (see below). **If REQUEST CHANGES (at least one CRITICAL finding):** Report the findings to the user. Do NOT merge. Say: -> "The review found blocking issues (see above). Fix them and run `/ship` again." +> "The review found blocking issues (see above). Fix them and run `/submit-for-review` again." -Return to the coding loop. When fixed, run `/ship` again from Step 1. +Return to the coding loop. When fixed, run `/submit-for-review` again from Step 1. --- @@ -202,6 +202,6 @@ 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. -- `/ship` merges only to `dev` — never directly to `main`. +- `/submit-for-review` merges only to `dev` — never directly to `main`. - If `make merge` fails for any reason, report it and stop — do not attempt workarounds. - + diff --git a/.gemini/skills/deploy/SKILL.md b/.gemini/skills/deploy/SKILL.md index fe44e6f..81d0f8d 100644 --- a/.gemini/skills/deploy/SKILL.md +++ b/.gemini/skills/deploy/SKILL.md @@ -3,7 +3,7 @@ name: deploy description: Bump the project version, create a GitHub Release, and promote to production — handles both versioning and releasing in one step --- -> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt in a separate session. +> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt in a separate session. --- @@ -235,4 +235,4 @@ After the command runs, note the release URL from the output. Tell the user: > "Released vX.Y.Z. Issues #N, #M closed automatically. GitHub Release vX.Y.Z created at ``. Run `make deploy-prod` to ship to production." - + diff --git a/.gemini/skills/qa/SKILL.md b/.gemini/skills/qa/SKILL.md index 97fea27..5e768dc 100644 --- a/.gemini/skills/qa/SKILL.md +++ b/.gemini/skills/qa/SKILL.md @@ -3,7 +3,7 @@ name: qa description: View the QA queue or review a specific issue --- -> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt in a separate session. +> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt in a separate session. --- @@ -141,4 +141,4 @@ After applying labels, tell the user what was done: - Never post the comment without showing it to the user first. - Never apply labels without user confirmation (the confirmation in Step 3 is the single gate for both posting the comment and applying labels). - Never merge, deploy, or take any action beyond labeling and commenting. - + diff --git a/.gemini/skills/review/SKILL.md b/.gemini/skills/review/SKILL.md index 73f565f..539095c 100644 --- a/.gemini/skills/review/SKILL.md +++ b/.gemini/skills/review/SKILL.md @@ -3,7 +3,7 @@ name: review description: Run a standalone code review on a pull request --- -> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt in a separate session. +> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt in a separate session. --- @@ -55,7 +55,7 @@ The review must: After the review agent completes, relay its verdict to the user: -- **APPROVE** → "Review passed. Run `/ship` to merge (or it may already be merged if called from `/ship`)." +- **APPROVE** → "Review passed. Run `/submit-for-review` to merge (or it may already be merged if called from `/submit-for-review`)." - **REQUEST CHANGES** → Surface the CRITICAL findings. Say: "Fix the issues above and run `/review` again before merging." --- @@ -63,6 +63,6 @@ After the review agent completes, relay its verdict to the user: ## Important - This command does not commit, push, or merge anything. It only reviews. -- It may be called manually at any time, not just from `/ship`. +- It may be called manually at any time, not just from `/submit-for-review`. - The review comment is posted to GitHub for the audit trail. - + diff --git a/.gemini/skills/setup/SKILL.md b/.gemini/skills/setup/SKILL.md index 0b7a0cc..c91640b 100644 --- a/.gemini/skills/setup/SKILL.md +++ b/.gemini/skills/setup/SKILL.md @@ -3,7 +3,7 @@ name: setup description: Detect setup state, guide first-time configuration, populate labels, and walk through optional config values --- -> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt in a separate session. +> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt in a separate session. --- @@ -59,7 +59,7 @@ List the available skills: | Skill | What it does | |---|---| | `/start` | Creates a GitHub issue, feature branch, and writes code | -| `/ship` | Checks, commits, opens PR, spawns review agent, merges | +| `/submit-for-review` | Checks, commits, opens PR, spawns review agent, merges | | `/review` | Standalone code review on any PR | | `/deploy` | Bumps version, creates GitHub Release, promotes to production | | `/status` | Snapshot of open PRs and issues for the team | @@ -130,7 +130,7 @@ Cannot proceed without it. Stop. 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`, `/ship`, `/review`, `/deploy`, and `/status` will fail without one. This is not a hard stop — ask if the user wants to continue configuring anyway. +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 @@ -389,7 +389,7 @@ Ask: "Which milestone should new issues go under, if any? (name, number, or 'ski **DEFAULT_REVIEWERS** (Standard, Governed, and Custom) -"Comma-separated GitHub handles or team slugs that `/ship` adds as PR reviewers — leave unset to rely on CODEOWNERS or manual assignment." +"Comma-separated GitHub handles or team slugs that `/submit-for-review` adds as PR reviewers — leave unset to rely on CODEOWNERS or manual assignment." Example: `DEFAULT_REVIEWERS: "@alice,@bob"` @@ -475,4 +475,4 @@ Add a note: `/start` can be used to create well-formed GitHub issues without wri - 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 2 or Phase 3 — each write requires confirmation. - If the user skips a config value, do not ask again. Move on. - + diff --git a/.gemini/skills/start/SKILL.md b/.gemini/skills/start/SKILL.md index 0b45ced..ea4f3d9 100644 --- a/.gemini/skills/start/SKILL.md +++ b/.gemini/skills/start/SKILL.md @@ -3,7 +3,7 @@ name: start description: Start a new feature or bugfix --- -> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt in a separate session. +> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt in a separate session. --- @@ -150,9 +150,9 @@ Show the user: `On branch feature/` Now write the code. Do NOT commit anything. -When done, say: **"The code is ready for review. Please run `make dev` and test locally. Let me know if it looks good, needs changes, or should be scrapped. When you're happy, run `/ship` to commit, push, and open a PR."** +When done, say: **"The code is ready for review. Please run `make dev` and test locally. Let me know if it looks good, needs changes, or should be scrapped. When you're happy, run `/submit-for-review` to commit, push, and open a PR."** -- User says looks good → run `/ship` +- User says looks good → run `/submit-for-review` - User requests changes → iterate, repeat this message - User says scrap it → run `make abandon` @@ -210,7 +210,7 @@ gh issue comment --body "Resuming work. --remove-assignee @me`. - Apply resolved labels and milestone to every new issue. Label resolution order: per-invocation flag → pool selection from `bug, documentation, enhancement, chore` → omit (or create if `false` is `true`). Never apply a label not in `bug, documentation, enhancement, chore` unless `false` is `true`. - Milestone resolution order: per-invocation flag → auto-detected from GitHub open milestones. Never prompt for a milestone more than once per invocation. - + diff --git a/.gemini/skills/status/SKILL.md b/.gemini/skills/status/SKILL.md index 364ea21..4a58c99 100644 --- a/.gemini/skills/status/SKILL.md +++ b/.gemini/skills/status/SKILL.md @@ -3,7 +3,7 @@ name: status description: Summarize in-progress and recently completed work from GitHub and git --- -> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt in a separate session. +> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt in a separate session. --- @@ -180,4 +180,4 @@ Do not post, comment, write files, or take any action. Output only. - If `gh` is unauthenticated or any fetch fails, report the error and stop immediately. - Do not retry failed commands. - Strip the leading `@` from the subject when passing to `gh` flags that do not accept it. - + diff --git a/.gemini/skills/ship/SKILL.md b/.gemini/skills/submit-for-review/SKILL.md similarity index 87% rename from .gemini/skills/ship/SKILL.md rename to .gemini/skills/submit-for-review/SKILL.md index 37882a2..a4e885f 100644 --- a/.gemini/skills/ship/SKILL.md +++ b/.gemini/skills/submit-for-review/SKILL.md @@ -1,15 +1,15 @@ --- -name: ship +name: submit-for-review description: Type-check, commit, open PR, review, and merge to the integration branch --- -> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt in a separate session. +> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt in a separate session. --- -## What `/ship` does +## What `/submit-for-review` does -`/ship` is Phase 3 of the workflow: type-check, commit, open PR, spawn review agent, act on verdict. +`/submit-for-review` is Phase 3 of the workflow: type-check, commit, open PR, spawn review agent, act on verdict. --- @@ -26,7 +26,7 @@ Protected branches (not a feature branch): If the current branch matches any of the above, **abort immediately** and say: -> "You are on ``. `/ship` must be run from a feature branch. Switch to your feature branch first." +> "You are on ``. `/submit-for-review` must be run from a feature branch. Switch to your feature branch first." --- @@ -176,9 +176,9 @@ Apply QA label and report success (see below). **If REQUEST CHANGES (at least one CRITICAL finding):** Report the findings to the user. Do NOT merge. Say: -> "The review found blocking issues (see above). Fix them and run `/ship` again." +> "The review found blocking issues (see above). Fix them and run `/submit-for-review` again." -Return to the coding loop. When fixed, run `/ship` again from Step 1. +Return to the coding loop. When fixed, run `/submit-for-review` again from Step 1. --- @@ -201,6 +201,6 @@ 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. -- `/ship` merges only to `dev` — never directly to `main`. +- `/submit-for-review` merges only to `dev` — never directly to `main`. - If `make merge` fails for any reason, report it and stop — do not attempt workarounds. - + diff --git a/AGENTS.md b/AGENTS.md index 45ed045..13aea66 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,7 +49,7 @@ cd /path/to/a/consumer/project ## Self-hosting: using Code Cannon to develop Code Cannon - **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 `/ship`. +- **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. diff --git a/README.md b/README.md index c9d5121..b1799a6 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # Code Cannon -A portable agent workflow skill library. Write your team's development workflow once — start, ship, review, deploy — and sync it to Claude Code, Cursor, and other AI coding agents across all your projects. +A portable agent workflow skill library. Write your team's development workflow once — start, submit-for-review, review, deploy — and sync it to Claude Code, Cursor, and other AI coding agents across all your projects. Repository: [github.com/LightbridgeLab/CodeCannon](https://github.com/LightbridgeLab/CodeCannon) @@ -26,11 +26,11 @@ One source of truth. Every project. Every agent. **A complete development workflow in five commands:** ``` -/start → [code + test] → /ship → [QA] → /deploy +/start → [code + test] → /submit-for-review → [QA] → /deploy ``` - `/start` — creates a GitHub issue, feature branch, and writes code (with human approval before any work begins) -- `/ship` — checks, commits, opens PR, runs AI review, merges +- `/submit-for-review` — checks, commits, opens PR, runs AI review, merges - `/review` — standalone code review on any PR - `/deploy` — bumps version, creates a GitHub Release, promotes to production - `/status` — standup-ready snapshot of PRs, issues, and progress @@ -59,7 +59,7 @@ How this maps to Code Cannon behavior: 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. +**Reviewer selection is never automatic.** `/submit-for-review` 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. **Configure, don't fork.** Skills use `{{PLACEHOLDER}}` tokens for project-specific values. Your `.codecannon.yaml` fills them in. When upstream skills improve, pull the submodule and re-sync. @@ -96,7 +96,7 @@ Or run `/setup` for a guided walkthrough that detects your project state and con | Skill | Docs | Description | |---|---|---| | `/start` | [docs](docs/skills/start.md) | Create a GitHub issue, branch, and write code | -| `/ship` | [docs](docs/skills/ship.md) | Check, commit, open PR, review, merge | +| `/submit-for-review` | [docs](docs/skills/submit-for-review.md) | Check, commit, open PR, review, merge | | `/review` | [docs](docs/skills/review.md) | Standalone code review on a PR | | `/deploy` | [docs](docs/skills/deploy.md) | Bump version, create GitHub Release, promote to production | | `/qa` | [docs](docs/skills/qa.md) | QA queue and structured review workflow | diff --git a/ROADMAP.md b/ROADMAP.md index f05c2e3..dc93600 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -4,14 +4,14 @@ Ideas and future work. Not prioritized — just captured so they don't get lost. ## Swarm mode / multi-agent workflows -The current skill set (start/ship/review/version/release) assumes **deep mode**: one issue, one branch, one coherent PR. This works well for disciplined, sequential work. +The current skill set (start/submit-for-review/review/version/release) assumes **deep mode**: one issue, one branch, one coherent PR. This works well for disciplined, sequential work. In practice, developers often run multiple agents simultaneously on unrelated tasks — "swarm mode." This resists the ticket-per-change structure because the agents share a working directory and branch. Worktrees could isolate agents, but only Claude Code supports them natively; Cursor, Codex, and Gemini don't. Possible additions: - **`/checkpoint` skill** — commit and push WIP without the full ship ceremony. Gives save points during swarm mode without pretending each save is a reviewable unit. -- **Worktree launcher** — a `make agent name=` target that creates a worktree, launches an agent with `/start`, and registers cleanup after `/ship`. Orchestration layer outside the skills themselves. +- **Worktree launcher** — a `make agent name=` target that creates a worktree, launches an agent with `/start`, and registers cleanup after `/submit-for-review`. Orchestration layer outside the skills themselves. - **Conflict detection** — warn when multiple agents are modifying overlapping files on the same branch. Decision for now: better discipline (one agent per issue, sequential) is the right path. Revisit when the pain of sequential work outweighs the cost of coordination tooling. diff --git a/adapters/codex/config.yaml b/adapters/codex/config.yaml index 95c7000..cf3d006 100644 --- a/adapters/codex/config.yaml +++ b/adapters/codex/config.yaml @@ -3,6 +3,6 @@ description: OpenAI Codex CLI agent skills output_directory: .agents/skills output_extension: /SKILL.md notes: | - Sub-agent spawning (used in the /ship review step) is not available in Codex CLI. + Sub-agent spawning (used in the /submit-for-review review step) is not available in Codex CLI. That step must be performed manually by pasting the review-agent prompt into a new session. Skills are triggered by description matching or via the $skill-creator built-in. diff --git a/adapters/cursor/config.yaml b/adapters/cursor/config.yaml index 2b6adbf..91e36ae 100644 --- a/adapters/cursor/config.yaml +++ b/adapters/cursor/config.yaml @@ -3,6 +3,6 @@ description: Cursor agent-requested rules output_directory: .cursor/rules output_extension: .mdc notes: | - Sub-agent spawning (used in the /ship review step) is not available in Cursor. + Sub-agent spawning (used in the /submit-for-review review step) is not available in Cursor. That step must be performed manually by pasting the review-agent prompt into a new chat. Users trigger rules via @rulename in Agent mode, or the agent requests them by description. diff --git a/adapters/cursor/header.md b/adapters/cursor/header.md index dbc1c49..a87c21f 100644 --- a/adapters/cursor/header.md +++ b/adapters/cursor/header.md @@ -4,7 +4,7 @@ globs: alwaysApply: false --- -> **Cursor:** Trigger this skill via `@{skill}` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt. +> **Cursor:** Trigger this skill via `@{skill}` in Agent mode. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt. --- diff --git a/adapters/gemini/config.yaml b/adapters/gemini/config.yaml index 547b53a..5bc4498 100644 --- a/adapters/gemini/config.yaml +++ b/adapters/gemini/config.yaml @@ -3,6 +3,6 @@ description: Google Gemini CLI agent skills output_directory: .gemini/skills output_extension: /SKILL.md notes: | - Sub-agent spawning (used in the /ship review step) is not available in Gemini CLI. + Sub-agent spawning (used in the /submit-for-review review step) is not available in Gemini CLI. That step must be performed manually by pasting the review-agent prompt into a new session. Skills are triggered by description matching during conversation. diff --git a/adapters/gemini/header.md b/adapters/gemini/header.md index e87555f..692eec8 100644 --- a/adapters/gemini/header.md +++ b/adapters/gemini/header.md @@ -3,7 +3,7 @@ name: {skill} description: {description} --- -> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/ship` must be done manually using the review-agent prompt in a separate session. +> **Gemini CLI:** This skill is triggered by description matching. State any arguments in your message. Sub-agent spawning is not supported — the automated review step in `/submit-for-review` must be done manually using the review-agent prompt in a separate session. --- diff --git a/config.schema.yaml b/config.schema.yaml index d52fbab..a564a5a 100644 --- a/config.schema.yaml +++ b/config.schema.yaml @@ -21,7 +21,7 @@ placeholders: a different name (e.g. "master", "prod"). All release promotion targets this branch. default: "main" category: branches - used_in: [ship, deploy] + used_in: [submit-for-review, deploy] BRANCH_DEV: description: > @@ -29,7 +29,7 @@ placeholders: Set to enable two-branch mode (feature → BRANCH_DEV → BRANCH_PROD). Common values: "development", "dev", "staging". default: "" category: branches - used_in: [ship, deploy, qa, review-agent] + used_in: [submit-for-review, deploy, qa, review-agent] BRANCH_TEST: description: > @@ -46,13 +46,13 @@ placeholders: REVIEW_GATE: description: > - Controls the AI code review step in /ship. + Controls the AI code review step in /submit-for-review. "ai" (default): review agent is spawned and its verdict determines merge/reject. - "advisory": review agent is spawned and posts findings, but /ship merges regardless of verdict. - "off": no review agent is spawned; /ship merges immediately after CHECK_CMD passes. + "advisory": review agent is spawned and posts findings, but /submit-for-review merges regardless of verdict. + "off": no review agent is spawned; /submit-for-review merges immediately after CHECK_CMD passes. default: "ai" category: workflow - used_in: [ship, review] + used_in: [submit-for-review, review] DEV_CMD: description: "Start the local development server" @@ -70,16 +70,16 @@ placeholders: description: "Type-check / lint gate that must pass before shipping" default: "make check" category: workflow - used_in: [ship] + used_in: [submit-for-review] MERGE_CMD: description: "Merge the current feature PR into the integration branch" default: "make merge" category: workflow - used_in: [ship, deploy] + used_in: [submit-for-review, deploy] DEPLOY_PREVIEW_CMD: - description: "Deploy to the pre-production environment (BRANCH_DEV in two-branch mode, BRANCH_TEST in three-branch mode). Not used by /ship in trunk mode." + description: "Deploy to the pre-production environment (BRANCH_DEV in two-branch mode, BRANCH_TEST in three-branch mode). Not used by /submit-for-review in trunk mode." default: "make deploy-preview" category: workflow used_in: [deploy] @@ -128,7 +128,7 @@ placeholders: description: "Path to the review agent prompt file (generated from skills/review-agent.md)" default: ".claude/review-agent-prompt.md" category: paths - used_in: [ship, review, review-agent] + used_in: [submit-for-review, review, review-agent] # ── GitHub / PR settings ─────────────────────────────────────────────────── @@ -136,7 +136,7 @@ placeholders: description: "Comma-separated GitHub handles or team slugs to add as PR reviewers (e.g. @alice,@bob,org/team-name). Leave empty to rely solely on CODEOWNERS or manual assignment." default: "" category: github - used_in: [ship] + used_in: [submit-for-review] TICKET_LABELS: description: "Comma-separated pool of label names the agent may apply to new issues created by /start (e.g. 'bug,enhancement,good first issue'). The agent selects 1–3 labels from this pool based on the task content — it does not apply all of them blindly. Leave empty to apply no labels by default. Per-invocation --label flag bypasses pool selection entirely and uses the given value verbatim." @@ -157,10 +157,10 @@ placeholders: used_in: [start] QA_READY_LABEL: - description: "Label applied by /ship when a feature merges to BRANCH_DEV in two-branch mode, signaling it is ready for QA on the preview environment. In trunk and three-branch modes, /ship does not apply this label automatically. Only configure if you have an explicit QA gate for your integration branch environment." + description: "Label applied by /submit-for-review when a feature merges to BRANCH_DEV in two-branch mode, signaling it is ready for QA on the preview environment. In trunk and three-branch modes, /submit-for-review does not apply this label automatically. Only configure if you have an explicit QA gate for your integration branch environment." default: "ready-for-qa" category: github - used_in: [ship, qa] + used_in: [submit-for-review, qa] QA_PASSED_LABEL: description: "Label applied by /qa when a feature passes QA review. Leave empty to skip label application." diff --git a/docs/adapters.md b/docs/adapters.md index 3bd843c..45a19ab 100644 --- a/docs/adapters.md +++ b/docs/adapters.md @@ -13,25 +13,25 @@ Adapters translate Code Cannon's generic skill format into agent-specific file f ### Claude Code -The Claude adapter generates slash commands in `.claude/commands/`. Users invoke skills with `/skill-name` in Claude Code. The `/ship` skill can spawn a review sub-agent natively. +The Claude adapter generates slash commands in `.claude/commands/`. Users invoke skills with `/skill-name` in Claude Code. The `/submit-for-review` skill can spawn a review sub-agent natively. ### Cursor The Cursor adapter generates agent-requested rules in `.cursor/rules/`. Users trigger rules via `@rulename` in Agent mode, or the agent requests them by description. -**Limitation:** Cursor does not support sub-agent spawning. The review step in `/ship` (which spawns a separate review agent) must be performed manually by pasting the review-agent prompt into a new chat. +**Limitation:** Cursor does not support sub-agent spawning. The review step in `/submit-for-review` (which spawns a separate review agent) must be performed manually by pasting the review-agent prompt into a new chat. ### Codex CLI The Codex adapter generates agent skills in `.agents/skills/`. Each skill gets its own directory with a `SKILL.md` file containing YAML frontmatter (`name` and `description`). Skills are triggered by description matching during conversation or via the `$skill-creator` built-in. -**Limitation:** Codex CLI does not support sub-agent spawning. The review step in `/ship` must be performed manually by pasting the review-agent prompt into a new session. +**Limitation:** Codex CLI does not support sub-agent spawning. The review step in `/submit-for-review` must be performed manually by pasting the review-agent prompt into a new session. ### Gemini CLI The Gemini adapter generates agent skills in `.gemini/skills/`. Each skill gets its own directory with a `SKILL.md` file containing YAML frontmatter (`name` and `description`). Skills are triggered by description matching during conversation. -**Limitation:** Gemini CLI does not support sub-agent spawning. The review step in `/ship` must be performed manually by pasting the review-agent prompt into a new session. +**Limitation:** Gemini CLI does not support sub-agent spawning. The review step in `/submit-for-review` must be performed manually by pasting the review-agent prompt into a new session. ## Enabling adapters diff --git a/docs/branching.md b/docs/branching.md index db86f8d..5f3f2c6 100644 --- a/docs/branching.md +++ b/docs/branching.md @@ -8,16 +8,16 @@ Code Cannon supports three branching models. Set `BRANCH_DEV` and `BRANCH_TEST` ``` feature/ → main - /start /ship merges here + /start /submit-for-review merges here /deploy runs here ``` -The simplest model. Feature branches are created from and merged directly into `BRANCH_PROD` (default: `main`). `/ship` opens a PR targeting `main` with `Closes #N` — issues auto-close on merge. +The simplest model. Feature branches are created from and merged directly into `BRANCH_PROD` (default: `main`). `/submit-for-review` opens a PR targeting `main` with `Closes #N` — issues auto-close on merge. **When to use:** Solo developers, small teams, projects where every merge is production-ready. Fast iteration with low ceremony. **Skill behavior in trunk mode:** -- `/ship` targets `BRANCH_PROD` directly +- `/submit-for-review` targets `BRANCH_PROD` directly - `/deploy` runs from `BRANCH_PROD` — bumps version and creates a GitHub Release (no promotion PR needed) - QA labels are not applied automatically @@ -27,18 +27,18 @@ The simplest model. Feature branches are created from and merged directly into ` ``` feature/ → BRANCH_DEV → BRANCH_PROD - /start /ship /deploy + /start /submit-for-review /deploy ``` Feature PRs target `BRANCH_DEV`. Issues deliberately stay open through the feature merge — `Closes #N` is not used on feature PRs because they don't land in the default branch. Issues only auto-close when `/deploy` promotes `BRANCH_DEV` to `BRANCH_PROD`. -This supports a QA gate between merging code and shipping to production. After `/ship` merges a feature, you deploy the integration branch to a preview environment, test it, then run `/deploy` when satisfied. +This supports a QA gate between merging code and shipping to production. After `/submit-for-review` merges a feature, you deploy the integration branch to a preview environment, test it, then run `/deploy` when satisfied. **When to use:** Teams that want a review/QA gate before production. The most common model for teams with a staging or preview environment. **Skill behavior in two-branch mode:** -- `/ship` targets `BRANCH_DEV` and uses `Issue #N` (not `Closes`) -- `/ship` applies `QA_READY_LABEL` to the linked issue (if configured) +- `/submit-for-review` targets `BRANCH_DEV` and uses `Issue #N` (not `Closes`) +- `/submit-for-review` applies `QA_READY_LABEL` to the linked issue (if configured) - `/deploy` runs from `BRANCH_DEV` — bumps version, opens a promotion PR from `BRANCH_DEV` to `BRANCH_PROD` with `Closes #N` to auto-close issues ## Three-branch development @@ -47,7 +47,7 @@ This supports a QA gate between merging code and shipping to production. After ` ``` feature/ → BRANCH_DEV → BRANCH_TEST → BRANCH_PROD - /start /ship manual/future /deploy + /start /submit-for-review manual/future /deploy /promote ``` @@ -56,7 +56,7 @@ Adds a dedicated test/staging branch between integration and production. Feature **When to use:** Teams with a formal QA or staging environment that is separate from the integration environment. Common in regulated industries or teams with dedicated QA staff. **Skill behavior in three-branch mode:** -- `/ship` targets `BRANCH_DEV` (same as two-branch) +- `/submit-for-review` targets `BRANCH_DEV` (same as two-branch) - `/deploy` runs from `BRANCH_TEST` — bumps version and promotes `BRANCH_TEST` to `BRANCH_PROD` - The `BRANCH_DEV` to `BRANCH_TEST` step is outside Code Cannon's current scope @@ -74,8 +74,16 @@ These aren't rigid modes — they're starting points. Every setting is independe Code Cannon enforces branch rules at the skill level: -- `/ship` aborts if run from any protected branch (`BRANCH_PROD`, `BRANCH_DEV`, or `BRANCH_TEST` when set). It must be run from a `feature/*` branch. +- `/submit-for-review` aborts if run from any protected branch (`BRANCH_PROD`, `BRANCH_DEV`, or `BRANCH_TEST` when set). It must be run from a `feature/*` branch. - `/deploy` aborts if not on the required pre-production branch (determined by mode). - `/start` always creates `feature/*` branches via `gh issue develop`, ensuring every branch is linked to an issue. The agent will not proceed past these checks. There is no override flag — if you're on the wrong branch, switch first. + +## Working on parallel branches + +When working on multiple features simultaneously, **sequence tasks that touch overlapping files — don't parallelize them.** Submit and merge the first branch before starting the second. + +This is especially important for tasks that involve renaming, restructuring, or updating cross-references across skills. These changes tend to be broad in scope (touching many files) even though the individual edits are small. Running `sync.sh` amplifies the problem further: a one-line edit in a source skill becomes changes across every adapter directory (`.claude/`, `.cursor/`, `.agents/`, `.gemini/`), multiplying the conflict surface. + +If you do end up with parallel branches that conflict, the cleanest resolution is usually to re-apply the smaller change on a fresh branch off the updated integration branch, rather than resolving conflicts file-by-file. The mechanical nature of most cross-cutting changes (find-and-replace + `sync.sh`) makes this fast and reliable. diff --git a/docs/config-reference.md b/docs/config-reference.md index 1a1c74f..eef34dc 100644 --- a/docs/config-reference.md +++ b/docs/config-reference.md @@ -8,8 +8,8 @@ For the canonical source, see [`config.schema.yaml`](../config.schema.yaml). | Key | Default | Used in | Description | |---|---|---|---| -| `BRANCH_PROD` | `main` | ship, deploy | Production branch. All release promotion targets this branch. | -| `BRANCH_DEV` | *(empty)* | ship, deploy, qa, review-agent | Development/integration branch. Leave empty for trunk-based development. Set to enable two-branch mode. | +| `BRANCH_PROD` | `main` | submit-for-review, deploy | Production branch. All release promotion targets this branch. | +| `BRANCH_DEV` | *(empty)* | submit-for-review, deploy, qa, review-agent | Development/integration branch. Leave empty for trunk-based development. Set to enable two-branch mode. | | `BRANCH_TEST` | *(empty)* | deploy | Test/staging branch for three-branch workflows. Requires `BRANCH_DEV` to be set. | See [branching models](branching.md) for how these values change skill behavior. @@ -18,13 +18,13 @@ See [branching models](branching.md) for how these values change skill behavior. | Key | Default | Used in | Description | |---|---|---|---| -| `CHECK_CMD` | `make check` | ship | Type-check / lint gate that must pass before shipping. | +| `CHECK_CMD` | `make check` | submit-for-review | Type-check / lint gate that must pass before shipping. | | `DEV_CMD` | `make dev` | start | Start the local development server. Suggested to user after `/start` writes code. | | `ABANDON_CMD` | `make abandon` | start | Discard all changes and delete the current feature branch. | -| `MERGE_CMD` | `make merge` | ship, deploy | Merge the current feature PR into the integration branch. | +| `MERGE_CMD` | `make merge` | submit-for-review, deploy | Merge the current feature PR into the integration branch. | | `DEPLOY_PREVIEW_CMD` | `make deploy-preview` | deploy | Deploy to the pre-production environment. | | `DEPLOY_PROD_CMD` | `make deploy-prod` | deploy | Deploy to production. | -| `REVIEW_GATE` | `ai` | ship, review | Controls AI review in `/ship`. Values: `ai` (blocks on critical findings), `advisory` (posts but doesn't block), `off` (no review). | +| `REVIEW_GATE` | `ai` | submit-for-review, review | Controls AI review in `/submit-for-review`. Values: `ai` (blocks on critical findings), `advisory` (posts but doesn't block), `off` (no review). | ## Version bumping @@ -40,17 +40,17 @@ See [branching models](branching.md) for how these values change skill behavior. | Key | Default | Used in | Description | |---|---|---|---| -| `REVIEW_AGENT_PROMPT` | `.claude/review-agent-prompt.md` | ship, review, review-agent | Path to the review agent prompt file. | +| `REVIEW_AGENT_PROMPT` | `.claude/review-agent-prompt.md` | submit-for-review, review, review-agent | Path to the review agent prompt file. | ## GitHub / PR settings | Key | Default | Used in | Description | |---|---|---|---| -| `DEFAULT_REVIEWERS` | *(empty)* | ship | Comma-separated GitHub handles or team slugs to add as PR reviewers. | +| `DEFAULT_REVIEWERS` | *(empty)* | submit-for-review | Comma-separated GitHub handles or team slugs to add as PR reviewers. | | `TICKET_LABELS` | *(empty)* | start | Comma-separated label pool the agent may apply to new issues. The agent selects 1-3 fitting labels, not all of them. | | `TICKET_LABEL_CREATION_ALLOWED` | `false` | start | Whether the agent may create new GitHub labels when no pool label fits. | | `DEFAULT_MILESTONE` | *(empty)* | start | Milestone applied to every new issue. Overrides auto-detection from GitHub. | -| `QA_READY_LABEL` | `ready-for-qa` | ship, qa | Label applied by `/ship` in two-branch mode when a feature merges to `BRANCH_DEV`. | +| `QA_READY_LABEL` | `ready-for-qa` | submit-for-review, qa | Label applied by `/submit-for-review` in two-branch mode when a feature merges to `BRANCH_DEV`. | | `QA_PASSED_LABEL` | `qa-passed` | qa | Label applied by `/qa` when a feature passes QA. | | `QA_FAILED_LABEL` | `qa-failed` | qa | Label applied by `/qa` when a feature fails QA. | diff --git a/docs/customization.md b/docs/customization.md index aa27fa8..2dcecd6 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -6,7 +6,7 @@ Code Cannon is designed to be configured, not forked. All project-specific behav Skills in `skills/` use `{{PLACEHOLDER}}` tokens wherever behavior needs to vary between projects. When you run `sync.sh`, it reads your `.codecannon.yaml`, substitutes each placeholder with your project's value, and writes the generated skill files. -For example, the `/ship` skill contains: +For example, the `/submit-for-review` skill contains: ```markdown Run: @@ -42,7 +42,7 @@ See [branching models](branching.md) for a full explanation of each mode. ### Setting your check and deploy commands ```yaml -CHECK_CMD: make check # must pass before /ship proceeds +CHECK_CMD: make check # must pass before /submit-for-review proceeds DEV_CMD: make dev # suggested to user after /start writes code DEPLOY_PREVIEW_CMD: make deploy-preview DEPLOY_PROD_CMD: make deploy-prod @@ -66,7 +66,7 @@ REVIEW_GATE: "ai" # AI review posts findings but never blocks merge REVIEW_GATE: "advisory" -# No AI review at all — /ship merges immediately after checks pass +# No AI review at all — /submit-for-review merges immediately after checks pass REVIEW_GATE: "off" ``` @@ -137,7 +137,7 @@ When you run `sync.sh`, it computes the expected hash for each file. If the file To overwrite anyway: `sync.sh --force`. -To regenerate only specific skills: `sync.sh --skill start,ship`. +To regenerate only specific skills: `sync.sh --skill start,submit-for-review`. ### sync.sh reference diff --git a/docs/index.md b/docs/index.md index cea7281..9d92188 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # Code Cannon Documentation -Code Cannon is a portable agent workflow skill library. Write your team's development workflow once — start, ship, review, deploy — and sync it to Claude Code, Cursor, and other AI coding agents across all your projects. +Code Cannon is a portable agent workflow skill library. Write your team's development workflow once — start, submit-for-review, review, deploy — and sync it to Claude Code, Cursor, and other AI coding agents across all your projects. ## How it works @@ -13,12 +13,12 @@ Code Cannon is a portable agent workflow skill library. Write your team's develo The intended sequence for a complete change: ``` -/start → [code + local test] → /ship → [QA on preview] → /deploy +/start → [code + local test] → /submit-for-review → [QA on preview] → /deploy ``` - [`/start`](skills/start.md) — reads code, proposes an approach, **waits for human approval**, then creates the issue, branch, and writes code -- [`/ship`](skills/ship.md) — runs checks, commits everything, pushes, opens the PR, spawns an agent review, merges if approved -- [`/review`](skills/review.md) — standalone review on any PR; also called internally by `/ship` +- [`/submit-for-review`](skills/submit-for-review.md) — runs checks, commits everything, pushes, opens the PR, spawns an agent review, merges if approved +- [`/review`](skills/review.md) — standalone review on any PR; also called internally by `/submit-for-review` - [`/deploy`](skills/deploy.md) — bumps version, creates a GitHub Release, promotes to production - [`/status`](skills/status.md) — read-only snapshot of open PRs, merged work, and open issues - [`/qa`](skills/qa.md) — view the QA queue or record findings on a specific issue @@ -33,7 +33,7 @@ Code Cannon is opinionated about where humans stay in the loop: - `/qa` shows the review comment and waits for approval before posting. - Everything else runs unattended. -The agent commits; you test. `/start` writes code but does not commit — it hands off to you with "run your dev command and test locally." Committing happens in `/ship`. The human approval loop before shipping is where you catch things the agent missed. +The agent commits; you test. `/start` writes code but does not commit — it hands off to you with "run your dev command and test locally." Committing happens in `/submit-for-review`. The human approval loop before shipping is where you catch things the agent missed. ## Quickstart diff --git a/docs/skills/qa.md b/docs/skills/qa.md index 611a8b5..3503152 100644 --- a/docs/skills/qa.md +++ b/docs/skills/qa.md @@ -22,7 +22,7 @@ View the QA queue or record findings on a specific issue. `/qa` requires `QA_READY_LABEL` to be set in `.codecannon.yaml`. Without it, the skill can't identify which issues are waiting for QA. If unset, it explains how to enable the label workflow. -The QA label workflow is primarily used in two-branch mode, where `/ship` automatically applies `QA_READY_LABEL` after merging a feature to `BRANCH_DEV`. In trunk or three-branch mode, the label must be applied manually. +The QA label workflow is primarily used in two-branch mode, where `/submit-for-review` automatically applies `QA_READY_LABEL` after merging a feature to `BRANCH_DEV`. In trunk or three-branch mode, the label must be applied manually. ## Queue view (no argument) diff --git a/docs/skills/review.md b/docs/skills/review.md index fa199e9..1be0083 100644 --- a/docs/skills/review.md +++ b/docs/skills/review.md @@ -8,7 +8,7 @@ Run a standalone code review on a pull request. `/review` runs a code review on any PR using the project's review agent prompt. It reads the PR diff, examines files for context, and posts structured findings as a PR comment. -This is the same review that `/ship` runs automatically — `/review` just lets you trigger it independently at any time. +This is the same review that `/submit-for-review` runs automatically — `/review` just lets you trigger it independently at any time. ## Usage @@ -43,9 +43,9 @@ The review agent does NOT flag style preferences, documentation completeness, or ## Why it's built this way -**Standalone and composable.** `/review` exists separately from `/ship` so you can review any PR at any time — not just as part of the shipping pipeline. It's useful for reviewing PRs from other contributors or re-reviewing after changes. +**Standalone and composable.** `/review` exists separately from `/submit-for-review` so you can review any PR at any time — not just as part of the shipping pipeline. It's useful for reviewing PRs from other contributors or re-reviewing after changes. -**Same prompt, same standards.** Both `/ship` and `/review` use the same `REVIEW_AGENT_PROMPT`, so reviews are consistent regardless of how they're triggered. +**Same prompt, same standards.** Both `/submit-for-review` and `/review` use the same `REVIEW_AGENT_PROMPT`, so reviews are consistent regardless of how they're triggered. **Read-only.** `/review` never commits, pushes, or merges. It only reads and comments. This makes it safe to run at any point in the workflow. diff --git a/docs/skills/start.md b/docs/skills/start.md index 0fa9b2c..db2c2db 100644 --- a/docs/skills/start.md +++ b/docs/skills/start.md @@ -80,7 +80,7 @@ Milestones are resolved in a three-tier order: **Human gate before creation.** The agent proposes an approach and waits. This prevents wasted work on the wrong approach and gives you a chance to redirect before any GitHub artifacts are created. -**No commits during /start.** Code is written but not committed. This is intentional — the human testing loop between `/start` and `/ship` is where you catch things the agent missed. Committing happens in `/ship` after you've verified the code locally. +**No commits during /start.** Code is written but not committed. This is intentional — the human testing loop between `/start` and `/submit-for-review` is where you catch things the agent missed. Committing happens in `/submit-for-review` after you've verified the code locally. **Branch linking via `gh issue develop`.** Instead of `git checkout -b`, Code Cannon uses `gh issue develop` so the branch is linked to the issue in GitHub's UI. This makes it easy to find the branch from the issue and vice versa. diff --git a/docs/skills/ship.md b/docs/skills/submit-for-review.md similarity index 75% rename from docs/skills/ship.md rename to docs/skills/submit-for-review.md index a2834d9..1d2c1f7 100644 --- a/docs/skills/ship.md +++ b/docs/skills/submit-for-review.md @@ -1,28 +1,28 @@ -# /ship +# /submit-for-review Type-check, commit, open PR, spawn review agent, and merge. -**Source prompt:** [`../../skills/ship.md`](../../skills/ship.md) +**Source prompt:** [`../../skills/submit-for-review.md`](../../skills/submit-for-review.md) ## What it does -`/ship` is Phase 3 of the workflow — it takes code that has been written and tested locally, and moves it through the full shipping pipeline: check, commit, push, PR, review, merge. +`/submit-for-review` is Phase 3 of the workflow — it takes code that has been written and tested locally, and moves it through the full shipping pipeline: check, commit, push, PR, review, merge. It must be run from a `feature/*` branch. Running it from any protected branch (`BRANCH_PROD`, `BRANCH_DEV`, `BRANCH_TEST`) causes an immediate abort. ## Usage ``` -/ship +/submit-for-review ``` -No arguments. `/ship` operates on the current branch. +No arguments. `/submit-for-review` operates on the current branch. ## Step-by-step 1. **Verify branch** — confirms you're on a `feature/*` branch, not a protected branch. -2. **Type-check gate** — runs `CHECK_CMD`. If it fails, `/ship` stops and reports the errors. This is a hard gate — no bypass. +2. **Type-check gate** — runs `CHECK_CMD`. If it fails, `/submit-for-review` stops and reports the errors. This is a hard gate — no bypass. 3. **Identify linked issue** — looks for the issue number linked to this branch (from `gh issue develop` or the PR body). @@ -37,13 +37,13 @@ No arguments. `/ship` operates on the current branch. - `advisory`: spawns a review agent, posts findings, merges regardless - `off`: skips review entirely -7. **Act on verdict** — if `REVIEW_GATE` is `ai` and the review finds CRITICAL issues, `/ship` stops and asks you to fix them. Otherwise, it merges the PR. +7. **Act on verdict** — if `REVIEW_GATE` is `ai` and the review finds CRITICAL issues, `/submit-for-review` stops and asks you to fix them. Otherwise, it merges the PR. 8. **Post-merge** — in two-branch mode, applies `QA_READY_LABEL` to the linked issue if configured. Reports next steps based on your branching model. ## Reviewer selection -`/ship` adds reviewers from exactly two sources: +`/submit-for-review` adds reviewers from exactly two sources: - **CODEOWNERS file** — checked in `CODEOWNERS`, `.github/CODEOWNERS`, and `docs/CODEOWNERS`. GitHub automatically requests reviews from code owners. - **`DEFAULT_REVIEWERS` config** — comma-separated handles or team slugs added to the PR. @@ -60,13 +60,13 @@ The agent never infers reviewers from git history, blame, or team membership. ## Why it's built this way -**Single command for the full pipeline.** The check-commit-push-PR-review-merge sequence is mechanical and error-prone when done manually. `/ship` automates the entire chain while keeping a human gate (the review) in the middle. +**Single command for the full pipeline.** The check-commit-push-PR-review-merge sequence is mechanical and error-prone when done manually. `/submit-for-review` automates the entire chain while keeping a human gate (the review) in the middle. **Mandatory check gate.** `CHECK_CMD` must pass before anything is committed or pushed. This prevents known-broken code from ever reaching a PR. **Issue linking varies by mode.** In trunk mode, `Closes #N` auto-closes issues on merge because the PR targets the default branch. In multi-branch mode, `Issue #N` keeps issues open until `/deploy` promotes to production — this supports QA workflows where you want to track issues through the staging environment. -**QA label automation.** In two-branch mode, `/ship` applies `QA_READY_LABEL` to signal that a feature is ready for testing on the preview environment. This feeds into the `/qa` skill's queue view. +**QA label automation.** In two-branch mode, `/submit-for-review` applies `QA_READY_LABEL` to signal that a feature is ready for testing on the preview environment. This feeds into the `/qa` skill's queue view. ## Config keys used diff --git a/skills/qa.md b/skills/qa.md index 4d4fc7d..8a4f575 100644 --- a/skills/qa.md +++ b/skills/qa.md @@ -10,7 +10,7 @@ args: "none | issue number" > > To enable: add `QA_READY_LABEL: ready-for-qa` (or your preferred label name) to `.codecannon.yaml` and re-run `CodeCannon/sync.sh`. > -> Note: In trunk mode, `/ship` does not apply this label automatically — you would need to apply it manually or via a separate workflow. +> Note: In trunk mode, `/submit-for-review` does not apply this label automatically — you would need to apply it manually or via a separate workflow. Do not proceed. Stop here. {{/if}} diff --git a/skills/review-agent.md b/skills/review-agent.md index 14d4485..fb1603d 100644 --- a/skills/review-agent.md +++ b/skills/review-agent.md @@ -1,7 +1,7 @@ --- skill: review-agent type: prompt -description: Code review agent system prompt — not a slash command, used by /ship and /review +description: Code review agent system prompt — not a slash command, used by /submit-for-review and /review output_path_override: "{{REVIEW_AGENT_PROMPT}}" no_invocation_header: true --- diff --git a/skills/review.md b/skills/review.md index 076a178..2b65ca1 100644 --- a/skills/review.md +++ b/skills/review.md @@ -53,7 +53,7 @@ The review must: After the review agent completes, relay its verdict to the user: -- **APPROVE** → "Review passed. Run `/ship` to merge (or it may already be merged if called from `/ship`)." +- **APPROVE** → "Review passed. Run `/submit-for-review` to merge (or it may already be merged if called from `/submit-for-review`)." - **REQUEST CHANGES** → Surface the CRITICAL findings. Say: "Fix the issues above and run `/review` again before merging." --- @@ -61,5 +61,5 @@ After the review agent completes, relay its verdict to the user: ## Important - This command does not commit, push, or merge anything. It only reviews. -- It may be called manually at any time, not just from `/ship`. +- It may be called manually at any time, not just from `/submit-for-review`. - The review comment is posted to GitHub for the audit trail. diff --git a/skills/setup.md b/skills/setup.md index f4f282b..c1dd9b7 100644 --- a/skills/setup.md +++ b/skills/setup.md @@ -57,7 +57,7 @@ List the available skills: | Skill | What it does | |---|---| | `/start` | Creates a GitHub issue, feature branch, and writes code | -| `/ship` | Checks, commits, opens PR, spawns review agent, merges | +| `/submit-for-review` | Checks, commits, opens PR, spawns review agent, merges | | `/review` | Standalone code review on any PR | | `/deploy` | Bumps version, creates GitHub Release, promotes to production | | `/status` | Snapshot of open PRs and issues for the team | @@ -128,7 +128,7 @@ Cannot proceed without it. Stop. 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`, `/ship`, `/review`, `/deploy`, and `/status` will fail without one. This is not a hard stop — ask if the user wants to continue configuring anyway. +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 @@ -387,7 +387,7 @@ Ask: "Which milestone should new issues go under, if any? (name, number, or 'ski **DEFAULT_REVIEWERS** (Standard, Governed, and Custom) -"Comma-separated GitHub handles or team slugs that `/ship` adds as PR reviewers — leave unset to rely on CODEOWNERS or manual assignment." +"Comma-separated GitHub handles or team slugs that `/submit-for-review` adds as PR reviewers — leave unset to rely on CODEOWNERS or manual assignment." Example: `DEFAULT_REVIEWERS: "@alice,@bob"` diff --git a/skills/start.md b/skills/start.md index 2a98042..2aacf81 100644 --- a/skills/start.md +++ b/skills/start.md @@ -191,9 +191,9 @@ Show the user: `On branch feature/` Now write the code. Do NOT commit anything. -When done, say: **"The code is ready for review. Please run `{{DEV_CMD}}` and test locally. Let me know if it looks good, needs changes, or should be scrapped. When you're happy, run `/ship` to commit, push, and open a PR."** +When done, say: **"The code is ready for review. Please run `{{DEV_CMD}}` and test locally. Let me know if it looks good, needs changes, or should be scrapped. When you're happy, run `/submit-for-review` to commit, push, and open a PR."** -- User says looks good → run `/ship` +- User says looks good → run `/submit-for-review` - User requests changes → iterate, repeat this message - User says scrap it → run `{{ABANDON_CMD}}` @@ -258,7 +258,7 @@ gh issue comment --body "Resuming work. --remove-assignee @me`. diff --git a/skills/ship.md b/skills/submit-for-review.md similarity index 93% rename from skills/ship.md rename to skills/submit-for-review.md index e1b15c6..a2fa850 100644 --- a/skills/ship.md +++ b/skills/submit-for-review.md @@ -1,13 +1,13 @@ --- -skill: ship +skill: submit-for-review type: skill description: Type-check, commit, open PR, review, and merge to the integration branch args: none --- -## What `/ship` does +## What `/submit-for-review` does -`/ship` is Phase 3 of the workflow: type-check, commit, open PR, spawn review agent, act on verdict. +`/submit-for-review` is Phase 3 of the workflow: type-check, commit, open PR, spawn review agent, act on verdict. --- @@ -29,7 +29,7 @@ Protected branches (not a feature branch): If the current branch matches any of the above, **abort immediately** and say: -> "You are on ``. `/ship` must be run from a feature branch. Switch to your feature branch first." +> "You are on ``. `/submit-for-review` must be run from a feature branch. Switch to your feature branch first." --- @@ -200,9 +200,9 @@ Apply QA label and report success (see below). **If REQUEST CHANGES (at least one CRITICAL finding):** Report the findings to the user. Do NOT merge. Say: -> "The review found blocking issues (see above). Fix them and run `/ship` again." +> "The review found blocking issues (see above). Fix them and run `/submit-for-review` again." -Return to the coding loop. When fixed, run `/ship` again from Step 1. +Return to the coding loop. When fixed, run `/submit-for-review` again from Step 1. --- @@ -242,7 +242,7 @@ Report success based on mode: - When `{{REVIEW_GATE}}` is `"advisory"`, always merge after review completes, regardless of verdict. - When `{{REVIEW_GATE}}` is `"off"`, skip the review agent entirely — merge immediately after checks pass. {{#if BRANCH_DEV}} -- `/ship` merges only to `{{BRANCH_DEV}}` — never directly to `{{BRANCH_PROD}}`. +- `/submit-for-review` merges only to `{{BRANCH_DEV}}` — never directly to `{{BRANCH_PROD}}`. {{/if}} {{#if !BRANCH_DEV}} - Merges target `{{BRANCH_PROD}}` (trunk mode). diff --git a/sync.sh b/sync.sh index e193f4a..0c19da0 100755 --- a/sync.sh +++ b/sync.sh @@ -352,7 +352,7 @@ def main(): parser.add_argument('--validate', action='store_true', help='Pre-flight check: verify all {{PLACEHOLDERS}} in skills are defined in config. Exits non-zero if any are missing. Does not write files.') parser.add_argument('--skill', default='', - help='Sync only specific skill(s), comma-separated (e.g. start,ship)') + help='Sync only specific skill(s), comma-separated (e.g. start,submit-for-review)') args = parser.parse_args() project_root = Path.cwd() diff --git a/templates/AGENTS.md.template b/templates/AGENTS.md.template index 7a274f4..fda9302 100644 --- a/templates/AGENTS.md.template +++ b/templates/AGENTS.md.template @@ -5,7 +5,7 @@ Repository conventions for all AI coding agents (Claude Code, Cursor, Copilot, W ## Branch Strategy