thachvd-kit 1.0.33 → 1.0.35

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

@@ -4,16 +4,76 @@ const {
     snapshotPolicyFiles,
     applyPolicyUpgrades
 } = require('./policy');
+const { upgradeProject } = require('./upgrade');
+const { installGlobalPolicies } = require('./global');
 
 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('-');
 }
 
+function runUpgrade(args) {
+    const results = upgradeProject(process.cwd(), { dryRun: args.includes('--dry-run') });
+    const changed = results.filter(result => result.changed);
+    if (changed.length === 0) {
+        console.log('No managed project policy changes needed.');
+        return;
+    }
+    for (const result of changed) {
+        console.log(`${result.dryRun ? 'WOULD UPDATE' : 'UPDATED'} ${result.path}`);
+    }
+}
+
+function runGlobal(args) {
+    const homeDir = process.env.USERPROFILE || process.env.HOME;
+    if (!homeDir) {
+        console.error('Cannot determine home directory from USERPROFILE or HOME.');
+        process.exitCode = 1;
+        return;
+    }
+
+    const antigravityOnly = args.includes('--antigravity-only');
+    const codexOnly = args.includes('--codex-only');
+    if (antigravityOnly && codexOnly) {
+        console.error('Choose at most one of --antigravity-only or --codex-only.');
+        process.exitCode = 1;
+        return;
+    }
+
+    const results = installGlobalPolicies(homeDir, {
+        antigravityOnly,
+        codexOnly,
+        dryRun: args.includes('--dry-run')
+    });
+
+    for (const result of results) {
+        const status = result.changed ? (result.dryRun ? 'WOULD UPDATE' : 'UPDATED') : 'OK';
+        console.log(`${status} ${result.path}`);
+    }
+
+    if (results.some(result => result.changed) && !args.includes('--dry-run')) {
+        console.log('Restart Antigravity/Codex sessions so the updated global instructions are reloaded.');
+    }
+}
+
 const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === 'upgrade') {
+    runUpgrade(args.slice(1));
+    return;
+}
+
+if (command === 'global') {
+    runGlobal(args.slice(1));
+    return;
+}
+
 const shouldUpgradeGeneratedPolicy = isInitInvocation(args);
 const beforeSnapshot = shouldUpgradeGeneratedPolicy ? snapshotPolicyFiles(process.cwd()) : null;
 const force = args.includes('--yes') || args.includes('-y');