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.
- package/LICENSE +23 -0
- package/README.md +363 -0
- package/agents/chapterhouse.agent.md +40 -0
- package/agents/coder.agent.md +38 -0
- package/agents/designer.agent.md +43 -0
- package/agents/general-purpose.agent.md +30 -0
- package/dist/api/auth.js +159 -0
- package/dist/api/auth.test.js +463 -0
- package/dist/api/errors.js +95 -0
- package/dist/api/errors.test.js +89 -0
- package/dist/api/rate-limit.js +85 -0
- package/dist/api/server-runtime.js +62 -0
- package/dist/api/server.js +651 -0
- package/dist/api/server.test.js +385 -0
- package/dist/api/sse.integration.test.js +270 -0
- package/dist/api/sse.js +7 -0
- package/dist/api/team.js +196 -0
- package/dist/api/team.test.js +466 -0
- package/dist/cli.js +102 -0
- package/dist/config.js +299 -0
- package/dist/config.phase3.test.js +20 -0
- package/dist/config.test.js +148 -0
- package/dist/copilot/agents.js +447 -0
- package/dist/copilot/agents.squad.test.js +72 -0
- package/dist/copilot/classifier.js +72 -0
- package/dist/copilot/client.js +32 -0
- package/dist/copilot/client.test.js +100 -0
- package/dist/copilot/episode-writer.js +219 -0
- package/dist/copilot/episode-writer.test.js +41 -0
- package/dist/copilot/mcp-config.js +22 -0
- package/dist/copilot/okr-mapper.js +196 -0
- package/dist/copilot/okr-mapper.test.js +114 -0
- package/dist/copilot/orchestrator.js +685 -0
- package/dist/copilot/orchestrator.test.js +523 -0
- package/dist/copilot/router.js +142 -0
- package/dist/copilot/router.test.js +119 -0
- package/dist/copilot/skills.js +125 -0
- package/dist/copilot/standup.js +138 -0
- package/dist/copilot/standup.test.js +132 -0
- package/dist/copilot/system-message.js +143 -0
- package/dist/copilot/system-message.test.js +17 -0
- package/dist/copilot/tools.js +1212 -0
- package/dist/copilot/tools.okr.test.js +260 -0
- package/dist/copilot/tools.squad.test.js +168 -0
- package/dist/daemon.js +235 -0
- package/dist/home-path.js +12 -0
- package/dist/home-path.test.js +11 -0
- package/dist/integrations/ado-analytics.js +178 -0
- package/dist/integrations/ado-analytics.test.js +284 -0
- package/dist/integrations/ado-client.js +227 -0
- package/dist/integrations/ado-client.test.js +176 -0
- package/dist/integrations/ado-schema.js +25 -0
- package/dist/integrations/ado-schema.test.js +39 -0
- package/dist/integrations/ado-skill.js +55 -0
- package/dist/integrations/report-generator.js +114 -0
- package/dist/integrations/report-generator.test.js +62 -0
- package/dist/integrations/team-push.js +144 -0
- package/dist/integrations/team-push.test.js +178 -0
- package/dist/integrations/teams-notify.js +108 -0
- package/dist/integrations/teams-notify.test.js +135 -0
- package/dist/paths.js +41 -0
- package/dist/setup.js +149 -0
- package/dist/shutdown-signals.js +13 -0
- package/dist/shutdown-signals.test.js +33 -0
- package/dist/squad/charter.js +108 -0
- package/dist/squad/charter.test.js +89 -0
- package/dist/squad/context.js +48 -0
- package/dist/squad/context.test.js +59 -0
- package/dist/squad/discovery.js +280 -0
- package/dist/squad/discovery.test.js +93 -0
- package/dist/squad/index.js +7 -0
- package/dist/squad/mirror.js +81 -0
- package/dist/squad/mirror.scheduler.js +78 -0
- package/dist/squad/mirror.scheduler.test.js +197 -0
- package/dist/squad/mirror.test.js +172 -0
- package/dist/squad/registry.js +162 -0
- package/dist/squad/registry.test.js +31 -0
- package/dist/squad/squad-coordinator-system-message.test.js +190 -0
- package/dist/squad/squad-session-routing.test.js +260 -0
- package/dist/squad/types.js +4 -0
- package/dist/status.js +25 -0
- package/dist/status.test.js +22 -0
- package/dist/store/db.js +290 -0
- package/dist/store/db.test.js +126 -0
- package/dist/store/squad-sessions.test.js +341 -0
- package/dist/test/setup-env.js +3 -0
- package/dist/update.js +112 -0
- package/dist/update.test.js +25 -0
- package/dist/wiki/context.js +138 -0
- package/dist/wiki/fs.js +195 -0
- package/dist/wiki/fs.test.js +39 -0
- package/dist/wiki/index-manager.js +359 -0
- package/dist/wiki/index-manager.test.js +129 -0
- package/dist/wiki/lock.js +26 -0
- package/dist/wiki/lock.test.js +30 -0
- package/dist/wiki/log-manager.js +20 -0
- package/dist/wiki/migrate.js +306 -0
- package/dist/wiki/okr.test.js +101 -0
- package/dist/wiki/path-utils.js +4 -0
- package/dist/wiki/path-utils.test.js +8 -0
- package/dist/wiki/seed-team-wiki.js +296 -0
- package/dist/wiki/seed-team-wiki.test.js +69 -0
- package/dist/wiki/team-sync.js +212 -0
- package/dist/wiki/team-sync.test.js +185 -0
- package/dist/wiki/templates/okr.js +98 -0
- package/package.json +72 -0
- package/skills/.gitkeep +0 -0
- package/skills/find-skills/SKILL.md +161 -0
- package/skills/find-skills/_meta.json +4 -0
- package/skills/frontend-design/LICENSE.txt +177 -0
- package/skills/frontend-design/SKILL.md +42 -0
- package/skills/squad/SKILL.md +76 -0
- package/web/dist/assets/index-D-e7K-fT.css +10 -0
- package/web/dist/assets/index-DAg9IrpO.js +142 -0
- package/web/dist/assets/index-DAg9IrpO.js.map +1 -0
- package/web/dist/chapterhouse-icon.png +0 -0
- package/web/dist/chapterhouse-icon.svg +42 -0
- package/web/dist/chapterhouse-logo.svg +46 -0
- 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
|