ai-workflow-skill/docs/blog-project-example.md

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 orchestrator 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

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

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

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

orch ready --run blog_mvp_001 --json

Expected result:

{
  "ready": ["T1"]
}

5. Dispatch T1

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:

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

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

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

orch reconcile --run blog_mvp_001 --json
orch ready --run blog_mvp_001 --json

Expected result after reconciliation:

{
  "ready": ["T2"]
}

9. Leader Dispatches T2

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.

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

orch reconcile --run blog_mvp_001 --json
orch blocked --run blog_mvp_001 --json

Expected result:

{
  "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

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:

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

orch reconcile --run blog_mvp_001 --json
orch ready --run blog_mvp_001 --json

Expected result:

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

15. Leader Dispatches Three Tasks

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.

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:

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

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:

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