tmux-agent 0.1.0

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

@@ -0,0 +1,90 @@
+---
+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
+handoffs: 
+  - label: Build Specification
+    agent: speckit.specify
+    prompt: Implement the feature specification based on the updated constitution. I want to build...
+---
+
+## 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
+
+You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+Follow this execution flow:
+
+1. Load the existing constitution template at `.specify/memory/constitution.md`.
+   - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+     **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
+
+2. Collect/derive values for placeholders:
+   - If user input (conversation) supplies a value, use it.
+   - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
+   - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
+   - `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+     - MAJOR: Backward incompatible governance/principle removals or redefinitions.
+     - MINOR: New principle/section added or materially expanded guidance.
+     - PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
+   - If version bump type ambiguous, propose reasoning before finalizing.
+
+3. Draft the updated constitution content:
+   - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
+   - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
+   - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
+   - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
+
+4. Consistency propagation checklist (convert prior checklist into active validations):
+   - Read `SKILL_DIR/assets/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
+   - Read `SKILL_DIR/assets/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
+   - Read `SKILL_DIR/assets/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
+   - Read each stage reference file in `SKILL_DIR/references/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
+   - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
+
+5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
+   - Version change: old → new
+   - List of modified principles (old title → new title if renamed)
+   - Added sections
+   - Removed sections
+   - Templates requiring updates (✅ updated / ⚠ pending) with file paths
+   - Follow-up TODOs if any placeholders intentionally deferred.
+
+6. Validation before final output:
+   - No remaining unexplained bracket tokens.
+   - Version line matches report.
+   - Dates ISO format YYYY-MM-DD.
+   - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
+
+7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
+
+8. Output a final summary to the user with:
+   - New version and bump rationale.
+   - Any files flagged for manual follow-up.
+   - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
+
+Formatting & Style Requirements:
+
+- Use Markdown headings exactly as in the template (do not demote/promote levels).
+- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
+- Keep a single blank line between sections.
+- Avoid trailing whitespace.
+
+If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
+
+If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
+
+Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.

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

@@ -0,0 +1,89 @@
+---
+description: Create/update a Spec Group execution checklist (a meta spec that dispatches multiple feature specs).
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Treat a “Spec Group” as a **meta spec** that coordinates multiple feature specs and provides a single entrypoint for humans/agents, without duplicating implementation details.
+
+This stage is intentionally **index-only**:
+
+- ✅ Create/refresh a group-level checklist under `specs/<group>/checklists/`
+- ✅ Reference member specs via links to their `tasks.md` / `quickstart.md`
+- ❌ Do NOT copy/paste member tasks into the group spec (avoid parallel truth sources)
+
+> Note: This is different from `$speckit checklist` (requirements-quality unit tests). Here we generate an **execution checklist** for a multi-spec deliverable.
+
+## Interface (recommended)
+
+`$ARGUMENTS` format:
+
+- First token: **group feature id** (e.g., `046` or `046-core-ng-roadmap`)
+- Remaining tokens (optional): **member feature ids** (e.g., `045 039`)
+- Optional key/value args:
+  - `name=<slug>` (or `--name <slug>`) → checklist file name (default: `group.<members>.md`)
+  - `title=<text>` (or `--title <text>`) → checklist title
+  - `--from registry` → when member ids are omitted, derive members from `specs/<group>/spec-registry.json` (fallback: `spec-registry.md`) (default)
+  - `--force` → overwrite the existing checklist file
+  - `--dry-run` → only resolve paths / show output path, do not write files
+
+Examples:
+
+- `$speckit group 046 045 039 name=m0-m1 title="M0→M1"`
+- `$speckit group 046 --name group.registry` (group-only: derive members from registry)
+- `$speckit group 046-core-ng-roadmap 045-dual-kernel-contract 039-trait-converge-int-exec-evidence --name m0-m1`
+
+## Parallel Development Safety (Non-Negotiable)
+
+- Assume the working tree may contain unrelated, uncommitted changes from other concurrent 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`).
+
+## Execution Steps
+
+1) **Generate group checklist (write)**  
+From repo root, run:
+
+`SKILL_DIR/scripts/bash/spec-group-checklist.sh <group> [<member...>] [--from registry] [--name <name>] [--title <title>] [--force]`
+
+2) **Optional: show progress summary (read-only)**  
+Use the built-in multi-feature task extractor:
+
+`SKILL_DIR/scripts/bash/extract-tasks.sh --json --feature <member1> --feature <member2> ...`
+
+2.5) **Optional: show dependency graph (read-only)**  
+Render dependency graph from `spec-registry.json`:
+
+`SKILL_DIR/scripts/bash/spec-registry-graph.sh <group>`
+
+Or merge all groups:
+
+`SKILL_DIR/scripts/bash/spec-registry-graph.sh --all`
+
+3) **Optional: group acceptance (read-only)**  
+You can already validate multiple specs together using:
+
+`$speckit acceptance <member1> <member2> ...`
+
+## Output
+
+- Print the generated checklist file path.
+- If the file already exists and `--force` is not provided, stop and ask whether to overwrite or create a new name.
+
+## Relationship to Other Stages (How to Compose)
+
+> Conclusion: **`group` does not replace `plan/tasks/implement`**. It provides an “I only remember the group id” entrypoint and dispatch view; implementation details stay inside each member spec to avoid parallel truth sources.
+
+- `$speckit plan <group>` / `$speckit tasks <group>`: still operate on the **group spec itself** (roadmap/gates/scheduling/evidence write-back). Do not copy member implementation tasks here.
+- `$speckit group <group>`: generates/refreshes the **index checklist** under `specs/<group>/checklists/*` (member jumps + gate summary). This is the main navigation when you “only remember 046”.
+- `$speckit implement-task <member> ...`: real code changes usually happen in member specs; jump from the group checklist to the member’s `tasks.md` and execute there.
+- `$speckit acceptance <member...>`: already supports multi-spec; if you only want to input the group id, derive members from `spec-registry.json` (script falls back to md): `spec-group-members.sh <group> --json`.

package/.codex/skills/speckit/references/implement-task.md

@@ -0,0 +1,115 @@
+---
+description: Execute a small, explicitly selected set of tasks from tasks.md using a task-driven, minimal-context workflow (does NOT change $speckit implement behavior).
+---
+
+## 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`).
+
+## Goal
+
+Implement **only** the requested task(s) (or the next incomplete task by default), while keeping context loading minimal:
+
+- Read `tasks.md` once.
+- Do NOT bulk-load optional design artifacts up-front.
+- Load additional docs/files **only when the selected task requires them**.
+
+## Accepted Task Selectors (from `$ARGUMENTS`)
+
+This stage is intentionally task-driven. Determine which task(s) to execute using `$ARGUMENTS`:
+
+- If `$ARGUMENTS` contains one or more Task IDs like `T006` / `T042`, execute those tasks only.
+- Else, if `$ARGUMENTS` contains `next N` or a bare number `N`, execute the next `N` incomplete tasks (cap at 5).
+- Else (empty or anything else), execute exactly the **next 1** incomplete task.
+
+If a requested Task ID is already completed (`[x]`), skip it and report that it was already done.
+If a requested Task ID cannot be found, ERROR and stop.
+
+## Execution Steps
+
+### 1) Resolve feature paths (single source of truth)
+
+Run `SKILL_DIR/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for:
+
+- `FEATURE_DIR`
+- `AVAILABLE_DOCS`
+
+Derive absolute paths:
+
+- `TASKS = FEATURE_DIR/tasks.md`
+- `PLAN = FEATURE_DIR/plan.md`
+- `SPEC = FEATURE_DIR/spec.md`
+
+If the user selected a feature for this invocation (via leading `029`, `SPECIFY_FEATURE=...`, or `spec=029`), pass it explicitly to scripts using `--feature <id>` (e.g., `--feature 029`) to avoid implicit inference.
+
+### 2) Checklist gate (fast, file-light)
+
+If `FEATURE_DIR/checklists/` exists:
+
+- For each checklist file, compute `total / done / todo` by counting checklist lines (e.g. using `rg` on `^- \\[[ xX]\\]`).
+- If any checklist has unfinished items, STOP and ask the user:
+  - "Some checklists are incomplete. Do you want to proceed with this task anyway? (yes/no)"
+  - Wait for user response.
+- If all checklists are complete (or no checklists dir), continue.
+
+### 3) Load minimal required context
+
+1. Read `TASKS` fully.
+2. Do NOT read `SPEC`, `PLAN`, `research.md`, `data-model.md`, `quickstart.md`, `contracts/` yet.
+3. Only load additional files when the selected task(s) require them.
+
+**Optional**: If (and only if) the selected task mentions architecture/stack/project structure and `PLAN` is needed to decide file locations, read `PLAN` (but prefer scanning only the relevant headings/sections).
+
+### 4) Select the task(s) to execute
+
+From the parsed `TASKS` file:
+
+- Identify incomplete tasks: lines matching `- [ ] T\\d+`.
+- Map Task ID → full task line text (description, file paths, story labels).
+
+Apply the selection rules defined above (Task IDs / next N / next 1).
+
+### 5) For EACH selected task: execute in a tight loop
+
+For each task (in order):
+
+1. **Determine the working set (no wandering)**:
+   - Extract file paths mentioned in the task line (e.g., `packages/foo/src/x.ts`).
+   - If the task line does not name file paths, derive the minimum search keys (symbol names, package names, error types).
+2. **Load only what you need**:
+   - If file paths are present: open those files first.
+   - If not: use targeted search (`rg`) to locate the smallest relevant entrypoints.
+   - Only if search is insufficient, use one targeted `auggie.codebase-retrieval` call scoped to the current task.
+3. **Implement the task**:
+   - Make minimal, focused changes.
+   - Avoid unrelated refactors.
+4. **Minimal validation for this task**:
+   - Prefer the smallest relevant check described by the repo or by the task itself (unit test, package test, or a single command).
+   - If no guidance exists, do a local, lightweight sanity check appropriate for the change (do not run large suites by default).
+5. **Mark completion**:
+   - Update `TASKS`: change this task line from `- [ ]` to `- [x]`.
+   - If the task requires adding notes/evidence (e.g. perf baselines), write them to the specified artifact and keep them brief.
+6. **Stop condition**:
+   - After each task, if more tasks remain in this batch, continue.
+   - After the batch completes, STOP and report what was done and what the next unchecked task is.
+
+## Output / Reporting
+
+At the end, report:
+
+- Which task IDs were executed and marked complete
+- Key files changed (paths only)
+- Any remaining blockers / required clarifications (if any)
+- Suggested next command, e.g. `$speckit implement-task <feature> next` or `$speckit implement-task <feature> T0XX`

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

@@ -0,0 +1,129 @@
+---
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+handoffs:
+  - label: Acceptance Review
+    agent: spec.acceptance
+    prompt: Run a post-implementation acceptance review
+    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`).
+
+## Spec Group Quick Mode (e.g. `$speckit implement 046`)
+
+If the target feature is a **Spec Group** (the feature directory contains `spec-registry.json`, fallback: `spec-registry.md`), treat it as a “dispatcher entrypoint”:
+
+1) Resolve members (registry order)
+   - Run: `SKILL_DIR/scripts/bash/spec-group-members.sh <group> --json`
+   - Take the `members` list from the output (e.g. `["045","039",...]`) and process in order (dedupe is fine).
+
+2) Generate/refresh the group execution index checklist (optional but recommended)
+   - Run: `SKILL_DIR/scripts/bash/spec-group-checklist.sh <group> --from registry --name group.registry`
+   - If the file already exists and you did not pass `--force` (so the script errors), do not overwrite; just continue (the index checklist is not a hard gate).
+
+3) Execute this `implement` workflow for each member (“recursive”)
+   - For each member, make step 1 in the Outline explicit with `--feature <member>`. The rest of the steps stay the same.
+   - Recommendation: in group mode, treat “checklists gate” as **informational only** (show the table but do not block on missing items) to avoid extra interaction at the dispatcher level.
+
+4) Optional write-back after each member
+   - If a group checklist exists (e.g. `specs/<group>/checklists/group.registry.md`), you can mark the corresponding member line from `- [ ]` to `- [x]` as a “dispatcher progress view”.
+   - After all members are done, run once: `$speckit acceptance <group>` (acceptance will expand group members).
+
+## Outline
+
+1. Run `SKILL_DIR/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. If you need to target a specific spec by number/id, add `--feature 025` (or `--feature 025-my-feature`). All paths must be absolute. 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. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
+   - Scan all checklist files in the checklists/ directory
+   - For each checklist, count:
+     - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
+     - Completed items: Lines matching `- [X]` or `- [x]`
+     - Incomplete items: Lines matching `- [ ]`
+   - Create a status table:
+
+     ```text
+     | Checklist | Total | Completed | Incomplete | Status |
+     |-----------|-------|-----------|------------|--------|
+     | ux.md     | 12    | 12        | 0          | ✓ PASS |
+     | test.md   | 8     | 5         | 3          | ✗ FAIL |
+     | security.md | 6   | 6         | 0          | ✓ PASS |
+     ```
+
+   - Calculate overall status:
+     - **PASS**: All checklists have 0 incomplete items
+     - **FAIL**: One or more checklists have incomplete items
+
+   - **If any checklist is incomplete**:
+     - Display the table with incomplete item counts
+     - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
+     - Wait for user response before continuing
+     - If user says "no" or "wait" or "stop", halt execution
+     - If user says "yes" or "proceed" or "continue", proceed to step 3
+
+   - **If all checklists are complete**:
+     - Display the table showing all checklists passed
+     - Automatically proceed to step 3
+
+3. Load and analyze the implementation context:
+   - **REQUIRED**: Read tasks.md for the complete task list and execution plan
+   - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
+   - **IF EXISTS**: Read data-model.md for entities and relationships
+   - **IF EXISTS**: Read contracts/ for API specifications and test requirements
+   - **IF EXISTS**: Read research.md for technical decisions and constraints
+   - **IF EXISTS**: Read quickstart.md for integration scenarios
+   - **IF EXISTS**: Read notes/ for entry points, invariants, and session context (Non-SSoT)
+
+   If this run involves long-chain exploration and you suspect the session may compact, proactively run `$speckit notes <feature>` to flush "entry points + next actions" before continuing.
+
+4. Parse tasks.md structure and extract:
+   - **Task phases**: Setup, Tests, Core, Integration, Polish
+   - **Task dependencies**: Sequential vs parallel execution rules
+   - **Task details**: ID, description, file paths, parallel markers [P]
+   - **Execution flow**: Order and dependency requirements
+
+5. Execute implementation following the task plan:
+   - **Phase-by-phase execution**: Complete each phase before moving to the next
+   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together
+   - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
+   - **File-based coordination**: Tasks affecting the same files must run sequentially
+   - **Validation checkpoints**: Verify each phase completion before proceeding
+
+6. Implementation execution rules:
+   - **Setup first**: Initialize project structure, dependencies, configuration
+   - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
+   - **Core development**: Implement models, services, CLI commands, endpoints
+   - **Integration work**: Database connections, middleware, logging, external services
+   - **Polish and validation**: Unit tests, performance optimization, documentation
+
+7. Progress tracking and error handling:
+   - Report progress after each completed task
+   - Halt execution if any non-parallel task fails
+   - For parallel tasks [P], continue with successful tasks, report failed ones
+   - Provide clear error messages with context for debugging
+   - Suggest next steps if implementation cannot proceed
+   - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
+
+8. Completion validation:
+   - Verify all required tasks are completed
+   - Check that implemented features match the original specification
+   - Validate that tests pass and coverage meets requirements
+   - Confirm the implementation follows the technical plan
+   - Report final status with summary of completed work
+
+Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `$speckit tasks` first to regenerate the task list.
+
+After implementation, run `$speckit acceptance` to validate the latest codebase against every coded point in `spec.md` (FR/NFR/SC) and detect drift.

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

@@ -0,0 +1,82 @@
+---
+description: Maintain handoff-friendly notes for the current feature (manual flush button before long explorations / session compaction; not SSoT)
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input (if not empty) and record it as the intent of this session/flush inside the notes.
+
+## “Filesystem as Working Memory” (Notes Edition)
+
+- **Filesystem as memory**: Put long content/research/intermediate artifacts into files; keep chat focused on “conclusions + pointers”.
+- **Read before decide**: Before pushing forward, read `notes/README.md` (and `plan.md`/`tasks.md` if present) to restore goal/state into the attention window.
+- **Keep failure traces**: Keep errors/failed attempts as traces (at least in a session file; add a one-line summary + link in README).
+- **Append-only history**: Write session details to `notes/sessions/*` (append-only; do not rewrite old sessions). Keep README as a one-screen dashboard + pointers.
+
+## What Notes Are For (Important)
+
+- `specs/<feature>/notes/**` are **engineering notes / handoff materials**: reduce long-chain exploration costs and avoid “re-reading the whole repo” next time.
+- Notes are **not** SSoT: any decision that changes requirements/contracts/architecture/quality gates MUST be written back to `spec.md` / `plan.md` / `tasks.md` (or `docs/specs/*`). Do not leave it only in notes.
+- Notes should be “actionable and relayable”:
+  - Entry points (files/symbols + one-line conclusion)
+  - Key chain nodes (shortest jumps from business usage → code landing points)
+  - Invariants / pitfalls (assumptions that must not break)
+  - Next actions (concrete edits the next executor can do immediately + validation method)
+
+## Default Artifacts
+
+Maintain the following files under `specs/<feature>/notes/` (create as needed; avoid empty-doc spam):
+
+- `README.md`: one-screen entrypoint (must be short; only “current status / conclusions / next actions / failure summaries + pointers”)
+- `entrypoints.md`: entry point index (files/symbols + one-line conclusion)
+- `questions.md`: open questions and blockers
+- `sessions/<YYYY-MM-DD>.md`: session-level increments (recommended default) as append-only history and failure traces
+
+## Outline
+
+1) **Resolve feature directory**
+   - Run from repo root: `SKILL_DIR/scripts/bash/check-prerequisites.sh --json`
+   - Parse `FEATURE_DIR` from output (must be an absolute path).
+
+2) **Ensure notes directory exists**
+   - Run: `SKILL_DIR/scripts/bash/setup-notes.sh --json`
+   - Parse: `NOTES_DIR` / `NOTES_README` / `NOTES_ENTRYPOINTS` / `NOTES_QUESTIONS` / `SESSIONS_DIR`
+   - Default behavior: only write minimal skeleton when files are missing/empty; never overwrite existing content (`--force` overwrites).
+
+3) **Read-before-decide (lightweight attention refresh)**
+   - Open and quickly scan:
+     - `NOTES_README`
+     - `FEATURE_DIR/plan.md` (and `FEATURE_DIR/tasks.md` if present)
+   - If `NOTES_README` is no longer “one-screen readable”, trim it (move long content into `sessions/*`, keep README as pointers).
+
+4) **Update `notes/README.md` (required)**
+   - Goal: keep it “one-screen readable”; do not pile long explanations into README.
+   - At minimum include these sections (short bullets are fine):
+     - `Scope`: what these notes cover / do not cover
+     - `Entry Points`: link to `entrypoints.md` (or list 3–8 key entry points directly)
+     - `Current Status`: one-line focus + progress/stage (checkboxes OK)
+     - `Current Hypothesis`: current best judgement (1–5 items)
+     - `Errors Encountered`: failure trace summaries (1–5 items; details in session)
+     - `Next Actions`: next executable edit points (file path/symbol + validation method)
+     - `Last Flush`: timestamp + this `$ARGUMENTS` (helps recall “why we wrote this”)
+
+5) **Write `notes/sessions/<YYYY-MM-DD>.md` (recommended default)**
+   - Goal: capture “this flush’s details” as append-only history (do not rewrite old sessions).
+   - Suggested sections:
+     - `Intent`: this `$ARGUMENTS` (one line is enough)
+     - `What Changed`: index of files/symbols touched (index only)
+     - `Findings`: conclusions / evidence / counterexamples
+     - `Errors (Failure Traces)`: failure → fix/mitigation → whether written back to SSoT
+     - `Next Actions`: next executable points + validation method
+   - Link this session from README `Last Flush`.
+
+6) **Update other notes docs as needed**
+   - If you found new entry points: update `entrypoints.md` (index only, no long prose).
+   - If you are blocked or need user decisions: update `questions.md` using “question → impact → decision needed”.
+
+7) **Consistency self-check (lightweight)**
+   - If notes mention key decisions that belong to SSoT, ensure they are written back into `spec.md`/`plan.md`/`tasks.md` (avoid parallel truth sources).

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

@@ -0,0 +1,87 @@
+---
+description: Deepen planning in one pass by running an auto-resolving clarification loop (self Q&A) and then producing a more explicit, implementation-ready plan with fewer unknowns.
+handoffs:
+  - label: Create Tasks
+    agent: speckit.tasks
+    prompt: Break the plan into tasks
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Reduce ambiguity and deepen the implementation plan **without interactive questioning**:
+
+1) Use a clarify-style ambiguity scan, but **self-answer** the highest-impact questions by selecting the best option/recommended answer.
+2) Write the resolved clarifications back into the spec (same integration rules as `clarify`).
+3) Produce / refine `plan.md` and Phase 0/1 artifacts (`research.md`, `data-model.md`, `contracts/`, `quickstart.md`) with a higher explicitness bar (fewer "TBD"/"NEEDS CLARIFICATION") and no drift from the updated spec.
+
+## Operating Constraints
+
+- Assume unrelated parallel work exists; never run destructive git/system commands.
+- Keep spec as WHAT and plan as HOW. Only write HOW decisions into plan; write WHAT clarifications into spec.
+- Do not ask the user questions in this stage. If a decision is too risky to auto-resolve, record it as an explicit **Assumption** with a clear follow-up validation step.
+
+## Execution Steps
+
+### 1) Resolve paths & prerequisites
+
+From repo root, run `SKILL_DIR/scripts/bash/check-prerequisites.sh --json --paths-only` once (add `--feature <id>` if needed). Parse:
+
+- `FEATURE_SPEC`
+- `IMPL_PLAN`
+- `FEATURE_DIR`
+
+If `FEATURE_SPEC` is missing, instruct the user to run `$speckit specify` first (do not create a spec here).
+If `IMPL_PLAN` is missing or empty, run `SKILL_DIR/scripts/bash/setup-plan.sh --json` to initialize it from the template (do not overwrite unless explicitly asked).
+
+Load `.specify/memory/constitution.md` and the latest `FEATURE_SPEC`.
+
+### 2) Auto-clarify (self Q&A, non-interactive)
+
+Baseline: read and follow `SKILL_DIR/references/clarify.md` EXACTLY, with these overrides:
+
+- Replace the interactive questioning loop with **self Q&A**:
+  - Generate a prioritized queue of candidate clarification questions (max **12**).
+  - For each question, determine the recommended/suggested answer exactly as in `clarify` rules, then **auto-accept** it (no user prompt).
+  - For each auto-accepted answer, produce a concise audit-friendly rationale (NOT persisted to disk):
+    - `**Decision logic:**` 5–12 bullets, covering Criteria / Tradeoffs / Risks / Implications.
+  - Immediately integrate each answer into the spec using the same incremental write rules as `clarify` (create/append in `## Clarifications` and update the appropriate sections).
+  - Mark the clarification line with an `AUTO:` prefix, e.g. `- AUTO: Q: ... → A: ...`.
+
+- Stop early if no high-impact ambiguities remain.
+- If a high-impact ambiguity cannot be responsibly auto-resolved:
+  - Do not guess silently.
+  - Record it under `## Clarifications` as an explicit assumption using the same bullet format (prefix the line with `ASSUMPTION:`), and also add a follow-up validation note in `plan.md` (next step).
+
+### 3) Plan deepening (higher explicitness bar)
+
+Baseline: read and follow `SKILL_DIR/references/plan.md` EXACTLY, with these additional requirements:
+
+- Keep Phase 0/1 artifacts aligned:
+  - If `research.md` / `data-model.md` / `contracts/` / `quickstart.md` already exist, update them to reflect the newly applied `AUTO`/`ASSUMPTION` clarifications (do not leave stale contradictions).
+  - If they do not exist, generate them following the plan workflow.
+- Eliminate placeholders:
+  - No `NEEDS CLARIFICATION` left in `Technical Context` unless it is truly unavoidable; when unavoidable, convert it into an explicit assumption + a validation task.
+- Make decisions explicit and testable:
+  - Fill the `Perf Evidence Plan (MUST)` section with either a concrete evidence plan or `N/A` plus a concrete rationale.
+  - If the plan touches Logix runtime hot paths, ensure the plan includes reproducible baseline/diff commands consistent with the perf-evidence references.
+- Add a short `## Deepening Notes` section near the top of `plan.md`:
+  - Include up to 8 bullets of the most consequential auto-decisions (not all), each as `- Decision: <...> (source: spec clarify AUTO/ASSUMPTION)`.
+- Ensure the final plan can drive `$speckit tasks` deterministically (clear structure, stable file paths, measurable gates).
+
+### 4) Report completion
+
+Report:
+
+- How many AUTO clarifications were applied to spec
+- Whether any ASSUMPTION items remain (list them)
+- Paths written: `FEATURE_SPEC`, `IMPL_PLAN`, and any generated Phase 0/1 artifacts
+- Suggested next command (`$speckit tasks` recommended)