thachvd-kit 1.0.11 → 1.0.13

package/bin/cli.js

@@ -942,14 +942,16 @@ ${autoSkillsList}
 - **In Progress:** Initial setup
 - **Next:** —
 
----
-
-## Known Issues / Tasks
-
-<!-- Add known issues or pending tasks -->
-`;
-}
-
+
+---
+
+## Known Issues / Tasks
+
+<!-- Add known issues or pending tasks -->
+`;
+}
+
+
 function generateClaudeMd(data) {
     return `# CLAUDE.md — ${data.project_name}
 # Generated by thachvd-kit. See PROJECT_CONTEXT.md for full stack info.
@@ -958,132 +960,260 @@ function generateClaudeMd(data) {
 ## Project
 ${data.description}
 Stack: ${data.primary_language} | ${(data.frameworks || []).join(', ')}
-
+
 ## Rules
 - Read PROJECT_CONTEXT.md first for stack details and agent routing.
 - If PROJECT_CONTEXT.md is missing or stale, create/update it before major work.
 - Follow skills in .agent/skills/ (or .claude/skills/).
 - Tests are mandatory. Verify before claiming done.
 - Max ${data.max_file_lines || '300'} lines per file.
-
-## Key Skills
-- Plan: \`plan-writing\` → \`executing-plans\`
-- Review: \`requesting-code-review\` / \`receiving-code-review\`
-- Quality: \`clean-code\`, \`verification-before-completion\`
-- Workflow: \`subagent-driven-development\`, \`finishing-a-development-branch\`
-
-## Commands
-- \`/plan\` — Create implementation plan
-- \`/debug\` — Systematic debugging
-- \`/test\` — Run test suite
-- \`/deploy\` — Deploy checklist
+
+## Key Skills
+- Plan: \`plan-writing\` → \`executing-plans\`
+- Review: \`requesting-code-review\` / \`receiving-code-review\`
+- Quality: \`clean-code\`, \`verification-before-completion\`
+- Workflow: \`subagent-driven-development\`, \`finishing-a-development-branch\`
+
+## Commands
+- \`/plan\` — Create implementation plan
+- \`/debug\` — Systematic debugging
+- \`/test\` — Run test suite
+- \`/deploy\` — Deploy checklist
 
 See PROJECT_CONTEXT.md for full agent routing table.
 `;
 }
 
 function generateAgentsMd(data) {
-    return `# AGENTS.md — ${data.project_name}
-# Generated by thachvd-kit. See PROJECT_CONTEXT.md for full stack info.
-# Platform: Codex / AGENTS-compatible editors
+    const frameworks = (data.frameworks || []);
+    const primaryLang = data.primary_language || 'javascript';
+    const pkgManager = data.package_manager || 'npm';
+    const testFramework = data.test_framework || 'auto-detect';
+    const database = data.database || 'none';
+    const cloud = data.cloud || 'none';
+    const infrastructure = (data.infrastructure || []);
+    const appRoot = data.app_root || '.';
+    const maxFileLines = data.max_file_lines || '300';
+
+    // Build dev commands section based on detected package manager and framework
+    const isNode = ['javascript', 'typescript'].includes(primaryLang);
+    const isPython = primaryLang === 'python';
+    const isGo = primaryLang === 'go';
+    const isRust = primaryLang === 'rust';
+    const isPhp = primaryLang === 'php';
+
+    let installCmd = 'npm install';
+    let devCmd = 'npm run dev';
+    let buildCmd = 'npm run build';
+    let testCmd = 'npm test';
+    let lintCmd = 'npm run lint';
+
+    if (pkgManager === 'pnpm') { installCmd = 'pnpm install'; devCmd = 'pnpm dev'; buildCmd = 'pnpm build'; testCmd = 'pnpm test'; lintCmd = 'pnpm lint'; }
+    else if (pkgManager === 'yarn') { installCmd = 'yarn'; devCmd = 'yarn dev'; buildCmd = 'yarn build'; testCmd = 'yarn test'; lintCmd = 'yarn lint'; }
+    else if (pkgManager === 'bun') { installCmd = 'bun install'; devCmd = 'bun dev'; buildCmd = 'bun run build'; testCmd = 'bun test'; lintCmd = 'bun run lint'; }
+    else if (isPython) { installCmd = 'pip install -r requirements.txt'; devCmd = 'python manage.py runserver'; buildCmd = '# no build step'; testCmd = 'pytest'; lintCmd = 'ruff check .'; }
+    else if (isGo) { installCmd = 'go mod download'; devCmd = 'go run .'; buildCmd = 'go build ./...'; testCmd = 'go test ./...'; lintCmd = 'golangci-lint run'; }
+    else if (isRust) { installCmd = 'cargo build'; devCmd = 'cargo run'; buildCmd = 'cargo build --release'; testCmd = 'cargo test'; lintCmd = 'cargo clippy'; }
+    else if (isPhp) { installCmd = 'composer install'; devCmd = 'php artisan serve'; buildCmd = '# no build step'; testCmd = testFramework === 'pest' ? './vendor/bin/pest' : './vendor/bin/phpunit'; lintCmd = 'php artisan pint'; }
+
+    if (testFramework === 'vitest') testCmd = `${pkgManager === 'pnpm' ? 'pnpm' : pkgManager === 'yarn' ? 'yarn' : pkgManager === 'bun' ? 'bun run' : 'npx'} vitest`;
+    else if (testFramework === 'jest') testCmd = `${pkgManager === 'pnpm' ? 'pnpm' : pkgManager === 'yarn' ? 'yarn' : 'npx'} jest`;
+
+    // Build stack overview section
+    const stackLines = [
+        `- **Language:** ${primaryLang}`,
+        frameworks.length > 0 ? `- **Frameworks:** ${frameworks.join(', ')}` : null,
+        database !== 'none' ? `- **Database:** ${database}` : null,
+        pkgManager !== 'auto-detect' ? `- **Package Manager:** ${pkgManager}` : null,
+        testFramework !== 'auto-detect' ? `- **Test Framework:** ${testFramework}` : null,
+        cloud !== 'none' ? `- **Cloud:** ${cloud}` : null,
+        infrastructure.length > 0 ? `- **Infrastructure:** ${infrastructure.join(', ')}` : null,
+    ].filter(Boolean).join('\n');
+
+    // Build architecture notes hint
+    const archNotes = data.architecture_notes && !data.architecture_notes.includes('<!-- Add')
+        ? `\n${data.architecture_notes}`
+        : '';
+
+    // Agent routing table
+    const agentTable = resolveAgentTable(data);
+    const agentRows = agentTable.map(([task, agent, skills]) => `| ${task} | \`${agent}\` | ${skills} |`).join('\n');
+
+    // Auto-resolved skills
+    const autoSkills = resolveSkills(data);
+    const skillsList = autoSkills.map(s => `- ${s}`).join('\n');
+
+    return `# ${data.project_name}
 
-## Project
 ${data.description}
-Stack: ${data.primary_language} | ${(data.frameworks || []).join(', ') || 'no framework'}
-
-## Mandatory First Action
-- Read \`PROJECT_CONTEXT.md\` before making plans or code changes.
-- If \`PROJECT_CONTEXT.md\` is missing or stale, create/update it before major work.
-- If \`context.needs_ai_refinement: true\`, refine \`PROJECT_CONTEXT.md\` first, then set:
-  - \`context.status: refined\`
-  - \`context.needs_ai_refinement: false\`
-  - \`context.last_refined_at: <today>\`
-
-## Working Rules
-- Use \`.agent/agents\`, \`.agent/skills\`, \`.agent/rules\`, and \`.agent/workflows\` as the local project kit.
-- Match the task against the Agent Routing table in \`PROJECT_CONTEXT.md\`.
-- Load relevant skills before editing code.
-- Tests are mandatory. Verify before claiming done.
-- Keep files under ${data.max_file_lines || '300'} lines when practical, then split into modules.
-- Update dependent files together when a change crosses boundaries.
-
-## Preferred Workflow
-- Plan work from \`PROJECT_CONTEXT.md\` first.
-- For feature work, use: \`plan-writing\` -> \`executing-plans\` -> \`verification-before-completion\`.
-- For reviews, use: \`requesting-code-review\` / \`receiving-code-review\`.
-- For debugging, use: \`systematic-debugging\`.
-
-## Key Paths
-- Project context: \`PROJECT_CONTEXT.md\`
-- Agent kit: \`.agent/\`
-- Skills: \`.agent/skills/\`
-- Workflows: \`.agent/workflows/\`
-
-See \`PROJECT_CONTEXT.md\` for stack details, routing, and auto-resolved skills.
+
+## Project Overview
+
+${stackLines}
+
+---
+
+## Core Architecture
+
+<!-- AI: Scan the project and replace this section with actual directory structure and key module descriptions -->
+${appRoot !== '.' ? `- **App Root:** \`${appRoot}\`` : ''}
+
+---
+
+## Development Workflow
+
+### Prerequisites
+- ${primaryLang.charAt(0).toUpperCase() + primaryLang.slice(1)} toolchain installed
+${pkgManager !== 'auto-detect' ? `- \`${pkgManager}\` (Package Manager)` : ''}
+
+### Key Commands
+- **Install Dependencies:** \`${installCmd}\`
+- **Development Server:** \`${devCmd}\`
+- **Build for Production:** \`${buildCmd}\`
+- **Run Tests:** \`${testCmd}\`
+- **Linting:** \`${lintCmd}\`
+
+---
+
+## Coding Conventions
+
+<!-- AI: Scan the project and replace this section with actual conventions (API patterns, state management, styling, naming, routing) -->
+
+---
+
+## Performance & Optimization
+
+<!-- AI: Scan vite.config / webpack / build config and replace with actual optimizations used -->
+
+---
+
+## Coding Rules
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+### 1. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+### 2. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+### 3. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+\`\`\`
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+\`\`\`
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+### 4. Universal Standards
+
+- Respond in user's language; code/comments in English.
+- \`clean-code\` applies to all code, all languages.
+- Tests are mandatory.
+- Verify with evidence before claiming done.
+- Identify dependent files before modifying any.
+- Keep files under ${maxFileLines} lines; split into modules if exceeded.
 `;
 }
 
-function generateAiContextRefinementPrompt(data) {
+function generateAgentsMdRefinementPrompt(data) {
     const evidence = (data.scan_evidence || []).length > 0
         ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
         : '- No scan evidence was captured during init.';
 
-    return `# AI Context Refinement
-
-Use this prompt in your AI editor after \`thachvd-kit init\`.
-
-## Goal
+    return `# AGENTS.md Refinement Prompt
 
-Refine \`PROJECT_CONTEXT.md\` so it reflects the real project more accurately than the baseline init scan.
+Run this in your AI editor right after \`thachvd-kit init --scan\`.
+The goal is to replace the placeholder sections in \`AGENTS.md\` with real project knowledge.
 
-## Current Baseline
+## Baseline Detected
 
-- Project: ${data.project_name}
-- Type: ${data.project_type}
-- Stack: ${data.primary_language} | ${(data.frameworks || []).join(', ') || 'no framework'}
-- Database: ${data.database || 'none'}
-- Infra: ${(data.infrastructure || []).join(', ') || 'none'}
+- **Project:** ${data.project_name}
+- **Stack:** ${data.primary_language} | ${(data.frameworks || []).join(', ') || 'no framework'}
+- **Database:** ${data.database || 'none'}
+- **Package Manager:** ${data.package_manager || 'auto-detect'}
 
 ## Scan Evidence
 
 ${evidence}
 
-## Instructions For The AI Agent
-
-1. Read \`PROJECT_CONTEXT.md\` first.
-2. Inspect the project selectively to improve factual accuracy.
-3. Prioritize:
-   - real database/config detection
-   - domain/capability inference
-   - architecture notes
-   - more accurate auto-resolved skills
-   - important project-specific constraints
-4. Update \`PROJECT_CONTEXT.md\` directly.
-5. Distinguish facts from inferences when uncertain.
-6. Do not implement product code in this pass. Only refine project context.
-
-## Suggested Files To Inspect
-
-- Root manifests: \`package.json\`, \`composer.json\`, \`Cargo.toml\`, \`pyproject.toml\`
-- Infrastructure/config: Docker, CI, env, framework config files
-- Database config and models
-- Main app entry points, routing, controllers/services
-- README and existing documentation
-
-## Desired Improvements
-
-- Correct the \`database\` field if config files reveal the real DB.
-- Add architecture notes that explain the actual structure.
-- Infer domain capabilities such as scraping, browser automation, external API integrations, queues, workers, etc.
-- Expand auto-resolved skills when there is clear evidence in the codebase.
-- Add caveats or assumptions if parts of the stack are still uncertain.
-
-## Completion Standard
-
-When done, summarize:
-- what was corrected
-- what is still inferred
-- which files provided the strongest evidence
+## Your Task
+
+Update **only** the placeholder sections in \`AGENTS.md\` (marked with \`<!-- AI: ... --\`>):
+
+### 1. Core Architecture
+Scan the \`src/\` (or equivalent) directory. For each major folder, write one bullet:
+\`- **\`src/folder/\`**: What it contains and its role\`
+Keep it concise — one line per folder.
+
+### 2. Coding Conventions
+Inspect actual code patterns and write conventions grouped by topic:
+- API integration patterns (how HTTP calls are made)
+- State management patterns
+- Styling conventions
+- Component/file naming rules
+- Routing and auth patterns
+
+### 3. Performance & Optimization
+Check \`vite.config.js\`, \`webpack.config.js\`, \`package.json\` scripts, or build configs. List actual optimizations:
+- Code splitting, lazy loading, chunking
+- Compression, caching strategies
+- PWA, image optimization, etc.
+
+## Rules
+
+- Replace placeholders with real content. Remove the \`<!-- AI: ... -->\` comments.
+- Do NOT change \`## Project Overview\`, \`## Development Workflow\`, or \`## Coding Rules\` sections.
+- Do NOT implement any product code.
+- If a section is not applicable, write \`N/A\` and remove the placeholder.
+
+## Files To Inspect
+
+- \`src/\` or \`app/\` directory structure
+- Build config: \`vite.config.*\`, \`webpack.config.*\`, \`next.config.*\`
+- Entry points: \`main.js\`, \`app.js\`, \`index.ts\`
+- Router definition
+- Example API service files
+- Example store/state files
+- README if present
 `;
 }
 
@@ -1115,7 +1245,7 @@ async function main() {
 
     console.log(pc.bold(pc.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')));
     console.log('  ' + pc.bold('thachvd-kit') + ' — Project Init Wizard');
-    console.log(`  Generates .agent/ folder & smart PROJECT_CONTEXT.md${useScan ? ' (scan-assisted)' : ''}`);
+    console.log(`  Generates AGENTS.md${useScan ? ' (scan-assisted)' : ''}`);
     console.log(pc.bold(pc.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')) + '\n');
 
     let projectSetup = 'new';
@@ -1265,91 +1395,46 @@ async function main() {
     data.scan_evidence = scanned?.scan_evidence || [];
     data.app_root = scanned?.app_root || '.';
 
-    if (!assumeYes) {
-        const aiRefineAnswer = await askQuestions({
-            type: 'confirm',
-            name: 'ai_refine',
-            message: 'Should the agent refine PROJECT_CONTEXT.md on first session start?',
-            initial: useScan
-        });
-        requestAiRefinement = Boolean(aiRefineAnswer.ai_refine);
-    }
-
-    data.context_status = 'baseline';
-    data.needs_ai_refinement = requestAiRefinement;
-    data.last_refined_at = 'not-yet-refined';
     data.infrastructure = [];
     if (data.uses_docker) data.infrastructure.push('docker');
     if (data.cloud !== 'none') data.infrastructure.push(data.cloud);
-
-    // --- Copy .agent folder ---
-    const agentDir = path.join(targetDir, '.agent');
-    console.log(`\n${pc.bold(pc.cyan('━━ Generating Files ━━'))}`);
-
-    if (!fs.existsSync(agentDir)) {
-        fs.mkdirSync(agentDir, { recursive: true });
-    }
-
-    // Copy folders: agents, rules, skills, workflows
-    const foldersToCopy = ['agents', 'rules', 'skills', 'workflows'];
-    for (const folder of foldersToCopy) {
-        const srcPath = path.join(sourceDir, folder);
-        const destPath = path.join(agentDir, folder);
-        if (fs.existsSync(srcPath)) {
-            // Use basic recursive copy since Node 16.7 fs.cpSync handles this
-            fs.cpSync(srcPath, destPath, { recursive: true, force: true });
-            console.log(`  ${pc.green('✓')} Copied ${pc.bold(`.agent/${folder}`)}`);
-        } else {
-            console.log(`  ${pc.yellow('-')} Source ${folder} not found.`);
-        }
-    }
-
-    // Write contexts
-    const projectContextPath = path.join(targetDir, 'PROJECT_CONTEXT.md');
-    fs.writeFileSync(projectContextPath, generateProjectContext(data), 'utf8');
-    console.log(`  ${pc.green('✓')} Generated ${pc.bold('PROJECT_CONTEXT.md')}`);
 
-    const claudeMdPath = path.join(targetDir, 'CLAUDE.md');
-    fs.writeFileSync(claudeMdPath, generateClaudeMd(data), 'utf8');
-    console.log(`  ${pc.green('✓')} Generated ${pc.bold('CLAUDE.md')}`);
+    console.log(`\n${pc.bold(pc.cyan('━━ Generating Files ━━'))}`);
 
+    // Write AGENTS.md — the only output file
     const agentsMdPath = path.join(targetDir, 'AGENTS.md');
+    const agentsMdExists = fs.existsSync(agentsMdPath);
+    if (agentsMdExists && !assumeYes) {
+        const res = await askQuestions({
+            type: 'confirm',
+            name: 'overwrite',
+            message: 'AGENTS.md already exists. Overwrite?',
+            initial: false
+        });
+        if (!res.overwrite) {
+            console.log(pc.yellow('\nAborted. Existing AGENTS.md unchanged.'));
+            process.exit(0);
+        }
+    }
+
     fs.writeFileSync(agentsMdPath, generateAgentsMd(data), 'utf8');
     console.log(`  ${pc.green('✓')} Generated ${pc.bold('AGENTS.md')}`);
 
-    let aiRefinementPath = null;
-    if (requestAiRefinement) {
-        aiRefinementPath = path.join(targetDir, 'AI_CONTEXT_REFINEMENT.md');
-        fs.writeFileSync(aiRefinementPath, generateAiContextRefinementPrompt(data), 'utf8');
-        console.log(`  ${pc.green('✓')} Generated ${pc.bold('AI_CONTEXT_REFINEMENT.md')}`);
-    }
+    console.log(`\n${pc.bold(pc.green('━━ Done! ━━'))}
 
-    // Summary
-    const autoSkills = resolveSkills(data);
-    console.log(`\n${pc.bold(pc.green('━━ Done! ━━'))}
-  
-  ${pc.bold('Project:')} ${data.project_name}
-  ${pc.bold('Stack:')}   ${data.primary_language} | ${(data.frameworks || []).join(', ') || 'no framework'}
-  ${pc.bold('Infra:')}   ${(data.infrastructure || []).join(', ') || 'none'}
-  
-  ${pc.bold('Auto-resolved skills:')}
-${autoSkills.map(s => '    · ' + s).join('\n')}
-
-  ${pc.bold('Generated files:')}
-    · ${pc.bold(projectContextPath)}
-    · ${pc.bold(claudeMdPath)}
-    · ${pc.bold(agentsMdPath)}
-${aiRefinementPath ? `    · ${pc.bold(aiRefinementPath)}` : ''}
+  ${pc.bold('Project:')} ${data.project_name}
+  ${pc.bold('Stack:')}   ${data.primary_language} | ${(data.frameworks || []).join(', ') || 'no framework'}
+
+  ${pc.bold('Generated:')} ${pc.bold(agentsMdPath)}
 
   ${pc.bold('Next steps:')}
-    1. Your kit is installed in ${pc.bold('./.agent')}
-    2. Review ${pc.bold('PROJECT_CONTEXT.md')} first and add architecture notes
-    3. ${aiRefinementPath ? `Open ${pc.bold('AI_CONTEXT_REFINEMENT.md')} in your AI editor to refine project context` : `Instruct the agent to read/update ${pc.bold('PROJECT_CONTEXT.md')} before major tasks`}
-    4. Open project in Claude Code or Codex — the agent will read context on start
+    1. ${useScan ? `Open ${pc.bold('AGENTS.md')} — paste its content into your AI editor to fill in the placeholders` : `Edit ${pc.bold('AGENTS.md')} and fill in Core Architecture, Coding Conventions, Performance sections`}
+    2. Commit ${pc.bold('AGENTS.md')} to the repo
+    3. Open project in Claude Code / Codex / Antigravity — agent reads AGENTS.md automatically
 `);
 }
-
-main().catch(err => {
-    console.error(pc.red('\nError during init:'), err);
-    process.exit(1);
-});
+
+main().catch(err => {
+    console.error(pc.red('\nError during init:'), err);
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "thachvd-kit",
-    "version": "1.0.11",
+    "version": "1.0.13",
     "description": "Project context bootstrap kit for Antigravity, Claude Code, and Codex",
     "bin": {
         "thachvd-kit": "./bin/cli.js"