botscaffold

Documentation

Overview

Package botscaffold renders a new bot bundle (main.bot + manifest.yaml + README.md + the bundle layout directories) from a builder Spec. It is the single engine behind both bot-creation surfaces — the studio's "New bot" flow and `iterion bots create` — and is deliberately server-importable (pkg/cli wraps it too; the server must not import pkg/cli).

The generated workflow follows the house v2 shape: ONE adaptive agent carrying the whole mission (see docs/workflow_authoring_pitfalls.md — over-framing is an anti-pattern), with worktree/sandbox/permission/ budget as opt-in workflow-level dials. Rendered output is never trusted: main.bot is parsed AND compiled before anything is written, and manifest.yaml is decoded through the same strict loader the runtime uses.

Index

• Constants
• Variables
• func TemplateIDs() []string
• type Overrides
• type Result
  • func Scaffold(dir string, s Spec) (Result, error)
• type Spec
  • func SpecFromTemplate(id string, ov Overrides) (Spec, error)
  • func (s *Spec) Validate() error
  • func (s Spec) WorkflowName() string
• type Template
  • func TemplateByID(id string) (Template, bool)
  • func Templates() []Template
• type VarSpec

Constants

const DefaultTemplateID = "blank"

DefaultTemplateID is the gallery entry used when a caller names none.

Variables

var SlugRe = regexp.MustCompile(`^[a-z][a-z0-9-]{1,63}$`)

SlugRe is the accepted shape for a new bot's directory/technical name.

Functions

func TemplateIDs

func TemplateIDs() []string

TemplateIDs lists the gallery's entry IDs, in display order.

Types

type Overrides

type Overrides struct {
	Slug         string
	DisplayName  string
	Description  string
	Instructions string
	Model        string
	Backend      string
	Worktree     *bool
	Sandbox      *bool
}

Overrides are the fields a caller may set on top of a template's Spec. An empty string or a nil pointer keeps the template's own value, so a caller only states what the operator actually asked for.

type Result

type Result struct {
	Dir   string   `json:"dir"`
	Files []string `json:"files"`
}

Result reports what Scaffold wrote.

func Scaffold

func Scaffold(dir string, s Spec) (Result, error)

Scaffold renders the bundle into dir (created; must not already contain a main.bot). The rendered main.bot is parsed and compiled and the manifest decoded BEFORE any file lands, so a generation bug can never write a broken bundle.

type Spec

type Spec struct {
	// Slug is the bundle directory + technical name (SlugRe).
	Slug        string `json:"slug"`
	DisplayName string `json:"display_name,omitempty"`
	Icon        string `json:"icon,omitempty"`
	Description string `json:"description,omitempty"`
	WhenToUse   string `json:"when_to_use,omitempty"`

	// Instructions is the mission of the single campaign agent — the
	// bot's system prompt body.
	Instructions string `json:"instructions"`

	// Model/Backend override the engine's auto-detection when set.
	Model   string `json:"model,omitempty"`
	Backend string `json:"backend,omitempty"`

	// Skills are library skill names attached to the agent (DSL
	// `skills:` field, resolved by pkg/skilllib at run time).
	Skills []string `json:"skills,omitempty"`

	// Capabilities are host capabilities granted to the agent (DSL
	// `capabilities:` field, e.g. board.read / board.move).
	Capabilities []string `json:"capabilities,omitempty"`

	Vars []VarSpec `json:"vars,omitempty"`

	// Advanced dials — all optional.
	Worktree   bool   `json:"worktree,omitempty"`
	Sandbox    bool   `json:"sandbox,omitempty"`
	Permission string `json:"permission,omitempty"` // "", "ask", "deny"

	MaxCostUSD  float64 `json:"max_cost_usd,omitempty"`
	MaxDuration string  `json:"max_duration,omitempty"` // Go duration string, e.g. "2h"

	// ScheduleCron adds a kind=schedule invocation with this
	// suggested_cron to the manifest so the bot home can offer a
	// one-click schedule trigger.
	ScheduleCron string `json:"schedule_cron,omitempty"`
}

Spec is everything the builder form collects.

func SpecFromTemplate

func SpecFromTemplate(id string, ov Overrides) (Spec, error)

SpecFromTemplate resolves a gallery template and applies overrides on top. It lives here rather than in a single caller so every creation surface (the CLI, and any future server-side template endpoint) shares one definition of "start from a template" — the studio currently does this merge in TypeScript, which is exactly the drift this prevents.

func (*Spec) Validate

func (s *Spec) Validate() error

Validate normalizes the Spec in place, then rejects a malformed one with an explicit, field-naming error. Normalizing here (rather than on each surface) is what keeps the CLI and the studio from drifting: a caller that forgets to trim would otherwise get a baffling `invalid slug " foo"`.

func (Spec) WorkflowName

func (s Spec) WorkflowName() string

WorkflowName is the Slug as a DSL identifier — the DSL grammar has no hyphens in idents, so kebab-case slugs become snake_case here.

type Template

type Template struct {
	ID          string `json:"id"`
	Icon        string `json:"icon"`
	Name        string `json:"name"`
	Description string `json:"description"`
	// Spec is the pre-filled builder form (Slug left empty — the user
	// names their bot).
	Spec Spec `json:"spec"`
}

Template is one entry of the builder's "start from a template" gallery. Everything is a pre-filled Spec fragment — the form stays fully editable after picking one.

func TemplateByID

func TemplateByID(id string) (Template, bool)

TemplateByID looks up one gallery entry.

func Templates

func Templates() []Template

Templates returns the curated gallery, "blank" first. The slice is freshly built per call so callers can't mutate the catalog.

type VarSpec

type VarSpec struct {
	Name string `json:"name"`
	// Type is one of the DSL literal kinds: string, int, bool, float.
	Type string `json:"type"`
	// Default is the raw default value; empty means the type's zero
	// value ("", 0, false, 0.0) so the rendered declaration is always
	// complete and the bot always launches without mandatory inputs.
	Default string `json:"default,omitempty"`
	// Description becomes a `##` comment above the declaration.
	Description string `json:"description,omitempty"`
}

VarSpec declares one workflow input var for the generated bot.