thachvd-kit 1.0.35 → 1.0.37

package/skills/subagent-driven-development/task-reviewer-prompt.md

@@ -0,0 +1,207 @@
+# 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 SKILL.md 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: [REPORT_FILE]
+
+    ## Diff Under Review
+
+    **Base:** [BASE_SHA]
+    **Head:** [HEAD_SHA]
+    **Diff file:** [DIFF_FILE]
+
+    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.
+
+    ## You Do Not Dispatch Subagents
+
+    Do all of this review yourself. Never spawn a subagent to review part
+    of the diff, and never spawn another reviewer for a second opinion.
+    This process already provides every review seat the work gets; a
+    reviewer you spawn duplicates one of them at full cost, and its
+    verdict counts for nothing. If the diff feels too large for one
+    pass, review it in passes yourself and say so in your report.
+
+    ## 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.
+
+    Evidence you cannot see is not evidence that doesn't exist. If the
+    report or its test evidence looks truncated, or you cannot locate the
+    results it claims, re-read the file at its stated path — and if it is
+    genuinely missing or garbled, report that as a gap for the controller.
+    Re-running the suite to regenerate what you failed to read is not
+    verification; illegibility of the evidence is not invalidation of it.
+
+    ## 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 the brief lists several files each with its own change (a batched
+    dispatch), check the diff against that list file by file: every listed
+    file must have its corresponding hunk. A listed file the diff never
+    touches is a Missing finding, no matter how clean the rest of the
+    batch looks.
+
+    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
+
+    ### 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 SKILL.md Model Selection
+- `[BRIEF_FILE]` — REQUIRED: the task brief file (`node scripts/task-brief.js 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)
+- `[REPORT_FILE]` — REQUIRED: the file the implementer wrote its detailed
+  report to
+- `[BASE_SHA]` — commit before this task
+- `[HEAD_SHA]` — current commit
+- `[DIFF_FILE]` — REQUIRED: the path the controller wrote the review
+  package to (`node scripts/review-package.js PLAN_FILE BASE HEAD` prints the unique
+  path it wrote; the package never enters the controller's context)
+
+**Reviewer returns:** Spec Compliance verdict (✅/❌/⚠️), Strengths, Issues
+(Critical/Important/Minor), Task quality verdict

package/skills/upstream.json

@@ -0,0 +1,30 @@
+{
+  "obra/superpowers": {
+    "commit": "5bf4e78011075bcfc0dc295f0724994cd123ee71",
+    "files": [
+      "skills/using-git-worktrees/SKILL.md",
+      "skills/subagent-driven-development/SKILL.md",
+      "skills/subagent-driven-development/implementer-prompt.md",
+      "skills/subagent-driven-development/task-reviewer-prompt.md",
+      "skills/subagent-driven-development/re-review-prompt.md",
+      "skills/subagent-driven-development/scripts/review-package",
+      "skills/subagent-driven-development/scripts/sdd-workspace",
+      "skills/subagent-driven-development/scripts/task-brief",
+      "skills/requesting-code-review/code-reviewer.md",
+      "skills/finishing-a-development-branch/SKILL.md"
+    ],
+    "adapted_entrypoints": [
+      "skills/subagent-driven-development/scripts/review-package.js",
+      "skills/subagent-driven-development/scripts/sdd-workspace.js",
+      "skills/subagent-driven-development/scripts/task-brief.js",
+      "skills/subagent-driven-development/scripts/sdd-workspace-lib.js"
+    ],
+    "adapted_files": [
+      "skills/using-git-worktrees/SKILL.md",
+      "skills/subagent-driven-development/SKILL.md",
+      "skills/subagent-driven-development/task-reviewer-prompt.md",
+      "skills/subagent-driven-development/re-review-prompt.md",
+      "skills/finishing-a-development-branch/SKILL.md"
+    ]
+  }
+}

package/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: using-git-worktrees
+description: Use when the user explicitly wants an isolated workspace, especially for parallel feature development
+---
+
+# Using Git Worktrees
+
+## Overview
+
+When isolation is intended, ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
+
+**Core principle:** Determine the intended workspace first. Respect an explicit request to stay on the current branch/workspace. If isolation is requested, prefer native tools, then fall back to git. Never fight the harness.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Step 0: Detect Existing Isolation
+
+**Before creating anything, check if you are already in an isolated workspace.**
+
+```text
+git rev-parse --git-dir
+git rev-parse --git-common-dir
+git rev-parse --show-toplevel
+git rev-parse --show-superproject-working-tree
+git branch --show-current
+```
+
+**Submodule guard:** differing Git directory results are also possible inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
+
+```text
+# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
+git rev-parse --show-superproject-working-tree
+```
+
+**If `--git-dir` differs from `--git-common-dir` (and this is not a submodule):** You are already in a linked worktree. Skip to Step 2 (Project Setup). Do NOT create another worktree.
+
+Report with branch state:
+- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
+- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
+
+**If the values match (or this is a submodule):** You are in a normal repo checkout.
+
+If the user explicitly says to work on the current branch/workspace, stay there. If the user invokes `/using-git-worktrees` or explicitly requests isolation, that is consent to isolate. If intent is unspecified, stay in the current workspace by default. Do not recommend or create a worktree solely because an implementation plan is large, risky, or being executed by SDD. Follow a project-level preference only when it explicitly requires isolation.
+
+Honor any existing declared preference without asking. If isolation is not explicitly requested or required by project policy, skip to Step 2 in the current workspace.
+
+## Step 1: Create Isolated Workspace
+
+**You have two mechanisms. Try them in this order.**
+
+### 1a. Native Worktree Tools (preferred)
+
+The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 2.
+
+Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
+
+Only proceed to Step 1b if you have no native worktree tool available.
+
+### 1b. Git Worktree Fallback
+
+**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
+
+#### Directory Selection
+
+Follow this priority order. Explicit user preference always beats observed filesystem state.
+
+1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
+
+2. **Check for an existing project-local worktree directory:**
+   ```text
+   PowerShell: Test-Path .worktrees; Test-Path worktrees
+   CMD:        if exist .worktrees echo .worktrees & if exist worktrees echo worktrees
+   ```
+   If found, use it. If both exist, `.worktrees` wins.
+
+3. **If there is no other guidance available**, default to `.worktrees/` at the project root.
+
+#### Safety Verification (project-local directories only)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```text
+git check-ignore .worktrees
+```
+
+If `.worktrees` does not exist, check the directory name you will create:
+
+```text
+git check-ignore worktrees
+```
+
+**If NOT ignored:** Add the appropriate entry to `.gitignore`, show that change clearly, and proceed only after the ignore rule is in place. Do not silently commit unrelated changes.
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+#### Create the Worktree
+
+```text
+# Determine the path using the host shell, then run the portable Git command.
+git worktree list --porcelain
+git branch --list <branch>
+git worktree add "<path>" -b "<branch>"       # new branch
+git worktree add "<path>" "<branch>"          # existing, unattached branch
+```
+
+Never reset, force-checkout, delete, or steal an existing branch attached to another worktree.
+
+**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), report that clearly. If isolation was explicitly required, stop rather than silently working on the current branch; otherwise ask whether to continue in the current workspace, then run setup and baseline tests there only with that choice.
+
+## Step 2: Project Setup
+
+Auto-detect and run appropriate setup. Read the repository's `AGENTS.md`, `.agent/docs/tooling.md`, package scripts, and lockfiles first; do not install dependencies that the project workflow does not require:
+
+```text
+package-lock.json -> npm
+pnpm-lock.yaml    -> pnpm
+yarn.lock         -> yarn
+bun.lock*         -> bun
+requirements.txt  -> pip
+uv.lock           -> uv
+Cargo.toml        -> cargo
+go.mod            -> go
+composer.json     -> composer
+```
+
+Use the project's documented bootstrap command after detecting the package manager.
+
+## Step 3: Verify Clean Baseline
+
+Run tests to ensure workspace starts clean:
+
+```text
+# Run the project-appropriate command (one command, not a shell expression):
+npm test
+# or cargo test / pytest / go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### Report
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| Already in linked worktree | Skip creation (Step 0) |
+| In a submodule | Treat as normal repo (Step 0 guard) |
+| Native worktree tool available | Use it (Step 1a) |
+| No native tool | Git worktree fallback (Step 1b) |
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check instruction file, then default `.worktrees/` |
+| Directory not ignored | Add to .gitignore + commit |
+| Permission error on create | Sandbox fallback, work in place |
+| Tests fail during baseline | Report failures + ask |
+| No package.json/Cargo.toml | Skip dependency install |
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "I'm obviously not in a worktree — no need to check" | Run Step 0. Harness-created isolation and submodules both fool eyeballing; the detection commands settle it. |
+| "`git worktree add` is quicker than hunting for a native tool" | A native tool (e.g. `EnterWorktree`) owns placement, branching, and cleanup. Bypassing it is the #1 mistake — it creates phantom state your harness can't see or manage. |
+| "The worktree directory is surely ignored already" | Run `git check-ignore`. An unignored worktree directory commits the whole tree into the repo. |
+| "Any directory name works" | Explicit instructions beat an existing project-local directory, which beats the `.worktrees/` default. |
+| "The workspace is fresh — baseline tests can wait" | A dirty baseline makes every later failure ambiguous. Run the tests now; proceeding past failures is your human partner's call. |