# Blog Project Example

## Goal

This document simulates how a leader should use `orch` and how workers should use `inbox` for a blog MVP.

Assumptions:

- stack: `Next.js + PostgreSQL + Prisma`
- features: public blog pages, admin login, post CRUD, tags, basic tests
- leader owns planning, architecture, dependency decisions, and final integration

## Task Graph

The leader decomposes the work into these tasks:

- `T1`: project skeleton and base wiring
- `T2`: data model and migrations
- `T3`: auth and API contract
- `T4`: backend post and tag APIs
- `T5`: admin UI
- `T6`: public blog UI
- `T7`: QA and acceptance
- `T8`: final integration and user-facing handoff

Dependencies:

- `T2` depends on `T1`
- `T3` depends on `T2`
- `T4` depends on `T3`
- `T5` depends on `T3`
- `T6` depends on `T3`
- `T7` depends on `T4`, `T5`, and `T6`
- `T8` depends on `T7`

## Who Uses What

- leader uses the `orch` skill and `orch` CLI
- workers use the `inbox` skill and `inbox` CLI
- `orch` is the leader's main interface
- `inbox` is the worker's main interface

## Simulated Leader Flow

### 1. Create the Run

```bash
orch run init --db .agents/coord.db --run blog_mvp_001 --goal "Build blog MVP" --summary "Public blog plus admin CRUD" --json
```

### 2. Register Tasks

```bash
orch task add --run blog_mvp_001 --task T1 --title "Project skeleton" --summary "Initialize app structure, env template, and DB wiring" --default-to foundation-worker --json
orch task add --run blog_mvp_001 --task T2 --title "Data model and migrations" --summary "Create users, posts, tags, and post_tags schema" --default-to db-worker --json
orch task add --run blog_mvp_001 --task T3 --title "Auth and API contract" --summary "Define admin auth flow and CRUD contract" --default-to backend-worker --json
orch task add --run blog_mvp_001 --task T4 --title "Backend APIs" --summary "Implement post and tag CRUD" --default-to backend-worker --json
orch task add --run blog_mvp_001 --task T5 --title "Admin UI" --summary "Implement login and post management pages" --default-to admin-ui-worker --json
orch task add --run blog_mvp_001 --task T6 --title "Public blog UI" --summary "Implement homepage, post detail, and tag page" --default-to frontend-worker --json
orch task add --run blog_mvp_001 --task T7 --title "QA and acceptance" --summary "Run smoke tests and verify MVP acceptance" --default-to qa-worker --json
orch task add --run blog_mvp_001 --task T8 --title "Final integration" --summary "Leader verifies final system and prepares handoff" --json
```

### 3. Register Dependencies

```bash
orch dep add --run blog_mvp_001 --task T2 --depends-on T1 --json
orch dep add --run blog_mvp_001 --task T3 --depends-on T2 --json
orch dep add --run blog_mvp_001 --task T4 --depends-on T3 --json
orch dep add --run blog_mvp_001 --task T5 --depends-on T3 --json
orch dep add --run blog_mvp_001 --task T6 --depends-on T3 --json
orch dep add --run blog_mvp_001 --task T7 --depends-on T4 --json
orch dep add --run blog_mvp_001 --task T7 --depends-on T5 --json
orch dep add --run blog_mvp_001 --task T7 --depends-on T6 --json
orch dep add --run blog_mvp_001 --task T8 --depends-on T7 --json
```

### 4. Ask What Is Ready

```bash
orch ready --run blog_mvp_001 --json
```

Expected result:

```json
{
  "ready": ["T1"]
}
```

### 5. Dispatch `T1`

```bash
orch dispatch --run blog_mvp_001 --task T1 --to foundation-worker --body "Set up the app skeleton, env.example, Prisma initialization, base routes, and startup instructions." --json
```

The leader does not hand-write `inbox send`. `orch dispatch` does that under the hood.

If nothing else is actionable after dispatch, the leader should block on `orch wait` instead of sleeping:

```bash
orch wait --run blog_mvp_001 --for task_blocked,task_done,task_failed --after-event 0 --timeout-seconds 900 --json
```

## Simulated Worker Flow

### 6. Foundation Worker Polls Inbox

```bash
inbox fetch --db .agents/coord.db --agent foundation-worker --status pending --json
inbox claim --db .agents/coord.db --agent foundation-worker --thread thr_t1_attempt1 --lease-seconds 1800 --json
inbox update --db .agents/coord.db --agent foundation-worker --thread thr_t1_attempt1 --status in_progress --summary "Initializing project and wiring Prisma" --json
```

### 7. Foundation Worker Finishes

```bash
inbox done --db .agents/coord.db --agent foundation-worker --thread thr_t1_attempt1 --summary "Project skeleton complete" --body "Project starts locally, DB wiring exists, and env template is present." --json
```

## Leader Reconciliation Loop

### 8. Leader Reconciles

```bash
orch reconcile --run blog_mvp_001 --json
orch ready --run blog_mvp_001 --json
```

Expected result after reconciliation:

```json
{
  "ready": ["T2"]
}
```

### 9. Leader Dispatches `T2`

```bash
orch dispatch --run blog_mvp_001 --task T2 --to db-worker --body "Create the blog schema with users, posts, tags, and post_tags. Include migration files and keep the schema MVP-scoped." --json
```

### 10. Worker Gets Blocked

The database worker discovers a missing product decision.

```bash
inbox update --db .agents/coord.db --agent db-worker --thread thr_t2_attempt1 --status blocked --summary "Need post status values" --payload-json '{"question":"Should MVP support only draft and published, or more states?"}' --json
inbox wait-reply --db .agents/coord.db --thread thr_t2_attempt1 --after-event 0 --timeout-seconds 1800 --json
```

### 11. Leader Reviews Blocked Work Through `orch`

```bash
orch reconcile --run blog_mvp_001 --json
orch blocked --run blog_mvp_001 --json
```

Expected result:

```json
{
  "blocked": [
    {
      "task_id": "T2",
      "thread_id": "thr_t2_attempt1",
      "question": "Should MVP support only draft and published, or more states?"
    }
  ]
}
```

### 12. Leader Answers Without Leaving the Scheduler

```bash
orch answer --run blog_mvp_001 --task T2 --body "Use only draft and published for the MVP. Do not add archived or soft delete yet." --json
```

`orch answer` writes the response back into the mapped inbox thread.

### 13. `T2` Completes, Then `T3` Runs

The worker resumes and finishes through `inbox done`.

The leader continues the same loop:

```bash
orch reconcile --run blog_mvp_001 --json
orch ready --run blog_mvp_001 --json
orch dispatch --run blog_mvp_001 --task T3 --to backend-worker --body "Define admin auth and the API contract for posts and tags. Output the contract as a project artifact and keep UI workers unblocked." --json
```

## Parallel Stage

### 14. `T3` Finishes and Unblocks `T4`, `T5`, and `T6`

```bash
orch reconcile --run blog_mvp_001 --json
orch ready --run blog_mvp_001 --json
```

Expected result:

```json
{
  "ready": ["T4", "T5", "T6"]
}
```

### 15. Leader Dispatches Three Tasks

```bash
orch dispatch --run blog_mvp_001 --task T4 --to backend-worker --body "Implement the post and tag APIs exactly as defined by the contract." --json
orch dispatch --run blog_mvp_001 --task T5 --to admin-ui-worker --body "Build the admin login and post management UI against the published API contract." --json
orch dispatch --run blog_mvp_001 --task T6 --to frontend-worker --body "Build the public blog pages against the published API contract." --json
```

### 16. Another Block Arrives

The admin UI worker asks whether to use a rich text editor.

```bash
inbox update --db .agents/coord.db --agent admin-ui-worker --thread thr_t5_attempt1 --status blocked --summary "Editor choice undecided" --payload-json '{"question":"Should the admin editor use a rich text editor or plain textarea in MVP?"}' --json
```

Leader response:

```bash
orch reconcile --run blog_mvp_001 --json
orch blocked --run blog_mvp_001 --json
orch answer --run blog_mvp_001 --task T5 --body "Use a plain textarea in MVP. Avoid adding a rich text dependency in this phase." --json
```

The worker then resumes after `inbox wait-reply` wakes with the leader's answer. No side uses blind `sleep` loops.

## QA and Follow-Up Fix

### 17. QA Runs After `T4`, `T5`, and `T6`

```bash
orch reconcile --run blog_mvp_001 --json
orch ready --run blog_mvp_001 --json
orch dispatch --run blog_mvp_001 --task T7 --to qa-worker --body "Verify login, post CRUD, public blog pages, and tag filtering. Return minimal repro steps for any failures." --json
```

### 18. QA Finds a Contract Mismatch

QA reports that deleting a post returns an unexpected response shape.

The leader can create a follow-up fix task:

```bash
orch task add --run blog_mvp_001 --task T7a --title "Fix delete post response mismatch" --summary "Align delete response with the published API contract" --default-to backend-worker --json
orch dep add --run blog_mvp_001 --task T7a --depends-on T7 --json
orch reconcile --run blog_mvp_001 --json
orch ready --run blog_mvp_001 --json
orch dispatch --run blog_mvp_001 --task T7a --to backend-worker --body "Fix the delete post response so it matches the contract used by QA and admin UI." --json
```

## Final Leader Responsibilities

The leader still owns:

- keeping the run coherent
- answering blocked questions
- deciding scope reductions such as textarea instead of rich text
- adding fix tasks after QA
- verifying final acceptance before handoff

The workers do not own those cross-task decisions.

## What This Example Shows

- leader planning and dispatch happen through `orch`
- worker execution happens through `inbox`
- blocked handling stays leader-controlled
- `inbox` is the durable bus
- `orch` is the actual scheduling surface
- leader and workers wait on blocking CLI primitives rather than manual sleeps