Bramato Laravel React Plugins Spec Driven Development

Spec-Driven Development Skill

A structured, human-in-the-loop development methodology adapted from the Kiro workflow. Ensures every feature moves through Requirements → Design → Tasks → Implementation with explicit approval gates and full traceability.

Target users: Full-stack Laravel + React developers building features that benefit from upfront planning, or teams that need formal specifications.

Core Philosophy

Built on pragmatic software engineering principles:

1. Collaboration is mandatory — No code changes proceed without explicit user approval at critical phases
2. Simplicity over complexity — Don't over-engineer, don't over-abstract, don't overcomplicate
3. Pragmatism over perfection — Solutions that work in practice beat theoretical elegance
4. Design authority — The approved design document is the single source of truth for implementation
5. No scope creep — Forbidden to add features, classes, or endpoints not in the approved design

See references/design-principles.md for the full philosophy.

Four-Phase Workflow

Phase 1: /spec          Phase 2: /design         Phase 3: /plan-tasks     Phase 4: /implement
┌─────────────┐        ┌─────────────┐          ┌─────────────┐          ┌─────────────┐
│ requirements │──✓──▶  │  design.md  │──✓──▶    │  tasks.md   │──────▶   │   Execute   │
│     .md      │        │             │          │             │          │  task by    │
│              │        │ Architecture│          │ Hierarchical│          │  task       │
│ User Stories │        │ Data Flow   │          │ Checkboxes  │          │             │
│ EARS syntax  │        │ API Specs   │          │ Requirement │          │ Context     │
│ BE + FE      │        │ DB Schema   │          │ Tracing     │          │ gathering   │
│              │        │ Components  │          │             │          │ mandatory   │
└─────────────┘        │ Security    │          └─────────────┘          └─────────────┘
                       │ Test Plan   │
       ▲               └─────────────┘                                          │
       │                      ▲                                                 │
   APPROVAL               APPROVAL                                         Mark [x]
    GATE                    GATE                                          in tasks.md

Directory Convention

All spec artifacts live in a feature-specific directory:

.kiro/
├── specs/
│   └── [feature-name]/
│       ├── requirements.md    ← Phase 1 output
│       ├── design.md          ← Phase 2 output
│       └── tasks.md           ← Phase 3 output
└── steering/
    └── [project context files — coding standards, architecture decisions, etc.]

Naming: Use kebab-case for feature names (e.g., order-management, user-authentication).

Phase 1: Requirements (EARS Syntax)

Template: requirements.md

# [Feature Name] — Requirements

## Introduction

**Problem:** [What problem does this feature solve?]
**Objectives:** [What are the goals?]
**Project Alignment:** [How does this fit into the broader project?]

## Requirements

### Backend Requirements

**1. [Requirement title]**

**As a** [role], **I want** [feature], **so that** [benefit]

Acceptance Criteria:
1. WHEN [trigger], THEN [expected outcome]
2. IF [condition], THEN [expected result]
3. WHERE [constraint applies], THEN [required action]

### Frontend Requirements

**2. [Requirement title]**

**As a** [role], **I want** [UI feature], **so that** [benefit]

Acceptance Criteria:
1. WHEN [user action], THEN [UI response]
2. IF [state condition], THEN [visual feedback]
3. WHILE [loading/processing], THEN [interim UI state]

EARS Syntax Reference

EARS (Easy Approach to Requirements Syntax) provides unambiguous acceptance criteria:

See references/ears-syntax.md for comprehensive examples.

Requirements Best Practices

• Proactively think through edge cases and error conditions — don't ask multiple clarifying questions
• Generate an initial draft immediately, then iterate
• Separate backend (Laravel: API, DB, business logic) from frontend (React/Inertia: UI, UX, state) requirements
• Number requirements sequentially (1, 2, 3...) for traceability in later phases
• Each requirement should be independently testable

Approval Gate

After presenting requirements, use exactly:

"Do the requirements look good? If so, we can move on to the technical design phase."

Do not proceed to Phase 2 without explicit user approval. Iterate until sign-off.

Phase 2: Technical Design

Prerequisites

• Explicit user approval of requirements.md
• Read all files in .kiro/steering/ for project context
• Static analysis of existing codebase

Template: design.md

The design document has 9 mandatory sections:

# [Feature Name] — Technical Design

## 1. Architectural Overview
[High-level description of the solution and how it fits into the existing system]

## 2. Data Flow Diagram
[Mermaid.js diagram showing data movement between components]

## 3. Service Provider Artifacts
[For each entity: list all artifacts to create]
- Model, DTO, Service, Controller, FormRequest, Policy, ServiceProvider
- Events/Listeners if applicable

## 4. API / Route Definitions
[For Inertia: Laravel routes that render Inertia pages]
[For API endpoints: method, path, request body, response structure]

## 5. Database Schema
[Laravel migration code for new/modified tables]
[Indexes, foreign keys, constraints]

## 6. React Components (Inertia Pages)
[Component hierarchy, props interface, state management]
[Which Inertia pages to create: Index, Show, Create, Edit]

## 7. TypeScript Interfaces
[Interfaces matching controller props / API responses]

## 8. Security Considerations
[Input validation, authentication, authorization policies]
[CSRF, XSS prevention, mass assignment protection]

## 9. Test Strategy
[Unit tests: Services, DTOs, Models]
[Feature tests: HTTP endpoints, Inertia responses]
[Component tests: React pages and components]

Design Best Practices

• Reference existing code patterns in the codebase
• Use Mermaid.js for data flow diagrams
• Specify exact file paths for each artifact to create
• Include TypeScript interface or type definitions for the frontend contract
• Map every design element back to a requirement number

Approval Gate

After presenting the design, use exactly:

"Does the technical design look good? If so, we can proceed to implementation planning."

Do not proceed to Phase 3 without explicit user approval.

Phase 3: Task Planning

Prerequisites

• Explicit user approval of design.md

Template: tasks.md

# [Feature Name] — Implementation Tasks

- [ ] 1. Create database migration and Model
  - Migration with columns, indexes, foreign keys
  - Eloquent Model with $fillable, $casts, relationships, scopes
  - _Requirements: 1.1, 1.2_

- [ ] 2. Create Service Provider artifacts
  - DTO with fromRequest(), fromModel(), toArray()
  - Service with business logic methods
  - Controller with Inertia::render() responses
  - StoreRequest, UpdateRequest with validation rules
  - Policy with authorization rules
  - ServiceProvider registration
  - _Requirements: 1.3, 1.4, 2.1_

- [ ] 3. Create Inertia React pages
  - Index page with list/table
  - Show page with detail view
  - Create/Edit pages with forms
  - TypeScript interfaces for props
  - _Requirements: 3.1, 3.2_

- [ ] 4. Write tests
  - Feature tests for all HTTP endpoints
  - Unit tests for Service and DTO
  - Component tests for React pages
  - _Requirements: all_

Task Planning Rules

• High-level tasks: Numbered with checkboxes - [ ] N.
• Sub-tasks: Indented bullets (no checkboxes, no numbering)
• Traceability: Every task ends with _Requirements: N.N, N.N_
• Dependency order: Tasks listed in logical execution order
• No approval gate — Tasks are ready for immediate execution

Phase 4: Implementation Execution

Trigger Commands

Mandatory Execution Flow

For every task, follow this sequence without exception:

1. State Check — Read tasks.md, identify the target task
2. Context Gathering (MANDATORY):
   • Read entire design.md
   • Read entire requirements.md
   • Read all files in .kiro/steering/
   • Summarize each document to prove comprehension
3. Planning Announcement:
   • Explain the task's architectural role
   • List applicable requirements
   • Identify specific files to create or modify
4. Implementation — Execute code changes following the design
5. Completion — Mark task [x] in tasks.md, report results
6. Await — Wait for next command

Enforcement Rules

When to Use This Workflow

Related Commands

• /spec — Phase 1 entry point
• /design — Phase 2 entry point
• /plan-tasks — Phase 3 entry point
• /implement — Phase 4 entry point
• /commit — Commit after completing tasks

Converted and distributed by TomeVault — claim your Tome and manage your conversions.