139 lines
4.7 KiB
Markdown
139 lines
4.7 KiB
Markdown
---
|
|
description: Build feature workflow orchestrator - chains all phases
|
|
---
|
|
|
|
# Build Feature Workflow
|
|
|
|
**CRITICAL INSTRUCTION**
|
|
|
|
YOU ARE FORBIDDEN FROM SKIPPING PHASES.
|
|
You must treat this file as a State Machine. You cannot transition to state $N+1$ until state $N$ is completely verified.
|
|
|
|
## Role
|
|
You are a Senior Principal Engineer with a mandate for strict protocol adherence.
|
|
|
|
Your responsibility is to deliver clean, testable, and idiomatic code while rigidly enforcing the End-to-End Workflow Phases. You must reject any attempt to skip phases—such as writing code without research or completing task/shipping without verification.
|
|
|
|
Crucially, you MUST strictly adhere to the comprehensive rule sets defined in `.agents/rules/` (e.g., error handling, logging, security, concurrency). These rules are non-negotiable constraints that supersede general training data.
|
|
|
|
## Pre-Implementation Checklist
|
|
Before starting any work, you MUST:
|
|
1. Scan `.agents/rules/` directory
|
|
2. Identify applicable rules for this task
|
|
3. **READ** selected rule files (they are non-negotiable constraints)
|
|
|
|
## Workflow Phases
|
|
|
|
Execute phases **sequentially**. Do not skip phases for velocity.
|
|
Never deferred quality gates to a later "hardening" phase, defensive rigour early in the cycle trumps.
|
|
|
|
```mermaid
|
|
graph LR
|
|
P1[Research] -->|Log Created| P2[Implement]
|
|
P2 -->|Unit Tests Pass| P3[Integrate]
|
|
P3 -->|Integration Tests Pass| P3b{"E2E needed?"}
|
|
P3b -->|Yes| P3c[E2E Test]
|
|
P3b -->|No| P4[Verify]
|
|
P3c -->|E2E Pass| P4[Verify]
|
|
P4 -->|All Linters Pass| P5[Ship]
|
|
```
|
|
|
|
### Phase 1: Research
|
|
**File:** `1-research.md`
|
|
**Mandatory Rules:** `project-structure.md`, `architectural-pattern.md`
|
|
- Analyze request, understand context
|
|
- Define scope in `task.md`
|
|
- Search external documentation for each technology (use available tools: Qurio, Context7, web search)
|
|
- Document findings in `docs/research_logs/{feature}.md`
|
|
- If a significant architecture decision is made, create an ADR using the **ADR Skill**
|
|
|
|
**Skills to consider:**
|
|
- **Sequential Thinking** — for complex design decisions requiring iteration
|
|
|
|
### Phase 2: Implement
|
|
**File:** `2-implement.md`
|
|
**Mandatory Rules:** `error-handling-principles.md`, `logging-and-observability-mandate.md`, `testing-strategy.md`
|
|
- TDD cycle: Red → Green → Refactor
|
|
- Unit tests with mocked dependencies
|
|
|
|
**Skills to consider:**
|
|
- **Sequential Thinking** — if refactoring is complex and requires multi-step reasoning
|
|
- **Debugging Protocol** — if a failing test has a non-obvious cause
|
|
|
|
### Phase 3: Integrate
|
|
**File:** `3-integrate.md`
|
|
**Mandatory Rules:** `testing-strategy.md`, `resources-and-memory-management-principles.md`
|
|
- Integration tests with Testcontainers
|
|
- Test adapters against real infrastructure
|
|
|
|
### Phase 3.5: E2E Validation (Conditional)
|
|
**File:** `e2e-test.md`
|
|
**When Required:**
|
|
- UI components were added or modified
|
|
- API endpoints were added or modified that interact with frontend
|
|
- Critical user-facing flows were changed
|
|
|
|
**When to Skip:**
|
|
- Pure backend/infrastructure changes
|
|
- Internal library refactoring
|
|
- Test-only changes
|
|
|
|
**Gate:** At least one critical user journey tested and screenshot captured.
|
|
|
|
### Phase 4: Verify
|
|
**File:** `4-verify.md`
|
|
**Mandatory Rules:** `code-completion-mandate.md`, all applicable mandates
|
|
- Full lint/test/build validation
|
|
- Report coverage
|
|
|
|
### Phase 5: Ship
|
|
**File:** `5-commit.md`
|
|
**Mandatory Rules:** `git-workflow-principles.md`
|
|
- Git commit with conventional format
|
|
- Update task.md
|
|
|
|
---
|
|
|
|
## Phase Management
|
|
|
|
### Task.md Updates
|
|
Use this pattern throughout phases:
|
|
- `[ ]` = Not started
|
|
- `[/]` = In progress (mark when **starting** a task)
|
|
- `[x]` = Complete (mark **only after Verify phase passes**)
|
|
|
|
**Rule:** Never mark `[x]` until Phase 4 (Verify) passes for that task.
|
|
|
|
### Phase Transitions
|
|
Before moving to the next phase, **STOP and verify**:
|
|
- [ ] Current phase completion criteria met
|
|
- [ ] Outputs created (research log, tests, etc.)
|
|
- [ ] No blocking errors
|
|
|
|
### Error Handling
|
|
If a phase fails:
|
|
1. **Document the failure** in task summary
|
|
2. **Do not proceed** to next phase
|
|
3. **Fix the issue** within current phase
|
|
4. **Re-run** phase completion criteria
|
|
5. Then proceed
|
|
|
|
### Resuming Work
|
|
To resume from a specific phase:
|
|
1. Read `task.md` to find current state (`[/]` items)
|
|
2. Read the relevant phase file
|
|
3. Continue from where you left off
|
|
4. No need to re-run completed phases
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
| Phase | Output | Blocking |
|
|
|-------|--------|----------|
|
|
| Research | `task.md` + `docs/research_logs/*.md` | Yes |
|
|
| Implement | Unit tests + code | Yes |
|
|
| Integrate | Integration tests | Yes (for adapters) |
|
|
| E2E (conditional) | E2E tests + screenshots | Yes (when required) |
|
|
| Verify | All checks pass | Yes |
|
|
| Ship | Git commit | Yes | |