GSD Integration Guide

Overview

How the Four Systems Connect

The four integration subsystems operate at different points in the GSD workflow lifecycle, but they share a common dependency: the .planning/ directory.

The data flow is unidirectional: .planning/ data flows outward to the integration subsystems, never the reverse. GSD commands modify .planning/ state, and the integration subsystems observe those changes.

In a typical session, the subsystems activate in this order: (1) Orchestrator classifies intent and determines the GSD command, (2) Skill Loader prepares relevant skills for the phase, (3) GSD executes the phase with loaded skills, (4) if skills are generated during execution, Reference Injection annotates them, (5) Dashboard regenerates to reflect the new state.

Session Observation

Throughout all GSD-integrated work sessions, the integration layer maintains passive observation of patterns worth capturing. These observations are recorded to .planning/patterns/sessions.jsonl and feed into skill-creator's pattern detection pipeline. The types of observations recorded during GSD integration include:

• Orchestrator classifications — Input text, chosen command, confidence score, and which stage produced the result.
• Skill loading patterns — Which skills were loaded for which phase type, and which were deferred.
• Phase outcomes — Whether phases completed successfully, partially, or with failures.
• User corrections — When the user overrides an orchestrator classification, that correction is the highest-signal observation in the system.

Observations are append-only (never modified after writing) and are excluded from git by default.

Key Concepts

How It Works

GSD Orchestrator

The GSD Orchestrator (src/orchestrator/, introduced in v1.7) provides a 5-stage intent classification pipeline that translates natural language user requests into specific GSD slash commands.

Stage 1 — Exact Match: A dictionary lookup maps unambiguous phrases directly to GSD commands. This stage handles roughly 80% of real-world requests with zero computational overhead.

Stage 2 — Lifecycle Filtering: The orchestrator reads the project's .planning/ directory to determine the current project state and eliminates commands that are impossible given that state.

Stage 3 — Bayesian Classification: When multiple candidates survive lifecycle filtering, the orchestrator computes posterior probabilities for each remaining command. A command exceeding the confidence threshold (default 0.8) wins.

Stage 4 — Semantic Fallback: When Bayesian classification fails, the orchestrator falls back to embedding-based similarity.

Stage 5 — Confidence Resolution: If no stage has produced a result above the confidence threshold, the orchestrator presents the top candidates and asks the user to clarify.

# Complete flow example:
# User says: "review the requirements"

Stage 1 (Exact Match): No exact match found
Stage 2 (Lifecycle): Current state = milestone active, phases 1-3 planned
  Candidates: progress, discuss-phase, plan-phase, verify-work
Stage 3 (Bayesian): "review" + "requirements"
  P(progress | input) = 0.72
  P(verify-work | input) = 0.18
  P(discuss-phase | input) = 0.10
  Winner: /gsd:progress (0.72 < 0.8 threshold, not confident)
Stage 4 (Semantic): embedding similarity
  progress: 0.89
  verify-work: 0.61
  Winner: /gsd:progress (clear semantic winner)

Result: /gsd:progress

Lifecycle State Matrix

YOLO Mode Behavior

When .planning/config.json has "mode": "yolo", the orchestrator changes its resolution behavior at Stage 5. Instead of asking the user to clarify, it selects the highest-probability candidate and proceeds automatically. The confidence threshold for YOLO mode is lowered to 0.6.

Phase Skill Loading

The Phase Skill Loader (src/orchestrator/skill-loader.ts, introduced in v1.11) solves a critical problem: when GSD forks a subagent context to execute a phase, that subagent starts with a clean context window. The skill loader bridges this gap.

Before any GSD phase execution begins, the skill loader performs a four-step process: scan for skills, score for relevance, apply model filtering, and load within token budget.

Different GSD profiles have different budgets: the executor profile allocates 20,000 characters, the planner profile allocates 12,000 characters, and the researcher profile allocates 8,000 characters.

# Skill loading before /gsd:execute-phase 3
# Phase 3: "Build authentication module"

Scanning .claude/commands/:
  - git-commit-helper.md (relevance: 0.82)
  - react-patterns.md (relevance: 0.91)
  - test-before-commit.md (relevance: 0.88)
  - deployment-checklist.md (relevance: 0.31)

Scanning ~/.claude/commands/:
  - git-commit-helper.md (relevance: 0.79) -- CONFLICT, project-level wins
  - typescript-conventions.md (relevance: 0.85)

After scoring and budget (executor profile: 20,000 chars):
  LOADED: react-patterns.md (4,200 chars)
  LOADED: test-before-commit.md (3,100 chars)
  LOADED: typescript-conventions.md (2,800 chars)
  LOADED: git-commit-helper.md (2,600 chars, project-level)
  Budget used: 12,700 / 20,000 chars
  DEFERRED: deployment-checklist.md (below relevance threshold)

GSD Reference Injection

GSD Reference Injection (src/detection/gsd-reference.ts, introduced in v1.12) addresses a traceability problem. The reference injection system reads the .planning/ directory during skill generation and embeds three types of contextual data: phase goals, requirement IDs (formatted as REQ-xxx), and related file paths.

# Skill generated during Phase 3 execution
# Phase 3: "Build authentication module"

Generated skill: auth-test-patterns.md
Injected references:
  phase_context:
    phase: 3
    name: "Build authentication module"
    goals:
      - "JWT token validation for all API routes"
      - "Role-based access control middleware"
  requirement_ids:
    - REQ-012: "All API endpoints must require authentication"
    - REQ-015: "Role-based access control for admin functions"
  related_files:
    - src/middleware/auth.ts
    - src/middleware/rbac.ts
    - tests/auth.test.ts

Dashboard Generation

The Dashboard Generation system (desktop/src/dashboard/, introduced in v1.13) produces six HTML dashboard pages from the data stored in the .planning/ directory.

• Index (Project Overview) — Top-level summary showing the active milestone, current phase, overall progress percentage.
• Requirements — Tracking view of all REQ-xxx entries showing which have been addressed.
• Roadmap — Phase-by-phase status view derived from ROADMAP.md.
• Milestones — Completion tracking showing milestone-level progress.
• State (Session Memory) — View of STATE.md contents.
• Console (Command Interface) — Interactive command interface for issuing GSD commands.

Phase Transition Hooks

Hooks run after the phase completes, not during. If a hook fails, the failure is logged but does not roll back the phase transition.

# Regenerate dashboards manually
skill-creator invoke gsd-dashboard

# Serve dashboards outside GSD-OS
node serve-dashboard.mjs
# Dashboard available at http://localhost:3000

Usage Examples

# 1. User provides natural language intent
User: "Let's build phase 4"

# 2. Orchestrator classifies intent
Stage 1 (Exact): "build phase 4" -> exact match: /gsd:execute-phase 4
Result: /gsd:execute-phase 4 (confidence: 1.0)

# 3. Phase Skill Loader activates before execution
Loading skills for phase 4: "Implement user dashboard"
  LOADED: react-patterns.md (relevance: 0.94)
  LOADED: test-before-commit.md (relevance: 0.87)
  LOADED: dashboard-layout.md (relevance: 0.92)
  Budget: 9,800 / 20,000 chars (executor profile)

# 4. Execution proceeds with loaded skills
# 5. New pattern detected during execution
# 6. Reference Injection embeds context in generated skill
# 7. Dashboard regenerates to reflect phase progress

# User provides ambiguous request
User: "I need to look at what happened"

Stage 1 (Exact): No match
Stage 2 (Lifecycle): phase 5 completed but not verified
  Candidates: progress, verify-work, discuss-phase
Stage 3 (Bayesian): No winner above 0.8 threshold
Stage 4 (Semantic): No clear winner
Stage 5 (Confidence Resolution):
  "I'm not certain what you'd like to do. Did you mean:
   1. /gsd:verify-work 5 (71% confidence)
   2. /gsd:progress (68% confidence)
  Which would you prefer?"

# Phase execution with tight budget (planner profile)
/gsd:plan-phase 6

Skill loading (planner profile: 12,000 char budget):
  LOADED: planning-patterns.md (3,400 chars, relevance: 0.96)
  LOADED: requirement-tracing.md (2,900 chars, relevance: 0.91)
  LOADED: task-decomposition.md (3,200 chars, relevance: 0.88)
  Budget used: 9,500 / 12,000 chars
  DEFERRED: git-commit-helper.md (2,800 chars, would exceed budget)
  DEFERRED: test-patterns.md (3,100 chars, low relevance: 0.42)

Note: 2 skills deferred due to budget constraints.

# Recommended .gitignore entries for .planning/
.planning/patterns/
.planning/staging/
.planning/console/

# Force full dashboard regeneration
skill-creator invoke gsd-dashboard --force

# Verify dashboard files exist
ls desktop/src/dashboard/generated/

# Serve dashboards for browser access
node serve-dashboard.mjs --port 3000

{
  "integration": {
    "session_observation": true,
    "skill_loading": true,
    "passive_monitoring": true,
    "dashboard_generation": true
  }
}

# Backup the full .planning/ directory:
tar czf planning-backup-$(date +%Y%m%d).tar.gz .planning/

# Restore from backup:
tar xzf planning-backup-20260224.tar.gz

# Force dashboard regeneration after restore:
skill-creator invoke gsd-dashboard --force

Troubleshooting

Orchestrator routes to the wrong command

Check the confidence threshold in .planning/skill-creator.json. Also verify that ROADMAP.md and STATE.md accurately reflect the current project state.

Skills not loading before phase execution

Verify that skill_loading is set to true in .planning/skill-creator.json. Check that skills exist in .claude/commands/ or ~/.claude/commands/.

Dashboard shows stale data

Run skill-creator invoke gsd-dashboard --force to regenerate all dashboard pages.

Reference injection missing from generated skills

Verify that REQUIREMENTS.md exists and contains properly formatted REQ-xxx entries.

Token budget exceeded during phase execution

Increase the budget for the relevant profile in .planning/skill-creator.json or remove low-value skills.

Integration subsystem appears inactive

Verify that .planning/skill-creator.json exists and contains the integration section with feature flags set to true. The integration subsystems check for the presence of ROADMAP.md as a signal that GSD is properly initialized.

Related Capabilities