GSD + Skill Creator Advanced Guide

2. The Vision-to-Mission Pipeline (VTM)

Every significant piece of work in GSD passes through a five-stage pipeline that transforms an idea into a verified deliverable. The pipeline is not metaphorical — it maps directly to GSD commands and file artifacts.

The Pipeline in Practice: BLN Textbook

The Blender User Manual (BLN) demonstrates the full pipeline at scale. The vision was a comprehensive Blender manual — 10 research modules covering all of Blender 4.4, from interface to furry arts production.

Vision: A mission pack defined the scope: 10 chapters, glossary, cross-references, production-quality prose. Success criteria were explicit — 100K+ words, 6 Blender domains, 350+ target pages.

Research: Five research agents ran in parallel, each responsible for 2 modules. They produced 107K words of structured research — technical depth with pedagogical framing — in a single wave.

Planning: The research output fed into chapter plans. Each chapter had a REQUIREMENTS.md and PLAN.md with section-level specifications, glossary terms, and cross-reference targets.

Execution: Six chapter expansion agents ran in parallel. Each received its research module plus the master glossary, ensuring consistency. The output was 329 pages of final content.

Verification: Goal-backward analysis checked every success criterion against the deliverables. Coverage audits confirmed cross-module references resolved correctly. The verification matrix scored 12/12 PASS.

Total: 11 parallel agents, 107K words of research, 329-page PDF, one session.

3. Wave-Based Parallel Execution

GSD decomposes execution into waves — ordered batches of work where parallelism is safe within a wave and sequencing is enforced between waves. This is how the system runs multiple agents without race conditions or context conflicts.

Wave 0 Haiku	Foundation. Sequential. Schemas, templates, directory structure, shared constants. Everything downstream depends on these artifacts existing. Haiku is fast and cheap — foundation work is mechanical.
Wave 1 Sonnet	Content production. Parallel. Multiple agents writing simultaneously into non-overlapping file spaces. Each agent gets its own scope (chapter, module, component). Sonnet balances quality with throughput.
Wave 2 Opus	Synthesis. Sequential. Cross-module integration, cross-reference resolution, consistency audits, style normalization. Opus handles the long-context reasoning this requires.
Wave 3 Sonnet/Haiku	Publication. Sequential. Assembly into final output format, verification against success criteria, delivery (commit, release, FTP sync). Mechanical work, lower model tier.

Real Numbers

The BLN mission used 11 agents across 4 waves with an estimated 761K tokens. The HEL research project used 9 agents producing 28 documents and 91K words. The Seattle 360 engine has shipped 64 autonomous releases so far, each following the same wave structure at smaller scale.

Why Waves Work

Waves solve the fundamental tension between parallelism and correctness. Within a wave, agents operate on disjoint file sets — no merge conflicts, no overwritten work. Between waves, the sequential barrier ensures downstream agents see the complete output of upstream work. The model assignment per wave (Haiku for scaffolding, Sonnet for content, Opus for synthesis) optimizes cost without sacrificing quality where it matters.

4. The Skill System

Skills are the adaptive learning layer. They auto-activate based on context — you never invoke them manually. When you start planning a phase, the gsd-workflow skill loads. When you commit, beautiful-commits activates. When you work on research, research-engine provides the pipeline.

Skill Anatomy

Each skill is a YAML-frontmatter markdown file in .claude/skills/. The frontmatter defines activation:

---
name: research-engine
description: Autonomous research pipeline
triggers:
  intents:
    - research
    - investigate
    - deep dive
  contexts:
    - planning research phases
    - producing research documents
applies_to:
  - "www/**/*.html"
  - "www/**/*.md"
---

The body contains the skill's instructions — the knowledge and patterns the agent should apply when the skill is active. Skills compose naturally: when you run a research phase that produces commits, research-engine + gsd-workflow + beautiful-commits all activate simultaneously.

69 Installed Skills

Skills are organized by domain: GSD workflow management, agent orchestration (Gastown convoy, GUPP, fleet-mission), content pipelines (research-engine, publish-pipeline), session management (session-awareness, context-handoff, beads-state), security (security-hygiene), and development patterns (typescript-patterns, test-generator, code-review). The skill-integration skill manages the lifecycle of all other skills — it observes patterns and can suggest new skills when it detects recurring workflows.

How Skills Compose

The power of the skill system is composition. A typical autonomous research mission activates:

• gsd-workflow — phase routing, lifecycle management
• research-engine — topic-to-document pipeline, HTML/PDF output
• publish-pipeline — Pandoc + XeLaTeX templates, FTP sync
• beautiful-commits — conventional commits with semantic structure
• session-awareness — cross-session state, crash recovery
• beads-state — git-friendly persistence for orchestration state

No configuration required. The skills detect context and load themselves.

5. Agent Orchestration Patterns

The system includes five proven orchestration patterns, each designed for a different topology of work. These are not theoretical — every pattern has been validated at production scale with real deliverables.

New Subagent Fields (Claude Code v2.1.88+)

The latest Claude Code release added powerful subagent configuration fields that these patterns leverage:

• effort — control reasoning depth per agent
• maxTurns — set execution budgets to prevent runaway agents
• isolation: worktree — each agent gets its own git worktree, eliminating file conflicts
• memory — per-agent persistent memory across turns
• skills — explicitly load skills into subagent context
• mcpServers — connect agents to MCP tool servers

6. The Hook System

Hooks provide deterministic automation — behaviors that fire reliably every time, independent of the LLM's reasoning. Unlike skills (which influence the LLM's behavior), hooks execute scripts before or after tool calls and cannot be overridden by the model.

Available Hook Points

Example: Commit Validation Hook

A PreToolUse hook on Bash intercepts every git commit command and validates the message against Conventional Commits format before allowing it to execute:

{
  "event": "PreToolUse",
  "tool": "Bash",
  "if_conditions": { "command_contains": "git commit" },
  "script": "validate-conventional-commit.sh",
  "action": "block_on_failure"
}

This fires every time, regardless of which skill is active or what the LLM's instructions say. The commit either passes validation or it does not. Deterministic.

Hook + Skill Composition

The hook system and skill system work in complementary layers. Skills guide the LLM's reasoning ("use conventional commits, include a scope"). Hooks enforce invariants the LLM must not violate ("this commit message does not match the format — blocked"). The combination produces reliable behavior: the skill makes the model want to do the right thing; the hook ensures it.

7. NASA Systems Engineering Methodology

GSD's planning methodology is adapted from NASA's systems engineering process. The core insight: planning is the hard part; once the plans are done the code is easy. The methodology has three levels, each building on the previous.

Level 1: Requirements

What must be true when this phase is complete? Requirements are concrete, verifiable, and scoped. They live in REQUIREMENTS.md and use the pattern: "The system shall [verb] [object] [constraint]." Requirements are written before any implementation discussion.

Level 2: Plan

How will the requirements be satisfied? Plans decompose into tasks, specify file paths, define wave assignments, and estimate model profiles. The plan is the execution contract — agents follow it literally. Plans live in PLAN.md and reference specific requirements by ID.

Level 3: Execution

The plan is executed by agents following the wave structure. Each task maps to a commit (or small set of commits). Execution is deterministic: given the same plan and the same model, you get substantially the same output.

Pre-Execution Intelligence

The methodology's secret weapon is answering questions before building. The /gsd:discuss-phase command gathers context through adaptive questioning. The /gsd:research-phase command produces research documents. The /gsd:list-phase-assumptions command surfaces hidden assumptions. By the time execution begins, there are no open questions — only tasks.

Verification

Verification checks what was built against what was planned. The /gsd:verify-work command performs goal-backward analysis: start from each requirement, trace forward to find the artifact that satisfies it. Any requirement without a corresponding deliverable is a gap. The 4-level verification ladder (static, artifact, behavioral, human) ensures thoroughness.

8. State Management

GSD is a disk-driven state machine. All state lives in files — no databases, no external services, no hidden memory. This makes the system inspectable, diffable, and crash-recoverable.

The .planning/ Directory

The .planning/ directory is gitignored by design. It contains all mutable project state:

• STATE.md — current phase, active workstreams, blockers
• ROADMAP.md — milestone phases with status indicators
• REQUIREMENTS.md — per-phase requirements
• config.json — project configuration (model profile, toggles)
• Phase directories (phase-01/, phase-02/, ...) with PLAN.md, research, artifacts

Cross-Session Persistence

MEMORY.md provides cross-session persistence for Claude agents. It is structured into HOT (always in context), WARM (loaded at session start), and COLD (referenced on demand) sections. The session-awareness skill manages session recovery, and context-handoff creates structured handoff documents when sessions end.

Beads-State

For multi-agent orchestration, the beads-state system provides git-friendly, crash-recoverable state persistence. Agent identities, work assignments, progress counters, and completion status are all stored as flat files that survive process crashes and context compactions. The PostCompact hook triggers state recovery automatically.

Crash Recovery

Because all state is on disk, crash recovery is reading files. The /gsd:resume-work command reads the latest state, reconstructs context, and resumes execution from where it left off. The /gsd:health command diagnoses and repairs state inconsistencies. No work is lost to crashed sessions.

9. Model Profiles

Different tasks need different levels of intelligence. GSD provides three profiles that control which model is assigned to each execution role. Switch profiles with /gsd:set-profile.

Role	Quality	Balanced	Budget
Orchestration (mayor, coordinator)	Opus	Sonnet	Sonnet
Content production (polecats, fleet)	Sonnet	Sonnet	Haiku
Synthesis (cross-module, verification)	Opus	Sonnet	Sonnet
Scaffolding (schemas, templates)	Haiku	Haiku	Haiku
Planning (requirements, research)	Opus	Sonnet	Haiku

Quality profile uses Opus for all reasoning-heavy work. Best for complex milestones where correctness matters more than cost. The BLN textbook used this profile.

Balanced profile is the default. Sonnet handles most work, Haiku handles scaffolding. Good for daily development where throughput and cost are both factors.

Budget profile pushes Haiku as far as it can go. Use for mechanical work: generating boilerplate, running formatting passes, producing repetitive content from templates. Not recommended for research or synthesis.

10. Real-World Case Studies

11. Common Pitfalls