thachvd-kit 1.0.37 → 1.0.39

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

@@ -1,207 +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
+# 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/system-discovery/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: system-discovery
+description: Build or refresh the AS-IS system map for a brownfield multi-repository workspace using Codebase Memory MCP as the primary structural source.
+---
+
+# System Discovery
+
+Use this skill only for documentation/discovery. Do not modify product code.
+
+## Preconditions
+
+- `.thachvd/system.json` exists.
+- Repositories in that manifest have been indexed with Codebase Memory MCP.
+- If the index is stale or missing, stop and tell the user to run `thachvd-kit spec index`.
+
+## Goal
+
+Create a reviewed AS-IS map of what the current system does before detailed reverse-engineered specs are generated.
+
+## Analysis profile
+
+Read `profile` from `.thachvd/system.json`.
+
+- `auto`: infer a practical profile for each repository from code/config evidence. A multi-repo system may mix backend, frontend, mobile, and infra repos. Record inferred profiles with evidence.
+- `backend`: emphasize routes/RPC, middleware, auth/policies, services/domain logic, persistence/migrations/transactions, cache, queues/events/jobs/schedulers, external clients, feature flags, retry/idempotency/concurrency and rollback/failure paths.
+- `frontend`: emphasize routes/navigation, page/component composition, state management, API/data clients, forms/validation, auth/session, feature flags, analytics, accessibility, loading/error/empty states, browser storage and build/runtime config.
+- `fullstack`: apply both backend and frontend emphasis and trace client/server boundaries, shared schemas/types, auth/session propagation, BFF/SSR/server actions, and end-to-end failures.
+- `mobile`: emphasize navigation, lifecycle/background work, local storage/cache, offline/sync, permissions, push, deep links, auth refresh, platform-specific code, device integrations and release config.
+- `infra`: emphasize IaC modules/stacks, environments/workspaces, CI/CD, secrets, IAM, networking, state backends, observability, capacity/autoscaling, deployment ordering, rollback/recovery and destructive-change safeguards.
+
+Profile guidance is a checklist, not a source of truth. Never omit real behavior merely because it falls outside the selected profile.
+
+## Documentation language
+
+Read `language` from `.thachvd/system.json`.
+
+- `vi`: write prose, headings, explanations, and summaries in natural Vietnamese.
+- `en`: write prose, headings, explanations, and summaries in English.
+- Always preserve code identifiers, class/function names, API routes, event/queue names, database/schema names, file paths, commands, and source anchors exactly as they appear in source.
+- When writing Vietnamese, retain the original English technical term in parentheses if translating it would reduce precision.
+
+The implementation and tests are the source of truth. Never invent business intent.
+
+## Read first
+
+1. `.thachvd/system.json`
+2. Existing files under the configured `spec_root`
+3. Relevant `AGENTS.md` / `.agent/docs/*` files when present
+
+## Discovery method
+
+Use Codebase Memory MCP first for structural questions: repository inventory, symbols, entry points, callers/callees, data flow, cross-service links, routes, jobs, events, schedulers, queues, clients, and shared persistence. Use direct file reads only to verify or fill gaps.
+
+Inspect all configured repositories. Pay special attention to framework side paths that are often missed by direct call graphs: middleware, observers/hooks, event listeners, background jobs, schedulers, policies/guards, migrations, CLI commands, configuration, and tests.
+
+Do not document dead code as active behavior unless evidence shows it is reachable or intentionally retained.
+
+## Outputs
+
+Write or update these files under `spec_root`:
+
+- `architecture/system-overview.md`
+- `architecture/repo-map.md`
+- `architecture/capability-map.md`
+- `architecture/integrations.md`
+- `glossary.md`
+
+### system-overview.md
+
+Describe:
+- system purpose as observable from code
+- major actors/interfaces
+- major runtime/deployment components
+- major data stores
+- major external systems
+- top-level business capabilities
+- uncertainty / missing evidence
+
+### repo-map.md
+
+For every repository:
+- responsibility
+- primary entry points
+- owned data or services
+- inbound dependencies
+- outbound dependencies
+- events/queues/jobs
+- important source anchors
+
+### capability-map.md
+
+Group by business capability, not repository boundary.
+
+For every capability:
+- short observable purpose
+- participating repositories
+- primary entry points
+- important data/entities
+- integrations/events
+- candidate scope for later reverse engineering
+
+Add a matrix showing capability × repository participation.
+
+### integrations.md
+
+Document cross-repository and external contracts:
+- HTTP/RPC
+- events/messages/queues
+- scheduled/batch interactions
+- shared database/storage access
+- third-party systems
+
+Include direction, producer/caller, consumer/callee, contract location, and evidence.
+
+### glossary.md
+
+Capture domain terms found in code/tests/docs. Mark ambiguous terms instead of guessing.
+
+## Evidence rules
+
+For every important claim, include the strongest available source anchor: repository + file + symbol/function/class; add line ranges when available.
+
+Classify uncertain statements as one of:
+- Confirmed by implementation
+- Confirmed by tests
+- Inferred
+- Unknown / owner confirmation required
+
+Never turn an inference into a requirement or business rationale.
+
+## Human review gate
+
+End by summarizing:
+- proposed capability boundaries
+- ambiguous ownership
+- suspicious cross-repo coupling
+- missing/uncertain business terminology
+- areas that should be split/merged before detailed specs
+
+Do not proceed to detailed PRD/Design reverse engineering until the user/team approves the capability map.