/plan-md-authoring

name: plan-md-authoring
description: How to write the initial PLAN.md at the start of a John project. Use this skill whenever the user has just run /john:init, when there is no PLAN.md yet, or when the user says "let's start a new project" / "design the plan" / "what should we build." PLAN.md is the durable contract that spans knowledge engineering (knowledge phases) and app building (app phases) in ONE session — get it right at the top or every phase pays for it.
metadata:
  triggers:
    - write PLAN.md
    - author the plan
    - design the plan
    - initialize plan
    - start of project
    - start a new project
    - no plan yet
    - what should we build
    - design the app-type definition

plan-md-authoring

You are writing PLAN.md for the first time on a new John project. After this, [[plan-md-evolution]] takes over — this skill is just the bootstrap.

The plan is not a recipe. It's a **wide-tunnel agreement** between you and the user about what's being built, how the work decomposes into phases, and where the open decisions are. Too narrow and you'll regret it in two phases when the corpus surprises you. Too loose and you'll re-derive everything every iteration.

When to start writing

After `/john:init` has scaffolded `<project>/.john/` and put the user's input materials in `<project>/.john/input/`. Before you've parsed anything. Before you've decided on a knowledge schema.

The plan should be **written through a conversation with the user**, not generated unilaterally. If you find yourself filling in sections without asking, stop and ask. You only get one chance to shape a project at the top — don't waste it on assumptions.

The skeleton

PLAN.md has these sections in this order. Some come from your conversation with the user; some you fill in as the project progresses.

# PLAN.md — <project name>

## Project intent
<what the produced app does, who uses it, what it consumes, what success looks like>

## Knowledge inventory (from the knowledge phases)
<initial: pointer to .john/input/ and a one-line corpus profile
 over time: pointers to <project>/.claude/skills/ and <project>/.agents/skills/ once the knowledge phases ship>

## App-type definition
- Knowledge format: <facts? rules? stories? wiki? mixed? — initial guess, may evolve>
- Knowledge schema: <starter sketch; expect to iterate>
- App mechanism: <how the produced app works for end-users>
- Build pipeline: <the rest of this doc — phases that build the app>

## Phases
### Phase 1: <name>
- Intent: <one sentence>
- Subagent assignments: <if vertical fan-out, what's the unit?>
- Execution: <Workflow yes/no; if yes: worker agent + cross-check agent + model — see [[vertical-workflows]]>
- Skills to invoke: <[[skill-1]], [[skill-2]]>
- Required artifacts (disk-verifiable): <paths the engine can check>
- Done criteria: <observable conditions; not "feels finished">

### Phase 2: ...
...

## Subagent matrix
<for any phase with vertical fan-out, the list of work units and current state.
 may be empty at first, fills in as phases hit fan-out points>

## Open decisions
<things you want the user to weigh in on before you barrel forward>

## Log
<append-only, most recent first. dated entries:
 - phase advances ("Phase 2 done, X artifacts produced")
 - decisions you made and why
 - blockers you wrote to "Open decisions"
 - user instructions received mid-flight>

What goes in each section — the taste calls

**Project intent.** Specific enough to disambiguate ("a study companion that quizzes the user on chapter content"), wide enough not to overfit ("a study companion" alone is fine; "a Next.js SPA with React 19 and Tailwind 4" is too narrow at intent-time — that's a runtime decision). The intent should still make sense if you change app mechanism later.

**Knowledge inventory.** Initially just a pointer + one-line profile of the corpus: "10 PDFs, ~2000 pages total, financial regulations in Chinese." Don't speculate about what'll come out yet. After the knowledge phases ship, this becomes a pointer to the produced skills.

**App-type definition.** Knowledge format / knowledge schema / app mechanism / build pipeline are a **cascade** — each constrains the next. [[schema-design]] teaches the cascade methodology in depth (and the corpus-survey step that grounds it); your job in this section is to *apply* the cascade, not re-explain it. Sketch each structure for *this* project with the user, and explicitly mark each "may evolve." Two cheap commitments worth writing in here from day one: the extraction phase opens with a **schema pilot** (diverse sample before mass extraction — [[schema-design]]), and entries carry a **`schema_version`** field so later schema changes stay detectable and migratable.

This section is the user's project taste applied. Wide tunnel — sketch loose, iterate as the corpus reveals itself. The cascade's order matters: settle format first, derive schema, derive runtime, derive pipeline. Reversing the order over-fits.

**Phases.** This is the build pipeline. For the knowledge phases, John suggests a starter (parse → survey → schema-design → chunk → extract → rewrite → package, see [[phase-design]]) but the user or active template can override. For the app phases, they come from your conversation about the app mechanism. Don't try to nail every phase at start — leave the last few as "TBD: decide after phase N" if you genuinely don't know yet.

**Subagent matrix.** Often empty at PLAN.md authoring time. Fills in when a phase hits fan-out. For a large uniform fan-out, note whether the phase runs as a dynamic workflow ([[vertical-workflows]]) or inline dispatch ([[subagent-dispatch]]) — the work units and event paths are the same either way.

**Open decisions.** Be brave about putting stuff here. "Open decisions" is the user's chance to weigh in; if you suppress your uncertainty, you'll guess wrong and waste a phase.

**Log.** Append-only. Most recent first. Real reverse-chronological de