don-cheli-sdd 1.13.0 → 1.15.0

package/.agent/skills/doncheli-api-contract/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: doncheli-api-contract
+description: Design complete API contracts covering endpoints, auth, rate limiting, error handling, retries, circuit breaker and idempotency. Activate when user mentions "api contract", "api design", "endpoint", "webhook", "REST", "GraphQL", "OpenAPI", "design the API".
+---
+
+# Don Cheli: API Contract Designer
+
+## Instructions
+
+1. Identify the API style: REST, GraphQL, gRPC, Webhook, or mixed
+2. For each resource/operation, define:
+   - Method + path (REST) or operation name (GraphQL/gRPC)
+   - Request schema: headers, path params, query params, body
+   - Response schemas: success + all error cases
+3. Design cross-cutting concerns:
+   - **Auth**: mechanism (JWT, OAuth2, API Key, mTLS), scopes, token lifetime
+   - **Rate limiting**: strategy (token bucket / leaky bucket), limits per tier, headers exposed
+   - **Error handling**: standard error envelope, HTTP status mapping, error codes catalog
+   - **Retries**: which operations are safe to retry, backoff strategy, max attempts
+   - **Circuit breaker**: thresholds, half-open probe, fallback behavior
+   - **Idempotency**: which operations require idempotency keys, TTL, conflict semantics
+4. Define versioning strategy (URL path, header, or content negotiation)
+5. Flag breaking vs. non-breaking changes policy
+
+## Output Format
+
+```
+## API Contract: <service/feature name>
+
+### Style & Version
+- Protocol: REST / GraphQL / gRPC / Webhook
+- Base URL: …
+- Version: v1 (strategy: <path/header/content-negotiation>)
+
+### Endpoints / Operations
+
+#### <METHOD> <path>
+**Purpose:** …
+**Auth required:** yes/no — scope: …
+**Request:**
+```json
+{
+  "field": "type — description"
+}
+```
+**Response 200:**
+```json
+{ … }
+```
+**Error responses:**
+| Status | Code          | Meaning              |
+|--------|---------------|----------------------|
+| 400    | INVALID_INPUT | …                    |
+| 409    | CONFLICT      | …                    |
+
+**Idempotency:** required / not required — key: <header name>
+
+---
+
+### Cross-Cutting Concerns
+
+**Auth:** …
+**Rate Limiting:** X req/min per API key; headers: X-RateLimit-Remaining, X-RateLimit-Reset
+**Retry Policy:** safe methods (GET, PUT, DELETE) — exponential backoff, max 3 attempts
+**Circuit Breaker:** open at 50% error rate over 10s window; half-open probe after 30s
+**Error Envelope:**
+```json
+{ "error": { "code": "…", "message": "…", "trace_id": "…" } }
+```
+
+### Breaking Change Policy
+- Breaking: removing fields, changing types, removing endpoints → requires major version bump
+- Non-breaking: adding optional fields, new endpoints → compatible within same version
+```
+
+## Quality Gate
+
+- Every endpoint must have at least one documented error response
+- Idempotency policy must be explicit (required or not required) for every mutating operation
+- Auth scopes must be listed for every endpoint that requires authentication
+- Rate limit headers must be named consistently across all endpoints
+
+## Do not use this skill when
+
+- The API already exists and the user wants to review it (use doncheli-review instead)
+- The user only wants implementation, not contract design (use doncheli-implement instead)

package/.agent/skills/doncheli-audit-trail/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: doncheli-audit-trail
+description: Record and query the decision log for a project. Activate when user mentions "audit", "trail", "log decisions", "decision history", "why was this decided", "ADR", "architecture decision".
+---
+
+# Don Cheli: Audit Trail
+
+## Instructions
+
+1. Maintain a structured decision log at `.especdev/decisiones.md`
+2. When invoked to **record** a decision:
+   - Extract: decision title, date, context, options considered, chosen option, rationale, consequences
+   - Append as a new ADR-style entry (numbered, never edited after creation)
+   - Tag with: [technical | product | process | security]
+3. When invoked to **query** the log:
+   - Accept a keyword or topic and return matching entries
+   - Show: decision ID, date, title, one-line summary, and link to full entry
+4. When invoked to **review** a past decision:
+   - Find the entry, show full context, and ask if a superseding decision should be recorded
+   - Never overwrite the original — only append a "Superseded by ADR-XXX" note
+5. Surface related decisions automatically when the user is working on a feature that has prior ADRs
+6. Each entry is immutable once committed — audit integrity is the primary constraint
+
+## Output Format
+
+```markdown
+## ADR-007 — 2026-03-28
+
+**Title:** Use PostgreSQL over MongoDB for user data
+**Tags:** [technical] [database]
+**Status:** Accepted
+
+### Context
+Needed a persistence layer for structured user profiles with relational queries.
+
+### Options Considered
+- MongoDB: flexible schema, horizontal scale
+- PostgreSQL: ACID, relational queries, mature ecosystem
+
+### Decision
+PostgreSQL — relational guarantees outweigh schema flexibility for this use case.
+
+### Consequences
+- Migrations required for schema changes
+- Scales vertically before needing sharding
+```

package/.agent/skills/doncheli-changelog/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: doncheli-changelog
+description: Auto-generate CHANGELOG.md entries from git commit history. Activate when user mentions "changelog", "release notes", "what changed", "generate changelog", "CHANGELOG", "release history".
+---
+
+# Don Cheli: Changelog Auto-Generator
+
+## Instructions
+
+1. Determine the commit range:
+   - Default: from the last semver tag to HEAD
+   - With `--from`/`--to`: use the specified refs
+   - With `--version`: use that as the new version number
+2. Run `git log --oneline <range>` and parse conventional commit prefixes
+3. Map commit types to Keep a Changelog categories:
+   - `feat` / `feat!` → Added (breaking changes go in a separate top section)
+   - `fix` → Fixed
+   - `refactor` / `perf` → Changed
+   - `docs` → Changed
+   - `security` → Security
+   - `deprecated` → Deprecated
+   - `remove` → Removed
+   - `test` / `chore` / `ci` → omit by default (include with `--verbose`)
+4. Extract the short hash and append it to each entry for traceability
+5. Skip merge commits (`Merge branch`, `Merge pull request`)
+6. Insert the new section at the top of `CHANGELOG.md`, below the header — never overwrite existing entries
+7. If no `CHANGELOG.md` exists, create it with the standard Keep a Changelog header
+8. With `--dry-run`, print to stdout only — do not write to file
+9. After writing, confirm with the user and suggest `git add CHANGELOG.md`
+
+## Quality Gate
+
+- If fewer than 2 commits are found in the range, warn the user before generating
+- If breaking changes are detected (`feat!`, `BREAKING CHANGE` footer), highlight them prominently
+- Never infer a version number from non-semver tags — ask the user to provide `--version`

package/.agent/skills/doncheli-context-health/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: doncheli-context-health
+description: Report the current state of the context window and recommend compression or cleanup actions. Activate when user mentions "context health", "context window", "how much context", "context full", "running out of context", "compress context".
+---
+
+# Don Cheli: Context Health Monitor
+
+## Instructions
+
+1. Estimate the current context window usage based on:
+   - Files loaded in the current session
+   - Conversation length (turns × average tokens)
+   - Any large outputs already in context
+2. Report usage as a percentage of the model's context limit
+3. Apply thresholds from the global rules:
+   - > 50K tokens in a result → recommend isolating in subagent
+   - > 200K session tokens → recommend summarizing and compressing context
+4. Identify the highest-cost items in the current context:
+   - Large file reads
+   - Repeated content
+   - Verbose tool outputs that could be summarized
+5. Recommend specific actions:
+   - Which files can be evicted (already processed)
+   - Which outputs should be summarized
+   - Whether a subagent should handle the next task
+6. If context is healthy (< 40% used), confirm and suggest no action
+7. Never truncate or discard context without explicit user confirmation
+
+## Output Format
+
+```
+## Context Health — 2026-03-28T16:00Z
+
+### Usage Estimate
+- Current session: ~85K tokens
+- Model limit: 200K tokens
+- Usage: 42% ✅ (healthy)
+
+### Largest Items
+1. src/payments/processor.ts full read — ~8K tokens (can evict — already analyzed)
+2. Test run output from 14:32 — ~12K tokens (can summarize — report saved)
+3. Conversation history — ~18K tokens (normal)
+
+### Recommendations
+- No immediate action required
+- If you add 3+ more large files, consider /dc:destilar to compress session notes
+- Next heavy task: use a subagent to isolate output
+
+### Warning Threshold
+Will warn again at 70% usage (~140K tokens)
+```

package/.agent/skills/doncheli-data-policy/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: doncheli-data-policy
+description: Audit and document what personal or sensitive data the project collects, processes, and stores. Activate when user mentions "privacy", "data policy", "what data", "GDPR", "personal data", "data retention", "PII".
+---
+
+# Don Cheli: Data Policy Auditor
+
+## Instructions
+
+1. Scan the codebase for PII and sensitive data patterns:
+   - Database models / schemas for fields like email, phone, name, address, IP, location
+   - API request/response payloads
+   - Logging statements that may capture sensitive fields
+   - Third-party integrations that receive user data
+2. Build a data inventory table: field name, model, purpose, retention, shared with
+3. Check against common compliance requirements:
+   - GDPR: lawful basis, right to erasure, data minimization
+   - CCPA: disclosure, opt-out
+   - SOC2: access controls, encryption at rest/transit
+4. Flag violations as [critical | warning | info]
+5. Generate a draft Privacy Notice section if requested (`--generate-notice`)
+6. Save the audit to `.especdev/data-policy-audit-<date>.md`
+7. Never make assumptions about compliance status — only report findings and flag gaps
+
+## Output Format
+
+```
+## Data Policy Audit — 2026-03-28
+
+### Data Inventory
+| Field     | Model      | Purpose       | Retention | Shared With     |
+|-----------|-----------|---------------|-----------|----------------|
+| email     | User       | Auth, comms   | Indefinite| SendGrid, Auth0|
+| ip_address| AuditLog   | Security      | 90 days   | Internal only  |
+
+### Compliance Gaps
+🔴 CRITICAL: ip_address logged in plain text in audit_logs — encrypt or hash
+🟡 WARNING:  No data retention policy enforced for User.email — GDPR Art. 5(e)
+🟢 INFO:     No right-to-erasure endpoint found — required for GDPR compliance
+
+### Recommendations
+1. Add @Encrypted() decorator to ip_address field
+2. Implement DELETE /users/:id endpoint that purges all PII
+3. Document data retention in Privacy Policy
+```

package/.agent/skills/doncheli-debate/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: doncheli-debate
+description: Run an adversarial multi-role debate to surface trade-offs and reach a reasoned decision. Activate when user mentions "debate", "discuss", "trade-off", "decision", "compare options", "pros and cons", "choose between".
+---
+
+# Don Cheli: Adversarial Debate Panel
+
+## Roles
+
+Each role is played by a separate internal agent with its own agenda:
+
+| Role           | Primary Concern                          |
+|----------------|------------------------------------------|
+| CPO            | User value, market fit, time-to-market   |
+| Architect      | Scalability, maintainability, tech debt  |
+| QA Lead        | Reliability, testability, edge cases     |
+| UX Lead        | Usability, accessibility, consistency    |
+| Business       | Cost, ROI, risk, compliance              |
+
+## Instructions
+
+1. Read the decision or proposal to evaluate
+2. Each role presents its **position** (2–4 bullets) — what it likes and what it fears
+3. Each role MUST identify at least one concrete problem with every other role's proposal (no free passes)
+4. After all attacks, each role proposes one mitigation or compromise
+5. Synthesize tensions and produce a decision with explicit trade-offs accepted
+
+## Output Format
+
+```
+## Debate: <topic>
+
+### Round 1 — Positions
+**CPO:** …
+**Architect:** …
+**QA Lead:** …
+**UX Lead:** …
+**Business:** …
+
+### Round 2 — Attacks (each role vs. others)
+**CPO → Architect:** …
+**Architect → CPO:** …
+… (all cross-attacks)
+
+### Round 3 — Mitigations
+**CPO proposes:** …
+… (one per role)
+
+### Decision
+**Chosen approach:** …
+**Trade-offs accepted:** …
+**Conditions / guardrails:** …
+```
+
+## Quality Gate
+
+- No role may agree unconditionally with another — every role must raise at least one concern
+- The Decision section must name at least two trade-offs explicitly accepted
+- If consensus is impossible, output "DEADLOCK" and list the 2–3 unresolved tensions for human escalation
+
+## Do not use this skill when
+
+- The decision is already made and the user only wants implementation help
+- The question has a single objectively correct answer (use doncheli-reasoning instead)

package/.agent/skills/doncheli-diagram/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: doncheli-diagram
+description: Auto-generate Mermaid or C4 diagrams from code analysis. Activate when user mentions "diagram", "mermaid", "architecture diagram", "C4", "class diagram", "sequence diagram", "ERD", "flowchart", "visualize code".
+---
+
+# Don Cheli: Diagram Generator
+
+## Instructions
+
+1. Determine the diagram type from the request or flag: class, sequence, architecture, erd, flowchart
+2. Identify the scope: specific file, module, feature, or full project
+3. Analyze the relevant source files:
+   - **class**: parse class/interface definitions, inheritance, and composition
+   - **sequence**: trace function calls, async flows, and inter-module communication
+   - **architecture**: identify top-level modules, external services, and data flows (C4 Context/Container)
+   - **erd**: parse ORM models, entity fields, and relationships
+   - **flowchart**: follow conditional logic for a specific feature or endpoint
+4. Build the Mermaid diagram — validate syntax mentally before outputting
+5. Keep diagrams readable: maximum 20 nodes, split into subdiagrams if larger
+6. Never invent relationships not present in the code
+7. Add a generation timestamp as a Mermaid comment
+8. Offer to embed the diagram in the target file (README, spec doc, ADR)
+
+## Supported Outputs
+
+- Inline Mermaid code blocks (default) — renders in GitHub, GitLab, Notion
+- C4 PlantUML (with `--format c4`) for advanced architecture docs
+- Save to file with `--output <path>`
+
+## Quality Gate
+
+- If the analyzed scope yields fewer than 3 nodes, warn the user the diagram may not be useful
+- If source files are not readable (permissions, binary), skip and report which files were skipped
+- Do not use this skill to generate diagrams from memory — always analyze actual source files

package/.agent/skills/doncheli-distill/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: doncheli-distill
+description: Extract behavioral specifications and architecture diagrams from existing code (Blueprint Distillation / reverse engineering). Activate when user mentions "distill", "reverse engineer", "extract spec", "blueprint distillation", "understand codebase", "document existing code".
+---
+
+# Don Cheli: Blueprint Distillation
+
+## Instructions
+
+1. Identify the target module, service or codebase to distill
+2. Scan entry points (routes, controllers, event handlers, CLI commands)
+3. Trace data flows: inputs → transformations → outputs → side effects
+4. Identify implicit business rules embedded in conditionals, validations, error handling
+5. Map entity relationships from data models and DB schemas
+6. Generate Gherkin scenarios that describe the observed behavior (not the code)
+7. Produce a C4-style architecture diagram in text (Mermaid or ASCII)
+8. Flag ambiguities, dead code, and undocumented assumptions with `[NEEDS CLARIFICATION]`
+
+## Output Format
+
+```
+## Blueprint: <module/service name>
+
+### Architecture Diagram
+```mermaid
+…
+```
+
+### Distilled Spec (Gherkin)
+```gherkin
+Feature: <name>
+  Background: …
+
+  Scenario: <happy path>
+    Given …
+    When …
+    Then …
+
+  Scenario: <edge case / sad path>
+    …
+```
+
+### Implicit Business Rules
+1. <rule> — found in: <file:line>
+…
+
+### Ambiguities & Dead Code
+- [NEEDS CLARIFICATION] <description> — <file:line>
+…
+```
+
+## Quality Gate
+
+- Every entry point must map to at least one Gherkin scenario
+- Architecture diagram must show at least: external inputs, internal modules, data stores, external services
+- Business rules must cite their source location
+
+## Do not use this skill when
+
+- The user wants to write new specs for a new feature (use doncheli-spec instead)
+- The codebase has no existing logic to analyze

package/.agent/skills/doncheli-drift/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: doncheli-drift
+description: Detect and reconcile divergence between specs and implementation. Activate when user mentions "drift", "sync", "spec divergence", "out of sync", "spec doesn't match", "implementation differs".
+---
+
+# Don Cheli: Spec Drift Detector
+
+## Instructions
+
+1. Read the current spec files in `.especdev/specs/` and the relevant source code
+2. Compare spec scenarios (Gherkin / acceptance criteria) against the actual implementation
+3. Identify three categories of drift:
+   - **Ghost**: code exists but no spec covers it
+   - **Phantom**: spec exists but no code implements it
+   - **Mutant**: code and spec exist but behavior diverges
+4. For each drift finding, report: file path, spec reference, severity (critical / warning / info)
+5. Propose a reconciliation: either update the spec or flag the code for correction
+6. Never auto-modify code — output a reconciliation plan for human approval
+7. Save a drift report to `.especdev/drift-report-<date>.md` if findings exceed 3 items
+8. If zero drift is found, confirm with a brief "No drift detected — spec and code are aligned"
+
+## Output Format
+
+```
+## Drift Report — <date>
+
+### Ghost (code without spec)
+- src/payments/refund.ts:42 — no spec covers the refund edge case
+
+### Phantom (spec without code)
+- specs/checkout.feature:Scenario 3 — "Apply coupon on mobile" — not implemented
+
+### Mutant (behavior mismatch)
+- specs/auth.feature:Scenario 1 expects 401 on expired token; code returns 403
+
+### Reconciliation Plan
+1. [Phantom] Implement "Apply coupon on mobile" or mark as backlog in .especdev/backlog.md
+2. [Mutant] Fix auth.ts to return 401 — spec is correct per RFC 7235
+3. [Ghost] Add spec for refund edge case before next release
+```
+
+## Do not use this skill when
+
+- The user only wants to run tests (use doncheli-tea instead)
+- The spec has not been written yet (use dc:especificar first)

package/.agent/skills/doncheli-estimate/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: doncheli-estimate
+description: Estimate effort, duration and cost using 4 complementary models (Function Points, Planning Poker AI, COCOMO, Historical). Activate when user mentions "estimate", "estimation", "effort", "how long", "cost", "story points", "sizing".
+---
+
+# Don Cheli: Estimation Engine
+
+## Instructions
+
+1. Read the feature, story or task description
+2. Run all 4 estimation models independently (treat each as a separate agent):
+   - **Function Points**: count inputs, outputs, queries, files, interfaces; apply complexity weights
+   - **Planning Poker AI**: 3 independent agents guess simultaneously (pessimist, realist, optimist), then reconcile using Delphi method
+   - **COCOMO II**: classify project size (Organic / Semi-detached / Embedded), apply effort equation
+   - **Historical**: look for comparable past tasks in `.especdev/hallazgos.md` and `docs/`; extrapolate velocity
+3. Compute the consolidated estimate with 90% confidence interval
+4. Flag hidden risks that inflate variance
+
+## Output Format
+
+```
+## Estimation: <feature name>
+
+| Model            | Estimate   | Unit       | Confidence |
+|------------------|------------|------------|------------|
+| Function Points  | X          | hours      | medium     |
+| Planning Poker   | X–Y        | story pts  | high       |
+| COCOMO II        | X          | person-days| medium     |
+| Historical       | X          | days       | low/med    |
+
+**Consolidated:** X–Y days (90% CI)
+**Key assumptions:** …
+**Top 3 risks that increase variance:** …
+```
+
+## Quality Gate
+
+- All 4 models must be executed; do not skip any
+- If Historical has no comparable baseline, mark as N/A and explain
+- If Planning Poker spread > 2x, escalate: ask the user to clarify scope before finalizing
+
+## Do not use this skill when
+
+- The task is trivially small (< 1 hour) — just state it directly
+- The user is asking for a rough gut-feel order of magnitude; use a one-liner instead

package/.agent/skills/doncheli-implement/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: doncheli-implement
+description: Execute TDD implementation from task list following RED-GREEN-REFACTOR cycle with mandatory tests, stub detection, and quality gates. Activate when user mentions "implement", "build", "code", "develop", "implementar".
+---
+
+# Don Cheli: TDD Implementer
+
+## Iron Law #1: TDD is MANDATORY
+Every piece of production code MUST have a test written BEFORE the implementation.
+
+## Cycle
+1. **RED**: Write a test that FAILS
+2. **GREEN**: Write MINIMUM code to make the test pass
+3. **REFACTOR**: Clean up without changing behavior
+
+## Rules
+- Never skip tests
+- Never mark a task complete if stubs exist (`// TODO`, `throw new Error('not implemented')`)
+- Run linter after each task
+- Check coverage >= 85% on new code
+- If a test fails 3 times, STOP and ask the user (Stop-Loss rule)
+
+## Quality Gates
+- Gate 5: All tasks have TDD pairs (test + implementation)
+- Gate 6: All tests pass, coverage met, lint clean, build succeeds

package/.agent/skills/doncheli-migrate/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: doncheli-migrate
+description: Plan and execute technology migrations with wave planning, breaking change detection and task generation. Activate when user mentions "migrate", "migration", "upgrade", "move from", "switch to", "Vue to React", "JS to TS", "v1 to v2".
+---
+
+# Don Cheli: Migration Planner
+
+## Instructions
+
+1. Identify source stack/version and target stack/version
+2. Scan the codebase (or description) to inventory affected modules, dependencies, patterns
+3. Build the equivalence map: `source construct → target construct`
+4. Detect breaking changes (API removals, semantic shifts, config format changes)
+5. Produce a wave plan ordered by risk and dependency graph (low-risk, foundational first)
+6. Generate atomic migration tasks, each independently deployable or reviewable
+
+## Output Format
+
+```
+## Migration Plan: <source> → <target>
+
+### Equivalence Map
+| Source                  | Target                        | Notes          |
+|-------------------------|-------------------------------|----------------|
+| <old pattern/API>       | <new pattern/API>             | …              |
+
+### Breaking Changes
+1. <change> — Impact: <high/medium/low> — Mitigation: …
+…
+
+### Wave Plan
+**Wave 1 — Foundation (lowest risk)**
+- [ ] Task: …
+- [ ] Task: …
+
+**Wave 2 — Core Migration**
+- [ ] Task: …
+
+**Wave 3 — Cleanup & Optimization**
+- [ ] Task: …
+
+### Rollback Strategy
+…
+
+### Definition of Done
+- [ ] All tests pass on target stack
+- [ ] No references to deprecated source APIs remain
+- [ ] Performance benchmarks ≥ baseline
+```
+
+## Quality Gate
+
+- Every breaking change must have an explicit mitigation
+- Wave 1 must be deployable independently without completing later waves
+- If the migration affects >10 files, confirm scope with the user before generating all tasks
+
+## Do not use this skill when
+
+- The change is a minor dependency bump with no API changes (use a standard fix commit)
+- The user only wants to understand differences, not plan tasks (use doncheli-reasoning instead)

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

@@ -0,0 +1,19 @@
+---
+name: doncheli-plan
+description: Generate technical blueprint from Gherkin specs including API contracts, service design, database schema, and WebSocket events. Activate when user mentions "plan", "blueprint", "technical design", "architecture", "planificar".
+---
+
+# Don Cheli: Technical Planner
+
+## Instructions
+1. Read the Gherkin specs and DBML schemas
+2. Define API contracts (REST endpoints with request/response schemas)
+3. Design service layer (modules, repositories, services)
+4. Define WebSocket events (if real-time features exist)
+5. Map database schema from DBML to ORM
+6. Check constitution adherence
+7. Output as `blueprint.plan.md`
+
+## Quality Gate
+- Every Gherkin scenario must map to at least one API endpoint or service method
+- All DBML tables must have corresponding ORM models in the plan