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#

PhaseOwner1 — PRDInvoke skill: write-a-prd2 — Issues from PRDInvoke skill: prd-to-issues3 — ArchitectureInvoke skill: software-architect4 — QA PlanningThis skill5 — DevelopmentInvoke skills: senior-frontend, senior-backend6 — Automated TestingThis skill (npm test + Playwright)7 — Code ReviewInvoke skill: code-review:code-review8 — PR + Close + AdvanceThis skill

---

Workflow#

text

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:

text

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:

markdown

## 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:

bash

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)#

markdown

## 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#

markdown

## 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.

TemplatePurposeWhen to useFeature SpecificationFull spec with scenarios, FRs, entities, success criteriaPhase 1 PRD creationImplementation PlanPhased plan with research, gates, MVP cut linePhase 2 issue breakdownTask BreakdownT-NNN task list with parallel markers and user story linksPhase 2 / Phase 4 prepRequirements ChecklistCHK-NNN quality gates for spec approvalBefore Phase 2 beginsConstitution (optional)Project-level architectural principlesPhase 0 for greenfield projects

---

Quality Gates#

GateRequirementOn failureQA Plan existsBefore Phase 5 startsBlock — do not proceedUnit coverage>= 80%Return to Phase 5E2E testsAll passingReturn to Phase 5RegressionsZero detectedReturn to Phase 5Code ReviewApprovedReturn to Phase 5

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