Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

v1.60.0.0 feat(fanout): /fanout decomposes design doc into N parallel agent tasks (rebased, hardened) #1949

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sohmn wants to merge 3 commits into garrytan:main
base: main
Choose a base branch
Loading
from sohmn:feat/fanout-skill-v2
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
40 changes: 40 additions & 0 deletions CHANGELOG.md
View file Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,45 @@
# Changelog

## [1.60.0.0] - 2026年06月12日

**New skill: `/fanout` decomposes a finished design doc into 2-3 parallel agent tasks.**
**Per-slab prompt files plus a worktree dispatch script. v0 produces the plan and stops.**

After `/office-hours` + eng-review + `/design-consultation` produces a design doc, the bottleneck is execution: one agent works through the whole doc serially. `/fanout docs/designs/MY_FEATURE.md` reads the doc, identifies independent slabs of work via a 4-layer heuristic (numbered phases, implementation subsections, file-reference tables, natural seams), promotes shared groundwork to a synchronous Slab 0, builds a slab matrix with verification gates, and writes a `## Parallel Execution Plan` section back to the doc. Alongside it: one editable `<topic>-slab-<k>.prompt.md` per slab and a `worktree-dispatch.sh` with Slab 0 ready to run and Slabs 1-N commented out, uncommented manually after Slab 0 lands on main.

### The shape of the win

No production benchmarks yet, this is a v0 release. The structural argument:

- Serial implementation of a 3-subsystem design doc waits on one agent finishing each subsystem in sequence.
- Parallel implementation runs three agents concurrently after a brief Slab 0 (shared groundwork) lands. Wall-clock collapses to Slab 0 time plus the slowest slab, instead of the sum.
- The slab matrix plus explicit Slab 0 promotion is the structural defense against three parallel agents tripping over the same shared type file. The skill also names the coordination tax it can't remove: every slab's /ship queues a CHANGELOG/VERSION entry, and each slab after the first rebases over the earlier ones.

Real numbers land in v1 with the first production runs and a paid E2E eval. Until then the win is qualitative: it turns "wait for one agent" into "wait for the slowest of three."

### What this means for builders

If you're sitting on a finished design doc that touches 3+ subsystems, `/fanout` turns it into 2-3 worktrees you can dispatch in parallel, each with an editable prompt file. Read the appended section, tweak the prompts if you want, run the script, let Slab 0 land before uncommenting the rest. Caps at 3 slabs by default because more is usually false parallelism. Pure prompt-based skill, no new binaries, no eval cost.

### Itemized changes

#### Added
- `/fanout` skill at `fanout/SKILL.md.tmpl` and generated `fanout/SKILL.md`.
- Free `bun test` fixture at `test/fanout.test.ts` validates frontmatter, section structure, and the hardening guardrails below.
- `/fanout` routing line in `CLAUDE.md`, rows in `README.md`, `AGENTS.md`, `docs/skills.md`, and a `test/skill-coverage-matrix.ts` entry.

#### Hardening (from the first PR's adversarial review, all six prior limitations closed)
- Worktree dirs and branch names carry a doc-path hash suffix, so two design docs with the same filename stem can't collide.
- CHANGELOG/VERSION are named expected-conflict files in the Merge order, the per-slab prompts, and the wall-clock report, so the coordination tax of parallel /ship is visible up front.
- Slab 0 promotion keeps contract ownership with the owning slab (Slab 0 lands skeletons only).
- An over-decomposition guard stops the skill when more than a third of slabs end up chained, and the natural-seams heuristic refuses docs whose shared contracts are marked draft.
- Table cells escape `|` and collapse newlines so odd file paths can't corrupt the slab matrix.
- Per-slab prompt files replace heredocs in the dispatch script, eliminating the EOF-breakout class and making each slab's marching orders user-editable before dispatch.

#### For contributors
- Design doc at [`docs/designs/FANOUT.md`](docs/designs/FANOUT.md) documents the slab detection heuristic, Slab 0 promotion logic, conflict resolution rules, edge cases, and the v0.1 hardening section.
- No new infrastructure: skill is auto-discovered by `setup` via the existing top-level-directory glob.

## [1.58.0.0] - 2026年06月12日

## **Your documents grow diagrams. Mermaid and excalidraw fences render as real pictures,**
Expand Down
1 change: 1 addition & 0 deletions CLAUDE.md
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -903,6 +903,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
Expand Down
3 changes: 2 additions & 1 deletion README.md
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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. |
Expand Down
2 changes: 1 addition & 1 deletion VERSION
View file Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
1.58.0.0
1.60.0.0
Loading
Loading

AltStyle によって変換されたページ (->オリジナル) /