Developer guide

Prerequisites

Install only the tools needed for the task. Project wrappers own tool versions where available.

No container runtime is required. Local development does not use Docker, Docker Compose, or Testcontainers.

Repository setup

Run these commands in PowerShell from the directory where you keep source repositories.

gh auth login

gh repo clone maximus-txm/txm-enrollment
cd txm-enrollment

git switch develop
git pull --ff-only origin develop
git status --short --branch

Task readiness

Backlog entries are Project drafts. Convert a draft to a repository issue before implementation so it has an issue number.

• Convert the Project draft to an issue in txm-enrollment.
• Assign the issue to the developer doing the work.
• Confirm dependency tasks are merged into develop.
• Confirm linked specifications and their transitive dependencies are FROZEN.
• Have the Lead authorize the assigned issue in the exact Ready status.
• Run /prepare-task {issue-number} for the repository issue.
• Preparation produces one PREPARED consolidated reference under specs/implementation-docs/, with automatic completeness, integrity, and freshness checks.
• Immediately run /implement-task {issue-number}. No document approval, separate preparation review, documentation PR, or prior merge is required.

Do not start implementation from Backlog. /prepare-task requires an explicit numbered repository issue and never changes Project status. /implement-task requires the assigned issue in Ready and its complete, prepared, fresh reference. The reference may be untracked; it is carried into the task branch without committing it first.

Task workflow

One issue, one consolidated agent reference, one implementation session, one task branch, one independently reviewed implementation diff, and one implementation pull request.

1. /prepare-task

   Prepare the agent reference

   Run /prepare-task {issue-number}. The agent consolidates the task's complete frozen source closure, constraints, inputs, and verification into one non-normative reference. It invents no requirements or decisions. Successful checks mark it PREPARED; no document approval or separate documentation PR is needed. It remains uncommitted, creates no new preparation branch, and never moves the implementation task status.

2. /implement-task

   Implement and verify

   Run /implement-task {issue-number}. The agent creates the task branch from develop, validates the local prepared reference, carries it and required safe graph output unchanged onto the branch, moves the item to In progress, and implements the task. Every change remains uncommitted; unrelated dirty files are not carried.

3. /review

   Independent review

   Run /review {issue-number}. Review is read-only and checks the complete uncommitted diff against the prepared reference, independently checks the complete canonical source closure, and reviews correctness and unnecessary complexity.

4. CHANGES_REQUIRED

   Correct findings

   Resume with /implement-task {issue-number} on the same branch. Apply only the required corrections, rerun verification, and repeat /review. A reference defect returns to /prepare-task {issue-number} on the same task branch, preserving implementation files, then directly to implementation revalidation and fresh reviews.

5. Manual review

   Inspect the exact diff

   After review returns PASS, the developer manually inspects the uncommitted changes. Any later change requires another independent and manual review.

6. /pr

   Publish

   Only /pr may stage, commit, push, and open the pull request to develop. It adds the required completion evidence and moves the Project item to In review. This one PR includes the exact implementation and prepared reference checked by independent review and the fresher. Nothing may change after that review.

Agents do not merge or mark work Done. Pull request acceptance and final Project status remain human-controlled.

Commands

Use repository wrappers and the smallest check that covers your change.

Repository state

git status --short --branch

Full build

.\gradlew.bat --no-daemon --console=plain --stacktrace clean check build

Graph freshness

graph-check

Graph navigation

graph-query "<question>"

Graph update

graph-update — preparation for its reference change, implementation for code changes; never review or PR publication

The prepared reference contains the final verification commands for its task. Task 1 records the Gradle and Graphify wrappers as expected outputs; preparation must not require those files before that task creates them.

Troubleshooting