282 lines
9.4 KiB
Markdown
282 lines
9.4 KiB
Markdown
# 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
|