second-brain-os: Skill for Codex

Flow

You don't remember every skill, so ask.

A flow is a path through the skills. Most paths run along one main flow, and a few on-ramps merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.

Every flow skill resolves the project and its paths from docs/agents/project-context.md; specs, tickets and maps live as files in the project folder. Resolve it first; each later skill reuses it, and a /handoff file carries it into the next session.

When invoked, read the situation, name the path in two or three lines (which skills, in what order, and why), and offer to start the first one. Don't run the whole chain unasked.

First: is it small?

If the change fits in this session and nothing about it is unclear (a typo, a one-line config change, a short email, a quick edit to an existing doc), just do it. No spec, no tickets. The flow is for work that needs thinking or spans sessions.

The main flow: idea → done

The route most work travels. You have an idea and want it built, whether it's an app feature, an annual plan, a curriculum, a set of docs or a program launch.

1. Sharpen the idea by interview.
   • /grill-with-docs when the project should keep its terms and decisions: CONTEXT.md and ADRs in an app repo, glossary.md and decisions/ in a knowledge project (an annual plan, a curriculum, a program).
   • /grill-me when nothing should be recorded: a decision you're weighing, a draft plan, an idea. Both run the same /grilling primitive.
2. Branch: can you settle every question in conversation? If a question needs something concrete to react to (a UI, a state model, a rough outline, a first draft of one section), detour through /prototype, bridged by /handoff in both directions:
   • /handoff out, then open a fresh session against that file,
   • /prototype to answer the question with something throwaway,
   • /handoff back what you learned, and reference it from the original idea thread.
3. Branch: is this a multi-session build? Decide after grilling, not before. It's multi-session when building takes more than one sitting, or when other people contribute, review or sign off along the way.
   • Yes → /to-spec (the thread becomes spec.md in the project), then /to-tickets to split it into tracer-bullet tickets (tickets/NN-slug.md), each declaring its blocking edges on a **Blocked by:** line. Then build one ticket per session, clearing context between each one.
   • No → build it right here, in the same context window: /implement builds straight from the conversation, code or knowledge work.
4. Build → /implement, which routes itself:
   • Code (something that runs): drives /tdd at the agreed seams, commits on the ticket's branch in the app repo, runs /code-review on the commit, and closes the ticket with evidence.
   • Knowledge work (a doc, page, deck, diagram, plan, message): hands the making to the skill that owns the medium, reviews it, and closes the ticket with evidence.
   • The whole spec at once: every code ticket on the frontier builds in parallel in its own worktree, merged onto one integration branch, with the written tickets done one at a time alongside. Use it when the tickets are solid and you'd rather review the result than each ticket.
   • Reach for /tdd on its own for one behaviour test-first with no spec, and /code-review on its own to review a branch against a fixed point.