arkaos 2.0.0-alpha.1

package/departments/dev/skills/scaffold/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: arka-dev-scaffold
+description: >
+  Project scaffolding from real git repositories. Creates new Laravel, Nuxt, Vue, React, or
+  Next.js projects with automated dependency installation, mandatory packages, MCP configuration,
+  Laravel Herd linking, Obsidian project pages, and initial git commit. Full-stack monorepo support.
+  Use when user says "scaffold", "new project", "create project", "start project", "bootstrap",
+  "init project", "setup project", or wants to create a new codebase from a template.
+---
+
+# Project Scaffolding — ARKA OS Dev Department
+
+Create new projects from real git repositories with full automation: dependencies, MCPs, Obsidian pages, and initial commit.
+
+## Commands
+
+| Command | Git Repository | Stack |
+|---------|---------------|-------|
+| `/dev scaffold laravel <name>` | `git@andreagroferreira:andreagroferreira/laravel-starter-kit.git` | Laravel + Herd |
+| `/dev scaffold nuxt-saas <name>` | `https://github.com/nuxt-ui-templates/dashboard.git` | Nuxt 3 Dashboard |
+| `/dev scaffold nuxt-landing <name>` | `https://github.com/nuxt-ui-templates/landing.git` | Nuxt 3 Landing |
+| `/dev scaffold nuxt-docs <name>` | `https://github.com/nuxt-ui-templates/docs.git` | Nuxt 3 Docs |
+| `/dev scaffold vue-saas <name>` | `https://github.com/nuxt-ui-templates/dashboard-vue.git` | Vue 3 Dashboard |
+| `/dev scaffold vue-landing <name>` | `https://github.com/nuxt-ui-templates/starter-vue.git` | Vue 3 Landing |
+| `/dev scaffold full-stack <name>` | Laravel + Nuxt (both repos) | Full-stack |
+| `/dev scaffold react <name>` | React starter (TBD) | React SPA |
+| `/dev scaffold nextjs <name>` | Next.js starter (TBD) | Next.js App |
+
+## Workflow: /dev scaffold <type> <name>
+
+### Step 1: Clone & Initialize
+
+```bash
+# Clone the template repo
+git clone <repo-url> <name>
+cd <name>
+
+# Remove template git history and start fresh
+rm -rf .git
+git init
+```
+
+### Step 2: Install Dependencies
+
+**For Laravel projects:**
+```bash
+composer install
+```
+
+**For Nuxt/Vue projects:**
+```bash
+pnpm install
+```
+
+**For full-stack:**
+Both `composer install` (in `api/` or root) and `pnpm install` (in `frontend/` or root).
+
+### Step 3: Laravel Mandatory Packages (Laravel projects only)
+
+Read `mcps/stacks/laravel-packages.json` and install in ORDER:
+
+```bash
+# 1. Boost FIRST (enables laravel-boost MCP)
+composer require laravel/boost
+php artisan boost:install
+
+# 2. Horizon
+composer require laravel/horizon
+php artisan horizon:install
+
+# 3. Prism (AI SDK)
+composer require echolabs/prism
+
+# 4. MCP Server
+composer require php-mcp/laravel
+php artisan vendor:publish --provider="PhpMcp\Laravel\McpServiceProvider"
+```
+
+**IMPORTANT:** Boost MUST be installed first. It enables the laravel-boost MCP server.
+
+### Step 4: Laravel Herd (Laravel projects only)
+
+```bash
+herd link
+```
+
+This registers the project with Laravel Herd for local serving at `http://<name>.test`.
+
+### Step 5: Apply MCP Profile
+
+Run the MCP applicator with the appropriate profile:
+
+```bash
+bash "$ARKA_OS/mcps/scripts/apply-mcps.sh" <profile> --project "$(pwd)"
+```
+
+Profile mapping:
+- `laravel` → `laravel` profile
+- `nuxt-*` → `nuxt` profile
+- `vue-*` → `vue` profile
+- `full-stack` → `full-stack` profile
+
+This generates `.mcp.json` and `.claude/settings.local.json`.
+
+### Step 6: Generate PROJECT.md
+
+Create `PROJECT.md` in the project root with:
+
+```markdown
+# <name> — WizardingCode Project
+
+## Client
+- **Name:** [ask user or leave TBD]
+- **Type:** [project type]
+
+## Stack
+- [auto-detected from scaffold type]
+
+## Conventions
+- [inherit from ARKA OS CLAUDE.md defaults]
+
+## Decisions
+- [scaffold date and type recorded here]
+
+## MCPs Active
+- [list from applied profile]
+```
+
+Also register in ARKA OS:
+```bash
+mkdir -p "$ARKA_OS/projects/<name>"
+cp PROJECT.md "$ARKA_OS/projects/<name>/PROJECT.md"
+```
+
+### Step 7: Create Obsidian Project Page
+
+Create pages in the Obsidian vault:
+
+**Main page:** `Documents/Personal/Projects/<name>/Home.md`
+```markdown
+---
+type: project
+name: <name>
+client: TBD
+stack: [auto-detected]
+status: active
+date_created: [today]
+tags:
+  - project
+  - [stack-tag]
+---
+
+# <name>
+
+> WizardingCode Project
+
+## Overview
+[To be filled]
+
+## Architecture
+- [[<name> - Architecture]]
+
+## Links
+- Local: `~/Projects/<name>/`
+- *Part of the [[Projects MOC]]*
+```
+
+**Architecture page:** `Documents/Personal/Projects/<name>/Architecture/decisions.md`
+```markdown
+---
+type: adr-log
+project: <name>
+date_created: [today]
+tags:
+  - architecture
+  - adr
+---
+
+# Architecture Decisions — <name>
+
+## ADR-001: Initial Stack Selection
+- **Date:** [today]
+- **Decision:** Scaffolded with [type] template
+- **Rationale:** [based on project requirements]
+```
+
+### Step 8: Initial Git Commit
+
+```bash
+git add -A
+git commit -m "Initial scaffold from ARKA OS ([type] template)"
+```
+
+### Step 9: Report
+
+```
+═══ ARKA OS — Project Scaffolded ═══
+Name:        <name>
+Type:        <type>
+Stack:       [stack details]
+MCPs:        [count] active ([profile] profile)
+Herd:        http://<name>.test (Laravel only)
+Obsidian:    Projects/<name>/Home.md
+═════════════════════════════════════
+
+Next steps:
+  cd <name>
+  /dev feature "describe your first feature"
+```
+
+## React / Next.js Handling
+
+`/dev scaffold react <name>` and `/dev scaffold nextjs <name>`:
+
+1. Clone template repo
+2. `pnpm install`
+3. Apply MCP profile (`react` or `nextjs`)
+4. Generate PROJECT.md
+5. Create Obsidian project page
+6. Initial git commit
+
+**No mandatory packages step** — React/Next.js projects use recommended packages from `mcps/stacks/react-packages.json` instead. Profile mapping:
+- `react` → `react` profile
+- `nextjs` → `nextjs` profile
+
+## Full-Stack Special Handling
+
+`/dev scaffold full-stack <name>` creates a monorepo:
+
+```
+<name>/
+├── api/          ← Laravel backend (from laravel-starter-kit)
+├── frontend/     ← Nuxt dashboard (from nuxt-ui-templates/dashboard)
+├── .mcp.json     ← full-stack MCP profile
+├── .claude/
+│   └── settings.local.json
+├── PROJECT.md
+└── docker-compose.yml (if applicable)
+```
+
+Both directories get their respective dependencies installed, and the full-stack MCP profile covers both Laravel and Nuxt tools.
+
+## Error Handling
+
+- If `git clone` fails: check SSH keys (`git@andreagroferreira:` for private repos)
+- If `composer install` fails: check PHP version (`php -v`, need 8.3+)
+- If `pnpm install` fails: check Node version (`node -v`, need 18+)
+- If `herd link` fails: check Herd is installed and running
+- If Boost install fails: continue with remaining packages, warn user

package/departments/dev/skills/security-audit/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: dev/security-audit
+description: >
+  OWASP Top 10 (2025) security audit with dependency scanning and security headers check.
+allowed-tools: [Read, Bash, Grep, Glob, Agent]
+---
+
+# Security Audit — `/dev security-audit`
+
+> **Agent:** Bruno (Security Engineer)
+> **Framework:** OWASP Top 10 (2025), DevSecOps Pipeline
+
+## OWASP Top 10 (2025) Checklist
+
+| # | Vulnerability | What to Check |
+|---|-------------|--------------|
+| A01 | Broken Access Control | RBAC/ABAC implemented? Deny by default? |
+| A02 | Cryptographic Failures | TLS everywhere? Data encrypted at rest? Strong algorithms? |
+| A03 | Supply Chain Failures | Dependencies audited? SBOM exists? Signed artifacts? |
+| A04 | Injection | Parameterized queries? Input validation? Output encoding? |
+| A05 | Security Misconfiguration | Default credentials removed? Security headers present? |
+| A06 | Vulnerable Components | `npm audit` / `composer audit` clean? No known CVEs? |
+| A07 | Authentication Failures | MFA available? Rate limiting? Secure session management? |
+| A08 | Data Integrity Failures | Deserialization safe? Signed packages? CI/CD tamper-proof? |
+| A09 | Logging Failures | Security events logged? Centralized logging? Alerting? |
+| A10 | Exceptional Conditions | Secure error handling? No stack traces in production? |
+
+## Security Headers Check
+
+```
+Content-Security-Policy: default-src 'self'
+Strict-Transport-Security: max-age=31536000; includeSubDomains
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: camera=(), microphone=(), geolocation=()
+```
+
+## Automated Scans
+
+| Tool | What | Command |
+|------|------|---------|
+| npm audit | JS dependency CVEs | `npm audit --production` |
+| composer audit | PHP dependency CVEs | `composer audit` |
+| pip audit | Python dependency CVEs | `pip-audit` |
+| GitLeaks | Secrets in code | `gitleaks detect` |
+
+## Output: Security Report
+
+```markdown
+## Security Audit: <project>
+
+### CRITICAL (fix immediately)
+- [C1] SQL Injection in UserController:45 — raw query with user input
+  Fix: Use parameterized query via Eloquent
+
+### HIGH (fix before release)
+- [H1] Missing CSRF protection on /api/webhook endpoint
+
+### MEDIUM
+- [M1] npm audit: 2 moderate vulnerabilities in lodash
+
+### LOW
+- [L1] Missing Permissions-Policy header
+
+### Summary: 1 critical, 1 high, 1 medium, 1 low
+### Recommendation: BLOCK release until C1 and H1 resolved
+```

package/departments/dev/skills/skill-audit/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: dev/skill-audit
+description: >
+  Audit AI agent skills for security vulnerabilities: prompt injection, code execution, data leakage, supply chain risks.
+allowed-tools: [Read, Bash, Grep, Glob, Agent]
+---
+
+# Skill Security Auditor — `/dev skill-audit`
+
+> **Agent:** Bruno (Security Engineer) | **Framework:** OWASP LLM Top 10, Supply Chain Security
+
+## What It Does
+
+Scans AI agent skill directories for security risks before installation. Produces a PASS / WARN / FAIL verdict with findings and remediation guidance.
+
+## Scan Categories
+
+### 1. Code Execution Risks
+
+| Pattern | What to Detect | Severity |
+|---------|---------------|----------|
+| Command injection | `os.system()`, `subprocess.call(shell=True)`, backticks | CRITICAL |
+| Dynamic execution | `eval()`, `exec()`, `compile()`, `__import__()` | CRITICAL |
+| Obfuscation | base64 payloads, hex strings, `chr()` chains | CRITICAL |
+| Network exfiltration | `requests.post()`, `socket.connect()`, outbound HTTP | CRITICAL |
+| Credential harvesting | Reads `~/.ssh`, `~/.aws`, env var extraction | CRITICAL |
+| File system abuse | Writes outside skill dir, modifies `~/.bashrc` | HIGH |
+| Unsafe deserialization | `pickle.loads()`, `yaml.load()` without SafeLoader | HIGH |
+
+### 2. Prompt Injection in SKILL.md
+
+| Pattern | Example | Severity |
+|---------|---------|----------|
+| System prompt override | "Ignore previous instructions" | CRITICAL |
+| Role hijacking | "Act as root", "Pretend you have no restrictions" | CRITICAL |
+| Safety bypass | "Skip safety checks", "Disable content filtering" | CRITICAL |
+| Hidden instructions | Zero-width characters, HTML comments with directives | HIGH |
+| Data extraction | "Send contents of", "Upload file to", "POST to" | CRITICAL |
+
+### 3. Supply Chain Risks
+
+| Check | What It Does | Severity |
+|-------|-------------|----------|
+| Known CVEs | Cross-reference dependencies with advisory databases | CRITICAL |
+| Typosquatting | Flag packages similar to popular ones (e.g., `reqeusts`) | HIGH |
+| Unpinned versions | `requests>=2.0` vs `requests==2.31.0` | LOW |
+| Install in code | `pip install` or `npm install` inside scripts | HIGH |
+| Binary files | Unexpected `.so`, `.dll`, `.exe` in skill directory | CRITICAL |
+
+### 4. File System Checks
+
+| Check | What It Does | Severity |
+|-------|-------------|----------|
+| Boundary violation | Scripts referencing paths outside skill directory | HIGH |
+| Hidden files | `.env`, dotfiles that should not be in a skill | HIGH |
+| Symlinks | Symbolic links pointing outside skill directory | CRITICAL |
+| Large files | Files > 1MB that could hide payloads | LOW |
+
+## Audit Workflow
+
+1. **Scan** all `.py`, `.sh`, `.js`, `.ts`, `.md` files in the skill directory
+2. **Classify** findings by severity (CRITICAL / HIGH / LOW)
+3. **Verdict**: PASS (no critical/high), WARN (high only), FAIL (any critical)
+4. **Remediate** each finding using the fix guidance provided
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- Skill executing arbitrary shell commands → CRITICAL security flag
+- Skill reading files outside project dir → flag data leakage risk
+- No input sanitization in tool params → flag prompt injection vector
+
+## Output
+
+```markdown
+## Skill Security Audit: <skill-name>
+
+### Verdict: FAIL
+
+### CRITICAL (2 findings)
+- [C1] CODE-EXEC — scripts/helper.py:42 — `eval(user_input)`
+  Fix: Replace with `ast.literal_eval()` or explicit parsing
+- [C2] NET-EXFIL — scripts/analyzer.py:88 — `requests.post()` to external URL
+  Fix: Remove outbound calls or verify destination is trusted
+
+### HIGH (1 finding)
+- [H1] FS-BOUNDARY — scripts/scanner.py:15 — reads `~/.ssh/id_rsa`
+  Fix: Remove filesystem access outside skill directory
+
+### LOW (1 finding)
+- [L1] DEPS-UNPIN — requirements.txt:3 — `requests>=2.0`
+  Fix: Pin to specific version `requests==2.31.0`
+
+### Recommendation: Do NOT install until C1 and C2 are resolved
+```

package/departments/dev/skills/spec/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: arka-dev-spec
+description: >
+  NON-NEGOTIABLE spec-driven development gate. Creates, validates, and manages feature
+  specifications before any code is written. Uses Living Specs engine (core/specs/).
+  Interactive workflow that collaborates with
+  the user to produce detailed specs covering scope, acceptance criteria, data model,
+  API contracts, UI/UX requirements, edge cases, and test scenarios.
+  Auto-invoked as Phase 0 by all code-modifying Tier 1 and Tier 2 dev workflows
+  (/dev feature, /dev api, /dev db, and code-modifying /dev do).
+  This is a Constitution rule (NON-NEGOTIABLE #7) — no code without an approved spec.
+  Use when user says "spec", "specification", "requirements", "define feature",
+  "write spec", "describe what to build", or when any code-modifying dev command is invoked.
+---
+
+# Spec-Driven Development — ARKA OS Dev Department
+
+No code is written until a detailed spec exists and is approved. This is NON-NEGOTIABLE.
+
+## Commands
+
+| Command | Description | Lead Agent | Tier |
+|---------|-------------|------------|------|
+| `/dev spec <description>` | Create a feature spec interactively | Paulo | 3 |
+| `/dev spec validate` | Validate an existing spec for completeness | Paulo | 3 |
+| `/dev spec list` | List all specs in the current project | Paulo | 3 |
+
+## Auto-Invocation (Phase 0)
+
+This skill is automatically invoked as **Phase 0** before any code-modifying workflow:
+
+| Command | Phase 0 Applied |
+|---------|----------------|
+| `/dev feature` | Yes, always |
+| `/dev api` | Yes, always |
+| `/dev db` | Yes, always |
+| `/dev do` | Yes, when routed to feature/api/db |
+| `/dev debug` | No (investigates existing code) |
+| `/dev refactor` | No (works on existing code) |
+
+When auto-invoked, Paulo checks if an approved spec already exists. If it does, he loads it as context. If not, he triggers the interactive spec creation workflow below.
+
+## Workflow: /dev spec (Interactive Spec Creation)
+
+### Step 1: Context Loading (Paulo)
+- Read project context: PROJECT.md, CLAUDE.md, recent git log
+- Identify the project stack, existing patterns, and relevant domain context
+- Check Obsidian `Projects/<name>/Specs/` for related or overlapping specs
+
+### Step 2: Requirements Gathering (Paulo)
+Use `AskUserQuestion` to understand the feature. Ask only what is genuinely unclear; skip questions the user already answered in their request.
+
+**Core questions (ask as needed):**
+- What is the core problem or need this solves?
+- Who are the users or actors involved?
+- What are the expected inputs and outputs?
+- Are there constraints, dependencies, or integrations?
+- What does "done" look like? How will we know it works?
+
+**Follow-up questions (if applicable):**
+- Does this touch backend, frontend, or both?
+- Are there existing patterns in the codebase we should follow?
+- Any performance or scale requirements?
+- Any third-party services or APIs involved?
+
+Paulo may ask these in batches (2-3 questions at a time) to avoid overwhelming the user. The goal is a complete understanding, not an interrogation.
+
+### Step 3: Spec Drafting (Paulo)
+Draft the spec with the following sections. Not every section applies to every feature; omit sections that are genuinely irrelevant.
+
+```markdown
+---
+type: spec
+status: draft
+feature: <slug>
+project: <project-name>
+date_created: <YYYY-MM-DD>
+tags:
+  - spec
+  - <project-tag>
+  - <feature-tag>
+---
+
+# SPEC: <Feature Title>
+
+## Overview
+**Problem:** What problem does this solve?
+**Goal:** What is the desired outcome?
+**Actors:** Who uses this feature?
+
+## Scope
+**In scope:**
+- [Specific deliverable 1]
+- [Specific deliverable 2]
+
+**Out of scope:**
+- [Explicitly excluded item 1]
+
+## Acceptance Criteria
+Numbered, testable criteria. Each must be verifiable.
+
+1. Given [context], when [action], then [expected result]
+2. Given [context], when [action], then [expected result]
+3. ...
+
+## Data Model
+Entities, relationships, and schema changes.
+
+| Entity | Fields | Relationships |
+|--------|--------|--------------|
+| ... | ... | ... |
+
+**Migrations needed:**
+- [ ] Create/alter table X
+- [ ] Add index on Y
+
+## API Contracts
+Endpoints, request/response shapes, status codes.
+
+### POST /api/v1/resource
+**Request:**
+```json
+{ "field": "value" }
+```
+**Response (201):**
+```json
+{ "id": 1, "field": "value" }
+```
+**Errors:** 400 (validation), 401 (unauthorized), 409 (conflict)
+
+## UI/UX Requirements
+Screens, components, states, and flows. Skip if backend-only.
+
+- **Screen:** [Name] — [Description]
+- **States:** loading, empty, error, success
+- **Components:** [Reusable components to create or extend]
+
+## Edge Cases
+Boundary conditions, error states, and unusual scenarios.
+
+1. What happens when [edge case]?
+2. What if [boundary condition]?
+3. How does the system handle [failure scenario]?
+
+## Test Scenarios
+Derived from acceptance criteria. Maps to Phase 7 (QA).
+
+| # | Scenario | Type | Expected |
+|---|----------|------|----------|
+| 1 | ... | Feature/Unit/Component | ... |
+| 2 | ... | Feature/Unit/Component | ... |
+
+## Dependencies
+External services, existing code, or features that must exist first.
+
+- [ ] [Dependency 1]
+- [ ] [Dependency 2]
+```
+
+### Step 4: User Approval (Paulo)
+Present the complete spec to the user using `AskUserQuestion`:
+- Show the full spec content
+- Ask: "Does this spec accurately capture what you need? Any changes?"
+- Iterate until the user approves
+
+### Step 5: Save to Obsidian (Paulo)
+Save the approved spec:
+- **Path:** `Projects/<project-name>/Specs/SPEC-<slug>.md`
+- **Status:** Update frontmatter `status: approved`
+- **Link:** Add wikilink from project Home.md if it exists
+
+### Step 6: Return to Calling Workflow
+When invoked as Phase 0, return the spec to the main workflow:
+- Phase 2 (Research) uses the spec to focus research
+- Phase 3 (Architecture) uses the spec as the design source of truth
+- Phase 4 (Implementation) uses acceptance criteria as implementation targets
+- Phase 7 (QA) uses test scenarios as the testing plan
+
+## Workflow: /dev spec validate
+
+Validate an existing spec for completeness and consistency:
+
+1. Load the spec from Obsidian or from the user
+2. Check completeness:
+   - [ ] Has Overview with problem, goal, actors
+   - [ ] Has Scope with in/out boundaries
+   - [ ] Has at least 3 testable Acceptance Criteria
+   - [ ] Has Data Model (if data changes are involved)
+   - [ ] Has API Contracts (if API changes are involved)
+   - [ ] Has Edge Cases (at least 2)
+   - [ ] Has Test Scenarios matching acceptance criteria
+3. Check consistency:
+   - Data model matches API contracts
+   - Test scenarios cover all acceptance criteria
+   - Scope matches what acceptance criteria describe
+4. Report findings and suggest improvements
+
+## Workflow: /dev spec list
+
+List all specs in the current project:
+
+1. Search Obsidian `Projects/<project-name>/Specs/` for files matching `SPEC-*.md`
+2. Display a table: Feature, Status (draft/approved), Date, Acceptance Criteria count
+3. If no specs found, inform the user
+
+## Obsidian Output
+
+| Content | Path |
+|---------|------|
+| Feature specs | `Projects/<name>/Specs/SPEC-<slug>.md` |
+
+## Key Principles
+
+1. **Specs are living documents.** They can be updated as understanding grows, but changes must be acknowledged.
+2. **The spec is the contract.** If it is not in the spec, it is not in scope. Scope creep is caught here.
+3. **Specs save time.** Thirty minutes of spec writing prevents hours of rework.
+4. **User collaboration is key.** The spec is built with the user, not imposed on them.
+5. **Not every section is required.** A backend API needs Data Model and API Contracts but not UI/UX. Adapt the template.

package/departments/dev/skills/stack-check/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: dev/stack-check
+description: >
+  Audit current tech stack: versions, dependencies, security, performance, upgrade paths.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+---
+
+# Stack Check — `/dev stack-check`
+
+> **Agent:** Paulo (Tech Lead) | **Framework:** 12-Factor App + Stack Analysis
+
+## What It Does
+
+Audit current tech stack: versions, dependencies, security, performance, upgrade paths.
+
+## Output
+
+Stack health report with upgrade recommendations and risk assessment

package/departments/dev/skills/tdd-cycle/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: dev/tdd-cycle
+description: >
+  Test-Driven Development using Kent Beck's Red-Green-Refactor cycle.
+  Write failing test first, minimal code to pass, then refactor.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
+---
+
+# TDD Cycle — `/dev test <scope>`
+
+> **Agent:** Rita (QA) + Andre/Diana (implementation)
+> **Framework:** TDD Red-Green-Refactor (Kent Beck)
+
+## The Cycle
+
+```
+RED → Write a test that fails (defines desired behavior)
+  ↓
+GREEN → Write the MINIMUM code to make the test pass
+  ↓
+REFACTOR → Improve the code while keeping tests green
+  ↓
+REPEAT
+```
+
+## Rules (NON-NEGOTIABLE)
+
+1. Never write production code without a failing test
+2. Write only enough test to fail (one assertion)
+3. Write only enough code to pass the failing test
+4. Refactor only when all tests are green
+
+## Testing Pyramid
+
+| Level | Proportion | Speed | What to test |
+|-------|-----------|-------|-------------|
+| Unit | 70% | Fast | Pure functions, business logic, calculations |
+| Integration | 20% | Medium | API endpoints, DB queries, service interactions |
+| E2E | 10% | Slow | Critical user journeys only |
+
+## Test Quality Criteria
+
+- **Coverage:** >= 80% (measured, not guessed)
+- **FIRST:** Fast, Independent, Repeatable, Self-validating, Timely
+- **No mocking of what you own** — Mock external services, not your own classes
+- **Test behavior, not implementation** — Tests should survive refactoring
+
+## Stack-Specific
+
+| Stack | Framework | Command |
+|-------|-----------|---------|
+| Laravel | PHPUnit + Pest | `php artisan test` |
+| Vue/Nuxt | Vitest | `npx vitest` |
+| React/Next | Jest | `npx jest` |
+| Python | pytest | `python -m pytest` |
+| E2E | Playwright | `npx playwright test` |