thachvd-kit 1.0.29 → 1.0.30

package/bin/cli.js

@@ -9,7 +9,9 @@ const packageJson = require('../package.json');
 
 const sourceDir = path.resolve(__dirname, '..');
 const targetDir = process.cwd();
-const FORGE_COMMANDS = ['forge-task', 'forge-fast', 'forge-debug', 'forge-research', 'forge-review', 'forge-release'];
+const CODEBASE_MEMORY_PACKAGE = 'codebase-memory-mcp';
+const CODEBASE_MEMORY_BINARY = 'codebase-memory-mcp';
+const RTK_INSTALL_COMMAND = 'cargo install --git https://github.com/rtk-ai/rtk --branch master rtk';
 
 // --- Skill Resolver ---
 
@@ -119,73 +121,48 @@ const BACKEND_FRAMEWORKS = ['laravel', 'cakephp', 'symfony', 'codeigniter', 'exp
 const MOBILE_DESKTOP_FRAMEWORKS = ['tauri', 'flutter', 'react-native'];
 const IGNORED_SCAN_DIRS = new Set(['.git', 'node_modules', 'vendor', 'dist', 'build', 'coverage', '.next', '.nuxt', '.turbo', '.cache', 'storage', 'tmp']);
 
-function printHelp() {
-    console.log(`
-${pc.bold('Usage:')}
-  thachvd-kit [--yes]
-  thachvd-kit init [--yes]
-  thachvd-kit --version
-  thachvd-kit --help
-
-${pc.bold('Commands:')}
-  init      Bootstrap shared AI-agent rules and tooling
-
-${pc.bold('Options:')}
-  --yes     Overwrite generated files when they already exist
-  --no-setup-mcp Skip local Codegraph and Playwright MCP setup
-  --version Show the installed CLI version
-  --help    Show this help message
-
-${pc.bold('What gets generated:')}
-  AGENTS.md   Shared instructions for Codex, Antigravity, Claude Code, and Cursor
-  CLAUDE.md   Claude Code entry file that imports AGENTS.md
-  GEMINI.md   Antigravity entry file that points to AGENTS.md
-  .cursorrules Cursor entry file that points to AGENTS.md
-  .agent/     Shared docs, skills, workflows, agents, and rules
-  ~/.codex/skills/  Selected Codex skills copied to global user dir (shows in $ menu)
-  .claude/skills/   Selected Claude Code project skills copied from .agent/skills
-
+function printHelp() {
+    console.log(`
+${pc.bold('Usage:')}
+  thachvd-kit init [--yes]
+  thachvd-kit setup [--yes]
+  thachvd-kit doctor
+  thachvd-kit --version
+  thachvd-kit --help
+
+${pc.bold('Commands:')}
+  init      Generate project context files and documentation
+  setup     Install/configure optional MCP and local tooling
+  doctor    Check project context and local integrations
+
+${pc.bold('Options:')}
+  --yes     Overwrite generated files or accept setup defaults
+  --no-setup-mcp Skip MCP setup (legacy init compatibility)
+  --version Show the installed CLI version
+  --help    Show this help message
+
+${pc.bold('What gets generated:')}
+  AGENTS.md   Shared instructions for Codex, Antigravity, Claude Code, and Cursor
+  CLAUDE.md   Claude Code entry file that imports AGENTS.md
+  GEMINI.md   Antigravity entry file that points to AGENTS.md
+  .cursorrules Cursor entry file that points to AGENTS.md
+  .agent/docs/ Project context, architecture, conventions, workflow, and tooling docs
+
 ${pc.bold('Workflow guide:')}
-  Every task               /forge-task     Route and continue the selected workflow in this turn
-  Small obvious fix        /forge-fast     Fast path; skips spec/plan/review but still verifies
-  Idea is fuzzy            /brainstorm  Explore options, tradeoffs, and recommended direction
-  Research first           /forge-research Evidence-based research; no product-code edits
-  Scope needs a contract    /forge-task    Handles research, spec, plan approval, implementation, and review
-  New app from scratch     /create      Turn an app idea into plan + implementation flow
-  Feature is clear         /plan        Create docs/PLAN-*.md first, no code yet
-  Existing app update      /enhance     Add or change a feature in an existing codebase
-  Bug or failing behavior  /forge-debug  Investigate symptoms, root cause, fix
-  UI / UX work             ui-ux-pro-max, frontend-specialist, $frontend-design, $webapp-testing
-  Run or add tests         /test        Generate tests, run tests, check coverage
-  Preview locally          /preview     Start, stop, restart, or health-check dev server
-  Deploy / infra           /deploy      Release, hosting, Docker, cloud, environment setup
-  Pre-merge review         /forge-review Run the five-axis review before calling work complete
-  Npm package release      /forge-release Verify, version, tag, publish, and verify the package
-  Project state            /status      Summarize stack, progress, preview, pending work
-  Multi-domain work        /orchestrate Coordinate frontend, backend, data, security, QA
-
-${pc.bold('Common explicit skill prompts:')}
-  Use /forge-task to route and continue a request in one turn.
-  Use /forge-fast for a one-file fix with no behavior or contract change.
-  Use /brainstorm for this feature idea before planning.
-  Use /forge-task when requirements or scope need an explicit contract.
-  Use /plan for this feature; do not write code yet.
-  Use /enhance to implement this planned feature.
-  Use /forge-debug for this failing behavior and find the root cause before editing.
-  Use /review before claiming this feature/refactor complete.
-  Use /forge-release for npm versioning and publishing.
-  Use $clean-code before editing this module.
-  Use $systematic-debugging to investigate this bug.
-  Use $webapp-testing to verify the UI with Playwright.
-  Use $verification-before-completion before claiming done.
-  Use $writing-skills to improve a SKILL.md description.
-
-${pc.bold('Tip:')}
-  Skills are copied for Codex/Claude, but you can call them explicitly with $skill-name
-  when implicit matching does not fire.
-`);
-
-}
+  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('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.
+`);
+}
 
 function formatScanPreviewLines(scanned) {
     return [
@@ -903,10 +880,10 @@ function resolveAgentTable(data) {
 }
 // --- File Generators ---
 
-function generateSharedAgentsMd(data) {
-    return `# AGENTS.md
-
-Shared operating instructions for Codex, Antigravity, Claude Code, and Cursor.
+function generateSharedAgentsMd(data) {
+    return `# AGENTS.md
+
+Shared operating instructions for Codex, Antigravity, Claude Code, and Cursor.
 
 ## Startup
 
@@ -914,57 +891,24 @@ Shared operating instructions for Codex, Antigravity, Claude Code, and Cursor.
 2. Read \`.agent/docs/project.md\` for detected stack, commands, and routing.
 3. Read \`.agent/docs/workflow.md\` for the task flow before editing.
 4. Read \`.agent/docs/architecture.md\` and \`.agent/docs/conventions.md\` before planning code changes.
-5. Read \`.agent/docs/tooling.md\` when the task needs Playwright, codegraph, MCP, or native Codex/Claude skill setup.
-6. Select and load only the agent, skill, or workflow files that match the current task.
-
-If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the docs by scanning the project before making product code changes.
-
-## Task Flow
-
-Forge is the member-facing command suite. Use \`/forge-task <request>\` in Antigravity, Claude Code, or Cursor, and \`$forge-task <request>\` in Codex. The command classifies the request and continues the selected workflow in the same turn; it must not stop at a member-facing \`NEXT\` command.
-
-- Questions and analysis without a command: answer directly and do not edit code.
-- Edit requests without a command: route internally as \`forge-task\` before editing.
-- Simple fix: use \`/forge-fast <request>\` only for one-file, unambiguous changes with no behavior or contract change.
-- Bug or failing behavior: use \`/forge-debug <symptom>\` and follow the evidence-first root-cause flow.
-- Research: use \`/forge-research <question>\`; research does not edit product code.
-- Feature or refactor: \`forge-task\` handles research/brainstorm, spec, plan approval, implementation, test, and review in sequence.
-- Pre-merge review: use \`/forge-review\` even when implementation was done by another client or member.
-- Release or npm publish: use \`/forge-release\`; release work never uses the fast path.
-- Multi-domain work: use \`.agent/workflows/orchestrate.md\` and route to the relevant specialist docs.
-- UI work: read \`.agent/agents/frontend-specialist.md\` and applicable design skills before editing.
-
-### Fast Path (Forge \`forge-fast\`)
+5. Read \`.agent/docs/tooling.md\` when the task needs MCP, RTK, or browser verification.
 
-The fast path intentionally bypasses only Spec, Plan, and the feature/refactor Review gate for a trivial change. It never bypasses inspection, focused verification, or reporting evidence. The agent must state this protocol before editing:
+If any \`.agent/docs/*.md\` file still contains \`TODO: refine\`, update the docs by scanning the project before making product code changes.
 
-\`\`\`text
-FAST_PATH: simple-fix
-REASON: [why the change is one-file and unambiguous]
-SCOPE: [file or narrow area]
-\`\`\`
+## Workflow
 
-If the scope expands, stop and internally re-route through \`forge-task\`. Do not silently skip gates for work that changes behavior, APIs, schemas, security, CI, dependencies, workflows, or release state.
-
-### Gated Flow (feature or refactor)
+Superpowers is the primary workflow backend. Use its native skills when available:
 
-1. **Spec** — run \`.agent/workflows/spec.md\` when scope is ambiguous, touches multiple files, or would take more than ~30 minutes. Skip only for single-line/self-contained fixes. Stop at its exit criteria and wait for human confirmation before moving on.
-2. **Plan** — run \`.agent/workflows/plan.md\` (project-planner agent, no code writing). Wait for explicit user approval of the plan file before implementing.
-3. **Implement** — smallest coherent change per the approved plan, with focused tests for changed behavior.
-4. **Review** — run \`.agent/workflows/review.md\` (five-axis review) before the change is considered done. All 🔴 BLOCKING items must be resolved or explicitly accepted with rationale.
+- 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\`.
 
-A feature/refactor task is not "done" until step 4's exit criteria are met — passing tests alone does not satisfy the gate. Simple fixes use the explicit \`forge-fast\` path above. See \`.agent/docs/getting-started.md\` for the complete route guide.
+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.
 
-## Skill Loading
-
-- Treat \`.agent/skills/\` as the shared source of truth for all kit skills.
-- Codex exposes skills from \`~/.codex/skills/\` in the \`$\` menu; \`thachvd-kit\` copies selected skills there on init.
-- Claude Code project skills live in \`.claude/skills/\`.
-- If a skill is missing from the global dir, fall back to the matching \`.agent/skills/<skill>/SKILL.md\` file.
-- Do not load skill bodies by default; load a skill only when the user mentions it, the task clearly matches its description, or \`.agent/docs/project.md\` routes the task to it.
-- Prefer explicit skill mentions for predictable behavior: \`$clean-code\`, \`$systematic-debugging\`, \`$webapp-testing\`, or any skill listed in \`.agent/docs/project.md\`.
-- Run \`thachvd-kit --help\` to see common workflow and skill recommendations.
-- When creating or improving skills, use \`writing-skills\` first and make the \`description\` field specific enough for implicit invocation.
+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.
 
 ## Rules
 
@@ -972,23 +916,19 @@ A feature/refactor task is not "done" until step 4's exit criteria are met — p
 - 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 using MCP server tools (e.g., \`codegraph\` for codebase search/symbol tracking, \`context7\` for API/docs queries, and \`playwright\` for browser/UI testing and verification) to explore, search, and verify rather than recursively listing directories, running expensive shell commands/grep, or reading large files. This minimizes token usage and maintains a cleaner context.
+- **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.
 - 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\`.
 
-## Shared Knowledge
-
-- Project docs: \`.agent/docs/\`
-- Specialist agents: \`.agent/agents/\`
-- Skills: \`.agent/skills/\`
-- Codex global skills: \`~/.codex/skills/\` (installed by thachvd-kit init)
-- Claude Code project skills: \`.claude/skills/\`
-- Workflows: \`.agent/workflows/\`
-- Tooling setup: \`.agent/docs/tooling.md\`
-- Antigravity mirror rules: \`.agent/rules/GEMINI.md\`
-- Cursor entry rules: \`.cursorrules\`
-`;
-}
+## Shared Knowledge
+
+- Project context: \`.agent/docs/\`
+- Tooling setup: \`.agent/docs/tooling.md\`
+- Superpowers: installed through the AI client's official plugin surface
+- RTK: optional local CLI for compact command output
+- Antigravity and Cursor entry rules: \`GEMINI.md\` and \`.cursorrules\`
+`;
+}
 
 function generateSharedClaudeMd() {
     return `@AGENTS.md
@@ -1074,8 +1014,6 @@ function resolveCommands(data) {
 
 function generateProjectDoc(data) {
     const commands = resolveCommands(data);
-    const agentRows = resolveAgentTable(data).map(([task, agent, skills]) => `| ${task} | \`${agent}\` | ${skills} |`).join('\n');
-    const skillsList = resolveSkills(data).map(s => `- ${s}`).join('\n');
     const evidence = (data.scan_evidence || []).length > 0
         ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
         : '- TODO: refine scan evidence by inspecting the project.';
@@ -1108,29 +1046,20 @@ Generated by thachvd-kit on ${new Date().toISOString().split('T')[0]}.
 - Test: \`${commands.test}\`
 - Lint: \`${commands.lint}\`
 
-## Available MCP Tools
+## Available Integrations
 
-Use these tools as first-class search and verification methods — prefer them over shell commands or file reads.
+Use these integrations when available. Run thachvd-kit doctor to check the current machine.
 
 | MCP | When to Use |
 |-----|-------------|
-| \`codegraph\` | Explore symbols, trace call chains, find usages — use BEFORE reading files |
+| \`codebase-memory-mcp\` | Explore symbols, trace call chains, architecture, and impact |
 | \`context7\` | Look up library/framework docs, API signatures, migration guides |
-| \`playwright\` | Verify UI behavior, take screenshots, test forms and navigation |
+| \`playwright\` | Verify UI behavior, take screenshots, test forms and navigation |
+| \`rtk\` | Reduce noisy output from git, tests, builds, and package commands |
 
 > Check \`.agent/docs/tooling.md\` for setup details and additional MCP servers.
 
-## Agent Routing
-
-| Task Type | Agent | Primary Skills |
-|-----------|-------|----------------|
-${agentRows}
-
-## Auto-Resolved Skills
-
-${skillsList}
-
-## Scan Evidence
+## Scan Evidence
 
 ${evidence}
 `;
@@ -1182,38 +1111,77 @@ function generateConventionsDoc(data) {
 `;
 }
 
-function generateWorkflowDoc() {
-    return `# Agent Workflow
+function generateWorkflowDoc() {
+    return `# Agent Workflow
+
+This project uses Superpowers as the workflow backend. thachvd-kit only provides project context and integration setup.
+
+## Before Every Task
+
+1. Read AGENTS.md and the relevant files under .agent/docs/.
+2. Use the native Superpowers skill that matches the request.
+3. Use codebase-memory MCP for structural discovery when available.
+4. Make changes only after the required planning gate.
+5. Verify the change and request review before completion.
+
+## Route Matrix
+
+| Situation | Superpowers path | 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 |
+
+## 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
+
+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.
+
+## Documentation Maintenance
+
+- Update architecture.md when structure or boundaries change.
+- Update conventions.md when repeated project patterns become clear.
+- Update project.md when stack, scripts, or test tooling changes.
+- Keep AGENTS.md concise and put project-specific detail under .agent/docs/.
+`;
+    /* Legacy workflow text below remains unreachable for source compatibility. */
+    return `# Agent Workflow
 
 ## Before Every Task
 
 1. Read AGENTS.md.
 2. Read .agent/docs/project.md.
-3. Use \`/forge-task <request>\` (or \`$forge-task <request>\` in Codex) when the request changes code and the path is not obvious.
+3. Use the matching native Superpowers skill for the task.
 4. Read only the relevant docs under .agent/agents, .agent/skills, .claude/skills, and .agent/workflows.
-5. Check if MCP servers (like \`codegraph\`) are active/available and prioritize using them as the primary entry point to search and locate files, symbols, and code blocks.
+5. Use codebase-memory MCP for structural discovery when available, then verify the actual files before editing.
 
 ## Route Matrix
 
 | Situation | Command | Workflow / gate |
 |---|---|---|
 | Question or analysis only | direct answer | no edits |
-| One obvious local fix | \`/forge-fast\` | \`.agent/workflows/simple.md\`, fast-path |
-| Bug, regression, failing test, or unknown error | \`/forge-debug\` | \`.agent/workflows/debug.md\`, evidence-first |
-| Research request | \`/forge-research\` | evidence report, no edits |
-| New behavior, multi-file change, or unclear scope | \`/forge-task\` | research/spec/plan approval -> implement -> review |
-| Pre-merge review | \`/forge-review\` | \`.agent/workflows/review.md\`, five-axis |
-| npm version, tag, publish, or deployment | \`/forge-release\` | \`.agent/workflows/release.md\`, release gate |
-| Several specialist domains | \`/orchestrate\` | plan -> approval -> parallel work -> integration verify |
+| One obvious local fix | fast path | inspect -> edit -> focused verify |
+| Bug, regression, failing test, or unknown error | systematic-debugging | reproduce -> root cause -> regression test -> fix -> verify |
+| Research request | direct research | evidence report, no edits |
+| New behavior, multi-file change, or unclear scope | brainstorming -> writing-plans -> executing-plans | explicit approval before implementation |
+| Pre-merge review | requesting-code-review | blocking findings resolved |
+| Several specialist domains | subagent-driven-development | task review and final review |
 
 If a task is not clearly simple, use the standard flow. Never use the fast path for behavior, API, schema, security, CI, dependency, workflow, or release changes.
 
-## Skill Selection
+## Superpowers Skills
 
-- Prefer native skill discovery when the client exposes it.
-- Codex global skills live in ~/.codex/skills/ and are visible via the $ menu; thachvd-kit copies selected skills there on init.
-- Claude Code project skills live in .claude/skills.
-- Shared fallback skills live in .agent/skills.
+- Use brainstorming for unclear requirements.
+- Use using-git-worktrees and writing-plans before non-trivial implementation.
+- Use test-driven-development, executing-plans or subagent-driven-development during implementation.
+- Use systematic-debugging for bugs and requesting-code-review before completion.
+- thachvd-kit does not copy or replace Superpowers skills.
 - Do not load skill bodies by default.
 - Load a skill when the user mentions it, the task clearly matches its SKILL.md description, or .agent/docs/project.md routes the task to it.
 - Use explicit skill names in prompts for predictable behavior, for example $webapp-testing or $clean-code.
@@ -1238,9 +1206,9 @@ Then:
 5. Run verification (prioritize using Playwright MCP for web/UI changes to automate verification and capture screenshots).
 6. Summarize changed files and verification evidence.
 
-For bugs, use \`/forge-debug\` with \`$systematic-debugging\`, the \`debugger\` agent, and \`testing-patterns\`: reproduce, isolate the root cause, add regression protection, make the smallest fix, and verify.
+For bugs, use \`/forge-debug\` with Superpowers' \`systematic-debugging\` when available, otherwise the matching local skill, plus the \`debugger\` agent and \`testing-patterns\`: reproduce, isolate the root cause, add regression protection, make the smallest fix, and verify.
 
-For features or refactors, this flow runs *inside* the gated flow defined in AGENTS.md (spec -> plan -> implement -> review) — steps 3-5 above are the "Implement" phase, and step 6 is not a substitute for the mandatory \`.agent/workflows/review.md\` gate.
+For features or refactors, prefer the Superpowers chain when available: brainstorm/spec -> worktree -> detailed plan -> approval -> TDD/task execution -> per-task review -> final review -> finish branch. Otherwise use the local gated flow defined in AGENTS.md (spec -> plan -> implement -> review). Steps 3-5 above are the "Implement" phase, and step 6 is not a substitute for the mandatory review gate.
 
 ## Definition of Done (feature or refactor)
 
@@ -1266,21 +1234,54 @@ Do not report a feature/refactor task as done if any box above is unchecked —
 }
 
 function generateGettingStartedDoc() {
+    return `# Getting Started
+
+thachvd-kit creates project context. Superpowers owns the development workflow.
+
+## Setup
+
+1. Run \`thachvd-kit init\` in the repository.
+2. Install Superpowers from the official plugin surface for the AI client you use.
+3. Run \`thachvd-kit setup\` to configure codebase-memory MCP and print integration guidance.
+4. Run \`thachvd-kit doctor\` and restart the AI client.
+
+## Standard Flow
+
+Use Superpowers native skills:
+
+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\`.
+
+## 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.
+
+## 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.
+`;
+    /* Legacy text below remains unreachable for source compatibility and is removed in a later major cleanup. */
     return `# Getting Started With This Kit
 
 Read this after \`thachvd-kit init\`. The kit gives every member one entry point, then selects only the process and expertise the task needs.
 
 ## Forge Command Map
 
-| Client | Task | Fast | Debug | Research | Review | Release |
-|---|---|---|---|---|---|---|
-| Codex | \`$forge-task\` | \`$forge-fast\` | \`$forge-debug\` | \`$forge-research\` | \`$forge-review\` | \`$forge-release\` |
-| Antigravity | \`/forge-task\` | \`/forge-fast\` | \`/forge-debug\` | \`/forge-research\` | \`/forge-review\` | \`/forge-release\` |
-| Claude Code | \`/forge-task\` | \`/forge-fast\` | \`/forge-debug\` | \`/forge-research\` | \`/forge-review\` | \`/forge-release\` |
-| Cursor | \`/forge-task\` | \`/forge-fast\` | \`/forge-debug\` | \`/forge-research\` | \`/forge-review\` | \`/forge-release\` |
+| Client | Task | Fast | Debug | Research | Review |
+|---|---|---|---|---|---|
+| Codex | \`$forge-task\` | \`$forge-fast\` | \`$forge-debug\` | \`$forge-research\` | \`$forge-review\` |
+| Antigravity | \`/forge-task\` | \`/forge-fast\` | \`/forge-debug\` | \`/forge-research\` | \`/forge-review\` |
+| Claude Code | \`/forge-task\` | \`/forge-fast\` | \`/forge-debug\` | \`/forge-research\` | \`/forge-review\` |
+| Cursor | \`/forge-task\` | \`/forge-fast\` | \`/forge-debug\` | \`/forge-research\` | \`/forge-review\` |
 
 Forge commands accept free-form text after the command and continue the selected workflow in the same turn. Plain questions remain normal chat; edit requests without a command are implicitly routed as \`forge-task\`.
 
+Forge is a routing layer. For feature/refactor work, prefer native Superpowers skills when available: brainstorming, using-git-worktrees, writing-plans, subagent-driven-development or executing-plans, test-driven-development, requesting-code-review, and finishing-a-development-branch. If Superpowers is not installed, use the matching \`.agent/skills/\` and \`.agent/workflows/\` fallback; do not maintain a competing duplicate methodology. Install the full execution backend from https://github.com/obra/superpowers#quickstart.
+
 Codex Forge skills live in \`~/.codex/skills/forge-*/SKILL.md\`. Antigravity Forge workflows live in \`.agent/workflows/forge-*.md\`. Claude Code Forge commands live in \`.claude/commands/forge-*.md\`. Cursor Forge commands live in \`.cursor/commands/forge-*.md\`.
 
 ## Start Every Task With Forge
@@ -1288,11 +1289,12 @@ Codex Forge skills live in \`~/.codex/skills/forge-*/SKILL.md\`. Antigravity For
 Use the matching Forge command before editing whenever the request is not a simple question. \`forge-task\` must route internally and continue; it must not stop by asking the member to type a second command.
 
 \`\`\`text
-ROUTE: question | fast | feature | bug | research | review | release | multi-domain
+ROUTE: question | fast | feature | bug | research | review | multi-domain
 WORKFLOW: [exact .agent/workflows/<name>.md file]
 SKILLS: [matching skills, or none]
 AGENTS: [matching specialist agents, or none]
 GATE: fast-path | standard | human-approval
+BACKEND: superpowers-native | forge-fallback
 ACTION: [what the agent is doing next in this turn]
 \`\`\`
 
@@ -1308,7 +1310,6 @@ A workflow is the process and its gates. A skill is the method or checklist. An
 | Bug, regression, failing test, or unknown error | \`/forge-debug <symptom>\` | bug | reproduce -> isolate -> regression test -> fix -> verify |
 | Research request | \`/forge-research <question>\` | research | evidence report, no edits |
 | Pre-merge or independent review | \`/forge-review\` | review | five-axis review; resolve blocking findings |
-| Version, tag, npm publish, or deployment | \`/forge-release\` | release | release checklist; never fast-path |
 | Frontend + backend + data/security together | \`/orchestrate\` | standard | plan -> approval -> specialist work -> integration verify |
 
 ## Standard Feature Flow
@@ -1329,7 +1330,7 @@ Use \`/forge-debug <symptom>\`, not the feature flow, when something is failing
 6. Run focused tests, then broader verification when the blast radius is shared.
 7. Use \`/review\` when the fix touches multiple files, contracts, security, or release behavior.
 
-Load \`$systematic-debugging\`, the \`debugger\` agent, and \`testing-patterns\` for this route.
+Load Superpowers' \`systematic-debugging\` when available, otherwise the matching local skill, plus the \`debugger\` agent and \`testing-patterns\` for this route.
 
 ## Simple Fast Path
 
@@ -1352,7 +1353,6 @@ This bypasses only Spec, Plan, and the feature/refactor Review gate. It never by
 - \`forge-debug\`: systematic root-cause investigation and regression protection.
 - \`/test\`: add or run tests and assess coverage.
 - \`/review\`: five-axis review before completion or merge.
-- \`forge-release\`: verify, version, tag, publish, and verify npm output.
 - \`$clean-code\` and \`$verification-before-completion\`: default implementation hygiene.
 - \`$webapp-testing\`: browser/UI verification; use Playwright when available.
 
@@ -1382,10 +1382,49 @@ function resolveToolingSetup(data) {
     return { runner, playwrightCommand };
 }
 
-function generateToolingDoc(data) {
-    const { runner, playwrightCommand } = resolveToolingSetup(data);
-
-    return `# Optional Tooling
+function generateToolingDoc(data) {
+    const { runner, playwrightCommand } = resolveToolingSetup(data);
+
+    return `# Optional Tooling
+
+Run \`thachvd-kit doctor\` to check the current machine. thachvd-kit does not install workflow skills or copy agent folders.
+
+## Superpowers
+
+Install Superpowers separately for each AI client from its official plugin surface:
+
+- 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\`
+
+Guide: https://github.com/obra/superpowers#installation
+
+## Codebase Memory MCP
+
+Use \`codebase-memory-mcp\` for symbol search, call paths, architecture, and impact analysis.
+
+- Install: \`npm install -g codebase-memory-mcp\`
+- Index a repository: \`codebase-memory-mcp cli index_repository --repo-path .\`
+- Keep local index state out of git unless the team explicitly chooses a shared snapshot.
+
+## RTK
+
+RTK is optional command-output compression, not a workflow engine.
+
+- Install: \`cargo install --git https://github.com/rtk-ai/rtk --branch master rtk\`
+- Prefer it for verbose git, test, build, package, and container commands when available.
+
+## Playwright
+
+- Check: \`${runner} playwright --version\`
+- Browser install: \`${playwrightCommand}\`
+- Use the project's existing Playwright scripts when available.
+`;
+    /* Legacy tooling text below remains unreachable for source compatibility. */
+
+    return `# Optional Tooling
 
 This kit keeps tool setup explicit. Do not assume these tools are available until you verify them in the current environment.
 
@@ -1664,6 +1703,19 @@ function copyForgeCommands() {
         claude: path.join(targetDir, '.claude', 'commands'),
         cursor: path.join(targetDir, '.cursor', 'commands')
     };
+
+    for (const commandName of REMOVED_FORGE_COMMANDS) {
+        const filename = `${commandName}.md`;
+        for (const destination of Object.values(destinations)) {
+            const commandPath = path.join(destination, filename);
+            if (fs.existsSync(commandPath)) fs.rmSync(commandPath, { force: true });
+        }
+        if (codexSkillsDir) {
+            const codexSkillPath = path.join(codexSkillsDir, commandName);
+            if (fs.existsSync(codexSkillPath)) fs.rmSync(codexSkillPath, { recursive: true, force: true });
+        }
+    }
+
     let antigravity = 0;
     let claude = 0;
     let cursor = 0;
@@ -1729,23 +1781,85 @@ async function writeGeneratedFile(relativePath, content, assumeYes) {
     return true;
 }
 
-function homePath(...parts) {
+function homePath(...parts) {
     const home = process.env.USERPROFILE || process.env.HOME;
     return home ? path.join(home, ...parts) : null;
-}
-
-function commandExists(command) {
+}
+
+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 runDoctor() {
+    console.log(pc.bold(pc.cyan('thachvd-kit doctor')));
+    const requiredFiles = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', '.cursorrules',
+        path.join('.agent', 'docs', 'project.md'), path.join('.agent', 'docs', 'workflow.md')];
+    for (const relativePath of requiredFiles) {
+        const ok = fs.existsSync(path.join(targetDir, relativePath));
+        console.log(`  ${ok ? pc.green('OK') : pc.yellow('WARN')} ${relativePath}`);
+    }
+
+    const tools = [
+        [CODEBASE_MEMORY_BINARY, `npm install -g ${CODEBASE_MEMORY_PACKAGE}`],
+        ['rtk', 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']
+    ];
+    console.log(`\n${pc.bold('Local integrations')}`);
+    for (const [binary, hint] of tools) {
+        const ok = commandExists(binary);
+        console.log(`  ${ok ? pc.green('OK') : pc.yellow('WARN')} ${binary}${ok ? '' : ` - ${hint}`}`);
+    }
+
+    console.log(`\n${pc.bold('Next step')}`);
+    console.log('  Run thachvd-kit setup to configure MCP and print client-specific Superpowers setup.');
+}
+
+async function runSetup(args) {
+    const skipMcpSetup = args.includes('--no-setup-mcp');
+    console.log(pc.bold(pc.cyan('thachvd-kit setup')));
+    printSuperpowersInstallGuide();
+    if (!skipMcpSetup) {
+        console.log(pc.bold('MCP setup'));
+        for (const result of setupMcpServers({ install: true })) {
+            const marker = result.ok ? pc.green('OK') : pc.yellow('WARN');
+            console.log(`  ${marker} ${result.message}`);
+        }
+    }
+    console.log(`\n${pc.bold('RTK')}`);
+    if (commandExists('rtk')) {
+        console.log(`  ${pc.green('OK')} rtk already installed`);
+    } else {
+        console.log(`  ${pc.yellow('WARN')} rtk is not installed; run: ${RTK_INSTALL_COMMAND}`);
+    }
+    console.log('\nRestart your AI client after installing plugins or changing MCP configuration.');
+}
+
+function commandExists(command) {
     const checker = process.platform === 'win32' ? 'where' : 'command';
     const args = process.platform === 'win32' ? [command] : ['-v', command];
     const result = spawnSync(checker, args, { encoding: 'utf8', shell: process.platform !== 'win32' });
     return result.status === 0;
 }
 
-function ensureGlobalNpmPackage(binaryName, packageName) {
-    if (commandExists(binaryName)) {
-        return { ok: true, message: `${binaryName} already installed` };
-    }
-    if (!commandExists('npm')) {
+function ensureGlobalNpmPackage(binaryName, packageName, install = false) {
+    if (commandExists(binaryName)) {
+        return { ok: true, message: `${binaryName} already installed` };
+    }
+    if (!install) {
+        return { ok: false, message: `${binaryName} is missing; run: npm install -g ${packageName}` };
+    }
+    if (!commandExists('npm')) {
         return { ok: false, message: `npm not found; run: npm install -g ${packageName}` };
     }
     const result = spawnSync('npm', ['install', '-g', packageName], {
@@ -1758,17 +1872,9 @@ function ensureGlobalNpmPackage(binaryName, packageName) {
     return { ok: true, message: `installed ${binaryName}` };
 }
 
-function ensureCodegraphCli() {
-    return ensureGlobalNpmPackage('codegraph', '@colbymchenry/codegraph');
-}
-
-function ensureContext7Cli() {
-    return ensureGlobalNpmPackage('context7-mcp', '@upstash/context7-mcp');
-}
-
-function ensurePlaywrightMcpCli() {
-    return ensureGlobalNpmPackage('playwright-mcp', '@playwright/mcp');
-}
+function ensureCodebaseMemoryCli(install = false) {
+    return ensureGlobalNpmPackage(CODEBASE_MEMORY_BINARY, CODEBASE_MEMORY_PACKAGE, install);
+}
 
 function readJsonFile(filePath) {
     if (!fs.existsSync(filePath)) return {};
@@ -1790,10 +1896,10 @@ function mergeMcpJson(filePath, withType = false) {
         return { ok: false, message: `${filePath} is not valid JSON; skipped` };
     }
     data.mcpServers = data.mcpServers || {};
-    const baseServers = {
-        codegraph: { command: 'codegraph', args: ['serve', '--mcp'] },
-        playwright: { command: 'playwright-mcp' },
-        context7: { command: 'context7-mcp' }
+    const baseServers = {
+        'codebase-memory-mcp': { command: CODEBASE_MEMORY_BINARY, args: [] },
+        playwright: { command: 'playwright-mcp' },
+        context7: { command: 'context7-mcp' }
     };
     if (data.permissions && Array.isArray(data.permissions.allow)) {
         const requiredPermissions = [
@@ -1827,13 +1933,12 @@ startup_timeout_sec = 20
 tool_timeout_sec = 120
 `);
     }
-    if (!/\[mcp_servers\.codegraph\]/.test(existing)) {
-        blocks.push(`[mcp_servers.codegraph]
-command = "codegraph"
-args = ["serve", "--mcp"]
-startup_timeout_sec = 20
-tool_timeout_sec = 120
-`);
+    if (!/\[mcp_servers\.codebase-memory-mcp\]/.test(existing)) {
+        blocks.push(`[mcp_servers.codebase-memory-mcp]
+command = "${CODEBASE_MEMORY_BINARY}"
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+`);
     }
     if (!/\[mcp_servers\.playwright\]/.test(existing)) {
         blocks.push(`[mcp_servers.playwright]
@@ -1846,7 +1951,7 @@ tool_timeout_sec = 120
     }
     const separator = existing && !existing.endsWith('\n') ? '\n\n' : existing ? '\n' : '';
     fs.writeFileSync(filePath, existing + separator + blocks.join('\n'), 'utf8');
-    return { ok: true, message: `configured context7, codegraph, playwright MCP in ${filePath}` };
+    return { ok: true, message: `configured codebase-memory-mcp, context7, playwright MCP in ${filePath}` };
 }
 
 const DOD_HOOK_MARKER = 'feature/refactor Definition-of-Done gate';
@@ -1921,11 +2026,12 @@ function mergeClaudeProjectHooks(filePath) {
     return { ok: true, message: `configured Definition-of-Done Stop hook in ${filePath}` };
 }
 
-function setupMcpServers() {
-    const results = [];
-    results.push(ensureCodegraphCli());
-    results.push(ensureContext7Cli());
-    results.push(ensurePlaywrightMcpCli());
+function setupMcpServers(options = {}) {
+    const install = options.install === true;
+    const results = [];
+    results.push(ensureCodebaseMemoryCli(install));
+    results.push(ensureGlobalNpmPackage('context7-mcp', '@upstash/context7-mcp', install));
+    results.push(ensureGlobalNpmPackage('playwright-mcp', '@playwright/mcp', install));
 
     const codexConfig = homePath('.codex', 'config.toml');
     if (codexConfig) results.push(appendMcpTomlIfMissing(codexConfig));
@@ -1962,12 +2068,22 @@ async function main() {
         return;
     }
 
-    if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
-        printHelp();
-        return;
-    }
-
-    if (command !== 'init') {
+    if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
+        printHelp();
+        return;
+    }
+
+    if (command === 'doctor') {
+        runDoctor();
+        return;
+    }
+
+    if (command === 'setup') {
+        await runSetup(rawArgs.slice(1));
+        return;
+    }
+
+    if (command !== 'init') {
         console.error(pc.red(`Unknown command: ${command}`));
         printHelp();
         process.exit(1);
@@ -2024,41 +2140,13 @@ async function main() {
     if (data.uses_docker) data.infrastructure.push('docker');
     if (data.cloud !== 'none') data.infrastructure.push(data.cloud);
 
-    const shouldSetupMcp = !skipMcpSetup;
+    const shouldSetupMcp = args.includes('--setup-mcp') && !skipMcpSetup;
 
     console.log(`\n${pc.bold(pc.cyan('Generating Files'))}`);
 
     // Shared entry files are written after the .agent folder is available.
 
-    // Copy .agent folder
-    const { copied, skipped } = copyAgentFolder();
-    if (copied > 0) {
-        console.log(`  ${pc.green('OK')} Copied ${pc.bold('.agent/')} (${copied} file${copied !== 1 ? 's' : ''} added${skipped > 0 ? `, ${skipped} skipped` : ''})`);
-    } else if (skipped > 0) {
-        console.log(`  ${pc.yellow('~')} ${pc.bold('.agent/')} already exists - ${skipped} file${skipped !== 1 ? 's' : ''} skipped (no overwrite)`);
-    }
-
-    const nativeSkills = copySelectedSkillFolders(data, assumeYes);
-    if (nativeSkills.copied > 0) {
-        console.log(`  ${pc.green('OK')} Copied native skills to ${pc.bold('~/.codex/skills/')} and ${pc.bold('.claude/skills/')} (${nativeSkills.skills.join(', ')})`);
-    } else if (nativeSkills.skipped > 0) {
-        console.log(`  ${pc.yellow('~')} Native skills already exist - ${nativeSkills.skipped} file${nativeSkills.skipped !== 1 ? 's' : ''} skipped`);
-    }
-
-    const codexPrompts = copyCodexPrompts();
-    if (codexPrompts.copied > 0) {
-        console.log(`  ${pc.green('OK')} Installed Codex custom prompts in ${pc.bold('~/.codex/prompts/')} (${codexPrompts.prompts.map(name => `/prompts:${name}`).join(', ')})`);
-    }
-
-    const legacyClientCommands = copyClientWorkflowCommands();
-    if (legacyClientCommands.claude > 0 || legacyClientCommands.cursor > 0) {
-        console.log(`  ${pc.dim('~')} Preserved legacy workflow aliases for Claude Code and Cursor (${legacyClientCommands.claude}/${legacyClientCommands.cursor})`);
-    }
-
-    const forgeCommands = copyForgeCommands();
-    if (forgeCommands.commands.length > 0) {
-        console.log(`  ${pc.green('OK')} Installed Forge commands (${forgeCommands.commands.join(', ')}) for Antigravity (${forgeCommands.antigravity}), Claude Code (${forgeCommands.claude}), Cursor (${forgeCommands.cursor}), and Codex skills (${forgeCommands.codex})`);
-    }
+    console.log(`  ${pc.green('OK')} Project context generation enabled; workflow skills remain client-managed by Superpowers`);
 
 
     const generatedFiles = [
@@ -2080,11 +2168,7 @@ async function main() {
         else console.log(`  ${pc.yellow('~')} Skipped ${pc.bold(relativePath)}`);
     }
 
-    console.log(`\n${pc.bold(pc.cyan('Configuring Claude Code hooks'))}`);
-    const hookResult = mergeClaudeProjectHooks(path.join(targetDir, '.claude', 'settings.json'));
-    console.log(`  ${hookResult.ok ? pc.green('OK') : pc.yellow('~')} ${hookResult.message}`);
-
-    if (shouldSetupMcp) {
+    if (shouldSetupMcp) {
         console.log(`\n${pc.bold(pc.cyan('Configuring MCP'))}`);
         for (const result of setupMcpServers()) {
             const marker = result.ok ? pc.green('OK') : pc.yellow('~');
@@ -2103,40 +2187,28 @@ async function main() {
     - ${pc.bold('GEMINI.md')} Antigravity entry
     - ${pc.bold('.cursorrules')} Cursor entry
     - ${pc.bold('.agent/docs/')} scan-based project rules, including ${pc.bold('getting-started.md')} (standard flow vs fast path)
-    - ${pc.bold('.agent/')} skills, workflows, agents, and rules
-    - ${pc.bold('~/.codex/skills/')} selected Codex skills installed globally (visible in $ menu)
-    - ${pc.bold('~/.codex/skills/forge-*/')} Forge Codex skills (visible as $forge-task, $forge-fast, and related skills)
-    - ${pc.bold('~/.codex/prompts/')} legacy Codex prompts retained for compatibility
-    - ${pc.bold('.claude/skills/')} selected Claude Code native skills
-    - ${pc.bold('.claude/commands/forge-*.md')} Forge Claude Code commands (visible as /forge-task and related commands)
-    - ${pc.bold('.cursor/commands/forge-*.md')} Forge Cursor commands (visible as /forge-task and related commands)
-    - ${pc.bold('.agent/workflows/forge-*.md')} Forge Antigravity workflows (visible as /forge-task and related commands)
-    - ${pc.bold('.claude/settings.json')} Definition-of-Done Stop hook (Claude Code only — blocks reporting a feature/refactor "done" without a plan + review pass)
+    - ${pc.bold('.agent/docs/')} project context and local operating notes
 
   ${pc.bold('MCP/tooling setup:')}
-    - Codegraph CLI checked or installed; MCP configured for Codex, Gemini/Antigravity, and Claude Code
-    - Context7 MCP configured for Codex and Gemini/Antigravity
-    - Playwright MCP configured for Codex, Gemini/Antigravity, and Claude Code
-    - Browser install hint: ${pc.bold(resolveToolingSetup(data).playwrightCommand)}
-    - Codegraph index hint: run ${pc.bold('codegraph init -i')} when a project index is missing, then keep ${pc.bold('.codegraph/')} uncommitted
+    - 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 optional RTK
 
   ${pc.bold('Next steps:')}
-    1. Read ${pc.bold('.agent/docs/getting-started.md')} for the standard flow vs fast path
-    2. Copy the prompt below into your AI editor and describe what the project does
-    3. Commit ${pc.bold('AGENTS.md')}, ${pc.bold('CLAUDE.md')}, ${pc.bold('GEMINI.md')}, ${pc.bold('.cursorrules')}, ${pc.bold('.agent/')}, and ${pc.bold('.claude/settings.json')}
-    4. Open the project in Codex, Antigravity, Claude Code, or Cursor
+    1. Read ${pc.bold('.agent/docs/getting-started.md')} for the standard Superpowers flow
+    2. Run ${pc.bold('thachvd-kit setup')} for optional integrations
+    3. Run ${pc.bold('thachvd-kit doctor')} to verify the machine
+    4. Commit ${pc.bold('AGENTS.md')}, ${pc.bold('CLAUDE.md')}, ${pc.bold('GEMINI.md')}, ${pc.bold('.cursorrules')}, and ${pc.bold('.agent/docs/')}
 
   ${pc.bold('Copy this prompt into your AI editor:')}
 ${pc.dim('---')}
-Read CLAUDE.md (if using Claude Code), AGENTS.md, and all files under .agent/docs/.
-Ask me what this project does and any important conventions I want preserved.
-Then scan this repository.
-Update CLAUDE.md, AGENTS.md, .cursorrules and .agent/docs/project.md, .agent/docs/architecture.md, .agent/docs/conventions.md, .agent/docs/workflow.md, and .agent/docs/tooling.md with factual project-specific rules.
-Do not implement product code.
-Remove TODO: refine only when backed by evidence from the codebase.
-${pc.dim('---')}
-`);
-}
+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.
+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.
+${pc.dim('---')}
+`);
+}
 
 main().catch(err => {
     console.error(pc.red('\nError during init:'), err);