agent-tmux 0.1.0

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

@@ -0,0 +1,269 @@
+---
+
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/[###-feature-name]/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, notes/ (optional)
+
+**Tests**: The examples below include test tasks. Tests are OPTIONAL by default - only include
+them if explicitly requested in the feature specification, or if your project’s quality gates require
+tests for this change. If a change touches performance-sensitive paths, include performance regression
+defenses (baseline + guard) unless explicitly justified. If a change introduces breaking changes, include
+a migration note task (plan.md / PR) and follow the project’s compatibility policy (do not add “silent”
+compat layers unless they are explicitly planned).
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+<!--
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+
+  The $speckit tasks stage MUST replace these with actual tasks based on:
+  - User stories from spec.md (with their priorities P1, P2, P3...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+Examples of foundational tasks (adjust based on your project):
+
+- [ ] T004 Setup database schema and migrations framework
+- [ ] T005 [P] Implement authentication/authorization framework
+- [ ] T006 [P] Setup API routing and middleware structure
+- [ ] T007 Create base models/entities that all stories depend on
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T00X [P] Define unified minimal IR + drift prevention (docs/specs + parser/codegen)
+- [ ] T00X [P] Define deterministic identity model (instanceId/txnSeq/opId) and remove random/time defaults
+- [ ] T00X [P] Enforce transaction boundary (no IO in txn window, no writable ref escape hatches)
+- [ ] T00X [P] Define external reactive source integration: signal-dirty (pull-based), no render-level tearing (single snapshot anchor), and sharded notify to avoid O(N) selector work
+- [ ] T00X [P] Encapsulate internal hooks as explicit injectable contracts (Runtime Services); avoid magic fields / parameter explosion; document migration in specs/[###-feature]/plan.md
+- [ ] T00X [P] Normalize package public submodules: PascalCase `src/*.ts` (except `index.ts`/`global.d.ts`), move non-submodule code into `src/internal/**`, and keep `exports` from exposing internals
+- [ ] T00X [P] Decompose oversized modules/files (≥1000 LOC or expected to exceed): define a decomposition brief (mutually exclusive submodules), pick structure (flat `*.*.ts` vs directory), keep refactor semantics-preserving, and add incremental verification checkpoints
+- [ ] T00X [P] Add controlled trial-run harness (RunSession + Evidence/IR export) with schema validation; ensure parallel sessions are isolated
+- [ ] T00X [P] Define performance budget + baseline measurement approach (benchmark/profile)
+- [ ] T00X [P] Define diagnostic events/Devtools surfaces + expected overhead (enabled vs disabled)
+- [ ] T00X [P] Provide user-facing performance mental model (≤5 keywords, cost model, optimization ladder) and align terminology across docs/benchmarks/diagnostics
+- [ ] T009 Setup environment configuration management
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test\_[name].py
+- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test\_[name].py
+
+### Implementation for User Story 1
+
+- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T016 [US1] Add validation and error handling
+- [ ] T017 [US1] Add logging for user story 1 operations
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
+
+---
+
+## Phase 4: User Story 2 - [Title] (Priority: P2)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test\_[name].py
+- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test\_[name].py
+
+### Implementation for User Story 2
+
+- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - [Title] (Priority: P3)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test\_[name].py
+- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test\_[name].py
+
+### Implementation for User Story 3
+
+- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+[Add more user story phases as needed, following the same pattern]
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX Code cleanup and refactoring
+- [ ] TXXX Performance optimization across all stories
+- [ ] TXXX Performance regression guard (bench/profile baseline + CI-friendly check if applicable)
+- [ ] TXXX Diagnosability & explainability polish (events/trace/devtools UX + overhead validation)
+- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
+- [ ] TXXX Security hardening
+- [ ] TXXX Run quickstart.md validation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
+
+### Within Each User Story
+
+- Tests (if included) MUST be written and FAIL before implementation
+- Models before services
+- Services before endpoints
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- All Setup tasks marked [P] can run in parallel
+- All Foundational tasks marked [P] can run in parallel (within Phase 2)
+- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
+- All tests for a user story marked [P] can run in parallel
+- Models within a story marked [P] can run in parallel
+- Different user stories can be worked on in parallel by different team members
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all tests for User Story 1 together (if tests requested):
+Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
+Task: "Integration test for [user journey] in tests/integration/test_[name].py"
+
+# Launch all models for User Story 1 together:
+Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Create [Entity2] model in src/models/[entity2].py"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories
+
+### Parallel Team Strategy
+
+With multiple developers:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: User Story 1
+   - Developer B: User Story 2
+   - Developer C: User Story 3
+3. Stories complete and integrate independently
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Verify tests fail before implementing
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence

package/.codex/skills/speckit/references/acceptance.md

@@ -0,0 +1,183 @@
+---
+description: Perform a post-implementation acceptance review by validating every coded point in spec.md against the current codebase.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Run a “God View” acceptance pass **after implementation**: verify every coded point in `spec.md` (e.g., `FR-xxx`, `NFR-xxx`, `SC-xxx`) against the latest source code, and surface drift, conflicts, and missing coverage.
+
+## Operating Constraints
+
+- **Default to READ-ONLY**: do **not** modify any files unless the user explicitly asks.
+- **Parallel Work Safety (Non-Negotiable)**: Assume the working tree may contain unrelated, uncommitted changes from other parallel tasks.
+  - ABSOLUTELY PROHIBITED: any form of `git restore`, `git checkout -- <path>`, `git reset`, `git clean`, `git stash`.
+  - Avoid staging/committing/history rewriting unless explicitly requested by the user: `git add`, `git commit`, `git rebase`, `git merge`, `git cherry-pick`, `git push`.
+  - Read-only git commands are allowed (e.g., `git status`, `git diff`).
+- **Evidence-driven**: Do not mark an item as PASS without pointing to concrete evidence (file paths / symbols / tests / commands).
+- **Non-resident commands**: If unsure a command terminates, use `timeout 30s <command>` (or an equivalent one-shot invocation).
+
+## Execution Steps
+
+### 1) Initialize Context
+
+This stage supports validating **one or multiple** specs in a single run.
+
+**Target specs (multi-spec mode):**
+
+- If `$ARGUMENTS` contains one or more feature ids (e.g. `026`, `026-my-feature`, `027`), treat them as targets.
+- If `SPECIFY_FEATURE` is already set (e.g. when using `$speckit acceptance 026 027`), include it as a target as well.
+- Target ordering (important): if both `SPECIFY_FEATURE` and `$ARGUMENTS` are present, treat `SPECIFY_FEATURE` as the **first** target, then append `$ARGUMENTS` tokens in order.
+- De-duplicate targets; keep the resulting order.
+- **Spec Group shorthand**: if a target feature is a “Spec Group” (its feature directory contains `spec-registry.json` or `spec-registry.md`), expand it into member specs (in registry order) by running:  
+  `SKILL_DIR/scripts/bash/spec-group-members.sh <group> --json`  
+  Then append its `members` immediately after the group target (de-duplicate). This enables a “group-id-only” shorthand while still running multi-spec acceptance.
+- If no targets are provided, fall back to the inferred “current” feature (single-spec mode).
+
+From repo root, set `REPO_ROOT="$(pwd)"` so you can form absolute paths consistently.
+
+For **each** target feature, run:
+
+`SKILL_DIR/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks --feature <id>`
+
+Parse JSON for `FEATURE_DIR` and `AVAILABLE_DOCS`. All paths must be absolute.
+
+Derive absolute paths:
+
+- `SPEC = FEATURE_DIR/spec.md`
+- `PLAN = FEATURE_DIR/plan.md`
+- `TASKS = FEATURE_DIR/tasks.md`
+- `CONSTITUTION = REPO_ROOT/.specify/memory/constitution.md`
+
+Abort with a clear error if any required file is missing (and instruct which prerequisite command to run).
+For single quotes in args like "I'm Groot", use escape syntax: e.g. `I'\''m Groot` (or double-quote if possible: `"I'm Groot"`).
+
+### 2) Optional Checklist Gate
+
+For each `FEATURE_DIR`, if `FEATURE_DIR/checklists/` exists:
+
+- Scan all checklist files in `checklists/`.
+- For each checklist, count:
+  - Total items: lines matching `- [ ]` or `- [X]` or `- [x]`
+  - Completed items: lines matching `- [X]` or `- [x]`
+  - Incomplete items: lines matching `- [ ]`
+- If any checklist is incomplete: **STOP** and ask whether to continue acceptance anyway.
+
+### 3) Load Artifacts (Progressive Disclosure)
+
+- **REQUIRED (per spec)**: `spec.md`, `plan.md`, `tasks.md`
+- **REQUIRED**: `.specify/memory/constitution.md` (for MUST/SHOULD validation)
+- **IF EXISTS (per spec)**: `research.md`, `data-model.md`, `contracts/`, `quickstart.md`
+
+From `spec.md`, load the minimum needed to extract and interpret coded points:
+
+- Functional Requirements
+- Non-Functional Requirements
+- Success Criteria
+- User Stories (only as supporting context)
+
+### 4) Build Coded Points Inventory (SSoT = spec.md)
+
+Prefer a deterministic, script-backed inventory over ad-hoc grep.
+
+**MUST** run `SKILL_DIR/scripts/bash/extract-coded-points.sh --json` once for all targets (repeat `--feature`):
+
+`SKILL_DIR/scripts/bash/extract-coded-points.sh --json --feature 024 --feature 025`
+
+Use the script output as the source-of-truth inventory:
+
+- `points`: the canonical coded points list (**definitions** only; one row per code)
+- `occurrences`: all mentions (includes cross-references like “see FR-004”)
+- `duplicateDefinitions`: same code defined multiple times (treat as DRIFT/HIGH)
+- `orphanReferences`: code referenced but never defined (treat as FAIL/HIGH)
+
+Only fall back to manual search if the script fails or the spec format is non-standard.
+
+### 5) Determine Implementation Footprint
+
+Prefer a deterministic, script-backed inventory over ad-hoc parsing.
+
+**MUST** run `SKILL_DIR/scripts/bash/extract-tasks.sh --json` once for all targets (repeat `--feature`):
+
+`SKILL_DIR/scripts/bash/extract-tasks.sh --json --feature 024 --feature 025`
+
+Use the script output as the source-of-truth task inventory:
+
+- `tasks`: task list with `done` status + phase/story/[P] + `refs` (if tasks lines contain `Refs:`)
+- `counts` / `byPhase` / `byStory`
+- `duplicates`: duplicate task ids (treat as DRIFT/HIGH)
+
+Optionally (read-only), if the repo is a git repo:
+
+- Use `git diff --name-only` (and/or `git status`) to list changed files
+- Classify each changed file as “in-scope” (mentioned in tasks/plan) vs “out-of-scope” (potential drift / parallel work)
+
+Do **not** assume the diff equals the feature; treat tasks/plan as the feature boundary and flag mismatches.
+
+### 6) Evidence Gathering Per Coded Point
+
+For **each** coded point (e.g., `FR-001`), collect (per spec):
+
+- **Implementation evidence**: file paths + key symbols or config knobs that implement it
+- **Verification evidence**: tests (unit/integration/contract), quickstart steps, checklist items, or reproducible commands
+- **Task linkage**: which task IDs implement/validate it (prefer explicit references; otherwise infer by text + file path overlap)
+- **Drift check**:
+  - If code contradicts `spec.md` or `plan.md` → mark **DRIFT**
+  - If code conflicts with constitution MUSTs → mark **DRIFT (CRITICAL)**
+
+If you cannot prove PASS, mark **PARTIAL/UNKNOWN** and explain what evidence is missing.
+
+### 7) Produce Acceptance Matrix (Compact, Exhaustive Over Codes)
+
+Output acceptance matrices covering **every** coded point in **each** spec.
+
+Important: In multi-spec mode, codes like `FR-001` are **not globally unique**. Always include the feature id (or spec directory) in the matrix key.
+
+Recommended format:
+
+| Feature | Code | Type | Status | Evidence | Verification | Task IDs | Notes / Drift |
+| ------- | ---- | ---- | ------ | -------- | ------------ | -------- | ------------- |
+
+Status must be one of:
+
+- **PASS**: implemented + verified
+- **PARTIAL**: implemented but missing verification / measurable criteria
+- **FAIL**: not implemented
+- **DRIFT**: implemented but contradicts spec/plan/constitution
+- **UNKNOWN**: insufficient evidence to decide
+
+### 8) Cross-Cutting Checks
+
+- **Plan alignment**: major architecture choices, dependencies, and project structure still match the codebase.
+- **NFR coverage**: performance budgets/baselines and diagnosability requirements are reflected in code/tests/docs.
+- **Constitution alignment**: only flag what’s actually applicable, but treat MUST violations as CRITICAL.
+- **Cross-spec conflicts (multi-spec mode)**: highlight any contradictory requirements/plans, shared-file contention, or API/contract drift between the target specs.
+
+### 9) Quality Gates (One-Shot)
+
+- Prefer explicit “quality gates” commands written in `plan.md`.
+- If missing, infer the minimal one-shot checks from repo conventions (e.g., `typecheck` / `lint` / `test`) and run them once (avoid watch mode).
+- Record PASS/FAIL and a short blocker summary (no walls of logs).
+
+### 10) Next Actions
+
+Provide a prioritized list:
+
+- CRITICAL drift to resolve first
+- Missing coded points
+- Missing verification (tests/bench/diagnostics)
+
+Ask the user:
+
+“Do you want me to turn the top N gaps into concrete follow-up tasks (and where should they live: append to `tasks.md` vs a separate follow-up file)?”
+
+## Context
+
+$ARGUMENTS

package/.codex/skills/speckit/references/analyze.md

@@ -0,0 +1,186 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `$speckit tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Parallel Work Safety (Non-Negotiable)**: Assume the working tree may contain unrelated changes from other concurrent tasks. Never run any command that discards or rewrites changes (e.g., any form of `git restore`, `git checkout -- <path>`, `git reset`, `git clean`, `git stash`).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `$speckit analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `SKILL_DIR/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. If you need to target a specific spec by number/id, add `--feature 025` (or `--feature 025-my-feature`). Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Non-Functional Requirements
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID  | Category    | Severity | Location(s)      | Summary                      | Recommendation                       |
+| --- | ----------- | -------- | ---------------- | ---------------------------- | ------------------------------------ |
+| A1  | Duplication | HIGH     | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+| --------------- | --------- | -------- | ----- |
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `$speckit implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run $speckit specify with refinement", "Run $speckit plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS