thachvd-kit 1.0.36 → 1.0.38

package/bin/upgrade.js

@@ -1,298 +1,303 @@
-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
-};
+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 plus thachvd-kit's native workflow skills (installed under \`.agents/skills/\` and \`.claude/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\` -> choose workspace -> \`/implement\`.
+- Large feature needing decomposition: add \`/to-tickets\`, choose workspace, then choose \`/implement\` or \`/subagent-driven-development\`.
+- 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.
+- Workspace choice: stay on the current branch when explicitly requested; use \`/using-git-worktrees\` only when isolation is wanted.
+- Branch handoff: \`/finishing-a-development-branch\` after verification and review.
+
+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 Matt workflow engine; it installs Matt's promoted skills plus thachvd-kit native skills (\`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 and thachvd-kit native skills (`.agents/skills/` and `.claude/skills/`) as the workflow layer; 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 -> choose workspace -> /implement | spec agreed before implementation |
+| Large feature needing decomposition | /grill-with-docs -> /to-spec -> /to-tickets -> choose workspace -> executor | tickets agreed before implementation |
+| Huge, multi-session uncertainty | /wayfinder | shared decision map before implementation |
+| Bug or failing behavior | /diagnosing-bugs | reproduce -> root cause -> regression protection -> fix -> verify |
+| Test-driven implementation | /tdd | red -> green -> refactor per slice |
+| 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) -> choose workspace -> choose executor (/implement or /subagent-driven-development) -> /code-review -> /finishing-a-development-branch.`;
+
+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 plus thachvd-kit's native workflow skills (installed under .agents/skills/ and .claude/skills/ by `thachvd-kit setup`) as the workflow layer. Native skills add opt-in workspace isolation, subagent-driven execution, and branch finishing; they do not replace Matt's planning, implementation, testing, or review skills."
+    );
+    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 + Native Workflow Skills
+
+Matt Pocock's promoted engineering and productivity skills are installed project-locally under \`.agents/skills/\` (never globally); thachvd-kit native workflow skills are installed under \`.agents/skills/\` and \`.claude/skills/\`:
+
+- Install the promoted set: \`thachvd-kit skills install\` (\`--dry-run\` to preview the command without running it)
+- Check what is installed: \`thachvd-kit skills check\` (read-only)
+- 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\`.
+- Native skills: \`/using-git-worktrees\` (opt-in isolation), \`/subagent-driven-development\` (alternative executor for multi-task plans), and \`/finishing-a-development-branch\`.
+- Native skills are refreshed from bundled copies; runtime updates never fetch upstream repositories.`;
+
+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 promoted and native skill sets by default; add \`--no-install-skills\` to skip) and RTK.
+4. Inside the AI client, run \`/setup-matt-pocock-skills\` once to configure the issue tracker, triage labels, and doc layout.
+5. Run \`thachvd-kit doctor\` and restart the AI client.`;
+
+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. Choose the current branch/workspace or \`/using-git-worktrees\` when isolation is wanted.
+5. Choose \`/implement\` (with \`/tdd\` where useful) or \`/subagent-driven-development\` for multiple relatively independent tasks.
+6. \`/code-review\`, then \`/finishing-a-development-branch\` once verification is complete.
+
+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 and thachvd-kit native 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 plus thachvd-kit native 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
+};