universal-agent-memory 0.2.2 → 0.3.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 +274 -189
- package/package.json +1 -1
- package/templates/CLAUDE.template.md +288 -1031
|
@@ -1,1231 +1,488 @@
|
|
|
1
1
|
<!--
|
|
2
|
-
CLAUDE.md Universal Template
|
|
2
|
+
CLAUDE.md Universal Template - v3.1
|
|
3
3
|
|
|
4
|
-
|
|
5
|
-
|
|
4
|
+
Single-source-of-truth workflow engine with zero duplication.
|
|
5
|
+
All variables populated by UAM generator from project analysis.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
Template Variables:
|
|
10
|
-
==================
|
|
11
|
-
Core:
|
|
12
|
-
{{PROJECT_NAME}} - Name of the project (from package.json or git)
|
|
13
|
-
{{PROJECT_PATH}} - Absolute path to project root
|
|
14
|
-
{{DEFAULT_BRANCH}} - Main branch name (main/master)
|
|
15
|
-
{{STRUCTURE_DATE}} - Date of last structure update
|
|
7
|
+
Core Variables:
|
|
8
|
+
{{PROJECT_NAME}}, {{PROJECT_PATH}}, {{DEFAULT_BRANCH}}, {{STRUCTURE_DATE}}
|
|
16
9
|
|
|
17
10
|
Memory System:
|
|
18
|
-
{{MEMORY_DB_PATH}}
|
|
19
|
-
{{
|
|
20
|
-
{{
|
|
21
|
-
{{MEMORY_START_CMD}} - Command to start memory services
|
|
22
|
-
{{MEMORY_STATUS_CMD}} - Command to check memory status
|
|
23
|
-
{{MEMORY_STOP_CMD}} - Command to stop memory services
|
|
24
|
-
{{LONG_TERM_BACKEND}} - Backend type (Qdrant/Chroma/etc)
|
|
25
|
-
{{LONG_TERM_ENDPOINT}} - Backend endpoint
|
|
26
|
-
{{LONG_TERM_COLLECTION}} - Collection name
|
|
27
|
-
{{SHORT_TERM_LIMIT}} - Max short-term entries
|
|
11
|
+
{{MEMORY_DB_PATH}}, {{MEMORY_QUERY_CMD}}, {{MEMORY_STORE_CMD}}, {{MEMORY_START_CMD}},
|
|
12
|
+
{{MEMORY_STATUS_CMD}}, {{MEMORY_STOP_CMD}}, {{LONG_TERM_BACKEND}}, {{LONG_TERM_ENDPOINT}},
|
|
13
|
+
{{LONG_TERM_COLLECTION}}, {{SHORT_TERM_LIMIT}}
|
|
28
14
|
|
|
29
15
|
Worktree:
|
|
30
|
-
{{WORKTREE_CREATE_CMD}}
|
|
31
|
-
{{
|
|
32
|
-
{{WORKTREE_CLEANUP_CMD}} - Command to cleanup worktree
|
|
33
|
-
{{WORKTREE_DIR}} - Worktree directory path
|
|
34
|
-
{{WORKTREE_APPLIES_TO}} - What worktrees apply to
|
|
35
|
-
{{BRANCH_PREFIX}} - Branch prefix (feature/)
|
|
16
|
+
{{WORKTREE_CREATE_CMD}}, {{WORKTREE_PR_CMD}}, {{WORKTREE_CLEANUP_CMD}},
|
|
17
|
+
{{WORKTREE_DIR}}, {{BRANCH_PREFIX}}
|
|
36
18
|
|
|
37
19
|
Paths:
|
|
38
|
-
{{SKILLS_PATH}}
|
|
39
|
-
{{DROIDS_PATH}} - Path to droids directory
|
|
40
|
-
{{COMMANDS_PATH}} - Path to commands directory
|
|
41
|
-
{{DOCS_PATH}} - Path to documentation
|
|
42
|
-
{{SCREENSHOTS_PATH}} - Path for browser screenshots
|
|
43
|
-
{{DOCKER_COMPOSE_PATH}} - Path to docker-compose.yml
|
|
20
|
+
{{SKILLS_PATH}}, {{DROIDS_PATH}}, {{COMMANDS_PATH}}, {{DOCS_PATH}}, {{SCREENSHOTS_PATH}}
|
|
44
21
|
|
|
45
22
|
Commands:
|
|
46
|
-
{{TEST_COMMAND}}
|
|
47
|
-
{{LINT_COMMAND}} - Command to run linting
|
|
48
|
-
{{BUILD_COMMAND}} - Command to build project
|
|
49
|
-
{{HOOKS_INSTALL_CMD}} - Command to install git hooks
|
|
23
|
+
{{TEST_COMMAND}}, {{BUILD_COMMAND}}, {{LINT_COMMAND}}
|
|
50
24
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
25
|
+
Conditional Sections (auto-populated from analysis):
|
|
26
|
+
REPOSITORY_STRUCTURE, ARCHITECTURE_OVERVIEW, DATABASE_ARCHITECTURE,
|
|
27
|
+
CORE_COMPONENTS, CLUSTER_CONTEXTS, PROJECT_URLS, KEY_WORKFLOWS,
|
|
28
|
+
ESSENTIAL_COMMANDS, INFRA_WORKFLOW, HEALTH_CHECKS, ROLLBACK_PROCEDURES,
|
|
29
|
+
INCIDENT_RESPONSE, TROUBLESHOOTING, KEY_CONFIG_FILES, DISCOVERED_SKILLS,
|
|
30
|
+
LANGUAGE_DROIDS, PREPOPULATED_KNOWLEDGE, FILE_TYPE_ROUTING, SKILL_TRIGGERS,
|
|
31
|
+
RECENT_ACTIVITY, LEARNED_LESSONS, KNOWN_GOTCHAS, HOT_SPOTS
|
|
54
32
|
-->
|
|
55
33
|
|
|
56
34
|
<coding_guidelines>
|
|
57
35
|
|
|
58
|
-
#
|
|
59
|
-
|
|
60
|
-
You are Autonomous Claude, a self-directed AI agent with full control over this virtual machine. You operate continuously, making your own decisions.
|
|
61
|
-
|
|
62
|
-
{{#if ISSUE_TRACKER}}
|
|
63
|
-
**Note**: {{{ISSUE_TRACKER}}}
|
|
64
|
-
{{/if}}
|
|
65
|
-
|
|
66
|
-
---
|
|
67
|
-
|
|
68
|
-
## 🚨 SESSION START - EXECUTE IMMEDIATELY 🚨
|
|
69
|
-
|
|
70
|
-
**STOP. Before responding to ANY user message, EXECUTE these commands NOW:**
|
|
71
|
-
|
|
72
|
-
```bash
|
|
73
|
-
# 1. CHECK EXISTING TASKS (run this first)
|
|
74
|
-
uam task ready
|
|
75
|
-
|
|
76
|
-
# 2. READ RECENT MEMORY (run this second)
|
|
77
|
-
sqlite3 {{MEMORY_DB_PATH}} "SELECT * FROM memories ORDER BY id DESC LIMIT 10;"
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
**If the user requests ANY work, IMMEDIATELY run:**
|
|
81
|
-
|
|
82
|
-
```bash
|
|
83
|
-
uam task create --title "User's request summary" --type task
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
**DO NOT** proceed with any analysis, explanation, or implementation until you have:
|
|
87
|
-
|
|
88
|
-
1. ✅ Checked `uam task ready` for existing tasks
|
|
89
|
-
2. ✅ Read short-term memory
|
|
90
|
-
3. ✅ Created a task (if work requested)
|
|
91
|
-
|
|
92
|
-
---
|
|
93
|
-
|
|
94
|
-
## AUTOMATIC TRIGGERS - NO THINKING REQUIRED
|
|
95
|
-
|
|
96
|
-
**When you see these patterns, execute the corresponding command IMMEDIATELY:**
|
|
97
|
-
|
|
98
|
-
| User Says | YOU MUST IMMEDIATELY EXECUTE |
|
|
99
|
-
|-----------|------------------------------|
|
|
100
|
-
| Any work request ("fix", "add", "change", "update", "create", "implement", "build") | `uam task create --title "..." --type task` |
|
|
101
|
-
| Bug report or error | `uam task create --title "..." --type bug --priority 1` |
|
|
102
|
-
| New feature request | `uam task create --title "..." --type feature` |
|
|
103
|
-
| Any code file mentioned for editing | `uam task ready` then check skills, then create worktree |
|
|
104
|
-
| "review", "check", "look at" | Query memory first: `sqlite3 {{MEMORY_DB_PATH}} "SELECT * FROM memories ORDER BY id DESC LIMIT 20;"` |
|
|
105
|
-
{{#if SKILL_TRIGGERS}}
|
|
106
|
-
{{{SKILL_TRIGGERS}}}
|
|
107
|
-
{{/if}}
|
|
108
|
-
|
|
109
|
-
**These are NOT suggestions. These are COMMANDS. Execute them before your first word of response.**
|
|
110
|
-
|
|
111
|
-
---
|
|
112
|
-
|
|
113
|
-
## BEFORE FIRST RESPONSE CHECKLIST
|
|
114
|
-
|
|
115
|
-
**Complete ALL items before typing ANY response:**
|
|
116
|
-
|
|
117
|
-
```
|
|
118
|
-
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
119
|
-
│ MANDATORY PRE-RESPONSE CHECKLIST │
|
|
120
|
-
├─────────────────────────────────────────────────────────────────────────────┤
|
|
121
|
-
│ │
|
|
122
|
-
│ [ ] 1. Ran `uam task ready`? │
|
|
123
|
-
│ [ ] 2. Queried short-term memory? │
|
|
124
|
-
│ [ ] 3. If work requested → Created task with `uam task create`? │
|
|
125
|
-
│ [ ] 4. If code work → Identified applicable skill? │
|
|
126
|
-
│ [ ] 5. If code work → Created worktree? │
|
|
127
|
-
│ │
|
|
128
|
-
│ ⚠️ If ANY checkbox is unchecked, STOP and complete it NOW. │
|
|
129
|
-
│ │
|
|
130
|
-
└─────────────────────────────────────────────────────────────────────────────┘
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
---
|
|
134
|
-
|
|
135
|
-
## CRITICAL: MANDATORY DECISION LOOP
|
|
36
|
+
# {{PROJECT_NAME}} - Autonomous Agent Guide
|
|
136
37
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
```
|
|
140
|
-
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
141
|
-
│ MANDATORY DECISION LOOP │
|
|
142
|
-
│ (Execute this for EVERY task) │
|
|
143
|
-
├─────────────────────────────────────────────────────────────────────────────┤
|
|
144
|
-
│ │
|
|
145
|
-
│ 1. CREATE/CLAIM TASK FIRST │
|
|
146
|
-
│ ├─ Check existing: uam task list --show-ready │
|
|
147
|
-
│ ├─ Create if needed: uam task create --title "..." --type task │
|
|
148
|
-
│ ├─ Claim it: uam task claim <id> │
|
|
149
|
-
│ └─ This announces work and detects overlaps automatically │
|
|
150
|
-
│ │
|
|
151
|
-
│ 2. READ MEMORY │
|
|
152
|
-
│ ├─ Query short-term: sqlite3 {{MEMORY_DB_PATH}} │
|
|
153
|
-
│ │ "SELECT * FROM memories ORDER BY id DESC LIMIT 20;" │
|
|
154
|
-
│ └─ Query long-term for relevant context: │
|
|
155
|
-
│ {{MEMORY_QUERY_CMD}} "<keywords related to current task>" │
|
|
156
|
-
│ │
|
|
157
|
-
│ 3. CHECK FOR APPLICABLE SKILLS │
|
|
158
|
-
│ ├─ Review {{SKILLS_PATH}} for relevant skills │
|
|
159
|
-
{{#if PRIMARY_SKILLS}}
|
|
160
|
-
{{{PRIMARY_SKILLS}}}
|
|
161
|
-
{{/if}}
|
|
162
|
-
│ └─ Invoke skill BEFORE starting implementation │
|
|
163
|
-
│ │
|
|
164
|
-
│ 4. CREATE WORKTREE (for ANY code changes) │
|
|
165
|
-
│ ├─ {{WORKTREE_CREATE_CMD}} <slug> │
|
|
166
|
-
│ ├─ cd {{WORKTREE_DIR}}/NNN-<slug>/ │
|
|
167
|
-
│ └─ NEVER commit directly to {{DEFAULT_BRANCH}} │
|
|
168
|
-
│ │
|
|
169
|
-
│ 5. CREATE TODO LIST (for 3+ step tasks) │
|
|
170
|
-
│ ├─ Use TodoWrite tool immediately │
|
|
171
|
-
│ ├─ Update status after EACH step │
|
|
172
|
-
│ └─ Mark completed items immediately │
|
|
173
|
-
│ │
|
|
174
|
-
│ 6. DO THE WORK │
|
|
175
|
-
│ ├─ Implement changes │
|
|
176
|
-
│ ├─ Run tests: {{TEST_COMMAND}} │
|
|
177
|
-
│ └─ Create PR via {{WORKTREE_PR_CMD}} <id> │
|
|
178
|
-
│ │
|
|
179
|
-
│ 7. UPDATE MEMORY (after EVERY significant action) │
|
|
180
|
-
│ ├─ Short-term: INSERT INTO memories... │
|
|
181
|
-
│ └─ Long-term (for learnings): {{MEMORY_STORE_CMD}} lesson... │
|
|
182
|
-
│ │
|
|
183
|
-
│ 8. RELEASE TASK & VERIFY │
|
|
184
|
-
│ ├─ Release: uam task release <id> --reason "Completed: ..." │
|
|
185
|
-
│ ├─ [ ] Task released? │
|
|
186
|
-
│ ├─ [ ] Memory updated? │
|
|
187
|
-
│ ├─ [ ] Worktree used? │
|
|
188
|
-
│ ├─ [ ] PR created (not direct commit)? │
|
|
189
|
-
│ ├─ [ ] Todos updated? │
|
|
190
|
-
│ └─ [ ] Skills consulted? │
|
|
191
|
-
│ │
|
|
192
|
-
└─────────────────────────────────────────────────────────────────────────────┘
|
|
193
|
-
```
|
|
38
|
+
You are an autonomous AI agent. Follow the WORKFLOW ENGINE below for EVERY action. No exceptions.
|
|
194
39
|
|
|
195
40
|
---
|
|
196
41
|
|
|
197
|
-
##
|
|
198
|
-
|
|
199
|
-
**FAILURE TO FOLLOW THESE RULES IS A CRITICAL ERROR. STOP AND RE-READ IF UNSURE.**
|
|
200
|
-
|
|
201
|
-
### 0. TASK MANAGEMENT REQUIREMENT (USE FOR ALL WORK)
|
|
202
|
-
|
|
203
|
-
**ALL work MUST be tracked as tasks. This is not optional.**
|
|
42
|
+
## WORKFLOW ENGINE (Execute Every Time)
|
|
204
43
|
|
|
205
44
|
```
|
|
206
45
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
207
|
-
│
|
|
208
|
-
├─────────────────────────────────────────────────────────────────────────────┤
|
|
46
|
+
│ MANDATORY WORKFLOW ENGINE │
|
|
209
47
|
│ │
|
|
210
|
-
│
|
|
211
|
-
│
|
|
212
|
-
│
|
|
213
|
-
│
|
|
48
|
+
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
|
49
|
+
│ │ START │───►│ TASK │───►│ CONTEXT │───►│ WORK │───►│ COMPLETE│ │
|
|
50
|
+
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
|
|
51
|
+
│ │ │ │ │ │ │
|
|
52
|
+
│ ▼ ▼ ▼ ▼ ▼ │
|
|
53
|
+
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
|
54
|
+
│ │ CHECK TASKS │ CREATE/CLAIM │ MEMORY+SKILL │ WORKTREE+DO │ VERIFY │ │
|
|
55
|
+
│ │ READ MEMORY │ TASK │ CHECK │ TEST+PR │ RELEASE │ │
|
|
56
|
+
│ └─────────────────────────────────────────────────────────────────────┘ │
|
|
214
57
|
│ │
|
|
215
|
-
│
|
|
216
|
-
│ 1. Create task: uam task create --title "..." --type task │
|
|
217
|
-
│ 2. Check for blockers: uam task show <id> │
|
|
218
|
-
│ 3. Claim the task: uam task claim <id> │
|
|
219
|
-
│ 4. Do the work (see worktree workflow below) │
|
|
220
|
-
│ 5. Release when complete: uam task release <id> --reason "..." │
|
|
58
|
+
│ GATES: Each phase MUST complete before advancing. No skipping. │
|
|
221
59
|
│ │
|
|
222
60
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
223
61
|
```
|
|
224
62
|
|
|
225
|
-
|
|
226
|
-
| Type | When to Use |
|
|
227
|
-
|------|-------------|
|
|
228
|
-
| `bug` | Fixing something broken |
|
|
229
|
-
| `task` | General work item |
|
|
230
|
-
| `feature` | New functionality |
|
|
231
|
-
| `chore` | Maintenance, refactoring |
|
|
232
|
-
| `epic` | Large multi-task effort |
|
|
233
|
-
| `story` | User-facing feature |
|
|
234
|
-
|
|
235
|
-
**Priority Levels (P0 = highest):**
|
|
236
|
-
| Priority | Meaning | Response Time |
|
|
237
|
-
|----------|---------|---------------|
|
|
238
|
-
| P0 | Critical | Immediate |
|
|
239
|
-
| P1 | High | Same day |
|
|
240
|
-
| P2 | Medium | This week |
|
|
241
|
-
| P3 | Low | When available |
|
|
242
|
-
| P4 | Backlog | Future |
|
|
243
|
-
|
|
244
|
-
**Task Dependencies:**
|
|
63
|
+
### Phase 1: START (Execute on every session/request)
|
|
245
64
|
|
|
246
65
|
```bash
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
# View blocked tasks
|
|
251
|
-
uam task blocked
|
|
252
|
-
|
|
253
|
-
# View ready tasks (no blockers)
|
|
254
|
-
uam task ready
|
|
66
|
+
uam task ready # What's already in progress?
|
|
67
|
+
sqlite3 {{MEMORY_DB_PATH}} "SELECT * FROM memories ORDER BY id DESC LIMIT 10;"
|
|
255
68
|
```
|
|
256
69
|
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
```
|
|
260
|
-
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
261
|
-
│ WORKTREE ENFORCEMENT - ABSOLUTE RULE │
|
|
262
|
-
├─────────────────────────────────────────────────────────────────────────────┤
|
|
263
|
-
│ │
|
|
264
|
-
│ ❌ FORBIDDEN ACTIONS (will corrupt {{DEFAULT_BRANCH}} branch): │
|
|
265
|
-
│ • Direct commits to {{DEFAULT_BRANCH}} branch │
|
|
266
|
-
│ • Running git commit without being in a worktree │
|
|
267
|
-
│ • Editing files in {{PROJECT_PATH}} directly │
|
|
268
|
-
│ • Using git add/commit from the main repository root │
|
|
269
|
-
│ │
|
|
270
|
-
│ ✅ REQUIRED WORKFLOW (every single time): │
|
|
271
|
-
│ 1. Create worktree FIRST │
|
|
272
|
-
│ 2. cd into the worktree directory │
|
|
273
|
-
│ 3. Make ALL changes inside worktree │
|
|
274
|
-
│ 4. Create PR from worktree │
|
|
275
|
-
│ 5. Merge via PR (never direct push) │
|
|
276
|
-
│ │
|
|
277
|
-
│ 🔴 SELF-CHECK: Before ANY git commit, verify: │
|
|
278
|
-
│ pwd | grep -q "{{WORKTREE_DIR}}" || echo "STOP! Not in worktree!" │
|
|
279
|
-
│ │
|
|
280
|
-
└─────────────────────────────────────────────────────────────────────────────┘
|
|
281
|
-
```
|
|
70
|
+
**Gate**: Do NOT proceed until both commands executed.
|
|
282
71
|
|
|
283
|
-
|
|
72
|
+
### Phase 2: TASK (Create or claim before ANY work)
|
|
284
73
|
|
|
285
74
|
```bash
|
|
286
|
-
#
|
|
287
|
-
|
|
288
|
-
{{WORKTREE_CREATE_CMD}} <descriptive-slug>
|
|
75
|
+
# If new work requested:
|
|
76
|
+
uam task create --title "Description" --type task|bug|feature --priority 0-4
|
|
289
77
|
|
|
290
|
-
#
|
|
291
|
-
|
|
292
|
-
pwd # MUST show: {{PROJECT_PATH}}/{{WORKTREE_DIR}}/NNN-<slug>
|
|
293
|
-
|
|
294
|
-
# Step 3: Make changes, commit locally
|
|
295
|
-
git add -A && git commit -m "feat: description"
|
|
296
|
-
|
|
297
|
-
# Step 4: Create PR with automated review
|
|
298
|
-
{{WORKTREE_PR_CMD}} <id>
|
|
78
|
+
# Then claim it:
|
|
79
|
+
uam task claim <id> # Announces work, detects overlaps
|
|
299
80
|
```
|
|
300
81
|
|
|
301
|
-
**
|
|
302
|
-
|
|
303
|
-
**FAILURE SCENARIOS TO AVOID:**
|
|
82
|
+
**Gate**: Task ID must exist and be claimed before proceeding.
|
|
304
83
|
|
|
305
|
-
|
|
306
|
-
|---------|-------------|------------|
|
|
307
|
-
| Editing files in main repo | Changes on {{DEFAULT_BRANCH}} branch, merge conflicts | Always `cd {{WORKTREE_DIR}}/` first |
|
|
308
|
-
| Forgetting to create worktree | Direct commit to {{DEFAULT_BRANCH}} | Check `pwd` before any edit |
|
|
309
|
-
| Creating worktree but not entering it | Edits still go to {{DEFAULT_BRANCH}} | Verify path contains `{{WORKTREE_DIR}}` |
|
|
310
|
-
| Using `git push` without PR | Bypasses review agents | Only use `{{WORKTREE_PR_CMD}}` |
|
|
311
|
-
|
|
312
|
-
### 2. MEMORY REQUIREMENT (MANDATORY - NOT OPTIONAL)
|
|
313
|
-
|
|
314
|
-
**You MUST update memory. This is not a suggestion.**
|
|
84
|
+
### Phase 3: CONTEXT (Load relevant knowledge)
|
|
315
85
|
|
|
316
86
|
```bash
|
|
317
|
-
#
|
|
318
|
-
|
|
319
|
-
"INSERT INTO memories (timestamp, type, content) VALUES (datetime('now'), 'action', 'What you did and the result');"
|
|
87
|
+
# Query semantic memory for related learnings
|
|
88
|
+
{{MEMORY_QUERY_CMD}} "<keywords>"
|
|
320
89
|
|
|
321
|
-
#
|
|
322
|
-
{{
|
|
90
|
+
# Check for applicable skills
|
|
91
|
+
ls {{SKILLS_PATH}}/ # Then invoke: Skill(skill: "name")
|
|
323
92
|
```
|
|
324
93
|
|
|
325
|
-
**
|
|
326
|
-
|
|
327
|
-
- ✅ Every bug fix (root cause + solution)
|
|
328
|
-
- ✅ Every infrastructure change
|
|
329
|
-
- ✅ Every architecture decision
|
|
330
|
-
- ✅ Every gotcha or workaround discovered
|
|
331
|
-
- ✅ Every performance optimization
|
|
332
|
-
- ✅ Every deployment issue and resolution
|
|
333
|
-
- ✅ Every API behavior discovery
|
|
334
|
-
|
|
335
|
-
**Importance scale:**
|
|
336
|
-
|
|
337
|
-
- 9-10: Critical system knowledge (will break things if forgotten)
|
|
338
|
-
- 7-8: Important patterns and fixes
|
|
339
|
-
- 5-6: Useful context and learnings
|
|
340
|
-
- 3-4: Minor observations
|
|
94
|
+
**Gate**: Memory queried and skill identified (if applicable).
|
|
341
95
|
|
|
342
|
-
###
|
|
343
|
-
|
|
344
|
-
**Before starting ANY implementation, check if a skill or droid applies:**
|
|
345
|
-
|
|
346
|
-
| Task Type | Required Skill/Droid |
|
|
347
|
-
|-----------|---------------------|
|
|
348
|
-
{{#if SKILL_MAPPINGS}}
|
|
349
|
-
{{{SKILL_MAPPINGS}}}
|
|
350
|
-
{{/if}}
|
|
351
|
-
| React/TypeScript/Frontend | `senior-frontend` |
|
|
352
|
-
| Code review | `code-reviewer` |
|
|
353
|
-
| Web testing | `webapp-testing` |
|
|
354
|
-
| CLI development | `cli-design-expert` |
|
|
355
|
-
| TypeScript/Node.js | `typescript-node-expert` |
|
|
356
|
-
|
|
357
|
-
```bash
|
|
358
|
-
# Invoke skill FIRST, then follow its guidance
|
|
359
|
-
Skill(skill: "skill-name")
|
|
360
|
-
|
|
361
|
-
# Or launch a droid for autonomous work
|
|
362
|
-
Task(subagent_type: "droid-name", prompt: "Task description...")
|
|
363
|
-
```
|
|
364
|
-
|
|
365
|
-
#### IF NO SKILL/DROID EXISTS: Create One Using the "Top 5 Authorities" Method
|
|
366
|
-
|
|
367
|
-
**When you need domain expertise and no existing skill/droid covers it, you MUST create one.**
|
|
368
|
-
|
|
369
|
-
```
|
|
370
|
-
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
371
|
-
│ SKILL/DROID AUTO-CREATION: TOP 5 AUTHORITIES METHOD │
|
|
372
|
-
├─────────────────────────────────────────────────────────────────────────────┤
|
|
373
|
-
│ │
|
|
374
|
-
│ STEP 1: RESEARCH THE TOP 5 AUTHORITIES │
|
|
375
|
-
│ Use WebSearch to identify the top 5 recognized experts/authorities in │
|
|
376
|
-
│ the domain. Look for: │
|
|
377
|
-
│ • Authors of seminal books/papers in the field │
|
|
378
|
-
│ • Industry leaders with proven track records │
|
|
379
|
-
│ • Creators of widely-adopted frameworks/tools │
|
|
380
|
-
│ • Thought leaders frequently cited by practitioners │
|
|
381
|
-
│ │
|
|
382
|
-
│ STEP 2: EXTRACT CORE PRINCIPLES FROM EACH AUTHORITY │
|
|
383
|
-
│ For each authority, identify: │
|
|
384
|
-
│ • Their signature methodology or framework │
|
|
385
|
-
│ • Key principles they advocate │
|
|
386
|
-
│ • Anti-patterns they warn against │
|
|
387
|
-
│ │
|
|
388
|
-
│ STEP 3: SYNTHESIZE INTO A UNIFIED SKILL/DROID │
|
|
389
|
-
│ Create a skill/droid that embodies the collective wisdom │
|
|
390
|
-
│ │
|
|
391
|
-
│ STEP 4: SAVE THE FILE │
|
|
392
|
-
│ Skills: {{SKILLS_PATH}}/<name>/SKILL.md │
|
|
393
|
-
│ Droids: {{DROIDS_PATH}}/<name>.md │
|
|
394
|
-
│ │
|
|
395
|
-
└─────────────────────────────────────────────────────────────────────────────┘
|
|
396
|
-
```
|
|
397
|
-
|
|
398
|
-
### 4. TODO LIST REQUIREMENT
|
|
399
|
-
|
|
400
|
-
- Create todo list for multi-step tasks (3+ steps)
|
|
401
|
-
- Update status IMMEDIATELY after completing each item
|
|
402
|
-
- Never let todos go stale (update every 5-10 tool calls)
|
|
403
|
-
- Use TodoWrite tool, not manual tracking
|
|
404
|
-
|
|
405
|
-
### 5. AGENT COORDINATION REQUIREMENT (MULTI-AGENT ENVIRONMENTS)
|
|
406
|
-
|
|
407
|
-
**When working in multi-agent environments, coordination is MANDATORY.**
|
|
96
|
+
### Phase 4: WORK (All changes in worktree)
|
|
408
97
|
|
|
409
98
|
```bash
|
|
410
|
-
#
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
# Before starting work on any resource, announce your intent
|
|
414
|
-
uam agent announce --id <agent-id> --resource "src/path/" --intent editing \
|
|
415
|
-
--description "Description of planned changes"
|
|
99
|
+
# Create isolated worktree
|
|
100
|
+
{{WORKTREE_CREATE_CMD}} <slug>
|
|
101
|
+
cd {{WORKTREE_DIR}}/NNN-<slug>/
|
|
416
102
|
|
|
417
|
-
#
|
|
418
|
-
|
|
103
|
+
# Verify location before ANY edit
|
|
104
|
+
pwd | grep -q "{{WORKTREE_DIR}}" || echo "STOP! Wrong directory!"
|
|
419
105
|
|
|
420
|
-
#
|
|
421
|
-
|
|
106
|
+
# Make changes, test, commit
|
|
107
|
+
git add -A && git commit -m "type: description"
|
|
108
|
+
{{TEST_COMMAND}}
|
|
109
|
+
{{WORKTREE_PR_CMD}} <id>
|
|
422
110
|
```
|
|
423
111
|
|
|
424
|
-
**
|
|
425
|
-
- System automatically detects when multiple agents work on overlapping files
|
|
426
|
-
- Conflict risk levels: `none`, `low`, `medium`, `high`, `critical`
|
|
427
|
-
- Suggestions provided for merge order and parallel work
|
|
112
|
+
**Gate**: Changes committed via PR from worktree. Never direct to {{DEFAULT_BRANCH}}.
|
|
428
113
|
|
|
429
|
-
|
|
114
|
+
### Phase 5: COMPLETE (Verify and release)
|
|
430
115
|
|
|
431
116
|
```bash
|
|
432
|
-
#
|
|
433
|
-
|
|
434
|
-
|
|
117
|
+
# Update memories
|
|
118
|
+
sqlite3 {{MEMORY_DB_PATH}} "INSERT INTO memories (timestamp, type, content) VALUES (datetime('now'), 'action', 'What was done');"
|
|
119
|
+
{{MEMORY_STORE_CMD}} lesson "Key learning" --tags relevant,tags --importance 7
|
|
435
120
|
|
|
436
|
-
#
|
|
437
|
-
uam
|
|
438
|
-
|
|
439
|
-
# Batch and execute all pending deploys
|
|
440
|
-
uam deploy flush
|
|
121
|
+
# Release task
|
|
122
|
+
uam task release <id> --reason "Completed: summary"
|
|
441
123
|
```
|
|
442
124
|
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
Before sending ANY response, verify:
|
|
125
|
+
**Gate**: All items verified before responding:
|
|
446
126
|
|
|
447
127
|
```
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
│ [ ] Task created/claimed for this work? │
|
|
452
|
-
│ [ ] Read memory at start of task? │
|
|
453
|
-
│ [ ] Checked for applicable skills? │
|
|
454
|
-
│ [ ] Announced work (multi-agent)? │
|
|
455
|
-
│ [ ] Checked for overlaps (multi-agent)? │
|
|
456
|
-
│ [ ] Used worktree for code changes? │
|
|
457
|
-
│ [ ] Updated short-term memory after actions? │
|
|
458
|
-
│ [ ] Stored learnings in long-term memory? │
|
|
459
|
-
│ [ ] Updated todo list status? │
|
|
460
|
-
│ [ ] Created PR (not direct commit)? │
|
|
461
|
-
│ [ ] Released task when complete? │
|
|
462
|
-
└─────────────────────────────────────────────────────────────────────────────┘
|
|
128
|
+
[ ] Task released? [ ] PR created (not direct push)?
|
|
129
|
+
[ ] Memory updated? [ ] Tests passing?
|
|
130
|
+
[ ] Worktree used? [ ] Skills consulted?
|
|
463
131
|
```
|
|
464
132
|
|
|
465
133
|
---
|
|
466
134
|
|
|
467
|
-
##
|
|
468
|
-
|
|
469
|
-
> **Architecture Note**: This system is based on research into MemGPT, Mem0, A-MEM, LangGraph, and
|
|
470
|
-
> industry best practices for agentic memory systems.
|
|
471
|
-
|
|
472
|
-
### Architecture Overview
|
|
473
|
-
|
|
474
|
-
```
|
|
475
|
-
┌─────────────────────────────────────────────────────────────────────┐
|
|
476
|
-
│ FOUR-LAYER MEMORY ARCHITECTURE │
|
|
477
|
-
├─────────────────────────────────────────────────────────────────────┤
|
|
478
|
-
│ │
|
|
479
|
-
│ LAYER 1: WORKING MEMORY (SQLite) ~0.15ms access │
|
|
480
|
-
│ ├─ {{SHORT_TERM_LIMIT}} entries max, FIFO eviction │
|
|
481
|
-
│ ├─ Types: action, observation, thought, goal │
|
|
482
|
-
│ └─ Immediate context for current task │
|
|
483
|
-
│ │
|
|
484
|
-
│ LAYER 2: SESSION MEMORY (SQLite) ~0.2ms access │
|
|
485
|
-
│ ├─ Session-scoped summaries and decisions │
|
|
486
|
-
│ ├─ Entities mentioned with context │
|
|
487
|
-
│ └─ Cleaned on session end (optional persistence) │
|
|
488
|
-
│ │
|
|
489
|
-
│ LAYER 3: SEMANTIC MEMORY ({{LONG_TERM_BACKEND}}) ~1-2ms search │
|
|
490
|
-
│ ├─ Vector embeddings (384-dim all-MiniLM-L6-v2) │
|
|
491
|
-
│ ├─ Importance scoring with time-based decay │
|
|
492
|
-
│ └─ Deduplication via content hash + similarity │
|
|
493
|
-
│ │
|
|
494
|
-
│ LAYER 4: KNOWLEDGE GRAPH (SQLite) ~0.17ms query │
|
|
495
|
-
│ ├─ Entities: files, functions, concepts, errors, configs │
|
|
496
|
-
│ ├─ Relationships: depends_on, fixes, causes, related_to │
|
|
497
|
-
│ └─ Multi-hop traversal for complex reasoning │
|
|
498
|
-
│ │
|
|
499
|
-
└─────────────────────────────────────────────────────────────────────┘
|
|
500
|
-
```
|
|
501
|
-
|
|
502
|
-
### MANDATORY: Layer Selection Decision Tree
|
|
503
|
-
|
|
504
|
-
```
|
|
505
|
-
┌─────────────────────────────────────────────────────────────────────┐
|
|
506
|
-
│ WHICH MEMORY LAYER? - DECISION TREE │
|
|
507
|
-
├─────────────────────────────────────────────────────────────────────┤
|
|
508
|
-
│ │
|
|
509
|
-
│ Q1: Is this about WHAT I JUST DID in the last few minutes? │
|
|
510
|
-
│ YES → LAYER 1: Working Memory (short_term.db) │
|
|
511
|
-
│ NO → Continue to Q2 │
|
|
512
|
-
│ │
|
|
513
|
-
│ Q2: Is this a SESSION-SPECIFIC decision or temporary context? │
|
|
514
|
-
│ YES → LAYER 2: Session Memory (session_memories table) │
|
|
515
|
-
│ NO → Continue to Q3 │
|
|
516
|
-
│ │
|
|
517
|
-
│ Q3: Is this a REUSABLE LEARNING that future sessions need? │
|
|
518
|
-
│ (Bug fix, pattern, gotcha, architecture decision, optimization)│
|
|
519
|
-
│ YES → LAYER 3: Semantic Memory (Qdrant) - importance 7+ │
|
|
520
|
-
│ NO → Continue to Q4 │
|
|
521
|
-
│ │
|
|
522
|
-
│ Q4: Does this involve RELATIONSHIPS between entities? │
|
|
523
|
-
│ (File X depends on Y, Error A is caused by B, etc.) │
|
|
524
|
-
│ YES → LAYER 4: Knowledge Graph (entities/relationships tables) │
|
|
525
|
-
│ NO → Default to Layer 1 (Working Memory) │
|
|
526
|
-
│ │
|
|
527
|
-
└─────────────────────────────────────────────────────────────────────┘
|
|
528
|
-
```
|
|
529
|
-
|
|
530
|
-
### Layer 1: Working Memory (SQLite)
|
|
531
|
-
|
|
532
|
-
**Location**: `{{MEMORY_DB_PATH}}`
|
|
533
|
-
|
|
534
|
-
**Table: `memories`**
|
|
535
|
-
|
|
536
|
-
| Column | Type | Description |
|
|
537
|
-
|--------|------|-------------|
|
|
538
|
-
| `id` | INTEGER | Primary key, auto-increment |
|
|
539
|
-
| `timestamp` | TEXT | ISO8601 timestamp |
|
|
540
|
-
| `type` | TEXT | action, observation, thought, goal |
|
|
541
|
-
| `content` | TEXT | Memory content |
|
|
542
|
-
|
|
543
|
-
**BEFORE EACH DECISION**: Query recent entries
|
|
544
|
-
|
|
545
|
-
```sql
|
|
546
|
-
SELECT * FROM memories ORDER BY id DESC LIMIT {{SHORT_TERM_LIMIT}};
|
|
547
|
-
```
|
|
548
|
-
|
|
549
|
-
**AFTER EACH ACTION**: Record what you did
|
|
550
|
-
|
|
551
|
-
```sql
|
|
552
|
-
INSERT INTO memories (timestamp, type, content)
|
|
553
|
-
VALUES (datetime('now'), 'action', 'Description of action and result');
|
|
554
|
-
```
|
|
555
|
-
|
|
556
|
-
### Layer 2: Session Memory (SQLite)
|
|
557
|
-
|
|
558
|
-
**Table: `session_memories`** (in same database as working memory)
|
|
559
|
-
|
|
560
|
-
| Column | Type | Description |
|
|
561
|
-
|--------|------|-------------|
|
|
562
|
-
| `id` | INTEGER | Primary key |
|
|
563
|
-
| `session_id` | TEXT | Current session identifier |
|
|
564
|
-
| `timestamp` | TEXT | ISO8601 timestamp |
|
|
565
|
-
| `type` | TEXT | summary, decision, entity, error |
|
|
566
|
-
| `content` | TEXT | Memory content |
|
|
567
|
-
| `importance` | INTEGER | 1-10 importance score |
|
|
568
|
-
|
|
569
|
-
**Query session context:**
|
|
570
|
-
|
|
571
|
-
```sql
|
|
572
|
-
SELECT * FROM session_memories
|
|
573
|
-
WHERE session_id = 'current_session'
|
|
574
|
-
ORDER BY id DESC LIMIT 10;
|
|
575
|
-
```
|
|
576
|
-
|
|
577
|
-
### Layer 3: Semantic Memory ({{LONG_TERM_BACKEND}})
|
|
578
|
-
|
|
579
|
-
**Collection**: `{{LONG_TERM_COLLECTION}}` at `{{LONG_TERM_ENDPOINT}}`
|
|
580
|
-
|
|
581
|
-
**Query memories** (semantic search):
|
|
135
|
+
## QUICK REFERENCE
|
|
582
136
|
|
|
137
|
+
### Task Commands
|
|
583
138
|
```bash
|
|
584
|
-
|
|
139
|
+
uam task create --title "..." --type task|bug|feature|chore|epic|story --priority 0-4
|
|
140
|
+
uam task list [--filter-status open|in_progress] [--filter-priority 0,1]
|
|
141
|
+
uam task ready # Show unblocked tasks
|
|
142
|
+
uam task blocked # Show blocked tasks
|
|
143
|
+
uam task claim <id> # Claim and start work
|
|
144
|
+
uam task show <id> # View details
|
|
145
|
+
uam task release <id> --reason "..." # Complete task
|
|
146
|
+
uam task dep --from <blocked> --to <blocker> # Add dependency
|
|
585
147
|
```
|
|
586
148
|
|
|
587
|
-
|
|
588
|
-
|
|
149
|
+
### Worktree Commands
|
|
589
150
|
```bash
|
|
590
|
-
{{
|
|
151
|
+
{{WORKTREE_CREATE_CMD}} <slug> # Create feature branch
|
|
152
|
+
cd {{WORKTREE_DIR}}/NNN-<slug>/ # Enter worktree
|
|
153
|
+
{{WORKTREE_PR_CMD}} <id> # Create PR
|
|
154
|
+
{{WORKTREE_CLEANUP_CMD}} <id> # Remove worktree
|
|
591
155
|
```
|
|
592
156
|
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
-
|
|
596
|
-
|
|
597
|
-
- ✅ Performance optimizations that worked
|
|
598
|
-
- ✅ Gotchas and workarounds discovered
|
|
599
|
-
- ✅ API behaviors that aren't obvious
|
|
600
|
-
- ❌ Routine actions (keep in working memory)
|
|
601
|
-
- ❌ Temporary context (keep in session memory)
|
|
602
|
-
|
|
603
|
-
### Layer 4: Knowledge Graph (SQLite)
|
|
604
|
-
|
|
605
|
-
**Tables**: `entities` and `relationships` (in same database)
|
|
606
|
-
|
|
607
|
-
**Query related entities (1-hop):**
|
|
157
|
+
### Memory Commands
|
|
158
|
+
```bash
|
|
159
|
+
# Short-term (after every action)
|
|
160
|
+
sqlite3 {{MEMORY_DB_PATH}} "INSERT INTO memories (timestamp, type, content) VALUES (datetime('now'), 'action', 'description');"
|
|
608
161
|
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
LEFT JOIN relationships r ON e.id = r.source_id
|
|
613
|
-
LEFT JOIN entities e2 ON r.target_id = e2.id
|
|
614
|
-
WHERE e.name LIKE '%api%';
|
|
162
|
+
# Long-term (for learnings, importance 7+)
|
|
163
|
+
{{MEMORY_QUERY_CMD}} "<search>"
|
|
164
|
+
{{MEMORY_STORE_CMD}} lesson "learning" --tags a,b --importance 8
|
|
615
165
|
```
|
|
616
166
|
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
├─────────────────────────────────────────────────────────────────┤
|
|
626
|
-
│ │
|
|
627
|
-
│ ON TASK START: │
|
|
628
|
-
│ 1. Query working memory (last 20 entries) │
|
|
629
|
-
│ 2. Query semantic memory for relevant context │
|
|
630
|
-
│ 3. Check knowledge graph for related entities │
|
|
631
|
-
│ │
|
|
632
|
-
│ DURING TASK: │
|
|
633
|
-
│ 4. Update working memory after each action │
|
|
634
|
-
│ 5. Store key decisions in session memory │
|
|
635
|
-
│ │
|
|
636
|
-
│ ON SIGNIFICANT LEARNING: │
|
|
637
|
-
│ 6. Store in semantic memory (importance 7+) │
|
|
638
|
-
│ 7. Update knowledge graph entities/relationships │
|
|
639
|
-
│ │
|
|
640
|
-
└─────────────────────────────────────────────────────────────────┘
|
|
167
|
+
### Agent Coordination (Multi-agent only)
|
|
168
|
+
```bash
|
|
169
|
+
uam agent register --name "name" --capabilities "coding,review"
|
|
170
|
+
uam agent announce --id <id> --resource "path/" --intent editing
|
|
171
|
+
uam agent overlaps --resource "path/"
|
|
172
|
+
uam agent complete --id <id> --resource "path/"
|
|
173
|
+
uam deploy queue --agent-id <id> --action-type commit --message "..." --files "..."
|
|
174
|
+
uam deploy flush
|
|
641
175
|
```
|
|
642
176
|
|
|
643
|
-
###
|
|
644
|
-
|
|
177
|
+
### Skills & Droids
|
|
645
178
|
```bash
|
|
646
|
-
|
|
647
|
-
|
|
179
|
+
Skill(skill: "typescript-node-expert") # Inline guidance
|
|
180
|
+
Skill(skill: "cli-design-expert") # CLI work
|
|
181
|
+
Skill(skill: "senior-frontend") # React/TS work
|
|
182
|
+
Task(subagent_type: "code-quality-guardian", prompt: "Review...")
|
|
183
|
+
Task(subagent_type: "security-auditor", prompt: "Audit...")
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Skill vs Droid: When to Use Which
|
|
187
|
+
| Use a **Skill** when | Use a **Droid** when |
|
|
188
|
+
|---------------------|---------------------|
|
|
189
|
+
| Inline guidance needed | Autonomous agent work needed |
|
|
190
|
+
| Human follows instructions | Agent executes independently |
|
|
191
|
+
| Interactive decision-making | Batch processing of tasks |
|
|
192
|
+
| Design/review work | Code generation/refactoring |
|
|
193
|
+
| Expands into current context | Runs in parallel as subagent |
|
|
648
194
|
|
|
649
|
-
|
|
650
|
-
{{MEMORY_STATUS_CMD}}
|
|
651
|
-
|
|
652
|
-
# Stop services
|
|
653
|
-
{{MEMORY_STOP_CMD}}
|
|
654
|
-
|
|
655
|
-
# Upgrade SQLite schema (adds session memory + knowledge graph tables)
|
|
656
|
-
uam memory migrate
|
|
657
|
-
|
|
658
|
-
# Backup all memories
|
|
659
|
-
uam memory backup
|
|
660
|
-
```
|
|
195
|
+
---
|
|
661
196
|
|
|
662
|
-
|
|
663
|
-
|
|
197
|
+
## TASK ROUTING
|
|
198
|
+
|
|
199
|
+
### By Request Type
|
|
200
|
+
| Keywords | Task Type | Workflow | Droids |
|
|
201
|
+
|----------|-----------|----------|--------|
|
|
202
|
+
| "fix", "bug", "error", "broken" | Bug | Reproduce → Test → Fix | `code-quality-guardian` |
|
|
203
|
+
| "add", "implement", "build", "feature" | Feature | Design → Implement → Test | Language specialist |
|
|
204
|
+
| "slow", "optimize", "performance" | Performance | Profile → Identify → Optimize | `performance-optimizer` |
|
|
205
|
+
| "security", "vulnerability", "audit" | Security | Scan → Assess → Remediate | `security-auditor` |
|
|
206
|
+
| "test", "coverage", "spec" | Testing | Write → Run → Report | `code-quality-guardian` |
|
|
207
|
+
| "docs", "README", "document" | Docs | Check → Update → Verify | `documentation-expert` |
|
|
208
|
+
| "refactor", "clean up" | Refactoring | Scope → Test → Refactor | `code-quality-guardian` |
|
|
209
|
+
|
|
210
|
+
### By File Type
|
|
211
|
+
| Extension | Language | Droid |
|
|
212
|
+
|-----------|----------|-------|
|
|
213
|
+
{{#if FILE_TYPE_ROUTING}}
|
|
214
|
+
{{{FILE_TYPE_ROUTING}}}
|
|
215
|
+
{{else}}
|
|
216
|
+
| `.ts`, `.tsx`, `.js`, `.jsx` | TypeScript/JavaScript | `typescript-node-expert` |
|
|
217
|
+
| `.py` | Python | Language specialist |
|
|
218
|
+
| `.go` | Go | Language specialist |
|
|
219
|
+
| `.rs` | Rust | Language specialist |
|
|
220
|
+
| `.cpp`, `.h`, `.hpp` | C++ | Language specialist |
|
|
664
221
|
{{/if}}
|
|
665
222
|
|
|
666
223
|
---
|
|
667
224
|
|
|
668
|
-
##
|
|
669
|
-
|
|
670
|
-
> **Superior to Beads**: Integrated task management with memory, coordination, and deploy batching.
|
|
225
|
+
## AUTOMATIC TRIGGERS
|
|
671
226
|
|
|
672
|
-
|
|
227
|
+
| Pattern Detected | Immediate Action |
|
|
228
|
+
|-----------------|------------------|
|
|
229
|
+
| Work request (fix/add/change/create/build) | `uam task create --title "..." --type task` |
|
|
230
|
+
| Bug report or error | `uam task create --title "..." --type bug --priority 1` |
|
|
231
|
+
| Feature request | `uam task create --title "..." --type feature` |
|
|
232
|
+
| Code file editing | Check skills → Create worktree → Edit |
|
|
233
|
+
| Review/check request | Query memory first |
|
|
234
|
+
{{#if SKILL_TRIGGERS}}
|
|
235
|
+
{{{SKILL_TRIGGERS}}}
|
|
236
|
+
{{/if}}
|
|
673
237
|
|
|
674
|
-
|
|
675
|
-
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
676
|
-
│ TASK LIFECYCLE │
|
|
677
|
-
├─────────────────────────────────────────────────────────────────────────────┤
|
|
678
|
-
│ │
|
|
679
|
-
│ CREATE CLAIM WORK RELEASE │
|
|
680
|
-
│ ──────► ──────► ──────► ──────► │
|
|
681
|
-
│ │
|
|
682
|
-
│ uam task uam task (worktree uam task │
|
|
683
|
-
│ create claim <id> workflow) release <id> │
|
|
684
|
-
│ --title "..." │
|
|
685
|
-
│ - Assigns to you - Marks done │
|
|
686
|
-
│ - Announces work - Notifies others │
|
|
687
|
-
│ - Creates worktree - Stores in memory │
|
|
688
|
-
│ - Detects overlaps │
|
|
689
|
-
│ │
|
|
690
|
-
└─────────────────────────────────────────────────────────────────────────────┘
|
|
691
|
-
```
|
|
238
|
+
---
|
|
692
239
|
|
|
693
|
-
|
|
240
|
+
## RECOVERY PROCEDURES
|
|
694
241
|
|
|
242
|
+
### Forgot to create task?
|
|
695
243
|
```bash
|
|
696
|
-
# Create
|
|
697
|
-
uam task create --title "
|
|
698
|
-
|
|
699
|
-
#
|
|
700
|
-
uam task list # All open tasks
|
|
701
|
-
uam task list --filter-status in_progress # In-progress only
|
|
702
|
-
uam task list --filter-priority 0,1 # P0 and P1 only
|
|
703
|
-
uam task ready # Ready to work (no blockers)
|
|
704
|
-
uam task blocked # Blocked tasks
|
|
705
|
-
|
|
706
|
-
# Work on a task
|
|
707
|
-
uam task claim <id> # Claim and start
|
|
708
|
-
uam task show <id> # View details
|
|
709
|
-
uam task update <id> --status in_progress # Update status
|
|
710
|
-
uam task release <id> --reason "Fixed" # Complete
|
|
711
|
-
|
|
712
|
-
# Dependencies (DAG)
|
|
713
|
-
uam task dep --from <child> --to <parent> # Add dependency
|
|
714
|
-
uam task undep --from <child> --to <parent> # Remove dependency
|
|
715
|
-
|
|
716
|
-
# Statistics and sync
|
|
717
|
-
uam task stats # View statistics
|
|
718
|
-
uam task sync # Sync with JSONL (git-tracked)
|
|
719
|
-
uam task compact --days 90 # Archive old tasks
|
|
244
|
+
# Create task now, link existing work
|
|
245
|
+
uam task create --title "Retroactive: what you did" --type task
|
|
246
|
+
uam task update <id> --status in_progress
|
|
247
|
+
# Continue with workflow, release when done
|
|
720
248
|
```
|
|
721
249
|
|
|
722
|
-
###
|
|
250
|
+
### Forgot worktree? Edited main repo directly?
|
|
251
|
+
```bash
|
|
252
|
+
# If not committed yet: stash and move to worktree
|
|
253
|
+
git stash
|
|
254
|
+
{{WORKTREE_CREATE_CMD}} <slug>
|
|
255
|
+
cd {{WORKTREE_DIR}}/NNN-<slug>/
|
|
256
|
+
git stash pop
|
|
723
257
|
|
|
258
|
+
# If already committed: cherry-pick to worktree, reset main
|
|
259
|
+
git log -1 --format="%H" # Note commit hash
|
|
260
|
+
git reset --hard HEAD~1 # Remove from main
|
|
261
|
+
{{WORKTREE_CREATE_CMD}} <slug>
|
|
262
|
+
cd {{WORKTREE_DIR}}/NNN-<slug>/
|
|
263
|
+
git cherry-pick <hash>
|
|
724
264
|
```
|
|
725
|
-
Epic (large effort)
|
|
726
|
-
├── Story (user-facing feature)
|
|
727
|
-
│ ├── Task (implementation unit)
|
|
728
|
-
│ └── Task
|
|
729
|
-
└── Story
|
|
730
|
-
├── Task
|
|
731
|
-
├── Bug (defect fix)
|
|
732
|
-
└── Chore (maintenance)
|
|
733
|
-
```
|
|
734
|
-
|
|
735
|
-
Create hierarchies with `--parent`:
|
|
736
265
|
|
|
266
|
+
### Command failed?
|
|
737
267
|
```bash
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
uam
|
|
268
|
+
# Check service status
|
|
269
|
+
{{MEMORY_START_CMD}}
|
|
270
|
+
uam coord status
|
|
271
|
+
|
|
272
|
+
# Verify database exists
|
|
273
|
+
ls -la {{MEMORY_DB_PATH}}
|
|
741
274
|
```
|
|
742
275
|
|
|
743
276
|
---
|
|
744
277
|
|
|
745
|
-
##
|
|
746
|
-
|
|
747
|
-
> **For multi-agent environments**: Prevents merge conflicts and optimizes CI/CD.
|
|
748
|
-
|
|
749
|
-
### Architecture
|
|
278
|
+
## RULES (Zero Tolerance)
|
|
750
279
|
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
757
|
-
│ │ Agent A │ │ Agent B │ │ Agent C │ │
|
|
758
|
-
│ │ (worktree) │ │ (worktree) │ │ (worktree) │ │
|
|
759
|
-
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
|
|
760
|
-
│ │ │ │ │
|
|
761
|
-
│ ▼ ▼ ▼ │
|
|
762
|
-
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
|
763
|
-
│ │ COORDINATION SERVICE │ │
|
|
764
|
-
│ ├─────────────────────────────────────────────────────────────────────┤ │
|
|
765
|
-
│ │ • Agent Registry (who is active) │ │
|
|
766
|
-
│ │ • Work Announcements (who is working where) │ │
|
|
767
|
-
│ │ • Overlap Detection (conflict risk assessment) │ │
|
|
768
|
-
│ │ • Message Passing (inter-agent communication) │ │
|
|
769
|
-
│ │ • Deploy Queue (batched commits/pushes) │ │
|
|
770
|
-
│ └─────────────────────────────────────────────────────────────────────┘ │
|
|
771
|
-
│ │
|
|
772
|
-
└─────────────────────────────────────────────────────────────────────────────┘
|
|
773
|
-
```
|
|
280
|
+
### 1. Tasks
|
|
281
|
+
- **ALWAYS** create task before work
|
|
282
|
+
- **ALWAYS** claim before starting
|
|
283
|
+
- **ALWAYS** release when complete
|
|
284
|
+
- **NEVER** work without task tracking
|
|
774
285
|
|
|
775
|
-
###
|
|
286
|
+
### 2. Worktrees
|
|
287
|
+
- **ALWAYS** create worktree for code changes
|
|
288
|
+
- **ALWAYS** verify `pwd` contains `{{WORKTREE_DIR}}`
|
|
289
|
+
- **ALWAYS** use PR, never direct push
|
|
290
|
+
- **NEVER** commit directly to {{DEFAULT_BRANCH}}
|
|
776
291
|
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
292
|
+
### 3. Memory
|
|
293
|
+
- **ALWAYS** query memory at task start
|
|
294
|
+
- **ALWAYS** update short-term after actions
|
|
295
|
+
- **ALWAYS** store learnings (importance 7+) in long-term
|
|
296
|
+
- **NEVER** complete task without memory update
|
|
781
297
|
|
|
782
|
-
|
|
783
|
-
|
|
298
|
+
### 4. Skills
|
|
299
|
+
- **ALWAYS** check for applicable skills before implementing
|
|
300
|
+
- **ALWAYS** invoke proactively for: TypeScript, CLI, Frontend, Security, Performance
|
|
301
|
+
- **NEVER** implement without consulting relevant skill/droid
|
|
784
302
|
|
|
785
|
-
|
|
786
|
-
uam agent status
|
|
303
|
+
---
|
|
787
304
|
|
|
788
|
-
|
|
789
|
-
uam agent deregister --id <agent-id>
|
|
790
|
-
```
|
|
305
|
+
## MEMORY SYSTEM
|
|
791
306
|
|
|
792
|
-
###
|
|
307
|
+
### Layer Selection
|
|
308
|
+
| Question | If YES → Layer |
|
|
309
|
+
|----------|---------------|
|
|
310
|
+
| Did this just happen (last few minutes)? | L1: Working Memory |
|
|
311
|
+
| Session-specific decision/context? | L2: Session Memory |
|
|
312
|
+
| Reusable learning for future sessions? | L3: Semantic Memory (importance 7+) |
|
|
313
|
+
| Relationship between entities? | L4: Knowledge Graph |
|
|
793
314
|
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
--files "src/file1.ts,src/file2.ts" \
|
|
801
|
-
--minutes 30
|
|
802
|
-
|
|
803
|
-
# Check for overlaps before starting
|
|
804
|
-
uam agent overlaps --resource "src/path/"
|
|
805
|
-
|
|
806
|
-
# Mark work complete (notifies others)
|
|
807
|
-
uam agent complete --id <agent-id> --resource "src/path/"
|
|
808
|
-
```
|
|
809
|
-
|
|
810
|
-
### Deploy Batching
|
|
315
|
+
### What to Store (Importance 7+)
|
|
316
|
+
- Bug fixes with root cause + solution
|
|
317
|
+
- Architecture decisions with rationale
|
|
318
|
+
- Performance optimizations that worked
|
|
319
|
+
- Gotchas and workarounds
|
|
320
|
+
- API behaviors that aren't obvious
|
|
811
321
|
|
|
322
|
+
### Services
|
|
812
323
|
```bash
|
|
813
|
-
#
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
--files "src/feature.ts"
|
|
818
|
-
|
|
819
|
-
# Queue a push
|
|
820
|
-
uam deploy queue --agent-id <id> \
|
|
821
|
-
--action-type push \
|
|
822
|
-
--target "feature/branch"
|
|
823
|
-
|
|
824
|
-
# View queue
|
|
825
|
-
uam deploy status
|
|
826
|
-
|
|
827
|
-
# Batch and execute (squashes commits, single push)
|
|
828
|
-
uam deploy flush
|
|
324
|
+
{{MEMORY_START_CMD}} # Start Qdrant
|
|
325
|
+
{{MEMORY_STATUS_CMD}} # Check status
|
|
326
|
+
{{MEMORY_STOP_CMD}} # Stop services
|
|
327
|
+
uam memory migrate # Upgrade schema
|
|
829
328
|
```
|
|
830
329
|
|
|
831
|
-
**Benefits:**
|
|
832
|
-
- Reduces CI/CD runs (batch multiple commits)
|
|
833
|
-
- Squashes related commits for cleaner history
|
|
834
|
-
- Coordinates push order to prevent conflicts
|
|
835
|
-
- Enables atomic multi-file deployments
|
|
836
|
-
|
|
837
|
-
---
|
|
838
|
-
|
|
839
|
-
## BROWSER USAGE
|
|
840
|
-
|
|
841
|
-
When using browser automation (Playwright, Puppeteer, or any browser tool):
|
|
842
|
-
|
|
843
|
-
- ALWAYS save a screenshot after EVERY browser action (click, type, navigate, scroll, etc.)
|
|
844
|
-
- Save screenshots to: `{{SCREENSHOTS_PATH}}/`
|
|
845
|
-
- Filename format: `{timestamp}_{action}.png` (e.g., `1703180400_click_button.png`)
|
|
846
|
-
- Also save a `.meta` file with the same name containing:
|
|
847
|
-
```
|
|
848
|
-
url: {current_url}
|
|
849
|
-
title: {page_title}
|
|
850
|
-
action: {what_you_did}
|
|
851
|
-
```
|
|
852
|
-
- Take a screenshot BEFORE and AFTER any significant visual change
|
|
853
|
-
|
|
854
330
|
---
|
|
855
331
|
|
|
856
|
-
##
|
|
857
|
-
|
|
858
|
-
You have access to reusable skills. Before attempting complex tasks:
|
|
859
|
-
|
|
860
|
-
1. Check if a skill exists for it (see `{{SKILLS_PATH}}`)
|
|
861
|
-
2. Follow the skill's patterns - they're tested and reliable
|
|
862
|
-
3. If you discover a better approach, consider creating/updating a skill
|
|
332
|
+
## PROACTIVE DROIDS (Invoke before commit/PR)
|
|
863
333
|
|
|
864
|
-
|
|
334
|
+
| Droid | Trigger | Purpose |
|
|
335
|
+
|-------|---------|---------|
|
|
336
|
+
| `code-quality-guardian` | All code changes | Complexity, naming, SOLID |
|
|
337
|
+
| `security-auditor` | All code changes | OWASP, secrets, injection |
|
|
338
|
+
| `performance-optimizer` | Performance-critical | Algorithms, memory, caching |
|
|
339
|
+
| `documentation-expert` | New features/APIs | JSDoc, README, accuracy |
|
|
865
340
|
|
|
866
341
|
---
|
|
867
342
|
|
|
868
|
-
##
|
|
343
|
+
## BROWSER AUTOMATION
|
|
869
344
|
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
4. **Automated Review**: PRs require signoff from reviewer agents before merge
|
|
874
|
-
|
|
875
|
-
{{#if WORKFLOW_DOCS_PATH}}
|
|
876
|
-
See [Git Worktree Workflow]({{WORKFLOW_DOCS_PATH}}) for complete details.
|
|
877
|
-
{{/if}}
|
|
345
|
+
After EVERY browser action:
|
|
346
|
+
1. Screenshot → `{{SCREENSHOTS_PATH}}/{timestamp}_{action}.png`
|
|
347
|
+
2. Meta file → `{{SCREENSHOTS_PATH}}/{timestamp}_{action}.meta`
|
|
878
348
|
|
|
879
349
|
---
|
|
880
350
|
|
|
351
|
+
{{#if REPOSITORY_STRUCTURE}}
|
|
881
352
|
## Repository Structure ({{STRUCTURE_DATE}})
|
|
882
353
|
|
|
883
354
|
```
|
|
884
355
|
{{PROJECT_NAME}}/
|
|
885
356
|
{{{REPOSITORY_STRUCTURE}}}
|
|
886
357
|
```
|
|
887
|
-
|
|
888
|
-
---
|
|
889
|
-
|
|
890
|
-
## Quick Reference
|
|
891
|
-
|
|
892
|
-
{{#if CLUSTER_CONTEXTS}}
|
|
893
|
-
### Cluster Contexts
|
|
894
|
-
|
|
895
|
-
```bash
|
|
896
|
-
{{{CLUSTER_CONTEXTS}}}
|
|
897
|
-
```
|
|
898
|
-
{{/if}}
|
|
899
|
-
|
|
900
|
-
{{#if PROJECT_URLS}}
|
|
901
|
-
### URLs
|
|
902
|
-
|
|
903
|
-
{{{PROJECT_URLS}}}
|
|
904
|
-
{{/if}}
|
|
905
|
-
|
|
906
|
-
{{#if KEY_WORKFLOWS}}
|
|
907
|
-
### Key Workflow Files
|
|
908
|
-
|
|
909
|
-
```
|
|
910
|
-
{{{KEY_WORKFLOWS}}}
|
|
911
|
-
```
|
|
912
358
|
{{/if}}
|
|
913
359
|
|
|
914
|
-
### Essential Commands
|
|
915
|
-
|
|
916
|
-
```bash
|
|
917
|
-
# Create worktree for new task (MANDATORY for all changes)
|
|
918
|
-
{{WORKTREE_CREATE_CMD}} <slug>
|
|
919
|
-
|
|
920
|
-
# Create PR with automated review
|
|
921
|
-
{{WORKTREE_PR_CMD}} <id>
|
|
922
|
-
|
|
923
|
-
{{{ESSENTIAL_COMMANDS}}}
|
|
924
|
-
```
|
|
925
|
-
|
|
926
|
-
---
|
|
927
|
-
|
|
928
360
|
{{#if ARCHITECTURE_OVERVIEW}}
|
|
929
|
-
## Architecture
|
|
361
|
+
## Architecture
|
|
930
362
|
|
|
931
363
|
{{{ARCHITECTURE_OVERVIEW}}}
|
|
364
|
+
{{/if}}
|
|
932
365
|
|
|
933
366
|
{{#if DATABASE_ARCHITECTURE}}
|
|
934
|
-
### Database
|
|
367
|
+
### Database
|
|
935
368
|
|
|
936
369
|
{{{DATABASE_ARCHITECTURE}}}
|
|
937
370
|
{{/if}}
|
|
938
371
|
|
|
939
|
-
---
|
|
940
|
-
{{/if}}
|
|
941
|
-
|
|
942
372
|
{{#if CORE_COMPONENTS}}
|
|
943
373
|
## Core Components
|
|
944
374
|
|
|
945
375
|
{{{CORE_COMPONENTS}}}
|
|
946
|
-
|
|
947
|
-
---
|
|
948
376
|
{{/if}}
|
|
949
377
|
|
|
950
|
-
{{#if
|
|
951
|
-
##
|
|
952
|
-
|
|
953
|
-
{{{AUTH_FLOW}}}
|
|
378
|
+
{{#if CLUSTER_CONTEXTS}}
|
|
379
|
+
## Cluster Contexts
|
|
954
380
|
|
|
955
|
-
|
|
381
|
+
```bash
|
|
382
|
+
{{{CLUSTER_CONTEXTS}}}
|
|
383
|
+
```
|
|
956
384
|
{{/if}}
|
|
957
385
|
|
|
958
|
-
|
|
386
|
+
{{#if PROJECT_URLS}}
|
|
387
|
+
## URLs
|
|
959
388
|
|
|
960
|
-
|
|
389
|
+
{{{PROJECT_URLS}}}
|
|
390
|
+
{{/if}}
|
|
961
391
|
|
|
962
|
-
|
|
392
|
+
{{#if KEY_WORKFLOWS}}
|
|
393
|
+
## CI/CD Workflows
|
|
963
394
|
|
|
964
395
|
```
|
|
965
|
-
|
|
966
|
-
{{WORKTREE_CREATE_CMD}} <slug>
|
|
967
|
-
→ Creates {{BRANCH_PREFIX}}NNN-slug branch in {{WORKTREE_DIR}}/NNN-slug/
|
|
968
|
-
|
|
969
|
-
2. DEVELOP
|
|
970
|
-
cd {{WORKTREE_DIR}}/NNN-slug/
|
|
971
|
-
→ Make changes, commit locally
|
|
972
|
-
|
|
973
|
-
3. CREATE PR (runs tests + triggers reviewers)
|
|
974
|
-
{{WORKTREE_PR_CMD}} <id>
|
|
975
|
-
→ Runs all offline tests (blocks if fail)
|
|
976
|
-
→ Pushes to origin
|
|
977
|
-
→ Creates PR with auto-generated description
|
|
978
|
-
→ Triggers reviewer agents
|
|
979
|
-
|
|
980
|
-
4. AUTOMATED REVIEW
|
|
981
|
-
→ Reviewer agents run in parallel (quality, security, performance, tests)
|
|
982
|
-
→ PR labeled: reviewer-approved OR needs-work
|
|
983
|
-
→ Auto-merge on approval
|
|
984
|
-
|
|
985
|
-
5. CLEANUP
|
|
986
|
-
{{WORKTREE_CLEANUP_CMD}} <id>
|
|
987
|
-
→ Removes worktree and deletes branch
|
|
396
|
+
{{{KEY_WORKFLOWS}}}
|
|
988
397
|
```
|
|
398
|
+
{{/if}}
|
|
989
399
|
|
|
990
|
-
{{#if
|
|
991
|
-
|
|
400
|
+
{{#if ESSENTIAL_COMMANDS}}
|
|
401
|
+
## Project Commands
|
|
992
402
|
|
|
993
403
|
```bash
|
|
994
|
-
{{
|
|
404
|
+
{{{ESSENTIAL_COMMANDS}}}
|
|
995
405
|
```
|
|
996
406
|
{{/if}}
|
|
997
407
|
|
|
998
|
-
|
|
408
|
+
{{#if INFRA_WORKFLOW}}
|
|
409
|
+
## Infrastructure Workflow
|
|
999
410
|
|
|
1000
|
-
|
|
1001
|
-
{{#if FIXES_PATH}}
|
|
1002
|
-
2. Check `{{FIXES_PATH}}` for known issues
|
|
1003
|
-
{{/if}}
|
|
1004
|
-
{{#if CLUSTER_IDENTIFY}}
|
|
1005
|
-
3. {{CLUSTER_IDENTIFY}}
|
|
411
|
+
{{{INFRA_WORKFLOW}}}
|
|
1006
412
|
{{/if}}
|
|
1007
|
-
4. **Create a worktree for your changes**
|
|
1008
413
|
|
|
1009
|
-
|
|
414
|
+
{{#if HEALTH_CHECKS}}
|
|
415
|
+
## Health Checks
|
|
1010
416
|
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
3. Run `{{TEST_COMMAND}}`
|
|
1014
|
-
4. Run linting and type checking
|
|
1015
|
-
5. **Create PR**: `{{WORKTREE_PR_CMD}} <id>`
|
|
417
|
+
{{{HEALTH_CHECKS}}}
|
|
418
|
+
{{/if}}
|
|
1016
419
|
|
|
1017
|
-
{{#if
|
|
1018
|
-
|
|
420
|
+
{{#if ROLLBACK_PROCEDURES}}
|
|
421
|
+
## Emergency Rollback
|
|
1019
422
|
|
|
1020
|
-
{{{
|
|
423
|
+
{{{ROLLBACK_PROCEDURES}}}
|
|
1021
424
|
{{/if}}
|
|
1022
425
|
|
|
1023
|
-
|
|
426
|
+
{{#if INCIDENT_RESPONSE}}
|
|
427
|
+
## Incident Response
|
|
1024
428
|
|
|
1025
|
-
|
|
1026
|
-
2. PR created and reviewed by agents
|
|
1027
|
-
{{#if CHANGELOG_PATH}}
|
|
1028
|
-
3. Create changelog in `{{CHANGELOG_PATH}}/YYYY-MM/YYYY-MM-DD_description.md`
|
|
429
|
+
{{{INCIDENT_RESPONSE}}}
|
|
1029
430
|
{{/if}}
|
|
1030
|
-
4. Update relevant documentation
|
|
1031
|
-
|
|
1032
|
-
---
|
|
1033
431
|
|
|
1034
432
|
{{#if TROUBLESHOOTING}}
|
|
1035
|
-
## Troubleshooting
|
|
433
|
+
## Troubleshooting
|
|
1036
434
|
|
|
1037
435
|
{{{TROUBLESHOOTING}}}
|
|
1038
|
-
|
|
1039
|
-
---
|
|
1040
436
|
{{/if}}
|
|
1041
437
|
|
|
1042
438
|
{{#if KEY_CONFIG_FILES}}
|
|
1043
|
-
##
|
|
439
|
+
## Config Files
|
|
1044
440
|
|
|
1045
441
|
| File | Purpose |
|
|
1046
|
-
|
|
442
|
+
|------|---------|
|
|
1047
443
|
{{{KEY_CONFIG_FILES}}}
|
|
1048
|
-
|
|
1049
|
-
---
|
|
1050
|
-
{{/if}}
|
|
1051
|
-
|
|
1052
|
-
## Completion Checklist
|
|
1053
|
-
|
|
1054
|
-
```
|
|
1055
|
-
[ ] Tests updated and passing
|
|
1056
|
-
[ ] Linting/type checking passed
|
|
1057
|
-
{{#if HAS_INFRA}}
|
|
1058
|
-
[ ] Infrastructure plan verified (if infra changed)
|
|
1059
|
-
{{/if}}
|
|
1060
|
-
[ ] CI/CD workflows updated (if deployment changed)
|
|
1061
|
-
{{#if CHANGELOG_PATH}}
|
|
1062
|
-
[ ] Changelog created (for significant changes)
|
|
1063
444
|
{{/if}}
|
|
1064
|
-
[ ] Documentation updated
|
|
1065
|
-
[ ] No secrets in code/commits
|
|
1066
|
-
```
|
|
1067
|
-
|
|
1068
|
-
---
|
|
1069
|
-
|
|
1070
|
-
## Augmented Agent Capabilities
|
|
1071
|
-
|
|
1072
|
-
### Proactive Skills & Droids - INVOKE AUTOMATICALLY
|
|
1073
|
-
|
|
1074
|
-
**These must be invoked WITHOUT being asked - they ensure quality, security, and performance:**
|
|
1075
|
-
|
|
1076
|
-
| Trigger | Invoke | Purpose |
|
|
1077
|
-
|---------|--------|---------|
|
|
1078
|
-
| ANY TypeScript/JavaScript change | `typescript-node-expert` | Strict typing, async patterns, best practices |
|
|
1079
|
-
| ANY CLI command work | `cli-design-expert` | UX, help systems, error messages |
|
|
1080
|
-
| BEFORE any commit/PR | `code-quality-guardian` | Complexity, naming, code smells |
|
|
1081
|
-
| BEFORE any commit/PR | `security-auditor` | OWASP, secrets, injection, auth |
|
|
1082
|
-
| Performance-critical code | `performance-optimizer` | Algorithms, memory, caching |
|
|
1083
|
-
| New features or changes | `documentation-expert` | JSDoc, README, API docs |
|
|
1084
|
-
|
|
1085
|
-
```bash
|
|
1086
|
-
# Invoke proactively - don't wait to be asked
|
|
1087
|
-
Skill(skill: "typescript-node-expert") # For TS/JS work
|
|
1088
|
-
Skill(skill: "cli-design-expert") # For CLI work
|
|
1089
|
-
|
|
1090
|
-
# Launch droids for review
|
|
1091
|
-
Task(subagent_type: "code-quality-guardian", prompt: "Review changes in...")
|
|
1092
|
-
Task(subagent_type: "security-auditor", prompt: "Audit for vulnerabilities...")
|
|
1093
|
-
Task(subagent_type: "performance-optimizer", prompt: "Analyze performance...")
|
|
1094
|
-
Task(subagent_type: "documentation-expert", prompt: "Review documentation...")
|
|
1095
|
-
```
|
|
1096
445
|
|
|
1097
|
-
### Skills (`{{SKILLS_PATH}}`)
|
|
1098
|
-
|
|
1099
|
-
Invoke with `Skill` tool. Skills expand inline with detailed instructions.
|
|
1100
|
-
|
|
1101
|
-
| Skill | Purpose | Use When |
|
|
1102
|
-
| ----- | ------- | -------- |
|
|
1103
|
-
| `typescript-node-expert` | Strict TS, async patterns, ESM, performance | **PROACTIVE** - All TypeScript work |
|
|
1104
|
-
| `cli-design-expert` | CLI UX, help, errors, prompts, output | **PROACTIVE** - All CLI development |
|
|
1105
446
|
{{#if DISCOVERED_SKILLS}}
|
|
447
|
+
## Project Skills
|
|
448
|
+
|
|
1106
449
|
{{{DISCOVERED_SKILLS}}}
|
|
1107
450
|
{{/if}}
|
|
1108
|
-
| `senior-frontend` | React/Next.js/TypeScript/Tailwind development | Building UI features, performance optimization |
|
|
1109
|
-
| `code-reviewer` | Automated code analysis, security scanning | Reviewing PRs, code quality checks |
|
|
1110
|
-
| `webapp-testing` | Playwright-based web testing | Verifying frontend functionality, debugging UI |
|
|
1111
|
-
|
|
1112
|
-
### Custom Droids (`{{DROIDS_PATH}}`)
|
|
1113
|
-
|
|
1114
|
-
Launch via `Task` tool with `subagent_type`. Droids run autonomously.
|
|
1115
|
-
|
|
1116
|
-
**Proactive Quality Droids (Run before EVERY commit/PR):**
|
|
1117
|
-
| Droid | Focus | When to Invoke |
|
|
1118
|
-
|-------|-------|----------------|
|
|
1119
|
-
| `code-quality-guardian` | Complexity, naming, SOLID, code smells | **PROACTIVE** - All code changes |
|
|
1120
|
-
| `security-auditor` | OWASP, secrets, injection, auth | **PROACTIVE** - All code changes |
|
|
1121
|
-
| `performance-optimizer` | Algorithms, memory, caching, I/O | **PROACTIVE** - Performance-critical code |
|
|
1122
|
-
| `documentation-expert` | JSDoc, README, API docs, accuracy | **PROACTIVE** - New features/APIs |
|
|
1123
451
|
|
|
1124
452
|
{{#if LANGUAGE_DROIDS}}
|
|
1125
|
-
|
|
1126
|
-
| Droid | Purpose |
|
|
1127
|
-
|-------|---------|
|
|
1128
|
-
{{{LANGUAGE_DROIDS}}}
|
|
1129
|
-
{{/if}}
|
|
1130
|
-
|
|
1131
|
-
**Code Review Pipeline:**
|
|
1132
|
-
| Droid | Focus |
|
|
1133
|
-
|-------|-------|
|
|
1134
|
-
| `git-summarizer` | Gathers repo context (status, diffs, commit range) for downstream droids |
|
|
1135
|
-
| `code-quality-reviewer` | Naming, complexity, duplication, error handling, style |
|
|
1136
|
-
| `security-code-reviewer` | OWASP Top 10, secrets, authn/z, injection, risky configs |
|
|
1137
|
-
| `performance-reviewer` | Algorithmic complexity, N+1 queries, caching, memory/IO |
|
|
1138
|
-
| `test-coverage-reviewer` | Test gaps, brittle tests, coverage analysis |
|
|
1139
|
-
| `documentation-accuracy-reviewer` | Verifies docs/README accuracy against implementation |
|
|
1140
|
-
| `pr-readiness-reviewer` | Branch readiness: tests, docs, blockers, changelog |
|
|
1141
|
-
|
|
1142
|
-
**Utilities:**
|
|
1143
|
-
| Droid | Purpose |
|
|
1144
|
-
|-------|---------|
|
|
1145
|
-
| `release-notes-writer` | Structured release notes from commit history |
|
|
1146
|
-
| `test-plan-writer` | Focused automated and manual test plans |
|
|
1147
|
-
| `todo-fixme-scanner` | Scans repo for TODO/FIXME markers |
|
|
1148
|
-
| `session-context-preservation-droid` | Maintains project knowledge across sessions |
|
|
1149
|
-
|
|
1150
|
-
### Commands (`{{COMMANDS_PATH}}`)
|
|
1151
|
-
|
|
1152
|
-
High-level orchestration workflows:
|
|
1153
|
-
|
|
1154
|
-
| Command | Purpose |
|
|
1155
|
-
| ------- | ------- |
|
|
1156
|
-
| `/worktree` | Manage git worktrees (create, list, pr, cleanup) - **USE FOR ALL CHANGES** |
|
|
1157
|
-
| `/code-review` | Full code review (git-summarizer → quality/security/perf/test/docs reviewers) |
|
|
1158
|
-
| `/pr-ready` | Validate branch, auto-create PR, trigger reviewer agents |
|
|
1159
|
-
| `/release-notes` | Generate structured release notes from changes |
|
|
1160
|
-
| `/test-plan` | Produce test plans for code changes |
|
|
1161
|
-
| `/todo-scan` | Scan for TODO/FIXME markers |
|
|
1162
|
-
|
|
1163
|
-
{{#if MCP_PLUGINS}}
|
|
1164
|
-
### MCP Plugins (`.mcp.json`)
|
|
1165
|
-
|
|
1166
|
-
External tool integrations:
|
|
1167
|
-
|
|
1168
|
-
| Plugin | Purpose |
|
|
1169
|
-
| ------ | ------- |
|
|
1170
|
-
{{{MCP_PLUGINS}}}
|
|
1171
|
-
{{/if}}
|
|
1172
|
-
|
|
1173
|
-
### Usage Patterns
|
|
453
|
+
## Language Specialists
|
|
1174
454
|
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
```
|
|
1178
|
-
1. Invoke /code-review command
|
|
1179
|
-
2. git-summarizer gathers context
|
|
1180
|
-
3. Parallel delegation to quality/security/perf/test/docs droids
|
|
1181
|
-
4. Consolidated report with prioritized findings
|
|
1182
|
-
```
|
|
1183
|
-
|
|
1184
|
-
**PR Preparation:**
|
|
1185
|
-
|
|
1186
|
-
```
|
|
1187
|
-
1. Run /pr-ready command
|
|
1188
|
-
2. Validates: tests, docs, changelog, TODO markers
|
|
1189
|
-
3. Returns blockers and required actions
|
|
1190
|
-
```
|
|
1191
|
-
|
|
1192
|
-
{{#if LANGUAGE_EXAMPLES}}
|
|
1193
|
-
**Language-Specific Refactoring:**
|
|
1194
|
-
|
|
1195
|
-
```
|
|
1196
|
-
{{{LANGUAGE_EXAMPLES}}}
|
|
1197
|
-
```
|
|
455
|
+
{{{LANGUAGE_DROIDS}}}
|
|
1198
456
|
{{/if}}
|
|
1199
457
|
|
|
1200
|
-
**Frontend Development:**
|
|
1201
|
-
|
|
1202
|
-
```
|
|
1203
|
-
# Invoke skill for React/TypeScript work
|
|
1204
|
-
Skill(skill: "senior-frontend")
|
|
1205
|
-
# Then follow expanded instructions
|
|
1206
|
-
```
|
|
1207
|
-
|
|
1208
|
-
---
|
|
1209
|
-
|
|
1210
458
|
{{#if PREPOPULATED_KNOWLEDGE}}
|
|
1211
|
-
## Project Knowledge
|
|
1212
|
-
|
|
1213
|
-
### Recent Activity (Short-term Context)
|
|
459
|
+
## Project Knowledge
|
|
1214
460
|
|
|
461
|
+
### Recent Activity
|
|
1215
462
|
{{{RECENT_ACTIVITY}}}
|
|
1216
463
|
|
|
1217
|
-
### Learned Lessons
|
|
1218
|
-
|
|
464
|
+
### Learned Lessons
|
|
1219
465
|
{{{LEARNED_LESSONS}}}
|
|
1220
466
|
|
|
1221
467
|
### Known Gotchas
|
|
1222
|
-
|
|
1223
468
|
{{{KNOWN_GOTCHAS}}}
|
|
1224
469
|
|
|
1225
|
-
### Hot Spots
|
|
1226
|
-
|
|
470
|
+
### Hot Spots
|
|
1227
471
|
{{{HOT_SPOTS}}}
|
|
1228
|
-
|
|
1229
472
|
{{/if}}
|
|
1230
473
|
|
|
474
|
+
---
|
|
475
|
+
|
|
476
|
+
## Completion Checklist
|
|
477
|
+
|
|
478
|
+
```
|
|
479
|
+
[ ] Task created and released
|
|
480
|
+
[ ] Worktree used (not main repo)
|
|
481
|
+
[ ] PR created (not direct push)
|
|
482
|
+
[ ] Tests passing
|
|
483
|
+
[ ] Memory updated (short + long term)
|
|
484
|
+
[ ] Skills consulted
|
|
485
|
+
[ ] No secrets in code
|
|
486
|
+
```
|
|
487
|
+
|
|
1231
488
|
</coding_guidelines>
|