thachvd-kit 1.0.36 → 1.0.38

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 thachvd
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 thachvd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -27,6 +27,218 @@ thachvd-kit doctor
 
 After the first skill install, run `/setup-matt-pocock-skills` once inside your AI client to configure the issue tracker, triage labels, and generated docs location — thachvd-kit does not simulate that skill.
 
+## Brownfield System Specs
+
+This workflow is **opt-in**. Normal `thachvd-kit init/upgrade -> setup -> development` behavior is unchanged unless you run `thachvd-kit spec init`.
+
+The same happy path works for **one repository or many**:
+
+```bash
+cd your-repo-or-workspace
+
+thachvd-kit spec init --language vi   # optional; omit for English
+thachvd-kit spec index
+thachvd-kit spec discover
+
+# In your AI client:
+# /system-discovery
+
+# Human-review:
+# system-specs/architecture/capability-map.md
+
+thachvd-kit spec reverse
+
+# In your AI client:
+# /system-reverse-engineer
+
+thachvd-kit spec verify
+
+# In your AI client:
+# /system-spec-review
+
+thachvd-kit spec check
+thachvd-kit spec link
+```
+
+### Documentation language
+
+Use `--language vi` when you want human-facing specs in Vietnamese:
+
+```bash
+thachvd-kit spec init --language vi
+```
+
+If Vietnamese is your normal preference across projects, set it once at user level:
+
+```bash
+thachvd-kit config set spec-language vi
+```
+
+Then plain `thachvd-kit spec init` uses Vietnamese by default. A project-level `--language en|vi` always overrides the user default. Use `thachvd-kit config show` to inspect the current setting.
+
+The setting is stored in `.thachvd/system.json` and reused by `/system-discovery`, `/system-reverse-engineer`, and `/system-spec-review`. Only prose/headings/explanations are localized; code identifiers, class/function names, API routes, event/queue names, database/schema names, file paths, commands, and source anchors remain exactly as they appear in source. Default is `en`.
+
+### Analysis profiles
+
+Profiles adjust what discovery/reverse/review should inspect most carefully. They do **not** override code/tests and they do not hide behavior outside the selected profile.
+
+The default is `auto`, so the normal command remains:
+
+```bash
+thachvd-kit spec init
+```
+
+In `auto` mode, the agent infers a practical profile for each repository from code/config evidence. A multi-repo system can therefore contain a backend API, frontend app, worker and infra repo without forcing one profile across all of them.
+
+You can explicitly bias the checklist when a project is known:
+
+```bash
+thachvd-kit spec init --profile backend
+thachvd-kit spec init --profile frontend
+thachvd-kit spec init --profile fullstack
+thachvd-kit spec init --profile mobile
+thachvd-kit spec init --profile infra
+```
+
+Current emphasis:
+
+- `backend`: routes/RPC, auth/policies, services/domain, DB/migrations/transactions, queues/jobs/events/schedulers, retries/idempotency/concurrency, external clients and rollback/failure behavior.
+- `frontend`: routes/navigation, components/pages, state/data clients, forms/validation, auth/session, accessibility, analytics, loading/error states, browser storage and runtime/build config.
+- `fullstack`: both sides plus client/server contracts, shared schemas/types, auth propagation, SSR/BFF/server actions and end-to-end failures.
+- `mobile`: app lifecycle/background work, offline/sync, local storage, permissions, push/deep links, auth refresh, platform/device integrations and release config.
+- `infra`: IaC, environments, CI/CD, secrets/IAM/networking, state backends, observability, scaling, deployment order, rollback/recovery and destructive-change safeguards.
+
+Set a user default if you frequently work on the same class of project:
+
+```bash
+thachvd-kit config set spec-profile backend
+```
+
+Precedence is: explicit `--profile` → user config → `auto`.
+
+### Automatic repository detection
+
+`spec init` does not require `--repo` in the normal case:
+
+- if the current directory is a Git repository, it is treated as a single-repo system;
+- otherwise, direct child Git repositories are detected as a multi-repo system;
+- `--repo` remains available only as an override for unusual directory layouts.
+
+For a single repo, `system-specs/` lives in that repo. For multiple repos, run from the common workspace directory; that workspace owns `.thachvd/system.json` and `system-specs/`.
+
+For team use, make sure the configured `spec_root` is version-controlled. In a single repo this happens naturally. In a multi-repo workspace whose parent directory is not itself a Git worktree, use a dedicated docs/spec Git repository or set `--spec-root` to a location that is committed. `thachvd-kit spec doctor` warns when the spec root is not in a committed Git worktree; the kit does not silently initialize or choose a remote repository for you.
+
+`spec init` also installs the bundled `/system-discovery`, `/system-reverse-engineer`, and `/system-spec-review` skills into the workspace so the flow can run from the common parent directory.
+
+### What the AI phases do
+
+`/system-discovery` builds the coarse AS-IS map first:
+
+- system overview
+- repository responsibilities
+- capability map
+- cross-repository integrations
+- domain glossary
+
+A human reviews the capability boundaries before deep documentation begins.
+
+Then `thachvd-kit spec reverse` writes the handoff for `/system-reverse-engineer`. With **no capability argument**, one invocation processes the entire approved capability map and creates/updates:
+
+- `system-specs/capabilities/<capability>/prd.md`
+- `system-specs/capabilities/<capability>/design.md`
+- real cross-repository flow specs under `system-specs/flows/`
+- real cross-boundary contracts under `system-specs/contracts/`
+
+Internally the agent works capability-by-capability, persists progress to `system-specs/_meta/reverse-progress.json`, and resumes incomplete capabilities on later invocations. The user does **not** need to manually run one command per module.
+
+A capability argument is only a targeted refresh:
+
+```bash
+thachvd-kit spec reverse booking
+```
+
+Use that later when only Booking changed or needs to be re-documented.
+
+### Independent verification and drift detection
+
+After reverse engineering finishes:
+
+```bash
+thachvd-kit spec verify
+# In your AI client: /system-spec-review
+thachvd-kit spec check
+```
+
+`/system-spec-review` independently reconstructs implementation coverage and tries to find missing behavior, unsupported claims, weak/broken source anchors, PRD/design contradictions, and cross-repository contract gaps. It writes:
+
+- `system-specs/_meta/review.md`
+- `system-specs/_meta/verification.json`
+
+The verification JSON stores a full-system repository snapshot plus **capability-specific `verified_commits` and repository-relative `source_paths`**. `spec check` compares each capability against its own baseline, including committed, staged, unstaged, and untracked changes, so re-verifying one capability cannot accidentally make unrelated specs look current.
+
+Use `thachvd-kit spec check --strict` in CI when stale/unknown specs should fail the check.
+
+For an incremental refresh:
+
+```bash
+thachvd-kit spec reverse booking
+# /system-reverse-engineer
+thachvd-kit spec verify booking
+# /system-spec-review
+thachvd-kit spec check
+```
+
+Only Booking's verification baseline advances; unrelated capabilities keep their previous verified commits.
+
+The reverse author is not allowed to call its own output independently verified; only the review phase may mark a capability `verified`.
+
+### Spec health check
+
+`thachvd-kit spec doctor` is read-only and summarizes the documentation system in one place:
+
+- configured repos and Git HEAD availability
+- Codebase Memory availability
+- system-spec skills installed on agent surfaces
+- capability map presence
+- reverse checkpoint progress
+- independent verification/review metadata
+- current drift state
+- whether the spec root is version-controlled
+- AGENTS.md links
+
+```bash
+thachvd-kit spec doctor
+thachvd-kit spec doctor --strict
+```
+
+`--strict` exits non-zero when any WARN/ERROR remains, which is useful for CI or release gates.
+
+### Optional Shinpr recipe integration
+
+`recipe-reverse-engineer` is no longer part of the required flow. If you use Claude Code and want its extra generate -> verify -> review -> revise loop for individual implementation scopes, install it once:
+
+```bash
+thachvd-kit spec recipe-setup
+```
+
+The bundled `/system-reverse-engineer` skill may use that helper when available, but it still works without it.
+
+### Flow summary
+
+1. `spec init` auto-detects one or many repos and creates the workspace/spec structure.
+2. `spec index` indexes all configured repos with codebase-memory-mcp.
+3. `spec discover` creates the handoff for `/system-discovery`.
+4. Human review confirms the system/capability boundaries.
+5. `spec reverse` creates/resumes the whole-system `/system-reverse-engineer` checkpoint.
+6. The author agent writes AS-IS PRD/design/flow/contract docs using fixed templates.
+7. `spec verify` creates the handoff for independent `/system-spec-review`.
+8. The reviewer writes machine-readable verification/provenance metadata.
+9. `spec check` detects code/spec drift deterministically from Git.
+10. `spec doctor` provides a read-only health summary for the spec system.
+11. `spec link` adds an idempotent managed block to each repo's `AGENTS.md` so future agents discover and check the reviewed system specs. By default it refuses to link when any capability is not independently `verified`; `--allow-unverified` is an explicit escape hatch.
+
+Observed behavior from code/tests and undocumented business rationale must remain distinct. Existing human-edited spec docs are not overwritten by `spec init --yes`.
+
 ## Generated Files
 
 - `AGENTS.md`: shared project instructions.
@@ -141,12 +353,27 @@ Examples: `rtk git status`, `rtk npm test`, `rtk git log`. If it is not installe
 thachvd-kit init [--yes]
 thachvd-kit upgrade [--dry-run]
 thachvd-kit global [--dry-run] [--antigravity-only|--codex-only]
+thachvd-kit config show
+thachvd-kit config set spec-language en|vi
+thachvd-kit config unset spec-language
+thachvd-kit config set spec-profile auto|backend|frontend|fullstack|mobile|infra
+thachvd-kit config unset spec-profile
 thachvd-kit setup [--no-setup-mcp] [--no-setup-hook] [--no-install-rtk] [--no-index] [--no-install-skills]
 thachvd-kit doctor
 thachvd-kit prompt
 thachvd-kit skills install [--dry-run]
 thachvd-kit skills check
 thachvd-kit skills update [--dry-run]
+thachvd-kit spec init [--name NAME] [--language en|vi] [--profile auto|backend|frontend|fullstack|mobile|infra] [--repo PATH ...] [--spec-root PATH] [--yes]
+thachvd-kit spec index [--repo NAME ...] [--dry-run]
+thachvd-kit spec discover
+thachvd-kit spec reverse [CAPABILITY] [--reset]
+thachvd-kit spec verify [CAPABILITY]
+thachvd-kit spec check [--strict]
+thachvd-kit spec doctor [--strict]
+thachvd-kit spec recipe-setup [--fullstack] [--dry-run]   # optional Claude Code helper
+thachvd-kit spec link [--dry-run] [--allow-unverified]
+thachvd-kit spec status
 thachvd-kit --help
 ```
 
@@ -163,3 +390,16 @@ npm run release:verify
 ```
 
 Release only from a clean, verified, pushed `main` branch. `npm publish` requires valid npm authentication and any configured 2FA code.
+
+## Native Workflow Skills
+
+The workflow layer combines Matt Pocock's planning and implementation skills with thachvd-kit's bundled native skills. `thachvd-kit setup` and `thachvd-kit skills install` install the native set to both `.agents/skills/` and `.claude/skills/`.
+
+- `/using-git-worktrees` is opt-in workspace isolation; an explicit choice to work on the current branch always wins.
+- `/subagent-driven-development` is an alternative executor to `/implement` for plans with multiple relatively independent tasks. It uses bundled cross-platform Node entrypoints on Windows and falls back to `/implement` when subagent dispatch is unavailable.
+- `/finishing-a-development-branch` verifies and hands off a branch, cleaning only manually managed project-local worktrees safely.
+- `/system-discovery` builds the reviewed AS-IS repo/capability/integration map for a brownfield system with one or many repositories, using Codebase Memory MCP as the primary structural source.
+- `/system-reverse-engineer` turns the approved map into PRD/design/flow/contract specs for the whole system, using a durable checkpoint so large systems can resume safely; a named capability is only a targeted refresh.
+- `/system-spec-review` independently verifies coverage/evidence and writes commit/source-path provenance used by `spec check` for drift detection.
+
+`thachvd-kit skills update` refreshes native skills from bundled repository copies and never fetches Superpowers at runtime. See `THIRD_PARTY_NOTICES.md` for recorded upstream provenance.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,49 @@
+# Third-Party Notices
+
+## Superpowers
+
+Repository: https://github.com/obra/superpowers
+Upstream commit: `5bf4e78011075bcfc0dc295f0724994cd123ee71`
+
+Portions of the worktree and subagent-driven development workflows are derived from:
+
+- `skills/using-git-worktrees/SKILL.md`
+- `skills/subagent-driven-development/`
+- `skills/requesting-code-review/code-reviewer.md`
+- `skills/finishing-a-development-branch/SKILL.md`
+
+The vendored source is retained for comparison with the recorded upstream commit. Adapted Windows/runtime entrypoints are documented in the native skill directory and do not replace the upstream source scripts.
+
+Copyright (c) 2025 Jesse Vincent
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+### Vendoring maintenance
+
+To refresh these files deliberately:
+
+1. Fetch the latest `obra/superpowers` repository.
+2. Inspect changes to the recorded upstream files and compare them with the recorded SHA.
+3. Port relevant upstream changes and reapply only the minimal thachvd-kit adaptations.
+4. Update `skills/upstream.json` and this notice with the new SHA.
+5. Run the native-skill regression tests and the full release verification.
+
+`thachvd-kit skills update` never fetches Superpowers. Runtime updates use the repository-owned vendored copies.

package/bin/cli.js

@@ -7,6 +7,7 @@ const prompts = require('prompts');
 const pc = require('picocolors');
 const packageJson = require('../package.json');
 const mattSkills = require('./matt-skills');
+const nativeSkills = require('./native-skills');
 const {
     QUALITY_FLOOR_SECTION,
     AGENT_RULES_SECTION,
@@ -47,12 +48,16 @@ ${pc.bold('Usage:')}
   thachvd-kit init [--yes]
   thachvd-kit upgrade [--dry-run]
   thachvd-kit global [--dry-run] [--antigravity-only|--codex-only]
+  thachvd-kit config show
+  thachvd-kit config set spec-language en|vi
+  thachvd-kit config set spec-profile auto|backend|frontend|fullstack|mobile|infra
   thachvd-kit setup [--yes] [--no-install-skills]
   thachvd-kit doctor
   thachvd-kit prompt
   thachvd-kit skills install [--dry-run]
   thachvd-kit skills check
   thachvd-kit skills update [--dry-run]
+  thachvd-kit spec --help
   thachvd-kit --version
   thachvd-kit --help
 
@@ -60,10 +65,12 @@ ${pc.bold('Commands:')}
   init      Generate project context files and documentation (new projects)
   upgrade   Safely add/update thachvd-kit's managed policy blocks in an existing project (does not rescan or regenerate)
   global    Patch a managed tool-routing block into the current user's Antigravity/Codex global instructions
+  config    Read or update user-level spec defaults such as language and analysis profile
   setup     Install/configure MCP, Matt Pocock skills, and recommended local tooling
   doctor    Check project context and local integrations
   prompt    Print the saved project-indexing prompt again
   skills    Install, check, or update the promoted Matt Pocock skill set
+  spec      Brownfield system documentation for one or many repositories
 
 ${pc.bold('Options:')}
   --yes     Overwrite generated files or accept setup defaults
@@ -71,7 +78,7 @@ ${pc.bold('Options:')}
   --no-setup-hook Skip the Claude Code Definition-of-Done Stop hook during setup
   --no-install-rtk Skip auto-installing rtk via cargo during setup
   --no-index      Skip auto-indexing the repository with codebase-memory-mcp during setup
-  --no-install-skills Skip installing Matt Pocock skills during setup
+  --no-install-skills Skip installing Matt Pocock and thachvd-kit native skills during setup
   --dry-run Preview a change without writing it (upgrade/global/skills install/skills update)
   --antigravity-only Limit global to the Antigravity global instructions
   --codex-only    Limit global to the Codex global instructions
@@ -86,10 +93,12 @@ ${pc.bold('What gets generated:')}
   .agent/docs/ Project context, architecture, workflow, tooling, and durable onboarding prompt
 
 ${pc.bold('Workflow:')}
-  Matt Pocock's promoted skills (installed under .agents/skills/) are the
-  workflow layer. Use the matching skill when a specialized workflow is
-  useful; if unsure which one, use /ask-matt. Do not invoke a heavyweight
-  skill for a localized, obvious change.
+  Matt Pocock's promoted skills plus thachvd-kit's native worktree/SDD skills
+  form the workflow layer. Use /using-git-worktrees only when isolation is
+  intended; choose /implement or /subagent-driven-development as alternative
+  executors for a plan, then finish with /code-review and
+  /finishing-a-development-branch.
+  Unsure which planning or implementation skill fits? Use /ask-matt.
 
 ${pc.bold('Tip:')}
   Run thachvd-kit setup to install the promoted skill set and configure
@@ -1018,7 +1027,7 @@ ${QUALITY_FLOOR_SECTION}
 function generateWorkflowDoc() {
     return `# Agent Workflow
 
-This project uses Matt Pocock's promoted skills (installed under .agents/skills/ by \`thachvd-kit setup\`) as the workflow layer. thachvd-kit only provides project context, the skill manifest, and integration setup; it is not a second workflow engine.
+This project uses Matt Pocock's promoted skills plus thachvd-kit's native workflow skills (installed under .agents/skills/ and .claude/skills/ by \`thachvd-kit setup\`) as the workflow layer. Native skills add opt-in workspace isolation, subagent-driven execution, and branch finishing; they do not replace Matt's planning, implementation, testing, or review skills.
 
 ## Before Every Task
 
@@ -1035,8 +1044,8 @@ This project uses Matt Pocock's promoted skills (installed under .agents/skills/
 | Question or research only | direct answer or research | no product-code edits |
 | Clear, localized change | fast path (no skill) | inspect -> edit -> focused verify |
 | Ambiguous feature or design | /grill-with-docs, then optionally /to-spec | durable contract before implementation when useful |
-| Normal feature | /grill-with-docs -> /to-spec -> /implement | spec agreed before implementation |
-| Large feature needing decomposition | /grill-with-docs -> /to-spec -> /to-tickets -> /implement | tickets agreed before implementation |
+| Normal feature | /grill-with-docs -> /to-spec -> choose workspace -> /implement | spec agreed before implementation |
+| Large feature needing decomposition | /grill-with-docs -> /to-spec -> /to-tickets -> choose workspace -> executor | tickets agreed before implementation |
 | Huge, multi-session uncertainty | /wayfinder | shared decision map before implementation |
 | Bug or failing behavior | /diagnosing-bugs | reproduce -> root cause -> regression protection -> fix -> verify |
 | Test-driven implementation | /tdd | red -> green -> refactor per slice |
@@ -1047,7 +1056,9 @@ Not sure which row applies? Run /ask-matt instead of guessing.
 
 ## Standard Feature Flow
 
-/grill-with-docs -> /to-spec -> (/to-tickets for large work) -> /implement (with /tdd where it helps) -> /code-review.
+/grill-with-docs -> /to-spec -> (/to-tickets for large work) -> choose workspace -> choose executor (/implement or /subagent-driven-development) -> /code-review -> /finishing-a-development-branch.
+
+Choose the current branch/workspace when the user explicitly wants to work there. Use /using-git-worktrees only when isolation is requested or appropriate workspace isolation already exists. SDD is for plans with multiple relatively independent tasks and falls back to /implement when subagent dispatch is unavailable; it never forces a worktree.
 
 ${FAST_PATH_SECTION}
 
@@ -1063,13 +1074,13 @@ ${FAST_PATH_SECTION}
 function generateGettingStartedDoc() {
     return `# Getting Started
 
-thachvd-kit creates project context. Matt Pocock's promoted skills own the development workflow.
+thachvd-kit creates project context. Matt Pocock's promoted and thachvd-kit native skills own the development workflow.
 
 ## Setup
 
 1. Run \`thachvd-kit init\` in the repository.
 2. Open or print \`.agent/docs/index-project-prompt.md\` with \`thachvd-kit prompt\`.
-3. Run \`thachvd-kit setup\` (installs the promoted skill set by default; add \`--no-install-skills\` to skip) and RTK.
+3. Run \`thachvd-kit setup\` (installs promoted and native skill sets by default; add \`--no-install-skills\` to skip) and RTK.
 4. Inside the AI client, run \`/setup-matt-pocock-skills\` once to configure the issue tracker, triage labels, and doc layout.
 5. Run \`thachvd-kit doctor\` and restart the AI client.
 
@@ -1116,9 +1127,9 @@ function generateToolingDoc(data) {
 
 Run \`thachvd-kit doctor\` to check the current machine.
 
-## Matt Pocock Skills
+## Matt Pocock Skills + Native Workflow Skills
 
-Matt Pocock's promoted engineering and productivity skills are the workflow layer for this project, installed project-locally under \`.agents/skills/\` (never globally):
+Matt Pocock's promoted engineering and productivity skills are installed project-locally under \`.agents/skills/\` (never globally). thachvd-kit also bundles native workflow skills to both \`.agents/skills/\` and \`.claude/skills/\`:
 
 - Install the promoted set: \`thachvd-kit skills install\` (\`--dry-run\` to preview the command without running it)
 - Check what is installed: \`thachvd-kit skills check\` (read-only)
@@ -1126,6 +1137,8 @@ Matt Pocock's promoted engineering and productivity skills are the workflow laye
 - The full manifest lives in \`bin/matt-skills.js\` (\`PROMOTED_SKILLS\`); it mirrors upstream's \`skills/engineering/\` + \`skills/productivity/\` catalog and never includes \`in-progress\`, \`misc\`, or \`deprecated\` skills.
 - After the first install, run \`/setup-matt-pocock-skills\` once inside the AI client to configure the issue tracker, triage labels, and generated docs location. thachvd-kit does not simulate that skill.
 - Unsure which skill fits a task? Run \`/ask-matt\`.
+- Native skills: \`/using-git-worktrees\` (opt-in isolation), \`/subagent-driven-development\` (alternative executor for multi-task plans), and \`/finishing-a-development-branch\`.
+- SDD's upstream shell scripts are retained for provenance; cross-platform Node entrypoints are used by the adapted workflow on Windows.
 
 ${TOOL_ROUTING_SECTION}
 
@@ -1213,6 +1226,17 @@ function runDoctor() {
     }
     const setupSkillOk = mattSkills.isSkillInstalled(targetDir, mattSkills.SETUP_SKILL_NAME);
     console.log(`  ${setupSkillOk ? pc.green('OK') : pc.yellow('WARN')} ${mattSkills.SETUP_SKILL_NAME} available`);
+    console.log(`\n${pc.bold('thachvd-kit native skills')}`);
+    const nativeStatus = nativeSkills.checkNativeSkills(targetDir);
+    for (const name of nativeSkills.NATIVE_SKILLS) {
+        const status = nativeStatus.skills[name];
+        console.log(`  ${status.agents && status.claude ? pc.green('OK') : pc.yellow('WARN')} ${name} (.agents: ${status.agents ? 'installed' : 'missing'}, .claude: ${status.claude ? 'installed' : 'missing'})`);
+    }
+    for (const surface of nativeSkills.NATIVE_SKILL_SURFACES) {
+        const support = nativeStatus.surfaces[surface.id].support;
+        const status = support.missing.length === 0 ? pc.green('OK') : pc.yellow('WARN');
+        console.log(`  ${status} support files (${surface.relativeDir}: ${support.missing.length === 0 ? 'installed' : 'missing'})`);
+    }
     const contextMdExists = fs.existsSync(path.join(targetDir, 'CONTEXT.md'));
     const docsAdrExists = fs.existsSync(path.join(targetDir, 'docs', 'adr'));
     console.log(`  ${pc.dim('-')} CONTEXT.md ${contextMdExists ? 'detected' : 'not created yet (informational only)'}`);
@@ -1243,8 +1267,18 @@ async function runSetup(args) {
             console.log(`  ${skillsMarker} ${skillsResult.message}`);
         }
         printMattSkillsSetupReminder();
+        console.log(`\n${pc.bold('thachvd-kit native skills')}`);
+        const nativeStatus = nativeSkills.checkNativeSkills(targetDir);
+        if (nativeStatus.allInstalled) {
+            console.log(`  ${pc.green('OK')} native skill set already installed (${nativeStatus.total}/${nativeStatus.total})`);
+        } else {
+            const nativeResult = nativeSkills.installNativeSkills(targetDir);
+            const nativeMarker = nativeResult.ok ? pc.green('OK') : pc.yellow('WARN');
+            console.log(`  ${nativeMarker} ${nativeResult.message}`);
+        }
     } else {
         console.log(`${pc.bold('Matt Pocock skills')}\n  ${pc.dim('skipped (--no-install-skills)')}`);
+        console.log(`${pc.bold('thachvd-kit native skills')}\n  ${pc.dim('skipped (--no-install-skills)')}`);
     }
     if (!skipMcpSetup) {
         console.log(pc.bold('MCP setup'));
@@ -1527,37 +1561,60 @@ function runSkillsCommand(args) {
 
     if (subcommand === 'install') {
         console.log(pc.bold(pc.cyan('thachvd-kit skills install')));
-        const result = mattSkills.installSkills(targetDir, { dryRun });
-        console.log(`  ${result.ok ? pc.green('OK') : pc.yellow('WARN')} ${result.message}`);
-        if (!dryRun && result.ok) printMattSkillsSetupReminder();
-        if (!result.ok) process.exitCode = 1;
+        const mattResult = mattSkills.installSkills(targetDir, { dryRun });
+        console.log(`\n${pc.bold('Matt Pocock skills')}`);
+        console.log(`  ${mattResult.ok ? pc.green('OK') : pc.yellow('WARN')} ${mattResult.message}`);
+        const nativeResult = nativeSkills.installNativeSkills(targetDir, { dryRun });
+        console.log(`\n${pc.bold('thachvd-kit native skills')}`);
+        if (dryRun) for (const item of nativeResult.operations) console.log(`  ${pc.dim('would copy')} ${item.relativePath} -> ${item.surface}`);
+        console.log(`  ${nativeResult.ok ? pc.green('OK') : pc.yellow('WARN')} ${nativeResult.message}`);
+        if (!dryRun && mattResult.ok) printMattSkillsSetupReminder();
+        if (!mattResult.ok || !nativeResult.ok) process.exitCode = 1;
         return;
     }
 
     if (subcommand === 'check') {
         console.log(pc.bold(pc.cyan('thachvd-kit skills check')));
         const status = mattSkills.checkSkills(targetDir);
+        console.log(`\n${pc.bold('Matt Pocock skills')}`);
         for (const name of mattSkills.PROMOTED_SKILLS) {
             const installed = status.installed.includes(name);
             console.log(`  ${installed ? pc.green('OK') : pc.yellow('WARN')} ${name}`);
         }
         console.log(`\n  ${status.installed.length}/${status.total} promoted skills installed in ${mattSkills.SKILLS_RELATIVE_DIR}`);
-        if (status.missing.length > 0) {
-            console.log(`  Run: ${pc.bold('thachvd-kit skills install')}`);
+        if (status.missing.length > 0) console.log(`  Run: ${pc.bold('thachvd-kit skills install')}`);
+        console.log(`\n${pc.bold('thachvd-kit native skills')}`);
+        const nativeStatus = nativeSkills.checkNativeSkills(targetDir);
+        for (const name of nativeSkills.NATIVE_SKILLS) {
+            const item = nativeStatus.skills[name];
+            console.log(`  ${item.agents && item.claude ? pc.green('OK') : pc.yellow('WARN')} ${name}`);
+            console.log(`    .agents: ${item.agents ? 'installed' : 'missing'}`);
+            console.log(`    .claude: ${item.claude ? 'installed' : 'missing'}`);
+        }
+        for (const surface of nativeSkills.NATIVE_SKILL_SURFACES) {
+            const support = nativeStatus.surfaces[surface.id].support;
+            const status = support.missing.length === 0 ? pc.green('OK') : pc.yellow('WARN');
+            console.log(`  ${status} support files (${surface.relativeDir}: ${support.missing.length === 0 ? 'installed' : 'missing'})`);
         }
+        if (!nativeStatus.allInstalled) console.log(`  Run: ${pc.bold('thachvd-kit skills install')}`);
         return;
     }
 
     if (subcommand === 'update') {
         console.log(pc.bold(pc.cyan('thachvd-kit skills update')));
         const result = mattSkills.updateSkills(targetDir, { dryRun });
+        console.log(`\n${pc.bold('Matt Pocock skills')}`);
         if (dryRun) {
             for (const item of result.results) console.log(`  ${pc.dim('would run')} ${item.command}`);
         } else {
             for (const item of result.results) console.log(`  ${item.ok ? pc.green('OK') : pc.yellow('WARN')} ${item.name}`);
         }
         console.log(`\n  ${result.ok ? pc.green('OK') : pc.yellow('WARN')} ${result.message}`);
-        if (!result.ok) process.exitCode = 1;
+        const nativeResult = nativeSkills.updateNativeSkills(targetDir, { dryRun });
+        console.log(`\n${pc.bold('thachvd-kit native skills')}`);
+        if (dryRun) for (const item of nativeResult.operations) console.log(`  ${pc.dim('would copy')} ${item.relativePath} -> ${item.surface}`);
+        console.log(`  ${nativeResult.ok ? pc.green('OK') : pc.yellow('WARN')} ${nativeResult.message}`);
+        if (!result.ok || !nativeResult.ok) process.exitCode = 1;
         return;
     }
 
@@ -1712,12 +1769,12 @@ async function main() {
     - ${pc.bold('.agent/docs/index-project-prompt.md')} durable onboarding prompt
 
   ${pc.bold('MCP/tooling setup:')}
-    - Matt Pocock's promoted skills (.agents/skills/) are the workflow layer
-    - Run ${pc.bold('thachvd-kit setup')} to install them and configure codebase-memory MCP and recommended RTK
+    - Matt Pocock's promoted and thachvd-kit native skills are the workflow layer
+    - Run ${pc.bold('thachvd-kit setup')} to install both groups and configure codebase-memory MCP and recommended RTK
 
   ${pc.bold('Next steps:')}
     1. Run ${pc.bold('thachvd-kit prompt')} and paste the saved prompt into your AI editor
-    2. Run ${pc.bold('thachvd-kit setup')} to install the promoted skill set and RTK
+    2. Run ${pc.bold('thachvd-kit setup')} to install promoted and native skill sets and RTK
     3. Run ${pc.bold('thachvd-kit doctor')} to verify the machine
     4. Re-run ${pc.bold('thachvd-kit prompt')} whenever you need the onboarding prompt again
 
@@ -1732,4 +1789,3 @@ main().catch(err => {
     console.error(pc.red('\nError during init:'), err);
     process.exit(1);
 });
-