stacks-flow

# 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](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](NOTICE.md) and [LICENSE](LICENSE). Read [the Stacks adaptation rules](ENGINEERING.md) with the engineering workflows.