thachvd-kit 1.0.34 → 1.0.36

package/README.md

@@ -1,8 +1,8 @@
 # thachvd-kit
 
-`thachvd-kit` bootstraps project context for AI coding agents. It creates shared entry files and scan-based documentation so an agent can understand the repository quickly.
+`thachvd-kit` bootstraps project context for AI coding agents. It creates shared entry files and scan-based documentation so an agent can understand the repository quickly, and it installs/checks [Matt Pocock's promoted skills](https://github.com/mattpocock/skills) — the single workflow layer for planning, implementation, debugging, architecture, and review.
 
-Workflow skills are intentionally not copied into projects. Install [Superpowers](https://github.com/obra/superpowers#installation) through the official plugin surface for the AI client each member uses.
+Skill bodies are intentionally not vendored into this kit or copied globally. `thachvd-kit skills install` delegates to the upstream `skills` CLI and installs the promoted set project-locally under `.agents/skills/`.
 
 ## Quick Start
 
@@ -15,9 +15,17 @@ thachvd-kit setup
 thachvd-kit doctor
 ```
 
-`global` installs a managed tool-routing block into the current user's Antigravity and Codex global instruction files while preserving unrelated user content. `init` is project-focused. It does not install external workflow skills or create a second workflow engine.
+For an existing project:
 
-For an existing project that already has refined `.agent/docs/*`, use `thachvd-kit upgrade` instead of re-running `init --yes`. `upgrade` only adds/updates thachvd-kit managed policy blocks and removes a small set of obsolete generated defaults; it preserves project-specific knowledge.
+```bash
+thachvd-kit upgrade
+thachvd-kit setup
+thachvd-kit doctor
+```
+
+`global` installs a managed tool-routing block into the current user's Antigravity and Codex global instruction files while preserving unrelated user content. `init` is safe and project-focused: it does not install external tools, install skills, or create a second workflow engine. For an existing project that already has refined `.agent/docs/*`, use `thachvd-kit upgrade` instead of re-running `init --yes` — it only adds/updates thachvd-kit's managed policy blocks and removes a small set of obsolete generated defaults, preserving project-specific knowledge (see Safe Project Upgrade below). `setup` installs the promoted Matt Pocock skill set by default (`--no-install-skills` to skip) alongside MCP/RTK tooling.
+
+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.
 
 ## Generated Files
 
@@ -29,24 +37,25 @@ For an existing project that already has refined `.agent/docs/*`, use `thachvd-k
 - `.agent/docs/architecture.md`: architecture notes to refine over time.
 - `.agent/docs/conventions.md`: coding and verification conventions.
 - `.agent/docs/workflow.md`: the project workflow contract.
-- `.agent/docs/tooling.md`: Superpowers, MCP, RTK, and Playwright setup.
+- `.agent/docs/tooling.md`: Matt Pocock skills, MCP, RTK, and Playwright setup.
 - `.agent/docs/getting-started.md`: member onboarding guide.
 - `.agent/docs/index-project-prompt.md`: durable prompt for the first project scan.
 
-`init` does not generate `.agent/skills`, `.agent/workflows`, `.agent/agents`, Forge commands, or client-specific skill copies. `setup` can optionally add a Claude Code Stop hook (see below); it never adds workflow content of its own.
+`init` does not generate `.agent/skills`, `.agent/workflows`, `.agent/agents`, or client-specific skill copies — skills are installed by `thachvd-kit setup`/`skills install` into `.agents/skills/` instead. `setup` can optionally add a Claude Code Stop hook (see below); it never adds workflow content of its own.
 
 ## Workflow
 
-Superpowers is the primary workflow backend:
+[Matt Pocock's promoted skills](https://github.com/mattpocock/skills) (`skills/engineering/` + `skills/productivity/`) are the workflow layer, installed project-locally under `.agents/skills/`:
 
-1. `brainstorming` for unclear requirements.
-2. `using-git-worktrees` for isolated work.
-3. `writing-plans`, then explicit approval.
-4. `test-driven-development` and `executing-plans` or `subagent-driven-development`.
-5. `requesting-code-review` and `verification-before-completion`.
-6. `finishing-a-development-branch`.
-
-For bugs, use `systematic-debugging`: reproduce, inspect, test hypotheses, add regression protection, fix the root cause, and verify.
+- Ambiguous feature or design: `/grill-with-docs`, then optionally `/to-spec` for a durable contract.
+- Normal feature: `/grill-with-docs` -> `/to-spec` -> `/implement`.
+- Large feature needing decomposition: add `/to-tickets` before `/implement`.
+- Huge, multi-session uncertainty: `/wayfinder`.
+- Bug or failing behavior: `/diagnosing-bugs`.
+- Test-driven implementation: `/tdd`.
+- Architecture survey: `/improve-codebase-architecture` (`/codebase-design` for the design vocabulary).
+- Pre-completion review: `/code-review`.
+- Unsure which skill fits? Run `/ask-matt`.
 
 Fast-path eligibility is based on risk and contract surface, not file count. A localized, mechanically obvious, low-risk change with focused verification can use the client fast path; a one-file security, schema, payment, concurrency, or public-contract change should not.
 
@@ -91,9 +100,19 @@ thachvd-kit upgrade
 
 ## Integrations
 
-### Superpowers
+### Matt Pocock Skills
+
+The promoted engineering + productivity catalog from [mattpocock/skills](https://github.com/mattpocock/skills), installed project-locally (never globally) under `.agents/skills/`:
+
+```bash
+thachvd-kit skills install        # install the promoted set (--dry-run to preview)
+thachvd-kit skills check          # read-only: report what's installed
+thachvd-kit skills update         # re-add each promoted skill individually to update it (slower: one clone per skill)
+```
+
+The manifest (`bin/matt-skills.js`) mirrors upstream's `skills/engineering/` + `skills/productivity/` catalog and deliberately excludes `skills/in-progress`, `skills/misc`, and `skills/deprecated`. Installation targets the Codex and Antigravity agent identifiers of the upstream `skills` CLI, both of which resolve to `.agents/skills/`.
 
-Install it separately for each AI client. The official guide contains the current commands for Claude Code, Antigravity, Codex App, Codex CLI, and Cursor.
+After the first install, run `/setup-matt-pocock-skills` once inside your AI client — it configures the issue tracker, triage labels, and generated docs location. thachvd-kit does not simulate that skill.
 
 ### codebase-memory-mcp
 
@@ -122,15 +141,18 @@ 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 setup [--no-setup-mcp] [--no-setup-hook] [--no-install-rtk] [--no-index]
+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 --help
 ```
 
-`setup` configures MCP entries for detected clients, prints official Superpowers installation guidance, and adds a Claude Code Stop hook that checks for Plan/Review/Verification evidence before a feature or refactor can be reported as done (skip with `--no-setup-hook`). The hook only checks for evidence; it never prescribes which skill must produce it, so it works whether that evidence came from Superpowers or from a manual process. It also auto-installs missing npm-based MCP packages (`codebase-memory-mcp`, `context7-mcp`, `playwright-mcp`), indexes the current repository with `codebase-memory-mcp` (skip with `--no-index`), and installs `rtk` via `cargo` when `cargo` is available (skip with `--no-install-rtk`). Superpowers itself cannot be auto-installed by this CLI — it is installed through each AI client's own plugin command, not a shell command this tool can run. `doctor` is read-only and reports missing integrations without changing the machine.
+`init` generates project context for a new project; `upgrade` and `global` are the safe, additive-only paths for an existing project or machine (see Safe Project Upgrade and Global Tool Routing above). `setup` installs the promoted Matt Pocock skill set by default (skip with `--no-install-skills`), configures MCP entries for detected clients, and adds a Claude Code Stop hook that checks for Plan/Review/Verification evidence before a feature or refactor can be reported as done (skip with `--no-setup-hook`). The hook only checks for evidence; it never prescribes which skill must produce it, so it works whether that evidence came from a Matt Pocock skill or a manual process. `setup` also auto-installs missing npm-based MCP packages (`codebase-memory-mcp`, `context7-mcp`, `playwright-mcp`), indexes the current repository with `codebase-memory-mcp` (skip with `--no-index`), and installs `rtk` via `cargo` when `cargo` is available (skip with `--no-install-rtk`). `doctor` is read-only and reports missing integrations, including the promoted skill set, without changing the machine.
 
-The project-indexing prompt is saved by `init`, so installing Superpowers or RTK afterward cannot make it disappear. Run `thachvd-kit prompt` whenever you need to print it again.
+The project-indexing prompt is saved by `init`, so installing skills or RTK afterward cannot make it disappear. Run `thachvd-kit prompt` whenever you need to print it again.
 
 ## Development
 

package/bin/cli.js

@@ -6,6 +6,15 @@ const { spawnSync } = require('child_process');
 const prompts = require('prompts');
 const pc = require('picocolors');
 const packageJson = require('../package.json');
+const mattSkills = require('./matt-skills');
+const {
+    QUALITY_FLOOR_SECTION,
+    AGENT_RULES_SECTION,
+    CONVENTIONS_STANDARDS_SECTION,
+    FAST_PATH_SECTION,
+    GETTING_STARTED_FAST_PATH_SECTION,
+    TOOL_ROUTING_SECTION
+} = require('./policy');
 
 const sourceDir = path.resolve(__dirname, '..');
 const targetDir = process.cwd();
@@ -36,17 +45,25 @@ function printHelp() {
     console.log(`
 ${pc.bold('Usage:')}
   thachvd-kit init [--yes]
-  thachvd-kit setup [--yes]
+  thachvd-kit upgrade [--dry-run]
+  thachvd-kit global [--dry-run] [--antigravity-only|--codex-only]
+  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 --version
   thachvd-kit --help
 
 ${pc.bold('Commands:')}
-  init      Generate project context files and documentation
-  setup     Install/configure MCP and recommended local tooling
+  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
+  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
 
 ${pc.bold('Options:')}
   --yes     Overwrite generated files or accept setup defaults
@@ -54,6 +71,10 @@ ${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
+  --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
   --version Show the installed CLI version
   --help    Show this help message
 
@@ -64,19 +85,15 @@ ${pc.bold('What gets generated:')}
   .cursorrules Cursor entry file that points to AGENTS.md
   .agent/docs/ Project context, architecture, workflow, tooling, and durable onboarding prompt
 
-${pc.bold('Workflow guide:')}
-  Every task               Superpowers     Use the matching native Superpowers skill
-  Idea is fuzzy             brainstorming  Clarify intent and tradeoffs before coding
-  Scope needs a contract    writing-plans   Create a detailed plan before implementation
-  Execute an approved plan executing-plans Follow the approved plan with verification
-  Bug or failing behavior  systematic-debugging Find the root cause before editing
-  Pre-merge review         requesting-code-review Review before completion or merge
-  UI / UX work             $frontend-design, $webapp-testing
-  Project state             thachvd-kit doctor
+${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.
 
 ${pc.bold('Tip:')}
-  Install Superpowers separately for each AI client from its official plugin surface.
-  Run thachvd-kit setup for the integration checklist and doctor to verify it.
+  Run thachvd-kit setup to install the promoted skill set and configure
+  local tooling, then thachvd-kit doctor to verify the machine.
 `);
 }
 
@@ -742,7 +759,6 @@ function scanProject() {
         infrastructure: uniq(infrastructure),
         ci_cd: ciCd,
         test_framework: TEST_FRAMEWORK_CHOICES.includes(testFramework) ? testFramework : 'auto-detect',
-        max_file_lines: '300',
         code_style: 'project-standard',
         architecture_notes: '<!-- Add notes -->',
         current_phase: 'Initial setup',
@@ -769,35 +785,33 @@ If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the doc
 
 ## Workflow
 
-Superpowers is the primary workflow backend. Use its native skills when available:
+Matt Pocock's promoted skills (installed under \`.agents/skills/\` by \`thachvd-kit setup\`) are the workflow layer. Use the matching skill when a specialized workflow is useful:
 
-- New idea or unclear requirement: \`brainstorming\`.
-- Feature/refactor: \`using-git-worktrees\` -> \`writing-plans\` -> explicit approval -> \`executing-plans\` or \`subagent-driven-development\`.
-- Implementation: \`test-driven-development\` and focused verification.
-- Bug or failing behavior: \`systematic-debugging\` followed by a regression test.
-- Before completion: \`requesting-code-review\` and \`verification-before-completion\`.
-- Branch completion: \`finishing-a-development-branch\`.
+- Clear, localized change: inspect -> edit -> focused verification. Do not force a heavyweight skill.
+- Ambiguous feature or design: \`/grill-with-docs\`, then optionally \`/to-spec\` for a durable contract.
+- Normal feature: \`/grill-with-docs\` -> \`/to-spec\` -> \`/implement\`.
+- Large feature needing decomposition: add \`/to-tickets\` before \`/implement\`.
+- Huge, multi-session uncertainty: \`/wayfinder\`.
+- Bug or failing behavior: \`/diagnosing-bugs\`.
+- Test-driven implementation: \`/tdd\` (skip the ceremony for trivial config/text changes).
+- Architecture survey: \`/improve-codebase-architecture\`; use \`/codebase-design\` as the design vocabulary.
+- Pre-completion review: \`/code-review\` once when code risk warrants it.
 
-Questions and research do not edit product code. A simple fix may use a fast path only when it is one-file, unambiguous, and changes no behavior or contract. State the scope and verification before editing. If the scope grows, switch to the full Superpowers flow.
+If unsure which skill fits, use \`/ask-matt\`.
 
-If Superpowers is unavailable, follow the plain-language flow in \`.agent/docs/workflow.md\`; do not expect this kit to provide a second copy of the workflow engine.
+Questions and research do not edit product code. A fast path is allowed only when the change is localized, mechanically obvious, low-risk, and has focused verification; file count alone is not a gate. State the scope and verification before editing. If the task becomes ambiguous or its behavior, contract, or risk surface grows, use the matching planning skill above instead.
 
-## Rules
+See \`.agent/docs/workflow.md\` for the full route matrix. This kit does not implement a second workflow engine; it only installs and checks the promoted skill set (\`thachvd-kit skills install|check|update\`).
 
-- Respond in the user's language; keep code, identifiers, and code comments in English.
-- State assumptions when the request is ambiguous.
-- Prefer the existing project style over new abstractions.
-- Keep changes surgical and remove only dead code introduced by your change.
-- **MCP First**: Prioritize \`codebase-memory-mcp\` for symbols, call paths, architecture, and impact; use \`context7\` for API/docs queries and \`playwright\` for browser/UI verification. Fall back to normal file search when an integration is unavailable.
-- Prefer \`rtk\` by default for verbose shell commands such as \`rtk git status\`, \`rtk npm test\`, and \`rtk git log\`. Run the underlying command directly only when RTK is unavailable or incompatible.
-- Tests or equivalent verification are mandatory before claiming done.
-- Keep files under ${data.max_file_lines || '300'} lines unless the project already has a different standard in \`.agent/docs/conventions.md\`.
+${QUALITY_FLOOR_SECTION}
+
+${AGENT_RULES_SECTION}
 
 ## Shared Knowledge
 
 - Project context: \`.agent/docs/\`
 - Tooling setup: \`.agent/docs/tooling.md\`
-- Superpowers: installed through the AI client's official plugin surface
+- Matt Pocock skills: promoted set installed under \`.agents/skills/\` via \`thachvd-kit skills install\`
 - RTK: recommended local CLI for compact command output
 - Antigravity and Cursor entry rules: \`GEMINI.md\` and \`.cursorrules\`
 `;
@@ -807,7 +821,7 @@ function generateIndexProjectPrompt() {
     return `# Project Indexing Prompt
 
 Read CLAUDE.md (if using Claude Code), AGENTS.md, and all files under .agent/docs/.
-Use Superpowers for the workflow and use codebase-memory MCP for structural code discovery when available.
+Use the project's Matt Pocock skills for workflow (see AGENTS.md; run /ask-matt if unsure which fits) and use codebase-memory MCP for structural code discovery when available.
 Ask me what this project does and any important conventions I want preserved.
 Then scan this repository and refine the generated context docs with factual rules.
 Do not implement product code during onboarding.
@@ -985,16 +999,12 @@ Before non-trivial implementation work, inspect this file. If it is stale or sti
 `;
 }
 
-function generateConventionsDoc(data) {
+function generateConventionsDoc() {
     return `# Coding Conventions
 
-## Current Standards
+${CONVENTIONS_STANDARDS_SECTION}
 
-- Maximum file length: ${data.max_file_lines || '300'} lines unless the existing project standard is stricter.
-- Code comments and identifiers should be written in English.
-- Keep changes scoped to the user request.
-- Prefer existing local patterns over introducing new abstractions.
-- TODO: refine naming, formatting, folder, API, state, styling, and testing conventions from the real codebase.
+${QUALITY_FLOOR_SECTION}
 
 ## Verification
 
@@ -1008,34 +1018,38 @@ function generateConventionsDoc(data) {
 function generateWorkflowDoc() {
     return `# Agent Workflow
 
-This project uses Superpowers as the workflow backend. thachvd-kit only provides project context and integration setup.
+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.
 
 ## Before Every Task
 
 1. Read AGENTS.md and the relevant files under .agent/docs/.
-2. Use the native Superpowers skill that matches the request.
+2. Use the promoted skill that matches the request, or run /ask-matt if unsure which one fits.
 3. Use codebase-memory MCP for structural discovery when available.
-4. Make changes only after the required planning gate.
+4. Make changes only after the required planning gate for that situation.
 5. Verify the change and request review before completion.
 
 ## Route Matrix
 
-| Situation | Superpowers path | Gate |
+| Situation | Skill | Gate |
 |---|---|---|
 | Question or research only | direct answer or research | no product-code edits |
-| One obvious local fix | fast path | inspect -> edit -> focused verify |
-| Bug or failing behavior | systematic-debugging | reproduce -> root cause -> regression test -> fix -> verify |
-| New behavior or refactor | brainstorming -> writing-plans -> executing-plans | explicit plan approval before implementation |
-| Multi-part implementation | subagent-driven-development | task review and final review |
-| Pre-merge | requesting-code-review | blocking findings resolved |
+| 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 |
+| 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 |
+| Architecture survey | /improve-codebase-architecture (+ /codebase-design vocabulary) | findings reviewed before large refactors |
+| Pre-merge | /code-review | blocking findings resolved |
+
+Not sure which row applies? Run /ask-matt instead of guessing.
 
 ## Standard Feature Flow
 
-brainstorming -> using-git-worktrees -> writing-plans -> user approval -> test-driven-development -> executing-plans or subagent-driven-development -> requesting-code-review -> verification-before-completion -> finishing-a-development-branch.
-
-## Fast Path
+/grill-with-docs -> /to-spec -> (/to-tickets for large work) -> /implement (with /tdd where it helps) -> /code-review.
 
-Use it only for one-file, unambiguous changes with no behavior, API, schema, security, dependency, CI, workflow, or release contract change. State the narrow scope and verification before editing. If the scope grows, switch to brainstorming and writing-plans.
+${FAST_PATH_SECTION}
 
 ## Documentation Maintenance
 
@@ -1049,33 +1063,31 @@ Use it only for one-file, unambiguous changes with no behavior, API, schema, sec
 function generateGettingStartedDoc() {
     return `# Getting Started
 
-thachvd-kit creates project context. Superpowers owns the development workflow.
+thachvd-kit creates project context. Matt Pocock's promoted 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. Install Superpowers and RTK, then run \`thachvd-kit setup\`.
-4. Run \`thachvd-kit doctor\` and restart the AI client.
+3. Run \`thachvd-kit setup\` (installs the promoted skill set 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.
 
 ## Standard Flow
 
-Use Superpowers native skills:
+1. \`/grill-with-docs\` for unclear requirements or design.
+2. \`/to-spec\` when a durable implementation contract is useful.
+3. \`/to-tickets\` for large work that benefits from decomposition.
+4. \`/implement\`, with \`/tdd\` where red-green-refactor helps.
+5. \`/code-review\` once before completion.
 
-1. \`brainstorming\` for unclear requirements.
-2. \`using-git-worktrees\` for isolated work.
-3. \`writing-plans\`, then wait for explicit approval.
-4. \`test-driven-development\` and \`executing-plans\` or \`subagent-driven-development\`.
-5. \`requesting-code-review\` and \`verification-before-completion\`.
-6. \`finishing-a-development-branch\`.
+Not sure which skill fits? Run \`/ask-matt\`.
 
 ## Bug Flow
 
-Use \`systematic-debugging\`: reproduce the symptom, inspect the path with codebase-memory MCP, test hypotheses, add regression protection, fix the root cause, and verify.
+Use \`/diagnosing-bugs\`: reproduce the symptom, inspect the path with codebase-memory MCP, test hypotheses, add regression protection, fix the root cause, and verify.
 
-## Fast Path
-
-Use a fast path only for one-file, unambiguous changes with no behavior or contract change. State the scope and verification before editing. If the scope expands, return to brainstorming and writing-plans.
+${GETTING_STARTED_FAST_PATH_SECTION}
 `;
 }
 
@@ -1102,19 +1114,20 @@ function generateToolingDoc(data) {
 
     return `# Optional Tooling
 
-Run \`thachvd-kit doctor\` to check the current machine. thachvd-kit does not install workflow skills or copy agent folders.
+Run \`thachvd-kit doctor\` to check the current machine.
 
-## Superpowers
+## Matt Pocock Skills
 
-Install Superpowers separately for each AI client from its official plugin surface:
+Matt Pocock's promoted engineering and productivity skills are the workflow layer for this project, installed project-locally under \`.agents/skills/\` (never globally):
 
-- Claude Code: \`/plugin install superpowers@claude-plugins-official\`
-- Antigravity: \`agy plugin install https://github.com/obra/superpowers\`
-- Codex App: install it from the Plugins sidebar.
-- Codex CLI: open \`/plugins\` and install Superpowers.
-- Cursor: \`/add-plugin superpowers\`
+- 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)
+- Update the promoted set: \`thachvd-kit skills update\` (re-adds each skill individually for safety, so it is slower than install — one network clone per skill)
+- 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\`.
 
-Guide: https://github.com/obra/superpowers#installation
+${TOOL_ROUTING_SECTION}
 
 ## Codebase Memory MCP
 
@@ -1167,17 +1180,8 @@ function homePath(...parts) {
     return home ? path.join(home, ...parts) : null;
 }
 
-function printSuperpowersInstallGuide() {
-    console.log(`
-${pc.bold('Superpowers setup')} (official client integrations)
-  Claude Code:  /plugin install superpowers@claude-plugins-official
-  Antigravity:  agy plugin install https://github.com/obra/superpowers
-  Codex App:    install Superpowers from the Plugins sidebar
-  Codex CLI:    open /plugins, search Superpowers, then Install Plugin
-  Cursor:       /add-plugin superpowers
-
-  Full guide: https://github.com/obra/superpowers#installation
-`);
+function printMattSkillsSetupReminder() {
+    console.log(`  Run ${pc.bold('/setup-matt-pocock-skills')} once inside your AI client to configure the issue tracker, triage labels, and generated docs location.`);
 }
 
 function runDoctor() {
@@ -1191,10 +1195,7 @@ function runDoctor() {
 
     const tools = [
         [CODEBASE_MEMORY_BINARY, `npm install -g ${CODEBASE_MEMORY_PACKAGE}`],
-        ['rtk', `recommended: ${RTK_INSTALL_COMMAND}`],
-        ['agy', 'install Antigravity before running its Superpowers plugin command'],
-        ['claude', 'install Claude Code before installing its Superpowers plugin'],
-        ['codex', 'install Codex before using its Superpowers plugin']
+        ['rtk', `recommended: ${RTK_INSTALL_COMMAND}`]
     ];
     console.log(`\n${pc.bold('Local integrations (RTK recommended)')}`);
     for (const [binary, hint] of tools) {
@@ -1202,6 +1203,21 @@ function runDoctor() {
         console.log(`  ${ok ? pc.green('OK') : pc.yellow('WARN')} ${binary}${ok ? '' : ` - ${hint}`}`);
     }
 
+    console.log(`\n${pc.bold('Matt Pocock skills')}`);
+    const skillStatus = mattSkills.checkSkills(targetDir);
+    if (skillStatus.missing.length === 0) {
+        console.log(`  ${pc.green('OK')} promoted skill set installed (${skillStatus.total}/${skillStatus.total})`);
+    } else {
+        console.log(`  ${pc.yellow('WARN')} ${skillStatus.missing.length} promoted skill(s) missing`);
+        console.log(`       Run: ${pc.bold('thachvd-kit skills install')}`);
+    }
+    const setupSkillOk = mattSkills.isSkillInstalled(targetDir, mattSkills.SETUP_SKILL_NAME);
+    console.log(`  ${setupSkillOk ? pc.green('OK') : pc.yellow('WARN')} ${mattSkills.SETUP_SKILL_NAME} available`);
+    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)'}`);
+    console.log(`  ${pc.dim('-')} docs/adr ${docsAdrExists ? 'detected' : 'not created yet (informational only)'}`);
+
     console.log(`\n${pc.bold('Next step')}`);
     console.log('  Run thachvd-kit prompt to print the saved project-indexing prompt.');
 }
@@ -1211,8 +1227,25 @@ async function runSetup(args) {
     const skipHookSetup = args.includes('--no-setup-hook');
     const skipRtkInstall = args.includes('--no-install-rtk');
     const skipIndex = args.includes('--no-index');
+    const skipSkillsInstall = args.includes('--no-install-skills');
     console.log(pc.bold(pc.cyan('thachvd-kit setup')));
-    printSuperpowersInstallGuide();
+    if (!skipSkillsInstall) {
+        console.log(pc.bold('Matt Pocock skills'));
+        const skillStatus = mattSkills.checkSkills(targetDir);
+        if (skillStatus.missing.length === 0) {
+            // Already fully installed: `setup` only ensures presence, it
+            // never re-installs or updates on its own. Explicit
+            // `thachvd-kit skills update` is required for that.
+            console.log(`  ${pc.green('OK')} promoted skill set already installed (${skillStatus.total}/${skillStatus.total})`);
+        } else {
+            const skillsResult = mattSkills.installSkills(targetDir);
+            const skillsMarker = skillsResult.ok ? pc.green('OK') : pc.yellow('WARN');
+            console.log(`  ${skillsMarker} ${skillsResult.message}`);
+        }
+        printMattSkillsSetupReminder();
+    } else {
+        console.log(`${pc.bold('Matt Pocock skills')}\n  ${pc.dim('skipped (--no-install-skills)')}`);
+    }
     if (!skipMcpSetup) {
         console.log(pc.bold('MCP setup'));
         for (const result of setupMcpServers({ install: true })) {
@@ -1393,7 +1426,7 @@ tool_timeout_sec = 120
 const DOD_HOOK_MARKER = 'feature/refactor Definition-of-Done gate';
 
 function generateDodStopHookPrompt() {
-    return `Input JSON (Stop hook payload): $ARGUMENTS\n\nCheck this project's ${DOD_HOOK_MARKER}. This kit does not define its own workflow steps; it only verifies that evidence of the gate exists, regardless of which skill produced it (a Superpowers skill such as \`writing-plans\`/\`requesting-code-review\`, or an equivalent documented step). Use the \`last_assistant_message\` field as the authoritative final response. Use \`transcript_path\` only for additional context because the transcript may not contain the final response yet.\n\nFor a feature or refactor (multi-file change, new behavior, or non-trivial refactor), completion requires evidence of:\n- Plan: a plan was written and explicitly approved by the human before implementation started.\n- Review: the change was reviewed (correctness, simplicity, architecture, security, performance) and blocking issues were resolved.\n- Verification: tests or equivalent verification ran and passed.\n\nA one-file, unambiguous fix with no behavior/contract change is exempt from the Plan and Review evidence only when the final response states FAST_PATH: simple-fix, its reason, and its narrow scope. Verification is still mandatory in that case.\n\nSteps:\n1. If the input JSON has \`stop_hook_active: true\`, allow stopping immediately (already checked once this cycle; never block twice in a row).\n2. Inspect the changed files and the \`last_assistant_message\` field.\n3. If no source files changed, the final response does not claim the task is done/complete, or the final response explicitly contains FAST_PATH: simple-fix and the changed scope is clearly a simple/self-contained fix, allow stopping.\n4. If it is a feature/refactor-scale change and the final response claims completion, verify that the response (or the visible transcript) shows evidence of an approved plan and a completed review. If either is missing, block; a generic statement that the task was simple is not enough.\n5. Return exactly JSON: {"ok": true} to allow stopping, or {"ok": false, "reason": "..."} to block.\n\nWhen blocking, name exactly which gate is missing without prescribing which skill or workflow must produce it.`;
+    return `Input JSON (Stop hook payload): $ARGUMENTS\n\nCheck this project's ${DOD_HOOK_MARKER}. This kit does not define its own workflow steps or require any specific workflow skill; it only verifies that evidence of the gate exists, however that evidence was produced (a documented planning/review skill, a manual process, or anything equivalent). Use the \`last_assistant_message\` field as the authoritative final response. Use \`transcript_path\` only for additional context because the transcript may not contain the final response yet.\n\nVerification is never optional: every change, fast path included, requires semantic evidence in the final response or visible transcript that focused tests or equivalent verification actually ran and passed (for example test/build output, or a described manual verification). Do not require a specific command; judge the evidence on its meaning.\n\nFor any change that is not a verified fast path (see below), completion additionally requires evidence of:\n- Plan: a plan was written and explicitly approved by the human before implementation started.\n- Review: the change was reviewed (correctness, simplicity, architecture, security, performance) and blocking issues were resolved.\n\nFast-path eligibility is based on risk and contract surface, not file count. A change is fast path only when it is localized, mechanically obvious, low-risk, and has no meaningful public API, schema, auth/security, data-integrity, payment, concurrency, dependency, CI/release, or architectural risk, with focused verification available. A source file plus its own focused test can still be fast path; a one-file auth, payment, schema, security, or concurrency change is not fast path no matter how small. A verified fast-path change is exempt from the Plan and Review evidence only when the final response states FAST_PATH: simple-fix, its reason, and its narrow scope — Verification evidence is still mandatory in that case, not optional.\n\nSteps:\n1. If the input JSON has \`stop_hook_active: true\`, allow stopping immediately (already checked once this cycle; never block twice in a row).\n2. Inspect the changed files and the \`last_assistant_message\` field.\n3. If no source files changed or the final response does not claim the task is done/complete, allow stopping.\n4. If the final response explicitly contains FAST_PATH: simple-fix, first check the claim against the risk criteria above, not file count. If it actually touches one of those risk areas regardless of file count, the FAST_PATH claim is invalid; treat it as a full feature/refactor change and continue to step 5. Otherwise, look for semantic evidence that focused verification actually ran and passed. If that evidence is present, allow stopping. If it is missing, block with {"ok": false, "reason": "Missing Verification evidence: ..."}.\n5. If the final response claims completion for a change that is not a verified fast path, check all three gates: (a) a plan was written and explicitly approved by the human before implementation started; (b) the change was reviewed and blocking issues were resolved; (c) tests or equivalent verification ran and passed. If any one of the three is missing, block naming exactly that gate; a generic statement that the task was simple, or that it touched only one file, is not enough on its own.\n6. Return exactly JSON: {"ok": true} to allow stopping, or {"ok": false, "reason": "..."} to block.\n\nWhen blocking, name exactly which gate is missing without prescribing which skill or workflow must produce it.`;
 }
 
 function isDefinitionOfDoneHook(hook) {
@@ -1488,9 +1521,57 @@ function setupMcpServers(options = {}) {
     return results;
 }
 
+function runSkillsCommand(args) {
+    const subcommand = args[0];
+    const dryRun = args.includes('--dry-run');
+
+    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;
+        return;
+    }
+
+    if (subcommand === 'check') {
+        console.log(pc.bold(pc.cyan('thachvd-kit skills check')));
+        const status = mattSkills.checkSkills(targetDir);
+        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')}`);
+        }
+        return;
+    }
+
+    if (subcommand === 'update') {
+        console.log(pc.bold(pc.cyan('thachvd-kit skills update')));
+        const result = mattSkills.updateSkills(targetDir, { dryRun });
+        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;
+        return;
+    }
+
+    console.error(pc.red(`Unknown skills subcommand: ${subcommand || '(none)'}`));
+    console.error('Usage: thachvd-kit skills install|check|update [--dry-run]');
+    process.exit(1);
+}
+
 // --- Main CLI ---
 
 async function main() {
+    // Note: 'upgrade' and 'global' are handled directly by bin/entry.js
+    // (bin/upgrade.js / bin/global.js) before this module is even required,
+    // so they never reach here.
     const rawArgs = process.argv.slice(2);
     const command = rawArgs[0] && !rawArgs[0].startsWith('-') ? rawArgs[0] : 'init';
     const args = command === 'init' ? rawArgs.slice(rawArgs[0] === 'init' ? 1 : 0) : rawArgs.slice(1);
@@ -1520,6 +1601,11 @@ async function main() {
         return;
     }
 
+    if (command === 'skills') {
+        runSkillsCommand(rawArgs.slice(1));
+        return;
+    }
+
     if (command !== 'init') {
         console.error(pc.red(`Unknown command: ${command}`));
         printHelp();
@@ -1559,8 +1645,7 @@ async function main() {
         uses_docker: scanned?.uses_docker ?? true,
         cloud: scanned?.cloud || 'none',
         package_manager: scanned?.package_manager || 'auto-detect',
-        test_framework: scanned?.test_framework || 'auto-detect',
-        max_file_lines: scanned?.max_file_lines || '300'
+        test_framework: scanned?.test_framework || 'auto-detect'
     };
 
     data.database = data.database || scanned?.database || 'none';
@@ -1568,7 +1653,6 @@ async function main() {
     data.cloud = data.cloud || scanned?.cloud || 'none';
     data.package_manager = data.package_manager || scanned?.package_manager || 'auto-detect';
     data.test_framework = data.test_framework || scanned?.test_framework || 'auto-detect';
-    data.max_file_lines = data.max_file_lines || scanned?.max_file_lines || '300';
     data.framework_details = scanned?.framework_details || [];
     data.scan_evidence = scanned?.scan_evidence || [];
     data.app_root = scanned?.app_root || '.';
@@ -1583,7 +1667,7 @@ async function main() {
 
     // Shared entry files are written after the .agent folder is available.
 
-    console.log(`  ${pc.green('OK')} Project context generation enabled; workflow skills remain client-managed by Superpowers`);
+    console.log(`  ${pc.green('OK')} Project context generation enabled; run thachvd-kit setup to install the promoted Matt Pocock skill set`);
 
 
     const generatedFiles = [
@@ -1593,7 +1677,7 @@ async function main() {
         ['.cursorrules', generateSharedCursorrules(data)],
         [path.join('.agent', 'docs', 'project.md'), generateProjectDoc(data)],
         [path.join('.agent', 'docs', 'architecture.md'), generateArchitectureDoc(data)],
-        [path.join('.agent', 'docs', 'conventions.md'), generateConventionsDoc(data)],
+        [path.join('.agent', 'docs', 'conventions.md'), generateConventionsDoc()],
         [path.join('.agent', 'docs', 'workflow.md'), generateWorkflowDoc()],
         [path.join('.agent', 'docs', 'tooling.md'), generateToolingDoc(data)],
         [path.join('.agent', 'docs', 'getting-started.md'), generateGettingStartedDoc()],
@@ -1628,12 +1712,12 @@ async function main() {
     - ${pc.bold('.agent/docs/index-project-prompt.md')} durable onboarding prompt
 
   ${pc.bold('MCP/tooling setup:')}
-    - Superpowers is the workflow backend; install it from the official client/plugin surface
-    - Run ${pc.bold('thachvd-kit setup')} to configure codebase-memory MCP and recommended RTK
+    - 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
 
   ${pc.bold('Next steps:')}
     1. Run ${pc.bold('thachvd-kit prompt')} and paste the saved prompt into your AI editor
-    2. Install Superpowers and RTK, then run ${pc.bold('thachvd-kit setup')}
+    2. Run ${pc.bold('thachvd-kit setup')} to install the promoted skill set 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
 

package/bin/entry.js

@@ -11,6 +11,8 @@ function isInitInvocation(args) {
     if (args.includes('--help') || args.includes('-h') || args.includes('--version') || args.includes('-v')) {
         return false;
     }
+    // Note: 'upgrade' and 'global' are handled and returned above before this
+    // is ever called, so they never reach here.
     const first = args[0];
     return !first || first === 'init' || first.startsWith('-');
 }

package/bin/matt-skills.js

@@ -0,0 +1,192 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// Source repository for Matt Pocock's promoted skills, installed via the
+// upstream `skills` CLI (npx skills@latest add <source>).
+const MATT_SKILLS_SOURCE = 'mattpocock/skills';
+
+// This list mirrors upstream's promoted daily-driver catalog:
+// https://github.com/mattpocock/skills -> skills/engineering/ + skills/productivity/
+// Do NOT add anything from skills/in-progress, skills/misc, or skills/deprecated —
+// those are explicitly not part of the supported set. Update this list by hand
+// when upstream promotes a new skill or retires one; there is no reliable
+// upstream "promoted only" filter, so this manifest is the source of truth.
+const PROMOTED_SKILLS = [
+    // skills/engineering
+    'ask-matt',
+    'code-review',
+    'codebase-design',
+    'diagnosing-bugs',
+    'domain-modeling',
+    'grill-with-docs',
+    'implement',
+    'improve-codebase-architecture',
+    'prototype',
+    'research',
+    'resolving-merge-conflicts',
+    'setup-matt-pocock-skills',
+    'tdd',
+    'to-spec',
+    'to-tickets',
+    'triage',
+    'wayfinder',
+    'wizard',
+    // skills/productivity
+    'grill-me',
+    'grilling',
+    'handoff',
+    'teach',
+    'to-questionnaire',
+    'wait-what',
+    'writing-for-agents'
+];
+
+// Agent identifiers as understood by the upstream `skills` CLI. Codex and
+// Antigravity share the project-local .agents/skills directory; Claude Code
+// also receives its native .claude/skills integration so skills are exposed
+// as slash commands such as /ask-matt and /implement.
+const SUPPORTED_AGENTS = ['codex', 'antigravity', 'claude-code'];
+
+// Project-local install target. Skills are intentionally not installed
+// globally (see AGENTS.md / .agent/docs/tooling.md for the reasoning).
+const SKILLS_RELATIVE_DIR = path.join('.agents', 'skills');
+
+const SETUP_SKILL_NAME = 'setup-matt-pocock-skills';
+
+function npxCommand() {
+    return process.platform === 'win32' ? 'npx.cmd' : 'npx';
+}
+
+function skillsDirFor(targetDir) {
+    return path.join(targetDir, SKILLS_RELATIVE_DIR);
+}
+
+function isSkillInstalled(targetDir, name) {
+    return fs.existsSync(path.join(skillsDirFor(targetDir), name, 'SKILL.md'));
+}
+
+// Read-only: never spawns a process. Safe to call from `doctor` and
+// `skills check`.
+function checkSkills(targetDir) {
+    const installed = [];
+    const missing = [];
+    for (const name of PROMOTED_SKILLS) {
+        (isSkillInstalled(targetDir, name) ? installed : missing).push(name);
+    }
+    return { installed, missing, total: PROMOTED_SKILLS.length };
+}
+
+// Builds the argv for `npx skills@latest add <source> ...`. Always passes
+// `--skill <name>` as separate argv entries (never `--skill=<name>`): current
+// `skills` CLI versions have a parsing bug where the `--skill=<name>` form is
+// silently ignored and installs every skill in the source repository,
+// including skills/in-progress, skills/misc, and skills/deprecated.
+function buildAddArgs(skillNames) {
+    return [
+        '-y', // npx: auto-confirm installing the `skills` package itself
+        'skills@latest',
+        'add',
+        MATT_SKILLS_SOURCE,
+        '--skill', ...skillNames,
+        '--agent', ...SUPPORTED_AGENTS,
+        '-y' // skills CLI: skip its own confirmation prompts
+    ];
+}
+
+function formatCommand(args) {
+    return `${npxCommand()} ${args.join(' ')}`;
+}
+
+function runNpx(args, options = {}) {
+    return spawnSync(npxCommand(), args, {
+        cwd: options.cwd,
+        encoding: 'utf8',
+        stdio: options.stdio || 'pipe',
+        shell: process.platform === 'win32'
+    });
+}
+
+// Installs the full promoted set in a single `add` call (one clone, one
+// filtered install). Never uses `--all`, which would also install
+// in-progress/misc/deprecated skills.
+function installSkills(targetDir, options = {}) {
+    const dryRun = options.dryRun === true;
+    const args = buildAddArgs(PROMOTED_SKILLS);
+    const command = formatCommand(args);
+
+    if (dryRun) {
+        return { ok: true, dryRun: true, command, message: `Dry run: would run ${command}` };
+    }
+
+    const result = runNpx(args, { cwd: targetDir, stdio: 'inherit' });
+    if (result.error || result.status !== 0) {
+        return { ok: false, dryRun: false, command, message: `failed to install promoted skills; run manually: ${command}` };
+    }
+    return {
+        ok: true,
+        dryRun: false,
+        command,
+        message: `installed ${PROMOTED_SKILLS.length} promoted Matt Pocock skills to ${SKILLS_RELATIVE_DIR}`
+    };
+}
+
+// Updates each promoted skill by re-adding it individually and idempotently.
+// This is deliberately NOT `npx skills update`: upstream has a known issue
+// where updating one project skill can reinstall every skill from the
+// source. Re-adding by explicit single-skill name only ever touches that
+// skill's directory (verified manually against the upstream CLI).
+// Trade-off: this does one network clone of the source repo per promoted
+// skill (~PROMOTED_SKILLS.length calls), so it is noticeably slower than
+// `installSkills`'s single batched call. That cost is accepted deliberately
+// for the safety guarantee above; revisit only if upstream ships a scoped,
+// non-destructive `update`.
+function updateSkills(targetDir, options = {}) {
+    const dryRun = options.dryRun === true;
+    const results = [];
+
+    for (const name of PROMOTED_SKILLS) {
+        const args = buildAddArgs([name]);
+        const command = formatCommand(args);
+
+        if (dryRun) {
+            results.push({ name, ok: true, dryRun: true, command });
+            continue;
+        }
+
+        const result = runNpx(args, { cwd: targetDir, stdio: 'pipe' });
+        const ok = !result.error && result.status === 0;
+        results.push({
+            name,
+            ok,
+            dryRun: false,
+            command,
+            error: ok ? null : (result.stderr || result.stdout || `exit ${result.status}`)
+        });
+    }
+
+    const failed = results.filter(r => !r.ok);
+    const message = dryRun
+        ? `Dry run: would update ${PROMOTED_SKILLS.length} promoted skills one by one`
+        : failed.length === 0
+            ? `updated ${PROMOTED_SKILLS.length} promoted Matt Pocock skills`
+            : `updated ${results.length - failed.length}/${PROMOTED_SKILLS.length} promoted skills; failed: ${failed.map(f => f.name).join(', ')}`;
+
+    return { ok: failed.length === 0, dryRun, results, message };
+}
+
+module.exports = {
+    MATT_SKILLS_SOURCE,
+    PROMOTED_SKILLS,
+    SUPPORTED_AGENTS,
+    SKILLS_RELATIVE_DIR,
+    SETUP_SKILL_NAME,
+    npxCommand,
+    skillsDirFor,
+    isSkillInstalled,
+    checkSkills,
+    buildAddArgs,
+    formatCommand,
+    installSkills,
+    updateSkills
+};

package/bin/policy.js

@@ -49,11 +49,11 @@ const FAST_PATH_SECTION = `## Fast Path
 
 Fast-path eligibility is based on risk and contract surface, not file count. Use it only when the change is localized, mechanically obvious, has no meaningful public API, schema, security, data-integrity, dependency, CI/release, or architectural risk, and has focused verification available. A two-file change such as code plus its focused test may still be fast-path; a one-file auth, payment, schema, concurrency, or other high-risk change is not.
 
-State the narrow scope and verification before editing. If the task becomes ambiguous, introduces new behavior or architectural decisions, or its risk/contract surface grows, switch to brainstorming and planning.`;
+State the narrow scope and verification before editing. If the task becomes ambiguous, introduces new behavior or architectural decisions, or its risk/contract surface grows, switch to the matching planning skill (for example /grill-with-docs or /wayfinder).`;
 
 const GETTING_STARTED_FAST_PATH_SECTION = `## Fast Path
 
-Use a fast path when the change is localized, mechanically obvious, low-risk, and has focused verification. File count alone does not determine eligibility: code plus a focused test can still be trivial, while a one-file security, schema, payment, concurrency, or public-contract change requires the full workflow. If scope or risk grows, return to brainstorming and planning.`;
+Use a fast path when the change is localized, mechanically obvious, low-risk, and has focused verification. File count alone does not determine eligibility: code plus a focused test can still be trivial, while a one-file security, schema, payment, concurrency, or public-contract change requires the full workflow. If scope or risk grows, return to the matching planning skill (for example /grill-with-docs or /wayfinder).`;
 
 const TOOL_ROUTING_SECTION = `## Tool Routing
 
@@ -100,11 +100,11 @@ function replaceFastPathInline(markdown) {
     return normalizeNewlines(markdown)
         .replace(
             'Questions and research do not edit product code. A simple fix may use a fast path only when it is one-file, unambiguous, and changes no behavior or contract. State the scope and verification before editing. If the scope grows, switch to the full Superpowers flow.',
-            'Questions and research do not edit product code. A fast path is allowed only when the change is localized, mechanically obvious, low-risk, and has focused verification; file count alone is not a gate. State the scope and verification before editing. If the task becomes ambiguous or its behavior, contract, or risk surface grows, switch to the full Superpowers flow.'
+            'Questions and research do not edit product code. A fast path is allowed only when the change is localized, mechanically obvious, low-risk, and has focused verification; file count alone is not a gate. State the scope and verification before editing. If the task becomes ambiguous or its behavior, contract, or risk surface grows, switch to the matching planning skill instead.'
         )
         .replace(
             'Questions and research do not edit product code. A simple fix may use a fast path only when it is one-file, unambiguous, and changes no behavior or contract. State the narrow scope and verification before editing. If the scope grows, return to brainstorming and planning.',
-            'Questions and research do not edit product code. A fast path is allowed only when the change is localized, mechanically obvious, low-risk, and has focused verification; file count alone is not a gate. State the narrow scope and verification before editing. If scope or risk grows, return to brainstorming and planning.'
+            'Questions and research do not edit product code. A fast path is allowed only when the change is localized, mechanically obvious, low-risk, and has focused verification; file count alone is not a gate. State the narrow scope and verification before editing. If scope or risk grows, return to the matching planning skill instead.'
         );
 }
 
@@ -183,8 +183,12 @@ module.exports = {
     POLICY_PATHS,
     QUALITY_FLOOR_SECTION,
     AGENT_RULES_SECTION,
+    CONVENTIONS_STANDARDS_SECTION,
     FAST_PATH_SECTION,
+    GETTING_STARTED_FAST_PATH_SECTION,
     TOOL_ROUTING_SECTION,
+    normalizeNewlines,
+    replaceSection,
     upgradeGeneratedContent,
     upgradeAgentsMarkdown,
     upgradeConventionsMarkdown,

package/bin/upgrade.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const { normalizeNewlines, replaceSection, FAST_PATH_SECTION, GETTING_STARTED_FAST_PATH_SECTION } = require('./policy');
 
 const START = '<!-- thachvd-kit:project-policy:start -->';
 const END = '<!-- thachvd-kit:project-policy:end -->';
@@ -19,6 +20,8 @@ Prefer the smallest sufficient change, not the fewest lines of code.
 - Tests or equivalent verification are mandatory before claiming completion.
 ${END}`;
 
+// Files managed by the "## Engineering Policy" block above (unchanged from
+// before the Matt Pocock migration).
 const TARGETS = [
     'AGENTS.md',
     path.join('.agent', 'docs', 'conventions.md'),
@@ -27,7 +30,7 @@ const TARGETS = [
 ];
 
 function normalize(text) {
-    return String(text || '').replace(/\r\n/g, '\n');
+    return normalizeNewlines(text);
 }
 
 function removeKnownObsoleteDefaults(text) {
@@ -57,16 +60,223 @@ function upsertManagedBlock(content) {
     return `${trimmed}${trimmed ? '\n\n' : ''}${PROJECT_POLICY}\n`;
 }
 
+// --- Superpowers -> Matt Pocock skills migration -------------------------
+//
+// thachvd-kit used to generate Superpowers-branded workflow content into
+// AGENTS.md, .cursorrules, and .agent/docs/{workflow,tooling,getting-started,
+// index-project-prompt}.md. `upgrade` must move an existing project's
+// *generated* sections over to the current Matt Pocock skill workflow while
+// leaving hand-written/custom content alone.
+//
+// This never does a blind "contains Superpowers" strip. Each replacement is
+// gated on the exact signature thachvd-kit itself used to emit for that
+// section (checked with `LEGACY.test(...)` against the section body before
+// touching it); a section whose content doesn't match is left untouched,
+// including if the user rewrote it themselves. The "## Fast Path" sections
+// are the one exception: they are already synced unconditionally by
+// bin/policy.js for `init`, and this mirrors that exact behavior instead of
+// duplicating a second definition of "current" fast-path wording.
+
+const SUPERPOWERS_MIGRATION_TARGETS = [
+    'AGENTS.md',
+    '.cursorrules',
+    path.join('.agent', 'docs', 'workflow.md'),
+    path.join('.agent', 'docs', 'tooling.md'),
+    path.join('.agent', 'docs', 'getting-started.md'),
+    path.join('.agent', 'docs', 'index-project-prompt.md')
+];
+
+function extractSection(text, heading) {
+    const marker = `${heading}\n`;
+    const start = text.indexOf(marker);
+    if (start < 0) return null;
+    const searchFrom = start + marker.length;
+    const nextHeading = text.indexOf('\n## ', searchFrom);
+    const end = nextHeading >= 0 ? nextHeading + 1 : text.length;
+    return { start, end, body: text.slice(start, end) };
+}
+
+// Replaces a heading-delimited section only when its current body matches a
+// known legacy signature. Leaves the text unchanged if the heading is
+// missing or its content doesn't look like thachvd-kit's own old output.
+function replaceLegacySection(text, heading, legacySignature, replacement) {
+    const section = extractSection(text, heading);
+    if (!section || !legacySignature.test(section.body)) return text;
+    const prefix = text.slice(0, section.start);
+    const suffix = text.slice(section.end).replace(/^\n+/, '');
+    return `${prefix}${replacement.trimEnd()}\n\n${suffix}`.replace(/\n{3,}/g, '\n\n');
+}
+
+// Replaces one exact known-legacy line/sentence with its current
+// equivalent. Safe because the match is the full, specific sentence
+// thachvd-kit generated, not a loose keyword.
+function replaceLegacyLine(text, legacyLine, replacementLine) {
+    return text.includes(legacyLine) ? text.split(legacyLine).join(replacementLine) : text;
+}
+
+const AGENTS_WORKFLOW_SECTION = `## Workflow
+
+Matt Pocock's promoted skills (installed under \`.agents/skills/\` by \`thachvd-kit setup\`) are the workflow layer. Use the matching skill when a specialized workflow is useful:
+
+- Clear, localized change: inspect -> edit -> focused verification. Do not force a heavyweight skill.
+- Ambiguous feature or design: \`/grill-with-docs\`, then optionally \`/to-spec\` for a durable contract.
+- Normal feature: \`/grill-with-docs\` -> \`/to-spec\` -> \`/implement\`.
+- Large feature needing decomposition: add \`/to-tickets\` before \`/implement\`.
+- Huge, multi-session uncertainty: \`/wayfinder\`.
+- Bug or failing behavior: \`/diagnosing-bugs\`.
+- Test-driven implementation: \`/tdd\` (skip the ceremony for trivial config/text changes).
+- Architecture survey: \`/improve-codebase-architecture\`; use \`/codebase-design\` as the design vocabulary.
+- Pre-completion review: \`/code-review\` once when code risk warrants it.
+
+If unsure which skill fits, use \`/ask-matt\`.
+
+Questions and research do not edit product code. A fast path is allowed only when the change is localized, mechanically obvious, low-risk, and has focused verification; file count alone is not a gate. State the scope and verification before editing. If the task becomes ambiguous or its behavior, contract, or risk surface grows, use the matching planning skill above instead.
+
+See \`.agent/docs/workflow.md\` for the full route matrix. This kit does not implement a second workflow engine; it only installs and checks the promoted skill set (\`thachvd-kit skills install|check|update\`).`;
+
+function migrateAgentsStyleMarkdown(content) {
+    let text = normalize(content);
+    text = replaceLegacySection(text, '## Workflow', /Superpowers is the primary workflow backend/, AGENTS_WORKFLOW_SECTION);
+    text = replaceLegacyLine(
+        text,
+        "- Superpowers: installed through the AI client's official plugin surface",
+        '- Matt Pocock skills: promoted set installed under `.agents/skills/` via `thachvd-kit skills install`'
+    );
+    // Older, short-form .cursorrules that never embedded the full AGENTS.md body.
+    text = replaceLegacyLine(
+        text,
+        'Use Superpowers as the workflow backend. Use direct local evidence when it is sufficient and structural tooling such as codebase-memory MCP only when ownership, call paths, architecture, or impact need discovery.',
+        "Use Matt Pocock's promoted skills (`.agents/skills/`) as the workflow backend; run `/ask-matt` if unsure which one fits. Use direct local evidence when it is sufficient and structural tooling such as codebase-memory MCP only when ownership, call paths, architecture, or impact need discovery."
+    );
+    return text;
+}
+
+const WORKFLOW_ROUTE_MATRIX_SECTION = `## Route Matrix
+
+| Situation | Skill | Gate |
+|---|---|---|
+| 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 |
+| 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 |
+| Architecture survey | /improve-codebase-architecture (+ /codebase-design vocabulary) | findings reviewed before large refactors |
+| Pre-merge | /code-review | blocking findings resolved |
+
+Not sure which row applies? Run /ask-matt instead of guessing.`;
+
+const WORKFLOW_STANDARD_FLOW_SECTION = `## Standard Feature Flow
+
+/grill-with-docs -> /to-spec -> (/to-tickets for large work) -> /implement (with /tdd where it helps) -> /code-review.`;
+
+function migrateWorkflowMarkdown(content) {
+    let text = normalize(content);
+    text = replaceLegacyLine(
+        text,
+        'This project uses Superpowers as the workflow backend. thachvd-kit only provides project context and integration setup.',
+        "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."
+    );
+    text = replaceLegacyLine(
+        text,
+        '2. Use the native Superpowers skill that matches the request.',
+        '2. Use the promoted skill that matches the request, or run /ask-matt if unsure which one fits.'
+    );
+    text = replaceLegacySection(text, '## Route Matrix', /Superpowers path/, WORKFLOW_ROUTE_MATRIX_SECTION);
+    text = replaceLegacySection(text, '## Standard Feature Flow', /\bbrainstorming\s*->/, WORKFLOW_STANDARD_FLOW_SECTION);
+    // Always kept in sync with the current risk-based wording, same as
+    // bin/policy.js does for a freshly generated project.
+    text = replaceSection(text, '## Fast Path', FAST_PATH_SECTION);
+    return text;
+}
+
+const TOOLING_MATT_SKILLS_SECTION = `## Matt Pocock Skills
+
+Matt Pocock's promoted engineering and productivity skills are the workflow layer for this project, installed project-locally under \`.agents/skills/\` (never globally):
+
+- 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)
+- Update the promoted set: \`thachvd-kit skills update\` (re-adds each skill individually for safety, so it is slower than install — one network clone per skill)
+- 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\`.`;
+
+function migrateToolingMarkdown(content) {
+    const text = normalize(content);
+    return replaceLegacySection(text, '## Superpowers', /Install Superpowers separately/, TOOLING_MATT_SKILLS_SECTION);
+}
+
+const GETTING_STARTED_SETUP_SECTION = `## 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.
+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.`;
+
+const GETTING_STARTED_STANDARD_FLOW_SECTION = `## Standard Flow
+
+1. \`/grill-with-docs\` for unclear requirements or design.
+2. \`/to-spec\` when a durable implementation contract is useful.
+3. \`/to-tickets\` for large work that benefits from decomposition.
+4. \`/implement\`, with \`/tdd\` where red-green-refactor helps.
+5. \`/code-review\` once before completion.
+
+Not sure which skill fits? Run \`/ask-matt\`.`;
+
+const GETTING_STARTED_BUG_FLOW_SECTION = `## Bug Flow
+
+Use \`/diagnosing-bugs\`: reproduce the symptom, inspect the path with codebase-memory MCP, test hypotheses, add regression protection, fix the root cause, and verify.`;
+
+function migrateGettingStartedMarkdown(content) {
+    let text = normalize(content);
+    text = replaceLegacyLine(
+        text,
+        'thachvd-kit creates project context. Superpowers owns the development workflow.',
+        "thachvd-kit creates project context. Matt Pocock's promoted skills own the development workflow."
+    );
+    text = replaceLegacySection(text, '## Setup', /Install Superpowers and RTK/, GETTING_STARTED_SETUP_SECTION);
+    text = replaceLegacySection(text, '## Standard Flow', /Use Superpowers native skills/, GETTING_STARTED_STANDARD_FLOW_SECTION);
+    text = replaceLegacySection(text, '## Bug Flow', /`systematic-debugging`/, GETTING_STARTED_BUG_FLOW_SECTION);
+    // Always kept in sync, same reasoning as the workflow.md Fast Path above.
+    text = replaceSection(text, '## Fast Path', GETTING_STARTED_FAST_PATH_SECTION);
+    return text;
+}
+
+function migrateIndexProjectPrompt(content) {
+    return replaceLegacyLine(
+        normalize(content),
+        'Use Superpowers for the workflow and use codebase-memory MCP for structural code discovery when available.',
+        'Use the project\'s Matt Pocock skills for workflow (see AGENTS.md; run /ask-matt if unsure which fits) and use codebase-memory MCP for structural code discovery when available.'
+    );
+}
+
+function migrateSuperpowersWorkflow(relativePath, content) {
+    const normalized = relativePath.split(path.sep).join('/');
+    if (normalized === 'AGENTS.md' || normalized === '.cursorrules') return migrateAgentsStyleMarkdown(content);
+    if (normalized.endsWith('/workflow.md')) return migrateWorkflowMarkdown(content);
+    if (normalized.endsWith('/tooling.md')) return migrateToolingMarkdown(content);
+    if (normalized.endsWith('/getting-started.md')) return migrateGettingStartedMarkdown(content);
+    if (normalized.endsWith('/index-project-prompt.md')) return migrateIndexProjectPrompt(content);
+    return normalize(content);
+}
+
+const ALL_UPGRADE_TARGETS = Array.from(new Set([...TARGETS, ...SUPERPOWERS_MIGRATION_TARGETS]));
+
 function upgradeProject(rootDir, options = {}) {
     const dryRun = options.dryRun === true;
     const results = [];
 
-    for (const relativePath of TARGETS) {
+    for (const relativePath of ALL_UPGRADE_TARGETS) {
         const fullPath = path.join(rootDir, relativePath);
         if (!fs.existsSync(fullPath)) continue;
 
         const existing = fs.readFileSync(fullPath, 'utf8');
-        const updated = upsertManagedBlock(existing);
+        let updated = migrateSuperpowersWorkflow(relativePath, existing);
+        if (TARGETS.includes(relativePath)) updated = upsertManagedBlock(updated);
+
         const changed = normalize(existing) !== updated;
         if (changed && !dryRun) fs.writeFileSync(fullPath, updated, 'utf8');
         results.push({ path: relativePath, changed, dryRun: changed && dryRun });
@@ -80,7 +290,9 @@ module.exports = {
     END,
     PROJECT_POLICY,
     TARGETS,
+    SUPERPOWERS_MIGRATION_TARGETS,
     removeKnownObsoleteDefaults,
     upsertManagedBlock,
+    migrateSuperpowersWorkflow,
     upgradeProject
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "thachvd-kit",
-    "version": "1.0.34",
+    "version": "1.0.36",
     "description": "Cross-agent project rules bootstrap kit for Codex, Antigravity, and Claude Code",
     "bin": {
         "thachvd-kit": "./bin/entry.js"
@@ -15,8 +15,8 @@
         "node": ">=16.7"
     },
     "scripts": {
-        "test": "node test/cli.test.js && node test/policy.test.js && node test/upgrade.test.js && node test/global.test.js",
-        "release:verify": "npm test && node --check bin/cli.js && node --check bin/entry.js && node --check bin/policy.js && node --check bin/upgrade.js && node --check bin/global.js && npm pack --dry-run",
+        "test": "node test/cli.test.js && node test/policy.test.js && node test/matt-skills.test.js && node test/upgrade.test.js && node test/global.test.js",
+        "release:verify": "npm test && node --check bin/cli.js && node --check bin/entry.js && node --check bin/policy.js && node --check bin/matt-skills.js && node --check bin/upgrade.js && node --check bin/global.js && npm pack --dry-run",
         "preversion": "npm run release:verify",
         "release:patch": "npm version patch",
         "release:dry-run": "npm pack --dry-run",