devmind 1.1.0 → 1.1.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.
Files changed (55) hide show
  1. package/README.md +13 -1
  2. package/dist/cli/handlers.js +1 -1
  3. package/dist/cli/handlers.js.map +1 -1
  4. package/dist/cli/register-database.js +4 -0
  5. package/dist/cli/register-database.js.map +1 -1
  6. package/dist/codebase/generators/architecture-extractor.d.ts +41 -0
  7. package/dist/codebase/generators/architecture-extractor.js +388 -0
  8. package/dist/codebase/generators/architecture-extractor.js.map +1 -0
  9. package/dist/codebase/generators/architecture.d.ts +2 -4
  10. package/dist/codebase/generators/architecture.js +123 -30
  11. package/dist/codebase/generators/architecture.js.map +1 -1
  12. package/dist/codebase/generators/modules.js +8 -8
  13. package/dist/codebase/generators/overview.js +24 -24
  14. package/dist/codebase/index.js +1 -1
  15. package/dist/codebase/index.js.map +1 -1
  16. package/dist/codebase/parsers/typescript.js +9 -0
  17. package/dist/codebase/parsers/typescript.js.map +1 -1
  18. package/dist/codebase/scanners/filesystem.js +1 -4
  19. package/dist/codebase/scanners/filesystem.js.map +1 -1
  20. package/dist/commands/analyze.js +7 -1
  21. package/dist/commands/analyze.js.map +1 -1
  22. package/dist/commands/audit-design.js.map +1 -1
  23. package/dist/commands/audit-report.js.map +1 -1
  24. package/dist/commands/audit-source.js +3 -1
  25. package/dist/commands/audit-source.js.map +1 -1
  26. package/dist/commands/audit.js.map +1 -1
  27. package/dist/commands/claude-plugin.js.map +1 -1
  28. package/dist/commands/codex-plugin.js.map +1 -1
  29. package/dist/commands/design-system.js.map +1 -1
  30. package/dist/commands/extract.js +4 -1
  31. package/dist/commands/extract.js.map +1 -1
  32. package/dist/commands/retrieve.js +6 -2
  33. package/dist/commands/retrieve.js.map +1 -1
  34. package/dist/commands/status.js.map +1 -1
  35. package/dist/core/source-file-cache.js +4 -1
  36. package/dist/core/source-file-cache.js.map +1 -1
  37. package/dist/database/cli/register-database.js +4 -0
  38. package/dist/database/cli/register-database.js.map +1 -1
  39. package/dist/database/commands/generate.d.ts +1 -0
  40. package/dist/database/commands/generate.js +23 -14
  41. package/dist/database/commands/generate.js.map +1 -1
  42. package/dist/database/commands/handoff.js +123 -123
  43. package/dist/database/commands/handoff.js.map +1 -1
  44. package/dist/database/commands/learn.js +5 -1
  45. package/dist/database/commands/learn.js.map +1 -1
  46. package/dist/database/commands/memory.js +113 -113
  47. package/dist/database/commands/watch.js +1 -1
  48. package/dist/database/commands/watch.js.map +1 -1
  49. package/dist/database/extractors/mysql.js +45 -45
  50. package/dist/database/extractors/postgres.js +54 -54
  51. package/dist/database/extractors/sqlite.js +8 -8
  52. package/dist/database/generators/templates.js +520 -520
  53. package/dist/generators/unified.js +4 -3
  54. package/dist/generators/unified.js.map +1 -1
  55. package/package.json +85 -77
@@ -727,27 +727,27 @@ export class TemplateGenerator {
727
727
  return output;
728
728
  }
729
729
  generateTransactionPatterns() {
730
- return `-- Transaction Examples
731
- -- Use transactions for atomic operations
732
-
733
- BEGIN TRANSACTION;
734
-
735
- -- 1. Create parent record
736
- INSERT INTO orders (user_id, total, status)
737
- VALUES ($1, $2, 'pending')
738
- RETURNING id;
739
-
740
- -- 2. Create child records
741
- INSERT INTO order_items (order_id, product_id, quantity, price)
742
- VALUES
743
- ($3, $4, $5, $6),
744
- ($3, $7, $8, $9);
745
-
746
- -- 3. Update inventory
747
- UPDATE products SET stock = stock - $5 WHERE id = $4;
748
- UPDATE products SET stock = stock - $8 WHERE id = $7;
749
-
750
- COMMIT;
730
+ return `-- Transaction Examples
731
+ -- Use transactions for atomic operations
732
+
733
+ BEGIN TRANSACTION;
734
+
735
+ -- 1. Create parent record
736
+ INSERT INTO orders (user_id, total, status)
737
+ VALUES ($1, $2, 'pending')
738
+ RETURNING id;
739
+
740
+ -- 2. Create child records
741
+ INSERT INTO order_items (order_id, product_id, quantity, price)
742
+ VALUES
743
+ ($3, $4, $5, $6),
744
+ ($3, $7, $8, $9);
745
+
746
+ -- 3. Update inventory
747
+ UPDATE products SET stock = stock - $5 WHERE id = $4;
748
+ UPDATE products SET stock = stock - $8 WHERE id = $7;
749
+
750
+ COMMIT;
751
751
  `;
752
752
  }
753
753
  // ============================================================================
@@ -879,51 +879,51 @@ COMMIT;
879
879
  generateEdgeCasesTest(schema) {
880
880
  const tableName = schema.tables[0]?.name || 'table_name';
881
881
  const pk = schema.tables[0]?.primaryKey || 'id';
882
- return `/**
883
- * Edge Case Tests for ${tableName}
884
- * AUTO-GENERATED by cohere
885
- */
886
-
887
- describe('${tableName} Edge Cases', () => {
888
- const orgId = 'test-org-id';
889
-
890
- describe('Empty Result Sets', () => {
891
- test('SELECT returns empty array when no rows match', async () => {
892
- const result = await query(
893
- 'SELECT * FROM ${tableName} WHERE id = $1 AND organization_id = $2',
894
- ['nonexistent-id', orgId]
895
- );
896
- expect(result.rows).toEqual([]);
897
- });
898
- });
899
-
900
- describe('Primary Key Edge Cases', () => {
901
- test('INSERT fails on duplicate primary key', async () => {
902
- await expect(query(
903
- 'INSERT INTO ${tableName} (id) VALUES ($1)',
904
- ['existing-id']
905
- )).rejects.toThrow('duplicate_key');
906
- });
907
-
908
- test('UPDATE modifies correct row', async () => {
909
- const result = await query(
910
- 'UPDATE ${tableName} SET updated_at = NOW() WHERE id = $1 AND organization_id = $2 RETURNING id',
911
- ['target-id', orgId]
912
- );
913
- expect(result.rowCount).toBe(1);
914
- });
915
- });
916
-
917
- describe('Soft Delete Edge Cases', () => {
918
- test('SELECT excludes soft-deleted records by default', async () => {
919
- const result = await query(
920
- 'SELECT * FROM ${tableName} WHERE organization_id = $1',
921
- [orgId]
922
- );
923
- expect(result.rows.every(r => r.deleted_at === null)).toBe(true);
924
- });
925
- });
926
- });
882
+ return `/**
883
+ * Edge Case Tests for ${tableName}
884
+ * AUTO-GENERATED by cohere
885
+ */
886
+
887
+ describe('${tableName} Edge Cases', () => {
888
+ const orgId = 'test-org-id';
889
+
890
+ describe('Empty Result Sets', () => {
891
+ test('SELECT returns empty array when no rows match', async () => {
892
+ const result = await query(
893
+ 'SELECT * FROM ${tableName} WHERE id = $1 AND organization_id = $2',
894
+ ['nonexistent-id', orgId]
895
+ );
896
+ expect(result.rows).toEqual([]);
897
+ });
898
+ });
899
+
900
+ describe('Primary Key Edge Cases', () => {
901
+ test('INSERT fails on duplicate primary key', async () => {
902
+ await expect(query(
903
+ 'INSERT INTO ${tableName} (id) VALUES ($1)',
904
+ ['existing-id']
905
+ )).rejects.toThrow('duplicate_key');
906
+ });
907
+
908
+ test('UPDATE modifies correct row', async () => {
909
+ const result = await query(
910
+ 'UPDATE ${tableName} SET updated_at = NOW() WHERE id = $1 AND organization_id = $2 RETURNING id',
911
+ ['target-id', orgId]
912
+ );
913
+ expect(result.rowCount).toBe(1);
914
+ });
915
+ });
916
+
917
+ describe('Soft Delete Edge Cases', () => {
918
+ test('SELECT excludes soft-deleted records by default', async () => {
919
+ const result = await query(
920
+ 'SELECT * FROM ${tableName} WHERE organization_id = $1',
921
+ [orgId]
922
+ );
923
+ expect(result.rows.every(r => r.deleted_at === null)).toBe(true);
924
+ });
925
+ });
926
+ });
927
927
  `;
928
928
  }
929
929
  generateCRUDEdgeCases(schema) {
@@ -939,20 +939,20 @@ describe('${tableName} Edge Cases', () => {
939
939
  ? " const orgId = 'test-org-id';"
940
940
  : ' // No organization_id column in this table';
941
941
  const softDeleteTest = table.columns.some((c) => c.name === 'deleted_at')
942
- ? `
943
- test('Soft-deleted records are excluded by default', async () => {
944
- const result = await query('SELECT * FROM ' + table.name);
945
- expect(result.rows.every(r => r.deleted_at === null)).toBe(true);
942
+ ? `
943
+ test('Soft-deleted records are excluded by default', async () => {
944
+ const result = await query('SELECT * FROM ' + table.name);
945
+ expect(result.rows.every(r => r.deleted_at === null)).toBe(true);
946
946
  });`
947
947
  : '';
948
948
  const updateTest = table.primaryKey.length > 0
949
- ? `
950
- test('UPDATE with valid ' + table.primaryKey[0] + ' succeeds', async () => {
951
- const result = await query(
952
- 'UPDATE ' + table.name + ' SET updated_at = NOW() WHERE id = $1 RETURNING id',
953
- ['test-id']
954
- );
955
- expect(result.rowCount).toBeGreaterThanOrEqual(0);
949
+ ? `
950
+ test('UPDATE with valid ' + table.primaryKey[0] + ' succeeds', async () => {
951
+ const result = await query(
952
+ 'UPDATE ' + table.name + ' SET updated_at = NOW() WHERE id = $1 RETURNING id',
953
+ ['test-id']
954
+ );
955
+ expect(result.rowCount).toBeGreaterThanOrEqual(0);
956
956
  });`
957
957
  : '';
958
958
  return ('/**\n' +
@@ -1088,266 +1088,266 @@ describe('${tableName} Edge Cases', () => {
1088
1088
  }
1089
1089
  generateHandoffTemplate(schema) {
1090
1090
  const tablesList = schema.tables.map((t) => `- \`${t.name}\``).join('\n');
1091
- return `# Agent Handoff Record
1092
-
1093
- > AUTO-GENERATED by cohere. Read this before continuing.
1094
-
1095
- ## Session Info
1096
-
1097
- | Field | Value |
1098
- |-------|-------|
1099
- | **Agent ID** | \`{agentId}\` |
1100
- | **Session ID** | \`{sessionId}\` |
1101
- | **Timestamp** | \`{timestamp}\` |
1102
- | **Duration** | \`{duration}\` |
1103
- | **Status** | \`{status}\` |
1104
-
1105
- ---
1106
-
1107
- ## What Was Attempted
1108
-
1109
- ### Goals
1110
- - Goal 1
1111
- - Goal 2
1112
- - Goal 3
1113
-
1114
- ### Actions Taken
1115
-
1116
- | Step | Action | Result |
1117
- |------|--------|--------|
1118
- | 1 | Action description | ✅ Success / ❌ Failed |
1119
- | 2 | Action description | ✅ Success / ❌ Failed |
1120
- | 3 | Action description | ⏸️ Paused |
1121
-
1122
- ---
1123
-
1124
- ## What Succeeded
1125
-
1126
- - ✅ Success item 1
1127
- - ✅ Success item 2
1128
-
1129
- ---
1130
-
1131
- ## What Failed
1132
-
1133
- - ❌ Failed item 1
1134
- - ❌ Failed item 2 with error: \`{error}\`
1135
-
1136
- ### Error Details
1137
- \`\`\`
1138
- {errorStackTrace}
1139
- \`\`\`
1140
-
1141
- ### Recovery Attempts
1142
- 1. Attempt 1: Result
1143
- 2. Attempt 2: Result
1144
-
1145
- ---
1146
-
1147
- ## Decisions Made
1148
-
1149
- | Decision ID | Choice | Rationale |
1150
- |-------------|--------|-----------|
1151
- | DECISION_001 | Choice A | Rationale |
1152
- | DECISION_002 | Choice B | Rationale |
1153
-
1154
- > See \`.ai/decisions/\` for detailed decision logs.
1155
-
1156
- ---
1157
-
1158
- ## Current State
1159
-
1160
- ### Last Completed Step
1161
- \`\`\`
1162
- {lastCompletedStep}
1163
- \`\`\`
1164
-
1165
- ### Pending Work
1166
- - [ ] Pending item 1
1167
- - [ ] Pending item 2
1168
-
1169
- ### Known Issues
1170
- - Issue 1: Description
1171
- - Issue 2: Description
1172
-
1173
- ---
1174
-
1175
- ## Context for Next Agent
1176
-
1177
- ### Variables
1178
- \`\`\`json
1179
- {variablesJson}
1180
- \`\`\`
1181
-
1182
- ### Schema State
1183
- - Tables modified: {modifiedTables}
1184
- - New relationships: {newRelationships}
1185
-
1186
- ### Tables in Scope
1187
- ${tablesList}
1188
-
1189
- ---
1190
-
1191
- ## Next Steps
1192
-
1193
- ### Immediate Actions
1194
- 1. Next action 1
1195
- 2. Next action 2
1196
-
1197
- ### Recommended Approach
1198
- \`\`\`
1199
- {recommendedApproach}
1200
- \`\`\`
1201
-
1202
- ### Expected Duration
1203
- - \`{estimatedDuration}\`
1204
-
1205
- ---
1206
-
1207
- ## Files Generated
1208
-
1209
- | File | Purpose |
1210
- |------|---------|
1211
- | \`.ai/state/CURRENT_STATE.md\` | Progress snapshot |
1212
- | \`.ai/context/SESSION_CONTEXT.json\` | Machine-readable state |
1213
- | \`.ai/decisions/\` | Decision logs |
1214
-
1215
- ---
1216
-
1217
- > **PROTOCOL**: Before spawning subagents:
1218
- > 1. Generate handoff file
1219
- > 2. Pass handoff to next agent
1220
- > 3. Next agent reads \`.ai/state/CURRENT_STATE.md\` first
1091
+ return `# Agent Handoff Record
1092
+
1093
+ > AUTO-GENERATED by cohere. Read this before continuing.
1094
+
1095
+ ## Session Info
1096
+
1097
+ | Field | Value |
1098
+ |-------|-------|
1099
+ | **Agent ID** | \`{agentId}\` |
1100
+ | **Session ID** | \`{sessionId}\` |
1101
+ | **Timestamp** | \`{timestamp}\` |
1102
+ | **Duration** | \`{duration}\` |
1103
+ | **Status** | \`{status}\` |
1104
+
1105
+ ---
1106
+
1107
+ ## What Was Attempted
1108
+
1109
+ ### Goals
1110
+ - Goal 1
1111
+ - Goal 2
1112
+ - Goal 3
1113
+
1114
+ ### Actions Taken
1115
+
1116
+ | Step | Action | Result |
1117
+ |------|--------|--------|
1118
+ | 1 | Action description | ✅ Success / ❌ Failed |
1119
+ | 2 | Action description | ✅ Success / ❌ Failed |
1120
+ | 3 | Action description | ⏸️ Paused |
1121
+
1122
+ ---
1123
+
1124
+ ## What Succeeded
1125
+
1126
+ - ✅ Success item 1
1127
+ - ✅ Success item 2
1128
+
1129
+ ---
1130
+
1131
+ ## What Failed
1132
+
1133
+ - ❌ Failed item 1
1134
+ - ❌ Failed item 2 with error: \`{error}\`
1135
+
1136
+ ### Error Details
1137
+ \`\`\`
1138
+ {errorStackTrace}
1139
+ \`\`\`
1140
+
1141
+ ### Recovery Attempts
1142
+ 1. Attempt 1: Result
1143
+ 2. Attempt 2: Result
1144
+
1145
+ ---
1146
+
1147
+ ## Decisions Made
1148
+
1149
+ | Decision ID | Choice | Rationale |
1150
+ |-------------|--------|-----------|
1151
+ | DECISION_001 | Choice A | Rationale |
1152
+ | DECISION_002 | Choice B | Rationale |
1153
+
1154
+ > See \`.ai/decisions/\` for detailed decision logs.
1155
+
1156
+ ---
1157
+
1158
+ ## Current State
1159
+
1160
+ ### Last Completed Step
1161
+ \`\`\`
1162
+ {lastCompletedStep}
1163
+ \`\`\`
1164
+
1165
+ ### Pending Work
1166
+ - [ ] Pending item 1
1167
+ - [ ] Pending item 2
1168
+
1169
+ ### Known Issues
1170
+ - Issue 1: Description
1171
+ - Issue 2: Description
1172
+
1173
+ ---
1174
+
1175
+ ## Context for Next Agent
1176
+
1177
+ ### Variables
1178
+ \`\`\`json
1179
+ {variablesJson}
1180
+ \`\`\`
1181
+
1182
+ ### Schema State
1183
+ - Tables modified: {modifiedTables}
1184
+ - New relationships: {newRelationships}
1185
+
1186
+ ### Tables in Scope
1187
+ ${tablesList}
1188
+
1189
+ ---
1190
+
1191
+ ## Next Steps
1192
+
1193
+ ### Immediate Actions
1194
+ 1. Next action 1
1195
+ 2. Next action 2
1196
+
1197
+ ### Recommended Approach
1198
+ \`\`\`
1199
+ {recommendedApproach}
1200
+ \`\`\`
1201
+
1202
+ ### Expected Duration
1203
+ - \`{estimatedDuration}\`
1204
+
1205
+ ---
1206
+
1207
+ ## Files Generated
1208
+
1209
+ | File | Purpose |
1210
+ |------|---------|
1211
+ | \`.ai/state/CURRENT_STATE.md\` | Progress snapshot |
1212
+ | \`.ai/context/SESSION_CONTEXT.json\` | Machine-readable state |
1213
+ | \`.ai/decisions/\` | Decision logs |
1214
+
1215
+ ---
1216
+
1217
+ > **PROTOCOL**: Before spawning subagents:
1218
+ > 1. Generate handoff file
1219
+ > 2. Pass handoff to next agent
1220
+ > 3. Next agent reads \`.ai/state/CURRENT_STATE.md\` first
1221
1221
  `;
1222
1222
  }
1223
1223
  generateMultiAgentProtocol(schema) {
1224
1224
  const tablesList = schema.tables.map((t) => t.name).join(', ');
1225
- return `# Multi-Agent Protocol
1226
-
1227
- > AUTO-GENERATED by cohere. Protocol for agent-to-agent handoff.
1228
-
1229
- ## Overview
1230
-
1231
- This document defines the protocol for safe handoff between AI agents working on the same codebase.
1232
-
1233
- ## Protocol Steps
1234
-
1235
- ### 1. Pre-Handoff (Current Agent)
1236
-
1237
- Before ending your session:
1238
-
1239
- \`\`\`bash
1240
- cohere-db handoff --record --status {status} --agentId {agentId}
1241
- \`\`\`
1242
-
1243
- This creates:
1244
- - \`.ai/handoffs/HANDOFF_<timestamp>.md\` - Full handoff record
1245
- - \`.ai/state/CURRENT_STATE.md\` - Current progress snapshot
1246
- - \`.ai/context/SESSION_CONTEXT.json\` - Machine-readable state
1247
-
1248
- ### 2. Handoff Transfer
1249
-
1250
- Share these files with the next agent:
1251
- - Handoff file location
1252
- - Session context JSON
1253
- - Any modified files
1254
-
1255
- ### 3. Post-Handoff (Next Agent)
1256
-
1257
- On receiving handoff:
1258
-
1259
- \`\`\`bash
1260
- # List available sessions
1261
- cohere-db handoff --list
1262
-
1263
- # Resume specific session
1264
- cohere-db handoff --resume <session_id>
1265
-
1266
- # Read state first
1267
- cat .ai/state/CURRENT_STATE.md
1268
- \`\`\`
1269
-
1270
- ---
1271
-
1272
- ## State Files
1273
-
1274
- ### CURRENT_STATE.md
1275
-
1276
- | Section | Purpose |
1277
- |---------|---------|
1278
- | Session Status | Agent ID, timestamp, status |
1279
- | Progress | Completed steps, current step, remaining |
1280
- | Work Queue | Pending tasks, blocked tasks |
1281
- | Variables | Key state variables |
1282
- | Checkpoints | Saved checkpoints |
1283
-
1284
- ### SESSION_CONTEXT.json
1285
-
1286
- Machine-readable state for programmatic access:
1287
-
1288
- \`\`\`json
1289
- {
1290
- "session": { "id", "agentId", "status" },
1291
- "state": { "phase", "progress" },
1292
- "variables": { /* key-value pairs */ },
1293
- "schema": { "databaseType", "tablesModified" },
1294
- "decisions": [ { "id", "title", "choice" } ]
1295
- }
1296
- \`\`\`
1297
-
1298
- ---
1299
-
1300
- ## Tables in Scope
1301
-
1302
- ${tablesList}
1303
-
1304
- ---
1305
-
1306
- ## Constraints
1307
-
1308
- | Constraint | Value |
1309
- |------------|-------|
1310
- | Max handoff size | 10KB |
1311
- | Checkpoint interval | 5 minutes |
1312
- | Decision logging | Required for major choices |
1313
-
1314
- ---
1315
-
1316
- ## CLI Commands
1317
-
1318
- | Command | Description |
1319
- |---------|-------------|
1320
- | \`cohere-db handoff --record\` | Record current session |
1321
- | \`cohere-db handoff --list\` | List available sessions |
1322
- | \`cohere-db handoff --resume <id>\` | Resume from session |
1323
- | \`cohere-db handoff --status completed\` | Mark session complete |
1324
-
1325
- ---
1326
-
1327
- ## Best Practices
1328
-
1329
- 1. **Checkpoint frequently** - Save state every 5-10 minutes
1330
- 2. **Log decisions** - Use decision IDs in handoffs
1331
- 3. **Document failures** - Include error context in handoff
1332
- 4. **Atomic handoffs** - Complete handoff before ending session
1333
-
1334
- ---
1335
-
1336
- ## Example Flow
1337
-
1338
- \`\`\`
1339
- Agent A (in progress)
1340
- ↓
1341
- cohere-db handoff --record --status paused
1342
- ↓
1343
- Agent B receives files
1344
- ↓
1345
- cohere-db handoff --resume sess_abc123
1346
- ↓
1347
- Agent B continues work
1348
- ↓
1349
- cohere-db handoff --record --status completed
1350
- \`\`\`
1225
+ return `# Multi-Agent Protocol
1226
+
1227
+ > AUTO-GENERATED by cohere. Protocol for agent-to-agent handoff.
1228
+
1229
+ ## Overview
1230
+
1231
+ This document defines the protocol for safe handoff between AI agents working on the same codebase.
1232
+
1233
+ ## Protocol Steps
1234
+
1235
+ ### 1. Pre-Handoff (Current Agent)
1236
+
1237
+ Before ending your session:
1238
+
1239
+ \`\`\`bash
1240
+ cohere-db handoff --record --status {status} --agentId {agentId}
1241
+ \`\`\`
1242
+
1243
+ This creates:
1244
+ - \`.ai/handoffs/HANDOFF_<timestamp>.md\` - Full handoff record
1245
+ - \`.ai/state/CURRENT_STATE.md\` - Current progress snapshot
1246
+ - \`.ai/context/SESSION_CONTEXT.json\` - Machine-readable state
1247
+
1248
+ ### 2. Handoff Transfer
1249
+
1250
+ Share these files with the next agent:
1251
+ - Handoff file location
1252
+ - Session context JSON
1253
+ - Any modified files
1254
+
1255
+ ### 3. Post-Handoff (Next Agent)
1256
+
1257
+ On receiving handoff:
1258
+
1259
+ \`\`\`bash
1260
+ # List available sessions
1261
+ cohere-db handoff --list
1262
+
1263
+ # Resume specific session
1264
+ cohere-db handoff --resume <session_id>
1265
+
1266
+ # Read state first
1267
+ cat .ai/state/CURRENT_STATE.md
1268
+ \`\`\`
1269
+
1270
+ ---
1271
+
1272
+ ## State Files
1273
+
1274
+ ### CURRENT_STATE.md
1275
+
1276
+ | Section | Purpose |
1277
+ |---------|---------|
1278
+ | Session Status | Agent ID, timestamp, status |
1279
+ | Progress | Completed steps, current step, remaining |
1280
+ | Work Queue | Pending tasks, blocked tasks |
1281
+ | Variables | Key state variables |
1282
+ | Checkpoints | Saved checkpoints |
1283
+
1284
+ ### SESSION_CONTEXT.json
1285
+
1286
+ Machine-readable state for programmatic access:
1287
+
1288
+ \`\`\`json
1289
+ {
1290
+ "session": { "id", "agentId", "status" },
1291
+ "state": { "phase", "progress" },
1292
+ "variables": { /* key-value pairs */ },
1293
+ "schema": { "databaseType", "tablesModified" },
1294
+ "decisions": [ { "id", "title", "choice" } ]
1295
+ }
1296
+ \`\`\`
1297
+
1298
+ ---
1299
+
1300
+ ## Tables in Scope
1301
+
1302
+ ${tablesList}
1303
+
1304
+ ---
1305
+
1306
+ ## Constraints
1307
+
1308
+ | Constraint | Value |
1309
+ |------------|-------|
1310
+ | Max handoff size | 10KB |
1311
+ | Checkpoint interval | 5 minutes |
1312
+ | Decision logging | Required for major choices |
1313
+
1314
+ ---
1315
+
1316
+ ## CLI Commands
1317
+
1318
+ | Command | Description |
1319
+ |---------|-------------|
1320
+ | \`cohere-db handoff --record\` | Record current session |
1321
+ | \`cohere-db handoff --list\` | List available sessions |
1322
+ | \`cohere-db handoff --resume <id>\` | Resume from session |
1323
+ | \`cohere-db handoff --status completed\` | Mark session complete |
1324
+
1325
+ ---
1326
+
1327
+ ## Best Practices
1328
+
1329
+ 1. **Checkpoint frequently** - Save state every 5-10 minutes
1330
+ 2. **Log decisions** - Use decision IDs in handoffs
1331
+ 3. **Document failures** - Include error context in handoff
1332
+ 4. **Atomic handoffs** - Complete handoff before ending session
1333
+
1334
+ ---
1335
+
1336
+ ## Example Flow
1337
+
1338
+ \`\`\`
1339
+ Agent A (in progress)
1340
+ ↓
1341
+ cohere-db handoff --record --status paused
1342
+ ↓
1343
+ Agent B receives files
1344
+ ↓
1345
+ cohere-db handoff --resume sess_abc123
1346
+ ↓
1347
+ Agent B continues work
1348
+ ↓
1349
+ cohere-db handoff --record --status completed
1350
+ \`\`\`
1351
1351
  `;
1352
1352
  }
1353
1353
  // ============================================================================
@@ -1360,197 +1360,197 @@ cohere-db handoff --record --status completed
1360
1360
  return templates;
1361
1361
  }
1362
1362
  generateDecisionTemplate(schema) {
1363
- return `# Decision: {decisionTitle}
1364
-
1365
- > AUTO-GENERATED by cohere. Decision ID: \`{decisionId}\`
1366
-
1367
- ## Metadata
1368
-
1369
- | Field | Value |
1370
- |-------|-------|
1371
- | **Decision ID** | \`{decisionId}\` |
1372
- | **Timestamp** | \`{timestamp}\` |
1373
- | **Agent ID** | \`{agentId}\` |
1374
- | **Session ID** | \`{sessionId}\` |
1375
- | **Status** | \`{status}\` |
1376
-
1377
- ---
1378
-
1379
- ## Context
1380
-
1381
- ### Problem Statement
1382
-
1383
- {problemDescription}
1384
-
1385
- ### Constraints
1386
-
1387
- - Constraint 1
1388
- - Constraint 2
1389
- - Constraint 3
1390
-
1391
- ### Requirements
1392
-
1393
- 1. Requirement 1
1394
- 2. Requirement 2
1395
-
1396
- ---
1397
-
1398
- ## Options Considered
1399
-
1400
- ### Option A: {optionATitle}
1401
-
1402
- | Attribute | Value |
1403
- |-----------|-------|
1404
- | Pros | Pro 1, Pro 2 |
1405
- | Cons | Con 1, Con 2 |
1406
- | Risk | Low/Medium/High |
1407
- | Effort | Small/Medium/Large |
1408
-
1409
- ### Option B: {optionBTitle}
1410
-
1411
- | Attribute | Value |
1412
- |-----------|-------|
1413
- | Pros | Pro 1, Pro 2 |
1414
- | Cons | Con 1, Con 2 |
1415
- | Risk | Low/Medium/High |
1416
- | Effort | Small/Medium/Large |
1417
-
1418
- ---
1419
-
1420
- ## Decision
1421
-
1422
- > **{chosenOption}** was selected
1423
-
1424
- ### Rationale
1425
-
1426
- {choiceRationale}
1427
-
1428
- ### Trade-offs
1429
-
1430
- | Factor | Impact |
1431
- |--------|--------|
1432
- | Factor 1 | {impact1} |
1433
- | Factor 2 | {impact2} |
1434
-
1435
- ---
1436
-
1437
- ## Implementation
1438
-
1439
- ### Chosen Approach
1440
-
1441
- {implementationDetails}
1442
-
1443
- ### Files Modified
1444
-
1445
- | File | Change |
1446
- |------|--------|
1447
- | file1.ts | Modification A |
1448
- | file2.sql | Modification B |
1449
-
1450
- ---
1451
-
1452
- ## Outcome
1453
-
1454
- ### Expected Results
1455
-
1456
- 1. Expected outcome 1
1457
- 2. Expected outcome 2
1458
-
1459
- ### Potential Risks
1460
-
1461
- 1. Risk 1 - Mitigation
1462
- 2. Risk 2 - Mitigation
1463
-
1464
- ### Follow-up Required
1465
-
1466
- - [ ] Follow-up item 1
1467
- - [ ] Follow-up item 2
1468
-
1469
- ---
1470
-
1471
- ## Related Decisions
1472
-
1473
- | ID | Decision | Relationship |
1474
- |----|----------|--------------|
1475
- | DECISION_001 | Related decision | Precedes |
1476
- | DECISION_003 | Related decision | Extends |
1477
-
1478
- ---
1479
-
1480
- > **USAGE**: Use this format for all significant decisions.
1481
- > Decision IDs are referenced in handoffs for context.
1363
+ return `# Decision: {decisionTitle}
1364
+
1365
+ > AUTO-GENERATED by cohere. Decision ID: \`{decisionId}\`
1366
+
1367
+ ## Metadata
1368
+
1369
+ | Field | Value |
1370
+ |-------|-------|
1371
+ | **Decision ID** | \`{decisionId}\` |
1372
+ | **Timestamp** | \`{timestamp}\` |
1373
+ | **Agent ID** | \`{agentId}\` |
1374
+ | **Session ID** | \`{sessionId}\` |
1375
+ | **Status** | \`{status}\` |
1376
+
1377
+ ---
1378
+
1379
+ ## Context
1380
+
1381
+ ### Problem Statement
1382
+
1383
+ {problemDescription}
1384
+
1385
+ ### Constraints
1386
+
1387
+ - Constraint 1
1388
+ - Constraint 2
1389
+ - Constraint 3
1390
+
1391
+ ### Requirements
1392
+
1393
+ 1. Requirement 1
1394
+ 2. Requirement 2
1395
+
1396
+ ---
1397
+
1398
+ ## Options Considered
1399
+
1400
+ ### Option A: {optionATitle}
1401
+
1402
+ | Attribute | Value |
1403
+ |-----------|-------|
1404
+ | Pros | Pro 1, Pro 2 |
1405
+ | Cons | Con 1, Con 2 |
1406
+ | Risk | Low/Medium/High |
1407
+ | Effort | Small/Medium/Large |
1408
+
1409
+ ### Option B: {optionBTitle}
1410
+
1411
+ | Attribute | Value |
1412
+ |-----------|-------|
1413
+ | Pros | Pro 1, Pro 2 |
1414
+ | Cons | Con 1, Con 2 |
1415
+ | Risk | Low/Medium/High |
1416
+ | Effort | Small/Medium/Large |
1417
+
1418
+ ---
1419
+
1420
+ ## Decision
1421
+
1422
+ > **{chosenOption}** was selected
1423
+
1424
+ ### Rationale
1425
+
1426
+ {choiceRationale}
1427
+
1428
+ ### Trade-offs
1429
+
1430
+ | Factor | Impact |
1431
+ |--------|--------|
1432
+ | Factor 1 | {impact1} |
1433
+ | Factor 2 | {impact2} |
1434
+
1435
+ ---
1436
+
1437
+ ## Implementation
1438
+
1439
+ ### Chosen Approach
1440
+
1441
+ {implementationDetails}
1442
+
1443
+ ### Files Modified
1444
+
1445
+ | File | Change |
1446
+ |------|--------|
1447
+ | file1.ts | Modification A |
1448
+ | file2.sql | Modification B |
1449
+
1450
+ ---
1451
+
1452
+ ## Outcome
1453
+
1454
+ ### Expected Results
1455
+
1456
+ 1. Expected outcome 1
1457
+ 2. Expected outcome 2
1458
+
1459
+ ### Potential Risks
1460
+
1461
+ 1. Risk 1 - Mitigation
1462
+ 2. Risk 2 - Mitigation
1463
+
1464
+ ### Follow-up Required
1465
+
1466
+ - [ ] Follow-up item 1
1467
+ - [ ] Follow-up item 2
1468
+
1469
+ ---
1470
+
1471
+ ## Related Decisions
1472
+
1473
+ | ID | Decision | Relationship |
1474
+ |----|----------|--------------|
1475
+ | DECISION_001 | Related decision | Precedes |
1476
+ | DECISION_003 | Related decision | Extends |
1477
+
1478
+ ---
1479
+
1480
+ > **USAGE**: Use this format for all significant decisions.
1481
+ > Decision IDs are referenced in handoffs for context.
1482
1482
  `;
1483
1483
  }
1484
1484
  generateDecisionLog(schema) {
1485
1485
  const tablesList = schema.tables.map((t) => `- \`${t.name}\``).join('\n');
1486
- return `# Decision Log
1487
-
1488
- > AUTO-GENERATED by cohere. All decisions made during this session.
1489
-
1490
- ## Overview
1491
-
1492
- This log tracks all significant decisions made by agents working on this codebase.
1493
-
1494
- ## Decision Index
1495
-
1496
- | ID | Date | Title | Status |
1497
- |----|------|-------|--------|
1498
- | DECISION_001 | YYYY-MM-DD | Decision title | Active |
1499
- | DECISION_002 | YYYY-MM-DD | Decision title | Active |
1500
-
1501
- ---
1502
-
1503
- ## Active Decisions
1504
-
1505
- ### DECISION_001: {decisionTitle}
1506
-
1507
- **Status:** Active
1508
- **Date:** {date}
1509
- **Agent:** {agentId}
1510
-
1511
- **Summary:** Brief summary of decision
1512
-
1513
- **Impact:** Tables affected: ${tablesList}
1514
-
1515
- ---
1516
-
1517
- ## Archived Decisions
1518
-
1519
- ### DECISION_XXX: {archivedTitle}
1520
-
1521
- **Status:** Archived
1522
- **Date:** {date}
1523
- **Reason:** Context no longer relevant
1524
-
1525
- ---
1526
-
1527
- ## Adding New Decisions
1528
-
1529
- Use the template in \`.ai/decisions/decision-template.md\`:
1530
-
1531
- \`\`\`bash
1532
- # Create new decision
1533
- cp .ai/decisions/decision-template.md .ai/decisions/DECISION_003.md
1534
-
1535
- # Edit the file with your decision
1536
- # Update this log
1537
- \`\`\`
1538
-
1539
- ---
1540
-
1541
- ## Decision Categories
1542
-
1543
- | Category | Description |
1544
- |----------|-------------|
1545
- | schema | Database schema changes |
1546
- | query | Query pattern choices |
1547
- | architecture | System design decisions |
1548
- | workflow | Process/flow decisions |
1549
-
1550
- ---
1551
-
1552
- > **NOTE**: Decision IDs are referenced in handoffs.
1553
- > Always update this log when creating new decisions.
1486
+ return `# Decision Log
1487
+
1488
+ > AUTO-GENERATED by cohere. All decisions made during this session.
1489
+
1490
+ ## Overview
1491
+
1492
+ This log tracks all significant decisions made by agents working on this codebase.
1493
+
1494
+ ## Decision Index
1495
+
1496
+ | ID | Date | Title | Status |
1497
+ |----|------|-------|--------|
1498
+ | DECISION_001 | YYYY-MM-DD | Decision title | Active |
1499
+ | DECISION_002 | YYYY-MM-DD | Decision title | Active |
1500
+
1501
+ ---
1502
+
1503
+ ## Active Decisions
1504
+
1505
+ ### DECISION_001: {decisionTitle}
1506
+
1507
+ **Status:** Active
1508
+ **Date:** {date}
1509
+ **Agent:** {agentId}
1510
+
1511
+ **Summary:** Brief summary of decision
1512
+
1513
+ **Impact:** Tables affected: ${tablesList}
1514
+
1515
+ ---
1516
+
1517
+ ## Archived Decisions
1518
+
1519
+ ### DECISION_XXX: {archivedTitle}
1520
+
1521
+ **Status:** Archived
1522
+ **Date:** {date}
1523
+ **Reason:** Context no longer relevant
1524
+
1525
+ ---
1526
+
1527
+ ## Adding New Decisions
1528
+
1529
+ Use the template in \`.ai/decisions/decision-template.md\`:
1530
+
1531
+ \`\`\`bash
1532
+ # Create new decision
1533
+ cp .ai/decisions/decision-template.md .ai/decisions/DECISION_003.md
1534
+
1535
+ # Edit the file with your decision
1536
+ # Update this log
1537
+ \`\`\`
1538
+
1539
+ ---
1540
+
1541
+ ## Decision Categories
1542
+
1543
+ | Category | Description |
1544
+ |----------|-------------|
1545
+ | schema | Database schema changes |
1546
+ | query | Query pattern choices |
1547
+ | architecture | System design decisions |
1548
+ | workflow | Process/flow decisions |
1549
+
1550
+ ---
1551
+
1552
+ > **NOTE**: Decision IDs are referenced in handoffs.
1553
+ > Always update this log when creating new decisions.
1554
1554
  `;
1555
1555
  }
1556
1556
  }