Design & Planning Tools (Stream D)

Stream D contains 7 tools for turning specs into actionable implementation artifacts — schemas, UI contracts, architecture decisions, execution plans, and event contracts.

generate_adr

Generate Architecture Decision Records for a spec.

What it produces: Structured ADR documents covering the decision context, options considered, decision made, and consequences. Format follows MADR (Markdown Architectural Decision Records).

When to use: When a spec involves a significant technology choice, architecture pattern, or trade-off that future developers need to understand.

Prompt: "Generate ADRs for spec SPEC-004 in project proj_abc123"

Example output:

# ADR-001: Use Redis for session storage

## Status: Accepted

## Context
The authentication spec requires session persistence across multiple server instances...

## Decision
Use Redis as the session store...

## Consequences
- Positive: Horizontal scaling without sticky sessions
- Negative: Adds Redis as a required infrastructure dependency

---

design_schema

Design database schema from spec requirements.

What it produces:

• Table definitions with columns, types, and constraints
• Primary and foreign key relationships
• Index suggestions for query performance
• Migration hints
• Schema in multiple dialects (SQL, Prisma, SQLAlchemy, GORM, etc.)

When to use: When a spec involves data persistence and you need a concrete starting point for the database layer.

Prompt: "Design the database schema for spec SPEC-002 in project proj_abc123"

---

define_ui_contract

Define UI component contracts, data flow, and state management.

What it produces:

• Component interface definitions (props, events, slots)
• Data flow diagram (which components own which state)
• State management approach (local, context, store)
• API contract between frontend and backend
• Accessibility requirements

When to use: For any spec that includes a frontend component, form, or user interaction.

Prompt: "Define the UI contract for the login flow in spec SPEC-001 for project proj_abc123"

---

challenge_spec

Stress-test a spec for failures, concurrency, scale, and edge cases.

What it checks:

• Concurrency issues (race conditions, deadlocks)
• Scale breaking points (what happens at 10x, 100x load?)
• Failure modes (what if the database is unavailable?)
• Edge cases not covered by the acceptance criteria
• Security surface area

When to use: For any spec that will run in production with real users. Especially valuable for specs touching payments, authentication, or real-time features.

Prompt: "Challenge spec SPEC-003 for project proj_abc123"

---

generate_execution_plan

Generate a step-by-step PLAN.md for implementing a spec — RED/GREEN/VERIFY cycle with parallelizable steps.

What it produces:

## Phase 1: Foundation (parallel)
- [ ] Step 1a: Create database migration
- [ ] Step 1b: Define TypeScript interfaces
- [ ] Step 1c: Write failing tests (RED)

## Phase 2: Implementation (sequential)
- [ ] Step 2a: Implement repository layer (GREEN)
- [ ] Step 2b: Implement service layer

## Phase 3: Verification
- [ ] Step 3a: Run full test suite (VERIFY)
- [ ] Step 3b: Update spec status to review

When to use: Before implementation begins. The PLAN.md becomes the implementation contract for the AI agent or developer.

Prompt: "Generate an execution plan for spec SPEC-005 in project proj_abc123"

---

generate_orchestration_script

Generate a 3-layer parallel automation script (worktrees + claude -p) for running multiple specs concurrently.

What it produces: A shell script that:

• Creates isolated git worktrees per spec
• Launches claude -p workers in parallel
• Manages resource allocation based on available CPU and RAM
• Monitors worker health and handles failures

When to use: When you need to implement multiple independent specs simultaneously and want maximum parallelism.

Prompt: "Generate an orchestration script for specs SPEC-010, SPEC-011, SPEC-012 in project proj_abc123"

---

event_contracts

Manage event-driven architecture contracts — generate JSON Schema event contracts for producer/consumer validation.

What it produces:

• JSON Schema definitions for each event type
• Producer contract (what the emitter guarantees)
• Consumer contract (what the subscriber expects)
• Versioning strategy
• Backward compatibility notes

When to use: For any spec that involves message queues, event buses (Kafka, RabbitMQ, AWS SQS/SNS, NATS), or webhook integrations.

Prompt: "Define event contracts for the order processing flow in spec SPEC-008 for project proj_abc123"

Example output:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "OrderPlaced",
  "version": "1.0.0",
  "type": "object",
  "required": ["orderId", "customerId", "items", "total", "placedAt"],
  "properties": {
    "orderId": { "type": "string", "format": "uuid" },
    "customerId": { "type": "string", "format": "uuid" },
    "items": { "type": "array", "items": { "$ref": "#/definitions/OrderItem" } },
    "total": { "type": "number", "minimum": 0 },
    "placedAt": { "type": "string", "format": "date-time" }
  }
}