Core Concepts

IAS is built around a small set of concepts that work together. This page gives you a quick mental model of each one -- enough to navigate the Console, talk to your team, and understand what agents are doing on your behalf.

Workspaces

A workspace is your team's top-level boundary in IAS. It groups repositories, team members, jobs, and configuration under a single tenancy.

• Think of it like a GitHub organization -- everything your team does happens inside a workspace.
• Each workspace has a unique slug (e.g., acme-eng), its own member list, and its own policies.
• Most teams need only one workspace. Create additional workspaces when you need hard isolation between projects or clients.

Next step: Create a workspace to get started.

Repositories

A repository in IAS is a reference to a Git repository your team works on. The Console stores metadata about the repo -- its name, URL hash, connection status, and job history -- but never the source code itself.

• Repositories are registered in the Console, then linked to a local checkout on your machine via ias repo link.
• Each repository has its own job queue, decision log, goal history, and agent activity.
• You can manage multiple repositories within a single workspace.

Next step: Add a repository and link it locally.

Jobs and Tasks

Jobs are the fundamental units of work in IAS. Every action an agent performs -- writing code, reviewing a pull request, bootstrapping a repository -- is tracked as a job.

Job lifecycle

Each job moves through a defined set of states:

Job types

IAS uses specialized job types for different kinds of work:

Each job carries a prompt (what the agent should do), evidence (what it accomplished), and metadata (timing, ownership, retry state).

Goals (Runs)

A goal -- also called a run -- is a scoped unit of work with a clear outcome. When you tell IAS "Add user settings page with theme preference," that becomes a goal.

• Goals are stored as artifacts in your repository under docs/ias/runs/YYYYMMDD-<slug>/.
• Each goal directory contains the original intent, proposal, task breakdowns, decision records, and execution evidence.
• The Console maintains a pointer to each goal so you can track progress and review outcomes from the web UI.
• Goals decompose into one or more jobs that agents execute. As jobs complete, evidence accumulates in both the repo and the Console.

Goals can be created from the Console UI, via the CLI (./scripts/ias new-run <slug>), or through the intake flow.

Intakes and Goal Proposals

Intakes are the front door for getting work into IAS. An intake captures your raw input -- a description of what you want done, in plain language -- and turns it into a structured, reviewable plan before any code is written.

How intent becomes a goal

1. Capture -- You submit an intake with your intent. This can be a sentence, a detailed spec, or anything in between. You can attach files, links, and context.
2. Intent review -- IAS processes the intake through an AI-powered review that produces a structured goal proposal. The proposal includes scope, constraints, a readiness scorecard, and identified gaps.
3. Approval -- You review the proposal. If it looks right, approve it and IAS creates a goal with associated tasks. If it needs refinement, iterate on the proposal or answer blocking questions first.

The readiness scorecard highlights missing information, ambiguous requirements, and potential risks before any code is written. Conversion to a goal is blocked if critical policy gates are not met.

Inbox and Decision Requests

The Inbox is the canonical mechanism for human-in-the-loop collaboration. When an agent encounters ambiguity or a choice that requires human judgment, it creates a decision request that appears in your Inbox.

How decision requests work

1. Request -- While executing a job, an agent creates a decision request with structured options, context about why the decision matters, and often a recommended path.
2. Answer -- You review the request in your Inbox and select an option. Your answer is recorded with a timestamp and rationale.
3. Apply -- For run-scoped decisions, IAS creates an Apply Decision job that commits the corresponding change to the repository. The commit links back to the decision record for traceability.

Decision requests are designed to be non-blocking. Agents can continue working on other tasks while waiting for your answer. When you respond, work resumes automatically.

Every decision and its answer become part of the permanent audit trail in both the Console and the repository.

Learn more: Inbox and Decision Requests

Uncertainties

Not every unknown becomes a decision request. Agents track uncertainties internally -- missing information identified during execution. Many uncertainties are resolved autonomously through research, inference, or reasonable defaults.

When an uncertainty cannot be resolved without human input, it gets escalated to a decision request in your Inbox. This two-tier model means you only see the decisions that genuinely need your judgment.

Uncertainties are tracked in the repository under docs/ias/gaps.md, giving you visibility into what assumptions agents are making even when they do not ask for help.

Agents (Workers)

An agent -- also called a worker -- is a local process that connects to the Console, claims jobs from the queue, and executes them against your Git checkout.

• Agents heartbeat to the Console at regular intervals to report availability.
• When a job enters the queue for a mapped repository, the agent claims and executes it.
• Execution happens entirely locally -- the agent reads from and writes to your Git repository.
• When done, the agent reports evidence back to the Console: commit SHAs, PR URLs, changed files, and logs.

IAS has two agent components:

Start both together with ias agent start, or run them independently with ias worker start and ias runner start.

Next step: Configure agents to start processing tasks.

AI runtime compatibility

IAS agents work with the AI coding tools you already use. The agent framework connects to Claude Code, Codex CLI, and Gemini CLI. The Console adds orchestration and visibility without replacing your preferred AI runtime.

Context Lake

The Context Lake is IAS's unified knowledge layer. It aggregates context from multiple sources -- your codebase, documentation, tickets, conversations, and previous agent runs -- into a structured form that agents can consume.

• Rather than re-explaining your project for each goal, the Context Lake provides durable, up-to-date context that any agent can read.
• This is what allows one agent to pick up where another left off without losing understanding.
• Context is built automatically via the Build Context and Context Architect jobs, or populated manually.

Key context artifacts live in your repository under docs/ias/:

Because these artifacts are committed to Git, they are portable, versioned, and accessible to any tool -- not just IAS.

Learn more: Context Lake

Spaces and Workstreams

Spaces and workstreams help you organize visibility and focus within a workspace.

• A workstream represents a stream of related work -- for example, a product area, a client engagement, or a sprint theme.
• A space is a view that scopes the Console UI to a subset of repositories, goals, and activity relevant to a particular workstream.

Spaces let team members focus on what matters to them without seeing unrelated noise. They are an organizational layer on top of the core workspace, not a security boundary.

Learn more: Spaces and Workstreams

Git as the Source of Truth

IAS treats Git as the canonical source of truth for all work. This is a deliberate architectural choice:

• Every action produces a commit. When an agent writes code, answers a decision, or modifies context, the result is a Git commit with a real SHA. You can inspect, revert, or cherry-pick any change.
• Full audit trail. The chain from intent to goal to task to commit is traceable. You can always answer "why was this change made?" by following the trail.
• No hidden state. Agent context, decisions, gaps, and run state live in files in your repository, not in an opaque database.
• Durable re-entry. Because context lives in repo files rather than chat history, any agent can pick up where another left off. There is no "can you re-explain the project?" -- the agent reads docs/ias/ and understands the current state.
• Portability. If you stop using IAS, all artifacts remain in your repository as plain Markdown and JSON files. There is no data export step.

The Console maintains its own database for coordination (job queues, agent status, real-time updates), but the repository is always the authoritative record of what was done and why.