@devran-ai/kit 4.1.0

package/.agent/skills/plan-validation/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: plan-validation
+description: Quality gate for implementation plans. Validates schema compliance, cross-cutting concerns, and completeness scoring before user presentation.
+version: 1.0.0
+triggers: [post-plan-creation]
+allowed-tools: Read, Grep
+---
+
+# Plan Validation
+
+> Quality gate ensuring every implementation plan meets enterprise standards
+> before being presented to the user for approval.
+
+---
+
+## Overview
+
+This skill is used by the planner agent as a self-validation checklist after creating a plan but BEFORE presenting it to the user. The planner applies the validation pipeline below to its own output, verifying against the quality schema (`plan-schema.md`), checking cross-cutting concerns, and calculating a completeness score. Plans that fail validation are revised before presentation.
+
+**Invocation**: The planner runs this checklist during `/plan` workflow step 3.5. This is NOT a separate agent — the planner validates its own plan against these criteria.
+
+---
+
+## Validation Pipeline
+
+### Step 1: Task Size Classification
+
+Determine the task size from the plan content:
+
+| Indicator | Classification |
+|-----------|---------------|
+| Plan references 1-2 files | **Trivial** |
+| Plan references 3-10 files | **Medium** |
+| Plan references 10+ files | **Large** |
+| Estimated effort < 30 minutes | **Trivial** |
+| Estimated effort 1-4 hours | **Medium** |
+| Estimated effort > 4 hours | **Large** |
+
+Use the HIGHER classification when indicators conflict.
+
+### Step 2: Schema Compliance
+
+Verify all required sections are present and substantively populated:
+
+**Tier 1 Sections (Always Required)**:
+
+| # | Section | Check |
+|---|---------|-------|
+| 1 | Context & Problem Statement | Present and >= 2 sentences |
+| 2 | Goals & Non-Goals | Both goals AND non-goals stated |
+| 3 | Implementation Steps | Steps have file paths and verification criteria |
+| 4 | Testing Strategy | Test types specified with coverage targets |
+| 5 | Security Considerations | Substantive content or explicit "N/A — [reason]" |
+| 6 | Risks & Mitigations | At least 1 risk with severity and mitigation |
+| 7 | Success Criteria | Measurable, checkable outcomes |
+
+**Tier 2 Sections (Required for Medium/Large)**:
+
+| # | Section | Check |
+|---|---------|-------|
+| 8 | Architecture Impact | Components and files identified |
+| 9 | API / Data Model Changes | Schemas defined (or N/A with reason) |
+| 10 | Rollback Strategy | Concrete undo procedure |
+| 11 | Observability | Logging/metrics plan |
+| 12 | Performance Impact | Assessment provided |
+| 13 | Documentation Updates | Specific docs identified |
+| 14 | Dependencies | Blockers and dependents listed |
+| 15 | Alternatives Considered | At least 1 rejected alternative with reasoning |
+
+### Step 3: Cross-Cutting Verification
+
+These sections MUST be non-empty regardless of task domain:
+
+| Section | Acceptable Content |
+|---------|-------------------|
+| **Security Considerations** | Specific requirements from `rules/security.md` OR `N/A — [valid justification]` |
+| **Testing Strategy** | At least unit test plan with coverage target OR `N/A — [valid justification]` |
+| **Documentation Updates** | Specific docs listed OR `N/A — no docs affected` |
+
+**Unacceptable**: Empty section, placeholder text, section completely missing.
+
+### Step 4: Specificity Audit
+
+Verify that implementation steps are actionable, not vague:
+
+| Vague (FAIL) | Specific (PASS) |
+|-------------|-----------------|
+| "Update the component" | "Add `onSubmit` handler to `src/components/LoginForm.tsx`" |
+| "Add tests" | "Create `tests/auth.test.js` with login success/failure cases" |
+| "Fix the bug" | "Change line 42 of `lib/parser.js`: replace `==` with `===`" |
+| "Style the UI" | "Add Tailwind classes `flex gap-4 p-6` to `Header.tsx`" |
+
+**Rule**: Every implementation step MUST include a file path.
+
+### Step 5: Completeness Scoring
+
+Calculate the score using the rubric from `plan-schema.md`:
+
+**Tier 1 Scoring** (60 points max):
+
+| Section | Points |
+|---------|--------|
+| Context & Problem Statement | 10 |
+| Goals & Non-Goals | 10 |
+| Implementation Steps | 10 |
+| Testing Strategy | 10 |
+| Security Considerations | 10 |
+| Risks & Mitigations | 5 |
+| Success Criteria | 5 |
+
+**Tier 2 Scoring** (20 additional points):
+
+| Section | Points |
+|---------|--------|
+| Architecture Impact | 4 |
+| API / Data Model Changes | 3 |
+| Rollback Strategy | 3 |
+| Observability | 2 |
+| Performance Impact | 2 |
+| Documentation Updates | 2 |
+| Dependencies | 2 |
+| Alternatives Considered | 2 |
+
+**Score Rules**:
+- Section present and substantively populated = full points
+- Section present but placeholder/minimal = half points
+- Section missing = 0 points
+- "N/A" with valid justification = full points
+
+**Domain Enhancement Scoring** (bonus/penalty on top of tier score):
+- For each domain in `matchedDomains` from the loading engine:
+  - Domain enhancer section present and substantive = **+2 bonus points**
+  - Domain matched but enhancer section missing = **-2 penalty points**
+  - Domain matched with "N/A — [valid reason]" = no bonus, no penalty
+- Maximum domain bonus: +6 points (3 domains × 2 points)
+- Domain scoring does not change the pass threshold — it provides additional quality signal
+
+### Step 6: Verdict
+
+| Condition | Verdict | Action |
+|-----------|---------|--------|
+| Score >= 70% of tier max | **PASS** | Present plan to user with score |
+| Score < 70% of tier max | **REVISE** | Identify gaps, revise, re-validate |
+
+**Revision Protocol**:
+1. Identify the specific missing or weak sections
+2. Provide targeted instructions to the planner for revision
+3. Re-run validation after revision
+4. Maximum 2 revision cycles — then present with warnings
+
+---
+
+## Output Format
+
+After validation, append to the plan:
+
+```markdown
+## Plan Quality Assessment
+
+**Task Size**: [Trivial/Medium/Large]
+**Quality Score**: [X]/[max] ([percentage]%) [+N domain bonus / -N domain penalty]
+**Verdict**: [PASS/REVISE]
+
+### Validation Results
+
+| Check | Status |
+|-------|--------|
+| Schema Compliance | [sections present]/[sections required] |
+| Cross-Cutting Concerns | [All addressed / Missing: X, Y] |
+| Specificity Audit | [All steps have file paths / X steps lack paths] |
+| Domain Enhancement | [N domains matched, N enhancer sections present] |
+| Rules Consulted | [list of rule files referenced] |
+| Matched Domains | [list from loading engine] |
+```
+
+---
+
+## Integration
+
+- **Invoked by**: `/plan` workflow (step 3.5, between plan creation and user presentation)
+- **Depends on**: `plan-schema.md` for scoring rubric, `domain-enhancers.md` for domain sections
+- **Feeds into**: Plan quality score shown to user alongside the plan
+- **Learning**: Quality scores are logged to `.agent/contexts/plan-quality-log.md` for adaptive improvement
+
+---
+
+## Principles
+
+1. **Validate, don't block**: The goal is quality improvement, not gatekeeping. After 2 revision cycles, present the plan with warnings rather than blocking indefinitely.
+2. **Score transparently**: The user sees the quality score and understands what was checked.
+3. **Learn from outcomes**: Post-implementation retrospectives compare predicted vs. actual to calibrate future scoring.
+4. **Cross-cutting is non-negotiable**: Security, testing, and documentation sections must ALWAYS be addressed. This is the single most impactful quality gate.

package/.agent/skills/plan-writing/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: plan-writing
+description: Structured task planning with clear breakdowns, dependencies, and verification criteria.
+version: 1.0.0
+allowed-tools: Read, Glob, Grep
+---
+
+# Plan Writing
+
+> Small tasks, clear outcomes, verifiable results.
+
+---
+
+## Overview
+
+Framework for breaking down work into clear, actionable tasks with verification criteria.
+
+---
+
+## Task Breakdown Principles
+
+### 1. Small, Focused Tasks
+
+- Each task: 2-5 minutes
+- One clear outcome per task
+- Independently verifiable
+
+### 2. Clear Verification
+
+- How do you know it's done?
+- What can you check/test?
+- What's the expected output?
+
+### 3. Logical Ordering
+
+- Dependencies identified
+- Parallel work where possible
+- Critical path highlighted
+- **Verification is always LAST**
+
+---
+
+## Planning Principles
+
+> 🔴 **NO fixed templates. Each plan's CONTENT is UNIQUE to the task.**
+> ✅ **Every plan MUST satisfy the quality schema in `plan-schema.md`.**
+> Dynamic content within a consistent structure = the standard.
+
+### Principle 1: Right-Size to Task Tier
+
+Plan length MUST match task complexity:
+
+| Task Tier | Max Sections | Max Tasks | Guideline |
+| --------- | ------------ | --------- | --------- |
+| **Trivial** (1-2 files) | Tier 1 only (7 sections) | 5-8 tasks | ~1 page — concise, no specialist synthesis |
+| **Medium** (3-10 files) | Tier 1 + Tier 2 (15 sections) | 8-15 tasks | 2-3 pages — includes specialist input |
+| **Large** (10+ files) | Tier 1 + Tier 2 + domains (15+ sections) | 15-25 tasks | 3-5 pages — full multi-agent synthesis |
+
+| ❌ Wrong | ✅ Right |
+| -------- | -------- |
+| 50 tasks with sub-sub-tasks | Right-sized task count per tier |
+| Every micro-step listed | Only actionable items |
+| Verbose descriptions | One-line per task |
+| Large task crammed into 1 page | Large task gets full Tier 2 coverage |
+| Trivial task with 15 sections | Trivial task uses Tier 1 only |
+
+> **Rule:** Trivial tasks stay concise (~1 page). Medium/Large tasks expand to cover all required tier sections. Never sacrifice completeness for brevity on complex tasks.
+
+---
+
+### Principle 2: Be SPECIFIC, Not Generic
+
+| ❌ Wrong             | ✅ Right                                                 |
+| -------------------- | -------------------------------------------------------- |
+| "Set up project"     | "Run `npx create-next-app`"                              |
+| "Add authentication" | "Install next-auth, create `/api/auth/[...nextauth].ts`" |
+| "Style the UI"       | "Add Tailwind classes to `Header.tsx`"                   |
+
+---
+
+### Principle 3: Dynamic Content Based on Context
+
+**For NEW PROJECT:**
+
+- What tech stack?
+- What's the MVP?
+- What's the file structure?
+
+**For FEATURE ADDITION:**
+
+- Which files are affected?
+- What dependencies needed?
+- How to verify it works?
+
+**For BUG FIX:**
+
+- What's the root cause?
+- What file/line to change?
+- How to test the fix?
+
+---
+
+### Principle 4: Verification is Simple
+
+| ❌ Wrong                     | ✅ Right                                     |
+| ---------------------------- | -------------------------------------------- |
+| "Verify the component works" | "Run `npm run dev`, click button, see toast" |
+| "Test the API"               | "curl localhost:3000/api/users returns 200"  |
+| "Check styles"               | "Open browser, verify dark mode works"       |
+
+---
+
+### Principle 5: Cross-Cutting Concerns Are Mandatory
+
+Every plan MUST explicitly address:
+
+1. **Security**: Reference `.agent/rules/security.md` — what security implications exist?
+2. **Testing**: Reference `.agent/rules/testing.md` — what test types are needed? Coverage targets?
+3. **Documentation**: Reference `.agent/rules/documentation.md` — which docs need updating?
+
+If a concern is genuinely not applicable, state `N/A — [one-line justification]`.
+
+**NEVER silently omit these sections.** Silent omission is a plan defect.
+
+---
+
+### Principle 6: Schema Compliance
+
+Every plan MUST satisfy the quality schema defined in `plan-schema.md`:
+
+- **Tier 1** sections are ALWAYS required. Omitting any Tier 1 section is a plan defect.
+- **Tier 2** sections are required for Medium and Large tasks (3+ files or 1+ hours).
+- Before presenting a plan, validate it against the schema checklist.
+- Plans scoring below 70% of their tier maximum must be revised before presentation.
+
+See also: `domain-enhancers.md` for domain-specific plan sections.
+
+---
+
+## Plan Structure (Minimal)
+
+```markdown
+# [Task Name]
+
+## Goal
+
+One sentence: What are we building/fixing?
+
+## Tasks
+
+- [ ] Task 1: [Action] → Verify: [Check]
+- [ ] Task 2: [Action] → Verify: [Check]
+- [ ] Task 3: [Action] → Verify: [Check]
+
+## Done When
+
+- [ ] [Main success criteria]
+
+## Notes
+
+[Any important considerations]
+```
+
+> **That's it.** No phases, no sub-sections unless truly needed.
+
+---
+
+## Best Practices
+
+1. **Start with goal** — What are we building/fixing?
+2. **Max 10 tasks** — If more, break into multiple plans
+3. **Each task verifiable** — Clear "done" criteria
+4. **Project-specific** — No copy-paste templates
+5. **Update as you go** — Mark `[x]` when complete
+
+---
+
+## When to Use
+
+- New project from scratch
+- Adding a feature
+- Fixing a bug (if complex)
+- Refactoring multiple files

package/.agent/skills/plan-writing/domain-enhancers.md

@@ -0,0 +1,184 @@
+# Domain-Specific Plan Enhancers
+
+> When the loading engine matches specific domains for a task, the planner
+> MUST include the corresponding domain-specific sections below.
+> These sections are additive to the base plan schema (Tier 1 + Tier 2).
+
+---
+
+## Frontend Domain
+
+**Triggered when**: `frontend` domain matched (keywords: react, next.js, component, css, ui, ux, etc.)
+
+Include in plan:
+
+- **Accessibility (WCAG 2.1 AA)**: Identify components requiring ARIA labels, keyboard navigation, screen reader support, color contrast compliance (minimum 4.5:1 normal text, 3:1 large text)
+- **Responsive Design**: Specify breakpoints to test (mobile 375px, tablet 768px, desktop 1280px), identify layout changes per breakpoint, verify touch targets (minimum 44x44px)
+- **Bundle Size Impact**: Estimate size of new dependencies, identify tree-shaking opportunities, consider code splitting for new routes, set bundle budget (initial JS < 200KB gzipped)
+- **Core Web Vitals**: Assess impact on LCP (< 2.5s), CLS (< 0.1), INP (< 200ms), identify render-blocking resources
+- **Component Composition**: Specify component hierarchy, prop interfaces, state management approach (local vs. global), identify shared components for extraction
+- **Rendering Strategy**: SSR vs CSR vs ISR decision for each route, hydration impact assessment, streaming SSR opportunities
+- **Design System Compliance**: Verify alignment with existing design tokens (colors, spacing, typography), identify new tokens required
+- **Error Boundaries**: Define error boundary placement, fallback UI for each failure mode, error reporting integration
+
+---
+
+## Backend Domain
+
+**Triggered when**: `backend` domain matched (keywords: api, server, node, express, middleware, endpoint, etc.)
+
+Include in plan:
+
+- **API Contract**: Define request/response schemas (Zod validation), HTTP methods, status codes, error response format (RFC 7807 Problem Details), versioning strategy
+- **Error Handling**: Specify error response structure, error codes, client-facing messages vs. internal logging, error correlation IDs for tracing
+- **Rate Limiting**: Identify endpoints requiring rate limits, specify limits (requests/minute/user), throttling strategy (sliding window vs. token bucket), response headers (X-RateLimit-*)
+- **Middleware Chain**: Document new middleware additions, execution order, impact on existing middleware stack, short-circuit conditions
+- **Database Interaction**: Query patterns (parameterized), transaction boundaries, connection pooling impact, N+1 query prevention
+- **Input Validation**: Validation layer placement (controller vs. middleware), sanitization strategy, content-type enforcement, request size limits
+- **Idempotency**: Identify non-idempotent operations, implement idempotency keys for critical mutations, retry safety assessment
+- **Observability**: Structured logging format (JSON), request tracing headers (X-Request-ID propagation), health check endpoint specification
+
+---
+
+## Database Domain
+
+**Triggered when**: `database` domain matched (keywords: database, sql, migration, schema, query, orm, etc.)
+
+Include in plan:
+
+- **Migration Rollback**: Write both up and down migrations, test rollback procedure before deploying, zero-downtime migration pattern (expand-contract for schema changes)
+- **Index Impact Analysis**: Identify queries affected by schema changes, recommend index additions/removals, estimate query performance impact, verify composite index column order matches query patterns
+- **Data Integrity**: Define constraints (foreign keys, unique, not null, check), cascade behavior for deletions, domain invariant enforcement at database level
+- **Backup Verification**: Verify backup exists before destructive migrations, test restore procedure for critical tables, point-in-time recovery validation
+- **Query Performance**: Benchmark key queries before and after changes (EXPLAIN ANALYZE), set acceptable latency thresholds (p50 < 10ms, p99 < 100ms for OLTP), identify sequential scan risks
+- **Consistency Model**: Specify required consistency level (strong/eventual), transaction isolation level selection (Read Committed default, Serializable for financial), optimistic vs. pessimistic locking strategy
+- **Data Classification**: Identify PII columns requiring encryption at rest, data retention policy compliance, audit trail requirements for sensitive data mutations
+- **Connection Management**: Connection pool sizing for workload (pool_size = num_cores * 2 + disk_spindles), statement timeout configuration, idle connection cleanup
+
+---
+
+## DevOps Domain
+
+**Triggered when**: `devops` domain matched (keywords: deploy, ci, cd, docker, kubernetes, pipeline, etc.)
+
+Include in plan:
+
+- **Infrastructure Changes**: Specify IaC modifications (Dockerfile, docker-compose, CI config), environment variable additions, 12-Factor App compliance check
+- **Monitoring & Alerting**: Define new metrics to track, alerting thresholds (SLO-derived), dashboard updates, golden signals coverage (latency, traffic, errors, saturation)
+- **Progressive Rollout**: Strategy for deployment (canary → staged → full), rollback triggers (error rate > 1%, latency p99 > 2x baseline), automated rollback criteria, health check endpoints
+- **Runbook Updates**: Document operational procedures for the new functionality, incident response steps, escalation paths
+- **Environment Parity**: Verify changes work across dev, staging, and production environments, configuration drift detection
+- **GitOps Compliance**: Infrastructure changes committed to version control, declarative configuration (desired state, not imperative scripts), automated drift reconciliation
+- **Container Security**: Base image selection (distroless/alpine preferred), multi-stage build optimization, no secrets in image layers, vulnerability scanning in CI
+- **Observability Pipeline**: Log aggregation configuration, trace sampling strategy, metric cardinality assessment, correlation between logs/traces/metrics
+
+---
+
+## Security Domain
+
+**Triggered when**: `security` domain matched (keywords or implicit triggers: auth, login, signup, form, payment, etc.)
+
+Include in plan (in addition to mandatory security considerations):
+
+- **Threat Model (STRIDE)**: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege — assess each for the change with severity rating
+- **Authentication Flow Impact**: How the change affects login, session management, token lifecycle, OAuth 2.0 flow selection (Authorization Code + PKCE for SPAs, Client Credentials for M2M)
+- **Data Classification**: Identify data sensitivity levels (public, internal, confidential, restricted), storage and transmission requirements per level
+- **Compliance Requirements**: GDPR/CCPA implications (data minimization, consent, right to erasure, breach notification within 72 hours)
+- **Secret Management**: New secrets required, rotation policy, storage mechanism (environment variables only), zero hardcoded credentials enforcement
+- **Zero Trust Assessment**: Authentication at every boundary (never trust, always verify), least privilege access for new endpoints/services, micro-segmentation for new network paths
+- **Supply Chain Security**: New dependency audit (license, maintainer, vulnerability scan), lockfile integrity verification, SRI hashes for CDN resources
+- **Input Boundary Defense**: All external inputs validated and sanitized, output encoding for context (HTML/URL/JS), parameterized queries only (no string concatenation)
+
+---
+
+## Performance Domain
+
+**Triggered when**: `performance` domain matched (keywords: slow, optimize, speed, bundle, lighthouse, cache, etc.)
+
+Include in plan:
+
+- **Performance Budget**: Define acceptable thresholds (LCP < 2.5s, FID < 100ms, page load < 3s, API p99 < 500ms, memory < 512MB per process)
+- **Profiling Strategy**: Tools and methods to measure before/after (Lighthouse, Chrome DevTools, load testing with k6/Artillery), baseline measurement requirements
+- **Caching Architecture**: Cache layers (browser → CDN → application → database), TTL values per layer, invalidation strategy (time-based, event-driven, version-key), cache stampede prevention (stale-while-revalidate, locking)
+- **Lazy Loading**: Identify resources for deferred loading, intersection observer patterns, dynamic imports for route-level code splitting, image loading strategy (responsive images, next-gen formats)
+- **Benchmarking**: Define benchmark suite, baseline measurements, regression detection thresholds, automated performance gates in CI
+- **Database Query Optimization**: EXPLAIN ANALYZE for new/modified queries, index coverage verification, N+1 detection, read replica routing for heavy reads
+- **Concurrency Model**: Event loop impact assessment, worker thread candidates for CPU-intensive operations, connection pool saturation risk
+- **CDN Strategy**: Edge caching rules for static assets, cache-control header specification, origin shield configuration, geographic distribution assessment
+
+---
+
+## Mobile Domain
+
+**Triggered when**: `mobile` domain matched (keywords: mobile, react native, expo, ios, android, etc.)
+
+Include in plan:
+
+- **Platform Parity**: Identify iOS vs. Android differences in behavior, UI, or API access, platform-specific code paths (#ifdef equivalent)
+- **Offline Support**: Define offline behavior, data sync strategy (optimistic vs. pessimistic), conflict resolution (last-write-wins, CRDT, manual merge), network-aware queries
+- **App Store Guidelines**: Compliance with Apple HIG and Material Design 3, review guideline risks, in-app purchase requirements
+- **Native Modules**: Bridge requirements, native module dependencies, build configuration changes (Podfile/build.gradle)
+- **Device Testing**: Target device matrix, screen size variations, OS version compatibility (minimum iOS 15 / Android API 26)
+- **Navigation Architecture**: Navigation pattern selection (stack, tab, drawer), deep linking support, back navigation handling per platform
+- **Mobile Performance Budget**: App startup time < 2s, frame rate 60fps minimum, memory usage < 150MB, APK/IPA size budget
+- **State Persistence**: Local storage strategy (AsyncStorage, SQLite, MMKV), state rehydration on app resume, background task handling
+
+---
+
+## Reliability Domain
+
+**Triggered when**: `reliability` domain matched (keywords: reliability, uptime, monitoring, sre, sla, slo, sli, etc.)
+
+Include in plan:
+
+- **SLO Definition**: Define Service Level Objectives for affected services (availability target, latency targets at p50/p95/p99, error rate budget)
+- **SLI Instrumentation**: Specify Service Level Indicators to measure (request success rate, request latency, system throughput), measurement method and data source
+- **Error Budget Impact**: Assess how the change affects existing error budgets, define acceptable error budget consumption for rollout
+- **Golden Signals**: Monitoring for all four golden signals (latency, traffic, errors, saturation) for new/modified services
+- **Resilience Patterns**: Circuit breaker placement, retry policy (exponential backoff with jitter), timeout configuration, bulkhead isolation for critical paths
+- **Incident Preparedness**: Runbook for new failure modes, alerting rules (page vs. ticket), escalation matrix, blast radius assessment
+- **Chaos Engineering**: Identify failure injection points for validation, steady-state hypothesis, abort conditions for chaos experiments
+- **Capacity Planning**: Resource requirements (CPU, memory, network, storage), scaling triggers (auto-scale thresholds), load testing validation for expected traffic growth
+
+---
+
+## Observability Domain
+
+**Triggered when**: `observability` domain matched (keywords: logging, tracing, metrics, monitoring, alerting, opentelemetry, etc.)
+
+Include in plan:
+
+- **Three Pillars Coverage**: Specify logging additions (structured JSON), metrics (counters, histograms, gauges), traces (span creation, context propagation)
+- **OpenTelemetry Integration**: SDK initialization, auto-instrumentation scope, manual span creation for business-critical paths, sampling strategy (head-based vs. tail-based)
+- **Log Architecture**: Log levels and when to use each (ERROR: actionable failures, WARN: degradation, INFO: business events, DEBUG: development only), structured fields, correlation ID propagation
+- **Alerting Strategy**: Alert conditions derived from SLOs, notification channels (PagerDuty/Slack), alert fatigue prevention (multi-window burn rate), silence/snooze policies
+- **Dashboard Design**: Key metrics visualization, RED method (Rate, Errors, Duration) per service, drill-down capability from overview to detail
+- **Cost Management**: Metric cardinality assessment, log volume projection, trace sampling rate optimization, retention policy per signal type
+
+---
+
+## Distributed Systems Domain
+
+**Triggered when**: `architecture` domain matched AND task involves multiple services, message queues, or event-driven patterns
+
+Include in plan:
+
+- **Consistency Strategy**: CAP theorem trade-off for the specific use case, consistency model selection (strong, eventual, causal), Saga pattern for distributed transactions (choreography vs. orchestration)
+- **Communication Pattern**: Synchronous (REST/gRPC) vs. asynchronous (message queue/event stream) decision per interaction, protocol selection criteria
+- **Fault Tolerance**: Failure mode analysis for each service interaction, fallback behavior, partial failure handling, data loss prevention
+- **Event-Driven Design**: Event schema definition (CloudEvents format), event ordering guarantees, idempotent consumers, dead letter queue strategy
+- **Service Discovery**: Registration mechanism, health check protocol, load balancing strategy (client-side vs. server-side), circuit breaker integration
+- **Data Sovereignty**: Which service owns which data, cross-service data access patterns (API calls, not shared databases), eventual consistency reconciliation
+
+---
+
+## Usage
+
+The planner reads this file when domain-specific sections are needed:
+
+1. Loading engine returns `matchedDomains` array
+2. For each matched domain, include the corresponding enhancer section
+3. Domain sections are added AFTER the base plan schema sections
+4. Multiple domains can be active simultaneously (e.g., frontend + backend for a full-stack feature)
+5. Each domain section contributes to the plan quality score (+2 bonus per matched domain section present, -2 penalty per missing)
+6. Domain enhancers leverage the specialized knowledge of their corresponding elevated agents (e.g., reliability domain draws from reliability-engineer's SRE Golden Signals framework)

package/.agent/skills/plan-writing/plan-retrospective.md

@@ -0,0 +1,116 @@
+# Plan Retrospective
+
+> Post-implementation review protocol for measuring plan accuracy
+> and feeding learnings back into future plan generation.
+
+---
+
+## Overview
+
+After a planned task reaches the VERIFY phase (all implementation complete, tests running), this retrospective compares the original plan against actual implementation to identify accuracy gaps and improve future planning.
+
+---
+
+## When to Run
+
+- **Primary Trigger**: The `plan-complete` hook in `.agent/hooks/hooks.json` fires when workflow state transitions to VERIFY phase
+- **Manual Trigger**: User runs `/retrospective` on a completed plan
+- **Data Flow**: The hook reads the original plan file (`docs/PLAN-{slug}.md`), compares against `git diff --name-only` from the plan's creation timestamp, then appends results to `.agent/contexts/plan-quality-log.md`
+- **Frequency**: After every planned task completes implementation
+- **Blocking**: No — this is a learning activity, not a quality gate (severity: medium, onFailure: log)
+- **Planner Integration**: The planner reads `plan-quality-log.md` during Requirements Analysis (Step 1) to adjust estimates and predictions for future plans
+
+---
+
+## Retrospective Dimensions
+
+### 1. File Prediction Accuracy
+
+Compare files listed in the plan vs. files actually modified:
+
+| Metric | Measurement |
+|--------|-------------|
+| **Files Predicted** | Count of unique file paths in the plan |
+| **Files Actually Modified** | Count from `git diff --name-only` against plan start |
+| **Prediction Accuracy** | Predicted / Actual (percentage) |
+| **Surprise Files** | Files modified that were NOT in the plan |
+| **Unused Predictions** | Files in the plan that were NOT modified |
+
+### 2. Task Completeness
+
+| Metric | Measurement |
+|--------|-------------|
+| **Tasks Planned** | Count of implementation steps in original plan |
+| **Tasks Completed** | Steps that matched actual work |
+| **Surprise Tasks** | Work done that wasn't in the plan |
+| **Dropped Tasks** | Planned tasks that turned out unnecessary |
+| **Completeness Score** | (Completed - Surprise) / Planned |
+
+### 3. Estimate Accuracy
+
+| Metric | Measurement |
+|--------|-------------|
+| **Estimated Effort** | Total hours from plan |
+| **Actual Effort** | Approximate actual time spent |
+| **Drift** | Actual / Estimated (ratio; 1.0 = perfect) |
+| **Drift Direction** | Over-estimated / Under-estimated / Accurate |
+
+### 4. Risk Prediction
+
+| Metric | Measurement |
+|--------|-------------|
+| **Risks Identified** | Count of risks in plan |
+| **Risks Materialized** | Planned risks that actually occurred |
+| **Surprise Risks** | Unplanned risks that emerged |
+| **Risk Prediction Rate** | Materialized / (Materialized + Surprise) |
+
+### 5. Specialist Contribution Value
+
+| Specialist | Contribution Accurate? | Key Insight That Helped |
+|-----------|----------------------|------------------------|
+| Architect | Yes/No/Partial | [what was most useful] |
+| Security-Reviewer | Yes/No/Partial | [what was most useful] |
+| TDD-Guide | Yes/No/Partial | [what was most useful] |
+
+---
+
+## Output Format
+
+Append one row to `.agent/contexts/plan-quality-log.md`:
+
+```markdown
+| [date] | [plan name] | [quality score] | [files predicted] | [files actual] | [surprise count] | [estimate drift] | [key learning] |
+```
+
+### Key Learning Format
+
+Capture the single most important learning in one sentence:
+
+**Good examples**:
+- "Auth tasks consistently require middleware changes not predicted in plans"
+- "Database migration effort was 2x underestimated due to index rebuilding"
+- "Frontend plans should always include accessibility testing as a task"
+
+**Bad examples**:
+- "The plan was good" (not actionable)
+- "Everything went as expected" (no learning value)
+
+---
+
+## Adaptive Feedback
+
+The planner agent reads `plan-quality-log.md` at the start of each planning session to:
+
+1. **Adjust estimates**: If historical drift is consistently 1.5x, multiply estimates by 1.5
+2. **Predict surprise files**: If auth tasks consistently miss middleware, proactively include middleware files
+3. **Weight risks**: If certain risk categories historically materialize, elevate their severity
+4. **Improve domain sections**: If specific domain enhancer sections are consistently unhelpful, deprioritize them
+5. **Value specialists**: If security-reviewer contributions are consistently accurate, weight their input more heavily
+
+---
+
+## Example Retrospective Entry
+
+```
+| 2026-03-16 | PLAN-user-auth | 72/80 | 8 | 11 | 3 (middleware, session config, error handler) | 1.4x | Auth plans should include middleware and session store files by default |
+```