@codename_inc/spectre 3.7.0 → 4.0.0

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

@@ -0,0 +1,211 @@
+---
+name: "plan"
+description: "👻 | Unified planning entry point - researches, assesses complexity, routes to workflow - primary agent"
+user-invocable: true
+---
+
+# plan
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+# plan: Intelligent Planning Router
+
+## Description
+
+- **What** — Research codebase, assess complexity, route to appropriate workflow (direct tasks or plan-first)
+- **Outcome** — Detailed task breakdown ready for execution
+
+## ARGUMENTS Input
+
+<ARGUMENTS> $ARGUMENTS </ARGUMENTS>
+
+## MANDATORY COMPLIANCE RULES
+
+> **⚠️ NON-NEGOTIABLE**: This workflow MUST invoke nested workflows via the Skill tool. Failure to invoke `Skill(create_plan)` and `Skill(create_tasks)` (Claude slash route: `create_plan` and `create_tasks`) is a critical error. Do NOT summarize, describe, or skip these workflows. INVOKE THEM.
+
+**After ANY user conversation or questions:**
+
+1. Re-read this prompt from Step 4
+2. Determine where you are in the workflow
+3. Execute the next required Skill invocation
+
+**You MUST call these skills (not describe them):**
+
+- Use the **Skill** tool with `skill: "spectre-create_plan"` and `args: "{path} --depth {tier}"` — generates plan.md
+- Use the **Skill** tool with `skill: "spectre-create_tasks"` and `args: "{path}"` — generates tasks.md
+
+## Instructions
+
+- Research before routing; present architectural options for user buy-in
+- Route based on hard-stops and clarity, not point-scoring
+- Never overwrite existing `tasks.md` or `plan.md` — use scoped names
+
+## Step 1 - Research Codebase
+
+- **Action** — DetermineOutputDir:
+
+  - `OUT_DIR=docs/tasks/{branch_name}` (or user-specified)
+  - `mkdir -p "${OUT_DIR}"`
+
+- **Action** — ScanExistingContext: Read all existing artifacts in `{OUT_DIR}/ (if you haven’t already)` and assess coverage across 4 dimensions.
+
+  Scan for: `task_context.md`, `specs/plan.md`, `concepts/scope.md`, `research/*.md`
+
+  | Dimension | Covered if artifact contains... | Covered by |
+  | --- | --- | --- |
+  | **File locations** | Specific file paths relevant to this feature, entry points, config files | `@finder` |
+  | **Code understanding** | Data flow analysis, dependency tracing, how current code works with file:line refs | `@analyst` |
+  | **Codebase patterns** | Similar implementations found in codebase, reusable components, naming/style conventions | `@patterns` |
+  | **External research** | Best practices, libraries/frameworks, prior art, common pitfalls with source links | `@web-research` |
+
+  For each dimension, assess: **covered** (artifact has substantive findings for this feature) or **gap** (missing, superficial, or about a different feature).
+
+- **Action** — DispatchResearch: Spawn agents **only for dimensions marked as gaps**. Skip agents whose dimensions are already covered. Each prompt must include the feature/problem description from ARGUMENTS so the agent has full context.
+
+  - **If all 4 covered** → skip to SaveResearch (merge existing findings into task_context.md if scattered across files)
+
+  - **If gaps exist** → spawn only the needed agents in parallel:
+
+  - `@finder` *(if File locations = gap)* — "Find all files, components, entry points, routes, and configuration related to \[feature/problem\]. Include: (1) files that would need to be modified or extended, (2) entry points where this feature connects to the system (routes, handlers, event listeners, CLI commands), (3) configuration files, schemas, or migrations that may be affected, (4) test files covering the affected areas. Return file paths organized by relevance."
+
+  - `@analyst` *(if Code understanding = gap)* — "Analyze how the code paths related to \[feature/problem\] work end-to-end. Trace: (1) data flow from input through processing to storage and output, (2) key dependencies and how components interact, (3) state management patterns and data access methods in the affected areas, (4) error handling and edge cases in the current implementation. Return findings with specific file:line references."
+
+  - `@patterns` *(if Codebase patterns = gap)* — "Find existing implementations in this codebase that are similar to \[feature/problem\] and could serve as a reference. Look for: (1) analogous features already built — how were they structured?, (2) reusable components, utilities, or abstractions we should leverage, (3) conventions for naming, file organization, and code style in this area, (4) testing patterns used for similar features. Return concrete code examples with file:line references."
+
+  - `@web-research` *(if External research = gap)* — "Research best practices, proven patterns, relevant libraries/frameworks, and how other projects solve \[feature/problem\]. Focus on: (1) industry best practices and common pitfalls, (2) libraries or frameworks that simplify this work, (3) how well-known open-source projects approach similar problems, (4) architectural patterns recommended for this type of feature. Return findings with source links."
+
+  - **Wait** for all dispatched agents; read identified files
+
+- **Action** — SaveResearch: Merge all findings (existing artifacts + new agent results) into `{OUT_DIR}/task_context.md` with sections: Architecture Patterns, Dependencies, Implementation Approaches, Impact Summary, and External Research (best practices, recommended libraries/frameworks, prior art, common pitfalls)
+
+## Step 2 - Assess Complexity
+
+Use research findings from Step 1 to determine appropriate planning depth.
+
+- **Action** — AssessFromResearch: Score complexity signals from research:
+
+  | Signal | Source | Assessment |
+  | --- | --- | --- |
+  | Files impacted | @finder | 1-3 files = Low, 4-8 = Med, 9+ = High |
+  | Pattern match | @patterns | Clear existing pattern = Low, Adapt pattern = Med, New pattern = High |
+  | Components crossed | @analyst | 1 component = Low, 2-3 = Med, 4+ = High |
+  | Data model changes | Research findings | None = Low, Modify existing = Med, New models/schema = High |
+  | Integration points | Research findings | Internal only = Low, 1-2 external = Med, 3+ external = High |
+  | External complexity | @web-research | Well-documented with libraries = Low, Some prior art = Med, Novel/emerging = High |
+
+- **Action** — CheckHardStops: Any true = automatic COMPREHENSIVE | db_schema_destructive | new_service_or_component | auth_or_pii_change | | payment_billing_logic | public_api_change | caching_consistency | slo_sla_risk |
+
+- **Action** — DetermineTier:
+
+  - **LIGHT**: All/most Low signals, single component, clear pattern match, no hard-stops
+  - **STANDARD**: Mix of Low/Med signals, multi-file but contained scope, no hard-stops
+  - **COMPREHENSIVE**: Any High signal, multiple Med signals, or any hard-stop triggered
+
+- **Action** — LogTier: Note the assessed tier in your response for transparency, then proceed immediately to the next step. Do NOT ask for confirmation.
+
+> **CHECKPOINT**: After determining tier, proceed IMMEDIATELY to the next step — Step 3 (High-Level Design) for STANDARD/COMPREHENSIVE, or Step 4 (Route) for LIGHT. Do NOT end turn here. Do NOT ask user to confirm the tier.
+
+## Step 3 - High-Level Design
+
+**SKIP IF LIGHT** — proceed directly to Step 4.
+
+Goal: align on the *shape* of the solution before generating a full plan. This catches misalignments early and gives the user a chance to redirect before reading a long plan doc.
+
+- **Action** — PresentDesign: Synthesize research from Step 1 into a single proposed approach with open questions. Present inline (do not write a separate design file).
+
+  **Format**:
+
+  > Here's the high-level design I'd take. Scan the shape, then resolve any open questions or push back on the approach.
+  >
+  > **Approach**: [1-2 paragraph summary of the solution shape — what changes structurally, not file-by-file]
+  >
+  > **Key components touched**:
+  > - `path/file.ts` — [what shifts and why]
+  > - `path/other.ts` — [what shifts and why]
+  >
+  > **Key decisions**:
+  > - [decision] — [rationale; alternative considered]
+  > - [decision] — [rationale; alternative considered]
+  >
+  > **Open questions** (with default assumption):
+  > 1. [question] — *default: [assumption]*
+  > 2. [question] — *default: [assumption]*
+  >
+  > Reply with answers, edits to the approach, or 'looks good' to continue.
+
+  **CRITICAL**:
+  - **Single proposed approach**, not a menu. If a true fork exists, surface it as an open question with your recommendation — not as parallel options.
+  - Stay at the *shape* level: components, key decisions, structural changes. Defer file-by-file detail to `create_plan`.
+  - Open questions should be specific and answerable; pair each with a default assumption so the user can skip if the default is fine.
+
+- **Action** — IterateDesign: If the user replies with answers, edits, or pushback, update the design and re-present. Loop until user says 'looks good' (or equivalent).
+
+- **Wait** — User signals alignment.
+
+- **Action** — PersistDesign: Append a "Selected Design" section to `{OUT_DIR}/task_context.md` capturing the agreed approach, key decisions, and resolved questions. This is what `create_plan` consumes.
+
+> **CHECKPOINT**: After alignment, proceed IMMEDIATELY to Step 4. The ONLY valid next action is invoking a Skill.
+
+## Step 4 - Route to Workflow
+
+### ⛔ MANDATORY SKILL INVOCATION ⛔
+
+```plaintext
+┌────────────────────────────────────────────────────────────────────────┐
+│  YOU MUST USE THE SKILL TOOL TO INVOKE THESE COMMANDS                  │
+│                                                                        │
+│  ❌ WRONG: "I'll now create the plan..."                               │
+│  ❌ WRONG: "The next step would be to run create_plan"        │
+│  ❌ WRONG: Ending turn without invoking Skill tool                     │
+│                                                                        │
+│  ✅ CORRECT: Skill tool with skill: "spectre-create_plan", args: "..." │
+│  ✅ CORRECT: Skill tool with skill: "spectre-create_tasks", args: "..."│
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+**DO NOT:**
+
+- Say you’ll create a plan or set of tasks yourself without running the skill tool
+- Describe what you would do
+- Summarize the plan/task steps yourself
+- End your turn without invoking Skill
+- Write plan.md or tasks.md content directly
+
+**YOU MUST:**
+
+- Use the Skill tool: `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth {tier}"`
+- Use the Skill tool: `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md"`
+
+---
+
+### Routing Logic
+
+- **If LIGHT**:
+
+  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md --depth light"`
+  - **Wait** — Returns task breakdown with brief implementation approach
+  - Skip to footer
+
+- **ElseIf STANDARD**:
+
+  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth standard"`
+  - **Wait** — Returns focused plan (Overview, Approach, Out of Scope)
+  - **Action** — PromptUser: "Review plan. Reply 'Approved' or provide feedback."
+  - **Wait** — User approval
+  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md"`
+  - **Wait** — Returns task breakdown
+
+- **ElseIf COMPREHENSIVE**:
+
+  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth comprehensive"`
+  - **Wait** — Returns full plan (all sections: Architecture, Phases, API Design, Testing Strategy, etc.)
+  - **Action** — PromptUser: "Review plan. Reply 'Approved' or provide feedback."
+  - **Wait** — User approval
+  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md"`
+  - **Wait** — Returns task breakdown
+
+---
+
+- **Action** — RenderFooter: Use `Skill(spectre-guide)` skill for Next Steps

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

@@ -0,0 +1,42 @@
+---
+name: "plan_review"
+description: "👻 | Find simplifications in a plan or tasks"
+user-invocable: true
+---
+
+# plan_review
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+
+You are a senior staff engineer with deep expertise in system design, architecture, and pragmatic problem-solving. Your specialty is finding the simplest path to meet all requirements.
+
+Review the following [plan/document/tasks/context] and identify opportunities to simplify while ensuring all requirements and functionality are delivered.
+
+For each simplification opportunity, provide:
+1. **What to simplify** - Specific component, process, or decision
+2. **Why** - What complexity it removes (cognitive load, dependencies, maintenance burden, etc.)
+3. **Impact** - Confirm that all original requirements remain satisfied
+4. **Risk** - Any trade-offs or risks introduced by the simplification
+
+Focus on:
+- Removing unnecessary abstractions or indirection
+- Consolidating duplicated logic or patterns
+- Questioning assumptions that add complexity
+- Identifying over-engineering
+- Suggesting proven, boring solutions over novel approaches
+
+## Testing Review
+**Context**: We use fast TDD with 1 happy path test + 1 unhappy path test per feature. A separate task handles achieving 100% test coverage post-feature work.
+
+Evaluate the testing approach and flag:
+- **Over-testing**: Tests beyond 1 happy + 1 unhappy path that should be deferred to the coverage task
+- **Wrong tests**: Testing implementation details instead of behavior, brittle tests that will break on refactors, or tests that don't actually validate requirements
+- **Missing critical paths**: Cases where the 1+1 approach genuinely misses a requirement-breaking scenario (rare, but call it out)
+- **Test complexity**: Overly elaborate test setup, mocking, or assertions that could be simpler
+
+Remember: The goal is fast feedback during development. More comprehensive testing comes later.
+
+End with a prioritized list of recommendations (high/medium/low impact).

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

@@ -0,0 +1,110 @@
+---
+name: "quick_dev"
+description: "👻 | Quickly scope, research, & plan s/m tasks - primary agent"
+user-invocable: true
+---
+
+# quick_dev
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+
+# quick_dev: Scope → Research → Plan for Small/Medium Tasks
+
+## Description
+- **What** — Lightweight workflow for bug fixes and small features: confirm scope, research via parallel agents, create implementation plan
+- **Outcome** — Validated scope, research synthesis, `quick_task_plan.md` with parent/sub-task structure
+
+## ARGUMENTS Input
+
+<ARGUMENTS>
+$ARGUMENTS
+</ARGUMENTS>
+
+## Step 1 - Gather Context
+
+- **Action** — ImmediateReply: Respond before running tools
+  - **If** ARGUMENTS has task context → proceed to Step 2
+  - **Else** → ask: "What are you trying to build or fix? Share any docs or context."
+  - **CRITICAL**: No tool calls here. No technical questions — research answers those.
+- **Wait** — Only if ARGUMENTS empty
+
+- **Action** — ReadFiles: Read any files mentioned by user completely (no limit/offset)
+
+## Step 2 - Confirm Scope (Functional Only)
+
+**Scope is about WHAT we're building, not HOW.** Technical approach comes from research.
+
+**DO NOT ask about**: implementation approach or technical decisions — research answers those.
+
+- **Action** — PresentScope:
+  > **📋 Scope Confirmation**
+  >
+  > **Objective**: {functional outcome}
+  >
+  > **✅ In Scope**: {what the feature does — behaviors, not implementation}
+  >
+  > **❌ Out of Scope**: {what we're NOT building}
+  >
+  > **UX Assumptions**: {how you imagine the user flow working}
+  >
+  > **Constraints**: {user-provided only}
+  >
+  > Any items to move between IN/OUT? Clarify UX flow? Reply with changes or 'Confirmed'.
+
+- **Wait** — User confirms or provides changes (apply and proceed)
+
+## Step 3 - Research
+
+- **Action** — SpawnAgents: Launch parallel research agents
+  - `@finder` — find WHERE files/components live
+  - `@analyst` — understand HOW code works
+  - `@patterns` — find similar implementations
+  - `@web-research` — external docs (only if user asks)
+  - **Wait** for ALL agents to complete
+
+- **Action** — Synthesize: Compile findings with file paths, patterns, architectural decisions
+
+## Step 4 - Clarify Ambiguities
+
+- **Action** — AskClarifyingQuestions: Use AskUserQuestion tool for 2-4 questions
+  - **Only ask** what research revealed needs user decision: UX preferences, behavioral trade-offs
+  - For multi-option questions: include Pros/Cons/Trade-offs
+  - **Never ask** scope questions (settled in Step 2) or technical questions answerable by code
+
+## Step 5 - Create Plan
+
+- **Action** — DetermineOutputDir:
+  - `OUT_DIR=docs/tasks/{branch_name}` (or user-specified)
+  - `mkdir -p "${OUT_DIR}/specs"`
+
+- **Action** — GeneratePlan: Create `{OUT_DIR}/specs/quick_task_plan.md` (use scoped name if exists)
+
+  **Plan Structure**:
+  1. Agreed Scope (Objective, In/Out of Scope, Constraints)
+  2. Research Summary (key codebase findings)
+  3. Approach Summary (strategy, integration points)
+  4. Implementation Tasks (see format below)
+  5. Success Criteria
+
+  **Task Format**: `## Phase` → `### [1.1] Parent Task` → `- [ ] **1.1.1** Sub-task` → `- [ ] Criterion`
+
+  **Sub-task guidance**:
+  - Start with action verb, use technical terms, name files/components
+  - Include: patterns, integration points, constraints
+  - Exclude: code snippets, line-by-line steps
+  - 2-3 acceptance criteria per sub-task
+
+  **Bounds**: ~3 phases, ~8 parent tasks max. If exceeds → suggest `create_tasks`
+
+- **Action** — ValidateCoverage: Verify all in-scope items have tasks; no out-of-scope tasks added
+
+## Step 6 - Document & Handoff
+
+- **Action** — PresentSummary:
+  > **Task Plan Created**: `{path}`
+  > ✅ Scope | ✅ Research | ✅ Plan
+
+- **Action** — RenderFooter: Use `Skill(spectre-guide)` skill for Next Steps

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

@@ -0,0 +1,82 @@
+---
+name: "rebase"
+description: "👻 | Safe guided rebase w/conflict handling - primary agent"
+user-invocable: true
+---
+
+# rebase
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+
+# rebase: Safe Git Rebase with Automatic Conflict Resolution
+
+## Description
+- **What** — Guide rebase with safety refs, automatic conflict resolution, test verification
+- **Outcome** — Successfully rebased branch with resolved conflicts, passing tests, smoketest guide
+
+## ARGUMENTS Input
+
+Optional target branch to rebase onto.
+
+<ARGUMENTS>
+$ARGUMENTS
+</ARGUMENTS>
+
+## Instructions
+- Auto-commit uncommitted changes (no confirmation)
+- Auto-resolve conflicts favoring target branch conventions (no prompts)
+- Track every resolution decision for summary
+- Actually run tests, don't just suggest
+
+## Step 1 - Confirm Target Branch
+
+- **Action** — CheckArguments:
+  - **If** ARGUMENTS has branch → proceed
+  - **Else** → ask: "What branch to rebase onto? (e.g., `origin/main`)"
+- **Wait** — If needed
+
+## Step 2 - Prepare
+
+- **Action** — EnsureCleanTree:
+  - **If** uncommitted changes → `git commit -am "chore: snapshot before rebase"`
+- **Action** — FetchLatest: `git fetch origin`
+- **Action** — CreateSafetyRef: `git branch backup/rebase-$(date +%Y%m%d-%H%M%S)`
+- **Action** — AssessComplexity: Light (≤5 commits), Moderate (5-20), Large (>20)
+
+## Step 3 - Execute Rebase
+
+- **Action** — StartRebase: `git rebase {target_branch}`
+  - **If** no conflicts → skip to Step 4
+
+- **Action** — ResolveAllConflicts: For each conflict:
+  1. Read conflict markers
+  2. Resolve (favor target branch patterns)
+  3. Track: `{file}: {decision} — {rationale}`
+  4. `git add {file}`
+  5. `git rebase --continue`
+  - Repeat until complete
+
+## Step 4 - Verify
+
+- **Action** — RunLint: Fix violations
+- **Action** — RunTestSuite: Detect command (npm test, pytest, cargo test, go test), run full suite
+- **Action** — ValidateRebase: Confirm commit count, no unexpected changes
+
+## Step 5 - Summary
+
+- **Action** — GenerateSummary:
+  > **Rebase Summary**
+  > - Branch: {current} → {target}
+  > - Commits: {count} | Conflicts: {count} | Tests: {PASS/FAIL}
+  >
+  > **Decisions**: | File | Decision | Rationale |
+  >
+  > **Smoketest Guide** (based on files touched):
+  > - {Feature Area}: [ ] {behavior to verify}
+  >
+  > **Safety**: Backup `{branch}` | Restore: `git reset --hard {backup}`
+
+- **Action** — RenderFooter: Use `Skill(spectre-guide)` skill for Next Steps

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

@@ -0,0 +1,17 @@
+---
+name: "recall"
+description: "👻 | Search Project Knowledge"
+user-invocable: true
+---
+
+# recall
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+# /recall - Search Project Knowledge
+
+Load the `spectre-recall` skill and follow its instructions.
+
+**Search query**: $ARGUMENTS

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

@@ -0,0 +1,168 @@
+---
+name: "research"
+description: "👻 | Research codebase with parallel agents - primary agent"
+user-invocable: true
+---
+
+# research
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+
+# research_codebase: Parallel Evidence-Based Codebase Analysis
+
+## Description
+- Description — Conduct comprehensive codebase research by spawning parallel specialized sub-agents and synthesizing their findings into structured documentation. Prioritizes direct readings of live code with specific file paths and line numbers. Supports follow-up questions with document updates.
+- Desired Outcome — Complete research document with YAML frontmatter, concrete evidence (file paths/line numbers), architectural insights, GitHub permalinks (when applicable), saved to `TASK_DIR/research/{topic}_{date}.md`, ready for task formalization or planning.
+
+## ARGUMENTS Input
+
+Optional user input to seed this workflow.
+
+<ARGUMENTS>
+$ARGUMENTS
+</ARGUMENTS>
+
+## Step (1/8) - Immediate Reply & Gather Context
+
+- **Action** — ImmediateReply: Respond immediately before running any commands or tools.
+  - Check for ARGUMENTS and extract research topic
+  - **If** ARGUMENTS exists → acknowledge topic; extract research question
+  - **Else** → prompt user: "I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections."
+  - **CRITICAL**: Do NOT run any tool calls in this step
+- **Wait** — User provides research query (if needed)
+
+## Step (2/8) - Read Mentioned Files
+
+- **Action** — ReadMentionedFiles: Read any directly mentioned files FULLY before decomposition.
+  - **If** user mentions specific files (tickets, docs, JSON) → read them FULLY using Read tool WITHOUT limit/offset
+  - **CRITICAL**: Read these files in main context before spawning sub-agents
+  - Ensures full context before decomposing research
+
+## Step (3/8) - Decompose & Plan Research
+
+- **Action** — AnalyzeQuestion: Break down research query into composable areas.
+  - Ultrathink about underlying patterns, connections, architectural implications user seeking
+  - Identify specific components, patterns, concepts to investigate
+  - Consider relevant directories, files, architectural patterns
+  - Create research plan using TodoWrite to track all subtasks
+- **Action** — SpawnSpecializedAgents: Launch parallel sub-agents for comprehensive research.
+  - **Codebase Research**:
+    - **finder**: Find WHERE files and components live
+    - **analyst**: Understand HOW specific code works
+    - **patterns**: Find examples of similar implementations
+  - **Web Research** (when task requires 3rd party frameworks/platforms/services/libraries/SDKs):
+    - **web-research**: External documentation and resources
+    - **IMPORTANT**: Instruct to return LINKS with findings; include links in final report
+  - **3rd Party Libraries** (only if user explicitly asks):
+    - Use Context 7 MCP tool to search external documentation
+  - **Linear Tickets** (if relevant):
+    - **linear-ticket-reader**: Get full details of specific ticket
+    - **linear-searcher**: Find related tickets or historical context
+  - **Agent Strategy**: Start with locator → use analyzer on promising findings → run multiple agents in parallel for different searches; each agent knows its job (tell what you're looking for, not how to search)
+
+## Step (4/8) - Synthesize Findings
+
+- **Action** — WaitForAgents: Wait for ALL sub-agent tasks to complete before proceeding.
+- **Action** — CompileResults: Synthesize all sub-agent results into coherent findings.
+  - Prioritize live codebase findings as primary source of truth
+  - Connect findings across different components
+  - Include specific file paths and line numbers for reference
+  - Highlight patterns, connections, architectural decisions
+  - Answer user's specific questions with concrete evidence
+- **Action** — GatherMetadata: Collect document metadata for YAML frontmatter.
+  - Current date/time with timezone (ISO format)
+  - Current commit hash (`git rev-parse HEAD`)
+  - Current branch name (`git rev-parse --abbrev-ref HEAD`)
+  - Repository name
+
+## Step (5/8) - Generate Research Document
+
+- **Output Location** — DetermineOutputDir: Decide where to save artifacts for this workflow.
+  - `branch_name=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)`
+  - **If** user specifies `target_dir/path` → `OUT_DIR={that value}`
+  - **Else** → `OUT_DIR=docs/tasks/{branch_name}`
+  - `mkdir -p "OUT_DIR/research"`
+- **Action** — CreateDocument: Structure research document with YAML frontmatter and comprehensive findings.
+  - **Frontmatter** (YAML at top):
+    - date: [ISO format with timezone]
+    - git_commit: [commit hash]
+    - branch: [branch name]
+    - repository: [repo name]
+    - topic: "[User's Question/Topic]"
+    - tags: [research, codebase, relevant-component-names]
+    - status: complete
+    - last_updated: [YYYY-MM-DD]
+    - last_updated_by: [Researcher name]
+  - **Document Sections** (in order):
+    1. Title: `# Research: [User's Question/Topic]`
+    2. Metadata header (Date, Git Commit, Branch, Repository)
+    3. Research Question (original user query)
+    4. Summary (high-level findings answering question)
+    5. Detailed Findings (by Component/Area with file:line references)
+    6. Code References (path/to/file:line with descriptions)
+    7. Architecture Insights (patterns, conventions, design decisions)
+    8. Related Research (links to other research docs in `docs/` (look for /research directories))
+    9. Open Questions (areas needing further investigation)
+
+## Step (6/8) - Add Permalinks & Save
+
+- **Action** — AddGitHubPermalinks: Generate GitHub permalinks if applicable.
+  - Check if on main branch or commit pushed: `git branch --show-current` and `git status`
+  - **If** on main/master OR pushed → generate permalinks:
+    - Get repo info: `gh repo view --json owner,name`
+    - Create: `https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}`
+    - Replace local file references with permalinks in document
+  - **Else** → keep local file references
+- **Action** — SaveDocument: Save research document to standardized location under `{OUT_DIR}/research/`.
+  - Filename: `{research_topic}_{MMDDYY}.md`
+  - Path: `{OUT_DIR}/research/{filename}`
+- **Action** — PresentFindings: Present concise summary to user.
+  - Concise summary of key findings
+  - Include key file references for easy navigation
+  - Ask if they have follow-up questions or need clarification
+
+## Step (7/8) - Handle Follow-ups & Handoff
+
+- **Action** — HandleFollowUps: If user has follow-up questions, update same document.
+  - **If** follow-up questions asked:
+    - Update frontmatter: `last_updated`, `last_updated_by`, add `last_updated_note: "Added follow-up research for [brief description]"`
+    - Add new section: `## Follow-up Research [timestamp]`
+    - Spawn new sub-agents as needed for additional investigation
+    - Continue updating document
+ - **Else** → proceed to handoff
+- **Action** — RenderFooter: Render Next Steps footer using `Skill(spectre-guide)` skill (contains format template and spectre command options)
+
+## Next Steps
+
+See `Skill(spectre-guide)` skill for footer format and command options.
+
+## Success Criteria
+
+- [ ] Immediate reply sent; research topic requested (Step 1 - no tool calls)
+- [ ] User research query received
+- [ ] Output directory determined inline (`OUT_DIR`) using branch name or user-specified path
+- [ ] Directly mentioned files read FULLY in main context before decomposition
+- [ ] Research question decomposed into composable areas with ultra-thinking about patterns/connections
+- [ ] Research plan created using TodoWrite to track subtasks
+- [ ] Specialized sub-agents spawned in parallel (finder, analyst, patterns, web-research as needed, linear agents if relevant)
+- [ ] Agent strategy followed (locator → analyzer → parallel execution)
+- [ ] Web research agents instructed to return LINKS (if used)
+- [ ] ALL sub-agents completed before synthesis
+- [ ] Findings compiled with live codebase prioritized as source of truth
+- [ ] Results include specific file paths and line numbers
+- [ ] Cross-component connections and patterns highlighted
+- [ ] Concrete evidence provided for user's questions
+- [ ] Metadata gathered for frontmatter (date/time ISO, commit hash, branch, repo name)
+- [ ] Research document created with YAML frontmatter at top
+- [ ] Frontmatter fields consistent (snake_case for multi-word: git_commit, last_updated)
+- [ ] Document includes all 9 required sections in order
+- [ ] GitHub permalinks generated if on main/master or pushed commit
+- [ ] Local file references replaced with permalinks (when applicable)
+- [ ] Document saved to `{OUT_DIR}/research/{topic}_{MMDDYY}.md`
+- [ ] Concise findings summary presented to user with key file references
+- [ ] Follow-up questions handled with document updates (frontmatter updated, new section added)
+ 
+- [ ] Next steps guide read and relevant options sourced for footer