@codename_inc/spectre 3.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joe Fernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,411 @@
+# SPECTRE: A Workflow for Product Builders
+
+**S**cope → **P**lan → **E**xecute → **C**lean → **T**est → **R**ebase → **E**valuate
+
+SPECTRE is a slash command based workflow for Claude Code designed to help you do ONE THING more, faster, and with higher quality.
+
+**🚀 Ship Product Features**
+
+SPECTRE's workflow covers the complete software development lifecycle - from scoping a feature, finalizing user flows, writing the technical design, generating tasks, executing the tasks, code review, validating the work, cleaning up and testing the work, and finally generating documentation as Skills your agent auto-loads when relevant.
+
+It has been tested on brand new codebases and codebases with hundreds of thousands of lines of code. Its been tested building websites, react native apps, native desktop apps, and personal software.
+
+**SPECTRE helps you get higher quality and more consistent results from your coding agent, while they work autonomously for much longer, so 10-100x'ing your typical output feels *easy* and more importantly, *repeatable.***
+
+![SPECTRE hero](./assets/images/spectre-hero.png)
+
+## ⚡ Quick Start
+
+### Within Claude Code
+
+```bash
+# Add marketplace and install
+/plugin marketplace add Codename-Inc/spectre
+/plugin install spectre@codename
+```
+
+Then start building:
+
+```plaintext
+/spectre:scope
+```
+
+That's it. You just start with 1 command to build features.
+
+### Within Codex
+
+```bash
+npx spectre install codex
+```
+
+When prompted, choose `project` to install into the current repo's `.codex`, or `user` to install into `~/.codex`.
+
+If you choose `project`, run `codex` from that repo.
+
+If you choose `user`, restart or open your normal Codex session.
+
+Then run a Spectre command such as:
+
+```plaintext
+spectre-scope
+```
+
+Current Codex behavior:
+
+- `user` scope installs Spectre workflow skills, runtime, agents, hooks, and shared skills under `~/.codex`
+- `project` scope installs the same Codex home structure inside `./.codex`
+- project installs create `.spectre/manifest.json` and project-local Codex config
+- session continuity uses Codex's official SessionStart hook for the visible status line and keeps the latest handoff in a managed `AGENTS.override.md` block
+- learned project skills still live under `.agents/skills/` and are synced into Codex config
+
+Capability matrix: [`docs/codex-capability-matrix.md`](./docs/codex-capability-matrix.md)
+Session continuity deep dive: [`docs/codex-sessionstart-memory.md`](./docs/codex-sessionstart-memory.md)
+
+![SPECTRE scope command](./assets/images/spectre-scope.png)
+
+## 🔁 How It Works
+
+- run one of the kickoff prompts in Claude Code - `/spectre:scope` is the main command for building new features, but also `/spectre:kickoff` for high ambiguity new features (includes web research), `/spectre:research` for codebase research "how might we build …” style Qs, or `/spectre:ux_spec` to define user flows, components, and layout for a new feature.
+
+- follow the prompts/instructions to create the related canonical document and Claude Code will suggest the next step in the SPECTRE workflow automatically (e.g., going from `scope` to `plan` to `tasks` and so on)
+
+- turn off auto-compact in Claude Code settings (`/config`) and run `/spectre:handoff` when the context window is getting full, then run `/clear` to start the next session. (`/spectre:forget` when you are switching gears)
+
+- SPECTRE saves canonical docs to a `docs/tasks/{topic}/specs` directory, and status updates from `/spectre:handoff` to `docs/tasks/{topic}/session_logs` directory. We recommend keeping this directory checked into git to be able to reference docs in the future.
+
+- thats it. scope features, plan features, build features, clean up/test features, document features, learn from features, repeat.
+
+## 🎯 Core SPECTRE Principles
+
+- Great Inputs → Great Outputs
+- Ambiguity is Death
+- One Workflow, Every Feature, Any Size, Any Codebase
+- Obvious > Clever
+
+## 👻 SPECTRE Purpose
+
+AI coding is changing product development, but why is it that Claude Code can still go off the rails? Why is it that some developers claim AI has 100x'd their output, while others still complain about the quality of the code it generates?
+
+Let me introduce you to a very simple concept that you need to drill into your head. With coding agents:
+
+> ### **💀 AMBIGUITY IS DEATH.**
+
+When the scope, ux, and plan are ambiguous, you must rely on the LLM to fill in the blanks. And while sometimes you can get lucky - especially for smaller features - for any *real* technology or product work, ambiguity is how you end up with spaghetti code, conflicts, and AI slop.
+
+LLMs need specificity. And typically, providing the right level of specificity is a lot of work. Just think about the most detailed spec or technical design you’ve ever written. Takes days and sometimes weeks.
+
+BUT --- you can use LLMs to make it EASY to provide that specificity. And that is exactly what SPECTRE does.
+
+### ✅ Workflows = Easy Button
+
+Prompt based workflows that generate canonical docs that you and your Agents are aligned on are how you get the best, highest quality, and most consistent results from AI Coding Agents.
+
+They provide the necessary context, detail, and structure for the agent to ask the right questions, investigate the right details, and generate the right requirements, plans, tasks, code, tests, and more.
+
+The better your prompt based workflows, the lower the ambiguity, the more AI can take on, the longer AI can work autonomously, the more easily you can multi-task, and suddenly you are 100x'ing your output.
+
+## 📄 Canonical Docs
+
+As a former PM I've lived the value of [Canonical Docs](https://naomi.com/canonical-everything-c85441a84e70) (shout out Naomi Gleit). The reasons they work for Humans are the same reasons they work with AI Agents (see 💀 Ambiguity is Death)
+
+In SPECTRE, the **structured workflows** generate some combination of the following canonical docs stored in `docs/tasks/{topic/feature}/specs`
+
+- `scope.md` - what are we building and importantly what are we NOT building
+- `ux.md` - the core user flows and components/layouts/interactions
+- `plan.md` - high level technical design and phasing
+- `tasks.md `- specific parent & sub-tasks to execute
+- `code_review.md` - prioritized code review feedback
+- `gaps.md` - task list of gaps identified from validation
+- `.claude/skills/{feature_name}/skill.md` - a skill for agents to auto-reference the work
+
+Not all are required. Sometimes I have scope.md and then use Claude Code's plan mode. Sometimes I have a ux.md and a tasks.md. The key thing to remember is that docs are the context in context engineering.
+
+### 💧 So.... Waterfall?
+
+Yeah basically Rapid Waterfall.
+
+Specificity up front forces clarity, reduces ambiguity, and leads to better 1st pass results.
+
+THEN -- you can iterate on the feature set, ux, architecture, etc. at lightning speed. AI coding agents are 10x better at working around *working* existing code. It's why they are so good at refactors. Because they are working with a working established baseline.
+
+**Workflows make it easier and faster to get to working code.**
+
+From there, you can iterate and adapt before you ship.
+
+## 📖 Background & Philosophy
+
+## About
+
+SPECTRE is the result of over 12 months of daily Claude Code use.
+
+These are the *actual* prompts I use and iterate upon non stop every day to build products.
+
+With SPECTRE, I built a React Native based AI Agent + GPS Rangefinder for Golfers (New June (in closed Alpha)) and a 250k line Tauri/Rust/React desktop application called Subspace (in open Beta - https://www.subspace.build).
+
+## 💡 Why
+
+I created SPECTRE because I wanted:
+
+- a repeatable daily driver workflow that works on brand new projects, and large existing codebases.
+
+- a single workflow that works on both small & big features without being overwhelmed with process
+
+- a workflow that delivers robust engineering plans when needed, or a concise set of tasks if not
+
+- hands on planning but hands off execution
+
+- higher quality INPUT with LESS WORK so i can ensure the outputs are more aligned with my vision
+
+- a workflow that lets Agents learn my codebase, features, patterns, bugs, so I don't have to remember everything
+
+- ***stupid. simple. memory.*** agent sessions are aware of the ongoing thread of work (/spectre:handoff)
+
+### My Workflow Iteration Process
+
+I improve these prompts daily, and I didn't just prompt Claude Code to generate these prompts. I iterated over many months, adjusting the prompts based on both the user experience of using them, and the quality of results that I got.
+
+For example:
+
+- I iterated on /spectre:scope until I felt like the types of questions actually help me get clear on what I'm building, without asking questions that it could easily get from codebase research
+- I iterated on the /spectre:execute workflow until it successfully delivered large tasks in a single context window using subagents that deliver completion reports to handoff to the next subagents, use TDD effectively, and autonomously adapt the tasks based on what was discovered DURING development instead of blindly
+- I iterated on the /spectre:clean and /spectre:test workflows until it felt automatic that we were sticking to our linting rules, every new feature was well tested/covered, the commits were grouped logically with the appropriate amount of detail.
+- I iterated on the /spectre:evaluate learning workflow until 1) the agent automatically reached for the skills generated at the start of every conversation, 2) captured the *right* details and insights, and 3) proactively updated relevant skills as we make changes and learn more.
+- I iterated on the /spectre:handoff workflow until the status update had the appropriate detail/context, and worked perfectly if I'm working across MANY sessions or just one.
+
+SPECTRE made products like New June and Subspace possible, and it is making it possible for me, an ex-Meta, ex-Amazon Technical Product Manager to build, ship, and iterate on products 100x the complexity of anything I've ever built in the past.
+
+## 🔄 The SPECTRE Workflow
+
+If you start with /scope, your agent will guide you through the rest of the steps automatically.
+
+| Phase | Command | What It Does |
+| --- | --- | --- |
+| **S**cope | `/spectre:scope` | Define requirements, constraints, success criteria |
+| **P**lan | `/spectre:plan` | Research codebase, create implementation plan |
+| **E**xecute | `/spectre:execute` | Parallel implementation with wave-based delivery |
+| **C**lean | `/spectre:clean` | Remove dead code, lint, format |
+| **T**est | `/spectre:test` | Risk-aware test coverage |
+| **R**ebase | `/spectre:rebase` | Safe merge preparation with conflict handling |
+| **E**valuate | `/spectre:evaluate` | Architecture review + knowledge capture |
+
+Each command ends with "Next Steps" suggestions, so you always know what prompt to run next — you don't have to remember what the prompts are, which is one thing that kills me about many other Spec Driven Development workflows.
+
+You can use *any* of the commands in any sequence you want - they are good standalone too. More on my typical daily usage below.
+
+## 🧠 SPECTRE Session Memory
+
+SPECTRE maintains and accumulates context across sessions when you use the /spectre:handoff command. To get the most from SPECTRE's Session Memory, we recommend that you:
+
+1. turn off auto-compact in Claude Code /config settings, and
+
+2. run /spectre:handoff liberally when you are switching gears or the context window is getting north of 160k tokens.
+
+### How It Works
+
+When you run /spectre:handoff, a status report will get generated for that session, and automatically loaded into your context window for the next session. You'll see a nice summary of the status when you run /clear.
+
+If you already had previous sessions, a subagent (@spectre:sync) will review the last 3 status updates and merge into a single continuous session memory.
+
+Voila -- trailing 3 session memory snapshots.
+
+If you want to start fresh — /spectre:forget archives the session_logs.
+
+```plaintext
+/spectre:handoff   # Save progress before session ends
+/spectre:forget    # Clear memory for fresh start
+```
+
+## 🧬 SPECTRE Evaluate
+
+The more I used SPECTRE and the faster I could build, the more frequently I found myself wanting to reference past work. Debugging sessions, a new architectural pattern, or how a feature works/was built.
+
+SPECTRE Evaluate combines **architecture review** with **knowledge capture** — reviewing what you built and learning from it in one step.
+
+### How It Works
+
+`/spectre:evaluate` runs two things in parallel:
+
+1. **Architecture review** — dispatches an Opus 4.6 subagent in the background to produce a principal-level architecture review of your completed work
+2. **Learn** — captures durable project knowledge (patterns, gotchas, decisions) into re-usable skills that **auto-load in future sessions**
+
+### The Hook + Skill Loop
+
+What is great about SPECTRE's learning system, is that Claude Code automatically loads skills that are relevant. We do this with a 'coercion' technique I borrowed from Jesse Vincent's great Superpowers skill.
+
+1. **SessionStart hook** — every time you start a conversation, SPECTRE's hook reads your project's knowledge registry and injects it into context. Claude now *knows what it knows* before you type a single word.
+
+2. **Skill auto-loading** — when your task matches a trigger word from the registry (e.g., you mention "auth" and there's a `feature-auth-flows` skill), Claude loads the full skill *before* searching the codebase. No wasted tool calls rediscovering what's already documented.
+
+The result: knowledge compounds across sessions instead of resetting to zero. The more you learn, the faster and more accurate every future session becomes.
+
+### What Gets Captured
+
+| Category | Example |
+| --- | --- |
+| **Gotchas** | "The websocket reconnect silently fails if..." |
+| **Decisions** | "We chose SQLite over Postgres because..." |
+| **Features** | Architecture dossiers — key files, flows, common tasks |
+| **Patterns** | Reusable solutions established across the codebase |
+| **Procedures** | Multi-step processes like deploy, release, migrate |
+
+You can also run these independently:
+
+```plaintext
+/spectre:evaluate              # Architecture review + learn (the full evaluate step)
+/spectre:learn                 # Just capture knowledge from this session
+/spectre:architecture_review   # Just run the architecture review
+/spectre:recall auth           # Find and load existing knowledge about auth
+```
+
+## 🤖 Subagents
+
+SPECTRE dispatches specialized subagents for different tasks:
+
+NOTE: You don't even need to know that these subagents exist. The prompts instruct Claude Code to call them automatically.
+
+Although I do sometimes use @spectre:web-research for web research. It's like mini deep-research.
+
+| Agent | Purpose |
+| --- | --- |
+| `@spectre:dev` | Implementation with MVP focus |
+| `@spectre:analyst` | Understand how code works |
+| `@spectre:finder` | Find where code lives |
+| `@spectre:patterns` | Find reusable patterns |
+| `@spectre:web-research` | Web research |
+| `@spectre:tester` | Test automation |
+| `@spectre:reviewer` | Independent code review |
+
+## 🛠️ How I Typically use SPECTRE
+
+99.9% of my day is spent using SPECTRE exactly like this.
+
+- start /spectre:scope to get crisp on what's in/out. this is non-negotiable unless the feature is a one line ask.
+
+  - if the feature's ux/user flow is unclear to me, or I want to make sure to really nail it, i run /spectre:ux_spec. Its similar to /spectre:scope but focuses on getting clear on the core user flows.
+
+- /spectre:plan to build out a well researched technical design or set of tasks
+
+  - once i have scope/plan/tasks, I typically run /spectre:handoff to get a fresh context window with awareness of what we're working on.
+
+- then run /spectre:execute to use parallel subagents to work through the tasks. Execute is a meta prompt that also calls /spectre:code_review and /spectre:validate.
+
+  - side note /spectre:validate is a killer prompt. It breaks down the original tasks and dispatches subagents to verify. find stuff missing all the time with this.
+
+  - when initial execution is complete, i run another /spectre:handoff to get the context window clean for fixes/touch ups.
+
+- for low-complexity tasks where I trust the agent end-to-end, I use /spectre:ship. Brain dump what I want, walk away, and review the PR. It autonomously scopes, implements with TDD, sweeps, rebases, and opens a PR — zero confirmation gates.
+
+- From here — I do a bunch of manual testing and fixing.
+
+  - I largely use Claude Code's built in /plan mode for fixes in this phase.
+
+  - If there is a bug that can't easily be solved, i use the /spectre:fix prompt for a more structured debugging approach.
+
+  - If something new comes up, or if the scope is not what I'd hoped, I run a new /scope cycle from within the project.
+
+  - I liberally use /spectre:handoff here to keep context windows clean as I work through issues, and keep the sessions on track with the progress we're making.
+
+- During the process of manual testing/fixing, I typically accumulate uncommitted changes. /spectre:sweep will get your changes committed, while
+
+  - running and addressing lint
+  - running tests and related tests on touched files
+  - finding obvious dead code/AI slop, and
+  - grouping changes logically with descriptive conventional commits
+
+- Once wrapping up, /spectre:clean is a much deeper cleanup that dispatches subagents to find dead code, duplicates, verifies, lint, commits any stragglers, etc.
+
+- Then /spectre:test does deep analysis and dispatches subagents to write tests based on a risk-adjusted framework focusing on behavior not implementation details.
+
+- Once cleaned/tested — /spectre:rebase works great to rebase onto your parent branch, but obviously you do you with your release flow. From here I create PR/merge or directly merge depending on the task.
+
+- Finally, I run /spectre:evaluate to get an architecture review and capture any knowledge worth preserving — patterns, gotchas, decisions. This builds institutional memory that loads automatically in future sessions.
+
+- From here, merge/PR, address any PR comments, etc. and get the feature checked back in.
+
+## 📋 Slash Command Reference
+
+### Core Workflow
+
+| Command | Description |
+| --- | --- |
+| `/spectre:scope` | Interactive feature scoping |
+| `/spectre:plan` | Research codebase, create implementation plan |
+| `/spectre:execute` | Wave-based parallel execution with code review |
+| `/spectre:clean` | Code cleanup and quality gates |
+| `/spectre:test` | Risk-aware test coverage |
+| `/spectre:rebase` | Safe rebase with conflict handling |
+| `/spectre:evaluate` | Architecture review + knowledge capture |
+
+### Quick Start
+
+| Command | Description |
+| --- | --- |
+| `/spectre:quick_dev` | Scope + plan for small/medium tasks |
+| `/spectre:ship` | Autonomous end-to-end: brain dump → scope → TDD → rebase → PR |
+
+### Discovery & Research
+
+| Command | Description |
+| --- | --- |
+| `/spectre:kickoff` | Deep research for high-ambiguity features |
+| `/spectre:research` | Parallel codebase research |
+
+### Session Memory
+
+| Command | Description |
+| --- | --- |
+| `/spectre:handoff` | Save session state snapshot |
+| `/spectre:forget` | Clear memory, archive logs |
+
+### Utilities
+
+These are situational commands.
+
+I use /spectre:fix for pretty much all bugs I run into.
+
+| Command | Description |
+| --- | --- |
+| `/spectre:sweep` | Light cleanup pass — lint, test, descriptive commits |
+| `/spectre:learn` | Capture knowledge for future sessions |
+| `/spectre:ux_spec` | UX specification for UI-heavy features |
+| `/spectre:fix` | Investigate bugs & implement fixes |
+
+## 📁 Repository Structure
+
+```plaintext
+spectre/
+├── .claude-plugin/
+│   └── marketplace.json  # Marketplace registration
+├── plugins/
+│   └── spectre/
+│       ├── .claude-plugin/
+│       │   └── plugin.json   # Plugin manifest
+│       ├── commands/         # Slash commands
+│       ├── agents/           # Subagent definitions
+│       ├── hooks/            # Session memory hooks
+│       └── skills/           # Skills
+├── scripts/              # Release & utility scripts
+└── CLAUDE.md
+```
+
+## Updating
+
+Skills update automatically when you update the plugin:
+
+`/plugin update spectre`
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Support and/or Feedback
+
+Issues: https://github.com/codename-inc/spectre/issues
+
+Email: [joe@bycodename.com](mailto:joe@bycodename.com?subject=Spectre%20Feedback)
+
+Socials:
+
+- Threads: [@joenandez](https://www.threads.com/joenandez)
+- X: [@joenandez](https://www.x.com/joenandez)
+- LinkedIn: [@joefernandez](https://www.linkedin.com/in/joefernandez/)

package/bin/spectre.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from '../src/main.js';
+
+main(process.argv.slice(2)).catch(error => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@codename_inc/spectre",
+  "version": "3.7.0",
+  "type": "module",
+  "bin": {
+    "spectre": "./bin/spectre.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "plugins",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test src/**/*.test.js plugins/spectre/hooks/scripts/test_*.cjs",
+    "tokens": "node scripts/count-tokens.js",
+    "release": "node scripts/release.js"
+  },
+  "dependencies": {
+    "@anthropic-ai/tokenizer": "^0.0.4"
+  }
+}

package/plugins/spectre/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "spectre",
+  "version": "3.7.0",
+  "description": "Agentic coding workflow with session memory. spectre guides you through Scope, Plan, Execute, Clean, Test, Rebase, and Extract phases."
+}

package/plugins/spectre/agents/analyst.md

@@ -0,0 +1,122 @@
+---
+name: analyst
+description: Analyzes codebase implementation details. Call the analyst agent when you need to find detailed information about specific components. As always, the more detailed your request prompt, the better! :)
+tools: Read, Grep, Glob, LS
+color: white
+model: claude-sonnet-4-6
+---
+
+You are a specialist at understanding HOW code works. Your job is to analyze implementation details, trace data flow, and explain technical workings with precise file:line references.
+
+## Core Responsibilities
+
+1. **Analyze Implementation Details**
+   - Read specific files to understand logic
+   - Identify key functions and their purposes
+   - Trace method calls and data transformations
+   - Note important algorithms or patterns
+
+2. **Trace Data Flow**
+   - Follow data from entry to exit points
+   - Map transformations and validations
+   - Identify state changes and side effects
+   - Document API contracts between components
+
+3. **Identify Architectural Patterns**
+   - Recognize design patterns in use
+   - Note architectural decisions
+   - Identify conventions and best practices
+   - Find integration points between systems
+
+## Analysis Strategy
+
+### Step 1: Read Entry Points
+- Start with main files mentioned in the request
+- Look for exports, public methods, or route handlers
+- Identify the "surface area" of the component
+
+### Step 2: Follow the Code Path
+- Trace function calls step by step
+- Read each file involved in the flow
+- Note where data is transformed
+- Identify external dependencies
+- Take time to ultrathink about how all these pieces connect and interact
+
+### Step 3: Understand Key Logic
+- Focus on business logic, not boilerplate
+- Identify validation, transformation, error handling
+- Note any complex algorithms or calculations
+- Look for configuration or feature flags
+
+## Output Format
+
+Structure your analysis like this:
+
+```
+## Analysis: [Feature/Component Name]
+
+### Overview
+[2-3 sentence summary of how it works]
+
+### Entry Points
+- `api/routes.js:45` - POST /webhooks endpoint
+- `handlers/webhook.js:12` - handleWebhook() function
+
+### Core Implementation
+
+#### 1. Request Validation (`handlers/webhook.js:15-32`)
+- Validates signature using HMAC-SHA256
+- Checks timestamp to prevent replay attacks
+- Returns 401 if validation fails
+
+#### 2. Data Processing (`services/webhook-processor.js:8-45`)
+- Parses webhook payload at line 10
+- Transforms data structure at line 23
+- Queues for async processing at line 40
+
+#### 3. State Management (`stores/webhook-store.js:55-89`)
+- Stores webhook in database with status 'pending'
+- Updates status after processing
+- Implements retry logic for failures
+
+### Data Flow
+1. Request arrives at `api/routes.js:45`
+2. Routed to `handlers/webhook.js:12`
+3. Validation at `handlers/webhook.js:15-32`
+4. Processing at `services/webhook-processor.js:8`
+5. Storage at `stores/webhook-store.js:55`
+
+### Key Patterns
+- **Factory Pattern**: WebhookProcessor created via factory at `factories/processor.js:20`
+- **Repository Pattern**: Data access abstracted in `stores/webhook-store.js`
+- **Middleware Chain**: Validation middleware at `middleware/auth.js:30`
+
+### Configuration
+- Webhook secret from `config/webhooks.js:5`
+- Retry settings at `config/webhooks.js:12-18`
+- Feature flags checked at `utils/features.js:23`
+
+### Error Handling
+- Validation errors return 401 (`handlers/webhook.js:28`)
+- Processing errors trigger retry (`services/webhook-processor.js:52`)
+- Failed webhooks logged to `logs/webhook-errors.log`
+```
+
+## Important Guidelines
+
+- **Always include file:line references** for claims
+- **Read files thoroughly** before making statements
+- **Trace actual code paths** don't assume
+- **Focus on "how"** not "what" or "why"
+- **Be precise** about function names and variables
+- **Note exact transformations** with before/after
+
+## What NOT to Do
+
+- Don't guess about implementation
+- Don't skip error handling or edge cases
+- Don't ignore configuration or dependencies
+- Don't make architectural recommendations
+- Don't analyze code quality or suggest improvements
+
+Remember: You're explaining HOW the code currently works, with surgical precision and exact references. Help users understand the implementation as it exists today.

package/plugins/spectre/agents/dev.md

@@ -0,0 +1,70 @@
+---
+name: dev
+description: Implementation specialist for writing and refactoring code. Focuses on simplicity, readability, MVP-first delivery. Use when writing new features, refactoring, or implementing tasks.
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: claude-sonnet-4-6
+color: red
+---
+
+You are an expert software engineer. Your philosophy: **simple, readable, maintainable code that ships**.
+
+## Constraints
+
+- **MVP-first**: Implement only what's needed now—no future-proofing
+- **Follow existing patterns**: Study similar code in the codebase first
+- **Simplest solution wins**: When choosing between approaches, pick the simpler one
+- **No enterprise abstractions**: Avoid complex patterns, frameworks, or unnecessary layers
+
+## When Writing Code
+
+1. Find similar implementations in the codebase—match their style
+2. Build the minimal working version first
+3. Use descriptive names that eliminate need for comments
+4. Handle errors gracefully with meaningful messages
+5. Add comments only for the "why", not the "what"
+
+## When Refactoring
+
+1. Eliminate unnecessary complexity
+2. Improve naming to enhance readability
+3. Remove redundant comments
+4. Simplify control flow and reduce nesting
+
+## Task Execution
+
+**Work only on assigned tasks.** Do not:
+- Add features not explicitly requested
+- Optimize or refactor outside assigned scope
+- Implement "nice-to-have" functionality
+
+## Completion Protocol
+
+**You MUST deliver a Completion Report when finished.** This report is your primary output—the parent agent and downstream agents depend on it to coordinate work and avoid rework.
+
+**You are not a blind executor.** During implementation, you will discover things the plan didn't anticipate. Your job is to surface these learnings.
+
+**Before writing your report, assess:**
+- Did implementation reveal constraints the plan missed?
+- Are downstream tasks affected by what you learned?
+- Should the parent agent reconsider any upcoming work?
+
+**Scope Signal** (required):
+
+| Signal | Meaning |
+|--------|---------|
+| ⚪ None | Proceeded as expected—no impact on future tasks |
+| 🟡 Minor | Small adjustments may be needed to future tasks |
+| 🟠 Significant | Learnings that likely affect the plan |
+| 🔴 Blocking | Stop—future tasks need re-evaluation |
+
+**Required Completion Report:**
+```
+## Completion Report
+
+**Completed:** [Tasks finished - exact titles]
+**Files changed:** [Path + brief description for each]
+**Scope signal:** [⚪/🟡/🟠/🔴] - [Justification]
+**Discoveries:** [What wasn't obvious from the spec?]
+**Guidance:** [What should downstream tasks know?]
+**Scope compliance:** ✅ No unauthorized extras added
+```