taskgraph_ts/docs/sdd_process.md

Spec-Driven Development Process

Overview

This document defines the SDD process for the alk.dev project. It leverages:

• Operation registry + call protocol for typed, composable tool invocation
• Hub coordination operations (coord.spawn, coord.status, coord.message, etc.) for parallel worktree/session orchestration
• OpenCode CLI as the agent execution environment (via the open-coordinator plugin as stopgap, transitioning to native hub operations)

Core Principles

1. Specification First: Invest in architecture before implementation
2. Roles as Modes: Same agent adopts different behavioral modes
3. Flexible Self: Agents can implement, self-review, and fix objectively
4. Task-Driven: Structured task graphs with dependency analysis
5. Safe Exit: Always have a way to unblock progress when stuck
6. Categorical Estimates: Use risk/scope/impact categories, not time estimates. These are structurally important — upstream failures multiply downstream damage regardless of developer type (human or LLM). See the cost-benefit framework.

Workflow Phases

Phase 0: Exploration (Conditional)

When: Requirements unclear, multiple approaches to evaluate, or hard problems need investigation.

Process:

1. Capture vision and guiding principles
2. Research Specialist investigates options (docs/research/ or external)
3. POC Specialist validates promising approaches (.worktrees/research/)
4. Document learnings
5. Converge on recommended approach

Output: Clear understanding of WHAT to build and WHY, with validated approaches

Phase 1: Architecture

Objective: Produce comprehensive, committed architecture specification.

Process:

1. Architect creates modular architecture docs in docs/architecture/ (Draft status)
2. Architecture Review validates for ambiguities, risks
3. Iterate until zero critical issues
4. Transition to Stable status

Output: Stable architecture documents ready for decomposition

Phase 2: Decomposition

Objective: Break architecture into atomic, dependency-ordered tasks.

Process:

1. Decomposer analyzes architecture
2. Creates tasks (markdown files in tasks/)
3. Establishes dependencies between tasks
4. Validates structure (no cycles, logical ordering)
5. Identifies review injection points

Output: Well-structured task graph in tasks/ directory

Phase 3: Implementation

Objective: Execute tasks in dependency order with verification.

Process:

1. Coordinator identifies parallelizable work
2. Coordinator spawns worktrees + sessions (via worktree_make swarm or hub coord.spawn when available)
   • Feature work: .worktrees/feat/<task-id>/ → Implementation Specialist
   • Research POCs: .worktrees/research/<task-id>/ → POC Specialist
3. Coordinator injects task context into each session
4. Agents execute tasks with self-verification
5. On completion: update task status, commit to worktree branch
6. On blocker: Safe Exit protocol, create blocker task
7. Merge worktrees back to main when complete

Output: Completed, verified implementation

Phase 4: Review & Finalization

Objective: Validate quality and readiness.

Process:

1. Code review at injected checkpoints
2. Final integration testing
3. Architecture sync check
4. Deployment preparation

Output: Production-ready codebase

Roles

Primary Roles

1. Architect

Responsibility: Create and maintain architecture specifications.

Mode: Primary (interactive with user)

Tools:

• Read, Write, Edit, Glob, Grep
• webSearch (research patterns, best practices)

Key Behaviors:

• Focus on WHAT and WHY, never HOW
• Document decisions with ADR format
• Redirect exploration work to Research Specialist
• Iterate based on review feedback

Deliverables:

• Modular architecture docs in docs/architecture/
• Component-specific documents

---

2. Decomposer

Responsibility: Transform architecture into atomic task graph.

Mode: Primary (interactive with user for approval)

Tools:

• Read, Glob, Grep

Key Behaviors:

• Decompose to atomic tasks (single objective, clear acceptance criteria)
• Establish logical dependencies
• Validate structure (no cycles, logical ordering)
• Inject review tasks at critical points

Deliverables:

• Task files in tasks/ directory
• Dependency graph validated

---

3. Coordinator

Responsibility: Orchestrate parallel task execution across worktrees and sessions.

Mode: Primary (manages worktrees and agent sessions)

Current (stopgap): Uses the open-coordinator opencode plugin for worktree management + session messaging. State tracked in ~/.config/opencode/open-coordinator/state.json.

Future: Uses hub coordination operations (coord.spawn, coord.status, coord.message, coord.abort) via the call protocol. State persisted in Postgres mappings table. Spoke runners replace the in-process plugin model.

Tools:

• worktree_mode, worktree_make (swarm), worktree_cleanup, worktree_overview
• Bash (opencode CLI for session interaction)
• Read (monitor task files)

Key Behaviors:

• Identify parallelizable task groups
• Spawn worktrees + sessions via worktree_make swarm (current) or hub.call("coord.spawn", ...) (future)
• Inject task context into sessions
• Monitor progress
• Handle blocked tasks (escalate or reassign)
• Merge completed worktrees

Deliverables:

• Coordinated parallel execution
• Blocked task escalation
• Merged branches

---

4. Implementation Specialist

Responsibility: Execute atomic tasks with self-verification.

Mode: Primary (works on assigned task in worktree)

Tools:

• Read, Write, Edit, Glob, Grep, Bash
• webSearch (documentation lookup)

Key Behaviors:

• Load task context (architecture, dependencies)
• Propose plan before implementing
• Implement following architecture constraints
• Self-verify against acceptance criteria
• Use Safe Exit when blocked
• Commit to worktree branch

Deliverables:

• Completed task implementation
• Tests passing
• Committed changes in worktree

---

Reviewer Roles

5. Architecture Reviewer

Responsibility: Validate architecture for ambiguities and risks.

Mode: Subagent (invoked by Architect)

Tools:

• Read, Grep

Key Behaviors:

• Check for undefined terms
• Identify missing trade-off documentation
• Validate quality attribute coverage
• Flag ambiguities that could cause implementation issues

---

6. Code Reviewer

Responsibility: Review code quality at checkpoints.

Mode: Subagent (invoked by Coordinator or as task)

Tools:

• Read, Grep, Bash (lint, test)

Key Behaviors:

• Check adherence to architecture
• Validate patterns and conventions
• Run linters and tests
• Identify security/performance concerns

---

7. Research Specialist

Responsibility: Research documentation, libraries, best practices.

Mode: Subagent (invoked by any role)

Tools:

• Read, Write, Glob
• webSearch (primary research tool)

Key Behaviors:

• Find and summarize documentation
• Evaluate library alternatives
• Document findings

---

8. POC Specialist

Responsibility: Create proof-of-concepts to validate technical approaches before production implementation.

Mode: Primary (works in isolated research worktree)

Worktree Location: .worktrees/research/<task-id>/

Tools:

• Read, Write, Edit, Glob, Grep, Bash
• webSearch (implementation references)

Key Behaviors:

• Create minimal POCs to validate hypotheses
• Work in isolated research worktrees
• Document findings and recommendations
• Timebox strictly - abandon if taking too long
• Be honest about limitations and blockers

When Invoked:

• After Research Specialist completes initial research
• When a technical approach needs validation before commitment
• When integration complexity or performance is uncertain

Deliverables:

• Working POC code
• Findings document with recommendation (proceed/pivot/block)
• Updated research task with results

---

Task File Format

Tasks are markdown files stored in tasks/. Since they're in the repo, they're automatically available in worktrees.

---
id: auth-setup
name: Setup Authentication
status: pending
depends_on: []
scope: moderate
risk: medium
impact: component
level: implementation
---

## Description

Implement OAuth2 authentication with provider abstraction.

## Acceptance Criteria

- [ ] OAuth2 flow works with Google provider
- [ ] Tokens stored securely
- [ ] Session management implemented

## References

- docs/architecture/auth.md

## Notes

> Agent fills this during implementation. Document any decisions,
> deviations from architecture, or relevant context discovered.

## Summary

> Agent fills this on completion. Brief description of what was
> implemented, files changed, and any follow-up needed.

Categorical Estimates

These fields are structurally important, not optional metadata. They power taskgraph decompose, risk-path, critical, and bottleneck — commands that reveal structural problems in the task graph. A task missing scope, risk, impact, or level is a red flag indicating incomplete decomposition. See the cost-benefit framework for the reasoning.

Scope	Description	Example
single	One function, one file	Add validation helper
narrow	One component, few files	Implement auth middleware
moderate	Feature, multiple components	Build user API endpoints
broad	Multi-component feature	Implement OAuth flow
system	Cross-cutting changes	Database migration

Risk	Failure Likelihood
trivial	Nearly impossible to fail
low	Standard implementation
medium	Some uncertainty
high	Significant unknowns
critical	High chance of failure

Task Lifecycle

Status values: pending → in-progress → completed | blocked | failed

On completion, the agent:

1. Updates status: completed
2. Fills in ## Summary section
3. Commits changes to worktree branch

Safe Exit Protocol

When a task becomes untendable:

Criteria

Hard Criteria (automatic):

• Same task fails verification 3+ times
• Task attempts exceed 5+ total

Soft Criteria (agent judgment):

• Ambiguous architecture
• Missing dependencies
• External library incompatibility
• Scope creep detected

Process

1. Create blocker task
2. Update original task: status: blocked, add blocker to depends_on
3. Document in task notes
4. Notify coordinator

Review Injection

Use graph analysis to determine where reviews should happen:

Analysis	Injection Point
Parallel groups	Review before groups merge
Bottleneck tasks	Review before critical path
High-risk tasks	Review before proceeding
Critical path	Review before critical tasks

Coordinator Implementation

Current (Stopgap)

The Coordinator uses the open-coordinator opencode plugin for worktree management and session messaging. This is a fork of open-trees with added session monitoring and messaging capabilities.

1. Identify parallel work
   Read task files → groups of independent tasks

2. Spawn worktrees + sessions
   worktree_make swarm → creates .worktrees/feat/<branch>

3. Inject task context
   opencode run -s <session-id> --agent implementation-specialist "Your task: <task-id>"

4. Monitor progress
   worktree_overview dashboard → status of all worktrees

5. Handle completion
   - Agent commits to worktree branch
   - Coordinator merges back to main

6. Handle blockers
   - Agent uses Safe Exit
   - Coordinator escalates or reassigns

State tracked at:

~/.config/opencode/open-coordinator/state.json

Each entry maps:

• worktreePath → filesystem location
• branch → git branch name
• sessionID → opencode session ID
• createdAt → timestamp

Future (Hub Operations)

Once the hub is operational, coordination uses native operations:

1. Identify parallel work
   hub.call("coord.spawn", { task, branch, ... })

2. Monitor progress
   hub.call("coord.status", { parentSessionId })

3. Message sessions
   hub.call("coord.message", { sessionId, message })

4. Handle aborts
   hub.call("coord.abort", { sessionId })

State moves from state.json to Postgres mappings table. The open-coordinator plugin becomes unnecessary — the hub provides the same capabilities as server-side operations accessible from any environment.

Document Structure

.opencode/
├── agents/
│   ├── architect.md
│   ├── decomposer.md
│   ├── coordinator.md
│   ├── implementation-specialist.md
│   ├── poc-specialist.md
│   ├── code-reviewer.md
│   ├── architecture-reviewer.md
│   └── research-specialist.md

docs/
├── architecture/
│   ├── hub-architecture.md
│   ├── call-graph.md
│   ├── spoke-runner.md
│   ├── operations.md
│   ├── mcp-server.md
│   ├── coordination.md
│   ├── storage/                  # Decomposed: README.md, table-reference.md, per-domain schema files, tasks.md
│   │   └── (ADRs in decisions/)
│   ├── agent-sessions.md
│   ├── pubsub-redis.md
│   └── infrastructure.md
├── sdd_process.md             # This document
└── decisions/                 # ADRs

tasks/
├── architecture/
│   └── auth-design.md
├── implementation/
│   ├── storage/
│   │   ├── tasks-table.md
│   │   └── migrations.md
│   └── auth/
│       └── oauth-flow.md
└── (taskgraph validates & analyzes dependency graph)

.worktrees/                    # Created by coordinator
├── feat/
│   ├── api-auth/
│   └── api-users/
└── research/
    └── storage-abstraction/

Agent Role Specs

Agent definitions are in .opencode/agents/:

• architect.md - Creates architecture specifications
• decomposer.md - Transforms architecture to task graph
• coordinator.md - Orchestrates parallel execution
• implementation-specialist.md - Executes tasks with self-verification
• poc-specialist.md - Creates proof-of-concepts for validation
• code-reviewer.md - Reviews code quality at checkpoints
• architecture-reviewer.md - Validates architecture specs
• research-specialist.md - Researches and documents findings

Use with opencode CLI:

# Spawn coordinator in interactive mode
opencode --agent coordinator

# Send task to implementation specialist
opencode run -s <session-id> --agent implementation-specialist "Your task: auth-setup"

Evolution

This document should evolve with the project:

1. Refine roles based on actual usage
2. Adjust task templates based on what works
3. Document coordinator patterns as they emerge
4. Capture learnings in after-action reviews