From a856822eba80931155852d0dbb8cd7f3fcaf473d Mon Sep 17 00:00:00 2001 From: adam Date: Mon, 23 Mar 2026 04:17:53 +1100 Subject: [PATCH] docs: update project documentation for v0.8.0 - README: update project status to v0.8.0, add template packs and artifact pipeline to quick start and features sections, show role mapping in config example, add tt init --template examples - CLAUDE.md: add template, automation, and permissions modules to architecture - CHANGELOG: add v0.8.0 entry with template packs, role mapping, artifact polling, and permission fixes - Cargo.toml: bump version to 0.8.0 Co-Authored-By: Claude Opus 4.6 --- CHANGELOG.md | 26 ++++++++++++++++++++++++++ CLAUDE.md | 5 ++++- Cargo.lock | 2 +- Cargo.toml | 2 +- README.md | 46 +++++++++++++++++++++++++++++++++++++++------- 5 files changed, 71 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2def0de..2349543 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,31 @@ # Changelog +## [0.8.0] - 2026-03-23 + +### Added +- **Template Packs**: `tt init --template ` generates a fully configured + `tutti.toml` from built-in or custom templates. Three starter templates: + `gstack-startup` (5-agent interactive SDLC), `rust-cli` (3-agent with verify + workflow), and `minimal` (2-agent fallback). +- **Role Mapping**: `[roles]` table maps logical roles to runtimes. Agents + declare `role = "planner"` instead of hardcoding `runtime = "claude-code"`. + Resolution order: explicit runtime > role lookup > defaults. +- **Repo Auto-Detection**: Templates declare `detect` (any-match) and + `detect_all` (all-match) arrays of filenames. `tt init` without `--template` + scans the repo root and suggests the best-matching template. +- **Artifact-Polling Mode**: When `artifact_glob` is set without `wait_for_idle`, + tutti polls for the artifact file instead of idle-detecting. Enables interactive + gstack skills (`/office-hours`, `/plan-eng-review`) where the agent waits for + human input mid-task. +- **Template Event Tagging**: `template_id` and `template_version` on + `AutomationRunRecord`, parsed from `# template:` comment in tutti.toml. + +### Fixed +- Added `Skill` and `AskUserQuestion` to `CLAUDE_TOOL_NAMES` so gstack skills + work in `dontAsk` permission mode. +- Dashboard focus sidebar race condition: fast poll no longer overwrites usage + stats with zeros from empty response. + ## [0.7.0] - 2026-03-22 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index 35d5abd..281d5f3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,11 +7,14 @@ ## Architecture - `src/cli/` — Clap command handlers, one file per subcommand -- `src/config/` — TOML config types and parsing +- `src/config/` — TOML config types and parsing (includes role mapping + `[roles]` table) - `src/runtime/` — RuntimeAdapter trait + per-runtime implementations - `src/session/` — tmux session management wrappers - `src/worktree/` — Git worktree lifecycle - `src/state/` — .tutti/ directory and agent state persistence +- `src/template/` — Template pack parsing, generation, repo detection, and built-in templates +- `src/automation/` — Workflow execution engine, artifact pipeline, artifact-polling mode +- `src/permissions/` — Claude Code settings generation and shell policy shims - `src/error.rs` — Central error types via thiserror ## Naming diff --git a/Cargo.lock b/Cargo.lock index e544d00..5f2c6af 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1816,7 +1816,7 @@ checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801" [[package]] name = "tutti" -version = "0.7.0" +version = "0.8.0" dependencies = [ "chrono", "clap", diff --git a/Cargo.toml b/Cargo.toml index 2acc187..ea87afa 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "tutti" -version = "0.7.0" +version = "0.8.0" edition = "2024" # intentional: codebase uses Rust 2024 let-chain syntax description = "Multi-agent orchestration CLI — your agents, all together" license = "MIT" diff --git a/README.md b/README.md index f487063..c923ced 100644 --- a/README.md +++ b/README.md @@ -21,10 +21,18 @@ Tutti spawns multiple AI coding agents in tmux sessions, gives each one its own ```bash cargo install tutti # install the CLI (requires Rust) cd your-project -tt init # create a tutti.toml with detected runtimes +tt init # auto-detect repo type and generate tutti.toml tt up # launch your agent team tt serve --port 4040 # start the web dashboard at localhost:4040 -tt run sdlc-auto # run a full plan→implement→test→review→ship pipeline +tt run sdlc-gstack # run an interactive design→review→implement→test→ship pipeline +``` + +Or pick a template explicitly: + +```bash +tt init --template gstack-startup # 5-agent interactive SDLC team +tt init --template rust-cli # 3-agent Rust project team +tt init --template minimal # 2-agent starter ``` **Prerequisites:** Rust toolchain, tmux, and at least one AI coding CLI installed (Claude Code, Codex, or Aider). @@ -66,13 +74,18 @@ Your agent team topology is defined in `tutti.toml` — who does what, which run [workspace] name = "my-project" +[roles] +implementer = "claude-code" +tester = "claude-code" +reviewer = "codex" + [[agent]] name = "implementer" -runtime = "claude-code" +role = "implementer" [[agent]] name = "tester" -runtime = "claude-code" +role = "tester" [[workflow]] name = "verify" @@ -83,7 +96,7 @@ text = "Run the test suite and report results." wait_for_idle = true ``` -Version it. Share it. Fork someone else's. +Swap `claude-code` for `codex` in `[roles]` and every agent using that role switches runtime — no per-agent edits. Version it. Share it. Fork someone else's. ## Quick Start @@ -114,11 +127,15 @@ echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc source ~/.zshrc ``` -## Project Status (v0.5.0 — March 2026) +## Project Status (v0.8.0 — March 2026) ### Built and usable now - Core CLI commands: `init`, `up`, `down`, `status`, `voices`, `watch`, `switch`, `diff`, `detect`, `land`, `review`, `send`, `handoff`, `attach`, `peek`, `logs`, `usage`, `run`, `verify`, `doctor`, `permissions`, `workspaces`, `issue-claim` -- Runtime adapters: Claude Code, Codex CLI, Aider +- Runtime adapters: Claude Code, Codex CLI, Aider, OpenClaw +- Template packs: `tt init --template gstack-startup` generates a fully configured team from built-in or custom templates, with repo auto-detection +- Role mapping: `[roles]` table maps logical roles to runtimes — swap providers without editing every agent +- Artifact pipeline: prompt steps capture and pass typed artifacts between workflow stages via `artifact_glob`/`artifact_name` +- Artifact-polling mode: interactive skills (e.g. `/office-hours`) wait for artifact files instead of idle detection, enabling human-in-the-loop workflows - Dependency-aware startup order (`depends_on`) - Per-agent git worktree isolation - Cross-workspace registry (`tt workspaces`, `tt up --all`, `tt down --all`) @@ -306,6 +323,21 @@ Reusable prompt components and skills are **phrases**. A phrase might be a CLAUD - Dispatch review packets to reviewer agent (`tt review `) - Ad-hoc prompt dispatch with optional auto-start + wait + captured output (`tt send --auto_up --wait --output`) +### Template Packs (Built) +- `tt init --template ` generates `tutti.toml` from built-in or custom templates +- Three starter templates: `gstack-startup` (5-agent interactive SDLC), `rust-cli` (3-agent with verify workflow), `minimal` (2-agent fallback) +- Repo auto-detection: templates declare `detect` (any-match) and `detect_all` (all-match) file patterns; `tt init` without `--template` scans the repo and suggests the best match +- Role mapping via `[roles]` table — agents declare `role = "planner"` instead of hardcoding runtimes; resolution order: explicit runtime > role lookup > defaults +- `{{project_name}}` variable substitution in template config body +- Template tag (`# template: name version`) in generated config, propagated to `AutomationRunRecord` + +### Artifact Pipeline (Built) +- Prompt steps capture output artifacts via `artifact_glob` and `artifact_name` — after a step completes, tutti globs for new files matching the pattern +- Downstream steps reference artifacts via `inject_files = ["{{output.artifact_name.path}}"]` — files are copied into the target agent's worktree +- Artifact-polling mode: when `artifact_glob` is set without `wait_for_idle`, tutti polls for the artifact file every 5s instead of idle-detecting, enabling interactive skills (e.g. `/office-hours`) where the agent waits for human input +- Pre-step snapshot prevents race conditions with concurrent runs +- Glob patterns support `~`, `{slug}`, `{workspace}`, and `{agent}` interpolation + ### Automation (Built) - `tt run` / `tt verify` reusable workflow execution with persisted run records - Run checkpoints persisted at `.tutti/state/workflow-checkpoints/.json` + `tt run --resume `