--- name: spike description: | Time-boxed technical investigation/feasibility study with Codex-first multi-agent collaboration (Codex + Opus 4.6 + Agent Teams). Codex CLI is consulted in EVERY phase for question framing, feasibility analysis, and final evaluation. Phase 1: Frame the investigation question & constraints (Claude user interaction + Codex question decomposition). Phase 2: Parallel investigation (Agent Teams: Researcher [Opus external research] + Feasibility Analyst [Codex deep analysis] + optional prototype). Phase 3: Codex synthesis into go/no-go recommendation & research report. Produces a DECISION DOCUMENT, NOT an implementation plan. Use /feature after a GO decision. metadata: short-description: Codex-first time-boxed technical investigation with Agent Teams (Decision phase) --- # Spike **Codex-first time-boxed technical investigation skill leveraging Codex deep reasoning, Opus 1M context, and Agent Teams.** > Preflight: ensure codex CLI is current (see codex-system skill). ## Overview This skill handles time-boxed feasibility studies and technical investigations. It produces a **decision document** (go/no-go recommendation), NOT an implementation plan. After a GO decision, the user proceeds to `/feature` (existing or greenfield mode) for actual implementation. ``` /spike <- This skill (investigation & decision) | After GO decision /feature <- Implementation planning | After approval /team-execute <- Parallel implementation + review ``` ### When to Use | Situation | Example | |-----------|---------| | **Technology feasibility** | "Can we use WebSocket for real-time sync?" | | **Library evaluation** | "Is DuckDB suitable for our analytics pipeline?" | | **Architecture question** | "Should we use event sourcing for the order system?" | | **Performance hypothesis** | "Can we serve 10k concurrent requests with this stack?" | | **Migration risk** | "What would it take to migrate from REST to gRPC?" | | **Integration question** | "Can we integrate with the Stripe Connect API for our use case?" | ### When NOT to Use - Bug diagnosis → `/troubleshoot` - Known feature to implement → `/feature` - Simple library lookup → direct research (Opus subagent) - Code review → `/team-execute --review-only` Full skill routing: `AGENTS.md` section "Routing Policy". ### Investigation Modes | Mode | Description | When to Use | |------|-------------|-------------| | **RESEARCH-ONLY** | No code written. Pure analysis from docs, examples, and Codex reasoning. | Library evaluation, architecture questions, migration risk | | **PROTOTYPE** | Small throwaway code to validate a specific technical question. Code is NOT production-quality. | Performance hypothesis, API integration feasibility, compatibility testing | ## Workflow ``` Phase 1: FRAME (Claude Lead + Codex Question Decomposition) Claude clarifies the spike question with the user, Codex decomposes into sub-questions and defines success criteria | Phase 2: INVESTIGATE (Agent Teams -- Parallel, Codex-driven) Researcher (Opus) <-> Feasibility Analyst (Codex) communicate bidirectionally Optional: Codex prototype (danger-full-access) for hands-on validation | Phase 3: SYNTHESIZE (Codex Evaluation + Claude Lead + User) Codex evaluates all evidence against success criteria, produces go/no-go recommendation, Claude presents to user ``` --- ## Phase 1: FRAME (Claude Lead + Codex Question Decomposition) **Clarify the spike question with the user, then consult Codex to decompose it into a structured investigation plan.** > A well-framed question is half the answer. Phase 1 ensures we investigate the right thing within the right constraints. ### Step 0: Resolve Workspace Resolve this spike's deterministic workspace once. The title becomes file and directory names, so give it a short English descriptor of the question -- not the user's raw wording, which the Language Protocol keeps out of paths: ```bash python3 .claude/skills/_shared/workspace.py --skill spike --title "{short English title}" --create ``` This prints one JSON object: `slug`, `team_name`, and `paths` (`brief`, `research`, `feasibility`, `report`, `prototype_dir`, `team_dir`). Exit 0 resolved/created; 1 bad args; 2 applies only to `--verify` (used later in Phase 3); 3 the workspace directories could not be created. Use `{slug}`, `{team_name}`, and every `paths.*` value from this JSON verbatim for the rest of this skill -- do not re-derive them by hand in a later phase. ### Step 1: Gather Spike Parameters from User Ask the user to provide: 1. **Question / Hypothesis**: What are we trying to find out? (e.g., "Can we use SQLite for multi-tenant data isolation?") 2. **Time budget**: How long should this investigation take? (e.g., 30 min, 1 hour, 2 hours) 3. **Investigation mode**: RESEARCH-ONLY or PROTOTYPE? 4. **Success criteria**: What evidence would make this a GO? (e.g., "Library supports X, performance meets Y threshold") 5. **Context**: Why is this question important now? What decision depends on it? ### Step 2: Codex Question Decomposition (MANDATORY) Consult Codex to decompose the spike question into a structured investigation plan. Write the prompt to a file, then invoke the wrapper: ```text Objective: Decompose this spike question into a structured investigation plan. Context: - Spike question: {question/hypothesis from user} - Investigation mode: {RESEARCH-ONLY or PROTOTYPE} - Time budget: {time budget} - Success criteria: {user's success criteria} - Project context: {why this matters, what decision depends on it} Constraints: - Break the question into 3-5 concrete sub-questions that can be independently investigated - For each sub-question, specify what evidence would confirm or deny it - Identify the critical path (which sub-question is most decisive) - Suggest the investigation approach for each sub-question - Keep the plan achievable within the time budget Output format: ## Question Decomposition ## Sub-questions (ranked by decisiveness) ## Evidence Needed (per sub-question) ## Investigation Approach ## Critical Path (which finding would short-circuit the spike) ## Risk of Inconclusive Result ``` ```bash python3 .claude/skills/_shared/codex_consult.py --prompt-file .claude/logs/codex/prompt-spike-decomposition.md --label spike-decomposition ``` `.claude/skills/_shared/codex_consult.py` exits 0 when Codex answered normally, 2 if the Codex CLI is not installed, 3 if Codex failed or timed out -- check the JSON `ok` field and read `response_file` for the answer (`error`/`stderr_file` explain a failure). Every later Codex consultation in this skill follows this same write-prompt-then-invoke pattern without repeating these exit codes. ### Step 3: Create Spike Brief Combine user parameters + Codex decomposition into a Spike Brief following the template contract in `references/brief-template.md`. Write it to `{paths.brief}` (from Step 0) -- not only into this conversation -- then validate it: ```bash python3 .claude/skills/_shared/validate_doc.py --contract spike-brief --file {paths.brief} ``` `references/brief-template.md` is the single source of truth for the required sections; the `spike-brief` contract is pinned to that template by `tests/test_validate_doc.py`. Exit 0 means every required section is present; exit 2 means one is missing and the JSON `sections_missing` names it; exit 1 means the file does not exist. Fill the gap before spawning the team. The brief carries the success criteria and sub-questions that Phase 3 scores the evidence against, and `{paths.brief}` is in `REQUIRED_KEYS`, so the Phase 3 `--verify` gate fails without it. A brief that lives only in the Lead's context does not survive compaction or a session break -- which is why it is a file here, and why both teammates are pointed at the path instead of a pasted copy. --- ## Phase 2: INVESTIGATE (Agent Teams -- Parallel) **Launch Researcher and Feasibility Analyst in parallel via Agent Teams with bidirectional communication. Feasibility Analyst MUST consult Codex for all technical analysis.** > Key difference from subagents: Teammates can communicate with each other. > Researcher's external findings change Feasibility Analyst's analysis scope, and Analyst's technical questions trigger new research. ### Team Setup ``` Create an agent team named `{team_name}` for spike investigation: {slug} Spawn two teammates: 1. **Researcher** -- Uses WebSearch/WebFetch for external research (Opus 1M context) Prompt: "You are the Researcher for spike: {slug}. Your job: Gather external evidence to answer the spike's sub-questions. Spike Brief: read `{paths.brief}` (written and validated in Phase 1 Step 3). Tasks: 1. Research each sub-question from the Spike Brief: - Find official documentation, API specs, feature matrices - Look for benchmarks, performance data, known limitations - Find real-world usage examples and case studies 2. Identify risks and gotchas: - Known issues, bugs, breaking changes - Community sentiment (is the technology mature? well-maintained?) - License compatibility 3. Find comparable implementations: - How have others solved similar problems? - What alternatives exist and how do they compare? 4. Gather evidence for each sub-question: - Document evidence FOR and AGAINST each sub-question - Rate evidence quality (official docs > blog posts > forum answers) How to research: - Use WebSearch for comprehensive research: WebSearch: '{spike question} {sub-question keywords} best practices limitations benchmarks' - Use WebFetch for targeted documentation lookup: WebFetch: '{official docs URL}' with prompt to extract specific information - For library evaluation, check: - Official docs: features, constraints, API surface - GitHub: stars, issues, release frequency, last commit - Benchmarks: performance characteristics - Migration guides: complexity of adoption Save all findings to `{paths.research}` (from Phase 1 Step 0). Communicate with Feasibility Analyst teammate: - Share findings that affect technical feasibility - Respond to Analyst's requests for specific external data - Flag constraints or limitations that change the analysis IMPORTANT -- Work Log: When ALL your tasks are complete, write your work log to {paths.team_dir}researcher.md per the shared format: .claude/skills/_shared/work-log-format.md Role-specific sections (between Tasks Completed and Communication): ## Sources Consulted - {URL or source}: {what was found} ## Evidence Collected (per sub-question) - {sub-question}: FOR: {evidence} / AGAINST: {evidence} ## Key Findings - {finding}: {relevance to spike question} " 2. **Feasibility Analyst** -- Uses Codex CLI as PRIMARY analysis engine for technical feasibility Prompt: "You are the Feasibility Analyst for spike: {slug}. Your job: Evaluate the technical feasibility of the spike question through deep analysis. Codex CLI is your PRIMARY tool for reasoning about technical trade-offs and feasibility. Spike Brief: read `{paths.brief}` (written and validated in Phase 1 Step 3). Tasks: 1. Analyze technical feasibility of each sub-question 2. Evaluate compatibility with the existing codebase and architecture 3. Assess complexity and effort for implementation (if GO) 4. Identify technical risks and unknowns 5. If PROTOTYPE mode: build a minimal throwaway prototype to validate ## Codex Analysis Protocol (MANDATORY) You MUST consult Codex for EACH of the following analysis tasks. Do NOT skip Codex consultation -- it is the primary reasoning engine for this role. Each consultation below follows the same shape: write the prompt to a file, then run `python3 .claude/skills/_shared/codex_consult.py --prompt-file --label