start-dev

Files (8)

• SKILL.md
• evals.json · evals/
• objective.json · evals/files/objectives/auth-system/
• plan.md · evals/files/
• trigger-evals.json · evals/
• pr-templates.md · references/
• detect-objective.sh · scripts/
• detect-stack.sh · scripts/

SKILL.md (first lines)

# start-dev

Compatibility entry point for "implement this". Routes the request to the right piece of the workflow and stays out of the way.

> **Direction of travel.** Implementing and delivering are now separate skills: `worker-dev` (implement → validate → commit → handoff, inside an objective) and `deliver-dev` (review the integrated diff → gates → push → one PR for the objective). `/start-dev` remains a fully supported front door: for a simple standalone task it still runs the same implement→PR flow it always has, and for work an objective already owns it hands off to `worker-dev` and opens no PR. Nothing you invoke today stops working. Over time, reach for `/orchestrate-dev` for multi-part work, and `worker-dev`/`deliver-dev` directly when you want one half of an objective's flow.

## Why this skill exists

`start-dev` used to run one monolithic implementation→PR flow, which quietly assumed **every task is its own pull request**. That assumption breaks the moment a single user objective is split across several tasks: you get five PRs for one feature, five CI runs, five review cycles, and no place where the combined diff is ever reviewed. The routing below fixes that while preserving the one-task-one-PR path for the case where it is genuinely correct.

## Input

Parse `$ARGUMENTS` as one of:
- GitHub issue number(s): `#258` or `258 259 260`
- A free-text task description: `"Add rate limiting to the /login endpoint"`
- A file path to a spec or plan: `path/to/plan.md`

If `$ARGUMENTS` is empty, ask "What do you want to implement?" and stop.

## Step 0 — Route (do this before anything else)

```bash
REPO_ROOT="$(git rev-parse --show-toplevel)"
SKILL_DIR="${CLAUDE_SKILL_DIR:-$REPO_ROOT/skills/dev-workflow/start-dev}"

ROUTE="$(bash "$SKILL_DIR/scripts/detect-objective.sh" "$REPO_ROOT")"
MODE="$(echo "$ROUTE" | jq -r .mode)"
OBJECTIVE_ID="$(echo "$ROUTE" | jq -r '.objective_id // empty')"
echo "$ROUTE" | jq -r '"route: \(.mode) — \(.reason)"'
```

Then pick exactly one of three routes:

| Route | When | What runs | PR? |
|---|---|---|---|
| **A — worker only** | `MODE=worker-only`: an objective already owns this work (an `.dev-files/objectives/<id>/objective.json` is active, or an orchestrator invoked us) | `worker-dev` | **No** |
| **B — orchestrate** | The request is a non-trivial multi-part objective (see the test below) | Recommend/route to `orchestrate-dev` | One, opened by `deliver-dev` at the end of the objective |
| **C — implement + deliver** | `MODE=worker-and-deliver` and the task is genuinely simple and independent | this skill's own flow (identical to the pre-split `/start-dev`) | Yes — one |

### The multi-part test (route B)

**Skip this test entirely — route C is the answer — when `orchestrate-dev` sent the work here.** Its fall-through is one-directional: it already applied the orchestration test and decided against it, so re-applying the test here would bounce the request between the two skills forever. Recognise the hand-off by any of:

- `TAMIRS_ROUTED_FROM=orchestrate-dev` in the environment;
- the invocation says the orchestration decision is already made, or "do not route back";
- this run was reached from `orchestrate-dev` in the same session.

If the work genuinely looks bigger than `orchestrate-dev` judged, say so in one line and let the user decide — never re-route on your own.

Otherwise, route to `orchestrate-dev` when **two or more** of these hold:

- the work splits into parts that could progress independently;
- it needs more than one role (e.g. implementer **and** test-engineer **and** reviewer);
- it plausibly touches more than ~10 files or more than one subsystem;
- the user's phrasing is objective-shaped ("build the auth system", "migrate X to Y") rather than task-shaped;
- a spec/plan file was passed containing multiple distinct phases.

Say so in one line and offer the route rather than silently switching:

```
This looks like a multi-part objective (auth API + migration + tests, 3 roles).
Running /orchestrate-dev — one objective, one PR at the end.
Say "just do it directly" and I'll run it as a single task instead.
```

If the user declines, continue on route C — never refuse the work.

---

## Route A — worker only (objective already active)

The objective owns delivery. This run ends at **commit + handoff**, exactly like `worker-dev` invoked directly.

```
Skill: worker-dev
Arguments: <objective-id> <task-id>
```

`worker-dev` needs both ids and reads the task file for its `scope`, `role` and `validation_tier`. Resolve them before dispatching:

```bash
SHARED_DIR="$REPO_ROOT/skills/dev-workflow/_shared/scripts"
OBJECTIVE_ID="${OBJECTIVE_ID:-$(bash "$SHARED_DIR/objective-state.sh" active)}"
TASK_ID="$(bash "$SHARED_DIR/objective-state.sh" next "$OBJECTIVE_ID")"
```

If no task matches the user's request — they asked for something the objective does not cover — say so and ask whether to add a task to the objective or run it standalone (route C). Do not invent a task id.

**Hard stop:** do not `gh pr create`, do not `gh pr merge --auto`, do not merge the base branch, and do not run the full repo suite unless the task's `validation_tier` says to. Delivery for the whole objective happens once, in `deliver-dev`.

Report at the end:

```
Task complete — committed on <branch>, handoff written to
.dev-files/objectives/<id>/handoffs/<task-id>.json
No PR opened: objective <id> owns delivery (run /orchestrate-dev or /deliver-dev to ship it).
```

---

## Route B — multi-part objective

```
Skill: orchestrate-dev
Arguments: <the original $ARGUMENTS>
```

`orchestrate-dev` builds the task DAG, runs the workers (in parallel where the platform supports subagents, sequentially where it does not), integrates, and calls `deliver-dev` once. Nothing further is required here.

---

## Route C — simple standalone task (the classic `/start-dev` behaviour)

This is the original flow, unchanged. `worker-dev` and `deliver-dev` are objective-scoped — they need a task file and an objective branch respectively — so a genuine one-off task runs here rather than through them. This is exactly what `deliver-dev` means when it points non-objective work back at "start-dev's delivery path".

Sequence:

1. **Understand** — `gh issue view <n>`, or read the spec file; confirm your understanding in one sentence. When working from a GitHub issue, read the Resume block first and stop if it reports a blocker:
   ```bash

From Tamircohen28/tamirs-superpowers, MIT.

More from Tamircohen28/tamirs-superpowers