跳转至

Superpowers AI Notes Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build and publish a Chinese MkDocs Material source decomposition of superpowers-main as a standalone GitHub Pages site.

Architecture: Keep the analyzed source outside the documentation repository. The new repository contains only authored Markdown, MkDocs configuration, and one Pages workflow. Documentation chapters follow the runtime lifecycle and link each conclusion back to the upstream source repository and local snapshot paths.

Tech Stack: Markdown, MkDocs Material, Python 3, GitHub Actions Pages, GitHub CLI.

Global Constraints

  • Source snapshot: local /Users/hanqing/CliX/superpowers-main, plugin version 6.2.0.
  • Site generator: MkDocs Material only; no custom frontend framework.
  • Repository: public Hanqing/superpowers-ai-notes.
  • Build gate: mkdocs build --strict must pass before push.
  • Documentation language: Simplified Chinese, with source identifiers and API names preserved.
  • License: this analysis is CC BY-SA 4.0; upstream source remains MIT under obra/superpowers.

Task 1: Create repository metadata and design records

Files: - Create: README.md - Create: LICENSE - Create: docs/superpowers/specs/2026-08-02-superpowers-source-decomposition-design.md - Create: docs/superpowers/plans/2026-08-02-superpowers-ai-notes-implementation-plan.md

Interfaces: - Produces the public entry point, scope statement, source provenance and maintenance commands used by later tasks.

  • [x] Step 1: Write the public README with online repository and Pages URLs, local preview commands, chapter map and source/license notices.
  • [x] Step 2: Record the approved design in the design file with the lifecycle outline and the Pages architecture.
  • [x] Step 3: Record this implementation plan so future contributors can reproduce the build.

Task 2: Configure MkDocs Material and Pages deployment

Files: - Create: mkdocs.yml - Create: requirements.txt - Create: .github/workflows/deploy.yml - Create: .github/workflows/link-check.yml

Interfaces: - mkdocs.yml consumes the docs/ tree and produces site/. - deploy.yml installs requirements.txt, runs mkdocs build --strict, and deploys the artifact to GitHub Pages.

  • [x] Step 1: Define the Material theme, Chinese language, search, code annotations, admonitions, Mermaid, navigation tabs and footer links.
  • [x] Step 2: Define the explicit nav so chapter order remains stable as files are added.
  • [x] Step 3: Add the Pages workflow with contents: read, pages: write, id-token: write, build artifact upload and deploy-pages.
  • [x] Step 4: Add the strict build workflow for pull requests and pushes so broken links fail before deployment.

Task 3: Write the lifecycle chapters

Files: - Create: docs/index.md - Create: docs/chapters/01-overview.md - Create: docs/chapters/02-startup-injection.md - Create: docs/chapters/03-skill-system.md - Create: docs/chapters/04-design-and-planning.md - Create: docs/chapters/05-execution-and-collaboration.md

Interfaces: - Chapters consume the local source inventory and produce reader-facing explanations with stable source links.

  • [x] Step 1: Explain the global model: skills are process policies, hooks are bootstrap transport, and the harness remains the execution host.
  • [x] Step 2: Trace session startup from manifest to hook output to skill discovery.
  • [x] Step 3: Trace the design-to-plan state machine and its user approval gates.
  • [x] **Step 4: Trace plan execution, subagents, worktrees, parallel dispatch and task review.

Task 4: Write the quality and portability chapters

Files: - Create: docs/chapters/06-quality-loop.md - Create: docs/chapters/07-multi-harness.md - Create: docs/chapters/08-tests-and-evolution.md - Create: docs/appendix/skill-catalog.md - Create: docs/appendix/source-map.md - Create: docs/appendix/glossary.md

Interfaces: - These chapters consume the workflow model from Task 3 and complete the coverage of every first-class skill family and adapter.

  • [x] **Step 1: Model TDD, debugging, verification and review as one evidence loop.
  • [x] **Step 2: Compare platform adapters by bootstrap mechanism, tool mapping and payload shape.
  • [x] **Step 3: Inventory tests, shell scripts, version manifests and release safeguards.
  • [x] **Step 4: Add a complete skill catalog and file-to-concept source map.

Task 5: Verify and publish

Files: - Modify: README.md after the repository URL and Pages URL are known.

Interfaces: - Consumes the finished site and GitHub repository metadata; produces a deployed public URL.

  • [x] **Step 1: Install MkDocs Material in an isolated environment and run mkdocs build --strict.
  • [x] **Step 2: Inspect generated navigation and verify representative internal links.
  • [x] **Step 3: Initialize Git, commit only the new repository files, create the public GitHub repository, and push main.
  • [x] **Step 4: Enable Pages with GitHub Actions and wait for the deployment workflow.
  • [x] **Step 5: Publish the actual repository and Pages links in README, with the initial commit already containing both URLs.
  • [x] **Step 6: Verify gh run list, gh api repos/{owner}/{repo}/pages, and the live HTML response before claiming completion.