docs: Add Studio documentation and UTF-8 safety invariants

README.md:
- Add Studio section documenting the multi-agent workspace manager
- Document usage: run, list, status, accept, discard commands
- Explain worktree-based isolation and workflow

AGENTS.md:
- Add UTF-8 safe string slicing as critical invariant (#8)
- Add MUST NOT for byte-index slicing on multi-byte text (#5)
- Document parser sanitization as dangerous/subtle code path
  (prevents parser poisoning from inline tool-call JSON patterns)

Agent: lamport
This commit is contained in:
Dhanji R. Prasanna
2026-01-13 15:31:01 +05:30
parent 9a3b03a41f
commit 562c4199f8
2 changed files with 47 additions and 0 deletions

View File

@@ -322,6 +322,44 @@ G3 automatically saves session logs for each interaction in the `.g3/sessions/`
The `.g3/` directory is created automatically on first use and is excluded from version control.
## Studio - Multi-Agent Workspace Manager
Studio is a companion tool for managing multiple g3 agent sessions using git worktrees. Each session runs in an isolated worktree with its own branch, allowing multiple agents to work on the same codebase without conflicts.
### Usage
```bash
# Build studio alongside g3
cargo build --release
# Run an agent session (creates worktree, runs g3, tails output)
studio run --agent carmack "fix the memory leak in cache.rs"
# Run a one-shot session without a specific agent
studio run "add unit tests for the parser module"
# List all sessions
studio list
# Check session status (shows summary when complete)
studio status <session-id>
# Accept a session: merge changes to main and cleanup
studio accept <session-id>
# Discard a session: delete without merging
studio discard <session-id>
```
### How It Works
1. **Isolation**: Each session creates a git worktree at `.worktrees/sessions/<agent>/<session-id>/`
2. **Branching**: Sessions run on branches named `sessions/<agent>/<session-id>`
3. **Tracking**: Session metadata is stored in `.worktrees/.sessions/`
4. **Workflow**: Run → Review → Accept (merge) or Discard (delete)
Studio is the recommended way to run multiple agents in parallel on the same codebase, replacing the deprecated flock mode.
## Documentation Map
Detailed documentation is available in the `docs/` directory: