# OpenCode Superpowers Overview Blog Post - Design

**Date:** 2026-03-16

**Goal:** Write one blog post that summarizes https://github.com/obra/superpowers in my blog style, with OpenCode as the primary viewpoint, plus a short install/verify/update quick reference for other platforms.

**Audience:** Self-use / quick reference. Readers already use terminals and can run commands. Minimal storytelling, maximal usability.

**Non-Goals:**
- Rewriting all upstream docs.
- Duplicating detailed OpenCode install steps already covered in `src/ai/opencode-superpowers.md`.
- Teaching Git basics or agent fundamentals.

---

## Placement

- New article path: `src/ai/opencode-superpowers-overview.md`
- Sidebar: `src/.vuepress/sidebar.ts` under AI -> OpenCode

**Modify file:** `src/.vuepress/sidebar.ts`
- Ordering inside the OpenCode group (final):
  - `opencode.md`
  - `opencode-tui.md`
  - `opencode-superpowers-overview.md` (new)
  - `opencode-superpowers.md`
  - `opencode-skills-playbook.md`

**Exact sidebar edit:** in `src/.vuepress/sidebar.ts` under `"/ai/"` -> `text: "OpenCode"` -> `children`, insert a new item before the existing `superpowers` link:

- `text: "superpowers-总览"`
- `link: "opencode-superpowers-overview.md"`

Insertion point must be immediately before the existing item:

- `text: "superpowers"`
- `link: "opencode-superpowers.md"`

---

## Content Outline (Blog Style)

### Frontmatter

- `title`: OpenCode Superpowers：框架总览与上手路线
- `icon`: `mdi:rocket-launch-outline`
- `date`: 2026-03-16
- `category` (YAML list):
  - `AI`
  - `开发工具`
- `tag` (YAML list):
  - `OpenCode`
  - `Superpowers`
  - `Skills`
  - `工作流`

### Required Structure (match this blog)

The actual blog post must use:

- `#` title + `<!-- more -->`
- Markdown thematic breaks (`---`) between major sections (these are NOT the frontmatter `---` delimiters)
- Major headings as `## 一、二、三...` (Chinese numbered)

Heading format requirement:

- Use `## 一、...` `## 二、...` ... (Chinese numeral + `、`)

Recommended outline:

- `## 一、它是什么（1 屏）`
- `---`
- `## 二、上游 Basic Workflow（按上游 7 步原样列出）`
- `---`
- `## 三、技能选择速查（if/then + 指路）`
- `---`
- `## 四、安装与验证速查（OpenCode 为主 + 其他平台命令速查）`
- `---`
- `## 五、更新与排障（按平台）`

### Intro (1 screen)

- Superpowers = skills + initial instructions + workflow discipline.
- Key value: forces an agent to ask, plan, verify; not "jump to code".

### Upstream "Basic Workflow" (match upstream)

The section title must clearly say this list is the upstream default workflow.

Upstream list (7 items) - item text and order must match upstream README "The Basic Workflow" section:

1) `brainstorming`
2) `using-git-worktrees`
3) `writing-plans`
4) `subagent-driven-development` (or `executing-plans`)
5) `test-driven-development`
6) `requesting-code-review`
7) `finishing-a-development-branch`

After the list, add a short "常用配套" note (not part of the upstream numbered workflow):

- `systematic-debugging`
- `verification-before-completion`

Each step gets 1-2 lines in Chinese explaining "this step prevents X" (keep skill names in backticks unchanged).

Note: upstream step 4 includes `executing-plans` as the no-subagent option; keep the step title aligned with upstream wording, then explain when to use each.

### 3. Skill Map (quick decision)

Tiny "if/then" list for choosing a skill, and then point readers to `src/ai/opencode-skills-playbook.md` for full step-by-step.

Also address naming/prefix confusion explicitly:

- Load by the exact name shown in your environment.
- If your environment shows `superpowers/<name>`, load with prefix; otherwise load the bare name.

Link to existing posts (avoid duplication):

- `src/ai/opencode-superpowers.md` (installation / verification / Windows gotchas)
- `src/ai/opencode-skills-playbook.md` (scenarios with steps)

### 4. Installation Quick Reference (multi-platform)

Keep it short: minimal command(s) + one link to details.

**Source of truth requirement:** all install/update commands must be copied verbatim from upstream `obra/superpowers` docs (no guessing).

For each command block, add one upstream source link pointing to the exact upstream section you copied from.

Prefer GitHub permalinks pinned to a commit SHA (so the post stays verifiable even if upstream changes).

Fallback: if you cannot determine a SHA in the current environment, link to the upstream file on `main` and label it as "un-pinned".

**Anti-duplication guardrail (OpenCode):**

- Do NOT include OpenCode manual symlink/junction steps in this post.
- Only include the upstream one-liner (Fetch and follow...) and link to `src/ai/opencode-superpowers.md` for the full manual steps.

Do NOT copy the one-sentence "Clone ... then symlink ..." quick install from `docs/README.opencode.md` into this overview post.

The post must include these platform commands (verbatim from upstream at a pinned SHA):

- Claude Code: official marketplace install + update
- Cursor: plugin install command as shown in upstream README (typically `/add-plugin superpowers` in Cursor Agent chat)
- Codex: install instruction (points to upstream `.codex/INSTALL.md`)
- OpenCode: install instruction (points to upstream `.opencode/INSTALL.md`) + link to `src/ai/opencode-superpowers.md`
- Gemini CLI: extension install + update

Add a dedicated "Verify Installation" subsection (inspired by upstream): start a new session, ask for a task that should trigger a skill, confirm it auto-invokes.

Make verify copy-pastable:

- Example verification prompt (copy-paste): `帮我做一个需求拆解，但先选择并加载一个合适的 superpowers skill 再继续。`
- Expected: the assistant triggers a skill workflow (asks clarifying questions / produces a plan) instead of jumping straight to implementation.

**Command blocks requirement (actionability):**

- Provide one fenced block per platform (`text` or `bash`). Inside the block, include ONLY copy-pastable commands/instructions. Put the platform label outside the fenced block.

Make the block structure explicit:

- Exactly 5 install blocks (Claude Code / Cursor / Codex / OpenCode / Gemini CLI)
- Exactly 3 update blocks (Claude Code / OpenCode / Gemini CLI)
- Cursor + Codex updates are short plain-text notes (no code block)
- Exactly 1 verify block (shared across platforms):
  - line 1: copy/paste verification prompt
  - line 2: what to look for

No extra fenced blocks are allowed inside Install/Update/Verify sections beyond the counts listed (notes must be plain text outside fences).
Other sections may use fenced blocks if needed, but this post should keep them minimal.

### 5. Updating / Troubleshooting

Make this actionable by platform (1 line update + 1 line verify):

Important constraint: do not introduce inline commands here. All install/update commands must live inside the fenced command blocks defined in the "Command blocks requirement" section.

"Restart OpenCode" must be written as an exact action: fully quit the running opencode process (TUI/CLI) and launch it again.

Also include update notes to complete the "by platform" promise:

- Cursor: short note about Cursor plugin update mechanism; if unsure, reinstall using the same install command from the install blocks, then verify by triggering a skill.
- Codex: short note that re-running the same upstream Codex install instruction is equivalent to updating, then verify by triggering a skill.

Troubleshooting should be short and point to existing detailed sections in `src/ai/opencode-superpowers.md`.

Duplication guardrail (enforced): the overview post may include the upstream OpenCode one-liner install instruction + a link to `src/ai/opencode-superpowers.md`, but must not reproduce the full manual symlink walkthrough.

---

## Sources

- Upstream: https://github.com/obra/superpowers
- Upstream OpenCode doc: https://github.com/obra/superpowers/blob/main/docs/README.opencode.md

---

## Acceptance Criteria

- File exists: `src/ai/opencode-superpowers-overview.md`
- Contains: frontmatter + `#` title + `<!-- more -->`
- Structure: uses `---` separators and `## 一/二/三...` numbered headings
- Includes exactly 5 install fenced blocks, exactly 3 update fenced blocks, and exactly 1 verify fenced block, per the "Command blocks requirement" section
- Each install/update command block has a nearby upstream source link.
  - Preferred: a GitHub permalink pinned to a commit SHA
  - Fallback: an "un-pinned" link to `main` clearly labeled
- Upstream workflow section matches upstream 7-step basic workflow (and separates "配套技能" clearly)
- Does not repeat manual OpenCode symlink steps; instead links to `src/ai/opencode-superpowers.md`
- Sidebar updated: `src/.vuepress/sidebar.ts` includes `opencode-superpowers-overview.md` under AI -> OpenCode in the specified final order
- Build passes: `npm run docs:build`