@spectalk/agent

Multi-turn spec-writing agent. Translates vague feature requests into developer-ready technical specs.

How it works

You: "add a search bar"

→ Agent scans package.json → detects Next.js 15, Supabase
→ Agent asks: "Global search or search within a specific section?"
You: "global search for products"

→ Refiner agent reviews the spec for quality (file paths, edge cases, scope)
→ Spec saved to .spectalk/specs/add-search-bar.md
→ CLAUDE.md updated with spec reference

SpecTalk: Done. Scope: medium (~2–4h). Copy-ready prompt in your clipboard.

Install

npm install -g @spectalk/agent
# or
npx @spectalk/agent "add a search bar"

Usage

# Interactive (recommended for non-devs)
spectalk-agent

# Single feature, one shot
spectalk-agent "add dark mode"

# Pipe input
echo "add notifications" | spectalk-agent

# Different AI provider
spectalk-agent --provider openai "add search"
spectalk-agent --provider openrouter --model qwen/qwen-2.5-coder-32b-instruct "add search"
spectalk-agent --provider ollama --model qwen2.5-coder:32b "add search"

# MCP server mode (for IDE integration)
spectalk-agent --mcp

IDE Integration (MCP)

The MCP server works with any MCP-compatible IDE. The IDE's AI assistant discovers SpecTalk's tools and can call them on your behalf — no separate terminal needed.

Claude Code

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "spectalk": {
      "command": "npx",
      "args": ["-y", "@spectalk/agent", "--mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

Then in Claude Code: "Use SpecTalk to spec out adding a search bar"

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "spectalk": {
      "command": "npx",
      "args": ["-y", "@spectalk/agent", "--mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

Windsurf

Add to ~/.windsurf/mcp_config.json:

{
  "mcpServers": {
    "spectalk": {
      "command": "npx",
      "args": ["-y", "@spectalk/agent", "--mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

OpenCode

Add to your OpenCode config:

{
  "mcp": {
    "spectalk": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@spectalk/agent", "--mcp"]
    }
  }
}

Note: The MCP server generates specs using the Anthropic API by default. Set ANTHROPIC_API_KEY in the env block, or switch providers with --provider openai etc.

MCP Tools exposed

| Tool | Description | |------|-------------| | spectalk_spec | Full agent run: detect context → refine → write spec | | spectalk_detect_context | Scan project for tech stack | | spectalk_list_specs | List existing specs in .spectalk/specs/ | | spectalk_write_spec | Persist a spec you already have |

What gets written

• .spectalk/specs/<feature-slug>.md — the full spec (summary, steps, terms, copy-ready prompt)
• CLAUDE.md — reference injected if the file exists (AI coding tools pick it up automatically)

Multi-agent architecture

Two agents run in sequence:

1. Main agent — tool_use loop: detects stack, asks 0–2 clarifying questions, generates spec
2. Refiner agent — single pass: reviews for vague steps, wrong APIs, scope accuracy, missing edge cases

No framework (LangChain, LangGraph, AutoGen) — just the Anthropic SDK's native tool_use loop. Works with any provider that supports function calling: Anthropic, OpenAI, Groq, Google, OpenRouter, Ollama.

Providers

| Flag | Provider | Notes | |------|----------|-------| | --provider anthropic | Claude (default) | Best tool_use reliability | | --provider openai | GPT-4o | Good tool_use | | --provider groq | Llama 3.3 70B | Fast, free tier | | --provider google | Gemini 2.0 Flash | Good quality | | --provider openrouter | Any model via OpenRouter | Use --model qwen/... for QwenCoder | | --provider ollama | Local models | Use --model qwen2.5-coder:32b for local Qwen |