feature-factory

Feature Factory

A goal-driven, local-first loop for taking one feature from intent to shipped. The whole method exists to hold a single line in tension: don't let the process outrun the feature. Keep the spine (goal → TDD → deterministic verify → human merge → evidence-when-it-matters); delete ceremony aggressively.

This is a behavior guide, not an engine. Do not build generic config, executors, telemetry, optimizers, or a universal factory verify wrapper. Run the behavior; package nothing the feature didn't earn.

Core principle

The human defines the desired system state. Agents maintain the specifications. Tests and evidence decide whether reality complied. Two human gates are always required — approve the Goal Contract (cheap-to-change moment) and review the merge (irreversible moment) — plus a conditional third (plan approval) when a size/risk trigger fires (see step 2). Everything between is a single focused agent loop.

When to apply vs skip

• Apply to a bounded, shippable feature.
• Skip the heavy parts for trivial changes — an S-size fix is just: short goal in your head → TDD → run the repo's checks → merge. Don't generate documents for a one-liner.
• Refuse XL — if the feature is multi-day with shared contracts, migrations, auth/billing, or product ambiguity, split it first; do not run an XL feature through this loop whole.

The loop (six steps)

1. Intake — create or repair a Goal Contract

Make a quick size call now (step 2 formalizes it) — you need it to decide how heavy intake should be. For S-size/trivial changes, skip the file — a short goal stated in chat and confirmed by the human is enough; jump to step 3. Otherwise, copy assets/goal-contract.md into the target repo as goal.md under a feature dir (suggested: docs/factory/<date>-<slug>/goal.md); see assets/goal-contract-example.md for a filled example of the calibration expected. The template's core fields are enough for M features — the conditional half is for L or when a trigger fires. Draft it from the request first, then have the human confirm/correct each field — don't block on a blank form, and don't proceed past intake until the human has approved the wording. Enforce:

• All <!-- required --> fields present: Smallest shippable slice and Stop condition.
• Respect the caps (≤3, ≤5). A capped goal stays a goal, not waterfall-in-markdown.
• Every desired outcome maps to concrete evidence. Reject vague/solution-coupled outcomes.
• Fail rule: if a goal can't produce evidence, it's a wish with better formatting — it doesn't pass.
• Agents may propose Goal Amendments; never silently rewrite the goal.