@leejungkiin/awkit 1.1.6 → 1.1.9

package/skills/orchestrator/SKILL.md

@@ -1,58 +1,339 @@
 ---
 name: orchestrator
-description: Intelligent dispatcher — analyzes context and delegates to the right skill or workflow
+description: >-
+  Autonomous State Machine Gatekeeper — triages task complexity, enforces 5-Gate pipeline,
+  and auto-routes to the correct skill. AI tự kiểm tra trạng thái dự án và bắt buộc
+  user đi qua đúng Gate trước khi code. User KHÔNG CẦN gọi workflow bằng tay.
+metadata:
+  stage: core
+  version: "2.1"
+  replaces: "1.0"
+  tags: [orchestrator, routing, gate, triage, state-machine, core]
+agent: Orchestrator
+trigger: always
+invocation-type: auto
+priority: 0
 ---
 
-# Orchestrator Skill
+# Orchestrator v2.1 — Autonomous State Machine Gatekeeper
 
-## Purpose
-Route user requests to the correct workflow or skill based on context analysis.
+> **Purpose:** Route mọi request qua hệ thống 5-Gate tự động.
+> AI tự nhận diện project state → tự quyết định gate nào cần chạy.
+> User chỉ cần nói ý tưởng, AI lo phần còn lại.
 
-## Routing Logic
+---
+
+## ⚡ Core Principle
+
+```
+AI LÀ NGƯỜI GIÁM SÁT "CÁN CÂN" CỦA DỰ ÁN.
+- User không cần nhớ workflow nào để gọi
+- AI tự detect thiếu spec → tự hỏi
+- AI tự detect thiếu design → tự phác thảo
+- AI tự detect thiếu tickets → tự tạo
+- Chỉ cho phép code khi TẤT CẢ prerequisites thỏa mãn
+```
+
+### 6 Decision Principles (Auto-decide khi không cần hỏi user)
+
+```
+1. Complete > Shortcuts    — AI cost rẻ. Implement đủ, kể cả edge cases.
+2. Evidence > Assumptions  — Dựa trên data thực tế, không đoán.
+3. Standard > Custom       — Ưu tiên thư viện/pattern có sẵn.
+4. Explicit > Implicit     — Code rõ ràng, không clever tricks.
+5. Test > Trust            — Viết test, không "chắc chắn đúng".
+6. Small > Big             — Incremental changes, không big-bang.
+```
+
+---
+
+## 🎯 STEP 1: Complexity Triage (BẮT BUỘC)
+
+Mỗi khi nhận request từ user, orchestrator PHẢI phân loại complexity **TRƯỚC** mọi action khác.
+
+### Scoring Criteria
+
+```yaml
+factors:
+  persistence_change:  # Thay đổi Database/Storage/Model
+    score: +4
+    signals: ["database", "schema", "table", "collection", "model", "migration", "storage"]
+
+  new_feature:  # Feature hoàn toàn mới
+    score: +3
+    signals: ["tính năng mới", "new feature", "implement", "build", "tạo mới"]
+
+  multi_file:  # Ảnh hưởng nhiều file/module
+    score: +2
+    signals: [">3 files", "cross-module", "refactor lớn", "architecture"]
+
+  api_change:  # Thay đổi API contract
+    score: +2
+    signals: ["API", "endpoint", "request", "response", "contract"]
+
+  ui_only:  # Chỉ thay đổi UI/styling
+    score: +0
+    signals: ["đổi màu", "UI", "layout", "font", "padding", "margin"]
+
+  single_file_fix:  # Sửa 1 file, logic nhỏ
+    score: +0
+    signals: ["fix typo", "sửa lỗi nhỏ", "update text", "rename"]
+```
+
+### Classification
+
+```
+TRIVIAL  (score 0-2): Bypass ALL gates → Execute trực tiếp
+  Examples: đổi màu nút, sửa typo, thêm log, fix linter, update string
+
+MODERATE (score 3-5): Gate 3 + 4 + 5
+  Examples: thêm UI component, sửa logic business nhỏ, update 1-2 files
+
+COMPLEX  (score 6-10): ALL 5 Gates bắt buộc
+  Examples: thêm feature mới, thay đổi DB schema, refactor architecture, thêm API
+```
+
+### Output Format
+
+```
+🔍 TRIAGE: [TRIVIAL|MODERATE|COMPLEX] (score: N/10)
+   Factors: [list detected factors]
+   Gates required: [list gates]
+```
+
+---
+
+## 🚦 STEP 2: Gate State Check (Cho COMPLEX tasks)
+
+Sau khi triage = COMPLEX, orchestrator kiểm tra **tuần tự** từng Gate.
+Dừng tại Gate ĐẦU TIÊN chưa thỏa mãn.
+
+### Gate 1: Spec Clarification 🔴
+
+```
+CHECK: Tồn tại file mô tả feature này?
+  → Scan: docs/specs/<feature>.md HOẶC docs/BRIEF.md có section liên quan
+  → Hoặc: NeuralMemory có BRIEF/SPEC cho feature này
+
+PASS condition: File tồn tại VÀ có nội dung rõ ràng (use cases, target users, scope)
+
+FAIL action:
+  → Thông báo user: "Ý tưởng rất hay! Nhưng trước khi bắt tay vào code, 
+     để tôi hỏi vài câu để chốt rõ yêu cầu đã nhé."
+  → Kích hoạt: brainstorm-agent skill (Phase 2-6)
+  → Output: BRIEF.md hoặc docs/specs/<feature>.md
+  → Sau khi tạo xong → Re-check Gate 1 → Proceed Gate 2
+```
+
+### Gate 2: Architecture & Data Design 🟠
+
+```
+CHECK: Tồn tại bản thiết kế kỹ thuật đã được duyệt?
+  → Scan: docs/architecture/<feature>_design.md
+  → HOẶC: implementation_plan.md có section "Data Model" + marker "Approved"
+
+PASS condition: File tồn tại VÀ có marker "## Status: Approved"
+
+FAIL action:
+  → Thông báo user: "Đã có spec rồi. Giờ để tôi phác thảo thiết kế 
+     Database và API trước khi code, tránh phải sửa đi sửa lại sau nhé."
+  → Kích hoạt: spec-gate skill
+  → Output: docs/architecture/<feature>_design.md
+  → Yêu cầu user approve design
+  → Sau khi approved → Re-check Gate 2 → Proceed Gate 3
+```
+
+### Gate 3: Task Breakdown (Symphony) 🟡
+
+```
+CHECK: Có Symphony tasks liên kết feature này?
+  → symphony_available_tasks → filter by feature keyword/tag
+
+PASS condition: ≥1 task tồn tại cho feature này
+
+FAIL action:
+  → Đọc design doc từ Gate 2
+  → Auto-generate 3-8 micro-tasks
+  → Tạo Symphony tasks (symphony_create_task cho mỗi task)
+  → Present danh sách cho user confirm
+  → Sau khi confirm → Proceed Gate 4
+```
+
+### Gate 4: Execution 🟢
+
+```
+CHECK: Có ticket đang In Progress?
+  → symphony_available_tasks(filter="in_progress")
+
+🔍 SEARCH BEFORE BUILDING (BẮT BUỘC trước khi viết code mới):
+  Layer 0 — Structural (GitNexus, CHỈ khi .gitnexus/ tồn tại):
+    → gitnexus_impact: Check blast radius của symbol cần sửa
+    → gitnexus_context: Xem 360° callers/callees trước khi code
+    → gitnexus_query: Tìm execution flows liên quan
+  Layer 1 — Tried-and-True:
+    → nmem_recall: Tìm similar problems đã giải quyết trong brain
+    → grep_search: Tìm existing utils/patterns trong codebase
+  Layer 2 — New-and-Popular:
+    → Tìm thư viện/SDK chuẩn ngành cho problem này
+    → Ưu tiên well-maintained, community-backed solutions
+  Layer 3 — First-Principles:
+    → CHỈ build from scratch khi Layer 1+2 không có solution phù hợp
+    → Ghi lý do tại sao existing solutions không đáp ứng
+
+  ⚠️ KHÔNG được skip layers! Log kết quả search vào progress report.
+
+ACTION:
+  → Nếu chưa có → Claim task tiếp theo: symphony_claim_task
+  → Code THEO TICKET, THEO DESIGN DOC, THEO search results
+  → Nếu phát hiện cần sửa schema khác design → ⛔ DỪNG:
+    "Schema change ngoài approved design detected. 
+     Quay lại Gate 2 để cập nhật design doc."
+  → Complete ticket → symphony_complete_task
+```
+
+### Gate 5: Verification 🔵
+
+```
+ACTION: Auto-trigger sau mỗi Gate 4 completion
+  → verification-gate skill (evidence before claims)
+  → Boil-the-Lake checklist (completeness check)
+  → code-review skill (nếu task phức tạp)
+  → Đối chiếu: code thực tế vs design doc
+  → OK → Task done → Auto-Next (TP4 in symphony-enforcer)
+```
+
+---
+
+## 🔀 STEP 3: Slash Command Detection (Giữ lại)
+
+Nếu user dùng slash command rõ ràng → Load workflow file trực tiếp, SKIP triage.
 
-### 1. Slash Command Detection
 ```
 User input starts with `/` → Load workflow file directly
   /plan     → workflows/lifecycle/plan.md
   /code     → workflows/lifecycle/code.md
   /debug    → workflows/lifecycle/debug.md
-  ...etc (see GEMINI.md § 2)
+  /brainstorm → brainstorm-agent skill
+  ...etc (see GEMINI.md)
 ```
 
-### 2. Intent Detection (No slash command)
+> **Note:** Slash commands bypass triage vì user ĐÃ BIẾT mình cần gì.
+
+---
+
+## 🧠 STEP 4: Intent Detection (Fallback)
+
+Nếu KHÔNG phải slash command VÀ triage chưa rõ:
+
 ```yaml
 code_intent:
-  keywords: ["implement", "build", "create", "add", "code", "fix", "viết", "tạo"]
-  action: Suggest `/code` or `/codeExpert`
+  keywords: ["implement", "build", "create", "add", "code", "fix", "viết", "tạo", "làm"]
+  action: Run triage → route theo complexity
 
 debug_intent:
-  keywords: ["error", "bug", "crash", "fix", "lỗi", "sửa", "fail"]
-  action: Suggest `/debug` or `/debugExpert`
+  keywords: ["error", "bug", "crash", "fix", "lỗi", "sửa", "fail", "broken"]
+  action: systematic-debugging skill (bypass spec gates — debugging is reactive)
 
 plan_intent:
   keywords: ["plan", "design", "architect", "how to", "strategy", "thiết kế"]
-  action: Suggest `/plan` or `/planExpert`
+  action: Suggest Gate 1-2 flow
+
+brainstorm_intent:
+  keywords: ["brainstorm", "ý tưởng", "idea", "nên làm gì", "what should"]
+  action: brainstorm-agent skill
 
 context_intent:
   keywords: ["remember", "save", "continue", "where was I", "nhớ", "tiếp"]
-  action: Suggest `/recap` or `/save-brain`
+  action: Suggest /recap or /save-brain
 
-ads_intent:
-  keywords: ["ads", "campaign", "CPI", "ROAS", "quảng cáo"]
-  action: Suggest `/ads-audit` or `/adsExpert`
+refactor_intent:
+  keywords: ["refactor", "rename", "extract", "split", "move", "restructure", "blast radius", "impact"]
+  action: gitnexus-intelligence skill (impact analysis + safe refactoring)
 ```
 
-### 3. Skill Pack Check
+---
+
+## 🗣️ Communication Style
+
+Orchestrator KHÔNG nói giọng máy móc. Dùng giọng đồng nghiệp senior:
+
+```
+❌ "ERROR: Gate 1 not satisfied. Spec document missing."
+✅ "Ý tưởng rất hay! Kinh nghiệm cho thấy nếu không chốt yêu cầu trước, 
+    sau sửa cực lắm. Để tôi hỏi vài câu rồi mình chốt spec nhé?"
+
+❌ "Gate 2 failed. Architecture document required."  
+✅ "Đã hiểu yêu cầu rồi. Giờ để tôi phác thảo cấu trúc database 
+    cho anh xem trước — tránh kiểu vừa làm vừa đập đi xây lại."
+
+❌ "Execution blocked. No Symphony task found."
+✅ "Design ngon rồi! Giờ tôi bẻ ra thành 5 task nhỏ trên Symphony 
+    để track tiến độ nhé."
 ```
-If user request involves iOS-specific → Check if mobile-ios pack enabled
-If not enabled → Suggest: "awf enable-pack mobile-ios"
+
+---
+
+## 🚫 Anti-Patterns
+
+```yaml
+never_do:
+  - Cho phép code COMPLEX task mà chưa qua Gate 1-2
+  - Tự ý thêm cột DB ngoài approved design
+  - Hỏi "Bạn muốn chạy workflow nào?" — AI phải TỰ QUYẾT
+  - Tạo Symphony tickets trước khi có design doc (Gate 3 cần Gate 2)
+  - Force user qua 5 Gates cho trivial tasks
+  - Code mới mà chưa search existing solution (Search Before Building)
+  - Đồng ý approach có vấn đề mà không push back (Anti-sycophancy)
+  - Skip edge cases / error handling vì "trivial" (Boil the Lake)
+
+always_do:
+  - Hiển thị triage result trước mọi action
+  - Thông báo đang ở Gate nào khi chặn
+  - Giữ giọng thân thiện, giải thích LÝ DO chặn
+  - Cho phép user override gate: "skip gates" hoặc "bỏ qua"
+  - Re-check gates sau mỗi lần user provide input
+  - Search NeuralMemory + codebase TRƯỚC khi code mới
+  - Report DONE_WITH_CONCERNS nếu có caveats (Completion Status)
+  - Escalate sau 3 failed attempts (3-Strike Rule)
 ```
 
-### 4. Fallback
+---
+
+## 🔗 Skill Relationships
+
 ```
-No match → Ask clarifying question (max 2 times)
-Still unclear → Suggest `/help`
+DELEGATES TO:
+  Gate 1 → brainstorm-agent (phỏng vấn → BRIEF.md)
+  Gate 2 → spec-gate (thiết kế DB/API → design doc)
+  Gate 3 → symphony-enforcer (tạo + track tasks)
+  Gate 4 → relevant coding workflow (/code, /codeExpert)
+  Gate 5 → verification-gate + code-review
+
+WORKS WITH:
+  nm-memory-sync (đọc context từ NeuralMemory)
+  awf-session-restore (restore state)
+  symphony-orchestrator (đảm bảo Symphony server running)
+  gitnexus-intelligence (architectural awareness trước khi code)
+
+DOES NOT:
+  Execute code trực tiếp (delegates to workflows)
+  Modify files (chỉ route + enforce gates)
 ```
 
-## Auto-Activation
-This skill is always active. It runs as the first layer before any other processing.
+---
+
+## 🧩 Edge Cases
+
+| Tình huống | Xử lý |
+|-----------|--------|
+| User nói "skip gates" / "bỏ qua" | Cho phép bypass, ghi cảnh báo |
+| Feature đã có partial spec | Gate 1 pass, check Gate 2 |
+| Debug request | Bypass spec gates — debugging is reactive |
+| User follow-up nhỏ sau feature done | Re-triage — thường TRIVIAL |
+| Multiple features cùng lúc | Triage TỪNG feature riêng |
+| Spec tồn tại nhưng outdated | Cảnh báo "Spec cũ, cần update?" |
+| Project chưa có docs/ folder | Tạo folder structure tự động |
+
+---
+
+*orchestrator v2.0 — Autonomous State Machine Gatekeeper for AWKit*

package/skills/press-and-pr/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: press-and-pr
+description: When the user wants to get press coverage, media mentions, or editorial features for their app — including writing press releases, pitching journalists, getting on "best apps" lists, or building an app press kit. Use when the user mentions "press", "PR", "media coverage", "TechCrunch", "journalist", "press release", "app press kit", "get featured in media", "editorial coverage", "review from a blogger", or "app launch announcement". For Apple editorial featuring, see app-store-featured. For launch strategy, see app-launch.
+metadata:
+  version: 1.0.0
+---
+
+# Press & PR for Apps
+
+You help indie developers and app teams get genuine media coverage — which drives installs, backlinks, and App Store credibility.
+
+## Why Press Still Matters
+
+- **Web referral** in App Store Connect directly tracks installs from press links
+- **Backlinks** from high-authority sites (TechCrunch, The Verge) improve web presence
+- **Social proof** — "As seen on…" on your product page improves conversion
+- **Apple editorial** — press coverage increases editorial featuring consideration
+- **Organic amplification** — articles get shared, creating discovery beyond the original publication
+
+## Target Media Tiers
+
+### Tier 1 — High impact, harder to get
+
+| Publication | Focus | Notes |
+|-------------|-------|-------|
+| TechCrunch | Consumer tech, startups | Exclusives preferred |
+| The Verge | Consumer tech | Curated; quality bar is high |
+| Wired | Tech culture | Long-form, unique angle needed |
+| Fast Company | Innovation, productivity | Strong business angle |
+| 9to5Mac | iOS/macOS apps | App-specific, accessible |
+| MacStories | iOS apps | Very accessible for indie devs |
+
+### Tier 2 — Accessible, meaningful reach
+
+| Type | Examples |
+|------|---------|
+| App review blogs | AppAdvice, TouchArcade (games), AppShopper |
+| Niche newsletters | App-specific verticals (health, productivity, finance newsletters) |
+| YouTube channels | AppFind, MKBHD (for significant apps), niche channels |
+| Podcasts | App podcast appearances, niche shows |
+
+### Tier 3 — Start here
+
+| Type | Examples |
+|------|---------|
+| Reddit | r/iphone, r/androidapps, r/productivity (category-specific) |
+| Product Hunt | Launch day visibility |
+| Hacker News | Show HN post for technical/productivity apps |
+| Indie hackers | For indie developer community coverage |
+
+## What Makes a Story
+
+Press doesn't cover apps — they cover **stories**. Find your angle:
+
+| Angle | Example |
+|-------|---------|
+| **Numbers** | "App hit 100K downloads in 7 days with no marketing" |
+| **Problem solved** | "Solo dev built X because no existing tool did Y" |
+| **Unique data** | "Our app analyzed 10M habit logs — here's what we learned" |
+| **Category creation** | "We invented a new category of [type] app" |
+| **David vs Goliath** | Indie beating a Big Tech competitor |
+| **Timely** | Tied to a current news trend or cultural moment |
+| **Human story** | Founder's compelling personal motivation |
+
+**Test your angle:** Can you explain the story in 1 sentence that would make someone say "interesting"?
+
+## Press Kit
+
+Create a `presskit/` folder on your website or a Notion page with:
+
+```
+Press Kit Contents:
+- [ ] App name, one-liner, category
+- [ ] 3 founder photos (high-res, print-quality)
+- [ ] App icon (1024×1024px, PNG)
+- [ ] 5–10 screenshots (phone mockups, high-res)
+- [ ] App preview video (optional but impactful)
+- [ ] 3-sentence company/founder bio
+- [ ] Key stats (downloads, ratings, notable users)
+- [ ] Press quotes / prior coverage (if any)
+- [ ] App Store link + website
+- [ ] Press contact email
+```
+
+Host at: `yoursite.com/press` or a publicly shared Notion/Google Drive link.
+
+## Press Release Structure
+
+```
+FOR IMMEDIATE RELEASE
+
+[Headline — most newsworthy fact as a statement]
+[Subheadline — supporting detail]
+
+[City, Date] — [Hook sentence: what happened and why it matters]
+
+[Paragraph 1: The news — who, what, when, where]
+
+[Paragraph 2: The why — problem being solved, backstory, unique approach]
+
+[Paragraph 3: A quote from the founder]
+"[Quote that adds voice, not just restates facts]" — [Name], [Title], [Company]
+
+[Paragraph 4: Key features or data points — 3 max]
+
+[Paragraph 5: Availability, pricing, platforms]
+[App Name] is available on [iOS/Android/both] for [free/price]. Download at [App Store link].
+
+###
+
+About [Company]:
+[2–3 sentences]
+
+Media Contact:
+[Name] | [email] | [phone optional]
+```
+
+## Pitching Journalists
+
+### The Cold Pitch Email
+
+```
+Subject: [App Name] — [your angle in 8 words]
+e.g., "Habitica clone reached #1 Health with zero ad spend"
+
+Hi [First name],
+
+[1 sentence: why you're reaching out to them specifically]
+e.g., "I read your piece on [recent article] — [App Name] is related."
+
+[1 sentence: what the app does]
+[1 sentence: the story angle / most interesting stat or fact]
+[1 sentence: why now / why timely]
+
+Happy to send a promo code, press kit, or get on a quick call.
+
+[Your name]
+[App Store link]
+[Press kit link]
+```
+
+**Rules:**
+- Max 5 sentences in the pitch
+- Personalize the first line for each journalist — no mass blast
+- Don't attach files — link to your press kit
+- Send Tuesday–Thursday, 8–10am recipient's timezone
+- Follow up once after 5 business days — then move on
+
+### Finding the Right Journalists
+
+1. Search the target publication for recent app reviews in your category
+2. Note the byline — pitch that specific writer
+3. Check their Twitter/X bio for DM preference
+4. Use tools like Hunter.io for email guessing (format: first@publication.com)
+
+## Embargo Strategy
+
+For major launches, offer an embargo:
+
+- Contact journalists 1–2 weeks before launch
+- Offer exclusive access under embargo (story publishes on launch day)
+- One journalist per tier (don't offer the same exclusive to two competing outlets)
+- Provide TestFlight / Play beta access
+
+Exclusives dramatically increase pickup from Tier 1 publications.
+
+## Product Hunt Launch
+
+| Step | When | Action |
+|------|------|--------|
+| Create coming soon | 2 weeks before | Enable "coming soon" to collect followers |
+| Find a hunter | 1 week before | Ask an influential PH user to "hunt" you |
+| Prepare assets | 3 days before | Gallery, tagline, description, first comment |
+| Launch day | Tuesday–Thursday | Ship at 12:01am PST; all-day community engagement |
+| Follow-up post | Launch + 1 week | Share results as a Show HN or maker story |
+
+## Output Format
+
+### PR Plan
+
+```
+Story angle: [one sentence]
+
+Media targets:
+  Tier 1: [publication + journalist name]
+  Tier 2: [2–3 blogs/newsletters]
+  Tier 3: Product Hunt, Reddit r/[category], HN
+
+Timeline:
+  T-14: Press kit ready, press release drafted
+  T-10: Embargo pitches sent to Tier 1
+  T-7:  Follow-ups + Tier 2 pitches
+  T-0:  Launch + Product Hunt + Tier 3 posts
+  T+3:  Thank reporters who covered, share articles
+
+Press kit: [link]
+Press contact: [email]
+```
+
+## Related Skills
+
+- `app-launch` — Full launch strategy (PR is one channel within it)
+- `app-store-featured` — Press coverage supports Apple editorial consideration
+- `ua-campaign` — Complement PR with paid UA on launch week