DOMAIN:PROJECT_MANAGEMENT:WORK_PACKAGE_DESIGN

OWNER: faye (Team Alpha PM), sytske (Team Beta PM) UPDATED: 2026-03-24 SCOPE: all client projects, internal GE work packages PREREQUISITE: formal-specification.md (Anna's spec must exist before WP decomposition)

---

PRINCIPLE: WORK_PACKAGES_ARE_THE_UNIT_OF_EXECUTION

RULE: every piece of work an agent receives is a Work Package (WP). RULE: a WP must be completable in a single agent session (target: 15-45 minutes wall clock). RULE: a WP must have exactly one assignee agent. RULE: a WP must be traceable to exactly one formal spec requirement. REASON: agents have session limits, context windows, and cost gates. A WP that exceeds a single session wastes tokens on context rebuild. A WP with no spec traceability cannot be verified.

MENTAL_MODEL: - Formal Spec (Anna) = WHAT must be built - Work Package (Faye/Sytske) = HOW it gets built, by whom, in what order - The PM does not decide WHAT — the PM decides decomposition, sequencing, and assignment

---

WP_SIZING: THE_RIGHT_GRANULARITY

SIZE_TARGETS

TARGET_SMALL: 15-20 minutes — atomic change (add a column, create a migration, write a single endpoint) TARGET_MEDIUM: 20-35 minutes — one coherent feature unit (CRUD for one entity, a form with validation) TARGET_LARGE: 35-45 minutes — complex but self-contained (auth flow, payment integration, search with filters) TOO_SMALL: < 10 minutes — overhead of context loading exceeds work value. Merge into adjacent WP. TOO_LARGE: > 60 minutes — will exceed session cost gate ($5). Split immediately.

SIZING_HEURISTICS

HEURISTIC_1: count the files that need to change. 1-4 files = small, 5-8 = medium, 9+ = split. HEURISTIC_2: count the new database tables. 1 table + its API = one WP. Never 3+ tables in one WP. HEURISTIC_3: count the acceptance criteria from Anna's spec. 1-3 criteria = one WP. 4+ = split. HEURISTIC_4: if the WP description takes more than 10 lines, it is too big. Split it. HEURISTIC_5: if you cannot name the WP in 8 words, it is too big or too vague.

ANTI_PATTERNS

BAD: "Build the user management system"
WHY: 20+ files, multiple tables, auth logic, roles, UI. This is a feature, not a WP.

BAD: "Add created_at column to users table"
WHY: 30-second change. Merge into the WP that uses this column.

BAD: "Build API and frontend for orders"
WHY: Two swimming lanes (backend + frontend) forced into one WP. Split by lane.

GOOD: "WP-017: Create orders table migration and seed data"
GOOD: "WP-018: Build POST /api/orders endpoint with Zod validation"
GOOD: "WP-019: Build OrderForm client component with react-hook-form"
GOOD: "WP-020: Build OrdersTable server component with pagination"

---

DEPENDENCY_MAPPING

DEPENDENCY_TYPES

TYPE_HARD: WP-B cannot start until WP-A is complete. Example: API endpoint (A) before frontend that calls it (B). TYPE_SOFT: WP-B is easier if WP-A is done first, but can proceed with mocks. Example: design tokens (A) before component styling (B). TYPE_NONE: WPs are independent. Example: two different API endpoints with no shared logic.

DEPENDENCY_RULES

RULE: hard dependencies form a DAG (directed acyclic graph). Cycles are spec bugs — escalate to Anna. RULE: the critical path is the longest chain of hard dependencies. Optimize this chain first. RULE: soft dependencies should use interface contracts (types, API schemas) so both sides can proceed. RULE: every WP must declare its dependencies explicitly in the depends_on field. RULE: the orchestrator enforces hard dependencies — a WP will not be dispatched until all hard deps are COMPLETE.

DEPENDENCY_DISCOVERY

STEP_1: draw the data model from Anna's spec. Tables that reference other tables create hard deps (migration order). STEP_2: for each API endpoint, identify which tables it reads/writes. The migration WP is a hard dep. STEP_3: for each UI component, identify which API it calls. The API WP is a hard dep. STEP_4: for each cross-cutting concern (auth, i18n), identify which WPs need it. Auth is almost always on the critical path.

EXAMPLE DEPENDENCY GRAPH:

WP-001: DB migration (users, roles)
  └── WP-002: Auth API (login, register, session) [hard dep on WP-001]
       ├── WP-003: User CRUD API [hard dep on WP-002 for auth middleware]
       │    └── WP-006: User management UI [hard dep on WP-003]
       └── WP-004: Login/Register UI [hard dep on WP-002]

WP-005: DB migration (orders, order_items) [hard dep on WP-001 for users FK]
  └── WP-007: Orders API [hard dep on WP-005, soft dep on WP-002 for auth]
       └── WP-008: Orders UI [hard dep on WP-007]

WP-009: DESIGN.md setup + global styles [no deps]
  └── WP-010: Layout component + navigation [soft dep on WP-009]

Critical path: WP-001 → WP-002 → WP-003 → WP-006 (4 sequential WPs)
Parallelizable: WP-009/WP-010 can run alongside WP-001/WP-002

---

PARALLEL_EXECUTION_IDENTIFICATION

PARALLEL_RULES

RULE: WPs in different swimming lanes with no hard deps can run in parallel. RULE: max 5 concurrent WPs per feature branch (see dolly-routing.yaml). RULE: max 1 WP per agent at any time. RULE: parallel WPs must not modify the same files. If they do, create a merge conflict resolution WP after both complete.

PARALLEL_STRATEGY

STRATEGY_1: front-load the critical path. Start DB migrations and auth immediately. STRATEGY_2: while critical path WPs execute, run independent WPs in parallel lanes (design setup, test scaffolding, CI config). STRATEGY_3: after the first API endpoints land, frontend WPs can start consuming them while more APIs are built. STRATEGY_4: testing WPs (Antje's TDD specs) can be written in parallel with implementation — they only need Anna's spec, not the code.

PARALLEL_IDENTIFICATION_CHECKLIST

For each WP, ask:
[ ] Does it share any database tables with another in-flight WP? → Cannot parallel
[ ] Does it modify the same source files? → Cannot parallel
[ ] Does it depend on output from another in-flight WP? → Cannot parallel
[ ] Does it need an API that another in-flight WP is building? → Cannot parallel (unless mocked)
[ ] None of the above? → CAN parallel

---

SWIMMING_LANE_ASSIGNMENT

STANDARD_LANES

LANE_DB: database migrations, seed data, indexing. Agent: backend dev. LANE_API: REST endpoints, middleware, validation. Agent: backend dev. LANE_UI: React components, pages, client interactivity. Agent: frontend dev. LANE_DESIGN: DESIGN.md, tokens, component selection. Agent: alexander. LANE_TEST: TDD specs, integration tests, E2E. Agent: antje (specs), marije (execution). LANE_INFRA: Dockerfile, k8s manifests, CI/CD. Agent: infrastructure dev. LANE_CONTENT: copy, translations, documentation. Agent: content dev.

LANE_RULES

RULE: one WP belongs to exactly one swimming lane. RULE: if a WP spans two lanes, split it. Example: "Build orders API and UI" → split into LANE_API + LANE_UI. RULE: lane determines which agent gets assigned. Backend WPs go to backend devs, frontend to frontend devs. RULE: Team Alpha and Team Beta have their own lane agents. Shared agents (alexander, anna, antje) serve both teams.

LANE_ASSIGNMENT_MATRIX

| WP Type                     | Lane      | Team Alpha Agent | Team Beta Agent |
|-----------------------------|-----------|------------------|-----------------|
| DB migration                | LANE_DB   | urszula          | maxim           |
| API endpoint                | LANE_API  | urszula          | maxim           |
| React component             | LANE_UI   | floris           | floor           |
| Page/layout                 | LANE_UI   | floris           | floor           |
| Design tokens               | LANE_DESIGN | alexander      | alexander       |
| TDD spec                    | LANE_TEST | antje            | antje           |
| Test execution              | LANE_TEST | marije           | marije          |
| Kubernetes manifest         | LANE_INFRA | jorrit          | jorrit          |
| Content/copy                | LANE_CONTENT | joost         | joost           |

---

SPEC_TO_WP_TRACEABILITY

TRACEABILITY_RULES

RULE: every WP must reference at least one requirement ID from Anna's formal spec. RULE: every requirement in Anna's spec must be covered by at least one WP. RULE: the spec_refs field in the WP links to Anna's requirement IDs. RULE: when a WP is marked COMPLETE, its spec_refs are marked as "implemented" in the traceability matrix.

TRACEABILITY_MATRIX_TEMPLATE

## Traceability Matrix: [Project Name]

| Spec Req ID | Requirement Summary          | WP(s)              | Status       |
|-------------|------------------------------|---------------------|--------------|
| REQ-001     | User registration with email | WP-001, WP-002     | Implemented  |
| REQ-002     | Role-based access control    | WP-002, WP-003     | In Progress  |
| REQ-003     | Order creation               | WP-005, WP-007     | Not Started  |
| REQ-004     | Order list with pagination   | WP-007, WP-008     | Not Started  |
| REQ-005     | Email notifications          | WP-012              | Not Started  |

Coverage: 5/5 requirements mapped (100%)
Unmapped requirements: none
WPs without spec ref: none

---

COMPLETENESS_VERIFICATION

PRE_DISPATCH_CHECKLIST

Before releasing a WP set for execution, verify:

[ ] Every Anna spec requirement has at least one WP assigned
[ ] Every WP has exactly one assignee agent
[ ] Every WP has a swimming lane
[ ] Every WP has estimated size (S/M/L)
[ ] Every WP has spec_refs linking to Anna's requirements
[ ] Dependency graph has no cycles
[ ] Critical path is identified and optimized
[ ] No WP exceeds 45 minutes estimated
[ ] Parallel execution groups are identified
[ ] No two parallel WPs modify the same files
[ ] Auth/infrastructure WPs are scheduled first
[ ] Testing WPs are included for every functional WP
[ ] Integration testing WP exists at the end

POST_COMPLETION_VERIFICATION

After all WPs complete:

[ ] Traceability matrix shows 100% coverage
[ ] All acceptance criteria from Anna's spec are met
[ ] No WPs remain in BLOCKED or FAILED state
[ ] Integration tests pass
[ ] Koen's lint check passes
[ ] Jasper's SSOT reconciliation passes

---

WORK_PACKAGE_TEMPLATE

# Work Package Definition
id: "WP-{sequential_number}"
project: "{client_code}-{project_code}"
title: "{8 words max, verb-noun format}"
description: |
  {2-5 lines describing exactly what this WP produces.
   Be specific about inputs and outputs.
   Name the files that will be created or modified.}

# Assignment
assigned_to: "{agent_name}"
swimming_lane: "LANE_DB | LANE_API | LANE_UI | LANE_DESIGN | LANE_TEST | LANE_INFRA | LANE_CONTENT"
team: "alfa | bravo"

# Sizing
estimated_size: "S | M | L"
estimated_minutes: 15-45

# Dependencies
depends_on:
  - "WP-{n}"  # hard dependency
soft_depends_on:
  - "WP-{n}"  # can proceed with mocks if not ready

# Traceability
spec_refs:
  - "REQ-{n}"
  - "REQ-{m}"

# Acceptance Criteria (from Anna's spec, scoped to this WP)
acceptance_criteria:
  - "Migration creates {table} with columns: {list}"
  - "Endpoint returns 200 with {schema} on valid input"
  - "Component renders {elements} with {states}"

# Context for the executing agent
context: |
  {What the agent needs to know that isn't in the spec.
   API contracts from adjacent WPs.
   Design tokens from DESIGN.md.
   Any gotchas or constraints.}

# Output artifacts (contract-check verifies these exist after session)
produces:
  - "drizzle/migrations/{timestamp}_{name}.sql"
  - "lib/api/routes/{entity}.ts"
  - "components/{entity}/{component}.tsx"

# Contract-Check Gate (Anthropic Harness Pattern)
# Executor runs these checks BEFORE signaling completion.
# Failures trigger self-correction (max 3 attempts) within same session.
contract:
  deliverables: ["lib/api/routes/{entity}.ts", "lib/api/routes/{entity}.test.ts"]
  acceptance_tests: "lib/api/routes/{entity}.test.ts"  # Antje's TDD tests
  lint_check: true  # Run ESLint + tsc
  spec_ref: "REQ-{n}"  # Traceability to Anna's spec

# Pipeline complexity (determines which quality stages run)
# simple: Koen + Marta only
# normal: Koen + Marije + Marta (default)
# complex: full pipeline (Koen + Marije + Jasper + Marco + Ashley + Jaap + Marta)
# critical: expedited (Team Zulu hotfixes)
complexity: "normal"

---

EXAMPLE: FULL_WP_DECOMPOSITION

PROJECT: CRM for a small accounting firm SPEC: Anna produced 12 requirements (REQ-001 through REQ-012)

# Phase 1: Foundation (sequential, critical path)
- id: WP-001
  title: "Create database schema migration"
  lane: LANE_DB
  assigned_to: urszula
  size: M
  depends_on: []
  spec_refs: [REQ-001, REQ-002, REQ-003, REQ-006]

- id: WP-002
  title: "Build auth endpoints with session management"
  lane: LANE_API
  assigned_to: urszula
  size: L
  depends_on: [WP-001]
  spec_refs: [REQ-001]

# Phase 1: Parallel with foundation
- id: WP-003
  title: "Setup DESIGN.md and global theme tokens"
  lane: LANE_DESIGN
  assigned_to: alexander
  size: S
  depends_on: []
  spec_refs: []

- id: WP-004
  title: "Write TDD specs for auth and client CRUD"
  lane: LANE_TEST
  assigned_to: antje
  size: M
  depends_on: []
  spec_refs: [REQ-001, REQ-002, REQ-003]

# Phase 2: Core APIs (after auth)
- id: WP-005
  title: "Build client CRUD API endpoints"
  lane: LANE_API
  assigned_to: urszula
  size: M
  depends_on: [WP-002]
  spec_refs: [REQ-002, REQ-003]

- id: WP-006
  title: "Build invoice CRUD API endpoints"
  lane: LANE_API
  assigned_to: urszula
  size: M
  depends_on: [WP-005]
  spec_refs: [REQ-006, REQ-007]

# Phase 2: Frontend (after auth + design)
- id: WP-007
  title: "Build login and registration pages"
  lane: LANE_UI
  assigned_to: floris
  size: M
  depends_on: [WP-002, WP-003]
  spec_refs: [REQ-001]

- id: WP-008
  title: "Build app layout with sidebar navigation"
  lane: LANE_UI
  assigned_to: floris
  size: S
  depends_on: [WP-003]
  spec_refs: []

# Phase 3: Feature UI (after APIs land)
- id: WP-009
  title: "Build client list and detail pages"
  lane: LANE_UI
  assigned_to: floris
  size: M
  depends_on: [WP-005, WP-008]
  spec_refs: [REQ-002, REQ-003]

- id: WP-010
  title: "Build invoice creation and list pages"
  lane: LANE_UI
  assigned_to: floris
  size: L
  depends_on: [WP-006, WP-008]
  spec_refs: [REQ-006, REQ-007]

# Phase 4: Polish and testing
- id: WP-011
  title: "Run integration tests and fix failures"
  lane: LANE_TEST
  assigned_to: marije
  size: M
  depends_on: [WP-009, WP-010]
  spec_refs: [REQ-001 through REQ-012]

- id: WP-012
  title: "Lint check and code standards enforcement"
  lane: LANE_TEST
  assigned_to: koen
  size: S
  depends_on: [WP-009, WP-010]
  spec_refs: []

CRITICAL_PATH: WP-001 → WP-002 → WP-005 → WP-006 → WP-010 → WP-011 (6 sequential WPs) PARALLEL_GROUPS: {WP-001} || {WP-003, WP-004}, {WP-005} || {WP-007, WP-008}, {WP-009} || {WP-010} TOTAL_WPS: 12 ESTIMATED_TOTAL_TIME: ~6 hours agent time (with parallelism: ~3.5 hours wall clock)

---

REPLANNING_TRIGGERS

TRIGGER_1: WP fails 2x → PM reviews scope. May need splitting or reassignment. TRIGGER_2: dependency cycle discovered → escalate to Anna for spec clarification. TRIGGER_3: agent discovers missing requirement during execution → PM creates ad-hoc WP, updates traceability. TRIGGER_4: client changes scope → PM re-runs completeness verification, adds/removes WPs. TRIGGER_5: critical path WP blocked → PM looks for WPs that can be promoted to unblock other work.

---

PM_DECISION_FRAMEWORK

DECIDE_SPLIT_OR_MERGE: if agent feedback says "ran out of context" → split. If agent says "trivial, done in 2 minutes" → merge next time. DECIDE_SEQUENCE_OR_PARALLEL: if WPs share no files and no data deps → parallel. When in doubt, sequence. DECIDE_ASSIGNMENT: match swimming lane to agent specialty. Never assign a backend WP to a frontend agent. DECIDE_PRIORITY: critical path WPs first. Then WPs that unblock the most other WPs. Then nice-to-haves.

---

INTEGRATION_WITH_ORCHESTRATOR

The ge-orchestrator enforces WP execution: - WPs are submitted to ge:work:incoming Redis stream - Orchestrator checks work_package_deps table for unresolved hard dependencies - Only dispatches WP to triggers.{agent} when all hard deps are COMPLETE - Max 1 WP per agent, max 5 parallel per feature branch - On WP completion, orchestrator cascades unblock to dependent WPs

PM submits the full WP set. Orchestrator handles scheduling and dispatch. PM monitors progress via admin-ui dashboard and re-plans when triggers fire.