Planning Workflow

Standards metadata

ID: workflow.planning
Role: workflow
Level: MUST
Applies when: Material uncertainty about intended behavior or design must be resolved, or work requires sequencing, shared decisions, migration, delegation, or acceptance across multiple boundaries.
Does not apply when: A bounded local change has a clear agreed outcome, an obvious write set, a regression check, and an acceptance path, with no material uncertainty that could change those decisions.
Requires: core, workflow.implementation, workflow.verification, workflow.development-proportionality
Specializes: none
Verification: Active-plan structure fixtures and objective-level acceptance review.
Canonical owner: workflows/planning.md

Discovery Before Implementation Planning

Begin with the intended outcome and the facts needed to choose a suitable design. When material intent, behavior, constraints, or design choices remain unresolved, use Discovery And Design before writing the implementation plan. Discovery is the opening phase of this workflow; it is not an approved implementation direction.

Use an adaptive conversation supported by bounded investigation. Establish what the person is trying to achieve, distinguish firm requirements from suggestions and hypotheses, inspect current behavior and technical feasibility, and make consequential alternatives and implied behavior visible. Explain the emerging design back to the person before converting it into implementation work.

Do not treat a suggested mechanism, the current code, or the first plausible architecture as the objective. Apply the routed standards to the actual design decisions; a plan that merely lists standards does not establish that its design meets them.

Keep the effort proportionate. A small, clear task may need only a brief exchange and a concise explanation. Do not manufacture uncertainty, a questionnaire, a written plan, or an approval ceremony when the outcome and acceptance path are already clear. Conversely, the bounded-local exclusion does not apply merely because a proposed patch is small when its intended behavior remains materially unclear.

For substantial discovery, keep the main agent available for conversation while research agents investigate independent questions and a separate visual-document agent maintains the local shared picture. Follow the detailed procedure for ownership, unavailable capabilities, and the transition to canonical planning artifacts.

When A Written Plan Is Required

After resolving material intent and design uncertainty through discovery, apply the bounded-local exclusion before the written-plan triggers. A change with a clear objective, exact write set, regression check, and acceptance path may proceed directly even when it touches a public, generated, persistence, process, language, or user-interface boundary. State its write set inline; an exact write set does not require a plan artifact.

Create a written plan when the change introduces material sequencing, independently owned contract, migration, coordination, rollout, risk, or acceptance complexity that must remain stable during implementation. A boundary or file category alone does not satisfy this condition. Parallel work requires a plan only when ownership, dependency, integration, or stale-state coordination is material.

Artifact Model

Store a planned effort under one directory:

docs/plans/<plan-slug>/
  plan.md
  execution-ledger.md
  issues.md
  reports/

plan.md owns current objective, binding decisions, status, milestones, blockers, and exactly one next slice.
execution-ledger.md owns dated slice, verification, deviation, and commit summaries.
issues.md owns discovered issues and their dispositions.
reports/ owns investigations and detailed evidence.
ADRs own durable architecture decisions that outlive the plan.

Give each current decision one active owner and link to it from consumers.

Required Active-Plan Fields

An active plan states:

plan status;
objective and scope;
objective acceptance claims;
current acceptance status;
constraints and assumptions that affect decisions;
binding decisions and owners;
composed-design review applicability and, when applicable, the complete Architecture-owned artifact probe;
current phase;
exactly one next slice or none for terminal status;
milestones with goals, write sets, gates, and lifecycle states;
blockers;
re-plan triggers; and
links to ledger, issues, reports, and ADRs.

Use the plan template.

Every nonterminal written plan governed by this revision records the composed-design review as applicable or not-applicable. When applicable, answer every artifact probe in Architecture. When not applicable, record the concrete reason. Historical terminal plans are not rewritten solely to add this field.

Lifecycle

Discovery notes, candidate designs, and visual documents are provisional and do not acquire Planned status by being written. Planned continues to mean approved direction. Do not authorize implementation from a discovery artifact or add a discovery state to the implementation-plan lifecycle solely to store a discussion.

State	Meaning
`Planned`	Approved direction; implementation has not started.
`Active`	The current phase or slice is being implemented.
`Blocked`	A named dependency or required fact prevents progress.
`Implemented`	Source work is complete; objective acceptance is pending.
`Verifying`	Objective-level acceptance is running or awaiting environment.
`Accepted`	The named acceptance evidence passed.
`Deferred`	Work is intentionally excluded with owner and revisit trigger.
`Superseded`	A newer binding decision or plan replaces this item.

Implemented is not complete. Accepted requires every objective acceptance claim to be satisfied.

Exactly one current phase is identified. Multiple independent milestones may be implemented, but the active plan still names one next integration slice.

Explicit Plan Admission

Bind planned implementation to one canonical repository-relative plan.md path and one operation. A human follow-up may reuse an unambiguous selection already established in the conversation after checking current repository state, plan lifecycle, and authority. Obtain clarification when either selection is missing or ambiguous. Repository location, recency, and a next-slice field alone do not establish the selection or authorize execution.

Machine interfaces retain their declared explicit path and operation arguments. Conversational reuse supplies task context; it does not relax an API contract.

Planning owns these admission decisions:

start accepts only Planned and transitions it to Active;
continue accepts only Active without changing that state; and
verify accepts Implemented or Verifying, transitioning Implemented to Verifying when objective verification begins.

Blocked and Deferred are unavailable; report the blocker or revisit authority. Accepted, Superseded, and operation/state contradictions are invalid. Missing plan identity, operation, lifecycle facts, or required linked artifacts are unavailable. Security owns containment and traversal or symlink escape rejection; unsupported filesystem representation routes conditionally through Cross-Platform. Establish the operation and its authority through the binding rules above before implementation.

Concurrent Integration Routing

Ordinary planning does not require a revision digest, transition envelope, or reconciliation identity. Apply the Concurrent Plan Integration profile only when two or more proposals may be prepared from the same mutable plan revision before integration and correctness depends on detecting whether plan or shared-authority state changed before a proposal is integrated.

Do not select the profile merely because several people or agents participate. Serial collaboration, read-only investigations, non-authorizing reports, independent work whose admission facts cannot become stale, and one integration owner working from current state with no outstanding proposals remain under this workflow alone.

When the profile applies, it owns proposal revision checks, stale-state classification, compatibility, and reconciliation. This workflow continues to own plan lifecycle and artifact boundaries. Shared authority remains a serial integration-owner write in either case.

Repository Isolation In Written Plans

A written plan does not require a branch or worktree by default. When material review, concurrency, experimentation, release maintenance, risk containment, or repository controls make isolation part of the accepted approach, record the branch or worktree purpose, responsible owner, target branch, integration owner, visibility or long-lived status, and expected terminal disposition. When the plan authorizes worktree removal or registration pruning, also record the head-reachability and commit-disposition evidence required by Commit. Record an admitted base or revision only when stale-state coordination makes it relevant.

Commit owns ordinary branch selection, integration mechanism, history, and terminal cleanup. This workflow records only plan-level facts needed to keep scope, ownership, sequencing, or acceptance stable. File count, commit count, plan existence, delegation, and participant count do not independently require repository isolation.

Discuss material development and integration boundaries before implementation. Explain what coherent outcome each boundary makes visible or reviewable, what evidence supports it, and which findings would reopen the design. Where branches or merges serve that purpose, identify their intended role and integration points using Commit's Branch And Worktree Applicability, Governed Branch Context, and Integration Mechanism Selection rules.

These boundaries provide visibility into development and useful opportunities to reconsider direction. They do not require a branch per milestone, a merge per slice, a fixed commit count, or a particular history topology. If one serial change provides sufficient visibility and acceptance, say so. Commit retains authority over the actual branch, worktree, merge, history, and cleanup mechanics.

Policy Projection Completeness

A normative change updates every materially affected distribution and enforcement surface. Identify its canonical owner, declared semantic consumers, and review coverage. Review the returned consumers and explicitly declare missing actual relationships. An incomplete inventory remains an evidence need.

Keep one canonical requirement owner. Prompts, templates, examples, and automation project that owner's contract. When a rule prescribes a machine protocol, representation, or automated gate, bring its applicable consumers into agreement before the rule becomes mandatory. Select those surfaces from actual use.

Keep current relationships with their canonical authority and change-specific dispositions in the change record. Preserve the distinction between normative dependencies, descriptive support, optional references, and semantic impact. Use owned, distinguishable diagnostic outcomes; manual processes can record them in prose or tables, and tools use their declared contracts.

Standards-maintenance-specific declaration and publication procedures belong to the normative authoring owner workflow.standards-authoring, retrieved through the authoring interface when maintaining the library.

Acceptance Claims

Resolve an external-interface or environment assumption that could invalidate the design through the smallest adequate real observation before expanding implementation around it. Name the decision the observation can change and its stopping condition. Continue bounded independently useful work when the unavailable observation cannot change that work's decisions.

Distinguish this design observation from final acceptance evidence. For a remaining environment-qualified claim, name its owner and executable procedure; require hardware, credentials, or a vendor service only when the claim depends on them. Identify real producers, consumers, and the complete observable result.

Follow the verification workflow. Record each required claim with:

stable identifier and observable criterion;
evidence kind;
required environment;
execution mode;
pending, blocked, or satisfied status; and
evidence link when satisfied.

The plan-level acceptance status is:

Status	Meaning
`pending`	No required claim is satisfied yet.
`partial`	Some claims are satisfied and at least one remains pending.
`blocked`	At least one required claim cannot currently be run.
`satisfied`	Every required claim is satisfied.

Evidence kinds, environment requirements, and execution modes are independent. Do not treat manual, environment-qualified, or artifact evidence as higher positions in one hierarchy.

Milestones And Slices

Order milestones by dependency. For each milestone record:

one goal;
one coherent implementation unit;
exact allowed write set;
semantics or contracts preserved/replaced;
focused tests or fixtures;
objective-relevant verification gate;
re-plan conditions; and
lifecycle state.

Select one coherent implementation unit. Split it only when separation materially improves independent acceptance, risk containment, dependency ordering, conflict isolation, rollback, or feedback. A bounded change that can be understood and verified as a whole is one slice regardless of how many files or layers it touches. Do not split work merely to minimize diff size or satisfy a preferred commit cadence.

A written plan may contain one milestone and one implementation slice, and the complete requested change may be that slice. Prefer thin vertical milestones only when separation produces useful acceptance, risk reduction, or dependency ordering. For cross-layer work that benefits from separation, prefer a real vertical path before horizontal expansion. Do not substitute a headless path when the objective is user-facing. File count, layer count, line count, and commit cadence do not decide slice count.

Plans define semantic work, dependencies, evidence, and lifecycle; they do not own Git commit topology. Do not prescribe commit count, parentage, direct-child chains, exact-HEAD admission, or standalone lifecycle commits. Bind review to the identified material content or candidate revision, and require re-review only when that reviewed meaning changes. Adding review evidence or recording an unchanged lifecycle result does not invalidate the reviewed subject. Collect a review round's findings before revising material plan semantics. Record lifecycle changes with the coherent implementation, re-plan, accepted boundary, or final evidence that caused them; Commit owns the resulting commit boundary.

Current Plan State

Keep plan.md concise and current:

replace old binding decisions when re-planning;
mark the old decision Superseded in the ledger or ADR history;
move dated implementation detail and command output to the ledger/report;
remove completed task narration when milestone state and evidence link are sufficient; and
compact the plan when history obscures objective, blockers, or next slice.

Automated verification may inspect current plan structure and current authority. It must not use accepted historical narration in an active plan as migration, behavior, or lifecycle authority. Canonical package, disposition, lifecycle, and evidence records own those claims; the ledger and reports retain history. Perform this ownership review at completed-wave boundaries without using an arbitrary line-count trigger.

Keep one current interpretation and preserve superseded reasoning in history.

Re-Planning

Repair failed checks within the current slice while its objective, authority, ownership, contract, risk, and acceptance meaning remain valid. Add an affected file to the write set when it remains inside that boundary. Replan when evidence changes those decisions or shows that the admitted slice cannot deliver its outcome.

Stop and re-plan when:

objective, authority, ownership, or constraints change;
required facts invalidate a decision;
gate evidence shows that the admitted slice cannot deliver its outcome;
compatibility, migration, security, data, or lifecycle risk changes;
a directly affected file outside the stated write set changes objective, ownership, contract, risk, or acceptance scope;
a lower-fidelity check was being used for a higher-fidelity objective; or
a new dependency changes sequencing;
a replacement design changes the admitted composition; or
cumulative machinery or observed change propagation materially exceeds the composed-design admission.

Re-planning must:

record the trigger and evidence in the ledger;
replace the binding decision in the active plan;
mark the prior decision or milestone Superseded;
update downstream milestones, gates, and next slice; and
re-run the composed-design artifact probe when its composition changed; and
obtain clarification when no standards-compliant decision is supported.

Do not inherit a prior design's composed-design review after a material replacement. The replacement owns a current applicability decision and, when applicable, current answers.

Retain fallback behavior only for a real contract permitted by the routed contract guidance.

Systemic-Finding Re-Planning

Treat a finding as systemic when it reveals duplicated semantic authority, incomplete projection, ambient authority, a public/internal boundary leak, an invalid evidence oracle, or another defect that can recur across an owning semantic family. Do not admit another local example-by-example repair until the owning invariant and its consumers are bounded.

Systemic re-planning must:

identify the invariant family and canonical owner;
bound every authority, representation, and reachable consumer whose behavior can violate the class-level claim;
inspect sibling operations and equivalent representations only where they share that authority, reachable failure, or consumer promise;
replace local acceptance examples with a class-level acceptance claim and independent evidence appropriate to that claim; and
give every selected consumer a non-blocked disposition;
consider deletion, consolidation, a smaller Interface, stronger construction or type proof, and replacement of overlapping evidence before adding machinery; and
compare the repaired composition with the original objective and any applicable composed-design admission before implementation resumes.

Expand the bounded population when evidence reveals a new semantic owner, reachable consumer, material risk, or public or persistence promise. Finding another implementation file inside an already bounded owner does not by itself expand the design or restart the search. Stop when the canonical owner and the reachable consumer population have evidence-backed dispositions; do not search every file, type, test, or historical representation merely because it can be enumerated.

Record whether the original finding was isolated or systemic and the evidence supporting that classification. An empty impact result is not proof of no consumers unless current audited coverage establishes completeness. Missing ownership, inventory, or coverage is unavailable; contradictory authorities or incomplete dispositions are invalid. Stop implementation rather than continuing a narrow repair under either condition.

Findings

Record each discovered issue in issues.md with:

ID, severity, and evidence;
relationship to the objective;
owner and affected boundary;
fix-now, defer, or re-plan disposition;
verification needed; and
revisit trigger when deferred.

Fix an issue in the current slice only when it is inside the write set and required for that slice's acceptance. Otherwise defer it explicitly.

Concurrent Work

Delegate only independent work with non-overlapping primary write sets. Record:

owner;
primary and allowed-adjacent write sets;
read-only context;
forbidden/shared files;
output and verification contract;
report path;
escalation rule; and
serial integration order.

Core contracts, schemas, generated artifacts, lockfiles, shared fixtures, workflow files, and active plans remain serial unless assigned to one explicit owner.

Workers may not delete branches, worktrees, user changes, or shared history outside their declared ownership. The serial integration owner may perform predeclared terminal cleanup for clean branches and worktrees created by the governed task after Commit-required terminal evidence is recorded. This does not grant general destructive authority or permit force-removing unknown, dirty, locked, user-owned, or uniquely committed resources.

Completion

A plan is accepted only when:

all non-deferred milestones are Accepted or Superseded;
plan acceptance status is satisfied;
every objective acceptance claim has matching evidence;
unresolved follow-ups have owners and triggers;
implementation files are resolved;
the ledger contains final verification and commit summaries; and
the active plan links to the final evidence.

After acceptance, retain the plan as a concise decision/result index. The ledger and reports preserve history.

FilesExpand file tree

planning.md

Latest commit

History