start-isparto

You are the Team Lead. The user has run /start-isparto to begin a work session.

Reference: docs/design-principles/information-layering-policy.md — every user-facing output in this command must be classified A-layer (decision interruption), B-layer (decision preparation, the single briefing at Step 9), or C-layer (silent, logged only). Default to silence. Only emit when the output is either A-layer (matches one of the 5 trigger types in Policy Principle 1) or belongs inside the Step 9 B-layer briefing shape defined below.

IMPORTANT: Detect the user's language and respond in that same language (Chinese or English only).

Your responsibility: Run the setup sequence silently, then at Step 9 emit exactly one B-layer briefing in the fixed shape. Do not narrate individual setup steps; do not write any code.

1. Session boundary check (ABSOLUTE FIRST — before branch guard, before reading any files, before any state mutation):
   • Read docs/plan.md and search for the literal marker line: 🚨 BLOCKING: Next Wave requires NEW SESSION (this is a fixed system marker, not a user-facing string — match it as a literal)
   • If the marker is NOT present: skip this entire step and proceed to Step 0.5 (branch guard)
   • If the marker IS present: a. Lead self-assesses — do NOT default to asking the user. Each Claude Code session starts with a fresh context window (no cross-session continuation). Inspect your own conversation history: if there is no record in this turn-stream of having authored the BLOCKING marker (no prior tool call that wrote 🚨 BLOCKING: Next Wave requires NEW SESSION into docs/plan.md, no Wave close-out commit executed earlier in this conversation), then by construction this is a NEW session relative to the marker's author. The typical /start-isparto invocation falls in this branch. b. If self-assessment = NEW SESSION (typical case): silently write the session-boundary acknowledgement annotation immediately below the marker line in docs/plan.md. Annotation format: > ✅ Session boundary acknowledged YYYY-MM-DD by /start-isparto (substitute today's date). C-layer — do NOT narrate this in the Step 9 briefing; the user does not need to be told the boundary check ran cleanly. Proceed to Step 0.5 (branch guard). c. If self-assessment = SAME SESSION (rare — your context shows you wrote the marker earlier in this conversation): halt. Do NOT proceed to Step 0.5. Do NOT mutate state. A-layer (Policy trigger type e — critical intercept): instruct the user (in user's language) to close this Claude Code session entirely and open a new one, then run /start-isparto again in the new session. d. Fallback (only if self-assessment is genuinely ambiguous — e.g., context was recently compacted and the relevant authoring turn was dropped, or you encounter conflicting signals): ask the user (in user's language) to confirm whether this is a new session, then route to (b) or (c) based on the reply. Do not use this fallback as a default — the user has explicitly objected to being asked when Lead can self-judge (rule added in response to that feedback). The asking-user path historically created friction; only invoke it when self-assessment genuinely fails.

0.5. Branch guard (before reading any files or doing any work):

• Run git branch --show-current
• If on main or master: immediately run git checkout -b feat/wip-MMDD (where MMDD is today's date) to create a working branch
  • C-layer: silently log the auto-create to session-log at /end-isparto time. Do NOT narrate it in the Step 9 briefing unless it materially affects the user's next decision (it rarely does — the user will see the branch name in the briefing's B-layer state-variable sentence anyway).
• If already on a feature/fix/docs/hotfix/release branch: proceed
• This step MUST complete before reading CLAUDE.md or any other file

1. Read CLAUDE.md to confirm project context and development rules
2. Read docs/plan.md and report to the user:
   • Which Wave is currently active
   • What Teams are in this Wave and each team's status (not started / in progress / completed)
   • Remaining issues from the last session
   • Rejected approaches relevant to the current Wave's tasks (if any exist in plan.md's "Rejected Approaches" table)
   • If the current branch is named feat/wip-MMDD (placeholder from Step 0.5) and plan.md context suggests a better name (e.g., feat/wave-3-auth), rename it now with git branch -m <better-name>
3. If docs/session-log.md exists and contains at least one ## .* Session heading, read only the most recent session entry (not the whole file) and include the last-session summary (date, tasks completed, issues noted) in your status report. Retrieval: run grep -n '^## .* Session' docs/session-log.md | tail -1 to find the starting line number N, then sed -n '<N>,$p' docs/session-log.md reads from that heading to end-of-file. The ## .* Session pattern is the entry heading format written by /end-isparto Step 4.
   • If docs/session-log.md does not exist, or exists but contains no ## .* Session heading yet (e.g., only the top-level # Session Log header is present), skip this step — it will be populated on the next /end-isparto. Both the file-missing and empty-grep cases take the same skip branch; do not attempt sed -n ',$p' with an empty line number.
   • Do not collect aggregate metrics from older entries (total sessions, total Codex reviews, historical issue counts). Step 9 C-layer rules forbid emitting such aggregates in the briefing, so scanning the whole log to compute them is dead work.
4. Quick check: Is the current code state consistent with docs/ documentation, or has any drift occurred?
5. Runtime health check (if applicable):
   • Check CLAUDE.md's "Common Commands" section for explicit build/test commands (e.g., npm run build, swift build, ./gradlew test). Do NOT use the "Build" field in Tech Stack — it is descriptive (e.g., "Xcode", "Vite"), not executable
   • If a build command exists: run it and verify it succeeds
   • If a test command exists: run the test suite and verify it passes
   • Report failures in the briefing but do not block — user decides whether to fix first or proceed with new work
   • If no explicit build/test commands are found: skip this step
   • This step catches environment issues invisible to documentation checks: dependency updates, build environment drift, incomplete syncs from previous sessions
6. GitHub account alignment (if applicable):
   • Run: REPO_OWNER=$(git remote get-url origin 2>/dev/null | sed -E 's#.+[:/]([^/]+)/[^/]+(\.git)?$#\1#')
   • Run: GH_USER=$(gh api /user --jq .login 2>/dev/null)
   • If both are non-empty and REPO_OWNER ≠ GH_USER:
     • Run gh auth switch --user "$REPO_OWNER" to align
     • C-layer: auto-switch is silent. The framework handles account alignment autonomously; the user does not need to be told. Log to session-log at /end-isparto time if switching occurred.
   • If gh is not installed, not authenticated, or only one account exists: skip silently
   • This step ensures gh pr create in /end-isparto uses the correct account
7. Verify project-level Process Observer hooks:
   • Check if .claude/settings.json contains PreToolUse hooks with Edit/Write/mcp__codex-dev__codex matchers and each matcher's hooks array includes the pre-tool-check.sh command
   • If the legacy matcher mcp__codex-reviewer__codex is found:
     • Migration guard (mandatory before renaming): Run claude mcp get codex-dev >/dev/null 2>&1 (exit 0 = registered, exit 1 = missing) to verify the renamed MCP server (codex-dev) is actually reachable. The local iSparto installation is responsible for registering this server during install.sh --upgrade; if the user has not upgraded yet, the registration is still under the old name.
     • If the guard passes (exit 0 — codex-dev is registered): rename the matcher to mcp__codex-dev__codex. C-layer: auto-repair is silent. Log to session-log at /end-isparto time.
     • If the guard fails (non-zero exit — codex-dev is NOT registered, indicating a stale install): leave the old matcher in place and do NOT rename it. A renamed matcher would point to a non-existent MCP server and silently disable hook interception, which is worse than the legacy state. A-layer (Policy trigger type e — critical intercept): the framework cannot auto-repair this situation; the user must manually run the upgrade. Interrupt the Step 9 briefing and instead emit one A-layer interrupt using the standard wording rule: the local iSparto installation is stale (only the legacy codex-reviewer MCP server is registered), the Lead has skipped the hook-matcher migration to preserve interception, and the user should run ~/.isparto/install.sh --upgrade and then re-run /start-isparto. After emitting the A-layer interrupt, also skip the next bullet (the If any matcher is missing or its hook command is absent: auto-add them auto-add branch) — auto-adding a mcp__codex-dev__codex matcher on a stale install would re-introduce the same silent-disable bug — and proceed directly to Step 8.
   • If any matcher is missing or its hook command is absent:
     • Migration guard (mandatory before auto-adding): Run claude mcp get codex-dev >/dev/null 2>&1 (exit 0 = registered, exit 1 = missing) to verify the codex-dev MCP server is actually reachable. Writing a mcp__codex-dev__codex matcher on a stale install (where the server is still registered under the legacy name codex-reviewer) would point the matcher at a non-existent MCP server and silently disable hook interception, which is worse than leaving the matcher absent.
     • If the guard passes (exit 0 — codex-dev is registered): auto-add the missing matchers (same JSON as /init-isparto step 6). C-layer: auto-repair is silent. Log to session-log at /end-isparto time.
     • If the guard fails (non-zero exit — codex-dev is NOT registered, indicating a stale install): do NOT auto-add any matchers. A partial auto-add would leave the project in an inconsistent mid-state. A-layer (Policy trigger type e — critical intercept): interrupt the Step 9 briefing and emit one A-layer interrupt using the standard wording rule: the local iSparto installation is stale (only the legacy codex-reviewer MCP server is registered at the user level), the Lead has skipped the hook-matcher auto-add to preserve interception, and the user should run ~/.isparto/install.sh --upgrade and then re-run /start-isparto. After emitting the A-layer interrupt, proceed directly to Step 8.
   • This auto-repair ensures projects created before the layered hooks architecture get patched on first /start-isparto
8. Determine the collaboration mode (transparent to user, no mode switch needed):
   • Solo + Codex (default): use unless both Agent Team conditions are met
   • Agent Team: upgrade when BOTH — (1) work is decomposable into independent parallel sub-tasks, AND (2) file count × change size per file justifies coordination overhead (5 files with large changes → Agent Team; 5 files with 1-line edits → Solo)
   • Mode selection itself is B-layer (part of the Step 9 briefing) only when it materially affects the user's next decision (e.g., the user is about to approve a plan and needs to know whether Lead will run Solo or spawn Teammates). Otherwise it is C-layer: decide silently and reflect the mode implicitly in the next-action sentence at Step 9.