plan-authoring

name

plan-authoring

description

Author an executable, phased implementation plan under docs/plans — first gather real context from the repo and docs, debate the ambiguities, trade-offs and open decisions with the human, and only after explicit human confirmation write the plan. Produces Master Plans (a directory with a bootstrap entry point, master overview, and one self-sufficient file per phase) or Focused Plans (a single file), each with persistent checklists and per-phase executable prompts, so a fresh agent can run one phase per chat with no conversation memory. Use when the user asks to plan, design an implementation, break work into phases, or create a plan for a feature/module/migration/refactor.

Plan authoring — executable plans skill

Author an executable implementation plan: a structured, phased plan a coding agent later runs step by step, with the decisions already made. This is the "Plan" half of the spec-first pipeline in docs/process/02-ways-of-working.md; the discipline it must satisfy is .agents/rules/25-executable-plans.md. The companion review skill definition-of-done checks a change against its plan once the work is done — this skill writes the plan.

Read AGENTS.md and the applicable .agents/rules/ first, as always.

The one rule that shapes everything

Creativity belongs to the planning phase, not the execution phase.

Exploration, trade-offs, and decisions happen here, with the human. The finished plan records what was decided and why, so the executor implements rather than re-investigates. If a decision cannot be made now, the plan marks it explicitly open with rules for resolving it — it is never left silently for the executor to improvise.

Where plans live

docs/plans/ — gitignored except README.md (.agents/rules/25-executable-plans.md). Plans are local working artifacts; do not commit them and do not un-ignore the folder. Continuity between agents comes from the files and their checklists, not from git.

Plan files follow the folder's docs frontmatter convention (title / order / category: Plans / summary / author / date) — see the existing plans and templates. date is the authoring date; bump it on substantive edits.

The flow — do not skip a stage

Stage A — gather context

Before proposing anything, build real understanding. Do not invent files, commands, APIs, or decisions that do not exist (.agents/rules/00-agent-behavior.md).

Establish, from the user and from the repository:

• the problem and the goal; the expected functional behavior;
• constraints, technical requirements, and the relevant architectural decisions;
• risks; acceptance criteria; what is explicitly out of scope.

Inspect the repo and docs/ as needed to ground this: the affected services/apps, their AGENTS.md and .agents/rules/, the architecture docs, existing patterns, and any existing plan the work relates to. docs/ is the source of truth.

Ask for what is missing rather than assuming it (.agents/rules/03-surfacing-gaps-and-incomplete-work.md).

Stage B — debate with the human

Planning is a conversation, not a transcription. Before writing, surface and resolve:

• ambiguities and pending decisions;
• contradictions with the docs, the rules, or the request itself;
• alternatives where several reasonable solutions exist, with their trade-offs;
• scope and expectations — confirm what is in and out.

Drive every material decision to a resolution the human agrees with. The goal is that the final plan leaves no important decision open for the executor.

Stage C — human confirmation (a gate, not a formality)

Do not write the definitive plan until the human confirms that: the context is sufficient, the main decisions are made, the scope is clear, the relevant risks are covered, and the implementation strategy is acceptable. Ask explicitly. Only then proceed.

Stage D — write the plan

Pick the plan type (below), copy the matching template from templates/, and fill every section from what Stages A–C settled. Then confirm the files written and how to run them.

Choosing the plan type

• Master Plan — a large or strategic initiative: a full capability, a new module, an architectural migration, a major integration, a cross-cutting refactor, anything spanning several phases and sessions. → a directory.
• Focused Plan — a bounded change: one feature, a small migration, an architectural correction, a task the size of this skill itself. Same precision, fewer phases. → a single file.

When unsure, ask the human; do not default to the heavier form.

Layout and naming

Reuse the folder's NN-<slug>.md convention; lowercase, hyphen-separated slugs.

Focused Plan — one file:

docs/plans/NN-<slug>.md

Master Plan — a directory, phases in their own files:

docs/plans/<slug>/
  00-bootstrap.md        # execution entry point (preamble) — start/resume here
  01-master-plan.md      # goal, scope, decisions, phase index, global checklist
  phases/
    01-<phase-slug>.md   # one self-sufficient, independently executable phase
    02-<phase-slug>.md
    ...

Templates: templates/master-plan.md, templates/bootstrap.md, templates/phase.md, templates/focused-plan.md.

What every plan must contain

From .agents/rules/25-executable-plans.md, the required structure:

• Objective — what and why.
• Scope — what is included.
• Out of scope — what must not be done (guards against executor scope creep).
• Context & decisions already made — functional and technical decisions, constraints, confirmed assumptions, discarded alternatives, and the reasons for the important ones. Executors do not re-debate these.
• Relevant current state — what exists, which components change, dependencies, which docs must be respected.
• Phases — see below.

Phases

Order phases inner-to-outer, foundations first — never wire before the contracts and inner layers it depends on exist. For the backends use the Clean Architecture order in docs/software-architecture/01-clean-architecture-backend-and-identity.md (value objects → enums → domain errors → domain types → entities → aggregates → invariants/policies → domain services → ports → application DTOs → use cases → application ports → adapters → persistence → external integrations → transport → composition root → end-to-end). For the AI layer, web, or mobile use that project's architecture doc. The principle is fixed; the layer names follow the project.

Each phase must be self-sufficient — runnable in a fresh chat without prior conversation — yet must not duplicate the whole master plan. Each phase file contains:

• objective of the phase and the context it needs;
• preconditions;
• the exact work to do, in the expected order of implementation;
• files or areas likely involved, when identifiable;
• constraints and an explicit "do not do" list;
• acceptance criteria and mandatory validations;
• the tests required, and the quality / security / privacy checks;
• the conditions for the phase to be considered done;
• a persistent checklist;
• an executable prompt for the agent that will run the phase.

Checklists are the progress source of truth

Every phase carries a persistent checklist inside its file. The executor updates it on completion — do not represent progress with prose alone. Any future agent must be able to read the checklists and see immediately what is done, what remains, what was partial, and the correct next action. Tailor each checklist to its phase; a starting shape:

## Checklist

- [ ] Value objects / enums implemented
- [ ] Domain errors implemented
- [ ] Domain behavior + invariants implemented
- [ ] Ports defined
- [ ] Application use case implemented
- [ ] Adapters / persistence implemented
- [ ] Wiring completed
- [ ] Tests added (unit / integration / e2e as required)
- [ ] Quality gates passing
- [ ] Security review completed
- [ ] Privacy review completed

The per-phase executable prompt

Each phase ends with a concrete prompt for the agent that runs it. It states which phase this is, what to read first, the objective, exactly what to implement and in what order, the constraints to respect, the validations to run, when to stop, and which checklist to update. Optimize it for a coding agent: use concrete, verifiable instructions. Avoid vague phrasing — no "implement the necessary changes", "update the code accordingly", "fix whatever is needed", "refactor as appropriate".

The bootstrap file (Master Plans)

Every Master Plan includes 00-bootstrap.md, the standard entry point to start or resume execution. From templates/bootstrap.md, it tells the executing agent that it is running a multi-phase plan and must: read the current plan state, inspect the checklists, identify which phases are complete, determine the next pending phase, work only on that phase, not redo completed work, not anticipate future phases, not change scope without authorization, and update the corresponding state when finished. This is what makes the plan recoverable across agents and sessions without conversation memory.

Bake the mandatory checks into the plan

Do not restate the rules in the plan — reference them and make each phase's checks concrete and proportional to what it touches:

• Quality gates — the real repository commands, discovered, not invented: make fmt, fmt-check, lint, check, architecture-check, test, test-full from the root (target state; per-service fallback), per docs/process/05-definition-of-done-and-quality-gates.md. Confirm what exists with make help before citing a target.
• Security — proportional to the surface, per .agents/rules/05-security.md and .agents/rules/24-security-and-compliance.md (authn, authz, trust boundaries, input validation, injection, secret handling, sensitive-data logging, error leakage, tenant isolation, secure defaults). No generic controls unrelated to the change.
• Privacy — when the change touches data: PII, minimization, retention, logging, telemetry, exposure, cross-tenant access, deletion, sub-processors, and the LLM data boundary (.agents/rules/19-llm-data-boundary-and-code-egress.md). Repository rules win.
• Data access — .agents/rules/20-persistence-and-postgresql.md and .agents/rules/21-query-services.md: no N+1 under any circumstances; name and design out any 0+N shape; bound and paginate; batch and use set-based operations. Solve this in the design, never after building an architecture that introduces it.

Execution discipline the plan must enforce

The plan itself must make the executor's rules explicit (they are in .agents/rules/25-executable-plans.md): stay within the current phase; no opportunistic refactors or scope additions; no advancing via patches, workarounds, disabled tests, weakened validations, or known regressions — stop and ask instead; classify discoveries as plan-compatible (resolve + document) or plan-altering (stop + ask for consent). The executor implements the plan; it does not re-open decisions already made here.

Output

When the plan is written, report concisely: the files created, the plan type, the phase count, and how to start execution (for a Master Plan: "open a fresh chat and paste 00-bootstrap.md"). Do not begin executing the plan — this skill authors; execution is a separate step the human triggers.