Skip to main content

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

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 FunctionWhat It Does
forge_propose_toolsReads source files or a prompt and proposes a tool list
forge_generate_toolsTakes a proposal and generates Tool Spec + TypeScript
forge_list_operationsLists operations in an OpenAPI spec
forge_composeMerges multiple tool specs into a single agent
forge_validateValidates a Tool Spec YAML against the schema

​
When to Use Iterative vs CLI

ScenarioRecommended Approach
Exploring an unfamiliar codebaseIterative (terminal reads and proposes)
One-off generation from a known specCLI (svantic forge tool --spec ...)
Building an agent from mixed sourcesIterative (scan, prompt, compose in sequence)
CI/CD pipelineCLI or programmatic SDK
Prototyping and experimentingIterative

​
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.