> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Iterative generation

# Iterative Generation

The Svantic terminal can orchestrate multi-step Forge workflows conversationally. Instead of running individual CLI commands, you describe what you want and the terminal reads your files, proposes tools, lets you refine, scans additional sources, and composes the final agent -- all in one session.

This page walks through a typical iterative session.

## The Workflow

```
You describe what you need
  --> Terminal reads source files
  --> Terminal calls forge_propose_tools
  --> You review and modify the proposal
  --> Terminal calls forge_generate_tools
  --> Terminal calls compose to merge everything
  --> Done: deployable agent
```

## Step 1: Propose Tools from Source Code

Start by telling the terminal what you have:

```
> Read my source code in src/monitoring/ and propose tools for a monitoring agent.
```

The terminal reads every file in `src/monitoring/`, analyzes the exports and JSDoc comments, then calls `forge_propose_tools` internally. You see a response like:

```
I found 8 exported functions across 3 files. Here are the proposed tools:

  1. check_service_health    — Ping a service endpoint and return status
  2. list_active_alerts      — Query all unresolved alerts
  3. acknowledge_alert       — Mark an alert as acknowledged
  4. get_alert_history       — Fetch alert history for a monitor
  5. create_maintenance_window — Schedule a maintenance window
  6. list_monitors           — List all configured monitors
  7. enable_monitor          — Enable a disabled monitor
  8. disable_monitor         — Disable a monitor temporarily

Should I generate tools for all of these, or would you like to modify the list?
```

## Step 2: Refine the Proposal

Tell the terminal what to change:

```
> Remove create_maintenance_window and get_alert_history.
> Rename check_service_health to ping_service.
> Add a tool called escalate_alert that creates a PagerDuty incident from an alert.
```

The terminal updates its internal proposal. No code is generated yet.

## Step 3: Generate the Tools

```
> Now generate those tools.
```

The terminal calls `forge_generate_tools` with the finalized proposal. It produces:

* `monitoring.tool-spec.yaml`
* `monitoring.capabilities.ts`

The terminal confirms:

```
Generated 7 tools in ./tools/:
  - monitoring.tool-spec.yaml
  - monitoring.capabilities.ts

The escalate_alert tool calls PagerDuty's incident creation API.
All other tools delegate to your existing functions in src/monitoring/.
```

## Step 4: Compose Everything

```
> Combine the monitoring and slack tools into a single agent called ops-bot.
```

The terminal calls `compose` with both tool specs:

```
Composed ops-bot with 10 tools from 2 domains:

  monitoring: ping_service, list_active_alerts, acknowledge_alert,
              escalate_alert, list_monitors, enable_monitor, disable_monitor
  slack:      send_message, send_alert_card, list_channels

Generated standalone project in ./ops-bot/:
  - server.ts
  - .env.template
  - package.json
  - Dockerfile
  - tsconfig.json
  - capabilities/monitoring.ts
  - capabilities/slack.ts
```

## Step 5: Make Adjustments

You can keep iterating:

```
> Actually, add a schedule trigger that checks all monitors every 5 minutes.
```

The terminal updates the tool spec and regenerates:

```
Added schedule trigger "check_all_monitors" with cron "*/5 * * * *" to the monitoring spec.
Regenerated ops-bot with the new trigger wired in server.ts.
```

## Terminal Functions Reference

These are the Forge functions the terminal calls behind the scenes:

| Terminal Function       | What It Does                                            |
| ----------------------- | ------------------------------------------------------- |
| `forge_propose_tools`   | Reads source files or a prompt and proposes a tool list |
| `forge_generate_tools`  | Takes a proposal and generates Tool Spec + TypeScript   |
| `forge_list_operations` | Lists operations in an OpenAPI spec                     |
| `forge_compose`         | Merges multiple tool specs into a single agent          |
| `forge_validate`        | Validates a Tool Spec YAML against the schema           |

## When to Use Iterative vs CLI

| Scenario                             | Recommended Approach                          |
| ------------------------------------ | --------------------------------------------- |
| Exploring an unfamiliar codebase     | Iterative (terminal reads and proposes)       |
| One-off generation from a known spec | CLI (`svantic forge tool --spec ...`)         |
| Building an agent from mixed sources | Iterative (scan, prompt, compose in sequence) |
| CI/CD pipeline                       | CLI or programmatic SDK                       |
| Prototyping and experimenting        | Iterative                                     |

## Tips

* The terminal remembers context within a session. You can refer to "the monitoring tools" or "that Slack file" without repeating paths.
* Ask the terminal to explain a generated tool spec before generating code: "Show me what the tool spec looks like for list\_active\_alerts."
* If you are unsure what functions a file exports, ask: "What functions are in src/monitoring/alerts.ts?"
* You can mix generation paths in one session: scan some files, generate from a prompt, pull from an OpenAPI spec, then compose everything together.