forge-workflow 0.0.10 → 0.1.0-beta.2

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

@@ -1,7 +1,18 @@
 ---
 name: sonarcloud
-description: Pull issues, metrics, quality gates, and analysis data from SonarCloud
-tools: []
+description: >
+  Query SonarCloud code-quality data via the `/sonarcloud` slash command — the fast in-context
+  lookup for a project, branch, or PR. Handles `issues`, `metrics`, `gate` (pass/fail + failed
+  conditions), `health`, `pr <number>`, `hotspots`, `history`, plus `--branch`, `--severity`,
+  `--type`, `--new-code` filters. Use the moment the user types `/sonarcloud ...` or asks in
+  plain language: "what does SonarCloud say about this PR", "check the SonarCloud quality gate
+  before I ship", "SonarCloud blocker/critical bugs on develop", "new-code SonarCloud issues
+  on PR 214". Only READS/reports — does NOT fix findings or reply-to/resolve PR threads (that
+  is `review`); it is the lightweight command surface, NOT the deep-analysis session
+  correlating findings with local source or history trends (that is `sonarcloud-analysis`).
+  Not for local SAST scans of your own code, nor the Forge issue tracker (`forge issue ...`,
+  "open/ready issues") — here those bare words always mean SonarCloud.
+allowed-tools: Bash, Read, Grep, Glob, WebFetch
 ---
 
 # SonarCloud Query Command
@@ -41,7 +52,7 @@ Pull code quality data from SonarCloud. Requires `SONARCLOUD_TOKEN` environment
    - Optional filters (branch, severity, type, new-code, etc.)
 2. Check for `SONARCLOUD_TOKEN` environment variable. If not set, inform user.
 3. Check for `SONARCLOUD_ORG` environment variable or ask user for organization key.
-4. Execute the appropriate API call using curl or the TypeScript client at `next-app/src/lib/integrations/sonarcloud.ts`
+4. Execute the appropriate API call against the SonarCloud REST API (see the API Reference section below for endpoints)
 5. Format and present results clearly:
    - For issues: Group by severity/type, show file, line, message
    - For metrics: Show as table with metric name and value

package/skills/sonarcloud/evals/evals.json

@@ -0,0 +1,46 @@
+[
+  {
+    "query": "/sonarcloud gate my-project",
+    "should_trigger": true
+  },
+  {
+    "query": "/sonarcloud pr befach-web 214 --new-code",
+    "should_trigger": true
+  },
+  {
+    "query": "What does SonarCloud say about this pull request? Just the quality gate and the blocker issues, quick.",
+    "should_trigger": true
+  },
+  {
+    "query": "Show SonarCloud bugs and vulnerabilities on the develop branch for the api project",
+    "should_trigger": true
+  },
+  {
+    "query": "Any new-code SonarCloud issues on PR 88 before I ship?",
+    "should_trigger": true
+  },
+  {
+    "query": "Pull the SonarCloud coverage and code-smell numbers for my-project so I can eyeball them",
+    "should_trigger": true
+  },
+  {
+    "query": "Open an isolated SonarCloud deep-dive: correlate every flagged vulnerability with the actual source files, walk the analysis history for coverage trends, and hand back a synthesized technical-debt report",
+    "should_trigger": false
+  },
+  {
+    "query": "SonarCloud flagged issues on PR 214 — fix them, reply to each review thread, and mark them resolved",
+    "should_trigger": false
+  },
+  {
+    "query": "Run a SAST security scan over my code and list the vulnerabilities you find",
+    "should_trigger": false
+  },
+  {
+    "query": "Show me the open issues that are ready to work on next",
+    "should_trigger": false
+  },
+  {
+    "query": "Run lint and type-check and the test suite before I ship this branch",
+    "should_trigger": false
+  }
+]

package/skills/sonarcloud-analysis/SKILL.md

@@ -1,13 +1,18 @@
 ---
 name: sonarcloud-analysis
 description: >
-  Pull issues, metrics, quality gates, and analysis data from SonarCloud. ALWAYS
-  use this skill when the user mentions SonarCloud, asks about code quality metrics,
-  wants to check PR quality gates, or needs to review security vulnerabilities and
-  technical debt from static analysis. Also trigger during /review workflow when
-  SonarCloud issues need addressing. Trigger on phrases like "SonarCloud",
-  "quality gate", "code quality metrics", "technical debt", "coverage report",
-  "static analysis issues", "security vulnerabilities from scan".
+  SonarCloud deep-dive via its REST API: pull open issues (bugs, vulnerabilities, code
+  smells), coverage/duplication metrics, quality-gate pass/fail with failed thresholds,
+  security hotspots, and measure/analysis history for a whole project, branch, or PR, then
+  return a ranked summary. Use whenever the user names SonarCloud or asks about code-quality
+  metrics, technical debt, a red/failing quality gate, or static-analysis
+  vulnerabilities/hotspots — e.g. 'why is the SonarCloud gate failing on this PR' or 'pull
+  every BLOCKER vulnerability with file and line'. NOT for: the thin `/sonarcloud <query>
+  <project>` slash command for a quick lookup (sibling 'sonarcloud'); replying to/resolving PR
+  review threads across Greptile, CodeRabbit, or GitHub Actions ('review'); running local
+  lint/type-check/test/security scans pre-ship ('validate'); implementing or patching a
+  flagged issue ('dev'); or an external market/competitor report on SonarSource or DevSecOps
+  vendors ('parallel-deep-research').
 category: Code Quality
 tags: [sonarcloud, code-quality, issues, metrics, security]
 context: fork
@@ -77,12 +82,12 @@ export SONARCLOUD_ORG="your-org"
 export SONARCLOUD_PROJECT="your-project"
 
 # Common queries
-curl -H "Authorization: Bearer $TOKEN" \
-  "https://sonarcloud.io/api/issues/search?organization=$ORG&componentKeys=$PROJECT&resolved=false"
-curl -H "Authorization: Bearer $TOKEN" \
-  "https://sonarcloud.io/api/measures/component?component=$PROJECT&metricKeys=bugs,coverage"
-curl -H "Authorization: Bearer $TOKEN" \
-  "https://sonarcloud.io/api/qualitygates/project_status?projectKey=$PROJECT"
+curl -H "Authorization: Bearer $SONARCLOUD_TOKEN" \
+  "https://sonarcloud.io/api/issues/search?organization=$SONARCLOUD_ORG&componentKeys=$SONARCLOUD_PROJECT&resolved=false"
+curl -H "Authorization: Bearer $SONARCLOUD_TOKEN" \
+  "https://sonarcloud.io/api/measures/component?component=$SONARCLOUD_PROJECT&metricKeys=bugs,coverage"
+curl -H "Authorization: Bearer $SONARCLOUD_TOKEN" \
+  "https://sonarcloud.io/api/qualitygates/project_status?projectKey=$SONARCLOUD_PROJECT"
 ```
 
 ## Endpoints

package/skills/sonarcloud-analysis/evals/evals.json

@@ -1,50 +1,46 @@
 [
   {
-    "query": "Check the SonarCloud quality gate status for our latest PR — I want to see if there are any blockers before we can merge, especially around security vulnerabilities and code coverage",
+    "query": "Why is our quality gate red on this pull request? Break down exactly which conditions failed and by how much.",
     "should_trigger": true
   },
   {
-    "query": "Pull the SonarCloud analysis results for our project — show me all the critical and major security vulnerabilities found in the last scan, with file locations and remediation guidance",
+    "query": "How much technical debt has piled up in the codebase, and which files carry the worst maintainability rating?",
     "should_trigger": true
   },
   {
-    "query": "We're in /review and SonarCloud flagged some issues — get the full list of code smells, bugs, and vulnerabilities from the latest analysis so I can address them before the quality gate passes",
+    "query": "Give me the coverage and duplication numbers for the develop branch and flag the modules that regressed.",
     "should_trigger": true
   },
   {
-    "query": "What's our current technical debt ratio in SonarCloud? Show me the metrics dashboard — maintainability rating, reliability rating, security rating, and coverage percentage",
+    "query": "List every unresolved BLOCKER and CRITICAL vulnerability SonarCloud found, with file and line, so I know what to fix first.",
     "should_trigger": true
   },
   {
-    "query": "The SonarCloud quality gate is failing on our PR — pull the specific issues that are blocking it and show me what needs to be fixed, sorted by severity",
+    "query": "Pull the security hotspots that still need review and summarize the risk for each.",
     "should_trigger": true
   },
   {
-    "query": "Get the SonarCloud code coverage report for our project — I want to see which modules have low coverage and identify the files that need more tests before our next release",
+    "query": "Show me how our reliability and security ratings have trended over the last month of analyses.",
     "should_trigger": true
   },
   {
-    "query": "Implement a new REST API endpoint for user profile management with CRUD operations, input validation, and proper error handling",
+    "query": "/sonarcloud issues checkout-service --severity BLOCKER",
     "should_trigger": false
   },
   {
-    "query": "Search for best practices around implementing OAuth2 PKCE flow in a Node.js application",
+    "query": "Go through all the open PR review threads from Greptile and CodeRabbit, reply to each explaining the fix, and mark them resolved.",
     "should_trigger": false
   },
   {
-    "query": "Write a comprehensive market analysis of the DevSecOps tools landscape covering SAST, DAST, and SCA vendors",
+    "query": "Run lint, type-check, the test suite, and the security scanner and give me fresh output before I ship this branch.",
     "should_trigger": false
   },
   {
-    "query": "Scrape https://docs.sonarcloud.io and extract the full list of supported languages and analysis rules",
+    "query": "Fix the SQL-injection vulnerability SonarCloud flagged in login.ts and add a regression test.",
     "should_trigger": false
   },
   {
-    "query": "Build a structured company profile for SonarSource — return JSON with founding year, funding, products, and competitive positioning",
-    "should_trigger": false
-  },
-  {
-    "query": "Add proper citations to docs/research/security-audit-findings.md following our project's citation standards",
+    "query": "Produce a competitive market report comparing SonarCloud, Snyk, and Codacy for our tooling decision.",
     "should_trigger": false
   }
 ]

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

@@ -1,14 +1,24 @@
 ---
 name: status
-description: Check current stage and context
-tools: []
+description: >
+  Report where the project stands and what work is in flight -- the Forge status snapshot.
+  Reach for this at session start or whenever the user says "/status", "where am I", "what's
+  in progress", "catch me up", "resume work", or "what changed recently". It surfaces the workflow stage, your active/claimed issues, all issues ranked by
+  composite score with conflict-risk flags, stale already-merged issues (which it closes), and
+  recent commits. Use it to ORIENT and decide the next move -- it reports state; it does not
+  plan, develop, or claim issues. Not for: routing to a stage skill or documenting the full
+  issue-verb surface (kernel); ranking and EXPLAINING a single next-ready or blocked issue to
+  hand off (triage-ready); everyday create/update/list/close/comment/search issue ops
+  (issue-basics); the Hermes harness's token-bounded orient/recap contract (hermes-forge); or
+  the post-merge CI health check that closes issues after a merge lands (verify).
+allowed-tools: Bash, Read, Grep, Glob
 ---
 
 Check where you are in the project and what work is in progress.
 
 # Status Check
 
-This command helps you understand the current state of the project before starting new work.
+This skill helps you understand the current state of the project before starting new work.
 
 ## Usage
 
@@ -16,7 +26,7 @@ This command helps you understand the current state of the project before starti
 /status
 ```
 
-## What This Command Does
+## What This Skill Does
 
 ## Step 0: Sync team state
 
@@ -32,7 +42,7 @@ bash scripts/smart-status.sh
 ```
 This command dynamically computes and displays all issues ranked by composite score (priority, dependency impact, type, staleness, epic proximity). Output includes active sessions, conflict risk annotations, and grouped categories. No manual querying needed.
 
-For full context on any issue: `bd show <id>`
+For full context on any issue: `forge show <id>`
 
 ### Step 1b: Reconcile stale in-progress issues
 
@@ -44,15 +54,15 @@ DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|
 if [ -z "$DEFAULT_BRANCH" ]; then
   if git rev-parse --verify main >/dev/null 2>&1; then DEFAULT_BRANCH="main"
   elif git rev-parse --verify master >/dev/null 2>&1; then DEFAULT_BRANCH="master"
-  else echo "ERROR: No main or master branch found — skipping stale reconciliation" >&2; DEFAULT_BRANCH=""; fi
+  else echo "ERROR: No main or master branch found -- skipping stale reconciliation" >&2; DEFAULT_BRANCH=""; fi
 fi
 
 # For each in_progress issue, check if its PR was already merged
 if [ -n "$DEFAULT_BRANCH" ]; then
-  bd list --status=in_progress --json 2>/dev/null | jq -r '.[].id' | while read id; do
+  forge list --status=in_progress --json 2>/dev/null | jq -r '.[].id' | while read id; do
     # Search git log for the issue ID in commit messages (fixed-strings for literal match)
     if git log --oneline --first-parent "$DEFAULT_BRANCH" --fixed-strings --grep="$id" | grep -q .; then
-      echo "STALE: $id — found in git history, likely already merged"
+      echo "STALE: $id -- found in git history, likely already merged"
     fi
   done
 fi
@@ -60,7 +70,7 @@ fi
 
 If stale issues are found, close them:
 ```bash
-bd close <id> --force --reason="Already merged — detected during status reconciliation"
+forge close <id> --force --reason="Already merged -- detected during status reconciliation"
 ```
 
 ### Step 2: Review Recent Commits
@@ -89,4 +99,4 @@ forge team dashboard 2>&1 | head -5 || true
 
 - **If starting new work**: Run `/plan <feature-name>`
 - **If continuing work**: Resume with appropriate phase command
-- **If reviewing**: Run `/review <pr-number>` or `/premerge <pr-number>`
+- **If reviewing**: Run `/review <pr-number>` (the pre-merge doc gate is embedded in `/ship` and `/review`)

package/skills/status/evals/evals.json

@@ -0,0 +1,50 @@
+[
+  {
+    "query": "/status",
+    "should_trigger": true
+  },
+  {
+    "query": "where am I on this project right now?",
+    "should_trigger": true
+  },
+  {
+    "query": "catch me up -- what's in progress and what got merged recently?",
+    "should_trigger": true
+  },
+  {
+    "query": "I stepped away for a few days, give me the current state of the work before I dive back in",
+    "should_trigger": true
+  },
+  {
+    "query": "show me my active issues and which stage we're at",
+    "should_trigger": true
+  },
+  {
+    "query": "are there any in-progress issues that were already merged and should be closed?",
+    "should_trigger": true
+  },
+  {
+    "query": "what's the single best next issue to start, and explain why that one?",
+    "should_trigger": false
+  },
+  {
+    "query": "why is issue forge-456 blocked -- what's it waiting on?",
+    "should_trigger": false
+  },
+  {
+    "query": "route me to the correct Forge stage skill for opening a PR",
+    "should_trigger": false
+  },
+  {
+    "query": "create an issue titled 'fix flaky login test' and tag it a bug",
+    "should_trigger": false
+  },
+  {
+    "query": "the PR just merged to master -- confirm CI is green and close the linked issues",
+    "should_trigger": false
+  },
+  {
+    "query": "keep an eye on PR #88 until its checks and review threads settle",
+    "should_trigger": false
+  }
+]

package/skills/triage-ready/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: triage-ready
+description: >
+  Surfaces, ranks, and EXPLAINS the single best next issue in a Forge project — strictly
+  read-only. Recomputes the live ready queue and explains what is blocked via `forge issue
+  ready`/`blocked`/`stats`/`show`, always against the live kernel, never `forge board`.
+  Recommends ONE issue with a one-line reason, then hands off; never claims, comments, closes,
+  or mutates. Use when the user asks "what should I work on", "what's next", "what's ready",
+  "pick/triage my next task", "top of the ready queue", "which issue should I start", "why is
+  this issue blocked", or "what's blocking the most work". NOT for claiming or taking
+  ownership of the pick (use claim-safety), not for everyday issue
+  create/update/list/search/close/comment/dep CRUD (use issue-basics), not for reporting the
+  current workflow stage or "where am I / what's in flight" (use status), not for orienting a
+  whole session or routing to stage skills (use kernel), not for driving an issue to a merged
+  PR (use smith).
+allowed-tools: Read, Bash(forge:*)
+---
+
+# Triage: what should I work on next
+
+A read-only orientation skill. It answers "what is the single best thing to work
+on right now, and *why*?" and hands the pick off to `claim-safety` / `dev` — it
+never mutates the store itself.
+
+Readiness in the Forge kernel is a **derived read model**: an issue is ready only
+when every dependency is satisfied, it is unclaimed (no live lease), it is a
+claimable type (epics and decisions never enter the queue), and no defer window
+holds it back. Because it is derived, **always recompute it** — never trust a
+cached "status == ready". Recompute means: run the query fresh each time.
+
+## Do NOT use `board`
+
+`forge board` reads a legacy snapshot store, not the live kernel, so its readiness
+can be stale or wrong. This skill uses `forge issue ready`, `forge issue blocked`,
+and `forge issue stats` exclusively.
+
+## Procedure
+
+### 1. Take the pulse
+
+```bash
+forge issue stats --json
+```
+
+Returns `data.counts` (`open`/`done`/`cancelled` — keys are present only when
+non-zero, and there is no `in_progress` bucket: claimed work stays in status
+`open` and is surfaced via `active_claims`), `ready_count`, `blocked_count`, and
+`active_claims`. A high `blocked_count` relative to
+`ready_count` is your signal that dependency repair (not new work) is the real
+bottleneck — hand off to `dependency-planning` / `backlog-hygiene`.
+
+### 2. Rank the ready queue
+
+```bash
+forge issue ready --json
+```
+
+`data.issues[]` comes back ordered by `rank` (priority ascending, then id), each
+carrying `id`, `title`, `type`, `priority` (`P0`..`P4`), `rank`, `blocked`,
+`claimed_by`, `parent_id`, `labels[]`, and `dependencies[]`. The top item is your
+default pick. Surface the top few (see Fork points for how many), not the whole
+list.
+
+### 3. Explain WHY the top item is ready
+
+Do not just name it — justify it. Pull its full record:
+
+```bash
+forge issue show <id> --json
+```
+
+State the reason in one sentence, drawn from the record:
+
+- **Priority / rank** — `P0` at `rank` 0 outranks everything below it.
+- **Dependencies satisfied** — every id in `dependencies[]` is closed/done, so
+  nothing gates it (`blocked: false`).
+- **Unclaimed** — `claimed_by` is `null`, so no other agent holds the lease.
+- **Claimable type** — it is a `task`/`feature`/`bug`, not an `epic`/`decision`.
+
+### 4. Explain why the runners-up are NOT ready
+
+```bash
+forge issue blocked --json
+```
+
+For a blocked item, name the specific unmet dependency (from its `dependencies[]`
+cross-referenced against `forge issue show`) — e.g. "blocked by `forge-x` which is
+still `open`". This turns triage into an actionable map: the fastest way to unlock
+the most work is usually to finish the shared blocker.
+
+### 5. Hand off
+
+Recommend ONE issue with its one-line justification, then stop. The caller claims
+it (via `claim-safety`) and executes (via `dev`). Triage does not claim, comment,
+or close — it is strictly read-only.
+
+## Reliability
+
+- **Recompute, never cache.** Readiness is derived; re-run `forge issue ready`
+  every session rather than remembering a prior "ready" verdict.
+- **Respect non-claimable types.** Epics and decisions never appear in `ready`
+  (the queue surfaces only claimable types — `task`/`bug`), so do not hand them
+  off as work. There is no `claimable` field in the CLI JSON; this is behavioral,
+  not a flag you can read.
+- **Check the envelope.** Every `--json` reply carries `ok`; on `ok:false` read
+  `error.message` and retry the query rather than guessing at state.
+- **Read-only.** This skill runs only `stats`/`ready`/`blocked`/`show`. If a fix is
+  needed, hand off — never mutate here.
+
+## Fork points
+
+Editable knobs — change these to carve your own triage policy. This skill is a
+canonical source you fork, not a fixed ladder.
+
+| Knob | Default | How to change |
+|------|---------|---------------|
+| **Readiness query / filters** | `forge issue ready` (whole queue) | Narrow to a slice, e.g. `forge issue list --status open --priority P0 --json` or post-filter `ready` output by `labels[]`/`type` to focus one workstream. |
+| **How many items to surface** | Top 3 by `rank` | Raise for a broad standup view, lower to 1 for a strict "next task only" hand-off. |
+| **Stale threshold** | `forge issue stale --days 14` | Change `--days` to flag idle in-progress work sooner/later; surface stale claims as a caveat before recommending fresh work. |
+| **Priority ordering** | Kernel `rank` (priority, then id) | Re-rank the `ready` list by your own weights — epic proximity (`parent_id`), label, or age — before picking. |
+| **Blocked-explain depth** | One hop (direct unmet deps) | Trace transitively via repeated `forge issue show` when you need the full blocking chain; hand to `graph-forensics` for deep `explain`. |

package/skills/triage-ready/evals/evals.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "I just sat down at this repo — what's the highest-priority thing I can actually start right now?",
+    "should_trigger": true
+  },
+  {
+    "query": "Give me the top few off the ready queue and tell me why the first one is unblocked.",
+    "should_trigger": true
+  },
+  {
+    "query": "Why can't I start forge-2agy.2.2 yet? What's holding it up?",
+    "should_trigger": true
+  },
+  {
+    "query": "The backlog feels stuck — is it mostly blocked, and which one dependency would unlock the most work?",
+    "should_trigger": true
+  },
+  {
+    "query": "Pick my next task and justify the choice, don't grab it yet.",
+    "should_trigger": true
+  },
+  {
+    "query": "Claim forge-abc123 for me and confirm I actually hold the lease before I start editing.",
+    "should_trigger": false
+  },
+  {
+    "query": "Create a P1 bug titled 'login returns 500' and add a comment linking the repro.",
+    "should_trigger": false
+  },
+  {
+    "query": "Where am I in the workflow right now and what work is in flight?",
+    "should_trigger": false
+  },
+  {
+    "query": "Search every issue mentioning 'oauth' and list the open ones.",
+    "should_trigger": false
+  },
+  {
+    "query": "Take forge-xyz all the way through to a merged PR.",
+    "should_trigger": false
+  }
+]

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

@@ -1,19 +1,30 @@
 ---
 name: validate
-description: Complete validation (type/lint/tests/security)
-tools: []
+description: >
+  Forge VALIDATE stage — the pre-pull-request quality gate. Rebases the branch onto the
+  current base branch, then runs type-checking, linting, code review, an OWASP Top 10 security
+  review plus dependency scan, and the full test suite, demanding fresh passing output in THIS
+  session before anything ships. Reach for this whenever a branch is code-complete and someone
+  says: validate my changes, run the quality gates, run the pre-PR checks, type-check and lint
+  before the PR, run the security scan, or run the full test suite before opening a PR — and
+  for the literal `/validate` command or `bun run check`. This is the gate that runs AFTER
+  code is written but BEFORE a PR exists, so discriminate carefully: it does not implement
+  features or write tests (that is `/dev`), it does not push the branch or open the PR (that
+  is `/ship`), it does not answer PR review feedback from Greptile / SonarCloud / CodeRabbit
+  (that is `/review`), and it is not the post-merge CI health check (that is `/verify`).
+allowed-tools: Bash, Read, Grep, Glob
 ---
 
 > **Note:** Three things share the "validate" name in Forge:
-> - `/validate` (this command): Workflow Stage 3 — rebases onto the base branch, then runs type/lint/test/security checks
+> - `/validate` (this command): default-template validation command — rebases onto the base branch, then runs type/lint/test/security checks
 > - `forge-preflight` (formerly forge-validate): CLI tool — checks prerequisites before a stage
-> - `bun run check` (scripts/validate.sh): Local quality gate — runs type/lint/test/security checks only (does NOT rebase; assumes branch is already current with the base branch)
+> - `bun run check` (scripts/validate.js): Local quality gate — runs type/lint/test/security checks only (does NOT rebase; assumes branch is already current with the base branch)
 
 Run comprehensive validation including type checking, linting, code review, security review, and tests.
 
 # Validate
 
-This command validates all code before creating a pull request.
+This skill validates all code before creating a pull request.
 
 ## Usage
 
@@ -67,9 +78,9 @@ reflect the true state of what will be merged.
 </HARD-GATE>
 ```
 
-## What This Command Does
+## What This Skill Does
 
-**Quick Start**: Run `bun run check` to execute the full validation pipeline (implemented in `scripts/validate.sh`). The npm script is named `check`; the workflow command is `/validate`. See individual steps below for details.
+**Quick Start**: Run `bun run check` to execute the full validation pipeline (implemented in `scripts/validate.js`). The npm script is named `check`; the workflow command is `/validate`. See individual steps below for details.
 
 ### Step 1: Type Check
 ```bash
@@ -137,7 +148,7 @@ bun test    # or: npm run test, jest, vitest, etc.
 > - Did you verify OWASP Top 10 mitigations, not just check a box?
 > - Are there edge cases or integration scenarios you haven't tested?
 >
-> **If unsure**: Re-read the `## Technical Research` section in `docs/plans/YYYY-MM-DD-<slug>-design.md`
+> **If unsure**: Re-read the `## Technical Research` section in `docs/work/YYYY-MM-DD-<slug>/plan.md`
 
 ## On Validation Failure: 4-Phase Debug Mode
 
@@ -206,11 +217,12 @@ If you have attempted 3+ fixes without resolution:
 
 If any check fails:
 ```bash
-# Create Beads issue for problems
-bd create "Fix <issue-description>"
+# Create Forge issue for problems
+forge create "Fix <issue-description>"
 
 # Mark current issue as blocked
-bd update <current-id> --status blocked --comment "Blocked by <new-issue-id>"
+forge update <current-id> --status blocked
+forge comment <current-id> "Blocked by <new-issue-id>"
 
 # Output what needs fixing
 ```
@@ -230,13 +242,21 @@ until ALL FOUR show fresh output in this session:
 "Should pass", "was passing earlier", and "I'm confident" are not evidence.
 Run the commands. Show the output. THEN declare done.
 
-5. Context check: Run `bash scripts/beads-context.sh validate <id>` and address any warnings
-6. Stage transition: Run the following → exit 0 confirmed:
-   bash scripts/beads-context.sh stage-transition <id> validate ship \
-     --summary "<all checks pass/fail summary>" \
-     --decisions "<any failures diagnosed and fixed>" \
-     --artifacts "<scripts and commands run>" \
-     --next "<ship readiness notes>"
+5. Context check: confirm design + acceptance on the Forge issue (`forge issue show <id>`); if the beads-context helper is present, run `bash scripts/beads-context.sh validate <id>` and address any warnings
+6. Stage transition recorded (structured helper when present; kernel-native comment otherwise):
+   if [ -f scripts/beads-context.sh ]; then
+     bash scripts/beads-context.sh stage-transition <id> validate ship \
+       --summary "<all checks pass/fail summary>" \
+       --decisions "<any failures diagnosed and fixed>" \
+       --artifacts "<scripts and commands run>" \
+       --next "<ship readiness notes>"
+   else
+     forge comment <id> "Stage: validate complete → ready for ship
+Summary: <all checks pass/fail summary>
+Decisions: <any failures diagnosed and fixed>
+Artifacts: <scripts and commands run>
+Next: <ship readiness notes>"
+   fi
 </HARD-GATE>
 ```
 
@@ -262,8 +282,8 @@ Ready for /ship
   - validation.test.ts: Assertion failed
   - auth.test.ts: Timeout exceeded
 
-✓ Beads issue created: bd-k8m3 "Fix validation test"
-✓ Current issue marked: Blocked by bd-k8m3
+✓ Forge issue created: forge-k8m3 "Fix validation test"
+✓ Current issue marked: Blocked by forge-k8m3
 
 Fix issues then re-run /validate
 ```
@@ -271,20 +291,23 @@ Fix issues then re-run /validate
 ## Integration with Workflow
 
 ```
-Utility: /status     → Understand current context before starting
-Stage 1: /plan       → Design intent → research → branch + worktree + task list
-Stage 2: /dev        → Implement each task with subagent-driven TDD
-Stage 3: /validate      → Type check, lint, tests, security — all fresh output (you are here)
-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
+Utility: /status  -> Understand current context before starting
+
+Default template:
+  /plan      -> Optional default planner; external planners may satisfy /dev entry
+  /dev       -> Implement each task with subagent-driven TDD
+  /validate  -> Type check, lint, tests, security (you are here)
+  /ship      -> Push + create PR
+  /review    -> Address PR feedback
+  /verify    -> Post-merge health check
+
+Pre-merge gate: doc updates + CI-green checkpoint embedded in /ship and /review (not a separate stage).
 ```
 
 ## Tips
 
 - **All checks must pass**: Don't proceed to /ship with failures
 - **Security is mandatory**: OWASP Top 10 review required for all features
-- **Create issues for failures**: Track problems in Beads
+- **Create issues for failures**: Track problems in the Forge issue tracker
 - **TDD helps**: Tests should already pass from /dev phase
 - **Fix before shipping**: Resolve all issues before creating PR