ClaudeCraft Workflow Skill

Project Context

ClaudeCraft is a TUI-based spec-driven development orchestrator that enables:

• Idea → BRD → PRD → Spec → Tasks → Autonomous Implementation
• Parallel agent execution (max 6 concurrent)
• Git worktree isolation for all implementation work
• Real-time progress tracking in TUI
• Database-driven task management

The Happy Path

Complete workflow from idea to implementation:

┌─────────────────────────────────────────────────────────────────────┐
│                        HUMAN INTERACTION                            │
├─────────────────────────────────────────────────────────────────────┤
│  /claudecraft.brd     Interactive BRD creation with research          │
│        ↓                                                            │
│  /claudecraft.prd     Interactive PRD creation (from BRD or scratch)  │
│        ↓                                                            │
│  /claudecraft.specify Generate technical spec [APPROVAL REQUIRED]     │
├─────────────────────────────────────────────────────────────────────┤
│                      FULLY AUTONOMOUS                               │
├─────────────────────────────────────────────────────────────────────┤
│  /claudecraft.plan    Create implementation plan                       │
│        ↓                                                            │
│  /claudecraft.tasks   Decompose into database tasks                    │
│        ↓                                                            │
│  /claudecraft.implement Execute with parallel agents                   │
│        ↓                                                            │
│  /claudecraft.qa      Final validation and merge                       │
└─────────────────────────────────────────────────────────────────────┘

Commands Available

Discovery & Requirements (Human Interactive)

• /claudecraft.brd - NEW Guide user through creating a Business Requirements Document
• /claudecraft.prd - NEW Guide user through creating a Product Requirements Document
• /claudecraft.ingest - Import existing BRD/PRD document

Specification (Human Approval Required)

• /claudecraft.specify - Generate specification from requirements

Autonomous Execution

• /claudecraft.plan - Create technical implementation plan
• /claudecraft.tasks - Decompose plan into executable database tasks
• /claudecraft.implement - Execute autonomous implementation
• /claudecraft.qa - Run final QA validation

Project Setup

• /claudecraft.init - Initialize ClaudeCraft project

Key Principles

• constitution.md defines immutable project principles
• All specs live in specs/{spec-id}/
• Implementation happens in isolated git worktrees (.worktrees/)
• Human approval required only for specs, not implementation
• Implementation is fully autonomous after spec approval

Directory Structure

project-root/
├── .claudecraft/
│   ├── constitution.md              # Immutable project principles
│   ├── config.yaml                  # ClaudeCraft configuration
│   ├── claudecraft.db                  # SQLite database
│   ├── specs.jsonl                  # Git-friendly sync
│   └── memory/                      # Cross-session context
├── specs/{spec-id}/
│   ├── brd.md                       # Business Requirements Document
│   ├── prd.md                       # Product Requirements Document
│   ├── spec.md                      # Functional specification
│   ├── plan.md                      # Technical plan
│   ├── research.md                  # Codebase analysis
│   ├── validation.md                # Human approval record
│   ├── implementation/              # Task execution logs
│   └── qa/                          # QA reports
├── .claude/
│   ├── agents/                      # Sub-agent definitions
│   ├── commands/                    # Slash commands
│   ├── skills/claudecraft/             # This skill
│   └── hooks/                       # Lifecycle hooks
└── .worktrees/                      # Isolated development

Workflow Stages

1. Business Requirements (Human + AI) - Create BRD with /claudecraft.brd
2. Product Requirements (Human + AI) - Create PRD with /claudecraft.prd
3. Specification (Human + AI) [HUMAN GATE] - Generate and approve spec.md
4. Planning (Autonomous) - Create technical plan.md
5. Task Decomposition (Autonomous) - Create tasks in database
6. Implementation (Autonomous) - Parallel agent execution
7. Quality Assurance (Autonomous) - Final QA and merge

Sub-Agent Delegation

• claudecraft-architect: Planning, design decisions, task decomposition
• claudecraft-coder: Implementation of tasks
• claudecraft-reviewer: Code review against spec and standards
• claudecraft-tester: Test creation and execution
• claudecraft-qa: Final validation and sign-off

TUI Features

Launch with claudecraft tui:

• Specs Panel: View all specifications and their status
• Spec Editor: View/edit spec documents (BRD, PRD, spec, plan)
• Dependency Graph: Visualize task dependencies
• Swimlane Board (press 't'): Real-time task status across columns
• Agent Panel: Live view of running Claude Code agents

Database Schema

• specs: id, title, status, source_type, metadata
• tasks: id, spec_id, title, status, priority, dependencies, assignee
• execution_logs: task_id, agent_type, action, output, success
• active_agents: task_id, agent_type, slot, pid, started_at

Task Status Flow

TODO → IMPLEMENTING → TESTING → REVIEWING → DONE

Tasks are stored in SQLite database, visible in TUI swimlane board. Use claudecraft list-tasks to see all tasks.

Agent Commands

For TUI integration:

• claudecraft agent-start TASK-ID --type coder - Register active agent
• claudecraft agent-stop --task TASK-ID - Deregister agent
• claudecraft list-agents - View active agents

Best Practices

1. Always reference constitution.md
2. Follow existing codebase patterns
3. Write tests alongside code
4. Work in worktrees, never in main
5. Iterate based on feedback
6. Trust autonomous execution after spec approval