Sprint

Sprint Skill — Generic Sprint Management for bkit Users

Sprint = meta-container above bkit's PDCA 9-phase. A sprint groups one or more features under a shared scope, budget, and timeline. Each sprint runs its own 8-phase lifecycle: prd -> plan -> design -> do -> iterate -> qa -> report -> archived.

Quick Start

/sprint init my-launch --name "Q2 Launch" --trust L3
/sprint start my-launch

The skill handler routes through <bkit-root>/scripts/sprint-handler.js (bkit convention — handlers live at the bkit repo root scripts/ directory, NOT inside skills/<name>/scripts/). The handler composes Sprint 3 adapters (state-store + telemetry + doc-scanner + matrix-sync) into Sprint 2 use cases (start / advance / iterate / qa / report / archive). Sprint 1 entities (createSprint / SprintEvents / typedefs) are produced and consumed transparently along the way.

Resolving scripts/sprint-handler.js in this document: throughout this SKILL.md, references to scripts/sprint-handler.js mean <bkit-root>/scripts/sprint-handler.js (the canonical location). LLM dispatchers MUST NOT compose skills/sprint/scripts/sprint-handler.js — that path does not exist (Issue #107, fixed v2.1.19 S2 F2-1).

Arguments

Trust Level Scope (auto-run boundary)

Auto-Pause Safety Pins

Four armed triggers can pause a running sprint:

• QUALITY_GATE_FAIL — M3 > 0 OR S1 < 100
• ITERATION_EXHAUSTED — iter >= 5 AND matchRate < minAcceptable
• BUDGET_EXCEEDED — cumulativeTokens > config.budget
• PHASE_TIMEOUT — phase elapsed > config.phaseTimeoutHours

Pause writes an audit log entry and a SprintPaused event. Resume re-evaluates the triggers and refuses if any are still firing.

Cross-Sprint Architecture (Sprint 1+2+3+4)

USER COMMAND
   v
skills/sprint/SKILL.md (this file — frontmatter triggers in 8 languages)
   v
scripts/sprint-handler.js (English dispatcher)
   v
Sprint 3: lib/infra/sprint -> { stateStore, eventEmitter, docScanner, matrixSync }
   v
Sprint 2: lib/application/sprint-lifecycle -> startSprint / advancePhase / ...
   v
Sprint 1: lib/domain/sprint -> createSprint / SprintEvents / typedefs
   v
DISK: .bkit/state/sprints/<id>.json + .bkit/audit/<date>.jsonl

Examples

See:

• examples/basic-sprint.md
• examples/multi-feature-sprint.md
• examples/archive-and-carry.md

When NOT to Use

• Single-feature PDCA work — use bkit:pdca instead
• Starter level projects — sprint overhead exceeds value
• One-off bug fixes that do not warrant a master plan

Delegation notes

Extended trigger keywords, moved here from the frontmatter description (issue #129 token diet) — one anchor per language stays in the description; the full multilingual list is preserved below:

• JA: スプリント開始, スプリント状態, マスタープラン, マルチスプリント計画, スプリントマスタープラン
• ZH: 冲刺开始, 冲刺状态, 主计划, 多冲刺计划, 冲刺主计划
• ES: iniciar sprint, estado sprint, plan maestro, plan multi-sprint, plan maestro sprint
• FR: demarrer sprint, statut sprint, plan maître, plan multi-sprint, plan maître sprint
• DE: Sprint starten, Sprint Status, Masterplan, Multi-Sprint-Plan, Sprint-Masterplan
• IT: avviare sprint, stato sprint, piano principale, piano multi-sprint, piano principale sprint

Related Skills and Agents

• bkit:pdca — single-feature PDCA cycle (foundation primitive)
• bkit:control — automation level (L0-L4) — surfaces SPRINT_AUTORUN_SCOPE
• bkit:sprint-orchestrator (agent) — full lifecycle coordinator
• bkit:sprint-master-planner (agent) — plan/design generation
• bkit:sprint-qa-flow (agent) — 7-Layer dataFlowIntegrity verifier
• bkit:sprint-report-writer (agent) — KPI + lessons + carry items

10. Skill Invocation Contract (for LLM Dispatchers)

This contract specifies how an LLM dispatcher should construct the args object for each of the 16 sub-actions when invoking the underlying handler via scripts/sprint-handler.js.

10.1 Args Object Schema (per action)

10.1.2 measure action semantics (v2.1.16, Issue #94 F3)

/sprint measure <id> is the user-invokable partial-gate measurement command added in v2.1.16. It routes the requested gate(s) through lib/application/quality-gates/measure-router.js (single SoT shared with sprint-orchestrator self-assessment) and persists results into sprint.qualityGates subject to Trust Level scope.

Three invocation modes (mutually exclusive precedence: gate > gates > phase):

/sprint measure my-launch --gate M4                       # single gate
/sprint measure my-launch --gates M4,M8                   # multi-gate (CSV)
/sprint measure my-launch --phase design                  # phase batch (ACTIVE_GATES_BY_PHASE[design])

Agent routing (Master Plan §11.3 AC4 — 7 gates × 4 agents):

Gates outside this table (M5, M10, S2, S4) return { ok: false, reason: 'unsupported_gate' } — carried to v2.1.17.

Trust Level scope (Master Plan AC5):

• L0 / L1: preview mode — measurement returned but sprint.qualityGates NOT updated, no gate_measured audit entry.
• L2 / L3 / L4: record mode — qualityGates updated + gate_measured audit entry emitted per gate.

Audit emission (when in record mode):

{
  "action": "gate_measured",
  "category": "sprint",
  "actor": "user",
  "target": "<sprintId>",
  "details": {
    "sprintId": "...", "gateKey": "M4", "field": "M4_apiComplianceRate",
    "agent": "gap-detector", "value": 100, "threshold": 95, "passed": true,
    "source": "manual", "phase": "design", "trustLevel": "L3",
    "previousValue": null
  }
}

ENH-292 alignment: multi-gate / phase batch dispatches measurements sequentially (no Promise.all) to avoid #56293 sub-agent caching 10x.

Dispatcher requirement: the LLM dispatcher (main session) must inject deps.agentTaskRunner wrapping Claude Code's Task tool. Without it the use case returns reason: 'no_agent_runner' per gate (deterministic, not silent fail). The handler layer exposes createTaskToolRunner({ invokeTaskTool }) (in scripts/lib/sprint-handler-shared.js, re-exported from scripts/sprint-handler.js) to build this wrapper:

const { createTaskToolRunner } = require('<bkit-root>/scripts/lib/sprint-handler-shared');
const runner = createTaskToolRunner({
  invokeTaskTool: async ({ subagent_type, prompt }) => {
    // delegate to Claude Code's Task tool in the main session
    return { text: await callTaskTool({ subagent_type, prompt }) };
  },
});
await handleSprintAction('measure', { id, gate }, { agentTaskRunner: runner });

Fork mode changes when the result arrives (ENH-478, v2.1.37).

The snippet above assumes callTaskTool resolves to the subagent's finished text. On Claude Code v2.1.232 and later that assumption does not hold in an interactive session: fork mode is on by default, the Agent tool loses its run_in_background parameter, and "a background subagent's results reach Claude as a completion notification in a later turn" (code.claude.com/docs/en/sub-agents). The result is not lost — it arrives on a later turn — but it is not available inside the turn that spawned the subagent.

A dispatcher that awaits it in-turn therefore receives nothing, and the gate reports no_output: an honest "not measured" rather than a wrong score, with the likely cause named in the message. To measure inside one turn, either run non-interactively (-p, where fork mode is off) or set CLAUDE_CODE_FORK_SUBAGENT=0.

Nothing here is a workaround for a defect. It is the shape of the runtime, and a dispatcher that spans turns is the correct adaptation to it.

Two invocation paths:

1. In-process (primary, main session): the LLM dispatcher calls handleSprintAction(...) directly with deps.agentTaskRunner injected. Gate measurement works end-to-end.
2. Subprocess CLI (node scripts/sprint-handler.js ...): runs in a separate Node process that cannot see the Task tool, so it passes {} and gate measurement returns no_agent_runner. Use this path only for non-measurement actions (status, list, help) or when the in-process path is unavailable; for any action that measures gates, use the in-process dispatcher call with an injected runner.

10.1.1 phase --approve semantics (v2.1.16, Issue #95)

When a sprint is at Trust Level L2 (scope.stopAfter = "design") or any other level whose scope.requireApproval blocks a forward transition, the user can re-issue the phase action with --approve (and optional --reason) to cross the scope boundary for this single call only:

/sprint phase my-launch --to do --approve --reason "Design review complete, M4/M8 gates pass"

Semantics (Master Plan §11.2 AC1-AC6):

• Single-use: sprint.autoRun.scope is NOT mutated. The next transition faces the same scope check. To advance through multiple scope-blocking transitions, re-issue --approve each time (or escalate Trust Level via /bkit:control level <N>).
• No trust escalation: sprint.autoRun.trustLevelAtStart and the global automation level (/bkit:control) are unchanged. The approval is recorded per-call.
• Audit-logged: every --approve boundary crossing emits an audit-logger.writeAuditLog({ action: 'scope_boundary_approved', details: { sprintId, from, to, trustLevel, stopAfter, approvedBy, reason } }) entry. The --reason "..." value is the recorded rationale (null when omitted).
• Without --approve the legacy deadlock behavior is preserved: handler returns { ok: false, reason: 'requires_user_approval', stopAfter, hint }.

Use this when you want to advance past the scope boundary for one specific transition (e.g., L2 design → do after design review) without permanently relaxing the trust level.