tidaldb/.sdlc/tools/dev-driver/README.md

dev-driver

A stock sdlc tool that reads project state, finds the single most important next development action, dispatches it asynchronously, and exits. Paired with a recurring orchestrator action (every 4 hours), it makes your sdlc project self-advancing.

---

What it does

On each invocation, dev-driver applies a 5-level priority waterfall and takes exactly one action:

1. Flight lock — if a previous dispatch is still in flight (< 2h), do nothing
2. Quality check — if quality-check reports failures, do nothing (fix quality first)
3. Feature advancement — if any feature has an active directive, advance it one step
4. Wave start — if a milestone has all features PLANNED/READY, start the wave
5. Idle — nothing actionable, exit cleanly

One action per tick. The 4-hour recurrence IS the iteration rhythm.

---

Default action recipe

Create this action once in the sdlc UI or via CLI:

Label:      dev-driver
Tool:       dev-driver
Input:      {}
Recurrence: 14400    (4 hours in seconds)

Then run sdlc ui --run-actions to enable the orchestrator.

---

Priority waterfall (detail)

Level 1: Flight lock

Reads .sdlc/.dev-driver.lock. If the lock exists and is less than 2 hours old, exits immediately with { action: "waiting", lock_age_mins: N }.

This prevents double-dispatch when a previous Claude agent is still running.

Level 2: Quality check

Runs the quality-check tool. If any checks fail, exits with:

{ "action": "quality_failing", "failed_checks": ["test", "lint"] }

Fix the failing checks before dev-driver will advance features.

Level 3: Feature advancement

Finds features in implementation, review, audit, or qa phase with a pending directive. Picks the first one alphabetically. Dispatches:

claude --print "/sdlc-next <slug>"

This is /sdlc-next — one step only. The 4-hour recurrence advances the feature step by step over time. This is intentional: it keeps you in control and lets you course-correct between steps.

Returns:

{ "action": "feature_advanced", "slug": "my-feature", "phase": "implementation", "directive": "/sdlc-next my-feature" }

Level 4: Wave start

If no features have active directives but a milestone has all features in PLANNED or READY phase, starts the next wave:

claude --print "/sdlc-run-wave <milestone>"

Returns:

{ "action": "wave_started", "milestone": "v21-dev-driver" }

Level 5: Idle

No actionable work found. Returns:

{ "action": "idle", "reason": "no actionable work found" }

---

How to skip a feature

If you don't want dev-driver to autonomously advance a specific feature, add a task with skip:autonomous in the title:

sdlc task add <slug> --title "skip:autonomous: needs human review before proceeding"

Dev-driver will exclude this feature from Level 3 selection until the task is removed or marked done. You retain full control over which features advance autonomously.

---

One step, not full run

Dev-driver dispatches /sdlc-next <slug>, NOT /sdlc-run <slug>.

/sdlc-next executes exactly one directive (write a spec, approve a design, implement a task, etc.) and exits. The next tick, dev-driver will pick the same feature again and advance it one more step.

This means:

• Each tick = one atomic state machine step
• You can review after each step in the Actions page
• No surprise full-feature runs that take hours

---

Lock file

Path: .sdlc/.dev-driver.lock TTL: 2 hours

{
  "started_at": "2026-03-02T04:00:00.000Z",
  "action": "feature_advanced",
  "slug": "my-feature",
  "pid": 12345
}

The lock is written before each dispatch and cleared automatically after 2 hours. You can delete it manually if you need to run dev-driver before the TTL expires.

---

Output reference

All five possible outputs:

// Level 1 (lock)
{ "action": "waiting", "lock_age_mins": 45 }

// Level 1 (active run)
{ "action": "waiting", "reason": "agent run in progress" }

// Level 2
{ "action": "quality_failing", "failed_checks": ["test", "clippy"] }

// Level 3
{ "action": "feature_advanced", "slug": "my-feature", "phase": "implementation", "directive": "/sdlc-next my-feature" }

// Level 4
{ "action": "wave_started", "milestone": "v21-dev-driver" }

// Level 5
{ "action": "idle", "reason": "no actionable work found" }

All wrapped in: { "ok": true, "data": { ... }, "duration_ms": N }