@mohammadhprp/system-prompt 0.11.0 → 0.11.2

package/framework/skills/technical-design-doc-creator/examples.md

@@ -0,0 +1,35 @@
+# Technical Design Doc Creator Examples
+
+## Payment integration design doc
+
+User: "Create a TDD for integrating Stripe payments into our subscription system."
+
+Good agent behavior:
+
+- Ask about project size and type before generating, then size the document to the answer.
+- Detect the user's language and generate all headers and prose in it.
+- Enforce the mandatory sections: problem statement, scope, technical solution, risks, and implementation plan.
+- Make the Security section mandatory because this is a payment system, and collect PCI DSS, encryption, and PII handling details.
+- Keep the document at the architectural level: API contracts, data flow, and rollback strategy, not CLI commands or code snippets.
+
+## Small feature design doc
+
+User: "Write a design doc for adding user profile pictures."
+
+Good agent behavior:
+
+- Recognize this as a small feature and produce a streamlined TDD with only the essential sections.
+- Ask for the basic information needed: problem statement, scope, and technical approach.
+- Include an implementation plan with owner, status, and estimate columns.
+- Skip suggested sections like Migration Plan and Approval when they don't apply.
+
+## Migrating a database
+
+User: "Crie um TDD para migração do banco de dados PostgreSQL para MongoDB"
+
+Good agent behavior:
+
+- Detect Portuguese and generate the TDD in Portuguese with translated section headers.
+- Identify this as a data migration project and add a migration plan covering strategy, phases, and rollback.
+- Ask for the migration strategy, data mapping, and rollback plan before writing.
+- Note data integrity validation as a first-class concern rather than an afterthought.

package/framework/skills/tlc-spec-driven/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: tlc-spec-driven
+description: Feature planning and implementation with 4 adaptive phases (Specify, Design, Tasks, Execute). Auto-sizes depth by complexity. Writes testable requirements in EARS notation, atomic tasks, atomic Conventional Commits, and requirement traceability. Ships deterministic Python validation scripts so structural gates are enforced by code, not memory. Features an independent Verifier (author != verifier, evidence-or-zero), a discrimination sensor, a decision log (STATE.md), a test-coverage matrix, and a self-improving lessons layer. Stack-agnostic and tool-agnostic. Use when (1) planning features, (2) implementing with verification and atomic commits, (3) validating an implementation against a spec. Triggers on "specify feature", "discuss feature", "design", "tasks", "implement", "validate", "verify work", "UAT", "record decision", "pause work", "resume work". Do NOT use for pure architecture decomposition analysis or standalone technical design documents.
+license: CC-BY-4.0
+metadata:
+  author: Felipe Rodrigues - github.com/felipfr
+  version: 3.3.0
+---
+
+# Tech Lead's Club - Spec-Driven Development
+
+Plan and implement features with precision. Granular tasks. Clear dependencies. Right tools. Zero ceremony.
+
+```
+┌──────────┐   ┌──────────┐   ┌─────────┐   ┌─────────┐
+│ SPECIFY  │ → │  DESIGN  │ → │  TASKS  │ → │ EXECUTE │
+└──────────┘   └──────────┘   └─────────┘   └─────────┘
+   required      optional*      optional*     required
+
+* Agent auto-skips when scope doesn't need it
+```
+
+## Critical Rules (read before acting)
+
+**Loading this skill's files.** Reference files live under `references/` in this skill's own directory (where this `SKILL.md` resides). Resolve them relative to the skill directory - never the workspace root - and load them through the active skill by name; never assume a fixed install path. When a step tells you to read a reference, **read it completely (to EOF)** before acting - never act on a partial/truncated read.
+
+**Running this skill's scripts.** Every `scripts/*.py` shipped with this skill lives under that same skill directory. Resolve the skill directory first, then invoke `python3 <skill-dir>/scripts/<name>.py ...`. Never run `python3 scripts/...` from the consuming project root - that looks for a project-local `scripts/` tree that is not this skill. Project data under `.specs/` is still read/written relative to the project root (pass `--root` when the cwd is elsewhere). Below, `<skill-dir>` means the directory that contains this `SKILL.md`.
+
+**Execution contract - every task, non-negotiable (holds even if you do not open the reference files):**
+
+1. Tests derive from the spec's acceptance criteria and assert spec-defined outcomes - they never mirror the implementation.
+2. The gate must pass (tests pass) before a task is done - the test runner decides, not self-assessment.
+3. One atomic commit per task. Mark the task complete in `tasks.md` (and update spec traceability when used) **before** that commit, and include those updates in the same commit. Never batch tasks; never weaken, skip, or delete tests to make them pass.
+4. After the LAST task, a fresh **Verifier always runs automatically** (author ≠ verifier) - spec-anchored outcome check + discrimination sensor. It is never optional and never prompted. See Sub-Agent Delegation.
+5. **Blast radius:** approving a spec or tasks authorizes local implementation and local commits only. `git push`, force-push, deploy, production DB changes, and other remote / externally visible / destructive operations require an explicit go-ahead for that action.
+
+**Deterministic gates run before human review - not from memory.** The structural gates for the spec and tasks are enforced by scripts in this skill's `scripts/` directory, so they cannot silently drift when the model forgets a step:
+
+- Before confirming a spec: `python3 <skill-dir>/scripts/validate_spec.py <spec-path-or-feature>` (closure gate: EARS-shaped ACs, filled assumptions, well-formed requirement IDs, required sections).
+- Before presenting tasks for approval: `python3 <skill-dir>/scripts/validate_tasks.py <tasks-path-or-feature>` (granularity smell, diagram-vs-`Depends on` parity within a phase, no forward-phase dependency, every task carries `Tests` + `Gate`).
+- On each commit: `python3 <skill-dir>/scripts/check_commit.py --message "<msg>"` (Conventional Commits). Optionally wire it as a git `commit-msg` guard (git only, no agent dependency) - see [implement.md](references/implement.md).
+- Before declaring a feature done: `python3 <skill-dir>/scripts/validate_state.py <feature>` (completion gate: the Verifier's `validation.md` exists, its verdict is filled to PASS, and it cites `file:line` evidence - a missing, FAIL, placeholder, or evidence-free report fails). The closing step of Execute runs this automatically, the same way the lessons layer runs at distillation; it is not a manual step.
+
+A non-zero exit means STOP and fix before proceeding. Skip a script only when no code-execution tool is available; then perform the same checks by reading the artifact.
+
+**Before Execute:** read [implement.md](references/implement.md) completely and run `<skill-dir>/scripts/validate_tasks.py`; if a formal `tasks.md` packs into more than one task-budgeted batch (> ~8 tasks), present the sub-agent offer first (see Sub-Agent Delegation).
+
+## Auto-Sizing: The Core Principle
+
+**The complexity determines the depth, not a fixed pipeline.** Before starting any feature, assess its scope and apply only what's needed:
+
+| Scope       | What                     | Specify                                                 | Design                                          | Tasks                         | Execute                                               |
+| ----------- | ------------------------ | ------------------------------------------------------- | ----------------------------------------------- | ----------------------------- | ----------------------------------------------------- |
+| **Small**   | ≤3 files, one sentence   | One-liner spec (inline)                                 | Skip                                            | Skip                          | Implement + verify inline                             |
+| **Medium**  | Clear feature, <10 tasks | Spec (brief)                                            | Skip - design inline                            | Skip - tasks implicit         | Implement + verify                                    |
+| **Large**   | Multi-component feature  | Full spec + requirement IDs                             | Architecture + components                       | Full breakdown + dependencies | Implement + verify per task                           |
+| **Complex** | Ambiguity, new domain    | Full spec + [discuss gray areas](references/discuss.md) | [Research](references/design.md) + architecture | Breakdown + phase plan        | Implement + [interactive UAT](references/validate.md) |
+
+**Rules:**
+
+- **Specify and Execute are always required** - you always need to know WHAT and DO it
+- **Design is skipped** when the change is straightforward (no architectural decisions, no new patterns)
+- **Tasks is skipped** when there are ≤3 obvious steps (they become implicit in Execute)
+- **Discuss is triggered within Specify** when the agent detects ambiguous gray areas that need user input, or when the feature has any implicit-requirement dimension present (persistence/state, external calls, auth, payments, concurrency, state transitions)
+- **Interactive UAT is triggered within Execute** only for user-facing features with complex behavior
+
+**Safety valve:** Even when Tasks is skipped, Execute ALWAYS starts by listing atomic steps inline (see [implement.md](references/implement.md)). If that listing reveals >5 steps or complex dependencies, STOP and create a formal `tasks.md` - the Tasks phase was wrongly skipped.
+
+## .specs Structure
+
+```
+.specs/
+├── STATE.md            # Project memory: Decisions log (AD-NNN) + Handoff snapshot
+├── LESSONS.md          # Self-improving lessons playbook (rendered by scripts/lessons.py - do not hand-edit)
+├── lessons.json        # Canonical lessons state (machine-owned)
+└── features/           # Feature specifications
+    └── [feature]/
+        ├── spec.md         # Requirements with traceable IDs
+        ├── context.md      # User decisions for gray areas (only when discuss is triggered)
+        ├── design.md       # Architecture & components (only for Large/Complex)
+        ├── tasks.md        # Atomic tasks with verification (only for Large/Complex)
+        └── validation.md   # Verifier report: PASS/FAIL, per-AC evidence, sensor result, diff range
+```
+
+**Create artifacts lazily.** Write each file only when its phase actually produces content - never scaffold empty `context.md`, `design.md`, or `tasks.md` up front. An empty file signals a phase happened when it did not; absence is the correct state for a skipped phase. The deterministic validators (`scripts/validate_spec.py`, `scripts/validate_tasks.py`, `scripts/check_commit.py`, `scripts/validate_state.py`) ship inside this skill's own `scripts/` directory, alongside `lessons.py`.
+
+## Workflow
+
+**New feature:**
+
+1. Specify → (Design) → (Tasks) → Execute (depth auto-sized)
+
+**Resume work:**
+
+1. Read `.specs/STATE.md` (Handoff + Decisions).
+2. Reconcile Handoff against git (`branch`, `status --porcelain`, recent commits) and `tasks.md` - evidence wins over a stale snapshot. Full procedure: [memory.md](references/memory.md).
+3. Propose the reconciled next step before writing code.
+
+## Context Loading Strategy
+
+**On-demand load (only what the current task needs):**
+
+- `.specs/STATE.md` - Decisions section (read at Design, re-read on resume); Handoff section (read on resume only)
+- confirmed lessons - load at Specify and Design via `python3 <skill-dir>/scripts/lessons.py list --status confirmed` ([lessons.md](references/lessons.md)); confirmed only, never candidates
+- spec.md (when working on a specific feature)
+- context.md (when designing or implementing from user decisions)
+- design.md (when implementing from design)
+- tasks.md (when executing tasks)
+
+**Never load simultaneously:**
+
+- Multiple feature specs
+- Multiple architecture docs
+
+**Target:** <40k tokens total context
+**Reserve:** 160k+ tokens for work, reasoning, outputs
+**Monitoring:** Display status when >40k (see [context-limits.md](references/context-limits.md))
+
+## Sub-Agent Delegation
+
+**Trigger:** count total tasks. If the feature packs into more than one task-budgeted batch (> ~8 tasks) → offer sub-agents; if it fits a single batch (≤ ~8 tasks) → execute inline.
+
+**Offer-then-confirm** - never auto-spawn. The user must accept before any sub-agent is dispatched.
+
+**One worker per task-budgeted batch (~7 tasks, whole phases):** Phases stay the semantic/dependency unit; a **batch** is the execution unit - one or more *consecutive whole phases* packed to ~7 tasks. Walk phases in order, accumulate whole phases into the current batch until it reaches the budget, then start the next - **never split a phase** across workers. ~20 tasks → ~3 workers; scales linearly (40 → ~6). Each worker executes all its tasks in order (implement → gate → atomic commit), then reports a compact summary (tasks done, commit hashes, test counts, deviations). Batches run sequentially - a batch never starts until the previous one reports all tasks complete. Workers never spawn further sub-agents.
+
+**Verifier (always-on, never prompted):** After the final task is committed, the orchestrator dispatches a fresh Verifier sub-agent automatically - regardless of phase count. Validation never requires a user prompt; it is the closing step of Execute. **Author ≠ verifier**: the Verifier re-derives coverage independently using evidence-or-zero; it does not inherit the author's mental model. The Verifier: (1) performs a **spec-anchored outcome check** - confirms each test's asserted value matches the spec-defined expected outcome, flags spec-precision gaps; (2) runs a **discrimination sensor** - injects behavior-level faults in an isolated scratch (temp worktree or file copies - never `git stash`), confirms tests kill them, discards the scratch and verifies real-tree porcelain matches the pre-sensor baseline; surviving mutants become fix tasks; (3) writes `.specs/features/[feature]/validation.md` (PASS/FAIL, per-AC evidence, sensor result, diff range); (4) returns a compact verdict + ranked gap list to the orchestrator in chat. Gaps become fix tasks; the fix→re-verify loop is bounded to 3 iterations before escalating. (5) **distills lessons** - turns each grounded failure (surviving mutant, spec-precision gap, failed AC, SPEC_DEVIATION) into a reusable project-local lesson via `<skill-dir>/scripts/lessons.py`; a clean PASS records nothing (see [lessons.md](references/lessons.md)).
+
+**Model tier per role (only if the harness supports choosing a model per sub-agent).** Match the reasoning cost to the work instead of paying top-tier reasoning for boilerplate. A batch worker on a mechanical, low-ambiguity phase (entities, config, wiring, straightforward CRUD) runs on a faster/cheaper tier; a worker on a core-domain or high-ambiguity phase, and the Design phase itself, runs on a high-reasoning tier; the Verifier runs on a mid-to-high tier because it does adversarial reasoning and designs mutations. This is a portable recommendation: if the harness cannot set a per-sub-agent model, ignore it. Full rubric in [sub-agents.md](references/sub-agents.md).
+
+**Standalone fallback:** Without sub-agents, run `validate.md` as an independent fresh-eyes pass after the final commit - including the spec-anchored check and discrimination sensor.
+
+Full mechanics (worker payload, compact summary format, failure handling, context sizing, model tier, Verifier report format): [sub-agents.md](references/sub-agents.md).
+
+## Commands
+
+**Feature-level (auto-sized):**
+| Trigger Pattern | Reference |
+|----------------|-----------|
+| Specify feature, define requirements | [specify.md](references/specify.md) |
+| Discuss feature, capture context, how should this work | [discuss.md](references/discuss.md) |
+| Design feature, architecture | [design.md](references/design.md) |
+| Break into tasks, create tasks | [tasks.md](references/tasks.md) |
+| Implement task, build, execute | [implement.md](references/implement.md) |
+| Validate, verify, test, UAT, walk me through it | [validate.md](references/validate.md) |
+
+**Memory:**
+| Trigger Pattern | Reference |
+|----------------|-----------|
+| Record decision, this is a project-level decision | [memory.md](references/memory.md) |
+| Pause work, end session, I need to stop | [memory.md](references/memory.md) |
+| Resume work, continue, pick up where we left off | [memory.md](references/memory.md) |
+| Load lessons, what have we learned, apply past lessons | [lessons.md](references/lessons.md) |
+| Record lesson, distill lessons (auto-runs after validation) | [lessons.md](references/lessons.md) |
+
+## Knowledge Verification Chain
+
+When researching, designing, or making any technical decision, follow this chain in strict order. Never skip steps.
+
+```
+Step 1: Codebase → check existing code, conventions, and patterns already in use
+Step 2: Project docs → README, docs/, inline comments, `.specs/STATE.md` (Decisions)
+Step 3: Context7 MCP → resolve library ID, then query for current API/patterns
+Step 4: Web search → official docs, reputable sources, community patterns
+Step 5: Flag as uncertain → "I'm not certain about X - here's my reasoning, but verify"
+```
+
+**Rules:**
+
+- Never skip to Step 5 if Steps 1-4 are available
+- Step 5 is ALWAYS flagged as uncertain - never presented as fact
+- **NEVER assume or fabricate.** If you cannot find an answer, say "I don't know" or "I couldn't find documentation for this". Inventing APIs, patterns, or behaviors causes cascading failures across design → tasks → implementation. Uncertainty is always preferable to fabrication.
+
+## Output Behavior
+
+**Do the work; do not narrate the machinery.** Produce the right artifact for the phase instead of announcing the phase ("I will now run the Specify phase"). The user judges the output, not a play-by-play of the process. This keeps the flow from reading as robotic.
+
+**Match effort to the work.** Lightweight steps (feature-level checks, validation, mechanical tasks) do not need top-tier reasoning; heavy steps (complex design, ambiguous features) do. If the harness lets you pick a model per sub-agent, apply the tier rubric in [sub-agents.md](references/sub-agents.md); otherwise proceed and simply invest more care on the heavy steps. Mention this once per session at most, and only if it helps; skip it for an experienced user.
+
+**Write generated artifacts in a plain, decided voice.** Specs, ADRs, validation reports, commit messages, and chat summaries follow the writing rules in [coding-principles.md](references/coding-principles.md): lead with the verdict, state decisions definitively, cut filler and mechanical hedging.
+
+## Code Analysis
+
+Use available tools with graceful degradation. See [code-analysis.md](references/code-analysis.md).

package/framework/skills/tlc-spec-driven/examples.md

@@ -0,0 +1,34 @@
+# TLC Spec-Driven Examples
+
+## Specify and implement a small feature
+
+User: "Specify feature: add a 'last seen' timestamp to the profile page."
+
+Good agent behavior:
+
+- Auto-size the work: a ≤3 file change gets a one-line inline spec and skips Design and Tasks.
+- Execute always starts by listing atomic steps inline, and escalates to a formal `tasks.md` only if that listing reveals more than ~5 steps.
+- Derive tests from the spec's acceptance criteria, not the implementation.
+- Make one atomic Conventional Commit per task, with the task marked complete before the commit.
+
+## Full workflow on a complex feature
+
+User: "Specify feature: credit-based usage billing with metering and invoicing."
+
+Good agent behavior:
+
+- Run the full Specify → Design → Tasks → Execute cycle with requirement IDs in EARS notation.
+- Trigger discuss for gray areas (refunds, proration) and write decisions to `context.md`.
+- Run `validate_spec.py` and `validate_tasks.py` before confirming artifacts, and `check_commit.py` on each commit.
+- Offer sub-agents for batches over ~8 tasks, then let the orchestrator dispatch a fresh Verifier after the final commit.
+- Write the Verifier's `validation.md` with per-AC evidence and the discrimination sensor result.
+
+## Resume work
+
+User: "Resume work."
+
+Good agent behavior:
+
+- Read `.specs/STATE.md` and reconcile the Handoff against git (`branch`, `status --porcelain`, recent commits) and `tasks.md`.
+- Let evidence win over a stale snapshot when they disagree.
+- Propose the reconciled next step before writing any code.

package/framework/skills/tlc-spec-driven/references/code-analysis.md

@@ -0,0 +1,98 @@
+# Code Analysis Tools
+
+Use graceful degradation for code search and structural analysis.
+
+## Tool Priority
+
+1. **ast-grep** (`sg`) - Structural pattern-based search
+2. **ripgrep** (`rg`) - Fast context-aware text search
+3. **grep** - Standard text search (always available)
+
+## Detection
+
+Check tool availability before use:
+
+```bash
+# Check for ast-grep
+if command -v sg >/dev/null 2>&1; then
+  # Use ast-grep for structural search
+elif command -v rg >/dev/null 2>&1; then
+  # Fall back to ripgrep
+else
+  # Use standard grep as final fallback
+fi
+```
+
+## Usage Examples
+
+**Finding function definitions:**
+
+```bash
+# ast-grep (best - structural)
+sg -p 'function $NAME($$$) { $$$ }'
+
+# ripgrep (fallback - fast text)
+rg '^function\s+\w+\(' --type-add 'source:*.[extension]' -t source
+
+# grep (last resort - basic)
+grep -r '^function ' --include="*.[extension]"
+```
+
+**Finding imports/requires:**
+
+```bash
+# ast-grep
+sg -p 'import { $$$ } from "$MODULE"'
+
+# ripgrep
+rg '^import .* from' --type-add 'source:*.[extension]' -t source
+
+# grep
+grep -r '^import ' --include="*.[extension]"
+```
+
+**Finding class/component definitions:**
+
+```bash
+# ast-grep
+sg -p 'class $NAME { $$$ }'
+
+# ripgrep
+rg '^(class|export class)\s+\w+' --type-add 'source:*.[extension]' -t source
+
+# grep
+grep -r '^class ' --include="*.[extension]"
+```
+
+## Search Scope
+
+**Best practices:**
+
+- Limit to source file extensions relevant to project
+- Exclude directories: `node_modules`, `vendor`, `dist`, `build`, `.git`
+- Focus on source directories: `src`, `lib`, `app`
+- Use file type filters when available
+
+**Performance tips:**
+
+- Use specific patterns over broad searches
+- Limit directory depth with `--max-depth` (ripgrep/grep)
+- Cache results for repeated queries
+
+## Fallback Notice
+
+If ast-grep unavailable, display once per session:
+
+```
+⚠️ ast-grep not detected. Install for more precise structural code analysis.
+   https://ast-grep.github.io/guide/quick-start.html
+```
+
+## When to Use
+
+- Finding usage patterns across codebase
+- Identifying code structure and organization
+- Locating function/class/component definitions
+- Analyzing import/dependency patterns
+- Refactoring impact analysis
+- Code navigation in unfamiliar codebases

package/framework/skills/tlc-spec-driven/references/coding-principles.md

@@ -0,0 +1,72 @@
+# Coding Principles
+
+Behavioral bias, not checklist. Read before every implementation.
+
+---
+
+## Before Coding
+
+- State assumptions explicitly. If uncertain, ask.
+- Multiple interpretations exist? Present all-don't pick silently.
+- Simpler approach exists? Say so. Push back when warranted.
+- Something unclear? Stop. Name what's confusing. Ask.
+- User's approach seems wrong? Disagree honestly. Don't be sycophantic.
+
+---
+
+## During Implementation
+
+### Simplicity
+
+- No features beyond what was asked
+- No abstractions for single-use code
+- No "flexibility" or "configurability" not requested
+- No error handling for impossible scenarios
+- 200 lines that could be 50? Rewrite it.
+
+### Surgical Changes
+
+- Don't "improve" adjacent code, comments, or formatting
+- Don't refactor things that aren't broken
+- Match existing style, even if you'd do differently
+- Unrelated dead code noticed? Mention it-don't delete it
+- Remove ONLY imports/variables/functions YOUR changes orphaned
+- Don't remove pre-existing dead code unless asked
+
+### Test Integrity
+
+- NEVER weaken an existing test assertion to make it pass
+- NEVER delete a test to reduce failure count
+- NEVER use the test framework's skip/disable/pending mechanism to bypass a failing test
+- NEVER modify a task's tests afterward to make the implementation pass
+- If a test is genuinely wrong, STOP and confirm with the user before changing it
+- Tests are the spec - implementation conforms to tests, not the other way around
+
+### Goal-Driven
+
+- Transform vague tasks into verifiable goals
+- Multi-step work? State brief plan with verify checkpoints
+- Every changed line must trace directly to user's request
+
+---
+
+## After Each Change
+
+Ask: "Would senior engineer call this overcomplicated?"
+If yes → simplify before proceeding.
+
+---
+
+## Writing Voice (specs, ADRs, reports, commits, summaries)
+
+The artifacts this skill produces should read like a decided engineer wrote them, not like generated boilerplate.
+
+- **Lead with the verdict.** Validation reports and chat summaries open with PASS/FAIL and the one thing that matters, not a warm-up paragraph.
+- **Decisions are definitive.** An ADR or a recorded decision states what you chose: "we will", not "we might" or "we should probably". If it still hedges, it is not a decision yet.
+- **Cut filler and mechanical hedging.** Drop "it is worth noting", "as you can see", "in order to", and reflexive "may/might/could" on claims you are actually sure about. Reserve hedging for genuine uncertainty; using it everywhere signals nothing.
+- **One idea per sentence; short sentences.** Prefer the plain verb over the nominalization ("evaluated", not "performed an evaluation of"). Keep subject-verb-object near the front.
+- **Do not announce the phase.** Produce the artifact; do not narrate "I will now run Specify."
+- **Avoid the em dash as a default connector.** A comma, colon, or two sentences usually read cleaner.
+- **Writing in Portuguese:** keep sentences short; do not carry the long, multi-clause subordinate structure of Portuguese into the artifact. Plain and direct beats formal.
+
+None of this means dumbing down the content - only the prose carrying it.

package/framework/skills/tlc-spec-driven/references/context-limits.md

@@ -0,0 +1,31 @@
+# Context Limits
+
+## File Size Limits
+
+| File      | Max Tokens | ~Words | Warning At |
+| --------- | ---------- | ------ | ---------- |
+| spec.md   | 5,000      | 3,000  | 4,000      |
+| design.md | 8,000      | 4,800  | 6,400      |
+| tasks.md  | 10,000     | 6,000  | 8,000      |
+
+## Context Zones
+
+🟢 **Healthy** (<40k total): Silent
+🟡 **Moderate** (40-60k): Discrete footer note
+🔴 **Critical** (>60k): Active warning, suggest optimization
+
+## Monitoring
+
+Display context status in footer when >40k:
+
+```
+📊 Context: 52k tokens (moderate)
+  - tasks.md: 11k (ok)
+  - design.md: 6k (ok)
+  - Total: 52k / 200k (26%)
+```
+
+## Principles
+
+**Target:** <40k tokens loaded (20% of window)
+**Reserve:** 160k+ tokens for work, reasoning, outputs

package/framework/skills/tlc-spec-driven/references/design.md

@@ -0,0 +1,199 @@
+# Design
+
+**Goal**: Define HOW to build it. Architecture, components, what to reuse.
+
+**Skip this phase when:** The change is straightforward - no architectural decisions, no new patterns, no component interactions to plan. For simple features, design happens inline during Execute.
+
+## Process
+
+### 1. Load Context
+
+Read `.specs/features/[feature]/spec.md` before designing. If `.specs/features/[feature]/context.md` exists, load it too - it contains implementation decisions that constrain the design (layout choices, behavior preferences, interaction patterns). Decisions marked as "Agent's Discretion" are yours to decide.
+
+**Mandatory: read `.specs/STATE.md` `## Decisions` now.** This MUST happen before any architectural choices are made. Every `active` `AD-NNN` entry is a project-level constraint this design must conform to. If a decision from a prior feature conflicts with what is best for this feature, you have two options - both require an explicit choice:
+
+1. **Conform** - Design within the active constraint.
+2. **Supersede** - Append a new `AD-NNN` entry to `.specs/STATE.md` `## Decisions` that supersedes the old one (set the old entry's `status` to `superseded by AD-NNN`) and document the reason. The new decision becomes the project standard going forward.
+
+Silently ignoring an active decision is not an option - it creates invisible inconsistency across features.
+
+**Also load confirmed lessons** relevant to this feature: `python3 <skill-dir>/scripts/lessons.py list --status confirmed` (filter with `--scope`/`--query`). These are past verification failures distilled into guidance - apply them while designing. Load only `confirmed`. Skip silently if no store or no code tool. See [lessons.md](lessons.md).
+
+### 1.5. Research (Optional but Recommended)
+
+If the feature involves unfamiliar technology, patterns, or integrations, research before designing. Document findings briefly in the design doc or as inline notes. This prevents incorrect assumptions from propagating into tasks.
+
+Follow the **Knowledge Verification Chain** (see SKILL.md) in strict order:
+
+```
+Codebase → Project docs → Context7 MCP → Web search → Flag as uncertain
+```
+
+**CRITICAL: NEVER assume or fabricate information.** If you cannot find an answer through the chain, explicitly say "I don't know" or "I couldn't find documentation for this". Inventing an API, a pattern, or a behavior that doesn't exist is far worse than admitting uncertainty. Wrong assumptions propagate through design → tasks → implementation and cause cascading failures.
+
+Good triggers for research: new libraries, unfamiliar APIs, performance-sensitive features, security-sensitive features, patterns you haven't used in this codebase before.
+
+**Concern flagging (MUST do while reading code):** While walking the codebase via the Knowledge Verification Chain, flag any concerns you encounter in the areas this feature touches. Capture each finding in the `## Risks & Concerns` section of `design.md`:
+
+- **Fragile code** - tight coupling, large functions, implicit state
+- **Tech debt** - hacks, workarounds, deprecated APIs
+- **Security risks** - unvalidated input, auth gaps, exposed secrets
+- **Performance bottlenecks** - N+1 queries, unbounded loops, missing indexes
+- **Test coverage gaps** - untested paths the feature depends on
+
+Every flagged concern MUST include a mitigation - how the design (or a follow-up task) addresses it.
+
+### 2. Define Architecture
+
+**Large/Complex only - approach exploration:** Before committing to a single architecture, present 2-3 viable approaches with trade-offs and a recommendation. Lead with the recommendation to avoid analysis paralysis. All approaches must deliver the same scoped thing (no alternative scopes). Confirm the chosen approach with the user before detailing components. Medium features: skip - design inline.
+
+Overview of how components interact. Use mermaid diagrams when helpful.
+
+### 3. Identify Code Reuse
+
+**CRITICAL**: What existing code can we leverage? This saves tokens and reduces errors.
+
+Flag any concerns found here per step 1.5 into `## Risks & Concerns`.
+
+### 4. Define Components and Interfaces
+
+Each component: Purpose, Location, Interfaces, Dependencies, What it reuses.
+
+### 5. Define Data Models
+
+If the feature involves data, define models before implementation.
+
+---
+
+## Template: `.specs/features/[feature]/design.md`
+
+````markdown
+# [Feature] Design
+
+**Spec**: `.specs/features/[feature]/spec.md`
+**Status**: Draft | Approved
+
+---
+
+## Architecture Overview
+
+[Brief description of the architecture approach]
+
+```mermaid
+graph TD
+    A[User Action] --> B[Component A]
+    B --> C[Service Layer]
+    C --> D[Data Store]
+    B --> E[Component B]
+```
+````
+
+---
+
+## Code Reuse Analysis
+
+### Existing Components to Leverage
+
+| Component            | Location            | How to Use                |
+| -------------------- | ------------------- | ------------------------- |
+| [Existing Component] | `src/path/to/file`  | [Extend/Import/Reference] |
+| [Existing Utility]   | `src/utils/file`    | [How it helps]            |
+| [Existing Pattern]   | `src/patterns/file` | [Apply same pattern]      |
+
+### Integration Points
+
+| System         | Integration Method                      |
+| -------------- | --------------------------------------- |
+| [Existing API] | [How new feature connects]              |
+| [Database]     | [How data connects to existing schemas] |
+
+---
+
+## Components
+
+### [Component Name]
+
+- **Purpose**: [What this component does - one sentence]
+- **Location**: `src/path/to/component/`
+- **Interfaces**:
+  - `methodName(param: Type): ReturnType` - [description]
+  - `methodName(param: Type): ReturnType` - [description]
+- **Dependencies**: [What it needs to function]
+- **Reuses**: [Existing code this builds upon]
+
+### [Component Name]
+
+- **Purpose**: [What this component does]
+- **Location**: `src/path/to/component/`
+- **Interfaces**:
+  - `methodName(param: Type): ReturnType`
+- **Dependencies**: [Dependencies]
+- **Reuses**: [Existing code]
+
+---
+
+## Data Models (if applicable)
+
+### [Model Name]
+
+```typescript
+interface ModelName {
+  id: string
+  field1: string
+  field2: number
+  createdAt: Date
+}
+```
+
+**Relationships**: [How this relates to other models]
+
+### [Model Name]
+
+```typescript
+interface AnotherModel {
+  id: string
+  // ...
+}
+```
+
+---
+
+## Error Handling Strategy
+
+| Error Scenario | Handling      | User Impact      |
+| -------------- | ------------- | ---------------- |
+| [Scenario 1]   | [How handled] | [What user sees] |
+| [Scenario 2]   | [How handled] | [What user sees] |
+
+---
+
+## Risks & Concerns
+
+| Concern | Location (file:line) | Impact | Mitigation |
+| ------- | -------------------- | ------ | ---------- |
+| [Fragile code / tech debt / security / perf / test gap] | `src/path/file.ts:42` | [What breaks or degrades] | [How the design or a follow-up task addresses it] |
+
+> None found - is a valid entry.
+
+---
+
+## Tech Decisions (only non-obvious ones)
+
+| Decision          | Choice          | Rationale     |
+| ----------------- | --------------- | ------------- |
+| [What we decided] | [What we chose] | [Why - brief] |
+
+> **Project-level decisions:** If a decision here sets a convention, pattern, or constraint that future features must follow, append it to `.specs/STATE.md` `## Decisions` as the next `AD-NNN` entry (see [memory.md](memory.md)). Feature-local decisions stay only in this table.
+
+---
+
+## Tips
+
+- **Load context first** - If context.md exists, decisions there are locked
+- **Research when uncertain** - 5 minutes of research prevents hours of rework
+- **Reuse is king** - Every component should reference existing patterns
+- **Interfaces first** - Define contracts before implementation
+- **Keep it visual** - Diagrams save 1000 words
+- **Small components** - If component does 3+ things, split it
+- **Flag concerns inline** - Risks found during research go in Risks & Concerns with a mitigation
+- **Confirm before Tasks** - User approves design before breaking into tasks