You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: agent-first install guide and dual engine names (#524)
Rewrite agents-guide so coding agents are the installer and runner.
Point agent-assisted-setup at agents-guide (not contributor AGENTS.md).
Document code map / evidence log public names and OpenClaw bootstrap files.
Copy file name to clipboardExpand all lines: docs/agent-assisted-setup.md
+17-11Lines changed: 17 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,25 @@
1
1
# Agent-Assisted Setup
2
2
3
-
You can point an agent at the Brigade repository and ask it to install Brigade for you. The root `AGENTS.md` contains the direct instructions an agent should follow, so users should not need to paste a long prompt.
3
+
Point a coding agent at the Brigade repository (or paste a short prompt from the README). **The agent installs and wires Brigade.** Humans often never type `pipx` or `brigade setup`.
4
4
5
-
Brigade is designed to help users adapt an existing homegrown agent setup, not replace it wholesale. Keep the user's current memory owner, workspace or repo layout, harness choices, and local habits unless Brigade needs a small compatibility file or handoff inbox to make the workflow portable.
5
+
Root `AGENTS.md`is for **developing Brigade**. For install and adapt, agents follow **`docs/agents-guide.md`** (this doc is supporting detail).
6
6
7
-
The agent should treat Brigade setup as local workspace wiring, not as a release, deploy, or remote mutation. Local-first means local data on the operator-controlled machine first, before any external service; that machine can be a laptop, workstation, or VPS.
7
+
Brigade is designed so agents run the control plane (install, setup, verify, handoffs) and humans review when a gate is ambiguous or risky. Adapt an existing homegrown setup; do not replace it wholesale. Keep the user's memory owner, workspace or repo layout, harness choices, and local habits unless Brigade needs a small compatibility file or handoff inbox.
8
8
9
-
## Agent Entry Point
9
+
Treat setup as local workspace wiring, not as a release, deploy, or remote mutation. Local-first means data on the operator-controlled machine first (laptop, workstation, or VPS) before any external service.
10
+
11
+
Built-in engines use public names **code map** (`brigade code`) and **evidence log** (`brigade evidence`). Historical product names GraphTrail and MiseLedger may still appear in engine paths and MCP entry labels.
12
+
13
+
## Agent entry point
10
14
11
15
If an agent has access to this repository, it should start by reading:
12
16
13
-
-`AGENTS.md`
14
-
-`README.md`
15
-
-`docs/new-user-quickstart.md`
16
-
-`docs/agent-assisted-setup.md`
17
+
1.`README.md`
18
+
2.`docs/agents-guide.md`
19
+
3.`docs/agent-assisted-setup.md` (this file)
20
+
4.`docs/new-user-quickstart.md` if useful
17
21
18
-
Then it should work inside the target repo or operator workspace and run:
22
+
Then work inside the **target** repo or operator workspace and run:
- install the `brigade-cli` package if missing (humans often will not)
46
+
- run `brigade setup` so the code map and evidence engines are present
42
47
- run quickstart in dry-run mode first
43
48
- apply quickstart only after the dry-run looks reasonable
44
49
- run `operator doctor` and report the exact result
50
+
- prefer `brigade work verify run` for checks after wiring, not raw test claims
45
51
- explain which files are shareable or durable and which are local-only
46
-
- preserve the user's existing memory layout and agent conventions where possible
52
+
- preserve the user's existing memory layout and agent conventions where possible (including OpenClaw `SOUL.md`, `TOOLS.md`, `AGENTS.md`, `IDENTITY.md`, `MEMORY.md`, and related bootstrap files)
47
53
- suggest Brigade compatibility wiring instead of moving or renaming personal systems
48
54
- stop and ask before remote changes, destructive commands, new services, schedulers, or commits
Copy file name to clipboardExpand all lines: docs/agents-guide.md
+90-91Lines changed: 90 additions & 91 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,144 +1,147 @@
1
1
# Agent Guide: Installing and Adapting Brigade
2
2
3
-
Use this guide when a user points you at the Brigade repository and asks you to install, evaluate, or adapt Brigade for their workspace.
3
+
You are a coding agent. **You** install, set up, verify, and leave handoffs. The human usually does not type these commands. They point you at this repo (or paste a short prompt) and expect files and a doctor result on disk.
4
4
5
-
Developing Brigade itself? Start from `AGENTS.md` at the repo root, then `CONTRIBUTING.md`.
5
+
Developing Brigade itself? Start from root `AGENTS.md`, then `CONTRIBUTING.md`. That file is for contributors, not for wiring a user workspace.
6
6
7
-
## Start Here
7
+
## What Brigade is for
8
8
9
-
Read these files first:
9
+
Brigade is a **local control plane for coding agents**, not a human day-to-day terminal app.
-**Humans own:** policy and review when a gate is ambiguous or risky (or when they explicitly ask for a destructive or remote action).
13
+
-**Artifacts:** plain files on the machine (receipts, memory cards, configs). No daemon. No lock-in.
14
14
15
-
Brigade is local-first workspace wiring. Local-first means local data on the operator-controlled machine first, before any external service; that machine can be a laptop, workstation, or VPS. Brigade should help the user adapt their existing memory, handoff, and agent workflow instead of replacing it with someone else's exact layout.
Brigade supports Linux, macOS, and native Windows PowerShell with Python 3.10 or newer. If `pipx` is missing, use the platform package instructions in [`QUICKSTART.md`](../QUICKSTART.md#1-install). Do not assume WSL is required.
22
+
Standalone GraphTrail or MiseLedger product installs are replaced by `brigade setup`. Some binary and path names still use the historical labels.
20
23
21
-
When the user wants Brigade installed in a target repo or operator workspace, work in that target directory and run:
3.`docs/agent-assisted-setup.md` (boundaries and adaptation detail)
31
+
4.`docs/new-user-quickstart.md` if the target is a first-time human skim
32
+
33
+
Brigade is local-first workspace wiring. Local-first means data on the operator-controlled machine first (laptop, workstation, or VPS) before any external service. Adapt the user's existing memory, handoff, and agent workflow. Do not replace a working layout with someone else's exact tree.
34
+
35
+
## Installing for a user (you run this)
36
+
37
+
Platform: Linux, macOS, or native Windows PowerShell with Python 3.10 or newer. If `pipx` is missing, use the platform package instructions in [`QUICKSTART.md`](../QUICKSTART.md#1-install). Do not assume WSL is required.
38
+
39
+
Work in the **target** directory (the repo or operator workspace the user named), not the Brigade source tree unless they asked to develop Brigade.
40
+
41
+
Always dry-run before write. Then apply. Then doctor.
brigade operator doctor --target . --profile local-operator
38
63
```
39
64
40
-
If the user uses more than one harness, use a comma-separated list:
65
+
OpenClaw bootstrap files often include `SOUL.md`, `TOOLS.md`, `AGENTS.md`, `IDENTITY.md`, `MEMORY.md`, and related session-start files. Preserve them. Oversize bootstrap sets are a Bootstrap Doctor concern (`brigade add bootstrap-doctor` / bootstrap-doctor CLI), not something to silently truncate.
If you are unsure which harnesses the user uses, start with the current harness and explain how to add more later.
47
-
48
73
### Cursor GUI work loop at user scope
49
74
50
-
Cursor GUI agents need user-level wiring in addition to a repository handoff inbox. Preview the narrow profile before applying it:
75
+
Cursor GUI agents need user-level wiring in addition to a repository handoff inbox. Preview, then apply:
51
76
52
77
```bash
53
78
brigade harness install cursor --scope user --dry-run
54
79
brigade harness install cursor --scope user --write
55
80
brigade harness doctor cursor --scope user
56
81
```
57
82
58
-
This profile manages a local plugin rule, the global `brigade-work` skill, one `sessionStart` hook, and the `brigade`, `graphtrail`, and`miseledger`entries in `~/.cursor/mcp.json`. It preserves unrelated plugins, hooks, MCP servers, and sibling JSON fields. Existing values with a managed name are reported as conflicts instead of being replaced. Reload Cursor windows after a successful write.
83
+
This profile manages a local plugin rule, the global `brigade-work` skill, one `sessionStart` hook, and MCP entries for Brigade plus the code-map and evidence engines (often still labeled `graphtrail` /`miseledger` in native Cursor config). It preserves unrelated plugins, hooks, MCP servers, and sibling JSON fields. Existing values with a managed name are reported as conflicts instead of being replaced. Reload Cursor windows after a successful write.
59
84
60
-
To remove the profile, preview and then apply the ownership-aware uninstall:
85
+
Uninstall is ownership-aware:
61
86
62
87
```bash
63
88
brigade harness uninstall cursor --scope user --dry-run
64
89
brigade harness uninstall cursor --scope user --write
65
90
```
66
91
67
-
Uninstall removes entries only when they still match Brigade's ownership record. User-edited managed entries are preserved and reported as conflicts.
68
-
69
-
## Adapting Existing Setups
70
-
71
-
Before changing files, inspect the target directory for existing setup:
72
-
73
-
-`AGENTS.md`
74
-
-`CLAUDE.md`
75
-
-`MEMORY.md`
76
-
-`TOOLS.md`
77
-
-`.codex/`
78
-
-`.claude/`
79
-
-`.opencode/`
80
-
-`.antigravity/`
81
-
-`.pi/`
82
-
-`.cursor/`
83
-
-`.aider/`
84
-
-`.goose/`
85
-
-`.continue/`
86
-
-`.copilot/`
87
-
-`.qwen/`
88
-
-`.kimi/`
89
-
-`.adal/`
90
-
-`.openhands/`
91
-
-`.grok/`
92
-
-`.hermes/`
93
-
-`.openclaw/`
94
-
-`.mcp/`
95
-
96
-
Preserve the user's existing memory owner, conventions, repo layout, and tool-specific docs when possible. Prefer adding compatibility wiring such as handoff inboxes, shared instruction files, portable tool sources, or scanner config.
97
-
98
-
Do not force the user into Brigade's example layout when they already have a working homegrown setup. Do not assume the target must be a git repo; an OpenClaw/Hermes memory workspace or VPS operator directory is also a valid target.
99
-
100
-
## Local And Shareable Files
92
+
## After install: the agent work loop
93
+
94
+
Once doctor is healthy, **you** (the coding agent) should prefer:
95
+
96
+
```bash
97
+
brigade work verify run --target . --command "<real check>" --capture brigade-work
98
+
brigade code impact <symbol># when a change has blast radius
99
+
brigade evidence search "<query>"# when you need prior runs or claims
100
+
```
101
+
102
+
Do not claim tests passed without a real exit code. Prefer Brigade-wrapped verify over raw test commands when the project wires the work loop.
103
+
104
+
## Adapting existing setups
105
+
106
+
Before changing files, inventory what is already there:
107
+
108
+
-`AGENTS.md`, `CLAUDE.md`, `MEMORY.md`, `TOOLS.md`, `SOUL.md`, `IDENTITY.md` (OpenClaw and friends)
109
+
- harness dirs: `.codex/`, `.claude/`, `.cursor/`, `.openclaw/`, `.hermes/`, and the rest listed in the previous inventory
110
+
111
+
Preserve the user's memory owner, conventions, repo layout, and tool-specific docs when possible. Prefer adding compatibility wiring (handoff inboxes, shared instructions, portable tool sources, scanner config).
112
+
113
+
Do not force Brigade's example layout when they already have a working homegrown setup. Do not assume the target must be a git repo; an OpenClaw/Hermes memory workspace or VPS operator directory is valid.
114
+
115
+
When the target may already have scripts, handoffs, crons, or process managers, use adopt before rewrite:
-`MEMORY.md` and reviewed memory cards if this repo owns memory
106
-
-`rules/`
107
-
-`tools/`
108
-
- public docs
127
+
-`AGENTS.md`, `MEMORY.md` and reviewed memory cards if this repo owns memory
128
+
-`rules/`, `tools/`, public docs
109
129
110
130
Usually local-only:
111
131
112
132
-`.brigade/`
113
-
-`.codex/`
114
-
-`.claude/`
115
-
-`.opencode/`
116
-
-`.antigravity/`
117
-
-`.pi/`
118
-
-`.cursor/`
119
-
-`.aider/`
120
-
-`.goose/`
121
-
-`.continue/`
122
-
-`.copilot/`
123
-
-`.qwen/`
124
-
-`.kimi/`
125
-
-`.adal/`
126
-
-`.openhands/`
127
-
-`.grok/`
128
-
-`.hermes/`
129
-
-`.openclaw/`
130
-
-`.mcp/`
131
-
- generated `scripts/` projections
132
-
133
-
Do not commit generated local state unless the user explicitly asks and the Brigade docs say it is repo-shareable.
134
-
135
-
## Safety Boundaries
136
-
137
-
Do not start daemons, install schedulers, publish, push, tag, deploy, mutate remotes, install hooks, or run destructive commands as part of Brigade setup unless the user explicitly asks for that action.
133
+
- harness local dirs (`.codex/`, `.claude/`, `.cursor/`, `.openclaw/`, …)
134
+
- generated projections and scanner state
135
+
136
+
Do not commit generated local state unless the user explicitly asks and the docs say it is repo-shareable.
137
+
138
+
## Safety boundaries
139
+
140
+
Do not start daemons, install schedulers, publish, push, tag, deploy, mutate remotes, install hooks, or run destructive commands as part of Brigade setup unless the user explicitly asks.
138
141
139
142
Do not paste raw scanner output, session text, tokens, API keys, private hostnames, private repo names, or unredacted absolute paths into public issues or docs.
140
143
141
-
If setup fails, collect machine-readable output and summarize it after redaction:
144
+
If setup fails, collect machine-readable output and summarize after redaction:
0 commit comments