# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

LAIDA v3 is an agent-executable software architecture methodology. It transforms project requirements into structured YAML artifacts through 5 phases (0-4), each with 4 steps.

**Core Principle**: Generate atomic YAML files, not prose documents. Reference by ID (R-XXX, QAS-XXX), never duplicate content.

## Directory Structure

```
LAIDAv3/
├── .laida/
│   ├── config.yaml           # Phase/step definitions, scale thresholds
│   ├── prompts/
│   │   ├── base_prompt.yaml  # Shared system prompt (enables cache hits)
│   │   └── phase{0-4}/       # Step-specific prompts (step{0-3}_*.yaml)
│   ├── templates/            # Output schemas (7 artifacts + 11 cicd)
│   ├── matrices/             # Tech selection decision matrices
│   └── rules/                # Scale calculation algorithm
├── inputs/
│   ├── project_context.yaml  # User fills this to start methodology
│   └── project_context_template.yaml  # Template with all fields documented
└── outputs/
    └── phase{0-4}/           # Generated artifacts per step
```

## Key Files (Quick Reference)

| File | Read When | Contains |
|------|-----------|----------|
| `.laida/config.yaml` | Starting methodology | Phase/step definitions, ID patterns, scale thresholds |
| `.laida/prompts/base_prompt.yaml` | Before any step | Identity, principles, constraints, workflow |
| `inputs/project_context.yaml` | Starting new project | User input (13 sections) |
| `inputs/project_context_template.yaml` | Creating new project | Template with all fields documented |
| `.laida/rules/scale_calculation.yaml` | Phase 0 Step 0 | Scale algorithm, factor weights, override rules |
| `.laida/matrices/tech_selection.yaml` | Phase 0 Step 0 | Tech scoring, hard constraints (HC-XXX), soft rules (SR-XXX) |

### Files Created During Execution

| File | Created in | Critical For |
|------|------------|--------------|
| `methodology_config.yaml` | Phase 0 Step 0 | All subsequent steps (limits, skips) |
| `project_scale.yaml` | Phase 0 Step 0 | Scale-dependent behavior |
| `stack_summary.yaml` | Phase 0 Step 0 | Full tech stack reference |
| `context_map.yaml` | Phase 0 Step 1 | DDD context relationships |
| `rtm.yaml` | Phase 1 Step 0 | Traceability verification |

## Templates Disponibles

### Artifacts (`.laida/templates/`)

| Template | ID Pattern | Usado en | Descripción |
|----------|------------|----------|-------------|
| `risk.yaml` | R-XXX | Phase 0 Step 1 | Riesgos arquitectónicos |
| `qas.yaml` | QAS-XXX | Phase 0 Step 1 | Quality Attribute Scenarios |
| `bounded_context.yaml` | BC-XXX | Phase 0 Step 1 | Bounded contexts DDD |
| `function.yaml` | F-XXX | Phase 0 Step 2 | Requisitos funcionales |
| `adr.yaml` | ADR-XXX | Phase 0 Step 3 | Architecture Decision Records |
| `tdr.yaml` | TDR-XXX | Phase 0 Step 0 | Tech Decision Records |
| `directive.yaml` | M-XXX | Phase 0 Step 3 | Directivas arquitectónicas |

### CI/CD (`.laida/templates/cicd/`)

| Template | Genera | Usado en |
|----------|--------|----------|
| `dockerfile.yaml` | Dockerfile | Phase 4 Step 0 |
| `docker_compose.yaml` | docker-compose.yml | Phase 4 Step 0 |
| `github_ci.yaml` | .github/workflows/ci.yml | Phase 4 Step 0 |
| `github_release.yaml` | .github/workflows/release.yml | Phase 4 Step 3 |
| `github_security.yaml` | Security workflow | Phase 4 Step 0 |
| `pre_commit.yaml` | .pre-commit-config.yaml | Phase 4 Step 0 |
| `makefile.yaml` | Makefile | Phase 4 Step 0 |
| `dependabot.yaml` | dependabot.yml | Phase 4 Step 0 |
| `changelog.yaml` | CHANGELOG.md format | Phase 4 Step 3 |
| `contributing.yaml` | CONTRIBUTING.md | Phase 4 Step 3 |
| `dockerignore.yaml` | .dockerignore | Phase 4 Step 0 |

## Prompt Reference Map

### Localización Rápida

```
.laida/prompts/
├── base_prompt.yaml              ← SIEMPRE leer primero (identidad, principios)
├── phase0/
│   ├── step0_profiling.yaml      ← Scale + Tech Stack
│   ├── step1_foundation.yaml     ← Risks + QAS + Bounded Contexts
│   ├── step2_capabilities.yaml   ← Functions
│   └── step3_blueprint.yaml      ← ADRs + Directives + Roadmap
├── phase1/
│   ├── step0_traceability.yaml   ← RTM + Module Order
│   ├── step1_specification.yaml  ← Module Specs
│   ├── step2_validation.yaml
│   └── step3_assembly.yaml
├── phase2/
│   ├── step0_cot_architecture.yaml ← CoT Setup
│   ├── step1_file_structure.yaml
│   ├── step2_validation.yaml
│   └── step3_assembly.yaml
├── phase3/
│   ├── step0_foundations.yaml    ← Dependency Analysis
│   ├── step1_contracts.yaml      ← API Contracts
│   ├── step2_validation.yaml
│   └── step3_assembly.yaml
└── phase4/
    ├── _index.yaml               ← Resumen de Phase 4
    ├── step0_environment_scaffolding.yaml
    ├── step1_domain_application.yaml
    ├── step2_infrastructure.yaml
    └── step3_verification_release.yaml
```

### ¿Qué leer según la tarea?

| Si necesitas... | Lee primero |
|-----------------|-------------|
| Entender la metodología | `base_prompt.yaml` |
| Calcular escala del proyecto | `rules/scale_calculation.yaml` |
| Seleccionar tecnología | `matrices/tech_selection.yaml` |
| Schema de un artifact | `.laida/templates/{artifact}.yaml` |
| Ejecutar un step específico | `.laida/prompts/phase{N}/step{M}_*.yaml` |
| Ver config de fases | `.laida/config.yaml` |

## Output Directory Structure

### Phase 0: Strategic Foundation

```
outputs/phase0/
├── step0_profiling/
│   ├── project_scale.yaml        # Resultado: small|medium|large
│   ├── methodology_config.yaml   # Límites y skips según scale
│   └── tech/
│       ├── _index.yaml
│       ├── TDR-001_language.yaml
│       ├── TDR-002_framework.yaml
│       ├── TDR-003_database.yaml
│       ├── TDR-004_deployment.yaml
│       └── stack_summary.yaml
├── step1_foundation/
│   ├── risks/
│   │   ├── _index.yaml
│   │   └── R-001.yaml ... R-{max}.yaml
│   ├── qas/
│   │   ├── _index.yaml
│   │   └── QAS-001.yaml ... QAS-{max}.yaml
│   └── contexts/
│       ├── _index.yaml
│       ├── BC-001.yaml ... BC-{N}.yaml
│       └── context_map.yaml
├── step2_capabilities/
│   └── functions/
│       ├── _index.yaml
│       └── F-001.yaml ... F-{max}.yaml
└── step3_blueprint/
    ├── decisions/
    │   ├── _index.yaml
    │   └── ADR-001.yaml ...
    ├── directives/
    │   ├── _index.yaml
    │   └── M-001.yaml ...
    └── roadmap/
        └── phases.yaml
```

### Key Output Files

- `outputs/phase{N}/step{M}_*/` siempre tiene `_index.yaml`
- Para ver cobertura de traceability: `outputs/phase1/step0_traceability/rtm.yaml`
- Para ver roadmap: `outputs/phase0/step3_blueprint/roadmap/phases.yaml`

## Step Dependencies

### Phase 0 (Sequential within phase)

```
Step 0 → Step 1 → Step 2 → Step 3
  │        │        │        │
  │        │        │        └─ Needs: functions, qas, risks
  │        │        └─ Needs: methodology_config, qas, risks, contexts
  │        └─ Needs: project_scale, methodology_config, stack_summary
  └─ Needs: project_context.yaml (ENTRY POINT)
```

### Cross-Phase Dependencies

```
Phase 1 Step 0 requires ALL of:
  - outputs/phase0/step0_profiling/methodology_config.yaml
  - outputs/phase0/step1_foundation/risks/_index.yaml
  - outputs/phase0/step1_foundation/qas/_index.yaml
  - outputs/phase0/step2_capabilities/functions/_index.yaml
  - outputs/phase0/step3_blueprint/decisions/_index.yaml
  - outputs/phase0/step3_blueprint/roadmap/phases.yaml

Phase 4 requires:
  - outputs/phase3/step3_assembly/ (complete contracts package)
```

### Validation Before Proceeding

Before starting Phase N+1, verify:
1. All `_index.yaml` files exist in Phase N outputs
2. Coverage metrics in RTM show 100% for critical items
3. No `status: pending` artifacts remain

## File Naming Conventions

### Prompt Files
- Pattern: `step{N}_{descriptive_name}.yaml`
- Examples: `step0_profiling.yaml`, `step1_foundation.yaml`

### Artifact Files
- Pattern: `{ID_PREFIX}-{NNN}.yaml`
- Examples: `R-001.yaml`, `QAS-005.yaml`, `F-012.yaml`

### Index Files
- Always: `_index.yaml` (underscore prefix ensures sorting first)

### TDR Files (Tech Decisions)
- Pattern: `TDR-{NNN}_{category}.yaml`
- Categories: `language`, `framework`, `database`, `deployment`

### Searching Tips

```bash
# Find all risk definitions
.laida/templates/risk.yaml      # Schema
outputs/**/R-*.yaml             # Generated artifacts

# Find all QAS
.laida/templates/qas.yaml       # Schema
outputs/**/QAS-*.yaml           # Generated artifacts

# Find all prompts for a phase
.laida/prompts/phase{N}/*.yaml

# Find methodology config
outputs/phase0/step0_profiling/methodology_config.yaml
```

## ID Patterns

All artifacts use sequential IDs for traceability:

```
R-001, R-002         # Risks
QAS-001, QAS-002     # Quality Attribute Scenarios
F-001, F-002         # Functions
M-001, M-002         # Directives (Mandates)
ADR-001              # Architecture Decision Records
TDR-001              # Tech Decision Records
BC-001               # Bounded Contexts
```

## Methodology Execution

### Starting a Project
1. User completes `inputs/project_context.yaml`
2. Phase 0 Step 0 calculates scale and selects tech stack
3. Each subsequent step reads `_index.yaml` files from previous steps
4. Outputs go to `outputs/phase{N}/step{M}_{name}/`

### Scale-Adaptive Behavior

The methodology adapts based on calculated project scale:

| Scale | Max Risks | Max QAS | Max Functions | Skipped Sections |
|-------|-----------|---------|---------------|------------------|
| small | 5 | 5 | 15 | directive files, fitness functions |
| medium | 10 | 10 | 40 | chaos engineering |
| large | unlimited | unlimited | unlimited | none |

### Output Requirements
- Every output directory has `_index.yaml` for discoverability
- All metrics must be quantifiable (no "fast", "secure" without numbers)
- No placeholder content (TBD, TODO)
- Every artifact links to at least one parent (traceability)

## Phases Overview

| Phase | Name | Output Focus |
|-------|------|--------------|
| 0 | Strategic Foundation | Scale, tech stack, risks, QAS, bounded contexts, ADRs |
| 1 | Module Design | Module specs, DDD aggregates, validation |
| 2 | Physical Design | File structure, CoT architecture |
| 3 | Contract Definition | API contracts, dependency analysis |
| 4 | Implementation | Code scaffolding, verification, release |

## Editing Prompts

When modifying step prompts (`.laida/prompts/phase{N}/step{M}_*.yaml`):

1. Always include `extends: "../base_prompt.yaml"` at top
2. Define explicit `inputs` (required/reference) and `outputs` (files with purpose)
3. List `phases` as sequential numbered actions
4. Include `output_formats` with YAML schemas
5. Add `validation` with pre/post conditions

## Cross-Reference Validation

Before completing any step, verify:
- Every QAS links to at least one Risk
- Every Function links to at least one QAS
- Every ADR references Risks/QAS it addresses
- No orphan artifacts exist

## Constraints from project_context.yaml

These validation rules are enforced:
- `criticality: mission-critical` requires `budget >= 2000`
- `criticality: business-critical` requires `budget >= 500`
- `rpo_minutes: 0` requires `data_replication_strategy: sync`
- `hard_deadline: true` means date is contractual, not an estimate
