development-workflow

name	development-workflow
description	Follow the structured development workflow for implementing features. Covers the full cycle: architecture design, coding, testing, and review. Use when assigned a feature implementation, review, or testing task.

Development Workflow Skill

This skill defines how each role executes within the plan-heavy, execute-light development cycle. By the time you receive a task, the planning is done — your job is mechanical execution of the spec.

Role: Architect

When assigned a feature for technical design:

1. Read the feature spec — understand the requirements, user stories, and acceptance criteria
2. Read the PRD — understand the broader product context
3. Design the technical approach and post as a comment:

## Technical Design: {Feature Name}

### Data Models
- Schema definitions, relationships, migrations needed

### API Design
- Endpoints, request/response shapes, error handling

### Component Architecture
- File structure, component hierarchy, state management

### Dependencies
- External libraries, internal modules, other features this depends on

### Implementation Notes
- Specific patterns to follow, edge cases to handle
- Performance considerations
- Security considerations

4. Approve or request changes — comment "Approved for implementation" or list specific revisions needed
5. Set issue status to todo (ready for developer) or blocked (needs revision)

Role: Developer

When assigned a feature implementation task:

1. Read the feature spec (issue description) — this is your contract
2. Read the Architect's technical design (in comments) — follow it precisely
3. Plan your implementation — post a brief comment outlining your approach:
   • Files you'll create/modify
   • Order of operations
   • Any concerns or questions (raise these BEFORE coding)
4. Implement the feature — write the code
5. Post a completion summary as a comment:

## Implementation Complete

### Changes
- `path/to/file.ts` — description of changes
- `path/to/other.ts` — description of changes

### How to Test
- Step-by-step instructions to verify the feature works

### Notes
- Any deviations from the spec (with justification)
- Known limitations
- Follow-up work needed

6. Set status to in_review
7. Do NOT move on to other tasks until this one is reviewed

Role: QA Engineer

When assigned a review/test task:

1. Read the feature spec — understand what was supposed to be built
2. Read the Developer's completion summary — understand what was actually built
3. Review the implementation:
   • Does it meet the acceptance criteria?
   • Are there edge cases not handled?
   • Are there bugs or regressions?
   • Is the code clean and maintainable?
4. Post a review comment:

## QA Review

### Status: PASS / FAIL / NEEDS CHANGES

### Acceptance Criteria
- [x] Criterion 1 — verified
- [x] Criterion 2 — verified
- [ ] Criterion 3 — FAILED: description of issue

### Issues Found
1. **Bug**: description (severity: critical/high/medium/low)
2. **Suggestion**: description (non-blocking)

### Test Results
- Manual testing: PASS/FAIL
- Edge cases tested: list

5. Update status:
   • All criteria met → set status to done
   • Issues found → set status to blocked, clearly describe what needs fixing
   • Minor suggestions → set status to done with suggestions noted

Role: UX Expert

When assigned a UX review task:

1. Read the feature spec — understand the user's goal
2. Review the implementation against UX best practices:
   • Is the user flow intuitive?
   • Are error states handled gracefully?
   • Is the information hierarchy clear?
   • Are interactions consistent with the rest of the product?
   • Is it accessible?
3. Post a UX review comment:

## UX Review

### Overall Assessment
Brief summary of UX quality.

### Recommendations
1. **Critical**: issues that block usability
2. **Important**: issues that degrade experience
3. **Nice-to-have**: polish items

### Positive Notes
What works well (reinforce good patterns).

4. Approve or request changes via status update

Role: UI Expert

When assigned a UI implementation task:

1. Read the feature spec and any UX recommendations
2. Implement the UI following:
   • The project's design system and component library
   • Consistent spacing, typography, and color usage
   • Responsive design (mobile-first)
   • Accessibility standards (ARIA labels, keyboard nav, contrast)
3. Post a completion summary with screenshots or descriptions of the UI state
4. Set status to in_review

Issue Status Flow

backlog → todo → in_progress → in_review → done
                      ↓
                   blocked → (fix) → in_progress

• todo — ready for work, all dependencies met
• in_progress — actively being worked on (checkout the issue first)
• in_review — work complete, awaiting review
• blocked — reviewer found issues, needs revision
• done — approved and complete

Communication Rules

1. All communication via issue comments — no side channels
2. Be specific — reference file paths, line numbers, acceptance criteria by number
3. Be actionable — every comment should make it clear what happens next
4. Tag blockers — if you're waiting on someone, say who and what you need
5. Don't repeat work — read existing comments before starting