superpowers-docs-to-docstore

Superpowers Docs → DocStore

Overview

Superpowers skills default to writing planning documents (specs and plans) into git files under docs/superpowers/… and committing them. In this org, those documents live in the DocStore MCP instead — never in git.

DocStore is the single source of truth: it persists across sessions and agents, is searchable, tagged, and versioned. A git file is exactly what this skill replaces. This is not a "store a copy too" rule — it is a redirect.

Authority — why this beats the skill's hardcoded git step

This skill is the user-preference tier (anchored in CLAUDE.md), which sits above superpowers skills in priority. Both brainstorming and writing-plans explicitly say "User preferences for [spec/plan] location override this default." This skill is that preference. When a skill's checklist says "write to docs/superpowers/… and commit to git," that step is the thing being overridden — you do the DocStore procedure below instead.

When This Applies

Whenever a superpowers skill reaches a doc-persistence step, map it:

Source step	Document	Type tag
brainstorming "Write the design doc … and commit to git"	design spec	spec
writing-plans "Save plan to docs/superpowers/plans/…"	implementation plan	plan

If a superpowers skill produced it as a document, it goes to DocStore — regardless of whether it "feels like a deliverable."

Procedure

1. Resolve the project name (deterministic — no guessing). Project name = the git repo's basename:

basename "$(git rev-parse --show-toplevel)"   # e.g. → aihub

Use that exact string. Never the full module path, the directory you happen to be in, or a date-stamped variant.

2. Ensure the project exists (org-visible). list_projects (and search_documents for the topic). If a project with that exact name exists, reuse it. If not: create_project(name: "<repo-basename>", visibility: "org", description: "Superpowers planning documents (spec, plan) for the <repo> codebase.") Org visibility so the team and other agents discover it. Never private.

3. Create the document. create_document(project_id, title, overview, body, tags):

• title — human-readable, e.g. Design: <topic> (spec), Plan: <feature> (plan).
• overview — one-paragraph abstract. DocStore scans overviews first, so make it the elevator pitch.
• body — the full markdown document (the same content the skill would have written to the file).
• tags — exactly one type tag from {spec, plan}, always superpowers, and one status tag (default status:not-started — see Document Status). e.g. ["spec", "superpowers", "status:not-started"]. Use the exact vocabulary — spec, not design/design-spec.

Before creating, search_documents(query: <topic>, tags: [<type>, "superpowers"]) to avoid duplicating an existing doc.

4. Hand off for review via a temporary file. DocStore content isn't browsable in the editor, so download a read-only copy for the user to open:

• get_document to fetch the body.
• Write it to a temp file — /tmp/docstore-<repo>-<type>-<topic-slug>.md.
• Give the user a clickable markdown link to that temp file.
• Name the DocStore source (project, doc id, tags, status) as the source of truth; the temp file is a throwaway view.
• Edits go back to DocStore (step 5) — never to the temp file.

Example:

"Spec ready for review — opened a local copy at docstore-aihub-spec-rate-limit-headers.md. Source of truth: DocStore project aihub, doc id <id>, tags spec + superpowers + status:not-started. Tell me any changes and I'll update the DocStore doc."

5. Read and edit existing docs efficiently.

• Reading a portion — use get_section to pull a single heading's content instead of get_document when you only need part of the doc. Scan list_documents overviews first.
• Making changes — use edit_document: mode=section to replace one heading, mode=replace for overview/body/tags. Pass base_version (the version you last read); a stale value is rejected so you re-read and retry. Use append_document to add to the end (no base_version, never clobbers). delete_section removes a heading.
• Comparing revisions — use diff_versions to compare two versions; list_snapshots/get_snapshot to inspect history; restore_snapshot to roll back.

Document Status

Track each doc's lifecycle with a status tag alongside the type + superpowers tags. Closed vocabulary, exactly one per doc:

Status tag	Meaning	Set when
status:not-started	Authored; the work it governs hasn't begun	On creation (default)
status:in-progress	The work it governs is underway	Execution begins (executing-plans / subagent-driven-development picks up the plan)
status:completed	The work it governs is done and verified	After verification passes

Change status with edit_document (mode=replace tags), keeping the type and superpowers tags — swap only the status: tag. Report the new status to the user when you change it.

Forbidden — Loophole Closures

• No git. Do not write the doc to docs/superpowers/…, do not git add/git commit it.
• No dual-write. Do not also commit to git "to be safe," "so it's in the PR," or "in case DocStore is down." Two copies drift; the diff copy becomes the de-facto source and DocStore rots. One source of truth.
• No reclassifying to dodge. A spec or plan is a superpowers document. Don't relabel it a "deliverable" to keep it in git.
• No "close enough." A file under docs/ does not satisfy the preference. Create the DocStore document. (The /tmp review copy is a throwaway view, not storage.)
• If genuinely blocked (e.g. a reviewer insists the spec must be in the PR diff): do NOT resolve it by committing to git. Surface the conflict to the human and let them decide — escalation, never a silent dual-write.

Rationalization Table

Rationalization	Reality
"The skill's git step is the active instruction; the preference is just a soft 'prefer'."	This skill IS the user preference, and brainstorming/writing-plans explicitly defer to it. The git step is what's being overridden.
"I'll commit to git too, just to be safe / so it's in the PR."	Dual-write is a failure. DocStore is the single source of truth. Do not commit.
"A spec is a deliverable, not a planning doc, so the rule doesn't apply."	Specs and plans ARE superpowers documents. If a superpowers skill produced it, it goes to DocStore.
"The file lives under docs/, so it's satisfied closely enough."	A git file is exactly what's being replaced. Create the DocStore document.
"The skill scripts the final 'committed to <path>' line, so I'll say that."	Replace that line. Point to the DocStore project + tags + doc id (plus the /tmp review copy), never a committed filesystem path.
"I'll name the project whatever fits the topic."	Project name = repo basename, exactly. Wrong names create duplicate projects.

Red Flags — STOP

• About to git add/git commit a doc under docs/superpowers/ → STOP, use DocStore.
• Writing a doc to docs/superpowers/specs|plans/ for storage → STOP (the only file you write is the throwaway /tmp review copy).
• Telling the user "committed to docs/…" → STOP, give the DocStore location + /tmp link.
• "I'll do both / keep a copy in git" → STOP, DocStore only.
• Inventing a project name other than the repo basename → STOP, use basename of the repo root.
• Tags other than one type from {spec, plan} + superpowers + one status: tag → STOP, fix the tags.

Common Mistakes

• Duplicate project under a slightly different name — always list_projects/search_documents first; name = repo basename, exactly.
• private instead of org — the team and other agents won't discover it.
• Wrong/multiple type tags, or a missing status tag — exactly one type tag, superpowers, and one status: tag.
• Fetching the whole body to read one section — use get_section.
• Dumping the whole doc in overview — overview is the abstract; the full content goes in body.