thachvd-kit 1.0.35 → 1.0.37

package/README.md

@@ -162,4 +162,14 @@ npm test
 npm run release:verify
 ```
 
-Release only from a clean, verified, pushed `main` branch. `npm publish` requires valid npm authentication and any configured 2FA code.
+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.
+
+`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,
@@ -71,7 +72,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 +87,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 +1021,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 +1038,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 +1050,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 +1068,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 +1121,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 +1131,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 +1220,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 +1261,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 +1555,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 +1763,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 +1783,3 @@ main().catch(err => {
     console.error(pc.red('\nError during init:'), err);
     process.exit(1);
 });
-