thachvd-kit 1.0.8 → 1.0.11

package/README.md

@@ -1,82 +1,112 @@
-# thachvd-kit — Universal Agent Kit
-
-A universally compatible, high-power agent toolkit designed for **Antigravity**, **Claude Code**, and **Codex/OpenCode**. 
-It dynamically sets up rules and intelligently routes agent skills based on your project's technology stack using a CLI wizard.
-
-## 🚀 Quick Start
-
-You can initialize `thachvd-kit` in **any** project directory without manually copying files!
-
-Simply run the wizard:
+# thachvd-kit
+
+`thachvd-kit` bootstraps project context for AI coding agents such as Antigravity, Claude Code, and Codex.
+
+It installs a local `.agent/` kit, generates `PROJECT_CONTEXT.md`, and can scan an existing codebase to infer stack, framework, database, and infra signals before your agent starts working.
+
+## Quick Start
+
+Install globally:
 
 ```bash
-npx thachvd-kit init
-# or
-npx github:thachvd/thachvd-kit init
+npm install -g thachvd-kit
 ```
 
-The interactive wizard will first ask whether this is a new project or an existing one.
-If it is an existing project, it can scan the current codebase to prefill `PROJECT_CONTEXT.md`, or let you enter everything manually.
-The scan mode uses evidence-based detectors and shows why a framework was inferred, so you can quickly confirm or correct it.
-After init, you can also generate an AI refinement prompt to let your editor/agent deepen the project context.
+Then run inside any project folder:
 
 ```bash
-thachvd-kit init --scan
+thachvd-kit init
 ```
 
-Use `--scan` when you want to skip straight to codebase detection for an existing project.
-
-The wizard will then ask you a few questions about your project (frontend, backend, database, infrastructure, etc.). 
-Based on your answers, it will:
-1. **Copy** the highly optimized agents, skills, and rules to a `.agent` folder inside your project.
-2. **Generate** a smart `PROJECT_CONTEXT.md` file tailored specifically to your chosen stack.
-3. **Generate** a `CLAUDE.md` to ensure maximum cross-platform compatibility.
-
-### Global Installation (Like `agkit-init`)
-
-If you want to install it globally on your machine:
-
-```bash
-npm install -g github:thachvd/thachvd-kit
-```
-
-Then, whenever you start a new project, just type:
+You can also skip directly to scan mode:
 
 ```bash
-thachvd-kit init
+thachvd-kit init --scan
 ```
-
----
-
-## 🧠 How It Works
-
-This kit uses a **Universal Protocol Engine** (`GEMINI.md` / `CLAUDE.md`) that is completely stack-agnostic. 
-
-Instead of hardcoding rules, it relies on the `PROJECT_CONTEXT.md` file (generated by the CLI wizard) to automatically detect the environment and load the **right** skills:
-
-- Are you using **Laravel**? It loads `laravel-patterns`, `laravel-security`, and `laravel-tdd`.
-- Are you using **Go**? It brings in `golang-patterns` and `golang-testing`.
-- Are you using **React**? It primes the agent with `react-frontend` and `frontend-design`.
-- Are you using **Next.js**? It primes the agent with `nextjs-react-expert` and `frontend-design`.
-- Are you using **Tauri**? It primes the agent with `rust-pro` and `desktop-design`.
-
-## 🛠️ Features
-
-- 🎯 **50+ Production-Grade Skills:** From architecture patterns to multi-agent parallel dispatching.
-- ⚡️ **Subagent-Driven Development:** Agents act as your implementer, spec-verifier, and code-reviewer without human bottlenecks.
-- 🛡️ **Zero Hallucination Completion:** Built-in `verification-before-completion` forces the agent to run tests before claiming "done".
-- 🚀 **Isolated Worktrees:** Automatically manages hidden `git worktrees` so you never pollute your main branch with broken iterations.
-
-## Directory Structure (Inside your `.agent` folder)
-
-```text
-.agent/
-├── rules/GEMINI.md      ← The Universal Rules Engine
-├── agents/              ← 20+ specialized agents (frontend, backend, db, ...)
-├── skills/              ← 50+ domain & workflow skills
-└── workflows/           ← Executable workflows
-```
-
----
-
-**Made with ❤️ for AI-native software engineering.**
+
+## What `init` Does
+
+`thachvd-kit init` now supports both new and existing projects:
+
+- New project: enter context manually.
+- Existing project: choose scan mode or manual mode.
+- Scan mode: detect stack from the codebase, show evidence, then either accept detected values or review/edit them.
+
+Generated files:
+
+- `.agent/agents`
+- `.agent/rules`
+- `.agent/skills`
+- `.agent/workflows`
+- `PROJECT_CONTEXT.md`
+- `CLAUDE.md`
+- `AGENTS.md`
+- `AI_CONTEXT_REFINEMENT.md` when first-session AI refinement is enabled
+
+## Scan Behavior
+
+The scanner is hybrid and practical:
+
+- App stack detection uses an inferred `app_root` so nested apps like `src/` can still resolve Laravel, CakePHP, Next.js, and similar stacks correctly.
+- Infra detection stays repo-wide, so folders like `dev/`, `stg/`, `prod/` can still contribute Docker and CI evidence.
+- Noise folders such as `vendor`, `node_modules`, `.git`, `dist`, and `build` are ignored during recursive scan.
+
+The scan preview surfaces:
+
+- app root
+- project type
+- primary language
+- frameworks
+- database
+- package manager
+- test framework
+- cloud
+- infrastructure
+- CI/CD
+- evidence for each inferred framework
+
+## AI Refinement Flow
+
+`init` creates a baseline `PROJECT_CONTEXT.md`.
+
+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` / `AGENTS.md` instruct it to:
+
+1. Read `PROJECT_CONTEXT.md`
+2. Refine the context once if `needs_ai_refinement` is `true`
+3. Update the file to `context.status: refined`
+4. Set `context.needs_ai_refinement: false`
+
+This keeps `init` simple while still allowing a deeper AI pass without requiring API-key integration inside the CLI.
+
+## Skill Resolution
+
+The kit auto-loads generic and framework-specific skills based on detected context.
+
+Examples:
+
+- React -> `react-frontend`, `frontend-design`
+- Next.js -> `nextjs-react-expert`, `frontend-design`
+- Laravel -> `laravel-patterns`, `laravel-security`, `laravel-tdd`
+- Tauri -> `rust-pro`, `desktop-design`
+
+Generic quality skills such as `clean-code` and `systematic-debugging` are always included.
+
+## Directory Layout
+
+```text
+.agent/
+├── agents/
+├── rules/
+├── skills/
+└── workflows/
+```
+
+## Notes
+
+- `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

@@ -107,6 +107,7 @@ const CLOUD_CHOICES = ['aws', 'gcp', 'azure', 'vercel', 'fly', 'railway', 'none'
 const FRONTEND_FRAMEWORKS = ['vue', 'react', 'next', 'nuxt', 'svelte', 'angular'];
 const BACKEND_FRAMEWORKS = ['laravel', 'cakephp', 'symfony', 'codeigniter', 'express', 'fastapi', 'django', 'flask', 'gin', 'fiber', 'echo', 'nestjs', 'rails', 'spring', 'aspnet', 'axum', 'actix'];
 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(`
@@ -128,6 +129,7 @@ ${pc.bold('Options:')}
 
 function formatScanPreviewLines(scanned) {
     return [
+        ['App root', scanned.app_root || '.'],
         ['Project type', scanned.project_type || 'unknown'],
         ['Primary language', scanned.primary_language || 'unknown'],
         ['Frameworks', (scanned.frameworks || []).join(', ') || 'no framework'],
@@ -153,6 +155,10 @@ function fileExists(...parts) {
     return fs.existsSync(path.join(targetDir, ...parts));
 }
 
+function fileExistsAt(baseDir, ...parts) {
+    return fs.existsSync(path.join(baseDir, ...parts));
+}
+
 function readJsonIfExists(...parts) {
     const fullPath = path.join(targetDir, ...parts);
     if (!fs.existsSync(fullPath)) return null;
@@ -163,6 +169,16 @@ function readJsonIfExists(...parts) {
     }
 }
 
+function readJsonIfExistsAt(baseDir, ...parts) {
+    const fullPath = path.join(baseDir, ...parts);
+    if (!fs.existsSync(fullPath)) return null;
+    try {
+        return JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
 function readTextIfExists(...parts) {
     const fullPath = path.join(targetDir, ...parts);
     if (!fs.existsSync(fullPath)) return '';
@@ -173,17 +189,27 @@ function readTextIfExists(...parts) {
     }
 }
 
-function detectPackageManager() {
-    if (fileExists('pnpm-lock.yaml')) return 'pnpm';
-    if (fileExists('yarn.lock')) return 'yarn';
-    if (fileExists('bun.lockb') || fileExists('bun.lock')) return 'bun';
-    if (fileExists('package-lock.json')) return 'npm';
-    if (fileExists('uv.lock')) return 'uv';
-    if (fileExists('poetry.lock')) return 'pip';
-    if (fileExists('requirements.txt') || fileExists('pyproject.toml')) return 'pip';
-    if (fileExists('go.mod')) return 'go mod';
-    if (fileExists('Cargo.toml')) return 'cargo';
-    if (fileExists('composer.json')) return 'composer';
+function readTextIfExistsAt(baseDir, ...parts) {
+    const fullPath = path.join(baseDir, ...parts);
+    if (!fs.existsSync(fullPath)) return '';
+    try {
+        return fs.readFileSync(fullPath, 'utf8');
+    } catch {
+        return '';
+    }
+}
+
+function detectPackageManager(baseDir = targetDir) {
+    if (fileExistsAt(baseDir, 'pnpm-lock.yaml')) return 'pnpm';
+    if (fileExistsAt(baseDir, 'yarn.lock')) return 'yarn';
+    if (fileExistsAt(baseDir, 'bun.lockb') || fileExistsAt(baseDir, 'bun.lock')) return 'bun';
+    if (fileExistsAt(baseDir, 'package-lock.json')) return 'npm';
+    if (fileExistsAt(baseDir, 'uv.lock')) return 'uv';
+    if (fileExistsAt(baseDir, 'poetry.lock')) return 'pip';
+    if (fileExistsAt(baseDir, 'requirements.txt') || fileExistsAt(baseDir, 'pyproject.toml')) return 'pip';
+    if (fileExistsAt(baseDir, 'go.mod')) return 'go mod';
+    if (fileExistsAt(baseDir, 'Cargo.toml')) return 'cargo';
+    if (fileExistsAt(baseDir, 'composer.json')) return 'composer';
     return 'auto-detect';
 }
 
@@ -191,6 +217,76 @@ function uniq(values) {
     return Array.from(new Set(values.filter(Boolean)));
 }
 
+function detectAppRoot(baseDir) {
+    const candidates = [baseDir];
+    const queue = [{ dir: baseDir, depth: 0 }];
+
+    while (queue.length > 0) {
+        const { dir, depth } = queue.shift();
+        if (depth >= 2) continue;
+        let entries = [];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            if (IGNORED_SCAN_DIRS.has(entry.name)) continue;
+            const nextDir = path.join(dir, entry.name);
+            candidates.push(nextDir);
+            queue.push({ dir: nextDir, depth: depth + 1 });
+        }
+    }
+
+    const scoreCandidate = dir => {
+        let score = 0;
+        if (fileExistsAt(dir, 'composer.json')) score += 5;
+        if (fileExistsAt(dir, 'package.json')) score += 4;
+        if (fileExistsAt(dir, 'Cargo.toml')) score += 4;
+        if (fileExistsAt(dir, 'go.mod')) score += 4;
+        if (fileExistsAt(dir, 'pyproject.toml') || fileExistsAt(dir, 'requirements.txt')) score += 4;
+        if (fileExistsAt(dir, 'artisan')) score += 5;
+        if (fileExistsAt(dir, 'bin', 'cake') || fileExistsAt(dir, 'app', 'Config', 'core.php')) score += 5;
+        if (fileExistsAt(dir, 'src-tauri', 'tauri.conf.json') || fileExistsAt(dir, 'src-tauri', 'tauri.conf.json5')) score += 5;
+        if (fileExistsAt(dir, 'manage.py')) score += 4;
+        if (fileExistsAt(dir, 'Gemfile')) score += 4;
+        if (fileExistsAt(dir, 'pom.xml') || fileExistsAt(dir, 'build.gradle') || fileExistsAt(dir, 'build.gradle.kts')) score += 4;
+        if (fileExistsAt(dir, 'app', 'View') || fileExistsAt(dir, 'resources', 'views') || fileExistsAt(dir, 'templates') || fileExistsAt(dir, 'app', 'views')) score += 2;
+        return score;
+    };
+
+    const ranked = candidates
+        .map(dir => ({ dir, score: scoreCandidate(dir) }))
+        .filter(item => item.score > 0)
+        .sort((a, b) => (b.score - a.score) || (a.dir.length - b.dir.length));
+
+    return ranked[0]?.dir || baseDir;
+}
+
+function repoHasAny(baseDir, relativePaths, maxDepth = 3) {
+    const queue = [{ dir: baseDir, depth: 0 }];
+    while (queue.length > 0) {
+        const { dir, depth } = queue.shift();
+        for (const relativePath of relativePaths) {
+            if (fileExistsAt(dir, ...relativePath)) return true;
+        }
+        if (depth >= maxDepth) continue;
+        let entries = [];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            if (IGNORED_SCAN_DIRS.has(entry.name)) continue;
+            queue.push({ dir: path.join(dir, entry.name), depth: depth + 1 });
+        }
+    }
+    return false;
+}
+
 function evidenceIf(condition, label, weight = 1) {
     return condition ? { label, weight } : null;
 }
@@ -552,9 +648,10 @@ const FRAMEWORK_DETECTORS = [
 ];
 
 function scanProject() {
-    const pkg = readJsonIfExists('package.json') || {};
-    const composer = readJsonIfExists('composer.json') || {};
-    const rootEntries = fs.existsSync(targetDir) ? fs.readdirSync(targetDir) : [];
+    const appRoot = detectAppRoot(targetDir);
+    const pkg = readJsonIfExistsAt(appRoot, 'package.json') || {};
+    const composer = readJsonIfExistsAt(appRoot, 'composer.json') || {};
+    const rootEntries = fs.existsSync(appRoot) ? fs.readdirSync(appRoot) : [];
     const rootCsproj = rootEntries.find(name => name.endsWith('.csproj')) || '';
     const deps = {
         ...(pkg.dependencies || {}),
@@ -573,19 +670,19 @@ function scanProject() {
         depNames,
         composerDepNames,
         rootEntries,
-        fileExists,
-        requirementsText: readTextIfExists('requirements.txt'),
-        pyprojectText: readTextIfExists('pyproject.toml'),
-        goModText: readTextIfExists('go.mod'),
-        pubspecText: readTextIfExists('pubspec.yaml'),
-        gemfileText: readTextIfExists('Gemfile'),
-        pomText: readTextIfExists('pom.xml'),
-        gradleText: `${readTextIfExists('build.gradle')}\n${readTextIfExists('build.gradle.kts')}`,
-        cargoText: `${readTextIfExists('Cargo.toml')}\n${readTextIfExists('src-tauri', 'Cargo.toml')}`,
-        csprojText: rootCsproj ? readTextIfExists(rootCsproj) : '',
-        programCsText: readTextIfExists('Program.cs'),
-        viewFilesText: fs.existsSync(path.join(targetDir, 'app', 'View'))
-            ? fs.readdirSync(path.join(targetDir, 'app', 'View'), { recursive: true }).join('\n')
+        fileExists: (...parts) => fileExistsAt(appRoot, ...parts),
+        requirementsText: readTextIfExistsAt(appRoot, 'requirements.txt'),
+        pyprojectText: readTextIfExistsAt(appRoot, 'pyproject.toml'),
+        goModText: readTextIfExistsAt(appRoot, 'go.mod'),
+        pubspecText: readTextIfExistsAt(appRoot, 'pubspec.yaml'),
+        gemfileText: readTextIfExistsAt(appRoot, 'Gemfile'),
+        pomText: readTextIfExistsAt(appRoot, 'pom.xml'),
+        gradleText: `${readTextIfExistsAt(appRoot, 'build.gradle')}\n${readTextIfExistsAt(appRoot, 'build.gradle.kts')}`,
+        cargoText: `${readTextIfExistsAt(appRoot, 'Cargo.toml')}\n${readTextIfExistsAt(appRoot, 'src-tauri', 'Cargo.toml')}`,
+        csprojText: rootCsproj ? readTextIfExistsAt(appRoot, rootCsproj) : '',
+        programCsText: readTextIfExistsAt(appRoot, 'Program.cs'),
+        viewFilesText: fs.existsSync(path.join(appRoot, 'app', 'View'))
+            ? fs.readdirSync(path.join(appRoot, 'app', 'View'), { recursive: true }).join('\n')
             : ''
     };
 
@@ -631,7 +728,7 @@ function scanProject() {
     else if (frameworkDetails.some(item => item.projectType === 'web-app')) projectType = 'web-app';
     else if (frameworkDetails.some(item => item.kind === 'backend')) projectType = 'api';
     else if (frameworkDetails.some(item => item.kind === 'frontend')) projectType = 'web-app';
-    else if (fileExists('package.json') && pkg.bin) projectType = 'cli';
+    else if (fileExistsAt(appRoot, 'package.json') && pkg.bin) projectType = 'cli';
     else if (['php', 'python', 'go', 'java', 'ruby', 'csharp', 'rust'].includes(primaryLanguage)) projectType = 'api';
 
     if (hasDependency(depNames, 'pg', 'postgres', '@prisma/client') || /postgres/i.test(JSON.stringify(pkg))) database = 'postgres';
@@ -646,28 +743,30 @@ function scanProject() {
     else if (hasDependency(depNames, 'pytest') || textMatches(ctx.requirementsText, /\bpytest\b/i) || textMatches(ctx.pyprojectText, /\bpytest\b/i)) testFramework = 'pytest';
     else if (hasComposerDependency(composerDepNames, 'phpunit/phpunit')) testFramework = 'phpunit';
     else if (hasComposerDependency(composerDepNames, 'pestphp/pest')) testFramework = 'pest';
-    else if (fileExists('go.mod')) testFramework = 'go test';
+    else if (fileExistsAt(appRoot, 'go.mod')) testFramework = 'go test';
     else if (textMatches(ctx.gemfileText, /^\s*gem\s+["']rspec["']/im)) testFramework = 'rspec';
 
-    if (fileExists('Dockerfile') || fileExists('docker-compose.yml') || fileExists('docker-compose.yaml')) {
+    if (repoHasAny(targetDir, [['Dockerfile'], ['docker-compose.yml'], ['docker-compose.yaml']])) {
         infrastructure.push('docker');
     }
 
-    if (fileExists('vercel.json')) {
+    if (repoHasAny(targetDir, [['vercel.json']])) {
         cloud = 'vercel';
         infrastructure.push('vercel');
-    } else if (fileExists('fly.toml')) {
+    } else if (repoHasAny(targetDir, [['fly.toml']])) {
         cloud = 'fly';
         infrastructure.push('fly');
-    } else if (fileExists('railway.json') || fileExists('railway.toml')) {
+    } else if (repoHasAny(targetDir, [['railway.json'], ['railway.toml']])) {
         cloud = 'railway';
         infrastructure.push('railway');
     }
 
-    if (fileExists('.github', 'workflows')) ciCd = 'github-actions';
-    else if (fileExists('.gitlab-ci.yml')) ciCd = 'gitlab-ci';
-    else if (fileExists('.circleci', 'config.yml')) ciCd = 'circleci';
-    else if (fileExists('Jenkinsfile')) ciCd = 'jenkins';
+    if (repoHasAny(targetDir, [['.github', 'workflows'], ['.gitlab-ci.yml'], ['.circleci', 'config.yml'], ['Jenkinsfile']], 2)) {
+        if (repoHasAny(targetDir, [['.github', 'workflows']], 2)) ciCd = 'github-actions';
+        else if (repoHasAny(targetDir, [['.gitlab-ci.yml']], 2)) ciCd = 'gitlab-ci';
+        else if (repoHasAny(targetDir, [['.circleci', 'config.yml']], 2)) ciCd = 'circleci';
+        else if (repoHasAny(targetDir, [['Jenkinsfile']], 2)) ciCd = 'jenkins';
+    }
 
     const scanEvidence = [
         ...(languageDetections[0] ? [`language:${languageDetections[0].id} => ${languageDetections[0].evidence.join('; ')}`] : []),
@@ -676,6 +775,7 @@ function scanProject() {
 
     return {
         project_name: path.basename(targetDir),
+        app_root: path.relative(targetDir, appRoot) || '.',
         description: pkg.description || composer.description || 'A software project',
         project_type: PROJECT_TYPE_CHOICES.includes(projectType) ? projectType : 'web-app',
         primary_language: LANGUAGE_CHOICES.includes(primaryLanguage) ? primaryLanguage : 'typescript',
@@ -683,7 +783,7 @@ function scanProject() {
         framework_details: frameworkDetails,
         scan_evidence: scanEvidence,
         database: DATABASE_CHOICES.includes(database) ? database : 'none',
-        package_manager: PACKAGE_MANAGER_CHOICES.includes(detectPackageManager()) ? detectPackageManager() : 'auto-detect',
+        package_manager: PACKAGE_MANAGER_CHOICES.includes(detectPackageManager(appRoot)) ? detectPackageManager(appRoot) : 'auto-detect',
         uses_docker: infrastructure.includes('docker'),
         cloud,
         infrastructure: uniq(infrastructure),
@@ -791,10 +891,11 @@ context:
 ## Stack
 
 \`\`\`yaml
-stack:
-  primary_language: ${data.primary_language}
-  frameworks: [${(data.frameworks || []).join(', ')}]
-  database: ${data.database || 'none'}
+stack:
+  app_root: ${data.app_root || '.'}
+  primary_language: ${data.primary_language}
+  frameworks: [${(data.frameworks || []).join(', ')}]
+  database: ${data.database || 'none'}
   infrastructure: [${(data.infrastructure || []).join(', ')}]
   package_manager: ${data.package_manager || 'auto-detect'}
   test_framework: ${data.test_framework || 'auto-detect'}
@@ -852,11 +953,11 @@ ${autoSkillsList}
 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.
@@ -876,11 +977,52 @@ Stack: ${data.primary_language} | ${(data.frameworks || []).join(', ')}
 - \`/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
+
+## 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.
+`;
+}
+
 function generateAiContextRefinementPrompt(data) {
     const evidence = (data.scan_evidence || []).length > 0
         ? (data.scan_evidence || []).map(line => `- ${line}`).join('\n')
@@ -1121,6 +1263,7 @@ async function main() {
     data.max_file_lines = data.max_file_lines || scanned?.max_file_lines || '300';
     data.framework_details = scanned?.framework_details || [];
     data.scan_evidence = scanned?.scan_evidence || [];
+    data.app_root = scanned?.app_root || '.';
 
     if (!assumeYes) {
         const aiRefineAnswer = await askQuestions({
@@ -1170,6 +1313,10 @@ async function main() {
     fs.writeFileSync(claudeMdPath, generateClaudeMd(data), 'utf8');
     console.log(`  ${pc.green('✓')} Generated ${pc.bold('CLAUDE.md')}`);
 
+    const agentsMdPath = path.join(targetDir, 'AGENTS.md');
+    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');
@@ -1191,13 +1338,14 @@ ${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('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
+    4. Open project in Claude Code or Codex — the agent will read context on start
 `);
 }
 

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,7 +1,7 @@
 {
     "name": "thachvd-kit",
-    "version": "1.0.8",
-    "description": "Universal Agent Kit for Antigravity, Claude Code, and OpenCode",
+    "version": "1.0.11",
+    "description": "Project context bootstrap kit for Antigravity, Claude Code, and Codex",
     "bin": {
         "thachvd-kit": "./bin/cli.js"
     },
@@ -38,7 +38,7 @@
     "license": "MIT",
     "repository": {
         "type": "git",
-        "url": "git@github_home:holdon1996/thachvd-kit.git"
+        "url": "https://github.com/holdon1996/thachvd-kit.git"
     },
     "homepage": "https://github.com/holdon1996/thachvd-kit",
     "bugs": {

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
@@ -156,6 +157,7 @@ CLOUDS_ALL = ["aws", "gcp", "azure", "vercel", "fly", "railway", "digitalocean",
 FRONTEND_FRAMEWORKS = ["vue", "react", "next", "nuxt", "svelte", "angular"]
 BACKEND_FRAMEWORKS = ["laravel", "cakephp", "symfony", "codeigniter", "express", "fastapi", "django", "flask", "gin", "fiber", "echo", "nestjs", "rails", "spring", "aspnet", "axum", "actix"]
 MOBILE_DESKTOP_FRAMEWORKS = ["tauri", "flutter", "react-native"]
+IGNORED_SCAN_DIRS = {".git", "node_modules", "vendor", "dist", "build", "coverage", ".next", ".nuxt", ".turbo", ".cache", "storage", "tmp"}
 
 def read_text_if_exists(*parts):
     path = Path.cwd().joinpath(*parts)
@@ -171,23 +173,26 @@ def read_json_if_exists(*parts):
     except Exception:
         return None
 
-def detect_package_manager():
-    cwd = Path.cwd()
-    if (cwd / "pnpm-lock.yaml").exists(): return "pnpm"
-    if (cwd / "yarn.lock").exists(): return "yarn"
-    if (cwd / "bun.lockb").exists() or (cwd / "bun.lock").exists(): return "bun"
-    if (cwd / "package-lock.json").exists(): return "npm"
-    if (cwd / "uv.lock").exists(): return "uv"
-    if (cwd / "poetry.lock").exists(): return "poetry"
-    if (cwd / "requirements.txt").exists() or (cwd / "pyproject.toml").exists(): return "pip"
-    if (cwd / "go.mod").exists(): return "go mod"
-    if (cwd / "Cargo.toml").exists(): return "cargo"
-    if (cwd / "composer.json").exists(): return "composer"
+def detect_package_manager(base_dir=None):
+    base_dir = base_dir or Path.cwd()
+    if path_exists(base_dir, "pnpm-lock.yaml"): return "pnpm"
+    if path_exists(base_dir, "yarn.lock"): return "yarn"
+    if path_exists(base_dir, "bun.lockb") or path_exists(base_dir, "bun.lock"): return "bun"
+    if path_exists(base_dir, "package-lock.json"): return "npm"
+    if path_exists(base_dir, "uv.lock"): return "uv"
+    if path_exists(base_dir, "poetry.lock"): return "poetry"
+    if path_exists(base_dir, "requirements.txt") or path_exists(base_dir, "pyproject.toml"): return "pip"
+    if path_exists(base_dir, "go.mod"): return "go mod"
+    if path_exists(base_dir, "Cargo.toml"): return "cargo"
+    if path_exists(base_dir, "composer.json"): return "composer"
     return "auto-detect"
 
 def uniq(values):
     return list(dict.fromkeys(v for v in values if v))
 
+def path_exists(base_dir, *parts):
+    return base_dir.joinpath(*parts).exists()
+
 def evidence_if(condition, label, weight=1):
     return {"label": label, "weight": weight} if condition else None
 
@@ -215,10 +220,73 @@ def has_composer_dependency(composer_dep_names, *names):
 def text_matches(text, pattern):
     return bool(text and re.search(pattern, text, re.IGNORECASE | re.MULTILINE))
 
+def detect_app_root(base_dir):
+    candidates = [base_dir]
+    queue = [(base_dir, 0)]
+    while queue:
+        current, depth = queue.pop(0)
+        if depth >= 2:
+            continue
+        try:
+            entries = list(current.iterdir())
+        except Exception:
+            continue
+        for entry in entries:
+            if not entry.is_dir():
+                continue
+            if entry.name in IGNORED_SCAN_DIRS:
+                continue
+            candidates.append(entry)
+            queue.append((entry, depth + 1))
+
+    def score_candidate(path):
+        score = 0
+        if path_exists(path, "composer.json"): score += 5
+        if path_exists(path, "package.json"): score += 4
+        if path_exists(path, "Cargo.toml"): score += 4
+        if path_exists(path, "go.mod"): score += 4
+        if path_exists(path, "pyproject.toml") or path_exists(path, "requirements.txt"): score += 4
+        if path_exists(path, "artisan"): score += 5
+        if path_exists(path, "bin", "cake") or path_exists(path, "app", "Config", "core.php"): score += 5
+        if path_exists(path, "src-tauri", "tauri.conf.json") or path_exists(path, "src-tauri", "tauri.conf.json5"): score += 5
+        if path_exists(path, "manage.py"): score += 4
+        if path_exists(path, "Gemfile"): score += 4
+        if path_exists(path, "pom.xml") or path_exists(path, "build.gradle") or path_exists(path, "build.gradle.kts"): score += 4
+        if path_exists(path, "app", "View") or path_exists(path, "resources", "views") or path_exists(path, "templates") or path_exists(path, "app", "views"): score += 2
+        return score
+
+    ranked = [{"path": path, "score": score_candidate(path)} for path in candidates]
+    ranked = [item for item in ranked if item["score"] > 0]
+    ranked.sort(key=lambda item: (-item["score"], len(str(item["path"]))))
+    return ranked[0]["path"] if ranked else base_dir
+
+def repo_has_any(base_dir, relative_paths, max_depth=3):
+    queue = [(base_dir, 0)]
+    while queue:
+        current, depth = queue.pop(0)
+        for rel_parts in relative_paths:
+            if path_exists(current, *rel_parts):
+                return True
+        if depth >= max_depth:
+            continue
+        try:
+            entries = list(current.iterdir())
+        except Exception:
+            continue
+        for entry in entries:
+            if not entry.is_dir():
+                continue
+            if entry.name in IGNORED_SCAN_DIRS:
+                continue
+            queue.append((entry, depth + 1))
+    return False
+
 def scan_project():
-    pkg = read_json_if_exists("package.json") or {}
-    composer = read_json_if_exists("composer.json") or {}
-    root_entries = [p.name for p in Path.cwd().iterdir()] if Path.cwd().exists() else []
+    repo_root = Path.cwd()
+    app_root = detect_app_root(repo_root)
+    pkg = read_json_if_exists(app_root, "package.json") or {}
+    composer = read_json_if_exists(app_root, "composer.json") or {}
+    root_entries = [p.name for p in app_root.iterdir()] if app_root.exists() else []
     root_csproj = next((name for name in root_entries if name.endswith(".csproj")), "")
     deps = {}
     for key in ("dependencies", "devDependencies", "peerDependencies"):
@@ -228,53 +296,53 @@ def scan_project():
     for key in ("require", "require-dev"):
         composer_deps.update(composer.get(key, {}) or {})
     composer_dep_names = set(composer_deps.keys())
-    requirements = read_text_if_exists("requirements.txt")
-    pyproject = read_text_if_exists("pyproject.toml")
-    go_mod = read_text_if_exists("go.mod")
-    pubspec = read_text_if_exists("pubspec.yaml")
-    gemfile = read_text_if_exists("Gemfile")
-    pom = read_text_if_exists("pom.xml")
-    gradle = f"{read_text_if_exists('build.gradle')}\n{read_text_if_exists('build.gradle.kts')}"
-    cargo = f"{read_text_if_exists('Cargo.toml')}\n{read_text_if_exists('src-tauri/Cargo.toml')}"
-    csproj = read_text_if_exists(root_csproj) if root_csproj else ""
-    program_cs = read_text_if_exists("Program.cs")
+    requirements = read_text_if_exists(app_root, "requirements.txt")
+    pyproject = read_text_if_exists(app_root, "pyproject.toml")
+    go_mod = read_text_if_exists(app_root, "go.mod")
+    pubspec = read_text_if_exists(app_root, "pubspec.yaml")
+    gemfile = read_text_if_exists(app_root, "Gemfile")
+    pom = read_text_if_exists(app_root, "pom.xml")
+    gradle = f"{read_text_if_exists(app_root, 'build.gradle')}\n{read_text_if_exists(app_root, 'build.gradle.kts')}"
+    cargo = f"{read_text_if_exists(app_root, 'Cargo.toml')}\n{read_text_if_exists(app_root, 'src-tauri/Cargo.toml')}"
+    csproj = read_text_if_exists(app_root, root_csproj) if root_csproj else ""
+    program_cs = read_text_if_exists(app_root, "Program.cs")
 
     language_detections = [
         build_detection("typescript", [
-            evidence_if(Path("tsconfig.json").exists(), "found tsconfig.json", 4),
+            evidence_if(path_exists(app_root, "tsconfig.json"), "found tsconfig.json", 4),
             evidence_if(has_dependency(dep_names, "typescript", "ts-node", "tsx"), "package.json -> typescript toolchain", 2),
         ]),
         build_detection("javascript", [
-            evidence_if(Path("package.json").exists(), "found package.json", 2),
+            evidence_if(path_exists(app_root, "package.json"), "found package.json", 2),
             evidence_if(bool(dep_names), "package.json -> JavaScript dependency graph", 1),
         ]),
         build_detection("python", [
-            evidence_if(Path("requirements.txt").exists(), "found requirements.txt", 3),
-            evidence_if(Path("pyproject.toml").exists(), "found pyproject.toml", 2),
+            evidence_if(path_exists(app_root, "requirements.txt"), "found requirements.txt", 3),
+            evidence_if(path_exists(app_root, "pyproject.toml"), "found pyproject.toml", 2),
             evidence_if(text_matches(pyproject, r"\[tool\.(poetry|uv|hatch|pdm)\]"), "pyproject.toml -> Python tool section", 2),
         ]),
         build_detection("go", [
-            evidence_if(Path("go.mod").exists(), "found go.mod", 4),
+            evidence_if(path_exists(app_root, "go.mod"), "found go.mod", 4),
         ]),
         build_detection("php", [
-            evidence_if(Path("composer.json").exists(), "found composer.json", 4),
+            evidence_if(path_exists(app_root, "composer.json"), "found composer.json", 4),
             evidence_if(bool(composer_dep_names), "composer.json -> PHP dependency graph", 1),
         ]),
         build_detection("rust", [
-            evidence_if(Path("Cargo.toml").exists(), "found Cargo.toml", 4),
-            evidence_if(Path("src-tauri/Cargo.toml").exists(), "found src-tauri/Cargo.toml", 5),
+            evidence_if(path_exists(app_root, "Cargo.toml"), "found Cargo.toml", 4),
+            evidence_if(path_exists(app_root, "src-tauri", "Cargo.toml"), "found src-tauri/Cargo.toml", 5),
         ]),
         build_detection("java", [
-            evidence_if(Path("pom.xml").exists(), "found pom.xml", 4),
-            evidence_if(Path("build.gradle").exists() or Path("build.gradle.kts").exists(), "found Gradle build file", 3),
+            evidence_if(path_exists(app_root, "pom.xml"), "found pom.xml", 4),
+            evidence_if(path_exists(app_root, "build.gradle") or path_exists(app_root, "build.gradle.kts"), "found Gradle build file", 3),
         ]),
         build_detection("ruby", [
-            evidence_if(Path("Gemfile").exists(), "found Gemfile", 4),
-            evidence_if(Path("config.ru").exists(), "found config.ru", 1),
+            evidence_if(path_exists(app_root, "Gemfile"), "found Gemfile", 4),
+            evidence_if(path_exists(app_root, "config.ru"), "found config.ru", 1),
         ]),
         build_detection("csharp", [
             evidence_if(any(name.endswith(".sln") or name.endswith(".csproj") for name in root_entries), "found .sln/.csproj", 4),
-            evidence_if(Path("Program.cs").exists(), "found Program.cs", 1),
+            evidence_if(path_exists(app_root, "Program.cs"), "found Program.cs", 1),
         ]),
     ]
     language_detections = [item for item in language_detections if item["score"] >= 2]
@@ -283,8 +351,8 @@ def scan_project():
     framework_details = [
         {**build_detection("next", [
             evidence_if(has_dependency(dep_names, "next"), "package.json -> next", 4),
-            evidence_if(Path("next.config.js").exists() or Path("next.config.mjs").exists() or Path("next.config.ts").exists(), "found next.config.*", 3),
-            evidence_if(Path("app").exists() or Path("pages").exists(), "found app/ or pages/", 1),
+            evidence_if(path_exists(app_root, "next.config.js") or path_exists(app_root, "next.config.mjs") or path_exists(app_root, "next.config.ts"), "found next.config.*", 3),
+            evidence_if(path_exists(app_root, "app") or path_exists(app_root, "pages"), "found app/ or pages/", 1),
         ]), "kind": "frontend", "project_type": "web-app"},
         {**build_detection("react", [
             evidence_if(has_dependency(dep_names, "react"), "package.json -> react", 4),
@@ -295,14 +363,14 @@ def scan_project():
         ]), "kind": "frontend", "project_type": "web-app"},
         {**build_detection("nuxt", [
             evidence_if(has_dependency(dep_names, "nuxt"), "package.json -> nuxt", 4),
-            evidence_if(Path("nuxt.config.ts").exists() or Path("nuxt.config.js").exists(), "found nuxt.config.*", 3),
+            evidence_if(path_exists(app_root, "nuxt.config.ts") or path_exists(app_root, "nuxt.config.js"), "found nuxt.config.*", 3),
         ]), "kind": "frontend", "project_type": "web-app"},
         {**build_detection("svelte", [
             evidence_if(has_dependency(dep_names, "svelte", "@sveltejs/kit"), "package.json -> svelte", 4),
         ]), "kind": "frontend", "project_type": "web-app"},
         {**build_detection("angular", [
             evidence_if(has_dependency(dep_names, "@angular/core"), "package.json -> @angular/core", 4),
-            evidence_if(Path("angular.json").exists(), "found angular.json", 3),
+            evidence_if(path_exists(app_root, "angular.json"), "found angular.json", 3),
         ]), "kind": "frontend", "project_type": "web-app"},
         {**build_detection("express", [
             evidence_if(has_dependency(dep_names, "express"), "package.json -> express", 4),
@@ -315,39 +383,39 @@ def scan_project():
         ]), "kind": "backend", "project_type": "api", "language": "python"},
         {**build_detection("django", [
             evidence_if(text_matches(requirements, r"\bdjango\b") or text_matches(pyproject, r"\bdjango\b"), "Python deps -> django", 4),
-            evidence_if(Path("manage.py").exists(), "found manage.py", 2),
-            evidence_if(Path("templates").exists(), "found templates/", 1),
+            evidence_if(path_exists(app_root, "manage.py"), "found manage.py", 2),
+            evidence_if(path_exists(app_root, "templates"), "found templates/", 1),
         ]), "kind": "backend", "project_type": "web-app", "language": "python"},
         {**build_detection("flask", [
             evidence_if(text_matches(requirements, r"\bflask\b") or text_matches(pyproject, r"\bflask\b"), "Python deps -> flask", 4),
         ]), "kind": "backend", "project_type": "api", "language": "python"},
         {**build_detection("laravel", [
             evidence_if(has_composer_dependency(composer_dep_names, "laravel/framework"), "composer.json -> laravel/framework", 4),
-            evidence_if(Path("artisan").exists(), "found artisan", 3),
-            evidence_if(Path("resources/views").exists(), "found resources/views", 1),
+            evidence_if(path_exists(app_root, "artisan"), "found artisan", 3),
+            evidence_if(path_exists(app_root, "resources", "views"), "found resources/views", 1),
         ]), "kind": "backend", "project_type": "web-app", "language": "php"},
         {**build_detection("cakephp", [
             evidence_if(has_composer_dependency(composer_dep_names, "cakephp/cakephp"), "composer.json -> cakephp/cakephp", 4),
-            evidence_if(Path("bin/cake").exists(), "found bin/cake", 3),
-            evidence_if(Path("config/app.php").exists(), "found config/app.php", 2),
-            evidence_if(Path("app/Config/core.php").exists(), "found app/Config/core.php (CakePHP legacy)", 3),
-            evidence_if(Path("app/Controller/AppController.php").exists(), "found app/Controller/AppController.php", 2),
-            evidence_if(Path("app/Model/AppModel.php").exists(), "found app/Model/AppModel.php", 2),
-            evidence_if(Path("lib/Cake").exists(), "found lib/Cake", 3),
-            evidence_if(Path("cake/console/cake").exists(), "found cake/console/cake", 3),
-            evidence_if(Path("app/View").exists(), "found app/View", 2),
-            evidence_if(any(p.suffix.lower() == ".ctp" for p in Path("app/View").rglob("*.ctp")) if Path("app/View").exists() else False, "found .ctp view templates", 2),
+            evidence_if(path_exists(app_root, "bin", "cake"), "found bin/cake", 3),
+            evidence_if(path_exists(app_root, "config", "app.php"), "found config/app.php", 2),
+            evidence_if(path_exists(app_root, "app", "Config", "core.php"), "found app/Config/core.php (CakePHP legacy)", 3),
+            evidence_if(path_exists(app_root, "app", "Controller", "AppController.php"), "found app/Controller/AppController.php", 2),
+            evidence_if(path_exists(app_root, "app", "Model", "AppModel.php"), "found app/Model/AppModel.php", 2),
+            evidence_if(path_exists(app_root, "lib", "Cake"), "found lib/Cake", 3),
+            evidence_if(path_exists(app_root, "cake", "console", "cake"), "found cake/console/cake", 3),
+            evidence_if(path_exists(app_root, "app", "View"), "found app/View", 2),
+            evidence_if(any(p.suffix.lower() == ".ctp" for p in app_root.joinpath("app", "View").rglob("*.ctp")) if path_exists(app_root, "app", "View") else False, "found .ctp view templates", 2),
         ]), "kind": "backend", "project_type": "web-app", "language": "php"},
         {**build_detection("symfony", [
             evidence_if(has_composer_dependency(composer_dep_names, "symfony/framework-bundle"), "composer.json -> symfony/framework-bundle", 4),
-            evidence_if(Path("bin/console").exists(), "found bin/console", 2),
-            evidence_if(Path("config/bundles.php").exists(), "found config/bundles.php", 1),
-            evidence_if(Path("templates").exists(), "found templates/", 1),
+            evidence_if(path_exists(app_root, "bin", "console"), "found bin/console", 2),
+            evidence_if(path_exists(app_root, "config", "bundles.php"), "found config/bundles.php", 1),
+            evidence_if(path_exists(app_root, "templates"), "found templates/", 1),
         ]), "kind": "backend", "project_type": "web-app", "language": "php"},
         {**build_detection("codeigniter", [
             evidence_if(has_composer_dependency(composer_dep_names, "codeigniter4/framework"), "composer.json -> codeigniter4/framework", 4),
-            evidence_if(Path("spark").exists(), "found spark", 2),
-            evidence_if(Path("app/Config/App.php").exists(), "found app/Config/App.php", 1),
+            evidence_if(path_exists(app_root, "spark"), "found spark", 2),
+            evidence_if(path_exists(app_root, "app", "Config", "App.php"), "found app/Config/App.php", 1),
         ]), "kind": "backend", "project_type": "api", "language": "php"},
         {**build_detection("gin", [
             evidence_if(text_matches(go_mod, r"\bgithub\.com\/gin-gonic\/gin\b"), "go.mod -> github.com/gin-gonic/gin", 4),
@@ -360,8 +428,8 @@ def scan_project():
         ]), "kind": "backend", "project_type": "api", "language": "go"},
         {**build_detection("rails", [
             evidence_if(text_matches(gemfile, r'^\s*gem\s+["\']rails["\']'), "Gemfile -> rails", 4),
-            evidence_if(Path("bin/rails").exists(), "found bin/rails", 2),
-            evidence_if(Path("app/views").exists(), "found app/views", 1),
+            evidence_if(path_exists(app_root, "bin", "rails"), "found bin/rails", 2),
+            evidence_if(path_exists(app_root, "app", "views"), "found app/views", 1),
         ]), "kind": "backend", "project_type": "web-app", "language": "ruby"},
         {**build_detection("spring", [
             evidence_if(text_matches(pom, r"spring-boot") or text_matches(gradle, r"spring-boot"), "Java build -> spring-boot", 4),
@@ -372,8 +440,8 @@ def scan_project():
         ]), "kind": "backend", "project_type": "api", "language": "csharp"},
         {**build_detection("tauri", [
             evidence_if(has_dependency(dep_names, "@tauri-apps/api"), "package.json -> @tauri-apps/api", 4),
-            evidence_if(Path("src-tauri/tauri.conf.json").exists() or Path("src-tauri/tauri.conf.json5").exists(), "found src-tauri/tauri.conf.*", 4),
-            evidence_if(Path("src-tauri/Cargo.toml").exists(), "found src-tauri/Cargo.toml", 2),
+            evidence_if(path_exists(app_root, "src-tauri", "tauri.conf.json") or path_exists(app_root, "src-tauri", "tauri.conf.json5"), "found src-tauri/tauri.conf.*", 4),
+            evidence_if(path_exists(app_root, "src-tauri", "Cargo.toml"), "found src-tauri/Cargo.toml", 2),
         ]), "kind": "desktop", "project_type": "desktop", "language": "rust"},
         {**build_detection("axum", [
             evidence_if(text_matches(cargo, r"\baxum\b"), "Cargo.toml -> axum", 4),
@@ -413,7 +481,7 @@ def scan_project():
     elif any(item["project_type"] == "web-app" for item in framework_details): project_type = "web-app"
     elif any(item["kind"] == "backend" for item in framework_details): project_type = "api"
     elif any(item["kind"] == "frontend" for item in framework_details): project_type = "web-app"
-    elif Path("package.json").exists() and pkg.get("bin"): project_type = "cli"
+    elif path_exists(app_root, "package.json") and pkg.get("bin"): project_type = "cli"
     elif primary_language in ["php", "python", "go", "java", "ruby", "csharp", "rust"]: project_type = "api"
 
     if has_dependency(dep_names, "pg", "postgres", "@prisma/client") or "postgres" in json.dumps(pkg).lower(): database = "postgres"
@@ -428,26 +496,26 @@ def scan_project():
     elif has_dependency(dep_names, "pytest") or text_matches(requirements, r"\bpytest\b") or text_matches(pyproject, r"\bpytest\b"): test_framework = "pytest"
     elif has_composer_dependency(composer_dep_names, "phpunit/phpunit"): test_framework = "phpunit"
     elif has_composer_dependency(composer_dep_names, "pestphp/pest"): test_framework = "pest"
-    elif Path("go.mod").exists(): test_framework = "go test"
+    elif path_exists(app_root, "go.mod"): test_framework = "go test"
     elif text_matches(gemfile, r'^\s*gem\s+["\']rspec["\']'): test_framework = "rspec"
 
-    if Path("Dockerfile").exists() or Path("docker-compose.yml").exists() or Path("docker-compose.yaml").exists():
+    if repo_has_any(repo_root, [("Dockerfile",), ("docker-compose.yml",), ("docker-compose.yaml",)]):
         infrastructure.append("docker")
 
-    if Path("vercel.json").exists():
+    if repo_has_any(repo_root, [("vercel.json",)]):
         cloud = "vercel"
         infrastructure.append("vercel")
-    elif Path("fly.toml").exists():
+    elif repo_has_any(repo_root, [("fly.toml",)]):
         cloud = "fly"
         infrastructure.append("fly")
-    elif Path("railway.json").exists() or Path("railway.toml").exists():
+    elif repo_has_any(repo_root, [("railway.json",), ("railway.toml",)]):
         cloud = "railway"
         infrastructure.append("railway")
 
-    if Path(".github/workflows").exists(): ci_cd = "github-actions"
-    elif Path(".gitlab-ci.yml").exists(): ci_cd = "gitlab-ci"
-    elif Path(".circleci/config.yml").exists(): ci_cd = "circleci"
-    elif Path("Jenkinsfile").exists(): ci_cd = "jenkins"
+    if repo_has_any(repo_root, [(".github", "workflows")], max_depth=2): ci_cd = "github-actions"
+    elif repo_has_any(repo_root, [(".gitlab-ci.yml",)], max_depth=2): ci_cd = "gitlab-ci"
+    elif repo_has_any(repo_root, [(".circleci", "config.yml")], max_depth=2): ci_cd = "circleci"
+    elif repo_has_any(repo_root, [("Jenkinsfile",)], max_depth=2): ci_cd = "jenkins"
 
     scan_evidence = []
     if language_detections:
@@ -456,6 +524,7 @@ def scan_project():
 
     return {
         "project_name": Path.cwd().name,
+        "app_root": str(app_root.relative_to(repo_root)) if app_root != repo_root else ".",
         "description": pkg.get("description") or composer.get("description", "A software project"),
         "project_type": project_type if project_type in PROJECT_TYPES_ALL else "web-app",
         "primary_language": primary_language if primary_language in LANGUAGES_ALL else "typescript",
@@ -463,7 +532,7 @@ def scan_project():
         "framework_details": framework_details,
         "scan_evidence": scan_evidence,
         "database": database if database in DATABASES_ALL else "none",
-        "package_manager": detect_package_manager(),
+        "package_manager": detect_package_manager(app_root),
         "uses_docker": "docker" in infrastructure,
         "cloud": cloud,
         "infrastructure": uniq(infrastructure),
@@ -568,10 +637,11 @@ context:
 ## Stack
 
 ```yaml
-stack:
-  primary_language: {data['primary_language']}
-  frameworks: [{', '.join(frameworks)}]
-  database: {data.get('database', 'none')}
+stack:
+  app_root: {data.get('app_root', '.')}
+  primary_language: {data['primary_language']}
+  frameworks: [{', '.join(frameworks)}]
+  database: {data.get('database', 'none')}
   infrastructure: [{', '.join(infrastructure)}]
   package_manager: {data.get('package_manager', 'auto-detect')}
   test_framework: {data.get('test_framework', 'auto-detect')}
@@ -626,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.
@@ -657,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."
@@ -720,6 +831,7 @@ When done, summarize:
 
 def format_scan_preview_lines(scanned):
     return [
+        ("App root", scanned.get("app_root", ".")),
         ("Project type", scanned.get("project_type", "unknown")),
         ("Primary language", scanned.get("primary_language", "unknown")),
         ("Frameworks", ", ".join(scanned.get("frameworks", [])) or "no framework"),
@@ -735,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")
@@ -863,6 +975,7 @@ def main():
     data["code_style"] = data.get("code_style", (scanned or {}).get("code_style", "project-standard"))
     data["framework_details"] = data.get("framework_details", (scanned or {}).get("framework_details", []))
     data["scan_evidence"] = data.get("scan_evidence", (scanned or {}).get("scan_evidence", []))
+    data["app_root"] = data.get("app_root", (scanned or {}).get("app_root", "."))
     data["context_status"] = data.get("context_status", "baseline")
     data["needs_ai_refinement"] = data.get("needs_ai_refinement", False)
     data["last_refined_at"] = data.get("last_refined_at", "not-yet-refined")
@@ -885,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"):
@@ -912,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:')}
@@ -920,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__":