Iron Forge Documentation

Superpowers

Bộ 14 skills workflow hoàn chỉnh cho coding agents. Biến AI thành đồng đội viết code có kỷ luật, có quy trình, có chất lượng.

14

Skills

84.1k

GitHub Stars

6+

Platforms

Tác giả: Jesse Vincent (obra) | GitHub Repository | v5.0.2 (Mar 2026)

Chương 1: Giới thiệu Superpowers

Superpowers là gì?

Superpowers là một complete software development workflow (quy trình phát triển phần mềm hoàn chỉnh) dành cho coding agents. Nó không chỉ là tập hợp lệnh - mà là một hệ thống tư duy mang tính kỷ luật, được thiết kế để AI agent làm việc như một lập trình viên chuyên nghiệp.

Khi bạn kích hoạt Superpowers, agent sẽ không nhảy vào viết code ngay. Thay vào đó, nó sẽ:

1. Hỏi bạn đang thực sự muốn làm gì (Brainstorming)
2. Đề xuất 2-3 phương án và recommend (Thiết kế)
3. Lập kế hoạch chi tiết từng bước nhỏ 2-5 phút (Planning)
4. Giao nhiệm vụ cho subagent thực thi, review 2 giai đoạn (Execution)
5. Tự động verify mọi claim trước khi báo "xong" (Verification)

Tại sao 84k stars chỉ với 14 skills?

Triết lý cốt lõi

Cài đặt trên các Platform

Platform	Cách cài
Claude Code (Official)	/plugin install superpowers@claude-plugins-official
Claude Code (Custom)	/plugin marketplace add obra/superpowers-marketplace rồi /plugin install superpowers@superpowers-marketplace
Cursor	/add-plugin superpowers hoặc search "superpowers" trong plugin marketplace
Gemini CLI	gemini extensions install https://github.com/obra/superpowers
Codex	Nói với Codex: "Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md"
OpenCode	Native skill discovery via ~/.agents/skills/superpowers/ symlink

Sau khi cài, bạn không cần làm gì đặc biệt. Skills tự kích hoạt khi agent nhận ra context phù hợp. Verify bằng cách yêu cầu agent: "help me plan this feature" hoặc "let's debug this issue".

Chương 2: The Core Workflow - 7 bước chính

Đây là "happy path" (luồng chính) khi bạn yêu cầu Superpowers xây dựng một tính năng mới. Mỗi bước tương ứng một skill cụ thể, và agent tự động kích hoạt skill phù hợp:

Chương 3: brainstorming - Thiết kế trước khi code

Brainstorming là skill bắt buộc trước bất kỳ creative work nào. "Creative work" bao gồm: tính năng mới, thay đổi architecture, refactor lớn, hoặc bất kỳ thay đổi nào cần thiết kế.

Quy trình chi tiết (7 bước)

Bước	Hành động	Chi tiết
1. Explore	Tìm hiểu context	Đọc codebase, hiểu constraints, xác định scope
2. One Question	Hỏi từng câu một	KHÔNG hỏi nhiều câu cùng lúc. Mỗi câu phải dẫn đến insight mới.
3. Approaches	Đề xuất 2-3 hướng	Mỗi hướng có trade-offs rõ ràng. Recommend 1 hướng và giải thích WHY.
4. Present	Trình bày design theo sections	Từng phần một, không dump toàn bộ. Dùng diagrams khi cần.
5. Spec	Viết specification	Từ design → spec chi tiết. Đây là tài liệu chính để writing-plans dùng.
6. Review Loop	Spec review (max 5 vòng)	User review spec. Nếu feedback → sửa → review lại. Max 5 iterations.
7. Transition	User approve → writing-plans	Sau khi approve, chuyển sang planning. KHÔNG quay lại brainstorming.

Visual Companion (Trợ thủ trực quan)

Superpowers v5.0 thêm browser-based Visual Companion - một server nhẹ (zero-dependency, tự động tắt sau 30 phút idle) để hiển thị:

• Mockups: Wireframes, UI layouts, component placement
• Diagrams: Architecture diagrams, data flow, state machines
• Comparisons: So sánh 2-3 approaches bằng visual

Quy tắc: Chỉ dùng Visual Companion cho câu hỏi mang tính trực quan. Câu hỏi conceptual (ví dụ "nên dùng REST hay GraphQL?") → text là đủ.

Anti-Patterns - KHÔNG BAO GIỜ làm

Agent nghĩ...	Vấn đề
"Quá đơn giản, không cần design"	MỌI project đều cần design, dù là todo list hay config change. Simple ≠ trivial.
"User đã nói rõ, khỏi hỏi"	User biết WHAT, bạn phải tìm ra HOW. Hỏi để discover hidden constraints.
"Hỏi 5 câu cùng lúc cho nhanh"	User bị overwhelm. Mỗi câu trả lời thay đổi câu hỏi tiếp theo. One at a time.
"Viết code song song với design"	HARD-GATE violation. Code viết trong brainstorming sẽ bị delete.
"Đã approve approach, bắt đầu code"	Approve approach ≠ approve spec. Phải có written specification trước khi chuyển sang writing-plans.

Checklist trước khi chuyển sang Planning

• ☐ User đã approve approach (không chỉ "nghe hay đấy")
• ☐ Specification document đã viết đầy đủ
• ☐ Edge cases đã được identify
• ☐ Technical constraints đã rõ ràng
• ☐ Scope đã được bound (giới hạn) - biết rõ KHÔNG làm gì

Chương 4: writing-plans - Kế hoạch chi tiết

Plan trong Superpowers không phải "danh sách việc cần làm". Nó là blueprint chi tiết - giả định engineer đọc plan không có context, không có taste (thẩm mỹ code), không biết gì về project.

Cấu trúc Plan Document

Mỗi plan document bắt đầu bằng header bắt buộc:

# Implementation Plan: [Feature Name]
## Context
[Tóm tắt từ spec: mục tiêu, constraints, decisions đã đưa ra]

## Tasks
### Task 1: [Tên task mô tả]
**File:** `src/components/UserProfile.tsx`
**Test file:** `src/components/__tests__/UserProfile.test.tsx`

1. Viết test:
   ```typescript
   test('renders user name', () => { ... })
   ```
2. Chạy: `npm test -- UserProfile`
3. Verify: test FAILS với "Cannot find module"
4. Viết implementation: [code đầy đủ]
5. Chạy lại: `npm test -- UserProfile`
6. Verify: test PASSES
7. Commit: `git commit -m "feat: add UserProfile component"`

Quy tắc DRY, YAGNI, TDD trong Planning

Nguyên tắc	Áp dụng trong plan
DRY	Nếu 2 tasks tạo ra code tương tự → extract helper trong task riêng trước
YAGNI	Không có task nào "để sau có thể cần". Mỗi task phải giải quyết requirement hiện tại.
TDD	Mỗi task bắt đầu bằng test. Test file path + test code cụ thể. Không bao giờ skip.

Scope Check

Nếu spec quá lớn (nhiều subsystem độc lập), tách thành nhiều plan riêng biệt:

• Mỗi plan phải tạo ra working, testable software khi hoàn thành
• Plans thực thi theo thứ tự dependency
• Không bao giờ có plan "cleanup" cuối cùng - cleanup nằm ngay trong mỗi task (REFACTOR phase)

Plan Review Loop

Sau khi viết plan, bắt buộc review trước khi execute:

1. Agent tự review: tasks đúng thứ tự? Dependencies hợp lý? Có task nào quá lớn?
2. Present plan cho user (hoặc reviewer subagent)
3. Feedback → sửa plan → review lại
4. Approve → chuyển sang execution

Chương 5: subagent-driven-development - Giao việc cho subagent

Đây là "động cơ chính" (Core Engine) của Superpowers. Thay vì agent chính tự làm mọi thứ, nó đóng vai trò Controller - đọc plan, dispatch từng task cho fresh subagent, review kết quả.

Tại sao cần fresh subagent?

Vấn đề của 1 agent liên tục	Giải pháp subagent
Context dài → agent quên instruction	Fresh agent với task-specific context duy nhất
Sai ở task 3 → ảnh hưởng task 4+	Mỗi subagent độc lập, lỗi không lan truyền
Agent tự review code mình → thiên vị	Reviewer subagent không biết ai viết code

Quy trình Controller

1. Load plan - đọc plan document 1 lần, extract tất cả tasks
2. Dispatch task - tạo fresh subagent với prompt:

   You are implementing: [Task description]
   Project: [project context]
   Specification: [relevant spec section]
   File to modify: [exact path]
   Test to write first: [exact test code]
   Verification command: [exact command]
   IMPORTANT: Follow TDD - write test first, verify it fails,
   then implement, verify it passes.

3. Two-stage Review sau mỗi task (xem chi tiết bên dưới)
4. Handle status - dựa trên kết quả subagent
5. Dispatch next hoặc pause nếu có issue

Two-stage Review (Đánh giá 2 giai đoạn)

Task chỉ được coi là DONE khi pass cả 2 stage. Nếu fail ở stage nào → dispatch fix subagent → review lại.

Model Selection (Chọn model tự động)

Task type	Complexity	Model
Mechanical (rename, move, format)	1-2 files thay đổi	Cheap / fast model
Integration (connect APIs, wire components)	3-5 files	Standard model
Architecture / Review	Cross-cutting concerns	Most capable model

Status Protocol

Status	Ý nghĩa	Controller action
DONE	Task hoàn thành, tests pass	Dispatch next task
DONE_WITH_CONCERNS	Xong nhưng có vấn đề tiềm ẩn	Review concerns → quyết định fix hay tiếp
NEEDS_CONTEXT	Cần thêm thông tin	Cung cấp context → re-dispatch
BLOCKED	Không thể tiến hành	STOP. Escalate to user. Không đoán.

Fallback: executing-plans

Nếu platform không hỗ trợ subagent (ví dụ một số Codex setups), dùng executing-plans thay thế:

• Agent chính tự thực thi từng task trong plan
• Mỗi 3 tasks → tự review checkpoint
• Vẫn tuân thủ TDD cho mỗi task
• Stop ngay khi bị blocked, không đoán

dispatching-parallel-agents (Chạy song song)

Khi có 2+ independent problems (vấn đề hoàn toàn độc lập), dispatch nhiều agent song song:

Prompt Structure cho Parallel Agents

## Agent Prompt Template
1. Problem domain: [chỉ 1 domain cụ thể]
2. Files to investigate: [chỉ files trong domain]
3. Expected behavior: [output mong muốn]
4. Current behavior: [output hiện tại]
5. Rule: DO NOT modify files outside your domain
6. Rule: If you find root cause is OUTSIDE your domain, report BLOCKED

Chương 6: test-driven-development & systematic-debugging

test-driven-development (TDD)

Đây là skill nghiêm ngặt nhất trong Superpowers. "No exceptions" nghĩa là literally no exceptions:

• Utility function 1 dòng? Cần test.
• Bug fix thay đổi 1 ký tự? Cần test.
• Config change? Cần test.
• "Tôi chắc 100% nó hoạt động"? Cần test.

RED-GREEN-REFACTOR Cycle (Chi tiết)

Viết code trước test? Iron Law Response:

Master Rationalization Table cho TDD

Excuse (Lý do viện)	Reality (Thực tế)
"Quá đơn giản để test"	Code đơn giản vẫn break. Test viết mất 30 giây. Regression prevention miễn phí.
"Tôi sẽ test sau"	Tests viết sau = "code này làm gì?" Tests viết trước = "code này PHẢI làm gì?" → khác nhau hoàn toàn.
"Xóa X giờ code lãng phí"	Sunk cost fallacy. Code không đúng quy trình = nợ kỹ thuật. Xóa bây giờ rẻ hơn fix sau.
"TDD chậm quá"	TDD nhanh hơn debug. Tìm bug trước commit, prevent regression. Pragmatic = test-first.
"Giữ lại tham khảo rồi viết test trước"	Bạn sẽ adapt nó. Đó là testing-after với extra steps. Delete means delete.
"Emergency, no time"	Emergency = higher risk = MORE reason for TDD, not less.
"Test framework chưa setup"	Setup test framework IS the first task. BEFORE any production code.
"Code này chỉ là prototype"	Prototypes become production code. Always. Test it now.

verification-before-completion

Nói "xong" mà không verify = nói dối, không phải hiệu quả. Skill này thiết lập 5-step gate function:

Step	Action	Chi tiết
IDENTIFY	Xác định lệnh verify	Test command, build command, lint command - tuỳ context
RUN	Chạy lệnh	Chạy FRESH, không dùng cached results
READ	Đọc FULL output	Không scan lướt. Đọc từng dòng. Đặc biệt chú ý warnings.
VERIFY	Output khớp claim	"Tests pass" → phải thấy "X tests passed, 0 failed" trong output
CLAIM	Báo kết quả	CHỈ sau khi verify xong. Kèm evidence (dẫn chứng) cụ thể.

Red Flags - STOP ngay lập tức nếu thấy:

• Dùng từ "should", "probably", "seems to" khi mô tả kết quả
• Bày tỏ hài lòng trước khi verify: "Great!", "Perfect!", "Done!"
• Trust agent/subagent reports mà không verify independently
• Nói "tests pass" mà không ghi rõ bao nhiêu tests, output cụ thể
• Skip verification vì "đã test cái tương tự trước đó"

systematic-debugging (Debug có hệ thống)

Random fixes lãng phí thời gian và tạo bug mới. Quick patches che giấu vấn đề gốc. Superpowers chia debugging thành 4 phases bắt buộc:

Phase 1: Root Cause Investigation

• Đọc error message ACTUAL (không đoán từ tiêu đề)
• Reproduce bug (chạy lại → thấy lỗi) - nếu không reproduce được → chưa hiểu bug
• Check recent changes (git log --oneline -10, git diff HEAD~5)
• Trace data flow: Input → Processing → Output - chỗ nào sai?

Phase 2: Pattern Analysis

• Tìm working examples: cùng feature nhưng ở context khác hoạt động đúng
• Compare differences: code hoạt động vs code lỗi, khác nhau ở đâu?
• Check timing: bug xảy ra khi nào? Sau deploy? Sau update? Race condition?

Phase 3: Hypothesis and Testing

• Đặt giả thuyết CỤ THỂ: "Bug do X vì Y, chứng minh bằng Z"
• Test tối thiểu: 1 variable 1 thời điểm. KHÔNG đổi nhiều thứ cùng lúc
• Ghi kết quả: hypothesis đúng hay sai? Nếu sai → tại sao? → hypothesis mới

Phase 4: Implementation

• Tạo failing test reproduce bug (bắt buộc - bằng mã test, không phải manually)
• Implement single fix (1 thay đổi giải quyết root cause)
• Verify: test mới pass + KHÔNG break tests khác

Quy tắc 3 lần

Multiple fix cùng lúc?

KHÔNG BAO GIỜ. Fix nhiều thứ cùng lúc → nếu pass, bạn không biết fix nào thực sự cần thiết. Nếu fail, bạn không biết fix nào gây vấn đề mới. 1 fix = 1 test = 1 commit.

Chương 7: Code Review - Đánh giá code nghiêm túc

Code review trong Superpowers chia thành 2 skills: requesting (yêu cầu review) và receiving (nhận feedback). Cả hai đều có quy trình nghiêm ngặt.

requesting-code-review

Sau khi hoàn thành implementation, bắt buộc request review trước khi merge:

1. Chuẩn bị context cho reviewer:
   • WHAT: Tóm tắt những gì đã implement
   • PLAN: Link hoặc nội dung spec/plan
   • BASE_SHA → HEAD_SHA: Range commit thay đổi
2. Dispatch reviewer subagent (agent riêng, KHÔNG dùng agent chính):

   Review these changes:
   What: [implementation summary]
   Requirements: [from spec]
   Changes: `git diff BASE_SHA HEAD_SHA`
   Focus on: spec compliance, code quality, test coverage

3. Action based on severity:

   Severity	Action
   Critical	Fix ngay lập tức. Block mọi progress.
   Important	Fix trước khi tiếp tục task tiếp theo.
   Minor	Ghi nhận (log). Fix khi convenient.

receiving-code-review

Skill này đặc biệt vì nó chống lại một tendencies (xu hướng) tự nhiên của AI agents: performative agreement (đồng ý để tỏ ra lịch sự).

KHÔNG BAO GIỜ nói	THAY BẰNG
"You're absolutely right!"	"Fixed. [mô tả ngắn thay đổi]"
"Great point!"	"Good catch - [vấn đề cụ thể]. Fixed in [vị trí]."
"Thanks for catching that!"	"Resolved: [mô tả fix]"
"I totally agree"	"Verified: [reference evidence]. Implementing."

Response Pattern (Quy trình nhận feedback)

Step	Hành động	Chi tiết
1. READ	Đọc hết feedback	Đọc xong tất cả rồi mới phản ứng. Không reply từng comment.
2. UNDERSTAND	Diễn đạt lại requirement	Nếu không rõ: "Are you suggesting X because of Y?" - hỏi cụ thể.
3. VERIFY	Check codebase	Reviewer có thể sai. Verify bằng code thực, không tin review mù quáng.
4. EVALUATE	Áp dụng cho codebase NÀY	Best practice chung ≠ đúng cho project này. Context matters.
5. RESPOND	Technical reply	Acknowledgment hoặc reasoned pushback. Không performative.
6. IMPLEMENT	1 item 1 lúc	Fix từng feedback item, test mỗi cái, commit riêng.

YAGNI Check khi reviewer đề xuất

Khi reviewer nói "implement this properly" hoặc "add error handling for X": Grep codebase xem feature đó có ai dùng không. Nếu endpoint/function/feature không được gọi ở đâu → "This isn't called anywhere. Remove it? (YAGNI)" Đây là pushback hợp lệ, không phải lazy.

Khi nào Push Back?

• Reviewer suggest feature chưa ai dùng → YAGNI
• Reviewer suggest pattern không phù hợp project scale → over-engineering
• Reviewer dựa trên assumption sai (chưa đọc code kỹ) → cite evidence
• Reviewer suggest style preference, không phải bug → optional, discuss

Chương 8: Git Worktrees, Meta Skills & Kết thúc

using-git-worktrees (Workspace cách ly)

Git worktree cho phép nhiều branches được checkout đồng thời trong cùng repo. Superpowers dùng worktrees để tạo isolated workspace cho mỗi feature.

Quy trình tạo Worktree

1. Chọn directory: Kiểm tra .worktrees/ (convention) → đọc CLAUDE.md → hỏi user
2. Tạo branch + worktree:

   git worktree add .worktrees/feature-name -b feature/feature-name

3. Safety verification:

   git check-ignore .worktrees/feature-name
   # Phải return path (= đã ignored). Nếu không → thêm vào .gitignore

4. Project setup: Auto-detect và chạy:
   • package.json → npm install
   • Cargo.toml → cargo build
   • requirements.txt → pip install -r requirements.txt
5. Baseline tests: Chạy test suite → tất cả phải pass. Nếu fail → worktree có vấn đề, không phải code bạn.

using-superpowers (Kích hoạt Skills)

Skill "meta" quan trọng nhất - quy định cách agent sử dụng toàn bộ hệ thống:

Priority Hierarchy (Thứ tự ưu tiên)

Mức	Source	Override
1 (Cao nhất)	User instructions (CLAUDE.md, direct requests)	Override tất cả
2	Superpowers skills	Override system default
3 (Thấp nhất)	Default system prompt	Bị override bởi cả 2 trên

Skill Priority (Process trước Implementation)

• User nói "Build X" → brainstorming first, rồi mới build
• User nói "Fix bug Y" → systematic-debugging first, rồi mới fix
• User nói "Review code" → receiving-code-review, không phải quick scan

Skill check phải xảy ra TRƯỚC bất kỳ response nào, kể cả clarifying questions.

writing-skills (Viết skills mới)

Superpowers dùng TDD để viết... documentation! Chính skill này cũng tuân thủ RED-GREEN-REFACTOR:

TDD Phase	Áp dụng cho Skill
RED	Run pressure scenario WITHOUT skill → ghi baseline failures. Agent skip steps nào? Rationalize bằng gì?
GREEN	Viết skill address specific failures từ RED phase. Không viết skill "dự phòng".
REFACTOR	Tìm new rationalizations agent dùng để bypass skill → thêm chặn. Đây là bước lặp liên tục.

CSO - Claude Search Optimization

Skill discovery (tìm skill phù hợp) dựa trên description trong frontmatter. Quy tắc CSO:

• Description chỉ chứa "Use when..." triggers, KHÔNG tóm tắt workflow
• Nếu description chứa workflow summary → AI sẽ follow description thay vì đọc full skill → mất detail
• Tên skill: lowercase kebab-case, verb-first (ví dụ: writing-skills, requesting-code-review)

finishing-a-development-branch

Skill kết thúc workflow. Sau khi verify tests:

Option	Merge	Push	Keep Worktree	Cleanup
1. Merge locally	✓	-	-	✓
2. Create PR	-	✓	✓	-
3. Keep as-is	-	-	✓	-
4. Discard	-	-	-	✓ (force)

Option 4 (Discard): Yêu cầu gõ chính xác "discard" để confirm. Agent không bao giờ delete work mà không hỏi user.

Chương 9: Iron Laws & Anti-Patterns tổng hợp

Tổng hợp tất cả "luật sắt" và anti-patterns từ 14 skills tại một nơi. Đây là checklist để bạn hoặc agent kiểm tra mình có đang vi phạm không.

4 Iron Laws

Skill	Iron Law
test-driven-development	NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
verification-before-completion	NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
systematic-debugging	NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
writing-skills	NO SKILL WITHOUT A FAILING TEST FIRST

Master Red Flags

Bạn/Agent đang nghĩ...	Phải làm gì
"Quá đơn giản, không cần design"	STOP → Brainstorming. Mọi project cần design.
"Quick fix giờ, investigate sau"	STOP → Phase 1 Root Cause. Quick fix = technical debt.
"Viết code trước, test sau"	DELETE code. Start over with RED phase.
"Should work now" / "Probably fine"	RUN the verification command. Evidence over claims.
"Thử thêm 1 fix nữa" (đã fail 2+)	STOP → Reassess. 3+ failures = architecture problem.
"Tôi biết skill này rồi"	Skills evolve between versions. Invoke current version.
"You're absolutely right!"	DELETE response. State the technical fix instead.
"Emergency, no time for TDD"	Emergency = higher risk = MORE reason for TDD.
"Fix nhiều thứ cùng lúc cho nhanh"	Can't isolate what worked. 1 fix = 1 test = 1 commit.
"Test framework chưa setup"	Setup IS task 1. BEFORE any code.

Chương 10: Release History & Tương lai

Superpowers phát triển rất nhanh, từ v2.0 (Oct 2025) đến v5.0.2 (Mar 2026) - 5 tháng, 22 releases. Dưới đây là milestone quan trọng:

Version	Ngày	Highlights
v2.0	Oct 2025	Skills repo tách riêng. 9 skills mới. Auto-update trên session start.
v3.0.1	Oct 2025	Chuyển sang Anthropic first-party skills system.
v3.2.0	Oct 2025	Design docs trong brainstorming. superpowers: namespace.
v3.3.0	Oct 2025	Codex support (experimental). Cross-platform mở đầu.
v4.0.0	Dec 2025	Two-stage review. DOT flowcharts. Debugging tools bundled. Test infrastructure.
v4.2.0	Feb 2026	Worktree isolation bắt buộc. Main branch protection (yêu cầu consent).
v4.3.0	Feb 2026	Brainstorming HARD-GATE. Cursor support chính thức.
v5.0.0	Mar 2026	Visual brainstorming companion. Document review system. Architecture guidance.
v5.0.2	Mar 2026	Zero-dependency brainstorm server. Auto-exit 30 phút idle. Context isolation all delegation skills.

Cross-platform Evolution

• v3.3: Codex support (experimental)
• v3.5: OpenCode support
• v4.1: OpenCode native skills
• v4.3.1: Cursor support
• v5.0.1: Gemini CLI extension

Mục tiêu: mọi coding agent đều có thể dùng Superpowers, bất kể platform.

Windows Support

Nhiều bản fix dành riêng cho Windows: hook quoting issues (single vs double quotes), bash path discovery, symlink handling, CRLF line endings, O(n^2) performance fix trong escape_for_json. Windows là môi trường khó nhất nhưng được hỗ trợ đầy đủ.

Community & Links

Superpowers là open-source (MIT License). 24 contributors, 6.6k forks.

GitHub: obra/superpowers | Blog: Superpowers for Claude Code