thachvd-kit 1.0.10 → 1.0.13

package/README.md

@@ -40,6 +40,7 @@ Generated files:
 - `.agent/workflows`
 - `PROJECT_CONTEXT.md`
 - `CLAUDE.md`
+- `AGENTS.md`
 - `AI_CONTEXT_REFINEMENT.md` when first-session AI refinement is enabled
 
 ## Scan Behavior
@@ -73,7 +74,7 @@ If you enable first-session AI refinement, the generated context is marked with:
 - `context.status: baseline`
 - `context.needs_ai_refinement: true`
 
-Then, when your agent opens the project, `GEMINI.md` / `CLAUDE.md` instruct it to:
+Then, when your agent opens the project, `GEMINI.md` / `CLAUDE.md` / `AGENTS.md` instruct it to:
 
 1. Read `PROJECT_CONTEXT.md`
 2. Refine the context once if `needs_ai_refinement` is `true`
@@ -107,5 +108,5 @@ Generic quality skills such as `clean-code` and `systematic-debugging` are alway
 
 ## Notes
 
-- `thachvd-kit` is compatible with Codex workflows through `PROJECT_CONTEXT.md` and `CLAUDE.md`; it does not directly control Codex sessions.
+- `thachvd-kit` generates both `CLAUDE.md` for Claude Code and `AGENTS.md` for Codex/AGENTS-compatible editors.
 - The npm package page updates only after a new `npm publish`, not just after pushing to GitHub.

package/bin/cli.js

@@ -942,107 +942,278 @@ ${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.
-# Cross-platform: Claude Code · Codex · OpenCode
-
-## Project
-${data.description}
-Stack: ${data.primary_language} | ${(data.frameworks || []).join(', ')}
-
+# Platform: Claude Code
+
+## 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 generateAiContextRefinementPrompt(data) {
+function generateAgentsMd(data) {
+    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}
+
+${data.description}
+
+## 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 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
+    return `# AGENTS.md Refinement Prompt
 
-Use this prompt in your AI editor after \`thachvd-kit init\`.
+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.
 
-## Goal
+## Baseline Detected
 
-Refine \`PROJECT_CONTEXT.md\` so it reflects the real project more accurately than the baseline init scan.
-
-## Current Baseline
-
-- 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
 `;
 }
 
@@ -1074,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';
@@ -1224,86 +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')}`);
-
-    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.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);
+        }
     }
 
-    // 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)}
-${aiRefinementPath ? `    · ${pc.bold(aiRefinementPath)}` : ''}
+    fs.writeFileSync(agentsMdPath, generateAgentsMd(data), 'utf8');
+    console.log(`  ${pc.green('✓')} Generated ${pc.bold('AGENTS.md')}`);
+
+    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('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 Antigravity or Claude Code — 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/kit/README.md

@@ -1,6 +1,6 @@
-# 🛡️ Antigravity Project Kit
-
-This toolkit helps you build high-quality, modular, and performance-optimized applications by leveraging the full power of AI Agents with a Context-First approach.
+# 🛡️ Cross-Platform Project Kit
+
+This toolkit helps you build high-quality, modular, and performance-optimized applications by leveraging AI agents with a context-first approach across Antigravity, Claude Code, and Codex-compatible editors.
 
 ---
 
@@ -11,10 +11,11 @@ This toolkit helps you build high-quality, modular, and performance-optimized ap
 - Update project metadata (e.g., `package.json`).
 - Rename and fill out `PROJECT_CONTEXT.template.md` as `PROJECT_CONTEXT.md` in the root directory.
 
-### 2. Working with AI Agents
-- Always use the templates provided in `kit/PROMPT_RECIPE.md`.
-- Ensure the Agent reads and updates `PROJECT_CONTEXT.md`.
-- Enforce file splitting rules (e.g., Max 250 lines) to maintain a clean codebase.
+### 2. Working with AI Agents
+- Always use the templates provided in `kit/PROMPT_RECIPE.md`.
+- Ensure the Agent reads and updates `PROJECT_CONTEXT.md`.
+- Use `CLAUDE.md` for Claude Code and `AGENTS.md` for Codex when generating project-specific entry files.
+- Enforce file splitting rules (e.g., Max 250 lines) to maintain a clean codebase.
 
 ### 3. Proposed Structure
 - `.agent/rules/GEMINI.md`: Core behavioral rules and protocols.
@@ -29,4 +30,4 @@ This toolkit helps you build high-quality, modular, and performance-optimized ap
 
 ---
 
-*Powered by Antigravity Framework.*
+*Powered by thachvd-kit.*

package/package.json

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

package/rules/GEMINI.md

@@ -21,7 +21,7 @@ trigger: always_on
 ```
 
 > All routing decisions below depend on PROJECT_CONTEXT.md.
-> Without it, ask user to run: `python scripts/init.py`
+> Without it, ask user to run: `thachvd-kit init`
 > Baseline context must be refined once when `context.needs_ai_refinement = true`.
 
 ---
@@ -203,7 +203,7 @@ scripts/    → scripts/init.py, checklist.py, verify_all.py
 | Platform | Rules File | Skills Dir | Workflows |
 |----------|-----------|-----------|-----------|
 | **Antigravity** | `rules/GEMINI.md` (this file) | `skills/` | `workflows/` |
-| **Claude Code** | `CLAUDE.md` at project root | `.claude/skills/` | `.claude/commands/` |
-| **Codex / OpenCode** | `CLAUDE.md` at project root | `.claude/skills/` | — |
-
-> Run `python scripts/init.py --platform all` to generate platform-specific config files automatically.
+| **Claude Code** | `CLAUDE.md` at project root | `.agent/skills/` | `.agent/workflows/` |
+| **Codex / OpenCode** | `AGENTS.md` at project root | `.agent/skills/` | `.agent/workflows/` |
+
+> Run `thachvd-kit init` to generate project context and platform entry files automatically.

package/scripts/init.py

@@ -3,10 +3,11 @@
 thachvd-kit — Project Init Wizard
 Generates PROJECT_CONTEXT.md and optional platform config files.
 
-Usage:
-    python scripts/init.py                    # Interactive wizard
-    python scripts/init.py --platform all    # Also generate CLAUDE.md
-    python scripts/init.py --platform claude  # Only CLAUDE.md
+Usage:
+    python scripts/init.py                    # Interactive wizard
+    python scripts/init.py --platform all    # Also generate CLAUDE.md + AGENTS.md
+    python scripts/init.py --platform claude  # Only CLAUDE.md
+    python scripts/init.py --platform codex   # Only AGENTS.md
 """
 
 import sys
@@ -695,14 +696,14 @@ Based on your stack, these skills will be loaded automatically:
 """
 
 def generate_claude_md(data):
-    """Generate CLAUDE.md for Claude Code / Codex compatibility."""
-    return f"""# CLAUDE.md — {data['project_name']}
-# Generated by thachvd-kit. See PROJECT_CONTEXT.md for full stack info.
-# Cross-platform: Claude Code · Codex · OpenCode
-
-## Project
-{data['description']}
-Stack: {data['primary_language']} | {', '.join(data.get('frameworks', []))}
+    """Generate CLAUDE.md for Claude Code."""
+    return f"""# CLAUDE.md — {data['project_name']}
+# Generated by thachvd-kit. See PROJECT_CONTEXT.md for full stack info.
+# Platform: Claude Code
+
+## Project
+{data['description']}
+Stack: {data['primary_language']} | {', '.join(data.get('frameworks', []))}
 
 ## Rules
 - Read PROJECT_CONTEXT.md first for stack details and agent routing.
@@ -726,6 +727,47 @@ Stack: {data['primary_language']} | {', '.join(data.get('frameworks', []))}
 See PROJECT_CONTEXT.md for full agent routing table.
 """
 
+def generate_agents_md(data):
+    """Generate AGENTS.md for Codex and AGENTS-compatible editors."""
+    return f"""# AGENTS.md — {data['project_name']}
+# Generated by thachvd-kit. See PROJECT_CONTEXT.md for full stack info.
+# Platform: Codex / AGENTS-compatible editors
+
+## Project
+{data['description']}
+Stack: {data['primary_language']} | {', '.join(data.get('frameworks', [])) or '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.get('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.
+"""
+
 def generate_ai_context_refinement_prompt(data):
     scan_evidence = data.get("scan_evidence", [])
     evidence_block = "\n".join("- " + line for line in scan_evidence) if scan_evidence else "- No scan evidence was captured during init."
@@ -805,7 +847,7 @@ def format_scan_preview_lines(scanned):
 
 def main():
     parser = argparse.ArgumentParser(description="thachvd-kit project init wizard")
-    parser.add_argument("--platform", choices=["antigravity", "claude", "all"], default="antigravity",
+    parser.add_argument("--platform", choices=["antigravity", "claude", "codex", "all"], default="antigravity",
                         help="Which platform config to generate (default: antigravity)")
     parser.add_argument("--yes", "-y", action="store_true", help="Use defaults without prompting")
     parser.add_argument("--scan", action="store_true", help="Scan the current project to prefill or auto-generate PROJECT_CONTEXT.md")
@@ -956,11 +998,17 @@ def main():
     output_path.write_text(context_content, encoding="utf-8")
     print(f"  {green('✓')} {bold('PROJECT_CONTEXT.md')} generated")
 
-    # CLAUDE.md (for Claude Code / Codex)
+    # CLAUDE.md (for Claude Code)
     if args.platform in ("claude", "all"):
         claude_path = Path("CLAUDE.md")
         claude_path.write_text(generate_claude_md(data), encoding="utf-8")
-        print(f"  {green('✓')} {bold('CLAUDE.md')} generated (Claude Code / Codex)")
+        print(f"  {green('✓')} {bold('CLAUDE.md')} generated (Claude Code)")
+
+    # AGENTS.md (for Codex / AGENTS-compatible editors)
+    if args.platform in ("codex", "all"):
+        agents_path = Path("AGENTS.md")
+        agents_path.write_text(generate_agents_md(data), encoding="utf-8")
+        print(f"  {green('✓')} {bold('AGENTS.md')} generated (Codex)")
 
     ai_refine_path = None
     if data.get("needs_ai_refinement"):
@@ -983,6 +1031,7 @@ def main():
   {bold('Generated files:')}
     · {bold(str(output_path.resolve()))}
     · {bold(str(Path("CLAUDE.md").resolve())) if args.platform in ("claude", "all") else 'CLAUDE.md not generated for this platform'}
+    · {bold(str(Path("AGENTS.md").resolve())) if args.platform in ("codex", "all") else 'AGENTS.md not generated for this platform'}
     · {bold(str(ai_refine_path.resolve())) if ai_refine_path else 'AI_CONTEXT_REFINEMENT.md not generated'}
 
   {bold('Next steps:')}
@@ -991,7 +1040,7 @@ def main():
     3. Open project in your AI editor (Antigravity / Claude Code / Codex)
     4. The agent will read PROJECT_CONTEXT.md on session start
 
-{dim('  Tip: Run with --platform all to also generate CLAUDE.md')}
+{dim('  Tip: Run with --platform all to also generate CLAUDE.md and AGENTS.md')}
 """)
 
 if __name__ == "__main__":