@leejungkiin/awkit 1.4.3 → 1.5.1

package/skills/symphony-enforcer/examples/startup-protocol.md

@@ -0,0 +1,92 @@
+# STRICT STARTUP PROTOCOL (BẮT BUỘC)
+
+Mỗi khi bắt đầu task code/debug/plan, AI PHẢI đi qua **6 steps tuần tự**.
+KHÔNG được bắt đầu work cho đến khi TẤT CẢ steps ✅.
+
+## Step 0.5: Legacy Artifact Cleanup (AUTO)
+
+```
+→ Kiểm tra: .symphony/tasks.json tồn tại?
+→ CÓ  → ⚠️ CẢNH BÁO: "Legacy tasks.json detected. Symphony uses SQLite DB — this file is stale."
+       → Khuyên user xoá: "rm .symphony/tasks.json"
+       → KHÔNG tự xoá (safety guardrail) — chỉ cảnh báo.
+       → Ghi log vào NeuralMemory: "Legacy tasks.json found at {project}, warned user."
+→ KHÔNG → ✅ Clean (no legacy artifacts)
+→ Output: "🧹 Step 0.5: Legacy Check ✅ — No stale artifacts"
+```
+
+> **Lý do:** Symphony v2+ sử dụng SQLite DB (`symphony.db`) làm single source of truth.
+> File `tasks.json` là di sản từ phiên bản cũ (pre-SQLite). Nếu tồn tại song song sẽ gây
+> "split-brain" — một nửa tool đọc JSON, một nửa đọc DB → dữ liệu lệch pha.
+
+## Step 1: Project Identity — `.project-identity`
+
+```
+→ Kiểm tra: file .project-identity có tồn tại?
+→ CÓ  → Đọc projectId, projectName
+→ KHÔNG → ⛔ DỪNG. Hỏi user hoặc tạo .project-identity.
+→ Output: "📋 Step 1/6: Project Identity ✅ — {projectId}"
+```
+
+## Step 2: NeuralMemory Brain — Switch brain
+
+```
+→ nmem brain use <projectId>
+→ nmem_recap(level=1) — load context
+→ Output: "🧠 Step 2/6: Brain ✅ — switched to {projectId}"
+```
+
+## Step 3: Spec Alignment — Đọc Project Spec (Kiro + fallback)
+
+```
+→ CHECK 1 (Kiro — HIGHEST PRIORITY): .kiro/specs/ tồn tại?
+  → CÓ → Load specs từ .kiro/specs/:
+     - .kiro/specs/<project>/requirements.md → project spec
+     - .kiro/specs/<module>/requirements.md → module specs
+     - .kiro/specs/<module>/design.md → architecture
+     - .kiro/specs/<module>/tasks.md → task breakdown (cho Step 4)
+     → Extract constraints liên quan đến task hiện tại
+     → Output: "📐 Step 3/6: Kiro Specs Loaded ✅ — {N} modules, {M} design docs"
+
+→ CHECK 2 (fallback): docs/specs/PROJECT.md tồn tại?
+  → CÓ  → Đọc silent: PROJECT.md + TECH-SPEC.md + REQUIREMENTS.md
+         → Extract constraints liên quan đến task hiện tại
+         → NẾU PLANNING mode:
+            - Hỏi user 1-3 câu về constraints/UX cụ thể của feature
+  → KHÔNG → Skip (project chưa /init) → "📐 Step 3/6: No spec — skipped"
+```
+
+## Step 4: Symphony Task — Tạo hoặc nhận task
+
+```
+→ CHECK 1 (Kiro tasks): .kiro/specs/<module>/tasks.md tồn tại?
+  → CÓ + chưa import → Parse task items từ tasks.md:
+     - Group theo module name
+     - Đánh tag kèm module name
+     → ⛔ CẢNH BÁO: KHÔNG đồng bộ nhỏ lẻ lên Trello. Chỉ đồng bộ module/feature lớn.
+     → Output: "🎯 Step 4/6: Kiro Tasks Imported ✅ — {N} tasks created"
+     → Claim task phù hợp nhất với user request
+
+→ CHECK 2 (fallback): symphony_available_tasks(filter="my") → check active tasks
+  → CÓ task in_progress phù hợp → dùng tiếp
+  → CÓ task ready phù hợp → symphony_claim_task
+  → KHÔNG CÓ → symphony_create_task(title) → symphony_claim_task(new_id)
+→ Lưu task_id cho TP1-TP4
+→ Output: "🎯 Step 4/6: Task ✅ — #sym-XYZ claimed"
+```
+
+## Step 5: Confirmation Block
+
+```
+🚦 STARTUP PROTOCOL COMPLETE
+══════════════════════════════════════
+  Step 0.5: 🧹 Legacy Check     ✅  No stale artifacts
+  Step 1:   📋 Project Identity  ✅  {projectId}
+  Step 2:   🧠 NeuralMemory      ✅  brain: {projectId}
+  Step 3:   📐 Spec Alignment     ✅  {constraints_count} constraints loaded
+  Step 4:   🎯 Task              ✅  #sym-XYZ — "{title}"
+  Step 5:   ✅ READY TO WORK
+══════════════════════════════════════
+```
+
+> ⛔ **Nếu KHÔNG hiển thị confirmation block = VI PHẠM**

package/skills/symphony-enforcer/examples/task-completion.md

@@ -0,0 +1,100 @@
+# Task Completion Protocol (TP2) + Git Commit (TP2.5) + Auto-Next (TP4)
+
+## TP2: Task Complete — Completion Status Protocol
+
+**Khi nào:** AI detect ≥2/4 completion signals:
+
+```
+Signal 1: Final notify_user với BlockedOnUser=false
+Signal 2: Walkthrough artifact đã tạo
+Signal 3: Tất cả checklist items trong task.md đã [x]
+Signal 4: Verification pass (tests OK, build OK)
+```
+
+**Completion Status Protocol (4 statuses):**
+
+```
+DONE:
+  Điều kiện: Verification pass, không caveats.
+  Format: "✅ DONE — {summary}. Build: ✅. Tests: ✅ N/N."
+
+DONE_WITH_CONCERNS:
+  Điều kiện: Code hoạt động nhưng có caveats/risks.
+  Format: "⚠️ DONE_WITH_CONCERNS — {summary}.
+    Concerns: [list]  Risk: [mức độ]  Recommendation: [đề xuất]"
+
+BLOCKED:
+  Điều kiện: Không thể tiếp tục vì external dependency.
+  Format: "🚫 BLOCKED — {reason}. Attempted: [list] Needs: [what]"
+
+NEEDS_CONTEXT:
+  Điều kiện: Thiếu thông tin từ user.
+  Format: "❓ NEEDS_CONTEXT — {what's missing}. Question: [câu hỏi]"
+```
+
+⛔ **KHÔNG BAO GIỜ report DONE nếu thực tế là DONE_WITH_CONCERNS hoặc BLOCKED.**
+
+**Action (cho DONE status):**
+```
+0. ⚡ VERIFICATION GATE (BẮT BUỘC):
+   - IDENTIFY → RUN → READ → VERIFY
+   - If NO → FIX trước, KHÔNG complete task
+   - If YES → Proceed with evidence
+
+1. symphony_complete_task(task_id, summary="STATUS + EVIDENCE")
+2. Hiển thị: "✅ SYM #sym-XYZ — {STATUS}"
+3. → TRIGGER TP2.5 (Atomic Git Commit)
+4. → TRIGGER TP4 (Auto-Next) NGAY LẬP TỨC
+```
+
+---
+
+## TP2.5: Atomic Git Commit (BẮT BUỘC)
+
+**Khi nào:** Ngay sau TP2 (task done), TRƯỚC TP4. Chỉ trigger khi có code changes.
+
+**Action:**
+```
+1. git status --porcelain → KHÔNG CÓ changes → skip
+2. Xác định commit type: feat | fix | refactor | docs
+3. Format: "{type}({scope}): {task_summary}"
+4. git add <files> → git commit -m "{message}"
+5. ⚠️ KHÔNG AUTO-PUSH — chỉ commit local
+```
+
+**Enforcement:**
+- ❌ KHÔNG auto-push
+- ❌ KHÔNG commit nếu có unresolved merge conflicts
+- ❌ KHÔNG commit files ngoài scope task
+- ✅ Mỗi task = 1 commit (atomic, traceable)
+
+---
+
+## TP3: Abandoned / Context Switch
+
+**Khi nào:** User đổi topic, AI timeout, user nói dừng.
+
+**Action:** `symphony_abandon_task(task_id, reason="...")`
+
+---
+
+## TP4: Auto-Next Suggestion (BẮT BUỘC)
+
+**Khi nào:** Ngay sau TP2 (task completed). KHÔNG ĐƯỢC BỎ QUA.
+
+**Action:**
+```
+1. ĐỌC projectId từ .project-identity
+2. symphony task list -P <projectId> -s ready (CHỈ tasks cùng project)
+   ⚠️ TUYỆT ĐỐI KHÔNG dùng filter="ready" không có project filter
+3. Lọc top 2-3 ready tasks theo priority
+4. Present cho user:
+   ➡️ NEXT STEPS ({projectName})
+   📋 #sym-A1 — Auth Module (P0, ready)
+   📋 #sym-A2 — Dashboard UI (P1, ready)
+5. Nếu KHÔNG CÓ ready tasks → "✨ Không còn task ready! Tạo task mới hoặc chuyển phase."
+```
+
+**Enforcement:**
+- ❌ KHÔNG kết thúc conversation mà KHÔNG present next suggestion
+- ❌ KHÔNG show tasks từ project khác

package/skills/symphony-enforcer/examples/three-phase.md

@@ -0,0 +1,107 @@
+# Three-Phase Auto-Enforcement Protocol (BẮT BUỘC)
+
+> **Vấn đề:** AI không tự chủ động dùng Three-Phase nếu không bị ép.
+> **Giải pháp:** Auto-detect + auto-announce + auto-enforce.
+
+## Phase State Tracking
+
+AI PHẢI duy trì trạng thái phase hiện tại xuyên suốt Gate 4:
+
+```
+current_phase = "A" | "B" | "C" | "none"
+phase_b_confirmed = false | true
+checkpoint_count = 0
+```
+
+## Auto-Detection: Khi nào kích hoạt Three-Phase?
+
+Tại đầu Gate 4 (EXECUTION bắt đầu), AI PHẢI tự kiểm tra:
+
+```
+1. Task được triage là COMPLEX?
+2. Task có UI component? (detect qua):
+   → Symphony task title chứa: screen, view, UI, layout, dashboard, form
+   → Implementation plan mentions: Composable, Fragment, Activity, Screen, View
+   → Design doc tồn tại (docs/design/ hoặc docs/architecture/ có UI sections)
+   → Spec references: wireframe, mockup, screenshot
+   → Platform: Android/iOS/React Native/Flutter (hầu hết có UI)
+
+Nếu CẢ HAI điều kiện thỏa:
+   → BẮT BUỘC kích hoạt Three-Phase
+   → Hiển thị Phase Announcement Block
+```
+
+## Phase Announcement Block (BẮT BUỘC)
+
+Khi kích hoạt Three-Phase, AI PHẢI hiển thị:
+
+```
+🎯 THREE-PHASE EXECUTION ACTIVATED
+══════════════════════════════════════
+🏗️ Phase A: Infrastructure Setup
+   → {list tasks for Phase A}
+🎨 Phase B: UI Shell (Mock Data)
+   → {list tasks for Phase B}
+   → 🧪 AUTO DEVICE TEST (Maestro) sau phase này
+⚡ Phase C: Logic Integration
+   → {list tasks for Phase C}
+   → 🧪 AUTO DEVICE TEST (Maestro) mỗi feature
+══════════════════════════════════════
+Bắt đầu Phase A...
+```
+
+## Phase Transition Triggers (TỰ ĐỘNG)
+
+```yaml
+auto_triggers:
+  phase_a_to_b:
+    signal: Tất cả [INFRA] tasks đã done + build OK
+    action: |
+      - Announce: "🏗️ Phase A ✅ — Build thành công. Chuyển sang Phase B (UI Shell)."
+      - Set current_phase = "B"
+      - Bắt đầu code UI tasks
+
+  phase_b_to_checkpoint:
+    signal: Tất cả [UI] tasks đã done
+    action: |
+      - ⛔ TRIGGER TP1.7 (Checkpoint)
+      - Đọc `.project-identity` -> `autoVerification`
+      - NẾU `true`: 
+        + Chạy Auto Build → check exit code 0
+        + Dùng mcp_maestro_launch_app và take_screenshot
+        + NẾU fail → DỪNG (notify_user BlockedOnUser=true)
+        + NẾU pass → Báo cáo Screenshot (BlockedOnUser=false) và làm tiếp Phase C
+      - NẾU `false` (default):
+        + DỪNG VÀ CHỜ user test thủ công (notify_user BlockedOnUser=true)
+        + CHỜ user xác nhận "OK" mới đi tiếp Phase C
+
+  checkpoint_to_phase_c:
+    signal: Build success & App launched (autoVerification=true) HOẶC User confirmed "OK" (autoVerification=false)
+    action: |
+      - Set phase_b_confirmed = true
+      - Set current_phase = "C"
+      - Announce: "🎨 Phase B ✅ — UI đã được duyệt. Chuyển sang Phase C (Logic)."
+
+  phase_c_per_feature:
+    signal: 1 feature [LOGIC] đã done + có UI impact
+    action: |
+      - TRIGGER TP1.7 (mini checkpoint)
+      - Batch các features nhỏ lại nếu có thể
+```
+
+## Enforcement Rules
+
+```
+❌ VI PHẠM NẶNG:
+  - Code logic (Phase C) khi phase_b_confirmed = false
+  - Skip Phase Announcement Block
+  - Bỏ qua TP1.7
+  - Chạy Auto-verification khi `autoVerification: false`
+  - Chờ user test thủ công khi `autoVerification: true`
+
+✅ BẮT BUỘC:
+  - Luôn announce phase transition rõ ràng
+  - Luôn đọc `autoVerification` trong `.project-identity` trước khi trigger check
+  - Gắn BlockedOnUser = true cho mode manual, false cho mode auto
+  - Ghi lại phase state vào NeuralMemory khi chuyển phase
+```

package/skills/symphony-enforcer/examples/trigger-points.md

@@ -0,0 +1,99 @@
+# Trigger Points: TP1, TP1.5, TP1.7
+
+## TP1: Progress Milestone
+
+**Khi nào:** Milestone xảy ra:
+- Chuyển mode: PLANNING → EXECUTION → VERIFICATION
+- Gọi `notify_user` (TRƯỚC khi gọi)
+- Hoàn thành 1 component/file lớn
+- Phát hiện vấn đề cần thay đổi approach
+
+**Action:**
+```
+symphony_report_progress(
+  task_id=current_task,
+  progress=estimated_percentage,
+  last_action="mô tả ngắn"
+)
+```
+
+**Progress Guide (Three-Phase Model):**
+```
+  10% — Task created, đang research/đọc code
+  20% — Implementation plan approved
+  25% — Phase A done (build OK, dependencies ready)
+  30% — Phase B bắt đầu (UI shell coding)
+  45% — Phase B done → USER TEST CHECKPOINT #1 (UI review)
+  50% — Phase C bắt đầu (logic integration)
+  50-85% — Phase C per-feature (each feature = +5-10%)
+  85% — Phase C done, đang final verification
+  90% — Walkthrough/docs tạo xong
+ 100% — Hoàn thành (auto-trigger TP2)
+```
+
+**Enforcement:**
+- ❌ KHÔNG được gọi `notify_user` mà chưa `report_progress` trước đó
+- ❌ KHÔNG được chuyển mode (task_boundary) mà chưa report
+
+---
+
+## TP1.5: Design Compliance Check (Gate 4 Enforcement)
+
+**Khi nào:** Mỗi khi AI sửa file liên quan đến DB/Model/Schema trong EXECUTION mode.
+
+**Trigger signals:**
+```
+File patterns:
+  - **/models/**,  **/entities/**,  **/schemas/**
+  - **Migration*, **Schema*, **Model*
+  - *.entity.*, *.model.*, *.schema.*
+  - Database.swift, AppDatabase.swift, schema.prisma, etc.
+```
+
+**Action:**
+```
+1. Kiểm tra: docs/architecture/<feature>_design.md tồn tại?
+   → KHÔNG → ⚠️ Warning: "Đang sửa model file nhưng chưa có approved design."
+     → Nếu COMPLEX task → ⛔ DỪNG, enforce Gate 2
+     → Nếu TRIVIAL/MODERATE → Warning only, tiếp tục
+
+2. Đối chiếu thay đổi vs approved design:
+   → Thêm field KHÔNG có trong design? → ⛔ DỪNG
+   → Đổi type khác design? → ⛔ DỪNG
+   → Xóa field trong design? → ⛔ DỪNG
+   → Thêm field CÓ trong design? → ✅ OK
+
+3. Khi DỪNG:
+   → Thông báo schema change ngoài approved design
+   → Kích hoạt spec-gate skill để update design doc
+   → Sau khi re-approve → tiếp tục code
+```
+
+---
+
+## TP1.7: Flexible Checkpoint (Manual vs Auto)
+
+**Cấu hình Mode Verification:**
+- `{"autoVerification": true}` → **Auto Device Checkpoint (ADC)**: Dùng Maestro tự build & chụp screenshot. Tiến thẳng (BlockedOnUser=false).
+- `{"autoVerification": false}` (hoặc không khai báo) → **Manual Checkpoint**: Dừng chờ user test (BlockedOnUser=true). **MẶC ĐỊNH an toàn**.
+
+**Khi nào trigger TP1.7:**
+1. **Phase B → C Transition (BẮT BUỘC cho COMPLEX):** ALL UI screens đã code xong
+2. **Sau mỗi feature trong Phase C (COMPLEX tasks):** Feature X đã code xong logic
+
+**Action (Tùy theo Mode):**
+```
+1. Report progress trước: symphony_report_progress(current_task, progress)
+2. Kiểm tra cờ `autoVerification` trong .project-identity.
+
+=== TRƯỜNG HỢP 1: autoVerification = false (Default Manual) ===
+   - Announce "🧪 MANUAL USER TEST CHECKPOINT #{N}"
+   - Đưa hướng dẫn test cụ thể
+   - Gọi notify_user(BlockedOnUser=true) — DỪNG và CHỜ user response
+
+=== TRƯỜNG HỢP 2: autoVerification = true (Auto Maestro) ===
+   - Chạy Auto Build
+   - Chạy mcp_maestro_launch_app, mcp_maestro_take_screenshot
+   - NẾU Build/Run Lỗi: BlockedOnUser=true
+   - NẾU Pass: BlockedOnUser=false. Lập tức đi tiếp!
+```

package/skills/symphony-orchestrator/SKILL.md

@@ -61,7 +61,7 @@ npm i -g @leejungkiin/awkit-symphony
 ### Bước 2: Verify
 
 ```bash
-symphony --version   # Expected: 0.1.0+
+symphony --version   # Expected: 1.5.0+
 symphony --help      # Shows: preflight, task, agent, dispatch, next, etc.
 ```
 

package/skills/writing-skills/SKILL.md

@@ -1,110 +1,122 @@
 ---
 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.
+description: Use when creating or updating AWKit skills or workflow documentation and you need a lean, searchable, testable skill structure.
 ---
 
-# Writing Skills
+# Writing Skills — Router
 
 ## Overview
 
-Writing skills IS Test-Driven Development applied to process documentation.
+**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.
+Write pressure scenarios, observe failure, write the minimum useful skill, then close loopholes without bloating the main file.
+
+**Core principle:** If you did not watch an agent fail without the skill, you do not know whether the skill teaches the right behavior.
+
+**Required background:** `test-driven-development` from the `superpowers` pack when you need the full RED-GREEN-REFACTOR discipline.
 
 ## 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:** Session narratives or one-off implementation logs
+
+### Skill Types
+
+- **Technique** — Concrete method with steps
+- **Pattern** — Decision framework or mental model
+- **Reference** — API docs, syntax guides, environment-specific notes
 
-**Skills ARE:** Reusable techniques, patterns, tools, reference guides
-**Skills are NOT:** Narratives about how you solved a problem once
+## Topic Index
 
-## Standard Skill Structure
+| Topic | When to Load | File |
+|-------|--------------|------|
+| Search optimization and descriptions | Naming skills and writing trigger metadata | `examples/cso-optimization.md` |
+| TDD for skills | Designing validation for skills and workflow docs | `examples/tdd-for-skills.md` |
+| Anti-rationalization patterns | Hardening discipline skills against loopholes | `examples/anti-rationalization.md` |
 
-Every AWKit skill MUST follow this structure:
+## SKILL.md Structure
+
+**Frontmatter:** Only `name` and `description`
+
+- `name`: letters, numbers, hyphens only
+- `description`: start with `Use when...`
+- Keep the description focused on trigger conditions, not on the workflow internals
 
 ```markdown
 ---
 name: skill-name
-description: When to use + auto-trigger description (for CATALOG.md matching)
+description: Use when [triggering conditions and symptoms]
 ---
 
-# Skill Title
+# Skill Name
+## Overview
+## When to Use / When Not to Use
+## Core Pattern
+## Quick Reference
+## Implementation
+## Common Mistakes
+```
+
+## Directory Structure
 
-## 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)
+```text
+skills/skill-name/
+├── SKILL.md
+├── examples/
+├── references/
+└── scripts/
 ```
 
-**Required sections:** Overview, When to Use, The Process
-**Recommended for discipline skills:** Iron Law, Red Flags, Anti-Rationalization Table
+Put only the routing logic and core rules in `SKILL.md`. Push heavy references and extended examples into side files.
+
+## Code Examples
+
+**One excellent example beats many mediocre ones.**
+
+Prefer one real, runnable example over five thin examples in different languages.
 
-## When to Create a Skill
+## Flowchart Usage
 
-**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
+Use flowcharts only for non-obvious branching or loops where agents commonly stop too early. Use plain markdown for linear instructions and reference material.
 
-**Don't create for:**
-- One-off solutions
-- Standard practices well-documented elsewhere
-- Project-specific conventions (put in GEMINI.md or docs/specs/)
+## The Iron Law
 
-## Skill Types
+```text
+NO SKILL WITHOUT A FAILING TEST FIRST
+```
+
+No exceptions for "small doc updates" or "just adding one section".
 
-### Rigid Skills (Follow Exactly)
-- `verification-gate` — No shortcuts for verification
-- `systematic-debugging` — 4-phase process mandatory
-- TDD enforcement — RED-GREEN-REFACTOR cycle
+## Skill Creation Checklist
 
-### Flexible Skills (Adapt Principles)
-- `brainstorm-agent` — Adapt questions to context
-- `ios-engineer` — Apply patterns per project needs
+**RED**
 
-**The skill itself tells you which type it is.**
+- [ ] Create pressure scenarios or realistic retrieval tasks
+- [ ] Run them without the skill
+- [ ] Capture exact failures and rationalizations
 
-## Key Writing Principles
+**GREEN**
 
-### 1. Token Efficiency (Critical)
-- Every token competes for agent context
-- Use tables over paragraphs for rules
-- Use bullet points over prose
-- Eliminate redundancy ruthlessly
+- [ ] Write the minimum skill that addresses the observed failures
+- [ ] Keep trigger metadata short and precise
+- [ ] Add only the references/examples required to teach the missing behavior
 
-### 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
+**REFACTOR**
 
-### 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`
+- [ ] Add explicit counters for new loopholes
+- [ ] Keep `SKILL.md` lean and move detail to side files
+- [ ] Re-run the same validation after every material change
 
-## Checklist: Before Publishing Skill
+## Stop Rule
 
-- [ ] 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
+Do not batch-create multiple skills without validating each one first.
 
 ## Integration
 
-**Related:**
-- `awf-version-tracker` — Auto-snapshot skill changes
-- CATALOG.md — Skill registry
+- `awf-version-tracker` — snapshot skill changes
+- `single-flow-task-execution` — useful when implementing multi-step skill refactors
+- `superpowers` pack — deeper TDD and verification references when you need them
+
+---
 
-**Workflows:**
-- `/skill-health` — Check skill system health
-- `/skill-rollback` — Rollback broken skill changes
+*writing-skills — Lean Router Architecture*

package/skills/writing-skills/examples/anti-rationalization.md

@@ -0,0 +1,53 @@
+# Bulletproofing Skills Against Rationalization
+
+Skills that enforce discipline need to resist rationalization. Agents will look for loopholes under pressure.
+
+## Close Every Loophole Explicitly
+
+Do not just state the rule. Forbid the common workarounds.
+
+```markdown
+# Bad
+Write code before test? Delete it.
+
+# Good
+Write code before test? Delete it. Start over.
+
+**No exceptions:**
+- Do not keep it as "reference"
+- Do not adapt it while writing tests
+- Do not look at it
+- Delete means delete
+```
+
+## Address Spirit-vs-Letter Arguments
+
+Add the foundational rule early:
+
+```markdown
+**Violating the letter of the rules is violating the spirit of the rules.**
+```
+
+## Build a Rationalization Table
+
+Every repeated excuse should become an explicit counter-rule.
+
+```markdown
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code still breaks. |
+| "I'll test after" | Tests-after answers a different question. |
+| "This case is special" | Special pleading is how process discipline collapses. |
+```
+
+## Create a Red Flags List
+
+```markdown
+## Red Flags
+- Code before test
+- "I already checked manually"
+- "Close enough"
+- "I'll tighten it later"
+```
+
+When these appear, stop and re-run the intended process.