@engineereddev/fractal-planner 0.1.1

package/skills/retry/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: fp:retry
+description: Retry a single failed task from a fractal-planner plan. Spawns a fresh builder → verifier → committer cycle for the specified task and updates execution-state.json on success.
+argument-hint: <plan-session-id> <task-id> [--max-iterations N]
+allowed-tools: AskUserQuestion, Read, Write, Edit, Bash, Task, Glob, Grep, mcp__linear-server__update_issue
+---
+
+# Fractal Planner: Task Retry
+
+You are retrying a single failed task from a fractal-planner implementation plan. You spawn a fresh builder → verifier → committer cycle and update `execution-state.json` (and Linear) on success.
+
+## Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` to extract:
+- `planId` — first positional argument (required)
+- `taskId` — second positional argument (required)
+- `--max-iterations N` — optional, defaults to 3
+
+Usage examples:
+- `/fp:retry abc123 1.2`
+- `/fp:retry abc123 1.2 --max-iterations 5`
+
+If `planId` or `taskId` is missing, report the error and stop:
+> "Usage: `/fp:retry <plan-session-id> <task-id> [--max-iterations N]`"
+
+## Step 2: Load Plan & Validate Preconditions
+
+Read from `.fractal-planner/plans/{planId}/`:
+1. `plan.md` — execution order and acceptance criteria (REQUIRED)
+2. `tasks.md` — full task tree with hints and metadata (REQUIRED)
+3. `execution-state.json` — resume artifact with task map and status (REQUIRED)
+
+If any required file is missing, report the error and stop:
+> "Plan '{planId}' not found or implementation not yet started. Run `/fp:plan` then `/fp:implement {planId}` first."
+
+Parse `execution-state.json`:
+- Extract `taskMap` — object mapping plan task IDs to native task IDs
+- Extract `failureReasons` — object mapping plan task IDs to failure reasons
+- Extract `skippedTasks`
+
+**Validate task exists in taskMap:**
+
+If `taskId` is NOT a key in `taskMap`, stop:
+> "Task {taskId} not found in execution state. Valid task IDs: {comma-separated taskMap keys}"
+
+Get `nativeId = taskMap[taskId]`.
+
+**Read native task file to validate FAILED status:**
+
+Read `~/.claude/tasks/fp-impl-{planId}/{nativeId}.json`.
+
+If the file does not exist, stop:
+> "Native task file not found for {taskId}. The implementation team may have been deleted."
+
+Parse the JSON and check:
+- If `status != "completed"` OR `metadata.fpStatus != "FAILED"`:
+  > "Task {taskId} is not in FAILED state (current status: {status}, fpStatus: {metadata.fpStatus or 'none'}). Only FAILED tasks can be retried."
+
+**Validate dependencies are completed:**
+
+Find task `{taskId}` in `plan.md` to get its dependencies. For each dependency `depId`:
+- Get `depNativeId = taskMap[depId]`
+- Read `~/.claude/tasks/fp-impl-{planId}/{depNativeId}.json`
+- If `status != "completed"` OR `metadata.fpStatus != "COMPLETED"`:
+  > "Cannot retry task {taskId}: dependency {depId} is not COMPLETED (status: {status}, fpStatus: {metadata.fpStatus or 'none'}). Complete or fix dependencies first."
+
+## Step 3: Load Task Context
+
+From `tasks.md` and `plan.md`, extract for task `{taskId}`:
+- Description
+- Acceptance criteria (numbered list)
+- Implementation hints
+- References (file:line pairs)
+- Files to modify
+- Tests required flag
+- Test commands
+
+**Load codebase context** (same three-tier fallback as fp:implement):
+1. Try `.fractal-planner/plans/{planId}/context.md`
+2. If not found, generate it by reading `package.json`, scanning project structure, identifying patterns
+3. If both fail, set codebaseContext to empty string
+
+**Check for previous evidence**:
+Read `.fractal-planner/plans/{planId}/evidence/task-{taskId}-verification.md` if it exists. Extract the failure details to inject into the builder's context.
+
+## Step 4: Execute Retry Loop
+
+Initialize `iteration = 1`.
+
+Display to user:
+```
+Retrying task {taskId}: {description}
+Max iterations: {maxIterations}
+Previous failure evidence: {found / not found}
+Previous failure reason: {failureReasons[taskId] or "not recorded"}
+```
+
+### 4.1: Spawn Builder
+
+Spawn a fresh builder as a subagent via the Task tool:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Implement task {taskId}",
+  prompt: "You are a builder agent implementing a single task.
+
+{codebaseContext}
+
+{If iteration > 1 or previous evidence exists:}
+PREVIOUS ATTEMPT FAILED.
+Failure details:
+{previousFailureDetails or evidence file contents}
+
+Review the existing code and fix all issues listed.
+
+---
+
+Implement task {taskId}:
+Description: {description}
+
+Acceptance Criteria:
+{numbered criteria}
+
+Implementation Hints:
+{hints, or omit section if empty}
+
+References:
+{file:line refs, or omit section if empty}
+
+Files to Modify: {list or 'determine from context'}
+Tests Required: {yes/no}
+Test Commands: {commands or omit if empty}
+
+MUST NOT DO:
+{guardrails, or omit section if empty}
+
+RULES:
+- Implement with REAL code only. No stubs, placeholders, or TODOs.
+- If testsRequired is true, write tests.
+- Follow existing codebase patterns.
+- Track ALL files you create or modify.
+
+When done, output EXACTLY this format:
+IMPLEMENTATION COMPLETE: {taskId}
+
+FILES_MODIFIED:
+- /absolute/path/to/file1
+- /absolute/path/to/file2"
+)
+```
+
+Wait for the builder subagent to complete. Extract `FILES_MODIFIED` from its output.
+
+If the builder's output does not contain `IMPLEMENTATION COMPLETE`, treat it as a failure and proceed to 4.3 (failure handling) with the builder output as the error.
+
+### 4.2: Verify Implementation
+
+Spawn a verification subagent:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Verify task {taskId}",
+  prompt: "You are a verification agent for a fractal-planner retry.
+
+Task ID: {taskId}
+Description: {description}
+
+Acceptance Criteria:
+{numbered criteria}
+
+Files Modified by Builder:
+{FILES_MODIFIED list}
+
+Test Commands: {commands or 'none'}
+Tests Required: {yes/no}
+
+{codebaseContext}
+
+Instructions:
+1. Read each modified file listed above.
+2. For each acceptance criterion, verify it is met by the code.
+3. If tests are required, run the test commands via Bash.
+4. Run: bun run typecheck (if tsconfig.json exists in the project root).
+5. Write your evidence to: .fractal-planner/plans/{planId}/evidence/task-{taskId}-verification.md
+
+Evidence file format:
+---
+# Verification Evidence: Task {taskId}
+
+Result: PASS | FAIL
+Timestamp: {ISO timestamp}
+Task: {description}
+
+## Criteria Results
+| # | Criterion | Result | Evidence |
+|---|-----------|--------|---------|
+| 1 | {text} | PASS/FAIL | {snippet} |
+
+## Test Output
+\`\`\`
+{test output or 'Tests not required'}
+\`\`\`
+
+## Typecheck Output
+\`\`\`
+{typecheck output or 'No tsconfig.json found'}
+\`\`\`
+
+## Files Reviewed
+- {absolute file path}
+
+## Summary
+{1-2 sentence summary}
+---
+
+6. After writing the evidence file, output EXACTLY:
+If ALL criteria pass: VERIFICATION PASSED
+If ANY check fails:
+VERIFICATION FAILED
+Failed:
+- Criterion {N}: {text} — {reason and fix instruction}
+Passed:
+- Criterion {N}: {text}
+Tests: {PASS/FAIL with relevant output}
+Typecheck: {PASS/FAIL with errors if any}"
+)
+```
+
+### 4.3: Handle Verification Result
+
+**If VERIFICATION PASSED:**
+1. Proceed to Step 5 (commit + update state).
+
+**If VERIFICATION FAILED:**
+1. Store the failure report as `previousFailureDetails`.
+2. Increment `iteration`.
+3. If `iteration > maxIterations`:
+   - Display to user: "Task {taskId} still fails after {maxIterations} iterations."
+   - Show the last `VERIFICATION FAILED` report.
+   - Suggest: "Check evidence at `.fractal-planner/plans/{planId}/evidence/task-{taskId}-verification.md`"
+   - Stop.
+4. Else: loop back to Step 4.1 (fresh builder with failure context).
+
+## Step 5: Commit
+
+Spawn a committer subagent:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Commit task {taskId} changes",
+  prompt: "You are a git commit specialist.
+
+Follow the fp:commit skill instructions to create ONE git commit.
+
+TASK CONTEXT:
+- Task ID: {taskId}
+- Description: {description}
+
+FILES_MODIFIED:
+{paste the file list}
+
+INSTRUCTIONS:
+1. Detect commit style from git log (SEMANTIC|PLAIN|SHORT)
+2. Detect language (Korean|English)
+3. Stage only these specific files
+4. Create ONE commit with message based on task description
+5. Output EXACTLY:
+COMMIT COMPLETED
+Hash: {short hash}
+Message: {commit message}
+OR: COMMIT FAILED
+Error: {error message}"
+)
+```
+
+Extract commit hash from committer output. If commit fails, use `AskUserQuestion`:
+- "Git commit failed for task {taskId}. How should we proceed?"
+- Options: "Continue without committing" / "Stop"
+- If "Stop", report failure and stop.
+
+## Step 6: Update Execution State & Linear
+
+**Update native task status:**
+
+The native task system has no live team context during `fp:retry` (the team was deleted after `fp:implement`). Update `execution-state.json` directly instead of calling `TaskUpdate`:
+
+1. Read `.fractal-planner/plans/{planId}/execution-state.json`
+2. Remove `{taskId}` from `failureReasons` (it is no longer failed)
+3. Write the updated JSON back
+
+**Note on native task file**: The task JSON at `~/.claude/tasks/fp-impl-{planId}/{nativeId}.json` reflects the old FAILED status, but since the team is deleted, `TaskUpdate` is not available. The `execution-state.json` is the authoritative resume artifact for `fp:implement` resumes; `fp:status` reads both files and should prefer `execution-state.json` for retry-updated tasks.
+
+**Update Linear (if mapping exists):**
+
+Check for `.fractal-planner/plans/{planId}/linear-mapping.json`. If it exists:
+1. Read it to find the Linear issue ID for task `{taskId}`
+2. Find the resolved status ID for "review" (or "completed" as fallback)
+3. Call `mcp__linear-server__update_issue` with the resolved status
+4. If the call fails, log a warning but do NOT stop
+
+## Step 7: Report & Next Steps
+
+```
+## Retry Result: {planId} / {taskId}
+
+**Status**: PASSED ✅
+**Iterations**: {iteration}/{maxIterations}
+**Commit**: {hash or "none (commit failed or skipped)"}
+
+Task {taskId} ({description}) has been completed.
+Execution state updated: `.fractal-planner/plans/{planId}/execution-state.json`
+
+### P1 Limitation
+Tasks previously skipped due to this failure (blocked dependents) remain deleted
+in the native task system and will NOT be automatically re-queued. To implement
+downstream tasks, start a new plan:
+  /fp:plan  (then /fp:implement on the new plan)
+
+To resume the original plan for any remaining non-blocked tasks:
+  /fp:implement {planId}
+```
+
+## Important
+
+- This skill operates WITHOUT a live tracker teammate — `execution-state.json` is updated directly
+- The builder and verifier are spawned as **subagents** (Task tool), not teammates
+- Always validate preconditions (FAILED status + all deps COMPLETED) before proceeding
+- Evidence files are written to `.fractal-planner/plans/{planId}/evidence/` — create the directory if needed
+- If Linear mapping exists, update Linear after updating execution state (best-effort, never block on failure)
+- The native team `fp-impl-{planId}` has been deleted by `fp:implement` Step 6, so `TaskUpdate` is unavailable; use `execution-state.json` as the authoritative resume artifact

package/skills/status/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: fp:status
+description: Read-only status reporter for fractal-planner implementation plans. Shows progress bar, per-task status table, and links to evidence files. Reads native task JSON files directly.
+argument-hint: <plan-session-id>
+allowed-tools: Read, Glob, Bash
+---
+
+# Fractal Planner: Plan Status
+
+You are generating a read-only status report for a fractal-planner implementation plan.
+
+## Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` to extract `planId` (the first positional argument).
+
+If no `planId` is provided, report the error and stop:
+> "Usage: `/fp:status <plan-session-id>`"
+
+## Step 2: Load Execution State & Native Task Files
+
+### 2.1: Read Execution State
+
+Read `.fractal-planner/plans/{planId}/execution-state.json`.
+
+If missing, report the error and stop:
+> "Plan '{planId}' has no execution state. Run `/fp:implement {planId}` first to start implementation."
+
+Parse:
+- `taskMap` — object mapping plan task IDs to native task IDs (e.g., `{ "1.1": "3", "2.1": "5" }`)
+- `skippedTasks` — object mapping plan task IDs to skip reasons
+- `failureReasons` — object mapping plan task IDs to failure reasons
+- `maxIterations`, `planId`, `team`
+
+Also read `plan.md` for task descriptions (used in the task table):
+Read `.fractal-planner/plans/{planId}/plan.md`. If missing, use task IDs as descriptions.
+
+### 2.2: Read Native Task JSON Files
+
+The native task JSON files are stored at `~/.claude/tasks/fp-impl-{planId}/`.
+
+Use Glob to find all task files:
+```
+Glob("~/.claude/tasks/fp-impl-{planId}/*.json")
+```
+
+For each file found, read it and parse:
+- `id` — native task ID
+- `subject` — contains `[{planTaskId}] {description}` — extract planTaskId from the `[...]` prefix
+- `status` — `pending`, `in_progress`, `completed`, or `deleted`
+- `metadata` — object with `fpStatus`, `iterations`, `commit`, `summary`, `reason` fields
+- `blockedBy` — array of blocking native task IDs (empty if unblocked)
+
+Build a `statusMap` keyed by plan task ID:
+```
+statusMap[planTaskId] = {
+  nativeId,
+  status,           // native status
+  fpStatus,         // metadata.fpStatus (COMPLETED | FAILED | SKIPPED | absent)
+  iterations,       // metadata.iterations (e.g. "1/3")
+  commit,           // metadata.commit
+  summary,          // metadata.summary
+  reason,           // metadata.reason (for FAILED) or skippedTasks[planTaskId] (for SKIPPED)
+  blockedBy         // array of native IDs still blocking this task
+}
+```
+
+If the `~/.claude/tasks/fp-impl-{planId}/` directory does not exist or is empty:
+- Fallback: use only `execution-state.json` data
+- Mark all tasks in `taskMap` as PENDING (the team may still be initializing, or files are unavailable)
+
+### 2.3: Scan for Evidence Files
+
+```bash
+ls .fractal-planner/plans/{planId}/evidence/ 2>/dev/null
+```
+
+Collect evidence file names for later display.
+
+## Step 3: Classify Tasks & Compute Statistics
+
+For each plan task ID in `taskMap`, classify its status:
+
+| Condition | Classification |
+|-----------|---------------|
+| In `skippedTasks` AND (`status == "deleted"` OR native file absent) | **SKIPPED** |
+| `status == "completed"` AND `fpStatus == "FAILED"` | **FAILED** |
+| `status == "completed"` AND (`fpStatus == "COMPLETED"` OR fpStatus absent) | **COMPLETED** |
+| `status == "in_progress"` | **IN_PROGRESS** |
+| `status == "pending"` | **PENDING** |
+| `status == "deleted"` AND `fpStatus == "SKIPPED"` | **SKIPPED** |
+| Native file not found AND not in `skippedTasks` | **PENDING** (not yet created or team initializing) |
+
+Count each classification:
+- `total` = number of keys in `taskMap`
+- `completed` = count of COMPLETED
+- `inProgress` = count of IN_PROGRESS
+- `pending` = count of PENDING
+- `failed` = count of FAILED
+- `skipped` = count of SKIPPED
+
+Compute progress percentage: `floor((completed / total) * 100)`
+
+Build a 20-character progress bar using block characters:
+- Filled blocks (`█`): `floor(completed / total * 20)` chars
+- Empty blocks (`░`): remainder
+
+## Step 4: Render Status Report
+
+Present the following formatted report:
+
+```
+## Plan Status: {planId}
+
+**Progress**: [{████████░░░░░░░░░░░░}] {completed}/{total} tasks ({pct}%)
+
+### Summary
+| Status      | Count |
+|-------------|-------|
+| ✅ Completed | {N}  |
+| 🔄 In Progress | {N} |
+| ⏳ Pending   | {N}  |
+| ❌ Failed    | {N}  |
+| ⏭️ Skipped   | {N}  |
+
+### Task Table
+| # | ID | Description | Status | Iterations | Commit | Notes |
+|---|-----|-------------|--------|------------|--------|-------|
+{one row per task in taskMap order, using statusMap data}
+```
+
+Row format:
+- `#` — sequential number
+- `ID` — plan task ID
+- `Description` — from plan.md or `[{planTaskId}] {subject}` if plan.md unavailable
+- `Status` — COMPLETED / IN_PROGRESS / PENDING / FAILED / SKIPPED
+- `Iterations` — `metadata.iterations` or `-` if not started
+- `Commit` — `metadata.commit` (short hash) or `-`
+- `Notes` — `metadata.summary` for COMPLETED, `metadata.reason` for FAILED, `skippedTasks[id]` for SKIPPED, blank otherwise
+
+If there are FAILED tasks, add a section:
+
+```
+### Failed Tasks
+{For each FAILED task:}
+- **[{id}]** {description}
+  - Iterations used: {iterations}
+  - Reason: {reason from metadata or failureReasons}
+  - Evidence: `.fractal-planner/plans/{planId}/evidence/task-{id}-verification.md` {(exists) or (not found)}
+```
+
+If evidence files were found, add a section:
+
+```
+### Evidence Files
+{For each evidence file found, read it and extract the Result line:}
+- `task-{id}-verification.md`: {PASS | FAIL} — {1-line summary from evidence file}
+```
+
+## Step 5: Show Next Steps
+
+After the report, show contextual next steps:
+
+- If all tasks are COMPLETED:
+  > "All {N} tasks complete. Implementation finished."
+- If any IN_PROGRESS tasks exist:
+  > "Implementation session is active. A `/fp:implement` session may be running."
+- If PENDING tasks remain and no IN_PROGRESS tasks:
+  > "Run `/fp:implement {planId}` to continue implementation."
+- If FAILED tasks exist:
+  > "To retry a failed task: `/fp:retry {planId} {taskId}`"
+  > "To resume full implementation (if all deps are met): `/fp:implement {planId}`"
+- If SKIPPED tasks exist (and some FAILED tasks exist):
+  > "Note: {N} tasks were skipped due to failed dependencies. Use `/fp:retry` to fix failed tasks, then start a new plan to implement the skipped downstream tasks."
+
+## Important
+
+- This skill is **read-only** — it does not modify any files
+- Primary source of truth: native task JSON files at `~/.claude/tasks/fp-impl-{planId}/`
+- Secondary source of truth: `execution-state.json` (for `skippedTasks`, `failureReasons`, and `taskMap`)
+- `progress.md` (if it exists) is a human-readable snapshot from the end of the last `fp:implement` run — do NOT use it as a status source
+- If task JSON files are unavailable (team not yet initialized or already deleted), fall back to `execution-state.json` data only
+- Present the report in a clean, scannable format — users run this to get a quick health check