wayform 0.3.0 → 0.4.0
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/README.md +318 -199
- package/dist/build-skill.js +86 -0
- package/dist/build-skill.js.map +1 -0
- package/dist/build.js +188 -0
- package/dist/build.js.map +1 -0
- package/dist/cli.js +6 -1
- package/dist/cli.js.map +1 -1
- package/dist/frontmatter.js.map +1 -1
- package/dist/guard-hook.js +52 -13
- package/dist/guard-hook.js.map +1 -1
- package/dist/hook-clients.js +61 -17
- package/dist/hook-clients.js.map +1 -1
- package/dist/hook.js +14 -10
- package/dist/hook.js.map +1 -1
- package/dist/init-configs.js +18 -1
- package/dist/init-configs.js.map +1 -1
- package/dist/init-remote.js +11 -0
- package/dist/init-remote.js.map +1 -1
- package/dist/plan-mirror.js +57 -0
- package/dist/plan-mirror.js.map +1 -0
- package/dist/remote-read.js +37 -4
- package/dist/remote-read.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,166 +1,217 @@
|
|
|
1
1
|
# Wayform
|
|
2
2
|
|
|
3
|
-
**
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
**A plan layer for teams that build with agents.** One prompt becomes a full
|
|
4
|
+
engineering plan — built from the repo in front of the agent plus the team's
|
|
5
|
+
settled decisions — that stays a living, versioned document as the team
|
|
6
|
+
revises it, ships it, and moves on to the next one. Every teammate's agent
|
|
7
|
+
reads the same plans and the same decision history, in whatever client they
|
|
8
|
+
use: Claude Code, Cursor, Codex, or any MCP client.
|
|
9
|
+
|
|
10
|
+
Works from day one for a single developer; a team simply adds more writers to
|
|
11
|
+
the same space.
|
|
6
12
|
|
|
7
13
|
```
|
|
8
|
-
you
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
14
|
+
you teammate
|
|
15
|
+
│ plan_brief → write the plan │
|
|
16
|
+
│ create_plan → transition to active │ new session opens
|
|
17
|
+
▼ ▼
|
|
18
|
+
gateway (shared space) ───────► session-start briefing
|
|
19
|
+
│ transition to building → shipped injects settled decisions
|
|
20
|
+
▼ and in-flight plans
|
|
21
|
+
decisions join the team's memory
|
|
15
22
|
```
|
|
16
23
|
|
|
17
24
|
## Why this exists
|
|
18
25
|
|
|
19
|
-
AI pair-programming has a memory problem, and it
|
|
20
|
-
starts cold.
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
in
|
|
33
|
-
|
|
34
|
-
- **
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
26
|
+
AI pair-programming has a memory problem, and it compounds in teams. Every
|
|
27
|
+
session starts cold. Plan mode in a coding agent throws away everything the
|
|
28
|
+
team already decided, so a plan can silently contradict a settled call — or a
|
|
29
|
+
collaborator re-explains the same context to their own agent, every day. The
|
|
30
|
+
context that matters — *what we decided, why, and what's already in flight* —
|
|
31
|
+
lives in Slack scrollback, `docs/plans/*.md` nobody re-reads, and people's
|
|
32
|
+
heads.
|
|
33
|
+
|
|
34
|
+
Wayform makes the **plan** the shared object instead of a local markdown file
|
|
35
|
+
or a throwaway plan-mode transcript:
|
|
36
|
+
|
|
37
|
+
- **Plans are briefed, not blind.** Before an agent writes a plan, `plan_brief`
|
|
38
|
+
hands it the team's relevant decisions, constraints, and any related
|
|
39
|
+
in-flight plans — so the plan starts from what's already settled instead of
|
|
40
|
+
contradicting it.
|
|
41
|
+
- **Plans are living documents.** A plan is created, revised, and moved through
|
|
42
|
+
a lifecycle (draft → active → building → shipped) as a versioned record any
|
|
43
|
+
teammate's agent can read or edit — never a local file only one person has
|
|
44
|
+
open.
|
|
45
|
+
- **Shipping a plan writes memory.** When a plan ships, the decisions it
|
|
46
|
+
produced join the team's shared memory, so the next plan (or the next
|
|
47
|
+
session, for anyone) starts from them.
|
|
48
|
+
- **Vendor-neutral.** One remote MCP server, the same tool contract, works
|
|
49
|
+
identically in Claude Code, Cursor, Codex, or any MCP client that speaks
|
|
50
|
+
Streamable HTTP + OAuth.
|
|
51
|
+
- **You own the data.** The store backing every plan and decision is a
|
|
52
|
+
**private git repo in your own GitHub account** — append-only, full history,
|
|
53
|
+
`git log` as the audit trail. No vendor database holds your team's plans.
|
|
54
|
+
|
|
55
|
+
**The product plane is remote MCP only.** A local git/stdio mode exists in
|
|
56
|
+
`src/` for legacy installs; it is not the path this project ships or
|
|
57
|
+
maintains going forward — see [Legacy: local mode](#legacy-local-mode).
|
|
43
58
|
|
|
44
59
|
---
|
|
45
60
|
|
|
46
|
-
##
|
|
61
|
+
## How it works
|
|
62
|
+
|
|
63
|
+
1. **Brief.** Before writing a plan (including in plan mode), the agent calls
|
|
64
|
+
`plan_brief(project, prompt)` with the task in the user's own words. It
|
|
65
|
+
returns the decisions and constraints that bind the work, related in-flight
|
|
66
|
+
plans, and fact ids to inherit — it does not write the plan for you.
|
|
67
|
+
2. **Write and record.** The agent writes the plan from that brief plus the
|
|
68
|
+
repo, then calls `create_plan(project, title, body, inherits: [...])`. The
|
|
69
|
+
plan comes back numbered (`#N`) and starts as `draft`.
|
|
70
|
+
3. **Move it forward.** `transition_plan` advances the plan: `active` once the
|
|
71
|
+
team agrees, `building` once an agent starts implementing, `shipped` once
|
|
72
|
+
it merges. `edit_plan` revises the body at any point before it ships; every
|
|
73
|
+
edit keeps the prior version readable.
|
|
74
|
+
4. **Decisions join memory.** Shipping a plan passes `decisions` — the atomic,
|
|
75
|
+
self-contained calls the plan settled, each with its "because" — into the
|
|
76
|
+
team's shared memory (`write_context`'s ledger), where `search_memory` and
|
|
77
|
+
`plan_brief` will find them for the next plan.
|
|
78
|
+
5. **Every session starts briefed.** The session-start hook injects the
|
|
79
|
+
project's canon decisions, recent activity, and a topic manifest before the
|
|
80
|
+
agent does anything — reads are guaranteed, not hoped for.
|
|
81
|
+
6. **The guard catches contradictions in flight.** Before a mutating tool call
|
|
82
|
+
(an edit or a shell command), the proposed action is checked against the
|
|
83
|
+
team's live decisions; a contradiction needs the user's confirmation
|
|
84
|
+
before it runs. See [The guard](#the-guard).
|
|
85
|
+
7. **The plan mirror keeps plans visible in-repo.** An admin can turn on
|
|
86
|
+
writing every in-flight plan as read-only markdown into
|
|
87
|
+
`.wayform/plans/<N>-<title>.md` in each teammate's checkout — gitignored,
|
|
88
|
+
never part of the repo's history. See [Plan mirror](#plan-mirror).
|
|
47
89
|
|
|
48
|
-
|
|
90
|
+
---
|
|
49
91
|
|
|
50
|
-
|
|
92
|
+
## Hosted quickstart
|
|
51
93
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
```
|
|
94
|
+
There are three roles: the **gateway operator** deploys the Worker once (see
|
|
95
|
+
[gateway/README.md](gateway/README.md)); a **team leader** creates the space;
|
|
96
|
+
each **member** connects their client. As a team leader or solo user:
|
|
56
97
|
|
|
57
|
-
|
|
58
|
-
on install.
|
|
98
|
+
### 1. Get allowlisted
|
|
59
99
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
> The clone-then-install path above uses npm's copy path and works everywhere.
|
|
64
|
-
> See [Troubleshooting](#troubleshooting).
|
|
100
|
+
Ask the gateway operator to add your GitHub login or org to the allowlist and
|
|
101
|
+
send you the MCP URL (default production URL:
|
|
102
|
+
`https://memorylayer-gateway.memory-layer.workers.dev`). No token, ever.
|
|
65
103
|
|
|
66
|
-
### 2. Create the
|
|
104
|
+
### 2. Create the space repo
|
|
67
105
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
or SSH. No accounts, no separate auth.
|
|
106
|
+
Create a **private** GitHub repo (e.g. `yourteam-memory`) and give it a
|
|
107
|
+
first commit. This repo *is* your team's memory — every decision and plan edit lands
|
|
108
|
+
here as a commit, in your account, under your history.
|
|
72
109
|
|
|
73
|
-
### 3.
|
|
110
|
+
### 3. Initialize this product repo
|
|
74
111
|
|
|
75
|
-
|
|
112
|
+
In the product repo (the codebase you work in — not the memory repo):
|
|
76
113
|
|
|
77
114
|
```bash
|
|
78
|
-
wayform
|
|
115
|
+
npm i -g wayform
|
|
116
|
+
wayform init --remote --clients cursor,claude
|
|
79
117
|
```
|
|
80
118
|
|
|
81
|
-
|
|
119
|
+
Pick only the clients this project actually uses. This writes
|
|
120
|
+
project-scoped, URL-only configuration (`.mcp.json`, `.cursor/mcp.json`,
|
|
121
|
+
`.codex/config.toml`, …, plus `.wayform-hook.env`) — no credential in any of
|
|
122
|
+
it. Never add Wayform to a user-global MCP file, or it follows you into
|
|
123
|
+
unrelated folders.
|
|
82
124
|
|
|
83
|
-
|
|
84
|
-
(`.claude/settings.json`, `.mcp.json`), Cursor (`.cursor/hooks.json`,
|
|
85
|
-
`.cursor/mcp.json`), and Codex (`.codex/hooks.json` and project
|
|
86
|
-
`.codex/config.toml`)
|
|
87
|
-
- **End-of-turn write-review hooks** (the Stop hook — see
|
|
88
|
-
[The loop](#the-loop-how-reads-and-writes-actually-happen))
|
|
89
|
-
- Your per-user, **gitignored** `.memorylayer-hook.env` (identity + repo URL —
|
|
90
|
-
secrets never enter git)
|
|
125
|
+
### 4. Connect and pick the memory repo
|
|
91
126
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
127
|
+
Connect the `wayform` MCP server and sign in with GitHub. Follow the guided
|
|
128
|
+
App installation and select **only** the private memory repo from step 2.
|
|
129
|
+
Public or branchless repos are rejected. The App gets Contents read/write on
|
|
130
|
+
exactly that repo — nothing else in your account.
|
|
95
131
|
|
|
96
|
-
|
|
97
|
-
Wayform, because we just set it up."* Then have a teammate (or a second
|
|
98
|
-
machine) open a fresh session — the decision should be in their context without
|
|
99
|
-
anyone pasting it. That round-trip is the product.
|
|
132
|
+
### 5. Hook login (once per machine)
|
|
100
133
|
|
|
101
|
-
|
|
134
|
+
```bash
|
|
135
|
+
wayform login
|
|
136
|
+
```
|
|
102
137
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
The local mode above needs each member to hold a git token. The **hosted
|
|
106
|
-
gateway** removes even that: a stateless Cloudflare Worker exposes the same
|
|
107
|
-
tools over **MCP Streamable HTTP**. Identity is **GitHub OAuth** (the same App
|
|
108
|
-
that writes the memory repo). Members never copy, paste, or store a Wayform
|
|
109
|
-
credential.
|
|
110
|
-
|
|
111
|
-
Wayform is **vendor-neutral**. The same URL works in Cursor, Claude Code,
|
|
112
|
-
Codex, Devin, Antigravity, or any MCP client that speaks Streamable HTTP +
|
|
113
|
-
OAuth. Configure it in **this product repo** (the codebase you work in) — never
|
|
114
|
-
as a user-global MCP, or it will follow you into unrelated folders.
|
|
115
|
-
|
|
116
|
-
Every customer is a new team. The operator allowlists their GitHub user or org;
|
|
117
|
-
they create their own private memory repo, initialize project-scoped config,
|
|
118
|
-
and select that memory repo in the guided App installation. Teammates are
|
|
119
|
-
invited in-agent by GitHub username.
|
|
120
|
-
|
|
121
|
-
**Operator (once per client):** add their GitHub login or org to the allowlist,
|
|
122
|
-
then send the MCP URL. Never send a token.
|
|
123
|
-
|
|
124
|
-
**They do:**
|
|
125
|
-
|
|
126
|
-
1. On GitHub, create a **private** team-memory repo and give it a first commit
|
|
127
|
-
(for example, initialize it with a README).
|
|
128
|
-
2. In the product repo, run
|
|
129
|
-
`wayform init --remote --clients cursor,claude` with the clients the team
|
|
130
|
-
actually uses. This writes URL-only, project-scoped configuration.
|
|
131
|
-
3. Connect the `wayform` MCP server. Sign in with GitHub, follow the guided App
|
|
132
|
-
installation, and select only the private memory repo from step 1.
|
|
133
|
-
4. Run `wayform login` once on the machine so session hooks can authenticate.
|
|
134
|
-
5. Run `wayform doctor`; resolve every failed hosted check before continuing.
|
|
135
|
-
6. Ask the agent to record a test decision, then open a new session and confirm
|
|
136
|
-
that decision is already present.
|
|
137
|
-
7. Commit the URL-only project configuration. Teammates run remote init and
|
|
138
|
-
authenticate; nobody copies a credential.
|
|
138
|
+
Session-start and guard hooks authenticate via the OS credential store after
|
|
139
|
+
this — no pasted secret.
|
|
139
140
|
|
|
140
|
-
###
|
|
141
|
+
### 6. Run diagnostics
|
|
141
142
|
|
|
142
|
-
|
|
143
|
-
|
|
143
|
+
```bash
|
|
144
|
+
wayform doctor
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Resolve every failed hosted check before relying on the loop.
|
|
148
|
+
|
|
149
|
+
### 7. Verify the round-trip
|
|
150
|
+
|
|
151
|
+
Ask the agent to record a test decision (or draft a small plan), open a new
|
|
152
|
+
session, and confirm the context is already there. Check the memory repo on
|
|
153
|
+
GitHub for a new commit, authored as you. Then commit the generated,
|
|
154
|
+
credential-free project config so teammates only need to authenticate.
|
|
155
|
+
|
|
156
|
+
### Client setup (project-scoped, OAuth)
|
|
144
157
|
|
|
145
158
|
| Client | Project file (commit this) | Do **not** use (global) | Authenticate |
|
|
146
159
|
|---|---|---|---|
|
|
147
|
-
| **Cursor** | `.cursor/mcp.json` → `{ "mcpServers": { "wayform": { "url": "
|
|
148
|
-
| **Claude Code** | `.mcp.json` (same JSON), or `claude mcp add --transport http --scope project wayform <url
|
|
149
|
-
| **Codex** | `.codex/config.toml` → `url` + `auth = "oauth"` | `~/.codex/config.toml` | `codex mcp login wayform` |
|
|
150
|
-
| **Devin CLI** | `.devin/mcp_config.json` → `{ "url": "
|
|
151
|
-
| **Antigravity** | `.agents/mcp_config.json` → `{ "serverUrl": "
|
|
160
|
+
| **Cursor** | `.cursor/mcp.json` → `{ "mcpServers": { "wayform": { "type": "http", "url": "…/mcp" } } }` | `~/.cursor/mcp.json` | Connect |
|
|
161
|
+
| **Claude Code** | `.mcp.json` (same JSON), or `claude mcp add --transport http --scope project wayform <url>/mcp` | `--scope user` | `claude mcp login wayform` |
|
|
162
|
+
| **Codex** | `.codex/config.toml` → `[mcp_servers.wayform]` with `url` + `auth = "oauth"` | `~/.codex/config.toml` | `codex mcp login wayform` |
|
|
163
|
+
| **Devin CLI** | `.devin/mcp_config.json` → `{ "url": "…/mcp", "transport": "http" }` | `--scope user` / `~/.config/devin/mcp_config.json` | `devin mcp login wayform` |
|
|
164
|
+
| **Antigravity** | `.agents/mcp_config.json` → `{ "mcpServers": { "wayform": { "serverUrl": "…/mcp" } } }` | `~/.gemini/config/mcp_config.json` | Authenticate in MCP settings (DCR) |
|
|
152
165
|
|
|
153
|
-
`wayform init --remote --clients cursor,claude` writes
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
166
|
+
`wayform init --remote --clients cursor,claude` writes only those clients'
|
|
167
|
+
files. With `--yes` and no `--clients`, it updates folders already present in
|
|
168
|
+
the repo rather than creating the rest. `wayform doctor` says "run wayform
|
|
169
|
+
login" when the hook session is missing — never "paste a token".
|
|
157
170
|
|
|
158
171
|
Do **not** add Wayform as a Devin Cloud **organization-wide** MCP if you only
|
|
159
|
-
want it in this repo — that surface is shared across the org
|
|
172
|
+
want it in this one repo — that surface is shared across the org.
|
|
160
173
|
|
|
161
|
-
Endpoints,
|
|
174
|
+
Endpoints, the operator deploy runbook, and space administration
|
|
175
|
+
(`invite_member`, `revoke_member`) live in
|
|
162
176
|
[gateway/README.md](gateway/README.md).
|
|
163
177
|
|
|
178
|
+
### Build a plan
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
wayform build 17 # or: wayform build 17 --client codex --project acme
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Run from your repo after `wayform init --remote`. It launches your own coding agent
|
|
185
|
+
(Claude Code, Cursor or Codex) interactively in your terminal with the
|
|
186
|
+
installed `wayform-build` skill; the agent builds plan #17 with one subagent
|
|
187
|
+
per checklist item, each briefed with the team's decisions, and ticks the plan
|
|
188
|
+
as it goes. No headless runs, no hosted execution.
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## MCP tools
|
|
193
|
+
|
|
194
|
+
All 16 tools the gateway exposes over MCP (`gateway/src/mcp-tools.ts`):
|
|
195
|
+
|
|
196
|
+
| Tool | What it does |
|
|
197
|
+
|---|---|
|
|
198
|
+
| `plan_brief` | Brief a new plan: the settled decisions, constraints, and related in-flight plans that bind it, before you write anything. Read-only. |
|
|
199
|
+
| `task_brief` | Brief one task of a plan for a subagent: the decisions that bind that task, as text to paste at the top of its prompt. Read-only. |
|
|
200
|
+
| `create_plan` | Record a new engineering plan (markdown) as a living, versioned document the team and every agent can read. Starts as `draft`. |
|
|
201
|
+
| `read_plan` | Read one plan's state, decisions, and body — or list a project's plans. Read-only. |
|
|
202
|
+
| `edit_plan` | Revise a draft/active/building plan's body or title; every edit is a new version, old ones stay readable. Pass `base_rev` (shown by `read_plan`) to reject the edit if the plan changed since. |
|
|
203
|
+
| `transition_plan` | Move a plan through draft → active → building → shipped (or mark it superseded); shipping turns its decisions into memory. |
|
|
204
|
+
| `set_plan_mirror` | Turn on/off mirroring a project's in-flight plans as read-only markdown into every teammate's repo. Admin only. |
|
|
205
|
+
| `read_context` | Pull shared planning context: a recency snapshot, or (with `query`) relevance-ranked results across the whole indexed history. Read-only. |
|
|
206
|
+
| `write_context` | Append one settled decision or durable context; each write is its own commit, attributed to the writer. |
|
|
207
|
+
| `search_memory` | Search all recorded decisions/context before contradicting, re-deciding, or re-asking something that may already be settled. Read-only. |
|
|
208
|
+
| `memory_feedback` | Mark a retrieved fact `useful`, `wrong`, or `stale`. |
|
|
209
|
+
| `supersede_facts` | Confirm which existing facts a new entry actually replaces or corrects. |
|
|
210
|
+
| `invite_member` | Grant a GitHub user access to this space by username — no token ever changes hands. Admin only. |
|
|
211
|
+
| `revoke_member` | Remove a GitHub user (pending invite or live member) from this space. Admin only. |
|
|
212
|
+
| `list_sessions` | List every client currently connected to your own Wayform account. Read-only. |
|
|
213
|
+
| `revoke_session` | Disconnect one client from your own account (e.g. after losing a laptop). |
|
|
214
|
+
|
|
164
215
|
---
|
|
165
216
|
|
|
166
217
|
## The guard
|
|
@@ -168,19 +219,36 @@ Endpoints, allowlist, and the deploy runbook live in
|
|
|
168
219
|
Reading decisions back is half the loop. The other half is catching an agent
|
|
169
220
|
about to contradict one.
|
|
170
221
|
|
|
171
|
-
With the hosted gateway configured, `wayform init` wires a
|
|
172
|
-
Claude Code. Before any
|
|
173
|
-
checked against the team's live decisions. If it contradicts one, you
|
|
174
|
-
confirmation prompt naming the decision, who made it, and when:
|
|
222
|
+
With the hosted gateway configured, `wayform init` wires a pre-tool hook in
|
|
223
|
+
Claude Code, Cursor and Codex. Before any edit or shell command, the proposed
|
|
224
|
+
action is checked against the team's live decisions. If it contradicts one, you
|
|
225
|
+
get a confirmation prompt naming the decision, who made it, and when:
|
|
175
226
|
|
|
176
227
|
> **Wayform — this contradicts a recorded team decision:**
|
|
177
228
|
> We ruled out a second datastore; Postgres is not being added.
|
|
178
229
|
> — Skanda, 2026-07-12
|
|
179
230
|
|
|
180
|
-
|
|
181
|
-
|
|
231
|
+
How you confirm depends on the client, because only Claude Code's hook can ask:
|
|
232
|
+
|
|
233
|
+
| Client | Tools guarded | On a contradiction |
|
|
234
|
+
| --- | --- | --- |
|
|
235
|
+
| Claude Code | `Edit`, `Write`, `Bash` | Native permission prompt (verified live). |
|
|
236
|
+
| Cursor | `Shell`, `Write`, `StrReplace`, `Edit`, `Delete` | Blocked; the agent asks you, and only if you confirm calls `guard_allow` with the block's ticket and retries (verified live). |
|
|
237
|
+
| Codex | `Bash`, `apply_patch` | Same as Cursor. Codex runs project hooks only once trusted; `init` writes that trust to `~/.codex/config.toml`. Verified live. |
|
|
182
238
|
|
|
183
|
-
|
|
239
|
+
Onboarding notes:
|
|
240
|
+
|
|
241
|
+
- **Codex:** run `codex mcp login wayform` in a terminal in the repo (the in-session reconnect can't start the browser flow), then start a **new** Codex session; a session started before login skips the wayform server.
|
|
242
|
+
- **Codex:** if a "Wayform" app is connected to your ChatGPT account, disconnect it (or run Codex with `-c features.apps=false`); it shadows the project's wayform server with stale tools and a sign-in loop.
|
|
243
|
+
- **Cursor:** `agent mcp login wayform` (or approve in the IDE). Cursor's guard blocks with a ticket, and `guard_allow` lifts it after you confirm.
|
|
244
|
+
|
|
245
|
+
A `guard_allow` ticket lets actions that contradict that one decision proceed,
|
|
246
|
+
for you only, for 10 minutes; a different conflict asks again. Reads are never
|
|
247
|
+
guarded, so only mutating tools pay any latency, capped at 6 seconds before the
|
|
248
|
+
check gives up and allows; any failure allows.
|
|
249
|
+
|
|
250
|
+
Turn it off per machine by setting `WAYFORM_GUARD=off` in the shell
|
|
251
|
+
environment the agent runs in.
|
|
184
252
|
|
|
185
253
|
How often it fires:
|
|
186
254
|
|
|
@@ -192,19 +260,19 @@ curl -H "$WAYFORM_AUTH" \
|
|
|
192
260
|
|
|
193
261
|
---
|
|
194
262
|
|
|
195
|
-
##
|
|
263
|
+
## Plan mirror
|
|
196
264
|
|
|
197
|
-
|
|
198
|
-
|
|
265
|
+
A space admin can mirror a project's in-flight plans (draft, active, building)
|
|
266
|
+
into every teammate's code repo as readable markdown:
|
|
199
267
|
|
|
200
|
-
|
|
201
|
-
|---|---|
|
|
202
|
-
| `read_context(project, budget_tokens?)` | Pull latest and return the projected context — every recorded decision, in write order, packed to a token budget (default 4000) so reads never flood a session as the store grows. |
|
|
203
|
-
| `write_context(project, type, payload)` | Append one decision (`type: "decision"`) or durable background (`type: "context"`) as its own file, commit, push. The commit is the event; the author is the attribution. |
|
|
268
|
+
> "turn on the plan mirror for project MemoryLayer" → `set_plan_mirror(project, enabled: true)`
|
|
204
269
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
270
|
+
At each session start the hook writes `.wayform/plans/<N>-<title>.md` and
|
|
271
|
+
removes plans that shipped or were superseded. The folder git-ignores itself
|
|
272
|
+
(`.wayform/.gitignore` is `*`), so it never shows up in commits, diffs, or
|
|
273
|
+
`git status`. Plans only, never memories. The files are a read-only view: change
|
|
274
|
+
a plan with `edit_plan`. Turning the mirror off removes the folder at the next
|
|
275
|
+
session start.
|
|
208
276
|
|
|
209
277
|
## The loop — how reads and writes actually happen
|
|
210
278
|
|
|
@@ -217,7 +285,8 @@ sessions, never in unrelated chats.
|
|
|
217
285
|
**Writes have three paths, softest first:**
|
|
218
286
|
|
|
219
287
|
1. **Say it** (any client, incl. Claude Desktop): *"record this decision: X
|
|
220
|
-
because Y
|
|
288
|
+
because Y"* or *"plan out X"*. A direct command the model complies with
|
|
289
|
+
near-reliably.
|
|
221
290
|
2. **`/remember`** (Claude Code / Cursor): one-word gesture; ships in
|
|
222
291
|
`.claude/commands/remember.md`. `/remember we decided X because Y`, or bare
|
|
223
292
|
`/remember` to record the last settled decision.
|
|
@@ -233,29 +302,25 @@ coding session. (The flip side: failures are quiet — that's what `doctor` is
|
|
|
233
302
|
for.)
|
|
234
303
|
|
|
235
304
|
**Claude Desktop** has no hook system, so it's MCP-pull-only: register
|
|
236
|
-
`wayform` as a
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
| `
|
|
250
|
-
| `
|
|
251
|
-
| `
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
| `MEMORYLAYER_AUTO_PUSH` | no | `false` to skip pushing (local smoke tests). |
|
|
256
|
-
|
|
257
|
-
Hosted hook env contains only project settings and the gateway URL. The OAuth
|
|
258
|
-
session is held by the native OS credential store after `wayform login`.
|
|
305
|
+
`wayform` as a remote MCP server and it reads when the model chooses to — path
|
|
306
|
+
1 is your write path there.
|
|
307
|
+
|
|
308
|
+
## Configuration (`.wayform-hook.env`)
|
|
309
|
+
|
|
310
|
+
Written by `wayform init --remote`, project-scoped, **credential-free** (URL +
|
|
311
|
+
project name only — safe to commit; `wayform init` removes it from
|
|
312
|
+
`.gitignore` for this reason). The legacy filename `.memorylayer-hook.env` and
|
|
313
|
+
the `MEMORYLAYER_` variable prefix are still read indefinitely, so old configs
|
|
314
|
+
keep working.
|
|
315
|
+
|
|
316
|
+
| Var | Meaning |
|
|
317
|
+
|-----|---------|
|
|
318
|
+
| `WAYFORM_GATEWAY_URL` | Gateway base URL. Presence selects hosted mode. |
|
|
319
|
+
| `WAYFORM_PROJECT` | Project/space name. Default: repo directory name. |
|
|
320
|
+
| `WAYFORM_READ_BUDGET_TOKENS` | Read token budget. Default 4000; `<=0` = unlimited. |
|
|
321
|
+
|
|
322
|
+
`WAYFORM_GUARD=off` (in the shell environment, not this file) disables the
|
|
323
|
+
guard hook per machine.
|
|
259
324
|
|
|
260
325
|
## Diagnostics
|
|
261
326
|
|
|
@@ -263,27 +328,23 @@ session is held by the native OS credential store after `wayform login`.
|
|
|
263
328
|
wayform doctor
|
|
264
329
|
```
|
|
265
330
|
|
|
266
|
-
Read-only. Checks the
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
write "silently" does nothing — fail-open means problems hide here first.
|
|
331
|
+
Read-only. Checks the resolved config, hosted login/session state, gateway
|
|
332
|
+
reachability, and the default project name. Run it whenever a read, write, or
|
|
333
|
+
plan call "silently" does nothing — fail-open means problems hide here first.
|
|
270
334
|
|
|
271
335
|
## Security & data ownership
|
|
272
336
|
|
|
273
|
-
- **
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
a
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
- **Trust boundary to know about:** everything a space member writes is
|
|
285
|
-
injected into every member's sessions. You trust the people in your space —
|
|
286
|
-
that's the model, stated plainly.
|
|
337
|
+
- **The gateway is a stateless proxy.** The source of truth is a private
|
|
338
|
+
GitHub repo in *your* account — plans and decisions alike are commits there.
|
|
339
|
+
The App holds Contents-only permission on exactly one repo per space;
|
|
340
|
+
members are keyed by GitHub user id after OAuth. The Worker holds operator
|
|
341
|
+
secrets in Cloudflare's secret store, never in code or git. Members never
|
|
342
|
+
see a Wayform API key.
|
|
343
|
+
- **One GitHub user belongs to one Wayform space** for now; multi-space
|
|
344
|
+
membership is a deferred product decision.
|
|
345
|
+
- **Trust boundary to know about:** everything a space member writes — plans
|
|
346
|
+
included — is injected into every member's sessions. You trust the people in
|
|
347
|
+
your space; that's the model, stated plainly.
|
|
287
348
|
- **Rate limits — wired but NOT currently enforcing.** Verified live
|
|
288
349
|
2026-08-30: the binding is bound and called on every request, but returned
|
|
289
350
|
success for 100+ requests in seconds against a limit of 20/60s. Treat these
|
|
@@ -299,8 +360,8 @@ write "silently" does nothing — fail-open means problems hide here first.
|
|
|
299
360
|
|
|
300
361
|
### Managing your own sessions
|
|
301
362
|
|
|
302
|
-
Every editor you connect is a separate OAuth grant.
|
|
303
|
-
|
|
363
|
+
Every editor you connect is a separate OAuth grant. Review and disconnect them
|
|
364
|
+
yourself, from any agent — no operator involved:
|
|
304
365
|
|
|
305
366
|
> "list my wayform sessions"
|
|
306
367
|
> "revoke wayform session <id>"
|
|
@@ -308,39 +369,50 @@ disconnect them yourself, from any agent — no operator involved:
|
|
|
308
369
|
`list_sessions` shows each connected client, when it was connected, and marks
|
|
309
370
|
the one you are currently using. `revoke_session` disconnects one and takes
|
|
310
371
|
effect immediately; that client must sign in again. Both act only on **your**
|
|
311
|
-
account — removing a *teammate* from the space is `revoke_member`,
|
|
312
|
-
|
|
313
|
-
|
|
372
|
+
account — removing a *teammate* from the space is `revoke_member`, admin-only.
|
|
373
|
+
A revoke that cannot be confirmed reports an error rather than claiming
|
|
374
|
+
success, so "revoked" always means revoked.
|
|
314
375
|
|
|
315
376
|
## Troubleshooting
|
|
316
377
|
|
|
317
378
|
| Symptom | Cause & fix |
|
|
318
379
|
|---|---|
|
|
319
|
-
|
|
|
320
|
-
|
|
|
321
|
-
| Reads/writes silently do nothing | `wayform doctor`. Hosted: usually `wayform login`. Local: missing `.memorylayer-hook.env`, no repo access, or unpushed local commits (self-heals on next read). |
|
|
322
|
-
| Teammates still see old behavior after an upgrade | The fix lives in the **global binary** — each teammate must reinstall it (committed project configs aren't enough), and a running MCP server needs a restart to pick it up. |
|
|
380
|
+
| Reads/writes/plan calls silently do nothing | `wayform doctor`. Usually `wayform login`, or the space isn't allowlisted yet. |
|
|
381
|
+
| Teammates still see old behavior after an upgrade | The fix lives in the **global binary** — each teammate must reinstall it (`npm i -g wayform`) and restart any running MCP server to pick it up. |
|
|
323
382
|
| macOS `curl` fails TLS against the hosted gateway (`workers.dev`) | LibreSSL negotiation quirk — add `--tlsv1.2`. Client-side only; SDK-based MCP clients are unaffected. |
|
|
383
|
+
| `.memorylayer-hook.env` from an old install | Still read automatically; `wayform init --remote` migrates it to `.wayform-hook.env` (and rewrites it credential-free) the next time it runs. |
|
|
324
384
|
|
|
325
385
|
## Project status
|
|
326
386
|
|
|
327
|
-
|
|
328
|
-
|
|
387
|
+
Plans #1–#16 have shipped the plan object, plan generation, and the pre-UI
|
|
388
|
+
hardening pass (guard, recall, HTTP API, multi-team, this doc) on the hosted
|
|
389
|
+
gateway — GitHub OAuth, no member API keys. The desktop app (Phase 3, plan #5)
|
|
390
|
+
has not been built yet; today the plan is authored and read through whatever
|
|
391
|
+
MCP client the agent runs in.
|
|
329
392
|
|
|
330
|
-
**Deliberately not built yet
|
|
331
|
-
|
|
393
|
+
**Deliberately not built yet** (see plan #2's cut lines): an orchestrator, a
|
|
394
|
+
repo-map product, hosted execution of dispatched agents, a live session
|
|
395
|
+
viewer, an accounts system beyond OAuth + the GitHub App, and a CRDT sync
|
|
396
|
+
engine — optimistic writes plus last-write-wins on a versioned plan body is
|
|
397
|
+
enough until two people demonstrably edit one plan at once.
|
|
332
398
|
|
|
333
399
|
## Repo layout
|
|
334
400
|
|
|
335
401
|
```
|
|
336
|
-
src/ local CLI + stdio MCP server (init, hooks, store, doctor)
|
|
337
|
-
gateway/ hosted gateway — Cloudflare Worker (own README + runbook)
|
|
402
|
+
src/ local CLI + legacy stdio MCP server (init, hooks, store, doctor)
|
|
403
|
+
gateway/ hosted gateway — Cloudflare Worker, the product plane (own README + runbook)
|
|
338
404
|
dist/ pre-built JS, committed (installs need no toolchain)
|
|
339
|
-
docs/plans/ implementation plans docs/specs/ design specs
|
|
340
|
-
docs/roadmap/ production + graph-store roadmaps
|
|
341
405
|
test/ node:test suites (gateway has its own under gateway/test/)
|
|
342
406
|
```
|
|
343
407
|
|
|
408
|
+
Plans and specs are no longer kept as local `docs/` files — they live in the
|
|
409
|
+
Wayform space itself (`create_plan`, `read_plan`) and are visible in-repo,
|
|
410
|
+
read-only, via the plan mirror.
|
|
411
|
+
|
|
412
|
+
## Desktop app
|
|
413
|
+
|
|
414
|
+
A macOS app for reading and editing plans lives in [`app/`](app/README.md).
|
|
415
|
+
|
|
344
416
|
## Development
|
|
345
417
|
|
|
346
418
|
```bash
|
|
@@ -352,3 +424,50 @@ wayform --help # subcommands: init, login, hook, doctor, space
|
|
|
352
424
|
Both planes share the entry format modules (`src/frontmatter.ts`,
|
|
353
425
|
`src/slug.ts`, `src/token-budget.ts`) — change the format in one place or not
|
|
354
426
|
at all.
|
|
427
|
+
|
|
428
|
+
---
|
|
429
|
+
|
|
430
|
+
## Legacy: local mode
|
|
431
|
+
|
|
432
|
+
Before the hosted gateway, each member cloned a shared git repo directly and
|
|
433
|
+
ran a local CLI + stdio MCP server. That code still lives in `src/` and still
|
|
434
|
+
works, but it is **not the product plane** — no plan tools, no guard, no plan
|
|
435
|
+
mirror, no session-start briefing beyond a raw recency dump. New setups should
|
|
436
|
+
use the [hosted quickstart](#hosted-quickstart) above.
|
|
437
|
+
|
|
438
|
+
```bash
|
|
439
|
+
git clone https://github.com/skandaramanan/Wayform /tmp/wayform \
|
|
440
|
+
&& npm install -g /tmp/wayform
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
> **Why not `npm install -g github:...`?** npm 10 has a git-global-install bug
|
|
444
|
+
> (the package is symlinked to an ephemeral cache dir that never gets checked
|
|
445
|
+
> out) that makes the one-liner fail with `command not found` or `ENOTDIR`.
|
|
446
|
+
> The clone-then-install path above uses npm's copy path and works everywhere.
|
|
447
|
+
|
|
448
|
+
One person creates a **private** git repo (e.g. `yourteam-memory`) and grants
|
|
449
|
+
each collaborator push access — this is the shared "key," just git access to
|
|
450
|
+
that repo. From your project repo:
|
|
451
|
+
|
|
452
|
+
```bash
|
|
453
|
+
wayform init
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
This writes session-start read hooks + local MCP registration for Claude
|
|
457
|
+
Code, Cursor, and Codex, an end-of-turn write-review Stop hook, and a
|
|
458
|
+
per-user, gitignored `.wayform-hook.env` (identity + repo URL — secrets never
|
|
459
|
+
enter git). One person commits the project configs; each teammate runs
|
|
460
|
+
`wayform init` once to set their own identity.
|
|
461
|
+
|
|
462
|
+
Local mode speaks only `read_context` / `write_context` / `search_memory` —
|
|
463
|
+
no plans. Configuration keys (local mode only):
|
|
464
|
+
|
|
465
|
+
| Var | Meaning |
|
|
466
|
+
|-----|---------|
|
|
467
|
+
| `CONTEXT_REPO_URL` | Shared context repo URL (may embed a git token). |
|
|
468
|
+
| `WAYFORM_AUTHOR` / `WAYFORM_AUTHOR_EMAIL` | Local commit author / attribution. |
|
|
469
|
+
| `CONTEXT_REPO_PATH` | Local clone path. Default: keyed per repo URL under `$XDG_DATA_HOME/memorylayer/clones/<repo-slug>-<hash>`. |
|
|
470
|
+
| `WAYFORM_AUTO_PUSH` | `false` to skip pushing (local smoke tests). |
|
|
471
|
+
|
|
472
|
+
`wayform doctor` also diagnoses local mode: env file, clone health and origin,
|
|
473
|
+
remote connectivity/auth, and unpushed commits.
|