skills/docs/superpowers/specs/2026-05-29-sp-stack-composer-design.md

# 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.

**Pre-move verification (planning step):** before relocating ~6k files, grep the repo
for any other reference to the root `docs/` path — the 383 `library-navigator` skills,
`marketplace.json`, and any build/lint scripts — and confirm none break. Relative links
*inside* `docs/` (e.g. `./<category>/README.md`) survive a wholesale move; references
*into* `docs/` from outside do not.

### 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.

**v1 seed scope:** ship ~15–20 of the most common app capabilities (auth, multi-tenancy,
payments, email-campaigns, transactional-email, file-upload, search, realtime/SSE,
rate-limiting, notifications, webhooks, validation, PWA, client data hooks, CLI, testing).
This bounds the manifest work; everything outside it degrades to the docs-traversal
fallback, not a wrong answer. Each seed row should be anchored against a real example
phrasing so the `capability` vocabulary maps to how users actually describe needs.

## 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.
```