@leejungkiin/awkit 1.1.4 → 1.1.7

package/skills/verification-gate/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: verification-gate
+description: Use BEFORE claiming any work is complete, fixed, or passing. Requires running verification commands and confirming output before making success claims. Evidence before assertions, always. Auto-triggers on task completion, commit, deploy, or any positive status claim.
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## When to Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction ("Done!", "Fixed!", "Works!")
+- Committing, PR creation, task completion
+- `symphony_complete_task` calls
+- Moving to next task
+- Deploying or pushing code
+
+## Verification Requirements by Claim Type
+
+| Claim | Requires | NOT Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, looks good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Feature works | Demo/run showing behavior | Code written, assumed works |
+| Requirements met | Line-by-line checklist | Tests passing |
+| Deploy succeeded | Health check: 200 OK | Deploy command completed |
+
+## Red Flags — STOP
+
+If you catch yourself thinking any of these, STOP and run verification:
+
+- Using "should", "probably", "seems to", "looks correct"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!")
+- About to commit/push without verification
+- Relying on partial verification
+- Thinking "just this once I can skip"
+- Tired and wanting work to be over
+- **ANY wording implying success without having run verification**
+
+## Anti-Rationalization Table
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler ≠ runtime |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Build passed so tests pass" | Build ≠ tests |
+| "I just changed one line" | One line can break everything |
+| "It's a trivial change" | Trivial changes have the sneakiest bugs |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] → [See: 34/34 pass] → "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Build:**
+```
+✅ [Run build] → [See: BUILD SUCCEEDED] → "Build passes"
+❌ "Linter passed so build is fine"
+```
+
+**Bug Fix:**
+```
+✅ Write regression test → Run (FAIL) → Fix → Run (PASS) → "Bug is fixed"
+❌ "I've changed the code, bug should be fixed"
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, so requirements are met"
+```
+
+## Symphony Integration
+
+When calling `symphony_complete_task`:
+1. Run ALL relevant verification commands FIRST
+2. Include verification evidence in the `summary` parameter
+3. Include `files_changed` list with ACTUAL changed files
+
+```
+❌ symphony_complete_task(summary="Implemented feature X")
+✅ symphony_complete_task(summary="Implemented feature X. Build: ✅ (exit 0). Tests: ✅ 47/47 pass. Lint: ✅ 0 errors.")
+```
+
+## Boil-the-Lake Completeness Checklist
+
+> **Principle:** AI's marginal cost is near zero. Ship completeness, not shortcuts.
+
+Trước khi claim DONE, kiểm tra **mỗi item** dưới đây:
+
+```
+☐ Error handling: MỌI code path có proper error handling?
+  → Network errors, parsing errors, invalid input, timeouts
+☐ Edge cases: Đã handle empty states, nil/null, boundary values?
+  → Empty list, first item, last item, max size
+☐ Logging: Đủ log cho production debugging?
+  → Errors logged with context, key operations tracked
+☐ Cleanup: Resources released? Listeners removed? Timers cancelled?
+☐ Input validation: User input được validate trước khi process?
+☐ Concurrency: Thread-safe? Race conditions handled?
+☐ Backwards compatibility: Breaking changes documented?
+```
+
+**Nếu thiếu bất kỳ item nào → report DONE_WITH_CONCERNS, không DONE.**
+
+## The Bottom Line
+
+**No shortcuts for verification. No shortcuts for completeness.**
+
+Run the command. Read the output. Check the checklist. THEN claim the result.
+
+This is non-negotiable.

package/skills/writing-skills/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: writing-skills
+description: Use when creating or modifying AWKit skills and workflows. Applies TDD methodology to process documentation. Ensures skills are testable, anti-rationalization-proof, and follow consistent structure.
+---
+
+# Writing Skills
+
+## Overview
+
+Writing skills IS Test-Driven Development applied to process documentation.
+
+**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
+
+## What is a Skill?
+
+A **skill** is a reference guide for proven techniques, patterns, or tools.
+
+**Skills ARE:** Reusable techniques, patterns, tools, reference guides
+**Skills are NOT:** Narratives about how you solved a problem once
+
+## Standard Skill Structure
+
+Every AWKit skill MUST follow this structure:
+
+```markdown
+---
+name: skill-name
+description: When to use + auto-trigger description (for CATALOG.md matching)
+---
+
+# Skill Title
+
+## Overview (1-2 sentences — what + why)
+## The Iron Law (core rule, no exceptions — for discipline skills)
+## When to Use / When NOT to Use
+## The Process (step by step)
+## Red Flags — STOP (catch rationalization)
+## Anti-Rationalization Table (excuse → reality)
+## Integration (related skills + workflows)
+```
+
+**Required sections:** Overview, When to Use, The Process
+**Recommended for discipline skills:** Iron Law, Red Flags, Anti-Rationalization Table
+
+## When to Create a Skill
+
+**Create when:**
+- Technique wasn't intuitively obvious
+- You'd reference this again across projects
+- Pattern applies broadly (not project-specific)
+- An agent repeatedly makes the same mistake
+
+**Don't create for:**
+- One-off solutions
+- Standard practices well-documented elsewhere
+- Project-specific conventions (put in GEMINI.md or docs/specs/)
+
+## Skill Types
+
+### Rigid Skills (Follow Exactly)
+- `verification-gate` — No shortcuts for verification
+- `systematic-debugging` — 4-phase process mandatory
+- TDD enforcement — RED-GREEN-REFACTOR cycle
+
+### Flexible Skills (Adapt Principles)
+- `brainstorm-agent` — Adapt questions to context
+- `ios-engineer` — Apply patterns per project needs
+
+**The skill itself tells you which type it is.**
+
+## Key Writing Principles
+
+### 1. Token Efficiency (Critical)
+- Every token competes for agent context
+- Use tables over paragraphs for rules
+- Use bullet points over prose
+- Eliminate redundancy ruthlessly
+
+### 2. Bulletproofing Against Rationalization
+- Agents are smart and WILL find loopholes under pressure
+- Close every loophole explicitly
+- Build rationalization table with common excuses
+- Create Red Flags list
+
+### 3. Cross-Referencing
+- Link related skills: `**Related:** verification-gate, systematic-debugging`
+- Note integration points: "Used by single-flow-task-execution"
+- Reference workflows: `/debug`, `/code`, `/deploy`
+
+## Checklist: Before Publishing Skill
+
+- [ ] SKILL.md follows standard structure
+- [ ] `name` and `description` in frontmatter
+- [ ] When to Use is clear and specific
+- [ ] Process steps are numbered and unambiguous
+- [ ] Anti-rationalization table covers common excuses
+- [ ] Integration section lists related skills/workflows
+- [ ] File < 500 lines
+- [ ] No narrative/story sections — only reference content
+- [ ] Updated CATALOG.md entry
+
+## Integration
+
+**Related:**
+- `awf-version-tracker` — Auto-snapshot skill changes
+- CATALOG.md — Skill registry
+
+**Workflows:**
+- `/skill-health` — Check skill system health
+- `/skill-rollback` — Rollback broken skill changes

package/workflows/conductor-codex.md

@@ -0,0 +1,125 @@
+---
+description: 🔍 Codex Conductor — Gọi Codex CLI rà soát code, debug, review logic, và verify refactor
+---
+
+# /conductor-codex — Three-Agent Inspector Workflow
+
+> Antigravity gọi Codex CLI (headless, read-only) khi cần rà soát chuyên sâu.
+> Codex CHỈ ĐỌC + TẠO BÁO CÁO `.md`. KHÔNG BAO GIỜ sửa code.
+
+// turbo-all
+
+---
+
+## Prerequisites
+
+1. Kiểm tra Codex CLI:
+```bash
+which codex || echo "NOT_INSTALLED"
+```
+2. Nếu chưa cài → đề xuất cài:
+```bash
+npm i -g @openai/codex
+```
+3. Tạo thư mục report nếu chưa có:
+```bash
+mkdir -p codex-reports
+```
+
+---
+
+## Sub-commands
+
+### `/conductor-codex:debug` — Phân tích root cause bug
+
+1. User mô tả bug (crash, lỗi logic, unexpected behavior)
+2. Thông báo: "🔍 Đang gọi Codex CLI phân tích bug..."
+3. Gọi CLI:
+```bash
+cd <PROJECT_ROOT> && timeout 120 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 2>/dev/null
+```
+4. Parse output → lưu vào `codex-reports/bug-analysis-<DATE>.md`
+5. Tóm tắt findings cho user
+6. Nếu critical → Antigravity thực hiện fix
+
+### `/conductor-codex:review` — Pre-commit code review
+
+1. Kiểm tra có uncommitted changes: `git diff --stat`
+2. Thông báo: "🔍 Đang gọi Codex CLI review code..."
+3. Gọi CLI:
+```bash
+cd <PROJECT_ROOT> && timeout 120 codex "Review the uncommitted changes in this repo. Check for: bugs, logic errors, edge cases, thread safety, security issues, performance problems. Rank issues by severity (critical/warning/info). DO NOT edit any files." --approval-mode suggest -q 2>/dev/null
+```
+4. Parse output → lưu vào `codex-reports/review-<DATE>.md`
+5. Tóm tắt: issues found + severity
+6. Nếu clean → suggest `git commit`
+
+### `/conductor-codex:logic` — Phân tích logic & edge cases
+
+1. Xác định file/module cần kiểm tra
+2. Thông báo: "🔍 Đang gọi Codex CLI kiểm tra logic..."
+3. Gọi CLI:
+```bash
+cd <PROJECT_ROOT> && timeout 120 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 2>/dev/null
+```
+4. Parse output → lưu vào `codex-reports/logic-analysis-<DATE>.md`
+5. Tóm tắt findings cho user
+
+### `/conductor-codex:test` — Generate test cases
+
+1. Xác định feature/module cần test
+2. Thông báo: "🔍 Đang gọi Codex CLI generate test cases..."
+3. Gọi CLI:
+```bash
+cd <PROJECT_ROOT> && timeout 120 codex "Analyze <FILE_OR_MODULE> and generate a comprehensive list of test cases. Include: happy path, edge cases, error cases, boundary values. Format as markdown table with columns: Test Name | Input | Expected Output | Type. DO NOT edit any files." --approval-mode suggest -q 2>/dev/null
+```
+4. Parse output → lưu vào `codex-reports/test-cases-<DATE>.md`
+5. Trình bày test plan cho user
+
+### `/conductor-codex:plan-review` — Review implementation plan
+
+1. Đọc `implementation_plan.md` hiện tại
+2. Thông báo: "🔍 Đang gọi Codex CLI review plan..."
+3. Gọi CLI:
+```bash
+cd <PROJECT_ROOT> && timeout 120 codex "Review this implementation plan in the current directory. Find: logic holes, missing error handling, security risks, race conditions, scalability issues, missing edge cases. Rate each issue by severity (critical/warning/info). DO NOT edit any files." --approval-mode suggest -q 2>/dev/null
+```
+4. Parse output → lưu vào `codex-reports/plan-review-<DATE>.md`
+5. Tóm tắt issues → Antigravity cập nhật plan
+
+---
+
+## Fallback Rules
+
+```yaml
+cli_not_installed:
+  - "⚠️ Codex CLI chưa cài. Chạy: npm i -g @openai/codex"
+  - Offer to install automatically
+
+cli_unavailable:
+  - "⚠️ Codex CLI không khả dụng, tiếp tục với Antigravity-only"
+  - Do NOT block workflow
+
+cli_timeout:
+  - "⏳ Codex phân tích quá lâu (>120s), bỏ qua và tiếp tục"
+
+cli_error:
+  - Log error
+  - Fall back gracefully
+  - Suggest: "codex --version" to check installation
+```
+
+---
+
+## Communication
+
+Mỗi khi gọi CLI, LUÔN thông báo user:
+```
+🔍 Đang gọi Codex CLI để [mục đích]...
+```
+
+Sau khi nhận kết quả:
+```
+✅ Codex rà soát xong. Báo cáo: codex-reports/<file>.md
+📊 Tóm tắt: [key findings]
+```

package/workflows/lifecycle/code.md

@@ -291,6 +291,29 @@ Khi user gõ `/code all-phases`:
 *   Cài thêm thư viện mới → Hỏi trước
 *   Deploy/Push code → **LUÔN LUÔN** hỏi trước
 
+### 5. TDD ENFORCEMENT (Superpowers-Inspired)
+
+> **Iron Law:** Write failing test FIRST, then implement. RED → GREEN → REFACTOR.
+> Ref: `~/.gemini/antigravity/skills/systematic-debugging/SKILL.md` Phase 4.
+
+**For PRODUCTION and ENTERPRISE quality levels:**
+```
+1. Write failing test for the feature/fix
+2. Run test → MUST FAIL (RED)
+3. Write MINIMAL code to make test pass
+4. Run test → MUST PASS (GREEN)
+5. Refactor if needed, tests still pass
+6. Commit
+```
+
+**Anti-Rationalization:**
+| Excuse | Reality |
+|--------|--------|
+| "I'll write tests after" | Untested code = unknown state |
+| "Too simple for tests" | Simple code breaks most |
+| "Tests slow me down" | Tests prevent 2h debug sessions |
+| "MVP doesn't need tests" | Even MVP needs syntax/build check |
+
 ---
 
 ## Giai đoạn 2: Hidden Requirements (Tự động thêm)
@@ -401,9 +424,13 @@ Test FAIL
 [Lần 3] Rollback + Approach khác → Test lại
     ↓
 ├── PASS → Thoát loop, tiếp tục
-└── FAIL → Hỏi User
+└── FAIL → ⚠️ 3-Fix Rule: Question architecture!
+         → Hỏi User + gợi ý /debug --systematic
 ```
 
+> **3-Fix Rule (from Superpowers):** Nếu 3 lần fix fail → đây KHÔNG phải bug đơn giản.
+> Đây là vấn đề kiến trúc. DỪNG fix symptoms, thảo luận root cause với user.
+
 ### 4.3. Khi fix loop thất bại
 
 ```

package/workflows/lifecycle/debug.md

@@ -9,6 +9,18 @@ description: 🐞 Sửa lỗi & Debug (Dual-Mode v5.0)
 
 ---
 
+## ⚠️ Iron Law (from systematic-debugging skill)
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+> Bắt buộc: Đọc `~/.gemini/antigravity/skills/systematic-debugging/SKILL.md` trước khi debug.
+> 4 phases: Root Cause → Pattern Analysis → Hypothesis → Implementation
+> 3-Fix Rule: Sau 3 fix thất bại → question architecture, discuss with user.
+
+---
+
 ## 🅰️ Expert Mode (Direct Execution)
 
 **Usage:**
@@ -16,20 +28,28 @@ description: 🐞 Sửa lỗi & Debug (Dual-Mode v5.0)
 /debug --auto-fix --file src/components/Cart.tsx
 ```
 
-**Logic:**
-1.  **Auto-Detect:**
-    -   Đọc logs gần nhất.
-    -   Parse error stack trace.
-    -   Identify file & line number.
-2.  **Root Cause Analysis:**
-    -   Phân tích code tại vị trí lỗi.
-    -   Đưa ra 1-2 giả thuyết.
-3.  **Auto-Fix (Safe Only):**
-    -   Lỗi *Safe-to-fix*: Missing import, typo, undefined check -> Sửa ngay.
-    -   Lỗi *Logic*: Báo cáo và đề xuất (không tự ý sửa).
-4.  **Symphony Sync:**
-    -   Nếu lỗi Critical và không thể auto-fix -> `symphony_create_task(title="Fix Critical Bug in Cart.tsx")`.
-5.  **Report:** "✅ Fixed 1 issue. ⚠️ Created task #456 for manual review."
+**Logic (follows 4-phase systematic debugging):**
+1.  **Phase 1 — Root Cause Investigation:**
+    -   Đọc error messages/stack traces HOÀN TOÀN (không skip).
+    -   Reproduce consistently — exact steps.
+    -   `git diff` — check recent changes.
+    -   Multi-component: add diagnostic logging ở mỗi boundary.
+    -   Trace data flow backward đến source.
+2.  **Phase 2 — Pattern Analysis:**
+    -   Find similar WORKING code in codebase.
+    -   Compare: list EVERY difference.
+3.  **Phase 3 — Hypothesis:**
+    -   "I think X is root cause because Y"
+    -   Test minimally — ONE variable at a time.
+4.  **Phase 4 — Implementation:**
+    -   Create failing test FIRST.
+    -   Implement single fix.
+    -   Verify: tests pass, no regressions.
+5.  **Symphony Sync:**
+    -   Nếu lỗi Critical và không thể auto-fix → `symphony_create_task(title="Fix Critical Bug in Cart.tsx")`.
+6.  **NeuralMemory:**
+    -   `nmem_remember` root cause + fix + pattern (cho future recall).
+7.  **Report:** "✅ Fixed 1 issue. Evidence: [test output]. ⚠️ Created task #456 for manual review."
 
 ---