planning-protocol

name	planning-protocol
description	Creates or revises the evidence-based implementation contract in .agents/PLAN.md.

Planning Protocol

For Level 2+ tasks, create .agents/PLAN.md from templates/PLAN.md and record required review artifact types/paths. Level 1 tasks do not use this protocol or create a plan.

The plan is an implementation contract, not a brainstorming document, progress log, or code draft. It must explain what changes, where, in what order, and how correctness will be verified.

Quality bar

A scoped implementation agent should be able to execute its assigned task without:

• Rediscovering the relevant architecture.
• Choosing unspecified product behavior.
• Guessing contracts or ownership.
• Expanding scope.
• Inventing validation commands.

Planning workflow

1. Understand

   • Restate the requested outcome.
   • Identify success criteria and non-goals.

2. Investigate

   • Read applicable repository instructions and docs.
   • Inspect relevant code, callers, dependencies, configuration, and tests.
   • Trace current behavior across affected boundaries.
   • Confirm available validation commands from repository configuration.

3. Resolve

   • Separate facts, assumptions, and open questions.
   • Ask only questions that materially change implementation.
   • Mark unresolved non-blocking details as Unconfirmed.

4. Design

   • Prefer existing repository patterns.
   • Define changed interfaces, data shapes, validation, errors, persistence, and UI states where relevant.
   • Record one recommended approach.
   • Include alternatives only when a user decision is required.

5. Decompose

   • Order phases by dependency and deliverable value.
   • Give each task one owner and one verifiable outcome.
   • Include exact files, symbols, or bounded areas when known.
   • State dependencies and exclusions.
   • Keep tasks small enough for one focused agent run.

6. Verify

   • Define targeted checks first.
   • Add broader regression, security, performance, migration, or manual checks when risk warrants them.
   • Tie completion criteria to observable behavior.

Evidence rules

• A repository fact must come from inspected code, docs, configuration, or tests.
• Do not present likely files or commands as confirmed.
• Do not invent package scripts, APIs, schemas, or conventions.
• Do not add speculative refactors or unrelated cleanup.
• Do not include code unless a short signature or data shape is necessary to define a contract.
• Do not include timelines or effort estimates unless explicitly requested.

Task requirements

Every implementation task must include:

• ID.
• Owner.
• Outcome.
• Files or bounded area.
• Dependencies.
• Implementation notes needed to avoid ambiguity.
• Validation.
• Status.

Avoid tasks such as:

• “Implement backend.”
• “Update frontend.”
• “Fix tests.”
• “Handle edge cases.”
• “Refactor as needed.”

Execution modes

• continuous: understood, reversible, low-risk work.
• phase-gated: intermediate user inspection or manual validation is valuable.
• approval-gated: auth, authorization, payments, migrations, destructive changes, sensitive data, or large refactors.

Include only meaningful pause points.

Plan depth

• level-2: compact plan with repository findings and one or two phases.
• level-3: full plan with contracts, risks, review strategy, and dependency-ordered phases.
• level-4: full plan with explicit approval gates, rollback, specialized reviews, and failure recovery.

Revision rules

• The first planner pass writes .agents/PLAN.md.
• Reviewers read .agents/PLAN.md directly and write only orchestrator-assigned typed .agents/REVIEW_<type>-<n>.md artifacts.
• Read assigned artifacts directly. Record accepted/rejected disposition by <artifact-path>#F<n>; do not copy reviewer prose into the plan.
• After critique, revise only accepted finding references or explicitly documented risk decisions.
• During implementation, change the plan only when scope, contract, ordering, or risk changes.
• Record execution history in the active tracker, not in the plan.
• Do not append competing plans; update the affected sections in place.

Handoff

After writing the plan, return only a short summary containing:

• Created or revised.
• Complexity and execution mode.
• Required agents.
• Blocking questions or approvals.
• Unconfirmed items.

Do not paste .agents/PLAN.md into chat.