universal-agent-memory 0.5.1 โ 0.5.3
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 +184 -97
- package/dist/bin/cli.js +5 -4
- package/dist/bin/cli.js.map +1 -1
- package/dist/cli/init.d.ts.map +1 -1
- package/dist/cli/init.js +87 -114
- package/dist/cli/init.js.map +1 -1
- package/dist/cli/memory.d.ts.map +1 -1
- package/dist/cli/memory.js +123 -10
- package/dist/cli/memory.js.map +1 -1
- package/dist/cli/update.d.ts +6 -0
- package/dist/cli/update.d.ts.map +1 -0
- package/dist/cli/update.js +137 -0
- package/dist/cli/update.js.map +1 -0
- package/package.json +1 -1
- package/templates/CLAUDE.template.md +114 -49
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
import chalk from 'chalk';
|
|
2
|
+
import ora from 'ora';
|
|
3
|
+
import { existsSync, readFileSync, writeFileSync, copyFileSync } from 'fs';
|
|
4
|
+
import { join } from 'path';
|
|
5
|
+
import { analyzeProject } from '../analyzers/index.js';
|
|
6
|
+
import { generateClaudeMd } from '../generators/claude-md.js';
|
|
7
|
+
import { mergeClaudeMd, validateMerge } from '../utils/merge-claude-md.js';
|
|
8
|
+
import { AgentContextConfigSchema } from '../types/index.js';
|
|
9
|
+
export async function updateCommand(options) {
|
|
10
|
+
const cwd = process.cwd();
|
|
11
|
+
const configPath = join(cwd, '.uam.json');
|
|
12
|
+
const claudeMdPath = join(cwd, 'CLAUDE.md');
|
|
13
|
+
const agentMdPath = join(cwd, 'AGENT.md');
|
|
14
|
+
console.log(chalk.bold('\n๐ UAM Update - Preserving All Customizations\n'));
|
|
15
|
+
// Check for existing config
|
|
16
|
+
if (!existsSync(configPath)) {
|
|
17
|
+
console.log(chalk.yellow('No .uam.json found. Run `uam init` first.'));
|
|
18
|
+
return;
|
|
19
|
+
}
|
|
20
|
+
// Load config
|
|
21
|
+
let config;
|
|
22
|
+
try {
|
|
23
|
+
const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
|
|
24
|
+
config = AgentContextConfigSchema.parse(raw);
|
|
25
|
+
}
|
|
26
|
+
catch (error) {
|
|
27
|
+
console.error(chalk.red('Invalid .uam.json configuration'));
|
|
28
|
+
console.error(error);
|
|
29
|
+
return;
|
|
30
|
+
}
|
|
31
|
+
// Analyze project
|
|
32
|
+
const spinner = ora('Analyzing project structure...').start();
|
|
33
|
+
let analysis;
|
|
34
|
+
try {
|
|
35
|
+
analysis = await analyzeProject(cwd);
|
|
36
|
+
spinner.succeed(`Analyzed: ${analysis.projectName}`);
|
|
37
|
+
}
|
|
38
|
+
catch (error) {
|
|
39
|
+
spinner.fail('Failed to analyze project');
|
|
40
|
+
console.error(chalk.red(error));
|
|
41
|
+
return;
|
|
42
|
+
}
|
|
43
|
+
// Find existing CLAUDE.md or AGENT.md
|
|
44
|
+
let existingPath = null;
|
|
45
|
+
let existingContent = null;
|
|
46
|
+
if (existsSync(claudeMdPath)) {
|
|
47
|
+
existingPath = claudeMdPath;
|
|
48
|
+
existingContent = readFileSync(claudeMdPath, 'utf-8');
|
|
49
|
+
}
|
|
50
|
+
else if (existsSync(agentMdPath)) {
|
|
51
|
+
existingPath = agentMdPath;
|
|
52
|
+
existingContent = readFileSync(agentMdPath, 'utf-8');
|
|
53
|
+
}
|
|
54
|
+
if (!existingContent) {
|
|
55
|
+
console.log(chalk.yellow('No CLAUDE.md or AGENT.md found. Run `uam generate` instead.'));
|
|
56
|
+
return;
|
|
57
|
+
}
|
|
58
|
+
// Create backup before update
|
|
59
|
+
const backupPath = existingPath + '.backup.' + new Date().toISOString().replace(/[:.]/g, '-');
|
|
60
|
+
if (options.dryRun) {
|
|
61
|
+
console.log(chalk.dim(`Would create backup at: ${backupPath}`));
|
|
62
|
+
}
|
|
63
|
+
else {
|
|
64
|
+
copyFileSync(existingPath, backupPath);
|
|
65
|
+
console.log(chalk.dim(`Created backup: ${backupPath}`));
|
|
66
|
+
}
|
|
67
|
+
// Generate new content from latest template
|
|
68
|
+
const genSpinner = ora('Generating updated content from latest template...').start();
|
|
69
|
+
let newContent;
|
|
70
|
+
try {
|
|
71
|
+
newContent = await generateClaudeMd(analysis, config);
|
|
72
|
+
genSpinner.succeed('Generated updated content');
|
|
73
|
+
}
|
|
74
|
+
catch (error) {
|
|
75
|
+
genSpinner.fail('Failed to generate new content');
|
|
76
|
+
console.error(chalk.red(error));
|
|
77
|
+
return;
|
|
78
|
+
}
|
|
79
|
+
// Merge: New template structure + existing user content
|
|
80
|
+
const mergeSpinner = ora('Merging with existing content (preserving all customizations)...').start();
|
|
81
|
+
let mergedContent;
|
|
82
|
+
try {
|
|
83
|
+
mergedContent = mergeClaudeMd(existingContent, newContent);
|
|
84
|
+
mergeSpinner.succeed('Merged content');
|
|
85
|
+
}
|
|
86
|
+
catch (error) {
|
|
87
|
+
mergeSpinner.fail('Failed to merge content');
|
|
88
|
+
console.error(chalk.red(error));
|
|
89
|
+
return;
|
|
90
|
+
}
|
|
91
|
+
// Validate merge
|
|
92
|
+
const validation = validateMerge(existingContent, mergedContent);
|
|
93
|
+
if (!validation.valid) {
|
|
94
|
+
console.log(chalk.yellow('\n Merge validation warnings:'));
|
|
95
|
+
for (const warning of validation.warnings) {
|
|
96
|
+
console.log(chalk.dim(` - ${warning}`));
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
// Show diff summary
|
|
100
|
+
const existingLines = existingContent.split('\n').length;
|
|
101
|
+
const newLines = newContent.split('\n').length;
|
|
102
|
+
const mergedLines = mergedContent.split('\n').length;
|
|
103
|
+
console.log(chalk.bold('\n๐ Update Summary:\n'));
|
|
104
|
+
console.log(chalk.dim(` Existing file: ${existingLines} lines`));
|
|
105
|
+
console.log(chalk.dim(` New template: ${newLines} lines`));
|
|
106
|
+
console.log(chalk.dim(` Merged result: ${mergedLines} lines`));
|
|
107
|
+
// Count preserved sections
|
|
108
|
+
const existingSections = (existingContent.match(/^## /gm) || []).length;
|
|
109
|
+
const mergedSections = (mergedContent.match(/^## /gm) || []).length;
|
|
110
|
+
console.log(chalk.dim(` Sections: ${existingSections} โ ${mergedSections}`));
|
|
111
|
+
if (options.dryRun) {
|
|
112
|
+
console.log(chalk.yellow('\n --dry-run: No changes made\n'));
|
|
113
|
+
// Show preview
|
|
114
|
+
console.log(chalk.dim('--- Preview (first 50 lines) ---\n'));
|
|
115
|
+
console.log(mergedContent.split('\n').slice(0, 50).join('\n'));
|
|
116
|
+
console.log(chalk.dim('\n... [truncated] ...'));
|
|
117
|
+
return;
|
|
118
|
+
}
|
|
119
|
+
// Write merged content
|
|
120
|
+
writeFileSync(existingPath, mergedContent);
|
|
121
|
+
console.log(chalk.green(`\nโ
Updated ${existingPath}\n`));
|
|
122
|
+
console.log('What was preserved:');
|
|
123
|
+
console.log(' โข All custom sections');
|
|
124
|
+
console.log(' โข URLs, kubectl contexts, workflows');
|
|
125
|
+
console.log(' โข Config files, gotchas, lessons');
|
|
126
|
+
console.log(' โข Any content not in the standard template');
|
|
127
|
+
console.log('');
|
|
128
|
+
console.log('What was updated:');
|
|
129
|
+
console.log(' โข Template structure and formatting');
|
|
130
|
+
console.log(' โข Standard sections (decision loop, memory system, etc.)');
|
|
131
|
+
console.log(' โข Code Field integration (v8.0)');
|
|
132
|
+
console.log(' โข Inhibition-style directives');
|
|
133
|
+
console.log('');
|
|
134
|
+
console.log(chalk.dim(`Backup saved at: ${backupPath}`));
|
|
135
|
+
console.log(chalk.dim('If something looks wrong, restore from backup.'));
|
|
136
|
+
}
|
|
137
|
+
//# sourceMappingURL=update.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"update.js","sourceRoot":"","sources":["../../src/cli/update.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "universal-agent-memory",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.3",
|
|
4
4
|
"description": "Universal AI agent memory system - CLAUDE.md templates, memory, worktrees for Claude Code, Factory.AI, VSCode, OpenCode",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -1,11 +1,24 @@
|
|
|
1
1
|
<!--
|
|
2
|
-
CLAUDE.md Universal Template -
|
|
2
|
+
CLAUDE.md Universal Template - v8.0
|
|
3
3
|
|
|
4
4
|
CHANGES IN THIS VERSION:
|
|
5
|
-
-
|
|
6
|
-
-
|
|
7
|
-
-
|
|
8
|
-
-
|
|
5
|
+
- Context Field integration (code field + inhibition-style directives)
|
|
6
|
+
- Inhibition > Instruction: "Do not X" creates blockers, "Do X" creates preferences
|
|
7
|
+
- 4-line code field for 100% assumption stating, 89% bug detection
|
|
8
|
+
- Simplified setup (auto-works, no clicking required)
|
|
9
|
+
- Database protection (never delete existing data)
|
|
10
|
+
|
|
11
|
+
CODE FIELD ATTRIBUTION:
|
|
12
|
+
The Code Field prompt technique is based on research from:
|
|
13
|
+
https://github.com/NeoVertex1/context-field
|
|
14
|
+
|
|
15
|
+
Context Field is experimental research on context field prompts and cognitive
|
|
16
|
+
regime shifts in large language models. The code_field.md prompt produces:
|
|
17
|
+
- 100% assumption stating (vs 0% baseline)
|
|
18
|
+
- 89% bug detection in code review (vs 39% baseline)
|
|
19
|
+
- 100% refusal of impossible requests (vs 0% baseline)
|
|
20
|
+
|
|
21
|
+
License: Research shared for exploration and reuse with attribution.
|
|
9
22
|
|
|
10
23
|
Core Variables:
|
|
11
24
|
{{PROJECT_NAME}}, {{PROJECT_PATH}}, {{DEFAULT_BRANCH}}, {{STRUCTURE_DATE}}
|
|
@@ -50,6 +63,39 @@
|
|
|
50
63
|
|
|
51
64
|
---
|
|
52
65
|
|
|
66
|
+
## ๐ CODE FIELD - MANDATORY FOR ALL CODE
|
|
67
|
+
|
|
68
|
+
**Before writing ANY code, apply these constraints:**
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
Do not write code before stating assumptions.
|
|
72
|
+
Do not claim correctness you haven't verified.
|
|
73
|
+
Do not handle only the happy path.
|
|
74
|
+
Under what conditions does this work?
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Code Generation Protocol
|
|
78
|
+
|
|
79
|
+
**BEFORE CODE** (required):
|
|
80
|
+
- State assumptions about input, environment, dependencies
|
|
81
|
+
- Enumerate edge cases and failure modes
|
|
82
|
+
- Define explicit scope ("This handles X, not Y")
|
|
83
|
+
- Ask: "What would break this? What would a malicious caller do?"
|
|
84
|
+
|
|
85
|
+
**IN CODE**:
|
|
86
|
+
- Comments explain *why*, not *what*
|
|
87
|
+
- Edge cases handled OR explicitly rejected with clear errors
|
|
88
|
+
- Error paths as considered as happy paths
|
|
89
|
+
- Smaller than your first instinct
|
|
90
|
+
|
|
91
|
+
**AFTER CODE** (required):
|
|
92
|
+
- "What this handles" section
|
|
93
|
+
- "What this does NOT handle" section
|
|
94
|
+
- Known limitations documented
|
|
95
|
+
- Conditions for correctness stated
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
53
99
|
## โก SESSION START PROTOCOL
|
|
54
100
|
|
|
55
101
|
**EXECUTE IMMEDIATELY before any response:**
|
|
@@ -64,6 +110,22 @@ uam agent status # Check other active agents
|
|
|
64
110
|
|
|
65
111
|
---
|
|
66
112
|
|
|
113
|
+
## ๐ CRITICAL INHIBITIONS
|
|
114
|
+
|
|
115
|
+
**These are BLOCKERS, not suggestions. Do not proceed without satisfying them.**
|
|
116
|
+
|
|
117
|
+
| Inhibition | Rationale |
|
|
118
|
+
|------------|-----------|
|
|
119
|
+
| Do not begin work without querying memory | Context prevents duplicate work |
|
|
120
|
+
| Do not commit to {{DEFAULT_BRANCH}} | All changes require worktree + PR |
|
|
121
|
+
| Do not claim work without overlap check | Prevents merge conflicts |
|
|
122
|
+
| Do not create PR with failing tests | Broken code must not merge |
|
|
123
|
+
| Do not complete task without storing learnings | Memory enables endless context |
|
|
124
|
+
| Do not write code without stating assumptions | Prevents hidden bugs |
|
|
125
|
+
| Do not handle only the happy path | Edge cases are where bugs live |
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
67
129
|
## ๐ค MULTI-AGENT COORDINATION PROTOCOL
|
|
68
130
|
|
|
69
131
|
### Before Claiming Any Work
|
|
@@ -98,21 +160,10 @@ uam agent announce \
|
|
|
98
160
|
| `high` | Wait or split work | Same file, different sections |
|
|
99
161
|
| `critical` | STOP - request handoff | Same file, same sections |
|
|
100
162
|
|
|
101
|
-
### Parallel Work Patterns
|
|
102
|
-
|
|
103
|
-
```bash
|
|
104
|
-
# CORRECT: Independent droids can run in parallel
|
|
105
|
-
Task(subagent_type: "code-quality-guardian", ...)
|
|
106
|
-
Task(subagent_type: "security-auditor", ...) # Runs concurrently
|
|
107
|
-
Task(subagent_type: "performance-optimizer", ...) # Runs concurrently
|
|
108
|
-
|
|
109
|
-
# CORRECT: Coordinate merge order for overlapping changes
|
|
110
|
-
# Agent A finishes first โ merges first
|
|
111
|
-
# Agent B rebases โ merges second
|
|
112
|
-
```
|
|
113
|
-
|
|
114
163
|
### Agent Capability Routing
|
|
115
164
|
|
|
165
|
+
Route tasks to specialized droids for optimal results:
|
|
166
|
+
|
|
116
167
|
| Task Type | Route To | Capabilities |
|
|
117
168
|
|-----------|----------|--------------|
|
|
118
169
|
| TypeScript/JavaScript | `typescript-node-expert` | typing, async, node |
|
|
@@ -122,6 +173,8 @@ Task(subagent_type: "performance-optimizer", ...) # Runs concurrently
|
|
|
122
173
|
| Documentation | `documentation-expert` | jsdoc, readme, api-docs |
|
|
123
174
|
| Code quality | `code-quality-guardian` | complexity, naming, solid |
|
|
124
175
|
|
|
176
|
+
**Missing expert?** Generate one: `uam droids add <name> --capabilities "..." --triggers "..."`
|
|
177
|
+
|
|
125
178
|
---
|
|
126
179
|
|
|
127
180
|
## ๐ MANDATORY DECISION LOOP
|
|
@@ -131,41 +184,50 @@ Task(subagent_type: "performance-optimizer", ...) # Runs concurrently
|
|
|
131
184
|
โ EXECUTE FOR EVERY TASK โ
|
|
132
185
|
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
|
|
133
186
|
โ โ
|
|
134
|
-
โ 1. MEMORY โ uam memory query "<keywords>"
|
|
187
|
+
โ 1. MEMORY โ Do not begin without: uam memory query "<keywords>"โ
|
|
135
188
|
โ โ Check for relevant past context โ
|
|
136
189
|
โ โ
|
|
137
|
-
โ 2. AGENTS โ uam agent overlaps
|
|
190
|
+
โ 2. AGENTS โ Do not claim without: uam agent overlaps โ
|
|
138
191
|
โ โ If overlap: coordinate or wait โ
|
|
139
192
|
โ โ
|
|
140
193
|
โ 3. SKILLS โ Check {{SKILLS_PATH}} for applicable skill โ
|
|
194
|
+
โ โ Missing skill? Generate: uam droids add โ
|
|
141
195
|
โ โ Invoke BEFORE implementing โ
|
|
142
196
|
โ โ
|
|
143
|
-
โ 4. WORKTREE โ {{
|
|
197
|
+
โ 4. WORKTREE โ Do not commit to {{DEFAULT_BRANCH}} โ
|
|
198
|
+
โ โ {{WORKTREE_CREATE_CMD}} <slug> โ
|
|
144
199
|
โ โ cd {{WORKTREE_DIR}}/NNN-<slug>/ โ
|
|
145
|
-
โ โ NEVER commit to {{DEFAULT_BRANCH}} โ
|
|
146
200
|
โ โ
|
|
147
|
-
โ 5.
|
|
201
|
+
โ 5. CODE โ Apply CODE FIELD constraints (above) โ
|
|
202
|
+
โ โ State assumptions โ Implement โ Test โ
|
|
148
203
|
โ โ
|
|
149
|
-
โ 6.
|
|
150
|
-
โ โ
|
|
204
|
+
โ 6. PR โ Do not merge with failing tests โ
|
|
205
|
+
โ โ {{WORKTREE_PR_CMD}} โ parallel reviews โ
|
|
151
206
|
โ โ
|
|
152
|
-
โ 7.
|
|
207
|
+
โ 7. MEMORY โ Do not complete without storing learnings โ
|
|
208
|
+
โ โ uam memory store "lesson" --importance 7+ โ
|
|
153
209
|
โ โ
|
|
154
210
|
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
155
211
|
```
|
|
156
212
|
|
|
157
213
|
---
|
|
158
214
|
|
|
159
|
-
## ๐ง MEMORY SYSTEM
|
|
215
|
+
## ๐ง ENDLESS CONTEXT - PROJECT MEMORY SYSTEM
|
|
216
|
+
|
|
217
|
+
**Your context is NOT limited to this conversation.**
|
|
160
218
|
|
|
161
|
-
|
|
219
|
+
Memory persists with the project, enabling:
|
|
220
|
+
- Recall of decisions from weeks/months ago
|
|
221
|
+
- Learning from past mistakes (gotchas)
|
|
222
|
+
- Understanding of why code is the way it is
|
|
223
|
+
- Handoff between sessions without information loss
|
|
162
224
|
|
|
163
225
|
```
|
|
164
226
|
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
165
|
-
โ L1: WORKING โ Recent actions โ {{SHORT_TERM_LIMIT}} max โ
|
|
166
|
-
โ L2: SESSION โ Current session โ Per session โ
|
|
167
|
-
โ L3: SEMANTIC โ Long-term learnings โ {{LONG_TERM_BACKEND}} โ
|
|
168
|
-
โ L4: KNOWLEDGE โ Entity relationships โ SQLite โ
|
|
227
|
+
โ L1: WORKING โ Recent actions โ {{SHORT_TERM_LIMIT}} max โ SQLite โ
|
|
228
|
+
โ L2: SESSION โ Current session โ Per session โ SQLite โ
|
|
229
|
+
โ L3: SEMANTIC โ Long-term learnings โ {{LONG_TERM_BACKEND}} โ Vector searchโ
|
|
230
|
+
โ L4: KNOWLEDGE โ Entity relationships โ SQLite โ Graph โ
|
|
169
231
|
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
170
232
|
```
|
|
171
233
|
|
|
@@ -176,21 +238,21 @@ Task(subagent_type: "performance-optimizer", ...) # Runs concurrently
|
|
|
176
238
|
| Learned something reusable | `uam memory store "lesson" --importance 8` |
|
|
177
239
|
| Fixed a tricky bug | `uam memory store "bug fix" --tags bug-fix --importance 7` |
|
|
178
240
|
| Discovered a gotcha | `uam memory store "gotcha" --tags gotcha --importance 9` |
|
|
179
|
-
|
|
|
241
|
+
| Made architectural decision | `uam memory store "decision: X because Y" --importance 8` |
|
|
180
242
|
|
|
181
243
|
### When to Query Memories
|
|
182
244
|
|
|
183
245
|
| Situation | Action |
|
|
184
246
|
|-----------|--------|
|
|
185
|
-
| Starting new work | `uam memory query "relevant keywords"` |
|
|
186
|
-
| Debugging | `uam memory query "similar error"` |
|
|
187
|
-
| Understanding
|
|
247
|
+
| Starting ANY new work | `uam memory query "relevant keywords"` |
|
|
248
|
+
| Debugging unfamiliar code | `uam memory query "similar error"` |
|
|
249
|
+
| Understanding past decisions | `uam memory query "why we did X"` |
|
|
188
250
|
|
|
189
251
|
---
|
|
190
252
|
|
|
191
253
|
## ๐ณ WORKTREE WORKFLOW
|
|
192
254
|
|
|
193
|
-
**
|
|
255
|
+
**Do not commit to {{DEFAULT_BRANCH}}. NO EXCEPTIONS.**
|
|
194
256
|
|
|
195
257
|
```bash
|
|
196
258
|
# Create
|
|
@@ -247,7 +309,7 @@ Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
|
|
|
247
309
|
| feature request | `uam task create --type feature` |
|
|
248
310
|
| code file for editing | check overlaps โ skills โ worktree |
|
|
249
311
|
| review/check/look | query memory first |
|
|
250
|
-
| ANY code change | tests required |
|
|
312
|
+
| ANY code change | apply CODE FIELD, tests required |
|
|
251
313
|
|
|
252
314
|
---
|
|
253
315
|
|
|
@@ -362,12 +424,13 @@ Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
|
|
|
362
424
|
## ๐งช Testing Requirements
|
|
363
425
|
|
|
364
426
|
1. Create worktree
|
|
365
|
-
2.
|
|
366
|
-
3.
|
|
427
|
+
2. Apply CODE FIELD (state assumptions first)
|
|
428
|
+
3. Update/create tests
|
|
429
|
+
4. Run `{{TEST_COMMAND}}`
|
|
367
430
|
{{#if LINT_COMMAND}}
|
|
368
|
-
|
|
431
|
+
5. Run `{{LINT_COMMAND}}`
|
|
369
432
|
{{/if}}
|
|
370
|
-
|
|
433
|
+
6. Create PR (do not merge with failing tests)
|
|
371
434
|
|
|
372
435
|
---
|
|
373
436
|
|
|
@@ -392,12 +455,13 @@ Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
|
|
|
392
455
|
## โ
Completion Checklist
|
|
393
456
|
|
|
394
457
|
```
|
|
458
|
+
โ Memory queried before starting
|
|
459
|
+
โ CODE FIELD applied (assumptions stated)
|
|
395
460
|
โ Tests pass
|
|
396
461
|
โ Lint/typecheck pass
|
|
397
462
|
โ Worktree used (not {{DEFAULT_BRANCH}})
|
|
398
|
-
โ
|
|
399
|
-
โ PR created
|
|
400
|
-
โ Parallel reviews passed
|
|
463
|
+
โ Learnings stored in memory
|
|
464
|
+
โ PR created with parallel reviews
|
|
401
465
|
{{#if HAS_INFRA}}
|
|
402
466
|
โ Infrastructure plan verified
|
|
403
467
|
{{/if}}
|
|
@@ -434,23 +498,24 @@ Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
|
|
|
434
498
|
โ โ
|
|
435
499
|
โ 4. FIX (if issues found) โ
|
|
436
500
|
โ โโ Create new worktree for fix โ
|
|
437
|
-
โ โโ
|
|
501
|
+
โ โโ Apply CODE FIELD for fix โ
|
|
438
502
|
โ โโ GOTO step 1 (Merge) โ
|
|
439
503
|
โ โโ Repeat until 100% working โ
|
|
440
504
|
โ โ
|
|
441
505
|
โ 5. COMPLETE โ
|
|
442
|
-
โ โโ
|
|
506
|
+
โ โโ Do not skip: uam memory store "what I learned" โ
|
|
443
507
|
โ โโ Close related tasks/issues โ
|
|
444
508
|
โ โโ Announce completion โ
|
|
445
509
|
โ โ
|
|
446
510
|
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
447
511
|
```
|
|
448
512
|
|
|
449
|
-
**โ ๏ธ
|
|
513
|
+
**โ ๏ธ Do not say "done" or "complete" until:**
|
|
450
514
|
- PR is merged (not just created)
|
|
451
515
|
- Deployment succeeded (not just triggered)
|
|
452
516
|
- Functionality verified working (not just "should work")
|
|
453
517
|
- All errors/issues fixed (iterate as needed)
|
|
518
|
+
- Learnings stored in memory
|
|
454
519
|
|
|
455
520
|
**Commands for completion:**
|
|
456
521
|
```bash
|
|
@@ -465,7 +530,7 @@ gh run view <run-id>
|
|
|
465
530
|
|
|
466
531
|
# If issues found, fix immediately
|
|
467
532
|
{{WORKTREE_CREATE_CMD}} hotfix-<issue>
|
|
468
|
-
# ... fix, test, PR, merge, repeat
|
|
533
|
+
# ... apply CODE FIELD, fix, test, PR, merge, repeat
|
|
469
534
|
```
|
|
470
535
|
|
|
471
536
|
---
|