@leejungkiin/awkit 1.4.3 → 1.5.1

package/skills/codex-conductor/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   Codex is READ-ONLY: it inspects and reports to .md files, never edits code.
 metadata:
   stage: core
-  version: "1.0"
+  version: "1.1"
   requires: codex (npm i -g @openai/codex)
   tags: [conductor, codex, debug, review, logic, verification, delegation]
 agent: Inspector
@@ -15,323 +15,119 @@ invocation-type: auto
 priority: 5
 ---
 
-# 🔍 Codex Conductor Skill
+# 🔍 Codex Conductor — Router
 
-> **Purpose:** Antigravity gọi Codex CLI qua terminal khi cần rà soát logic, debug, hoặc review code chuyên sâu.
-> **Key Benefit:** Codex cực mạnh rule compliance + logic analysis. Output = báo cáo `.md`, KHÔNG sửa code.
+> **Purpose:** Gọi Codex CLI qua terminal khi cần rà soát logic, debug, review code chuyên sâu.
+> **Key:** Codex = Inspector (báo cáo .md). TUYỆT ĐỐI KHÔNG sửa code.
 
----
+## 📋 Topic Index
+
+| Topic | Khi nào load | File |
+|-------|-------------|------|
+| 6 prompt templates (bug, review, logic, test, plan, refactor) | Khi cần invoke Codex | `examples/prompt-templates.md` |
 
-## ⚠️ Core Principle
+## ⚠️ Three-Agent Model
 
 ```
 Antigravity (IDE) = Executor — code, implement, create
 Gemini CLI        = Strategist — analysis, architecture, planning
 Codex CLI         = Inspector — debug, review, verify, test
-
-   ┌──────────────────────────────────────────────┐
-   │  Codex CHỈ RÀ SOÁT + TẠO BÁO CÁO (.md)     │
-   │  TUYỆT ĐỐI KHÔNG ĐƯỢC SỬA CODE              │
-   └──────────────────────────────────────────────┘
 ```
 
----
-
 ## 🔧 Prerequisites
 
-Trước khi gọi Codex CLI, kiểm tra:
-
 ```bash
-# Check if codex is installed
 which codex || command -v codex
+# If not installed: npm i -g @openai/codex
 ```
 
-```yaml
-if_not_installed:
-  option_1: "npm i -g @openai/codex"
-  option_2: Ask user to install manually
-  message: "⚠️ Codex CLI chưa cài. Chạy: npm i -g @openai/codex"
-```
-
----
-
 ## 🎯 Trigger Conditions
 
-Kích hoạt khi Antigravity nhận diện task cần thế mạnh Codex:
-
 ```yaml
 auto_trigger:
-  high_confidence:
-    - Bug report from user (crash, unexpected behavior)
-    - Pre-commit code review (>3 files changed)
-    - Logic verification (race conditions, edge cases)
-    - Implementation plan review (find holes in plan)
-    - Refactor verification (ensure no regression)
-
-  medium_confidence (confirm before invoking):
-    - Test case generation for new feature
-    - Security audit
-    - Performance bottleneck analysis
-
-  never_trigger:
-    - Simple questions / explanations
-    - UI-only changes (styling, layout)
-    - Documentation edits
-    - Tasks Antigravity can handle alone easily
+  high: Bug report | Pre-commit review (>3 files) | Logic verification | Plan review | Refactor verification
+  medium (confirm): Test generation | Security audit | Performance analysis
+  never: Simple questions | UI-only changes | Docs edits
 ```
 
----
-
-## 🔧 CLI Invocation Pattern
-
-### Mode 1: Quick Analysis (read + stream response)
+## 🔧 CLI Invocation
 
+### Mode 1: Quick Analysis
 ```bash
 cd <PROJECT_ROOT> && timeout 120 codex \
-  "<PROMPT>. DO NOT edit any files. Output your analysis as text." \
-  --approval-mode suggest \
-  -q 2>/dev/null
+  "<PROMPT>. DO NOT edit any files." \
+  --approval-mode suggest -q 2>/dev/null
 ```
 
-| Flag | Purpose |
-|------|---------|
-| `"prompt"` | Single-prompt mode — reads cwd, streams response, exits |
-| `--approval-mode suggest` | Read-only: can browse files, won't make changes |
-| `-q` | Quiet mode — no TUI, output to stdout |
-
-### Mode 2: Deep Inspection (exec with JSON output)
-
+### Mode 2: Deep Inspection
 ```bash
 cd <PROJECT_ROOT> && timeout 180 codex exec \
-  "<PROMPT>. DO NOT edit any files. Output your findings as structured text." \
+  "<PROMPT>. DO NOT edit any files." \
   --json 2>/dev/null
 ```
 
-| Flag | Purpose |
-|------|---------|
-| `exec` | Non-interactive scripting mode |
-| `--json` | Structured JSON output for parsing |
-
 ### Safety Rules
-
-```yaml
-safety:
-  - Codex TUYỆT ĐỐI KHÔNG ĐƯỢC sửa code. CHỈ đọc + báo cáo.
-  - ALWAYS use --approval-mode suggest (read-only mode).
-  - ALWAYS inject "DO NOT edit any files" in every prompt.
-  - Timeout: 120s for quick analysis, 180s for deep inspection.
-  - If CLI fails → gracefully fallback to Antigravity-only mode.
-  - NEVER pass secrets/tokens in prompt.
-  - Working directory: ALWAYS set to project root.
-  - Output: ALWAYS save to .md report file.
-```
-
----
-
-## 📋 Use Cases & Prompt Templates
-
-### 1. Bug Root Cause Analysis
-
-```bash
-codex "A bug was reported: <BUG_DESCRIPTION>. \
-Analyze the codebase to find the root cause. \
-List: (1) most likely root cause with file:line, \
-(2) contributing factors, (3) suggested fix approach. \
-DO NOT edit any files." \
---approval-mode suggest -q
-```
-
-**When:** User reports a bug, crash, or unexpected behavior.
-**Report to:** `codex-reports/bug-analysis-<date>.md`
-
-### 2. Pre-Commit Code Review
-
-```bash
-codex "Review the uncommitted changes in this repo. \
-Check for: bugs, logic errors, edge cases, thread safety, \
-security issues, performance problems, naming inconsistencies. \
-Rank issues by severity (critical/warning/info). \
-DO NOT edit any files." \
---approval-mode suggest -q
-```
-
-**When:** Before committing changes across >3 files.
-**Report to:** `codex-reports/review-<date>.md`
-
-### 3. Logic & Edge Case Analysis
-
-```bash
-codex "Analyze <FILE_OR_MODULE> for logic correctness. \
-Focus on: edge cases (null, empty, boundary), race conditions, \
-error handling gaps, unreachable code, off-by-one errors. \
-List each issue with file:line and severity. \
-DO NOT edit any files." \
---approval-mode suggest -q
-```
-
-**When:** Complex logic that needs verification.
-**Report to:** `codex-reports/logic-analysis-<date>.md`
-
-### 4. Test Case Generation
-
-```bash
-codex "Analyze <FILE_OR_MODULE> and generate a comprehensive \
-list of test cases. Include: happy path, edge cases, error cases, \
-boundary values, concurrent scenarios. Format as markdown table. \
-DO NOT edit any files." \
---approval-mode suggest -q
-```
-
-**When:** New feature needs test coverage planning.
-**Report to:** `codex-reports/test-cases-<date>.md`
-
-### 5. Implementation Plan Review
-
-```bash
-codex "Review this implementation plan: <PLAN_CONTENT>. \
-Find: logic holes, missing error handling, security risks, \
-race conditions, scalability issues, missing edge cases. \
-Rate each issue by severity. \
-DO NOT edit any files." \
---approval-mode suggest -q
-```
-
-**When:** After Antigravity creates an implementation plan.
-**Report to:** `codex-reports/plan-review-<date>.md`
-
-### 6. Refactor Verification
-
-```bash
-codex "Compare the recent changes in this repo against the \
-original code. Verify: (1) no behavioral regression, \
-(2) all original edge cases still handled, \
-(3) no new bugs introduced. List any regressions found. \
-DO NOT edit any files." \
---approval-mode suggest -q
-```
-
-**When:** After refactoring to ensure no regression.
-**Report to:** `codex-reports/refactor-verify-<date>.md`
-
----
+- ALWAYS `--approval-mode suggest` (read-only)
+- ALWAYS inject "DO NOT edit any files"
+- Timeout: 120s quick, 180s deep
+- CLI fails → fallback gracefully
+- NEVER pass secrets in prompt
 
 ## 🔄 Integration Flow
 
 ```
-1. Antigravity detects trigger condition
-2. Check Codex CLI: which codex || prompt install
-3. Thông báo user: "🔍 Đang gọi Codex CLI để [mục đích]..."
-4. Build prompt with project context
-5. Run: run_command("cd <ROOT> && timeout 120 codex '<prompt>' --approval-mode suggest -q")
-6. Capture output
-7. Save report to codex-reports/<type>-<date>.md
-8. Summarize key findings for user
-9. Act on findings (Antigravity executes fixes if needed)
+1. Detect trigger → 2. Check codex installed
+3. "🔍 Đang gọi Codex CLI [mục đích]..."
+4. Build prompt → 5. Run command
+6. Capture output → 7. Save to codex-reports/<type>-<date>.md
+8. Summarize findings → 9. Act on findings
 ```
 
-### Output Handling
-
-```yaml
-on_success:
-  - Parse Codex output (text or JSON)
-  - Save full report to codex-reports/<type>-<date>.md
-  - Extract key findings + severity
-  - Present summary to user
-  - If critical issues found → suggest fixes
+### Error Handling
 
-on_timeout:
-  - Log: "⏳ Codex analysis timed out (>120s), proceeding with Antigravity"
-  - Fall back to Antigravity-only analysis
+| Event | Action |
+|-------|--------|
+| Success | Parse → save report → summarize → suggest fixes |
+| Timeout | "⏳ Timed out (>120s)" → fallback Antigravity-only |
+| Error | Check `codex --version` → suggest install |
+| Not installed | Ask user to install |
 
-on_error:
-  - Log: "⚠️ Codex CLI invocation failed"
-  - Check: "codex --version" → suggest install if missing
-  - Fall back gracefully — CLI is enhancement, not dependency
+## 📁 Report Structure
 
-on_not_installed:
-  - Ask user: "Codex CLI chưa cài. Cài bằng: npm i -g @openai/codex?"
-  - If yes → run install → retry
-  - If no → fall back to Antigravity-only
 ```
-
----
-
-## 📁 Report Output Structure
-
+<project_root>/codex-reports/     # Gitignored recommended
+├── bug-analysis-<date>.md
+├── review-<date>.md
+├── logic-analysis-<date>.md
+└── ...
 ```
-<project_root>/
-└── codex-reports/          # Gitignored recommended
-    ├── bug-analysis-2026-03-21.md
-    ├── review-2026-03-21.md
-    ├── logic-analysis-2026-03-21.md
-    ├── test-cases-2026-03-21.md
-    ├── plan-review-2026-03-21.md
-    └── refactor-verify-2026-03-21.md
-```
-
----
 
 ## 🚫 Anti-Patterns
 
 ```yaml
 never_do:
   - Let Codex edit source code (EVER)
-  - Use --approval-mode auto or full-access (ALWAYS use suggest)
-  - Pass sensitive data (API keys, tokens) in prompts
-  - Block on CLI response indefinitely (always use timeout)
-  - Call CLI more than 3 times per task (diminishing returns)
-  - Ignore CLI output — if you called it, use the result
-  - Call Codex for tasks Antigravity handles well alone
+  - Use --approval-mode auto (ALWAYS suggest)
+  - Pass API keys/tokens in prompts
+  - Block without timeout
+  - Call CLI >3 times per task
 
 always_do:
-  - Mention to user: "🔍 Đang gọi Codex CLI [mục đích]..."
+  - Mention "🔍 Đang gọi Codex CLI..."
   - Include "DO NOT edit any files" in EVERY prompt
-  - Use --approval-mode suggest (read-only)
-  - Save reports to codex-reports/ directory
-  - Summarize findings before acting on them
-  - Fall back gracefully if CLI unavailable
-  - Check codex installation before first use
+  - Save reports to codex-reports/
+  - Fall back gracefully if unavailable
 ```
 
----
-
-## 🤝 Three-Agent Collaboration
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    User Request                          │
-└─────────────┬───────────────────────────────────────────┘
-              │
-              ▼
-    ┌─────────────────┐
-    │   Antigravity    │ ← Primary: plan, code, implement
-    │   (IDE Agent)    │
-    └───┬─────────┬───┘
-        │         │
-   Strategy?   Debug/Review?
-        │         │
-        ▼         ▼
-  ┌──────────┐ ┌──────────┐
-  │ Gemini   │ │ Codex    │
-  │ CLI      │ │ CLI      │
-  │ ────────── │ ────────── │
-  │ Architect │ │ Inspector│
-  │ .md only  │ │ .md only │
-  └──────────┘ └──────────┘
-```
-
----
-
-## 🧩 Skill Relationships
+## 🧩 Relationships
 
 ```
-Uses:      run_command (to invoke codex CLI)
-Enhances:  /debug, /code, /refactor, /plan workflows
-Saves to:  codex-reports/*.md
+Uses:      run_command (to invoke CLI)
+Enhances:  /debug, /code, /refactor, /plan
 Parallel:  gemini-conductor (different role, can coexist)
-Independent of: NeuralMemory (CLI has its own context)
+Independent of: NeuralMemory
 ```
 
 ---
 
-*codex-conductor v1.0 — Three-Agent Flow Inspector for Antigravity*
+*codex-conductor v1.1 — Modular Router Architecture*

package/skills/codex-conductor/examples/prompt-templates.md

@@ -0,0 +1,72 @@
+# Codex CLI Prompt Templates
+
+## 1. Bug Root Cause Analysis
+
+```bash
+codex "A bug was reported: <BUG_DESCRIPTION>. \
+Analyze the codebase to find the root cause. \
+List: (1) most likely root cause with file:line, \
+(2) contributing factors, (3) suggested fix approach. \
+DO NOT edit any files." \
+--approval-mode suggest -q
+```
+**Report to:** `codex-reports/bug-analysis-<date>.md`
+
+## 2. Pre-Commit Code Review
+
+```bash
+codex "Review the uncommitted changes in this repo. \
+Check for: bugs, logic errors, edge cases, thread safety, \
+security issues, performance problems, naming inconsistencies. \
+Rank issues by severity (critical/warning/info). \
+DO NOT edit any files." \
+--approval-mode suggest -q
+```
+**Report to:** `codex-reports/review-<date>.md`
+
+## 3. Logic & Edge Case Analysis
+
+```bash
+codex "Analyze <FILE_OR_MODULE> for logic correctness. \
+Focus on: edge cases (null, empty, boundary), race conditions, \
+error handling gaps, unreachable code, off-by-one errors. \
+List each issue with file:line and severity. \
+DO NOT edit any files." \
+--approval-mode suggest -q
+```
+**Report to:** `codex-reports/logic-analysis-<date>.md`
+
+## 4. Test Case Generation
+
+```bash
+codex "Analyze <FILE_OR_MODULE> and generate a comprehensive \
+list of test cases. Include: happy path, edge cases, error cases, \
+boundary values, concurrent scenarios. Format as markdown table. \
+DO NOT edit any files." \
+--approval-mode suggest -q
+```
+**Report to:** `codex-reports/test-cases-<date>.md`
+
+## 5. Implementation Plan Review
+
+```bash
+codex "Review this implementation plan: <PLAN_CONTENT>. \
+Find: logic holes, missing error handling, security risks, \
+race conditions, scalability issues, missing edge cases. \
+Rate each issue by severity. \
+DO NOT edit any files." \
+--approval-mode suggest -q
+```
+**Report to:** `codex-reports/plan-review-<date>.md`
+
+## 6. Refactor Verification
+
+```bash
+codex "Compare the recent changes in this repo against the \
+original code. Verify: (1) no behavioral regression, \
+(2) all original edge cases still handled, \
+(3) no new bugs introduced. List any regressions found. \
+DO NOT edit any files." \
+--approval-mode suggest -q
+```
+**Report to:** `codex-reports/refactor-verify-<date>.md`