thachvd-kit 1.0.30 → 1.0.31

package/README.md

@@ -28,6 +28,7 @@ thachvd-kit doctor
 - `.agent/docs/workflow.md`: the project workflow contract.
 - `.agent/docs/tooling.md`: Superpowers, MCP, RTK, and Playwright setup.
 - `.agent/docs/getting-started.md`: member onboarding guide.
+- `.agent/docs/index-project-prompt.md`: durable prompt for the first project scan.
 
 The kit does not generate `.agent/skills`, `.agent/workflows`, `.agent/agents`, Forge commands, Claude hooks, or client-specific skill copies.
 
@@ -65,13 +66,13 @@ The index is local state. Keep it out of git unless the team explicitly chooses
 
 ### RTK
 
-RTK is optional command-output compression, not a workflow engine:
+RTK is the recommended command-output layer, not a workflow engine. Prefer it by default for verbose shell commands:
 
 ```bash
 cargo install --git https://github.com/rtk-ai/rtk --branch master rtk
 ```
 
-Use it for verbose git, test, build, package, and container commands when available.
+Examples: `rtk git status`, `rtk npm test`, `rtk git log`. If it is not installed, run the underlying command directly.
 
 ## CLI
 
@@ -79,11 +80,14 @@ Use it for verbose git, test, build, package, and container commands when availa
 thachvd-kit init [--yes]
 thachvd-kit setup [--no-setup-mcp]
 thachvd-kit doctor
+thachvd-kit prompt
 thachvd-kit --help
 ```
 
 `setup` configures MCP entries for detected clients and prints official Superpowers installation guidance. It may install npm-based MCP packages when they are missing. `doctor` is read-only and reports missing integrations without changing the machine.
 
+The project-indexing prompt is saved by `init`, so installing Superpowers or RTK afterward cannot make it disappear. Run `thachvd-kit prompt` whenever you need to print it again.
+
 ## Development
 
 ```bash

package/bin/cli.js

@@ -127,13 +127,15 @@ ${pc.bold('Usage:')}
   thachvd-kit init [--yes]
   thachvd-kit setup [--yes]
   thachvd-kit doctor
+  thachvd-kit prompt
   thachvd-kit --version
   thachvd-kit --help
 
 ${pc.bold('Commands:')}
   init      Generate project context files and documentation
-  setup     Install/configure optional MCP and local tooling
+  setup     Install/configure MCP and recommended local tooling
   doctor    Check project context and local integrations
+  prompt    Print the saved project-indexing prompt again
 
 ${pc.bold('Options:')}
   --yes     Overwrite generated files or accept setup defaults
@@ -146,7 +148,7 @@ ${pc.bold('What gets generated:')}
   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
+  .agent/docs/ Project context, architecture, workflow, tooling, and durable onboarding prompt
 
 ${pc.bold('Workflow guide:')}
   Every task               Superpowers     Use the matching native Superpowers skill
@@ -164,7 +166,7 @@ ${pc.bold('Tip:')}
 `);
 }
 
-function formatScanPreviewLines(scanned) {
+function formatScanPreviewLines(scanned) {
     return [
         ['App root', scanned.app_root || '.'],
         ['Project type', scanned.project_type || 'unknown'],
@@ -917,6 +919,7 @@ If Superpowers is unavailable, follow the plain-language flow in \`.agent/docs/w
 - Prefer the existing project style over new abstractions.
 - Keep changes surgical and remove only dead code introduced by your change.
 - **MCP First**: Prioritize \`codebase-memory-mcp\` for symbols, call paths, architecture, and impact; use \`context7\` for API/docs queries and \`playwright\` for browser/UI verification. Fall back to normal file search when an integration is unavailable.
+- Prefer \`rtk\` by default for verbose shell commands such as \`rtk git status\`, \`rtk npm test\`, and \`rtk git log\`. Run the underlying command directly only when RTK is unavailable or incompatible.
 - Tests or equivalent verification are mandatory before claiming done.
 - Keep files under ${data.max_file_lines || '300'} lines unless the project already has a different standard in \`.agent/docs/conventions.md\`.
 
@@ -925,10 +928,31 @@ If Superpowers is unavailable, follow the plain-language flow in \`.agent/docs/w
 - 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
+- RTK: recommended local CLI for compact command output
 - Antigravity and Cursor entry rules: \`GEMINI.md\` and \`.cursorrules\`
 `;
 }
+
+function generateIndexProjectPrompt() {
+    return `# Project Indexing Prompt
+
+Read CLAUDE.md (if using Claude Code), AGENTS.md, and all files under .agent/docs/.
+Use Superpowers for the workflow and use codebase-memory MCP for structural code discovery when available.
+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.
+`;
+}
+
+function printProjectPrompt() {
+    const promptPath = path.join(targetDir, '.agent', 'docs', 'index-project-prompt.md');
+    if (!fs.existsSync(promptPath)) {
+        console.error(pc.yellow('No saved project prompt found. Run thachvd-kit init first.'));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(fs.readFileSync(promptPath, 'utf8'));
+}
 
 function generateSharedClaudeMd() {
     return `@AGENTS.md
@@ -1055,7 +1079,7 @@ Use these integrations when available. Run thachvd-kit doctor to check the curre
 | \`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 |
-| \`rtk\` | Reduce noisy output from git, tests, builds, and package commands |
+| \`rtk\` | Recommended proxy for noisy git, tests, builds, and package commands |
 
 > Check \`.agent/docs/tooling.md\` for setup details and additional MCP servers.
 
@@ -1241,8 +1265,8 @@ 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.
+2. Open or print \`.agent/docs/index-project-prompt.md\` with \`thachvd-kit prompt\`.
+3. Install Superpowers and RTK, then run \`thachvd-kit setup\`.
 4. Run \`thachvd-kit doctor\` and restart the AI client.
 
 ## Standard Flow
@@ -1323,7 +1347,7 @@ The plan is a gate, not a suggestion. Do not start product-code implementation b
 Use \`/forge-debug <symptom>\`, not the feature flow, when something is failing or the root cause is unknown:
 
 1. Capture the exact symptom, environment, reproduction, and expected result.
-2. Inspect the relevant code path with MCP/codegraph when available.
+2. Inspect the relevant code path with codebase-memory MCP when available.
 3. Form and test a small number of hypotheses; do not patch by guesswork.
 4. Add or update a regression test that fails before the fix when practical.
 5. Make the smallest root-cause fix.
@@ -1411,10 +1435,11 @@ Use \`codebase-memory-mcp\` for symbol search, call paths, architecture, and imp
 
 ## RTK
 
-RTK is optional command-output compression, not a workflow engine.
+RTK is the recommended command-output layer, not a workflow engine. Prefer it by default for verbose shell commands.
 
 - 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.
+- Examples: \`rtk git status\`, \`rtk npm test\`, \`rtk git log\`.
+- If it is unavailable, run the underlying command directly.
 
 ## Playwright
 
@@ -1460,24 +1485,23 @@ startup_timeout_sec = 20
 tool_timeout_sec = 120
 \`\`\`
 
-## Codegraph
+## Codebase Memory MCP
 
-Use codegraph for codebase exploration when the environment exposes it. The index is local state and should not be committed.
+Use codebase-memory-mcp for codebase exploration. The index is local state and should not be committed unless the team explicitly chooses a shared snapshot.
 
-- Check for an index: look for \`.codegraph/\`
-- Check CLI availability: \`codegraph --help\`
-- Install CLI if needed: \`npm install -g @colbymchenry/codegraph\`
-- Codex MCP CLI setup: \`codex mcp add codegraph -- codegraph serve --mcp\`
+- Check for an index: use the codebase-memory CLI status/index commands.
+- Check CLI availability: \`codebase-memory-mcp --help\`
+- Install CLI if needed: \`npm install -g codebase-memory-mcp\`
+- Index the repository: \`codebase-memory-mcp cli index_repository --repo-path .\`
 - Auto setup: \`thachvd-kit\`
-- If your Codex environment provides the codegraph CLI, run its project indexing step from the repository root.
-- Keep \`.codegraph/\` ignored in git.
+- If your Codex environment provides the codebase-memory CLI, run its indexing step from the repository root.
+- Keep local codebase-memory state ignored in git.
 
 Codex \`config.toml\` example:
 
 \`\`\`toml
-[mcp_servers.codegraph]
-command = "codegraph"
-args = ["serve", "--mcp"]
+[mcp_servers.codebase-memory-mcp]
+command = "codebase-memory-mcp"
 startup_timeout_sec = 20
 tool_timeout_sec = 120
 \`\`\`
@@ -1489,9 +1513,8 @@ Gemini CLI / Antigravity \`mcp_config.json\` example:
 \`\`\`json
 {
   "mcpServers": {
-    "codegraph": {
-      "command": "codegraph",
-      "args": ["serve", "--mcp"]
+    "codebase-memory-mcp": {
+      "command": "codebase-memory-mcp"
     },
     "context7": {
       "command": "context7-mcp"
@@ -1518,10 +1541,9 @@ Claude Code user config example:
 \`\`\`json
 {
   "mcpServers": {
-    "codegraph": {
-      "type": "stdio",
-      "command": "codegraph",
-      "args": ["serve", "--mcp"]
+    "codebase-memory-mcp": {
+      "type": "stdio",
+      "command": "codebase-memory-mcp"
     },
     "context7": {
       "type": "stdio",
@@ -1810,19 +1832,19 @@ function runDoctor() {
 
     const tools = [
         [CODEBASE_MEMORY_BINARY, `npm install -g ${CODEBASE_MEMORY_PACKAGE}`],
-        ['rtk', RTK_INSTALL_COMMAND],
+        ['rtk', `recommended: ${RTK_INSTALL_COMMAND}`],
         ['agy', 'install Antigravity before running its Superpowers plugin command'],
         ['claude', 'install Claude Code before installing its Superpowers plugin'],
         ['codex', 'install Codex before using its Superpowers plugin']
     ];
-    console.log(`\n${pc.bold('Local integrations')}`);
+    console.log(`\n${pc.bold('Local integrations (RTK recommended)')}`);
     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.');
+    console.log('  Run thachvd-kit prompt to print the saved project-indexing prompt.');
 }
 
 async function runSetup(args) {
@@ -1836,13 +1858,14 @@ async function runSetup(args) {
             console.log(`  ${marker} ${result.message}`);
         }
     }
-    console.log(`\n${pc.bold('RTK')}`);
+    console.log(`\n${pc.bold('RTK (recommended)')}`);
     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(`  ${pc.yellow('WARN')} recommended: rtk is not installed; run: ${RTK_INSTALL_COMMAND}`);
     }
     console.log('\nRestart your AI client after installing plugins or changing MCP configuration.');
+    console.log('Your onboarding prompt is saved at .agent/docs/index-project-prompt.md. Run thachvd-kit prompt to print it again.');
 }
 
 function commandExists(command) {
@@ -2078,6 +2101,11 @@ async function main() {
         return;
     }
 
+    if (command === 'prompt') {
+        printProjectPrompt();
+        return;
+    }
+
     if (command === 'setup') {
         await runSetup(rawArgs.slice(1));
         return;
@@ -2157,9 +2185,10 @@ async function main() {
         [path.join('.agent', 'docs', 'project.md'), generateProjectDoc(data)],
         [path.join('.agent', 'docs', 'architecture.md'), generateArchitectureDoc(data)],
         [path.join('.agent', 'docs', 'conventions.md'), generateConventionsDoc(data)],
-        [path.join('.agent', 'docs', 'workflow.md'), generateWorkflowDoc()],
+        [path.join('.agent', 'docs', 'workflow.md'), generateWorkflowDoc()],
         [path.join('.agent', 'docs', 'tooling.md'), generateToolingDoc(data)],
-        [path.join('.agent', 'docs', 'getting-started.md'), generateGettingStartedDoc()]
+        [path.join('.agent', 'docs', 'getting-started.md'), generateGettingStartedDoc()],
+        [path.join('.agent', 'docs', 'index-project-prompt.md'), generateIndexProjectPrompt()]
     ];
 
     for (const [relativePath, content] of generatedFiles) {
@@ -2186,26 +2215,22 @@ async function main() {
     - ${pc.bold('CLAUDE.md')} Claude Code entry that imports AGENTS.md
     - ${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/docs/')} project context and local operating notes
+    - ${pc.bold('.agent/docs/')} scan-based project rules and local operating notes
+    - ${pc.bold('.agent/docs/index-project-prompt.md')} durable onboarding prompt
 
   ${pc.bold('MCP/tooling setup:')}
     - Superpowers is the workflow backend; install it from the official client/plugin surface
-    - Run ${pc.bold('thachvd-kit setup')} to configure codebase-memory MCP and optional RTK
+    - Run ${pc.bold('thachvd-kit setup')} to configure codebase-memory MCP and recommended RTK
 
   ${pc.bold('Next steps:')}
-    1. Read ${pc.bold('.agent/docs/getting-started.md')} for the standard Superpowers flow
-    2. Run ${pc.bold('thachvd-kit setup')} for optional integrations
+    1. Run ${pc.bold('thachvd-kit prompt')} and paste the saved prompt into your AI editor
+    2. Install Superpowers and RTK, then run ${pc.bold('thachvd-kit setup')}
     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/')}
+    4. Re-run ${pc.bold('thachvd-kit prompt')} whenever you need the onboarding prompt again
 
-  ${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/.
-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.bold('Onboarding prompt saved to .agent/docs/index-project-prompt.md:')}
+${pc.dim('---')}
+${generateIndexProjectPrompt().trim()}
 ${pc.dim('---')}
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "thachvd-kit",
-    "version": "1.0.30",
+    "version": "1.0.31",
     "description": "Cross-agent project rules bootstrap kit for Codex, Antigravity, and Claude Code",
     "bin": {
         "thachvd-kit": "./bin/cli.js"