dev.md

Dev - Implement Specification

You are implementing a feature specification using TDD with specialized agents. Track all progress in real-time to a progress file.

Input

Specification or command: $ARGUMENTS

Workflow

Step 0: Determine What to Implement

If $ARGUMENTS is a file path (e.g., specs/phase2_specification.md):

• Read that specification file
• Extract the implementation steps

If $ARGUMENTS is "continue" or empty:

• Look for existing specs/*_progress.md files
• Find the most recent one with incomplete tasks
• Continue from where it left off

If $ARGUMENTS is a phase/step reference (e.g., "phase 2" or "step 3"):

• Find the matching specification in specs/
• Read and implement it

Step 1: Initialize Progress File

Create or update specs/{feature_name}_progress.md with this format:

# Implementation Progress: {Feature Name}

**Specification:** `specs/{feature_name}_specification.md`
**Started:** {current date/time}
**Status:** In Progress

---

## Progress Log

### {timestamp}
**Task:** {task description}
**Status:** Starting
**Agent:** {agent type being used}

---

CRITICAL: Write to the progress file IMMEDIATELY when:

• Starting a new task
• Completing a task
• Encountering an error
• Making a decision
• Running tests

Step 2: Implementation Process

For each implementation step in the specification:

1. Log the task start in progress file:

   ### {timestamp}
   **Task:** {task from spec}
   **Status:** In Progress
   **Agent:** {laravel-boost-builder|pest-playwright-tester|etc}

2. Write tests FIRST (TDD):

   • Use pest-playwright-tester agent to write tests
   • Log: "Writing tests for {component}"
   • Tests should fail initially (red phase)

3. Implement the code:

   • Use laravel-boost-builder agent for Laravel code
   • Use frontend-expert agent for UI components
   • Log: "Implementing {component}"

4. Run tests:

   • Verify tests pass (green phase)
   • Log: "Tests passing: {X} tests, {Y} assertions"

5. Log completion in progress file:

   ### {timestamp}
   **Task:** {task}
   **Status:** Completed
   **Files Created/Modified:**
   - `path/to/file1.php`
   - `path/to/file2.php`
   **Tests:** {X} passing

6. Run architecture review after significant code:

   • Use architecture-guardian agent
   • Log findings and any fixes made

Step 3: Progress File Format

Maintain this structure throughout:

# Implementation Progress: {Feature Name}

**Specification:** `specs/{feature_name}_specification.md`
**Started:** {date/time}
**Status:** In Progress | Completed | Blocked

---

## Summary

| Step | Description | Status | Tests |
|------|-------------|--------|-------|
| 1 | Create migrations | Completed | 5 |
| 2 | Create models | Completed | 12 |
| 3 | Create services | In Progress | - |
| 4 | Create UI | Pending | - |

---

## Progress Log

### 2026-01-08 12:30:00
**Task:** Create database migrations
**Status:** Completed
**Agent:** laravel-boost-builder
**Files Created:**
- `database/migrations/2026_01_08_create_x_table.php`
**Notes:** Added indexes on status and created_at columns

---

### 2026-01-08 12:35:00
**Task:** Write model tests (TDD)
**Status:** Completed
**Agent:** pest-playwright-tester
**Files Created:**
- `tests/Feature/Models/XTest.php`
**Tests:** 8 tests written, all failing (red phase - expected)

---

### 2026-01-08 12:40:00
**Task:** Implement models
**Status:** Completed
**Agent:** laravel-boost-builder
**Files Created:**
- `app/Models/X.php`
- `database/factories/XFactory.php`
**Tests:** 8 passing (green phase)

---

## Errors & Resolutions

### {timestamp}
**Error:** {error description}
**Resolution:** {how it was fixed}

---

## Architecture Review

### {timestamp}
**Reviewer:** architecture-guardian
**Assessment:** Good
**Findings:**
- {finding 1}
- {finding 2}
**Actions Taken:**
- {action if any}

---

## Final Status

**Completed:** {date/time}
**Total Tests:** {X} passing
**Files Created:** {count}
**Files Modified:** {count}

Step 4: Error Handling

When errors occur:

1. Log immediately:

   ### {timestamp}
   **Task:** {task}
   **Status:** Error
   **Error:** {error message}
   **Investigating...**

2. After resolution:

   ### {timestamp}
   **Task:** {task}
   **Status:** Resolved
   **Resolution:** {what fixed it}

Step 5: Completion

When all steps are done:

1. Run full test suite:

   php artisan test --compact

2. Run Pint for formatting:

   vendor/bin/pint --dirty

3. Run architecture review on all new code

4. Update progress file with final status:

   ## Final Status
   
   **Completed:** {date/time}
   **Total Tests:** {X} passing ({Y} assertions)
   **Files Created:** {list}
   **Files Modified:** {list}
   
   ### Acceptance Criteria
   - [x] Criteria 1 from spec
   - [x] Criteria 2 from spec
   - [x] All tests passing
   - [x] Code formatted with Pint
   - [x] Architecture review passed

5. Update summary table at top of progress file

6. Inform user that implementation is complete and ready for commit

Important Rules

1. Write to progress file IMMEDIATELY - not at the end, but as you go
2. Use TDD - always write tests first with pest-playwright-tester
3. Use specialized agents - match agent to task type
4. Log everything - tasks, completions, errors, decisions
5. Include timestamps - use format YYYY-MM-DD HH:MM:SS
6. Track files - list all created/modified files
7. Run architecture review - after significant code additions
8. Verify acceptance criteria - check each one from the spec
9. Use TodoWrite tool - for internal task tracking during implementation
10. Continue seamlessly - if "continue" is passed, pick up where left off

Agent Selection Guide

Task Type	Agent
Laravel code (models, migrations, services)	laravel-boost-builder
Writing tests	pest-playwright-tester
Running tests	pest-playwright-tester
Frontend (Livewire, Blade, CSS)	frontend-expert
Architecture review	architecture-guardian
Code exploration	Explore
Planning	Plan

Starting Implementation

1. Parse $ARGUMENTS to determine spec file
2. Read the specification
3. Create/update progress file with "Starting implementation"
4. Extract implementation steps from spec
5. Begin TDD cycle for first step
6. Log progress continuously
7. Complete all steps
8. Final review and summary