# Design: Speckit Integration into hyh

**Date**: 2025-12-29
**Status**: Approved
**Branch**: feature/speckit-integration

## Overview

Transform hyh from a low-level task orchestrator into a complete spec-driven development workflow tool. The speckit workflow from test-prompt becomes native to hyh, shipped as a Claude Code plugin with built-in git worktree management.

## Architecture

### Dual-Natured Tool

1. **Python Package** (`pip install hyh`)
   - Daemon with Unix socket RPC (per-worktree)
   - State management, task coordination, git mutex
   - Git worktree management (DHH-style)
   - `hyh init` scaffolds Claude Code plugin

2. **Claude Code Plugin** (generated by `hyh init`)
   - Commands: `/hyh`, `/hyh:help`
   - Hooks: SessionStart shows workflow state
   - Skills: spec-driven development guidance

### Worktree Pattern (DHH-style)

```
~/projects/
├── myapp/                      # Main repo (hyh init here)
├── myapp--42-user-auth/        # Feature worktree
├── myapp--43-payment-flow/     # Another feature
└── myapp--44-dashboard/        # Parallel work
```

## Command Structure

### Main Entry: `/hyh` with `$ARGUMENTS` routing

```
/hyh                        → Detect state, ask what to do
/hyh specify <idea>         → Create worktree + spec
/hyh plan                   → Generate design artifacts + tasks
/hyh implement              → Execute tasks via daemon
/hyh status                 → Show current workflow state
/hyh switch <N>             → Switch to worktree N
/hyh list                   → Show all worktrees
```

### Phase Mapping

| Phase | Includes | Output |
|-------|----------|--------|
| `specify` | specify + clarify | `spec.md` finalized |
| `plan` | plan + tasks + checklist + analyze | All design artifacts |
| `implement` | execute tasks | Working code |

## Package Structure

```
src/hyh/
├── __init__.py
├── client.py                    # CLI entry point (existing + new)
├── daemon.py                    # Unix socket RPC server (existing)
├── state.py                     # Task/WorkflowState structs (existing)
├── plan.py                      # UPDATED: Parse speckit checkbox format
├── worktree.py                  # NEW: Git worktree management
├── templates/                   # Bundled from test-prompt
│   ├── spec-template.md
│   ├── plan-template.md
│   ├── tasks-template.md
│   └── checklist-template.md
├── plugin/                      # Claude Code plugin files
│   ├── plugin.json
│   ├── commands/
│   │   ├── hyh.md
│   │   └── help.md
│   ├── skills/
│   │   └── spec-driven-dev.md
│   └── hooks/
│       └── hooks.json
└── scripts/
    └── ...
```

## CLI Commands

### New Commands

```bash
# Worktree management
hyh worktree create <slug>       # Create ../project--slug/, init specs/
hyh worktree list                # List all feature worktrees
hyh worktree switch <slug>       # Switch to worktree

# Workflow state
hyh workflow init                # Initialize workflow in current worktree
hyh workflow status              # Show phase, progress, next action

# Init
hyh init                         # Scaffold plugin + .hyh/ in main repo
```

### Updated Commands

```bash
hyh plan import --file <path>    # Parse speckit checkbox format
```

## Updated `plan.py` Parser

Parse speckit checkbox format:

```markdown
## Phase 2: User Story 1 - Authentication
- [ ] T005 [P] [US1] Create User model in src/models/user.py
- [ ] T006 [US1] Implement auth service in src/services/auth.py
- [x] T007 [US1] Add login endpoint in src/api/auth.py
```

Extracts:
- `id`: T005, T006, T007
- `status`: pending (`[ ]`) or completed (`[x]`)
- `parallel`: True if `[P]` present
- `user_story`: US1 (optional)
- `description`: "Create User model"
- `file_path`: parsed from description
- `phase`: from heading

Dependencies derived from phases (Phase N depends on Phase N-1).

## Command Flows

### `/hyh specify "user authentication"`

```
1. Parse slug: "user-auth"
2. Get next number: N=42
3. Run: hyh worktree create 42-user-auth
4. Load spec-template.md from .hyh/templates/
5. Fill template, identify [NEEDS CLARIFICATION] markers
6. Ask clarifying questions (max 5, one at a time)
7. Write specs/spec.md
8. Run: hyh workflow init --phase specify
```

### `/hyh plan`

```
1. Verify in worktree, spec.md exists
2. Load spec.md, .hyh/constitution.md (if exists)
3. Generate research.md (resolve unknowns)
4. Generate plan.md (architecture, tech stack)
5. Generate data-model.md, contracts/ (if applicable)
6. Generate tasks.md (speckit checkbox format)
7. Generate checklists/requirements.md
8. Run consistency analysis
9. Run: hyh plan import --file specs/tasks.md
10. Run: hyh workflow status (confirm tasks loaded)
```

### `/hyh implement`

```
1. Run: hyh workflow status (verify tasks exist)
2. Check checklists (ask to proceed if incomplete)
3. Loop:
   a. Run: hyh task claim → get task JSON
   b. If no task: done
   c. Execute task (create/modify files per instructions)
   d. Run: hyh task complete --id <id>
   e. Update specs/tasks.md (mark [x])
   f. Repeat
4. Run: hyh workflow status (show completion)
```

### `/hyh` (guided entry)

```
1. Run: hyh workflow status --json
2. Detect state:
   - No worktree? → "Start new feature?"
   - Has spec, no plan? → "Continue to planning?"
   - Has tasks, incomplete? → "Resume implementation?"
   - All complete? → "All tasks done! Ready to merge."
3. Present options via natural conversation
4. Route to appropriate phase
```

## Plugin Files

### plugin.json

```json
{
  "name": "hyh",
  "description": "Hold Your Horses - spec-driven development workflow",
  "version": "0.2.0",
  "commands": ["./commands/"],
  "skills": ["./skills/"],
  "hooks": "./hooks/hooks.json"
}
```

### hooks/hooks.json

```json
{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "hyh workflow status --quiet"
      }]
    }]
  }
}
```

## File Structure After `hyh init`

### Main Repo

```
.claude/plugins/hyh/
├── plugin.json
├── commands/
│   ├── hyh.md
│   └── help.md
├── skills/
│   └── spec-driven-dev.md
└── hooks/
    └── hooks.json

.hyh/
├── config.json                  # Main branch, next feature #
├── templates/
│   ├── spec-template.md
│   ├── plan-template.md
│   ├── tasks-template.md
│   └── checklist-template.md
└── constitution.md              # Optional
```

### Feature Worktree

```
myapp--42-user-auth/
├── .hyh/
│   └── state.json               # Daemon state
├── specs/
│   ├── spec.md
│   ├── plan.md
│   ├── research.md
│   ├── data-model.md
│   ├── tasks.md
│   ├── contracts/
│   └── checklists/
└── (project files via worktree)
```

## Preserved from test-prompt

| File | Status | Notes |
|------|--------|-------|
| `spec-template.md` | Exact copy | User stories with priorities |
| `plan-template.md` | Exact copy | Constitution check, structure |
| `tasks-template.md` | Exact copy | Checkbox format, phases |
| `checklist-template.md` | Exact copy | "Unit tests for requirements" |
| `constitution.md` | Exact copy | 5 principles, governance |
| `speckit.*.md` logic | Adapted | Merged into `/hyh` commands |

## Implementation Tasks

1. **Update `plan.py`** - Add speckit checkbox format parser
2. **Add `worktree.py`** - DHH-style worktree management
3. **Add workflow commands** - `hyh workflow init/status`
4. **Create plugin files** - Commands adapted from speckit
5. **Add `hyh init`** - Scaffold plugin + templates
6. **Bundle templates** - Include test-prompt templates in package
7. **Write tests** - Parser, worktree, workflow state

## Design Decisions

### Why Plugin Architecture (not embedded)?
- Keeps hyh core focused on infrastructure
- Plugin can evolve independently
- Users can customize commands/templates
- Follows Claude Code ecosystem patterns

### Why DHH-style Worktrees?
- Simple naming: `project--branch`
- Sibling directories, no nesting
- Easy to switch, list, cleanup
- Parallel work without conflicts

### Why Merge Phases?
- Three entry points match mental model (specify/plan/implement)
- Reduces command sprawl
- Natural checkpoints for user review
- Mirrors superpowers pattern

### Why Not `/hyh finish`?
- Merging is developer's domain
- Teams have different workflows (PR, direct merge, squash)
- hyh orchestrates development, not git workflow
