agent-method 1.5.0 → 1.5.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/README.md +256 -256
- package/lib/cli/check.js +1 -1
- package/lib/cli/init.js +1 -1
- package/lib/cli/refine.js +1 -1
- package/lib/cli/scan.js +2 -2
- package/lib/cli/status.js +1 -1
- package/lib/cli/upgrade.js +1 -1
- package/lib/init.js +1 -1
- package/package.json +1 -1
- package/templates/README.md +293 -293
- package/templates/entry-points/.cursorrules +8 -8
- package/templates/entry-points/AGENT.md +8 -8
- package/templates/entry-points/CLAUDE.md +8 -8
- package/templates/full/.cursorrules +8 -8
- package/templates/full/AGENT.md +8 -8
- package/templates/full/CLAUDE.md +8 -8
- package/templates/starter/.cursorrules +8 -8
- package/templates/starter/AGENT.md +8 -8
- package/templates/starter/CLAUDE.md +8 -8
package/README.md
CHANGED
|
@@ -1,256 +1,256 @@
|
|
|
1
|
-
# agent-method
|
|
2
|
-
|
|
3
|
-
A file-structure-first methodology for AI-agent-assisted development. Files are the interface — with optional CLI tools for validation, routing, and project management.
|
|
4
|
-
|
|
5
|
-
`ai-agents` `prompt-engineering` `developer-tools` `context-engineering` `agent-framework` `markdown` `llm-tools` `ai-workflow` `cursor` `claude-code`
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## The problem
|
|
10
|
-
|
|
11
|
-
AI-agent-assisted development breaks down in three ways:
|
|
12
|
-
|
|
13
|
-
- **Context rot** — agent quality degrades as context windows fill with irrelevant conversation
|
|
14
|
-
- **Amnesia** — decisions from session N are lost by session N+1
|
|
15
|
-
- **Scope drift** — without structured gates, work sprawls and progress becomes invisible
|
|
16
|
-
|
|
17
|
-
Existing solutions tie you to specific agent runtimes through CLI tools and slash commands. agent-method solves this with **files as the interface** — readable, portable, agent-agnostic.
|
|
18
|
-
|
|
19
|
-
## Quick start
|
|
20
|
-
|
|
21
|
-
### Option A: npx (recommended, zero-install)
|
|
22
|
-
|
|
23
|
-
```bash
|
|
24
|
-
npx agent-method init code ~/my-project
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
Replace `code` with your project type: `code`, `context`, `data`, `mix`, or `general`.
|
|
28
|
-
|
|
29
|
-
Done. Templates are copied, extensions merged, placeholders filled. Open `PROJECT.md` and start working.
|
|
30
|
-
|
|
31
|
-
### Option B: Setup script
|
|
32
|
-
|
|
33
|
-
```bash
|
|
34
|
-
git clone https://github.com/anthropics/agent-method.git
|
|
35
|
-
cd agent-method
|
|
36
|
-
bash setup.sh ~/my-project
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
Interactive installer — asks project name, type, runtime, tier, lifecycle, and profile.
|
|
40
|
-
|
|
41
|
-
### Option C: Manual copy
|
|
42
|
-
|
|
43
|
-
```
|
|
44
|
-
cp -r templates/starter/ ~/my-project/
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
Delete the two entry point files you don't use and fill in `PROJECT.md`.
|
|
48
|
-
|
|
49
|
-
## CLI Tools (optional)
|
|
50
|
-
|
|
51
|
-
The methodology works entirely through files, but CLI tools are available for validation, routing, and project management.
|
|
52
|
-
|
|
53
|
-
### Installation
|
|
54
|
-
|
|
55
|
-
```bash
|
|
56
|
-
npx agent-method # zero-install, runs directly
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
Or install permanently:
|
|
60
|
-
|
|
61
|
-
```bash
|
|
62
|
-
npm install -g agent-method # Node.js (global)
|
|
63
|
-
pip install agent-method-tools # Python (alternative)
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
Both distributions have identical commands, same registry, same templates.
|
|
67
|
-
|
|
68
|
-
### Developer commands
|
|
69
|
-
|
|
70
|
-
| Command | What it does |
|
|
71
|
-
|---------|-------------|
|
|
72
|
-
| `agent-method check` | Validate your entry point (auto-finds file, auto-detects type) |
|
|
73
|
-
| `agent-method scan` | Detect project type from directory contents |
|
|
74
|
-
| `agent-method route "<query>"` | Show how a query routes through the pipeline |
|
|
75
|
-
| `agent-method refine` | Extract refinement report from SESSION-LOG.md |
|
|
76
|
-
| `agent-method status` | Check if your methodology version is current |
|
|
77
|
-
| `agent-method upgrade` | Brownfield-safe methodology update |
|
|
78
|
-
| `agent-method init <type>` | Describe entry point contents for a project type |
|
|
79
|
-
|
|
80
|
-
### Project type aliases
|
|
81
|
-
|
|
82
|
-
Use friendly names with any command: `code`, `context`, `data`, `mix`, `general`.
|
|
83
|
-
|
|
84
|
-
```bash
|
|
85
|
-
agent-method init code # software project
|
|
86
|
-
agent-method init context # analytical/prompt project (PromptStudy)
|
|
87
|
-
agent-method init data # data index/querying project (SysMLv2)
|
|
88
|
-
agent-method init mix # multi-type project
|
|
89
|
-
agent-method route "query" -p context # route with project type
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
### Advanced: pipeline subcommands
|
|
93
|
-
|
|
94
|
-
For debugging individual pipeline stages: `agent-method pipeline classify|select|resolve|cascade|test`.
|
|
95
|
-
|
|
96
|
-
### Key features
|
|
97
|
-
|
|
98
|
-
- **All commands support `--json`** for machine-readable output
|
|
99
|
-
- **Smart defaults** — auto-finds entry point, session log, and project type
|
|
100
|
-
- **Two distributions** — `npx agent-method` (Node.js, zero-install) or `pip install agent-method-tools` (Python)
|
|
101
|
-
- **CLI is opt-in** — methodology works without it; tools add convenience
|
|
102
|
-
|
|
103
|
-
Run `agent-method --help` for full command reference.
|
|
104
|
-
|
|
105
|
-
## What you get
|
|
106
|
-
|
|
107
|
-
```
|
|
108
|
-
your-project/
|
|
109
|
-
CLAUDE.md / .cursorrules / AGENT.md # Agent entry point (pick one)
|
|
110
|
-
PROJECT.md # Project vision — fill this in first
|
|
111
|
-
PROJECT-PROFILE.md # Project type, lifecycle stage, extensions
|
|
112
|
-
STATE.md # Decisions, blockers, current position
|
|
113
|
-
ROADMAP.md # Phase breakdown with gate criteria
|
|
114
|
-
PLAN.md # Current task with verification criteria
|
|
115
|
-
.context/
|
|
116
|
-
BASE.md # Core context — always loaded with entry point
|
|
117
|
-
METHODOLOGY.md # Workflows, conventions overflow (lite/standard profiles)
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
Full tier adds: `REQUIREMENTS.md`, `SUMMARY.md`, `.context/REGISTRY.md`, `docs/`, `todos/backlog.md`.
|
|
121
|
-
|
|
122
|
-
Every file ships with **inline instructions** — the agent reads them and helps you populate each section.
|
|
123
|
-
|
|
124
|
-
## How it works
|
|
125
|
-
|
|
126
|
-
### Scoping rules
|
|
127
|
-
|
|
128
|
-
The entry point contains a table mapping query types to file sets. When you ask a question, the agent loads only the relevant files and constrains its writes. Context windows stay small, responses stay focused.
|
|
129
|
-
|
|
130
|
-
```markdown
|
|
131
|
-
| Query type | Read before acting | Update after acting |
|
|
132
|
-
|---------------------|------------------------------|----------------------------|
|
|
133
|
-
| **Code change** | .context/BASE.md + specialist | Source files, test files |
|
|
134
|
-
| **Planning** | REQUIREMENTS.md, ROADMAP.md | STATE.md, PLAN.md |
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
### Dependency cascade
|
|
138
|
-
|
|
139
|
-
"When X changes, also update Y." The agent checks this table after every file change, preventing files from drifting out of sync.
|
|
140
|
-
|
|
141
|
-
```markdown
|
|
142
|
-
| When this changes | Also update |
|
|
143
|
-
|----------------------|------------------------------------------------|
|
|
144
|
-
| Database schema | Migrations, type imports, .context/DATABASE.md |
|
|
145
|
-
| Phase completion | SUMMARY.md, STATE.md, ROADMAP.md |
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
### Context pairing
|
|
149
|
-
|
|
150
|
-
Instead of loading all context at once, the agent pairs `.context/BASE.md` with one specialist file per query type. A code change loads `BASE.md + DATABASE.md`. A planning query loads `REQUIREMENTS.md + ROADMAP.md`. Token usage stays low, relevance stays high.
|
|
151
|
-
|
|
152
|
-
### Cross-session memory
|
|
153
|
-
|
|
154
|
-
`STATE.md` persists decisions, blockers, and current position across sessions. The agent reads it at the start of every conversation — no re-explaining what happened yesterday.
|
|
155
|
-
|
|
156
|
-
## Integration profiles
|
|
157
|
-
|
|
158
|
-
Control how much methodology surface area gets installed. Match the profile to your model's capability.
|
|
159
|
-
|
|
160
|
-
| Profile | Best for | Entry point size | What's included |
|
|
161
|
-
|---------|----------|:-----------------:|-----------------|
|
|
162
|
-
| **lite** | Haiku, simple projects | ~25 lines | STATE.md, minimal rules, 2 cascade rules |
|
|
163
|
-
| **standard** | Sonnet (recommended) | ~40 lines | + PLAN.md, context pairing, 6 cascade rules, overflow to METHODOLOGY.md |
|
|
164
|
-
| **full** | Opus, complex projects | ~60 lines | All rules inline, all intelligence layer files |
|
|
165
|
-
|
|
166
|
-
Three rules followed consistently beat ten rules followed inconsistently.
|
|
167
|
-
|
|
168
|
-
## Project types
|
|
169
|
-
|
|
170
|
-
| Type | CLI name | What's added to the entry point |
|
|
171
|
-
|------|----------|-------------------------------|
|
|
172
|
-
| **General** | `general` | Universal scoping and cascade rules only |
|
|
173
|
-
| **Code** | `code` | Code change, bug fix, dependency, database, API, deployment scoping + cascade |
|
|
174
|
-
| **Data** | `data` | Data ingest, schema, document, entity, relationship, analytical query scoping + cascade |
|
|
175
|
-
| **Analytical** | `context` | Chain work, evaluation, composition, domain research scoping + cascade |
|
|
176
|
-
| **Mixed** | `mix` | Multiple extensions combined (code+data, code+analytical, etc.) |
|
|
177
|
-
|
|
178
|
-
Extensions are additive — they add rows to existing tables, never override universal content.
|
|
179
|
-
|
|
180
|
-
## Brownfield projects (existing codebases)
|
|
181
|
-
|
|
182
|
-
For projects with existing code, `setup.sh` detects project indicators and activates brownfield mode:
|
|
183
|
-
|
|
184
|
-
- **Never overwrites** existing files — only copies methodology files that don't already exist
|
|
185
|
-
- **Appends** methodology sections to your existing entry point (`CLAUDE.md`, `.cursorrules`, etc.)
|
|
186
|
-
- **Preserves** all your existing conventions, rules, and project terminology
|
|
187
|
-
- **Suggests** the Discovery workflow (WF-08) for systematic codebase understanding:
|
|
188
|
-
|
|
189
|
-
> Ask your agent: "Scan the codebase and populate the context files"
|
|
190
|
-
|
|
191
|
-
The agent inventories your project, maps dependencies, extracts patterns, and bootstraps `.context/` files — all without modifying your source code.
|
|
192
|
-
|
|
193
|
-
## Lifecycle stages
|
|
194
|
-
|
|
195
|
-
Projects evolve. The methodology adapts.
|
|
196
|
-
|
|
197
|
-
| Stage | When | What activates |
|
|
198
|
-
|-------|------|----------------|
|
|
199
|
-
| **Discovery** | Existing project, agent maps it first | SCAN features, WF-08 discovery workflow |
|
|
200
|
-
| **Design** | New project, defining architecture | Planning workflows, decision recording |
|
|
201
|
-
| **Development** | Building and iterating | Code/data/analytical workflows, full cascade |
|
|
202
|
-
| **Evolution** | Maintaining and extending | Context refresh, drift detection |
|
|
203
|
-
|
|
204
|
-
Transitions happen naturally — update `PROJECT-PROFILE.md` when you're ready to move on.
|
|
205
|
-
|
|
206
|
-
## Supported runtimes
|
|
207
|
-
|
|
208
|
-
| File | Runtime | Auto-loaded? |
|
|
209
|
-
|------|---------|:------------:|
|
|
210
|
-
| `CLAUDE.md` | Claude Code | Yes |
|
|
211
|
-
| `.cursorrules` | Cursor | Yes |
|
|
212
|
-
| `AGENT.md` | Any agent | No (paste or reference manually) |
|
|
213
|
-
|
|
214
|
-
All three contain identical scoping rules, cascade structure, and conventions — only the filename and auto-loading behavior differ.
|
|
215
|
-
|
|
216
|
-
## Template tiers
|
|
217
|
-
|
|
218
|
-
**Starter** (7 files) — Cross-session memory, scoped context loading, project profiling, structured execution. Good for most projects.
|
|
219
|
-
|
|
220
|
-
**Full** (11+ files) — Everything in starter, plus requirements tracking, execution history (`SUMMARY.md`), navigation registry, human-facing docs scaffold, and backlog capture. For complex or long-running projects.
|
|
221
|
-
|
|
222
|
-
## Methodology at a glance
|
|
223
|
-
|
|
224
|
-
| Concept | What it does |
|
|
225
|
-
|---------|-------------|
|
|
226
|
-
| **Intelligence layer** | PROJECT / STATE / ROADMAP / PLAN / SUMMARY files provide persistent cross-session memory |
|
|
227
|
-
| **Scoping rules** | Table-driven query routing — agent loads only what's relevant |
|
|
228
|
-
| **Dependency cascade** | "When X changes, also update Y" prevents file drift |
|
|
229
|
-
| **Context pairing** | One specialist file per query type, not everything at once |
|
|
230
|
-
| **Workflow stages** | Initialize → Scope → Plan → Execute → Verify → Close |
|
|
231
|
-
| **Integration profiles** | lite / standard / full — match methodology depth to model capability |
|
|
232
|
-
| **Brownfield merge** | Append-only integration — never overwrites, never deletes |
|
|
233
|
-
| **CLI tools (optional)** | 7 developer commands + pipeline subcommands for debugging |
|
|
234
|
-
| **32 agent capabilities** | Organized across 8 domains, activate behind the scenes |
|
|
235
|
-
|
|
236
|
-
## Documentation
|
|
237
|
-
|
|
238
|
-
| Document | Audience |
|
|
239
|
-
|----------|----------|
|
|
240
|
-
| [Quick start guide](docs/guides/quick-start.md) | Developers — setup and first session |
|
|
241
|
-
| [For developers](docs/guides/for-developers.md) | Developers — workflows, context, troubleshooting |
|
|
242
|
-
| [For managers](docs/guides/for-managers.md) | Managers — reading project status from methodology files |
|
|
243
|
-
| [Template kit](templates/README.md) | Template tiers, extensions, bootstrapping |
|
|
244
|
-
| [CLI tools](https://github.com/anthropics/agent-method#cli-tools-optional) | Command reference (or run `agent-method --help`) |
|
|
245
|
-
| [Docs hub](docs/index.md) | Full architecture, workflow, and methodology docs |
|
|
246
|
-
|
|
247
|
-
## Prior art
|
|
248
|
-
|
|
249
|
-
| System | Relationship |
|
|
250
|
-
|--------|-------------|
|
|
251
|
-
| [GSD (get-shit-done)](https://github.com/jlowin/get-shit-done) | Inspired the structured agent workflow. agent-method removes CLI dependency, adds scoping rules and context pairing |
|
|
252
|
-
| PromptStudy | Reference implementation. Scoping rules, cascade, and context pairing patterns extracted from real agent-human collaboration |
|
|
253
|
-
|
|
254
|
-
## License
|
|
255
|
-
|
|
256
|
-
MIT (pending)
|
|
1
|
+
# agent-method
|
|
2
|
+
|
|
3
|
+
A file-structure-first methodology for AI-agent-assisted development. Files are the interface — with optional CLI tools for validation, routing, and project management.
|
|
4
|
+
|
|
5
|
+
`ai-agents` `prompt-engineering` `developer-tools` `context-engineering` `agent-framework` `markdown` `llm-tools` `ai-workflow` `cursor` `claude-code`
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## The problem
|
|
10
|
+
|
|
11
|
+
AI-agent-assisted development breaks down in three ways:
|
|
12
|
+
|
|
13
|
+
- **Context rot** — agent quality degrades as context windows fill with irrelevant conversation
|
|
14
|
+
- **Amnesia** — decisions from session N are lost by session N+1
|
|
15
|
+
- **Scope drift** — without structured gates, work sprawls and progress becomes invisible
|
|
16
|
+
|
|
17
|
+
Existing solutions tie you to specific agent runtimes through CLI tools and slash commands. agent-method solves this with **files as the interface** — readable, portable, agent-agnostic.
|
|
18
|
+
|
|
19
|
+
## Quick start
|
|
20
|
+
|
|
21
|
+
### Option A: npx (recommended, zero-install)
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npx agent-method init code ~/my-project
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Replace `code` with your project type: `code`, `context`, `data`, `mix`, or `general`.
|
|
28
|
+
|
|
29
|
+
Done. Templates are copied, extensions merged, placeholders filled. Open `PROJECT.md` and start working.
|
|
30
|
+
|
|
31
|
+
### Option B: Setup script
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
git clone https://github.com/anthropics/agent-method.git
|
|
35
|
+
cd agent-method
|
|
36
|
+
bash setup.sh ~/my-project
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Interactive installer — asks project name, type, runtime, tier, lifecycle, and profile.
|
|
40
|
+
|
|
41
|
+
### Option C: Manual copy
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
cp -r templates/starter/ ~/my-project/
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Delete the two entry point files you don't use and fill in `PROJECT.md`.
|
|
48
|
+
|
|
49
|
+
## CLI Tools (optional)
|
|
50
|
+
|
|
51
|
+
The methodology works entirely through files, but CLI tools are available for validation, routing, and project management.
|
|
52
|
+
|
|
53
|
+
### Installation
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
npx agent-method # zero-install, runs directly
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Or install permanently:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npm install -g agent-method # Node.js (global)
|
|
63
|
+
pip install agent-method-tools # Python (alternative)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Both distributions have identical commands, same registry, same templates.
|
|
67
|
+
|
|
68
|
+
### Developer commands
|
|
69
|
+
|
|
70
|
+
| Command | What it does |
|
|
71
|
+
|---------|-------------|
|
|
72
|
+
| `npx agent-method check` | Validate your entry point (auto-finds file, auto-detects type) |
|
|
73
|
+
| `npx agent-method scan` | Detect project type from directory contents |
|
|
74
|
+
| `npx agent-method route "<query>"` | Show how a query routes through the pipeline |
|
|
75
|
+
| `npx agent-method refine` | Extract refinement report from SESSION-LOG.md |
|
|
76
|
+
| `npx agent-method status` | Check if your methodology version is current |
|
|
77
|
+
| `npx agent-method upgrade` | Brownfield-safe methodology update |
|
|
78
|
+
| `npx agent-method init <type>` | Describe entry point contents for a project type |
|
|
79
|
+
|
|
80
|
+
### Project type aliases
|
|
81
|
+
|
|
82
|
+
Use friendly names with any command: `code`, `context`, `data`, `mix`, `general`.
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
agent-method init code # software project
|
|
86
|
+
agent-method init context # analytical/prompt project (PromptStudy)
|
|
87
|
+
agent-method init data # data index/querying project (SysMLv2)
|
|
88
|
+
agent-method init mix # multi-type project
|
|
89
|
+
agent-method route "query" -p context # route with project type
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Advanced: pipeline subcommands
|
|
93
|
+
|
|
94
|
+
For debugging individual pipeline stages: `npx agent-method pipeline classify|select|resolve|cascade|test`.
|
|
95
|
+
|
|
96
|
+
### Key features
|
|
97
|
+
|
|
98
|
+
- **All commands support `--json`** for machine-readable output
|
|
99
|
+
- **Smart defaults** — auto-finds entry point, session log, and project type
|
|
100
|
+
- **Two distributions** — `npx agent-method` (Node.js, zero-install) or `pip install agent-method-tools` (Python)
|
|
101
|
+
- **CLI is opt-in** — methodology works without it; tools add convenience
|
|
102
|
+
|
|
103
|
+
Run `npx agent-method --help` for full command reference.
|
|
104
|
+
|
|
105
|
+
## What you get
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
your-project/
|
|
109
|
+
CLAUDE.md / .cursorrules / AGENT.md # Agent entry point (pick one)
|
|
110
|
+
PROJECT.md # Project vision — fill this in first
|
|
111
|
+
PROJECT-PROFILE.md # Project type, lifecycle stage, extensions
|
|
112
|
+
STATE.md # Decisions, blockers, current position
|
|
113
|
+
ROADMAP.md # Phase breakdown with gate criteria
|
|
114
|
+
PLAN.md # Current task with verification criteria
|
|
115
|
+
.context/
|
|
116
|
+
BASE.md # Core context — always loaded with entry point
|
|
117
|
+
METHODOLOGY.md # Workflows, conventions overflow (lite/standard profiles)
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Full tier adds: `REQUIREMENTS.md`, `SUMMARY.md`, `.context/REGISTRY.md`, `docs/`, `todos/backlog.md`.
|
|
121
|
+
|
|
122
|
+
Every file ships with **inline instructions** — the agent reads them and helps you populate each section.
|
|
123
|
+
|
|
124
|
+
## How it works
|
|
125
|
+
|
|
126
|
+
### Scoping rules
|
|
127
|
+
|
|
128
|
+
The entry point contains a table mapping query types to file sets. When you ask a question, the agent loads only the relevant files and constrains its writes. Context windows stay small, responses stay focused.
|
|
129
|
+
|
|
130
|
+
```markdown
|
|
131
|
+
| Query type | Read before acting | Update after acting |
|
|
132
|
+
|---------------------|------------------------------|----------------------------|
|
|
133
|
+
| **Code change** | .context/BASE.md + specialist | Source files, test files |
|
|
134
|
+
| **Planning** | REQUIREMENTS.md, ROADMAP.md | STATE.md, PLAN.md |
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Dependency cascade
|
|
138
|
+
|
|
139
|
+
"When X changes, also update Y." The agent checks this table after every file change, preventing files from drifting out of sync.
|
|
140
|
+
|
|
141
|
+
```markdown
|
|
142
|
+
| When this changes | Also update |
|
|
143
|
+
|----------------------|------------------------------------------------|
|
|
144
|
+
| Database schema | Migrations, type imports, .context/DATABASE.md |
|
|
145
|
+
| Phase completion | SUMMARY.md, STATE.md, ROADMAP.md |
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### Context pairing
|
|
149
|
+
|
|
150
|
+
Instead of loading all context at once, the agent pairs `.context/BASE.md` with one specialist file per query type. A code change loads `BASE.md + DATABASE.md`. A planning query loads `REQUIREMENTS.md + ROADMAP.md`. Token usage stays low, relevance stays high.
|
|
151
|
+
|
|
152
|
+
### Cross-session memory
|
|
153
|
+
|
|
154
|
+
`STATE.md` persists decisions, blockers, and current position across sessions. The agent reads it at the start of every conversation — no re-explaining what happened yesterday.
|
|
155
|
+
|
|
156
|
+
## Integration profiles
|
|
157
|
+
|
|
158
|
+
Control how much methodology surface area gets installed. Match the profile to your model's capability.
|
|
159
|
+
|
|
160
|
+
| Profile | Best for | Entry point size | What's included |
|
|
161
|
+
|---------|----------|:-----------------:|-----------------|
|
|
162
|
+
| **lite** | Haiku, simple projects | ~25 lines | STATE.md, minimal rules, 2 cascade rules |
|
|
163
|
+
| **standard** | Sonnet (recommended) | ~40 lines | + PLAN.md, context pairing, 6 cascade rules, overflow to METHODOLOGY.md |
|
|
164
|
+
| **full** | Opus, complex projects | ~60 lines | All rules inline, all intelligence layer files |
|
|
165
|
+
|
|
166
|
+
Three rules followed consistently beat ten rules followed inconsistently.
|
|
167
|
+
|
|
168
|
+
## Project types
|
|
169
|
+
|
|
170
|
+
| Type | CLI name | What's added to the entry point |
|
|
171
|
+
|------|----------|-------------------------------|
|
|
172
|
+
| **General** | `general` | Universal scoping and cascade rules only |
|
|
173
|
+
| **Code** | `code` | Code change, bug fix, dependency, database, API, deployment scoping + cascade |
|
|
174
|
+
| **Data** | `data` | Data ingest, schema, document, entity, relationship, analytical query scoping + cascade |
|
|
175
|
+
| **Analytical** | `context` | Chain work, evaluation, composition, domain research scoping + cascade |
|
|
176
|
+
| **Mixed** | `mix` | Multiple extensions combined (code+data, code+analytical, etc.) |
|
|
177
|
+
|
|
178
|
+
Extensions are additive — they add rows to existing tables, never override universal content.
|
|
179
|
+
|
|
180
|
+
## Brownfield projects (existing codebases)
|
|
181
|
+
|
|
182
|
+
For projects with existing code, `setup.sh` detects project indicators and activates brownfield mode:
|
|
183
|
+
|
|
184
|
+
- **Never overwrites** existing files — only copies methodology files that don't already exist
|
|
185
|
+
- **Appends** methodology sections to your existing entry point (`CLAUDE.md`, `.cursorrules`, etc.)
|
|
186
|
+
- **Preserves** all your existing conventions, rules, and project terminology
|
|
187
|
+
- **Suggests** the Discovery workflow (WF-08) for systematic codebase understanding:
|
|
188
|
+
|
|
189
|
+
> Ask your agent: "Scan the codebase and populate the context files"
|
|
190
|
+
|
|
191
|
+
The agent inventories your project, maps dependencies, extracts patterns, and bootstraps `.context/` files — all without modifying your source code.
|
|
192
|
+
|
|
193
|
+
## Lifecycle stages
|
|
194
|
+
|
|
195
|
+
Projects evolve. The methodology adapts.
|
|
196
|
+
|
|
197
|
+
| Stage | When | What activates |
|
|
198
|
+
|-------|------|----------------|
|
|
199
|
+
| **Discovery** | Existing project, agent maps it first | SCAN features, WF-08 discovery workflow |
|
|
200
|
+
| **Design** | New project, defining architecture | Planning workflows, decision recording |
|
|
201
|
+
| **Development** | Building and iterating | Code/data/analytical workflows, full cascade |
|
|
202
|
+
| **Evolution** | Maintaining and extending | Context refresh, drift detection |
|
|
203
|
+
|
|
204
|
+
Transitions happen naturally — update `PROJECT-PROFILE.md` when you're ready to move on.
|
|
205
|
+
|
|
206
|
+
## Supported runtimes
|
|
207
|
+
|
|
208
|
+
| File | Runtime | Auto-loaded? |
|
|
209
|
+
|------|---------|:------------:|
|
|
210
|
+
| `CLAUDE.md` | Claude Code | Yes |
|
|
211
|
+
| `.cursorrules` | Cursor | Yes |
|
|
212
|
+
| `AGENT.md` | Any agent | No (paste or reference manually) |
|
|
213
|
+
|
|
214
|
+
All three contain identical scoping rules, cascade structure, and conventions — only the filename and auto-loading behavior differ.
|
|
215
|
+
|
|
216
|
+
## Template tiers
|
|
217
|
+
|
|
218
|
+
**Starter** (7 files) — Cross-session memory, scoped context loading, project profiling, structured execution. Good for most projects.
|
|
219
|
+
|
|
220
|
+
**Full** (11+ files) — Everything in starter, plus requirements tracking, execution history (`SUMMARY.md`), navigation registry, human-facing docs scaffold, and backlog capture. For complex or long-running projects.
|
|
221
|
+
|
|
222
|
+
## Methodology at a glance
|
|
223
|
+
|
|
224
|
+
| Concept | What it does |
|
|
225
|
+
|---------|-------------|
|
|
226
|
+
| **Intelligence layer** | PROJECT / STATE / ROADMAP / PLAN / SUMMARY files provide persistent cross-session memory |
|
|
227
|
+
| **Scoping rules** | Table-driven query routing — agent loads only what's relevant |
|
|
228
|
+
| **Dependency cascade** | "When X changes, also update Y" prevents file drift |
|
|
229
|
+
| **Context pairing** | One specialist file per query type, not everything at once |
|
|
230
|
+
| **Workflow stages** | Initialize → Scope → Plan → Execute → Verify → Close |
|
|
231
|
+
| **Integration profiles** | lite / standard / full — match methodology depth to model capability |
|
|
232
|
+
| **Brownfield merge** | Append-only integration — never overwrites, never deletes |
|
|
233
|
+
| **CLI tools (optional)** | 7 developer commands + pipeline subcommands for debugging |
|
|
234
|
+
| **32 agent capabilities** | Organized across 8 domains, activate behind the scenes |
|
|
235
|
+
|
|
236
|
+
## Documentation
|
|
237
|
+
|
|
238
|
+
| Document | Audience |
|
|
239
|
+
|----------|----------|
|
|
240
|
+
| [Quick start guide](docs/guides/quick-start.md) | Developers — setup and first session |
|
|
241
|
+
| [For developers](docs/guides/for-developers.md) | Developers — workflows, context, troubleshooting |
|
|
242
|
+
| [For managers](docs/guides/for-managers.md) | Managers — reading project status from methodology files |
|
|
243
|
+
| [Template kit](templates/README.md) | Template tiers, extensions, bootstrapping |
|
|
244
|
+
| [CLI tools](https://github.com/anthropics/agent-method#cli-tools-optional) | Command reference (or run `npx agent-method --help`) |
|
|
245
|
+
| [Docs hub](docs/index.md) | Full architecture, workflow, and methodology docs |
|
|
246
|
+
|
|
247
|
+
## Prior art
|
|
248
|
+
|
|
249
|
+
| System | Relationship |
|
|
250
|
+
|--------|-------------|
|
|
251
|
+
| [GSD (get-shit-done)](https://github.com/jlowin/get-shit-done) | Inspired the structured agent workflow. agent-method removes CLI dependency, adds scoping rules and context pairing |
|
|
252
|
+
| PromptStudy | Reference implementation. Scoping rules, cascade, and context pairing patterns extracted from real agent-human collaboration |
|
|
253
|
+
|
|
254
|
+
## License
|
|
255
|
+
|
|
256
|
+
MIT (pending)
|
package/lib/cli/check.js
CHANGED
|
@@ -28,7 +28,7 @@ export function register(program) {
|
|
|
28
28
|
console.error(
|
|
29
29
|
"No entry point found in current directory " +
|
|
30
30
|
"(looked for CLAUDE.md, .cursorrules, AGENT.md).\n" +
|
|
31
|
-
"Specify a path: agent-method check path/to/CLAUDE.md"
|
|
31
|
+
"Specify a path: npx agent-method check path/to/CLAUDE.md"
|
|
32
32
|
);
|
|
33
33
|
process.exit(1);
|
|
34
34
|
}
|
package/lib/cli/init.js
CHANGED
|
@@ -44,7 +44,7 @@ export function register(program) {
|
|
|
44
44
|
if (!directory) {
|
|
45
45
|
console.log(
|
|
46
46
|
"\nTo create a project, specify a directory:\n" +
|
|
47
|
-
` agent-method init ${projectTypeArg} ~/my-project`
|
|
47
|
+
` npx agent-method init ${projectTypeArg} ~/my-project`
|
|
48
48
|
);
|
|
49
49
|
}
|
|
50
50
|
return;
|
package/lib/cli/refine.js
CHANGED
|
@@ -15,7 +15,7 @@ export function register(program) {
|
|
|
15
15
|
if (!sessionLog) {
|
|
16
16
|
console.error(
|
|
17
17
|
"No SESSION-LOG.md found in current directory.\n" +
|
|
18
|
-
"Specify a path: agent-method refine path/to/SESSION-LOG.md"
|
|
18
|
+
"Specify a path: npx agent-method refine path/to/SESSION-LOG.md"
|
|
19
19
|
);
|
|
20
20
|
process.exit(1);
|
|
21
21
|
}
|
package/lib/cli/scan.js
CHANGED
|
@@ -17,9 +17,9 @@ export function register(program) {
|
|
|
17
17
|
const friendlyMap = { analytical: "context", mixed: "mix" };
|
|
18
18
|
if (ptype in friendlyMap) {
|
|
19
19
|
result.friendly_name = friendlyMap[ptype];
|
|
20
|
-
result.init_command = `agent-method init ${friendlyMap[ptype]}`;
|
|
20
|
+
result.init_command = `npx agent-method init ${friendlyMap[ptype]}`;
|
|
21
21
|
} else {
|
|
22
|
-
result.init_command = `agent-method init ${ptype}`;
|
|
22
|
+
result.init_command = `npx agent-method init ${ptype}`;
|
|
23
23
|
}
|
|
24
24
|
|
|
25
25
|
console.log(`Scanning: ${directory}`);
|
package/lib/cli/status.js
CHANGED
|
@@ -38,7 +38,7 @@ export function register(program) {
|
|
|
38
38
|
message =
|
|
39
39
|
`Entry point ${basename_of(ep)} is outdated ` +
|
|
40
40
|
`(method_version: ${epVersion}, installed: ${installed}). ` +
|
|
41
|
-
`Run \`agent-method upgrade ${directory}\` to update.`;
|
|
41
|
+
`Run \`npx agent-method upgrade ${directory}\` to update.`;
|
|
42
42
|
}
|
|
43
43
|
|
|
44
44
|
if (opts.json) {
|
package/lib/cli/upgrade.js
CHANGED
|
@@ -65,7 +65,7 @@ export function register(program) {
|
|
|
65
65
|
`## Method version\n\n` +
|
|
66
66
|
`method_version: ${newVer}\n` +
|
|
67
67
|
`<!-- Tracks which methodology version generated this entry point -->\n` +
|
|
68
|
-
`<!-- Use \`agent-method status\` to compare against latest -->\n\n`;
|
|
68
|
+
`<!-- Use \`npx agent-method status\` to compare against latest -->\n\n`;
|
|
69
69
|
content = content.replace("## Conventions", insert + "## Conventions");
|
|
70
70
|
writeFileSync(ep, content, "utf-8");
|
|
71
71
|
}
|
package/lib/init.js
CHANGED
|
@@ -86,7 +86,7 @@ export async function initProject(projectType, directory, opts = {}) {
|
|
|
86
86
|
console.log(` 3. Delete the two entry point files you don't use`);
|
|
87
87
|
console.log(` (keep CLAUDE.md, .cursorrules, or AGENT.md)`);
|
|
88
88
|
console.log(` 4. Start a conversation — the agent reads the entry point`);
|
|
89
|
-
console.log(`\nRun \`agent-method check\` to validate your setup.`);
|
|
89
|
+
console.log(`\nRun \`npx agent-method check\` to validate your setup.`);
|
|
90
90
|
}
|
|
91
91
|
|
|
92
92
|
function detectBrownfield(dir) {
|
package/package.json
CHANGED