git:20260818.5925d86 to git:20260823.32d84c1

# Agents Inc — repository root

An agent composition framework for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).

Compose specialized subagents from atomic skills: pick a stack, choose your skills from an

interactive grid, and compile subagents that carry exactly the skills you selected. This was a single

CLI package until 2026-08-04 and is now a monorepo; `packages/cli` is still the only workspace that

publishes to npm.

| Workspace | What it is |

| ------------------- | ------------------------------------------------------ |

| `packages/cli` | the published CLI — `agents-inc` on npm |

| `apps/editor` | the editor (Vite + React, deployed to Cloudflare) |

| `apps/www` | the Astro site — landing page at `/`, docs at `/docs` |

| `apps/server` | the API worker (Hono) |

| `packages/matrix` | the skill catalog the web app reads |

| `packages/ui` | the design system shared by the web app |

| `packages/*-config` | shared eslint, prettier, typescript and vitest configs |

[`README.md`](./README.md) carries the full layout and how to work in the repository.

## Where things live

- **[`packages/cli/.ai-docs/DOCUMENTATION_MAP.md`](./packages/cli/.ai-docs/DOCUMENTATION_MAP.md)** is

the documentation index, and **[`packages/cli/CLAUDE.md`](./packages/cli/CLAUDE.md)** is the guide

for CLI work specifically. Read both when the work is in that package — neither loads from here.

- **[`todo/`](./todo/)** holds everything outstanding, one file per workspace:

[`cli.md`](./todo/cli.md), [`editor.md`](./todo/editor.md), [`www.md`](./todo/www.md),

[`server.md`](./todo/server.md), [`repo.md`](./todo/repo.md) for the repository itself, and

[`skills.md`](./todo/skills.md) for the skills marketplace repository, whose diffs land in

[`agents-inc/skills`](https://github.com/agents-inc/skills) rather than here.

[`plans/`](./todo/plans/) holds the detail for items that need it, and

[`archive.md`](./todo/archive.md) records what has landed.

[`ROADMAP.md`](./todo/ROADMAP.md) sequences everything outstanding across all six trackers —

phases in execution order; the trackers stay canonical, the roadmap only orders them and is

updated whenever a phase moves.

- **An item is deleted when it lands rather than ticked off**, and one line is appended to

`archive.md`. There is no done column and nothing is struck through, so everything in a tracker is

still open — and `archive.md` is the only record that a finished item ever existed.

## Repository-wide

- **Never run a git command that WRITES — read-only git is fine.** Reading is allowed and useful:

`git status`, `log`, `show`, `diff`, `blame`, `stash list` — checking history, dating a

regression, verifying what changed. What is forbidden is anything that mutates the index, the

working tree, history or a remote: `git add`, `commit`, `reset`, `stash` (push/pop/drop),

`checkout`, `restore`, `clean`, `push`, `rebase`, `merge`, amend. The user curates staging

deliberately (clarified by the owner 2026-08-09; the rule previously read as an absolute ban).

This rule is in `packages/cli/CLAUDE.md` as well, but it is not the CLI's rule and that file

does not load from here.

- **The CLI is deliberately narrower than the editor.** It handles a few clear use cases; the full

experience is the editor, and the two front doors are not meant to be feature-equivalent. So a CLI

surface that is smaller than the editor's is a design decision rather than a gap. The test is

direction of travel: the CLI must **consume** anything the editor can produce — a payload it cannot

install is a real defect — but it need not **author** what the editor authors. Both halves have

already been ruled in practice: the skill-category dropdown is editor-only because nothing on the

CLI side creates a custom skill, while the CLI installing editor-added external skills was a

genuine blocker, because that is consumption.

- **Always compact the session at 500k context used.** Not at a hard limit, and not only when

asked. Sessions here run long and orchestrate many sub-agents, each returning a large report, so

context fills unevenly and a limit hit mid-programme loses the thread of what landed, what is

running and what is still owed. Compact between units of work rather than mid-dispatch, so the

summary records a clean state.

- **`packages/cli` formats itself** — 100 columns, semicolons, double quotes — while everything else

uses the root config. Prettier picks the nearest config walking up, so this happens on its own; the

reasoning is in the `//` notes in [`package.json`](./package.json).

## How work gets implemented

Agreed process. It applies to every item in `todo/`, and the order is the point.

1. **Write the tests first — end-to-end plus whatever else fits — and watch them fail.** A test

that has never failed has not been shown to test anything.

2. Implement until they pass.

3. **Then** apply the `meta-design-expressive-typescript` skill — that skill only, no sub-agents —

and bring the code in line with its principles.

4. **Then run it by hand through the CLI** and confirm it does what it claims. Passing tests and a

working command are different claims; the `--from` work proved that when a green-looking path

exited 13 on an unsettled Ink render that no assertion covered.

5. **Then update the docs**, through the `codex-keeper` agent rather than inline — beyond the counts

a change's own diff moved.

6. **Then update `todo/`, in the same turn the work lands.** Delete the row from its tracker, append

one line to [`archive.md`](./todo/archive.md), and update [`ROADMAP.md`](./todo/ROADMAP.md) if a

phase moved. All three, always — a finished task still sitting in a tracker is indistinguishable

from an unstarted one, and `archive.md` is the only record that it ever existed. **The roadmap is

the half that gets forgotten**: it once ran a full day stale while eleven of its twenty rows

landed, which would have told a fresh session the programme had not started.

No jumping to step 2, and steps 5 and 6 are not a tidy-up phase to batch at the end — they are how

the work is finished.

**Sub-agents do not edit `todo/`.** The orchestrator does, as each agent lands. The trackers carry

curated git staging and several agents land at once, so briefs should say so explicitly.