swabbie.devPIP / 7.0

Agentic coding / product intent

A coding agent can finish the task and build the wrong product.

“Add file upload” sounds specific until the agent has to choose what validation, progress, cancellation, partial failure, retry, and recognizable completion mean for the person using it.

See what PIP changes ↓Follow a project example ↘

THE FAILURE Tests show behavior under tested conditions; they do not establish the product experience.

CRT // 9600 BAUDCH-01task / underspecifiedDEC VT220

$ task: Add file upload

MISSING DECISIONWhat should happen when the upload is still moving, cancelled, or fails?
A
Submit immediately

Save the task first. Attach in the background; a failed upload leaves a row with no obvious recovery.

plausible · tests can pass
B
Upload before submit

Hold the form until complete; cancellation discards the draft and makes the task feel blocked.

plausible · tests can pass

Both are plausible implementations of an underspecified task; each silently encodes a different product choice.

UNDEFINEDvalidation · progress · cancellation
RECOVERYfailure · retry · completion
01A task names a capability

It may leave the user-visible contract undefined.

02Two builds can both look correct

Tests can pass while the product experience diverges.

03The missing piece is a shared target

The agent needs current product intent before it changes code.

01 The fix

Give the agent one current target.

A PIP is the smallest coherent, current description of the intended product. It gives each coding session one canonical target and reduces product guesswork without pretending to specify every implementation detail. It is a target, not a plan; engineering still chooses the internals within those stated behaviors and constraints.

FLOW / INTENT TO RELEASEevidence informs review
Canonical PIP to aligned implementation reviewThe canonical PIP gives the agent relevant intent. The agent traces the existing owner, changes the smallest aligned slice, gathers focused evidence, and reviews that evidence against the PIP. Aligned evidence produces a recognizable done condition. Only a mismatch branches to an implementation gap or an unresolved product question requiring an authorized intent decision.01 / PIPCanonical PIPoutcome + boundary02 / READRelevant intentfocused context03 / TRACEExisting ownercode + surface04 / CHANGEAligned sliceno silent policy05 / EVIDENCEFocused evidencebehavior + constraints06 / REVIEWCompare to PIPalign or routeMISMATCHMISMATCHALIGNED / DONERecognizable product behaviorIMPLEMENTATION GAPFix the existing codeUNRESOLVED QUESTIONRoute an authorized intent decisionevidence informs review · canonical intent stays authoritative
  1. 01
    Canonical PIPStart with the current outcome and boundary.
  2. 02
    Relevant intentRead the slice that governs this change.
  3. 03
    Existing ownerTrace the current code, surface, and state owner.
  4. 04
    Smallest aligned sliceChange behavior within the stated constraints.
  5. 05
    Focused evidenceObserve the behavior and its constraints.
  6. 06
    Review against PIPCompare what happened with current intent.
  7. ALIGNED / DONE
    Recognizable done conditionEvidence matches intent; aligned product behavior is visible.
  8. MISMATCH
    Route the right next stepImplementation gap: fix existing code. Unresolved product question: route an authorized intent decision.

Focused context: the agent reads the relevant intent, traces the existing implementation owner, and changes the smallest aligned slice before it gathers focused evidence and reviews evidence against the PIP.

KEY DISTINCTION

Authority versus evidence. Evidence tells you what exists. The canonical PIP tells you what the product is meant to be; evidence does not rewrite canonical intent.

02 The package

Each view surfaces a different kind of guess.

Format 7.0 starts with three default files. Together they answer what result matters, which physical system owns it, and what the actor sees. Add another artifact only when it resolves a distinct, consequential product question; the default is an orientation, not a claim that every product needs only three files. Before agents create, update, or implement against a PIP, the project designates its canonical PIP location.

01DEFAULT

product.yaml

Outcome + boundary

Reduces capability drift. It owns the release outcome, boundary, actors, capabilities, inline acceptance, exclusions, measures, and optional product-wide DCL.

02DEFAULT

architecture/stack-context.md

Physical ownership

Makes physical ownership explicit. It names the physical systems, responsibility, owned state, deployment, external boundaries, and connections.

03DEFAULT

experience/user-flows.md

Actor-visible path

Exposes invisible UX decisions. It preserves actor actions, surfaces, choices, visible failure, recovery, and recognizable outcomes without internal call order.

MAP / ONE PACKAGE, DISTINCT VIEWSoptional detail branches out
PIP package structureThe PIP connects product scope, physical context, and actor experience, with optional detail added only when needed.PIP / 7.0current product intentproduct.yamloutcome · boundary · acceptancearchitecture/physical ownership + connectionsexperience/actor actions + visible outcomesoptional detailrules · data · sequences · quality

ADD WHEN NEEDED

Optional artifacts answer specific questions.

acceptance.yamlseveral scenarios or recovery paths
behavior/rules, decisions, or lifecycle states
data/product-significant entities and constraints
sequences/ordered calls, retries, and fallbacks
contracts/shared external boundaries
governance.yamlcurrent editing authority only, when project guidance is otherwise unclear
quality/measurable reliability, privacy, or performance bounds

RETRIEVAL

One fact, one owner. Stable direct links and concise current rationale preserve why a choice exists, so an agent can retrieve a focused slice without duplicating or losing context.

DCL / DEVELOPMENT COMPLEXITY LEVEL

DCL right-sizes the target using users, wait path, recovery, credible load, risk, and operations. It is not a score, gate, acceptance criterion, or mechanism prescription; low DCL never weakens security, privacy, authorization, money safety, or data integrity.

03 In a project

Desklight makes the done condition visible.

Start with a deliberately fictional task that is easy to underestimate. The authorized product decision, captured in the PIP, gives an agent a target it can inspect, implement, and compare with observed behavior.

DESKLIGHT / CAP-001DECISION RECORDED IN PIP

“Add file upload to the task.”

An authorized product decision chooses upload-before-submit for this release. The canonical PIP records that current intent for the agent.

VISIBLE CONTRACTKeep the task as a draft while a PDF, PNG, or JPEG up to 25 MB uploads.

Submit stays unavailable until upload completes. Cancel and recoverable failure preserve task text; invalid files show “File type or size not supported.”

product.yamlscope
schema_version: 7.0.0
name: Desklight
release: 1.0.0
outcome: >-
  A teammate can attach a file to a task draft, recognize
  upload progress, and submit only after a usable attachment
  is complete.
boundary: >-
  PDF, PNG, or JPEG up to 25 MB. The draft stays editable
  while the upload runs. No offline queue or background sync
  in this release.
capabilities:
  - id: CAP-001
    name: Attach a file before submitting a task
    behavior: >-
      Submit stays unavailable until upload completes; cancel
      or recoverable failure preserves task text.
    acceptance:
      - A valid file shows progress while the task stays a draft.
      - An invalid type or over-limit file shows "File type or size not supported".
      - Cancel shows "Upload cancelled" and keeps task text.
      - Failure shows "Upload failed" and Retry.
      - Completion shows attachment name + size; Submit becomes available.
agent briefbefore editing
  1. 01

    Read product.yaml. Restate the upload-before-submit behavior, file boundary, visible recovery, and exclusions.

  2. 02

    Read the concrete owner slices below. Trace the existing implementation owner for the path instead of guessing from a ticket.

  3. 03

    Make the smallest aligned slice. If the PIP cannot answer a product behavior, route an authorized intent decision instead of inventing policy.

  4. 04

    Gather focused evidence for valid, invalid, success, and failure/recovery states, then review it against the PIP. Keep observations outside the canonical package.

DONE WHENA teammate can upload a PDF, PNG, or JPEG up to 25 MB, see progress while drafting, see the invalid-file message when needed, cancel without losing task text, retry “Upload failed,” and submit after the attachment is recognizable.
architecture/stack-context.mdphysical owner
ARCH-001 · Desklight web app
owns: task detail surface + attachment request
owned state: task text + attachment status
runs: deployed web app with object storage
boundary: storage service owns file bytes
          web app owns task-facing status
experience/user-flows.mdvisible path
FLOW-001 · Task detail
SURFACE · Task detail
choose file → show progress while draft stays editable
invalid → show “File type or size not supported”
cancel → show “Upload cancelled” → keep task text
failure → show “Upload failed” → Retry / Remove
complete → show attachment name + size → Submit available
From intent to observed behavior
1Readrelevant PIP
2Tracecurrent owner
3Changesmallest slice
4Observesuccess + recovery
5Reviewagainst PIP

04 Add the skill

A PIP is content.
The skill is the procedure.

Product Intent Package content says what the product should be. Product Intent Manager teaches an agent how to create, update, and consume that intent safely: read the canonical PIP, inspect owners, preserve boundaries, and keep evidence outside it.

01

INSTALL

Put the skill in the project.

Keep the workflow next to the project when every contributor and coding agent needs the same PIP operating procedure.

git clone https://github.com/swabbie-dev/product-intent-package.git
mkdir -p .agents/skills
cp -R product-intent-package/skills/product-intent-manager \
  .agents/skills/product-intent-manager
02

INVOKE

Ask for the PIP workflow.

Use the skill by name, then point the agent at the canonical package 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, compare focused evidence with intent, and route unresolved product questions instead of quietly changing the target.

Read → trace → change → observe → review
Keep evidence outside the canonical PIP.
Raise one product question before 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.

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.

01

Current intent, not project history

The package says what the product is meant to be now. Git and working notes carry the chronology.

02

One fact, one owner

Keep a decision in the artifact responsible for it, then link to that owner when another view needs context.

03

Views have jobs

User flows show visible experience. Sequences show execution. Stack context shows physical ownership. Do not make one diagram do all three.

04

Alternatives stay isolated

A different end state belongs in a coherent PIP fork until an authorized editor adopts it.

05

Evidence cannot rewrite intent

Code, tests, tickets, and runtime behavior tell you what exists. They do not silently decide what should ship.

06

DCL right-sizes the work

Development Complexity Level communicates users, wait path, recovery, credible load, risk, and operations. It is not a score, gate, or mechanism prescription.