tmux-agent 0.1.0

package/.codex/skills/speckit/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: speckit
+description: In repositories that use `.specify/` + `specs/` (Spec Kit / Spec-Driven Development), use `$speckit <stage>` as a single stage router to write back key decisions into spec-kit artifacts (`spec.md`, `plan.md`, `tasks.md`, `checklists/*`, `.specify/memory/constitution.md`). Trigger only when the user makes an explicit decision/change; stay silent for casual chat/brainstorming.
+---
+
+# speckit (Stage Router)
+
+Goal: Drive a Spec-Driven workflow with one skill, treat spec artifacts as an executable single source of truth (spec → plan → tasks → implement), and write back key decisions promptly to avoid drift between code and specs.
+
+## When to trigger / when to stay silent
+
+Trigger (the user made an explicit decision/change that impacts artifacts):
+
+- Tech stack / architecture changes → usually run `clarify` first, then `plan`
+- Feature requirements added/removed/changed → `specify`
+- Principles / governance / quality gates changed → `constitution`
+- Ambiguity blocks implementation → `clarify` (write back to spec)
+- An external review produced `review.md` (plan review) → `review-plan`
+- Ingest an external review report into `plan.md` / `tasks.md` → `plan-from-review`
+- Ingest a question list (without `review.md`) into planning/tasks → `plan-from-questions`
+- Task decomposition/order/parallelization needs reshaping → `tasks`
+- Multi-spec coordination (Spec Group: one spec dispatches multiple specs) → `group`
+- Pre-implementation consistency check (read-only) → `analyze`
+- Generate a domain checklist (security/ux/api/performance/...) → `checklist`
+- Enter implementation and check tasks off → `implement`
+- Long exploration / context may be compacted: flush handoff notes → `notes`
+- Post-implementation acceptance & drift assessment (FR/NFR/SC) → `acceptance`
+- Implement only a specific TaskID / next task (task-driven, minimal context) → `implement-task`
+- Sync tasks to an issue tracker → `taskstoissues`
+
+Stay silent (do not auto-trigger):
+
+- Casual chat / brainstorming without a decision
+- Explaining concepts / answering questions without asking to update spec-kit artifacts
+
+## How it works (router + bundled resources)
+
+- Router: `$speckit <stage> ...` selects and executes the stage reference prompt.
+- Bundled resources: stage prompts, scripts, and templates live in this skill to keep the workflow stable and reusable.
+
+## Usage
+
+- Invocation: `$speckit <stage> <text...>`
+- `<stage>` must be one of:
+  - `constitution`
+  - `specify`
+  - `clarify`
+  - `clarify-auto`
+  - `clarify-detailed`
+  - `plan`
+  - `plan-deep`
+  - `review-plan`
+  - `plan-from-review`
+  - `plan-from-questions`
+  - `group`
+  - `tasks`
+  - `analyze`
+  - `checklist`
+  - `notes`
+  - `implement`
+  - `acceptance`
+  - `implement-task`
+  - `taskstoissues`
+
+If `<stage>` is missing or invalid: stop and ask the user to pick one from the list.
+
+## Optional: Specs Kanban
+
+An optional local Kanban to browse and drive `specs/*`:
+
+- Recommended: run as a standalone tool: `npx speckit-kit kanban`
+  - Set repo root: `npx speckit-kit kanban --repo-root /path/to/repo`
+  - Or env var: `SPECKIT_KIT_REPO_ROOT=/path/to/repo npx speckit-kit kanban`
+
+Note: the Kanban is shipped as an npm CLI package: `speckit-kit`.
+
+## Feature selection (recommended)
+
+Avoid accidentally targeting the “latest” spec; pick a feature explicitly:
+
+- Recommended: place the feature id as the first token after `<stage>`: `$speckit plan 025 ...`
+- Explicit env override: include `SPECIFY_FEATURE=025` (or `SPECIFY_FEATURE=025-my-feature`)
+- Alias forms: `feature=025` / `spec=025` / `feat=025` / `id=025` (normalized to `SPECIFY_FEATURE=...`)
+- Multi-spec acceptance: `acceptance` supports multiple ids: `$speckit acceptance 026 027`
+
+## Core workflow and artifact boundaries
+
+- Trigger form: users trigger by calling `$speckit <stage>` (slash commands are treated as aliases).
+- Recommended main flow: `constitution` → `specify` → `clarify` → `plan` → `tasks` → `implement`
+  - You can insert `notes` anywhere for a manual flush.
+  - You can insert `checklist` / `analyze` before implementation for convergence.
+- Recommended closure: run `acceptance` after `implement` to evaluate drift against coded points in `spec.md`.
+- Artifact boundaries:
+  - `constitution`: project principles and governance (global constraints)
+  - `specify`: requirements and success criteria (WHAT/WHY, not HOW)
+  - `clarify`: remove ambiguity and fill gaps (eliminate `[NEEDS CLARIFICATION]`)
+  - `plan`: technical/architecture plan (HOW at the macro level; details can live in sub-docs)
+  - `tasks`: executable task breakdown (order/dependencies/parallel markers/checkpoints)
+  - `implement`: implement from `tasks.md` and keep checking progress; write back to specs if needed
+- Feature context: feature id is `001-xxx`, mapping to `specs/<feature-id>/...`; scripts read `SPECIFY_FEATURE`, then infer from CWD, then fall back to the highest number under `specs/`.
+
+## Routing rules (avoid semantic drift)
+
+0. Derive `SKILL_DIR`: from the injected `SKILL.md` absolute path: `SKILL_DIR = dirname(path)`.
+   - Important: `SKILL_DIR/...` is a placeholder in docs; shell commands must use the actual absolute path.
+1. Parse from the user message:
+   - `stage`: the first token after `$speckit`
+   - `stage_args`: the remaining text (may be empty)
+   - If `stage_args` contains `SPECIFY_FEATURE=<id>`: treat it as the feature override; strip it from `stage_args`.
+   - If the first token of `stage_args` matches `026` or `026-xxx`: treat it as feature id and normalize to `SPECIFY_FEATURE=<token>`.
+   - If `stage_args` contains `feature=<id>` / `spec=<id>` / `feat=<id>` / `id=<id>`: treat it as feature id and normalize.
+   - If multiple forms are present, prefer explicit `SPECIFY_FEATURE=`.
+2. Before doing any action, read and follow `SKILL_DIR/references/<stage>.md` as authoritative.
+3. Execute strictly per `references/<stage>.md`; do not re-implement a “similar” flow in this file.
+4. In stage references, `$ARGUMENTS` means `stage_args`.
+
+## Stage reference mapping (authoritative)
+
+- `constitution` → `SKILL_DIR/references/constitution.md`
+- `specify` → `SKILL_DIR/references/specify.md`
+- `clarify` → `SKILL_DIR/references/clarify.md`
+- `clarify-auto` → `SKILL_DIR/references/clarify-auto.md`
+- `clarify-detailed` → `SKILL_DIR/references/clarify-detailed.md`
+- `plan` → `SKILL_DIR/references/plan.md`
+- `plan-deep` → `SKILL_DIR/references/plan-deep.md`
+- `review-plan` → `SKILL_DIR/references/review-plan.md`
+- `plan-from-review` → `SKILL_DIR/references/plan-from-review.md`
+- `plan-from-questions` → `SKILL_DIR/references/plan-from-questions.md`
+- `group` → `SKILL_DIR/references/group.md`
+- `tasks` → `SKILL_DIR/references/tasks.md`
+- `analyze` → `SKILL_DIR/references/analyze.md`
+- `checklist` → `SKILL_DIR/references/checklist.md`
+- `notes` → `SKILL_DIR/references/notes.md`
+- `implement` → `SKILL_DIR/references/implement.md`
+- `acceptance` → `SKILL_DIR/references/acceptance.md`
+- `implement-task` → `SKILL_DIR/references/implement-task.md`
+- `taskstoissues` → `SKILL_DIR/references/taskstoissues.md`
+
+Treat `references/<stage>.md` as the stage’s authoritative prompt:
+
+- Do not write a second “equivalent” flow in this file.
+- If a reference instruction does not match the real repo (missing scripts/paths), make the smallest fix and document the delta for prompt debugging.
+
+## Bundled resources
+
+- Stage prompts: `references/*.md`
+- Scripts: `scripts/bash/*.sh`
+- Templates: `assets/templates/*.md`
+
+Notes:
+
+- Repo root inference: scripts walk up from CWD to find `.specify/` or `specs/`, then fall back to git root/current directory; by default they operate on the repo you are currently in.
+- Templates: scripts prefer this skill’s templates (`assets/templates/*`); they do not depend on repo-local `.specify/templates/*`.
+- Feature inference: scripts do not depend on Git branches; prefer `SPECIFY_FEATURE`, then infer from CWD, then fall back to the highest number under `specs/`.
+- No VCS operations: scripts do not run `git checkout` / `git commit` or any history operation.
+- Script reading convention: do not read script source just to “see what it does”; treat scripts as controlled assets and run them with `--json`. Read source only when you need to modify or debug behavior.
+- Shell command conventions:
+  - Recommended: run scripts via absolute paths and quote them: `"<SKILL_DIR>/scripts/bash/check-prerequisites.sh" ...`
+  - If you need an env var in the same command: assign first, then use it: `SKILL_DIR="..."; "$SKILL_DIR/scripts/bash/check-prerequisites.sh" ...`
+  - Avoid: `SKILL_DIR="..." $SKILL_DIR/scripts/...` (shell expands `$SKILL_DIR` before assignment).
+
+## Script capabilities (no need to read source)
+
+- `scripts/bash/create-new-feature.sh`: create `specs/<NNN-*>/spec.md` (copy template or create empty), output JSON with `BRANCH_NAME` and `SPEC_FILE`; no VCS operations.
+- `scripts/bash/setup-plan.sh`: ensure `specs/<feature>/plan.md` exists (no overwrite unless `--force`), output JSON with `FEATURE_SPEC` and `IMPL_PLAN`.
+- `scripts/bash/setup-notes.sh`: ensure `specs/<feature>/notes/` skeleton exists (no overwrite unless `--force`), output JSON with `NOTES_DIR` / `NOTES_README` / `SESSIONS_DIR`; supports `--dry-run`.
+- `scripts/bash/check-prerequisites.sh`: check required files for the current feature and output JSON (optionally require `tasks.md`); read-only.
+- `scripts/bash/extract-user-stories.sh`: extract `User Story N` list from `spec.md` (with Priority + file+line evidence); supports `--json`; read-only.
+- `scripts/bash/extract-coded-points.sh`: extract coded points (FR/NFR/SC) from one or more `spec.md` files (with file+line evidence); supports `--json`; read-only.
+- `scripts/bash/extract-tasks.sh`: extract task list and completion status from one or more `tasks.md` files (with file+line evidence); supports `--json`; read-only.
+- `scripts/bash/extract-spec-ids.sh`: aggregate id registries (`us/codes/tasks`), supports `--kind/--kinds` + `--json`; read-only.
+- `scripts/bash/show-todo-tasks.sh`: summarize remaining tasks across `specs/*` (or expand by `--feature` / multiple ids), supports `--json`; read-only.
+- All scripts support `--feature 029` to target a spec; `setup-plan.sh` and `check-prerequisites.sh` also accept positional `029` / `029-xxx`.

package/.codex/skills/speckit/assets/templates/checklist-template.md

@@ -0,0 +1,49 @@
+# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
+
+**Purpose**: [Brief description of what this checklist covers]
+**Created**: [DATE]
+**Feature**: [Link to spec.md or relevant documentation]
+
+**Note**: This checklist is generated by the `$speckit checklist` stage based on feature context and requirements.
+
+<!--
+  ============================================================================
+  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
+
+  The $speckit checklist stage MUST replace these with actual items based on:
+  - User's specific checklist request
+  - Feature requirements from spec.md
+  - Technical context from plan.md
+  - Implementation details from tasks.md
+
+  DO NOT keep these sample items in the generated checklist file.
+  ============================================================================
+-->
+
+## [Category 1]
+
+- [ ] CHK001 First checklist item with clear action
+- [ ] CHK002 Second checklist item
+- [ ] CHK003 Third checklist item
+
+## [Category 2]
+
+- [ ] CHK004 Another category item
+- [ ] CHK005 Item with specific criteria
+- [ ] CHK006 Final item in this category
+
+## Performance & Observability _(if applicable)_
+
+- [ ] CHK0XX Performance budget + baseline measurement recorded (env/tool documented)
+- [ ] CHK0XX No critical regression (or justified in Complexity Tracking)
+- [ ] CHK0XX Logs/metrics/traces updated for key flows; PII/overhead reviewed
+- [ ] CHK0XX Diagnostics include stable identifiers to correlate requests/sessions/entities
+- [ ] CHK0XX Data consistency boundaries documented (transaction/atomicity/ordering as applicable)
+- [ ] CHK0XX Breaking change declared and migration note linked (per project policy)
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference

package/.codex/skills/speckit/assets/templates/notes-entrypoints-template.md

@@ -0,0 +1,11 @@
+# Entry Points
+
+## Specs (SSoT)
+
+- `../spec.md`
+- `../plan.md`
+- `../tasks.md` (if present)
+
+## Code Entry Points (Files / Symbols)
+
+- `<path>:<line>` — <why it matters / how to enter>

package/.codex/skills/speckit/assets/templates/notes-questions-template.md

@@ -0,0 +1,7 @@
+# Questions
+
+## Q1
+
+- Question:
+- Impact:
+- Decision needed:

package/.codex/skills/speckit/assets/templates/notes-readme-template.md

@@ -0,0 +1,36 @@
+# Notes (Working Memory)
+
+## Scope
+
+- <What this notes folder covers / does not cover>
+
+## Entry Points
+
+- `entrypoints.md`
+
+## Current Status
+
+- Focus: <one line>
+- Phase:
+  - [ ] Rehydrate / Align
+  - [ ] Explore / Locate
+  - [ ] Decide / Sync SSoT
+  - [ ] Implement / Verify
+
+## Current Hypothesis
+
+- <1–5 items>
+
+## Errors Encountered
+
+- <time> — <symptom> → <fix/mitigation> (link the session if any)
+
+## Next Actions
+
+- <concrete next changes + how to validate>
+
+## Last Flush
+
+- At: <YYYY-MM-DD HH:mm>
+- Intent: <this run's $ARGUMENTS>
+- Session: `sessions/<YYYY-MM-DD>.md` (if any)

package/.codex/skills/speckit/assets/templates/notes-session-template.md

@@ -0,0 +1,21 @@
+# Session: <YYYY-MM-DD>
+
+## Intent
+
+- <this run's $ARGUMENTS>
+
+## What Changed
+
+- <files/symbols/changes (index only)>
+
+## Findings
+
+- <conclusions / evidence / counterexamples>
+
+## Errors (Failure Traces)
+
+- <time> — <error/symptom> → <fix/mitigation> → <synced back to SSoT?>
+
+## Next Actions
+
+- <concrete next changes + how to validate>

package/.codex/skills/speckit/assets/templates/plan-template.md

@@ -0,0 +1,126 @@
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+
+**Note**: This template is copied into `specs/[###-feature-name]/plan.md` by the
+Speckit plan workflow (`setup-plan.sh`).
+
+## Summary
+
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., React, Next.js, FastAPI, Postgres, Redis or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., files / N/A]  
+**Testing**: [e.g., Vitest, Jest, Pytest, Go test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Node.js 20+, browsers, iOS/Android]  
+**Project Type**: [single repo / monorepo / packages + apps]  
+**Performance Goals**: [budgets + measurement method (benchmark/profile) or NEEDS CLARIFICATION]  
+**Constraints**: [include diagnostics overhead budgets if applicable]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Constitution Check
+
+_GATE: Must pass before implementation. Re-check after Phase 1 design._
+
+- Answer the following BEFORE starting implementation, and re-check after Phase 1:
+  - What user value is delivered, and how is it validated (acceptance scenarios / SC-*)?
+  - What public/external surfaces change (API/CLI/UI/config), and what is the compatibility policy?
+  - What docs/specs must be updated first (docs-first where applicable) to avoid drift?
+  - What are the key risks (security, data loss, privacy, performance) and mitigations?
+  - If performance-sensitive: what budgets/baselines exist, and how are regressions prevented?
+  - What diagnostics/observability signals are required for triage (logs/metrics/traces)?
+  - What quality gates will be run before merge (typecheck / lint / test / build), and what counts as “pass”?
+
+## Perf Evidence Plan (IF APPLICABLE)
+
+> If this feature touches performance-sensitive paths or external performance boundaries: this section must be filled. Otherwise mark it as `N/A`.
+
+- Baseline semantics: before/after code change OR A/B strategy (choose one)
+- envId: <os-arch.cpu.runtime-version>
+- tool: <benchmark/profile tool name>
+- collect (before): `specs/<id>/perf/before.<envId>.<tag>.<ext>`
+- collect (after): `specs/<id>/perf/after.<envId>.<tag>.<ext>`
+- diff: `specs/<id>/perf/diff.before__after.<ext>` (if applicable)
+- Failure policy: if results are not comparable (env/tool changes, insufficient sample size, high variance) → re-run or narrow the scope; do not draw hard conclusions when not comparable.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file ($speckit plan output)
+├── research.md          # Phase 0 output ($speckit plan)
+├── data-model.md        # Phase 1 output ($speckit plan)
+├── quickstart.md        # Phase 1 output ($speckit plan)
+├── contracts/           # Phase 1 output ($speckit plan)
+├── notes/               # Optional: handoff notes / entry points ($speckit notes)
+└── tasks.md             # Phase 2 output ($speckit tasks - NOT created by $speckit plan)
+```
+
+### Source Code (repository root)
+
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```text
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation                  | Why Needed         | Simpler Alternative Rejected Because |
+| -------------------------- | ------------------ | ------------------------------------ |
+| [e.g., 4th project]        | [current need]     | [why 3 projects insufficient]        |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient]  |

package/.codex/skills/speckit/assets/templates/spec-template.md

@@ -0,0 +1,135 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`  
+**Created**: [DATE]  
+**Status**: Draft  
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing _(mandatory)_
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements _(mandatory)_
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+_Example of marking unclear requirements:_
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Non-Functional Requirements (Quality)
+
+<!--
+  If this feature is performance/scale sensitive:
+  - Define budgets (latency/throughput/memory/alloc) and how they are measured
+  - Define observability: logs/metrics/traces + failure triage signals
+-->
+
+- **NFR-001**: If performance-sensitive, system MUST define budgets for critical paths
+  and record a measurable baseline before implementation.
+- **NFR-002**: System MUST provide structured diagnostic signals (logs/metrics/traces)
+  for key flows, with a documented enable/disable cost model.
+- **NFR-003**: Identifiers used in diagnostics SHOULD be stable and searchable.
+- **NFR-004**: Error handling MUST be explicit for user-facing failures, and MUST include
+  a clear triage path (where to look, what to collect).
+- **NFR-005**: If this feature introduces breaking changes, the project MUST document
+  the change and migration steps (where applicable).
+
+### Key Entities _(include if feature involves data)_
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria _(mandatory)_
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
+- **SC-005**: [Performance metric, e.g., "No regression in p95 latency / allocations for [hot path]"]
+- **SC-006**: [Diagnosability metric, e.g., "Devtools can explain 'why' for [event] with causal chain"]