Stacks flow

Stacks ships more than a hundred skills. You do not remember them all, so ask.
Read a selected skill before saying what it does or recommending a step be
skipped. The summaries here are orientation, not a substitute for its entrypoint.

Two kinds live in that set, and they are reached differently:

• Subsystem reference: stacks-orm, stacks-router, stacks-queue,
  stacks-cms, one per part of the framework. These are model-invoked, so the
  agent finds them on its own from the task. You rarely need to name one, and the
  full index is the feature-to-skill table in AGENTS.md.
• Craft skills: the ones below. These shape how the work happens, and this
  is the map of them.

Credit: the flow model here is adapted from Matt Pocock's ask-matt skill
(MIT), https://github.com/mattpocock/skills.

The main flow: idea to shipped

The route most work travels.

1. /stacks-office-hours turns an idea into a design document. It runs the
   stacks-grilling interview underneath, so vague answers get pushed on. Start
   here when the question is still "should we build this, and what exactly".
2. Branch: can every question be settled in conversation? If one needs a
   runnable answer (a state model, a UI direction), detour through
   /stacks-prototype, then come back with the verdict.
3. /stacks-plan-review turns the design into scope, data flow,
   architecture, a test matrix and an implementation plan. This is where
   stacks-codebase-design gets used, because the plan is where seams are chosen.
4. /stacks-new-feature slices the plan into tracer bullets and builds
   them in the model to migration to action to route to test order, one vertical
   slice at a time. It drives /stacks-tdd inside each slice.
5. /stacks-review reviews the diff on two axes, standards and spec, before
   anything merges.
6. /stacks-browse QAs the result in a real browser when the slice has a UI.
7. /stacks-retro looks back at the session and improves the environment the
   next one runs in.

Context hygiene

Keep steps 1 to 4 in one unbroken context window where you can, so the grilling,
the plan and the slicing all build on the same thinking. Each slice in step 4 can
then start fresh from its own ticket. When a session is running long, make the
cut at a phase boundary rather than mid-phase: PHASE-BOUNDARIES.md
has the ordered tree.

On-ramps

• Incoming issues or external PRs need sorting goes to
  /stacks-triage, which verifies the report and produces an agent-ready
  brief. Tickets created from an agreed spec are already ready and need no
  extra triage.
• A large effort still has unresolved decisions across sessions goes to
  /stacks-wayfinder. Resolve decision tickets, then synthesize their
  answers through stacks-to-spec before implementing the result.

A starting situation that generates work, then merges onto the main flow.

• Something is broken goes to /stacks-investigate. It refuses to
  theorise until it has a tight feedback loop, one command that already goes
  red on this bug, then fixes with a regression test. When the real finding is
  that there is no good seam to lock the bug down, it hands off to
  stacks-codebase-design.
• A visual surface needs to be built or lifted goes to
  /stacks-design-taste, or /stacks-redesign when the UI already exists
  and needs auditing first. Those two carry their own flow, including the
  aesthetic presets and the image-first pipeline.
• Something needs a human's hands goes to /stacks-wizard, which turns
  the manual procedure into a script the human runs once.
• Prose sounds generated goes to /stacks-humanizer for a broad
  editorial rewrite, or /stacks-unslop for an audit, minimal edits, or
  learning and matching a writer's voice. Review requests stay read-only.

Codebase health

Not feature work, upkeep.

• /stacks-codebase-design is the bench you design a module's shape on:
  module, interface, depth, seam, adapter, leverage, locality. Reach for it when
  the argument is about where a seam goes or how much a trait should hide.
• /stacks-security-audit for OWASP, STRIDE and attack-surface work.
• /stacks-improve-codebase-architecture surveys concrete deepening
  opportunities, weighted toward code that changes often. Pick a candidate
  before designing its interface with stacks-codebase-design.
• /stacks-registry and the other subsystem skills for the auditing patterns
  specific to one part of the framework.

Vocabulary underneath

Two model-invoked references that run beneath the other skills, each the single
source of truth for its vocabulary. Reach for them directly when the words,
not the process, are the problem.

• /stacks-domain-modeling sharpens the project's domain language:
  challenge a fuzzy term, resolve an overloaded one, record a hard-to-reverse
  decision as an ADR. In a Stacks app that language becomes model names, table
  names, route URIs and event names, so it is load-bearing.
• /stacks-codebase-design is the deep-module vocabulary for a module's
  shape. stacks-tdd and stacks-plan-review both speak it.

Standalone

For a multi-session build, use stacks-grill-with-docs to retain domain
decisions, stacks-to-spec to synthesize the agreed behavior, and
stacks-to-tickets to create self-contained slices with blocking edges.
stacks-implement works one ticket; stacks-implement-spec works the task graph
and verifies the integrated result. stacks-pr writes a reviewable PR body.
stacks-setup-engineering configures tracker conventions when needed; local
Markdown is a usable fallback without a setup ceremony.

stacks-research captures cited primary-source findings. stacks-to-questionnaire
drafts questions for knowledge another person holds; stacks-wait-what
re-explains a message that did not land. stacks-teach keeps a learning workspace.
For marketing tasks, use stacks-marketing to find the relevant channel workflow.

• /stacks-grilling is the interview primitive: rounds, the frontier, facts
  are the agent's job and decisions are yours. Reach for it directly when you
  want the interview with no wrapper.
• /stacks-guard is the safety layer: destructive-command detection, freeze
  mode, and the Claude Code hook that blocks the worst of it before it runs.
• /stacks-handoff compacts the conversation into a portable document.
  Narrow: only when something is actually travelling to a new harness, a new
  directory, or a colleague.
• /stacks-prototype answers one design question with throwaway code and
  keeps the artifact on a prototype/<name> branch.
• /stacks-writing-for-agents is the reference for writing any document an
  agent reads, including the skills themselves. Read it before adding anything to
  app/Skills/.
• /stacks-repl, /stacks-shell and /stacks-buddy drive the toolchain
  itself.

Precondition

Nothing to run first. buddy setup:ai <agent> links these into your agent's
directory, and app/Skills/<name>/SKILL.md shadows any of them per project.
The current upstream source and license are in NOTICE.md and
LICENSE. Read the Stacks adaptation rules
with the engineering workflows.