stream-it Usage Guide

stream-it is a set of development-workflow skills: 26 skills that take a change from "an idea" to "shipped code" through standard steps — requirements, design, breakdown, implementation, review, shipping — each owned by one skill.

It enables AI agents to act like experienced engineers — from understanding requirements, breaking down tasks, writing code, reviewing quality, to final submission and merge — autonomously completing the entire process. You just describe the feature idea, and the workflow handles the rest.

Two install routes — pick one, not both.

Option 1 (Recommended): Install as a skill directory

# Recommended — install all skills into ~/.agents/skills
npx skills add 9Ashwin/stream-it

# Or install a specific skill
npx skills add 9Ashwin/stream-it --skill ask-flow
npx skills add 9Ashwin/stream-it --skill prd
npx skills add 9Ashwin/stream-it --skill prd-to-spec
npx skills add 9Ashwin/stream-it --skill to-issues
npx skills add 9Ashwin/stream-it --skill triage
npx skills add 9Ashwin/stream-it --skill to-design
npx skills add 9Ashwin/stream-it --skill design-it
npx skills add 9Ashwin/stream-it --skill implement
npx skills add 9Ashwin/stream-it --skill test-first
npx skills add 9Ashwin/stream-it --skill loop-it
npx skills add 9Ashwin/stream-it --skill graph
npx skills add 9Ashwin/stream-it --skill diagnose
npx skills add 9Ashwin/stream-it --skill conflict
npx skills add 9Ashwin/stream-it --skill review-it
npx skills add 9Ashwin/stream-it --skill understand
npx skills add 9Ashwin/stream-it --skill ship-it
npx skills add 9Ashwin/stream-it --skill note-it
npx skills add 9Ashwin/stream-it --skill walkthrough
npx skills add 9Ashwin/stream-it --skill humanize-it
npx skills add 9Ashwin/stream-it --skill listenhub-tts
npx skills add 9Ashwin/stream-it --skill insight-diagram
npx skills add 9Ashwin/stream-it --skill code-to-spec
npx skills add 9Ashwin/stream-it --skill refactor
npx skills add 9Ashwin/stream-it --skill modern-go
npx skills add 9Ashwin/stream-it --skill smell
npx skills add 9Ashwin/stream-it --skill article-icons

# Global install (available for all projects)
npx skills add 9Ashwin/stream-it -g

# Update from the same source later
npx skills update -g

# Install to one agent only (universal = the ~/.agents/skills location above)
npx skills add 9Ashwin/stream-it -g -a universal

Skills land in ~/.agents/skills. This is the least-effort route: nothing to change in a profile, and it applies to every profile.

npx skills scans recursively and flattens skills/<bucket>/<skill> into ~/.agents/skills/<skill> on install — a skill root is scanned only one level deep, so the flattening is required. The picker still groups the 26 skills into the four buckets (flow / practice / meta / bonus) instead of listing them flat: each bucket is a plugin in .claude-plugin/marketplace.json, and a skill no plugin claims falls into a catch-all Other group. Copying by hand means doing the flattening step yourself:

# flattened, not the bucket
cp -R <stream-it>/skills/flow/graph ~/.agents/skills/graph

Option 2 (Optional): Install as a bundle

# Optional — install as a DSH bundle (config-only package)
dsh plugin --profile web add -w github:9Ashwin/stream-it

# Pin a commit for production instead of tracking the default branch
dsh plugin --profile web add -w github:9Ashwin/stream-it#<sha>

# Verify the bundle is registered in the profile
dsh --profile web --dump-config | grep -A3 stream-it

Prerequisites

Six-step closed loop, from requirements to delivery:

/prd transforms a vague feature idea into a structured product requirements document (PRD): clarify the ambiguity first, then state the requirements as verifiable acceptance criteria. It produces the PRD only — /to-issues does the breakdown.

How to Invoke

# Run this directly
/prd Add a priority feature to our task management system

# Or use trigger phrases
Write PRD for: User registration with email and phone support
Requirements analysis: Add rate limiting capability to the API

Workflow

• Agent asks clarifying questions (with letter options, reply quickly with "1A, 2C, 3B"), scaled to complexity rather than padded to a count
• Generates structured PRD based on answers (User Stories, Functional Requirements, Non-Goals, Acceptance Criteria)
• Presents PRD for review; confirm or adjust
• Saves PRD to tasks/prd-[feature-name].md
• Suggests the next steps: /prd-to-spec (optional) and /to-issues

Output Example

# after the PRD is saved
✅ PRD saved to tasks/prd-priority-system.md

/prd-to-spec  (optional — only for complex features)
/to-issues    (split the PRD into Issues with blocking edges)

/prd-to-spec transforms a product requirements document (PRD) into an implementable technical design SPEC. PRD says "what to build"; SPEC says "how to build it".

How to Invoke

# Run this directly
/prd-to-spec tasks/prd-priority-system.md

# Or use trigger phrases
PRD to design: Convert priority PRD to technical plan
Technical spec: Generate SPEC based on prd-user-auth.md

PRD → SPEC Mapping

SPEC Output Structure (11 Chapters)

Workflow

• Locate PRD file (auto-scan tasks/ or manually specified)
• (Optional) Analyze existing codebase: architecture, tech stack, patterns, conventions (skip if no codebase — propose architecture from scratch)
• Ask 3-5 technical clarification questions (with options)
• Generate complete SPEC document
• Present for review; confirm or iterate
• Save to tasks/spec-[feature-name].md

/to-issues breaks down a PRD and/or SPEC into vertically-sliced, independently implementable Issues and creates them on your chosen platform. It can be used standalone — no need to run /prd first.

How to Invoke

# Run this directly
/to-issues

# Or use trigger phrases
Create issues for: Create Issues from prd-user-auth.md
Break down issues: Break down implementable cards from SPEC
Generate cards: Break PRD and SPEC together into Issues

Input Sources

Creation Platforms

Workflow

• Locate input files (auto-detect or manually specify PRD/SPEC)
• Find prefactoring ("make the change easy" groundwork) and order it first
• Break down into vertical-slice Issues with a demo path and explicit Blocked by edges, numbered in dependency order
• Quiz the user: granularity, blocking edges, and whether each demo path is a behaviour rather than a layer
• Select creation platform (GitHub / Local)
• Create blockers first, then output a summary report (including the ready-to-start frontier)

Boundary: /triage only handles raw inbound items

/to-issues breaks down your own requirements, and its output is already agent-ready; bug reports, user feedback and requests filed by other people are the job of /triage — reproduce / understand first, then assign a role (ready / needs-info / bug-confirmed / duplicate / wontfix) and fill the ready ones out into agent-executable cards. Never triage /to-issues output. See 22. /triage.

This is the implementation step, and all three routes start from the Issue cards created by /to-issues: a single unit goes inline through /implement, sequential work through /loop-it, and parallel work through /graph. On every route the running agent writes the code itself — implementation is done inline, never by handing the work to an external command.

/implement — the single-unit inline loop

One issue, one card, one item in a spec — when there is exactly one unit, take this route: implement inline → prove with the project's gates → /review-it → /ship-it. It explicitly does not create a worktree, not dispatch a subagent and not create a wave branch — those are the orchestration owned by /loop-it and /graph, and putting a single unit on the graph or into a loop just pays orchestration cost for nothing.

• Read the unit first: list its acceptance criteria one by one, read the PRD / SPEC / design docs it references, then read the adjacent code and tests so naming, error handling and log style match the repo
• Prove it with the project's own gates (mise run check, go build ./... && go test ./..., pnpm --dir web lint, …): run the focused tests as you go and the full gate once at the end — a criterion that was never tested is not satisfied
• Do not expand scope: no force-push, never guess a vague acceptance criterion for the user (ask instead), and never smuggle an out-of-scope drive-by change into this diff (open another issue for it)

Reference: /test-first — red → green

Use it when behaviour should be pinned down before the implementation: one test → one piece of implementation → the next test, one seam at a time. It is also the reference /implement uses internally, and it can be invoked on its own.

• Agree the seams with the user up front: before writing any test, write down which seams will be tested and confirm it with the user — you cannot test everything, and agreeing the seams first puts the effort on critical paths and complex logic
• Three anti-patterns: coupled to the implementation (mocking internal collaborators, testing private methods, verifying through a side channel), tautological (recomputing the expected value the same way the implementation does, so it passes by construction), and horizontal slicing (writing all the tests first, which tests an imagined shape rather than user-facing behaviour)
• Loop rules: red before green (write the failing test first, then the least code that makes it pass), one slice at a time (one round = one seam + one test + one minimal implementation), and refactoring is not part of this loop (that belongs to /review-it)

Node Scope: Implement → Prove → Commit

• Each node owns an isolated git worktree and its own branch feat/node-{N}-{slug}; every edit happens inside that worktree
• It proves itself by running the project's own gates inside its worktree (e.g. go build ./..., go test ./..., mise run check); a criterion it did not test is not satisfied
• It commits to its own branch only: no push, no PR, no merge, and no self-review — a node report is evidence, not a verdict

/loop-it — Sequential Implementation

/loop-it fetches the open GitHub issues and resolves their order with a dependency-aware topological sort. It implements one Issue at a time, inline (read the requirement → write the code → prove it with the project's gates) and commits on that Issue's own branch — without pushing or opening a PR. At the end of the batch it merges the surviving branches into a single batch branch (failed branches are never merged in) and runs /review-it once and /ship-it once. It checkpoints progress to .loop-state.json after every status change, so a crash or interruption can resume from the last checkpoint instead of restarting the whole batch.

# Sequential: one Issue at a time, a commit per Issue, one review + one walkthrough + one ship at batch end
/loop-it

/graph — Parallel Implementation

/graph turns a task, PRD, or Issue set into a DAG, layers it into waves, and dispatches one subagent per independent node concurrently. Each node works in its own git worktree and commits only to its own branch, so parallel edits never clobber each other. Every wave ends with a mandatory fan-in barrier: wait for all of the wave's settlement notices → leak check → integrate (merge only the nodes that shipped, never a failed one) → run the gates on the integrated tree → review once (section by section, node by node) → ship once (one PR, closing the Issues the wave satisfied). Progress is checkpointed to .graph_state.json, and a graph.html tracker re-renders from that checkpoint at every wave boundary.

# Parallel: task/PRD/issues → DAG → waves → one worktree per node → fan-in barrier
/graph tasks/prd-url-shortener.md

A wave of one node has nothing to integrate: skip the wave branch and the merge ceremony, and review + ship that node's branch directly.

When a Node Fails

• Retry in place first with send_message, reusing that node's own context; then retry it as a fresh node; only then drop it
• Its dependents are marked blocked, but the rest of the wave still ships — a wave is not all-or-nothing — and a failed branch is never merged or marked shipped just to keep the wave moving

/review-it is the closeout check before shipping: prove the gates first, then review the diff, fixing real findings until none are actionable. Under the current contract it runs once per wave / batch, against the integrated diff — not once per node against its own fresh work.

Two Axes: Spec and Standards, Reported Separately

Every review answers two different questions, and it reports them as two sections, never one merged ranking — merge them and the naming-and-style findings drown out a missing acceptance criterion:

• Spec axis — does this diff do what was asked? Find the spec before reading the diff: the issue numbers in the commit messages (gh issue view <n>), a path the user handed you, or a matching tasks/prd-*.md / tasks/spec-*.md / docs/*.md. If none exists, say so and review against what the user actually asked for — never invent requirements. Check it three ways: required but missing / extra but unrequested / present but wrong. Every finding must quote the acceptance criterion it is checked against, so it is falsifiable rather than a preference.
• Standards axis — is this good code in this repo? That is the eight dimensions below, ordered by severity.

The Review Path

There is no external review CLI: once /review-it is loaded, the running agent performs the review itself with the principles below, and never shells out to a review command.

# Uncommitted changes (default): review the working tree, untracked files included
git status --short
git diff
git diff --cached

# Branch / PR: generate the diff against the base, then review it section by section
# base = the PR's base, else the repo's default branch — never a hardcoded main
base=$(gh pr view --json baseRefName --jq .baseRefName 2>/dev/null || git symbolic-ref -q --short refs/remotes/origin/HEAD | sed 's|^origin/||')
diff_file=$(mktemp)  # a fixed /tmp name is pre-creatable — don't
git diff "origin/$base"...HEAD > "$diff_file"

When the diff is large, or independence matters more, hand the diff file to a fresh subagent — it sees none of this conversation, so the prompt must be self-contained.

Review Principles

Review Modes

Wave Review: Once, Section by Section

• The review target is the integrated tree: for a /graph wave, git diff main...wave-{K}-{slug} (a single-node wave reviews that node's branch directly); for a /loop-it batch, the batch branch assembled at the end
• Read it one section per node / per issue, in planned order, and give the seams — shared interfaces, wiring/setup files, config and state — more attention than each node's interior: that is the class of defect a per-node self-review structurally cannot see
• This is the only review the wave gets: never skip it, and never let one feature's section absorb the whole pass
• Fix accepted findings, then re-run the gates on the integrated tree, until no actionable finding remains

/ship-it is the standard closing workflow after implementation is complete: commit code, create PR, merge, add implementation summary, close Issue. At the close of a /graph wave or a /loop-it batch it is called exactly once: one branch, one PR, one CI run, one merge, closing the several Issues that wave or batch satisfied.

How to Invoke

# Run this directly
/ship-it

# Or use trigger phrases
Submit code
Create PR and merge

Complete Flow

# Step 1: Commit code (link Issue)
git add <related files>
git commit -m "Add priority field to database (#42)"

# Step 2: Push branch
git push -u origin feat/issue-42-priority-field

# Step 3: Create PR (body includes Closes #42)
gh pr create --title "Add priority field" \
  --body "Closes #42 ..."

# Step 4: Merge
gh pr merge --squash --delete-branch

# Step 5: Close Issue (if not auto-closed)
gh issue close 42 --reason completed

Several Issues in One PR (Wave / Batch Mode)

A /graph wave and a /loop-it batch default to putting several Issues into one PR (after squash, only one commit remains). The PR body must list the evidence item by item — a single Closes #1 #2 #3 line is not enough, because then neither you nor the user can audit or revert a single feature.

• The commit column is mandatory: after the squash those commits are invisible on main, so the PR body is the only place left to trace or roll back a single item
• Evidence must be concrete: name the test or the command, never "tests pass"
• Mark manual acceptance per item: if nobody has walked that item's main path, write "Not manually accepted yet"; only the user can clear it, and the confirmation basis (time / environment) must be noted
• Close Issues one by one: give each item its own Closes #N (or close it manually after the merge) instead of one combined line
• This PR merges N items; to revert a single item after the squash, revert its commit from the table by hand

A single-item PR (one Issue, one PR) does not need this table — the "Complete Flow" above is enough.

Error Handling

/humanize-it rewrites specified documents to remove AI-generated feel. It automatically selects the most appropriate humanization strategy based on document type, iterating until the result meets quality standards.

How to Invoke

# Run this directly
/humanize-it docs/architecture.md

# Or use trigger phrases
De-AI: Rewrite this document in natural language
Reduce AIGC: humanize docs/blog-draft.md

Sub-Skill Capability Matrix

Automatic Strategy Selection

Iteration Mechanism

• Auto-detect document type, select first rewriting skill
• After rewriting, score on 5 dimensions (AI trace removal / naturalness / information completeness / style consistency / readability)
• Score ≥ 80 passes; output result
• If not meeting target, switch to next skill, continuing to optimize on top of previous rewrite
• Auto-switch if same skill shows no improvement for 3 consecutive rounds
• After all skills used once, start a new round from the beginning with new combinations
• Maximum 42 iterations; output current best result

/insight-diagram generates UML diagrams, architecture diagrams, and flowcharts for any project. After analyzing the codebase, it lets users choose which diagram types to generate, renders them as HTML+SVG, and saves to the docs/ directory.

How to Invoke

# Run this directly
/insight-diagram

# Or use trigger phrases
Generate architecture diagram: Analyze project structure and generate architecture diagram
Draw flowchart: Draw call flow diagram for this module
Generate UML: Generate class diagram and sequence diagram

Supported Diagram Types

A total of 17 diagram types, divided into structural and behavioral categories:

Structural Diagrams (Static)

Behavioral Diagrams (Dynamic)

★ Indicates most commonly used diagram types. Default recommended combination: Architecture Diagram + Sequence Diagram + Flowchart.

Workflow

• Analyze project codebase, identify key components and dependencies
• Present list of available diagram types; user selects which to generate
• Use architecture-diagram skill to render as HTML+SVG
• Save output to docs/ directory

/refactor provides expert-level code refactoring based on Martin Fowler's complete catalog from Refactoring 2nd Edition. By identifying code smells and applying proven refactoring techniques, it improves code maintainability, readability, and structure without changing external behavior.

How to Invoke

# Run this directly
/refactor

# Or use trigger phrases
Refactor: Refactor UserManager class, it's too large
Code smell: This function has Feature Envy, fix it
Extract method: Break this long method into smaller functions

Code Smell Catalog

Identifies 22 code smells, organized into five categories:

Refactoring Techniques Catalog

40+ refactoring techniques in 6 categories, each with mechanical steps and comparison examples:

Safety Protocol

• Preparation Phase: Write characterization tests → commit current state → create refactoring branch
• Each Step: One change at a time → compile passes → all tests pass → commit
• Verification Phase: All tests pass → manual smoke test → self-review diff → final commit
• Iron Rule: Don't change external behavior, don't mix with feature changes, every step backed by tests

Language-Specific Guides

/modern-go automatically upgrades Go code to modern idioms and APIs, similar to go fix. It scans go.mod to detect the Go version, then batch-applies version-appropriate transformation rules to Go source files, covering 35+ rules from Go 1.0 through 1.27+.

How to Invoke

# Run this directly
/modern-go

# Or use trigger phrases
Modernize: Modernize this project's Go code
Upgrade Go code: Update to Go 1.22 idioms
Gofix: Scan pkg/ directory and apply transformations

Workflow

• Read go.mod to get Go version
• Find .go files within target scope (specified file/directory/entire project)
• Scan each file for "Before" patterns, apply all transformations for versions ≤ project version
• Each transformation includes a concise comparison table and code examples (before/after)
• After editing, run goimports -w to clean imports
• Output transformation report: file count, transformations applied, rules skipped

Transformation Rule Catalog (by Go Version)

Safety Rules

• omitzero is suggested only, not auto-applied (may change JSON serialization behavior)
• SplitSeq is applied only when the loop body doesn't need index or full slice
• strings.Builder is applied only when concatenation happens inside a loop
• Each transformation that needs a new import auto-adds it and runs goimports to clean up

/note-it generates a structured implementation note for the current Issue after code implementation and review, recording design decisions, deviations, tradeoffs, and open questions. Output is saved as HTML in the docs/ directory.

How to Invoke

# Run this directly
/note-it

# Or use trigger phrases
Record notes: Generate implementation notes for Issue #42
Implementation notes: Record decisions and deviations from this implementation

Note Contents

Output

• Auto-detect the Issue number (from the branch name or the current context)
• Generate HTML format note file
• Save to docs/issue#NNNN.md
• If notes already exist for this Issue, prompt to append or overwrite

Positioning

/note-it sits between /review-it and /ship-it in the workflow, serving as the final checkpoint before submission — ensuring implementation intent is fully documented for future maintainers to understand the decision logic behind the code.

/walkthrough runs after implementation, its verification pass and /review-it, and before /ship-it: it writes one Markdown artifact a reviewer can read to catch up on what changed and what is proven to work, with visual proof of the demo path. The point is evidence, not assertion — a diff says what the code looks like; a walkthrough says what you ran, what it printed and what you saw.

How to Invoke

# Run this directly
/walkthrough

# Or use trigger phrases
Walkthrough: write the pre-ship walkthrough for user-auth
Write the walkthrough: collect the verification evidence and a draft PR

The Four Parts of the Artifact

Output

• Format: Markdown, one file
• Saved to tasks/walkthrough-<feature>.md (tasks/ is the collection's default directory for working artifacts)
• Filename in kebab-case; take the feature name from the user first, then the branch or a matching tasks/prd-*.md / spec-*.md, and ask if none exists
• Images default to relative paths (![caption](tasks/shot.png)), committed alongside the file: the artifact stays small and the diff stays reviewable
• Use a base64 data URI only when the artifact must survive on its own (pasted into a chat, an issue comment — anywhere the images will not travel with it), and say which mode you used

Positioning

/walkthrough is /note-it's sibling: both produce an artifact after review and before shipping, but they own different things — /note-it records design rationale (why it was built this way), while a walkthrough records evidence (what was run, what was seen) plus a pre-merge checklist. It records gate output; it does not replace the project's own gates. A step you could not verify is written as unverified or as a blocker — never as proven.

/code-to-spec analyzes an existing project's code, configuration, tests, and structure, then reverse-generates a complete SPEC document. The output can be used for project reconstruction, onboarding new team members, or comparing actual implementation against intended design.

How to Invoke

# Run this directly
/code-to-spec

# Or use trigger phrases
Generate design doc: Analyze current project and generate SPEC
Reverse spec: Reverse engineer this project's specification
Generate SPEC document: Generate technical SPEC for src/ directory

Analysis Depth

SPEC Document Structure (12 Chapters)

Workflow

• Confirm analysis scope (entire repo / specified directory / specific aspects) and depth level
• Scan project: identify entry points, directory structure, dependency graph, API routes, data models
• Extract business rules: derive from validation functions, guard clauses, test assertions
• Synthesize and generate 12-chapter SPEC document
• Present for review; iterate based on feedback
• Save to docs/SPEC.md or user-specified location

/smell analyzes a codebase for architectural anti-patterns, code smells, and algorithmic complexity hotspots. It produces a detailed markdown report with severity levels, evidence, and a refactoring roadmap.

How to Invoke

# Run this directly
/smell

# Or use trigger phrases
Code smell analysis: find code smells in this project
Architecture audit: detect architecture anti-patterns
Complexity scan: analyze code complexity and find hotspots

Detection Categories (8 Categories, 50+ Smells)

Report Structure

• Executive Summary with overall health assessment
• Architectural Style Detected vs. Expected
• Findings by severity (Critical / Warning / Suggestion)
• Dependency Graph Analysis and Module Health Scorecard
• Smell distribution across all 8 categories
• Refactoring Roadmap (Immediate / Short-Term / Long-Term)

/loop-it fetches all open GitHub issues and resolves dependency order. It implements one Issue at a time, inline (read the requirement → write the code → prove it with the project's gates) and commits on that Issue's own branch (no push, no PR). At the end of the batch it merges the surviving branches into a single batch branch (failed branches are never merged in) and runs /review-it once and /ship-it once. It persists progress to .loop-state.json so you can resume from where you left off after a crash or interruption.

How to Invoke

# Run this directly
/loop-it

# Or use trigger phrases
Batch implement: 实现所有issue
Loop issues: 批量实现
Resume loop: 恢复循环

Key Features

• Pre-flight Checks — Validates gh auth, git status, remote access, and branch cleanliness before starting
• Dependency-Aware Topological Sort — Parses issue bodies for dependency patterns and sorts accordingly
• Checkpoint/Resume — Persists state to .loop-state.json after every status transition; resume from checkpoint on crash
• Structured Error Recovery — 10 error classes (build, test, lint, merge conflict, CI, auth, rate limit, etc.) with per-class recovery strategies and retry limits
• Branch Hygiene — Isolated feat/issue-N-desc branch per issue; commits stay on that branch (no push); at batch end the surviving branches merge into one batch branch, while failed branches are never merged in and are preserved
• Dependency Blocking — Issues whose dependencies are not shipped are automatically blocked
• Progress Observability — Structured progress report after each issue (shipped/skipped/blocked/failed/remaining)

Pipeline Integration

# Full pipeline from PRD to shipped code
/prd → /prd-to-spec → /to-issues → /loop-it
                                               │
                                               └→ per issue: implement inline → prove → commit (× N)
                                                  batch end ×1: batch branch → /review-it → /walkthrough → /ship-it

/to-design turns a PRD (or a rough idea) into a design document written in the style of Go's official design proposals: plain language, concrete examples, and — above all — an honest account of why this approach and not the alternatives.

How to Invoke

# Run this directly
/to-design tasks/prd-priority-system.md

# Or use trigger phrases
Design doc: write a design doc for the priority system
prd-to-design: based on prd-user-auth.md

When to Use

• A PRD exists and you need to decide how to build it before committing
• The approach has real tradeoffs you want documented and debated
• The change is risky, breaking, or hard to reverse (a design doc forces the compatibility conversation early)
• Multiple people need to agree on a direction before work fans out
• You want a durable record of "why we chose X and rejected Y" — even if later rejected

Design Document Structure (distilled from 5 Go proposals)

Workflow

• Locate input (PRD file / Issue URL / pasted content / just an idea)
• (Optional) Scan the codebase: existing patterns, constraints, real pain to quote
• Find the genuine "forks in the road" and ask 3-5 clarifying questions
• Generate the design doc in Go-proposal style
• Present for review — steer feedback to Rationale and Compatibility
• Save to tasks/design-[feature-name].md

/graph turns a task (or PRD / SPEC / issue set) into a directed acyclic graph (DAG), layers it by dependency into supersteps (waves), then implements the independent nodes of each wave concurrently: one subagent per node implements inline and commits on its own branch inside its own git worktree; a fan-in barrier between waves then runs the leak check, merges only the nodes that shipped, runs the gates on the integrated tree, and reviews once + writes the walkthrough once + ships once before dynamically re-planning the next wave.

The design borrows from the trending idea of graph engineering, LangGraph's StateGraph / Pregel-BSP superstep model, and Claude's dynamic-workflow orchestration.

How to invoke

# Run this directly
/graph tasks/prd-url-shortener.md

# Or use trigger phrases
parallel implement: turn these issues into a task graph and run in parallel
build a graph: fan out the DAG concurrently

Core concepts (from LangGraph / graph engineering)

Workflow

• Decompose into nodes — reuse /to-issues rules; each node has title, deps, acceptance criteria, type, and scope_hint (files it's expected to touch)
• Build the DAG & validate — detect cycles (break by id), dangling deps, scope collisions
• Topological layering — Kahn's algorithm layers nodes into waves; nodes editing the same logic serialize to the next wave
• Render the graph & confirm — emit the layered plan + a Mermaid diagram, wait for user confirmation before fan-out
• Execute wave by wave — fan-out (multiple subagent calls in one response = parallel) → fan-in barrier → integrate, update state, dynamically re-plan

Key features

• Worktree isolation (mandatory) — each node owns a git worktree; parallel edits never clobber the working tree
• Fan-in barrier (mandatory) — wave N+1 cannot start before every node in wave N has finished and the wave's integration is done (BSP semantics)
• Scope-collision serialization — dep-free nodes editing the same logic split across waves; a shared "wiring file" (router/main) is exempt so it doesn't serialize the whole graph
• Dynamic re-plan — subagents report new work via a NEW_WORK: line; the barrier revises and re-layers the graph
• Failure blocks dependents — a failed node marks all its dependents blocked and skips them
• Checkpoint / resume — each wave writes .graph_state.json; a crash resumes at the wave boundary, and graph.html is re-rendered (open it in a browser — it auto-refreshes every 5s to track waves, node statuses, and progress live)
• Concurrency cap — default 3–4 parallel subagents to avoid rate limits and merge contention

Concurrent execution

# Per wave: fan-out → fan-in barrier
Wave 0 (parallel×3):  #1 db schema   #2 cache layer   #3 logging util
Wave 1 (parallel×2):  #4 API (deps #1)   #5 CLI (deps #2)
Wave 2 (parallel×1):  #6 integration (deps #4,#5)

# Each node, in its own worktree:
implement inline → prove → commit on its own branch

# End of each wave (once):
leak check → merge only shipped nodes → gates on the integrated tree → /review-it → /walkthrough → /ship-it

Pipeline integration

/prd → /prd-to-spec → /to-issues ┬→ /loop-it  # sequential: one node at a time
                                        └→ /graph    # parallel: whole wave at once

/understand turns the changes you just generated (usually AI-written) into a single-file interactive review webpage, so you can actually understand what changed before reviewing or shipping it. It scans the repo's uncommitted / branch changes and builds a Claude-style light-themed two-column page: a project file tree on the left, and the selected file's syntax-highlighted diff on the right, with a side rail that pairs each code segment with its unit requirement and a plain-language explanation.

How to Invoke

# Run this directly
/understand

# Or use trigger phrases
Review changes: Explain what this batch of new code does
Understand code: Walk me through the freshly generated changes

What You Get

How It Works

• Scan changes: committed (base..HEAD) + staged + unstaged + untracked files, baseline = merge-base with the main branch
• The agent reads every change, then writes requirement + explanation annotations
• Render a self-contained .understand/report.html and open it in the browser

Positioning

/understand is a comprehension companion to /review-it: where /review-it finds and fixes issues, /understand helps you see the intent and rationale behind freshly generated code before you commit to it.

/ask-flow is the entry point to the whole skill set: you cannot remember what all these skills own, so you ask. Describe where you are (a half-formed idea, a pile of inbound issues, code that will not work, a long implementation) and it gives you the next step, plus which decisions inside that step are yours to make.

How to Invoke

# Run this directly
/ask-flow

# Or just ask
Which skill should I use?
How do I run this workflow?

What It Routes

• Main line: /prd → /prd-to-spec (when the design is complex) → /to-issues → the fork (true parallelism /graph / sequential /loop-it / a single unit /implement) → implement inline → prove with the gates → /review-it → /ship-it; add /note-it when decisions need a record, and /walkthrough for the pre-ship walkthrough
• Bypasses: a bug goes to /diagnose, raw inbound items to /triage, pinning behaviour down first to /test-first, and an in-progress merge / rebase to /conflict
• It suggests, never executes: it will not grill your requirements, write a spec or edit a file, and it will not quietly run the skill you just asked about
• It reports its own gaps: the maintenance rule requires it to be re-read and updated whenever a skill is added, renamed or deleted — along with both READMEs and these two HTML guides — because a lying router is worse than no router

/triage handles raw items that arrive from outside: bug reports, user feedback, requests filed by other people. It reproduces / understands first, assigns each item exactly one role, and fills the ready ones out into agent-executable cards. Never triage /to-issues output — that is already agent-ready.

Roles (every item ends in exactly one)

Handling One Item

• Reproduce / understand first: follow the reported steps; if you cannot reproduce it, say plainly "I cannot reproduce this with X" instead of pretending
• Judge the blast radius: who is affected, can it corrupt data, is there a workaround, does it only happen on older versions
• Fill it out into an agent-ready card: the body must be good enough for "a subagent that does not share this conversation can start on its own" — repro steps, expected behaviour, acceptance criteria, files / modules involved, and explicit non-goals; the same bar as /to-issues
• Leave a trace: post one comment on that issue when done (role + reason + next step), never just change labels; when the batch is finished, report the number of new ready / needs-info / wontfix items to the user

The discipline for hard bugs, intermittent flakes and performance regressions: no reasoning starts until there is a command already red on this bug — jumping straight to "I bet it's here" is exactly the failure this skill exists to prevent. It does no /review-it / /ship-it; once the cause is pinned down, go back to the main line as a single-point change.

How to Invoke

# Run this directly
/diagnose

# Or just say
Debug this intermittent failure
What is this performance regression?

The Loop

• Build a feedback loop: get a tight pass/fail signal (red on this bug) — a failing test, a curl / HTTP script, a CLI call plus fixture, a headless browser, replaying a captured trace, a one-off harness, property / fuzzing, a bisection harness, a differential loop. The bar: can go red, deterministic, seconds, runs unattended
• Reproduce + minimise: confirm the red is the failure the user described, then cut until "removing any remaining element turns it green"
• 3–5 falsifiable hypotheses: each states "if X is the cause, then changing Y makes the bug disappear / changing Z makes it worse"; anything without a prediction is a feeling, not a hypothesis. Show the ranked list to the user first — their domain knowledge often reorders it instantly
• Instrument one variable at a time: every probe answers a specific prediction; prefer debugger / REPL > targeted logging > never "log everything and grep". Give every debug log a unique prefix (e.g. [DEBUG-a4f2]) so one grep clears them all at the end. For performance regressions, establish a baseline measurement first, then bisect
• Add the regression test at the right seam, then fix: the test must reproduce the real bug pattern at the call site; having no correct seam is itself a finding (record it and open a new issue on the main line)
• Close-out checklist: the original repro no longer occurs, the regression test passes (or "no correct seam" is recorded), every [DEBUG-...] probe is removed, throwaway prototypes are deleted, and the hypothesis that survived is written into the commit / PR description

/conflict resolves an in-progress git merge / rebase: recover both sides' intent, resolve hunk by hunk, run the project gates, and finish the operation. Always resolve, never --abort.

Steps

• Read the situation: git status, git log --oneline --graph -10, list the conflicted files; establish whether this is a merge or a rebase, where it branched from, and what this merge is meant to achieve
• Recover each conflict's original intent: read both sides' commit messages, look at the matching PRs and issues, grep call sites when needed — never just pick whichever side is newer or bigger
• Resolve hunk by hunk: keep both sides' intent when both can be preserved; when they genuinely conflict, take the side consistent with this merge's goal and write the tradeoff into the commit message — never invent new behaviour
• Run the project gates: build + test at minimum; the bar is the merged tree passing the gates on its own, not "the two sides look right together"
• Finish: git add every conflicted file and complete the operation (for a rebase, git rebase --continue until every commit is replayed), then write "which side gave up what" into the commit / PR description

Q: Do I have to use all steps in order?

No. Each Skill is independent and can be used standalone. For example, if you already have Issues, you can start directly from /implement (a single unit), /loop-it (sequential) or /graph (parallel); if code is already written, you can use /review-it directly. But going through the full workflow yields the best results.

Q: Where does /goal come from? Why isn't it in the skills directory?

/goal is a DSH command, not a skill, so it is not in ~/.agents/skills. A human types it to create a persisted objective with automatic continuation rounds. The model side of that surface is create_goal / update_goal, but create_goal only runs in a direct top-level human turn — a subagent, or a skill running mid-orchestration, cannot mint a long-horizon goal for itself. It is not the implementation step either: implementation is done inline by the agent, driven by /loop-it or /graph.

Q: Can I use this in non-GitHub projects?

Yes. /to-issues can save Issues as local Markdown files. /review-it only needs a local git repository. /ship-it currently depends on GitHub (gh CLI).

Q: How is /review-it different from manual code review?

/review-it is automated self-review, catching obvious issues before submission. It reports on two axes: the Spec axis checks whether the diff did what was asked (missing / extra / wrong, each finding quoting the acceptance criterion it is checked against), and the Standards axis checks code quality across 8 dimensions. The two are reported separately, never merged into one ranking. It doesn't replace team code review, but rather improves code quality before PR creation, reducing the low-level issues reviewers need to point out.

Q: How big should an Issue be?

Each Issue should represent work an agent can complete in a single session — typically 1-3 files of changes with clear acceptance criteria. /to-issues holds that line when it splits, and you can adjust before confirming.

Q: Is /prd-to-spec required? When can I skip it?

Not required. /prd-to-spec is an optional step. PRD says "what to do"; SPEC says "how to do it". The distinction: an AI agent executing /implement inherently possesses the "how" capability — it automatically analyzes the codebase, understands existing architecture and conventions, and makes reasonable technical decisions during implementation. In other words, the AI agent is a living SPEC engine — it doesn't need it drawn on paper first.

Most small to medium features work perfectly fine with just PRD → /to-issues → implementation. The following scenarios justify the extra step of /prd-to-spec:

• Multi-person/multi-agent parallel development — need shared technical conventions to avoid divergent implementations
• Changes spanning multiple services/modules — architecture decisions have broad impact and rework costs are high
• Need maintained documentation — a formal technical reference for the team to consult later
• Compliance/review requirements — organizational process mandates design documents
• PRD is too vague — SPEC can supplement with technical details to reduce agent interpretation variance

If your project is single-developer, feature boundaries are clear, and the agent already reliably understands the project structure, skipping /prd-to-spec is entirely reasonable — and often more efficient. Treat it as an optional tool in your toolkit — bring it out only when needed.

Q: Where does the 42 iteration limit in /humanize-it come from?

The number 42 isn't due to any special iteration requirement, but a geek culture tribute to the classic sci-fi novel The Hitchhiker's Guide to the Galaxy. In the book, a supercomputer computes for 7.5 million years and arrives at "the Answer to the Ultimate Question of Life, the Universe, and Everything" — which is 42. In programming circles, this number is popular for two reasons:

• Sci-fi tribute: A well-known Easter egg among programmers, representing the ultimate answer.
• ASCII coincidence: In ASCII encoding, 42 corresponds to the asterisk *. In computer science, * is commonly used as a wildcard meaning "anything" or "everything is possible." So "the ultimate answer is 42 (*)" perfectly aligns with the philosophical joke that it's "whatever answer you want."

In practice, most documents reach quality standards within 3-5 iterations. The core of iteration is intelligent strategy switching — when one rewriting approach plateaus, it automatically switches to another. The three strategies complement each other to cover different types of AI traces.

Q: Does /humanize-it support English documents?

Currently, the three sub-skills of /humanize-it are primarily optimized for Chinese text. humanizer-zh's pattern detection rules partially work for English as well, but rewriting effects are best for Chinese.

Q: What diagram types does /insight-diagram support?

/insight-diagram supports 17 diagram types, including system architecture diagrams, 14 UML diagrams (class, object, component, deployment, package, composite structure, profile, use case, activity, state machine, sequence, communication, timing, interaction overview), flowcharts, and swimlane diagrams. Output is in HTML+SVG format, saved to the docs/ directory. Applicable to any software project.