Stack Capability Pack Template

Use this folder as the starting point for every future learn/stacks/<stack-slug>/ pack.

A stack capability pack is not a framework encyclopedia. It is the operational file set that lets an AI-assisted solo developer decide whether a stack can ship a real app, then prove the app works across setup, development, packaging, release, and maintenance.

Copy Path

Copy or adapt this folder into a concrete stack pack:

learn/stacks/_template/      # source template
learn/stacks/<stack-slug>/   # concrete pack

Keep the concrete pack learn-first until it has repeated successful use. Do not create a live .agents/skills/<stack>/SKILL.md until the promotion criteria in promotion.md pass.

Pack Contract

Every concrete stack pack should answer these questions before an agent claims the stack is ready:

Question	File
Which docs and examples are authoritative?	docs-index.md
When should you choose or avoid this stack?	decision-guide.md
What is the smallest maintainable starter?	starter.md
Which reference apps prove real capability?	reference-apps.md
Which commands create, run, test, package, and release?	commands.md
Which evidence proves done?	quality-gates.md
Which traps repeatedly break AI-generated work?	pitfalls.md
What must agents never skip?	agent-guardrails.md
When should the pack become a live skill?	promotion.md

Minimum Done Criteria

A concrete stack pack is usable when these are true:

docs-index.md lists official docs, samples, API references, release notes, policy docs, and local recovery paths.
decision-guide.md names both strong and weak app shapes, with explicit avoid conditions.
starter.md gives the smallest maintainable starter shape and says what to exclude from v1.
commands.md has exact commands or an explicit Not applicable reason for every required command class.
quality-gates.md defines required, optional, manual, paid, device-dependent, package/signing, and release/store gates.
pitfalls.md records platform quirks, permission traps, stale examples, dependency constraints, and release blockers.
agent-guardrails.md tells agents how to source claims, when to stop, and what they may not run without approval.
Every Markdown file includes a  block with the sources actually consulted.

Gotcha: A stack pack without command-backed quality gates is just notes. Do not use it to guide app builds until it records the commands and evidence that prove the stack works on this machine.

Creation Flow

Start from templates/pack-checklist.md.
Fill docs-index.md before writing recommendations.
Write the decision guide and starter shape from official docs and real examples, not model memory.
Add commands and quality gates before building reference apps.
Record pitfalls as soon as a command, policy, package, permission, or device step fails.
Only consider skill promotion after real use proves the pack routes agent behavior reliably.