Best practices

​

Planning and selection

• Keep each feature small enough to implement and verify independently in one Agent session; split it first if it is too large.
• Write behavior as observable outcomes, not internal implementation steps.
• Use lower priority values for higher-priority work, together with claim --next to select ready work automatically.
• Run status at the start of every session instead of guessing the current state from the previous conversation.
• Write an ADR before making high-risk, cross-boundary, or difficult-to-reverse changes.
• Once every feature in a milestone is passing, run milestone archive before planning the next one, so feature_list.json stays focused on current work instead of accumulating every completed milestone.

​

Verification and evidence

• Use deterministic, repeatable commands with reliable exit codes for verification.
• Link each verification item only to the acceptance criteria it actually demonstrates.
• Use verify for automated checks; declare keyboard experience, visual confirmation, and similar human judgments as manual, then record them with evidence manual.
• Verify again after code changes; record the latest review after the latest verification.
• If an approved artifact changes in any way, record a new approval.

​

Collaboration

• In Solo mode, you normally do not need to call the low-level claim command, but feature start still establishes the lifecycle claim required for the work.
• owner identifies responsibility, while actor distinguishes different Agent sessions for the same owner.
• For long-running work, use claim renew before the lease expires so active work is not mistaken as available for takeover.
• Give parallel Agents separate workspaces, with one feature per workspace.
• Keep the reviewer separate from the claim owner so implementers do not review their own completion.

​

Sessions and Git

• Run session close at the end of a session, and include failed checks, uncommitted files, and next steps in the handoff.
• Commit feature_list.json, audit events, and protocol documents; do not commit local snapshots or .worktrees/.
• Use --push for cross-machine claims. A regular local claim does not provide a real-time distributed lock.
• Before workspace remove or workspace prune, confirm that work is committed and pushed; do not treat --force as a routine cleanup option.

​

Fields you should not edit directly

The CLI should maintain claims, workspaces, test/review evidence, and lifecycle states. Manual edits can bypass owner, commit, chronology, WIP, and concurrent-write checks, leaving state that appears valid but cannot be reproduced with confidence.