t-plan

What this skill does

# T-Plan Skill (Task-Based Orchestration)

## MANDATORY: STOP AND READ THIS FIRST

**You are an ORCHESTRATOR, not an implementer.**

Before doing ANYTHING else, you MUST:

1. **Create the session directory** with `mkdir -p .t-plan/<session-id>`
2. **Write intent.md** capturing the user's request
3. **Create the master task** with TaskCreate

**You MUST NOT:**
- Use Read, Grep, Glob, or WebSearch yourself (that's the EXPLORE subagent's job)
- Research documentation yourself (that's the VALIDATE subagent's job)
- Skip directly to analysis or recommendations

**If you find yourself exploring the codebase before writing intent.md, STOP. You have violated the workflow.**

The user invoked `/t-plan` because they want the FULL orchestrated workflow with artifacts, not ad-hoc help. Follow the steps below EXACTLY.

---

Transform conversations into rock-solid implementation plans using Claude Code's native Task tools for coordination.

## Architecture Overview

```
No hooks required - Task tools handle all coordination natively.

Orchestrator responsibilities:
- Session initialization (mkdir, .gitignore, current.txt pointer)
- Task lifecycle (TaskCreate, TaskUpdate)
- Pre-truncation before subagent dispatch
- Output verification after subagent return
- Retry logic (max 2 attempts)

Subagent responsibilities:
- Read context files (intent.md, explore.md, etc.)
- Write output files directly (explore.md, scout.md, validation-vNNN.json)
- Focus on their assigned task
```

**Reference material** (load when needed):
- Retry logic & parallel execution: See `references/subagent-patterns.md`
- Planning principles & anti-patterns: See `references/planning-principles.md`
- Plan output template: See `references/plan-template.md`

---

## Workflow

```
INTENT -> EXPLORE -> [gate] -> SCOUT -> DRAFT -> VALIDATE -> PLAN
   |          |                   |        |          |         |
 orch.     subagent            subagent  orch.    subagent   orch.+user
```

| Step | Actor | Output |
|------|-------|--------|
| **INTENT** | Orchestrator | Clear intent (gate: can direct EXPLORE?) |
| **EXPLORE** | Subagent | Codebase insights (gate: trivial -> skip?) |
| **SCOUT** | Subagent (optional) | Alternatives only (no docs) |
| **DRAFT** | Orchestrator | Initial approach (reads files, synthesizes) |
| **VALIDATE** | Subagent (required checkpoint) | Doc validation + snippets |
| **PLAN** | Orchestrator + User | Final plan, iterate until approved |

**Principles:**
- Subagents gather information
- Orchestrator synthesizes and decides
- Two gates: clarity (INTENT), complexity (EXPLORE)
- Single user checkpoint (PLAN)

---

## Session Directory Structure

```
.t-plan/
+-- current.txt                    # Text pointer: "auth-oauth-20260124-150230"
+-- .gitignore                     # Ignore all session dirs
+-- auth-oauth-20260124-150230/    # Session directory
    +-- intent.md                  # Orchestrator writes (Step 1)
    +-- explore.md                 # EXPLORE subagent writes
    +-- scout.md                   # SCOUT subagent writes (optional)
    +-- draft-v001.md              # Orchestrator writes (Step 4)
    +-- validation-v001.json       # VALIDATE subagent writes
    +-- plan.md                    # Final output (Step 6)
```

**Session ID format:** `<slug>-<YYYYMMDD-HHMMSS>`

---

## Step 1: INTENT [ORCHESTRATOR]

**Goal**: Capture user intent and initialize session.

### Initialize Session

```
SESSION_ID="<slug>-<YYYYMMDD-HHMMSS>"
Bash: mkdir -p .t-plan/${SESSION_ID}
Write: .t-plan/.gitignore -> "*\n!.gitignore\n"
Write: .t-plan/current.txt -> "${SESSION_ID}"
TaskCreate(subject: "T-Plan: [goal]", metadata: {"session_id": "${SESSION_ID}"})
TaskGet + TaskUpdate(status: "in_progress")
```

### Capture Intent

1. Capture the user's request in their terms
2. Clarify ambiguities that would prevent focused exploration
3. Do NOT assume technologies or solutions
4. Write intent to `.t-plan/${SESSION_ID}/intent.md`

### Clarity Gate

> "Can I write a focused prompt for the EXPLORE subagent?"

- **NO** -> Clarify using AskUserQuestion with options: "Narrow scope", "Define outcome", "Add constraints"
- **YES** -> Proceed to EXPLORE

---

## Step 2: EXPLORE [SUBAGENT]

**Goal**: Understand the codebase relevant to the user's intent.

### Dispatch Pattern

```
# Pre-truncate output
Write: .t-plan/${SESSION_ID}/explore.md -> ""

# Create tracking task
TaskCreate(subject: "EXPLORE: [area]", metadata: {"output_file": "explore.md"})

# Dispatch
Task(subagent_type: "Explore", allowed_tools: ["Read", "Grep", "Glob", "Write"], prompt: """
  **Context**: Read .t-plan/${SESSION_ID}/intent.md

  **Task**: Explore codebase to understand:
  1. Tech stack, frameworks, patterns
  2. Existing code related to [area]
  3. Project structure and conventions
  4. Relevant installed dependencies

  **Output**: Write to .t-plan/${SESSION_ID}/explore.md
  - Start with summary referencing intent.md (proof-of-read)
  - Include key files with line references
  - Describe architecture connections
""")

# Verify: exists + non-empty + references intent.md
# Retry up to 2 attempts (see references/subagent-patterns.md)
```

### Complexity Gate

> "Is this task trivially simple?" (single file, pattern exists, no deps, no architecture)

**If trivially simple:** Ask user: "Continue T-Plan" / "Normal plan mode" / "Skip to DRAFT"

**If not trivially simple:** Continue to SCOUT or DRAFT.

---

## Step 3: SCOUT [SUBAGENT] (Optional)

**Goal**: Find alternatives that might be simpler than the obvious approach.

### Dispatch Pattern

```
# Pre-truncate + create task
Write: .t-plan/${SESSION_ID}/scout.md -> ""
TaskCreate(subject: "SCOUT: alternatives")

# Dispatch
Task(subagent_type: "general-purpose", allowed_tools: ["Read", "Grep", "Glob", "Write"], prompt: """
  **Context**: Read intent.md and explore.md

  **Task**: Search for alternatives MEANINGFULLY simpler:
  - Fewer dependencies
  - Less code to maintain
  - Better fits existing patterns

  DO NOT query documentation (that's VALIDATE's job).

  **Output**: Write to .t-plan/${SESSION_ID}/scout.md
  Often correct output is: "No simpler alternatives found."
""")

# Verify: exists + non-empty + references explore.md
```

---

## Step 4: DRAFT [ORCHESTRATOR]

**Goal**: Synthesize all context and draft an initial approach.

### What to Do

1. Read intent.md, explore.md, scout.md (if exists)
2. Read key implementation files identified by EXPLORE
3. Write draft to `.t-plan/${SESSION_ID}/draft-v001.md`

```markdown
## Approach

**Goal**: [1-2 sentences]

**Key decisions**:
- [Decision 1]: [Choice] because [rationale]. Rejected: [alternatives]

**Files to modify/create**:
- `path/to/file.ts` - [what changes]

**Approach outline**:
1. [High-level step 1]
2. [High-level step 2]
```

Update master task: `TaskUpdate(metadata: {"draft_version": 1})`

---

## Step 5: VALIDATE [SUBAGENT] (Required Checkpoint)

**Goal**: Check the draft approach against official documentation.

> **Note**: VALIDATE is required before PLAN. If skipping (internal refactor, no external APIs),
> record explicit rationale in the plan.

### Dispatch Pattern

```
# Pre-truncate
Write: .t-plan/${SESSION_ID}/validation-v001.json -> ""
TaskCreate(subject: "VALIDATE: draft v1")

# Dispatch
Task(subagent_type: "general-purpose",
     allowed_tools: ["Read", "Grep", "Glob", "Write", "WebSearch", "WebFetch"],
     prompt: """
  **Context**: Read intent.md, explore.md, scout.md (if exists), draft-v001.md

  **Task**: Validate draft against official documentation.
  - Using RECOMMENDED patterns?
  - Any DEPRECATED APIs or anti-patterns?
  - What are the GOTCHAS?
  - Provide WORKING setup snippets

  **Output**: Write to .t-plan/${SESSION_ID}/validation-v001.json
  {
    "draft_version": 1,
    "status": "VALID" | "NEEDS_CHANGES",
    "confirmations": [...],
    "corrections": [...],
    "snippets": [...],
    "gotchas": [...],
    "doc_links": [...]
  }
""")

# Verify: valid JSON + draft_version matches + status