@cluesmith/codev 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (245) hide show
  1. package/bin/af.js +8 -0
  2. package/bin/codev.js +4 -0
  3. package/bin/consult.js +7 -0
  4. package/dist/agent-farm/cli.d.ts +11 -0
  5. package/dist/agent-farm/cli.d.ts.map +1 -0
  6. package/dist/agent-farm/cli.js +359 -0
  7. package/dist/agent-farm/cli.js.map +1 -0
  8. package/dist/agent-farm/commands/cleanup.d.ts +12 -0
  9. package/dist/agent-farm/commands/cleanup.d.ts.map +1 -0
  10. package/dist/agent-farm/commands/cleanup.js +154 -0
  11. package/dist/agent-farm/commands/cleanup.js.map +1 -0
  12. package/dist/agent-farm/commands/db.d.ts +38 -0
  13. package/dist/agent-farm/commands/db.d.ts.map +1 -0
  14. package/dist/agent-farm/commands/db.js +133 -0
  15. package/dist/agent-farm/commands/db.js.map +1 -0
  16. package/dist/agent-farm/commands/index.d.ts +11 -0
  17. package/dist/agent-farm/commands/index.d.ts.map +1 -0
  18. package/dist/agent-farm/commands/index.js +11 -0
  19. package/dist/agent-farm/commands/index.js.map +1 -0
  20. package/dist/agent-farm/commands/open.d.ts +15 -0
  21. package/dist/agent-farm/commands/open.d.ts.map +1 -0
  22. package/dist/agent-farm/commands/open.js +118 -0
  23. package/dist/agent-farm/commands/open.js.map +1 -0
  24. package/dist/agent-farm/commands/rename.d.ts +13 -0
  25. package/dist/agent-farm/commands/rename.d.ts.map +1 -0
  26. package/dist/agent-farm/commands/rename.js +33 -0
  27. package/dist/agent-farm/commands/rename.js.map +1 -0
  28. package/dist/agent-farm/commands/send.d.ts +9 -0
  29. package/dist/agent-farm/commands/send.d.ts.map +1 -0
  30. package/dist/agent-farm/commands/send.js +282 -0
  31. package/dist/agent-farm/commands/send.js.map +1 -0
  32. package/dist/agent-farm/commands/spawn.d.ts +15 -0
  33. package/dist/agent-farm/commands/spawn.d.ts.map +1 -0
  34. package/dist/agent-farm/commands/spawn.js +575 -0
  35. package/dist/agent-farm/commands/spawn.js.map +1 -0
  36. package/dist/agent-farm/commands/start.d.ts +9 -0
  37. package/dist/agent-farm/commands/start.d.ts.map +1 -0
  38. package/dist/agent-farm/commands/start.js +175 -0
  39. package/dist/agent-farm/commands/start.js.map +1 -0
  40. package/dist/agent-farm/commands/status.d.ts +8 -0
  41. package/dist/agent-farm/commands/status.d.ts.map +1 -0
  42. package/dist/agent-farm/commands/status.js +123 -0
  43. package/dist/agent-farm/commands/status.js.map +1 -0
  44. package/dist/agent-farm/commands/stop.d.ts +8 -0
  45. package/dist/agent-farm/commands/stop.d.ts.map +1 -0
  46. package/dist/agent-farm/commands/stop.js +76 -0
  47. package/dist/agent-farm/commands/stop.js.map +1 -0
  48. package/dist/agent-farm/commands/tower.d.ts +19 -0
  49. package/dist/agent-farm/commands/tower.d.ts.map +1 -0
  50. package/dist/agent-farm/commands/tower.js +125 -0
  51. package/dist/agent-farm/commands/tower.js.map +1 -0
  52. package/dist/agent-farm/commands/tutorial.d.ts +10 -0
  53. package/dist/agent-farm/commands/tutorial.d.ts.map +1 -0
  54. package/dist/agent-farm/commands/tutorial.js +49 -0
  55. package/dist/agent-farm/commands/tutorial.js.map +1 -0
  56. package/dist/agent-farm/commands/util.d.ts +15 -0
  57. package/dist/agent-farm/commands/util.d.ts.map +1 -0
  58. package/dist/agent-farm/commands/util.js +108 -0
  59. package/dist/agent-farm/commands/util.js.map +1 -0
  60. package/dist/agent-farm/db/errors.d.ts +17 -0
  61. package/dist/agent-farm/db/errors.d.ts.map +1 -0
  62. package/dist/agent-farm/db/errors.js +46 -0
  63. package/dist/agent-farm/db/errors.js.map +1 -0
  64. package/dist/agent-farm/db/index.d.ts +41 -0
  65. package/dist/agent-farm/db/index.d.ts.map +1 -0
  66. package/dist/agent-farm/db/index.js +168 -0
  67. package/dist/agent-farm/db/index.js.map +1 -0
  68. package/dist/agent-farm/db/migrate.d.ts +15 -0
  69. package/dist/agent-farm/db/migrate.d.ts.map +1 -0
  70. package/dist/agent-farm/db/migrate.js +137 -0
  71. package/dist/agent-farm/db/migrate.js.map +1 -0
  72. package/dist/agent-farm/db/schema.d.ts +16 -0
  73. package/dist/agent-farm/db/schema.d.ts.map +1 -0
  74. package/dist/agent-farm/db/schema.js +103 -0
  75. package/dist/agent-farm/db/schema.js.map +1 -0
  76. package/dist/agent-farm/db/types.d.ts +87 -0
  77. package/dist/agent-farm/db/types.d.ts.map +1 -0
  78. package/dist/agent-farm/db/types.js +65 -0
  79. package/dist/agent-farm/db/types.js.map +1 -0
  80. package/dist/agent-farm/index.d.ts +7 -0
  81. package/dist/agent-farm/index.d.ts.map +1 -0
  82. package/dist/agent-farm/index.js +373 -0
  83. package/dist/agent-farm/index.js.map +1 -0
  84. package/dist/agent-farm/servers/annotate-server.d.ts +9 -0
  85. package/dist/agent-farm/servers/annotate-server.d.ts.map +1 -0
  86. package/dist/agent-farm/servers/annotate-server.js +136 -0
  87. package/dist/agent-farm/servers/annotate-server.js.map +1 -0
  88. package/dist/agent-farm/servers/dashboard-server.d.ts +9 -0
  89. package/dist/agent-farm/servers/dashboard-server.d.ts.map +1 -0
  90. package/dist/agent-farm/servers/dashboard-server.js +939 -0
  91. package/dist/agent-farm/servers/dashboard-server.js.map +1 -0
  92. package/dist/agent-farm/servers/tower-server.d.ts +9 -0
  93. package/dist/agent-farm/servers/tower-server.d.ts.map +1 -0
  94. package/dist/agent-farm/servers/tower-server.js +463 -0
  95. package/dist/agent-farm/servers/tower-server.js.map +1 -0
  96. package/dist/agent-farm/state.d.ts +93 -0
  97. package/dist/agent-farm/state.d.ts.map +1 -0
  98. package/dist/agent-farm/state.js +253 -0
  99. package/dist/agent-farm/state.js.map +1 -0
  100. package/dist/agent-farm/tutorial/index.d.ts +8 -0
  101. package/dist/agent-farm/tutorial/index.d.ts.map +1 -0
  102. package/dist/agent-farm/tutorial/index.js +8 -0
  103. package/dist/agent-farm/tutorial/index.js.map +1 -0
  104. package/dist/agent-farm/tutorial/prompts.d.ts +57 -0
  105. package/dist/agent-farm/tutorial/prompts.d.ts.map +1 -0
  106. package/dist/agent-farm/tutorial/prompts.js +147 -0
  107. package/dist/agent-farm/tutorial/prompts.js.map +1 -0
  108. package/dist/agent-farm/tutorial/runner.d.ts +52 -0
  109. package/dist/agent-farm/tutorial/runner.d.ts.map +1 -0
  110. package/dist/agent-farm/tutorial/runner.js +204 -0
  111. package/dist/agent-farm/tutorial/runner.js.map +1 -0
  112. package/dist/agent-farm/tutorial/state.d.ts +26 -0
  113. package/dist/agent-farm/tutorial/state.d.ts.map +1 -0
  114. package/dist/agent-farm/tutorial/state.js +89 -0
  115. package/dist/agent-farm/tutorial/state.js.map +1 -0
  116. package/dist/agent-farm/tutorial/steps/first-spec.d.ts +7 -0
  117. package/dist/agent-farm/tutorial/steps/first-spec.d.ts.map +1 -0
  118. package/dist/agent-farm/tutorial/steps/first-spec.js +136 -0
  119. package/dist/agent-farm/tutorial/steps/first-spec.js.map +1 -0
  120. package/dist/agent-farm/tutorial/steps/implementation.d.ts +7 -0
  121. package/dist/agent-farm/tutorial/steps/implementation.d.ts.map +1 -0
  122. package/dist/agent-farm/tutorial/steps/implementation.js +76 -0
  123. package/dist/agent-farm/tutorial/steps/implementation.js.map +1 -0
  124. package/dist/agent-farm/tutorial/steps/index.d.ts +10 -0
  125. package/dist/agent-farm/tutorial/steps/index.d.ts.map +1 -0
  126. package/dist/agent-farm/tutorial/steps/index.js +10 -0
  127. package/dist/agent-farm/tutorial/steps/index.js.map +1 -0
  128. package/dist/agent-farm/tutorial/steps/planning.d.ts +7 -0
  129. package/dist/agent-farm/tutorial/steps/planning.d.ts.map +1 -0
  130. package/dist/agent-farm/tutorial/steps/planning.js +143 -0
  131. package/dist/agent-farm/tutorial/steps/planning.js.map +1 -0
  132. package/dist/agent-farm/tutorial/steps/review.d.ts +7 -0
  133. package/dist/agent-farm/tutorial/steps/review.d.ts.map +1 -0
  134. package/dist/agent-farm/tutorial/steps/review.js +78 -0
  135. package/dist/agent-farm/tutorial/steps/review.js.map +1 -0
  136. package/dist/agent-farm/tutorial/steps/setup.d.ts +7 -0
  137. package/dist/agent-farm/tutorial/steps/setup.d.ts.map +1 -0
  138. package/dist/agent-farm/tutorial/steps/setup.js +126 -0
  139. package/dist/agent-farm/tutorial/steps/setup.js.map +1 -0
  140. package/dist/agent-farm/tutorial/steps/welcome.d.ts +7 -0
  141. package/dist/agent-farm/tutorial/steps/welcome.d.ts.map +1 -0
  142. package/dist/agent-farm/tutorial/steps/welcome.js +50 -0
  143. package/dist/agent-farm/tutorial/steps/welcome.js.map +1 -0
  144. package/dist/agent-farm/types.d.ts +131 -0
  145. package/dist/agent-farm/types.d.ts.map +1 -0
  146. package/dist/agent-farm/types.js +5 -0
  147. package/dist/agent-farm/types.js.map +1 -0
  148. package/dist/agent-farm/utils/config.d.ts +27 -0
  149. package/dist/agent-farm/utils/config.d.ts.map +1 -0
  150. package/dist/agent-farm/utils/config.js +242 -0
  151. package/dist/agent-farm/utils/config.js.map +1 -0
  152. package/dist/agent-farm/utils/deps.d.ts +51 -0
  153. package/dist/agent-farm/utils/deps.d.ts.map +1 -0
  154. package/dist/agent-farm/utils/deps.js +194 -0
  155. package/dist/agent-farm/utils/deps.js.map +1 -0
  156. package/dist/agent-farm/utils/index.d.ts +6 -0
  157. package/dist/agent-farm/utils/index.d.ts.map +1 -0
  158. package/dist/agent-farm/utils/index.js +6 -0
  159. package/dist/agent-farm/utils/index.js.map +1 -0
  160. package/dist/agent-farm/utils/logger.d.ts +31 -0
  161. package/dist/agent-farm/utils/logger.d.ts.map +1 -0
  162. package/dist/agent-farm/utils/logger.js +58 -0
  163. package/dist/agent-farm/utils/logger.js.map +1 -0
  164. package/dist/agent-farm/utils/orphan-handler.d.ts +27 -0
  165. package/dist/agent-farm/utils/orphan-handler.d.ts.map +1 -0
  166. package/dist/agent-farm/utils/orphan-handler.js +127 -0
  167. package/dist/agent-farm/utils/orphan-handler.js.map +1 -0
  168. package/dist/agent-farm/utils/port-registry.d.ts +58 -0
  169. package/dist/agent-farm/utils/port-registry.d.ts.map +1 -0
  170. package/dist/agent-farm/utils/port-registry.js +149 -0
  171. package/dist/agent-farm/utils/port-registry.js.map +1 -0
  172. package/dist/agent-farm/utils/shell.d.ts +45 -0
  173. package/dist/agent-farm/utils/shell.d.ts.map +1 -0
  174. package/dist/agent-farm/utils/shell.js +120 -0
  175. package/dist/agent-farm/utils/shell.js.map +1 -0
  176. package/dist/cli.d.ts +10 -0
  177. package/dist/cli.d.ts.map +1 -0
  178. package/dist/cli.js +160 -0
  179. package/dist/cli.js.map +1 -0
  180. package/dist/commands/adopt.d.ts +12 -0
  181. package/dist/commands/adopt.d.ts.map +1 -0
  182. package/dist/commands/adopt.js +178 -0
  183. package/dist/commands/adopt.js.map +1 -0
  184. package/dist/commands/consult/index.d.ts +17 -0
  185. package/dist/commands/consult/index.d.ts.map +1 -0
  186. package/dist/commands/consult/index.js +405 -0
  187. package/dist/commands/consult/index.js.map +1 -0
  188. package/dist/commands/doctor.d.ts +10 -0
  189. package/dist/commands/doctor.d.ts.map +1 -0
  190. package/dist/commands/doctor.js +346 -0
  191. package/dist/commands/doctor.js.map +1 -0
  192. package/dist/commands/init.d.ts +12 -0
  193. package/dist/commands/init.d.ts.map +1 -0
  194. package/dist/commands/init.js +167 -0
  195. package/dist/commands/init.js.map +1 -0
  196. package/dist/commands/tower.d.ts +16 -0
  197. package/dist/commands/tower.d.ts.map +1 -0
  198. package/dist/commands/tower.js +21 -0
  199. package/dist/commands/tower.js.map +1 -0
  200. package/dist/commands/update.d.ts +13 -0
  201. package/dist/commands/update.d.ts.map +1 -0
  202. package/dist/commands/update.js +137 -0
  203. package/dist/commands/update.js.map +1 -0
  204. package/dist/lib/templates.d.ts +57 -0
  205. package/dist/lib/templates.d.ts.map +1 -0
  206. package/dist/lib/templates.js +205 -0
  207. package/dist/lib/templates.js.map +1 -0
  208. package/package.json +55 -0
  209. package/templates/AGENTS.md +49 -0
  210. package/templates/CLAUDE.md +47 -0
  211. package/templates/DEPENDENCIES.md +344 -0
  212. package/templates/agents/architecture-documenter.md +189 -0
  213. package/templates/agents/codev-updater.md +276 -0
  214. package/templates/agents/spider-protocol-updater.md +118 -0
  215. package/templates/annotate.html +903 -0
  216. package/templates/bin/agent-farm +18 -0
  217. package/templates/bin/annotate-server.js +140 -0
  218. package/templates/bin/codev-doctor +335 -0
  219. package/templates/builders.md +30 -0
  220. package/templates/config.json +7 -0
  221. package/templates/dashboard-split.html +1679 -0
  222. package/templates/dashboard.html +149 -0
  223. package/templates/plans/.gitkeep +0 -0
  224. package/templates/protocols/experiment/protocol.md +229 -0
  225. package/templates/protocols/experiment/templates/notes.md +97 -0
  226. package/templates/protocols/maintain/protocol.md +235 -0
  227. package/templates/protocols/spider/protocol.md +639 -0
  228. package/templates/protocols/spider/templates/plan.md +169 -0
  229. package/templates/protocols/spider/templates/review.md +207 -0
  230. package/templates/protocols/spider/templates/spec.md +140 -0
  231. package/templates/protocols/spider-solo/protocol.md +619 -0
  232. package/templates/protocols/spider-solo/templates/plan.md +169 -0
  233. package/templates/protocols/spider-solo/templates/review.md +207 -0
  234. package/templates/protocols/spider-solo/templates/spec.md +140 -0
  235. package/templates/protocols/tick/protocol.md +250 -0
  236. package/templates/protocols/tick/templates/plan.md +67 -0
  237. package/templates/protocols/tick/templates/review.md +90 -0
  238. package/templates/protocols/tick/templates/spec.md +61 -0
  239. package/templates/reviews/.gitkeep +0 -0
  240. package/templates/roles/architect.md +230 -0
  241. package/templates/roles/builder.md +175 -0
  242. package/templates/roles/consultant.md +27 -0
  243. package/templates/specs/.gitkeep +0 -0
  244. package/templates/templates/projectlist.md +129 -0
  245. package/templates/tower.html +1032 -0
package/templates/dashboard.html ADDED
@@ -0,0 +1,149 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <title>AF: {{PROJECT_NAME}}</title>
5
+ <style>
6
+ * { box-sizing: border-box; margin: 0; padding: 0; }
7
+ body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; padding: 20px; background: #1a1a1a; color: #fff; }
8
+ h1 { margin-bottom: 20px; font-size: 24px; font-weight: 600; }
9
+ h2 { font-size: 16px; font-weight: 500; margin-bottom: 15px; color: #888; }
10
+
11
+ .layout { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; }
12
+ .layout.no-builders { grid-template-columns: 1fr; }
13
+
14
+ .architect-section { }
15
+ .builders-section { }
16
+
17
+ .terminal-card { background: #2a2a2a; border-radius: 8px; overflow: hidden; margin-bottom: 15px; }
18
+ .terminal-header { padding: 10px 15px; background: #333; display: flex; justify-content: space-between; align-items: center; }
19
+ .terminal-header h3 { font-size: 14px; font-weight: 500; }
20
+ .terminal-status { font-size: 12px; padding: 2px 8px; border-radius: 4px; font-weight: 500; }
21
+
22
+ .status-architect { background: #8b5cf6; }
23
+ .status-spawning { background: #6366f1; }
24
+ .status-implementing { background: #3b82f6; }
25
+ .status-blocked { background: #ef4444; }
26
+ .status-pr-ready { background: #22c55e; }
27
+ .status-reviewing { background: #f59e0b; }
28
+ .status-complete { background: #10b981; }
29
+
30
+ iframe { width: 100%; height: 500px; border: none; background: #000; }
31
+ .builders-section iframe { height: 400px; }
32
+
33
+ .no-terminal { text-align: center; padding: 60px 40px; color: #666; background: #2a2a2a; border-radius: 8px; }
34
+ .no-terminal code { background: #333; padding: 4px 8px; border-radius: 4px; font-size: 13px; }
35
+
36
+ .instructions { margin-top: 20px; padding: 15px; background: #2a2a2a; border-radius: 8px; font-size: 13px; }
37
+ .instructions code { background: #333; padding: 2px 6px; border-radius: 3px; }
38
+ .instructions strong { color: #888; }
39
+
40
+ .refresh-btn {
41
+ position: fixed; top: 20px; right: 20px;
42
+ background: #333; color: #fff; border: none; padding: 8px 16px;
43
+ border-radius: 6px; cursor: pointer; font-size: 13px;
44
+ }
45
+ .refresh-btn:hover { background: #444; }
46
+
47
+ .builder-grid { display: grid; grid-template-columns: 1fr; gap: 15px; }
48
+ @media (min-width: 1400px) {
49
+ .builder-grid { grid-template-columns: 1fr 1fr; }
50
+ .builders-section iframe { height: 350px; }
51
+ }
52
+ </style>
53
+ </head>
54
+ <body>
55
+ <button class="refresh-btn" onclick="location.reload()">Refresh</button>
56
+ <h1>Agent Farm - {{PROJECT_NAME}}</h1>
57
+
58
+ <div class="layout" id="layout">
59
+ <!-- Content inserted by JavaScript -->
60
+ </div>
61
+
62
+ <div class="instructions">
63
+ <strong>Commands:</strong>
64
+ <code>architect start</code> ·
65
+ <code>architect spawn --project XXXX</code> ·
66
+ <code>architect open XXXX FILE</code> ·
67
+ <code>architect stop</code>
68
+ </div>
69
+
70
+ <script>
71
+ // Configuration - updated by architect CLI
72
+ const architectPort = 7680;
73
+ const builders = [];
74
+
75
+ const layout = document.getElementById('layout');
76
+
77
+ // Check if architect console is running
78
+ const architectRunning = architectPort > 0;
79
+
80
+ // Build architect section
81
+ let architectHtml = '';
82
+ if (architectRunning) {
83
+ architectHtml = `
84
+ <div class="architect-section">
85
+ <h2>Architect Console</h2>
86
+ <div class="terminal-card">
87
+ <div class="terminal-header">
88
+ <h3>Architect</h3>
89
+ <span class="terminal-status status-architect">active</span>
90
+ </div>
91
+ <iframe src="http://localhost:${architectPort}" title="Architect Console" allow="clipboard-read; clipboard-write"></iframe>
92
+ </div>
93
+ </div>
94
+ `;
95
+ } else {
96
+ architectHtml = `
97
+ <div class="architect-section">
98
+ <h2>Architect Console</h2>
99
+ <div class="no-terminal">
100
+ <p style="margin-bottom: 15px;">Architect console not running.</p>
101
+ <p>Run <code>architect start</code> to begin.</p>
102
+ </div>
103
+ </div>
104
+ `;
105
+ }
106
+
107
+ // Build builders section
108
+ let buildersHtml = '';
109
+ if (builders.length > 0) {
110
+ buildersHtml = `
111
+ <div class="builders-section">
112
+ <h2>Builders (${builders.length})</h2>
113
+ <div class="builder-grid">
114
+ ${builders.map(b => {
115
+ const statusClass = 'status-' + b.status.replace(/[^a-z]/g, '');
116
+ return `
117
+ <div class="terminal-card">
118
+ <div class="terminal-header">
119
+ <h3>Builder ${b.id}: ${b.name}</h3>
120
+ <span class="terminal-status ${statusClass}">${b.status} (${b.phase})</span>
121
+ </div>
122
+ <iframe src="http://localhost:${b.port}" title="Builder ${b.id}" allow="clipboard-read; clipboard-write"></iframe>
123
+ </div>
124
+ `;
125
+ }).join('')}
126
+ </div>
127
+ </div>
128
+ `;
129
+ } else {
130
+ buildersHtml = `
131
+ <div class="builders-section">
132
+ <h2>Builders</h2>
133
+ <div class="no-terminal">
134
+ <p style="margin-bottom: 15px;">No active builders.</p>
135
+ <p>Run <code>architect spawn --project XXXX</code></p>
136
+ </div>
137
+ </div>
138
+ `;
139
+ }
140
+
141
+ // Adjust layout if no builders
142
+ if (builders.length === 0) {
143
+ layout.classList.add('no-builders');
144
+ }
145
+
146
+ layout.innerHTML = architectHtml + buildersHtml;
147
+ </script>
148
+ </body>
149
+ </html>
package/templates/plans/.gitkeep ADDED
File without changes
package/templates/protocols/experiment/protocol.md ADDED
@@ -0,0 +1,229 @@
1
+ # EXPERIMENT Protocol
2
+
3
+ ## Overview
4
+
5
+ Disciplined experimentation: Each experiment gets its own directory with `notes.md` tracking goals, code, and results.
6
+
7
+ **Core Principle**: Document what you're trying, what you did, and what you learned.
8
+
9
+ ## When to Use
10
+
11
+ **Use for**: Testing approaches, evaluating models, prototyping, proof-of-concept work, research spikes
12
+
13
+ **Skip for**: Production code (use SPIDER/SPIDER-SOLO), simple one-off scripts, well-understood implementations (use TICK)
14
+
15
+ ## Structure
16
+
17
+ ```
18
+ experiments/
19
+ ├── 0001_descriptive_name/
20
+ │ ├── notes.md # Goal, code, results
21
+ │ ├── experiment.py # Your experiment code
22
+ │ └── data/
23
+ │ ├── input/ # Input data
24
+ │ └── output/ # Results, plots, etc.
25
+ └── 0002_another_experiment/
26
+ ├── notes.md
27
+ └── ...
28
+ ```
29
+
30
+ ## Workflow
31
+
32
+ ### 1. Create Experiment Directory
33
+
34
+ ```bash
35
+ # Create numbered directory
36
+ mkdir -p experiments/0001_experiment_name
37
+ cd experiments/0001_experiment_name
38
+
39
+ # Initialize notes.md from template
40
+ cp codev/protocols/experiment/templates/notes.md notes.md
41
+ ```
42
+
43
+ Or ask your AI assistant: "Create a new experiment for [goal]"
44
+
45
+ ### 2. Document the Goal
46
+
47
+ Before writing code, clearly state what you're trying to learn in `notes.md`:
48
+
49
+ ```markdown
50
+ ## Goal
51
+
52
+ What specific question are you trying to answer?
53
+ What hypothesis are you testing?
54
+ ```
55
+
56
+ ### 3. Write Experiment Code
57
+
58
+ - Keep it simple - experiments don't need production polish
59
+ - Reuse existing project modules where possible
60
+ - Any structure is fine - focus on learning, not architecture
61
+
62
+ **Dependencies**: If your experiment requires libraries not in the main project:
63
+ 1. Do NOT add them to the main project's `requirements.txt` or `pyproject.toml`
64
+ 2. Create a `requirements.txt` inside your experiment folder
65
+ 3. Document installation in `notes.md`
66
+
67
+ ### 4. Run and Observe
68
+
69
+ Execute your experiment and capture results:
70
+ - Save output files to `data/output/`
71
+ - Take screenshots of visualizations
72
+ - Log key metrics
73
+
74
+ ### 5. Document Results
75
+
76
+ Update `notes.md` with:
77
+ - What happened (actual results)
78
+ - What you learned (insights)
79
+ - What's next (follow-up actions)
80
+
81
+ ### 6. Commit
82
+
83
+ ```bash
84
+ git add experiments/0001_experiment_name/
85
+ git commit -m "[Experiment 0001] Brief description of findings"
86
+ ```
87
+
88
+ ## notes.md Template
89
+
90
+ See `templates/notes.md` for the full template. Key sections:
91
+
92
+ ```markdown
93
+ # Experiment ####: Name
94
+
95
+ **Status**: In Progress | Complete | Disproved | Aborted
96
+
97
+ **Date**: YYYY-MM-DD
98
+
99
+ ## Goal
100
+ What are you trying to learn?
101
+
102
+ ## Time Investment
103
+ Wall clock time vs active developer time
104
+
105
+ ## Code
106
+ - [experiment.py](experiment.py) - Brief description
107
+
108
+ ## Results
109
+ What happened? What did you learn?
110
+
111
+ ## Next Steps
112
+ What should be done based on findings?
113
+ ```
114
+
115
+ ## Best Practices
116
+
117
+ ### Keep It Simple
118
+ - Experiments don't need production polish
119
+ - Skip comprehensive error handling
120
+ - Focus on answering the question
121
+
122
+ ### Document Honestly
123
+ - Include failures - they're valuable learnings
124
+ - Note dead ends and why they didn't work
125
+ - Be specific about what surprised you
126
+
127
+ ### Track Time Investment
128
+ - Wall clock time: Total elapsed time
129
+ - Developer time: Active working time (excluding waiting)
130
+ - Helps estimate future similar work
131
+
132
+ ### Use Project Modules
133
+ - Don't duplicate existing code
134
+ - Import from your `src/` directory
135
+ - Experiments validate approaches, not reimplement them
136
+
137
+ ### Commit Progress
138
+ - Use `[Experiment ####]` commit prefix
139
+ - Commit intermediate results
140
+ - Include output files when reasonable
141
+
142
+ ## Integration with Other Protocols
143
+
144
+ ### Experiment → SPIDER/SPIDER-SOLO
145
+ When an experiment validates an approach for production use:
146
+
147
+ 1. Create a specification referencing the experiment
148
+ 2. Link to experiment results as evidence
149
+ 3. Use experiment code as reference implementation
150
+
151
+ Example spec reference:
152
+ ```markdown
153
+ ## Background
154
+
155
+ Experiment 0005 validated that [approach] achieves [results].
156
+ See: experiments/0005_validation_test/notes.md
157
+ ```
158
+
159
+ ### Experiment → TICK
160
+ For small, validated changes discovered during experimentation:
161
+ - Use TICK for quick implementation
162
+ - Reference experiment as justification
163
+
164
+ ## Numbering Convention
165
+
166
+ Use four-digit sequential numbering (consistent with project list):
167
+ - `0001_`, `0002_`, `0003_`...
168
+ - Shared sequence across all experiments
169
+ - Descriptive name after the number (snake_case)
170
+
171
+ Examples:
172
+ - `0001_api_response_caching`
173
+ - `0002_model_comparison`
174
+ - `0003_performance_baseline`
175
+
176
+ ## Git Workflow
177
+
178
+ ### Commits
179
+ ```
180
+ [Experiment 0001] Initial setup and goal
181
+ [Experiment 0001] Add baseline measurements
182
+ [Experiment 0001] Complete - caching improves latency 40%
183
+ ```
184
+
185
+ ### When to Commit
186
+ - After setting up the experiment
187
+ - After significant findings
188
+ - When completing the experiment
189
+
190
+ **Data Management**:
191
+ - Include `data/output/` ONLY if files are small (summary metrics, small plots)
192
+ - Do NOT commit large datasets, binary model checkpoints, or heavy artifacts
193
+ - Add appropriate entries to `.gitignore` for large files
194
+ - Consider storing large outputs externally and linking in notes
195
+
196
+ ## Example Experiment
197
+
198
+ ```
199
+ experiments/0001_caching_strategy/
200
+ ├── notes.md
201
+ ├── benchmark.py
202
+ ├── cache_test.py
203
+ └── data/
204
+ ├── input/
205
+ │ └── sample_requests.json
206
+ └── output/
207
+ ├── results.csv
208
+ └── latency_chart.png
209
+ ```
210
+
211
+ **notes.md excerpt:**
212
+ ```markdown
213
+ # Experiment 0001: Caching Strategy Evaluation
214
+
215
+ **Status**: Complete
216
+
217
+ **Date**: 2024-01-15
218
+
219
+ ## Goal
220
+ Determine if Redis caching improves API response times for repeated queries.
221
+
222
+ ## Results
223
+ - 40% latency reduction for cached queries
224
+ - Cache hit rate: 73% after warm-up
225
+ - Memory usage: 50MB for 10k cached responses
226
+
227
+ ## Next Steps
228
+ Create SPIDER spec for production caching implementation.
229
+ ```
package/templates/protocols/experiment/templates/notes.md ADDED
@@ -0,0 +1,97 @@
1
+ # Experiment ####: Name
2
+
3
+ **Status**: In Progress | Complete | Disproved | Aborted
4
+
5
+ **Date**: YYYY-MM-DD
6
+
7
+ ## Goal
8
+
9
+ What are you trying to learn or test? Be specific about:
10
+ - The question you're answering
11
+ - The hypothesis you're testing
12
+ - Success criteria (how will you know if it worked?)
13
+
14
+ ## Effort
15
+
16
+ **Approximate time spent**: [e.g., "4 hours"]
17
+
18
+ *(Optional: Break down into setup, coding, analysis if helpful)*
19
+
20
+ ## Approach
21
+
22
+ Brief description of the approach being tested:
23
+ - Key technique or method
24
+ - Why this approach was chosen
25
+ - Any alternatives considered
26
+
27
+ ## Environment & Reproduction
28
+
29
+ **How to run**:
30
+ ```bash
31
+ # Command to reproduce results
32
+ python experiment.py --input data/input/sample.json
33
+ ```
34
+
35
+ **Dependencies** (if different from main project):
36
+ - List any additional packages required
37
+ - Or reference: `pip install -r requirements.txt`
38
+
39
+ **Environment notes**:
40
+ - Python version, key library versions if relevant
41
+ - Any seeds or configuration needed for reproducibility
42
+
43
+ ## Code
44
+
45
+ List your experiment files:
46
+ - [`experiment.py`](experiment.py) - Brief description
47
+ - [Other files as needed]
48
+
49
+ ## Results
50
+
51
+ ### Summary
52
+
53
+ One-paragraph summary of key findings.
54
+
55
+ ### Key Findings
56
+
57
+ 1. **Finding one**: Description and significance
58
+ 2. **Finding two**: Description and significance
59
+ 3. **Finding three**: Description and significance
60
+
61
+ ### Metrics
62
+
63
+ | Metric | Value | Notes |
64
+ |--------|-------|-------|
65
+ | Metric 1 | Value | Context |
66
+ | Metric 2 | Value | Context |
67
+
68
+ ### Output Files
69
+
70
+ - `data/output/results.csv` - Raw results data
71
+ - `data/output/chart.png` - Visualization of findings
72
+
73
+ ## What Worked
74
+
75
+ - List things that went well
76
+ - Approaches that proved effective
77
+ - Useful discoveries
78
+
79
+ ## What Didn't Work
80
+
81
+ - Failed approaches (and why)
82
+ - Dead ends encountered
83
+ - Surprising obstacles
84
+
85
+ ## Next Steps
86
+
87
+ Based on these findings:
88
+
89
+ 1. **Immediate**: What should happen right after this experiment?
90
+ 2. **Follow-up experiments**: What new questions emerged?
91
+ 3. **Production path**: If validated, what's needed for production? (SPIDER spec?)
92
+
93
+ ## References
94
+
95
+ - Links to relevant documentation
96
+ - Related experiments
97
+ - External resources consulted
package/templates/protocols/maintain/protocol.md ADDED
@@ -0,0 +1,235 @@
1
+ # MAINTAIN Protocol
2
+
3
+ ## Overview
4
+
5
+ MAINTAIN is a periodic maintenance protocol for keeping codebases healthy. Unlike SPIDER/TICK (which have sequential phases), MAINTAIN is a **task list** where tasks can run in parallel and some require human review.
6
+
7
+ **Core Principle**: Regular maintenance prevents technical debt accumulation.
8
+
9
+ ## When to Use MAINTAIN
10
+
11
+ ### Triggers
12
+ - Before a release (clean slate for shipping)
13
+ - Quarterly maintenance window
14
+ - After completing a major feature
15
+ - When the codebase feels "crusty"
16
+ - Before major refactoring efforts
17
+
18
+ ### Skip MAINTAIN for
19
+ - Active development branches with pending PRs
20
+ - Emergency production issues
21
+ - When tests are failing (fix tests first)
22
+
23
+ ## Execution Model
24
+
25
+ MAINTAIN is executed by a Builder, spawned by the Architect:
26
+
27
+ ```
28
+ Architect: "Time for maintenance"
29
+ ↓
30
+ af spawn --protocol maintain
31
+ ↓
32
+ Builder works through task list
33
+ ↓
34
+ PR with maintenance changes
35
+ ↓
36
+ Architect reviews → Builder merges
37
+ ```
38
+
39
+ ## Prerequisites
40
+
41
+ Before starting MAINTAIN:
42
+ - [ ] Git working directory is clean
43
+ - [ ] All tests are passing
44
+ - [ ] No pending merges or PRs in flight
45
+
46
+ ---
47
+
48
+ ## Task List
49
+
50
+ ### Code Hygiene Tasks
51
+
52
+ | Task | Parallelizable | Human Review? | Description |
53
+ |------|----------------|---------------|-------------|
54
+ | Remove dead code | Yes | No | Delete unused functions, imports, unreachable code |
55
+ | Remove unused dependencies | Yes | Yes | Check package.json/requirements.txt for unused packages |
56
+ | Clean unused flags | Yes | No | Remove feature flags that are always on/off |
57
+ | Fix flaky tests | No | Yes | Investigate and fix intermittently failing tests |
58
+ | Update outdated dependencies | Yes | Yes | Bump dependencies with breaking change review |
59
+
60
+ **Tools**:
61
+ ```bash
62
+ # TypeScript/JavaScript
63
+ npx ts-prune # Find unused exports
64
+ npx depcheck # Find unused dependencies
65
+
66
+ # Python
67
+ ruff check --select F401 # Find unused imports
68
+ ```
69
+
70
+ ### Documentation Sync Tasks
71
+
72
+ | Task | Parallelizable | Human Review? | Description |
73
+ |------|----------------|---------------|-------------|
74
+ | Update arch.md | Yes | No | Sync architecture doc with actual codebase |
75
+ | Generate lessons-learned.md | Yes | Yes | Extract wisdom from review documents |
76
+ | Sync CLAUDE.md ↔ AGENTS.md | Yes | No | Ensure both files match |
77
+ | Check spec/plan/review consistency | Yes | Yes | Find specs without reviews, plans that don't match code |
78
+ | Remove stale doc references | Yes | No | Delete references to deleted code/files |
79
+
80
+ ### Project Tracking Tasks
81
+
82
+ | Task | Parallelizable | Human Review? | Description |
83
+ |------|----------------|---------------|-------------|
84
+ | Update projectlist.md status | Yes | No | Update project statuses |
85
+ | Archive terminal projects | Yes | No | Move completed/abandoned to terminal section |
86
+
87
+ ---
88
+
89
+ ## Task Details
90
+
91
+ ### Update arch.md
92
+
93
+ Scan the actual codebase and update `codev/resources/arch.md`:
94
+
95
+ 1. Verify directory structure matches documented structure
96
+ 2. Update component descriptions
97
+ 3. Add new utilities/helpers discovered
98
+ 4. Remove references to deleted code
99
+ 5. Update technology stack if changed
100
+
101
+ ### Generate lessons-learned.md
102
+
103
+ Extract actionable wisdom from review documents into `codev/resources/lessons-learned.md`:
104
+
105
+ 1. Read all files in `codev/reviews/`
106
+ 2. Extract lessons that are:
107
+ - Actionable (not just "we learned X")
108
+ - Durable (still relevant)
109
+ - General (applicable beyond one project)
110
+ 3. Organize by topic (Testing, Architecture, Process, etc.)
111
+ 4. Link back to source review
112
+ 5. Prune outdated lessons
113
+
114
+ **Template**:
115
+ ```markdown
116
+ # Lessons Learned
117
+
118
+ ## Testing
119
+ - [From 0001] Always use XDG sandboxing in tests to avoid touching real $HOME
120
+ - [From 0009] Verify dependencies actually export what you expect
121
+
122
+ ## Architecture
123
+ - [From 0008] Single source of truth beats distributed state
124
+ - [From 0031] SQLite with WAL mode handles concurrency better than JSON files
125
+
126
+ ## Process
127
+ - [From 0001] Multi-agent consultation catches issues humans miss
128
+ ```
129
+
130
+ ### Sync CLAUDE.md ↔ AGENTS.md
131
+
132
+ Ensure both instruction files contain the same content:
133
+
134
+ 1. Diff the two files
135
+ 2. Identify divergence
136
+ 3. Update the stale one to match
137
+ 4. Both should be identical (per AGENTS.md standard)
138
+
139
+ ### Remove Dead Code
140
+
141
+ Use static analysis to find and remove unused code:
142
+
143
+ 1. Run analysis tools (ts-prune, depcheck, ruff)
144
+ 2. Review findings for false positives
145
+ 3. Use `git rm` to remove confirmed dead code
146
+ 4. Commit with descriptive message
147
+
148
+ **Important**: Use `git rm`, not `rm`. Git history preserves deleted files.
149
+
150
+ ### Update Dependencies
151
+
152
+ Review and update outdated dependencies:
153
+
154
+ 1. Run `npm outdated` or equivalent
155
+ 2. Categorize updates:
156
+ - Patch: Safe to auto-update
157
+ - Minor: Review changelog
158
+ - Major: Requires human review for breaking changes
159
+ 3. Update and test
160
+ 4. Document any migration steps
161
+
162
+ ---
163
+
164
+ ## Validation
165
+
166
+ After completing tasks, validate the codebase:
167
+
168
+ - [ ] All tests pass
169
+ - [ ] Build succeeds
170
+ - [ ] No import/module errors
171
+ - [ ] Documentation links resolve
172
+ - [ ] Linter passes
173
+
174
+ If validation fails, investigate and fix before creating PR.
175
+
176
+ ---
177
+
178
+ ## Rollback Strategy
179
+
180
+ ### For code changes
181
+ ```bash
182
+ # Git history preserves everything
183
+ git log --all --full-history -- path/to/file
184
+ git checkout <commit>~1 -- path/to/file
185
+ ```
186
+
187
+ ### For untracked files
188
+ Move to `codev/maintain/.trash/YYYY-MM-DD/` before deleting. Retained for 30 days.
189
+
190
+ ---
191
+
192
+ ## Commit Messages
193
+
194
+ ```
195
+ [Maintain] Remove 5 unused exports
196
+ [Maintain] Update arch.md with new utilities
197
+ [Maintain] Generate lessons-learned.md
198
+ [Maintain] Sync CLAUDE.md with AGENTS.md
199
+ [Maintain] Update dependencies (patch)
200
+ ```
201
+
202
+ ---
203
+
204
+ ## Governance
205
+
206
+ MAINTAIN is an **operational protocol**, not a feature development protocol:
207
+
208
+ | Document | Required? |
209
+ |----------|-----------|
210
+ | Spec | No |
211
+ | Plan | No |
212
+ | Review | No |
213
+ | Consultation | No (human review of PR is sufficient) |
214
+
215
+ **Exception**: If MAINTAIN reveals need for architectural changes, those should follow SPIDER.
216
+
217
+ ---
218
+
219
+ ## Best Practices
220
+
221
+ 1. **Don't be aggressive**: When in doubt, keep the code
222
+ 2. **Check git blame**: Understand why code exists before deleting
223
+ 3. **Run full test suite**: Not just affected tests
224
+ 4. **Group related changes**: One commit per logical change
225
+ 5. **Document decisions**: Note why things were kept or removed
226
+
227
+ ---
228
+
229
+ ## Anti-Patterns
230
+
231
+ 1. **Deleting everything the audit finds**: Review each item
232
+ 2. **Skipping validation**: "It looked dead" is not validation
233
+ 3. **Using `rm` instead of `git rm`**: Lose history
234
+ 4. **Maintaining during active development**: Wait for PRs to merge
235
+ 5. **Ignoring false positives**: Fix audit logic if it's wrong