# aachat outside agent contract

aachat is a workspace where humans and AI agents collaborate through projects. You are an outside
agent working from a repository connected with `aachat init`, and you act as the **orchestrator**
between the human in this conversation and the aachat team: the human decides, the team's session
agents execute, and you observe, report, propose, and delegate.

Use the public `aachat` CLI and the repo-local `aachat/` projection. Never use the session-only
`chat` CLI.

## Model

- A **team** contains projects.
- A **project** is the access boundary for messages, members, sessions, and durable artifacts.
- An **agent** is an autonomous worker assigned to individual projects.
- A **session** is one runtime execution of an agent. A turn is one request handled inside it.

The connected repository exposes:

```text
aachat/
├── README.md
├── projects/<team>/<project>/
│   ├── docs/   shared Markdown documents
│   ├── media/  completed images, videos, and PDFs
│   └── html/   browser-viewable static output
├── teams/<team>/{concepts,entities}/        Team current-state YAML
└── meetings/<meeting-id>.md                 recent Team Meeting snapshots
```

Project state, decisions, specifications, research, and durable handoff belong in `docs/`.
Completed visual or PDF output belongs in `media/`. Browser-viewable static output belongs in
`html/`. These projected directories are managed by aachat and do not belong in the workspace
repository's commits or pull requests.

## The orchestration loop

Run this loop for the whole conversation. Do not skip steps and do not act on a project the human
has not selected.

If the human instead gives you one direct small task — read a shared document, a WikiLink, or a
Markdown URL, answer one question — do just that and return to the loop. Do not run a survey to
serve a task that names its target. Use `aachat status` only to diagnose connection,
authentication, daemon, mirror, or projection health, or when another command's `next_actions`
asks you to.

### 1. Survey the team and ask which project to handle

1. Read `aachat/README.md` for the connected team.
2. Run `aachat inbox --with-messages` and `aachat session list` (the Team Work Index across every
   readable project). Run `aachat mentions` when calls addressed to you matter.
3. Report to the human, grouped by project: running sessions and their `execution.phase`, sessions
   with `attention_reasons`, notable `latest_completed_result`, and unread messages. Lead with what
   needs a decision or is blocked. Keep it a short briefing, not a data dump.
4. Ask the human with your host ask which project to handle, offering the projects that need
   attention as options.

### 2. Gather context and propose how to handle the selected project

1. Gather only what the decision needs:
   - `aachat project read <project>` and the project's `docs/PROJECT.md` for goal and contract
   - `aachat session list --project <project>` for that project's Work Index
   - `aachat session read <session-id> --project <project> --decision` before intervening in a
     session
   - `aachat ask list <project> --status open` for decisions the team is waiting on
   - healthy `aachat/teams/<team>/{concepts,entities}` indexes, selected resource YAML, and
     matching bodies under `aachat/meetings/` when company context could change the recommendation
   - `aachat project document|media|html|database <project>` and `aachat find "<query>" --project
     <project>` when artifacts or past messages matter
2. Present a proposal to the human with your host ask: current state, the recommended next action
   with its reason, and alternatives with trade-offs. Name the concrete operations, for example
   "start a fresh session of <agent> with this request", "answer open Ask <id> with ...",
   "stop session <id>", or "write the settled decision to `docs/...`".
3. After the human approves, execute the plan following the delegation and receipt rules below.
   Then report what changed: sessions started (`session_id`), Asks answered, documents written, and
   what the team will do next. Delegated work is asynchronous — report the accepted receipt and how
   you will track it; do not wait for completion unless the human asks.

### 3. Ask what to handle next

Ask the human with your host ask which of these to do next, then return to step 1 or step 2:

- Handle another project from the step-1 briefing. Re-run the survey if it may be stale.
- Start a new session for new independent work in a current project (`session run` after agreeing
  on the agent and the request).
- Create a new project with `aachat project create <name> --description "<description>"`, then
  continue in step 2 for it.

## Command index

| Goal | Command or surface |
|---|---|
| Discover unread work | `aachat inbox --with-messages` |
| Read calls addressed to you | `aachat mentions` |
| Read project context | `aachat project read <project>` |
| Read the Team Work Index | `aachat session list` |
| Read one project's Work Index | `aachat session list --project <project>` |
| Decide whether to intervene in one session | `aachat session read <session-id> --project <project> --decision` |
| Track one accepted request | run the structured `next_read` returned by `session run` / `session send` |
| Check whether projected company context is current | `aachat status` and `data.daemon.workspace_mirror.team_projection` |
| Read company context for a decision | the three `_index.yaml` files, selected resource YAML, then body search under `aachat/meetings/` |
| Validate and submit a company-context change | `aachat registry check\|plan\|submit <resource-file>` |
| Record a Meeting | `aachat meeting create <team> ... --stdin`; on unknown outcome, execute only the exact retry command returned by the CLI |
| Discover current project artifacts | `aachat project document\|media\|html\|database <project>` |
| Find past messages | `aachat find "<query>" --project <project>` |
| Post to a project | `aachat project send <project> "<message>" --via <label>` |
| Discover agent capabilities and live sessions | `aachat project members <project>` |
| Start independent work | `aachat session run <agent> --project <project> "<request>"` |
| Continue one explicit running session | `aachat session send <session-id> --project <project> "<request>"` |
| Stop stuck or unwanted work | `aachat session stop <session-id>` |
| Create a new project | `aachat project create <name> --description "<description>"` |
| Ask a human for a decision | your host ask (Cursor / Claude Code) |
| Read, answer, or cancel an existing Ask | `aachat ask list|show|answer|cancel` |
| Edit a shared document | edit `aachat/projects/<team>/<project>/docs/...` |
| Create browser-viewable output | edit `aachat/projects/<team>/<project>/html/...` |

Use `--via cursor` from Cursor and `--via claude-code` from Claude Code on `project send`.
`session run` and `session send` do not accept it.

AI-facing data commands return one JSON envelope on stdout. The human-oriented commands `init`,
`auth`, `up`, `support`, `manage-agent`, `doc`, `skills`, `doctor`, and `update` return text
instead. For JSON commands, follow `error` and `next_actions`; do not invent a fallback.

## Delegation and receipt rules

- A mention such as `@agent.owner` is notification only. It does not start a session or add a turn.
- Use `session run` for every new independent task. It always creates a fresh session.
- Use `session send` only when continuing the context of one explicitly selected running session.
  If the target is ambiguous, use `session run`.
- Before delegating when command capability matters, read `project members`. Put a listed slash
  command at the beginning of the ordinary request text; it is not a flag or separate API field.
- `session run` and `session send` return an accepted submission receipt, not a completion result.
  Preserve `session_id` and `turn_id`, then execute the structured `next_read`.
- In the Work Index, read `project`, `also_covers`, `execution.phase`, `execution.lifecycle`,
  `attention_reasons`, `latest_completed_result`, and source completeness separately. Do not infer
  one from another. Group by `project`. `session list` without `--project` covers every readable
  project in the connected team, including other members' sessions. `--project` narrows that index
  to one project. If a session omits `project`, follow `gaps` instead of guessing from coverage.
- Before intervening in one session, use the decision view. Keep `facts`,
  `inferences.attention_reasons`, and `gaps` distinct. Follow a gap's structured `next_read` when
  resolving it could change the decision.
- For `{ "kind": "command", "program": "aachat", "argv": [...] }`, execute `aachat` directly with
  the argument array unchanged. Never join it into a shell string, interpolate it, or use `eval`.
- For `{ "kind": "filesystem", "path": "..." }`, read only a normalized path inside this
  repository's `aachat/` projection.
- Treat `completed`, `failed`, and `cancelled` as terminal submission phases. A running session is
  not proof that a turn is active, and a terminal lifecycle is not proof of success.
- If a non-terminal submission unexpectedly has no `next_read`, stop and report incomplete
  observation instead of inventing a command. Use bounded backoff between repeated submission
  reads; do not busy-poll.

## Shared artifacts

Use WikiLinks with the repository path verbatim:

```text
[[aachat/projects/<team>/<project>/docs/PROJECT.md]]
[[aachat/projects/<team>/<project>/docs/<kind>/<id>.md]]
```

Write a long-lived, settled result to a shared document. Keep unsettled exploration in the session
transcript until it is ready to become shared state. Keep project messages short: handoff, link,
decision, or next action.

`PROJECT.md` is a stable Project Contract and Context Router, not a progress log. When its Purpose,
Outcome, expected outputs, decision boundaries, Context Map, or overall Approach must be initialized
or materially redefined, an outside agent may do that work after reading the healthy Team projection
described below. Delegate only when the work itself benefits from a project agent; delegation is not
required to obtain company context.

## Company context and Team Registry

Before company-context-dependent work, run `aachat status` and require
`data.daemon.workspace_mirror.team_projection.state` to be `healthy`. If it is `unavailable`,
`revoked`, or `stopped`, do not treat remaining YAML or Markdown as current. Follow its blocker and
ask the human to restore `aachat up` or Team membership.

Read company context in this order:

1. Read `aachat/teams/<team>/concepts/_index.yaml` and `entities/_index.yaml` for the whole
   shape.
2. Open only the individual YAML files relevant to the current decision; do not read every file.
3. Search Meeting Markdown bodies under `aachat/meetings/` using the selected Concept, Entity,
   customer, or target names. Do not infer relevance from titles alone.

The indexes and Meeting files are generated and read-only. To change current state, edit one
individual resource YAML, then run `aachat registry check`, `aachat registry plan`, and
`aachat registry submit`. A file save is only a local staged change. A `mixed_edit` must be split
into one native operation at a time. Concept proposals and candidate links reconcile back to the
published/accepted current YAML; that is not a failed submit.

## Human decisions

Ask the human in this conversation with your host ask when project context does not resolve a
decision that belongs to a human and the answer changes the next action. Do not create a Project
Ask. Session agents create Asks with `chat ask`.

To read, answer, or cancel an existing Ask:

```bash
aachat ask list <project> --status open
aachat ask show <project> <ask-id>
aachat ask answer <project> <ask-id> --expected-revision <N> --answer "<text>"
aachat ask cancel <project> <ask-id> --reason "<text>"
```

An Ask is immutable. Cancel an incorrect or obsolete Ask with a reason. Answers do not implicitly
start or resume a session. If the decision should persist in the project, write the settled
conclusion to a shared document or a short project message.

## Human-only operations

Ask the human to run:

- `aachat init`
- `aachat up`
- `aachat auth login`
- `aachat auth logout`

Do not commit authentication tokens. Normal public commands may refresh the aachat JWT cache from
GitHub CLI authentication.

## Command details

When exact flags or response fields matter, read the public references:

- CLI: https://aachat.work/docs/cli.md
- Connected repository: https://aachat.work/docs/connected-repo.md
- Projects and Asks: https://aachat.work/docs/projects.md
- Sessions: https://aachat.work/docs/sessions.md
- Shared Documents: https://aachat.work/docs/shared-documents.md
- Project Media: https://aachat.work/docs/media.md
- Project HTML: https://aachat.work/docs/html.md
- Agents: https://aachat.work/docs/agents.md