spectre

Use whenever a message carries something the project must still know next week—record it immediately and unasked; the user will never say ‘remember this.’ Fires on: a decision made, reaffirmed, or reversed (‘we settled on X’, ‘not sharding after all’, ‘that’s the call’); a correction of you or standing guidance, however blunt or repeated (‘no, that’s wrong; X applies only to Y’); a gotcha, root cause, version pin, constraint, or convention worth handing to whoever hits it next (‘for future reference’, ‘so nobody else hits this’); maintained guidance now disproved; or a persistent blocker newly cleared, confirmed real, or otherwise changed state, even in passing. The user’s word alone is sufficient authority; never wait for repo evidence or an explicit save request. Not for work records or routine progress.

Meta cleanup utility: orchestrate parallel prune and risk-based tests, then one sweep/commit boundary. Use mid-work or before rebase/create-pr. Do NOT use as Ship's dependency, or for dead-code-only cleanup (spectre-prune), test-only work (spectre-test), commit-only hygiene (spectre-sweep), bug fixes (spectre-fix), or scoping/planning.

Delegate one small, unambiguous feature or reproducible bug fix to Spectre's autonomous TDD→opposite-runtime review→proof→draft-PR flow. Not for ambiguous/multi-area/high-risk/non-code work.

Execute tasks/plans with checks/reviews/proof. Use after planning/resume. Not for planning, unplanned fixes, or pruning.

Internal initializer for a missing Spectre feature root. Invoke only from a standalone workflow with no confirmed managed root. Do NOT invoke for existing roots, orchestrated calls missing a root, or direct user requests.

Investigate a reported bug, pin its root cause, and prepare an Execute handoff. Use for errors, stack traces, failing behavior, or repro steps. Do NOT use for greenfield work (plan/execute) or a complete repair report (execute).

Internal diagnose-and-repair engine for Spectre workflows. Use only when invoked by spectre-fix or spectre-delegate with an explicit phase and authorization contract. Do NOT invoke directly for user requests.

Clear session memory - archive all session files so next session starts fresh

Opt-in utility that turns reviewed Spectre plans or execution state into one safe, verifiable `/goal` completion contract for Codex, Claude Code, or both. Use only when a user explicitly asks for an autonomous goal prompt. Do NOT use as the Plan handoff, or to plan, implement, start goal mode, or handle quick work.

Save a quiet, branch-keyed session snapshot with continuity, active work, and optional task/todo state for automatic resume. Use when ending or pausing a coding session; do not use for project documentation or workflow routing.

Project kickoff — deep codebase + external research producing an evidence-backed kickoff doc, gap analysis, and MVP path before scoping. Use to start a fresh feature/project from an unclear problem, when the user wants research/options/an MVP recommendation before committing to scope or a plan. Do not trigger once scope is already defined (use /spectre:spectre-scope) or for a single targeted code question (use an analyst agent directly).

User-invoked front door for durable capture. Use when the user invokes /learn or asks to remember, correct, preserve, or summarize consequential project work; interpret the request and delegate persistence to Capture. Do not use for autonomous capture, routine progress, unsupported hypotheses, personal preferences, or knowledge lookup.

Create a repository-grounded aligned draft after confirmed Scope, present its concise alignment brief, and hand it to Execute preflight. Do not use for scoping, bug diagnosis, read-only work, or execution of approved artifacts.

Internal semantic classifier for Plan-or-Execute preparation. Use only from Plan or Execute with bounded routing input; never for planning, artifacts, telemetry, or user gates.

Create one self-contained HTML prototype to resolve ambiguity, validate flows, or render UX before planning. Use for prototype/mockup/preview requests and UX Stage 1→2; not for production code, multi-file apps, scope, or planning.

Run one acceptance-proof pass over completed work and publish reviewed user-facing evidence. Use from spectre-execute or standalone for acceptance evidence, screenshots/video/logs, or an HTML proof artifact. Do NOT use for implementation checks, repairs, unit tests, planning, or code review.

Find and remove confirmed-safe dead production/source code and artifacts from a scoped working set while surfacing uncertain items for manual review. Use standalone or as the prune phase inside spectre-clean/ship. Do NOT trigger for tests (spectre-test), final commit hygiene (spectre-sweep), bug fixes (spectre-fix), or broad behavior-changing refactors.

👻 | Safe guided git rebase — backup ref, auto-resolve conflicts, and either run affected post-rebase checks or hand advisory verification ownership to an orchestrating parent. Use to rebase the current branch onto a target (e.g. origin/main), especially when conflicts or post-rebase verification are expected. Do NOT use for merges, cherry-picks, interactive history edits, or non-git work.

Research a codebase to answer a question — fan out read-only agents (finder/analyst/patterns, web-research for 3rd-party), then synthesize evidence-backed findings into a saved research doc with file:line citations. Use when the user asks "how does X work", "where does Y live", "investigate/research Z before planning", or wants a written research artifact. Do NOT use to write code, plan a feature (use spectre-plan), or for a one-off lookup that needs no saved doc.

Scope a feature or improvement into explicit IN / OUT / ANTI-SCOPE boundaries before planning or code — grounds a hypothesis in repo reality, resolves blocking questions, and writes scope.md. Trigger for new or fuzzy work or re-scoping. Do NOT trigger for technical design/research (spectre-plan) or standalone bug diagnosis (spectre-fix).

Turn completed branch work into a reviewer-ready PR: directly coordinate cleanup, rebase, one advisory full suite, repair/route failures, and spectre-create_pr. Use when asked to ship finished work. Proof is optional. Do NOT use for implementation, main/master pushes, releases, or autonomous request-to-PR delivery.

Light pre-commit cleanup pass — diff sanity, log/dead-code hygiene, stale/uncovered integrated checks, then conventional-commit. Use standalone or as the final phase of spectre-clean/ship. Do NOT use for forensic cleanup (spectre-prune), authoring tests (spectre-test), or full validation.

Execute implementation via strict red/green/refactor — derive behavioral Test Opportunities, write a happy/failure baseline plus risk-justified cases, confirm RED before production code, then ship minimal GREEN code. Trigger for TDD, failing-test-first, or RED-GREEN-REFACTOR execution; not test auditing/planning (use spectre-test).

Triage a working set into risk tiers (P0–P3) and add risk-appropriate behavioral tests. Trigger after a feature is built or when asked to add/strengthen tests; when orchestrated by spectre-clean/ship, consume the parent risk plan and assigned test/fixture batch. Do NOT trigger for brute-force coverage, cleanup (spectre-prune), bug fixes (spectre-fix), final commit hygiene (spectre-sweep), or scoping/planning.

Define user flows, screens, states, copy, and accessibility in ux.md. Two stages: align flows, then specify. Use after scope/PRD for behavioral UX; not backend, scope, or architecture.

Validate that completed implementation actually delivers the scope/tasks requirements — chunks the work into areas, dispatches parallel @spectre:analyst validators that trace each requirement from user action to render, and writes one actionable validation_gaps.md ranking what's Delivered / Partial / Dead Code / Missing. Trigger after execute (or any build) when you need to confirm requirements are met before clean/test/ship. Do NOT trigger to fix the gaps (spectre-fix), to run the test suite (spectre-test), or to remove dead code (spectre-prune).

Use only for one bounded historical account at an explicit ownership boundary, not as proactive project memory. Fires on: Execute start after exact run/work identity exists; a meaningful blocked handoff or its resolution; Execute completion; Ship after the PR exists; standalone Create PR when no Execute or Ship parent owns the record; an explicit user request to snapshot or summarize a body of work; or a historical correction. Workflow ownership or explicit historical intent is required. Not for reusable guidance, routine progress, or orchestrated Create PR.