Add design spec for sp-stack full-stack library composer

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-05-29 22:40:47 +01:00
parent 0028c8adb6
commit 69c8135ea0
1 changed files with 136 additions and 0 deletions
--- a/docs/superpowers/specs/2026-05-29-sp-stack-composer-design.md
+++ b/docs/superpowers/specs/2026-05-29-sp-stack-composer-design.md
@@ -0,0 +1,136 @@
+# sp-stack — Full-Stack Library Composer
+
+**Date:** 2026-05-29
+**Status:** Approved (design)
+**Plugin:** `document-navigator`
+
+## Problem
+
+The marketplace exposes two ways into the 472-package `@suaveplan/*` catalog:
+
+- `library-navigator` — 383 self-contained `sp-<package>` skills, one per library.
+- `document-navigator/skills/sp` — greps the mirrored `docs/` tree to match a single
+  stated need to a package and pull verbatim code examples.
+
+Neither answers the question a user actually starts with: *"I want to build a
+multi-tenant SaaS with email campaigns, Stripe billing, and a booking calendar —
+which libraries do I need, and how do they fit together?"* Answering that today
+means many manual `sp` lookups and hand-assembling the result.
+
+We need a skill that takes a whole-app description and returns the complete library
+set, the wiring, and starter code — selected to **minimise the code the user writes**
+(prefer a turnkey `api-plugin-payment` over hand-assembling `payment` + `retry` +
+`webhook-client`).
+
+## Goals
+
+- Map a natural-language app description to the full set of `@suaveplan/*` packages
+  needed, across all 18 categories (backend, frontend, foundation, devtools).
+- Always prefer the highest-level turnkey package for each capability.
+- Emit a bill of materials, install command, host wiring, and starter code stitched
+  from **verbatim** docs examples — never fabricated imports.
+- Surface gaps honestly: capabilities with no `@suaveplan` package, and external
+  prerequisites (API keys, datastores).
+
+## Non-Goals
+
+- No automated or batch generation of per-library skills (GUIDELINES.md §1 stands;
+  the capability manifest is a separate hand-curated artifact).
+- No runtime/scaffolding tool — the skill emits code as text, it does not write a
+  project to disk.
+- No change to the 383 `library-navigator` skills.
+
+## Decisions
+
+1. **Approach C (hybrid).** A curated capability manifest covers the common 80% with
+   precise, code-minimal picks; the existing `sp` docs-traversal is the fallback for
+   the long tail. This is the only approach that both guarantees the "prefer turnkey"
+   behavior and cannot silently miss a library.
+2. **Housed in `document-navigator`**, sharing the relocated `docs/` tree. The composer
+   is a docs-navigation concern, so co-locating it avoids duplicating 32 MB or relying
+   on cross-plugin paths (which Claude Code has no mechanism for).
+3. **`docs/` moves under the plugin** so the plugin is self-contained and portable
+   regardless of distribution.
+
+## Architecture
+
+### File layout
+
+```
+plugins/document-navigator/
+  .claude-plugin/plugin.json
+  docs/                         # moved from repo root (32 MB, ~6k .md)
+  skills/
+    sp/SKILL.md                 # existing — description narrowed (see below)
+    sp-stack/
+      SKILL.md                  # new composer skill
+      capabilities.md           # curated capability manifest
+```
+
+### docs/ relocation
+
+`docs/` moves from the repo root to `plugins/document-navigator/docs/`. Every `docs/`
+reference in `sp/SKILL.md` is rewritten from the hard-coded
+`.claude/plugins/suaveplan-skills/docs/` path to `${CLAUDE_PLUGIN_ROOT}/docs/`.
+
+A repo-root path that only resolves when the entire marketplace is cloned together is
+replaced by a plugin-relative path that resolves however the plugin is installed.
+
+### Capability manifest (`capabilities.md`)
+
+A small, hand-curated table — the heart of Approach C. One row per common capability:
+
+| Field | Purpose |
+|---|---|
+| `capability` | e.g. `payments`, `multi-tenancy`, `email-campaigns`, `file-upload` |
+| `layer` | `backend` / `frontend` / `foundation` / `devtools` — drives grouping |
+| `primary` | the turnkey package, the minimise-code pick (`@suaveplan/api-plugin-payment`) |
+| `supporting` | deps it pulls in / commonly paired packages |
+| `example_doc` | path into `docs/` where the verbatim quick-start lives |
+| `external` | non-suaveplan prerequisites (Stripe keys, SurrealDB, SMTP) |
+
+The manifest is the only place the "prefer turnkey over low-level primitives" rule is
+encoded, so selection is deterministic rather than re-derived per request.
+
+## Composer flow
+
+1. Parse the app description into a capability list plus an inferred app-type.
+2. For each capability:
+   - **Manifest hit** → take `primary` + `supporting`, read its `example_doc` verbatim.
+   - **Manifest miss** → fall back to the `sp` docs-traversal (root → category →
+     subcategory → package) to locate candidates.
+3. Dedupe packages, order by dependency (turnkey plugins first), group by `layer`.
+4. Read the verbatim quick-start blocks from the docs tree.
+5. Emit the output.
+
+## Output shape
+
+- **Bill of materials** grouped by layer, with a one-line reason per package.
+- **Install command** — a single `bun add …`.
+- **Wiring** — the `createHost({ plugins: [...] })` composition.
+- **Starter code** — stitched from the verbatim docs examples.
+- **Gaps & prerequisites** — capabilities with no `@suaveplan` package (write custom
+  or bring third-party) and required external services.
+
+## Coexistence with `sp`
+
+Two skills, differentiated sharply by description so Claude selects the right one:
+
+- **`sp`** — narrowed to *"find the library for a single stated need / how do I use X."*
+- **`sp-stack`** — *"Describe a whole website/service/app; get the complete library set,
+  wiring, and starter code."*
+
+## Constraints inherited from existing skills
+
+- Only reference packages that exist under the docs tree; never invent package names.
+- Use exact `@suaveplan/<name>` identifiers.
+- Extract code examples verbatim; never fabricate import paths.
+
+## Risks
+
+- **Manifest drift.** New packages need manual addition. Mitigation: the docs-traversal
+  fallback keeps the long tail reachable, so a missing manifest row degrades to the
+  current `sp` behavior rather than a wrong answer.
+- **Two code paths.** Manifest + fallback. Both are simple, and the fallback is the
+  existing, already-exercised traversal.
+```