sprint

Orchestrate Agentic Sprint Loop

Orchestrate a structured, 5-phase agentic sprint loop across specified tickets, issues, or feature goals.

Reference Practice: @docs/AgenticLoop.md

Role Contract — Direct Execution

You, the agent that received this invocation, are the sprint orchestrator for this task. Execute all five phases below yourself, in this session. Do not hand the sprint as a whole to another agent, subagent, or external CLI, and do not spawn a second sprint orchestrator. Delegation is exactly one level deep: helpers are started with --role advisor|developer|reviewer and are leaf workers that never run harnez agent themselves. Delegation inside the workflow is still required where each phase says so — the reusable advisor (Phase 1), the named developers (Phase 2), and the independent reviewer (Phase 3) are delegated by you and report back to you. This is not a choice: direct invocation always means inline execution. To delegate sprint execution to a different agent, the user invokes the sprinter delegator, not this skill.

---

Invocation Syntax

• /sprint <ticket-numbers> (e.g. /sprint 003, 004, 011 or /sprint 039)
• /sprint "<feature-goal-or-task-description>"

---

5-Phase Sprint Workflow

Follow these 5 phases sequentially:

Phase 1: Sequential Advisory Discovery (One Reusable Advisor)

1. Parse the target tickets or goals from the prompt.
2. Reuse the current advisor session if available; a closed or parked advisor remains eligible for native reuse. Start a new reusable advisor (via synchronous harnez agent start --role advisor --model <model> --name sprint-advisor "<short ticket-referencing prompt>" or native advisor session) with a frontier model only when no compatible session exists or the existing one has an explicit health/compatibility failure, such as the Codex usage-limit dead-session behavior. Record its session ID and model. Use this same advisor for every ticket, one at a time; never dispatch the next ticket before the previous ticket's compaction completes. The command prints the reply directly; if parallel work is explicitly wanted, run it through the host's visible background-job facility so the user can see and stop it.
3. Hand the advisor one ticket or bounded goal at a time (e.g. synchronous harnez agent resume --name <advisor_session_id> "<short follow-up>"). Instruct it to:
   • Audit problem statements in issues/ and related code paths using targeted grep_search and range-bounded reads (avoid whole-file reads on AGENTS.md or active prompt rules).
   • Check whether work is already completed or if prior assumptions changed.
   • Identify target files, exact line ranges, and test requirements.
   • Formulate a clean, step-by-step implementation plan.
   • Recommend broader subsystem/work categories, short technical developer names (e.g. cli, spec, docs), and a suitable model for each, chosen from harnez agent models (ROLES, USE columns). Explicitly justify any recommendation to use the top frontier model for development.
   • Work within the requested advice scope: it may edit tickets, create documents under docs/ or issues/, and make tiny 3–4 line fixes only when the build stays clean. Verify the build for such fixes. Do not perform normal coding or split a larger change into tiny fixes to bypass this limit; hand normal implementation to developers.
   • Make intermediate commits when reasoning locks in substeps of the requested advice, committing only its scoped changes and observing the applicable review requirements. Persist conclusions, decisions, and handoff details in tickets/docs before compaction.
4. Collect each ticket's findings and durable references into the orchestrator's sprint plan. After each ticket, the orchestrator must explicitly call the available session-compaction operation (harnez agent compact --name <session_id>) on the advisor session and confirm completion. This includes an explicit call after the last ticket, even if no further work is queued. An instruction to the advisor to compact itself is not a substitute. Keep the same session for clean-but-cached reuse, including hours later; do not replace it with a fresh advisor per ticket.
5. Present the synthesized plan and task sequence to the user.
   • Outside research (model comparisons, library or API surveys) goes to separate helpers whose prompt says "web research only, do not inspect the repository"; otherwise the advisor rules pull them into repo audits. Delete them once their reply is collected.
6. Keep the host orchestrator responsive throughout delegation. Do not block the main chat on subagent waits unless the user explicitly asked to wait or the next integration step is blocked on a child result.

Phase 2: Sequential Development & Test Verification (Reusable Developers)

1. Create or reuse one developer agent per broader subsystem/work category from the advisor's plan (via harnez agent start --role developer --model <model> --name <category> "<prompt>" or native subagent), rather than one per ticket. Give each a short technical name users can refer to, and record its name, session ID, category, and model. Select a suitable lower-cost model; use the top frontier model only when the advisor explicitly recommends it. An explicitly named provider:model:tier must be dispatched exactly through harnez agent start; on failure, report it and ask for guidance rather than substituting the host model or a native subagent.
   • Plan first (read-only): recommended: the developer's initial prompt asks for a read-only plan ("read-only: plan ...", no edits yet); the host reviews it, then resume grants write authority. No prompt template: agents have their own best practices, and stored first prompts are how we observe them.
2. Process tasks one by one in sequence through the matching named developer (resumed via harnez agent resume --name <session_id> "<task>" to avoid concurrent edits to the same codebase/worktree). Reuse that session for later work in its category, supplying bounded tasks and durable references.
3. Follow Test-Driven Development (TDD):
   • Add or update unit tests alongside or before modifying implementation code.
   • Run tests (go test -count=1 ./..., make test) to verify each milestone before moving to the next.
   • Under a one-run test budget (make test-q1), write the full output to a file and grep it for --- FAIL; piping into tail loses the failing test's name and the rerun needs a code change first.
   • A failure in a test the milestone didn't touch gets its own ticket (with the failing output and a hypothesis); never loosen the assertion or retry until it passes.
   • Maintain codebase stability, ensuring clean compilation at every step.
   • For defect-shaped tickets: establish a concrete reproduction baseline before coding the fix (see @docs/AgenticLoop.md Phase 2, "Repro-before-fix").
4. Milestone-Boundary Atomic Commits: Commit each verified milestone upon passing tests and review (git commit -m "feat/fix(...): ... (issue XXX MX)"). Never carry uncommitted working tree diffs across milestone transitions.
5. After each larger work item, persist its learnings in issues/docs/code and pass the Phase 3 review gate before committing implementation. Then the orchestrator must make an explicit final session-compaction call (harnez agent compact --name <session_id>) for that developer and confirm completion before handing it another item or parking it. Merely telling the developer to compact at the end does not satisfy this checkpoint.

Phase 3: Pre-Commit Review Gate & Nuance Follow-Up Tracking

1. Spawn an independent reviewer subagent (via harnez agent start --role reviewer --model sol "Review diff HEAD~1" or dedicated review pass).
2. The reviewer audits the full git diff (git diff, git status) and verifies:
   • Test Assertion Rigor: Are assertions meaningful, robust, and verifying real behaviors?
   • Documentation & Tracker Sync: Are issues/*.md statuses, issues/README.md, docs/README.md, and AGENTS.md updated?
   • Invariants & CLI Design: Are command boundaries (apply vs init) and architectural rules respected?
   • Media & Demo Verification: If reels, WebM files, or UI screenshots were produced, has explicit user confirmation been obtained before publishing?
   • Code Cleanliness: Is the code token-efficient, idiomatic, and minimal?
   • Root Cause vs. Symptom: For defensive/robustness fixes, ask whether the unexpected input's source can be fixed instead; verify any upstream fix against the real tool before treating it as done (see @docs/AgenticLoop.md Phase 3).
3. Follow-Up Scheduling & Nuance Buffering:
   • Blocking defects: Must be corrected before committing the sprint.
   • Non-blocking nuances / architectural improvements: File or buffer into a dedicated Nuance Refinement Ticket (#XXX-refinements or scheduled follow-up ticket) rather than stalling sprint velocity with endless micro-adjustments.
4. Address any review findings before proceeding to commit.
5. Apply this gate to intermediate implementation commits as well as the final sprint commit. After a larger work item is committed and its learnings documented, complete the developer compaction checkpoint from Phase 2; return to Phase 2 if more development remains.

Phase 4: Process & Subagent Hygiene (Compact, Park & Drain)

For hung or killed quota-1 test runs, use harnez clean procs q1 --kill; it releases quota state only after verifying the recorded process group is gone.

1. Inspect running background tasks using harnez agent list and available task/session tools.
2. Explicitly terminate completed, idle, or zombie background jobs, schedule timers, and watch subprocesses (harnez agent stop --name <id> or harnez agent delete --name <id>). Drain outstanding delegated work before parking sessions.
3. Preserve the reusable advisor and named developer sessions for later reuse; do not blanket-kill them. Confirm the advisor's post-last-ticket compaction and each developer's post-larger-item compaction completed. If a session received additional work afterward, persist its conclusions and have the orchestrator explicitly compact it again as the final call before parking. End disposable reviewer sessions with targeted cleanup (harnez agent delete --name <session_id>).
4. Ensure no background processes are left running unmonitored. A parked reusable session retains its identity without an active job or polling loop.
5. Use actual supported session-compaction operations (harnez agent compact), not invented commands or self-compaction prompts. If explicit compaction is unavailable or fails, report the affected session and limitation; do not claim it is compacted or ready for clean reuse. Same-session reuse is intended to retain useful cache while clearing ticket context, but cache retention, expiry, and billing depend on the backend and cannot be guaranteed.

Phase 5: Agentic Flow Quality Retrospective (Feedback & Tracker Sync)

1. Record session flow learnings, tooling friction, or agent harness feedback:
   • Add retrospective notes to docs/feedback/<YYYY-MM-DD>-<topic>.md or run /story if a major case study was produced.
   • Record how each model did in its role in the project's model doc (harnez: docs/Models.md), and update the roles/use guidance behind harnez agent models when evidence shows a model fits another role.
2. Synchronize the issue tracker:
   • Update issue status in issues/*.md (e.g. Status: Closed).
   • Update issues/README.md table.
   • Run harnez status to ensure all issue statuses are clean and validated.
   • When closing a ticket, check the whole file for multiple status-bearing fields and update all (see @docs/AgenticLoop.md Phase 5, "Single Status field").
3. Present a clear, concise summary of completed tickets and accomplishments to the user. Name each ticket or milestone at least once with a short label, e.g. "491 (component selection in apply)", not bare "491" (@docs/AgenticLoop.md §4, Status reports).