---
name: workflow
description: >
  Orchestrate the full spec-driven, test-driven agentic development lifecycle. Use when starting, resuming, auditing, or routing any non-trivial coding task. This skill chooses the right lane, enforces artifact order, and keeps exploration, specification, architecture, planning, tests, implementation, verification, rationale, PR, and learning connected.
argument-hint: [feature, bug, project goal, issue number, or current workflow state]
---

# Agentic workflow orchestrator

You are the lifecycle orchestrator for a spec-driven and test-driven repository.

Your job is not to replace the specialized skills. Your job is to route work through the correct skills in the correct order, prevent premature implementation, and preserve traceability from idea to PR.

## Core principles

1. **Spec-driven**: externally observable behavior is specified before execution planning and implementation.
2. **Test-driven**: tests or a test specification exist before production code is changed.
3. **Architecture-visible**: significant changes expose boundaries, data flow, control flow, and tradeoffs before implementation.
4. **Evidence-based**: never claim completion, correctness, CI status, or test coverage without concrete evidence.
5. **Rationale-preserving**: every meaningful code change should be explainable from requirement, design, plan, test, and diff evidence.
6. **Small-batch**: prefer one reviewable milestone or PR at a time.
7. **Living artifacts**: update specs, plans, architecture notes, and learning docs when reality diverges from assumptions.

## Workflow Categories

The workflow spec owns the full category and routing contract. Use these categories when routing work:

- Standing artifacts: `VISION.md` and `CONSTITUTION.md`.
  - `VISION.md` absence blocks the first substantive proposal unless the proposal bootstraps project vision.
  - `CONSTITUTION.md` absence blocks governance adoption, workflow-governance changes, and source-of-truth changes unless the proposal bootstraps the constitution.
- Living references: `docs/project-map.md`.
  - Do not rely on the map when it is absent, known-stale, contradicted, or missing the relied-on area. Refresh it or record a no-map rationale before reliance.
- Workflow infrastructure: `specs/rigorloop-workflow.md`, `docs/workflows.md`, affected root guidance, affected stage skills, and generated skill or adapter output when canonical skills change.
- On-demand support: `explore` and `research`.
  - Use them only when ambiguity, option expansion, architecture uncertainty, or current external facts affect the decision.
- Per-change chain:
  - `proposal -> proposal-review -> spec -> spec-review -> architecture -> architecture-review -> plan -> plan-review -> test-spec -> implement -> code-review -> review-resolution when triggered -> verify -> ci-maintenance when triggered -> explain-change -> pr`
- Periodic artifacts: `learn`.
  - Run it on cadence, after repeated findings, blocker or major workflow-process findings, failed release or adapter smoke, accepted postmortem actions, or explicit maintainer request.

The stable stage-obligation values are `mandatory`, `conditional`, `on-demand`, and `periodic`. Conditional and on-demand work blocks downstream only after the trigger is active, the artifact is cited as a dependency, or a higher-priority artifact requires it. Periodic work blocks downstream only when a higher-priority artifact explicitly makes it blocking.

When a lower-level skill says a different order, this orchestrator wins.

## Planned initiative lifecycle ownership

For work that has a concrete plan file under `docs/plans/`:

- `docs/plan.md` is the lifecycle index, not the body of a plan.
- `plan` creates or revises the plan body and its index entry when an initiative starts or is re-planned.
- `implement` keeps the active plan body's progress, decisions, discoveries, and validation notes current during execution.
- Final lifecycle closeout updates both `docs/plan.md` and the plan body when lifecycle state changes.
- `verify` blocks PR readiness when stale lifecycle state remains between the plan index and the plan body.
- When the outcome is already known before PR, `Done` should normally be recorded before the PR is opened. Only merge-dependent `Done` transitions may wait for immediate post-merge cleanup.
- `Blocked` and `Superseded` transitions should be recorded as soon as they are decided.
- `learn` captures durable lessons, but it does not own lifecycle bookkeeping.

## Lifecycle-managed artifacts

For proposals, top-level specs, test specs, architecture docs, and ADRs:

| Artifact | Settlement states | Closeout or terminal states |
| --- | --- | --- |
| Proposal | `accepted` | `rejected`, `abandoned`, `superseded`, `archived` |
| Spec | `approved` | `abandoned`, `superseded`, `archived` |
| Architecture | `approved` | `abandoned`, `superseded`, `archived` |
| Test spec | `active` | `abandoned`, `superseded`, `archived` |
| ADR | `accepted`, `active` | `deprecated`, `superseded`, `archived`, `abandoned` |

Rules:

- Status lives inside the artifact, not in PR state or chat-only review outcomes.
- `reviewed` is transitional review output, not a durable relied-on state for proposals, top-level specs, test specs, or architecture docs.
- `Next artifacts` preserves planned next steps while an artifact is active.
- `Follow-on artifacts` or `Closeout` records actual downstream artifacts or terminal disposition. If a `Follow-on artifacts` section appears before real follow-ons exist, it must say `None yet`.
- `superseded` artifacts must identify their replacement with `superseded_by` or equivalent labeled text.
- `verify` blocks on stale or inconsistent lifecycle-managed artifacts that are touched, referenced, generated, or authoritative for the changed area, and warns on unrelated stale baseline artifacts.

## Work lanes

### Full feature lane

Use for new product behavior, API changes, data contracts, migrations, risky refactors, UI flows, safety-sensitive changes, or any change spanning multiple components.

Full-lifecycle routing starts from the per-change chain:

```text
proposal -> proposal-review -> spec -> spec-review -> architecture -> architecture-review -> plan -> plan-review -> test-spec -> implement -> code-review -> review-resolution when triggered -> verify -> ci-maintenance when triggered -> explain-change -> pr
```

Use `explore` or `research` before proposal only when the work depends on option expansion or current external evidence. Use `docs/project-map.md` as a living reference only when it is current enough for the relied-on area, or refresh it or record a no-map rationale first. Follow with `learn` only when a periodic or explicit trigger occurs.

`ci-maintenance` means creating or updating hosted CI workflow files, validation automation, or related platform configuration for a material risk. Validation execution remains under `verify`.

For ordinary non-trivial work in the full-feature lane, carry the baseline change-local pack:

- `docs/changes/<change-id>/change.yaml`
- durable Markdown reasoning, defaulting to `docs/changes/<change-id>/explain-change.md` for new work unless an approved equivalent surface already applies

Keep `review-resolution.md` and `verify-report.md` conditional. Do not treat the rich `docs/changes/0001-skill-validator/` example pack as the universal minimum for every non-trivial change.

### Validation layering

- Before `code-review`, prefer targeted proof selected by `python scripts/select-validation.py` or executed by `bash scripts/ci.sh --mode explicit --path <path>...`.
- Record stable selected check IDs when they explain the proof boundary, for example `skills.validate`, `review_artifacts.validate`, `selector.regression`, or `broad_smoke.repo`.
- Use broad smoke as a triggered handoff gate, not the first proof step for every PR. Authoritative triggers include main/release mode, `--broad-smoke`, active plan `broad_smoke_required: true`, test-spec, review-resolution, and release metadata.
- Preserve source attribution when available through `broad_smoke.sources`.
- Manual proof for normal changes belongs in `verify-report.md` when required; release smoke proof belongs in release metadata. Required manual proof should say `manual by design` when automation is intentionally not possible.

### Review-resolution contract

- Material findings must include evidence, required outcome, and a safe resolution path or `needs-decision` rationale.
- Record first-pass material review findings before review-driven fixes when feasible; reconstructed records must say they were reconstructed.
- For non-trivial changes with material findings, use `review-resolution.md` and approved dispositions: `accepted`, `rejected`, `deferred`, `partially-accepted`, and `needs-decision`.
- `needs-decision` is not final and blocks `verify`, `explain-change`, and `pr` until resolved or explicitly deferred by an authorized owner.
- `Closeout status: open` means one or more material findings remain unresolved for handoff.
- `Closeout status: closed` means every material finding has a final disposition plus required action, rationale, follow-up, and validation evidence.
- A closed handoff requires `review-log.md` to list no open findings.
- Detailed review record triggers are material findings, stage-owned non-approval outcomes that block downstream progress or require revision, reconstructed review evidence, closeout evidence citation, and explicit reviewer or maintainer request.
- A stage-owned non-approval outcome requiring revision still needs a same-stage later review round or explicit reviewer or owner closeout evidence naming the original Review ID; `review-resolution.md` alone is not a silent substitute for required re-review.
- For no-material review events, no-material detailed records need `review-log.md` but not an empty `review-resolution.md`.
- Do not add a dedicated `pr-review` stage; it is unsupported unless a later approved spec extends the stage set. A material maintainer PR comment that needs disposition must first be promoted into a supported formal lifecycle review record with a stable `Finding ID`.

### Review-stage handoff versus downstream readiness

- `spec-review` may report both immediate next repository stage and eventual `test-spec` readiness, but those are different concepts.
- After approved `spec-review`, the immediate next stage is `architecture` when architecture is still required, otherwise `plan`.
- Eventual `test-spec` readiness may be `ready` or `conditionally-ready` after approved `spec-review`; `conditionally-ready` must name the remaining intermediate dependency.
- `changes-requested` and `blocked` pair with eventual `test-spec` readiness `not-ready` and return the workflow to `spec`.
- `inconclusive` pairs with eventual `test-spec` readiness `not-assessed`, records the missing-input stop condition, and leaves immediate next stage empty.
- `plan-review` remains the normal immediate handoff to `test-spec`. If implementation readiness is discussed there, it is downstream readiness rather than the handoff itself.

### Execution-stage claim ownership

- `implement` may report milestone completion, validation, blockers, readiness for `code-review`, or the next milestone, but it does not claim review findings or `branch-ready`.
- Before `implement` hands off to `code-review`, the approved slice should satisfy a `first-pass acceptable result`.
- `implement` targets the `smallest scope-complete change`, not merely the smallest diff.
- The same-slice completeness set includes in-scope requirements, required authored surfaces, required aligned surfaces, required edge cases, and the targeted validation set.
- Required edge cases come from approved artifacts, named regression cases, changed branch conditions or touched failure paths, governing tests or fixtures, and required aligned wording distinctions for the slice.
- If a required surface stays unchanged, `implement` records `unaffected with rationale` in an authoritative surface such as the active plan or required change-local artifacts.
- If missing or contradictory inputs prevent that standard, stop with a blocker instead of handing off an incomplete slice to `code-review`.
- Later review comments may still happen. A `preventable first-pass miss` is only a finding that should have been caught by the same-slice completeness set, required edge cases, or targeted validation before `code-review`.
- `code-review` may inspect staged or unstaged diffs, PR diffs, or commit ranges. If it cites governing artifacts for a clean branch-scoped conclusion, those artifacts must be confirmed in tracked governing branch state.
- Missing tracked governing authority blocks `clean-with-notes`, but it does not suppress independently supported findings from the review surface.
- Named edge cases need direct proof for clean review or `branch-ready` outcomes; code-shape inference alone is insufficient.
- `verify` owns `branch-ready`. `pr` owns `pr-body-ready` and `pr-open-ready`.
- Avoid unqualified `PR-ready` as live workflow guidance or status language.

### Fast lane

Use for small, low-risk, well-understood changes that affect at most a few files and do not introduce architecture changes.

Required stages:

```text
spec inside the PR body, issue comment, commit message, or linked change note
→ implement
→ verify
→ pr
→ learn only if a durable lesson was discovered
```

Rules:

- Use the fast lane only for typos, formatting-only changes, small documentation clarifications, comment-only changes, small test-fixture corrections, small non-behavioral renames, or minor generated-artifact refreshes that do not change generator behavior.
- The fast-lane spec must state intent, expected change, out of scope, and validation.
- Approved fast-lane work may still omit `docs/changes/<change-id>/` when the governing workflow contract allows it.
- Still write tests first when feasible.
- Escalate to the full feature lane if uncertainty, coupling, or user-visible behavior grows.
- Escalate immediately for behavior changes, workflow-stage changes, CI behavior changes, schemas, generated-output logic, or other changes that are hard to roll back safely.

### Bugfix lane

Use `bugfix` when the task starts from a failure, regression, incident, or unexpected behavior.

Required stages:

```text
reproduce
→ diagnose
→ regression test
→ minimal fix
→ verify blast radius
→ explain-change
→ pr
→ learn when recurrence prevention matters
```

If the bug reveals an unclear or missing contract, update or create the relevant spec.

### Review-only lane

Use when the user asks for critique, readiness, audit, or explanation without changing files.

Possible review skills:

- `proposal-review`
- `spec-review`
- `architecture-review`
- `plan-review`
- `code-review`
- `verify`
- `explain-change`

Do not edit files unless the user asks for edits.

## Invocation context and continuation

Classify the request into one of these contexts before deciding whether to continue:

- `workflow-managed`: the agent is carrying a change through its normal downstream stages toward completion under the active lane.
- `isolated`: the user asked for one stage result only, such as standalone `proposal-review`, `spec-review`, `architecture-review`, `code-review`, `verify`, or `explain-change`.
- `direct-pr`: the user directly invoked `pr`.

Rules:

- In v1, workflow-managed autoprogression applies only to:
  - `proposal -> proposal-review`
  - `spec -> spec-review`
  - `architecture -> architecture-review` when that review stage is the next mandatory or triggered downstream stage
  - full-feature execution from `implement` through `pr`
- In the full-feature lane, continue through this downstream chain unless a stop condition applies:
  - `implement -> code-review`
  - `code-review -> review-resolution -> code-review` only for first-pass `changes-requested` findings that are fixable within current approved scope
  - `code-review -> verify` only for first-pass `clean-with-notes` once the review gate is satisfied
  - `verify -> ci-maintenance when triggered -> explain-change`; otherwise `verify -> explain-change`
  - `ci-maintenance -> explain-change`
  - `explain-change -> pr`
- In workflow-managed full-feature runs, autoprogressed `code-review` must emit its first-pass review record before any review-driven fix begins.
- In workflow-managed full-feature runs, first-pass `blocked` and `inconclusive` stop instead of entering `review-resolution`.
- Direct `proposal-review`, `spec-review`, `architecture-review`, `code-review`, `verify`, and `explain-change` stay isolated by default unless the user explicitly asks for end-to-end continuation.
- Direct `pr` remains in scope and still performs the `pr` stage itself when readiness passes. Isolation only prevents downstream continuation beyond `pr`.
- Fast-lane and bugfix execution remain on the repository's existing explicit-step behavior in v1.
- On-demand and periodic actions such as `explore`, `research`, and `learn` do not auto-run by default.

### Documentation or governance lane

Use when the task is about project rules, onboarding, architecture visibility, process, or repository memory.

Common skills:

- `constitution`
- `project-map`
- `architecture`
- `explain-change`
- `learn`

## Initial routing checklist

Before choosing a lane, classify the request:

1. Is this a bug, a new feature, a refactor, a migration, documentation, or a review?
2. Does it change externally observable behavior?
3. Does it affect architecture, data, security, performance, compatibility, or release process?
4. Is the problem statement stable enough to specify?
5. Are there unknown assumptions that need research?
6. Are current architecture boundaries visible enough to proceed?
7. What is the smallest safe reviewable slice?

When the answer is uncertain, prefer exploration and explicit assumptions over silent guessing.

## Required traceability

Maintain this chain whenever applicable:

```text
User problem or issue
→ Explore option IDs
→ Proposal decision
→ Requirement IDs
→ Architecture decisions / ADR IDs
→ Plan milestones
→ Test IDs
→ Changed files
→ Verification evidence
→ PR summary
→ Lessons learned
```

Use stable IDs:

- Options: `O1`, `O2`, `O3`
- Requirements: `R1`, `R2`, `R3`
- ADRs: `ADR-YYYYMMDD-slug`
- Milestones: `M1`, `M2`, `M3`
- Tests: `T1`, `T2`, `T3`
- Risks: `K1`, `K2`, `K3`

## Default artifact paths

Use existing repo conventions when present. If absent, prefer:

```text
AGENTS.md
CONSTITUTION.md
docs/project-map.md
docs/workflows.md
docs/proposals/YYYY-MM-DD-slug.md
docs/architecture/YYYY-MM-DD-slug.md
docs/adr/YYYY-MM-DD-slug.md
docs/plans/YYYY-MM-DD-slug.md
docs/plan.md
specs/slug.md
specs/slug.test.md
docs/explain/YYYY-MM-DD-slug.md
```

Do not overwrite older durable artifacts for a new initiative. Create a new dated file and update the relevant index.

## Continuation and checkpoints

For high-impact changes, produce the artifact and clearly mark whether it is ready for the next stage.

Do not ask for redundant approval merely to enter an already-known next mandatory or triggered downstream stage in a workflow-managed flow.

Pause instead when:

- the user explicitly asks to stop, pause, or inspect before the next stage;
- a spec gap, architecture conflict, failing validation result, or review finding requires a real user decision;
- the active plan or spec defines a separately reviewable checkpoint that should not be crossed automatically;
- missing permissions, network failures, or tool limitations prevent safe continuation;
- the next action would be merge, deploy, release, tag publication, branch deletion, history rewrite, rollback, or another stronger external/destructive action than PR creation.

Review-only or explicitly isolated stage requests stay isolated unless the user asks to continue.

## Stop conditions

Stop and surface the blocker when:

- the user explicitly asks to stop, pause, or inspect before the next stage;
- the requested behavior is ambiguous enough that different implementations would be valid;
- there is no way to verify a `MUST` requirement;
- the architecture boundary is unknown and the change is risky;
- a validation command fails and the failure is not understood;
- tests pass but do not actually assert the required behavior;
- the implementation requires secrets, credentials, external systems, or unavailable tools;
- a review finding, spec gap, or architecture conflict requires a real user decision;
- the next action would be merge, deploy, release, tag publication, branch deletion, history rewrite, rollback, or another stronger external/destructive action than PR creation;
- the diff introduces scope outside the approved spec or plan.

When stopped, provide the smallest concrete next artifact or decision needed to resume.

## Evidence collection efficiency

Use summary and stable-ID first reasoning before broad reads or raw excerpts. Prefer check IDs, requirement IDs, test IDs, file paths, counts, and line citations when inspecting large files, repeated scans, generated output, or validation output. Read exact ranges after locating relevant lines, then expand only when the narrower evidence is insufficient.

## When full-file read is required

Read the full file when the whole file is the review target, the relevant section cannot be isolated safely, surrounding context can change the conclusion, bounded searches disagree or produce incomplete evidence, or a behavior-changing edit depends on the whole source-of-truth artifact.

## Expected output

Always state:

- chosen lane and why;
- invocation context and why;
- current stage;
- artifacts found, created, or missing;
- next recommended skill or next automatic stage;
- blockers or assumptions;
- whether continuation happened, stopped, or is out of scope;
- whether implementation is allowed yet.