From bcfa57273bf520cc2f3b08ca6cce77ec6ae9cd85 Mon Sep 17 00:00:00 2001 From: sohmn Date: Tue, 9 Jun 2026 15:06:10 -0700 Subject: [PATCH] feat(fanout): wire /fanout into skill registries README (install snippet + table), CLAUDE.md routing, AGENTS.md, docs/skills.md, skill-coverage-matrix (gate: fanout.test.ts + coverage floor). llms.txt + proactive-suggestions.json regenerated. Co-Authored-By: Claude Fable 5 --- AGENTS.md | 1 + CLAUDE.md | 1 + README.md | 3 ++- docs/skills.md | 1 + gstack/llms.txt | 1 + scripts/proactive-suggestions.json | 5 +++++ test/skill-coverage-matrix.ts | 5 +++++ 7 files changed, 16 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 4df7eec35..a2cb78927 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,7 @@ Invoke them by name (e.g., `/office-hours`). | `/autoplan` | One command runs CEO → design → eng → DX review. | | `/design-consultation` | Build a complete design system from scratch. | | `/spec` | Turn vague intent into a precise, executable spec in five phases. Files a GitHub issue, optionally spawns a Claude Code agent in a fresh worktree, and lets `/ship` close the source issue on merge. | +| `/fanout` | Decompose a finished design doc into N parallel agent tasks. Identifies Slab 0 (shared groundwork) plus 2-3 independent slabs, appends a Parallel Execution Plan section to the doc, and emits per-slab prompt files plus a `worktree-dispatch.sh` sidecar. v0 produces the plan and stops; user runs the script. | ### Implementation + review diff --git a/CLAUDE.md b/CLAUDE.md index 984844902..05ceeb28b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -946,6 +946,7 @@ Key routing rules: - Architecture → invoke /plan-eng-review - Design system/plan review → invoke /design-consultation or /plan-design-review - Full review pipeline → invoke /autoplan +- Parallel execution of finished design doc → invoke /fanout - Bugs/errors → invoke /investigate - QA/testing site behavior → invoke /qa or /qa-only - Code review/diff check → invoke /review diff --git a/README.md b/README.md index af534d2c5..9046a63ea 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ Fork it. Improve it. Make it yours. And if you want to hate on free open source Open Claude Code and paste this. Claude does the rest. -> Install gstack: run **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /setup-gbrain, /retro, /investigate, /document-release, /document-generate, /codex, /cso, /autoplan, /plan-devex-review, /devex-review, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn. Then ask the user if they also want to add gstack to the current project so teammates get it. +> Install gstack: run **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /setup-gbrain, /retro, /investigate, /document-release, /document-generate, /codex, /cso, /autoplan, /fanout, /plan-devex-review, /devex-review, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn. Then ask the user if they also want to add gstack to the current project so teammates get it. ### Step 2: Team mode — auto-update for shared repos (recommended) @@ -205,6 +205,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan- | `/setup-browser-cookies` | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. | | `/autoplan` | **Review Pipeline** | One command, fully reviewed plan. Runs CEO → design → eng review automatically with encoded decision principles. Surfaces only taste decisions for your approval. | | `/spec` | **Spec Author** | Turn vague intent into a precise, executable spec in five phases (why, scope, technical with mandatory code-reading, draft, file). Codex quality gate before file (blocks below 7/10), fail-closed secret redaction, dedupe against existing issues, archive to `$GSTACK_STATE_ROOT/projects/$SLUG/specs/` for team-corpus recall. `--execute` spawns `claude -p` in a fresh worktree; `/ship` auto-closes the source issue on merge. Plan-mode aware. | +| `/fanout` | **Multi-agent Dispatcher** | Take a finished design doc and decompose it into N parallel agent tasks. Identifies Slab 0 (shared groundwork) plus 2-3 independent slabs, appends a Parallel Execution Plan section to the doc, and emits per-slab prompt files plus a `worktree-dispatch.sh` sidecar. v0 produces the plan and stops; user runs the script. | | `/learn` | **Memory** | Manage what gstack learned across sessions. Review, search, prune, and export project-specific patterns, pitfalls, and preferences. Learnings compound across sessions so gstack gets smarter on your codebase over time. | | `/make-pdf` | **Publisher** | Markdown in, publication-quality document out. Mermaid and excalidraw fences render as vector diagrams, fully offline. Images scale to the page and never truncate; wide diagrams get their own landscape page. `--to html` emits one self-contained file, `--to docx` a Word doc. | | `/diagram` | **Diagram Maker** | English in, editable diagram out. Emits a triplet: mermaid source, `.excalidraw` you can open and edit on excalidraw.com (hand-drawn style), and rendered SVG/PNG. Zero network. Embed the source in markdown and `/make-pdf` renders it. | diff --git a/docs/skills.md b/docs/skills.md index 8e8cb7adc..836a3f360 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -6,6 +6,7 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples. |-------|----------------|--------------| | [`/office-hours`](#office-hours) | **YC Office Hours** | Start here. Six forcing questions that reframe your product before you write code. Pushes back on your framing, challenges premises, generates implementation alternatives. Design doc feeds into every downstream skill. | | [`/spec`](#spec) | **Spec Author** | Turn vague intent into a precise, executable spec in five phases. Backlog-ready output that downstream skills can pick up. Optional agent spawn at the end. | +| [`/fanout`](#fanout) | **Multi-agent Dispatcher** | Decompose a finished design doc into N parallel agent tasks. Slab 0 plus 2-3 independent slabs, per-slab prompt files, and a worktree dispatch script. v0 produces the plan and stops. | | [`/plan-ceo-review`](#plan-ceo-review) | **CEO / Founder** | Rethink the problem. Find the 10-star product hiding inside the request. Four modes: Expansion, Selective Expansion, Hold Scope, Reduction. | | [`/plan-eng-review`](#plan-eng-review) | **Eng Manager** | Lock in architecture, data flow, diagrams, edge cases, and tests. Forces hidden assumptions into the open. | | [`/plan-design-review`](#plan-design-review) | **Senior Designer** | Interactive plan-mode design review. Rates each dimension 0-10, explains what a 10 looks like, fixes the plan. Works in plan mode. | diff --git a/gstack/llms.txt b/gstack/llms.txt index efe522f90..ccb7753ab 100644 --- a/gstack/llms.txt +++ b/gstack/llms.txt @@ -29,6 +29,7 @@ Conventions: - [/diagram](diagram/SKILL.md): Turn an English description (or mermaid source) into a diagram triplet: the source, an editable .excalidraw file you can open on excalidraw.com, and rendered SVG + PNG (clean mermaid style; the .excalidraw carries the hand-drawn aesthetic). - [/document-generate](document-generate/SKILL.md): Generate missing documentation from scratch for a feature, module, or entire project. - [/document-release](document-release/SKILL.md): Post-ship documentation update. +- [/fanout](fanout/SKILL.md): Decompose a finished design doc into N parallel agent tasks with worktree dispatch. - [/freeze](freeze/SKILL.md): Restrict file edits to a specific directory for the session. - [/gstack](gstack/SKILL.md): Router for the gstack skill suite. - [/gstack-upgrade](gstack-upgrade/SKILL.md): Upgrade gstack to the latest version. diff --git a/scripts/proactive-suggestions.json b/scripts/proactive-suggestions.json index d08c60853..2989142c3 100644 --- a/scripts/proactive-suggestions.json +++ b/scripts/proactive-suggestions.json @@ -93,6 +93,11 @@ "routing": "Reads all project docs, cross-references the\ndiff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation),\nupdates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,\ndetects architecture diagram drift, polishes CHANGELOG voice with a sell-test\nrubric, cleans up TODOS, and optionally bumps VERSION. Surfaces documentation\ndebt in the PR body. Use when asked to \"update the docs\", \"sync documentation\",\nor \"post-ship docs\". Proactively suggest after a PR is merged or code is shipped.", "voice_line": null }, + "fanout": { + "lead": "Decompose a finished design doc into N parallel agent tasks with worktree dispatch.", + "routing": "Takes a markdown file path, identifies independent slabs of work plus a shared-groundwork\nSlab 0, and writes a Parallel Execution Plan section back to the doc plus a\nworktree-dispatch.sh sidecar. Run after office-hours + eng-review + design when you\nwant 2-3 agents to implement the design in parallel worktrees.\nUse when asked to \"fan out a design\", \"parallelize this design doc\", \"split into\nmultiple agents\", \"run agents in parallel\", or when a finished design doc is ready\nfor multi-agent execution.", + "voice_line": "Voice triggers (speech-to-text aliases): \"fan this out\", \"parallelize this\"." + }, "freeze": { "lead": "Restrict file edits to a specific directory for the session.", "routing": "Blocks Edit and\nWrite outside the allowed path. Use when debugging to prevent accidentally\n\"fixing\" unrelated code, or when you want to scope changes to one module.\nUse when asked to \"freeze\", \"restrict edits\", \"only edit this folder\",\nor \"lock down edits\".", diff --git a/test/skill-coverage-matrix.ts b/test/skill-coverage-matrix.ts index 7359afbce..253dff7ac 100644 --- a/test/skill-coverage-matrix.ts +++ b/test/skill-coverage-matrix.ts @@ -76,6 +76,11 @@ export const SKILL_COVERAGE: Record = { ], rationale: '37 deterministic invariants pin Phase 1/3 gating, --execute race/security hardening, quality-gate redaction, archive contract, plan-mode-aware Phase 5. Periodic adds full PTY pipeline + LLM-judge.', }, + fanout: { + gate: ['test/fanout.test.ts', 'test/skill-coverage-floor.test.ts'], + periodic: [], + rationale: 'v0 produces a markdown section + prompt files + bash script; deterministic given input doc structure. fanout.test.ts pins frontmatter, section invariants, and the v0.1 hardening guardrails.', + }, // ─── Plan triad ───────────────────────────────────────────── 'plan-ceo-review': {