@xulthekl/team-flow 0.22.4

package/skills/build-executor/implementer-prompt.md

@@ -0,0 +1,162 @@
+# Implementer Subagent Prompt Template
+
+Use this template when dispatching an implementer subagent.
+
+```
+Subagent (general-purpose):
+  description: "Implement Task N: [task name]"
+  model: [MODEL — REQUIRED: choose per build-executor Model Selection; an omitted
+         model silently inherits the session's most expensive one]
+  prompt: |
+    You are implementing Task N: [task name]
+
+    ## Task Description
+
+    Read your task brief first: [BRIEF_FILE]
+    It contains the full task text from the plan.
+
+    ## Context
+
+    [Scene-setting: where this fits, dependencies, architectural context]
+
+    ## Planned Wave
+
+    You are assigned to planned wave [WAVE_ID] with strategy [WAVE_STRATEGY].
+    Read `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution show <change-dir> --json` before editing. Do not start
+    unless all declared dependencies have `pass` review receipts. A `parallel`
+    label permits concurrent dispatch only when the controller confirms the
+    platform supports it; never change the saved wave strategy yourself.
+
+    ## Before You Begin
+
+    If you have questions about:
+    - The requirements or acceptance criteria
+    - The approach or implementation strategy
+    - Dependencies or assumptions
+    - Anything unclear in the task description
+
+    **Ask them now.** Raise any concerns before starting work.
+
+    ## Your Job
+
+    Once you're clear on requirements:
+    1. Implement exactly what the task specifies
+    2. Write tests (following TDD if task says to)
+    3. Verify implementation works
+    4. Commit your work
+    5. Self-review (see below)
+    6. Report back
+
+    Work from: [directory]
+
+    **While you work:** If you encounter something unexpected or unclear, **ask questions**.
+    It's always OK to pause and clarify. Don't guess or make assumptions.
+
+    While iterating, run the focused test for what you're changing; run the
+    full suite once before committing, not after every edit.
+
+    ## Code Organization
+
+    You reason best about code you can hold in context at once, and your edits are more
+    reliable when files are focused. Keep this in mind:
+    - Follow the file structure defined in the plan
+    - Each file should have one clear responsibility with a well-defined interface
+    - If a file you're creating is growing beyond the plan's intent, stop and report
+      it as DONE_WITH_CONCERNS — don't split files on your own without plan guidance
+    - If an existing file you're modifying is already large or tangled, work carefully
+      and note it as a concern in your report
+    - In existing codebases, follow established patterns. Improve code you're touching
+      the way a good developer would, but don't restructure things outside your task.
+
+    ## When You're in Over Your Head
+
+    It is always OK to stop and say "this is too hard for me." Bad work is worse than
+    no work. You will not be penalized for escalating.
+
+    **STOP and escalate when:**
+    - The task requires architectural decisions with multiple valid approaches
+    - You need to understand code beyond what was provided and can't find clarity
+    - You feel uncertain about whether your approach is correct
+    - The task involves restructuring existing code in ways the plan didn't anticipate
+    - You've been reading file after file trying to understand the system without progress
+
+    **How to escalate:** Report back with status BLOCKED or NEEDS_CONTEXT. Describe
+    specifically what you're stuck on, what you've tried, and what kind of help you need.
+    The controller can provide more context, re-dispatch with a more capable model,
+    or break the task into smaller pieces.
+
+    ## Before Reporting Back: Self-Review
+
+    Review your work with fresh eyes. Ask yourself:
+
+    **Completeness:**
+    - Did I fully implement everything in the spec?
+    - Did I miss any requirements?
+    - Are there edge cases I didn't handle?
+
+    **Quality:**
+    - Is this my best work?
+    - Are names clear and accurate (match what things do, not how they work)?
+    - Is the code clean and maintainable?
+
+    **Discipline:**
+    - Did I avoid overbuilding (YAGNI)?
+    - Did I only build what was requested?
+    - Did I follow existing patterns in the codebase?
+
+    **Testing:**
+    - Do tests actually verify behavior (not just mock behavior)?
+    - Did I follow TDD if required?
+    - Are tests comprehensive?
+    - Is the test output pristine (no stray warnings or noise)?
+
+    If you find issues during self-review, fix them now before reporting.
+
+    ## After Review Findings
+
+    If a reviewer finds issues and you fix them, re-run the tests that cover
+    the amended code and append the results to your report file. Reviewers
+    will not re-run tests for you — your report is the test evidence.
+
+    ## Report Format
+
+    Write your full report to [REPORT_FILE]:
+    - What you implemented (or what you attempted, if blocked)
+    - What you tested and test results
+    - **TDD Evidence** (if TDD was required for this task):
+      - RED: command run, relevant failing output before implementation, and why the failure was expected
+      - GREEN: command run and relevant passing output after implementation
+    - Files changed
+    - Self-review findings (if any)
+    - Any issues or concerns
+    - Planned wave ID and commit base/head
+
+    `[REPORT_FILE]` is the **implementer report path**. Do not invent or reuse
+    it as review evidence: after a reviewer completes, the controller writes a
+    separate persisted review report and records that separate path in the wave
+    receipt.
+
+    Then report back with ONLY (under 15 lines — the detail lives in the
+    report file):
+    - **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+    - Commits created (short SHA + subject)
+    - One-line test summary (e.g. "14/14 passing, output pristine")
+    - Your concerns, if any
+    - The report file path
+
+    If BLOCKED or NEEDS_CONTEXT, put the specifics in the final message
+    itself — the controller acts on it directly.
+
+    Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness.
+    Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need
+    information that wasn't provided. Never silently produce work you're unsure about.
+```
+
+**Placeholders:**
+- `[task name]` — short name for the task
+- `[MODEL]` — REQUIRED: implementer model per build-executor Model Selection
+- `[BRIEF_FILE]` — REQUIRED: the task brief file (`scripts/task-brief PLAN N` prints the path)
+- `[directory]` — working directory for the implementation
+- `[REPORT_FILE]` — REQUIRED: the file path where the implementer writes its full report
+
+**Implementer returns:** Status (DONE/DONE_WITH_CONCERNS/BLOCKED/NEEDS_CONTEXT), commits, test summary, concerns, report file path.

package/skills/build-executor/references/execution-modes.md

@@ -0,0 +1,86 @@
+# Execution Modes Reference
+
+> 从 build-executor SKILL.md 提取的详细执行模式说明。
+
+## Mode Selection Flow
+
+For `full`/`hotfix`, generate proposed waves from the approved contract, then use the recommendation as a decision aid:
+
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf execution recommend <change-dir> \
+  --wave <wave-id>:<parallel|serial>:<task,...>[:<depends-on,...>] --json
+# Show every available mode, the observed facts, and the recommendation to the user.
+npx --yes --package @xulthekl/team-flow@0.22.4 tf execution plan <change-dir> \
+  --mode <selected-mode> --confirm --reason "user-selected execution mode" \
+  --wave <wave-id>:<parallel|serial>:<task,...>[:<depends-on,...>]
+# Add --acknowledge-recommendation when the selection differs from the recommendation.
+npx --yes --package @xulthekl/team-flow@0.22.4 tf execution show <change-dir> --json
+```
+
+The optional fourth `--wave` segment names prerequisite wave IDs. `execution show --json` reports `current`, plus each wave's `depends_on`, `receipt`, `blockers`, `retryable`, and `eligible` status.
+
+## Mode Criteria
+
+| Mode | Criteria |
+|------|----------|
+| **SDD** | Recommended for parallel waves, multiple waves, or work beyond the inline threshold |
+| **Inline** | Recommended for a single sequential task; always available for a user-confirmed choice |
+| **Batch Inline** | Recommended for a bounded sequential batch; it remains serial and is never presented as parallel |
+
+## SDD Workflow
+
+Dispatch according to the persisted plan, review each planned wave, and run a final broad review after all waves.
+
+### Planned-Wave Loop
+1. Read the current plan with `tf execution show <change-dir> --json`; only waves with `current: true` and `eligible: true` may start.
+2. A `parallel` wave may dispatch independent tasks simultaneously only when the platform supports concurrent dispatch.
+3. A `serial` wave dispatches one task at a time in listed order.
+4. After every wave, write a review report, then record one receipt:
+   ```bash
+   npx --yes --package @xulthekl/team-flow@0.22.4 tf execution review <change-dir> \
+     --wave <wave-id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>
+   ```
+5. Critical/Important findings require a `fail` receipt, focused repair, re-review, then replacement `pass` receipt.
+
+### Per-Task Loop
+1. **Dispatch implementer**: Load template with `tf runtime asset read skills/build-executor/implementer-prompt.md`. Extract task brief with `scripts/task-brief PLAN_FILE N`.
+2. **Handle response**: DONE → review. DONE_WITH_CONCERNS → assess. NEEDS_CONTEXT → provide. BLOCKED → re-dispatch or escalate.
+3. **Review**: Load `tf runtime asset read skills/build-executor/task-reviewer-prompt.md`.
+4. **Fix**: If Critical/Important, write `fail` receipt, dispatch fix, re-review, write `pass` receipt.
+5. **Mark complete**: Append to `.superpowers/sdd/progress.md`.
+
+## Batch Inline Execution
+
+Only when user explicitly confirms `batch-inline`. Current agent executes directly and serially. TDD Iron Law still applies.
+
+Procedure: announce mode → write failing test → confirm failure → implement → run suite → refactor → lightweight checkpoint → report.
+
+Boundaries: if any task touches >1 module, involves schema/API/config changes, or has open questions → downgrade to Inline or SDD.
+
+## Inline Execution Mode
+
+Only after user-confirmed `inline` selection is recorded. Executes in current session, writes one review receipt per planned wave.
+
+Per-task: extract brief → write failing test → confirm failure → implement → confirm green → checkpoint review → commit → save recovery checkpoint → append to progress ledger.
+
+## Model Selection
+
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime config --resolve-model <profile>
+```
+
+| Profile | Role |
+|---|---|
+| `mechanical` | Cheap, routine edits |
+| `standard` | Integration and judgment work |
+| `strong` | Architecture, design, and final review |
+| `review` | Review that matches the diff |
+
+## Recovery Checkpoint
+
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf checkpoint save <change-dir> \
+  --task <completed-task-id> --next "<next task>" --completed "<completed work>" \
+  --verification "<verification report path>" --review "<review report path>" \
+  --risk "<open risk or None>" --commit-start <base-sha> --commit-end <head-sha>
+```

package/skills/build-executor/task-reviewer-prompt.md

@@ -0,0 +1,195 @@
+# Task Reviewer Prompt Template
+
+Use this template when dispatching a task reviewer subagent. The reviewer
+reads the task's diff once and returns two verdicts: spec compliance and
+code quality.
+
+**Purpose:** Verify one task's implementation matches its requirements (nothing
+more, nothing less) and is well-built (clean, tested, maintainable)
+
+```
+Subagent (general-purpose):
+  description: "Review Task N (spec + quality)"
+  model: [MODEL — REQUIRED: choose per build-executor Model Selection; an omitted
+         model silently inherits the session's most expensive one]
+  prompt: |
+    You are reviewing one task's implementation: first whether it matches its
+    requirements, then whether it is well-built. This is a task-scoped gate,
+    not a merge review — a broad whole-branch review happens separately after
+    all tasks are complete.
+
+    ## What Was Requested
+
+    Read the task brief: [BRIEF_FILE]
+
+    Global constraints from the spec/design that bind this task:
+    [GLOBAL_CONSTRAINTS]
+
+    ## What the Implementer Claims They Built
+
+    Read the implementer's report: [IMPLEMENTER_REPORT_FILE]
+
+    ## Diff Under Review
+
+    **Base:** [BASE_SHA]
+    **Head:** [HEAD_SHA]
+    **Diff file:** [DIFF_FILE]
+
+    **Planned wave:** [WAVE_ID]
+
+    Read the diff file once — it contains the commit list, a stat summary,
+    and the full diff with surrounding context, and it is your view of the
+    change. The diff's context lines ARE the changed files: do not Read a
+    changed file separately unless a hunk you must judge is cut off
+    mid-function — and say so in your report. Do not re-run git commands.
+    If the diff file is missing, fetch the diff yourself:
+    `git diff --stat [BASE_SHA]..[HEAD_SHA]` and `git diff [BASE_SHA]..[HEAD_SHA]`.
+    Do not crawl the broader codebase. Inspect code outside the diff only
+    to evaluate a concrete risk you can name — one focused check per named
+    risk, and name both the risk and what you checked in your report.
+    Cross-cutting changes are legitimate named risks: if the diff changes
+    lock ordering, a function or API contract, or shared mutable state,
+    checking the call sites is the right method.
+
+    Your review is read-only on this checkout. Do not mutate the working
+    tree, the index, HEAD, or branch state in any way.
+
+    ## Do Not Trust the Report
+
+    Treat the implementer's report as unverified claims about the code. It
+    may be incomplete, inaccurate, or optimistic. Verify the claims against
+    the diff. Design rationales in the report are claims too: "left it per
+    YAGNI," "kept it simple deliberately," or any other justification is the
+    implementer grading their own work. Judge the code on its merits — a
+    stated rationale never downgrades a finding's severity.
+
+    ## Tests
+
+    The implementer already ran the tests and reported results with TDD
+    evidence for exactly this code. Do not re-run the suite to confirm their
+    report. Run a test only when reading the code raises a specific doubt
+    that no existing run answers — and then a focused test, never a
+    package-wide suite, race detector run, or repeated/high-count loop. If
+    heavy validation seems warranted, recommend it in your report instead of
+    running it. If you cannot run commands in this environment, name the
+    test you would run.
+
+    Warnings or other noise in the implementer's reported test output are
+    findings — test output should be pristine.
+
+    ## Part 1: Spec Compliance
+
+    Compare the diff against What Was Requested:
+
+    - **Missing:** requirements they skipped, missed, or claimed without
+      implementing
+    - **Extra:** features that weren't requested, over-engineering, unneeded
+      "nice to haves"
+    - **Misunderstood:** right feature built the wrong way, wrong problem
+      solved
+
+    If a requirement cannot be verified from this diff alone (it lives in
+    unchanged code or spans tasks), report it as a ⚠️ item instead of
+    broadening your search.
+
+    ## Part 2: Code Quality
+
+    **Code quality:**
+    - Clean separation of concerns?
+    - Proper error handling?
+    - DRY without premature abstraction?
+    - Edge cases handled?
+
+    **Tests:**
+    - Do the new and changed tests verify real behavior, not mocks?
+    - Are the task's edge cases covered?
+
+    **Structure:**
+    - Does each file have one clear responsibility with a well-defined interface?
+    - Are units decomposed so they can be understood and tested independently?
+    - Is the implementation following the file structure from the plan?
+    - Did this change create new files that are already large, or
+      significantly grow existing files? (Don't flag pre-existing file
+      sizes — focus on what this change contributed.)
+
+    Your report should point at evidence: file:line references for every
+    finding and for any check you would otherwise answer with a bare
+    "yes." A tight report that cites lines gives the controller everything
+    it needs.
+
+    Your final message is the report itself: begin directly with the
+    spec-compliance verdict. Every line is a verdict, a finding with
+    file:line, or a check you ran — no preamble, no process narration,
+    no closing summary.
+
+    ## Calibration
+
+    Categorize issues by actual severity. Not everything is Critical.
+    Important means this task cannot be trusted until it is fixed: incorrect
+    or fragile behavior, a missed requirement, or maintainability damage you
+    would block a merge over — verbatim duplication of a logic block,
+    swallowed errors, tests that assert nothing. "Coverage could be broader"
+    and polish suggestions are Minor.
+    If the plan or brief explicitly mandates something this rubric calls a
+    defect (a test that asserts nothing, verbatim duplication of a logic
+    block), that IS a finding — report it as Important, labeled
+    plan-mandated. The plan's authorship does not grade its own work; the
+    human decides.
+    Acknowledge what was done well before listing issues — accurate praise
+    helps the implementer trust the rest of the feedback.
+
+    ## Output Format
+
+    Write your full review to [REVIEW_REPORT_FILE]. This distinct review report
+    path must point to a non-empty, persisted review report before the
+    controller records a receipt. After the verdict, provide the exact receipt
+    command for the controller:
+
+    ```bash
+    npx --yes --package @xulthekl/team-flow@0.22.4 tf execution review <change-dir> --wave [WAVE_ID] --base [BASE_SHA] --head [HEAD_SHA] --report [REVIEW_REPORT_FILE] --verdict <pass|fail>
+    ```
+
+    Use `fail` for any Critical/Important finding. A repair must be re-reviewed
+    and recorded with a replacement `pass` receipt before a dependent wave may start.
+
+    ### Spec Compliance
+
+    - ✅ Spec compliant | ❌ Issues found: [what's missing/extra/misunderstood,
+      with file:line references]
+    - ⚠️ Cannot verify from diff: [requirements you could not verify from the
+      diff alone, and what the controller should check — report alongside the
+      ✅/❌ verdict for everything you could verify]
+
+    ### Strengths
+    [What's well done? Be specific.]
+
+    ### Issues
+
+    #### Critical (Must Fix)
+    #### Important (Should Fix)
+    #### Minor (Nice to Have)
+
+    For each issue: file:line, what's wrong, why it matters, how to fix
+    (if not obvious).
+
+    ### Assessment
+
+    **Task quality:** [Approved | Needs fixes]
+
+    **Reasoning:** [1-2 sentence technical assessment]
+```
+
+**Placeholders:**
+- `[MODEL]` — REQUIRED: reviewer model per build-executor Model Selection
+- `[BRIEF_FILE]` — REQUIRED: the task brief file (`scripts/task-brief PLAN N` prints the path; same file the implementer worked from)
+- `[GLOBAL_CONSTRAINTS]` — the binding requirements copied verbatim from the plan's Global Constraints section or the spec: exact values, formats, and stated relationships between components (not process rules — those are already in this template)
+- `[IMPLEMENTER_REPORT_FILE]` — REQUIRED: the file the implementer wrote its detailed report to
+- `[REVIEW_REPORT_FILE]` — REQUIRED: a distinct, persisted, non-empty file where the reviewer writes this review; this exact path is stored in the receipt
+- `[BASE_SHA]` — commit before this task
+- `[HEAD_SHA]` — current commit
+- `[DIFF_FILE]` — REQUIRED: the path the controller wrote the review package to (`scripts/review-package BASE HEAD` prints the unique path it wrote; the package never enters the controller's context)
+- `[WAVE_ID]` — REQUIRED: the execution-plan wave being reviewed
+
+**Reviewer returns:** Spec Compliance verdict (✅/❌/⚠️), Strengths, Issues (Critical/Important/Minor), Task quality verdict
+
+A fix dispatch can address spec gaps and quality findings together; re-review after fixes covers both verdicts.