flow-conductor

flow-conductor

The science

• Queueing theory: Little's Law — WIP = throughput × cycle_time. Holding WIP constant, halving cycle time doubles throughput. The skill computes WIP utilization and cycle-time trend across stages.
• Lean kanban: pull-based work — work is pulled into a stage only when capacity is available. The conductor refuses (advisory mode) or blocks (enforce mode) new starts above WIP limit.
• Bottleneck identification (theory of constraints) — system throughput is determined by the slowest stage. The conductor names the current bottleneck stage and the data behind that judgment.
• State-machine integrity (CS) — invalid transitions (e.g. Done without verification, or PR-open without commits) are flagged.
• Cycle-time as leading metric (econ) — short cycle time → faster learning → less wasted exploration. The conductor surfaces cycle-time outliers as the highest-leverage place to act.

When to invoke

• Daily (recommended): launchd at 09:00 weekdays
• Manual: /flow-conductor or /delivery/flow-conductor
• Before pulling new work: /flow-conductor --before-pull

Profile check

python3 "$WOVOL_LAB_ROOT/.claude/skills/_foundation/profile-manager/scripts/profile.py" verify wovol || exit 2

Args

• --before-pull — strict mode; exits non-zero if WIP limit exceeded (script callers can chain this before starting new work)
• --enforce — same as --before-pull but with stronger UX gates (warns at multiple stages)
• --comment-on-bottleneck — post a comment on the oldest bottleneck item (uses pre-submit-confirm gate)
• --config <file> — override default flow-conductor.local.yml

Pipeline

1. Collect state in parallel:

   • Linear: list issues per state (Todo / In Progress / In Review / Done) for the configured project, plus updatedAt per item
   • GitHub: list open PRs (draft / ready / approved) + age per PR
   • Git: list local branches with ahead-behind counts vs main; dirty working tree warning

2. Compute critical path (WOV-79/80):

   • Invoke progressive-decompose/scripts/critical_path.py with the active issue list
   • Produces {issue_id: {on_critical_path, path_length_pt}}
   • The top 1-3 critical-path issues are rendered as the first block of the daily survey — these are the items that, if moved forward, reduce time-to-release
   • The same map is passed downstream to progressive-decompose and bottleneck-detector so decomposition pressure and leverage labels are weighted by CP membership

3. Compute metrics:

   • WIP per stage
   • Mean / median cycle time per stage (using Linear state-change history)
   • Stale-item flagging (no activity in N days; thresholds from config)
   • Bottleneck stage = stage where (current WIP × mean cycle time) is largest

4. Invoke bottleneck-detector agent with the collected data to produce a human-readable diagnosis (1 short paragraph, the WHY behind the numbers).

5. Apply WIP-limit policy:

   • Default WIP limits (from config): In Progress = 1, In Review = 2
   • Per-stage utilization: current_wip / limit
   • If --before-pull and any stage > 100%: exit non-zero
   • If advisory mode (default): warn at > 80%

6. Render report as Markdown to audit/delivery/flow-{date}.md:

   # Flow — YYYY-MM-DD
   
   ## Critical path (top 3)
   1. PROJ-79  build — critical_path.py        (in progress, 2pt)
   2. PROJ-80  integrate — CP downgrade        (todo, 1pt)
   3. PROJ-62  sanitize for public release     (todo, 3pt)
   
   ## Snapshot
   | Stage | WIP | Limit | Util | Oldest item age |
   |---|---|---|---|---|
   | In Progress | 0 | 1 | 0% | — |
   | In Review | 3 | 2 | 150% | 8d |
   | Done (last 7d) | 5 | — | — | — |
   
   ## Bottleneck
   **In Review** (current bottleneck — 150% utilization, oldest item 8d)
   
   Diagnosis: PRs are landing slower than they're opening; oldest is
   blocked on reviewer feedback. Two oldest:
   - TEAM-101: 8d, waiting on @reviewer (last comment 5d ago)
   - TEAM-102: 4d, draft state (needs to switch to ready)
   
   ## Stale items
   - TEAM-103 (Todo, 14d untouched) — consider closing or re-scoping
   - TEAM-104 (In Progress, 6d no commits) — likely abandoned
   
   ## Cycle time trend
   - 7d median: 2.3 days (Todo → Done)
   - 30d median: 1.8 days
   - Trending up ⚠ (50% increase from baseline)
   
   ## Recommendation
   1. Land one of the two In Review items today before starting anything new
   2. Switch TEAM-102 from draft to ready (no extra work needed)
   3. Decide on TEAM-103 / TEAM-104 — close or revive
   
   ## Local git state
   - main: up to date, clean ✓
   - feature/foo: 3 commits ahead, no PR (consider /pr-handoff)
   - wip/bar: 1 commit ahead, dirty tree ⚠
   

7. Optional: if --comment-on-bottleneck, post a 1-line comment on the oldest bottleneck item ("This item has been in for Nd") — pre-submit-confirm prompts.

Anti-patterns this skill refuses

• Pushing more work to an over-utilized stage. With --before-pull, exits non-zero rather than letting the caller start a new task.
• Auto-closing stale items. Surfaces them; never decides for you.
• Naming a bottleneck without data. The diagnosis paragraph cites numbers from the snapshot.
• Optimizing local-machine state without project-state context. The git section is always after the Linear/GitHub view (the project bottleneck dominates the local cleanliness).

Hooks engaged

Hook	When	What
audit-logger	every tool call	Standard
pre-submit-confirm	--comment-on-bottleneck only	Gates the optional Linear comment

Failure modes

Symptom	Cause	Action
Linear MCP down	Outage	Render git + GitHub only; note Linear unavailable
gh not authed	Token expired	Render Linear + git only; note gh unavailable
0 issues / 0 PRs	Empty project	Output: "Nothing in flight. Pull new work freely."
WIP limit exceeded in --before-pull	Real overload	Exit non-zero; caller (script) refuses to start work

Configuration

config/delivery.local.yml (gitignored, shared with delivery suite):

wip_limits:
  in_progress: 1
  in_review: 2

cycle_time_targets:
  iteration_minutes: 30
  pr_lead_time_hours: 24

bottleneck:
  stale_days_in_review: 3
  stale_days_in_progress: 5
  stale_days_in_todo: 14

flow_conductor:
  cycle_time_baseline_days: 30
  cycle_time_warn_growth_pct: 50         # warn if 7d median > baseline + 50%

Output

Stdout: 1-paragraph summary + recommendation. audit/delivery/flow-{date}.md: full report. Exit non-zero only with --before-pull and WIP > 100%.