@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/skills/game-development/spec-ecosystem/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: spec-ecosystem
+description: Comprehensive spec writing system for game development. Templates, decision logging, and structured documentation. Use when creating game specifications, plans, or task breakdowns.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Game Spec Ecosystem Skill
+
+> **Purpose:** Provide structured templates and workflows for professional game development documentation.
+
+---
+
+## When to Use This Skill
+
+| Scenario | Action |
+|----------|--------|
+| Starting new game project | Use `/gamekit.init` |
+| Writing game specification | Use `/gamekit.spec` + templates |
+| Creating implementation plan | Use `/gamekit.plan` + templates |
+| Breaking down into tasks | Use `/gamekit.tasks` |
+
+---
+
+## 4-Layer Documentation System
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  LAYER 4: SESSION STATE (Real-time)                      │
+│  → .agent/memory/session.json, SESSION_SUMMARY.md        │
+├──────────────────────────────────────────────────────────┤
+│  LAYER 3: DECISION LOG (Q&A History)                     │
+│  → .agent/memory/decisions.md, .agent/adr/ADR-xxx.md     │
+├──────────────────────────────────────────────────────────┤
+│  LAYER 2: SPEC & PLAN (Static)                           │
+│  → SPEC-{game}.md, PLAN-{game}.md, TASKS-{game}.md       │
+├──────────────────────────────────────────────────────────┤
+│  LAYER 1: CONSTITUTION & CHANGELOG (Foundation)          │
+│  → constitution.md, CHANGELOG.md, VERSION.md             │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Document Types
+
+### SPEC (Specification)
+**Purpose:** Define WHAT and WHY
+**Contains:** Problem, User Stories, Acceptance Criteria, Out of Scope, Constraints
+**Template:** See `templates/SPEC-template.md`
+
+### PLAN (Implementation Plan)
+**Purpose:** Define HOW and WHO
+**Contains:** File structure, Task breakdown, Agent assignments, Dependencies
+**Template:** See `templates/PLAN-template.md`
+
+### TASKS (Task List)
+**Purpose:** Executable checklist
+**Contains:** Ordered tasks with status, verification criteria
+**Template:** See `templates/TASKS-template.md`
+
+### DECISIONS (Decision Log)
+**Purpose:** Record all Q&A with rationale
+**Contains:** Questions, Answers, Reasoning, Technical Impact
+**Template:** See `decision-log-format.md`
+
+---
+
+## Workflow Integration
+
+```
+/gamekit.init
+     │
+     ▼
+constitution.md (Project principles)
+     │
+     ▼
+/gamekit.spec (Use explained-qa skill)
+     │
+     ▼
+SPEC-{game}.md ──────┬──────── decisions.md
+     │               │
+     ▼               │ (logged)
+/gamekit.plan        │
+     │               │
+     ▼               │
+PLAN-{game}.md ──────┘
+     │
+     ▼
+/gamekit.tasks
+     │
+     ▼
+TASKS-{game}.md
+     │
+     ▼
+/game-hybrid (Implementation)
+```
+
+---
+
+## Naming Conventions
+
+| Document | Naming Pattern | Example |
+|----------|----------------|---------|
+| Specification | `SPEC-{game-slug}.md` | `SPEC-dungeon-crawler.md` |
+| Plan | `PLAN-{game-slug}.md` | `PLAN-dungeon-crawler.md` |
+| Tasks | `TASKS-{game-slug}.md` | `TASKS-dungeon-crawler.md` |
+| Decisions | `decisions.md` (single file) | Append per session |
+| ADR | `ADR-{number}-{short-title}.md` | `ADR-001-use-ecs.md` |
+
+---
+
+## Quality Gates
+
+### Before SPEC Approval
+- [ ] Problem statement has measurable impact
+- [ ] All user stories have clear benefits
+- [ ] Acceptance criteria are testable
+- [ ] Out of scope section exists
+- [ ] No implementation details in SPEC
+
+### Before PLAN Approval
+- [ ] All tasks have INPUT → OUTPUT → VERIFY
+- [ ] Dependencies are explicit
+- [ ] Agent assignments are correct
+- [ ] File structure is complete
+- [ ] Phase X verification defined
+
+### Before Implementation
+- [ ] SPEC approved by user
+- [ ] PLAN approved by user
+- [ ] All decisions logged
+- [ ] No blocking questions remain
+
+---
+
+## Integration with Existing Workflows
+
+| Existing Workflow | Integration Point |
+|-------------------|-------------------|
+| `/game-from-idea` | Phase 1 uses `explained-qa` for ideation |
+| `/game-hybrid` | Tier 1 Macro Spec uses SPEC template |
+| `/brainstorm` | Uses `explained-qa` for all game questions |
+| `/spec` | Extended by `gamekit.spec` for games |
+
+---
+
+## Anti-Patterns (AVOID)
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Skip SPEC, jump to code | Always SPEC → PLAN → CODE |
+| Put HOW in SPEC | SPEC = WHAT, PLAN = HOW |
+| Forget decision log | Log EVERY significant decision |
+| Use generic templates | Use game-specific templates |
+| Start without constitution | Define principles first |

package/.agent/skills/game-development/spec-ecosystem/decision-log-format.md

@@ -0,0 +1,129 @@
+# Decision Log Format
+
+> Format for recording all Q&A decisions during game development.
+> Append to `.agent/memory/decisions.md` after each session.
+
+---
+
+## Purpose
+
+1. **Prevent re-asking** - AI reads this before asking questions
+2. **Preserve rationale** - Future developers understand WHY
+3. **Enable handoff** - New team members understand decisions
+4. **Support rollback** - If decision needs reverting, context is preserved
+
+---
+
+## File Location
+
+```
+.agent/memory/decisions.md
+```
+
+---
+
+## Entry Format
+
+```markdown
+## Session: [YYYY-MM-DD]
+
+### Q[N]: [Topic Title]
+- **Câu hỏi:** [Original technical question]
+- **Giải thích:** [Analogy/explanation provided to user]
+- **Trả lời:** [User's choice - A/B/C or custom]
+- **Lý do:** "[User's reasoning, quoted if provided]"
+- **Ảnh hưởng:** [Technical impact on project]
+
+---
+```
+
+---
+
+## Example Entries
+
+```markdown
+## Session: 2026-01-29
+
+### Q1: Timestep Mode
+- **Câu hỏi:** Fixed Timestep hay Variable Timestep?
+- **Giải thích:** Như đồng hồ cơ (fixed) vs nhịp tim (variable)
+- **Trả lời:** A (Fixed Timestep)
+- **Lý do:** "Game này có multiplayer, cần công bằng"
+- **Ảnh hưởng:** Sử dụng FixedUpdate() cho physics, Time.fixedDeltaTime = 0.02f
+
+---
+
+### Q2: Art Style
+- **Câu hỏi:** Phong cách đồ họa?
+- **Giải thích:** Pixel Art vs Vector vs 3D Low-Poly
+- **Trả lời:** Pixel Art
+- **Lý do:** "Muốn retro vibe, team quen làm pixel"
+- **Ảnh hưởng:** Texture Import = Point Filter, Pixels Per Unit = 16
+
+---
+
+### Q3: Save System
+- **Câu hỏi:** PlayerPrefs hay JSON file?
+- **Giải thích:** Post-it note (PlayerPrefs) vs Hồ sơ (JSON)
+- **Trả lời:** C (Để AI quyết định)
+- **AI quyết định:** JSON vì game có inventory phức tạp
+- **Ảnh hưởng:** Sử dụng JsonUtility + Application.persistentDataPath
+
+---
+
+## Session: 2026-01-30
+
+### Q4: Monetization Model
+- **Câu hỏi:** F2P với ads, IAP, hay Premium?
+- **Giải thích:** Miễn phí xem quảng cáo vs Mua đồ vs Mua game 1 lần
+- **Trả lời:** F2P với Rewarded Ads
+- **Lý do:** "Thị trường mobile casual phù hợp F2P"
+- **Ảnh hưởng:** Integrate Unity Ads, design reward structures
+
+---
+```
+
+---
+
+## AI Reading Protocol
+
+Before asking ANY question, AI MUST:
+
+1. **Read** `.agent/memory/decisions.md`
+2. **Check** if topic already decided
+3. **If decided** → Use existing decision, don't re-ask
+4. **If not decided** → Ask using `explained-qa` format
+
+```markdown
+🔍 **Checking decisions.md...**
+- Timestep: ✅ Fixed (Q1)
+- Art Style: ✅ Pixel Art (Q2)
+- Save System: ✅ JSON (Q3)
+- Monetization: ✅ F2P + Rewarded Ads (Q4)
+- Multiplayer: ❓ Not decided yet → ASKING...
+```
+
+---
+
+## Categories for Organization
+
+| Category | Topics |
+|----------|--------|
+| **Architecture** | Timestep, ECS vs OOP, Event system |
+| **Art** | Style, resolution, animation |
+| **Audio** | Music style, SFX approach |
+| **Gameplay** | Core loop, difficulty, progression |
+| **Technical** | Engine, platform, performance targets |
+| **Business** | Monetization, analytics, launch strategy |
+
+---
+
+## Integration Points
+
+| Workflow/Skill | How It Uses decisions.md |
+|----------------|--------------------------|
+| `/gamekit.spec` | Appends decisions during spec creation |
+| `/game-from-idea` | Records ideation choices |
+| `/game-hybrid` | Records architecture decisions in Tier 1 |
+| `explained-qa` | Logs every answered question |
+| `project-planner` | Reads to understand context |

package/.agent/skills/game-development/spec-ecosystem/templates/PLAN-template.md

@@ -0,0 +1,178 @@
+# PLAN Template for Game Projects
+
+> Template for creating implementation plans from approved specs. Replace placeholders with actual content.
+
+---
+
+## 📋 Overview
+
+[Brief description of what this plan implements, referencing the SPEC.]
+
+**Based on:** `SPEC-{game-slug}.md`
+**Project Type:** [MOBILE / WEB / PC / VR-AR]
+
+---
+
+## ✅ Success Criteria
+
+| # | Criterion | Verification Method |
+|---|-----------|---------------------|
+| 1 | [From SPEC AC1] | [How to verify] |
+| 2 | [From SPEC AC2] | [How to verify] |
+| 3 | [From SPEC AC3] | [How to verify] |
+
+---
+
+## 🛠️ Tech Stack
+
+| Component | Technology | Rationale |
+|-----------|------------|-----------|
+| **Engine** | [Unity/Godot/etc] | [Why chosen] |
+| **Language** | [C#/GDScript/etc] | [Why chosen] |
+| **Backend** | [Firebase/Supabase/None] | [Why chosen] |
+| **Analytics** | [Firebase/GameAnalytics/etc] | [Why chosen] |
+
+---
+
+## 📁 File Structure
+
+```
+Assets/
+├── _Project/
+│   ├── Scripts/
+│   │   ├── Core/          # Managers, Events, Utils
+│   │   ├── Gameplay/      # Game mechanics
+│   │   ├── UI/            # UI controllers
+│   │   └── Input/         # Input handling
+│   ├── Prefabs/
+│   ├── Scenes/
+│   │   ├── Bootstrap.unity
+│   │   ├── MainMenu.unity
+│   │   └── Game.unity
+│   └── ScriptableObjects/
+│       ├── Config/
+│       └── Data/
+├── Art/
+│   ├── Sprites/
+│   ├── UI/
+│   └── Animations/
+├── Audio/
+│   ├── Music/
+│   └── SFX/
+└── Addressables/
+```
+
+---
+
+## 📊 Task Breakdown
+
+### Phase 1: Core Systems
+
+| Task ID | Name | Agent | Priority | Dependencies | INPUT → OUTPUT → VERIFY |
+|---------|------|-------|----------|--------------|-------------------------|
+| 1.1 | [Task name] | [agent] | P0 | None | [I] → [O] → [V] |
+| 1.2 | [Task name] | [agent] | P0 | 1.1 | [I] → [O] → [V] |
+
+### Phase 2: Gameplay
+
+| Task ID | Name | Agent | Priority | Dependencies | INPUT → OUTPUT → VERIFY |
+|---------|------|-------|----------|--------------|-------------------------|
+| 2.1 | [Task name] | [agent] | P1 | 1.x | [I] → [O] → [V] |
+| 2.2 | [Task name] | [agent] | P1 | 2.1 | [I] → [O] → [V] |
+
+### Phase 3: UI & Polish
+
+| Task ID | Name | Agent | Priority | Dependencies | INPUT → OUTPUT → VERIFY |
+|---------|------|-------|----------|--------------|-------------------------|
+| 3.1 | [Task name] | [agent] | P2 | 2.x | [I] → [O] → [V] |
+| 3.2 | [Task name] | [agent] | P2 | 3.1 | [I] → [O] → [V] |
+
+### Phase 4: Audio & Effects
+
+| Task ID | Name | Agent | Priority | Dependencies | INPUT → OUTPUT → VERIFY |
+|---------|------|-------|----------|--------------|-------------------------|
+| 4.1 | [Task name] | [agent] | P2 | None | [I] → [O] → [V] |
+
+---
+
+## 🔀 Parallel Execution Groups
+
+```
+GROUP A (Core - Sequential):
+├── 1.1 [First task]
+└── 1.2 [Depends on 1.1]
+
+GROUP B (Can parallel with A):
+├── Art assets
+└── Audio assets
+
+GROUP C (After A):
+├── 2.1 Gameplay
+└── 2.2 Features
+
+GROUP D (Final):
+├── 3.x UI Polish
+└── 4.x Audio integration
+```
+
+---
+
+## ⚡ Agent Assignments Summary
+
+| Agent | Tasks | Total |
+|-------|-------|-------|
+| `unity-mobile-master` | [list] | X |
+| `game-developer` | [list] | X |
+| `ai-asset-factory` | [list] | X |
+| `ai-audio-factory` | [list] | X |
+
+---
+
+## Phase X: Verification
+
+### Build Check
+```bash
+# Unity build
+Unity -batchmode -buildTarget Android -executeMethod BuildScript.BuildAndroid
+
+# Or Godot export
+godot --export-release "Android" ./builds/game.apk
+```
+
+### Automated Tests
+- [ ] Unit tests pass
+- [ ] Integration tests pass
+- [ ] No compiler warnings
+
+### Manual Verification
+- [ ] Core loop playable
+- [ ] No game-breaking bugs
+- [ ] Performance target met (60 FPS)
+- [ ] Device testing (low-end + high-end)
+
+### Regression Check
+- [ ] All features from SPEC work
+- [ ] Audio plays correctly
+- [ ] Save/Load works
+
+---
+
+## ✅ PHASE X COMPLETION MARKER
+
+> Add after all checks pass:
+```
+## ✅ PHASE X COMPLETE
+- Build: Success
+- Tests: All pass
+- Performance: 60 FPS on target device
+- Date: [Current Date]
+```
+
+---
+
+## ✅ Approval
+
+> [!IMPORTANT]
+> Plan này cần được User approve trước khi bắt đầu Implementation.
+
+**Approved by:** [Name/Date]

package/.agent/skills/game-development/spec-ecosystem/templates/SPEC-template.md

@@ -0,0 +1,110 @@
+# SPEC Template for Game Projects
+
+> Template for creating game specifications. Replace placeholders with actual content.
+
+---
+
+## 📝 Problem Statement
+
+### Vấn đề hiện tại
+[Describe the problem this game/feature solves. Include measurable impact if available.]
+
+**Example:**
+> Người chơi mobile thường bỏ game casual sau 3-5 phút vì gameplay lặp lại. 
+> Cần game có core loop hấp dẫn giữ người chơi ít nhất 15 phút/session.
+
+---
+
+## 👥 User Stories
+
+| Priority | User Story |
+|----------|------------|
+| **P0** | Là **[user type]**, tôi muốn **[action]** để **[benefit]**. |
+| **P1** | Là **[user type]**, tôi muốn **[action]** để **[benefit]**. |
+| **P2** | Là **[user type]**, tôi muốn **[action]** để **[benefit]**. |
+
+**Example:**
+| Priority | User Story |
+|----------|------------|
+| **P0** | Là **người chơi casual**, tôi muốn **gameplay one-hand** để **chơi trên bus/metro**. |
+| **P1** | Là **người chơi**, tôi muốn **xem tiến độ rõ ràng** để **biết mình đang ở đâu**. |
+
+---
+
+## ✅ Acceptance Criteria
+
+| ID | Criterion | Testable? |
+|----|-----------|-----------|
+| AC1 | [Specific, measurable criterion] | ✅/❌ |
+| AC2 | [Specific, measurable criterion] | ✅/❌ |
+| AC3 | [Specific, measurable criterion] | ✅/❌ |
+
+**Example:**
+| ID | Criterion | Testable? |
+|----|-----------|-----------|
+| AC1 | Game load trong < 3 giây trên device 2GB RAM | ✅ |
+| AC2 | Tutorial hoàn thành trong < 60 giây | ✅ |
+| AC3 | Core loop rõ ràng: Action → Reward → Progression | ✅ |
+
+---
+
+## 🚫 Out of Scope
+
+| Item | Lý do |
+|------|-------|
+| [Feature NOT included] | [Why deferred] |
+| [Edge case NOT handled] | [Why excluded] |
+| [Platform NOT supported] | [Why not MVP] |
+
+**Example:**
+| Item | Lý do |
+|------|-------|
+| Multiplayer | Quá phức tạp cho MVP, xem xét v2 |
+| Cloud save | Chỉ cần local save cho prototype |
+| IAP | Chưa cần monetization cho soft launch |
+
+---
+
+## 🔧 Technical Constraints
+
+| Constraint | Requirement |
+|------------|-------------|
+| **Target Platform** | [iOS/Android/Web/PC] |
+| **Engine** | [Unity/Godot/Phaser] |
+| **Min Spec** | [Device requirements] |
+| **Integration** | [Must work with X] |
+
+**Example:**
+| Constraint | Requirement |
+|------------|-------------|
+| **Target Platform** | Android 8+ & iOS 14+ |
+| **Engine** | Unity 6 LTS |
+| **Min Spec** | 2GB RAM, GPU OpenGL ES 3.0 |
+| **Integration** | Firebase Analytics |
+
+---
+
+## 🎮 Game-Specific Details
+
+### Core Loop
+```
+[Action] → [Reward] → [Progression]
+```
+
+### Art Direction
+[Brief description of visual style]
+
+### Audio Direction
+[Brief description of sound/music style]
+
+### Monetization (if applicable)
+[F2P/Premium/Hybrid + high-level strategy]
+
+---
+
+## ✅ Approval
+
+> [!IMPORTANT]
+> Spec này cần được User approve trước khi chuyển sang PLAN.
+
+**Approved by:** [Name/Date]