LLM-Assisted Agent Authoring

invowk agent cmd and invowk agent mod help LLM agents create and change valid custom commands and local modules without guessing the current CUE contract.

Prompt for External Agents

Use prompt when another agent or tool will do the editing. The output is an operation-aware system prompt with the full current invowkfile.cue and invowkmod.cue schemas, plus Invowk-specific guidance about runtimes, dependencies, command visibility, module boundaries, and safe defaults.

# Print operation-aware command prompts for an external agent
invowk agent cmd prompt
invowk agent cmd prompt change --format json

# Print operation-aware module prompts
invowk agent mod prompt
invowk agent mod prompt create --format json

Generate or Change

Use create and change when Invowk should call the configured LLM provider, validate the generated CUE, and patch the bounded target files. Command authoring updates invowkfile.cue; module authoring updates only invowkmod.cue and invowkfile.cue inside the target module.

# With no configured provider, use an OpenAI-compatible local server
invowk agent cmd create docs --llm --llm-url http://localhost:1234/v1 'add a docs build command'

# Configure once, then generate without per-run LLM flags
invowk config set llm.provider codex
invowk agent cmd create lint 'add a lint command that runs golangci-lint'

# Generate and patch invowkfile.cue using the best available provider
invowk agent cmd create test --llm-provider auto 'add a test command'

# Change or remove an existing command
invowk agent cmd change lint --llm-provider claude 'run golangci-lint with --fix support'
invowk agent cmd remove lint --dry-run

# Preview the patch without writing
invowk agent cmd create release --llm-provider codex --dry-run 'add a release command'

# Print only the generated command object
invowk agent cmd create checklist --llm-provider claude --print 'add a release checklist command'

# Create, change, or remove a local module
invowk agent mod create io.example.tools --llm-provider codex 'create portable project tools'
invowk agent mod change io.example.tools --llm-provider codex 'add a formatting command'
invowk agent mod remove io.example.tools --dry-run

LLM-backed authoring commands use the same LLM provider flags as invowk audit: --llm-provider, --llm, --llm-url, --llm-model, --llm-api-key, --llm-timeout, and --llm-concurrency.

Configure llm.provider or llm.api once in config.cue to omit LLM flags on future create/change runs:

invowk config set llm.provider codex
invowk agent cmd create lint 'add a lint command that runs golangci-lint'

See Configuration Options for provider and API examples. Raw API keys should stay in environment variables, referenced with llm.api.api_key_env.

Write Behavior

Command create requires <name> and fails if that command already exists; use agent cmd change <name> to update an existing command. Module create requires <module-id> and fails if <module-id>.invowkmod already exists; use agent mod change <module-id-or-path> to update an existing local module. Use --dry-run to preview patches and --print to print generated output without writing. --verify validates the written module or resolves a written command with a dry-run execution plan.

:::caution Prompt content is sent to the configured provider LLM-backed create/change operations send the generated authoring system prompt and schemas, plus a user prompt containing your request and target path. Creating or changing a command in an existing invowkfile also sends that file's current content; changing a module sends its current module files. If the model returns invalid output, the repair retry also sends the validation error and the previous model response. Use a local provider when your command definitions or module files contain private project details. :::

Validation

Invowk accepts only one generated command object for command authoring, and the generated name must match the requested <name>. Module authoring accepts only generated invowkmod.cue and invowkfile.cue content, and invowkmod.cue must keep the requested module ID. Invowk uses structured JSON output with compatible OpenAI API backends, retries once with validation feedback when a model returns invalid output, and rejects malformed JSON, invalid CUE, full command cmds arrays in command_cue, and arbitrary extra generated module files.

Remove operations are deterministic: agent cmd remove <name> edits the target invowkfile without resolving an LLM provider, and agent mod remove <module-id-or-path> validates the exact local module and requires --force unless you pass --dry-run.