thachvd-kit 1.0.34 → 1.0.35

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,191 @@
+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 (verified
+// against its installed agent registry). Both currently resolve to the same
+// project-local skills directory below.
+const SUPPORTED_AGENTS = ['codex', 'antigravity'];
+
+// 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,86 +1,298 @@
-const fs = require('fs');
-const path = require('path');
-
-const START = '<!-- thachvd-kit:project-policy:start -->';
-const END = '<!-- thachvd-kit:project-policy:end -->';
-
-const PROJECT_POLICY = `${START}
-## Engineering Policy
-
-Prefer the smallest sufficient change, not the fewest lines of code.
-
-- Preserve required behavior, product and architectural contracts, UX/accessibility, security/data integrity, compatibility/performance, and maintainability before optimizing for simplicity.
-- Reuse an existing project abstraction when it satisfies the required contract. Do not bypass it merely because a lower-level primitive is shorter.
-- Avoid speculative abstractions and unrelated refactors.
-- Do not split or reorganize code solely to satisfy a line-count target. Prefer cohesive modules and split only for a concrete cohesion, ownership, testability, or maintainability benefit.
-- Fast-path eligibility is based on risk and contract surface, not file count. A code change plus its focused test can still be trivial; a one-file auth, payment, schema, concurrency, or public-contract change is not.
-- Use the cheapest reliable context source. Read/search directly for known local code and exact text; use one structural index such as codebase-memory-mcp or CodeGraph for unknown ownership, call paths, architecture, or impact; avoid duplicate retrieval once sufficient evidence is available.
-- Prefer RTK for verbose shell output when it preserves the information needed. Use raw output when required for diagnosis.
-- Tests or equivalent verification are mandatory before claiming completion.
-${END}`;
-
-const TARGETS = [
-    'AGENTS.md',
-    path.join('.agent', 'docs', 'conventions.md'),
-    path.join('.agent', 'docs', 'workflow.md'),
-    path.join('.agent', 'docs', 'tooling.md')
-];
-
-function normalize(text) {
-    return String(text || '').replace(/\r\n/g, '\n');
-}
-
-function removeKnownObsoleteDefaults(text) {
-    return normalize(text)
-        .replace(/^\s*- Maximum file length: 300 lines unless the existing project standard is stricter\.\s*\n?/gm, '')
-        .replace(/^\s*- Keep files under 300 lines unless the project already has a different standard[^\n]*\n?/gm, '')
-        .replace(/^\s*- \*\*MCP First\*\*:[^\n]*\n?/gm, '')
-        .replace(/^\s*- Use MCP first for code discovery and technical documentation;[^\n]*\n?/gm, '')
-        .replace(/Use it only for one-file, unambiguous changes with no behavior, API, schema, security, dependency, CI, workflow, or release contract change\.[^\n]*/g,
-            'Fast-path eligibility is based on risk and contract surface, not file count. Use it only for localized, mechanically obvious, low-risk changes with focused verification.')
-        .replace(/Use a fast path only for one-file, unambiguous changes with no behavior or contract change\.[^\n]*/g,
-            'Use a fast path only for localized, mechanically obvious, low-risk changes with focused verification; file count alone is not a gate.')
-        .replace(/\n{3,}/g, '\n\n');
-}
-
-function upsertManagedBlock(content) {
-    let text = removeKnownObsoleteDefaults(content);
-    const start = text.indexOf(START);
-    const end = text.indexOf(END);
-
-    if (start >= 0 && end >= start) {
-        const after = end + END.length;
-        return `${text.slice(0, start)}${PROJECT_POLICY}${text.slice(after)}`.replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
-    }
-
-    const trimmed = text.trimEnd();
-    return `${trimmed}${trimmed ? '\n\n' : ''}${PROJECT_POLICY}\n`;
-}
-
-function upgradeProject(rootDir, options = {}) {
-    const dryRun = options.dryRun === true;
-    const results = [];
-
-    for (const relativePath of TARGETS) {
-        const fullPath = path.join(rootDir, relativePath);
-        if (!fs.existsSync(fullPath)) continue;
-
-        const existing = fs.readFileSync(fullPath, 'utf8');
-        const updated = upsertManagedBlock(existing);
-        const changed = normalize(existing) !== updated;
-        if (changed && !dryRun) fs.writeFileSync(fullPath, updated, 'utf8');
-        results.push({ path: relativePath, changed, dryRun: changed && dryRun });
-    }
-
-    return results;
-}
-
-module.exports = {
-    START,
-    END,
-    PROJECT_POLICY,
-    TARGETS,
-    removeKnownObsoleteDefaults,
-    upsertManagedBlock,
-    upgradeProject
-};
+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 -->';
+
+const PROJECT_POLICY = `${START}
+## Engineering Policy
+
+Prefer the smallest sufficient change, not the fewest lines of code.
+
+- Preserve required behavior, product and architectural contracts, UX/accessibility, security/data integrity, compatibility/performance, and maintainability before optimizing for simplicity.
+- Reuse an existing project abstraction when it satisfies the required contract. Do not bypass it merely because a lower-level primitive is shorter.
+- Avoid speculative abstractions and unrelated refactors.
+- Do not split or reorganize code solely to satisfy a line-count target. Prefer cohesive modules and split only for a concrete cohesion, ownership, testability, or maintainability benefit.
+- Fast-path eligibility is based on risk and contract surface, not file count. A code change plus its focused test can still be trivial; a one-file auth, payment, schema, concurrency, or public-contract change is not.
+- Use the cheapest reliable context source. Read/search directly for known local code and exact text; use one structural index such as codebase-memory-mcp or CodeGraph for unknown ownership, call paths, architecture, or impact; avoid duplicate retrieval once sufficient evidence is available.
+- Prefer RTK for verbose shell output when it preserves the information needed. Use raw output when required for diagnosis.
+- 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'),
+    path.join('.agent', 'docs', 'workflow.md'),
+    path.join('.agent', 'docs', 'tooling.md')
+];
+
+function normalize(text) {
+    return normalizeNewlines(text);
+}
+
+function removeKnownObsoleteDefaults(text) {
+    return normalize(text)
+        .replace(/^\s*- Maximum file length: 300 lines unless the existing project standard is stricter\.\s*\n?/gm, '')
+        .replace(/^\s*- Keep files under 300 lines unless the project already has a different standard[^\n]*\n?/gm, '')
+        .replace(/^\s*- \*\*MCP First\*\*:[^\n]*\n?/gm, '')
+        .replace(/^\s*- Use MCP first for code discovery and technical documentation;[^\n]*\n?/gm, '')
+        .replace(/Use it only for one-file, unambiguous changes with no behavior, API, schema, security, dependency, CI, workflow, or release contract change\.[^\n]*/g,
+            'Fast-path eligibility is based on risk and contract surface, not file count. Use it only for localized, mechanically obvious, low-risk changes with focused verification.')
+        .replace(/Use a fast path only for one-file, unambiguous changes with no behavior or contract change\.[^\n]*/g,
+            'Use a fast path only for localized, mechanically obvious, low-risk changes with focused verification; file count alone is not a gate.')
+        .replace(/\n{3,}/g, '\n\n');
+}
+
+function upsertManagedBlock(content) {
+    let text = removeKnownObsoleteDefaults(content);
+    const start = text.indexOf(START);
+    const end = text.indexOf(END);
+
+    if (start >= 0 && end >= start) {
+        const after = end + END.length;
+        return `${text.slice(0, start)}${PROJECT_POLICY}${text.slice(after)}`.replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+    }
+
+    const trimmed = text.trimEnd();
+    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 ALL_UPGRADE_TARGETS) {
+        const fullPath = path.join(rootDir, relativePath);
+        if (!fs.existsSync(fullPath)) continue;
+
+        const existing = fs.readFileSync(fullPath, 'utf8');
+        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 });
+    }
+
+    return results;
+}
+
+module.exports = {
+    START,
+    END,
+    PROJECT_POLICY,
+    TARGETS,
+    SUPERPOWERS_MIGRATION_TARGETS,
+    removeKnownObsoleteDefaults,
+    upsertManagedBlock,
+    migrateSuperpowersWorkflow,
+    upgradeProject
+};