UNRELEASED DEVELOPMENT SNAPSHOT · READ-ONLY EXCERPT
skills/plan/SKILL.md

This is the cited technical source at local revision 275a354, inspected on 22 September 2026. It differs from the public release. This reference publishes only the cited sections, not an installable release or the development branch.
Line numbers refer to the complete recorded file. Uncited lines are omitted. Full-file SHA-256: c7a29082412a91c8f6ff19eda66e6c067b35b3366f7c46c5ff452dbefb807985.
1---
2name: plan
3layer: foundation
4workflow_root: true
5description: Use after DISCOVER, or standalone when you have a design doc and need to break it into executable work, to produce the cold-executor trio (plan.md + spec.md + prompt.md) together. Tasks are granularity-checked to roughly five minutes each and gated on operator approval.
6color: cyan
7tools: Read, Write, Edit, Bash, Grep, Glob
8voice: internal
9cli_support: [claude-code, codex, copilot]
10necessity: REQUIRED
11gap_if_skipped: "BUILD runs against an unwritten/unreviewed plan; the cold-executor trio (plan.md/spec.md/prompt.md) never exists, so CAPTURE and cold executors have nothing to read."
12navigation:
13  primary_intent: produce cold-executor trio (plan.md + spec.md + prompt.md) born together
14  triggers:
15    - operator types /li:plan as standalone (planner-as-module)
16    - cycle phase 4 invokes after DEFINE + DISCOVER
… omitted uncited lines …
253### Step 11 — Write artifacts
254
255**The trio comes from versioned template files (Slice 2 — design §3.3).** plan.md / spec.md / prompt.md are no longer rendered from inline prose; they are instantiated from the canonical template family, the **single source of truth** for their shape:
256
257- `scaffolding/01-foundation/templates/plan/plan.template.md` — **depth_schema-parametric** (flat / phased / tree marked sections).
258- `scaffolding/01-foundation/templates/plan/spec.template.md` — engineering master spec.
259- `scaffolding/01-foundation/templates/plan/prompt.template.md` — cold-executor handoff.
260
261Read the template, strip the comment header + the unused `depth_schema` sections (for plan.template.md), fill the placeholders, and write the result to the output path. The template files replace the previously-inline skeletons; if the scaffolding tree isn't present (e.g. a bare target repo before `bin/li-scaffold`), fall back to the structures documented below.
262
263**plan.md** (canonical, `.claude/plans/<slug>/plan.md`) — from `plan.template.md`:
264```markdown
265# Plan: <wedge title>   (size: <XS|S|M|L|XL> · schema: <flat|phased|tree>)
266
267**Generated by:** /li:plan on <date>
268**Status:** APPROVED
269**Design doc:** <path>
270**Discover report:** <path>
271**Scope:** <path to scope.md>
272
273## Summary
274<2-3 sentences>
275
276## Plan signals
277- Tasks: <N>
… omitted uncited lines …
337**Dependencies:** none
338**Subagent:** <name>
339**Acceptance:** <verify command or test>
340**Estimated tokens:** <N>
341
342[Complete code or detailed spec here — implementer reads this verbatim]
343
344### <next leaf>: ...
345```
346
347**spec.md** (canonical, `.claude/plans/<slug>/spec.md`) — from `spec.template.md`:
348- Master engineering specification — born in PLAN (v3.8 Feature 2.2: trio born together)
349- Architecture overview from design doc
350- Data model, interfaces, contracts
351- Requirements traced to design
352- Status: APPROVED (CAPTURE re-affirms on cycle-end, no longer the birth-point)
353
354**prompt.md** (canonical, `.claude/plans/<slug>/prompt.md`) — from `prompt.template.md` — **v3.8 Feature 2.2: born in PLAN, not CAPTURE.**
355
356It is a SELF-CONTAINED prompt: a fresh AI session reading only this prompt + the linked spec.md + plan.md can re-execute or extend the work without prior context. See `prompt.template.md` for the full skeleton (Context / Constraints / Acceptance criteria / Deliverables / How to re-execute / What you DON'T need to know).
357
358The trio (plan.md + spec.md + prompt.md) is the cold-executor handoff contract. Born together in PLAN — from the versioned templates above — so standalone planner-module invocations (`/li:plan <design.md>` without a surrounding cycle) produce a complete handoff. CAPTURE re-affirms the trio (verifies presence, updates with final-build evidence) but no longer generates prompt.md.
359
360**.planner-checkpoint.md** (`.claude/runtime/state/`):
361- State for `/li:resume`
362- Includes plan.md path, current task pointer, build-log placeholder
363
364### Step 11a — Trio completeness gate (mechanical — issue I4)
365
366The trio is the cold-executor handoff contract; a 2-of-3 or empty member silently breaks every
367cold resume (gstack #1127/#1791). Before declaring PLAN done, assert all three exist and are
368non-trivial — this is a real check, not a prose promise:
369
370```bash
371# the plan dir just written (newest under .claude/plans/); the orchestrator may
372# also export LINTEL_PLAN_DIR — prefer it, else the most recent dir.
373slug_dir="${LINTEL_PLAN_DIR:-$(ls -dt .claude/plans/*/ 2>/dev/null | head -1)}"
374slug_dir="${slug_dir%/}"
… omitted uncited lines …
440- `scaffolding/01-foundation/templates/plan/{plan,spec,prompt}.template.md` (the canonical trio templates)
441- CORE-PRINCIPLES.md
442- the active pack's compliance gates (`resolve_pack_field compliance.hooks`; none by default)
443- Recent relevant ADRs
444- `.claude/memory/lessons.md` (via `/li:lessons-surface`, keyword-scoped, non-blocking)
445
446**Writes:**
447- `plan.md` (canonical)
448- `spec.md` (draft, finalized in CAPTURE)
449- `work.json` (schema version 1; optional additive swarm fields only after opt-in)
450- `.claude/plans/<initiative>/swarm/` (optional charter, topology, briefs, and evidence destinations)
451- `.claude/runtime/state/.planner-checkpoint.md`
452- `.claude/runtime/state/00-state.md` (PLAN entry)
453- `.claude/runtime/audit/plan-metrics.jsonl`
454
455**Triggers:**
456- BUILD with plan.md as canonical source
457- `/li:swarm` when the validated map explicitly selects the swarm profile
458
459## Recommended agents to dispatch (from discover-report)
460
461- **Planner** (engineering/) — primary, task decomposition
462- **Architect** (engineering/) — sanity-check tech choices
463- **BackendArchitect / FrontendBuilder / DataPipelineDesigner** (engineering/) — per domain
464- **APIDesigner** (engineering/) — if API surface
465- **DatabaseDesigner** (engineering/) — if schema changes
466- **TerraformReviewer / K8sManifestReviewer** (devops/) — if infra
467- **ADRDrafter** (engineering/) — if non-trivial decisions surface during planning
… omitted uncited lines …
504/li:cycle → SENSE → DEFINE → DISCOVER → PLAN → BUILD → REVIEW → SHIP → CAPTURE
505                                          ▲
506                                  reads DEFINE + DISCOVER outputs from job dir
507```
508
509**2. Standalone:**
510```
511/li:plan <design.md>
512   ↓
513   workflow_root: true → spawns own job at .claude/runtime/jobs/plan-<stamp>-<hash>/
514       (job auto-spawn is dormant by decision, ADR-0008 — the job-begin hook is
515        not auto-registered; the trio + approval gate below run regardless)
516   produces: plan.md + spec.md + prompt.md (the trio)
517   handoff-size-check against 500k cap (trio + warming)
518   founder approval gate
519   → DONE, ready for cold-executor handoff
520```
521
522**3. Sub-module called by another workflow_root skill:**
523```
524/li:cycle                    OR    /li:safe-install
525  ↓ discovery                       ↓ pre-flight
526  CALL /li:plan --from <design>     CALL /li:plan --from <change-spec>
527  ↓ receives trio                   ↓ receives trio
528  proceed to BUILD with trio        proceed to execute with trio