# Board Execution

Board Execution is the Kanban execution engine used by Assemble during **Phase 4 — IMPLEMENT** of **COMPLEX** Spec-Driven workflows. Instead of treating implementation as one linear block, Assemble generates a structured `_board.yaml` and executes multiple tickets in parallel without losing review gates, dependency order, or traceability.

## Introduction

Board Execution sits between planning and delivery. Once `tasks.md` exists, Captain America converts it into `_board.yaml`, which becomes the source of truth for execution state. The engine then advances tickets through a controlled pipeline, automatically respecting dependencies, WIP limits, and role boundaries.

Use Board Execution when a workflow is large enough to benefit from parallelism. For smaller jobs, Assemble can keep a simpler linear implementation path.

## Board Format

`_board.yaml` stores workflow metadata, board columns, WIP limits, and every execution ticket.

### Example `_board.yaml`

```
meta:

workflow: feature-development

created_at: 2026-03-29T16:00:00Z

sprint_goal: "User management API + admin dashboard"

source_files:

- spec.md

- plan.md

- tasks.md

columns:

- todo

- in_progress

- review

- test

- done

wip_limits:

in_progress: 3

review: 2

test: 2

tickets:

- id: T-001

title: "Create POST /users endpoint"

type: story

story: "As an admin, I want to create a user through the API so that onboarding can be automated."

points: 5

priority: 1

acceptance_criteria:

- id: AC-001

given: "valid user payload"

when: "POST /users is called"

then: "the API returns 201 and the created user object"

- id: AC-002

given: "an email that already exists"

when: "POST /users is called"

then: "the API returns 409 with DUPLICATE_EMAIL"

depends_on: []

pipeline:

implement: [dev-backend]

review: [dev-fullstack]

test: [qa]

status: in_progress

assigned_to:

- dev-backend

started_at: 2026-03-29T16:10:00Z

completed_at: null

artifacts:

- path: src/api/users.ts

type: code

- path: tests/users.spec.ts

type: test

feedback:

review: null

test: null

- id: T-002

title: "Build users table on admin dashboard"

type: story

story: "As an admin, I want to see all users in a dashboard table so that I can manage accounts quickly."

points: 3

priority: 2

acceptance_criteria:

- id: AC-003

given: "existing users in the system"

when: "the admin dashboard loads"

then: "the table displays user name, email, and status"

depends_on:

- T-001

pipeline:

implement: [dev-frontend]

review: [dev-fullstack]

test: [qa]

status: todo

assigned_to: null

started_at: null

completed_at: null

artifacts: []

feedback:

review: null

test: null
```

### Field overview

- `meta`: workflow metadata and provenance
- `columns`: visible board stages
- `wip_limits`: maximum tickets allowed in constrained columns
- `tickets`: execution units with ownership, status, dependencies, artifacts, and feedback
- `acceptance_criteria`: Given/When/Then checks used during validation
- `pipeline`: role assignment for implement, review, and test

## Ticket Lifecycle

Each ticket follows the same lifecycle:

```
todo → in_progress → review → test → done
```

### Transition rules

#### `todo` → `in_progress`

Allowed only when:

- all `depends_on` tickets are already `done`
- the `in_progress` WIP limit is not exceeded
- implementation ownership is defined in `pipeline.implement`

On transition, the engine sets `assigned_to` and `started_at`.

#### `in_progress` → `review`

Allowed only after implementation artifacts exist. The ticket is reassigned to the review role defined in `pipeline.review`.

#### `review` → `in_progress`

Used when review finds blocking issues. Existing artifacts stay attached and blocking feedback is appended for the implementing agent.

#### `review` → `test`

Allowed only after explicit review approval. The ticket is then handed to the testing role defined in `pipeline.test`.

#### `test` → `in_progress`

Used when one or more acceptance criteria fail. Feedback should point to the exact acceptance criterion that failed.

#### `test` → `done`

Allowed only when every acceptance criterion passes. The engine sets `completed_at` and preserves the artifact and feedback trail.

## WIP Limits

WIP limits prevent the board from flooding a stage faster than the team can process it. They are configured in `wip_limits`.

```
wip_limits:

in_progress: 3

review: 2

test: 2
```

Rules:

- if `in_progress` is full, ready tickets remain in `todo`
- if `review` is full, completed implementation waits before moving forward
- if `test` is full, approved tickets queue until a slot opens
- columns without an explicit limit are unconstrained

## Dependency Resolution

A ticket can start only when every ticket listed in `depends_on` is already `done`. Dependency resolution is automatic; agents do not bypass it manually.

This enables safe parallelism:

- independent tickets can move at the same time
- blocked tickets remain visible
- downstream work starts only after upstream artifacts are complete and validated

## Context Injection

Board Execution injects ticket-specific context into each agent invocation rather than dumping the whole board into every prompt. Typical injected context includes:

- ticket identity: `id`, `title`, `type`, `priority`, `story`
- acceptance contract: full `acceptance_criteria`
- dependency context: dependency IDs plus completed artifacts from upstream tickets
- current state: `status`, `assigned_to`, timestamps, and known feedback
- current stage role: implement, review, or test

This keeps agents focused and reduces accidental cross-ticket interference.

## Agent Roles

Board Execution depends on clear responsibility boundaries:

- **PM (Professor X)** defines structured tickets and Given/When/Then acceptance criteria
- **Scrum Master (Captain America)** transforms `tasks.md` into `_board.yaml` and manages execution rules
- **Dev agents** implement ticket work during `in_progress`
- **Review agents** validate implementation quality before promotion to test
- **QA** verifies acceptance criteria in the `test` stage
- **Jarvis** orchestrates transitions, checks dependencies, and keeps state synchronized

## Integration with Spec-Driven Methodology

Board Execution powers **Phase 4 — IMPLEMENT** for complex workflows:

1. **BRAINSTORM** or upstream discovery, if needed
2. **SPECIFY** → `spec.md`
3. **PLAN** → `plan.md`
4. **TASKS** → `tasks.md`
5. **IMPLEMENT** → Captain America generates `_board.yaml`, then Board Execution runs tickets
6. **CLOSE** → Jarvis consolidates quality output in `_quality.md`

For simple work, Assemble can skip board creation and keep a linear implementation path. The board is for complexity, not ceremony.

## Anti-patterns

Avoid these mistakes:

- executing a ticket whose dependencies are not `done`
- exceeding a declared WIP limit
- skipping review or test to move faster
- injecting the full board into every ticket execution
- rewriting acceptance criteria during execution
- marking a ticket `done` without validating every Given/When/Then criterion
- dropping artifacts or feedback when a ticket loops back from review or test
- using the board for trivial work that does not justify Kanban overhead