Dev Workflow Orchestrator

Autonomous end-to-end lifecycle manager for Claude Code. Coordinates all phases from idea to merged PR. Delegates to your existing skills where they exist; owns the phases in between.

Skill Map

Workflow

IDEA
  |-- [Phase 1] invoke skill: write-a-prd
       |-- [Phase 2] invoke skill: prd-to-issues -> ordered issues
            |-- For each issue:
                 |-- [Phase 3] invoke skill: software-architect
                 |-- [Phase 4] QA Planning (before any code)
                 |-- [Phase 5] invoke skills: senior-frontend + senior-backend
                 |-- [Phase 6] npm test + Playwright + coverage check
                 |-- [Phase 7] invoke skill: code-review:code-review
                 |-- [Phase 8] PR created -> issue closed -> next issue

Session Start Protocol

At the start of every session, output this state block and ask the user to confirm:

DEV WORKFLOW STATE
 Feature PRD   : #[number] - [title]
 Current issue : #[number] - [title]
 Current phase : [1-8] - [phase name]
 Remaining     : #X, #Y, #Z

If starting fresh, ask: "Nova feature ou continuando uma issue existente?"

Phase 1 — PRD

Owner: your existing skill.

Invoke skill write-a-prd to create the PRD through user interview and codebase exploration. Wait for the PRD to be submitted as a GitHub issue before advancing.

Exit condition: PRD issue created on GitHub.

Phase 1.5 — Clarify

Trigger: PRD exists but contains ambiguities before issue breakdown begins.

If the PRD contains ambiguities, run a structured clarification pass: identify up to 5 critical unknowns, resolve each through targeted Q&A before proceeding to Phase 2.

1. Scan the PRD for gaps: missing edge-case behaviour, undefined user roles, vague success criteria, unstated constraints, or conflicting requirements.
2. List each unknown as a numbered question (max 5). Prioritise questions that affect scope, security, or core UX — skip cosmetic or low-stakes ambiguities.
3. Ask all questions in a single message. Wait for answers before continuing.
4. Update the PRD issue with the resolved answers and mark the clarification pass complete as a comment.

Skip this phase when the PRD is unambiguous or the user explicitly says to proceed.

Exit condition: All critical unknowns resolved and documented on the PRD issue.

Phase 2 — Issues from PRD

Owner: your existing skill.

Invoke skill prd-to-issues to break the PRD into independently-grabbable GitHub issues using tracer-bullet vertical slices. The skill handles ordering, dependencies, and scoping.

Wait for all issues to be created and confirmed by the user before advancing.

Exit condition: All issues created on GitHub, order confirmed by user.

Phase 3 — Architecture

Owner: software-architect skill.

Invoke skill software-architect to design the system structure for this issue/feature. For the first issue in a new feature, this produces the full architecture. For subsequent issues, review and update the existing architecture if the new issue changes boundaries.

Skip this phase for small issues that don't affect system structure (bug fixes, copy changes, minor UI tweaks).

Exit condition: Architecture document exists and is appropriate for the issue scope.

Phase 4 — QA Planning

Trigger: Architecture exists (or skipped) for this issue. Rule: This runs BEFORE any code is written.

Generate and post as a GitHub comment on the issue:

## Test Plan - #[issue-number]

### Unit Tests
- [ ] [unit] should [behavior] when [condition]

### Integration Tests
- [ ] [flow] should [result] given [state]

### Edge Cases
- [ ] Null / empty inputs
- [ ] Boundary values
- [ ] Concurrent operations (if applicable)
- [ ] Network / auth failures (if applicable)

### E2E Scenarios (Playwright)
- [ ] Happy path: [user does X -> sees Y]
- [ ] Error path: [user does X -> sees error Z]

### Regression Scope
- Features this change touches: [list files/components]

Exit condition: Test plan posted as issue comment. Do not write code before this exists.

Phase 5 — Development

Trigger: QA plan exists on the issue.

Invoke skills senior-frontend and/or senior-backend as appropriate for the implementation. Use senior-frontend for UI components, pages, and client-side logic. Use senior-backend for API routes, database schemas, and server-side logic.

Claude Code implements autonomously following these rules:

• Never commit directly to main
• Branch name: feat/#[issue-number]-short-description
• Commit format: feat: [description] (#[issue-number])
• No TODOs left in code
• Implement against ACs — keep the test plan visible while coding

Exit condition: Implementation complete, all files saved, ready for testing.

Phase 6 — Automated Testing

Trigger: Implementation complete.

5a — Unit & Integration

Always use npm to run tests, regardless of what package manager the project uses:

npm test -- --coverage

Gate: coverage >= 80%. If below, return to Phase 5 with coverage report.

5b — E2E via Playwright Agents (three-agent flow)

1. Planner — converts QA plan E2E scenarios into navigation flows
2. Generator — writes Playwright tests, validates selectors against running app
3. Healer — if a test fails, replays, diagnoses, and patches automatically

5c — Regression

Run smoke tests on every feature listed in "Regression Scope" from the QA plan.

Test Report (post as issue comment)

## Test Results - #[issue-number]
- Unit/Integration : X passing | X failing
- Coverage         : X% (gate: 80%)
- E2E              : X passing | X failing
- Regressions      : None | [list]

Exit condition: All green, coverage >= 80%, zero regressions. On failure, return to Phase 5 with the report attached.

Phase 7 — Code Review

Owner: your existing Code Review skill.

Invoke skill code-review:code-review directly. Pass it the branch/diff context. Wait for verdict before advancing.

• Approved -> advance to Phase 8
• Changes requested -> return to Phase 5 with review comments

Exit condition: Code Review skill returns Approved.

Phase 8 — PR + Close + Advance

Trigger: Code review approved.

7a — Create PR

## What
[One paragraph describing the change]

## Why
Closes #[issue-number]
Part of #[parent-PRD-number]

## Checklist
- [x] Unit/Integration tests passing
- [x] E2E tests passing
- [x] Coverage >= 80%
- [x] No regressions detected
- [x] Code review approved

7b — After merge

• Close issue with comment: Resolved via #[PR-number]
• Check off the corresponding item on the parent PRD issue

7c — Advance

• Issues remaining -> update state block -> return to Phase 3 (or Phase 4 if architecture unchanged) for next issue
• All issues done -> close parent PRD issue with summary -> workflow complete

Exit condition: PR merged, issue closed, next phase identified.

Reference Templates

This skill has detailed reference templates. Consult references/spec-templates.md for structured templates for specs, plans, tasks, and checklists.

Quality Gates

Never skip a gate. If the user requests skipping, state the risk clearly and require explicit confirmation before proceeding.