workflow-overview

Workflow Overview

This project uses a lightweight workflow: an optional brainstorm to agree on a design, then the coding agent implements directly. There is no task tracker and no separate planning phase — once the direction is clear, build it.

brainstorm (optional)  ──►  implement  ──►  commit
   (capture design)         (build it)     (docs + commit)

• Idea is rough or its scope/approach is unclear? Brainstorm first to agree on a design (use the brainstorming skill), then implement.
• Idea is already clear, or the developer says to just do it? Skip the brainstorm and implement directly.

Brainstorming is a tool, not a gate: reach for it when a moment of explicit design will help, and skip it when the change is small and well understood.

Prime directive

Read extras/manifesto/MANIFESTO.md before doing any work. It holds the project's vision and non-negotiable guidelines. Every change must respect it. If a request conflicts with the manifesto, raise it with the developer instead of silently violating it.

Before navigating or editing the codebase, read extras/internals/INTERNALS.md — the code map (an extension of CLAUDE.md) that says where each kind of change lives. Use the internals skill to consult it and to keep it honest when the structure changes.

If either file is still a stub marked "Not yet written" (fresh from init), populate it first: run workflow manifesto info / workflow internals info for instructions, then write the manifesto by interviewing the developer and the internals map from the codebase. Never invent a project's vision or guidelines.

The workflow CLI

Brainstorm notes are managed through the workflow CLI. Key commands:

Command	Use
workflow init	Scaffold extras/ and docs/ into a new project (MANIFESTO/INTERNALS as stubs).
workflow manifesto info	Print how to populate MANIFESTO.md; run it, then write the file by interviewing the developer.
workflow internals info	Print how to populate INTERNALS.md; run it, then write the file from the codebase.
workflow brainstorm new "<title>"	Create a brainstorm note.
workflow brainstorm list	List brainstorm notes.
workflow brainstorm delete "<name>"	Delete a note once its design has been implemented.

Run workflow with no arguments for full usage.

The brainstorm folder is a queue, not an archive: once a note's design has been implemented and committed, delete it. Keeping it clear keeps the next brainstorm precise.

Which skill, when

• Idea is rough / not fully specified? → use the brainstorming skill (optional — skip it when the change is clear).
• Need to find or change the right code (or the structure shifted)? → use the internals skill.

How to implement

Whether you brainstormed first or went straight in, when you build a change:

1. Respect the manifesto (extras/manifesto/MANIFESTO.md) and the internals map (extras/internals/INTERNALS.md).
2. Build it — how you build (test-first, tests-after, or otherwise) is up to you and the developer. Keep it minimal (YAGNI) and verify it actually works.
3. Confirm with the developer, then update docs/README.md and INTERNALS.md in the same change when behaviour or structure changed.
4. Commit with the conventional-commit skill (cmd-llm-conventional-commit), on the developer's go-ahead. If the change came from a brainstorm note that is now fully implemented, delete the note (workflow brainstorm delete).

Hard gates

• Do not commit until the change works, the developer confirms, and docs/internals are updated.