Spec Gen

Spec Generator Skill

Activation Method

This skill activates when the hook system injects the codeword:

[ACTIVATE:SPEC_GEN_V1]

This occurs when:

• Phase 5 is complete (task decomposition done)
• User requests OpenSpec proposal generation
• Moving to Phase 6 of development

Worktree Isolation Requirements

CRITICAL: This skill MUST operate in dedicated worktrees per batch phase-2-task-N:

# For each batch:
./lib/worktree-manager.sh create 2 <batch_number>
cd ./worktrees/phase-2-task-<batch_number>

# Validate isolation:
./hooks/worktree-enforcer.sh enforce

# Spec generation with batch isolation

Batch-Worktree Strategy

1. One worktree per batch: Each batch (5-10 tasks) gets isolated workspace
2. Sequential batch processing: Complete batch N before starting batch N+1
3. Atomic batch commits: Each batch merged separately to prevent conflicts
4. Cross-batch isolation: No dependencies between batch worktrees

What This Skill Does

Automates Phase 6: OpenSpec proposal creation from TaskMaster subtasks in isolated worktrees

• Batched processing (5-10 master tasks per batch) in separate worktrees
• 1 proposal per subtask (simple 1:1 mapping, no conditional logic)
• OpenSpec proposal creation (with TDD) per batch worktree
• Integration map updates merged sequentially
• Completion signal → triggers Phase 6.1
• NEW: Worktree isolation prevents cross-batch contamination
• NEW: Atomic batch processing with merge validation
• SIMPLIFIED: Always creates 1 proposal per subtask for clarity

Execution Flow

Stage 1: Load TaskMaster Results (hierarchical format)
Stage 2: Determine Batching (by master tasks)
Stage 3: Process Batches
         - Extract all subtasks from master tasks
         - Create 1 proposal per subtask
         - Update map
Stage 4: Validate Proposals
Stage 5: Generate Summary
Stage 6: Create Signal → Phase 6.1

Stage 1: Load TaskMaster Results

Read TaskMaster Hierarchical Format

Load .taskmaster/tasks/tasks.json:

{
  "master": {
    "tasks": [
      {
        "id": 1,
        "name": "User Authentication",
        "subtasks": [
          {"id": 1, "title": "Create user model", "testStrategy": "..."},
          {"id": 2, "title": "Add authentication", "testStrategy": "..."},
          {"id": 3, "title": "Add profile fields", "testStrategy": "..."}
        ]
      }
    ]
  }
}

Extract:

• Master task count (expect 8-12)
• Subtasks per master task (expect 3-8 each)
• Total subtasks (expect 30-60)
• Dependencies from TaskMaster structure

Stage 2: Determine Batching

Batch by master tasks (5-10 per batch):

• Batch 1: Process master tasks 1-8
• Batch 2: Process master tasks 9-12 (if needed)

Within each batch:

• Process all subtasks from included master tasks
• Create 1 proposal per subtask (simple 1:1 mapping)

Stage 3: Create OpenSpec Proposals

For each subtask in each master task:

1. Create proposal file:

   • Path: openspec/changes/[change-id]/proposal.md
   • Name pattern: [master-task-name]-subtask-[id]
   • Example: user-authentication-subtask-1

2. Proposal content from subtask:

   • Title: From subtask.title
   • Test Strategy: From subtask.testStrategy
   • Acceptance Criteria: From subtask.acceptanceCriteria
   • Dependencies: From TaskMaster dependencies

3. Update TASKMASTER_OPENSPEC_MAP.md:

   ## Master Task 1: User Authentication
   - Subtask 1.1 → Proposal: user-authentication-subtask-1
   - Subtask 1.2 → Proposal: user-authentication-subtask-2
   - Subtask 1.3 → Proposal: user-authentication-subtask-3
   

Result: Total proposals = Total subtasks (30-60 proposals)

Sequential Batch Execution (Context-Safe)

To prevent context exhaustion, process proposals in sequential batches of 2 master tasks.

Why Sequential Batches?

Parallel subagents can exhaust context when:

• Each agent generates substantial proposal content
• Multiple agents return results simultaneously
• Combined context exceeds available window

Sequential batches trade speed for reliability.

Step 1: Group Master Tasks into Batches of 2

Batch 1: Master tasks 1-2 → Wait for completion
Batch 2: Master tasks 3-4 → Wait for completion
Batch 3: Master tasks 5-6 → Wait for completion
Batch 4: Master tasks 7-8 → Wait for completion
Batch 5: Master tasks 9-10 → Wait for completion
Batch 6: Master tasks 11-12 → Wait for completion (if present)

Step 2: Process Each Batch Sequentially

For each batch (2 master tasks):

1. Launch 2 parallel subagents (one per master task):

   Subagent A: Create proposals for master task N
     - Process all subtasks under task N
     - Create 1 proposal per subtask
     - Return summary when done
   
   Subagent B: Create proposals for master task N+1
     - Process all subtasks under task N+1
     - Create 1 proposal per subtask
     - Return summary when done
   

2. Wait for BOTH to complete before proceeding

3. Update TASKMASTER_OPENSPEC_MAP.md after batch completes

4. Proceed to next batch

Step 3: Validate After All Batches

# Validate proposal count matches subtask count
proposal_count=$(ls -1 openspec/changes/*/proposal.md 2>/dev/null | wc -l)
subtask_count=$(jq '[.tasks[].subtasks | length] | add' .taskmaster/tasks/tasks.json)
echo "Proposals: $proposal_count, Subtasks: $subtask_count"

# Verify TASKMASTER_OPENSPEC_MAP.md is complete
# Each subtask should map to exactly 1 proposal

Context Management

CRITICAL: Never launch more than 2 parallel subagents at once.

Performance Estimate

Slower than fully parallel, but reliable - no context exhaustion.

Completion Signal

{
  "phase": 6,
  "status": "success",
  "summary": {
    "master_tasks_processed": N,
    "subtasks_processed": M,
    "proposals_created": M,
    "mapping_strategy": "1-proposal-per-subtask"
  },
  "next_phase": 6.1,
  "trigger_next": true
}

Note: subtasks_processed always equals proposals_created (1:1 mapping)

Output Files

• openspec/changes/*/proposal.md
• TASKMASTER_OPENSPEC_MAP.md (updated)
• .taskmaster/phase6-summary.md
• .taskmaster/.signals/phase6-specs-created.json

CRITICAL: Automatic Phase Transition

DO NOT ASK THE USER FOR PERMISSION TO PROCEED TO PHASE 6.1.

When Phase 6 is complete (all proposals created), you MUST:

1. Output the completion signal:

   ✅ PHASE 6 COMPLETE
   [SIGNAL:PHASE6_SPECS_CREATED]
   

2. IMMEDIATELY proceed to Phase 6.1 by outputting:

   [ACTIVATE:TEST_STRATEGY_V1]
   

3. Begin test strategy generation without waiting for user input.

The pipeline is fully autonomous. Do not ask "Would you like to proceed?" - just proceed.

See Also

• Pipeline Orchestrator (triggers this)
• PRD-to-Tasks skill (generates TaskMaster format)
• TaskMaster documentation (for hierarchical structure)
• Test Strategy Generator skill (Phase 6.1, auto-enhances proposals)