Product Context

product.md — the standing constitution every phase reads, so no work item has to restate it.

The two kinds of context

shipflow reads context at two different lifetimes:

	Answers	Lifetime
context.md	”What does this work item need?”	Disposable — one per work item, lives in .shipflow/{id}/
product.md	”What is always true here?”	Persistent — one per repo, committed, shared by the whole team

product.md is shipflow’s equivalent of a project constitution: domain glossary, architecture boundaries, house-rule conventions, non-negotiables, and a baseline definition of done. Every phase reads it; a single work item never has to restate any of it.

Creating it

/product-context

This is a bootstrap the first time (starting from templates/product.md) and an update afterward (only changing what’s asked or clearly stale). It’s grounded from evidence — your READMEs, package metadata, the repos in your config, and the conventions already dominant in your code — not invented. Anywhere it’s genuinely unsure, it leaves a placeholder and a “confirm with the team” note instead of guessing.

What’s in it

# {Product/Team} — Standing Context

- Owner(s), trackers, repos

## What this product is
## Domain glossary
## Architecture & boundaries
## Conventions (house rules)
## Non-negotiables
## Definition of done (baseline)
## Ownership / reviewers

---
Version · Ratified · Last amended

Non-negotiables are treated as implicit acceptance criteria. feature-verify checks them even though the work item never listed them — a change that violates one is a gap, exactly like a missed AC, and blocks the flow from reaching PR. Keep this list short and genuinely true; a wrong non-negotiable silently blocks unrelated PRs.

It’s a human-ratified document

product.md encodes team commitments, so the skill always presents the draft (or the diff, on an update) and asks you to ratify before finalizing — it will not silently mark itself final. The version footer follows semver by convention: patch for wording, minor for a new rule, major for a removed or changed principle.

Where each phase uses it

• feature-context — reads it to interpret the requirement in the product’s own terms.
• feature-plan — honors its conventions and boundaries; won’t plan changes in areas it marks out of bounds.
• feature-verify — grades its non-negotiables the same way it grades acceptance criteria.

If product.md doesn’t exist yet, phases still run — they just say so rather than inventing product rules. Set context.require_product_doc: true in shipflow.config.md if you’d rather hard-stop every phase until it exists.

Observe mode — the constitution learns from what shipped

Bootstrap/update is human-driven: you ask, it drafts, you ratify. Observe mode runs the other direction — ask “does product.md need updating?” and it reads every .shipflow/*/verify-report.md that reached READY, looking for patterns the document doesn’t capture yet:

• Scope-creep that recurs across work items — often a convention worth formalizing, not flagging every time.
• A non-negotiable that keeps getting violated or graded PARTIAL — either the wording needs clarifying, or it’s stale and should be softened.
• A convention that shows up repeatedly in plans’ impact analysis but isn’t written down.

It proposes a diff, each line citing the work item(s) that motivated it, and requires the same ratification as any other update — it never edits product.md on its own. If nothing recent suggests a change, it says so rather than manufacturing one.