aetherbound-guild/docs/runtime/PLAN_DRIVEN_DEVELOPMENT_PROTOCOL.md

Aetherbound Guild Plan-Driven Development Protocol

Applies to every future implementation milestone in this repository. It is a process contract, not a substitute for the active Goal or milestone contract.

Purpose

Keep product work understandable and recoverable. Every code change must serve one written player-visible outcome, one bounded implementation step, and one focused evidence boundary. Work does not advance because a command ran; it advances only after the written acceptance checks pass and the focused commit is pushed.

Required Order

Before editing code:

1. Read AGENTS.md, the active Goal, contract, checkpoint, plan and ledger.
2. Record the task envelope: role, target, authority, baseline, worktree owner, frozen scope, evidence floor, process state and one next action.
3. Update the active plan so exactly one step is IN_PROGRESS.
4. Name the files the step may change and the files it must not change.
5. Define the smallest player-visible stopping point and its acceptance checks.

During a step:

1. Make only the changes owned by that step.
2. Test from cheap to expensive: static, focused behavior, regression, simulation, runtime and then packaging only when separately authorized.
3. Treat the earliest failed boundary as the current issue. Do not skip it, loosen a check, or silently widen scope.
4. Keep failed or invalid attempts append-only and source-bound.
5. Do not start another feature while a step is failing or while its evidence is incomplete.

After a step:

1. Record the exact marker, command, source revision and evidence path.
2. Update the plan, checkpoint and append-only ledger.
3. Stage an explicit path list and inspect the staged diff.
4. Commit one focused change, push it, and verify HEAD == upstream and a clean worktree.
5. Stop at the legal terminal. The next step starts only after the previous step is complete and its stopping point is recorded.

Step Template

Every step in an implementation plan must contain:

ID:
PLAYER OUTCOME:
IN SCOPE:
OUT OF SCOPE:
OWNED FILES:
ACCEPTANCE CHECKS:
EVIDENCE LEVEL EXPECTED:
COMMIT BOUNDARY:
LEGAL TERMINAL:
NEXT STEP:

Exactly one step may be IN_PROGRESS; all others are COMPLETE, PENDING, or BLOCKED. A new finding belongs in the issue register until the current step is either repaired or formally closed.

Evidence And Human Gates

Use the repository evidence levels literally:

implemented -> automated_verified -> simulation_verified -> runtime_verified -> agent_visual_reviewed/machine_audio_checked -> human_reviewed -> device_verified -> release_accepted.

Never promote a lower level into a higher one. A screenshot does not prove touch, a simulated touch does not prove a physical device, and an automated comprehension check does not replace Owner play. Human understanding, fun, visual/audio acceptance and willingness to continue remain open until the Owner or a fresh player supplies that evidence.

Scope Guardrails

• One development session owns this repository unless the Owner explicitly authorizes a different topology.
• Do not use multi-Agent delegation for ordinary implementation in this plan.
• Do not mix other games, packaging, TestFlight, stores, release or bulk media generation into a gameplay step.
• Do not expand chapters, professions, enemies, economy or persistence while the current layer has not proven its player decision.
• Do not rewrite accepted design authority to make implementation pass. Record a contradiction and repair the earliest authority boundary first.

Stopping Rule

The work is complete for a milestone when its written player outcome is playable, its declared evidence is recorded at the actual level, the focused commit is pushed, the repository is clean/upstream, and one shortest next action is written. Anything beyond that stopping point requires a new plan or an explicit Owner scope change.