---
name: "spectre-kickoff"
description: "👻 | Project kickoff with deep research & MVP pathfinding - primary agent"
user-invocable: true
---

# kickoff

## Input Handling

Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.


# kickoff: Deep Codebase Research + MVP Path Discovery

Comprehensive codebase research, external best practices, and MVP implementation path with file:line evidence. Output: kickoff document with architecture insights, gap analysis, and implementation options saved to `docs/tasks/{task_name}/kickoff/`.

## ARGUMENTS

<ARGUMENTS>
$ARGUMENTS
</ARGUMENTS>

## Step 1: Acknowledge & Clarify

- **Action** — ImmediateReply: Respond before any tools.
  - **If** ARGUMENTS → acknowledge context, identify: what we're exploring, what decision we're heading toward, what success looks like
  - **Else** → prompt for project context
  - **CRITICAL**: No tool calls in this step

## Step 2: Gather Context & Decompose

- **Action** — ReadMentionedDocs: Read referenced docs FULLY in main context (not subagent). Extract: vision, constraints, decisions made, open questions.
- **Action** — DecomposeResearchAreas: Break project into research areas. Consider: components to investigate, directories/files, architectural patterns, data flows, existing code to extend.
- **Action** — CreateResearchPlan: Use TodoWrite to track research subtasks.

## Step 3: Deep Parallel Research

- **Action** — SpawnResearchAgents: Launch parallel agents for comprehensive context.

| Agent | Task | Required Output |
|-------|------|-----------------|
| @finder | Find relevant files, entry points, handlers, models | File paths by domain |
| @analyst | Trace data flow, dependencies, behavior, edge cases | file:line refs for ALL findings |
| @patterns | Find similar implementations, patterns to follow/avoid | Code examples with file:line |
| @web-research | Best practices, similar solutions, pitfalls | Findings WITH LINKS |

**Strategy**: locator → analyzer on findings → parallel for breadth. Spawn follow-ups if shallow. Demand file:line evidence.

**3rd Party Libs**: Use Context7 MCP for central libraries.

- **Action** — WaitForAgents: ALL agents must complete before synthesis. Update TodoWrite as each completes.

## Step 4: Synthesize Understanding

- **Action** — CompileFindings: Synthesize with file:line refs throughout.
  - Codebase: Connect findings across components, document data flow, answer "how does codebase handle [area]?"
  - Architecture: Patterns to follow (with examples), conventions, constraints, reuse vs build new
  - External: Industry patterns (with links), best practices, pitfalls

- **Action** — PerformGapAnalysis: Current capabilities (with file refs) vs required capabilities. What's missing vs needs modification.

- **Action** — IdentifyMVPAndOptions:
  - MVP: Core value, minimum for value, what to defer (informed by codebase complexity)
  - Options: 2-3 approaches with: summary, key decisions, code to leverage (file refs), new work, effort sense, trade-offs
  - Decision points: Architecture, scope, technology, integration, patterns

## Step 5: Generate Document

- **Action** — DetermineOutputDir:
  - Derive `task_name` from context (kebab-case)
  - `OUT_DIR = user_specified || docs/tasks/{task_name}/kickoff`
  - `mkdir -p "$OUT_DIR"`

- **Action** — CreateDocument: Structure with YAML frontmatter (date, git_commit, branch, repo, topic, tags, status).

  **Sections**: Title → Metadata → Project Context → Research Summary → Detailed Codebase Findings (by area, file:line refs, code snippets) → Code References (table) → Architecture Insights (patterns, conventions, constraints) → External Research (with links) → Gap Analysis → MVP Suggestion → Implementation Options (2-3 with trade-offs) → Decision Points → Open Questions → Related Resources

- **Action** — AddGitHubPermalinks: If on main/pushed, convert file refs to `https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}`

- **Action** — SaveDocument: Save as `{task_name}_kickoff.md` (timestamp variant if exists). **CRITICAL**: Save before Step 6.

## Step 6: Present & Scope

- **Action** — PresentSummary:
  > **Kickoff Complete** — saved to `{path}`
  >
  > **Vision**: [1-2 sentences]
  > **What Exists**: [key components with file:line refs]
  > **Architecture Insights**: [patterns, conventions, constraints]
  > **External Learnings**: [key insights with links]
  > **Gap**: [have → need]
  > **MVP Path**: [smallest valuable slice]
  >
  > **Scoping Questions** (before planning):
  > 1. [Scope/boundary question] — Option A (leverages `code:line`) vs Option B
  > 2. [Technical approach] — suggested vs alternative
  > 3. [Priority/constraint question]

- **Action** — EngageInScoping: Wait for response, ask follow-ups. No planning until ambiguities resolved. Research answerable questions instead of asking.

## Step 7: Handle Follow-ups

- **Action** — HandleFollowUps:
  - **If** clarifications → update doc with `## Scoping Clarifications [timestamp]`
  - **If** more research needed → spawn agents, demand file:line evidence, update doc
  - Continue until ambiguities resolved

## Step 8: Transition to Scope

- **Action** — SummarizeAndTransition:
  > **Ready for Scope Definition**
  >
  > **Established**: User problem, user value, key findings (file:line), decisions made, remaining ambiguities
  >
  > **Options**:
  > 1. "Proceed with scope" → `spectre-scope` with FROM_KICKOFF=true, SKIP_EXPLORATION=true
  > 2. "Skip to planning" → `spectre-plan` with kickoff doc context
  > 3. "Need to think" → `spectre-handoff`

- **Action** — ExecuteChoice:
  - **If** scope → invoke `spectre-scope` with: FROM_KICKOFF=true, KICKOFF_DOC={path}, SKIP_EXPLORATION=true, context summary
  - **If** planning → suggest `spectre-plan`
  - **If** pause → run `spectre-handoff`