@codename_inc/spectre 3.7.0 → 4.0.0

package/plugins/spectre-codex/skills/fix/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: "fix"
+description: "Investigate bugs & implement fixes - primary agent"
+user-invocable: true
+---
+
+# fix
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+# fix: Analyze bug and recommend fix
+
+## Description
+
+- **What** — Hypothesize root causes, investigate in parallel, recommend fix with logging
+- **Outcome** — Root cause identified, solution recommendation with `[🪳 TEMP]` debug logging
+
+## Variables
+
+### Dynamic Variables
+
+- `bug_report`: Error details, repro steps, context — (via ARGUMENTS: $ARGUMENTS)
+
+### Static Variables
+
+- `debug_prefix`: \[🪳 TEMP {TOPIC}\]
+
+## ARGUMENTS Input
+
+<ARGUMENTS> $ARGUMENTS </ARGUMENTS>
+
+## Step (1/5) - Gather Bug Context
+
+- **Action** — CheckInput: Verify bug report provided
+  - **If**: ARGUMENTS empty
+  - **Then**: Ask user for error message, repro steps, and relevant context
+  - **Else**: Use ARGUMENTS as bug report; request missing details if needed
+- **Wait** — Bug report with error details and repro steps
+
+## Step (2/5) - Generate Hypotheses
+
+- **Action** — Brainstorm: Reflect on 5-7 possible sources of the problem
+- **Action** — Prioritize: Distill to 1-2 most likely root causes
+  - Consider: the primary data flow for this component/module, recent changes, error patterns, stack traces, affected code paths
+
+## Step (3/5) - Investigate in Parallel
+
+- **Action** — DispatchAgents: Spawn parallel `@analyst` subagents to investigate top hypotheses
+  - Each agent gets one hypothesis to trace through codebase
+  - Agents search for: relevant code, recent commits, similar patterns, edge cases
+
+## Step (4/5) - Summarize Findings
+
+- **Action** — Synthesize: Summarize findings and solution recommendation
+  - Include: root cause, affected files, proposed fix approach
+  - **Rule**: Solution must include `{debug_prefix}` logging to verify fix and gather data if fix fails
+- **Action** — HoldForApproval: Present analysis; do NOT write code yet
+  - **Wait** — User approval before implementing fix
+
+## Step (5/5) - Execute
+
+- **Action** — Load TDD Skill: Load @spectre-tdd SKILL to use TDD
+- **Action** — Execute Fix: Add Logs and Implement Fix using TDD
+- **Action** — When finished, summarize what you delivered, including providing specific steps for the user to validate.
+
+## Next Steps
+
+Use the spectre-guide Skills and render the Next Steps Footer per the skill guidance

package/plugins/spectre-codex/skills/forget/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: "forget"
+description: "Clear session memory - archive all session files so next session starts fresh"
+user-invocable: true
+---
+
+# forget
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+
+# forget: Clear Session Memory
+
+## Description
+- **What** — Archive all session files (handoffs, todos, history) so the SessionStart hook doesn't auto-resume
+- **Outcome** — All session files moved to archive, user informed to start fresh session
+
+## Step (1/2) - Archive Session Logs
+
+- **Action** — ArchiveLogs: Move session logs to archive directory
+
+```bash
+branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)
+session_dir="docs/tasks/${branch}/session_logs"
+archive_dir="${session_dir}/archive"
+
+# Check if session logs exist
+if [ ! -d "$session_dir" ] || [ -z "$(ls -A ${session_dir}/*.json 2>/dev/null)" ]; then
+    echo "NO_SESSIONS"
+    exit 0
+fi
+
+# Create archive and move all session files
+mkdir -p "$archive_dir"
+mv ${session_dir}/*_handoff.json "$archive_dir/" 2>/dev/null || true
+mv ${session_dir}/*_todos.json "$archive_dir/" 2>/dev/null || true
+mv ${session_dir}/todos_history.json "$archive_dir/" 2>/dev/null || true
+
+# Count archived
+archived_count=$(ls -1 ${archive_dir}/*_handoff.json 2>/dev/null | wc -l | xargs)
+echo "ARCHIVED:${archived_count}"
+```
+
+## Step (2/2) - Confirm to User
+
+- **Action** — ConfirmCleared: Based on bash output, inform user
+
+  **If** output is `NO_SESSIONS`:
+  > No session logs found for this branch. Memory is already clear.
+
+  **Else** (output is `ARCHIVED:N`):
+  > ✓ Session memory cleared
+  >
+  > Archived {N} handoff file(s) to `docs/tasks/{branch}/session_logs/archive/`
+  >
+  > **Next**: Start a new session with `/clear` or close this terminal. Your next session will start fresh without auto-loaded context.
+
+## Success Criteria
+
+- [ ] Session logs directory checked for existence
+- [ ] All `*_handoff.json` files moved to `archive/` subdirectory
+- [ ] All `*_todos.json` files moved to `archive/` subdirectory
+- [ ] `todos_history.json` moved to `archive/` subdirectory
+- [ ] User informed of result (no sessions found OR count archived)
+- [ ] Clear instructions provided for starting fresh session

package/plugins/spectre-codex/skills/guide/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: "guide"
+description: "Use when rendering the Next Steps footer after any spectre command, suggesting next actions, or when users need guidance on which SPECTRE command to run."
+user-invocable: false
+---
+
+# SPECTRE Guide
+
+The single reference for how to use SPECTRE — for both humans and agents.
+
+## When to Load
+
+- After completing any spectre command (to render Next Steps footer)
+- When suggesting next actions to the user
+- When users ask "what command should I run?" or "how does SPECTRE work?"
+- When onboarding a new user to SPECTRE
+
+---
+
+## Core Philosophy
+
+SPECTRE exists because **ambiguity is death** for AI coding agents. When scope, UX, and plans are vague, you rely on the LLM to fill in the blanks — and that's how you end up with spaghetti code, conflicts, and AI slop.
+
+SPECTRE uses **structured workflows that generate canonical docs** — scope documents, UX specs, technical plans, task breakdowns — so you and your agent are aligned on exactly what's being built before a single line of code is written.
+
+The better the inputs, the better the outputs. SPECTRE makes it easy to provide great inputs.
+
+### Principles
+
+- **Great Inputs → Great Outputs** — specificity up front forces clarity
+- **Ambiguity is Death** — never let the LLM guess what you meant
+- **One Workflow, Every Feature, Any Size** — same process for a button or a backend rewrite
+- **Obvious > Clever** — boring solutions that work beat clever ones that break
+
+### Rapid Waterfall
+
+SPECTRE is essentially rapid waterfall: specificity up front → working code → iterate.
+
+AI agents are 10x better at working around *working* existing code. That's why they're great at refactors — they have an established baseline. SPECTRE gets you to working code faster, then you iterate.
+
+---
+
+## Getting Started
+
+### Installation
+
+```bash
+# In Claude Code
+/plugin marketplace add Codename-Inc/spectre
+/plugin install spectre@codename
+```
+
+### Your First Feature
+
+```plaintext
+scope
+```
+
+That's it. Start with scope, follow the prompts, and SPECTRE will guide you through the rest. Every command ends with "Next Steps" suggestions — you never have to remember what to run next.
+
+### Session Memory
+
+SPECTRE accumulates context across sessions:
+
+1. Turn off auto-compact in Claude Code `/config`
+2. Run `handoff` before session ends or when context window is getting full
+3. Run `/clear` — next session auto-loads your progress
+4. `forget` when switching gears to start fresh
+
+---
+
+## The SPECTRE Workflow
+
+**S**cope → **P**lan → **E**xecute → **C**lean → **T**est → **R**ebase → **E**valuate
+
+| Phase | Command | What It Does |
+|-------|---------|--------------|
+| **S**cope | `scope` | Define requirements, constraints, what's IN and OUT |
+| **P**lan | `plan` | Research codebase, create implementation plan + tasks |
+| **E**xecute | `execute` | Parallel subagent development in waves |
+| **C**lean | `clean` | Remove dead code, fix duplication, lint |
+| **T**est | `test` | Risk-aware test coverage (not brute-force 100%) |
+| **R**ebase | `rebase` | Safe merge preparation with conflict handling |
+| **E**valuate | `evaluate` | Architecture review + knowledge capture |
+
+You can use any command standalone — they don't require running in order.
+
+---
+
+## Typical Daily Usage
+
+This is how the creator of SPECTRE uses it daily:
+
+### Building a Feature (the main loop)
+
+1. **`scope`** — Get crisp on what's in/out. Non-negotiable unless it's a one-liner.
+   - If UX is unclear: run `ux_spec` first for user flows and components
+
+2. **`plan`** — Build a well-researched technical design or task set
+   - Once you have scope/plan/tasks, run `handoff` for a fresh context window
+
+3. **`execute`** — Parallel subagents work through the tasks
+   - Execute also calls code review and validation automatically
+   - When done, run `handoff` again for clean context
+
+4. **Manual testing + fixes** — Test the feature yourself
+   - Use Claude Code's built-in `/plan` mode for small fixes
+   - Use `fix` for structured debugging of tough bugs
+   - New scope needed? Run another `scope` cycle
+   - Use `handoff` liberally to keep context clean
+
+5. **`sweep`** — Commit accumulated changes with lint + test
+   - Groups changes logically with descriptive conventional commits
+
+6. **`clean`** then **`test`** — Deep cleanup and risk-aware testing
+
+7. **`rebase`** — Rebase onto parent branch, prepare for merge
+
+8. **`evaluate`** — Architecture review + capture knowledge for future sessions
+
+9. **Merge/PR** — Address PR comments, get it checked in
+
+### Quick Tasks (skip the ceremony)
+
+For small/medium changes (1-5 tasks):
+```plaintext
+quick_dev
+```
+Lightweight scope + plan that gets you to execution fast.
+
+### Autonomous Ship (zero gates)
+
+For low-complexity features/fixes where you trust the agent:
+```plaintext
+ship
+```
+Brain dump context, walk away, review the PR. Zero confirmation gates — scope, TDD, sweep, rebase, and PR creation happen autonomously.
+
+---
+
+## Command Reference
+
+### Phase: Scope — Discovery & Requirements
+
+| Command | When to Use |
+|---------|-------------|
+| `scope` | Starting any new feature — interactive scoping with IN/OUT boundaries |
+| `kickoff` | High-ambiguity projects — includes web research for best practices |
+| `research` | Need deep codebase understanding before planning |
+| `ux_spec` | UI-heavy features that need screen layouts, user flows, component states |
+
+### Phase: Plan — Research & Task Breakdown
+
+| Command | When to Use |
+|---------|-------------|
+| `plan` | Unified entry — researches, assesses complexity, routes to right workflow |
+| `create_plan` | Complex work needing architectural design before tasking |
+| `create_tasks` | Requirements/plan ready to become concrete tasks |
+| `plan_review` | Sanity check a plan/task list for over-engineering |
+
+### Phase: Execute — Development & Verification
+
+| Command | When to Use |
+|---------|-------------|
+| `execute` | Tasks exist, ready for coordinated multi-agent parallel execution |
+| `code_review` | Implementation complete, ready for in-depth review |
+| `validate` | Verify implementation against original scope requirement-by-requirement |
+| `create_test_guide` | Generate manual QA checklist based on features and risks |
+
+### Phase: Clean — Codebase Hygiene
+
+| Command | When to Use |
+|---------|-------------|
+| `clean` | Deep cleanup — dead code, duplication, artifacts |
+| `sweep` | Light pass — lint, test, descriptive commits for accumulated changes |
+
+### Phase: Test — Risk-Aware Coverage
+
+| Command | When to Use |
+|---------|-------------|
+| `test` | After changes — analyzes risk tiers (P0-P3), writes behavioral tests |
+
+### Phase: Rebase — Merge Preparation
+
+| Command | When to Use |
+|---------|-------------|
+| `rebase` | Rebase working branch onto target with conflict handling |
+
+### Phase: Evaluate — Review & Learn
+
+| Command | When to Use |
+|---------|-------------|
+| `evaluate` | Full evaluate — architecture review (background) + knowledge capture |
+| `learn` | Just capture knowledge from this session |
+| `architecture_review` | Just run the architecture review |
+| `recall {query}` | Find and load existing knowledge |
+
+### Session & Utilities
+
+| Command | When to Use |
+|---------|-------------|
+| `handoff` | Save session state — end of session, context full, switching gears |
+| `forget` | Clear memory, archive logs, start fresh |
+| `fix` | Structured debugging for tough bugs |
+| `quick_dev` | Lightweight scope + plan for small/medium tasks |
+| `ship` | Autonomous end-to-end: brain dump → scope → TDD → commit → rebase → PR |
+
+---
+
+## Quick Decision Tree
+
+**Starting a feature?**
+-> `scope` (always start here unless it's trivial)
+
+**Feature has complex UI?**
+-> `ux_spec` after scope, before plan
+
+**High ambiguity / new project?**
+-> `kickoff` (includes web research)
+
+**Need to understand code first?**
+-> `research`
+
+**Have scope, need plan?**
+-> `plan` (auto-routes based on complexity)
+
+**Have tasks, ready to build?**
+-> `execute`
+
+**Code complete, need review?**
+-> `code_review` then `validate`
+
+**Accumulated uncommitted changes?**
+-> `sweep` (light) or `clean` (deep)
+
+**Need test coverage?**
+-> `test`
+
+**Ready to merge?**
+-> `rebase`
+
+**Feature done?**
+-> `evaluate` (review + learn)
+
+**Ending session?**
+-> `handoff`
+
+**Switching contexts?**
+-> `forget`
+
+**Bug to fix?**
+-> `fix`
+
+**Small task, skip ceremony?**
+-> `quick_dev`
+
+**Low-complexity task, full autonomy?**
+-> `ship` (brain dump → PR, zero gates)
+
+---
+
+## Subagents
+
+SPECTRE dispatches these automatically — you don't need to call them directly. But `@web-research` is useful for ad-hoc web research (like mini deep-research).
+
+| Agent | Purpose | Model |
+|-------|---------|-------|
+| `@dev` | Implementation with MVP focus | sonnet |
+| `@analyst` | Understand how code works | haiku |
+| `@finder` | Find where code lives | haiku |
+| `@patterns` | Find reusable patterns | sonnet |
+| `@web-research` | Web research | sonnet |
+| `@tester` | Test automation | sonnet |
+| `@reviewer` | Independent code review | opus |
+| `@sync` | Session memory consolidation | haiku |
+
+---
+
+## Canonical Docs
+
+SPECTRE generates these documents in `docs/tasks/{branch_name}/`:
+
+| Document | Generated By | Purpose |
+|----------|-------------|---------|
+| `concepts/scope.md` | `scope` | What's IN and OUT |
+| `specs/ux.md` | `ux_spec` | User flows, components, interactions |
+| `specs/plan.md` | `create_plan` | Technical design and phasing |
+| `specs/tasks.md` | `create_tasks` | Concrete tasks with acceptance criteria |
+| `reviews/code_review.md` | `code_review` | Severity-based code review findings |
+| `validation/validation_gaps.md` | `validate` | Gaps between scope and implementation |
+| `testing/*_test_guide.md` | `create_test_guide` | Manual QA checklists |
+| `session_logs/*_handoff.json` | `handoff` | Session state snapshots |
+
+Keep these checked into git — they're the context in context engineering.
+
+---
+
+## For Agents: Footer Rendering
+
+**Always render a 60-column ASCII box footer at the end of command output.**
+
+### Template
+
+```
+╔══════════════════════════════════════════════════════════╗
+║ NEXT STEPS                                               ║
+╠══════════════════════════════════════════════════════════╣
+║ Phase: {phase} | {status} | {blockers}                   ║
+╟──────────────────────────────────────────────────────────╢
+║ Next — {concise recommendation; 1–2 lines max}           ║
+║                                                          ║
+║ Options:                                                 ║
+║ - {command or action} — {why}                   ║
+║ - {command or action} — {why}                   ║
+║ - {command or action} — {why}                   ║
+║   … up to 5 total; max 2 manual actions                  ║
+║                                                          ║
+║ Reply — {only if textual reply expected}                  ║
+╚══════════════════════════════════════════════════════════╝
+```
+
+### Status Values
+
+- `Active` — work in progress, no blockers
+- `Pending Input` — awaiting user decision/confirmation
+- `Blocked` — external dependency or unresolved issue
+- `On Hold` — paused, waiting for external factor
+- `Complete` — phase finished successfully
+
+### Footer Rules
+
+1. **Width**: Always 60 columns
+2. **Options**: Max 5 total, max 2 manual (non-slash) actions
+3. **Slash commands**: Use full `/spectre:` prefix
+4. **Manual actions**: No slash prefix (e.g., "Run manual tests")
+5. **Divider**: Include `╟──────╢` between status and next rows
+6. **Stage Awareness**: Only suggest commands that match current stage
+
+## For Agents: Slash Command Rules
+
+**CRITICAL:**
+
+1. **All SPECTRE commands use `/spectre:` prefix** (e.g., `scope`, `execute`)
+2. **Manual actions are NOT slash commands** (e.g., "Run tests", "Review PR feedback")
+3. **Never invent slash commands** — only suggest commands listed in this guide
+
+**Correct:**
+```
+scope — Interactive feature scoping
+execute — Parallel agent execution
+Run manual tests — Execute test guide checklist
+```
+
+**Incorrect:**
+```
+/scope — Missing spectre: prefix
+/run tests — Not a slash command
+/commit — Does not exist
+```

package/plugins/spectre-codex/skills/handoff/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: "handoff"
+description: "Save state snapshot to session_logs for session resume"
+user-invocable: true
+---
+
+# handoff
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+
+# handoff: Fast Session State Snapshot
+
+Generate progress update, gather context, output structured JSON for session resume. Output: `{timestamp}_handoff.json` in session_logs.
+
+**Performance Target**: 2-3 tool calls depending on session history
+
+**CRITICAL**: Do not narrate or explain what you're doing. No "Session count is 0, so..." or "Let me gather context...". Just execute the steps silently and output ONLY the final confirmation message. Every token matters at end of session.
+
+## ARGUMENTS
+
+<ARGUMENTS>
+$ARGUMENTS
+</ARGUMENTS>
+
+## Step 1: Gather Context (Single Bash Call)
+
+- **Action** — GatherContext: Run ONE bash command:
+
+```bash
+branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)
+mkdir -p "docs/tasks/${branch}/session_logs"
+
+# Count existing session logs for conditional flow
+session_count=$(ls docs/tasks/${branch}/session_logs/*_handoff.json 2>/dev/null | wc -l | xargs)
+
+beads_available=false
+beads_tasks='[]'
+beads_count=0
+
+if command -v bd &>/dev/null && bd doctor &>/dev/null; then
+  beads_available=true
+  open=$(bd list --label "$branch" --status open --json 2>/dev/null || echo '[]')
+  in_prog=$(bd list --label "$branch" --status in_progress --json 2>/dev/null || echo '[]')
+  blocked=$(bd list --label "$branch" --status blocked --json 2>/dev/null || echo '[]')
+  beads_tasks=$(echo "$open $in_prog $blocked" | jq -s 'add // []')
+  beads_count=$(echo "$beads_tasks" | jq 'length' 2>/dev/null || echo 0)
+fi
+
+cat << EOF
+{
+  "branch": "$branch",
+  "commit": "$(git rev-parse --short HEAD 2>/dev/null || echo unknown)",
+  "wip_count": $(git status --porcelain 2>/dev/null | wc -l | xargs),
+  "ts": "$(date +%Y-%m-%d-%H%M%S)",
+  "session_count": $session_count,
+  "beads_available": $beads_available,
+  "beads_count": $beads_count,
+  "beads": $beads_tasks
+}
+EOF
+```
+
+**Output**: JSON with branch, commit, wip_count, ts, session_count, beads_available, beads_count, beads[]
+
+## Step 2: Compose Handoff Data
+
+- **Action** — ComposeProgressUpdate: From session memory, compose using "WE" voice:
+
+  | Field | Required | Description |
+  |-------|----------|-------------|
+  | summary | ✓ | Slack-style paragraph a human would read |
+  | goal | ✓ | What we're building + success criteria |
+  | accomplished | ✓ | What we completed (2-5 bullets) |
+  | now | ✓ | **What you were actively working on when session ended** (critical!) |
+  | next_steps | ✓ | Upcoming work (2-4 bullets) |
+  | confidence | ✓ | high / medium / low |
+  | constraints | | Known constraints or assumptions |
+  | decisions | | Key decisions made (0-3 bullets) |
+  | blockers | | Things blocking progress |
+  | open_questions | | Questions needing answers |
+  | risks | | Identified risks |
+
+  **Tone**: "We finished the auth refactor and got tests passing. Hit a snag with OAuth callback - next we'll tackle session management."
+
+- **Action** — BuildWorkingSet: Capture active context:
+  - `key_files`: Files actively edited
+  - `active_ids`: Beads task IDs in progress
+  - `recent_commands`: Recent terminal commands (test, build, etc.)
+
+- **Action** — BuildBeadsTree (if available): From beads array, build hierarchy (epic → tasks → subtasks). Include task IDs for resume.
+
+## Step 3: Conditional Write
+
+Check `session_count` from Step 1:
+
+### If session_count = 0 (First Session)
+
+**Do not narrate. Just write the file and output the confirmation.**
+
+Write directly to `docs/tasks/{branch}/session_logs/{ts}_handoff.json`
+
+**JSON Schema**:
+```json
+{
+  "version": "1.1",
+  "timestamp": "{ts}",
+  "branch_name": "{branch}",
+  "task_name": "{ARGUMENTS or branch}",
+  "session_number": 1,
+  "progress_update": {
+    "summary": "string",
+    "goal": "string",
+    "accomplished": ["string"],
+    "now": "string (critical for resume)",
+    "next_steps": ["string"],
+    "confidence": "high|medium|low",
+    "constraints": ["string"],
+    "decisions": ["string"],
+    "blockers": ["string"],
+    "open_questions": ["string"],
+    "risks": ["string"]
+  },
+  "working_set": {
+    "key_files": ["path"],
+    "active_ids": ["bd-xxxxx"],
+    "recent_commands": ["command"]
+  },
+  "beads": {  // OMIT ENTIRE SECTION if beads_available=false OR beads_count=0
+    "available": true,
+    "workspace_label": "{branch}",
+    "task_count": "number",
+    "epic_id": "bd-xxxxx|null",
+    "epic_title": "string|null",
+    "tasks": [{"id", "title", "status", "type", "parent", "children", "labels"}]
+  },
+  "context": {
+    "wip_state": "uncommitted|clean",
+    "last_commit": "abc1234"
+  }
+}
+```
+
+Then respond: "✓ Handoff saved: {path}. First session recorded. Next session auto-resumes from this context."
+
+### If session_count >= 1 (Continuation)
+
+**Do not narrate. Just spawn the subagent and output the confirmation when done.**
+
+Spawn `@sesh:sync` subagent with the composed data:
+
+```
+<current_session>
+{full JSON object you composed above}
+</current_session>
+
+<session_logs_path>
+docs/tasks/{branch}/session_logs
+</session_logs_path>
+```
+
+The sync agent will:
+1. Read up to 3 previous handoff.json files
+2. Synthesize current context with historical arc
+3. Write the final `{ts}_handoff.json` with enriched continuity
+4. Return the file path
+
+Then respond: "✓ Handoff saved: {path}. Session {n} recorded with continuity from {x} previous sessions. Next session auto-resumes from this context."