let-it-go Usage Guide

let-it-go is a set of development-workflow skills: 27 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/let-it-go

# Or install specific skills — flow (10)
npx skills add 9Ashwin/let-it-go --skill ask-flow
npx skills add 9Ashwin/let-it-go --skill prd
npx skills add 9Ashwin/let-it-go --skill to-design
npx skills add 9Ashwin/let-it-go --skill to-issues
npx skills add 9Ashwin/let-it-go --skill implement
npx skills add 9Ashwin/let-it-go --skill loop-it
npx skills add 9Ashwin/let-it-go --skill graph
npx skills add 9Ashwin/let-it-go --skill review-it
npx skills add 9Ashwin/let-it-go --skill walkthrough
npx skills add 9Ashwin/let-it-go --skill ship-it

# bonus (7)
npx skills add 9Ashwin/let-it-go --skill test-first
npx skills add 9Ashwin/let-it-go --skill triage
npx skills add 9Ashwin/let-it-go --skill diagnose
npx skills add 9Ashwin/let-it-go --skill conflict
npx skills add 9Ashwin/let-it-go --skill refactor
npx skills add 9Ashwin/let-it-go --skill modern-go
npx skills add 9Ashwin/let-it-go --skill understand

# vendor — verbatim third-party copies (10)
npx skills add 9Ashwin/let-it-go --skill svg-diagram
npx skills add 9Ashwin/let-it-go --skill find-skills
npx skills add 9Ashwin/let-it-go --skill frontend-design
npx skills add 9Ashwin/let-it-go --skill humanizer-zh
npx skills add 9Ashwin/let-it-go --skill pptx
npx skills add 9Ashwin/let-it-go --skill resume-optimizer
npx skills add 9Ashwin/let-it-go --skill skill-creator
npx skills add 9Ashwin/let-it-go --skill teach
npx skills add 9Ashwin/let-it-go --skill ui-ux-pro-max
npx skills add 9Ashwin/let-it-go --skill web-design-guidelines

# Global install (available for all projects)
npx skills add 9Ashwin/let-it-go -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/let-it-go -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 groups the 27 entries into Let It Go Flow / Bonus / Vendor using the root .claude-plugin/marketplace.json; what lands in ~/.agents/skills is still flat, so the bucket exists in the repo only. Copying by hand means doing the flattening step yourself:

# flattened, not the bucket
cp -R <let-it-go>/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/let-it-go

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

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

Prerequisites

Six-step closed loop, from requirements to delivery (/to-design is inserted only when the change spans two or more services, alters the data model or a migration, or touches two or more external contracts — otherwise it is skipped):

/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 step: /to-issues

Output Example

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

/to-issues    (split the PRD into Issues with blocking edges)

/to-issues breaks down a PRD (or any piece of requirements prose) 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 this requirement into implementable cards
Generate cards: Break the PRD into Issues with blocking edges

Input Sources

Creation Platforms

Workflow

• Locate the input (auto-detect a PRD, specify one, or paste requirements prose)
• Find prefactoring ("make the change easy" groundwork) and order it first
• Break down into vertical-slice Issues, writing the contract fields (goal / non-goals / acceptance criteria / required evidence / external boundary / definition of done / open questions) into the body, 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 18. /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 → supervisor check, judged on evidence rather than how the diff looks) 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: per Issue — implement → prove → record evidence → supervisor check → commit; 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 → an evidence check on every node (judged on the evidence the node reports — commands and real output, not on how the diff reads) → 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, close the Issue, and write the implementation summary comment once (decisions / deviations / tradeoffs / open questions). It is the sole producer of the PR body — /walkthrough only supplies evidence, which this skill writes into the body once. 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

/svg-diagram is a house style for hand-written SVG diagrams: it fixes a technical look with CJK-friendly typography, and backs it with mechanical checks that prove the figure actually follows the rules. Flowcharts, architecture diagrams and sequence diagrams all go through it.

How to Invoke

# Run this directly
/svg-diagram

# Or use trigger phrases
Draw an architecture diagram: diagram the skill-loading flow as SVG
Draw a flowchart: draw this module's call flow as SVG

What the Conventions Cover

Mechanical Lint: tools/svg-lint

The skill ships a zero-dependency tools/svg-lint that runs 12 checks over an SVG: overlap, block spacing, box height, connector geometry, arrow markers, text overflow, viewBox clipping, font stack, palette conformance, light-background fallback, baseline offset, and XML escaping.

Workflow

• Put the file in an assets/ directory next to the document (e.g. docs/foo.md → docs/assets/foo-arch.svg)
• Reference it from Markdown with a relative path (![title](assets/xxx.svg)); never inline the SVG XML into the prose
• Walk the verification checklist yourself after generating, and fix spacing, padding, alignment and clipping before showing the result
• When the data in the document changes, update the SVG with it — a figure that contradicts the prose beside it is worse than no figure

/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.

Two Modes

When a request mixes both ("find the problems and fix them"): run audit first, confirm the findings with the user, then switch to fix on the agreed list.

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

/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 for this change

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 supplies evidence only: the commands and their real output, visual proof, risks, and manual acceptance status. The PR body and the merge checklist are not produced here — they are /ship-it's output, written once by that skill; a second copy here is the same content maintained in two places. 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.

/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 → record evidence) 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. The observation behind each acceptance criterion is recorded as structured evidence in that same checkpoint, and anything new found while running goes into a followup queue — so the batch can grow new issues while it runs instead of being frozen at the list written during decomposition.

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
• Per-issue supervisor check — after each issue is implemented, a reviewer with a fresh context reads the evidence (commands and their real output); the criterion is evidence, not diff aesthetics, while /ship-it still runs once at batch end
• Structured evidence — each acceptance criterion maps to an actual observation (test / runtime / database / external / human) carrying the command that produced it, its result and an artifact path; deferred stays distinguishable from pass, so a check that was never run cannot be written up as one that passed
• Follow-up ledger — a supervisor verdict of follow-up writes the new task into the checkpoint, versioned with the requirement's own material; at batch end each one is closed out, either promoted into a new issue for another round or dropped with a written reason
• 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 → /to-issues → /loop-it
                              │
                              └→ per issue: implement inline → prove → record evidence → supervisor check → commit (× N)
                                 batch end ×1: close out follow-ups → 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. The Markdown proposal is the primary deliverable; rendering it as a single-file HTML page is an optional presentation layer and is not done by default.

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, gives every node an evidence 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 PR body and merge checklist are produced by /ship-it alone; /walkthrough only supplies evidence.

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 → evidence check per node → merge only shipped nodes → gates on the integrated tree → /review-it → /walkthrough → /ship-it

Pipeline integration

/prd → /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 picks the next step, then starts it — reading that skill's body and following it, instead of naming a skill and leaving you to type it again.

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 → /to-design (conditional: written only when the change spans two or more services, alters the data model or a migration, or touches two or more external contracts; skipped otherwise) → /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 /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 starts that step: after routing it reads that skill's body and follows it, instead of naming a skill and leaving you to type it again; it stops only when two routes are genuinely close or the next step crosses the human judgement boundary (opening a PR, merging, product acceptance)
• 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

skills/vendor/ holds verbatim copies of third-party skills: this skill set did not write them, it collects them so they install alongside everything else. Which skill came from where, at which commit, is recorded in the manifest skills/vendor/vendor.json, and each skill directory carries a NOTICE.md (source / commit / license / sync date).

Maintenance Commands

make vendor        # copy every vendored skill in at its pinned commit
make vendor-check  # report vendored skills whose upstream has moved
make vendor-update # re-pin to upstream HEAD, sync, and validate
make vendor-list   # list vendored skills and pinned commits
make vendor-add URL=<git url> SKILL="name [name...]"
make check          # layout, frontmatter, cross-references, bundle patch
make test           # check first, then the bundled scripts' self-tests

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 running agent (see Step 2: Implementation).

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: Can I edit the skills under skills/vendor/?

No. Everything under skills/vendor/ is a verbatim copy of an upstream skill, and a local edit is overwritten by the next make vendor. Change the manifest in skills/vendor/vendor.json and re-sync; if what you want is a change this repo owns, write it as a flow / bonus skill. See 21. Vendor Skills and One-Command Sync.

Q: What does the /svg-diagram mechanical check cover?

It ships a zero-dependency tools/svg-lint with 12 checks: overlap, block spacing, box height, connector geometry, arrow markers, text overflow, viewBox clipping, font stack, palette conformance, light-background fallback, baseline offset, and XML escaping. The conventions themselves also cover layout, connector and arrow drawing, and the CJK font stack.