workflow

# Workflow-Driven Implementation

Implement an approved spec by having Claude **design and run its own Claude Code dynamic workflow** — an orchestration of real parallel subagents that build the spec in the background. You supply the spec, the goal, and the constraints; Claude chooses the phases, how many agents to run, and how they divide and cross-check the work. Only the final result returns to this conversation.

This skill is a peer of `/optimus:tdd`. Both implement a spec and feed the same `→ /optimus:pr` handoff; they differ in *how* they build.

**The quality bar, not a ceremony.** This skill does not supervise Red-Green-Refactor. It hands Claude a test-first **quality bar** — tests accompany or precede the code they cover, the full suite is run and left green, and that green run is the completion gate. If you want enforced per-behavior test-first discipline with a failing-test-first guarantee (the Iron Law), use `/optimus:tdd` instead. For restructuring existing code without new behavior, use `/optimus:refactor`.

## Step 1: Pre-flight

Read `$CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md` for workspace detection. If a multi-repo workspace is detected, run this skill inside the repo the user is targeting. If ambiguous, ask which repo.

### Verify prerequisites

Check that `.claude/CLAUDE.md` exists. If it doesn't, stop and recommend running `/optimus:init` first — coding guidelines and project context steer the workflow's quality bar.

This skill launches a Claude Code **dynamic workflow** (Step 4 invokes the Workflow tool). If dynamic workflows are not available in this session — a recent Claude Code is required, and on some plans the feature must be enabled in `/config` — stop now and tell the user to enable it. Do not proceed to create a branch in Step 3 for a launch that cannot run.

Load these documents (they become constraints in the workflow brief):

| Document | Role |
|----------|------|
| `.claude/CLAUDE.md` | Project overview — tech stack, test runner command |
| `coding-guidelines.md` | Code quality reference the workflow must follow |
| `testing.md` | Testing conventions — file location, naming, framework, mocking |
| `docs/product/tech-stack.md` *(if present)* | SDD steering — target stack |
| `docs/product/mvp-prd.md` *(if present)* | SDD steering — MVP scope |

Load the two `docs/` rows **only if they exist** (the optional spec-driven-development steering cascade scaffolded by `/optimus:spec-init`); see `$CLAUDE_PLUGIN_ROOT/references/sdd-mapping.md` for the precedence contract. For monorepos, read the "Monorepo Scoping Rule" section of `$CLAUDE_PLUGIN_ROOT/skills/init/references/constraint-doc-loading.md` and load the targeted subproject's docs.

### Verify test infrastructure

Locate the test runner command from `testing.md`, `CLAUDE.md`, or project manifests (`package.json` scripts, `Makefile`, `Cargo.toml`, etc.). Run it once to confirm it works and the suite is **currently green**.

- **Green** — proceed to Step 2. (The post-workflow green run in Step 5 is only meaningful against a known-green baseline.)
- **Failing** — stop and report. Resolve existing failures first; otherwise the workflow's green gate is meaningless.
- **No test runner found** — stop and recommend `/optimus:init` to set up test infrastructure. For a project with no code or detectable stack yet, tell the user to pick **Scaffold new project** when init asks.

**Capture the coverage baseline now** — this green run is the only point before the workflow modifies the tree. Detect a coverage command per `$CLAUDE_PLUGIN_ROOT/skills/tdd/references/coverage-detection.md`; if one exists, run it once and record the result as the Step 6 `Before` value. If none is available, skip this — Step 6 omits the Coverage section.

## Step 2: Acquire the spec

Resolve the spec with the shared cascade in `$CLAUDE_PLUGIN_ROOT/skills/tdd/references/spec-context-detection.md` (explicit `docs/specs/`/`docs/jira/` reference → build-spec auto-discovery → JIRA auto-discovery → none, plus long-spec distillation to a single-sentence goal).

If the cascade resolved a spec, use it. Otherwise, if the user gave a task inline (e.g., `/optimus:workflow "Build the CSV import pipeline"`), use it. Otherwise, use `AskUserQuestion` — header "Spec", question "What spec or feature should the workflow implement?".

Whatever the source — a spec or JIRA context the cascade resolved, an inline argument, or the answer above — apply the shared reference's **Distillation** step to the final spec/goal: if it runs longer than ~2-3 sentences, distill it to a single-sentence goal (the brief's `Goal:` slot in Step 4) and confirm via `AskUserQuestion` before proceeding.

**Light suitability guard** (this skill skips TDD's full classification — a workflow is not bound to testable-behavior decomposition):
- If the task is clearly **restructuring existing code without new behavior** → recommend `/optimus:refactor` and stop.
- If it is **documentation-only or pure configuration** → note a workflow is overkill; a normal turn (or `/optimus:commit`) suffices. Stop unless the user insists.
- Otherwise, proceed.

## Step 3: Create a feature branch

Keep the user's original branch clean — all workflow edits land on a new branch.

1. Record the current branch (this becomes the PR/MR target): `git rev-parse --abbrev-ref HEAD`
2. Derive a branch name. Read `$CLAUDE_PLUGIN_ROOT/skills/commit/references/branch-naming.md` for the convention. `<type>` is `feat` (or `fix`); `<description>` is the slugified goal.
3. Create and switch: `git checkout -b <branch-name>`
4. Report:

```
## Branch

Created branch `<branch-name>` from `<original-branch>`.
The workflow will build on this branch.
```

Do **not** add git-worktree isolation here — workflow subagents already run as isolated background agents with auto-approved edits; a second isolation layer would only blur the edit-scope guardrail in Step 4.

## Step 4: Design and run the workflow

Compose