feather-flow

name

feather-flow

description

The Feather Flow pipeline overview. **TRIGGER when the user expresses intent to build a new app, feature, or project from scratch** — phrases like "I want to build X", "let's create a Y", "help me make a Z", "want to build/design/sketch a [thing]". Routes to feather-brainstorm for ideation FIRST, then feather-spec for spec authoring, then feather-execute-task for build. **Use this BEFORE any scaffolding, file creation, or tech-choice discussion.** Also use when the user asks about the pipeline as a whole, is unsure where to enter, or needs to re-orient mid-implementation after a pivot. For direct task execution, invoke feather-execute-task. For spec authoring (when a docs/brainstorm.md already exists), invoke feather-spec. For discovery and brainstorming, invoke feather-brainstorm.

Feather Flow

End-to-end feature delivery. One pipeline of three stages — brainstorm, spec, execute — plus this overview skill.

---

When invoked

Three invocation patterns. Always quietly check docs/STATE.md and docs/ROADMAP.md first — they tell the agent what (if anything) is already in flight. Then route:

Input shape	Behaviour
Bare (/feather-flow alone)	If STATE.md has active work → show state-aware orientation (below). If empty → show standard orientation. Do not ask the user "describe what you were doing" — the state file already knows.
Help-shaped ("how does this work?", "what is feather-flow?", "walk me through this", "show me an example")	Show the standard orientation. (Even if state exists, the user is asking to learn, not to resume.)
Work description ("Want to build X", paste of a PRD, "thinking about a tool that does Y")	If STATE.md has active work → ask "you're in the middle of , want to pause that and start this, or finish first?" Otherwise route to feather-brainstorm. Do NOT show the orientation — the user is past it.

Quietly means: don't display ls output to the user. The check is for the agent's own routing decision, not user-facing chatter.

Orientation (show when bare/help-shaped invocation)

Use this verbatim, adapting only the closing call-to-action to the user's apparent state:

Feather Flow — a pipeline that takes you from "I want to build X" to a finished feature you can ship.

    You say: "I want to build X"
             │
             ▼
    ╭────────────────────────────────────╮
    │  1. Brainstorm                     │
    │  I ask, you answer; I sketch.      │
    │  → a doc anyone on your team       │
    │    can read                        │
    ╰─────────┬──────────────────────────╯
              │  ⏸  I stop. You say "ready for the spec?"
              ▼
    ╭────────────────────────────────────╮
    │  2. Spec                           │
    │  I write precise specs + a task    │
    │  list. You confirm.                │
    ╰─────────┬──────────────────────────╯
              │  ⏸  I stop. You say "ready to build?"
              ▼
    ╭────────────────────────────────────╮
    │  3. Build                          │
    │  For each task: I plan, you OK,    │
    │  I write code, we verify.          │
    ╰─────────┬──────────────────────────╯
              │  ⏸  I stop after every task. You say "next?"
              ▼
      finished feature  →  you take it from here

Nothing happens without you saying yes. I pause after each stage and after every task — you decide when to advance.

---

First time here? Say "show me an example" (or "walk me through a small one"). I'll demo the whole pipeline on a tiny scenario. Best way to see what this actually does before committing to anything.

Ready to start? Just tell me what you want to build. Vague is fine ("something to help my team manage projects"); specific works too ("add comments to tasks in my existing app"). Or paste notes / a draft PRD if you have them.

After showing the orientation, stop and wait for the user's next message. Do not pre-route.

State-aware orientation (when STATE.md or ROADMAP.md exists)

If docs/STATE.md shows active work or docs/ROADMAP.md has rows, the orientation should lead with what's already in flight, not the generic "first time here?" pitch.

Case 1 — STATE.md has active work (mid-build)

Show a state banner instead of the standard orientation:

    ╭─ in progress ─────────────────────────╮
    │  <feature-name>                    │
    │  Stage 3 (Build) · task <task-id>     │
    │  <task title>                         │
    │  Step: <mini-plan / awaiting code /   │
    │         awaiting verify>              │
    ╰───────────────────────────────────────╯

    Last completed: <task-id> on <date>
    Tasks remaining in this feature: <N>

To continue: say "continue" or "next". To start something different: tell me what you want to build (I'll ask whether to pause this or finish it first). To re-orient on the pipeline: say "show me the pipeline".

Derive every field from STATE.md and the active feature's tasks.md. Do not ask the user to describe their state.

Case 2 — no active work, but roadmap has planned items

Show the roadmap and offer the next planned thing:

    Roadmap:
    ✅ done       <name>  (merged <date>)
    ⏸ planned   <name>  — <one-line description>
    ⏸ planned   <name>  — <one-line description>

To start the next planned item (): say "start ". To pick a different planned item: name it. To start something not on the roadmap: tell me what you want to build. To re-orient on the pipeline: say "show me the pipeline".

Case 3 — empty (no state, no roadmap)

Show the standard orientation (the generic block above, no banner).

---

In all three cases, stop and wait for the user's next message. Never auto-resume, never auto-start the next planned feature.

Example walkthrough (when user says "show me an example")

When the user asks for an example or walkthrough, prefer visual structures over wall-of-text. Make the demo something they can scan and absorb at a glance, not read paragraph-by-paragraph.

Default scenario: a personal todo list app. Familiar to everyone, easy to picture, small enough to fit end-to-end on one screen. Use this unless the user names a different scenario. Avoid abstract or technical examples (word counter, URL parser, etc.) — they're harder to visualise and don't invite the user to actually build anything.

Other good fallback scenarios if "todo list" feels too cliché: shared family grocery list, daily journal, simple expense splitter, bookmark saver with tags. Pick the one closest to a need the user might actually have.

Required visual elements:

1. A tiny scenario — picked from above. State it as a one-line user goal: "I want a small todo list I can share with my family — add items, mark them done, see what's left."
2. An ASCII pipeline showing this scenario flowing through — adapt the orientation diagram with the scenario's specifics overlaid.
3. An ASCII screen mockup — show at least one screen of the example using box-drawing characters (┌ ┐ └ ┘ │ ─). For a todo list, that's the main list view: title, items with checkboxes, add field.
4. An ASCII file tree — show the artifacts each stage produces:

   docs/
     ├── brainstorm.md            (Stage 1 — project-level discovery + app shell)
     ├── sample-data.json         (Stage 1 — sample data for the prototype)
     ├── mockup.html              (Stage 1 — interactive project-wide prototype)
     └── features/todo-list/
           ├── spec.md            (Stage 2 — feature spec, 15 sections incl. inline screens)
           ├── design.md          (Stage 2 — optional, only if there are tech decisions)
           └── tasks.md           (Stage 2 — developer steps)
   

5. A numbered task list — show what tasks.md would contain. First task always proves the engine end-to-end (data model + add + mark done with a hardcoded UI), then real screens build on top.
6. The task cycle visualised — show one build cycle as a small diagram (mini-plan → write → verify → tick → ask), not a paragraph.

Closing CTA — encourage them to actually build it:

End with two inviting lines, first option being to build the example you just demoed:

"Want to actually build this todo list? Just say 'yes, let's build the todo list' and I'll start Stage 1 for real. Or tell me what else you want to build instead — vague or specific is fine."

This matters: the example should feel like an invitation, not a demo. Many users will say "yes" to building the demo'd thing because it removes the "what should I build?" friction — Concierge Default applied to onboarding.

Anti-patterns:

• ❌ Wall of text describing each stage in paragraphs
• ❌ Inline file paths without showing them as a tree
• ❌ Long bullet lists of decisions instead of a one-glance visual
• ❌ Time estimates ("~2 minutes", "30 minutes of conversation") — never promise duration
• ❌ Tech-stack mentions in the example (no "we'll use Next.js" — the example is about the pipeline, not the stack)
• ❌ Abstract scenarios (word counter, URL fetcher) — pick something the user might actually want
• ❌ Closing with "want to try it on something real?" alone — always offer to build the demo'd thing as option 1, then "or describe something else" as option 2

A project may contain one or many features. The project gets a single project-level docs/brainstorm.md (workflow + decomposition); each feature gets its own spec.md. docs/ROADMAP.md is the lightweight inventory + status of all features; docs/STATE.md says which feature is active right now. The Spec and Build stages run once per feature; brainstorm runs once per project.

                      docs/brainstorm.md  ← project-level workflow + decomposition
                      docs/ROADMAP.md     ← features inventory + status
                      docs/STATE.md       ← active feature + task + step
                                  │
                                  ▼
vague requirement / pain point / pivot / multi-feature project
        │
        ▼
feather-brainstorm          ← Stage 1: detect scope at project level,
        │                      expand horizons, capture cross-feature
        │                      workflow + decomposition + app shell.
        │                      Output: docs/brainstorm.md,
        │                              ROADMAP.md (features inventory),
        │                              sample-data.json, mockup.html
        │                              (project-wide interactive prototype)
        ▼
feather-spec                ← Stage 2: per-feature spec authoring.
        │                      For each feature: produces spec.md,
        │                      optional design.md, tasks.md.
        │                      Derives screens' inline ASCII from
        │                      docs/mockup.html. Multi-feature projects
        │                      iterate one feature at a time.
        ▼
feather-execute-task        ← Stage 3: build one task at a time,
        │                      gate at every step.
        │                      Output: working code, plans/, notes.md
        │                              + STATE.md updates per gate cycle
        ▼
       PR                   ← drafted by feather-execute-task, opened by user
                              On merge: ROADMAP.md updated, STATE.md cleared.
                              Next planned feature promoted.

---

Starting Mid-Pipeline

The user does not have to start at the beginning.

User has	Start here
Vague idea or pain point	feather-brainstorm
Multiple feature ideas to plan together	feather-brainstorm (scope-detection mode — captures all in docs/brainstorm.md Features section)
Mid-implementation pivot — scope changed	feather-brainstorm (pivot entry point)
Clear feature in mind, ready to spec	feather-spec
docs/brainstorm.md already written	feather-spec (specs the next planned feature from ROADMAP.md)
All spec artifacts for a feature, ready to build	feather-execute-task
Some tasks complete, resuming	feather-execute-task (reads STATE.md)
Feature shipped, picking up the next	feather-execute-task (reads ROADMAP.md)

Orientation: when STATE.md or any tasks.md exists, invoke feather-execute-task — it reads STATE.md (active feature + step) and the filesystem, and prints orientation automatically. feather-flow does not duplicate that logic.

---

The Three Skills

feather-brainstorm

Expand horizons before narrowing to spec.

Entry points:

• Vague: "I want a todo app" → starts with workflow walk-through
• Specific: clear feature → skips discovery, goes to horizon expansion
• Pivot: scope changed mid-implementation → captures what changed first

Output: docs/brainstorm.md (project-level discovery + app shell), docs/ROADMAP.md (features inventory), docs/sample-data.json + docs/mockup.html (interactive project-wide prototype)

---

feather-spec

Author all per-feature spec artifacts from the project-level brainstorm or from a clear feature.

Produces (per feature):

• spec.md — 15-section feature spec (what it does, who uses it, journey, data, screens inline, behavior, scope)
• design.md — architecture & tech decisions (optional — created only when there are tech decisions worth recording)
• decisions/NNNN-<slug>.md — per-feature ADRs
• tasks.md — developer task list, prove-engine-first ordering
• (Components: described inline within spec.md by default; promote to components/ only when shared across screens)
• (Layouts: derived inline as ASCII zone diagrams from the project-level docs/mockup.html — no per-feature mockup sidecars)

Test ordering (load-bearing rule): Integration tests → unit tests (coverage gaps only) → E2E (~1 per flow)

---

feather-execute-task

Build one task at a time. Gate at every step.

Loop: mini-plan → execute → verify → tick → ask

Verification classifies findings: task fix · spec divergence · spec ambiguity · cross-cutting issue · scope creep · unrelated bug/improvement

User owns the loop. Agent never auto-continues.

---

Artifact Map

docs/
  ├── brainstorm.md                      ← feather-brainstorm (project-level:
  │                                        workflow, decomposition, motivation,
  │                                        app shell; written once)
  ├── sample-data.json                   ← feather-brainstorm (realistic sample
  │                                        data for the prototype)
  ├── mockup.html                        ← feather-brainstorm (interactive
  │                                        project-wide prototype loading
  │                                        sample-data.json)
  ├── ROADMAP.md                         ← feather-brainstorm (features inventory,
  │                                        status updated by feather-execute-task)
  ├── STATE.md                           ← feather-execute-task (active feature,
  │                                        active task, current step; updated each
  │                                        gate cycle)
  ├── decisions/                         ← system-wide ADRs (cross-feature)
  └── features/
        └── <feature-name>/
              ├── spec.md                ← feather-spec (15-section feature spec,
              │                            screens fold inline)
              ├── design.md              ← feather-spec (architecture/tech — optional)
              ├── decisions/             ← feather-spec (per-feature ADRs)
              │     └── 0001-<slug>.md
              ├── tasks.md               ← feather-spec (developer task list)
              ├── plans/                 ← feather-execute-task (per-task records)
              │     └── T-01-<slug>.md
              └── notes.md               ← feather-execute-task (deferred findings)

Components: skipped by default. Add components/ only when components emerge as a recurring concern shared across multiple screens. Most teams describe components inline within spec.md.

Cross-feature decisions: if an ADR applies to the whole system rather than one feature, place at docs/decisions/0001-<slug>.md. Per-feature ADRs live inside the feature folder (decisions/).

Read/write profile:

• docs/brainstorm.md is written-once and rarely revised — discovery output captured at project start. Lowercase per the "written-once docs are lowercase" convention.
• ROADMAP.md changes when feature scope changes (rare). Edited by feather-brainstorm on scope detection; updated by feather-execute-task when a feature ships. UPPERCASE — continuously updated state.
• STATE.md changes every gate cycle (frequent). Edited by feather-execute-task only — never by humans, never by brainstorm or spec. UPPERCASE — continuously updated state.

---

Quick Reference

Question	Answer
Where does a vague idea start?	feather-brainstorm
Where do multiple feature ideas start?	feather-brainstorm — captures all in docs/brainstorm.md Features section + ROADMAP.md
Where does a pivot start?	feather-brainstorm (pivot entry point)
Where does the project-level workflow + decomposition live?	docs/brainstorm.md
Where does the features inventory live?	docs/ROADMAP.md
Which feature is currently being built?	docs/STATE.md
Where does the user's framing live?	docs/brainstorm.md (project-level, verbatim where the framing carries substance)
Where does the interactive project-wide prototype live?	docs/mockup.html (with docs/sample-data.json) — generated by feather-brainstorm
Where does the per-feature spec live?	features/<name>/spec.md (15 sections, screens inline)
Where do architecture/tech decisions live?	features/<name>/design.md (optional, feature-scoped)
Where do per-feature ADRs live?	features/<name>/decisions/NNNN-<slug>.md
Where do system-wide ADRs live?	docs/decisions/NNNN-<slug>.md (cross-feature)
What is the first task in tasks.md?	Prove the engine — hardcoded UI, full pipeline
What is the test order?	Integration → unit (gaps only) → E2E
Where do verification findings live?	notes.md (bugs) or spec.md (cross-cutting changes)
Where do spec divergences get recorded?	plans/T-NN-<slug>.md → Divergences resolved
Who opens the PR?	The user. Always.
Who owns the execution loop?	The user. Agent serves the step.
What happens when a feature ships?	ROADMAP.md row → ✅ done; STATE.md cleared; next planned feature surfaced

---

Anti-patterns (this skill)

❌ Don't	✅ Do
Run ls/find and show output to the user on bare invocation	Quietly check state if needed; show orientation, not directory listings
Expose internal vocabulary ("no docs/features/, no STATE.md")	Speak conceptually — "fresh start" or "no in-progress build"
Name sub-skills to the user ("feather-brainstorm to expand horizons")	Just describe the stages (Brainstorm / Spec / Build); the user doesn't need the file names
Skip the orientation on bare /feather-flow and ask "what do you want to build?"	Bare invocation = show orientation first; routing comes only after a work description
Show the orientation when the user already gave a work description	If they said what they want, route — don't make them read the manual first