Fix Bug / Add Feature¶

The fix-bug and add-feature pipelines are Agent Smith's core coding workflows. They take a ticket, understand the codebase, write code, run tests, and open a pull request.

Pipeline Steps¶

fix-bug (14 steps)add-feature (16 steps)fix-no-test (13 steps)

#	Command	What It Does
1	FetchTicket	Reads ticket from GitHub / AzDO / Jira / GitLab
2	CheckoutSource	Clones repo, creates `fix/{id}` branch
3	BootstrapProject	Detects language, framework, build system
4	LoadCodeMap	Generates LLM-navigable code map
5	LoadDomainRules	Loads coding standards from repo
6	LoadContext	Loads `.agentsmith/context.yaml`
7	AnalyzeCode	Scout agent identifies relevant files
8	Triage	Selects specialist roles for the task
9	GeneratePlan	AI generates step-by-step implementation plan
10	Approval	Shows plan, waits for OK (skipped in `--headless`)
11	AgenticExecute	AI writes code in an agentic loop
12	Test	Runs the project's test suite
13	WriteRunResult	Writes `result.md` with token usage and cost
14	CommitAndPR	Commits, pushes, opens PR, closes ticket

Same as fix-bug, plus two additional steps after AgenticExecute:

#	Command	What It Does
12	GenerateTests	AI generates tests for the new code
13	Test	Runs the full test suite (including new tests)
14	GenerateDocs	AI generates/updates documentation
15	WriteRunResult	Writes result with cost data
16	CommitAndPR	Commits everything, opens PR

Same as fix-bug but skips the Test step. Useful for documentation changes, config updates, or repos without a test suite.

The Scout Agent (AnalyzeCode)¶

Before any code is written, the scout agent runs during the AnalyzeCode step. It uses a cheaper, faster model to scan the codebase and identify which files are relevant to the ticket.

The scout:

Reads the code map (generated by LoadCodeMap)
Reads the ticket description and any linked issues
Searches the codebase by pattern to find related files
Produces a focused file list that gets passed to the main agent

This keeps the main agent's context window focused on what matters, rather than dumping the entire codebase into the prompt.

The Agentic Loop¶

The AgenticExecute step is where the AI actually writes code. It runs in an agentic loop — the AI calls tools, observes results, and decides what to do next.

┌─────────────────────────────────┐
│         AgenticExecute          │
│                                 │
│  ┌──────────┐                   │
│  │ AI Agent  │──→ read_file     │
│  │          │──→ write_file    │
│  │          │──→ search_code   │
│  │          │──→ run_command   │
│  │          │──→ list_files    │
│  │          │←── tool results  │
│  └──────────┘                   │
│       ↕                         │
│  Context compaction             │
│  (if iterations > threshold)    │
└─────────────────────────────────┘

Available Tools¶

The agent has access to these tools during the agentic loop:

Tool	Purpose	Example
`read_file`	Read file contents	Read a service class to understand its interface
`write_file`	Create or overwrite a file	Write the updated implementation
`search_code`	Search codebase by pattern	Find all usages of a method before renaming
`list_files`	List directory contents	Explore the project structure
`run_command`	Execute shell commands	Run `dotnet build` to check compilation

The agent decides which tools to call, in what order, and how many iterations it needs. A typical bug fix might look like:

Iteration 1: read_file("src/Services/UserService.cs")
Iteration 2: search_code("GetUserById")
Iteration 3: read_file("src/Repositories/UserRepository.cs")
Iteration 4: write_file("src/Services/UserService.cs", ...)
Iteration 5: run_command("dotnet build")

Tool execution

All tools run in the cloned repository's working directory. File paths are relative to the repo root. Shell commands execute with the repo root as the current directory.

Retry on Test Failure¶

When the Test step fails, Agent Smith does not immediately give up. The pipeline re-enters the agentic loop with the test output, allowing the AI to fix the failing tests:

[11/14] AgenticExecute  ✓  (wrote code)
[12/14] Test            ✗  (3 tests failed)
         ↓ re-enter agentic loop with failure output
[12/14] AgenticExecute  ✓  (fixed failing tests)
[12/14] Test            ✓  (all tests pass)

Max retries

The number of test-fix cycles is bounded by the retry configuration in agentsmith.yml. Default is 3 attempts.

Context Compaction¶

Long agentic sessions can exceed the model's context window. When the iteration count crosses threshold_iterations, a smaller model (e.g., Claude Haiku) summarizes the conversation so far, keeping only recent iterations verbatim:

agent:
  compaction:
    is_enabled: true
    threshold_iterations: 8
    max_context_tokens: 80000
    keep_recent_iterations: 3
    summary_model: claude-haiku-4-5-20251001

This allows long-running tasks (large features, multi-file refactors) to complete without hitting token limits.

Running¶

# Fix a bug from a ticket
agent-smith fix --ticket 54 --project my-project

# Add a feature, headless (no approval prompt)
agent-smith feature --ticket 12 --project my-project --headless

# Fix without running tests
agent-smith fix --ticket 54 --project my-project --no-test

Headless mode

In --headless mode, the Approval step is skipped automatically. This is required for CI/CD and chat gateway usage.

Output¶

On success, the pipeline produces:

A new branch with the changes (e.g., fix/54-null-ref-in-user-service)
A pull request on your Git provider with the implementation plan as description
A run result in .agentsmith/runs/r{NN}-slug/result.md with token usage, cost, and duration
The ticket is updated with the PR link and closed (if configured)