Combo with superpowers

Combo with superpowers

How ai-coding-ok and superpowers work together — one provides cross-session memory, the other provides deep thinking within a session.

---

The division of labor

	superpowers	ai-coding-ok
Primary value	Makes Claude think deeply about one thing	Makes Claude consistent across many things
Time scale	Within a single session	Across sessions, across months
Mechanism	Multi-sub-agent — "diverge + converge"	Three-tier memory — "record + recall"
Trigger	Planning, research, investigation	Every coding task (before + after)
Typical output	Design docs, research reports, option comparisons	Updated AGENTS.md, decisions-log.md, task-history.md

Intuition: superpowers is the "brain workshop." ai-coding-ok is the "institutional memory archive." You need both to make AI coding work like a real team.

---

The combo flow

1. ai-coding-ok Mode B  (Plan: load memory)        ← every task starts here
2. superpowers          (brainstorming → planning → execution)
3. ai-coding-ok Mode C  (Act: write memory back)   ← every task ends here

ai-coding-ok wraps around superpowers — it loads context before the thinking starts, and records the results after the thinking ends.

---

Five real-world recipes

Recipe 1: New project launch (Brainstorm → Memorize)

1. superpowers:

   "Design an architecture for a personal expense tracker. Compare three tech stacks."

   → Get a trade-off analysis of 3 options.

2. You pick one.

3. ai-coding-ok:

   "Project: personal expense tracker. Tech stack: Python + FastAPI + SQLite. Record the decision."

   → ai-coding-ok writes ADR-001 to decisions-log.md with the rationale.

Result: Next session, the AI reads decisions-log.md and knows why SQLite was chosen — no re-research needed.

---

Recipe 2: Fix a complex bug (Research → Fix → Record)

1. ai-coding-ok Plan phase: AI reads project-memory.md → checks "Known Issues" table. Is this bug already documented?

2. If new bug, deploy superpowers:

   "Debug this production error. Use deep-research to find the root cause."

3. After fixing, ai-coding-ok Act phase: AI writes the root cause and fix to project-memory.md's "Known Issues" table + task-history.md.

Result: The same bug type appears again → Plan phase hits the memory in 3 seconds → skips the entire superpowers investigation.

---

Recipe 3: Architecture refactor (Plan → Execute → Document)

1. superpowers:

   "Evaluate the cost and benefit of refactoring module X from synchronous to async."

2. You decide.

3. ai-coding-ok ensures execution:

   • Plan phase: break the refactor into verifiable small steps
   • Check phase: run tests at each step
   • Act phase: write ADR-XXX to decisions-log.md

Result: Six months later, you can look back and see why the refactor was done, how it was done, and what pitfalls were encountered.

---

Recipe 4: Multi-day feature (Context continuity)

A feature takes 3 days, multiple Claude Code sessions.

1. Day 1 start:

   "Add user authentication" → ai-coding-ok Plan: reads memory

2. Day 1 end:

   "Update task-history, I'll continue next session."

3. Day 2 start:

   "Continue TASK-037." AI reads task-history → immediately knows where you left off.

4. Need new component? Deploy superpowers:

   "Research the best JWT library for our stack."

Result: Zero time wasted on "re-establishing context" across 3 days of work.

---

Recipe 5: Team onboarding

New teammate joins the project:

1. They clone the project (already has ai-coding-ok installed)
2. They ask Claude:

   "Give me a 15-minute onboarding guide from the project memory. Use superpowers to deep-dive the most complex module."

Claude will:

• Extract architecture summary from project-memory.md
• List key decisions from decisions-log.md
• Summarize recent work from task-history.md
• Deep-dive the specified module with superpowers

Result: Day-1 productivity for new team members. No senior dev needed to hand-hold.

---

Anti-patterns: Don't do this

❌ Use superpowers for daily CRUD

Adding a field, fixing a typo, writing a simple endpoint — ai-coding-ok's PDCA is sufficient. superpowers is overkill and burns tokens.

❌ Use ai-coding-ok for brainstorming

ai-coding-ok is a recording system, not a thinking system. When you need divergent thinking, immediately switch to superpowers.

❌ Let both skills write to the same file

They can conflict. Division of labor:

• superpowers produces "design documents" → save to docs/
• ai-coding-ok records "design summary + rationale" → write to decisions-log.md

❌ Assume one replaces the other

They solve different problems. superpowers without ai-coding-ok = smart sessions that forget everything. ai-coding-ok without superpowers = consistent sessions that can't think deeply.

---

Compatibility details

ai-coding-ok v2.0+ has built-in compatibility with superpowers:

1. AGENTS.md hook: When superpowers' brainstorming reads AGENTS.md (Step 1: Explore project context), it hits the PDCA mandate — ai-coding-ok's Plan phase runs automatically.

2. writing-plans integration: Plans generated by superpowers automatically include a "Task N+1: Update project memory" step at the end.

3. Dual-path coverage: Whether you use superpowers or ai-coding-ok directly, PDCA executes. ai-coding-ok ensures Act runs after superpowers finishes.

See SKILL.md "Compatibility with superpowers" section for the technical details.

---

Configuration (optional)

If both skills are installed, add this to ~/.claude/settings.json:

{
  "preferences": {
    "default_workflow": "read .github/agent/memory/ before acting; record decisions to decisions-log.md"
  }
}

This makes the PDCA Plan/Act behavior the default even outside of ai-coding-ok triggered sessions.

---

Next steps

• PDCA Workflow — the loop that wraps around superpowers
• Four Modes — how Mode B and Mode C integrate with superpowers
• Daily Workflow — practical day-to-day usage