Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,9 +145,9 @@ Most code changes do not need a documentation change. Agents can read the code.

## Plans and work artifacts

- Do not commit per-task implementation plans, research notes, or agent scratch files. Keep temporary working material outside the worktree. `.plans/` is gitignored only as a safety net for legacy tooling. The exception is J5's own planning and research record: `docs/j5/plans/` and `docs/j5/research/` are committed, and follow [how the J5 docs are organized](docs/j5/process/docs.md).
- Do not commit implementation plans, research notes, or agent scratch files. Keep temporary working material outside the worktree. `.plans/` is gitignored only as a safety net for legacy tooling.
- Track active work in the GitHub issue that owns it, on `Jacksondr5/j5code`.
- A merged PR is the implementation record. Close or update its tracking item when the work lands; do not keep a second checklist in the repository. A plan under `docs/j5/plans/` states build status against a definition's criteria; that is its job, not a second checklist.
- A merged PR is the implementation record. Close or update its tracking item when the work lands; do not preserve a second checklist in the repository.

## How it works

Expand Down
2 changes: 1 addition & 1 deletion FORK.md
Original file line number Diff line number Diff line change
Expand Up @@ -280,7 +280,7 @@ Current candidate pin: `67a2be0fdbee7afb64b691f147ed286a108c706b`, from `t3code/

The upstream PR branch is moving history and has already been force-rewritten. Do not assume a future branch tip descends from this commit.

Every advance follows [Merging upstream](docs/j5/process/upstream-merge.md) and rewrites the [upstream convergence watchlist](docs/j5/research/upstream-convergence.md).
Every advance follows [Merging upstream](docs/j5/process/upstream-merge.md) and rewrites the [upstream convergence watchlist](docs/j5/product/upstream-convergence.md).

### Pin log

Expand Down
7 changes: 2 additions & 5 deletions docs/j5/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Everything about J5 Code — the product built on this fork of T3 Code — lives under `docs/j5/`. Upstream's own documentation (`docs/user/`, `docs/internals/`, `docs/operations/`) is left as upstream wrote it; J5 never edits it.

Every document here is one of five kinds, and the kind tells you how far to trust it: **definitions** describe the product and are kept true; **plans** sequence work and are history once executed; **research** reports what we learned as of a date; **records** say what happened on a day; **runbooks** tell an operator what to do. The kinds, their lifetimes, the identifier scheme, and the rules for changing a definition are in [how the docs are organized](process/docs.md) — read it before writing anything here.
Every document here is one of four kinds, and the kind tells you how far to trust it: **definitions** describe the product and are kept true; **records** say what happened on a day; **runbooks** tell an operator what to do; **process** docs are the rules for working in this repository. Plans, research, and build status live in GitHub issues and pull requests, not here. The kinds, their lifetimes, the identifier scheme, and the rules for changing a definition are in [how the docs are organized](process/docs.md) — read it before writing anything here.

## Reading order for newcomers

Expand All @@ -15,13 +15,10 @@ Agents changing the code: read the [J5 overview](product/overview.md) and [J5 an
5. [Glossary](product/glossary.md) — the vocabulary; every name in these docs resolves here.
6. [Agent-to-agent communication](product/a2a/index.md), then [Squadron](product/features/squadron.md) — the two definitions everything else stands on.
7. The rest of [`product/features/`](product/features/) — the feature definitions of record.
8. [Research synthesis](research/synthesis.md) — what we learned from T3 Code and Traycer.

## Contents

- **`product/`** — definitions: the [overview](product/overview.md) and [J5 and upstream](product/upstream.md), the core documents above, the [A2A trio](product/a2a/) (the communication protocol, the upstream substrate, the agent tool contracts), and [`features/`](product/features/) (Squadron, inbox, thread rendering, archive flow, Roles, Crews, Memos, Playbooks, Spawning Guide, sidebar and roster, PR pane, Shared Squadrons).
- **`plans/`** — the [dogfood v0 plan](plans/dogfood-v0.md) and the [A2A plan](plans/a2a.md). Build status against a definition's criteria lives only here. The backlog beyond these is the repository's GitHub milestones, in outcome order.
- **`research/`** — the studies behind the decisions: T3 Code, Traycer, the prior-art fleets, remote hosting. Each carries an `as_of` date; none is a source of truth about the product.
- **`product/`** — definitions: the [overview](product/overview.md) and [J5 and upstream](product/upstream.md), the core documents above, the [A2A trio](product/a2a/) (the communication protocol, the upstream substrate, the agent tool contracts), and [`features/`](product/features/) (Squadron, inbox, thread rendering, archive flow, Roles, Crews, Memos, Playbooks, Spawning Guide, sidebar and roster, Shared Squadrons).
- **`worklog/`** — records, named date-first: design sessions and rulings, the tickets and reviews of the A2A build and the dogfood queue, how the fork was set up, the phase-3 friction list.
- **`runbooks/`** — operating the software: the [dogfood runtime](runbooks/dogfood-runtime.md), [agent migration](runbooks/agent-migration.md), [macOS packaging](runbooks/macos-packaging.md), [machine senders](runbooks/machine-senders.md).
- **`process/`** — rules for working in this repository: [how the docs are organized](process/docs.md), [working in the repo](process/working-in-the-repo.md), [merging upstream](process/upstream-merge.md), and [pull requests](process/pull-requests.md). How the fleet is run day to day is the operator's own practice and lives outside the repository.
Expand Down
Loading
Loading