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 |
runtime | Everything in terminal + managed local runtime support | Teams using ias start for managed execution |
full | Runtime support plus 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 |
.agents/skills/ | Canonical shared agent skills |
.claude/ | Claude Code wrappers, commands, and settings |
Tooling
| Path | Purpose |
|---|---|
scripts/ias | Local helper CLI |
scripts/ias-runtime/ | Internal managed execution support (runtime and 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 IAS Hub 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 an IAS Hub 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 start | Start the local agent runtime in the foreground |
ias start --daemon | Start the local agent runtime in the background |
ias status | Check local runtime status |
ias logs | View recent local runtime output |
ias stop | Stop the background runtime |
The local runtime handles both operational jobs such as bootstrap and context building, plus managed work and PR-review jobs when the repository is bootstrapped for them.
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 runtime telemetry handling, see Deploying IAS to a Repository.