Field guide
A flexible
working practice
How the principles apply in practice: intent, evidence, design, connected context, and dogfooding.
- Source:
- docs/methodology.md
- Built from:
- da88c48
Current practices. Official identity and the eight principles live in PRODUCT.md. The principles draft elaborates optional themes; this document describes application, not a mandatory sequence or skill pipeline.
Who owns what
Flow's value does not depend on a starter, start, a hosting provider, or the whole delivery sequence (decision 0067).
| Owner | Owns |
|---|---|
| Flow plugin | Intent, judgment, specs, delivery principles, reusable skills |
| Starters | Optional, opinionated technology foundations |
| Project scripts | The authoritative verification commands |
| Native host | Sessions, worktrees, delegation, built-in review |
start ends at the initial commit; discovery and deployment are separate work. Skills work alone and compose when useful: explore without start, build without a spec, to-spec without to-tasks, or review on any change.
Keep people able to judge
Agent speed creates costs that green checks do not show: code no one understands (comprehension debt), rationale no one wrote down (intent debt), and a review queue that grows with each agent (orchestration tax). Answer them selectively, not with a new phase or document: stop for direction changes and consequential uncertainty, record why in the specs and decisions the work already warrants, say what a person should understand before consequential work ships, and run only as much in parallel as someone can judge. Small, clear work proceeds without any of this. Research note.
Clarify intent
Work backwards from the user outcome, keep doing nothing as an alternative, and offer the smallest investigation when one uncertainty blocks a choice. Before building something substantial, ask how the problem is solved today: an existing product, open-source tool, host feature, or manual workaround may already answer it, and adopting, integrating, deferring, or stopping are outcomes as valid as building; experience observes the finished journey. Sources: research note.
Combine focused questions, research, suggested directions, and exploration of alternatives. Reuse known context. Establish the intended outcome, consequential assumptions, existing evidence, and how the next test will inform a decision.
When commercial context affects the decision, use the known customer, buyer, business model, distribution, and evidence of maturity to guide refinement. Ask only for missing context that matters to the current uncertainty. Optional product-discovery skills do not block delivery work.
For a new product, keep the vision and core journeys broad while the active work stays bounded: the vision lives in PRODUCT.md, the first useful release bounds it, specs are independently deliverable increments, and tasks are their executable slices. to-spec decides how many specs the work needs (decision 0066). Specs say what and why; how is the agent's.
Record bounded increments in docs/specs/ when durable scope helps; record significant rationale in docs/decisions/. Small clear changes may need only conversation and code.
Defend the delivery boundary
For a new product or substantial feature, settle the delivery appetite early: a time target (and a cost limit when model, evaluation, or infrastructure spend is material), the first verifiable increment, and non-goals. Recover what is known and ask only for what is missing, with a suggested default. A small, understood change gets none of this.
During delivery, new scope gets a scope trade-off whether the user or an agent proposed it: defer, replace, reject, or expand the appetite, naming what changes. Review flags both unrequested additions and accepted behavior that went missing. Blockers to correctness, security, or required checks are never traded away to meet a target. Parallel work pays only when it saves more elapsed time than it costs to brief, start, and integrate. Elapsed time and cost are reported when observed and marked "not measured" otherwise. explore and to-spec capture the appetite, build's Scope guard defends it, (decision 0053); build slices work with several outcomes and the host decides the fan-out (Slices, decisions 0060, 0062, and 0066).
Observe and revisit
Use One Metric That Matters (OMTM) when a measurable focus can guide the current product decision. Explain the uncertainty it addresses, define the population, calculation, time window, and data source, and establish a baseline or mark it unknown. Set a justified target and review point with the intended decision response; retain supporting evidence and guardrails. Early discovery may need qualitative evidence before a useful metric can be selected. align evaluates evidence against these definitions and names what blocks a conclusion.
Identify relevant product and system signals while planning the work. Assess findings against the intended outcome, record limitations, and decide whether to continue, change direction, or stop. Update affected context when a decision changes.
Keep implementation correctness and evidence of customer value distinct. A working feature does not establish that it improved the intended outcome. An initiative's spec says, in one sentence, what should change for whom, what evidence will be looked at, and which decision it informs; delivery proves the evidence can be obtained, and the judgment comes after shipping, when unknowns stay unknown. A typo or internal cleanup needs none of this. Specific growth frameworks remain proposals under assessment.
Design for the purpose
Choose design priorities from what people need to do on each page or screen: decide and act, complete a task, understand information, or explore an experience.
Keep shared visual decisions in DESIGN.md and page-specific intent in a small brief when needed. When the look is not settled, the design skill compares rendered directions and records the one the user chooses. These practices are adapted from Impeccable.
Maintain connected context
Keep product intent, experience design, and architecture distinct while allowing findings in one to inform the others. Use the documentation guide for ownership and AGENTS.md for maintenance rules. Source assessments live in research, indexed in references.
After meaningful changes, align root documents with sync-docs or equivalent manual edits. Implementation work may update owning docs per build.
Coordinate independent sessions
Several sessions, in one host or several, can work on one repository without a coordinator. Discussion and single-writer work stay in the current checkout; Claude Code isolates genuinely concurrent writers in their own worktrees (claude -w, subagent worktree isolation) and sizes the fan-out; with the Flow plugin, a SessionStart report lists kept worktrees, unmerged branches, and open pull requests, and a guard hook blocks the destructive Git cases. Two rules stay with Flow: give parallel writers their own instance of any runtime state they would share (a database, port, or test account), and report sibling work you cannot see as unknown. This is best-effort: Git shows evidence, not locks, and two sessions can still race. The rules live in write-agents Sessions (decisions 0052 and 0062).
Write context for agents and humans
Use progressive disclosure: short routing in adopter instruction files when the project chooses to have them; root documents summarize their own concern; specs and decisions hold durable detail.
Documentation should preserve intent, constraints, and information that is difficult to rediscover. Avoid exhaustive trees and descriptions that duplicate readily discoverable code. Shared documents must remain readable by humans.
Keep a document's status apart from where it sits: a draft on main is still a draft, and an accepted change on a branch has not shipped. Sessions refresh only the owner sections and branch changes their work touches (write-agents Context freshness).
At major handoffs, lead with a short digest of outcome, scope, verification, and the next action, and link the full spec or diff rather than pasting it.
Assess documentation impact during implementation and review. Code establishes observed behavior; accepted documentation establishes intended behavior and constraints. When they diverge, identify which needs correction rather than silently treating either as justification to change the other.
Documentation responsibilities
These apply to manual work and skill use. They are not a fixed sequence.
| Activity | Documentation responsibility |
|---|---|
| Exploration | Preserve worthwhile possibilities; link evidence when saving artifacts. |
| Planning | Capture bounded scope in a spec file when the work warrants it; it is accepted before shipping ("build it" or "ship it" on a draft accepts it). Work without a spec is always allowed, in either delivery mode (unspecced work). The file is the record; in GitHub mode the pull request links it (decision 0044). |
| Execution | Update root context and specs when behavior or accepted intent changes. |
| Review | Repair confirmed defects with evidence, record what stays open, and update decisions or root docs when conclusions matter (review Repair; understandable change). |
Create only the artifacts the work needs.
Dogfood
Use this when changing Flow. Apply the skills already in the catalog, in proportion to the work, on a realistic task. Prefer this repository first. Record the run next to the other smoke notes: the task, which skills were actually followed, what happened, and what was not run.
Keep the two kinds of evidence apart:
- Structural checks —
pnpm validate,pnpm test, and smoke contracts, run in CI on ready pull requests (decision 0057). They show that links, package metadata, and documentation path rules match the catalog; smoke contracts check safety rules by keyword, not skill wording (decision 0044). - Live agent verification — a person or agent used a skill in a host. Name the host, the date, and what was observed. A structural pass is not a live run. One agent is not an independent review. CI makes no model calls; the optional LLM context review runs on request under the pr-review-contract and is not a substitute for human judgment on consequential changes.
Do not add a dogfood skill, a required pipeline, or a second copy of the product statement for the record.
Latest recorded run: 2026-10-27 start bootstrap.
Maintain shared language
Use GLOSSARY.md for project-specific meanings. Apply discipline through discussion and examples, informed by domain language research. Every skill names things with resolved glossary terms, in specs, interfaces, code, and tests (domain-modeling Shared language). When terms or consequential naming choices need active refinement, invoke the domain-modeling skill explicitly.
Add a term when local meaning or ambiguity cannot be safely inferred. Record a meaning when resolved and update affected documentation and skill instructions when present. Loading the glossary does not require editing it; routine clarification does not require a decision record.