diff --git a/.agents/README.md b/.agents/README.md index 371444a89d..b102aff013 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -337,28 +337,28 @@ small. To delegate without switching models, delegate to `general`. report with your intent: "investigate this and find the possible cause", "investigate and tell me where this points", or "does this still apply?". Explore until you and the agent roughly agree on the problem. -2. **Write the plan.** Run `/make-a-plan` — it executes in Build mode. - If you need to step in and answer something yourself, press TAB to - leave Build mode. Use Plan mode only when you want a hard guarantee - that the agent modifies no file under any circumstance. If you +2. **Write the plan.** Invoke `@make-a-plan`. Skills use the current agent; + select Build mode first when the skill needs to write files. Use Plan mode + only when you want a hard guarantee that the agent modifies no file under + any circumstance. If you explored with a weaker model but want a stronger one to write the plan, switch models first or delegate: - `/make-a-plan delegate to @engineer-glm`. + `@make-a-plan delegate to @engineer-glm`. 3. **Iterate on the plan.** The plan is saved to `.agents/plans/`, so you - never depend on LLM memory: read the file directly, or run `/review-plan` + never depend on LLM memory: read the file directly, or invoke `@review-plan` for a second opinion (delegation works here too). Complex plans deserve a review; simple ones can skip it. -4. **Execute.** Run `/implement-plan`. It first prints the full picture — +4. **Execute.** Invoke `@implement-plan`. It first prints the full picture — whether it will create an issue and a branch, the execution style, and a task checklist — and waits for your go-ahead. Say "step by step" to stop after each task (one commit per task) so you can verify as it goes; the default runs all tasks with one final commit. -5. **Land the work.** When it finishes, either push yourself and run - `/create-pr`, or loop `/review-code` → `/make-a-plan` → - `/implement-plan` until the findings are addressed, then push and - `/create-pr`. Nothing pushes for you — you always push from your shell. +5. **Land the work.** When it finishes, either push yourself and invoke + `@create-pr`, or loop `@review-code` → `@make-a-plan` → + `@implement-plan` until the findings are addressed, then push and invoke + `@create-pr`. Nothing pushes for you — you always push from your shell. -> Note: `/implement-plan` checks the current branch. On a base branch +> Note: `@implement-plan` checks the current branch. On a base branch > (`main`, `develop`, `staging`) it creates a GitHub issue and a branch > `issue-NNNN`; on an existing feature branch it continues there and > creates nothing. The pre-run summary tells you which applies. Read the @@ -367,14 +367,14 @@ small. To delegate without switching models, delegate to `general`. ### Big feature with multiple plans -When the work is too large for a single plan, tell `/make-a-plan` +When the work is too large for a single plan, tell `@make-a-plan` up front: produce a high-level roadmap where each task will get its own execution plan, and the roadmap doubles as the progress tracker. From there the flow mirrors the issue flow above, one level down: -take each roadmap task in turn, write its own plan (`/make-a-plan`, +take each roadmap task in turn, write its own plan (`@make-a-plan`, delegating when it helps), review it when the task is complex -(`/review-plan`), implement it (`/implement-plan`), and mark progress +(`@review-plan`), implement it (`@implement-plan`), and mark progress on the roadmap as you land each piece. ### Plan file naming (base + derivatives) @@ -392,7 +392,7 @@ keeps everything adjacent in `ls`: `2026-09-20-upload-pipeline-roadmap--task-01-chunk-upload.md` - Chained: `...--task-02-gc--review-01.md` -While a plan is still unimplemented, `/make-a-plan` revises it in +While a plan is still unimplemented, `@make-a-plan` revises it in place. Once implemented and reviewed, it writes a new followup file. Full rules live in the `planner` skill. @@ -401,11 +401,11 @@ Full rules live in the `planner` skill. Every plan carries `Status: draft | reviewed | done` plus an append-only `Review Log` (UTC ISO 8601, one line per entry): -- `draft` — fresh from `/make-a-plan`. -- `reviewed` — review feedback incorporated. `/review-plan` stays - read-only; only your explicit "apply" makes `/make-a-plan` apply +- `draft` — fresh from `@make-a-plan`. +- `reviewed` — review feedback incorporated. `@review-plan` stays + read-only; only your explicit "apply" makes `@make-a-plan` apply the changes, flip the status, and log one line. -- `done` — `/implement-plan` closes it on completion, logging the +- `done` — `@implement-plan` closes it on completion, logging the issue URL when one exists (never commit hashes). A plan approved with no changes goes `draft` → `done` directly. @@ -516,11 +516,11 @@ JSON, REPL access, and so on. ### A typical round -1. `/make-a-plan` — you get a plan and a saved file in `.agents/plans/`. -2. `/review-plan` — a second opinion; approve or request changes. -3. `/implement-plan` — the code gets written and committed. Starting from a base branch, it also opens the GitHub issue and the `issue-NNNN` branch; the plans that follow continue on that same branch. -4. `/review-code` — a reviewer checks the commit. -5. `/create-pr` — the branch goes up as a pull request. +1. `@make-a-plan` — you get a plan and a saved file in `.agents/plans/`. +2. `@review-plan` — a second opinion; approve or request changes. +3. `@implement-plan` — the code gets written and committed. Starting from a base branch, it also opens the GitHub issue and the `issue-NNNN` branch; the plans that follow continue on that same branch. +4. `@review-code` — a reviewer checks the commit. +5. `@create-pr` — the branch goes up as a pull request. Every step also works on its own, and you can always say what you want in plain words — the agents pick the right skill from what you say. diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md index 3ab1ccf5d5..00d8fd7dc6 100644 --- a/.agents/skills/create-pr/SKILL.md +++ b/.agents/skills/create-pr/SKILL.md @@ -18,7 +18,7 @@ push — the user pushes from their own shell. - The user asks to open or create a NEW PR for the current task branch, in any phrasing ("open a PR", "create the pull request", "put this up for - review") — or runs `/create-pr`. → **Open mode**. + review") — or invokes `@create-pr`. → **Open mode**. - The user asks to fix or update an EXISTING PR's title or description to match conventions. → **Update mode**. @@ -59,7 +59,7 @@ Run all checks before reporting, then report every failure together: 5. **Branch not pushed.** The remote-tracking ref `origin/` is missing, or `git rev-parse origin/` differs from HEAD — the branch was never pushed, or has commits the remote does not have. Never - push yourself; ask the user to push and to run `/create-pr` again + push yourself; ask the user to push and to invoke `@create-pr` again afterwards, then stop. ### 3. Already-open PR diff --git a/.agents/skills/implement-plan/SKILL.md b/.agents/skills/implement-plan/SKILL.md index ec81467343..87b7e2bf53 100644 --- a/.agents/skills/implement-plan/SKILL.md +++ b/.agents/skills/implement-plan/SKILL.md @@ -26,9 +26,9 @@ in the local working tree. - The user asks to implement or execute a plan, in any phrasing: "implement the plan", "execute it", "go build it" — or runs - `/implement-plan`. + `@implement-plan`. - A ready, reviewed plan is in the session context or a plan file path - was given (typically after `/make-a-plan` or `/review-plan`). + was given (typically after `@make-a-plan` or `@review-plan`). Do not use it to produce plans — that is the `make-a-plan` flow. @@ -149,9 +149,9 @@ stop and ask the user before splitting it. End by suggesting the next steps (suggestions, not a required pipeline — any instruction from me overrides them): -- `/review-code` — to review the changes just committed; it routes to - `/make-a-plan` by itself if the findings need one. -- `/create-pr` — when the task is done and the branch is ready to merge. +- `@review-code` — to review the changes just committed; it routes to + `@make-a-plan` by itself if the findings need one. +- `@create-pr` — when the task is done and the branch is ready to merge. ## User input, overrides and additional context diff --git a/.agents/skills/make-a-plan/SKILL.md b/.agents/skills/make-a-plan/SKILL.md index 2314b559a8..09f9a86a56 100644 --- a/.agents/skills/make-a-plan/SKILL.md +++ b/.agents/skills/make-a-plan/SKILL.md @@ -16,12 +16,12 @@ stop — this skill needs the build agent to save the plan. - The user asks to plan, design, or break down a task, in any phrasing: "make a plan", "how would we build X", "design an approach for Y" — - or runs `/make-a-plan`. + or invokes `@make-a-plan`. - The user asks to rework or extend an existing plan. While the plan is still unimplemented (pre-`implement-plan` iteration, e.g. after - `/review-plan` findings or user feedback), revise the saved plan file + `@review-plan` findings or user feedback), revise the saved plan file in place. Once the plan has been implemented and reviewed (post - `/review-code` findings on committed work), write a new derived plan + `@review-code` findings on committed work), write a new derived plan file instead — never rewrite the executed plan. The `planner` skill defines the derived naming (`--review-NN`, `--task-NN`). - The user says to apply `review-plan` findings to a still-unimplemented @@ -101,8 +101,8 @@ constraints and risks, what is deliberately out of scope, and the path where the is saved. Never assume that a short list of task names is enough context. End the final response by suggesting the next steps, in this order: -1. `/review-plan` — to get a second opinion on the plan before executing it. -2. `/implement-plan` — to execute the plan from the current session context. +1. `@review-plan` — to get a second opinion on the plan before executing it. +2. `@implement-plan` — to execute the plan from the current session context. These are suggestions, not a required pipeline — any instruction from me overrides them (for example, asking you to implement the plan directly). diff --git a/.agents/skills/planner/SKILL.md b/.agents/skills/planner/SKILL.md index a242cf83bd..c57cafa383 100644 --- a/.agents/skills/planner/SKILL.md +++ b/.agents/skills/planner/SKILL.md @@ -192,8 +192,8 @@ Source: review-code over `` (branch ``) | task `NN` of roadmap ` Created: YYYY-MM-DD ``` -End the response by suggesting the next steps: `/review-plan` to get a second -opinion on the plan and `/implement-plan` to execute it. +End the response by suggesting the next steps: `@review-plan` to get a second +opinion on the plan and `@implement-plan` to execute it. ### Plan Structure @@ -261,5 +261,5 @@ Before delivering the plan, confirm: - [ ] No task is XL or larger — break it down instead - [ ] Checkpoints exist after every 2-3 tasks - [ ] The response states the plan's path (saved or suggested) and suggests - `/review-plan` and `/implement-plan` + `@review-plan` and `@implement-plan` - [ ] The plan is ready for human review diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 65c811e71d..332e9ded5a 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -12,7 +12,7 @@ Act as a senior software engineer and perform a thorough code review. - The user asks to review code, in any phrasing: "review this diff", "review the PR", "check my changes", "code review" — or runs - `/review-code`. + `@review-code`. - A commit, branch, PR, or diff is ready and the user wants it assessed before merge. @@ -43,7 +43,7 @@ Act as a senior software engineer and perform a thorough code review. - **Approve (no required changes):** say so — there is nothing to address. - **Minor findings (nits):** applying them directly as-is is fine once the review is done — no plan needed. - - **Substantive findings:** suggest `/make-a-plan` to make a plan to address + - **Substantive findings:** suggest `@make-a-plan` to make a plan to address them. ### Hard rule — read-only while reviewing diff --git a/.agents/skills/review-plan/SKILL.md b/.agents/skills/review-plan/SKILL.md index c690df6b85..c286eeded0 100644 --- a/.agents/skills/review-plan/SKILL.md +++ b/.agents/skills/review-plan/SKILL.md @@ -12,15 +12,15 @@ implementation plan. ## When to use - The user asks to review a plan, in any phrasing: "review this plan", - "does this plan look right?", "second opinion on the plan" — or runs - `/review-plan`. -- A plan was just produced (typically by `/make-a-plan`) and the user + "does this plan look right?", "second opinion on the plan" — or invokes + `@review-plan`. +- A plan was just produced (typically by `@make-a-plan`) and the user wants it evaluated before executing it. ## Instructions 1. **Determine the plan under review** from the session context (for example, a - plan just produced by `/make-a-plan`) or from a plan file path given by the + plan just produced by `@make-a-plan`) or from a plan file path given by the user (typically under `.agents/plans/`). If a file path is given, read the file first so the complete plan is in context. 2. Delegate the review to the `general` subagent (via the task tool), unless the @@ -30,8 +30,8 @@ implementation plan. summarize it and do not act on its findings. 4. Right after the review, suggest the next step based on the verdict. These are suggestions — the user decides, and any instruction overrides them: - - **Approve** → suggest `/implement-plan` to execute it. - - **Request changes** → suggest `/make-a-plan` to make a plan to address the + - **Approve** → suggest `@implement-plan` to execute it. + - **Request changes** → suggest `@make-a-plan` to make a plan to address the findings. ### Hard rule — read-only while reviewing diff --git a/.agents/skills/ste/SKILL.md b/.agents/skills/ste/SKILL.md index 67e474ef6b..049c75c069 100644 --- a/.agents/skills/ste/SKILL.md +++ b/.agents/skills/ste/SKILL.md @@ -1,6 +1,6 @@ --- name: ste -description: Write or rewrite text in ASD-STE100 Simplified Technical English. ONLY use this skill when the user explicitly invokes it by name — i.e. they type "/ste" or literally write "use the ste skill" / "apply ASD-STE100". Do NOT trigger it on paraphrased intent such as "simplify this", "make it clearer", "write technical documentation", or "shorter sentences please" — the user has deliberately scoped this skill to explicit invocation only. For those requests, respond normally without loading this skill unless they name it. +description: Write or rewrite text in ASD-STE100 Simplified Technical English. ONLY use this skill when the user explicitly invokes it by name — i.e. they type "@ste" or literally write "use the ste skill" / "apply ASD-STE100". Do NOT trigger it on paraphrased intent such as "simplify this", "make it clearer", "write technical documentation", or "shorter sentences please" — the user has deliberately scoped this skill to explicit invocation only. For those requests, respond normally without loading this skill unless they name it. --- # ASD-STE100 Simplified Technical English @@ -11,7 +11,7 @@ Compliance note (for you, not for output): the official specification and its di ## When to use -Only when the user explicitly invokes it: they type `/ste`, or say "use +Only when the user explicitly invokes it: they type `@ste`, or say "use the ste skill" / "apply ASD-STE100". Requests like "simplify this", "make it clearer", or "shorter sentences" do NOT invoke it — respond normally unless it is named. diff --git a/.opencode/commands/create-pr.md b/.opencode/commands/create-pr.md deleted file mode 100644 index a6c21f7bb2..0000000000 --- a/.opencode/commands/create-pr.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -description: Create a PR for the current task branch or update an existing one — loads and follows the create-pr skill -agent: build ---- - -Load the **`create-pr`** skill and follow it as your only instruction. - -## User input, overrides and additional context - -$ARGUMENTS diff --git a/.opencode/commands/implement-plan.md b/.opencode/commands/implement-plan.md deleted file mode 100644 index eaf9d29fc3..0000000000 --- a/.opencode/commands/implement-plan.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -description: Execute a ready plan — task checklist, your confirmation, then all tasks with one commit (default) or step by step with a commit and a pause per task; creates issue + branch when on a base branch, or commits on the current branch with "direct" — loads and follows the implement-plan skill -agent: build ---- - -Load the **`implement-plan`** skill and follow it as your only instruction. - -## User input, overrides and additional context - -$ARGUMENTS diff --git a/.opencode/commands/make-a-plan.md b/.opencode/commands/make-a-plan.md deleted file mode 100644 index 27a2be5559..0000000000 --- a/.opencode/commands/make-a-plan.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -description: Investigate the chosen task, produce an implementation plan, and save it — loads and follows the make-a-plan skill -agent: build ---- - -Load the **`make-a-plan`** skill and follow it as your only instruction. - -## User input, overrides and additional context - -$ARGUMENTS diff --git a/.opencode/commands/resolve-git-conflicts.md b/.opencode/commands/resolve-git-conflicts.md deleted file mode 100644 index 05b13d3a4b..0000000000 --- a/.opencode/commands/resolve-git-conflicts.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: Resolve local git conflicts and stage the resolved files; never continues the rebase — loads and follows the resolve-git-conflicts skill -agent: build ---- - -Load the **`resolve-git-conflicts`** skill and follow it as your only instruction. diff --git a/.opencode/commands/review-code.md b/.opencode/commands/review-code.md deleted file mode 100644 index 4bea9ab7ff..0000000000 --- a/.opencode/commands/review-code.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -description: Code review — review a diff, PR, or code change — loads and follows the review-code skill -agent: build ---- - -Load the **`review-code`** skill and follow it as your only instruction. - -## User input, overrides and additional context - -$ARGUMENTS diff --git a/.opencode/commands/review-plan.md b/.opencode/commands/review-plan.md deleted file mode 100644 index 90bc6161a9..0000000000 --- a/.opencode/commands/review-plan.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -description: Plan review — evaluate an implementation plan before executing it — loads and follows the review-plan skill -agent: build ---- - -Load the **`review-plan`** skill and follow it as your only instruction. - -## User input, overrides and additional context - -$ARGUMENTS