Prepare a Product Tree Work Package for Coding Agents

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.

The goal

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.

The claim gate

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: true
completion_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.

What goes in a seed or delta flag work package

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.

A complete seed flag example

id: F-001
flag_type: seed
title: Implement single-session onboarding flow
milestone: m1
primitive_branch:
  - I-001    # User completes onboarding in a single session
status: ready
claimable: true
blocked_by: []
completion_proof_state: ready

work_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.

Ready-but-blocked patterns

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:

status: "ready"
claimable: false
blocked_by:
  - "SV-003"   # staging environment not yet provisioned

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.

What NOT to do

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

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.

Access readiness

Before marking any flag claimable: true, confirm the following:

All required service credentials exist in the referenced vault location
All required environments are provisioned and reachable
All required CLI tools and environment variables are documented in setup commands
All required design assets, samples, and snippets are committed to the artifact directory

If any of these is missing, the flag is not ready for a coding agent — even if the product description is perfect.

Introduction

Core Concepts

Guides

Skills & Templates

Prepare a Product Tree Work Package for Coding Agents

The goal

The claim gate

What goes in a seed or delta flag work package

Flag identity and primitive branch

Intended product behavior

Scope and non-scope

Acceptance criteria

Required services and readiness state

Setup and verification commands

Required artifacts and sample ids

Data shapes and expected outputs

Failure modes and edge cases

Relevant standards

Privacy, security, and authority limits

Completion Proof

Blocker reporting

A complete seed flag example

Ready-but-blocked patterns

What NOT to do

Completion Proof

Access readiness

​The goal

​The claim gate

​What goes in a seed or delta flag work package

Flag identity and primitive branch

Intended product behavior

Scope and non-scope

Acceptance criteria

Required services and readiness state

Setup and verification commands

Required artifacts and sample ids

Data shapes and expected outputs

Failure modes and edge cases

Relevant standards

Privacy, security, and authority limits

Completion Proof

Blocker reporting

​A complete seed flag example

​Ready-but-blocked patterns

​What NOT to do

​Completion Proof

​Access readiness

The goal

The claim gate

What goes in a seed or delta flag work package

A complete seed flag example

Ready-but-blocked patterns

What NOT to do

Completion Proof

Access readiness