Hub Tdd

---
name: hub-tdd
description: TDD workflow for MCP Hub implementation. Types → Tests (red) → Implementation (green) with git gates.
hooks:
  Stop:
    - hooks:
        - type: command
          command: "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/hub_tdd_stop.sh"
---

# /hub-tdd

Strict TDD workflow for implementing the MCP Hub from ADR-002. Enforces: types first, then tests (must be red), then implementation (must be green), with git commits at every checkpoint.

## Variables

RESUME: $ARGUMENTS (default: auto-detected from .hub-tdd/state.json)

## Module Order (dependency-driven)

| # | Module | Test Count | Depends On |
|---|--------|-----------|------------|
| 0 | hub-types | 0 (pure types) | — |
| 1 | identity | 4 | hub-types |
| 2 | attribution | 3 | hub-types, existing ThoughtData |
| 3 | workspace | 6 | identity |
| 4 | problems | 7 | workspace |
| 5 | proposals | 10 | problems |
| 6 | consensus | 5 | workspace |
| 7 | channels | 9 | problems |
| 8 | proxy | 5 | hub-handler interface |
| 9 | hub-handler | 18 | all modules |
| 10 | integration | 3 | everything |
| **Total** | | **70** | |

## Expected Test Counts Per Module

These counts are authoritative (derived from ADR Section 10 test IDs):

```json
{
  "identity": { "count": 4, "ids": "T-ID-1..4", "files": ["identity.test.ts"] },
  "attribution": { "count": 3, "ids": "T-ATT-1..3", "files": ["attribution.test.ts"] },
  "workspace": { "count": 6, "ids": "T-WS-1..6", "files": ["workspace.test.ts"] },
  "problems": { "count": 7, "ids": "T-PR-1..7", "files": ["problems.test.ts"] },
  "proposals": { "count": 10, "ids": "T-PP-1..10", "files": ["proposals.test.ts"] },
  "consensus": { "count": 5, "ids": "T-CON-1..5", "files": ["consensus.test.ts"] },
  "channels": { "count": 9, "ids": "T-CH-1..5, T-CHSUB-1..4", "files": ["channels.test.ts", "channel-subscription.test.ts"] },
  "proxy": { "count": 5, "ids": "T-PX-1..5", "files": ["proxy.test.ts"] },
  "hub-handler": { "count": 18, "ids": "T-PD-1..3, T-ERR-1..6, T-TERM-1..4, T-ISO-1..4, T-STOR-1..5", "files": ["hub-handler.test.ts", "errors.test.ts", "terminal-state.test.ts", "isolation.test.ts", "storage.test.ts"] },
  "integration": { "count": 3, "ids": "T-INT-1, T-CONC-1..2", "files": ["integration.test.ts", "concurrent.test.ts"] }
}

Module Step Lifecycle

Standard module: pending → types_written → tests_written → tests_red_verified → implemented → tests_green → complete

Exceptions:

• hub-types: pending → types_written → complete (no tests for pure type file)
• integration: pending → tests_written → tests_red_verified → implemented → tests_green → complete (no separate types step)

State File

Location: .hub-tdd/state.json (gitignored, ephemeral)

---

Phase 0: Resume or Initialize

OBJECTIVE: Detect existing state or create fresh run

1. Check if .hub-tdd/state.json exists.

2. IF EXISTS:
   a. Read state.json
   b. Display progress dashboard (see Dashboard section below)
   c. Identify current module and step
   d. Resume from that exact point (jump to the appropriate phase/step)
   e. IMPORTANT: On resume, verify the last gate claim. If state says module X is at
      "tests_red_verified", actually run the tests to confirm they still fail before proceeding.

3. IF NOT EXISTS:
   a. Create .hub-tdd/ directory
   b. Read the ADR: staging/docs/adr/002-mcp-hub-staging-adr.md
   c. Initialize state.json:

      {
        "status": "in_progress",
        "startedAt": "<ISO timestamp>",
        "updatedAt": "<ISO timestamp>",
        "adrPath": "staging/docs/adr/002-mcp-hub-staging-adr.md",
        "phase": "types",
        "modules": {
          "hub-types":    { "step": "pending", "commits": {} },
          "identity":     { "step": "pending", "commits": {} },
          "attribution":  { "step": "pending", "commits": {} },
          "workspace":    { "step": "pending", "commits": {} },
          "problems":     { "step": "pending", "commits": {} },
          "proposals":    { "step": "pending", "commits": {} },
          "consensus":    { "step": "pending", "commits": {} },
          "channels":     { "step": "pending", "commits": {} },
          "proxy":        { "step": "pending", "commits": {} },
          "hub-handler":  { "step": "pending", "commits": {} },
          "integration":  { "step": "pending", "commits": {} }
        },
        "gates": [],
        "testCounts": { "total": 0, "passing": 0, "failing": 0 }
      }

   d. Display module order table
   e. Proceed to Phase 1

Phase 1: Types (module: hub-types)

OBJECTIVE: Write all hub type definitions

SOURCE: ADR Section 1 (Data Model)

1. Read ADR Section 1 for all type definitions:
   - AgentIdentity
   - ThoughtData extension (agentId, agentName)
   - Workspace
   - Problem
   - Proposal
   - Review
   - ConsensusMarker
   - Channel
   - All enums and literal types

2. Write src/hub/hub-types.ts with all interfaces and types.

3. GATE: Type compilation check
   Run: npx tsc --noEmit src/hub/hub-types.ts
   REQUIRED: Must compile with 0 errors.
   If errors: fix and re-run until clean.

4. Update state:
   - modules.hub-types.step = "types_written"

5. COMMIT:
   git add src/hub/hub-types.ts
   git commit -m "feat(hub): add hub type definitions"

6. Record gate:
   {
     "name": "hub-types:complete",
     "passedAt": "<ISO timestamp>",
     "commitSha": "<sha from git rev-parse HEAD>",
     "commitMessage": "feat(hub): add hub type definitions"
   }

7. Update state:
   - modules.hub-types.step = "complete"
   - modules.hub-types.commits.types = "<sha>"
   - phase = "per-module"
   - Display progress dashboard

8. Proceed to Phase 2

Phase 2: Per-Module TDD Loop

OBJECTIVE: For each module, write tests first (verify red), then implement (verify green)

MODULE ORDER: identity, attribution, workspace, problems, proposals, consensus, channels, proxy, hub-handler

For each MODULE in order:

Step 2a: Write Types (if module has new types)

If this module int