tmux-agent 0.1.0

package/.codex/skills/speckit/references/plan-from-questions.md

@@ -0,0 +1,115 @@
+---
+description: Digest an external review question list (no review.md) and update plan.md (and tasks.md/spec.md if needed) to close the loop.
+handoffs:
+  - label: Refresh Tasks
+    agent: speckit.tasks
+    prompt: Update tasks based on the updated plan.md.
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding. This stage expects a *question list* pasted inline (no `review.md`).
+
+## Parallel Development Safety (Non-Negotiable)
+
+- Assume the working tree may contain unrelated, uncommitted changes from other parallel tasks.
+- NEVER try to "leave only this task's files" by reverting or cleaning other changes.
+- 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`).
+
+## Outline
+
+Goal: Take an external reviewer’s *questions* (asked from the “questioner” perspective) and merge the resulting decisions back into the feature artifacts so the spec-kit SSoT stays consistent.
+
+- Primary target: `plan.md`
+- Secondary targets (only when required by the questions/answers): `tasks.md`, `spec.md`, `data-model.md`, `contracts/*`
+
+## Execution Steps
+
+### 1) Resolve feature + file paths
+
+1. Run `SKILL_DIR/scripts/bash/setup-plan.sh --json` from repo root **once** and parse JSON:
+   - `FEATURE_SPEC` (spec.md path)
+   - `IMPL_PLAN` (plan.md path)
+2. Derive `FEATURE_DIR = dirname(FEATURE_SPEC)`.
+3. Determine candidate optional files (only load when needed):
+   - `TASKS_FILE = FEATURE_DIR/tasks.md`
+   - `DATA_MODEL = FEATURE_DIR/data-model.md`
+   - `RESEARCH = FEATURE_DIR/research.md`
+   - `CONTRACTS_DIR = FEATURE_DIR/contracts/`
+
+If `IMPL_PLAN` does not exist, stop and instruct the user to run `$speckit plan <feature>` first.
+
+### 2) Validate question input (no review.md in this flow)
+
+- If `$ARGUMENTS` is empty:
+  - Stop and ask the user to paste the question list (preferred format: one question per line; IDs like `Q001` are optional).
+- Otherwise:
+  - Normalize the questions into an internal list:
+    - If IDs are present, keep them (`Q001`, `Q002`, ...).
+    - If not, assign stable IDs in appearance order.
+
+### 3) Load context
+
+Read:
+- `FEATURE_SPEC`
+- `IMPL_PLAN`
+- `.specify/memory/constitution.md`
+
+If present and relevant to specific questions, also read:
+- `TASKS_FILE`
+- `DATA_MODEL`
+- `RESEARCH`
+- `CONTRACTS_DIR/*` (only the files actually referenced by questions or by planned changes)
+
+### 4) Answer questions → merge decisions into artifacts (do not append-only)
+
+For each question:
+
+1. Produce a direct answer (concise, decision-oriented).
+2. Decide which artifact(s) the answer impacts:
+   - Spec ambiguity / missing acceptance criteria → update `spec.md`
+   - Architecture / constraints / quality gates / performance & diagnostics plan → update `plan.md`
+   - Implied work items / sequencing / validation steps → update `tasks.md` (if it exists)
+   - Data / contracts correctness → update `data-model.md` / `contracts/*`
+3. Apply edits by **merging into the correct section(s)** (replace/adjust contradictory text; avoid duplicating near-identical bullets).
+
+If a question cannot be answered without product/business choice, do **NOT** guess:
+- Ask the user for a decision (offer 2–5 options).
+- After the user decides, continue and encode the answer back into the artifacts.
+
+### 5) Record a compact “Questions Digest” in plan.md
+
+In `plan.md`, add a small note near the top (or under `## Summary`) that:
+- States the source as “external questions pasted into `$speckit plan-from-questions`”.
+- Lists the key accepted changes, referencing question IDs (e.g., `Q003`, `Q007`).
+- If you changed `spec.md` or `tasks.md`, include a 1-line pointer to those updates.
+
+Keep it compact (a digest, not a transcript).
+
+### 6) Tasks handling (keep tasks.md as the task list)
+
+- If `tasks.md` exists:
+  - Add/adjust tasks to reflect accepted changes.
+  - Ensure tasks have concrete file paths and validation steps.
+- If `tasks.md` does not exist:
+  - Do **NOT** invent a full tasks list here.
+  - Recommend running `$speckit tasks <feature>` after `plan.md` is updated.
+
+### 7) Final validation
+
+- No contradictory statements left in `spec.md`/`plan.md`.
+- “Questions Digest” exists and references the right IDs.
+- Any new perf/diagnostics gates mentioned are actionable (what to measure, where, how to validate).
+
+## Report
+
+In your final response, include:
+- Which files were updated.
+- The recommended next command(s): typically `$speckit tasks <feature-id>` (if tasks are missing/outdated), or proceed to `$speckit implement <feature-id>`.

package/.codex/skills/speckit/references/plan-from-review.md

@@ -0,0 +1,89 @@
+---
+description: Digest an external review report (review.md) and update plan.md (and tasks.md/spec.md if needed) to close the loop.
+handoffs:
+  - label: Refresh Tasks
+    agent: speckit.tasks
+    prompt: Update tasks based on the updated plan.md and review.md.
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Parallel Development Safety (Non-Negotiable)
+
+- Assume the working tree may contain unrelated, uncommitted changes from other parallel tasks.
+- NEVER try to "leave only this task's files" by reverting or cleaning other changes.
+- 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`).
+- Do **NOT** delete `review.md`. Preserve it as evidence (you may add a small status note if needed).
+
+## Outline
+
+Goal: Take a review report (typically created by another LLM) and merge the actionable decisions back into the feature artifacts so the spec-kit SSoT stays consistent:
+
+- Primary target: `plan.md`
+- Secondary targets (only when required by the review): `tasks.md`, `spec.md`, `data-model.md`, `contracts/*`
+
+Execution steps:
+
+1. **Resolve feature + file paths**
+   - Run `SKILL_DIR/scripts/bash/setup-plan.sh --json` from repo root **once** and parse JSON:
+     - `FEATURE_SPEC` (spec.md path)
+     - `IMPL_PLAN` (plan.md path)
+   - Derive `FEATURE_DIR = dirname(FEATURE_SPEC)`.
+   - Determine candidate inputs:
+     - `REVIEW_FILE = FEATURE_DIR/review.md` (default)
+     - `TASKS_FILE = FEATURE_DIR/tasks.md` (optional)
+     - `DATA_MODEL = FEATURE_DIR/data-model.md` (optional)
+   - If `REVIEW_FILE` does not exist:
+     - Ask the user to provide the review content (paste) or to create `review.md` first, then stop.
+
+2. **Load context**
+   - Read:
+     - `FEATURE_SPEC`
+     - `IMPL_PLAN`
+     - `REVIEW_FILE`
+     - `.specify/memory/constitution.md`
+   - If present and relevant to review items, also load:
+     - `TASKS_FILE`
+     - `DATA_MODEL`
+     - `FEATURE_DIR/research.md`
+     - `FEATURE_DIR/contracts/*` (only the files mentioned by review)
+
+3. **Digest the review (item-by-item)**
+   - Highest priority: **Risks & Recommendations**
+     - For each risk: ensure `plan.md` includes a concrete mitigation plan (what to do, where, how to validate).
+     - If mitigation implies work: add/update concrete tasks in `tasks.md` (or flag that tasks are missing).
+   - Then: **Technical Analysis** and **Constitution Check / Quality Gates**
+     - If the review points out a violation or missing gate: either (a) change the plan to comply, or (b) explicitly justify the violation in `plan.md` (Complexity Tracking).
+     - If the review mentions performance/diagnostics, ensure the plan includes a reproducible baseline/measurement and the intended diagnostic surfaces/cost.
+   - Clarifications:
+     - If review identifies ambiguous requirements or missing edge cases, update `spec.md` (and keep `FR-/NFR-/SC-` points consistent).
+   - Data/contract correctness:
+     - If the review points out missing/incorrect domain modeling, update `data-model.md`.
+     - If the review changes external contracts, update `contracts/*` and ensure the plan/tasks reflect the change.
+
+4. **Apply edits (merge into the right sections, not append-only)**
+   - `plan.md`:
+     - Edit the relevant sections (Summary / Technical Context / Constitution Check / Project Structure / Complexity Tracking).
+     - Add a small “Review Digest” note near the top (or under Summary) containing:
+       - The review source file (`review.md`)
+       - A concise list of the key accepted changes (prefer referencing review item IDs like `R001`, `R101`, ...)
+   - `tasks.md` (if it exists):
+     - Add new tasks or adjust existing tasks to reflect accepted review changes.
+     - Ensure tasks have concrete file paths and validation steps.
+   - If `tasks.md` does not exist:
+     - Do **NOT** invent a full tasks list here.
+     - Mention that `$speckit tasks` should be run next after the plan is updated.
+
+5. **Close the loop (without deleting evidence)**
+   - Keep `review.md` in place.
+   - If `review.md` contains a `**Digest**: PENDING` line, update it to something like `**Digest**: DONE (YYYY-MM-DD)`; otherwise optionally add a short status line at the top of `review.md` (e.g., “Digested into plan.md/tasks.md on YYYY-MM-DD”).
+   - Output a brief summary: which files changed and what major review points were accepted/rejected (with 1-line rationale for rejections).

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

@@ -0,0 +1,97 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+handoffs: 
+  - label: Create Tasks
+    agent: speckit.tasks
+    prompt: Break the plan into tasks
+    send: true
+  - label: Create Checklist
+    agent: speckit.checklist
+    prompt: Create a checklist for the following domain...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Parallel Development Safety (Non-Negotiable)
+
+- Assume the working tree may contain unrelated, uncommitted changes from other parallel tasks.
+- NEVER try to "leave only this task's files" by reverting or cleaning other changes.
+- 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`).
+
+## Outline
+
+## Spec Group (dispatcher spec) note
+
+If the target feature is a **Spec Group** (its directory contains `spec-registry.json`, fallback: `spec-registry.md`, e.g. `specs/046-core-ng-roadmap/`), then this stage should produce a plan that is **dispatch / gates / evidence write-back** oriented:
+
+- The plan is mostly documentation deliverables (roadmap/registry/checklists/quickstart). Do not generate business-side `contracts/` or `data-model.md` (you can mark them as N/A).
+- The plan MUST clarify: member spec dependency order, milestone “done” criteria, and where evidence is written + how it is written back (avoid parallel truth sources).
+- To generate/refresh the group execution index checklist, use `$speckit group <group>` (derive members from registry).
+
+1. **Setup**: Run `SKILL_DIR/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. If you need to target a specific spec by number/id, add `--feature 025` (or `--feature 025-my-feature`). 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 context**: Read FEATURE_SPEC and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
+
+3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
+   - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
+   - Fill Constitution Check section from constitution
+   - Evaluate gates (ERROR if violations unjustified)
+   - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
+   - Phase 1: Generate data-model.md, contracts/, quickstart.md
+   - Re-evaluate Constitution Check post-design
+
+4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
+
+## Phases
+
+### Phase 0: Outline & Research
+
+1. **Extract unknowns from Technical Context** above:
+   - For each NEEDS CLARIFICATION → research task
+   - For each dependency → best practices task
+   - For each integration → patterns task
+
+2. **Generate and dispatch research agents**:
+
+   ```text
+   For each unknown in Technical Context:
+     Task: "Research {unknown} for {feature context}"
+   For each technology choice:
+     Task: "Find best practices for {tech} in {domain}"
+   ```
+
+3. **Consolidate findings** in `research.md` using format:
+   - Decision: [what was chosen]
+   - Rationale: [why chosen]
+   - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+### Phase 1: Design & Contracts
+
+**Prerequisites:** `research.md` complete
+
+1. **Extract entities from feature spec** → `data-model.md`:
+   - Entity name, fields, relationships
+   - Validation rules from requirements
+   - State transitions if applicable
+
+2. **Generate API contracts** from functional requirements:
+   - For each user action → endpoint
+   - Use standard REST/GraphQL patterns
+   - Output OpenAPI/GraphQL schema to `/contracts/`
+
+**Output**: data-model.md, /contracts/\*, quickstart.md
+
+## Key rules
+
+- Use absolute paths
+- ERROR on gate failures or unresolved clarifications

package/.codex/skills/speckit/references/review-plan.md

@@ -0,0 +1,156 @@
+---
+description: Review a speckit feature plan (spec.md + plan.md) and produce a structured review.md for later digestion via $speckit plan-from-review.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Parallel Development Safety (Non-Negotiable)
+
+- Assume the working tree may contain unrelated, uncommitted changes from other parallel tasks.
+- NEVER try to "leave only this task's files" by reverting or cleaning other changes.
+- 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`).
+- This is a **review-plan** stage: do not implement code changes. Only produce `review.md` under the feature directory.
+
+## Goal
+
+Generate a `review.md` report inside `specs/<feature>/review.md` that:
+
+- Is written in **English** by default (unless the user explicitly requests otherwise).
+- Contains actionable, structured review items with IDs (`R001`, `R101`, ...).
+- Clearly maps each recommendation to the correct artifact target:
+  - `spec.md` / `plan.md` / `tasks.md` / `data-model.md` / `contracts/*`
+- Includes explicit acceptance criteria / validation method for each item.
+- Can be later digested and closed-looped by `$speckit plan-from-review <feature>`.
+
+## Execution Steps
+
+### 1) Resolve feature directory (supports direct numeric IDs)
+
+1. Run `SKILL_DIR/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once**.
+   - If you need to target a specific spec by number/id, add `--feature 042` (or `--feature 042-my-feature`).
+   - Parse minimal JSON payload fields:
+     - `FEATURE_DIR`
+     - `FEATURE_SPEC`
+     - (Optionally capture `IMPL_PLAN`, `TASKS` if present.)
+   - If JSON parsing fails, stop and instruct the user to re-run `$speckit specify` / `$speckit plan` or verify the feature selection.
+
+2. Derive paths:
+   - `SPEC_FILE = FEATURE_SPEC` (spec.md)
+   - `PLAN_FILE = FEATURE_DIR/plan.md` (must exist)
+   - `TASKS_FILE = FEATURE_DIR/tasks.md` (optional)
+   - `REVIEW_FILE = FEATURE_DIR/review.md` (output)
+
+If `PLAN_FILE` does not exist, stop and instruct the user to run `$speckit plan <feature>` first.
+
+### 2) Load context (do not guess missing artifacts)
+
+Read:
+- `SPEC_FILE`
+- `PLAN_FILE`
+- `.specify/memory/constitution.md`
+
+If present and relevant, also read:
+- `TASKS_FILE`
+- `FEATURE_DIR/research.md`
+- `FEATURE_DIR/data-model.md`
+- `FEATURE_DIR/contracts/*` (only if the plan/spec declares external contracts or you need to audit protocol/API correctness)
+
+If you do not have codebase access, state that explicitly in the report under “Assumptions”, and avoid claiming verification of referenced files/symbols.
+
+### 3) Perform the review (aligned to speckit artifact boundaries)
+
+Cover these dimensions (mark N/A when not relevant):
+
+1. Spec ↔ Plan alignment
+   - Is every FR/NFR/SC and success criteria in `spec.md` addressed in `plan.md`?
+   - Is there scope creep in `plan.md` that is not declared in `spec.md`?
+
+2. Constitution / quality gates
+   - Are the Constitution Check items complete, executable, and compliant?
+   - If touching runtime core paths / diagnostic protocols / public APIs:
+     - Is there a reproducible performance baseline & measurement plan?
+     - Are diagnostic events/surfaces and overhead budgets specified?
+
+3. Tasks consistency (tasks.md is the only task list artifact)
+   - If `tasks.md` exists: are tasks executable (concrete file paths, dependencies/parallelism, validation)?
+   - If `tasks.md` does not exist: do NOT ask to add “Phase 2 tasks” into `plan.md`;
+     instead, list task suggestions in the review and require `$speckit tasks` next.
+
+4. Risks & mitigations
+   - Performance regression risks, diagnosability gaps/cost, breaking changes & missing migration notes,
+     IR/anchor drift, non-deterministic identity (random/time defaults), IO inside transaction window,
+     writable escape hatches (e.g., SubscriptionRef), etc.
+   - Every risk must have a concrete mitigation and a validation plan.
+
+### 4) Write `review.md` (MUST follow this template)
+
+Create or overwrite `REVIEW_FILE` with:
+
+```markdown
+# Review Report: [FEATURE_ID - Feature Name]
+
+**Status**: [REQUEST_CHANGES / APPROVED_WITH_SUGGESTIONS / APPROVED]
+**Digest**: PENDING
+**Reviewer**: [name]
+**Date**: YYYY-MM-DD
+
+## 0. Assumptions
+
+- [If any, e.g. “No codebase access; referenced paths not verified.”]
+
+## 1. Executive Summary
+
+- One-line verdict: [...]
+- Top 3 issues (if any): [...]
+
+## 2. Blockers
+
+> Only list items that block implementation / task breakdown.
+
+- R001 [BLOCKER] [Target: plan.md] [Location: plan.md#…] Issue: … Recommendation: … Acceptance: …
+- R002 [BLOCKER] [Target: spec.md] [Location: spec.md#…] Issue: … Recommendation: … Acceptance: …
+
+## 3. Risks & Recommendations
+
+- R101 [MAJOR] [Risk] … Mitigation: … Validation: …
+- R102 [MINOR] [Suggestion] … Validation: …
+
+## 4. Technical Analysis
+
+- Architecture soundness: …
+- Alignment/drift vs repo conventions: …
+- Feasibility and complexity: …
+
+## 5. Constitution Check
+
+- Performance & diagnosability: PASS/CONCERN/N/A — Evidence: … Next: …
+- IR/anchor drift risk: PASS/CONCERN/N/A — …
+- Stable identifiers (instanceId/txnSeq/opSeq): PASS/CONCERN/N/A — …
+- Transaction window (no IO): PASS/CONCERN/N/A — …
+- Breaking changes & migration notes: PASS/CONCERN/N/A — …
+- (If touching packages/*) public submodules / internal layering: PASS/CONCERN/N/A — …
+
+## 6. Coverage & Drift
+
+- Uncovered FR/NFR/SC gaps (only list gaps): …
+- plan ↔ tasks drift points (if tasks.md exists): …
+
+## 7. Next Actions
+
+- Save this file as `specs/<feature>/review.md`.
+- Go back to the speckit session and run: `$speckit plan-from-review <feature-id>` (and run `$speckit tasks` if you need to refresh the task list).
+```
+
+### 5) Report
+
+In your final response, include:
+- The `review.md` path you produced.
+- The recommended next command(s): typically `$speckit plan-from-review <feature-id>`.