chapterhouse 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/LICENSE +23 -0
  2. package/README.md +363 -0
  3. package/agents/chapterhouse.agent.md +40 -0
  4. package/agents/coder.agent.md +38 -0
  5. package/agents/designer.agent.md +43 -0
  6. package/agents/general-purpose.agent.md +30 -0
  7. package/dist/api/auth.js +159 -0
  8. package/dist/api/auth.test.js +463 -0
  9. package/dist/api/errors.js +95 -0
  10. package/dist/api/errors.test.js +89 -0
  11. package/dist/api/rate-limit.js +85 -0
  12. package/dist/api/server-runtime.js +62 -0
  13. package/dist/api/server.js +651 -0
  14. package/dist/api/server.test.js +385 -0
  15. package/dist/api/sse.integration.test.js +270 -0
  16. package/dist/api/sse.js +7 -0
  17. package/dist/api/team.js +196 -0
  18. package/dist/api/team.test.js +466 -0
  19. package/dist/cli.js +102 -0
  20. package/dist/config.js +299 -0
  21. package/dist/config.phase3.test.js +20 -0
  22. package/dist/config.test.js +148 -0
  23. package/dist/copilot/agents.js +447 -0
  24. package/dist/copilot/agents.squad.test.js +72 -0
  25. package/dist/copilot/classifier.js +72 -0
  26. package/dist/copilot/client.js +32 -0
  27. package/dist/copilot/client.test.js +100 -0
  28. package/dist/copilot/episode-writer.js +219 -0
  29. package/dist/copilot/episode-writer.test.js +41 -0
  30. package/dist/copilot/mcp-config.js +22 -0
  31. package/dist/copilot/okr-mapper.js +196 -0
  32. package/dist/copilot/okr-mapper.test.js +114 -0
  33. package/dist/copilot/orchestrator.js +685 -0
  34. package/dist/copilot/orchestrator.test.js +523 -0
  35. package/dist/copilot/router.js +142 -0
  36. package/dist/copilot/router.test.js +119 -0
  37. package/dist/copilot/skills.js +125 -0
  38. package/dist/copilot/standup.js +138 -0
  39. package/dist/copilot/standup.test.js +132 -0
  40. package/dist/copilot/system-message.js +143 -0
  41. package/dist/copilot/system-message.test.js +17 -0
  42. package/dist/copilot/tools.js +1212 -0
  43. package/dist/copilot/tools.okr.test.js +260 -0
  44. package/dist/copilot/tools.squad.test.js +168 -0
  45. package/dist/daemon.js +235 -0
  46. package/dist/home-path.js +12 -0
  47. package/dist/home-path.test.js +11 -0
  48. package/dist/integrations/ado-analytics.js +178 -0
  49. package/dist/integrations/ado-analytics.test.js +284 -0
  50. package/dist/integrations/ado-client.js +227 -0
  51. package/dist/integrations/ado-client.test.js +176 -0
  52. package/dist/integrations/ado-schema.js +25 -0
  53. package/dist/integrations/ado-schema.test.js +39 -0
  54. package/dist/integrations/ado-skill.js +55 -0
  55. package/dist/integrations/report-generator.js +114 -0
  56. package/dist/integrations/report-generator.test.js +62 -0
  57. package/dist/integrations/team-push.js +144 -0
  58. package/dist/integrations/team-push.test.js +178 -0
  59. package/dist/integrations/teams-notify.js +108 -0
  60. package/dist/integrations/teams-notify.test.js +135 -0
  61. package/dist/paths.js +41 -0
  62. package/dist/setup.js +149 -0
  63. package/dist/shutdown-signals.js +13 -0
  64. package/dist/shutdown-signals.test.js +33 -0
  65. package/dist/squad/charter.js +108 -0
  66. package/dist/squad/charter.test.js +89 -0
  67. package/dist/squad/context.js +48 -0
  68. package/dist/squad/context.test.js +59 -0
  69. package/dist/squad/discovery.js +280 -0
  70. package/dist/squad/discovery.test.js +93 -0
  71. package/dist/squad/index.js +7 -0
  72. package/dist/squad/mirror.js +81 -0
  73. package/dist/squad/mirror.scheduler.js +78 -0
  74. package/dist/squad/mirror.scheduler.test.js +197 -0
  75. package/dist/squad/mirror.test.js +172 -0
  76. package/dist/squad/registry.js +162 -0
  77. package/dist/squad/registry.test.js +31 -0
  78. package/dist/squad/squad-coordinator-system-message.test.js +190 -0
  79. package/dist/squad/squad-session-routing.test.js +260 -0
  80. package/dist/squad/types.js +4 -0
  81. package/dist/status.js +25 -0
  82. package/dist/status.test.js +22 -0
  83. package/dist/store/db.js +290 -0
  84. package/dist/store/db.test.js +126 -0
  85. package/dist/store/squad-sessions.test.js +341 -0
  86. package/dist/test/setup-env.js +3 -0
  87. package/dist/update.js +112 -0
  88. package/dist/update.test.js +25 -0
  89. package/dist/wiki/context.js +138 -0
  90. package/dist/wiki/fs.js +195 -0
  91. package/dist/wiki/fs.test.js +39 -0
  92. package/dist/wiki/index-manager.js +359 -0
  93. package/dist/wiki/index-manager.test.js +129 -0
  94. package/dist/wiki/lock.js +26 -0
  95. package/dist/wiki/lock.test.js +30 -0
  96. package/dist/wiki/log-manager.js +20 -0
  97. package/dist/wiki/migrate.js +306 -0
  98. package/dist/wiki/okr.test.js +101 -0
  99. package/dist/wiki/path-utils.js +4 -0
  100. package/dist/wiki/path-utils.test.js +8 -0
  101. package/dist/wiki/seed-team-wiki.js +296 -0
  102. package/dist/wiki/seed-team-wiki.test.js +69 -0
  103. package/dist/wiki/team-sync.js +212 -0
  104. package/dist/wiki/team-sync.test.js +185 -0
  105. package/dist/wiki/templates/okr.js +98 -0
  106. package/package.json +72 -0
  107. package/skills/.gitkeep +0 -0
  108. package/skills/find-skills/SKILL.md +161 -0
  109. package/skills/find-skills/_meta.json +4 -0
  110. package/skills/frontend-design/LICENSE.txt +177 -0
  111. package/skills/frontend-design/SKILL.md +42 -0
  112. package/skills/squad/SKILL.md +76 -0
  113. package/web/dist/assets/index-D-e7K-fT.css +10 -0
  114. package/web/dist/assets/index-DAg9IrpO.js +142 -0
  115. package/web/dist/assets/index-DAg9IrpO.js.map +1 -0
  116. package/web/dist/chapterhouse-icon.png +0 -0
  117. package/web/dist/chapterhouse-icon.svg +42 -0
  118. package/web/dist/chapterhouse-logo.svg +46 -0
  119. package/web/dist/index.html +15 -0
package/LICENSE ADDED
@@ -0,0 +1,23 @@
1
+ NOTICE: Chapterhouse is built on the original Max work by Burke Holland (https://github.com/burkeholland/max).
2
+
3
+ MIT License
4
+
5
+ Copyright (c) 2026 Burke Holland
6
+
7
+ Permission is hereby granted, free of charge, to any person obtaining a copy
8
+ of this software and associated documentation files (the "Software"), to deal
9
+ in the Software without restriction, including without limitation the rights
10
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11
+ copies of the Software, and to permit persons to whom the Software is
12
+ furnished to do so, subject to the following conditions:
13
+
14
+ The above copyright notice and this permission notice shall be included in all
15
+ copies or substantial portions of the Software.
16
+
17
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,363 @@
1
+ # Chapterhouse
2
+
3
+ Team-level AI orchestrator for engineering teams, powered by [Copilot SDK](https://github.com/github/copilot-sdk) — a daemon you run on your machine, controlled entirely from a web UI in your browser.
4
+
5
+ ## Attribution
6
+
7
+ Chapterhouse is built on [Max](https://github.com/burkeholland/max) by [Burke Holland](https://github.com/burkeholland). The original Max codebase provided the foundation for this project.
8
+
9
+ ## Highlights
10
+
11
+ - **Always running** — persistent local daemon with a browser frontend at `http://localhost:7788`.
12
+ - **Builds team memory without leaking personal context** — every Chapterhouse instance keeps a private local wiki at `~/.chapterhouse/wiki/`, while shared team pages live on the authoritative Team Chapterhouse deployment and sync down read-only to personal instances. That gives each engineer a place for personal notes and conversation history without turning OKRs, KPIs, and team docs into conflicting local forks.
13
+ - **Codes while you're away** — spins up real Copilot CLI worker sessions in any directory and reports back when they're done. The Workers tab in the web UI shows what's running.
14
+ - **Learns any skill** — pulls from [skills.sh](https://skills.sh) or builds new skills on demand.
15
+ - **Your Copilot subscription** — works with any model your subscription includes (Claude, GPT, Gemini, …). Auto-routing picks a tier per message.
16
+
17
+ ## Installation
18
+
19
+ **Requires Node.js 22.5 or later.**
20
+
21
+ Install globally via npm:
22
+
23
+ ```bash
24
+ npm install -g chapterhouse
25
+ ```
26
+
27
+ After installing, run first-time setup:
28
+
29
+ ```bash
30
+ chapterhouse setup
31
+ ```
32
+
33
+ Setup walks you through:
34
+
35
+ 1. **GitHub token** — Chapterhouse uses the Copilot CLI under the hood. Run `copilot login` (or `gh auth login --scopes copilot`) to authenticate before starting.
36
+ 2. **Config file** — Setup writes `~/.chapterhouse/.env`. You can edit it at any time. Key variables:
37
+
38
+ ```bash
39
+ # Required
40
+ COPILOT_MODEL=claude-sonnet-4-5 # default model; overridable per session
41
+
42
+ # Optional — API token auth (simpler, single-user)
43
+ API_TOKEN=your-secret-token
44
+
45
+ # Optional — Microsoft Entra ID auth (team deployments)
46
+ ENTRA_AUTH_ENABLED=true
47
+ ENTRA_TENANT_ID=your-tenant-id
48
+ ENTRA_CLIENT_ID=your-client-id
49
+
50
+ # Optional — Azure DevOps OKR integration
51
+ ADO_ORG=https://dev.azure.com/your-org
52
+ ADO_PROJECT=your-project
53
+ ADO_PAT=your-ado-pat-here
54
+
55
+ # Optional — Squad (multi-agent team) integration
56
+ ENABLE_SQUAD=1 # set to 1 to enable squad agent routing
57
+
58
+ # Optional — periodic decisions→wiki sync (requires ENABLE_SQUAD=1)
59
+ CHAPTERHOUSE_DECISIONS_SYNC_INTERVAL_MS=300000 # default 5 minutes (300 000 ms)
60
+ ```
61
+
62
+ Then start the daemon:
63
+
64
+ ```bash
65
+ chapterhouse start
66
+ ```
67
+
68
+ Open `http://localhost:7788` in your browser.
69
+
70
+ ## Install
71
+
72
+ ### Windows
73
+
74
+ ```powershell
75
+ irm https://raw.githubusercontent.com/bketelsen/chapterhouse/main/install.ps1 | iex
76
+ ```
77
+
78
+ ### macOS / Linux
79
+
80
+ ```bash
81
+ curl -fsSL https://raw.githubusercontent.com/bketelsen/chapterhouse/main/install.sh | bash
82
+ ```
83
+
84
+ Or clone and build manually:
85
+
86
+ ```bash
87
+ git clone https://github.com/bketelsen/chapterhouse.git ~/.chapterhouse/src
88
+ cd ~/.chapterhouse/src
89
+ npm install && npm run build && npm link
90
+ ```
91
+
92
+ ## Upgrading
93
+
94
+ If you already have Chapterhouse installed:
95
+
96
+ ```bash
97
+ chapterhouse update
98
+ ```
99
+
100
+ Or manually: `cd ~/.chapterhouse/src && git pull && npm install && npm run build`. Your `~/.chapterhouse/` config carries forward automatically.
101
+
102
+ ## Quick Start
103
+
104
+ ### 1. Run setup (one time)
105
+
106
+ ```bash
107
+ chapterhouse setup
108
+ ```
109
+
110
+ Picks a default model and writes `~/.chapterhouse/.env`. Past versions also configured Telegram — that's gone in v2; the web UI is the only client.
111
+
112
+ If you plan to use the Azure DevOps OKR integration, also set these in `~/.chapterhouse/.env`:
113
+
114
+ ```bash
115
+ ADO_ORG=https://dev.azure.com/your-org
116
+ ADO_PROJECT=your-project
117
+ ADO_PAT=your-ado-pat-here
118
+ ```
119
+
120
+ `ADO_ORG` and `ADO_PROJECT` are no longer baked into the app and must match your Azure DevOps tenant.
121
+
122
+ ### 2. Make sure Copilot CLI is authenticated
123
+
124
+ ```bash
125
+ copilot login
126
+ ```
127
+
128
+ ### 3. Start Chapterhouse
129
+
130
+ ```bash
131
+ chapterhouse start
132
+ ```
133
+
134
+ Or `chapterhouse start --open` to also pop a browser tab.
135
+
136
+ ### 4. Talk to Chapterhouse
137
+
138
+ Open `http://localhost:7788` in your browser and start typing. Examples:
139
+
140
+ - "Start working on the auth bug in /full/path/to/myapp"
141
+ - "What sessions are running?"
142
+ - "Check on the api-tests session"
143
+ - "What's the capital of France?"
144
+
145
+ ## Authentication modes
146
+
147
+ Chapterhouse currently supports two server auth modes:
148
+
149
+ 1. **Legacy API token** — set `API_TOKEN` (or persist a token at `~/.chapterhouse/api-token`). The loopback-only `/api/bootstrap` endpoint hands that token to the local SPA, which then sends it as `Authorization: Bearer ...` on API and SSE requests.
150
+ 2. **Microsoft Entra ID** — set `ENTRA_AUTH_ENABLED=true`, `ENTRA_TENANT_ID`, and `ENTRA_CLIENT_ID`. The web UI uses MSAL in the browser, signs the user in with Microsoft, and sends the **ID token** to the backend. The backend verifies that token against the tenant JWKS endpoint and treats the token's `roles` claim as the source of truth for app-role authorization.
151
+
152
+ Optional Entra settings:
153
+
154
+ - `ENTRA_REQUIRED_ROLE` — if set, the signed-in user must have this app role in the token's `roles` claim. This replaced the older group-based check.
155
+ - `ENTRA_TEAM_LEAD_ID` — optional for regular engineers, who can omit it entirely. Set it only for the one person who should be treated as `team-lead` for managerial functions such as `/api/team/report` and protected OKR/KPI/team wiki writes. Without it, the signed-in user is treated as `engineer`, which is the correct role for normal team members.
156
+
157
+ ## Docker (Personal)
158
+
159
+ For a single-user local deployment, use the personal compose file. It binds port `7788`, runs the daemon as the non-root `node` user, and persists state in `CHAPTERHOUSE_HOME` (default: `$HOME/.chapterhouse` on macOS/Linux).
160
+
161
+ **Authentication is required for Docker deployments.** Set either `API_TOKEN` or a working Entra config in `.env` before starting the container. For Entra, that means `ENTRA_AUTH_ENABLED=true`, `ENTRA_TENANT_ID`, and `ENTRA_CLIENT_ID`; add `ENTRA_REQUIRED_ROLE` if you want app-role gating. `ENTRA_TEAM_LEAD_ID` is optional for regular engineers and should only be set for the one person who needs team-lead/managerial permissions. If it is omitted, the user is treated as `engineer`. The process binds to `0.0.0.0` inside the container so Docker can publish port `7788`, and Chapterhouse refuses to start if neither auth mode is configured.
162
+
163
+ ```bash
164
+ cp .env.example .env # or create .env with your settings
165
+ docker compose -f docker-compose.personal.yml up --build -d
166
+ ```
167
+
168
+ `docker-compose.personal.yml` mounts `CHAPTERHOUSE_HOME` to `/home/node/.chapterhouse`, `COPILOT_HOME` to `/home/node/.copilot`, `GH_CONFIG_HOME` to `/home/node/.config/gh` (read-only), and loads `.env`, so you can provide `API_HOST`, `API_TOKEN`, any `ENTRA_*` settings, `TEAM_CHAPTERHOUSE_*` sync settings, and optional Copilot token overrides there.
169
+
170
+ By default, the compose file falls back to `$HOME/.chapterhouse`, `$HOME/.copilot`, and `$HOME/.config/gh`. On Windows, set the host paths explicitly before starting the stack:
171
+
172
+ ```powershell
173
+ $env:CHAPTERHOUSE_HOME = "$env:USERPROFILE\.chapterhouse"
174
+ $env:COPILOT_HOME = "$env:USERPROFILE\.copilot"
175
+ $env:GH_CONFIG_HOME = "$env:USERPROFILE\.config\gh"
176
+ docker compose -f docker-compose.personal.yml up --build -d
177
+ ```
178
+
179
+ You can also put those variables in a local `.env` file next to `docker-compose.personal.yml` if you prefer not to export them in your shell.
180
+
181
+ ### Docker Authentication
182
+
183
+ Chapterhouse uses the Copilot SDK's default logged-in-user auth flow unless you set an explicit token. In Docker, the recommended setup is:
184
+
185
+ 1. Authenticate on the host with `gh auth login`.
186
+ 2. Start the personal compose stack. The container reuses host GitHub CLI auth through the read-only `GH_CONFIG_HOME` mount.
187
+ 3. If you prefer an explicit token, set `COPILOT_TOKEN` in `.env` (or `GITHUB_TOKEN` as a fallback). Chapterhouse passes that token to the Copilot SDK directly. Classic `ghp_` personal access tokens are not supported by Copilot.
188
+
189
+ If auth expires or you want to authenticate from inside the container, run:
190
+
191
+ ```bash
192
+ docker compose -f docker-compose.personal.yml run --rm -it chapterhouse copilot login
193
+ ```
194
+
195
+ That login is persisted in `COPILOT_HOME`, so you only need to repeat it when the Copilot session expires or you want to switch accounts.
196
+
197
+ ## Team Deployment
198
+
199
+ For an Azure Container Apps deployment with Azure Container Registry, Azure Files-backed wiki storage, Key Vault, and a managed identity, see [deploy/README.md](deploy/README.md).
200
+
201
+ The deployment assets for the shared instance set Entra auth and `CHAPTERHOUSE_MODE=team`. In team mode, Chapterhouse seeds the shared wiki on first start so the initial OKR, KPI, team, and shared pages exist immediately.
202
+
203
+ ## CLI Commands
204
+
205
+ | Command | Description |
206
+ | --------------------------- | ------------------------------------------------- |
207
+ | `chapterhouse start` | Start the Chapterhouse daemon (web UI + HTTP API) |
208
+ | `chapterhouse start --open` | Same, plus open the browser |
209
+ | `chapterhouse setup` | Interactive first-run configuration |
210
+ | `chapterhouse update` | Check for and install updates |
211
+ | `chapterhouse help` | Show available commands |
212
+
213
+ ### Flags
214
+
215
+ | Flag | Description |
216
+ | ------------- | -------------------------------------------------------------------------------- |
217
+ | `--self-edit` | Allow Chapterhouse to modify its own source code (use with `chapterhouse start`) |
218
+ | `--open` | Open the web UI in your default browser when the daemon is ready |
219
+
220
+ ## Web UI
221
+
222
+ The browser app at `http://localhost:7788` is split into a few views:
223
+
224
+ - **Chat** — streaming markdown chat with the orchestrator. Type `/help` to see slash commands (`/cancel`, `/copy`, `/clear`, `/restart`, plus shortcuts to other tabs).
225
+ - **Workers** — list of running and recent agent tasks. Click one to inspect its description, status, and final output.
226
+ - **Wiki** — browse and edit local wiki pages under `~/.chapterhouse/wiki/pages/`. On personal instances, reads of team-scoped paths go through the team wiki sync layer instead of editing the shared source directly.
227
+ - **History** — daily conversation summaries written to your personal wiki under `pages/conversations/`.
228
+ - **Skills** — list of installed skills, broken out by source (bundled / local / global). Local skills can be uninstalled in place.
229
+ - **Settings** — model picker, auto-routing toggle, restart button.
230
+
231
+ ## How it Works
232
+
233
+ ```
234
+ Browser ──HTTP / SSE──► Chapterhouse Daemon
235
+
236
+ Orchestrator Session (Copilot SDK)
237
+
238
+ ┌───────────┼───────────┐
239
+ Worker 1 Worker 2 Worker N
240
+ ```
241
+
242
+ - **Daemon** (`chapterhouse start`) — persistent service running Copilot SDK + HTTP API + SPA static server.
243
+ - **Web UI** — Vite-built React SPA, served by the daemon out of `web/dist/`.
244
+ - **Orchestrator** — long-running Copilot session with custom tools for session management.
245
+ - **Workers** — child Copilot sessions for specific coding tasks.
246
+
247
+ ### Two-Tier Wiki Architecture
248
+
249
+ Chapterhouse uses two wiki layers on purpose: **personal memory stays local**, while **team knowledge has one authoritative home**. That split is what lets an engineer save private notes and conversation history freely without turning shared planning documents into a pile of unsynchronized copies.
250
+
251
+ #### Personal Wiki (private, local)
252
+
253
+ Your personal wiki lives at `~/.chapterhouse/wiki/`.
254
+
255
+ - It stores your local preferences, conversation history, personal notes, and the cached copies of team pages fetched from the team deployment.
256
+ - It is never shared or synced back to Team Chapterhouse.
257
+ - Your local instance can write to it freely, which makes it the right place for agent memory, scratch knowledge, and anything that should not become team policy just because one assistant session mentioned it.
258
+
259
+ The personal-memory tools still work against this local wiki:
260
+
261
+ - **`remember`** — save a fact, preference, project note, or decision into your private wiki
262
+ - **`recall`** / **`wiki_search`** / **`wiki_read`** — search the local wiki index, then open specific pages
263
+ - **`forget`** — remove lines, revise sections, or delete a local page
264
+ - **Index-first context** — Chapterhouse injects a ranked wiki summary into prompts so agents see what they already know without loading the full wiki every turn
265
+ - **Episodic memory** — daily conversation summaries are written asynchronously to `pages/conversations/YYYY-MM-DD.md`
266
+
267
+ #### Team Wiki (shared, authoritative on Team Chapterhouse)
268
+
269
+ The team wiki lives on the **Team Chapterhouse** instance and is the authoritative source for shared operating knowledge. Personal instances sync from it read-only so there is one place to manage OKRs, KPIs, team membership, and shared runbooks.
270
+
271
+ This is why the more sensitive namespaces are restricted: quarterly targets, KPI definitions, and official team roster data should not drift because several personal instances edited different copies at the same time. Shared notes stay collaborative, but the canonical planning data stays controlled.
272
+
273
+ On Entra-backed deployments, `ENTRA_TEAM_LEAD_ID` is optional for regular engineers. When it is set, Chapterhouse marks the signed-in user as `team-lead` when their token's `oid` matches that value. If it is omitted or the `oid` does not match, the authenticated user is treated as an `engineer`, which is the correct role for normal team members.
274
+
275
+ **Page namespaces and write permissions:**
276
+
277
+ | Path | Who can write | Purpose |
278
+ |------|--------------|---------|
279
+ | `pages/okrs/` | Team lead only | OKR definitions and quarterly targets |
280
+ | `pages/kpis/` | Team lead only | Team KPI tracking |
281
+ | `pages/team/` | Team lead only | Team member profiles, onboarding |
282
+ | `pages/shared/` | Any team member | Notes, decisions, runbooks, shared knowledge |
283
+
284
+ On a fresh team deployment, Chapterhouse seeds the wiki with starter pages for:
285
+
286
+ - `pages/okrs/2026-Q2.md`
287
+ - `pages/kpis/team.md`
288
+ - `pages/team/index.md`
289
+ - `pages/team/onboarding.md`
290
+ - `pages/shared/README.md`
291
+
292
+ #### Sync behavior on personal instances
293
+
294
+ Set `TEAM_CHAPTERHOUSE_URL` on a personal instance to enable team wiki sync. Once enabled:
295
+
296
+ - Requests to the team instance reuse the current browser session's `Authorization` header automatically; `TEAM_CHAPTERHOUSE_TOKEN` is an optional fallback for non-browser or pre-authenticated flows
297
+ - Team pages are fetched from the Team Chapterhouse API on demand
298
+ - Cached pages are stored locally at `~/.chapterhouse/wiki/.team-cache/`
299
+ - Cache freshness is controlled by `TEAM_WIKI_CACHE_TTL_MINUTES` (default: `60`)
300
+ - If Team Chapterhouse is unreachable, Chapterhouse serves stale cached content instead of failing hard
301
+ - Synced namespaces come from `TEAM_WIKI_PATHS` (default: `pages/team,pages/okrs,pages/kpis,pages/shared`)
302
+ - Listing wiki pages in the personal UI triggers a full sync and indexes the fetched team pages locally so they are discoverable in the wiki browser and prompt context
303
+
304
+ Relevant personal-instance settings:
305
+
306
+ ```bash
307
+ TEAM_CHAPTERHOUSE_URL=https://your-team-chapterhouse-url.azurecontainerapps.io
308
+ TEAM_CHAPTERHOUSE_TOKEN=
309
+ TEAM_WIKI_CACHE_TTL_MINUTES=60
310
+ TEAM_WIKI_PATHS=pages/team,pages/okrs,pages/kpis,pages/shared
311
+ ```
312
+
313
+ That cache is there for reliability as much as speed: engineers can keep reading the last known team state even when the shared deployment is temporarily unavailable.
314
+
315
+ #### Team wiki API (Team Chapterhouse)
316
+
317
+ The shared deployment exposes these wiki endpoints:
318
+
319
+ - `GET /api/team/wiki` — list all team wiki pages under the configured synced namespaces
320
+ - `GET /api/team/wiki/:path` — read a page (any team member)
321
+ - `PUT /api/team/wiki/:path` — write a page (subject to namespace permissions)
322
+
323
+ #### Tools available from personal Chapterhouse
324
+
325
+ Personal instances can work with the team wiki through dedicated tools instead of editing the shared source by hand:
326
+
327
+ - **`write_team_wiki`** — write shared notes to `pages/shared/` from any personal instance
328
+ - **`get_my_okrs`** — fetch the key results currently owned by the signed-in user from the team wiki
329
+
330
+ ## Development
331
+
332
+ ```bash
333
+ # Clone and install
334
+ git clone https://github.com/bketelsen/chapterhouse.git
335
+ cd chapterhouse
336
+ npm install
337
+ npm --prefix web install
338
+
339
+ # Watch mode (server)
340
+ npm run dev
341
+
342
+ # Watch mode (web UI, in a second terminal — proxies to the daemon on 7788)
343
+ npm run dev:web
344
+
345
+ # Build everything
346
+ npm run build
347
+ ```
348
+
349
+ The web UI lives in `web/`. Production builds emit to `web/dist/`, which the Express server serves out of in `src/api/server.ts`.
350
+
351
+ ### Releasing a new version
352
+
353
+ The release flow is: bump version → commit → tag → push (tag triggers npm publish via CI).
354
+
355
+ ```bash
356
+ # 1. Bump the version in package.json
357
+ npm version patch # or minor / major
358
+
359
+ # 2. Push the commit and the tag
360
+ git push origin main --follow-tags
361
+ ```
362
+
363
+ `npm version` handles the commit and tag automatically. `prepublishOnly` runs `npm run build` before publish so the tarball always contains a fresh build. If you don't have CI set up, publish manually with `npm publish` after the tag push.
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: Chapterhouse
3
+ description: Orchestrator — routes tasks to specialist agents and handles direct conversation
4
+ model: claude-sonnet-4.6
5
+ ---
6
+
7
+ You are Chapterhouse, a team-level AI assistant for engineering teams running 24/7 on the user's machine. You are the engineering team's always-on assistant.
8
+
9
+ ## Your Role
10
+
11
+ You are the orchestrator. You receive all user messages and decide how to handle them:
12
+
13
+ - **Direct answer**: For simple questions, general knowledge, status checks, math, quick lookups — answer directly. No tool calls needed.
14
+ - **Delegate to a specialist**: For tasks that need coding, design, or deep work — use `delegate_to_agent` to hand the task to the right agent.
15
+ - **Use a skill**: If you have a skill for what the user asks (email, browser, etc.), use it.
16
+
17
+ ## Your Agents
18
+
19
+ You manage a team of specialist agents. Each has their own persistent session, model, and expertise:
20
+
21
+ {agent_roster}
22
+
23
+ ## Delegation Rules
24
+
25
+ 1. **You are the dispatcher, not the laborer.** If a task requires running commands, editing files, writing code, debugging, or any execution — delegate it.
26
+ 2. **Pick the right specialist.** Design/UI work → @designer. Coding/debugging → @coder. Everything else → @general-purpose.
27
+ 3. **One tool call, one brief response.** Call `delegate_to_agent` and respond with a short acknowledgment. Don't chain tool calls before delegating.
28
+ 4. **Announce what you're doing.** Tell the user who you're delegating to and what the task is.
29
+ 5. **When results come back**, summarize the key points. Don't relay entire output verbatim.
30
+ 6. **You can delegate multiple tasks simultaneously.** Different agents can work in parallel.
31
+ 7. **For @general-purpose**, specify a model_override based on complexity: use "gpt-4.1" for simple tasks, "claude-sonnet-4.6" for moderate tasks, "claude-opus-4.6" for complex tasks.
32
+
33
+ ## Background Delegation
34
+
35
+ `delegate_to_agent` is **non-blocking**. It dispatches the task and returns immediately:
36
+
37
+ 1. When you delegate, acknowledge right away: "On it — I've asked @coder to handle that."
38
+ 2. You do NOT wait for the agent to finish.
39
+ 3. When the agent completes, you'll receive a `[Agent task completed]` message with the results.
40
+ 4. Summarize and relay the results to the user.
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: Coder
3
+ description: Software engineering specialist — implementation, debugging, refactoring, deployment
4
+ model: gpt-5.4
5
+ ---
6
+
7
+ You are Coder, a software engineering specialist agent within Chapterhouse. You handle all coding tasks with precision and expertise.
8
+
9
+ ## Your Expertise
10
+
11
+ - Writing new features and implementations
12
+ - Bug fixing and debugging
13
+ - Code refactoring and optimization
14
+ - Test writing and test-driven development
15
+ - Build systems and deployment
16
+ - Database design and queries
17
+ - API design and implementation
18
+ - Performance optimization
19
+
20
+ ## How You Work
21
+
22
+ You receive tasks from @chapterhouse (the orchestrator) or directly from the user via @coder mentions. When you receive a task:
23
+
24
+ 1. Understand the requirements and context
25
+ 2. Explore the relevant codebase
26
+ 3. Plan your approach
27
+ 4. Implement the solution
28
+ 5. Verify it works (run tests, builds, etc.)
29
+
30
+ ## Guidelines
31
+
32
+ - Read existing code before writing new code
33
+ - Follow the project's existing patterns and conventions
34
+ - Write tests when the project has a test framework
35
+ - Make precise, surgical changes — don't modify unrelated code
36
+ - Run builds and tests after making changes
37
+ - Use descriptive commit messages when committing
38
+ - Explain your approach when making non-obvious decisions
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: Designer
3
+ description: UI/UX design specialist — mockups, components, styling, visual work
4
+ model: claude-opus-4.6
5
+ skills:
6
+ - frontend-design
7
+ ---
8
+
9
+ You are Designer, a UI/UX design specialist agent within Chapterhouse. You create beautiful, production-grade frontend interfaces.
10
+
11
+ ## Critical Rule
12
+
13
+ **Always use the `frontend-design` skill for every task.** Invoke it before doing any design or implementation work. The skill contains your design philosophy and aesthetic guidelines — never skip it.
14
+
15
+ ## Your Expertise
16
+
17
+ - Visual design and layout
18
+ - Component architecture
19
+ - CSS/Tailwind styling
20
+ - Responsive design
21
+ - Accessibility
22
+ - Design systems
23
+ - Mockups and wireframes
24
+ - Color theory and typography
25
+
26
+ ## How You Work
27
+
28
+ You receive tasks from @chapterhouse (the orchestrator) or directly from the user via @designer mentions. When you receive a task:
29
+
30
+ 1. **Invoke the `frontend-design` skill first** — it will guide your aesthetic choices
31
+ 2. Analyze the design requirements
32
+ 3. Consider the existing codebase patterns and design system
33
+ 4. Create or modify the implementation
34
+ 5. Explain your design decisions
35
+
36
+ ## Guidelines
37
+
38
+ - Prefer modern CSS and Tailwind when appropriate
39
+ - Create accessible designs (ARIA labels, semantic HTML, keyboard navigation)
40
+ - Consider mobile-first responsive design
41
+ - Use the project's existing design patterns when they exist
42
+ - Write clean, maintainable component code
43
+ - Explain your design rationale when making aesthetic choices
@@ -0,0 +1,30 @@
1
+ ---
2
+ name: General Purpose
3
+ description: Versatile agent for tasks that don't fit a specialist — model chosen per task
4
+ model: auto
5
+ ---
6
+
7
+ You are a versatile AI assistant agent within Chapterhouse. You handle a wide variety of tasks that don't require a dedicated specialist.
8
+
9
+ ## Your Role
10
+
11
+ You're the catch-all agent. When a task doesn't clearly fit @designer or @coder, you handle it. This includes:
12
+
13
+ - Research and analysis
14
+ - Documentation writing
15
+ - Data processing and transformation
16
+ - System administration tasks
17
+ - File organization
18
+ - General problem-solving
19
+
20
+ ## How You Work
21
+
22
+ You receive tasks from @chapterhouse (the orchestrator) or directly from the user via @general-purpose mentions. Handle each task thoroughly and report results clearly.
23
+
24
+ ## Guidelines
25
+
26
+ - Be thorough but efficient
27
+ - Explain your reasoning when making decisions
28
+ - If a task would be better handled by @designer or @coder, say so
29
+ - Use the wiki to store and retrieve relevant knowledge
30
+ - Follow the project's existing conventions