01DEFAULT
product.yaml
Product scope
Name the release, the outcome it creates, the actors who use it, the capabilities that matter, and what is deliberately outside the boundary.
Product Intent Package / Format 7.0
Give your coding agent a product to build.
A PIP is the smallest current description of what a product should do, how people use it, and which outcomes and constraints matter.
GOOD TO KNOW The PIP is a target, not a project plan.
$ tree product-intent
product-intent/
├── product.yaml
├── architecture/
│ └── stack-context.md
└── experience/
└── user-flows.mdOUTCOMEwhat changes for the user
BOUNDARYwhat is in · what is out
CHECKintent ≠ evidence
01Scope before code
Decide the outcome and boundary first.
02Experience stays visible
Keep the actor path recognizable.
03Implementation has a target
Let the agent inspect, build, and verify against intent.
01 The idea
Prompts are inputs.
A PIP is the shared target.
Coding agents can write code from a brief, a ticket, or a conversation. The failure mode is not usually syntax. It is a drifting idea of what the product is supposed to become.
FLOW / INTENT TO RELEASEone shared target
KEY DISTINCTION
Evidence tells you what exists. The canonical PIP tells you what the product is meant to be.
02 The package
Start small. Add detail only when it earns its place.
Format 7.0 has three default files. Together they answer the three questions an agent needs before it changes a product: what is the result, what physical system supports it, and what does the actor see?
02DEFAULT
architecture/stack-context.md
Physical context
Show the clients, services, managed platforms, stores, external systems, ownership, deployment placement, and connections that make the product real.
03DEFAULT
experience/user-flows.md
Actor experience
Describe what people do, see, choose, recover from, and reach next. Keep invisible implementation logic out of the user flow.
MAP / ONE PACKAGE, DISTINCT VIEWSoptional detail branches out
ADD WHEN NEEDED
Optional artifacts answer specific questions.
acceptance.yamlseveral scenarios or recovery pathsbehavior/rules, decisions, or lifecycle statesdata/product-significant entities and constraintssequences/ordered calls, retries, and fallbackscontracts/shared external boundariesquality/measurable reliability, privacy, or performance bounds03 The skill
Make the standard available at the moment of coding.
The Product Intent Manager skill gives your agent the operating rules around the package: read the canonical PIP first, keep evidence outside it, and preserve intent while implementing.
01
INSTALL
Put the skill in the project.
Keep the skill next to the project when you want the workflow available to every contributor and coding agent.
git clone https://github.com/swabbie-dev/product-intent-package.git
cp -R product-intent-package/skills/product-intent-manager \
.agents/skills/product-intent-manager02
INVOKE
Ask for the PIP workflow.
Use the skill by name, then point the agent at the canonical package location before it plans or edits.
Use $product-intent-manager.
Read the canonical PIP at product/product-intent
before deciding what this change should do.03
ALIGN
Implement toward the target.
Inspect existing owners, follow the visible flow, and report deviations outside the PIP instead of quietly changing intent.
Read → inspect → implement → verify
If the target is unclear, raise one
product question before adding policy.SKILL BOUNDARY
The skill helps an agent manage intent. It does not grant permission to change a canonical product definition, deploy code, or mutate external systems.
04 In a project
Use one small example to keep the intent testable.
Here is a deliberately fictional starting point. The product is small enough to read in one pass, but specific enough to guide an agent.
product.yamlscope
schema_version: 7.0.0
name: Desklight
release: 1.0.0
outcome: >-
A team can see the next shared task and move it
forward without losing the current owner.
boundary: >-
One shared board, one active task per person, and
visible loading, completion, and recovery states.
actors:
- id: ACTOR-001
name: Teammate
goal: Keep shared work moving.
capabilities:
- id: CAP-001
name: Advance shared work
actor_ids: [ACTOR-001]
outcome: The task and its owner are visible after each action.agent briefbefore editing
- 01
Read
product.yaml. State the outcome and boundary in your own words. - 02
Read the stack context and user flow. Identify the existing implementation owner for the path.
- 03
Make the smallest change that aligns the code with the PIP. Keep new behavior inside its capability.
- 04
Run the focused regression and review the diff. Put observations and gaps in task notes, not the PIP.
DONE WHENThe user-visible outcome matches the package.
A focused implementation loop
1Readcanonical PIP
→2Tracecurrent owner
→3Changesmallest slice
→4Verifyagainst intent
05 The guardrails
Clarity is a technical advantage.
A PIP is useful when it stays coherent, current, and proportional. These are the habits that keep a package from turning into another document graveyard.
Current intent, not project history
The package says what the product is meant to be now. Git and working notes carry the chronology.
One fact, one owner
Keep a decision in the artifact responsible for it, then link to that owner when another view needs context.
Views have jobs
User flows show visible experience. Sequences show execution. Stack context shows physical ownership. Do not make one diagram do all three.
Alternatives stay isolated
A different end state belongs in a coherent PIP fork until an authorized editor adopts it.
Evidence cannot rewrite intent
Code, tests, tickets, and runtime behavior tell you what exists. They do not silently decide what should ship.