LiuMangMang/MyBlog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
MyBlog/docs/superpowers/specs/2026-03-16-opencode-superpowers-overview-design.md

8.8 KiB
Raw Permalink Blame History

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

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
Reference in New Issue View Git Blame Copy Permalink