Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 4 additions & 5 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,9 +53,9 @@ Terminal editor + headless CLI for AI agent orchestration. Rust 2024.

`acp`, `agent_session` (+ `tool_agent/`), `context_planner`, `diff_engine`, `git`, `git_conflict`, `history`, `indent`, `iteration`, `mcp`, `memory`, `observer`, `path_pattern`, `query_loader`, `repo_map` (+ topology / symbol enrichment), `scope_enforcer`, `session_state`, `skills`, `swarm` (+ backends incl. `deepseek`), `terminal`, `tree_sitter`, `types`, `util`, `validation_gate`, `workspace`, `write_gate`.

### DSL (9) — [`lib.rs`](crates/gaviero-dsl/src/lib.rs)
### DSL (11) — [`lib.rs`](crates/gaviero-dsl/src/lib.rs)

`ast`, `compiler`, `reviewers`, `workflow_params`, `error`, `lexer`, `parser`, `resolver`, `tiers`.
`ast`, `compiler`, `reviewers`, `workflow_params`, `error`, `lexer`, `parser`, `resolver`, `profile`, `patterns`, `inspect`. A script names tiers only; the model profile (`profile.rs`) is the one place a tier becomes a model.

### Other crates

Expand Down Expand Up @@ -165,10 +165,9 @@ pub use ::tree_sitter::{Language, Parser, Tree, Node, Query, QueryCursor, Point,

// gaviero-dsl
pub fn compile(...) -> Result<CompiledPlan, miette::Report>;
pub fn compile_with_vars(..., override_vars, override_tiers, override_params) -> …;
pub fn compile_file(..., override_vars, override_tiers, override_params) -> …;
pub fn compile_with_vars(source, filename, profile, ..., override_vars, agent_tiers, override_params) -> …;
pub fn compile_file_with_profile(path, profile, ..., override_vars, agent_tiers, override_params) -> …;
pub fn workflow_execution_mode(...) -> Result<ExecutionMode, miette::Report>;
pub use tiers::load_tier_overrides;
```

Binaries expose no library API.
Expand Down
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Subprocess coding agents (Claude Code, Codex, Cursor) reach core's in-process MC

`.gaviero-workspace` files (any basename, fixed extension) describe multi-folder workspaces; bare directories are treated as single-folder workspaces — a bare directory holding a workspace file first asks whether to open that workspace instead (`--folder` skips the question). Dispatched at TUI startup in [crates/gaviero-tui/src/main.rs](crates/gaviero-tui/src/main.rs). `gaviero --workspace <dir>` opens the workspace file already in `<dir>`, or has the first-run wizard ([crates/gaviero-tui/src/setup.rs](crates/gaviero-tui/src/setup.rs)) build `<dirname>.gaviero-workspace` from the sub-folders the user picks. That setup screen is the only place initial configuration is authored — it runs before `App` exists, at every launch while the target has no `.gaviero/settings.json` (a folder's own, or the one beside an opened `.gaviero-workspace` file — the workspace layer), and offers: editor-only (preselected, also Esc — writes nothing; `App::enter_editor_only` hides the side panel and skips agents, memory, code graph, MCP, remote and the root `.cursor`/`.cursorignore` writes), minimal (`{}`), or full — a byte-for-byte copy of the global `$GAVIERO_ROOT/.gaviero/settings.json`, or gaviero's built-in full settings when that file does not exist. Workspaces get the same three choices for that one workspace-layer file, which every member inherits; `--workspace` on a directory without a workspace file first picks the members and writes it (editor-only then writes just the workspace file). A `gaviero-cli` run never creates `.gaviero/settings.json`: it finds the workspace the TUI would open by walking up from its run root ([crates/gaviero-cli/src/state.rs](crates/gaviero-cli/src/state.rs)) and shares its memory, or runs on throwaway state with `--isolated` (also the fallback when no workspace is found).

Scripts stay provider-agnostic by asking for a tier (`agent { tier high }`, `param x { model "tier:high" }`). **Model profiles** say what each tier means for a run: `.gaviero/dsl/profiles/<name>.gaviero` holds only `client` + `tier` declarations (discovered like scripts — [crates/gaviero-core/src/script_profiles.rs](crates/gaviero-core/src/script_profiles.rs); merged in [crates/gaviero-dsl/src/profile.rs](crates/gaviero-dsl/src/profile.rs)). Chosen with `gaviero-cli --profile <name|path>` or the SWARM form; with no choice a profile named `default` fills only the tiers the script leaves open. Older per-script tier overrides still load via `gaviero-cli --tiers-file <path>` (`tier <alias> <client>` lines only — [crates/gaviero-dsl/src/tiers.rs](crates/gaviero-dsl/src/tiers.rs)).
Scripts choose models in one way only: by tier. Every agent declares its default tier (`agent { tier high }`); a workflow's `tiers { <agent> <tier> }` block moves agents in that workflow, `gaviero-cli --tier <agent>=<tier>` moves one for a run (beating the block), and a list item's `tier` moves its clone. Scripts never declare `client` blocks, `tier <alias> <client>` lines or model-valued params. **Model profiles** are the one place a tier becomes a model: `.gaviero/dsl/profiles/<name>.gaviero` holds only `client` + `tier` declarations (discovered like scripts — [crates/gaviero-core/src/script_profiles.rs](crates/gaviero-core/src/script_profiles.rs); merged in [crates/gaviero-dsl/src/profile.rs](crates/gaviero-dsl/src/profile.rs)). Chosen with `gaviero-cli --profile <name|path>` or the SWARM form; with no choice the profile named `default` is used. Shipped example: [crates/gaviero-dsl/examples/profiles/default.gaviero](crates/gaviero-dsl/examples/profiles/default.gaviero).

### Agent Runtime Parity

Expand All @@ -59,7 +59,7 @@ All interactive coding providers — Claude Code, Codex, Cursor, Ollama, DeepSee
- **Model spec is `provider:model`.** Bare names are rejected at dispatch (`validate_model_spec`, [crates/gaviero-core/src/swarm/backend/shared.rs](crates/gaviero-core/src/swarm/backend/shared.rs)). Prefixes: `claude:`, `codex:`, `cursor:`, `ollama:`, `local:`, `deepseek:`, `dsh:`.
- **Lock discipline.** Never hold a `Mutex` across I/O, parsing, or embedding. The memory `writer` task is the single owner of SQLite writes.
- **Two-layer graph context.** The pre-prompt assembler injects `<repo_topology>` (shallow filesystem-only folder map, [crates/gaviero-core/src/repo_map/topology.rs](crates/gaviero-core/src/repo_map/topology.rs)) plus `<repo_outline>` (PageRank-ranked code outline). The TUI `/lite` chat command drops `<repo_outline>` + memory + impact and keeps only topology.
- **Plan production.** When drafting implementation plans for other agents, assume Claude Code (`claude:fable` / `claude:opus`) or Codex (`codex:gpt-5.6-sol`) unless the user will implement themselves. Plans must be agent-executable: concrete work units, ownership boundaries, expected files/modules, verification steps, sequencing constraints. Example client roster: [crates/gaviero-dsl/examples/clients.gaviero](crates/gaviero-dsl/examples/clients.gaviero). Drafting is separate from *consuming*: a stored plan binds only while it is being executed — see the `plans/` rule under Rules.
- **Plan production.** When drafting implementation plans for other agents, assume Claude Code (`claude:fable` / `claude:opus`) or Codex (`codex:gpt-5.6-sol`) unless the user will implement themselves. Plans must be agent-executable: concrete work units, ownership boundaries, expected files/modules, verification steps, sequencing constraints. Example model profile (clients per tier): [crates/gaviero-dsl/examples/profiles/default.gaviero](crates/gaviero-dsl/examples/profiles/default.gaviero). Drafting is separate from *consuming*: a stored plan binds only while it is being executed — see the `plans/` rule under Rules.

## Rules

Expand Down
22 changes: 14 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,22 +115,16 @@ review src/auth/session.rs for race conditions
**DSL workflow** (`review.gaviero`):

```gaviero
client sonnet { tier cheap model "claude:sonnet" effort low default }
client opus { tier expensive model "claude:opus" effort high }

tier cheap sonnet
tier expensive opus

agent reviewer {
description "Review the PR and identify issues"
client opus
tier high
scope { read_only ["src/" "tests/"] }
prompt "Review {{PROMPT}} and list all bugs and style issues."
}

agent fixer {
description "Fix all issues found by the reviewer"
client sonnet
tier medium
depends_on [reviewer]
scope { owned ["src/" "tests/"] impact_scope true }
prompt "Fix every issue in the reviewer's list."
Expand All @@ -142,8 +136,20 @@ workflow review_and_fix {
}
```

A script names tiers only; a model profile (`.gaviero/dsl/profiles/default.gaviero`, see [the shipped one](crates/gaviero-dsl/examples/profiles/default.gaviero)) says which model each tier is:

```gaviero
client sonnet { model "claude:sonnet" effort medium privacy public }
client opus { model "claude:opus" effort high privacy public }

tier medium sonnet
tier high opus
```

```bash
gaviero-cli --script review.gaviero --prompt "the auth module"
gaviero-cli --script review.gaviero --prompt "the auth module" --tier fixer=high # one agent, one run
gaviero-cli --script review.gaviero --prompt "the auth module" --profile codex # every model at once
```

**Skills** — turn-scoped instruction templates under `.gaviero/skills/<name>/SKILL.md`, invoked in chat with `$skill-name`. They are found in each folder's `.gaviero/skills/`, in the workspace's — the `.gaviero/skills/` beside the `.gaviero-workspace` file, also for a one-folder workspace or a member folder opened on its own — and in the global `$GAVIERO_ROOT/.gaviero/skills/` (folder beats workspace beats global). Adding or removing a skill is picked up while gaviero runs, even when the `skills/` directory is created after launch. Use `/skills` to list or `/skills search <query>` for semantic discovery; `/skills` also lists every folder it scanned and each skill it could not load, with the reason (a missing `description`, a frontmatter `name` that differs from the folder name, a folder name outside `A-Za-z0-9_-`). `SKILL.md` may be any letter case, start with a BOM, and use YAML block values (`description: >`). Optional `skills.extraRoots` (array of paths, default `[]`, `~` expanded) adds foreign roots such as `~/.claude/skills` or `~/.codex/skills`; a missing configured root is a chat warning, not a silent skip.
Expand Down
8 changes: 4 additions & 4 deletions crates/gaviero-cli/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,10 +99,10 @@ parse Cli
├─ plan input:
│ --task → synthetic WorkUnit (owned=["."])
│ --work-units → Vec<WorkUnit> JSON
│ --script → gaviero_dsl::compile_file(..., override_vars,
│ override_tiers, override_params)
│ --script → gaviero_dsl::compile_file_with_profile(..., profile,
│ override_vars, agent_tiers, override_params)
│ + --workflow / --prompt / --prompt-file
│ + --var / --param / --tiers-file
│ + --var / --param / --tier / --profile
│
├─ iteration overlays (--max-retries, --attempts, --test-first, --no-iterate)
├─ --coordinated? → plan_coordinated → write .gaviero → exit
Expand Down Expand Up @@ -151,7 +151,7 @@ Binary only — no library API. Public surface is the CLI:
--repo / --workspace
--task | --work-units | --script
--workflow --prompt --prompt-file
--var KEY=VALUE --param NAME=VALUE --tiers-file
--var KEY=VALUE --param NAME=VALUE --tier AGENT=TIER --profile NAME|PATH
--model --coordinator-model --ollama-base-url
--auto-accept --resume --fresh --isolated --max-parallel
--max-retries --attempts --test-first --no-iterate
Expand Down
4 changes: 2 additions & 2 deletions crates/gaviero-cli/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Full user-facing flag tables: [README.md](README.md). Do not duplicate every fie
- **stdout = results, stderr = telemetry.** Observers always log to stderr.
- **Model spec:** `provider:model` required. Accepted prefixes include `claude:`, `codex:`, `cursor:`, `ollama:`, `local:`, `deepseek:`, `dsh:` ([`validate_model_spec`](../gaviero-core/src/swarm/backend/shared.rs)). Default: workspace `agent.model`, then `claude:sonnet`.
- **`--repo` vs `--workspace`:** `execution repo` vs `execution document` ([`workflow_execution_mode`](../gaviero-dsl/src/lib.rs)). Conflicts with each other; `--workspace` defaults to the plan file's directory when `--var PLAN_FILE=...` is set.
- **DSL precedence.** Tiers: `--tiers-file` or `--profile` (mutually exclusive) > script/includes > the implicit `default` profile. Vars: agent-level > `--var` > script-level. Params: `--param` (see [`workflow_params`](../gaviero-dsl/src/workflow_params.rs)).
- **DSL precedence.** Models: `--profile` (else the profile named `default`) says what each tier means; an agent's tier is `--tier AGENT=TIER` > the workflow's `tiers { }` > its own `tier`. Vars: agent-level > `--var` > script-level. Params: `--param` (see [`workflow_params`](../gaviero-dsl/src/workflow_params.rs)).
- **State follows the TUI.** [`state::discover`](src/state.rs) walks the run root and its parents for `.gaviero/settings.json` or `.gaviero/memory.db` (never `$HOME`) and honours a `*.gaviero-workspace` listing that folder. Runs share that workspace's memory (`MemoryStores::open` at its state root, configured embedder, repo scope = the member folder containing the run root). `--isolated`, or no workspace found, means throwaway memory/graph/telemetry in a temp dir; settings are still read, skills are off, and synthesized agent configs are restored at exit. Admin commands require a discovered workspace; `--history` / `--mcp-stats` fall back to the run root.
- **Never build a code graph for one root into another root's DB.** A build deletes every file it did not scan. A run from a workspace folder uses the graph the TUI keeps for that folder; subfolder runs use `<state_root>/.gaviero/graphs/<hash>/` (`RunState::graph_db`).
- **Memory ops open the same `MemoryServices`** as the TUI; never bypass the writer task.
Expand All @@ -49,7 +49,7 @@ Full user-facing flag tables: [README.md](README.md). Do not duplicate every fie

- **Never add a flag without adding the field on `Cli` first.** Docs trail the struct.
- **Never write directly to a file.** Synthetic-task mode still goes through the Write Gate (`AutoAccept` when `--auto-accept`).
- **Tier overrides only contain `tier` lines.** [`load_tier_overrides`](../gaviero-dsl/src/tiers.rs) rejects other items.
- **Models come from tiers only.** There is no `--tiers-file` and no model-valued `--param`; do not add one. `--param` values are list items (`id=tier`).
- **Always validate the model spec via core** — do not re-parse prefixes in CLI code.
- **Never document `--no-memory`.** It does not exist on `Cli`.

Expand Down
8 changes: 4 additions & 4 deletions crates/gaviero-cli/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,9 +151,9 @@ No public library API. The `Cli` struct in `src/main.rs` is authoritative; this
| `--prompt` | `<text>` | Inline text replacing every `{{PROMPT}}` (requires `--script`) |
| `--prompt-file` | `<path>` | File contents replacing every `{{PROMPT}}` (requires `--script`) |
| `--var` | `KEY=VALUE` | Override a `vars {}` entry (repeatable, requires `--script`) |
| `--param` | `NAME=VALUE` | Supply a workflow `param` (repeatable, requires `--script`) |
| `--profile` | `<name|path>` | Model profile from `.gaviero/dsl/profiles/` or a file path (`client` + `tier` only; requires `--script`; conflicts with `--tiers-file`) |
| `--tiers-file` | `<path>` | Tier overrides (`tier <role> <client>` lines only; requires `--script`) |
| `--param` | `NAME=VALUE` | Supply a workflow list `param`: `id=tier,…`, ids, or a list literal (repeatable, requires `--script`) |
| `--profile` | `<name|path>` | Model profile from `.gaviero/dsl/profiles/` or a file path (`client` + `tier` only; requires `--script`); default: the profile named `default` |
| `--tier` | `AGENT=TIER` | Run one agent on another tier; beats the workflow's `tiers { }` entry (repeatable; requires `--script`) |
| `--coordinated` | — | Emit a reviewable plan and exit (requires `--task`) |
| `--output` | `<path>` | Save the generated plan (`--coordinated` only) |

Expand Down Expand Up @@ -204,7 +204,7 @@ instead of overwriting it** — no flag required:
gaviero-cli --script crates/gaviero-dsl/examples/plan_refinement.gaviero \
--workflow feature-plan-refinement \
--prompt-file brief.md --var OUT_DIR=plans/my-feature \
--param roster=claude=claude:opus@max,codex=codex:gpt-5.6-sol@high
--param roster=claude=top-claude,codex=high-codex

# Same command again: detects v3, resumes at v4 reading the v3 plans
```
Expand Down
Loading
Loading