# 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)"

    | # | 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 | LoadCodingPrinciples | 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 |

=== "add-feature (16 steps)"

    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 |

=== "fix-no-test (13 steps)"

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

## How Skills Collaborate

Fix-bug and add-feature use the **hierarchical pipeline** pattern. For a general overview of all pipeline orchestration patterns, see [Multi-Agent Orchestration](../concepts/multi-agent-orchestration.md).

```mermaid
graph TD
    Ticket --> Scout["AnalyzeCode<br/>(scout agent)"]
    Scout --> Triage["Triage<br/>(select skills)"]
    Triage --> Plan["GeneratePlan<br/>[Lead]"]
    Plan -->|"plan injected"| Execute[AgenticExecute]
    Execute --> Test["Test Suite<br/>[Gate]"]
    Test -->|pass| PR[CommitAndPR]
    Test -->|fail| Execute

    style Plan fill:#27ae60,color:#fff
    style Test fill:#c0392b,color:#fff
```

The scout agent identifies relevant files using a cheaper model. The plan generated by the lead skill becomes part of the domain rules for the agentic execution loop. The test suite acts as a gate — if tests fail, the agent re-enters the loop to fix them.

## 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")
```

!!! info "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)
```

!!! tip "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:

```yaml
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

```bash
# 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

# Dry run -- show pipeline steps without executing
agent-smith fix --ticket 54 --project my-project --dry-run
agent-smith feature --ticket 12 --project my-project --dry-run
```

!!! note "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)
