he-plan

Hard Eng Plan

• Output = saved PLAN.md: ready plan + UX reference when applicable + baseline evidence + execution recommendation + authorization boundary, or explicit blocking decisions. Planning may produce the plan, research + isolated previews; production implementation waits for readiness + authorization.
• Context = Hard Eng workflow. Reuse current repository evidence + settled decisions; load Research or Codebase Design only when needed.

Routes

Select from the user's intent + actual scope, not a keyword alone. Existing ready plan → continue within its authorization; material change → reopen only the affected decision.

flowchart TD
  T{Planning need} -->|Explicit Wayfinder / large unclear effort| W[references/wayfinding.md]
  T -->|Small clear change| S[Compact PLAN.md]
  T -->|Feature / substantial or multi-session work| P[templates/PLAN.md]
  W -->|Direction resolved; implementation requested| P
  S --> U{Visible change?}
  P --> U
  U -->|Yes| X[references/ux.md]
  U -->|No| R[Readiness + authorization]
  X --> R
  click W "references/wayfinding.md"
  click P "templates/PLAN.md"
  click X "references/ux.md"

Plan + questions

• Tracked evidence = apply publication privacy before writing plans or attaching evidence.
• Both sizes = PLAN.md; one plan per effort at root or features/<slug>/PLAN.md (filename case-insensitive). Reuse it. Write brief fields + behavior → proof checkboxes, not narrative paragraphs; link detailed evidence instead of copying it. Fill every section; N/A — reason must follow repository facts. Unavailable tools, failed checks + missing proof are blockers, never N/A.
• Questions = inspect repository facts first; ask only user-dependent choices that can change outcome, UX, scope or material risk. Resolve prerequisite choices first; batch independent questions with a recommendation + consequences. Never supply the human's answer or treat silence as approval. Clear request → no ritual interview.
• Setup/adoption/update = follow integration setup for intended services, hosting, existing choices and real host readiness; greenfield imports alone cannot identify future integrations. New Flutter app = Riverpod per Building Flutter Apps.
• Proof = reconcile every material requested behavior + preserved constraint with an intended check + observable expected result in Acceptance + steps; explicitly mark exclusions or blockers. Fill the template's E2E: disposition separately from ux_reference: unchanged appearance does not waive an interaction journey. Use test design + E2E for applicable proof. Ready needs planned feature proof + actual baseline/UX evidence; Complete needs actual feature results. Deployment-only E2E requires Deploy and a configured verifier, never a Merge target that closes before runtime proof.
• Delivery = keep build acceptance local; retain the authorized destination + pending remote proof in Verification for HE Ship. Local Complete precedes shipping. Before UI implementation, retain the actual baseline for the later PR comparison even when planning used a mock; prepare task isolation.
• Flow gaps = for material state, permission, recovery or cross-system behavior, inspect existing entry points, relevant branches and success/failure/recovery outcomes before Ready. Reuse existing handlers; resolve consequential unspecified behavior through the questions above and carry the scenarios into acceptance. Settled low-risk work needs no extra walkthrough.
• Uncertainty = for a consequential unverified technical assumption, record current evidence, the cheapest discriminating check + what changes if false. Resolve planning-owned facts through research or an authorized isolated prototype; keep build-dependent details explicit for implementation. Unresolved product choices remain blockers; helper names and low-impact details do not.

Before handoff

• Baseline (Start Gate B) = run the Draft check on the starting implementation after planning/UX, before approval or implementation; previews must not contaminate it. Reuse only matching code/configuration/environment evidence. Record command + actual result in the plan. Failure → baseline repair; no baseline waiver.
• Sequencing = each substantial slice delivers observable behavior; choose an early thin slice that exercises consequential uncertainty when present. Parallel work needs agreed dependency interfaces + a named integration check; avoid a nominal slice that leaves the risk untouched.
• Execution recommendation = smallest suitable arrangement for this plan: one builder for contained work; independent work may run in parallel; substantial work benefits from a fresh verifier. Name responsibilities, dependencies and actually available model/tool capabilities; do not invent model availability, force four agents or dispatch while planning. Respect existing delegation limits.

Participation

Apply the existing Human-loop or Autonomous mode; that owner defines proposal approval, progress and authority boundaries.

Readiness + authorization

• Ready = outcome + boundaries understood; material blocking choices resolved; applicable ux_reference shown and its direction settled within the task's participation mode; baseline passed and any prerequisite repairs delivered; planned acceptance checks + actionable first step + execution recommendation. Deferred uncertainty stays explicit and must not contradict the authorized scope. After this passes and implementation is authorized, explicitly tell the user: Ready for build — plan and baseline are verified; implementation is starting. Do not use this handoff while proof is pending or blocked.
• Authority = user's conversation instructions under the participation rule above; plan records their scope, not a self-issued permission. Reuse valid proposal approval or autonomous authorization. Otherwise show the completed plan and ask once to proceed; plan-only requests end with the saved PLAN.md, not a chat-only plan.
• Approval covers outcome + boundaries. File/step/test/internal approach changes → update the same plan and continue. Changed outcome, material scope/risk or an unauthorized consequential action → resolve that boundary only. Plan edits do not expire approval; no hashes, receipts or approval commands.
• Plan checks = pass the Ready check once material choices are resolved and before authorized implementation; missing previews keep the plan Draft. A proposal awaiting choices stays Draft with Handoff: Approval; a settled proposal may pass Ready before final combined approval. Review evidence + N/A reasons against actual work: a structural pass proves neither truth, scope relevance, authority nor chronology. Host-native read-only controls remain separate.
• Draft handoff = declare Handoff: Clarification or Handoff: Approval in Decisions + authorization. Clarification needs a concrete prerequisite in Blockers (for example, which application is in scope); it may pause before UX/baseline work. Approval includes asking the user to accept recommendations or choose between prepared proposals: show the relevant flow/states first and fill baseline, UX + planned E2E evidence. Do not label a proposal review as clarification. Stop enforcement = plan checks; feedback grants no authority. Older active Draft plans must choose the appropriate handoff before pausing.
• Handoff = ready + authorized + implementation requested → continue through Hard Eng. Discovery-only Wayfinder sessions retain their charting/one-ticket stop boundaries.