Prepare a Product Tree Work Package for Coding Agents
How to write seed and delta flags that give coding agents everything they need to claim, implement, verify, and return evidence without avoidable blockers.
A coding handoff is not a ticket and not a vague story. It is a structured work package attached to a seed or delta flag that gives a coding agent the exact product outcome to build, all the resources it needs to build it, and clear proof criteria to know when it is done. This guide shows you how to write flags that meet that bar.
Your job as a product author is to ensure a coding agent can claim the work, set up the environment, understand the target, implement within constraints, run proof, attach evidence, and know when to stop or report a blocker — all without asking clarifying questions. Every ambiguity you leave in a flag becomes a blocker after the agent starts.
A coding agent can only claim a flag when all five conditions are true simultaneously:
flag_type: "seed" # or "delta"status: "ready"blocked_by: []claimable: truecompletion_proof_state: "ready"
The workspace Coding work switch must also be enabled. If any of these conditions is false, the agent cannot claim the flag. Do not mark a flag claimable: true until every item in the work-package checklist is satisfied.
Every claimable flag must include all of the following. Missing items are the most common cause of blocked agents.
Flag identity and primitive branch
The flag id and which primitive (or set of primitives) this work addresses. Links the flag to product truth.
Intended product behavior
Plain statement of what the product must do when this work is complete. Drawn from the intent’s expected_end_state.
Scope and non-scope
Explicit boundaries. What the agent must build, and what it must not touch. Taken directly from the intent’s scope and non_scope fields.
Acceptance criteria
User-facing and system-facing criteria. Both must be falsifiable. Vague criteria (“it works”) are not acceptance criteria.
Required services and readiness state
Every service the agent needs, its environment URL, access method, and current readiness. If a service is not ready, the flag must be claimable: false.
Setup and verification commands
Exact commands to set up the environment and verify it is working before implementation starts.
Required artifacts and sample ids
Every sample, fixture, design asset, snippet, or manifest the agent needs. Referenced by artifact id or path.
Data shapes and expected outputs
Input and output data structures. Match the intent’s input_data and output_data fields.
Failure modes and edge cases
Known failure scenarios the agent must handle. Drawn from the intent’s failure_behavior.
Relevant standards
Any standard primitives that govern this work. The agent must implement within these constraints.
Privacy, security, and authority limits
What data the agent may touch, what it may not expose, and who must approve any exceptions.
Completion Proof
What evidence removes the flag. Not a description of file edits — a description of observable outcomes.
Blocker reporting
How the agent should report a blocker and what evidence to attach. The agent must know when to stop and how to hand back.
id: F-001flag_type: seedtitle: Implement single-session onboarding flowmilestone: m1primitive_branch: - I-001 # User completes onboarding in a single sessionstatus: readyclaimable: trueblocked_by: []completion_proof_state: readywork_package: intended_behavior: > A new user can finish all three onboarding steps, confirm their profile, and land on the home screen within one uninterrupted session. If the session expires mid-flow, progress is restored on next open. The user does not restart from step 1. scope: > Steps 1–3 of the web and iOS onboarding funnel. Email OTP verification via SV-001. non_scope: > Invited team-member onboarding. Enterprise SSO. Password reset during onboarding. Android native app. acceptance_criteria: user_facing: - "A new user can complete all three steps and reach the home screen." - "An expired session restores progress — user resumes at the step they left." - "Every error state shows a plain-language description and a retry action." system_facing: - "Confirmed user record is written on step 3 completion." - "Email verified flag is set before home screen is rendered." - "OTP verification round-trip completes within 30 s on staging." required_services: - id: SV-001 name: Auth service — email verification environments: staging: url: "https://auth-staging.example.com" status: available access: "API key in 1Password > Engineering > Auth Service API Keys" simulation: "Magic code: 000000 (staging only)" readiness: confirmed setup_commands: - "cp .env.staging.example .env.local" - "pnpm install" - "pnpm dev" - "# Confirm staging auth API is reachable:" - "curl https://auth-staging.example.com/health" verification_commands: - "pnpm test:e2e --spec=onboarding" - "# Expected: all 3 steps pass, email verified flag is true in test DB" required_artifacts: - id: SA-001 description: "Sanitized funnel analytics fixture used as input sample" path: "ready/m1/artifacts/samples/SA-001.json" - id: DS-001 description: "Onboarding flow Figma designs (all three steps)" path: "ready/m1/artifacts/designs/DS-001-onboarding-flow.pdf" data_shapes: input: - field: email type: string format: RFC 5322 - field: display_name type: string max_length: 64 - field: avatar type: file required: false accepted_types: ["image/png", "image/jpeg"] max_size_mb: 5 output: - field: user_id type: uuid - field: email_verified type: boolean - field: session_token type: string expiry: "24h" failure_modes: - scenario: "OTP delivery delayed beyond 60 s" required_behavior: "Show resend option; do not block the step indefinitely." - scenario: "Auth API returns 503" required_behavior: "Block the step, show retry, log incident id." - scenario: "User closes app mid-flow" required_behavior: "Restore progress from local draft on next open." relevant_standards: - id: ST-001 title: "Onboarding flow error states must be self-recoverable" privacy_and_security: - "OTP codes must never be logged or persisted beyond the verification call." - "Avatar uploads must be scanned for malicious content before storage." - "Session tokens must be stored in httpOnly cookies — not localStorage." - "No PII may appear in client-side error messages." authority_limits: - "Do not change the password policy. It is governed by the security team." - "Do not add new OAuth providers without a product lead approval."completion_proof: description: > The flag is complete when all three onboarding steps pass the E2E test suite, the confirmed user record and email_verified flag are present in the staging database, and a product lead has reviewed a screen recording of a full flow run from a fresh incognito session. evidence_required: - "E2E test run output showing all assertions passing" - "Staging DB snapshot showing confirmed user record with email_verified: true" - "Screen recording of full onboarding flow (fresh session, web)" does_not_require: - "Specific internal file names or implementation details" - "Code review approval (that is a code review step, not Completion Proof)"blocker_policy: > If any required service is unreachable, any acceptance criterion is ambiguous, or any required artifact is missing, stop work and open a blocker flag with the flag id, a plain-language description of the block, and any evidence you have gathered. Do not attempt a workaround that falls outside the stated scope.
Sometimes the product branch is fully specified and Completion Proof is clear, but a dependency is not yet resolved. In that case, mark the flag ready but set claimable: false and list what is blocking:
This tells product authors and tools that the work package is complete — the blocker is an external dependency, not a product authoring gap. Fix the blocker, clear blocked_by, and flip claimable: true when the dependency resolves.
Do not prescribe internal file edits unless a standard, interface, architecture decision, or user instruction requires it. The coding environment chooses its implementation strategy inside the product, service, authority, and proof constraints. Telling an agent which file to edit is a scope violation unless a standard explicitly requires it.
Do not make a flag claimable because the prose sounds clear while access, samples, designs, or proof are missing. A well-written flag with a missing service credential or a missing design asset will block immediately. Verify every referenced resource exists and is accessible before setting claimable: true.
Do not close flags based on a coding agent’s self-report. Completion Proof must be supplied — observable evidence that the product outcome was achieved. A coding agent saying “it’s done” is not evidence.
Completion Proof says what evidence removes the flag. It is not a description of which files to edit. Write it as observable outcomes: test results, database states, screen recordings, API response snapshots, or external validation. The agent attaches the evidence; a human (or automated check) reviews it.
