P01 - Feature through a user-approved spec and derived plan
Choose the commands you use
Operating system
CodeArbiter host
Know before you begin
P01 is the first Practitioner lesson in this preview. It starts from the F04 repair boundary and ends with one preserved feature attempt on a safe learner branch.
Complete F04 and begin in the same Academy fork and clone. Before Prepare, switch to main and confirm that git status --short prints nothing. Keep a native terminal open at the clone root for Academy Prepare, Check, and Reset. Keep one CodeArbiter harness open at that same clone for the feature workflow.
This lesson has two honest review paths. In Solo practice, you review the drafted specification yourself, using the checklist below. In Collaborative practice, you ask for or use feedback in the Arbiter Academy GitHub Discussion, then relay that feedback to your agent. If feedback is not available, return to Solo practice. Neither path asks you to make up feedback or persist a marker that pretends to prove another person approved the work.
Commands shown as native-terminal actions are entered directly and never begin with !. A shell command shown for a harness begins with exactly one !. CodeArbiter commands and agent messages are entered in the selected harness and never begin with !.
What you will prove
You will preserve one feature attempt containing the exact specification, a plan derived from its acceptance criteria, the sanctioned transition of academy.feature.0002, a focused regression, and the bounded unresolved-ticket repair. The task is to report the exact total of open plus claimed tickets through the existing summary boundary.
The agent drafts the specification and stops. You choose a review path, then send a separate proceed instruction. Only then does the agent derive the plan, start the staged task, run the focused RED test, make the bounded repair, run GREEN verification, and invoke the governed commit gate.
Prepare safely
Prepare a numbered feature attempt
From a clean main branch at your Academy clone root, run Prepare in a native terminal. Academy creates the numbered attempt branch before any feature work begins.
The prepared branch preserves a fixed starting point for the specification, plan, repair, and final Check.
You · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path prepare P01-feature-through-planYou · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" prepare P01-feature-through-planYou · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" prepare P01-feature-through-planAcademy switches this clone to academy/P01-feature-through-plan/ATTEMPT_NUMBER and queues academy.feature.0002.
If Prepare stops, preserve its message and resolve the named clean-worktree or branch condition. Do not force-reset main or delete another attempt.
The numbered attempt branch records the baseline from which Check reconstructs the exercise.
ATTEMPT_NUMBER means the number Academy prints, such as 1; it is not text to type literally. Stay on that numbered branch for the whole attempt.
Ask CodeArbiter to draft the specification
In your selected CodeArbiter harness, send the copied host-native feature command. It is a CodeArbiter command, not a shell command, so it never begins with !. The agent drafts the specification and stops for your review.
The feature lane makes the observable contract explicit before work is planned or implemented.
Your agent · Claude Code harness · All operating systems
/ca:feature "Show unresolved tickets in the Workshop Queue summary"Your agent · Codex harness · All operating systems
$ca-feature "Show unresolved tickets in the Workshop Queue summary"Your agent · Pi harness · All operating systems
/ca-feature "Show unresolved tickets in the Workshop Queue summary"Your agent · Pi harness · All operating systems
/skill:ca-feature "Show unresolved tickets in the Workshop Queue summary"The agent writes .codearbiter/specs/academy-feature.md and asks for review before deriving a plan, starting the task, or editing production code.
If the feature lane reports that the repository or task is not ready, preserve its finding. Do not write a substitute specification or bypass its review stop.
The draft is a tracked input to your review, not proof that anyone approved it.
The feature command creates the draft and stops at the specification decision. It does not grant approval, derive a plan, start the task, or change production code.
Practice
Read the draft with its source boundary
Ask your active harness to show the drafted specification beside the queued task and current summary boundary. This is a request to your agent, not a shell command, so it never begins with !.
Review is reliable only when the proposed outcome is compared with the task that authorized it and the existing caller-visible behavior.
You · Claude Code harness · All operating systems
Open .codearbiter/specs/academy-feature.md, the academy.feature.0002 task in .codearbiter/open-tasks.md, tests/test_cli.py, and workshop_queue/cli.py. Show the draft acceptance criteria next to the current summary behavior. Do not derive a plan, start the task, edit files, or commit.You · Codex harness · All operating systems
Open .codearbiter/specs/academy-feature.md, the academy.feature.0002 task in .codearbiter/open-tasks.md, tests/test_cli.py, and workshop_queue/cli.py. Show the draft acceptance criteria next to the current summary behavior. Do not derive a plan, start the task, edit files, or commit.You · Pi harness · All operating systems
Open .codearbiter/specs/academy-feature.md, the academy.feature.0002 task in .codearbiter/open-tasks.md, tests/test_cli.py, and workshop_queue/cli.py. Show the draft acceptance criteria next to the current summary behavior. Do not derive a plan, start the task, edit files, or commit.You can see every drafted criterion, the queued task boundary, and that the existing JSON summary omits unresolved tickets.
If a required source is missing or the task is no longer queued, stop. Preserve the attempt and use Reset for a new baseline rather than inventing a replacement.
Your review compares the proposal to repository sources instead of a chat summary.
Use exactly one review path before you continue.
Review the specification yourself
You · Active CodeArbiter harness · All operating systems
Choose Solo practice when you are the reviewer. Check that the draft names open and claimed ticket states, states that their exact total is caller-visible, avoids prescribing a private implementation loop, and can map each criterion to a plan step and focused test.
Solo practice rehearses a concrete review decision without pretending that an external reviewer participated.
You can either identify a concrete correction for the draft or explain why each criterion is observable and testable.
If a criterion is vague or exceeds the task boundary, ask the agent to revise only the specification and return to this review. Do not continue to implementation.
This is a learner review rehearsal. Check does not authenticate it.
Request or relay collaborative feedback
You · Browser · All operating systems
Choose Collaborative practice only when you can request or use actual feedback. Open the Arbiter Academy GitHub Discussion, describe the draft's observable contract, and relay real feedback to your agent before continuing. If no feedback arrives, use Solo practice instead.
A discussion can add another perspective, but its absence must not cause invented feedback or an unverifiable claim.
Reviewed resources for Request or relay collaborative feedback
You either have real feedback to relay or have deliberately chosen the Solo practice path.
If the discussion is unavailable or no response arrives, do not wait or fabricate one. Return to Solo practice and use its checklist.
Discussion participation is external process context. Check does not authenticate a GitHub Discussion response.
If review finds a concrete correction
Use the revision action. It sends a bounded request and returns you to the same review choice. It does not begin planning or implementation.
Request a bounded specification revision
If review identifies a concrete correction, send this message in the active harness. It asks the agent to revise only the draft specification, do not derive a plan, and stop for another review. It is not a shell command, so it never begins with !.
A visible revision path lets a first-time learner correct a weak contract without accidentally authorizing planning or implementation.
You · Claude Code harness · All operating systems
Revise only .codearbiter/specs/academy-feature.md to address this concrete review finding: [paste the concrete finding here]. Keep the task boundary: the Workshop Queue summary must report the exact total of open plus claimed tickets. Do not derive a plan, start academy.feature.0002, edit tests or production code, or commit. Stop and show the revised acceptance criteria for my review.You · Codex harness · All operating systems
Revise only .codearbiter/specs/academy-feature.md to address this concrete review finding: [paste the concrete finding here]. Keep the task boundary: the Workshop Queue summary must report the exact total of open plus claimed tickets. Do not derive a plan, start academy.feature.0002, edit tests or production code, or commit. Stop and show the revised acceptance criteria for my review.You · Pi harness · All operating systems
Revise only .codearbiter/specs/academy-feature.md to address this concrete review finding: [paste the concrete finding here]. Keep the task boundary: the Workshop Queue summary must report the exact total of open plus claimed tickets. Do not derive a plan, start academy.feature.0002, edit tests or production code, or commit. Stop and show the revised acceptance criteria for my review.The agent changes only the draft specification and presents its revised criteria before any plan, task transition, test, production edit, or commit.
If the agent changes anything beyond the draft or starts planning, stop. Preserve the attempt and use Reset for a new baseline rather than trying to hide the boundary violation.
The revised specification remains visible for learner review. Check does not authenticate the review or revision conversation.
When the draft is acceptable
Give the separate proceed instruction
Only after you complete one review path, send this separate message in the selected harness. It tells the agent what to do next without claiming an authenticated approval.
The deliberate second instruction keeps drafting and review distinct from planning and implementation.
You · Claude Code harness · All operating systems
I completed the P01 review. Proceed with this feature: derive .codearbiter/plans/academy-feature.md from the specification, start academy.feature.0002 through the sanctioned task writer, add and run a focused failing summary regression before production code, make only the bounded open plus claimed repair, run focused and full GREEN verification, stage the exact final boundary, and invoke the CodeArbiter commit gate. Stop and report if a gate blocks. Do not write a marker that claims to prove review or approval.You · Codex harness · All operating systems
I completed the P01 review. Proceed with this feature: derive .codearbiter/plans/academy-feature.md from the specification, start academy.feature.0002 through the sanctioned task writer, add and run a focused failing summary regression before production code, make only the bounded open plus claimed repair, run focused and full GREEN verification, stage the exact final boundary, and invoke the CodeArbiter commit gate. Stop and report if a gate blocks. Do not write a marker that claims to prove review or approval.You · Pi harness · All operating systems
I completed the P01 review. Proceed with this feature: derive .codearbiter/plans/academy-feature.md from the specification, start academy.feature.0002 through the sanctioned task writer, add and run a focused failing summary regression before production code, make only the bounded open plus claimed repair, run focused and full GREEN verification, stage the exact final boundary, and invoke the CodeArbiter commit gate. Stop and report if a gate blocks. Do not write a marker that claims to prove review or approval.The agent derives the plan, moves only academy.feature.0002 through the task writer, and follows the bounded test-first feature path.
If the agent begins implementation before this message or a gate blocks, stop. Preserve the attempt and inspect the named boundary rather than writing an approval claim or direct Git commit.
The final commit can prove repository artifacts, not the identity or process of the reviewer.
After you send the proceed instruction, let the agent execute the governed path it describes. Add and run a focused summary test before touching production code. The RED result must fail because unresolved tickets are absent, not because a file, import, or fixture is broken. The repair remains the exact open + claimed assignment. Do not create a RED commit, amend, or rebase.
Recognize success
The attempt has one final green commit after Prepare. That commit contains exactly the feature specification, derived plan, canonical task-board transition, focused regression, and bounded production repair. The task has a writer-produced start date, and git status --short prints nothing before Check.
The specification is the review boundary. The plan has authority because it maps each approved criterion to implementation and verification work. It is not a separate approval ceremony.
Check
Run the external Academy Check
After the governed commit and a clean status, run the installed Academy Check in a native terminal. It reads the prepared baseline, final Git state, and live worktree from outside the learner flow.
Check independently recomputes the final artifact and commit-boundary contract.
You · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path check P01-feature-through-planYou · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" check P01-feature-through-planYou · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" check P01-feature-through-planCheck prints checkpoint P01-feature-through-plan: passed; progress: .academy/progress.json.
If Check fails, preserve the clean committed attempt and read the failed predicate. Use Reset for a new numbered attempt instead of rewriting committed evidence.
Only a passing external Check records P01 progress.
A pass contains checkpoint P01-feature-through-plan: passed; progress: .academy/progress.json. Check validates the final descendant commit, exact spec and plan shape, task transition, focused regression, bounded repair, and a clean worktree. It does not authenticate a human approval. It does not authenticate a GitHub Discussion response. It does not prove that you ran the test before production code or the order in which the agent ran RED and GREEN commands. Those are workflow practices you observe during the lesson, not claims made by this final-state verifier.
Recover or continue
If the draft is wrong, use the revision action and repeat the review before proceeding. If review is incomplete, plan coverage is weak, the task transition is wrong, or Check fails, preserve the attempt. Read the named predicate and correct only that boundary in a new numbered attempt. Do not conceal evidence by amending or rebasing history.
Hint 1
Read the queued task and current report API before reviewing the draft. Describe visible ticket states and caller-visible output, not a private loop you expect to edit.
Hint 2
For Solo practice, check that every acceptance criterion is observable, names the relevant ticket states, and can map to one plan step and one focused test. For Collaborative practice, compare the feedback with those same facts before relaying it.
Hint 3
The final verifier recomputes data and repository shape. Keep the test narrow and inspect the final commit boundary; it cannot reconstruct chat, review, or command history.
After Check passes, leave the completed branch intact and return to main with this native-terminal action.
Return to main after success
After Check passes, return to main in a native terminal without deleting the completed attempt branch.
The passing attempt remains available for a reviewer to inspect while the clone is ready for the next guided lesson.
You · Native terminal · Windows
git switch mainYou · Native terminal · macOS
git switch mainYou · Native terminal · Linux
git switch mainGit switches to main and leaves academy/P01-feature-through-plan/ATTEMPT_NUMBER reachable.
If Git refuses because work is uncommitted, stop and preserve it. Do not force the switch or delete the completed attempt.
The completed evidence remains separated from main and available for later inspection.
P02 is public, guided, and runnable in this preview. Continue with its published Academy lesson after you return to main; do not substitute unpublished source exercises for the accepted course.
If P01 needs another attempt, use the preserved retry action.
Create a preserved numbered retry
Use Reset only when P01 needs another attempt. Run it in a native terminal at the Academy clone root; it preserves the earlier attempt before creating the next number.
Preserved retries leave review and implementation evidence inspectable instead of hiding it with a force reset or rebase.
You · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path reset P01-feature-through-planYou · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" reset P01-feature-through-planYou · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" reset P01-feature-through-planAcademy archives the prior attempt and prints the next academy/P01-feature-through-plan/ATTEMPT_NUMBER branch.
If Reset stops, preserve its message and current branch. Resolve only the named repository condition; never force-reset or delete the prior attempt.
A retry starts from the clean lesson baseline while the earlier attempt remains reachable.
Understand the mechanism
A feature contract begins with observable behavior. The specification tells the agent and reviewer what must be true; the plan traces that contract into work; the focused test protects the caller boundary; and the commit gate records only the verified final change. Academy Check then compares the prepared baseline, commit ancestry, required artifacts, and live worktree without trusting a transcript supplied by the learner checkout.