---
name: doc-iplan
description: Create an Implementation Plan (IPLAN) - Layer 8 of the SDD flow, the mandatory execution bridge from SPEC/TDD to source code via an executable, session-resumable file manifest. Use when ready to implement a SPEC component. Single-document authoring primitive; for end-to-end or batch generation the autopilot (`doc-iplan-autopilot`) drives this skill.
metadata:
  tags:
    - sdd-workflow
    - layer-8-artifact
  custom_fields:
    layer: 8
    artifact_type: IPLAN
    skill_category: core-workflow
    upstream_artifacts: [SPEC, TDD]
    downstream_artifacts: [CODE]
    version: "0.24.0"
    framework_spec_version: "0.40.0"
    last_updated: "2026-05-23"
    adapts: [section_toggles, glossary]
---

# doc-iplan

## Purpose

Create an **Implementation Plan (IPLAN)** — Layer 8 of the SDD flow. An IPLAN
bridges SPEC + TDD to source code: declares test-first file order (inherited
from TDD), executable bash commands, session progress for stateless executors,
and an audit trail from spec to delivered files.

**Layer**: 8 (final doc layer; downstream is Code).
**Upstream**: SPEC, TDD (per the necessary-upstream contract; the rest of
the chain is reachable transitively via SPEC/TDD's own @-tag references).

One IPLAN per SPEC component (matching its TDD). Bugfixes with no new
functionality use a temporary plan in `docs/08_IPLAN/tmp/` instead.

## When to Use

Use `doc-iplan` when:

- Layers 1–7 exist and the source TDD has reached IPLAN-Ready ≥ 90/100.
- You are ready to bridge a SPEC/TDD component into source code.
- You need an executable, session-resumable plan for stateless coding agents.

For end-to-end generation from a SPEC/TDD, a prompt, or an existing IPLAN, use
`../doc-iplan-autopilot/SKILL.md`.

## Prerequisites

Before writing, read:

1. **Template (source of truth):** `${CLAUDE_PLUGIN_ROOT}/framework/layers/08_IPLAN/IPLAN-TEMPLATE.yaml`
2. **Index template:** `${CLAUDE_PLUGIN_ROOT}/framework/layers/08_IPLAN/IPLAN-00_index.TEMPLATE.yaml`
3. **Layer README:** `${CLAUDE_PLUGIN_ROOT}/framework/layers/08_IPLAN/README.md`
4. **ID & tag standards:** `${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md`
5. **Authoring style:** `${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md`

Read the upstream **TDD** (primary source for the file manifest and test-first
order) and the **SPEC** it derives from. Reference only documents that exist;
never invent placeholders like `IPLAN-XXX` or `TBD`. Confirm no ID collision:
`ls docs/08_IPLAN/ 2>/dev/null`.

## Layer Guidance

### Permanent vs Temporary plans (decide first)

| | Permanent IPLAN (`IPLAN-NN_{slug}.yaml`) | Temporary IPLAN (`tmp/TMP-IPLAN-*.yaml`) |
|---|---|---|
| **Purpose** | Implement a SPEC component via TDD test cases | Bugfix, correction, investigation — no new functionality |
| **Requires TDD** | Yes — one IPLAN per SPEC/TDD | No — standalone |
| **Registered in index?** | Yes — `IPLAN-00_index.yaml` | No |
| **Triggers audit trail?** | Yes — code inventory, session log | No — disposable |
| **Deleted when?** | Never — historical record (use ABANDONED) | Within 7 days of DONE/ABANDONED |
| **Naming** | `IPLAN-NN_{slug}.yaml` (NN sequential, never reused) | `TMP-IPLAN-YYYY-MM-DD_{slug}.yaml` |

**Rule of thumb:** implements a TDD test contract → permanent; restores intended
behavior or fixes a bug → temporary.

### Required structure (11 sections — subtype-dependent subset)

The IPLAN is a YAML document with `metadata` (`document_type: iplan-document`,
`layer: 8`) followed by the sections matching `IPLAN-TEMPLATE.yaml`. The
required-section set depends on `document_control.subtype` (CLEANUP-PR-E
item 17):

- **`code_build`**: sections 1-6 below (document_control, file_manifest,
  execution_commands, implementation_contracts, session_handoff,
  traceability).
- **`deploy`**: sections 1, 7-11 (document_control,
  rollback_procedure, smoke_tests, canary_metrics,
  observability_hooks, runbook_reference) + traceability.
- **`combined`** (default): all 11 sections.

Sections 1-6 (code_build set):

1. **Document Control** — `iplan_id` (`IPLAN-NN`), `source_spec`
   (`@spec: SPEC-NN`), status (`Draft | In Progress | Completed`), version,
   dates, author, `complexity` (1=1 file, 5=architectural), `estimated_files`,
   `session_count`.
2. **File Manifest** — declared creation order, **tests before implementation**
   (TDD principle); each file carries `order`, `status`, `session`, `verified`.
3. **Execution Commands** — runnable bash for `setup`, `implementation`, and
   `validation` (the actual bridge to code).
4. **Implementation Contracts** — Protocol interfaces, exception hierarchies,
   state machines, data models, DI interfaces live *inside* the IPLAN. Required
   only when 3+ files share interfaces; otherwise state "No implementation
   contracts".
5. **Session Handoff** — the stateless-executor bridge; `sessions[]` with
   `partial_work`, `blockers`, `next_session_directive`, `validation_results`.
6. **Traceability** — required upstream tags (`@spec`, `@tdd`), downstream
   `code_paths` / `test_paths`, and `code_inventory` (audit trail of every
   file created/modified with session attribution and `verified` status).

Sections 7-11 (deploy set; required when subtype is `deploy` or `combined`):

7. **Rollback Procedure** — step-by-step rollback with documented
   reversal per cutover step + verification + reversible flag.
8. **Smoke Tests** — post-cutover smoke checks with named pass criteria
   per cutover step.
9. **Canary Metrics** — explicit thresholds (latency, error rate,
   saturation) per metric + canary window + action on breach.
10. **Observability Hooks** — named signals emitted at deploy events
    - dashboard URLs.
11. **Runbook Reference** — pointer to on-call runbook + new
    failure-mode entries this deploy adds.

### Session handoff protocol

Each stateless session: 1) read `session_handoff.sessions` for the last
state → 2) find the next `NOT_STARTED`/`PARTIAL` file in `file_manifest` →
3) read `partial_work` if resuming → 4) continue, do **not** regenerate
completed work → 5) update file status → 6) append a session with a
`next_session_directive`. Markers: `NOT_STARTED | IN_PROGRESS | DONE | PARTIAL`.

### Document ID and tags

- **IPLAN is a DOCUMENT-level artifact** — referenced in dash form `IPLAN-NN`
  (e.g. `@iplan: IPLAN-01`). There is **no** hierarchical dotted element ID for
  an IPLAN; never write `IPLAN.NN.SS.xxxx`.
- IPLAN is Layer 8, so it carries the **required upstream tags** (per the
  necessary-upstream contract): `@spec @tdd`. Hierarchical upstreams use the
  dotted form (`@tdd: TDD.01.04.a3c1`); document-level upstreams use dash
  form (`@spec: SPEC-01`). Upstream BRD/PRD/EARS/BDD/ADR lineage is reachable
  transitively via SPEC/TDD's own @-tag references — do not emit
  `@brd:`/`@prd:`/`@ears:`/`@bdd:`/`@adr:` on IPLAN elements.
- **Removed patterns** (do not use): `TASK-XXX`, `TODO-XXX`, `TI-XXX`,
  `ITEM-XXX`, and any `IPLAN.NN.SS.xxxx` hierarchical ID.

## Creation Process

1. **Determine type** — permanent vs temporary (table above).
2. **Reserve ID** — next free `IPLAN-NN` (two digits, sequential, never reused);
   the ID typically matches its SPEC/TDD component.
   *Per-layer independence (CLEANUP-PR-F item 18):* pick the next-free
   number in YOUR layer's index — the upstream's number is NOT your number
   (doc numbers are per-layer sequential and independent; see
   `framework/governance/ID_NAMING_STANDARDS.md` §Cross-layer cardinality).
3. **Create the file** — permanent: `docs/08_IPLAN/IPLAN-NN_{slug}.yaml`;
   temporary: `docs/08_IPLAN/tmp/TMP-IPLAN-YYYY-MM-DD_{slug}.yaml`.
4. **Select subtype** (CLEANUP-PR-E item 17) — decide which subtype
   this IPLAN is and write it to `document_control.subtype`:
   - `code_build`: file-manifest + Red/Green/Refactor + execution
     commands. NO rollback/smoke/canary/observability sections. Use
     when the IPLAN translates SPEC/TDD to source code only;
     deployment is a separate plan.
   - `deploy`: rollback + smoke + canary + observability + runbook
     sections. NO file-manifest / execution-commands. Use when the
     IPLAN executes a cutover of code that's already authored.
   - `combined` (default): both sets required. Use when one IPLAN
     covers code authoring AND deploy.
   The auditor reads `subtype` and dispatches different required-section
   sets. Missing field defaults to `combined`.
5. **Document Control first**, then complete all sections required for
   the chosen subtype (template marks each section with
   `_required_when_subtype:`).
6. **Declare the file manifest** (code_build / combined only)
   test-first, every file `status: NOT_STARTED`.
7. **Write execution commands** (code_build / combined only) —
   `setup` / `implementation` / `validation`.
8. **Define implementation contracts** (code_build / combined only)
   if 3+ files share interfaces; else state "No implementation contracts".
9. **Seed session handoff** (code_build / combined only) so the first
   executor has a clear `next_session_directive`; add an empty
   `code_inventory`.
10. **For deploy subtype only**: complete rollback_procedure,
    smoke_tests, canary_metrics, observability_hooks,
    runbook_reference (sections 7-11).
11. **Register in the index** (permanent only) — add to
    `docs/08_IPLAN/IPLAN-00_index.yaml` and update `metadata.total_plans`.
12. **Validate** (below) and commit the IPLAN and index together.

## Validation

**This skill is the validator** (no runtime code). Apply against `${CLAUDE_PLUGIN_ROOT}/framework/layers/08_IPLAN/README.md` and `${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md`.

- [ ] `metadata.layer: 8`, `document_type: iplan-document`.
- [ ] Document Control complete (`iplan_id`, `source_spec`, status, dates).
- [ ] All 6 sections present and non-empty.
- [ ] File Manifest lists tests before implementation; each file has a status
      marker and `verified` flag.
- [ ] Execution commands cover setup / implementation / validation.
- [ ] Implementation Contracts declared (or "No implementation contracts").
- [ ] Session Handoff seeded with a `next_session_directive`.
- [ ] Required upstream tags (`@spec @tdd`, per necessary-upstream contract)
      reference existing docs; document ID is `IPLAN-NN` (no dotted IPLAN
      element ID).
- [ ] `code_inventory` ready to record created/modified files.
- [ ] Permanent plan registered in `IPLAN-00_index.yaml`; temporary under `tmp/`.

**Error codes** (all severity `error`): `XDOC-006` tag format invalid · `XDOC-008` broken internal link · `XDOC-009` missing traceability section.

**Quality gate (blocking):** CODE-Ready score ≥ 90/100 with 0 Tier-1 errors
before implementation begins. If issues are found, fix and re-check; if
unfixable, log for manual review.

## Next Skill

IPLAN is the last documentation layer. Proceed to **Code**: execute the file
manifest test-first, updating `status`/`verified`, `session_handoff`, and
`code_inventory` so any later stateless session can resume.

## Adaptation

Read `.aidoc/profile.yaml`; honor only this skill's knobs
(`section_toggles`, `glossary`). Ignore unknown keys; absent a profile, use
framework defaults. Authority:
`${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md`.

## Related Resources

- Template / authoring rules: `${CLAUDE_PLUGIN_ROOT}/framework/layers/08_IPLAN/IPLAN-TEMPLATE.yaml`
- Index template: `${CLAUDE_PLUGIN_ROOT}/framework/layers/08_IPLAN/IPLAN-00_index.TEMPLATE.yaml`
- Layer README: `${CLAUDE_PLUGIN_ROOT}/framework/layers/08_IPLAN/README.md`
- ID & tag standards: `${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md`
- Quality gate: `../doc-iplan-audit/SKILL.md` · Fixes: `../doc-iplan-fixer/SKILL.md`
- Generation pipeline: `../doc-iplan-autopilot/SKILL.md`

## Quick Reference

| | |
|---|---|
| **Purpose** | Bridge a SPEC/TDD component into source code |
| **Layer** | 8 (final doc layer; downstream = Code) |
| **Upstream tags** | `@spec @tdd` (per necessary-upstream contract) |
| **Key decision** | Permanent vs Temporary |
| **Document ID** | `IPLAN-NN` (dash form; no dotted element ID) |
| **Six sections** | doc_control · file_manifest · execution_commands · implementation_contracts · session_handoff · traceability |
| **Handoff markers** | NOT_STARTED · IN_PROGRESS · DONE · PARTIAL |
| **Next** | Code (implementation) |