# Agent design and implementation workflow

Current policy, adopted 11 October and updated 15 October 2026. [AGENTS.md](../AGENTS.md) is the entry point;
[PROJECT_PLAN.md](PROJECT_PLAN.md) owns the current game brief and acceptance status;
[TESTING.md](TESTING.md) owns test selection, exact commands and evidence procedure.
Use this guide for gameplay/design experiments, substantial implementation, delegation
or uncertain review scope. A typo or isolated lookup does not require the whole guide.

### Task routing

Copyable examples for slices, fixes, reviews and general work are in
[workflow prompts](WORKFLOW_PROMPTS.md); load them when choosing a prompt, not for every task.

Classify the requested action before applying an implementation procedure. Loading a
skill, discovering a defect or seeing gameplay files does not expand authorization.

| Requested work | Route |
|---|---|
| Implement a runtime/gameplay feature, fix, refactor or experiment | Use [projecti-slice](../.agents/skills/projecti-slice/SKILL.md); classify actual risk, select required reviews/checks and close only the authorized slice. Ask human timing when playable behavior/human gameplay acceptance is affected. |
| Review existing work, including retrospective Ponytail review | Read-only review route below; select relevant perspectives against existing scope. No implementation pre/post ceremony or playable-checkpoint question. |
| Documentation-only edit | Proportionate document review/checks and scoped local commit closure; no routine playable timing question or Unity operation. Policy changes affecting authority, evidence or acceptance still require independent review. |
| Research, planning, lookup or explanation | Answer the requested question or produce the requested plan. No implementation agents, edits, tests, Unity operations or commits inferred; explicitly requested artifacts/actions retain their authorized scope. |

For mixed requests, separate authorized actions in one packet. Explicit no-tests/read-only
constraints win. Honor human review explicitly requested for any task; an excluded routine
timing question never removes a required approval or existing acceptance gate.

### Read-only review route

Establish the requested revision/milestones, current dirty diff, current project status and affected accepted requirements.
Select independent technical/gameplay/design-UX perspectives according to actual risk and
explicit requested coverage, without automatically deploying all three for every review.
Consequential existing authority/lifecycle/shared-state boundaries retain required coverage.
Give reviewers bounded read-only scopes; reconcile concrete findings and return prioritized
locations, failure scenarios, smallest corrections, recommended checks and evidence limits.
Ponytail adds completeness/correctness/simplicity inspection to those perspectives.

Do not repair findings, run tests/builds, operate Unity, stage or commit merely because a
review found a defect. Those actions require separate authorization. A retrospective supplies
current review findings, not historical pre-review, fresh automated proof or human acceptance.

## 1. Classify the actual boundary

Record the risk and reason in the task packet. Review effort and verification scope
are separate decisions: fewer reviewers never remove affected test/acceptance gates.
Classify by player impact, uncertainty, coupling and reversibility, not line count,
number of files, primitive artwork or the word "prototype". Escalate as soon as a
new boundary appears; do not wait for final review.

| Risk | Trigger and examples | Review requirement |
|---|---|---|
| High | Authority/RPC validation, session or object lifecycle, rewards/progression, persistence/schema, shared state ownership, or broad system coupling. Examples: revive/reset, portal participants, Keeper protection, proc/refund/defense changes affecting several systems. Uncertain consequential boundaries are high. | Three independent read-only technical, gameplay and design/UX perspectives before the implementation slice and against its integrated result. |
| Medium | Bounded behavior or presentation change with understood contracts and limited effects: a weapon tuning experiment, a local HUD layout, a narrow Editor/reporting change without lifecycle/identity changes. A settings-layout change preserves the existing local storage contract/schema. | Relevant independent specialist review before implementation and against the integrated result; record selected perspectives and why others add little. Escalate systemic tuning or newly discovered shared-state/lifecycle effects. |
| Low | Small, reversible change with no gameplay, shared-state, lifecycle, schema or significant presentation effect: wording/link repair, isolated lookup or mechanical documentation correction. | Lead inspection and appropriate focused checks; no automatic subagent team. Escalate if assumptions fail. |

A one-number damage/cooldown change can affect kill times, proc chains, refunds,
defense and spawn pressure. Trace those interactions before calling it bounded.
Documentation that changes authority, evidence or acceptance policy deserves
independent review even though it changes no runtime code. This policy revision
itself used all three perspectives under the previous policy.

## 2. Use one compact task packet

Keep one proportionate record of scope, risk/ownership, relevant requirements, checks,
evidence/omissions and stopping point for substantial reviews, documentation and implementation.
For runtime/gameplay slices, load the [implementation packet and player-experience guidance](../.agents/skills/projecti-slice/references/implementation.md#2-use-one-compact-task-packet).

### Human review timing

Playable implementation requires the [human-timing procedure](../.agents/skills/projecti-slice/references/implementation.md#human-review-timing)
at slice start. Supplied timing counts; silence changes scheduling only, never approval.
Pending acceptance blocks dependent promotion. Reviews/docs/lookups have no routine playable
question; explicit human-review requests still apply.

## 3. Distinguish exploration from promotion

For runtime/gameplay experiments or promotion, load the [complete exploration/promotion procedure](../.agents/skills/projecti-slice/references/implementation.md#3-distinguish-exploration-from-promotion).
Prototype labels never relax authority, accepted requirements or affected normal gates.
Campaign caps remain owned by the [retained record](PACK_ARRIVAL_VALIDATION.md).

## 4. Review, delegate and integrate

The risk table governs future generic review-selection wording in older plans.
It supersedes their blanket "three perspectives for every substantial slice" defaults,
not specific feature contracts, acceptance scenarios, approvals or historical evidence.
Explicit user requirements and specifically mandated feature reviews remain binding.
Read only the relevant plan sections and evidence; consult history when provenance,
an unresolved defect or a conflicting decision makes it necessary.

Give each reviewer a bounded packet of relevant accepted requirements/contracts, code or actual diff, evidence,
constraints, explicit question, read-only/file ownership and acceptance criteria. Do not require
each reviewer to reread the whole brief or chronology; include affected open acceptance gates.
Each independently returns recommendation, paths, concrete changes, risks, checks,
unresolved decisions and confidence/limits before seeing other conclusions.

- Technical: inputs/outputs, authority, serialization/migration, failure paths,
  contracts, lifecycle, units, threading, IDs, overflow, RPC validation and evidence.
- Gameplay: player loop, solo/four-player effects, encounters, dominant combinations,
  actual numbers/triggers, runtime hooks and challenge/control/refund/proc/defense limits.
- Design/UX: vocabulary, hierarchy, onboarding, consistency, accessibility, scope,
  simpler alternatives and actual rendered effects/full flows where changed.

At most the lead plus three independent reviewers run concurrently. Reviewers are
read-only; lead or one assigned implementer writes after a files/functions/steps/proof
mini-plan. Never assign concurrent writers to shared files or competing reviewer fixes.
Lead owns integration, verification strategy/evidence acceptance and final reporting;
an explicitly assigned test operator may own execution as described below. Reconcile
findings using code, measurements and user intent, not votes. Reviews do not replace tests
or human playtesting.

Beyond required independent reviews, delegate only when the benefit justifies coordination;
handle trivial work directly.
Use clean forks and explicit ownership. Fresh review context is required for high-risk
authority/lifecycle changes. Resume the same implementer for fixes, rerun affected proof,
and use compact delta rechecks. Do not repeat whole review rounds without new concerns.

### Ponytail post-review before committing

Include Ponytail's correctness, completeness and simplicity lens in the existing
risk-based post-review, normally the technical perspective; low-risk slices use lead
inspection. Do not add a fourth reviewer or a duplicate blanket review round. Preserve
all required technical/gameplay/design-UX perspectives and accepted requirements.

Inspect the actual final slice diff for defects, missed requirements, unnecessary
abstractions, duplicate logic, speculative flexibility, unrelated edits and simpler
complete alternatives. Check proposed commit scope and evidence/source compatibility.
Reviewers remain read-only and independent; return locations, failure scenarios and
verification for blockers, with optional suggestions and acceptance limits separately.
Lead resolves blockers, records deferrals, obtains compact affected delta rechecks and
reruns invalidated proof. Optional style preferences do not reopen a completed slice.

### Model policy

This is the canonical ProjectI model policy, superseding earlier project/global
complex-task defaults. It does not change the user's global file for other projects.

| Work | Model | Reasoning |
|---|---|---|
| Lead: design, implementation, check selection, difficult diagnosis and final decisions | `gpt-6.1-sol` | Ultra |
| Test operator: execute a substantial agreed verification batch and report evidence | `gpt-6.1-sol` | Medium |
| Final reviewer: correctness, scope, Ponytail simplicity and commit readiness | `gpt-6.1-sol` | Medium |
| Complex/uncertain delegation, architecture, multi-file changes, difficult debugging, networking, VR, physics, NOVA, substantial reviews | `gpt-6.1-sol` | Medium |
| Isolated lookup/mechanical work reviewed by the lead | `gpt-6-luna` | High |

Set model and reasoning explicitly when delegating. Few changed lines do not guarantee
low complexity. Report model unavailability and a proposed fallback before substitution;
no terra/astra by default. Review roles need not be separate implementation agents, and
a plan alone does not request implementation agents during research/planning.

### Delegated test execution

Whenever assigning a substantial verification batch, including docs/tooling work, load the
[verification handoff procedure](../.agents/skills/projecti-slice/references/verification.md#delegated-test-execution).
The lead selects checks/accepts evidence; the operator receives exclusive execution ownership
and frozen inputs. This route does not itself authorize tests, fixes or extra retries.

## 5. Verify, report and stop

Read [TESTING.md](TESTING.md) before selecting/executing checks, and relevant entries
in [TEST_CATALOGUE.md](TEST_CATALOGUE.md) rather than every fixture. Retain exact discovery,
exclusive Editor ownership, cleanup sequencing, immutable identity, failure classification,
omission reporting and bounded retries. Freeze integrated source; run broad checks once
and repeat only invalidated checks. A focused pass does not close omitted gates.

Report what changed and why, actual focused/integrated proof, compatible historical
reuse, omissions/reasons and remaining acceptance. Stop when the agreed scope and proof
are satisfied; incomplete human/hardware/separate-network or natural coverage remains
explicitly open. Prose-only policy changes require documentation checks, not Unity runs.
Record new decisions briefly in the current plan and archive chronology separately.

### Slice closure and local commits

Sequence: scope and required pre-review; implement with focused proof; required post-review
with Ponytail checks; resolve blockers; freeze source; final agreed verification (delegated
where useful); lead checks evidence and proposed commit scope; scoped local commit.
Insert ASAP human review at the first safe checkpoint and pause feedback-dependent work;
present End human review after the lead accepts final proof. Human-before-commit gates
still apply; otherwise the local checkpoint may precede deferred human acceptance.
Any code/asset correction
invalidates affected proof and requires the relevant delta recheck before closure.

Standing user authorization permits scoped local commits for authorized implementation
and documentation tasks after required reviews and agreed checks pass. No separate commit
confirmation is needed. An explicit task-specific request to leave work uncommitted still
wins. Read-only review, research and chat-only planning authorize no staging or commits.
Use imperative subjects and commit by coherent completed behavior,
not elapsed time. Stage only task-owned paths or hunks; inspect the staged diff and preserve
unrelated staged/working changes. If unrelated staged changes prevent an isolated commit,
use a safe scoped method or report the obstruction; never commit or unstage them silently.
Never automatically push, amend, blanket-stage or include pre-existing work from other slices.

A checkpoint commit may say "human acceptance pending" without claiming production approval.
If human acceptance is explicitly a prerequisite for that slice's commit, wait for it.
Pending acceptance never permits promotion or dependent work through a required gate.
Report commit identity, checks/reuse/omissions, unresolved acceptance and next action.

This policy replaces older generic no-auto-commit/no-commit defaults for future authorized
work, including old plan boilerplate. Historical no-commit/push statements remain truthful
records; this policy does not authorize committing their accumulated dirty work. A newer
explicit task restriction still wins. Push authorization remains separate.

## 6. Evaluate instruction changes

When changing workflow/skill instructions, load the [evaluation procedure](WORKFLOW_MAINTENANCE.md#6-evaluate-instruction-changes).
Read-only walkthroughs check consistency; they do not prove speed, savings or game quality.

## Research basis and limits

Historical rationale and applicability limits live in [workflow maintenance](WORKFLOW_MAINTENANCE.md#research-basis-and-limits).
Load them for policy research or provenance, not routine implementation/review.