Agent Framework
Learn what the IAS Agent Framework provides, how it structures context for AI agents, and the CLI commands available for managing agent workflows.
The IAS Agent Framework is the deployable component that gets installed into your repositories. It provides the scaffold, CLI tooling, and operational processes that AI agents need to work effectively on your codebase. Everything the framework creates is Markdown and JSON, committed directly to your repository.
What the Framework Provides
The Agent Framework turns any Git repository into an AI-ready workspace. It delivers five capabilities:
Structured context. A documentation scaffold under docs/ias/ that gives agents a consistent way to understand your project -- its constraints, goals, prior decisions, and current state. Agents read this context automatically instead of relying on chat history or re-explanation.
CLI tooling. Commands for bootstrapping, preflight checks, creating runs, and managing the agent lifecycle. The CLI works locally without requiring a server or Console connection.
Process documentation. Guides for agent behavior: the run protocol (how to plan, execute, and close a goal), decision tracking (how to surface and record choices), and quality gates (what must be true before a PR is opened).
Templates. Reusable artifact templates for implementation plans, decision records, run logs, and other structured documents that agents create during execution.
Role-based execution. Defined roles (implementer, reviewer, PM, orchestrator) with corresponding sandboxing policies. A reviewer role gets read-only filesystem access; an implementer gets write access. This limits blast radius when agents operate autonomously.
Bootstrap Profiles
When you deploy IAS into a repository, you choose a bootstrap profile that determines what gets installed. Profiles are additive -- each larger profile includes everything from the smaller ones.
| Profile | Includes | Best for |
|---|---|---|
terminal | Docs scaffold, agent configs, local CLI | Interactive terminal agents only |
hybrid | Everything in terminal + automated runner | Automated execution and overnight runs |
control-plane | Docs scaffold, agent configs, Console integration | Teams using the Command Center |
full | Everything (CLI + runner + Console integration) | Full-featured setup |
For detailed installation instructions, profile selection guidance, and post-bootstrap configuration, see Deploying IAS to a Repository.
Repository Structure
After bootstrapping, your repository contains the following IAS-owned paths:
Documentation scaffold
| Path | Purpose |
|---|---|
docs/ias/project-context.md | Project metadata, constraints, stakeholders, success criteria |
docs/ias/gaps.md | Tracked knowledge gaps and open questions |
docs/ias/context/ | Human-curated context: base goal, inputs, references |
docs/ias/decisions/ | Auditable decision records |
docs/ias/runs/ | Goal-scoped execution artifacts (one directory per run) |
docs/ias/process/ | Agent operating procedures and policies |
docs/ias/templates/ | Reusable artifact templates |
docs/ias/policy/ | Git and execution policy configuration |
Agent configuration
| Path | Purpose |
|---|---|
AGENTS.md | Top-level agent operating protocol |
CLAUDE.md | Claude-specific operating notes |
.claude/ | Claude Code skills, commands, and settings |
.codex/skills/ | Codex CLI role-based skills |
Tooling
| Path | Purpose |
|---|---|
scripts/ias | Local helper CLI |
scripts/ias-runner/ | Hybrid runner for automated execution (hybrid/full profiles) |
CLI Commands
The IAS CLI spans the full agent lifecycle: setup, repository operations, and execution.
Setup and diagnostics
| Command | Description |
|---|---|
ias setup | Interactive first-time configuration (Console URL, auth, workspace) |
ias doctor | Verify your environment: Node.js, Git, auth tokens, config files |
ias auth login | Authenticate with the Command Center via browser-based device login |
Repository operations
| Command | Description |
|---|---|
ias install <path> | Bootstrap IAS into a repository (guided interactive flow) |
ias bootstrap <path> | Lower-level bootstrap with explicit flags and profile selection |
ias repo link <path> | Map a local checkout to a Command Center repository record |
ias repo inspect <path> | Display repository identity metadata |
ias preflight | Check that a bootstrapped repo is ready for a run |
ias new-run <slug> | Create a new run scaffold under docs/ias/runs/ |
Execution
| Command | Description |
|---|---|
ias worker start | Start the CLI worker (foreground, or --daemon for background) |
ias runner start | Start the hybrid runner for automated job execution |
ias agent start | Start both worker and runner together |
The worker and runner are distinct executors. The worker handles operational jobs (bootstrap, apply decision, build context). The runner handles work jobs -- the primary implementation job type that runs bounded Codex SDK turns. Running ias agent start launches both.
Git-Native by Design
All IAS artifacts are plain Markdown and JSON files committed to your repository. This design choice has several consequences:
- Full auditability. Every change an agent makes -- code, context, decisions -- is a Git commit with a real SHA. You can inspect, revert, or cherry-pick any change.
- No vendor lock-in. Artifacts are human-readable without IAS tooling. If you stop using IAS, everything remains in your repo as standard files.
- Works with any Git workflow. Feature branches, trunk-based development, pull requests, or any other branching strategy.
- Durable re-entry. Any agent can pick up where another left off by reading
docs/ias/. There is no "can you re-explain the project?" -- the context is in the files.
Local-Only Mode
For sensitive or client codebases where IAS framework files should not appear in Git history, use local-only mode:
ias install /path/to/repo --local-onlyLocal-only mode adds .gitignore rules that keep framework files (scripts, agent configs, process docs, templates) untracked while allowing project artifacts (project-context.md, decisions, gaps, runs) to be committed as usual.
Each developer on the team bootstraps locally to get the runtime files. Project context and decision records are still shared through Git for auditability.
For more details on local-only behavior, including runner telemetry handling, see Deploying IAS to a Repository.