diff --git a/.claude/commands/qa.md b/.claude/commands/qa.md index 1dbb3d4..718a7bb 100644 --- a/.claude/commands/qa.md +++ b/.claude/commands/qa.md @@ -1,4 +1,4 @@ -You are executing the `/qa` skill. Your argument is: $ARGUMENTS +View the QA queue or review a specific issue --- @@ -158,4 +158,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/.claude/commands/release.md b/.claude/commands/release.md index 5642a08..94a42be 100644 --- a/.claude/commands/release.md +++ b/.claude/commands/release.md @@ -1,4 +1,4 @@ -You are executing the `/release` skill. Your argument is: $ARGUMENTS +Create a GitHub Release and promote the pre-production branch to production --- @@ -357,4 +357,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/.claude/commands/review.md b/.claude/commands/review.md index d21fb26..e6f32d2 100644 --- a/.claude/commands/review.md +++ b/.claude/commands/review.md @@ -1,4 +1,4 @@ -You are executing the `/review` skill. Your argument is: $ARGUMENTS +Run a standalone code review on a pull request --- @@ -54,4 +54,4 @@ After the review agent completes, relay its verdict to the user: - This command does not commit, push, or merge anything. It only reviews. - It may be called manually at any time, not just from `/ship`. - The review comment is posted to GitHub for the audit trail. - + diff --git a/.claude/commands/setup.md b/.claude/commands/setup.md index 1a4b5c5..a5180ee 100644 --- a/.claude/commands/setup.md +++ b/.claude/commands/setup.md @@ -1,4 +1,4 @@ -You are executing the `/setup` skill. Your argument is: $ARGUMENTS +Detect setup state, guide first-time configuration, populate labels, and walk through optional config values --- @@ -469,4 +469,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 53b3351..074b96f 100644 --- a/.claude/commands/ship.md +++ b/.claude/commands/ship.md @@ -1,4 +1,4 @@ -You are executing the `/ship` skill. Your argument is: $ARGUMENTS +Type-check, commit, open PR, review, and merge to the integration branch --- @@ -191,4 +191,4 @@ Report success based on mode: - When `ai` is `"off"`, skip the review agent entirely — merge immediately after checks pass. - In trunk mode, merges target `main`. Otherwise, `/ship` merges only to `dev` — never directly to `` or `main`. - If `make merge` fails for any reason, report it and stop — do not attempt workarounds. - + diff --git a/.claude/commands/start.md b/.claude/commands/start.md index 4afee6e..c171a09 100644 --- a/.claude/commands/start.md +++ b/.claude/commands/start.md @@ -1,4 +1,4 @@ -You are executing the `/start` skill. Your argument is: $ARGUMENTS +Start a new feature or bugfix --- @@ -226,4 +226,4 @@ When done, say: **"The code is ready for review. Please run `make dev` and test - `gh issue create` must use `--title` and `--body` flags. Never open an interactive editor. - The issue is assigned to `@me` at creation. If you are creating a ticket on someone else's behalf, remove the assignee after creation with `gh issue edit --remove-assignee @me`. - Apply resolved labels and milestone to every new issue. Label resolution order: per-invocation flag → pool selection from `` → omit (or create if `false` is `true`). Never apply a label not in `` unless `false` is `true`. Milestone resolution order: per-invocation flag → `` config → auto-detected from GitHub open milestones. Never prompt for a milestone more than once per invocation. - + diff --git a/.claude/commands/status.md b/.claude/commands/status.md index 65c177c..8df3878 100644 --- a/.claude/commands/status.md +++ b/.claude/commands/status.md @@ -1,4 +1,4 @@ -You are executing the `/status` skill. Your argument is: $ARGUMENTS +Summarize in-progress and recently completed work from GitHub and git --- @@ -175,4 +175,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/.claude/commands/version.md b/.claude/commands/version.md index fa78575..516dd78 100644 --- a/.claude/commands/version.md +++ b/.claude/commands/version.md @@ -1,4 +1,4 @@ -You are executing the `/version` skill. Your argument is: $ARGUMENTS +Bump the project version, tag, and push — run before deploying to preview --- @@ -79,4 +79,4 @@ Report based on mode: - **Trunk mode** (`dev` empty): "Tagged vX.Y.Z. Run `/release` to create the GitHub Release." - **Two-branch mode** (`dev` set, `` empty): "Tagged vX.Y.Z. Run `make deploy-preview` to deploy to preview for testing. When testing is complete, run `/release`." - **Three-branch mode** (both set): "Tagged vX.Y.Z. Run `make deploy-preview` to deploy to staging. When testing is complete, run `/release`." - + diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..f05c2e3 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,21 @@ +# Roadmap + +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. + +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. +- **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. + +## Three-branch Makefile targets + +GitHub issue #6. `Makefile.agents.mk` lacks `STAGING_BRANCH` support — no `promote` target, no staging guard rails. The skills handle three-branch mode but the Makefile doesn't. diff --git a/adapters/claude/header.md b/adapters/claude/header.md index ed35b67..696a8e5 100644 --- a/adapters/claude/header.md +++ b/adapters/claude/header.md @@ -1,4 +1,4 @@ -You are executing the `/{skill}` skill. Your argument is: $ARGUMENTS +{description} --- diff --git a/skills/release.md b/skills/release.md index aae011f..09cad71 100644 --- a/skills/release.md +++ b/skills/release.md @@ -1,7 +1,7 @@ --- skill: release type: skill -description: "Create a GitHub Release; in two-branch and three-branch mode, also promotes the pre-production branch to `{{BRANCH_PROD}}`" +description: Create a GitHub Release and promote the pre-production branch to production args: none ---