forge-workflow 0.0.9 → 0.1.0-beta.2

package/{.github/prompts/plan.prompt.md → skills/plan/SKILL.md}

@@ -1,14 +1,35 @@
 ---
 name: plan
-description: Design intent → research → branch + worktree + task list
-tools: []
+description: >
+  Forge PLAN stage — first stop when starting a NEW or unscoped feature. Sets up an
+  isolated worktree up front, then runs one-question-at-a-time brainstorming for design
+  intent, commits a design doc, does technical/OWASP/DRY + codebase research, and produces a
+  TDD task list for /dev. Trigger on "let's plan X", "scope a new feature", "brainstorm before we
+  build", "write a design doc", "break this into tasks", or "set up a worktree and task list
+  before coding". Reach for this even when the ask sounds like only design or only scoping —
+  plan owns intent → research → task-list setup as one stage. NOT for driving a feature to a
+  merged PR (that is smith), NOT for implementing tasks that already exist (dev), NOT for a
+  standalone deep-research pass into an approved design doc (research), NOT for reporting
+  where work stands or what is stale (status), and NOT for everyday issue create/list/close or
+  picking the next ready issue (issue-basics / triage-ready).
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob
 ---
 
 Plan a feature from scratch: brainstorm design intent, research technical approach, then set up branch, worktree, and a complete task list ready for /dev.
 
 # Plan
 
-This command runs in **3 phases**. Each phase ends with a HARD-GATE. Do not skip phases.
+`/plan` is the default planning super-skill. A full invocation runs the three legacy sections below (intent, research, setup/task list), but v3 treats the internal planning work as callable sub-skills:
+
+- `plan.intent_capture`
+- `plan.parallel_research`
+- `plan.parallel_critics`
+- `plan.synthesis`
+- `plan.final_lock`
+
+Do not assume every invocation must run every sub-skill. Run only the requested/required sub-skill when the user asks for partial planning work, and record skipped nodes as skipped rather than silently deleting them from the graph. External planner artifacts may satisfy `/dev` entry without running `/plan`, per D34, if they provide the required structured task list and acceptance criteria.
+
+Planning template behavior is resolved through the runtime graph and `.forge/config.yaml`, not through a separate planner-only config file. Use `forge options why <plan-subskill>`, `forge options diff`, and `forge options lint` to inspect configured planning mode, convergence threshold, critic set, and partial invocation choices.
 
 ---
 
@@ -22,14 +43,15 @@ Before ANY planning work begins:
    - Tell the user: "You are on '<branch>'. Planning must start from a clean worktree on master.
      Run: git checkout master — then re-run /plan."
 3. If on master, create the worktree NOW before asking any questions:
-   a. bd worktree create .worktrees/<slug> --branch feat/<slug>
+   a. forge worktree create <slug> --branch feat/<slug>
    b. cd .worktrees/<slug>
 4. Confirm: "Working in isolated worktree: .worktrees/<slug> (branch: feat/<slug>)"
 5. Create the epic issue and record the stage transition:
    ```bash
-   bd create --title="<feature-name>" --type=epic
-   bd update <id> --status=in_progress
-   bash scripts/beads-context.sh stage-transition <id> none plan
+   forge create --title="<feature-name>" --type=epic
+   forge update <id> --status=in_progress
+   # Record the none→plan stage transition kernel-natively on the Forge issue.
+   forge comment <id> "Stage: none → plan"
    ```
 6. ONLY THEN begin Phase 1.
 
@@ -48,6 +70,8 @@ between parallel features or sessions.
 /plan <feature-slug>
 /plan <feature-slug> --strategic   # Major architecture change: creates design doc PR before Phase 2
 /plan <feature-slug> --continue    # After --strategic PR is merged: run Phase 2 + 3
+/plan <feature-slug> --only=critics # Partial invocation: run one planning sub-skill and record evidence
+/plan <feature-slug> --only=lock    # Partial invocation: lock an already-supported plan
 ```
 
 ---
@@ -59,10 +83,10 @@ Before proceeding to Phase 1, check for cross-developer conflicts:
 
 ```bash
 # Auto-sync to get latest team state
-bash scripts/sync-utils.sh auto-sync
+forge sync || true
 
 # Check for conflicts with this issue's planned work area
-bash scripts/conflict-detect.sh --issue <beads-id>
+bash scripts/conflict-detect.sh --issue <forge-id>
 ```
 
 If exit code 2 (validation error): show error message, abort — do not show conflict prompt.
@@ -71,7 +95,7 @@ If exit code 1 (conflicts found):
 - Display the conflict output to the developer
 - Ask: "Other developers are working in overlapping areas. Proceed anyway? (y/n)"
 - If `n`: exit cleanly, no side effects
-- If `y`: log override via `bd comments add <id> "Conflict override: proceeding despite overlap with <conflicting-issues>"`, then continue to Phase 1
+- If `y`: log override via `forge comment <id> "Conflict override: proceeding despite overlap with <conflicting-issues>"`, then continue to Phase 1
 - Audit: record conflict override per OWASP A09
 
 If exit code 0: proceed silently to Phase 1.
@@ -100,7 +124,7 @@ If merge conflicts or unmet dependencies are found:
 - Display the findings to the developer
 - Ask: "In-flight PRs have potential conflicts. Proceed with planning anyway? (y/n)"
 - If `n`: exit cleanly, no side effects
-- If `y`: log override via `bd comments add <id> "PR coordination override: proceeding despite in-flight conflicts"`, then continue to Phase 1
+- If `y`: log override via `forge comment <id> "PR coordination override: proceeding despite in-flight conflicts"`, then continue to Phase 1
 
 ---
 
@@ -109,7 +133,7 @@ If merge conflicts or unmet dependencies are found:
 Before starting planning, verify team identity is mapped:
 
 ```bash
-bash scripts/forge-team/index.sh verify 2>&1 || true
+forge team verify 2>&1 || true
 ```
 
 If verify reports issues, address them before proceeding (the output will include `FORGE_AGENT_7f3a:PROMPT:` directives with exact commands to run).
@@ -125,11 +149,14 @@ If verify reports issues, address them before proceeding (the output will includ
 Before exploring context or asking questions, check for potential conflicts with in-flight work:
 
 ```bash
-# If a Beads issue ID is known (e.g., from /status or bd ready):
-bash scripts/dep-guard.sh check-ripple <beads-issue-id>
+# If a Forge issue ID is known (e.g., from /status or forge ready):
+# Advisory only — runs when the dep-guard tooling is present; a failure is non-fatal.
+if [ -f scripts/dep-guard.sh ]; then
+  bash scripts/dep-guard.sh check-ripple <forge-issue-id> || echo "dep-guard ripple check skipped (advisory)"
+fi
 
 # If no issue exists yet (first-time plan):
-bd list --status=open,in_progress
+forge list --status=open,in_progress
 ```
 
 Review the output. If overlaps are detected:
@@ -156,7 +183,7 @@ When `check-ripple` detects overlapping issues AND contract metadata is availabl
    - **CRITICAL**: Consumer is in an active in_progress issue's task list
 3. **When uncertain, default to HIGH** — conservative over permissive
 4. Recommend one action:
-   - Add dependency (`bd dep add <source> <target>`)
+   - Add dependency (`forge issue dep add <source> <target>`)
    - Coordinate with other issue's developer
    - Scope down current feature to avoid overlap
    - Proceed as-is (no real conflict)
@@ -203,7 +230,7 @@ Propose 2-3 concrete approaches with:
 
 ### Step 4: Write design doc
 
-Save to `docs/plans/YYYY-MM-DD-<slug>-design.md` with these sections:
+Save to `docs/work/YYYY-MM-DD-<slug>/plan.md` with these sections:
 - **Feature**: slug, date, status
 - **Purpose**: what problem it solves
 - **Success criteria**: measurable, specific
@@ -215,7 +242,7 @@ Save to `docs/plans/YYYY-MM-DD-<slug>-design.md` with these sections:
 
 Commit the design doc:
 ```bash
-git add docs/plans/YYYY-MM-DD-<slug>-design.md
+git add docs/work/YYYY-MM-DD-<slug>/plan.md
 git commit -m "docs: add design doc for <slug>"
 ```
 
@@ -228,7 +255,7 @@ After committing the design doc, push to a proposal branch and open PR:
 git checkout -b feat/<slug>-proposal
 git push -u origin feat/<slug>-proposal
 gh pr create --title "Design: <feature-name>" \
-  --body "Design doc for review. See docs/plans/YYYY-MM-DD-<slug>-design.md"
+  --body "Design doc for review. See docs/work/YYYY-MM-DD-<slug>/plan.md"
 ```
 
 **STOP here.** Present the PR URL. Wait for the user to merge the proposal PR.
@@ -239,8 +266,8 @@ After merge, run `/plan <slug> --continue` to proceed to Phase 2 + 3.
 ```
 <HARD-GATE: Phase 1 exit>
 Do NOT begin Phase 2 (web research) until:
-1. User has approved the design in this session
-2. Design doc exists at docs/plans/YYYY-MM-DD-<slug>-design.md
+1. User has approved the design in this session OR external-planner evidence satisfies the `/dev` entry contract from D34
+2. Design doc exists at docs/work/YYYY-MM-DD-<slug>/plan.md
 3. Design doc includes: success criteria, edge cases, out-of-scope, ambiguity policy
 4. Design doc is committed to git
 </HARD-GATE>
@@ -252,84 +279,39 @@ Do NOT begin Phase 2 (web research) until:
 
 **Goal**: Find HOW to build it — best practices, known issues, security risks, TDD scenarios.
 
-Record the phase transition before starting research:
+Record the phase transition before starting research (kernel-native):
 ```bash
-bash scripts/beads-context.sh stage-transition <id> plan research
+forge comment <id> "Stage: plan → research"
 ```
 
-Run these in parallel:
+Delegate the technical investigation to the **research** skill, which owns this bundle so it
+can be invoked on its own and reused mid-flow by other stages:
 
-### Web research (parallel-deep-research skill)
 ```
-Skill("parallel-deep-research")
+Skill("research")   # run in "Plan bundle" mode for this feature's design doc
 ```
-Search for:
-- "[tech stack] [feature] best practices [year]"
-- "[library/framework] [feature] implementation patterns"
-- "Known issues / gotchas with [approach selected]"
-
-### OWASP Top 10 analysis
-
-For this feature's risk surface, document each relevant OWASP category:
-- What the risk is
-- Whether it applies to this feature
-- What mitigation will be implemented
-
-### Codebase exploration (Explore agent)
-- Similar existing patterns to reuse
-- Files this feature will affect
-- Existing test infrastructure to leverage
-
-### DRY check (mandatory — use actual search tools)
-
-Before finalizing the approach, run Grep/Glob/Read searches for existing implementations of the planned function or pattern. Do not rely on memory or assumptions — execute the searches.
-
-```
-Grep(searchTerm)   # e.g., the function or concept name
-Glob("**/*.js")    # narrow to affected file types if needed
-Read(matchedFile)  # inspect any match in context
-```
-
-If a match is found:
-- Update the design doc's "Approach selected" section to say "extend existing [file/function]" — not "create new".
-- Note the existing file path and line number in the design doc.
-
-If no match is found: proceed. The DRY gate is cleared.
-
-### Blast-radius search (mandatory for remove/rename/replace features)
-
-If this feature involves **removing**, **renaming**, or **replacing** a concept, tool, or dependency:
-
-1. Grep the ENTIRE codebase for the thing being removed/renamed:
-   ```
-   Grep("<thing-being-removed>")     # exact name
-   Grep("<thing-being-removed>", -i)  # case-insensitive variant
-   Glob("**/*<thing>*")              # files named after it
-   ```
-
-2. For EVERY match found:
-   - Note the file path and line number in the design doc
-   - Add a cleanup task to the task list (Phase 3)
-   - Flag matches in unexpected packages or config files explicitly
-
-3. Common hiding spots to check:
-   - `package.json` (scripts, dependencies, description)
-   - `install.sh` / setup scripts
-   - CI/CD workflows (`.github/workflows/`)
-   - Agent config files (`lib/agents/`, `.cursorrules`, etc.)
-   - Documentation (`docs/`, `README.md`, `AGENTS.md`)
-   - Import statements and require() calls
-
-If no removal/rename is involved, this section is skipped.
 
-### TDD test scenarios
+Hand research the approved approach and the design doc path. It runs the following in parallel
+and appends the results under a `## Technical Research` section in the design doc (not a
+separate file):
 
-Identify at minimum 3 test scenarios:
-- Happy path
-- Error / failure path
-- Edge case from Phase 1
+- **Web research** — best practices, implementation patterns, and known gotchas for the chosen
+  approach. (For an external market/vendor landscape, research escalates to
+  `parallel-deep-research`; code-level questions use WebSearch/Context7.)
+- **OWASP Top 10 analysis** — for each relevant category: the risk, whether it applies, and the
+  mitigation to implement.
+- **DRY check** — Grep/Glob/Read for existing implementations; if found, switch "Approach
+  selected" to "extend existing <file>:<line>" instead of "create new".
+- **Blast-radius search** (mandatory for remove/rename/replace) — grep the ENTIRE repo (exact +
+  case-insensitive + filename glob) and record every hit (including `package.json`, setup
+  scripts, `.github/workflows/`, agent config, and docs), adding a cleanup task for each.
+- **Codebase exploration** (Explore agent) — similar patterns to reuse, affected files, and
+  test infrastructure to leverage.
+- **TDD test scenarios** — at least 3: happy path, error/failure path, and one Phase-1 edge case.
 
-Append all research findings to the design doc under a `## Technical Research` section (not a separate file).
+If the research skill is not available in the active toolset, run the same bundle inline with
+WebSearch/WebFetch, Grep/Glob/Read, and the Explore agent — the Phase 2 exit gate below verifies
+the outputs regardless of who produced them.
 
 ---
 
@@ -349,9 +331,9 @@ Do NOT begin Phase 3 (setup) until:
 
 **Goal**: Create branch, worktree, and a complete task list ready for /dev.
 
-Record the phase transition before starting setup:
+Record the phase transition before starting setup (kernel-native):
 ```bash
-bash scripts/beads-context.sh stage-transition <id> research setup
+forge comment <id> "Stage: research → setup"
 ```
 
 ### Step 1: Link child issues to the epic
@@ -359,7 +341,7 @@ bash scripts/beads-context.sh stage-transition <id> research setup
 The epic was created in the Entry HARD-GATE (Phase 1 entry). If this feature requires child issues (sub-tasks tracked separately), create them now and link to the epic:
 
 ```bash
-bd create --title="<sub-task-name>" --type=feature --parent=<epic-id>
+forge create --title="<sub-task-name>" --type=feature --parent=<epic-id>
 ```
 
 ### Step 2: Branch + worktree
@@ -377,9 +359,9 @@ else
   # Step 2b: Verify .worktrees/ is gitignored — add if missing
   git check-ignore -v .worktrees/ || echo ".worktrees/" >> .gitignore
 
-  # Step 2c: Create a Beads-aware worktree rooted on master
+  # Step 2c: Create an isolated worktree rooted on master
   git checkout master
-  bd worktree create .worktrees/<slug> --branch feat/<slug>
+  forge worktree create <slug> --branch feat/<slug>
   cd .worktrees/<slug>
 fi
 ```
@@ -439,53 +421,54 @@ For each task, confirm it maps to a specific requirement, success criterion, or
 
 **Before finalizing**: flag any tasks that touch areas not fully specified in the design doc. Present flagged tasks to user for quick clarification before saving.
 
-Save to `docs/plans/YYYY-MM-DD-<slug>-tasks.md`.
+Save to `docs/work/YYYY-MM-DD-<slug>/tasks.md`.
 
-### Step 5b: Beads context
+### Step 5b: Issue context (design + acceptance)
 
-After saving the task list, attach design context and acceptance criteria to the Beads issue so downstream stages (`/dev`, `/validate`, `/review`) can retrieve it without re-reading the design doc.
+After saving the task list, attach design context and acceptance criteria to the Forge issue so downstream stages (`/dev`, `/validate`, `/review`) can retrieve it without re-reading the design doc. These are native Kernel issue fields — no separate tracker required.
 
 ```bash
-# Link design metadata (task count + task file path) to the Beads issue
-bash scripts/beads-context.sh set-design <id> <task-count> docs/plans/YYYY-MM-DD-<slug>-tasks.md
+# Link design metadata (task count + task file path) to the Forge issue
+forge update <id> --design "<task-count> tasks | docs/work/YYYY-MM-DD-<slug>/tasks.md"
 
 # Record the success criteria from the design doc on the issue
-bash scripts/beads-context.sh set-acceptance <id> "<success-criteria from design doc>"
+forge update <id> --acceptance "<success-criteria from design doc>"
 ```
 
-Both commands must exit with code 0. If either fails, investigate (wrong issue ID? missing script?) before continuing.
+Both commands must exit with code 0. If either fails, investigate (wrong issue ID? bad flag value?) before continuing.
 
-### Step 5c: Contract extraction and logic-level dependency review
+### Step 5c: Contract extraction and logic-level dependency review (advisory, optional)
 
-After saving the task list and Beads context, extract and store contract metadata, then run the logic-level Phase 3 dependency review:
+After saving the task list and issue context, extract and store contract metadata, then run the logic-level Phase 3 dependency review. **This step uses the `dep-guard` dependency tooling; on a kernel-only setup it is skipped — it is advisory and never a hard block.**
 
 ```bash
-# Extract contracts — only call store-contracts if extract succeeds (exit 0)
-if bash scripts/dep-guard.sh extract-contracts docs/plans/YYYY-MM-DD-<slug>-tasks.md > /tmp/contracts.txt; then
-  bash scripts/dep-guard.sh store-contracts <id> "$(cat /tmp/contracts.txt)"
-else
-  echo "No contracts found — skipping store-contracts"
+if [ -f scripts/dep-guard.sh ]; then
+  # extract-contracts exits 1 when there simply are no contracts (normal, not an error),
+  # so store-contracts only runs when contracts were actually extracted.
+  if bash scripts/dep-guard.sh extract-contracts docs/work/YYYY-MM-DD-<slug>/tasks.md > /tmp/contracts.txt; then
+    # Contracts found — store them. A real store-contracts failure stays visible (not masked).
+    bash scripts/dep-guard.sh store-contracts <id> "$(cat /tmp/contracts.txt)"
+  fi
+  # check-ripple is advisory (needs the dependency-guard tooling); a failure is non-fatal.
+  bash scripts/dep-guard.sh check-ripple <id> || echo "dep-guard ripple check skipped (advisory)"
 fi
-
-# Re-run ripple check using Beads JSON + logic-level analysis
-bash scripts/dep-guard.sh check-ripple <id>
 ```
 
 `extract-contracts` exits 1 when no contracts are found (not an error — just nothing to store). `store-contracts` must exit 0 if called.
 
-`check-ripple` is now advisory but logic-aware. It should:
-- read Beads issue data via JSON
+When available, `check-ripple` is advisory but logic-aware. It should:
+- read the issue data via JSON
 - analyze import/call-chain, contract, and behavioral dependency signals
 - show rubric score, confidence, issue pairs, and proposed dependency updates with pros/cons
 - stop for user approval whenever a dependency mutation is proposed
 
-If the user approves a dependency mutation, apply it explicitly:
+If the user approves a dependency mutation, apply it explicitly (only when the tooling is present):
 
 ```bash
 bash scripts/dep-guard.sh apply-decision <id> <dependent-id> <depends-on-id> "<approval rationale>"
 ```
 
-That approval step must validate with `bd dep cycles`, show `bd graph`, summarize `bd ready`, and persist the decision via `bd set-state` plus `bd comments`. Beads remains the canonical machine-readable decision record; the plan docs hold only the concise summary.
+That approval step must inspect blockers with `forge issue blocked` (and `forge issue children <epic-id>` for the epic rollup), summarize `forge ready`, and persist the decision via `forge update` plus `forge comment`. The Forge Kernel is the canonical machine-readable decision record; the plan docs hold only the concise summary.
 
 ### Step 6: User review
 
@@ -495,68 +478,60 @@ Present the full task list. Allow the user to reorder, split, or remove tasks.
 
 ```
 <HARD-GATE: /plan exit>
-Do NOT proceed to /dev until ALL are confirmed:
+For a full `/plan` handoff only, do NOT hand off from `/plan` to `/dev` until ALL are confirmed:
 1. git branch --show-current output shows feat/<slug>
 2. git worktree list shows .worktrees/<slug>
 3. Baseline tests ran — either passing OR user confirmed to proceed past failures
-4. Beads issue is created with status=in_progress
-5. Task list exists at docs/plans/YYYY-MM-DD-<slug>-tasks.md
+4. Forge issue is created and in_progress (`forge issue show <id>` confirms status=in_progress)
+5. Task list exists at docs/work/YYYY-MM-DD-<slug>/tasks.md
 6. User has confirmed task list is correct
-7. `beads-context.sh set-design` ran successfully (exit code 0)
-8. `beads-context.sh set-acceptance` ran successfully (exit code 0)
-9. `dep-guard.sh store-contracts` ran successfully (exit code 0) — or skipped if no contracts found
-10. `dep-guard.sh check-ripple` ran successfully and any proposed dependency mutation was reviewed with the user before calling `apply-decision`
+7. Design captured on the Forge issue — `forge update <id> --design ...` ran successfully (exit code 0)
+8. Acceptance criteria captured on the Forge issue — `forge update <id> --acceptance ...` ran successfully (exit code 0)
+9. Contract metadata stored via `dep-guard store-contracts` (exit code 0) — or skipped if no contracts found OR the beads-backed dep-guard tooling is unavailable
+10. `dep-guard check-ripple` reviewed with the user before any `apply-decision` dependency mutation — or skipped when the dep-guard tooling is unavailable
+
+If `/dev` is entered from an external planner, this `/plan` exit gate is not required. Instead, the external artifact must satisfy the L1 `/dev` entry contract: structured task list, acceptance criteria, and enough design intent for TDD implementation.
+
+If only a sub-skill was invoked, do not claim full `/plan` completion. Record that sub-skill's evidence, gate outcome, and skipped graph nodes.
 </HARD-GATE>
 ```
 
-After all HARD-GATE items pass, validate context and record the stage transition:
+After all HARD-GATE items pass, confirm issue context and record the stage transition kernel-natively on the Forge issue:
 
 ```bash
-bash scripts/beads-context.sh validate <id>
-bash scripts/beads-context.sh stage-transition <id> plan dev \
-  --summary "<design approach chosen, task count>" \
-  --decisions "<key trade-offs resolved during Q&A>" \
-  --artifacts "docs/plans/YYYY-MM-DD-<slug>-design.md docs/plans/YYYY-MM-DD-<slug>-tasks.md" \
-  --next "<first dev task focus area>"
+# Confirm the issue carries design + acceptance context.
+forge issue show <id>
+
+# Record the plan→dev transition kernel-natively (Stage:/Summary:/Decisions:/Artifacts:/Next: envelope).
+forge comment <id> "Stage: plan complete → ready for dev
+Summary: <design approach chosen, task count>
+Decisions: <key trade-offs resolved during Q&A>
+Artifacts: docs/work/YYYY-MM-DD-<slug>/plan.md docs/work/YYYY-MM-DD-<slug>/tasks.md
+Next: <first dev task focus area>"
 ```
 
 ---
 
-## Example Output (Phase 3 complete)
-
-```
-✓ Phase 1: Design intent captured
-  - Design doc: docs/plans/<date>-<slug>-design.md
-  - Approach: <selected approach> (selected over <alternatives>)
-  - Ambiguity policy: Rubric scoring (>= 80% proceed, < 80% ask)
-
-✓ Phase 2: Technical research complete
-  - OWASP Top 10: <N> risks identified, <N> mitigations planned
-  - TDD scenarios: <N> identified
-  - Sources: <N> references
+## Dynamic Phase 3 Output
 
-✓ Phase 3: Setup complete
-  - Beads: <issue-id> (in_progress)
-  - Branch: feat/<slug>
-  - Worktree: .worktrees/<slug> (baseline: <N>/<N> tests passing)
-  - Task list: docs/plans/<date>-<slug>-tasks.md (<N> tasks)
+Phase 3 output is generated from the live Forge issue, branch/worktree setup, baseline validation, and task list paths at runtime. It reports the Forge issue, branch, worktree, `docs/work/YYYY-MM-DD-<slug>/plan.md`, and `docs/work/YYYY-MM-DD-<slug>/tasks.md` from the actual run instead of a static example.
 
-⏸️  Task list ready for review. Confirm to proceed.
+## Integration with Workflow
 
-After confirming, run: /dev
 ```
+Utility: /status     -> Understand current context before starting
 
-## Integration with Workflow
+Default template:
+  /plan     -> Optional default planner; external planners may satisfy /dev entry
+  /dev      -> Implement each task with subagent-driven TDD and continuous validation
+  /ship     -> Push + create PR
+  /review   -> Address GitHub Actions, Greptile, SonarCloud
+  /verify   -> Post-merge CI check on default branch
 
-```
-Utility: /status     → Understand current context before starting
-Stage 1: /plan       → Design intent → research → branch + worktree + task list (you are here)
-Stage 2: /dev        → Implement each task with subagent-driven TDD
-Stage 3: /validate      → Type check, lint, tests, security — all fresh output
-Stage 4: /ship       → Push + create PR
-Stage 5: /review     → Address GitHub Actions, Greptile, SonarCloud
-Stage 6: /premerge   → Update docs, hand off PR to user
-Stage 7: /verify     → Post-merge CI check on main
+Manual/support surfaces:
+  /validate  -> Cold-start or recovery validation, not a required stage boundary
+
+Pre-merge gate: doc updates + CI-green checkpoint embedded in /ship and /review (not a separate stage).
 ```
 
 ## Tips

package/skills/plan/evals/evals.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "I want to build a rate-limiter for our public API — help me nail down the design, then break it into tasks before I write any code.",
+    "should_trigger": true
+  },
+  {
+    "query": "Let's kick off the webhook-retry feature: ask me the key decisions one at a time, write it up, and set me up to start developing.",
+    "should_trigger": true
+  },
+  {
+    "query": "Scope out adding SSO to the admin dashboard — pin down requirements and edge cases and give me an ordered TDD task list on its own branch.",
+    "should_trigger": true
+  },
+  {
+    "query": "Before anyone touches the notification service I want a real plan: a worktree, some research on the approach, and a task list /dev can just run.",
+    "should_trigger": true
+  },
+  {
+    "query": "Starting the CSV-export epic today — brainstorm the approach with me and produce a committed design doc plus tasks.",
+    "should_trigger": true
+  },
+  {
+    "query": "Grab the highest-priority ready issue and take it all the way to an open PR — plan, build, validate, ship — just pause for my approval before merge.",
+    "should_trigger": false
+  },
+  {
+    "query": "The design doc and task list are already in docs/work; start implementing the first task with RED-GREEN-REFACTOR.",
+    "should_trigger": false
+  },
+  {
+    "query": "The design is approved and written — now go do the deep web and codebase research and append it under the Technical Research section.",
+    "should_trigger": false
+  },
+  {
+    "query": "Which stage am I on for the billing branch, and is any of my work going stale?",
+    "should_trigger": false
+  },
+  {
+    "query": "Create a bug issue for the broken logout redirect and link it under the auth epic.",
+    "should_trigger": false
+  }
+]