docs(ai): 新增 OpenCode superpowers 文章并更新侧边栏
This commit is contained in:
@@ -0,0 +1,109 @@
|
||||
# OpenCode Superpowers Overview Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Add one new blog post that summarizes `obra/superpowers` (OpenCode-first) + update the AI/OpenCode sidebar entry, matching this blog's writing style.
|
||||
|
||||
**Architecture:** One new Markdown article under `src/ai/` plus a small ordering update in `src/.vuepress/sidebar.ts`. Use upstream README as the source-of-truth for workflow + install commands.
|
||||
|
||||
**Tech Stack:** VuePress v2 + vuepress-theme-hope, Markdown, TypeScript config.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Gather upstream command strings + permalinks
|
||||
|
||||
**Files:**
|
||||
- Read: `~/.config/opencode/superpowers/README.md`
|
||||
|
||||
- [ ] **Step 1: Get upstream repo HEAD SHA (for permalinks)**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
git -C "$HOME/.config/opencode/superpowers" rev-parse HEAD
|
||||
```
|
||||
|
||||
Expected: prints a 40-char SHA.
|
||||
|
||||
- [ ] **Step 2: Identify exact upstream snippets to copy**
|
||||
|
||||
From upstream `README.md`:
|
||||
|
||||
- Installation commands (Claude Code official + marketplace, Cursor, Codex, OpenCode, Gemini)
|
||||
- Update command (Claude Code)
|
||||
- Verify Installation paragraph
|
||||
- Basic Workflow list
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Create the new overview post
|
||||
|
||||
**Files:**
|
||||
- Create: `src/ai/opencode-superpowers-overview.md`
|
||||
|
||||
- [ ] **Step 1: Add frontmatter + title + `<!-- more -->`**
|
||||
|
||||
Requirements:
|
||||
|
||||
- Chinese
|
||||
- Major headings `## 一、二、三...`
|
||||
- Use `---` thematic breaks between major sections
|
||||
|
||||
- [ ] **Step 2: Add sections per spec**
|
||||
|
||||
Include:
|
||||
|
||||
- What it is (1 screen)
|
||||
- Upstream Basic Workflow (7 steps; step 4 includes "subagent-driven-development or executing-plans")
|
||||
- Skill map (if/then) + links to existing posts:
|
||||
- `src/ai/opencode-superpowers.md`
|
||||
- `src/ai/opencode-skills-playbook.md`
|
||||
- Install/Verify/Update quick reference with strict fenced-block counts:
|
||||
- 5 install blocks (Claude/Cursor/Codex/OpenCode/Gemini)
|
||||
- 1 verify block (2 lines)
|
||||
- 3 update blocks (Claude/OpenCode/Gemini)
|
||||
- Cursor + Codex updates as plain text notes (no fenced blocks)
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Update sidebar order
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/.vuepress/sidebar.ts`
|
||||
|
||||
- [ ] **Step 1: Insert new link under AI -> OpenCode**
|
||||
|
||||
Insert before the existing:
|
||||
|
||||
- `text: "superpowers"`
|
||||
- `link: "opencode-superpowers.md"`
|
||||
|
||||
New item:
|
||||
|
||||
- `text: "superpowers-总览"`
|
||||
- `link: "opencode-superpowers-overview.md"`
|
||||
|
||||
Ensure final order:
|
||||
|
||||
1) `opencode.md`
|
||||
2) `opencode-tui.md`
|
||||
3) `opencode-superpowers-overview.md`
|
||||
4) `opencode-superpowers.md`
|
||||
5) `opencode-skills-playbook.md`
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Verify build
|
||||
|
||||
**Files:**
|
||||
- None
|
||||
|
||||
- [ ] **Step 1: Run production build**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
npm run docs:build
|
||||
```
|
||||
|
||||
Expected: `success VuePress build completed`.
|
||||
@@ -0,0 +1,211 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user