spec-workflow

OpenSpec Workflow Orchestration

Spec-driven development protocol for coordinating multi-agent workflows.

UUID Enforcement

CRITICAL: The conversation_id MUST always be a UUID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). NEVER use descriptive names, slugs, or human-readable strings. If no UUID is available, generate one with uuidgen or python3 -c "import uuid; print(uuid.uuid4())". Self-check: does the conversation_id match the pattern [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}? If not, STOP and use a real UUID.

Directory Structure

.scaffolding/conversations/{conversation_id}/specs/
  proposal.md   -- WHY + WHAT (analyst)
  design.md     -- WHAT + HOW (architect)
  tasks.md      -- checklist (architect)

Status Lifecycle

Tracked in .scaffolding/conversations/{conversation_id}/context.json:

Status	Meaning	Transition
exploring	Research phase	-> drafting when proposal done
drafting	Design + tasks	-> implementing when tasks done
implementing	Code changes	-> reviewing when tasks complete
reviewing	Verification	-> complete when verified
complete	Done	-> archived on request
archived	Historical	Terminal state

Agent Routing in /workflow

Phase	Agent	Reads	Writes	Gate
1. Analyze	analyst	requirements	proposal.md	proposal written
1b. Research (conditional)	researcher	requirements	ResearchPack	score >= 80
2. Design	architect	proposal.md	design.md, tasks.md	score >= 85
3. Apply	developer	tasks.md, design.md	source code	validation passes
4. Verify	reviewer	design.md, tasks.md	review report	no criticals

When Researcher Is Needed

Analyst flags need for research in proposal.md. Researcher is invoked ONLY when the task involves:

• New external API integration (e.g., Stripe, Twilio)
• Unfamiliar library not yet in the project
• Best practices requiring current internet research
• Version-specific documentation for upgrades/migrations

Analyst writes proposal directly (no researcher) for:

• Internal codebase refactoring
• UI/styling changes
• Bug fixes with known root cause
• Configuration changes
• Features using only existing project dependencies

When to Create vs Skip Specs

Task Type	Use Specs?	Reason
New feature	Yes	Needs design, multi-file
Architecture change	Yes	Needs decisions documented
Multi-agent workflow	Yes	Needs coordination
Bug fix (simple)	No	Direct to developer
Typo / config tweak	No	Direct to developer
Single-file refactor	No	Direct to developer

Orchestration Steps

1. Obtain conversation_id UUID: From prompt context or generate via uuidgen. MUST be a UUID, never a descriptive name.
2. Create specs directory: mkdir -p .scaffolding/conversations/{conversation_id}/specs/
3. Set specs_path: .scaffolding/conversations/{conversation_id}/specs/
4. Analyst writes proposal.md (requirements, scope, impact, feasibility)
5. If research needed: analyst flags in proposal.md, researcher is invoked (score >= 80)
6. Architect writes design.md + tasks.md (incorporating proposal.md and ResearchPack if available)
7. Pass specs_path in every agent delegation prompt
8. Update context.json status after each phase transition
9. Gate enforcement: Block next phase if quality gate fails

Context JSON Schema

{
  "conversation_id": "abc-123",
  "status": "implementing",
  "created_at": "2026-01-15T10:00:00Z",
  "description": "Feature description",
  "agents_involved": ["architect", "developer"]
}

Schema Reference

Custom schema: .scaffolding/openspec/schemas/scaffolding-workflow/schema.yaml Config: .scaffolding/openspec/config.yaml Templates: .scaffolding/openspec/schemas/scaffolding-workflow/templates/