212 lines
8.8 KiB
Markdown
212 lines
8.8 KiB
Markdown
# 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`
|