The AI Coach project taught me that process keeps Claude on track: PRDs, build guides, agent gates, CLAUDE.md. The toolkit extracted that process into a reusable template. But the process still started with a human reading an issue, deciding what to research, and writing the first brief. This project asks: what if we automate that too?

The result is claude-engineering-agent: a Python CLI that takes a Linear issue identifier, researches it using multiple tools, produces a structured technical brief, optionally generates a build spec, and can hand off to Claude Code for implementation and PR creation. The whole chain runs from a single command.

The pipeline

The agent supports three progressive modes that build on each other:

Research (default): read the Linear issue, investigate using GitHub code search and web search, produce a structured brief, post it back to Linear as a comment, and add a "researched" label.

Spec (--spec): research first, then generate an implementation specification with phased build guides, posted as a second Linear comment.

Implement (--implement): research, spec, then hand off to Claude Code CLI for execution. Claude Code works through the build guide phase by phase, with the toolkit's subagent ecosystem (code-reviewer, test-generator, phase-acceptance) gating each phase. A PR is created at the end.

Each step reads the previous step's output from Linear comments, so the pipeline is stateless. Any step can be run independently with --spec-only or --implement-only flags if the prerequisites already exist. That means you can run research, review the brief, tweak it, and then run implementation separately.

The tool chain

The interesting architectural decision was using Anthropic's MCP Connector rather than client-side MCP. The MCP Connector passes mcp_servers=[...] directly in the messages.create() call; Anthropic's infrastructure handles connection, tool discovery, and execution server-side. No MCP Python SDK, no session management, no tool wrappers.

Python CLI claude-agent JAM-nnn Claude API Streaming + MCP Connector MCP Connector (server-side) Linear MCP Issues + comments GitHub MCP Code + files Web search Libraries, docs, best practices Research brief → Linear comment Claude Code CLI --implement mode Pull request GitHub

This was a deliberate choice over client-side MCP. All the MCP servers are remote and URL-accessible (Linear at mcp.linear.app/mcp, GitHub at api.githubcopilot.com/mcp), we only need tools (not MCP resources or prompts), and it eliminates an entire client layer. It's the pattern Anthropic recommends for production API integrations and it's what their enterprise customers are building.

Web search runs as a Claude server tool alongside the MCP connections, so all three tool types (Linear MCP, GitHub MCP, web search) are available in the same agentic loop.

Adaptive research

The agent doesn't follow a fixed script. Claude generates a research plan based on the issue content, executes it step by step, evaluates intermediate results, and adapts. It might add new research steps if initial findings reveal a gap, skip redundant steps if an earlier result already answered the question, or terminate early if it has enough information.

Findings are grounded against the target repo's own skills and agents. If the repo contains .claude/skills/ and .claude/agents/, the agent reads their descriptions at startup and injects the inventory into the system prompt. This means the research brief references the developer's actual tooling rather than generic recommendations. If the repo has no skills or agents, it works without them.

The agent is also repo-agnostic: install it once as a global CLI tool via uv tool install, then run it from any git repository. It discovers the repo context (owner, name, skills, agents) from the current working directory.

Token optimisation

Two techniques reduced input token usage noticeably. First, deferred tool loading. The MCP Connector discovers all available tools on each server: Linear has 35+ tools, GitHub has 41+. Most of which the agent never uses. Using defer_loading, we eagerly load only the tools the agent actually calls (about 10 across both servers) and defer the rest. This keeps the tool inventory in the system prompt much smaller.

Second, the local skills inventory. Rather than having Claude read every skill file via GitHub MCP on every run, the CLI reads skill descriptions from YAML frontmatter at startup and injects just the names and descriptions into the prompt. Claude only uses GitHub MCP to read a skill's full content when it's genuinely relevant to the research.

Dogfooding

I tested the agent against six sub-issues of an FCA Regulatory RAG project, covering data parsing, synthetic data generation, ingestion pipelines, retrieval, evaluation frameworks, and documentation. The results were solid: research relevance scored 4/5 consistently, brief quality hit 5/5 (specific library names, API model IDs, concrete steps rather than generic advice), and every brief was unmistakably about its issue rather than boilerplate.

Token usage ranged from 223K to 604K input tokens per issue, with durations from 103 seconds to 17 minutes depending on how many tool calls Claude decided it needed. The agent called between 6 and 18 tools per issue; that variation is the adaptive planning in action.

The implementation pipeline

The --implement flag takes the pipeline from research into code. After producing a research brief and build spec (both posted to Linear), the implementer launches Claude Code CLI in a new branch. It passes the build spec as a phased implementation guide, and Claude Code works through each phase sequentially.

The toolkit's subagent ecosystem gates each phase: code-reviewer and test-generator run as pre-PR gates, phase-acceptance validates against the spec's requirements before moving to the next phase. When all phases complete, a PR is created with the full implementation.

This is the process from the AI Coach project and the claude-toolkit template, automated end-to-end. The human wrote the Linear issue; everything after that is tool-chained.

What this evolved from

This project is a direct evolution of the development process I built during AI Coach. That project proved that Claude Code works best with structured process: PRDs, build guides, agent gates, documentation that updates itself. The toolkit extracted the process into a reusable template. This project automates the front end: issue analysis, research, and spec generation that feeds into the same process.

It's also a demonstration of tool chaining across four distinct systems: Linear MCP for issue management, GitHub MCP for code search, web search for technical research, and Claude Code CLI for implementation. Each tool handles what it's best at, and the Claude API orchestrates the chain.

Follow-on note: I'm interested in the emerging loop concept and will iterate this agent further down the line.

For now, the current source code is on GitHub.