charles/claude-hooks

Fork

You've already forked claude-hooks

Code Issues 10 Pull requests Projects Releases Packages 1 Wiki Activity Actions

M18-4: Architect agent bootstrap (host-mode, singleton) #165

New issue

Closed

opened 2026-04-20 16:02:57 +00:00 by code-lead · 0 comments

code-lead commented

2026-04-20 16:02:57 +00:00

Collaborator

Copy link

As an operator, I want a new architect agent type that runs in the host process (no container), has filesystem access to the repo, can call the service's own HTTP API, and exposes a persistent chat session the UI can talk to, so that spec writing / breakdown / assignment become an interactive workflow instead of webhook-only dispatch.

Acceptance criteria

Agent type

config/agents.json::types.architect entry:
- forgejo_user: "architect" (new Forgejo account; operator provisions the token file)
- default_model: "claude-opus-4-7[1m]" (1M context — spec work needs it)
- container: { enabled: false } — bypasses the container-reconcile flow
- plugins: [] — no per-agent plugin set (runs with the host's ~/.claude config)
- default_system_prompt — purpose, scope, guard-rails (full text in #M18-5)
Singleton: db.ts seeds one architect-default row; Agents CRUD UI refuses to create a second architect instance (409 Conflict)
ResolvedAgent gains a host_mode: boolean flag derived from container.enabled === false
agent-runner.runAgentTask branches: host mode skips container.ts::exec, invokes SDK query() inline in the service process with cwd: process.cwd()

Security & isolation

Host mode is only available to a hardcoded set of types (for now: architect). Any other type with container.enabled: false fails loadWebhookConfig at startup
Architect's SDK invocation inherits the service's env but loads its OWN credentials dir (~/.config/claude-hooks/agent-env/architect/). Operator provisions via just agent-env-sync architect
Skill surface restricted: architect can call breakdown, read/write specs/*.md, POST to its own service's /breakdown, /task, /cancel. Explicitly cannot merge PRs or push to main
scripts/smoke-creds.sh learns to probe architect (host-mode: filesystem + token file, not container exec)

Sessions & chat

New endpoints on apps/server:
- POST /architect/chat — body { session_id?, message }. If session_id absent, creates a new one. Returns { session_id, task_id } and starts streaming SSE at /architect/stream/:task_id
- GET /architect/sessions — list persisted sessions (id, first-message preview, last-updated, turn count)
- GET /architect/sessions/:id — full transcript
- DELETE /architect/sessions/:id — drop
Sessions stored in SQLite (architect_sessions table: id, created_at, updated_at, title, messages JSON)
SSE event shape matches existing pushEvent envelope so renderers can be shared with the monitor

Docs

CLAUDE.md "Roles" table gains architect row
README "Architect agent" section — purpose, limits, how to provision its token, how it differs from other agents

Tests

architect.test.ts — start a session, send a message, mock the SDK, assert the stream event shape
Routing sanity: architect CANNOT be targeted by webhook dispatch (unit test against webhook-routing.ts)

Out of scope

Chat UI itself — #M18-5
Multi-user sessions — singleton operator only
Running in a container — explicit non-goal (architect needs host access)

Dependencies

Blocks on #M18-2 (monorepo + packages/shared types).
Can parallel with #M18-3.
Unblocks #M18-5.

References

Spec: specs/m18-ui-rewrite-and-architect.md §Story M18-4

As an operator, I want a new **architect** agent type that runs **in the host process** (no container), has filesystem access to the repo, can call the service's own HTTP API, and exposes a persistent chat session the UI can talk to, so that spec writing / breakdown / assignment become an interactive workflow instead of webhook-only dispatch. ## Acceptance criteria ### Agent type - [ ] `config/agents.json::types.architect` entry: - `forgejo_user: "architect"` (new Forgejo account; operator provisions the token file) - `default_model: "claude-opus-4-7[1m]"` (1M context — spec work needs it) - `container: { enabled: false }` — bypasses the container-reconcile flow - `plugins: []` — no per-agent plugin set (runs with the host's `~/.claude` config) - `default_system_prompt` — purpose, scope, guard-rails (full text in #M18-5) - [ ] **Singleton**: `db.ts` seeds one `architect-default` row; Agents CRUD UI refuses to create a second architect instance (`409 Conflict`) - [ ] `ResolvedAgent` gains a `host_mode: boolean` flag derived from `container.enabled === false` - [ ] `agent-runner.runAgentTask` branches: host mode skips `container.ts::exec`, invokes SDK `query()` inline in the service process with `cwd: process.cwd()` ### Security & isolation - [ ] Host mode is only available to a hardcoded set of types (for now: `architect`). Any other type with `container.enabled: false` fails `loadWebhookConfig` at startup - [ ] Architect's SDK invocation inherits the service's env but loads its OWN credentials dir (`~/.config/claude-hooks/agent-env/architect/`). Operator provisions via `just agent-env-sync architect` - [ ] Skill surface restricted: architect can call `breakdown`, read/write `specs/*.md`, POST to its own service's `/breakdown`, `/task`, `/cancel`. Explicitly cannot merge PRs or push to `main` - [ ] `scripts/smoke-creds.sh` learns to probe architect (host-mode: filesystem + token file, not container exec) ### Sessions & chat - [ ] New endpoints on `apps/server`: - `POST /architect/chat` — body `{ session_id?, message }`. If `session_id` absent, creates a new one. Returns `{ session_id, task_id }` and starts streaming SSE at `/architect/stream/:task_id` - `GET /architect/sessions` — list persisted sessions (id, first-message preview, last-updated, turn count) - `GET /architect/sessions/:id` — full transcript - `DELETE /architect/sessions/:id` — drop - [ ] Sessions stored in SQLite (`architect_sessions` table: id, created_at, updated_at, title, messages JSON) - [ ] SSE event shape matches existing `pushEvent` envelope so renderers can be shared with the monitor ### Docs - [ ] CLAUDE.md "Roles" table gains `architect` row - [ ] README "Architect agent" section — purpose, limits, how to provision its token, how it differs from other agents ### Tests - [ ] `architect.test.ts` — start a session, send a message, mock the SDK, assert the stream event shape - [ ] Routing sanity: architect CANNOT be targeted by webhook dispatch (unit test against `webhook-routing.ts`) ## Out of scope - Chat UI itself — #M18-5 - Multi-user sessions — singleton operator only - Running in a container — explicit non-goal (architect needs host access) ## Dependencies - **Blocks on #M18-2** (monorepo + `packages/shared` types). - **Can parallel with #M18-3.** - **Unblocks #M18-5.** ## References - Spec: `specs/m18-ui-rewrite-and-architect.md` §Story M18-4

code-lead added this to the Next-gen UI + architect agent milestone

2026-04-20 16:02:57 +00:00

code-lead added the

area:agents

type:user-story

labels

2026-04-20 16:02:57 +00:00

code-lead was assigned by claude-desktop

2026-04-20 18:21:51 +00:00

code-lead referenced this issue from a commit

2026-04-20 18:45:16 +00:00

feat(architect): host-mode agent bootstrap (M18-4 / #165)

code-lead referenced this issue from a pull request that will close it,

2026-04-20 18:45:42 +00:00

feat(architect): host-mode agent bootstrap (M18-4) #180

code-lead referenced this issue from a commit

2026-04-20 18:57:28 +00:00

feat(architect): host-mode agent bootstrap (M18-4)

code-lead closed this issue

2026-04-20 18:57:28 +00:00

code-lead referenced this issue from a commit

2026-04-20 21:45:24 +00:00

feat(planner): architect chat UI with streaming + slash + @file (M18-5)

code-lead referenced this issue

2026-04-20 21:45:47 +00:00

feat(planner): architect chat UI with streaming + slash + @file (M18-5) #192

code-lead referenced this issue from a commit

2026-04-20 21:51:13 +00:00

feat(planner): architect chat UI with streaming + slash + @file (M18-5)

code-lead referenced this issue from a commit

2026-04-20 22:20:11 +00:00

feat(planner): architect chat UI with streaming + slash + @file (M18-5) (#192)

claude-desktop referenced this issue

2026-04-21 11:21:33 +00:00

refactor(agents): rename architect agent type → foreman #217

code-lead referenced this issue from a commit

2026-04-21 11:36:07 +00:00

refactor(agents): rename architect agent type → foreman (#217)

No Branch/Tag specified

main

chore/sync-pre-push-from-forge-base

fix/flows-yaml-dispatch-identity

feat/board-tap-to-assign

dev/1107

code-lead/1106

code-lead/1108

dev/1104

code-lead/1103

code-lead/1080

dev/1087

feat/flows-yaml-ci-events

chore/board-drop-stalled-and-density-controls

fix/flows-yaml-routes-always-register

flows-yaml/api-defaults

dev/1023

fix/event-log-history-bleed

fix/janitor-fix-ci-logs-and-cap

dev/1022

fix/board-card-provider

code-lead/1036

dev/1025

code-lead/1020

dev/1017

code-lead/1026

feat/web-shortcut-registry-1018

dev/1015

code-lead/1009

code-lead/1008

dev/975

dev/969

dev/973

dev/967

code-lead/968

code-lead/953

dev/970

dev/976

code-lead/966

code-lead/956

code-lead/951

dev/962

dev/963

dev/977

dev/955

dev/983

dev/961

dev/974

code-lead/950

code-lead/939

dev/941

dev/940

dev/937

dev/938

dev/936

dev/935

feat/web-i18n-fr-locale

feat/spec-editor-ui-polish

chore/drop-legacy-compat

fix/skills-drop-preview-pane

fix/882-skills-safety-rail

dev/911

dev/909

dev/923

dev/917

dev/915

feat/879-sr11-m2-drop-legacy-skill

code-lead/873

dev/881

code-lead/869

dev/867

code-lead/845

code-lead/843

code-lead/844

dev/837

dev/861

dev/849

code-lead/837

code-lead/842

fix/dedup-rebase-inflight

dev/838

code-lead/847

dev/833

code-lead/848

pr/838

code-lead/841

feat/settings-save-bar/836

code-lead/840

dev/846

code-lead/839

dev/832

fix/board-sse-stale-cache

dev/834

dev/835

feat/settings-breadcrumbs

feat/forge-oauth-credentials

refactor/service-config-consolidation

feat/agent-tokens-to-secrets

feat/gitlab-oauth-to-db

feat/authelia-rip-and-voice-fixes

fix/rebase-storm-and-dead-letter

code-lead/797

code-lead/796

dev/811

code-lead/798

dev/810

code-lead/795

dev/808

code-lead/794

dev/805

dev/802

dev/803

feat/avatar-menu-settings-entry

feat/per-agent-token-tracking

dev/793

dev/747

dev/752

code-lead/790

code-lead/759

dev/756

dev/760

dev/741

dev/767

dev/740

dev/709

dev/644

dev/637

boss/614

dev/600

dev/611

dev/585

fix/login-bonus-fixes

boss/544

dev/542

refactor/api-prefix-and-session-gate

dev/489

boss/531

boss/518

dev/499

boss/516

dev/530

dev/517

dev/519

dev/515

dev/522

dev/503

dev/471

boss/329

dev/417

dev/418

dev/402

boss/327

dev/334

dev/332

boss/326

boss/325

dev/331

boss/324

boss/323

boss/322

dev/294

test/s11-task-analytics

dev/262

boss/270

dev/268

foreman/ui-consolidation-spec

dev/234

boss/196

boss/176

boss/164

fix/124-session-persist-bind

boss/52

dev/87

boss/73

dev/77

dev/81

dev/82

boss/79

dev/42

dev/35

boss/7

No results found.

Labels

Clear labels

area:agents

Agent types, pool scheduling, per-instance config

area:dashboard

Dashboard UI and observability surfaces

area:database

DB layer — schema, migrations, ORM, raw SQL

area:design

UI/UX mockup work — routes to designer agent

area:design-review

Design review dispatch — routes to design-reviewer agent

area:flows

Flow runner — YAML loader, executor, op registry, expression eval

area:infra

Deployment, isolation, containers, systemd units

area:meta

Tracking, scaffolding, project setup

area:security

Security — routes to reviewer-security (opus)

area:sessions

Session-id store, Claude SDK resume logic

area:webhook

Forgejo webhook routing and handlers

area:workdir

Clone cache, worktrees, git identity

security

Security-sensitive issue

Tracking or decisions, not implementation work

No labels

Milestone

Clear milestone

No items

No milestone

Next-gen UI + architect agent

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

code-lead

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

charles/claude-hooks#165

Reference in a new issue

Repository

charles/claude-hooks

Title

Body

No description provided.

Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?

Rows
Columns