0282 — Developer experience: @stackra/skills, @stackra/cli, @stackra/mcp and Vellum as the SDLC

Accepted · 2026-10-22

Amends 0016 (where the agent source lives), 0127 (the developer row) and 0199 (how the agent kit installs). Sets the condition under which 0067 and decision D15 of 0121 are superseded.

Context

Stackra’s agent material (skills, rules, sub-agents, hooks) lives in this repository’s .agents/ and is projected into each assistant’s directory by tools/scripts/agents-sync.mjs (0016). Operations such as scaffolding, gen and validation live in tools/scripts. The public template (figentra/stackra-template) cannot copy those scripts without also copying Figentra-internal ones, and an agent kit committed into every project drifts and gives away the know-how. 0083 already names @stackra/cli as the stackra binary, 0199 installs an agent kit through stackra agents sync, and 0217 defines the product MCP gateway that exposes tenant actions. The SDLC is spec-kit (0067, pinned by D15 of 0121). Vellum (figentra/vellum, @vellum/*) is a separate product that already has protocol, engine, storage, renderers, method, plugins, CLI and MCP packages with tests. The owner decided the package split, the distribution model and the SDLC path in chat on 2026-10-22.

Decision

Packages

1. Three developer packages. @stackra/skills, @stackra/cli and @stackra/mcp live in this monorepo in the developer category, and each is published to npm as a separate package with changesets, on the one fixed @stackra/* version (decision 5 of 0177), not on version lines of their own. The public template consumes them and ships no internal scripts.
2. @stackra/skills is the agent-neutral source. Every Stackra skill, rule, sub-agent, command and hook is written once in one neutral format: Markdown with frontmatter, like @vellum/method. Renderers write it into each tool’s layout: Claude Code (.claude/), OpenCode (.opencode/), Kiro (.kiro/), Cursor (.cursor/rules), and AGENTS.md for Codex, Gemini and others. The renderer layer is shared with Vellum (@vellum/renderers), not duplicated. Projects pin a version through the catalog; updates arrive through changesets and Renovate.
3. @stackra/cli (stackra) runs every operation. new (package, service, app and their kinds), gen, validate, verify, doctor, db diff, structure, agents setup|sync|check and spec (which wraps Vellum). The agents commands run the skills renderers, install the guard hooks and render .mcp.json from .mcp.yaml; decision 10 says which command writes where. Root package.json scripts call it. The scaffold templates live inside it.
4. Figentra-internal operations stay here. Linear, the bot identities, the merge gate, the secrets inbox, delegation and the spend meter stay in this repository’s tools/scripts and are not part of the published CLI.
5. @stackra/mcp shares one core with the CLI and has two modes. It is distinct from the product MCP gateway of 0217.
   • Local (stdio, inside a repository): inspect the manifest (actions, events, routes, permissions, settings); create members and kinds; run gen, validate and verify and explain failures; call actions; read traces; query the local database through the local runtime. Writes go through the same commands and gates as the CLI.
   • Hosted (mcp.stackra.dev, OAuth): anonymous, read-only search of docs, ADRs, the registry and examples. After sign-in, the user’s projects (environments, deploys, logs, manifests), read-only first. Deploy and other writes come later, and only behind explicit approval.

Distribution and intellectual property

6. Layer 1, open conventions. Structure, naming, decorators and boundaries are the public @stackra/skills. stackra agents setup installs them at the user level (the Claude plugin marketplace, OpenCode and Kiro global config). They are never committed into a repository, and they work offline.
7. Layer 2, know-how. Generators, reviewer checklists, orchestration, the deeper SDLC method and fix playbooks are served at runtime by the hosted MCP as tools and prompts after a licensed sign-in. The local plugin is a thin client, and nothing is written to disk. Layer 2 needs an online sign-in.
8. Layer 3, deterministic logic. This is @stackra/cli, and its basic commands are open. Pro commands ship as @stackra-pro/* packages, built in the private figentra/stackra-pro repository and served compiled and licensed through Keygen (decision 2 of 0177). They plug into the CLI behind a free contract; @stackra/cli never imports them (decision 4 of 0202).
9. What a project holds. Projects and the template keep only AGENTS.md (project facts), CLAUDE.md and .mcp.yaml. They hold no .agents/, no .claude/agents, .claude/skills, .claude/commands or .claude/hooks, and no OpenCode skill folders. The guard hooks install at the user level through the plugin.
10. Setup and sync write different places. stackra agents setup writes the layer-1 files and the guard hooks to each tool’s user-level location. stackra agents sync|check writes and checks only the project files of decision 9 and the .mcp.json rendered from .mcp.yaml. This settles where the renderers of decision 3 write (owner, 2026-10-22).

SDLC

11. Vellum becomes the SDLC if the spike passes. If the Phase T spike (STA-298) passes, Vellum is Stackra’s SDLC: the method, signed approvals, recorded task evidence, a tamper-evident ledger, vellum verify in the Quality Gate, and a read-only MCP. A follow-up ADR then supersedes 0067 and D15 of 0121, the existing specs in .agents/specs migrate, and spec-kit (the specify-cli pin) is removed.
12. The figentra/sdlc Claude plugin is retired. Its method lives in @vellum/method. Stackra’s additions (the Impact questionnaire, the Linear key, the risk and lane rules) become a Vellum preset.
13. Until the spike. spec-kit stays and 0067 is unchanged. The spec-kit skills move into @stackra/skills and the spec gate into @stackra/cli as those packages are built.
14. If the spike fails. spec-kit stays, and Vellum is added only as the approval and evidence layer.
15. Where SDLC pieces go. Method, prompts and templates go to skills. Deterministic checks (the spec gate, lint, evidence, the Linear link) go to the CLI and the Quality Gate. Read-only spec status goes to the MCP. Approvals and the ledger stay in Vellum.
16. Vellum is continued, not rewritten. Gaps such as vellum sync and the doctor categories are Vellum issues, filed in figentra/vellum.

Consequences

• A project carries three small files instead of an agent tree, so an upgrade is a version bump and nothing drifts in the repository.
• The know-how in layer 2 is not on disk, which protects it, but it is unavailable offline; layer 1 and the open CLI still work offline.
• The renderer layer has two consumers (Stackra and Vellum), so a change to @vellum/renderers must keep both working.
• tools/scripts splits in two: operations that move into @stackra/cli and Figentra-internal operations that stay. Each script needs a home before the CLI ships.
• Three more packages carry release checks and changesets; they move with the one fixed @stackra/* version, so a release bumps them with every other free package.
• Until STA-298 reports, spec-kit and the move of its skills and gate into the new packages run side by side.

Enforcement

planned — each of the following, none of which exists yet:

• The three packages pass the release checks of 0177 (publint, attw, the packed-tarball smoke test) and carry changesets.
• A packed-tarball test of @stackra/cli fails if a Figentra-internal command (Linear, bot identity, merge, secrets inbox, delegation, spend) is present.
• A packed-tarball test of @stackra/skills fails if layer-2 content (generators, reviewer checklists, orchestration, fix playbooks) is present.
• The validator check planned by 0202 fails when a free package, @stackra/cli included, imports @stackra-pro/*.
• A template check in figentra/stackra-template fails on .agents/, .claude/agents, .claude/skills, .claude/commands, .claude/hooks or an OpenCode skill folder.
• stackra agents check fails on drift between .mcp.yaml and .mcp.json, as pnpm agents:check does in this repository today.
• Tests of @stackra/mcp assert that local writes go through the CLI command core and that hosted writes refuse without approval.
• If STA-298 passes, vellum verify runs in the Quality Gate.

Open details

The owner did not give these; the conservative default below applies until an ADR changes it.

1. This repository’s .agents/. It stays the working source until @stackra/skills exists. Stackra content then moves into packages/developer/skills, and Figentra-internal agents and rules stay in .agents/.
2. Offline layer 2. A signed-out or offline session gets layer 1 only. Nothing from layer 2 is cached on disk.

Supersedes and sources

Supersedes: none. Amends: 0016, 0127, 0199. Conditionally supersedes, through a follow-up ADR if STA-298 passes: 0067 and D15 of 0121. Related: 0083, 0177, 0202, 0217, 0277 (the sign-in the hosted MCP uses). Sources: owner decisions in chat, 2026-10-22 (packages, MCP modes and SDLC; then the three distribution layers; then the split between agents setup and agents sync|check, decision 10).