spectre-guide

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

# In Claude Code
/plugin marketplace add Codename-Inc/spectre
/plugin install spectre@codename

Your First Feature

spectre-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 spectre-handoff before session ends or when context window is getting full
3. Run /clear — next session auto-loads your progress
4. spectre-forget when switching gears to start fresh

---

The SPECTRE Workflow

Scope → Plan → Execute → Clean → Test → Rebase → Evaluate

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. spectre-scope — Get crisp on what's in/out. Non-negotiable unless it's a one-liner.

   • If UX is unclear: run spectre-ux first for user flows and components

2. spectre-plan — Build a well-researched technical design or task set

   • Once you have scope/plan/tasks, run spectre-handoff for a fresh context window

3. spectre-execute — Parallel subagents work through the tasks

   • Execute also calls code review and validation automatically
   • When done, run spectre-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 spectre-fix for structured debugging of tough bugs
   • New scope needed? Run another spectre-scope cycle
   • Use spectre-handoff liberally to keep context clean

5. spectre-sweep — Commit accumulated changes with lint + test

   • Groups changes logically with descriptive conventional commits

6. spectre-clean then spectre-test — Deep cleanup and risk-aware testing

7. spectre-rebase — Rebase onto parent branch, prepare for merge

8. spectre-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):

spectre-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:

spectre-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

Phase: Plan — Research & Task Breakdown

Phase: Execute — Development & Verification

Phase: Clean — Codebase Hygiene

Phase: Test — Risk-Aware Coverage

Phase: Rebase — Merge Preparation

Phase: Evaluate — Review & Learn

Session & Utilities

---

Quick Decision Tree

Starting a feature? -> spectre-scope (always start here unless it's trivial)

Feature has complex UI? -> spectre-ux after scope, before plan

High ambiguity / new project? -> spectre-kickoff (includes web research)

Need to understand code first? -> spectre-research

Have scope, need plan? -> spectre-plan (auto-routes based on complexity)

Have tasks, ready to build? -> spectre-execute

Code complete, need review? -> spectre-code_review then spectre-validate

Accumulated uncommitted changes? -> spectre-sweep (light) or spectre-clean (deep)

Need test coverage? -> spectre-test

Ready to merge? -> spectre-rebase

Feature done? -> spectre-evaluate (review + learn)

Ending session? -> spectre-handoff

Switching contexts? -> spectre-forget

Bug to fix? -> spectre-fix

Small task, skip ceremony? -> spectre-quick_dev

Low-complexity task, full autonomy? -> spectre-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).

---

Canonical Docs

SPECTRE generates these documents in docs/tasks/{branch_name}/:

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:                                                 ║
║ - {spectre-command or action} — {why}                   ║
║ - {spectre-command or action} — {why}                   ║
║ - {spectre-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., spectre-scope, spectre-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:

spectre-scope — Interactive feature scoping
spectre-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