Preview 0.33

P01 - Feature through a reviewed specification and derived plan

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.

Why

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.33\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path prepare P01-feature-through-plan

You · Native terminal · macOS

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" prepare P01-feature-through-plan

You · Native terminal · Linux

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" prepare P01-feature-through-plan

Expected result

Academy switches this clone to academy/P01-feature-through-plan/ATTEMPT_NUMBER and queues academy.feature.0002.

If that does not happen

If Prepare stops, preserve its message and resolve the named clean-worktree or branch condition. Do not force-reset main or delete another attempt.

Evidence

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.

Describe the feature and review its draft

Ask Arbiter to draft a specification for a new JSON output field. The request includes a pause so you can practice reviewing the intended behavior.

Why

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 JSON summary" Use slug academy-feature and the full feature workflow for this new output field. academy.feature.0002 already tracks this feature, so do not record a separate work item for it. Draft the specification and stop for my review before planning, implementation, or commits.

Your agent · Codex harness · All operating systems

$ca-feature "Show unresolved tickets in the Workshop Queue JSON summary" Use slug academy-feature and the full feature workflow for this new output field. academy.feature.0002 already tracks this feature, so do not record a separate work item for it. Draft the specification and stop for my review before planning, implementation, or commits.

Your agent · Pi harness · All operating systems

/ca-feature "Show unresolved tickets in the Workshop Queue JSON summary" Use slug academy-feature and the full feature workflow for this new output field. academy.feature.0002 already tracks this feature, so do not record a separate work item for it. Draft the specification and stop for my review before planning, implementation, or commits.

Your agent · Pi harness · All operating systems

/skill:ca-feature "Show unresolved tickets in the Workshop Queue JSON summary" Use slug academy-feature and the full feature workflow for this new output field. academy.feature.0002 already tracks this feature, so do not record a separate work item for it. Draft the specification and stop for my review before planning, implementation, or commits.

Expected result

Arbiter opens a native specification describing unresolved as open plus claimed, excluding completed tickets, and waits at your requested review checkpoint.

If that does not happen

If native authoring fails, preserve the diagnostic and repair the installed plugin. Do not substitute a handwritten artifact.

Evidence

The draft is a tracked input to your review, not proof that anyone approved it.

Prepare leaves this feature unplanned. Arbiter creates the native specification when asked, then opens it for you to review. Your request explicitly asks for this pause; it is a learning checkpoint, not a default approval ceremony.

The agent maintains the saved specification and plan through the plugin. You review the intended behavior and the rendered pages. If authoring fails, keep the diagnostic and repair the installation before continuing.

Practice

Open and read the specification

Ask the agent to open the rendered specification. Read the problem, scope, and acceptance criteria as a person deciding whether this is the feature you want.

Why

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 the saved academy-feature specification for me. Summarize its observable behavior, exclusions, and unresolved choices. Keep the requested pause; do not implement yet.

You · Codex harness · All operating systems

Open the saved academy-feature specification for me. Summarize its observable behavior, exclusions, and unresolved choices. Keep the requested pause; do not implement yet.

You · Pi harness · All operating systems

Open the saved academy-feature specification for me. Summarize its observable behavior, exclusions, and unresolved choices. Keep the requested pause; do not implement yet.

Expected result

A readable specification and a short explanation of what the proposed feature will do.

If that does not happen

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.

Evidence

Your review concerns the intended result. The native engine owns artifact structure and consistency.

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.

Why

Solo practice rehearses a concrete review decision without pretending that an external reviewer participated.

Expected result

You can either identify a concrete correction for the draft or explain why each criterion is observable and testable.

If that does not happen

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.

Evidence

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.

Why

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

Expected result

You either have real feedback to relay or have deliberately chosen the Solo practice path.

If that does not happen

If the discussion is unavailable or no response arrives, do not wait or fabricate one. Return to Solo practice and use its checklist.

Evidence

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 !.

Why

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

Update the saved academy-feature specification to address this finding: [describe the concrete correction]. Keep the scope to unresolved JSON reporting. Show me the revised result before planning or implementation.

You · Codex harness · All operating systems

Update the saved academy-feature specification to address this finding: [describe the concrete correction]. Keep the scope to unresolved JSON reporting. Show me the revised result before planning or implementation.

You · Pi harness · All operating systems

Update the saved academy-feature specification to address this finding: [describe the concrete correction]. Keep the scope to unresolved JSON reporting. Show me the revised result before planning or implementation.

Expected result

The agent changes only the draft specification and presents its revised criteria before any plan, task transition, test, production edit, or commit.

If that does not happen

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.

Evidence

The revised specification remains visible for learner review. Check does not authenticate the review or revision conversation.

When the draft is acceptable

Continue from the reviewed outcome

When the intended behavior is right, continue past the pause you requested. Arbiter should maintain the plan and show the checks it actually runs.

Why

The deliberate second instruction keeps drafting and review distinct from planning and implementation.

You · Claude Code harness · All operating systems

Continue academy-feature. Create its native plan from the specification, start academy.feature.0002 through the task workflow, and implement the bounded JSON summary change. Run a focused regression while the behavior is missing, make the repair, then run the affected tests. Commit the complete green change through the commit gate. academy.feature.0002 is this feature's only work item: do not record another work item or attach the specification or plan to one. Do not push, merge, or publish. Stop and report any real blocker.

You · Codex harness · All operating systems

Continue academy-feature. Create its native plan from the specification, start academy.feature.0002 through the task workflow, and implement the bounded JSON summary change. Run a focused regression while the behavior is missing, make the repair, then run the affected tests. Commit the complete green change through the commit gate. academy.feature.0002 is this feature's only work item: do not record another work item or attach the specification or plan to one. Do not push, merge, or publish. Stop and report any real blocker.

You · Pi harness · All operating systems

Continue academy-feature. Create its native plan from the specification, start academy.feature.0002 through the task workflow, and implement the bounded JSON summary change. Run a focused regression while the behavior is missing, make the repair, then run the affected tests. Commit the complete green change through the commit gate. academy.feature.0002 is this feature's only work item: do not record another work item or attach the specification or plan to one. Do not push, merge, or publish. Stop and report any real blocker.

Expected result

The saved plan connects criteria to the test and implementation work. The agent reports the initial regression failure, the repaired result, and the governed commit.

If that does not happen

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.

Evidence

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.

From codeArbiter 3.8, the feature lane normally records its own work item once the specification exists. Here academy.feature.0002 already tracks the feature, and the commit gate cannot yet keep a task start and a new work item in one commit, so both prompts ask the lane not to record one. If the gate still stops on .codearbiter/open-tasks.md because a second queued row appeared, do not edit the board by hand. Use Reset and repeat the attempt.

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 is useful because it maps each reviewed criterion to implementation and verification work. It is not a separate approval ceremony.

Check

Run the external Academy Check

Ask the agent to run the installed external Academy Check. It supplies the plugin installation already loaded by your host so the native engine can inspect the saved artifacts.

Why

Check independently recomputes the final artifact and commit-boundary contract.

Your agent · Claude Code harness · All operating systems

Run the installed external Academy verifier for P01-feature-through-plan with --repository set to this clone and --plugin-root set to your loaded codeArbiter installation. Show the exact command and result. Do not use a verifier or helper from this checkout, change the artifacts to hide a failure, or claim unrun checks passed.

Your agent · Codex harness · All operating systems

Run the installed external Academy verifier for P01-feature-through-plan with --repository set to this clone and --plugin-root set to your loaded codeArbiter installation. Show the exact command and result. Do not use a verifier or helper from this checkout, change the artifacts to hide a failure, or claim unrun checks passed.

Your agent · Pi harness · All operating systems

Run the installed external Academy verifier for P01-feature-through-plan with --repository set to this clone and --plugin-root set to your loaded codeArbiter installation. Show the exact command and result. Do not use a verifier or helper from this checkout, change the artifacts to hide a failure, or claim unrun checks passed.

Expected result

Check prints checkpoint P01-feature-through-plan: passed; progress: .academy/progress.json.

If that does not happen

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.

Evidence

Check verifies committed native artifact readiness and lesson-specific code, test, and branch boundaries. It does not authenticate review, command chronology, or test execution.

A pass contains checkpoint P01-feature-through-plan: passed; progress: .academy/progress.json. Check uses the loaded plugin’s native reader on a disposable copy of the committed artifacts. It validates the final descendant commit, native spec and plan readiness, 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.

Why

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 main

You · Native terminal · macOS

git switch main

You · Native terminal · Linux

git switch main

Expected result

Git switches to main and leaves academy/P01-feature-through-plan/ATTEMPT_NUMBER reachable.

If that does not happen

If Git refuses because work is uncommitted, stop and preserve it. Do not force the switch or delete the completed attempt.

Evidence

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.

Why

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.33\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path reset P01-feature-through-plan

You · Native terminal · macOS

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" reset P01-feature-through-plan

You · Native terminal · Linux

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" reset P01-feature-through-plan

Expected result

Academy archives the prior attempt and prints the next academy/P01-feature-through-plan/ATTEMPT_NUMBER branch.

If that does not happen

If Reset stops, preserve its message and current branch. Resolve only the named repository condition; never force-reset or delete the prior attempt.

Evidence

A retry starts from the clean lesson baseline while the earlier attempt remains reachable.

Understand the mechanism

A feature starts from observable behavior. The specification says what must be true, the plan traces it into work, a focused test protects the caller boundary, and the commit gate records the verified result. Check compares your baseline, commit ancestry, artifacts, and worktree. Build a Feature End to End covers the lane.

Use this in your own project. Describe an observable improvement and its limits, review success and failure cases, and let the agent keep the plan current.

Next step

Continue with P02-commit-review-pr.

Recovery guidance