Domain: GSD — Function Reference

GSD (Get Shit Done) is the spec-driven development methodology domain. It owns phase planning, execution leases, agent spawn orchestration, skill registry, state key-value store, and evolution/rollback of project state. State is persisted as JSON at data/state/gsd-state.json (atomic write via temp-rename).

MCP Tools Exposed

Tool Name Description Input Schema Returns
gsd_vitals Get GSD command vitals — health, phase, active leases command?: string Markdown text with health, phase, lease count, objective
gsd_plan Generate PLAN.md template for a phase; optionally enqueue spawn flow phase: string (required), context?, auto_spawn?, skip_research?, skip_verify?, has_research? Markdown plan text + optional spawn flow summary
gsd_discuss Generate discussion context for a phase phase: string (required), topic? Markdown discussion string
gsd_state Manage GSD key-value state (get/set/list/delete) action: get\|set\|list\|delete (required), keyPath?, value? JSON string or plain text
gsd_validate Validate content against GSD doctrine content: string (required), type?: plan\|project\|requirements “DOCTRINE VALIDATED” or violation list
gsd_lease Manage execution leases action: issue\|return\|list (required), taskId?, scope?, leaseId?, result? Markdown lease info or list
gsd_dash Generate GSD dashboard format?: text\|json Dashboard text or JSON
gsd_evolve Evolution H12 — detect, apply, rollback, report refinements action: detect\|apply\|rollback\|report (required), scope?, candidateId?, force? Markdown evolution output
gsd_agent Manage agent spawn rules, plans, queue action: rules\|set_rule\|plan\|enqueue\|queue\|complete\|history (required), intent?, options?, rule?, status?, spawnId?, completionStatus?, note?, limit? JSON object
gsd_skill Manage skill registry and agent assignments action: list\|register\|bind\|unbind\|recommend (required), skillId?, title?, description?, tags?, agentId?, intent?, options? JSON object

Core Functions

initialize()

Purpose: Initialize GSD domain — loads persistent state from disk. Parameters: none Returns: Promise<true> Side effects: Populates stateCache in-memory, rehydrates activeLeases Map from non-expired persisted leases. Notes for rewrite: Must be called before any tool handler. Gate tool calls on Promise resolution.

syncProjectBinding(projectName, binding)

Purpose: Set or update roadmap↔GSD project binding metadata. Parameters: projectName: string, binding: { roadmapId?, pace?, projectPath? } Returns: { projectName, roadmapId, pace, projectPath, lastSyncedAt } Side effects: Writes to stateCache.bindings, calls saveState().

getProjectBinding(projectName)

Purpose: Retrieve stored binding for a project. Parameters: projectName: string Returns: Binding object or null.

removeProjectBinding(projectName)

Purpose: Delete a project binding. Parameters: projectName: string Returns: boolean (true if removed).

getBindingSummary()

Purpose: Return summary of all project bindings. Returns: { totalBindings, withRoadmap, withoutRoadmap, bindings[] }

resolveAgentSpawnPlan(intent, options)

Purpose: Build a spawn plan for a given intent using stored spawn rules. Applies option-based overrides (skipResearch, skipVerify, etc.). Parameters: intent: string, options: { skipResearch?, skipVerify?, hasResearch?, planFix? } Returns: { intent, before[], beforeParallel[], main[], after[], afterParallel[], notes, options, availableAgents[] } Notes for rewrite: This is the core plan-resolution logic; preserve stage-filtering rules for each intent.

queueAgentSpawnPlan(intent, options, source)

Purpose: Resolve spawn plan and push all flattened steps onto the spawn queue. Records a history event. Parameters: intent: string, options: object, source: { sourceTool? } Returns: { flowId, plan, queueItems[] } Side effects: Mutates stateCache.agentSystem.spawn.queue and .history; calls saveState().

listSpawnQueue(status)

Purpose: Return spawn queue items, optionally filtered by status. Parameters: status?: string Returns: Array of queue item objects.

completeSpawnQueueItem(spawnId, status, note)

Purpose: Mark a spawn queue item as completed/failed/skipped. Parameters: spawnId: string, status: completed|failed|skipped, note: string Returns: The updated item, or null if not found.

listSpawnHistory(limit)

Purpose: Return last N spawn history events. Parameters: limit: number (default 50, max 200) Returns: Array of history event objects.

registerSkill(skillId, payload)

Purpose: Register or update a skill in the registry. Parameters: skillId: string, payload: { title?, description?, tags? } Returns: { skillId, title, description, tags, createdAt, updatedAt }

bindSkillToAgent(agentId, skillId)

Purpose: Add a skill assignment to an agent. Parameters: agentId: string, skillId: string Returns: { agentId, skillIds[] } — must be a registered skill.

unbindSkillFromAgent(agentId, skillId)

Purpose: Remove a skill assignment from an agent. Parameters: agentId: string, skillId: string Returns: { agentId, skillIds[] }

listSkillMatrix(agentId)

Purpose: Show registry and per-agent skill assignments. Parameters: agentId?: string (if omitted, shows all agents) Returns: { registry, agents[{ agentId, skillIds[], skills[] }] }

recommendSkillsForIntent(intent, options)

Purpose: Flatten spawn plan for intent and return skills assigned to each agent in plan order. Parameters: intent: string, options: object Returns: { intent, agents[], skillIds[], skills[] }

setSpawnRule(intent, rule)

Purpose: Set or override a spawn rule for a given intent. Parameters: intent: string, rule: { before?, beforeParallel?, main?, after?, afterParallel?, notes? } Returns: { intent, rule }. Records history event.

getStateValue(keyPath)

Purpose: Read a value from stateCache by dot-notation path. Parameters: keyPath: string (e.g., "project.currentPhase") Returns: The value at that path, or undefined. Notes for rewrite: Segments validated against SAFE_KEY_PATH_PART_REGEX; reserved segments rejected.

setStateValue(keyPath, value)

Purpose: Write a value into stateCache by dot-notation path; creates intermediate objects as needed. Parameters: keyPath: string, value: any Returns: true Side effects: Calls saveState().

deleteStateValue(keyPath)

Purpose: Delete a leaf key from stateCache. Parameters: keyPath: string Returns: boolean

getCommandVitals(commandId)

Purpose: Load a GSD command .md file and parse its sections. Falls back to synthetic vitals if file not found. Parameters: commandId: string Returns: { command, sections: { objective, context, process, constraints, tasks, successChecks }, state: { phase, activeLeases, status }, health, synthetic? }

createLease(taskId, scope)

Purpose: Issue a timed execution lease for a task. Parameters: taskId: string, scope: string[] Returns: { leaseId, taskId, scope, issuedAt, expiresAt } Side effects: Adds to activeLeases Map and stateCache.leases, calls saveState(). Notes for rewrite: LEASE_DURATION_MS constant controls TTL.

returnLease(leaseId, result)

Purpose: Mark an active lease as returned. Parameters: leaseId: string, result: string (default "completed") Returns: boolean

listActiveLeases()

Purpose: Return all currently active (non-expired, non-returned) leases. Returns: Array of lease objects.

generatePlan(phase, context)

Purpose: Generate a PLAN.md template for a given phase; writes to disk. Parameters: phase: string|number, context?: string Returns: Plan markdown string (also written to PLANNING_ROOT/PLAN-phase-N.md).

generateDiscussion(phase, topic)

Purpose: Build a discussion prompt string for a phase. Parameters: phase: string|number, topic?: string Returns: Discussion markdown string.

validateContent(content, type)

Purpose: Check that content contains all required GSD doctrine sections. Parameters: content: string, type: plan|project|requirements Returns: { valid: boolean, missing: string[], type }

generateDashboard(format)

Purpose: Produce a text or JSON dashboard of project/lease/spawn state. Parameters: format: text|json Returns: Dashboard string.

detectEvolution(scope)

Purpose: Scan state for actionable evolution candidates (missing plans, stale leases, stale project). Parameters: scope: all|workflow|doctrine Returns: Array of { id, scope, confidence, description, action } candidates.

applyEvolution(candidateId, force)

Purpose: Execute the action for a detected candidate. Records rollback info. Parameters: candidateId: string, force?: boolean Returns: { success, candidateId, actionId?, message, recommendation? } Side effects: May write files, return leases, create directories.

rollbackEvolution(candidateId)

Purpose: Undo the most recent applied evolution action for a candidate. Parameters: candidateId: string Returns: { success, candidateId, actionId, message }

getStats()

Purpose: Return domain health metrics. Returns: { currentPhase, activeLeases, totalLeases, activeSpawnItems, totalSpawnItems, skillsRegistered, status }

listResources()

Purpose: Enumerate MCP resources: commands, agents, skills, spawn rules. Returns: Promise<Array<{ uri, name, mimeType, description }>>

readResource(uri)

Purpose: Read the content of a GSD MCP resource by URI. Parameters: uri: string (scheme: gsd://commands|agents|skills|spawn-rules/<id>) Returns: { id, category, content } (content capped at RESOURCE_CONTENT_LIMIT).

handleTool(name, rawArgs)

Purpose: Central dispatch for all GSD MCP tool calls after validation. Parameters: name: string, rawArgs: object Returns: Promise<string|object|null> (null means tool not handled here).

Database Operations

Operation Query Pattern Tables Used
None directly All state via JSON file (data/state/gsd-state.json) —

GSD domain does NOT use SQLite. All persistence is a single JSON file written atomically.

Key Algorithms

Atomic Write (atomicWriteSync) 

write data to tmp file (filePath + .tmp-{pid})
  on success: rename(tmp, filePath)
  on failure: unlink(tmp), rethrow

State Pruning (saveState) 

prune stateCache.leases: keep all active + last MAX_RETAINED_LEASES returned
prune spawn.queue: keep all pending + last (MAX_SPAWN_QUEUE_ENTRIES - pendingCount) closed
prune spawn.history: keep last MAX_SPAWN_HISTORY_ENTRIES
then atomicWriteSync(STATE_FILE, JSON)

Spawn Plan Flattening (flattenSpawnPlan) 

cursor = 1
for agent in plan.before:   push { order: cursor++, stage: before, mode: sequential }
for agent in plan.beforeParallel: push { order: cursor, stage: before, mode: parallel }; cursor++
for agent in plan.main:     push { order: cursor++, stage: main, mode: sequential }
for agent in plan.after:    push { order: cursor++, stage: after, mode: sequential }
for agent in plan.afterParallel: push { order: cursor, stage: after, mode: parallel }; cursor++

Option-Based Stage Skipping (shouldSkipByOption) 

intent=plan_phase  + stage=before + skipResearch|hasResearch → skip before/beforeParallel
intent=plan_phase  + stage=after  + skipVerify              → skip after/afterParallel
intent=execute_phase + stage=after + skipVerify             → skip after/afterParallel
intent=debug_issue + stage=after  + planFix=false           → skip after/afterParallel

Dot-Path Key Validation 

segments = keyPath.split(".")
each segment must match SAFE_KEY_PATH_PART_REGEX and not be in RESERVED_KEY_PATH_PARTS
traversal: reduce through stateCache object

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.