Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
c4996c4
docs(design): polish prototype status semantics and shared chrome
boh5 Aug 10, 2026
4f53cc6
docs(design): sync inspector polish and status lexicon
boh5 Aug 10, 2026
f4ffcbe
feat(design): sync micro-interactions and depth improvements to desig…
boh5 Aug 10, 2026
08ae3cf
fix(design): apply P0/P1 visual quality improvements
boh5 Aug 10, 2026
d853691
feat(prototypes): complete P2 polish improvements
boh5 Aug 10, 2026
893ee33
polish: comprehensive UI refinements across all prototypes
boh5 Aug 10, 2026
cb98acd
polish: enhance session.html UI components
boh5 Aug 10, 2026
6beb8c9
polish: unify typography across all prototypes
boh5 Aug 10, 2026
f73d240
docs(design): sync MASTER.md + pages/*.md with prototype polish (mode…
boh5 Aug 11, 2026
c527b28
polish(prototypes): simplify model menu, attachments, and inspector c…
boh5 Aug 11, 2026
445c8ed
feat(prototypes): refine project navigation rail
boh5 Aug 11, 2026
0d1f607
feat(prototypes): refine Todo capture and preview flow
boh5 Aug 11, 2026
02619f7
feat(workbench): align product with signal design system
boh5 Aug 13, 2026
d00e6bd
fix(session): preserve completed responses across restart
boh5 Aug 13, 2026
bde005a
feat(design-system): adopt Todo-only workbench design
boh5 Aug 16, 2026
c31f0ee
style(design-system): refine prototype visual depth
boh5 Aug 16, 2026
202fee6
feat(design-system): finalize Todo-only workbench contracts
boh5 Aug 16, 2026
747ecad
feat(workbench): hard-cut the Todo-only product
boh5 Aug 17, 2026
fc50542
test(agent-core): wait for persisted skill message
boh5 Aug 17, 2026
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
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ bun.lockb
.archcode
.specra
.playwright-mcp
.codex/config.toml
__test_tmp__/
__test__/
.turbo/
Expand Down
44 changes: 31 additions & 13 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,9 +71,11 @@ design-system/
└── prototypes/
```

`MASTER.md` and `pages/` are normative design specifications.
`prototypes/` contains supporting visual references, not authoritative
specifications.
`MASTER.md` and `pages/` define approved product and interaction contracts.
For a page with a current effective prototype, that prototype's actual browser
render is the visual delivery and visual acceptance authority. Source code,
tokens, DOM inspection, screenshots inferred from CSS, or prose specifications
cannot substitute for looking at the rendered prototype and rendered product.

Follow this order for every UI task:

Expand All @@ -82,9 +84,11 @@ Follow this order for every UI task:
explicit deviations from the Master and override it only for that page.
3. Inspect the current rendered product and implementation for established
product behavior, state semantics, and component interactions.
4. Inspect the relevant current HTML prototype under
`design-system/prototypes/` when one exists. Use it only as a supporting
rendered reference.
4. Open the relevant current HTML prototype under `design-system/prototypes/`
in a real browser when one exists. Use its actual rendered visual result as
the target for layout, density, typography, color, responsive behavior, and
interaction presentation; never claim visual completion from file or code
inspection alone.
5. UI/UX Pro Max is advisory, not authoritative. Use its searches as candidate
evidence and filter recommendations through ArchCode's established quiet
engineering workbench direction; never replace the Master with generic
Expand All @@ -94,9 +98,15 @@ Follow this order for every UI task:
product implementation as applicable.

Resolve conflicts as follows: a page override modifies `MASTER.md` only for
that page; the current product is authoritative for existing behavior and state
mechanics; an HTML prototype never overrides `MASTER.md`, a page override, or
current product behavior.
that page; the current product is authoritative for existing runtime facts,
domain state, persistence, and behavior that an approved design decision does
not intentionally change. The current prototype is authoritative for visual
delivery, while `MASTER.md` and page overrides define the product/interaction
rules that the visual must satisfy. A prototype never invents product
capability: if it visibly implies behavior the product does not have, classify
the mismatch before implementation. Fix an obvious prototype defect in the
prototype; escalate a genuine product decision to the user. Only explicitly
approved hard-cut decisions may remove or change existing product behavior.

Create or update an HTML prototype only for a new complex module, a major
layout change, or an uncertain visual direction. Routine UI fixes and small
Expand All @@ -111,12 +121,16 @@ that page's HTML instead of creating page-specific `.css` or `.js` files.

The current references are:

- Global Home: `design-system/prototypes/dashboard.html`
- Root no-project entry: `design-system/prototypes/index.html`
- Todos: `design-system/prototypes/todos.html`
- Automations: `design-system/prototypes/automations.html`
- Sessions: `design-system/prototypes/sessions.html`
- Session detail: `design-system/prototypes/session.html`

There is no Dashboard prototype. The root entry is only the zero-project
registration state; with a current/last project, `/` resolves to that project's
All todos surface as specified by `design-system/pages/root.md`.

When browser QA needs an HTTP origin, serve the prototype root without first
changing into that directory:

Expand Down Expand Up @@ -307,7 +321,11 @@ Every descriptor declares an explicit `outputPolicy`. Registry is the sole Raw-t
- `profiles.principal`, `profiles.deep`, and `profiles.fast` are all required, and unknown configuration keys fail strict validation.
- Profile-default merge order is shallow: model `options` → selected `variants[variant]` → Profile `options`. A user-facing root Session override resolves independently and never inherits principal Profile options.
- `providerOptions` follows the same shallow merge rule as one top-level key: later layers replace the whole `providerOptions` object rather than deep-merging nested provider settings.
- Unknown model ids, unknown variant names, and missing Profile config all fail fast with actionable errors.
- Missing required Profile config and unknown model ids are invalid. A Profile
may retain a removed Variant name for repair: Settings presents it as
attention and the runtime resolves that Profile through the selected Model's
default options until repaired. An explicit invalid Session override falls
back to its selected Profile; it never passes the unknown Variant downstream.
- LLM execution is centralized in `packages/agent-core/src/llm/`. Non-LLM runtime code must not import `streamText` or `generateText` directly from `"ai"`; use `runLlmStream`, `runLlmText`, or `runLlmObject` instead.
- `maxRetries` is not a configuration field. Managed calls force AI SDK `maxRetries: 0` so ArchCode owns retry/recovery, including HTTP 200 stream-body EOF/truncated-SSE failures that AI SDK retries cannot recover.
- Retry constants are internal v1 implementation details. There is no global recovery retry config yet. Existing auto-compact behavior is preserved; emergency context-overflow compact automation is follow-up/out-of-scope.
Expand Down Expand Up @@ -467,13 +485,13 @@ Project: `.archcode/runtime/memory/`, User: `~/.archcode/memory/` (user-global,

## Project Todos

Project Todos are project-owned intent, separate from Session-local `todo_write` execution checklists. Global `/` is Home; `/projects/:slug` redirects to the Project's `/projects/:slug/todos` board. Project pages share one `Todos / Automations / Sessions` toolbar, while Sessions remain independently creatable and recoverable execution workbenches. `ProjectTodoStateManager` owns strict Todo persistence, flat state updates (`idea`, `ready`, `in_progress`, `done`, `rejected`), archive state, revision checks, the canonical array order, ordered current `attachmentIds`, and narrow durable Run-now receipts. `ProjectTodoService` is the only Todo application boundary: it exposes list/create/flat-update, attachment operations, the composed `Run now` command, and root Session creation for `discussion`, `work`, and `automation`. A Todo never stores reverse Session, Plan, or Automation links.
Project Todos are project-owned intent, separate from Session-local `todo_write` execution checklists. Global `/` is only a registry-backed entry resolver: it replaces to the current/last valid project's `/projects/:slug/todos`, falls back to the first registered project in server order, or renders the sole no-project registration state. `ProjectLayout` owns the persistent Todo navigator, New Todo capture, and project-scoped Inspector; there is no aggregate Home and no `Todos / Automations / Sessions` project toolbar. `/projects/:slug` redirects to `/projects/:slug/todos`, while Runs and Schedules remain independently creatable and recoverable operational destinations inside the Todo workbench. `ProjectTodoStateManager` owns strict Todo persistence, flat state updates (`idea`, `ready`, `in_progress`, `done`, `rejected`), archive state, revision checks, the canonical array order, ordered current `attachmentIds`, and narrow durable Run-now receipts. `ProjectTodoService` is the only Todo application boundary: it exposes list/create/flat-update, attachment operations, the composed `Run now` command, and root Session creation for `discussion`, `work`, and `automation`. A Todo never stores reverse Session, Plan, or Automation links.

A Todo can have any number of root Sessions with immutable `{ kind: "todo", todoId, entry }` source. Each root family resolves the Todo's current attachment set at model and tool boundaries; references are never copied into Session messages or storage. `discussion` roots activate `shape-todo`, may update only their source Todo, and may delegate only Explore/Librarian. **Generate / Improve Plan** reuses the latest Discussion only when it is idle, then invokes `plan-work` for the unique `.archcode/plans/<todo-id>.md`. If no Discussion exists, the latest one is busy or suspended, it was deleted, or an idle reuse loses the acceptance race, the action creates a new Discussion whose first accepted message is the Plan request; it never races a generic Discussion start with a second command. Plan existence is not persisted; the Todo Plan endpoint only performs a fixed-path, bounded Markdown read. `work` and `automation` roots may start only from Ready or In Progress. At work creation only, `ProjectTodoService` checks that Plan path: an existing file starts with `execute-plan`, while no file preserves ordinary implementation behavior. Starting from Ready moves the Todo to In Progress, while starting from In Progress leaves it there. A Todo-created Automation stores immutable `{ kind: "todo", todoId, sessionId }` origin; every `start_session` Invocation persists `{ kind: "automation", automationId, invocationId, todoId }`. Direct-origin Invocations persist `todoId: null`. Todo moves never create, stop, rebind, or delete Sessions or Automations.

## HITL

HITL is a durable project-scoped approval/question queue backed by `.archcode/runtime/hitl-queue.json`. Server and Web routes expose redacted `displayPayload` data for approval/Home views; raw sensitive payloads must not be rendered or persisted in UI state. Deferred permission/question flows resolve safely on timeout, cancellation, or shutdown so long-running agent execution is not left hanging.
HITL is a durable project-scoped approval/question queue backed by `.archcode/runtime/hitl-queue.json`. Server and Web routes expose redacted `displayPayload` data for exact approval/question destinations and Todo navigator attention views; raw sensitive payloads must not be rendered or persisted in UI state. Deferred permission/question flows resolve safely on timeout, cancellation, or shutdown so long-running agent execution is not left hanging.

## Automation System

Expand Down
Loading
Loading