stacks-flow

# Stacks flow Stacks ships more than a hundred skills. You do not remember them all, so ask. 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](PHASE-BOUNDARIES.md) has the ordered tree. ## On-ramps 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. ## 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-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 - **`/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.