sqlew 4.0.3 → 4.0.5
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/CHANGELOG.md +58 -0
- package/LICENSE +177 -39
- package/NOTICE +24 -0
- package/README.md +171 -93
- package/assets/claude-md-snippets/plan-mode-integration.md +2 -2
- package/assets/config.example.toml +16 -0
- package/assets/sample-agents/sqlew-architect.md +1 -0
- package/assets/sample-agents/sqlew-researcher.md +1 -0
- package/assets/sample-agents/sqlew-scrum-master.md +1 -0
- package/dist/config/minimal-generator.d.ts.map +1 -1
- package/dist/config/minimal-generator.js +72 -91
- package/dist/config/minimal-generator.js.map +1 -1
- package/dist/config/types.d.ts +2 -12
- package/dist/config/types.d.ts.map +1 -1
- package/dist/config/types.js +1 -6
- package/dist/config/types.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/sync-commands.d.ts.map +1 -1
- package/dist/sync-commands.js +2 -7
- package/dist/sync-commands.js.map +1 -1
- package/docs/AI_AGENT_GUIDE.md +138 -37
- package/docs/DECISION_CONTEXT.md +41 -19
- package/package.json +11 -6
package/dist/config/types.js
CHANGED
package/dist/config/types.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA2YH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAgB;IACzC,QAAQ,EAAE;IACR,wDAAwD;KACzD;IACD,UAAU,EAAE;QACV,cAAc,EAAE,KAAK;QACrB,aAAa,EAAE,EAAE;QACjB,iBAAiB,EAAE,CAAC;KACrB;IACD,KAAK,EAAE;QACL,sBAAsB,EAAE,CAAC;QACzB,uBAAuB,EAAE,CAAC;QAC1B,0BAA0B,EAAE,EAAE;QAC9B,kBAAkB,EAAE,IAAI;QACxB,mBAAmB,EAAE,EAAE;QACvB,iCAAiC,EAAE,IAAI;QACvC,yBAAyB,EAAE,IAAI;QAC/B,sBAAsB,EAAE,IAAI;KAC7B;IACD,MAAM,EAAE;QACN,YAAY,EAAE,IAAI;QAClB,UAAU,EAAE,IAAI;QAChB,SAAS,EAAE,IAAI;KAChB;IACD,QAAQ,EAAE;QACR,KAAK,EAAE,IAAI;KACZ;CACF,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"sync-commands.d.ts","sourceRoot":"","sources":["../src/sync-commands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;
|
|
1
|
+
{"version":3,"file":"sync-commands.d.ts","sourceRoot":"","sources":["../src/sync-commands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsCH;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAgF7C"}
|
package/dist/sync-commands.js
CHANGED
|
@@ -12,12 +12,7 @@ import { loadConfigFile } from './config/loader.js';
|
|
|
12
12
|
const __filename = fileURLToPath(import.meta.url);
|
|
13
13
|
const __dirname = path.dirname(__filename);
|
|
14
14
|
const COMMANDS = [
|
|
15
|
-
{ filename: '
|
|
16
|
-
{ filename: 'sqw-secretary.md', configKey: 'secretary', displayName: 'Secretary' },
|
|
17
|
-
{ filename: 'sqw-plan.md', configKey: 'plan', displayName: 'Plan' },
|
|
18
|
-
{ filename: 'sqw-research.md', configKey: 'research', displayName: 'Research' },
|
|
19
|
-
{ filename: 'sqw-review.md', configKey: 'review', displayName: 'Review' },
|
|
20
|
-
{ filename: 'sqw-scrum.md', configKey: 'scrum', displayName: 'Scrum' },
|
|
15
|
+
{ filename: 'sqlew.md', configKey: 'sqlew', displayName: 'sqlew' },
|
|
21
16
|
];
|
|
22
17
|
/**
|
|
23
18
|
* Get source path for command files
|
|
@@ -104,7 +99,7 @@ export function syncCommandsWithConfig() {
|
|
|
104
99
|
}
|
|
105
100
|
// Show usage hint if any commands were copied
|
|
106
101
|
if (copied.length > 0) {
|
|
107
|
-
console.log(` Use
|
|
102
|
+
console.log(` Use command with / prefix: /sqlew`);
|
|
108
103
|
}
|
|
109
104
|
}
|
|
110
105
|
catch (error) {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"sync-commands.js","sourceRoot":"","sources":["../src/sync-commands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,8BAA8B,EAAE,MAAM,+BAA+B,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAQ3C,MAAM,QAAQ,GAAoB;IAChC,EAAE,QAAQ,EAAE,
|
|
1
|
+
{"version":3,"file":"sync-commands.js","sourceRoot":"","sources":["../src/sync-commands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,8BAA8B,EAAE,MAAM,+BAA+B,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAQ3C,MAAM,QAAQ,GAAoB;IAChC,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE;CACnE,CAAC;AAEF;;GAEG;AACH,SAAS,aAAa;IACpB,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,WAAW;IACtC,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC;AAC7D,CAAC;AAED;;GAEG;AACH,SAAS,aAAa;IACpB,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAClC,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB;IACpC,IAAI,CAAC;QACH,oCAAoC;QACpC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;QAClC,8BAA8B,CAAC,WAAW,CAAC,CAAC;QAE5C,cAAc;QACd,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;QAChC,MAAM,aAAa,GAAG,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;QAE5C,MAAM,UAAU,GAAG,aAAa,EAAE,CAAC;QACnC,MAAM,UAAU,GAAG,aAAa,EAAE,CAAC;QAEnC,iCAAiC;QACjC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC/B,OAAO,CAAC,KAAK,CAAC,yCAAyC,UAAU,EAAE,CAAC,CAAC;YACrE,OAAO;QACT,CAAC;QAED,iCAAiC;QACjC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC/B,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;QAED,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAa,EAAE,CAAC;QAE7B,uBAAuB;QACvB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;YAC3D,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;YAE3D,wDAAwD;YACxD,MAAM,SAAS,GAAG,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,KAAK,CAAC;YAE7D,IAAI,SAAS,EAAE,CAAC;gBACd,sCAAsC;gBACtC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;oBAC/B,wBAAwB;oBACxB,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;wBAC9B,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;wBACxC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;oBACnC,CAAC;yBAAM,CAAC;wBACN,OAAO,CAAC,KAAK,CAAC,4BAA4B,UAAU,EAAE,CAAC,CAAC;oBAC1D,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,4BAA4B;oBAC5B,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,8CAA8C;gBAC9C,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;oBAC9B,yBAAyB;oBACzB,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;oBAC1B,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;gBACpC,CAAC;gBACD,0CAA0C;YAC5C,CAAC;QACH,CAAC;QAED,iBAAiB;QACjB,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,GAAG,CAAC,+BAA+B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAChE,OAAO,CAAC,GAAG,CAAC,eAAe,UAAU,EAAE,CAAC,CAAC;QAC3C,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,GAAG,CAAC,6BAA6B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjE,CAAC;QAED,8CAA8C;QAC9C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,GAAG,CAAC,qCAAqC,CAAC,CAAC;QACrD,CAAC;IAEH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,mCAAmC;QACnC,OAAO,CAAC,KAAK,CAAC,8BAA8B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACxG,CAAC;AACH,CAAC"}
|
package/docs/AI_AGENT_GUIDE.md
CHANGED
|
@@ -1,7 +1,31 @@
|
|
|
1
|
-
# AI Agent Guide for
|
|
1
|
+
# AI Agent Guide for sqlew ADR System
|
|
2
2
|
|
|
3
3
|
**Quick Reference for Claude Code and other AI agents using sqlew (v4.0.0+)**
|
|
4
4
|
|
|
5
|
+
## What is sqlew?
|
|
6
|
+
|
|
7
|
+
sqlew is an **ADR (Architecture Decision Record) system designed for AI agents**. It enables you to create, query, and maintain structured architectural decisions in a SQL database, providing persistent context across sessions.
|
|
8
|
+
|
|
9
|
+
### Core Concept: ADR for AI
|
|
10
|
+
|
|
11
|
+
Traditional ADR uses Markdown files. sqlew brings ADR to AI agents through **RDBMS + MCP**:
|
|
12
|
+
|
|
13
|
+
**RDBMS (Relational Database)** enables efficient operations:
|
|
14
|
+
- **Indexed queries** – Find decisions by tags/layers in milliseconds
|
|
15
|
+
- **JOIN operations** – Query related decisions, constraints, and tasks together
|
|
16
|
+
- **Transaction safety** – ACID guarantees prevent data corruption
|
|
17
|
+
- **Scalability** – Handle thousands of ADRs without slowdown
|
|
18
|
+
|
|
19
|
+
**MCP (Model Context Protocol)** provides AI-native access:
|
|
20
|
+
- **Native tool calls** – AI agents use ADR as built-in functions
|
|
21
|
+
- **Structured parameters** – Type-safe, validated inputs prevent errors
|
|
22
|
+
- **Token efficiency** – Retrieve only required data (60-75% reduction)
|
|
23
|
+
- **Session persistence** – ADRs survive beyond individual conversations
|
|
24
|
+
|
|
25
|
+
**Result**: AI agents query ADRs like database operations, not file reads.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
5
29
|
## Most Important Rule
|
|
6
30
|
|
|
7
31
|
**ALWAYS include the `action` parameter in EVERY tool call.** This is the #1 cause of errors.
|
|
@@ -9,44 +33,52 @@
|
|
|
9
33
|
```javascript
|
|
10
34
|
// WRONG - Missing action
|
|
11
35
|
{
|
|
12
|
-
key: "
|
|
13
|
-
value: "
|
|
36
|
+
key: "auth_method",
|
|
37
|
+
value: "jwt"
|
|
14
38
|
}
|
|
15
39
|
|
|
16
40
|
// CORRECT - action parameter present
|
|
17
41
|
{
|
|
18
42
|
action: "set",
|
|
19
|
-
key: "
|
|
20
|
-
value: "
|
|
43
|
+
key: "auth_method",
|
|
44
|
+
value: "jwt"
|
|
21
45
|
}
|
|
22
46
|
```
|
|
23
47
|
|
|
24
48
|
---
|
|
25
49
|
|
|
26
|
-
## Quick Start
|
|
50
|
+
## Quick Start: Creating Your First ADR
|
|
27
51
|
|
|
28
|
-
### Basic
|
|
52
|
+
### Basic ADR Workflow
|
|
29
53
|
|
|
30
54
|
```javascript
|
|
31
|
-
// 1.
|
|
55
|
+
// 1. Record an architectural decision
|
|
32
56
|
{
|
|
33
57
|
action: "set",
|
|
34
58
|
key: "auth_method",
|
|
35
|
-
value: "
|
|
59
|
+
value: "We chose JWT authentication over session-based auth. JWT enables stateless API design and better horizontal scaling. Session-based auth was rejected due to scaling concerns with shared session stores.",
|
|
36
60
|
layer: "business",
|
|
37
|
-
tags: ["security", "authentication"]
|
|
61
|
+
tags: ["security", "authentication", "api"]
|
|
38
62
|
}
|
|
39
63
|
|
|
40
|
-
// 2.
|
|
64
|
+
// 2. Retrieve the decision
|
|
41
65
|
{
|
|
42
66
|
action: "get",
|
|
43
67
|
key: "auth_method"
|
|
44
68
|
}
|
|
45
69
|
|
|
46
|
-
// 3.
|
|
70
|
+
// 3. Search for related decisions
|
|
47
71
|
{
|
|
48
72
|
action: "list",
|
|
49
|
-
|
|
73
|
+
tags: ["authentication"],
|
|
74
|
+
status: "active"
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// 4. Add architectural constraint
|
|
78
|
+
{
|
|
79
|
+
action: "add",
|
|
80
|
+
category: "security",
|
|
81
|
+
constraint_text: "All authentication must use JWT with RS256 signing algorithm",
|
|
50
82
|
layer: "business"
|
|
51
83
|
}
|
|
52
84
|
```
|
|
@@ -55,33 +87,71 @@
|
|
|
55
87
|
|
|
56
88
|
## When to Use Each Tool
|
|
57
89
|
|
|
58
|
-
|
|
90
|
+
### Core ADR Tools
|
|
91
|
+
|
|
92
|
+
| Tool | ADR Purpose | Key Feature |
|
|
93
|
+
|------|-------------|-------------|
|
|
94
|
+
| **decision** | Record architectural decisions | Full version history, alternatives tracking |
|
|
95
|
+
| **constraint** | Define architectural principles | Category-based rules, validation support |
|
|
96
|
+
| **task** | Track decision implementation | Links to decisions, status tracking |
|
|
97
|
+
| **file** | Document impacted code | Shows which files implement decisions |
|
|
98
|
+
| **suggest** | Find similar decisions | Prevent duplicate ADRs, detect conflicts |
|
|
99
|
+
|
|
100
|
+
### Utility Tools
|
|
101
|
+
|
|
102
|
+
| Tool | Purpose | When to Use |
|
|
59
103
|
|------|---------|-------------|
|
|
60
|
-
| **
|
|
61
|
-
| **
|
|
62
|
-
| **
|
|
63
|
-
|
|
64
|
-
|
|
104
|
+
| **help** | Query action parameters | Need to check available parameters for an action |
|
|
105
|
+
| **example** | Browse code examples | Want to see working code snippets |
|
|
106
|
+
| **use_case** | Learn complete workflows | Need end-to-end multi-step scenarios |
|
|
107
|
+
|
|
108
|
+
> **Note**: Utility tools provide documentation and examples without affecting your ADR data.
|
|
65
109
|
|
|
66
|
-
###
|
|
110
|
+
### Understanding the ADR Data Model
|
|
67
111
|
|
|
68
|
-
| Concept |
|
|
69
|
-
|
|
70
|
-
| **Decision** |
|
|
71
|
-
| **Constraint** |
|
|
72
|
-
| **Task** |
|
|
112
|
+
| Concept | ADR Equivalent | Example |
|
|
113
|
+
|---------|----------------|---------|
|
|
114
|
+
| **Decision** | Architecture Decision Record | "We chose PostgreSQL over MongoDB for ACID compliance" |
|
|
115
|
+
| **Constraint** | Architectural Principle/Rule | "All database queries must use prepared statements" |
|
|
116
|
+
| **Task** | Implementation Action | "Migrate user authentication to JWT" |
|
|
117
|
+
| **File** | Impacted Component | "Modified auth.ts to implement JWT" |
|
|
73
118
|
|
|
74
|
-
###
|
|
119
|
+
### Complete ADR Workflow Example
|
|
75
120
|
|
|
76
121
|
```javascript
|
|
77
|
-
// 1. Record decision
|
|
78
|
-
{
|
|
122
|
+
// 1. Record decision with full context
|
|
123
|
+
{
|
|
124
|
+
action: "set",
|
|
125
|
+
key: "database_choice",
|
|
126
|
+
value: "PostgreSQL selected for production database. Alternatives considered: MongoDB (rejected: no ACID), MySQL (rejected: weaker JSON support). PostgreSQL chosen for ACID compliance, mature ecosystem, and superior JSON handling.",
|
|
127
|
+
layer: "data",
|
|
128
|
+
tags: ["database", "postgresql", "architecture"]
|
|
129
|
+
}
|
|
79
130
|
|
|
80
|
-
// 2.
|
|
81
|
-
{
|
|
131
|
+
// 2. Define constraints based on decision
|
|
132
|
+
{
|
|
133
|
+
action: "add",
|
|
134
|
+
category: "database",
|
|
135
|
+
constraint_text: "All database operations must use connection pooling with max 20 connections",
|
|
136
|
+
layer: "data"
|
|
137
|
+
}
|
|
82
138
|
|
|
83
|
-
// 3. Create task
|
|
84
|
-
{
|
|
139
|
+
// 3. Create implementation task
|
|
140
|
+
{
|
|
141
|
+
action: "create",
|
|
142
|
+
title: "Set up PostgreSQL connection pool",
|
|
143
|
+
description: "Implement connection pooling as per database_choice ADR",
|
|
144
|
+
layer: "data",
|
|
145
|
+
tags: ["database", "postgresql"]
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
// 4. Track file changes
|
|
149
|
+
{
|
|
150
|
+
action: "set",
|
|
151
|
+
path: "src/db/connection.ts",
|
|
152
|
+
description: "PostgreSQL connection pool implementation",
|
|
153
|
+
layer: "data"
|
|
154
|
+
}
|
|
85
155
|
```
|
|
86
156
|
|
|
87
157
|
---
|
|
@@ -147,13 +217,44 @@
|
|
|
147
217
|
|
|
148
218
|
---
|
|
149
219
|
|
|
150
|
-
## Best Practices
|
|
220
|
+
## ADR Best Practices for AI Agents
|
|
221
|
+
|
|
222
|
+
### Writing Good ADRs
|
|
223
|
+
|
|
224
|
+
1. **Include rationale** - Explain WHY, not just WHAT
|
|
225
|
+
```javascript
|
|
226
|
+
// BAD: "Use PostgreSQL"
|
|
227
|
+
// GOOD: "Use PostgreSQL for ACID compliance (rejected MongoDB for lack of transactions)"
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
2. **Document alternatives** - Show what was considered and rejected
|
|
231
|
+
```javascript
|
|
232
|
+
value: "JWT chosen. Alternatives: session-based (rejected: scaling), OAuth (overkill for internal API)"
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
3. **Use descriptive keys** - Make decisions discoverable
|
|
236
|
+
```javascript
|
|
237
|
+
// BAD: key: "db"
|
|
238
|
+
// GOOD: key: "database_postgresql_production"
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
4. **Tag comprehensively** - Enable efficient searching
|
|
242
|
+
```javascript
|
|
243
|
+
tags: ["database", "postgresql", "production", "acid", "scalability"]
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
5. **Link related entities** - Connect decisions to implementation
|
|
247
|
+
```javascript
|
|
248
|
+
// Record decision → Create constraint → Make task → Track files
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### Technical Best Practices
|
|
151
252
|
|
|
152
253
|
1. **Always include `action` parameter** - #1 error source
|
|
153
|
-
2. **
|
|
154
|
-
3. **
|
|
155
|
-
4. **
|
|
156
|
-
5. **
|
|
254
|
+
2. **Always specify `layer`** - Required for architectural organization
|
|
255
|
+
3. **Use `atomic: false` for batch operations** - Avoid all-or-nothing failures
|
|
256
|
+
4. **Check for duplicates first** - Use `suggest` tool before creating decisions
|
|
257
|
+
5. **Version important changes** - Increment version for significant updates
|
|
157
258
|
|
|
158
259
|
> **Detailed best practices**: See [BEST_PRACTICES.md](BEST_PRACTICES.md)
|
|
159
260
|
|
package/docs/DECISION_CONTEXT.md
CHANGED
|
@@ -1,10 +1,19 @@
|
|
|
1
|
-
#
|
|
1
|
+
# ADR Data Model - Architecture Decision Records (v3.2.2+)
|
|
2
2
|
|
|
3
3
|
## Overview
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
sqlew implements a **structured ADR (Architecture Decision Record) data model** that captures not just decisions, but the complete context: **WHY** a decision was made, what alternatives were considered, and the trade-offs involved. This transforms traditional text-based ADR into a queryable, AI-native database that maintains architectural knowledge across sessions.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
### What is an ADR?
|
|
8
|
+
|
|
9
|
+
**Architecture Decision Records (ADR)** are documents that capture important architectural decisions made along with their context and consequences. sqlew extends this concept by:
|
|
10
|
+
|
|
11
|
+
- **Structured storage** – ADR data stored as relational database records
|
|
12
|
+
- **Version history** – Track how decisions evolve over time
|
|
13
|
+
- **Relationship tracking** – Link decisions to tasks, files, and constraints
|
|
14
|
+
- **AI-native queries** – Search by tags, layers, similarity scores
|
|
15
|
+
|
|
16
|
+
> **Preserved in v4.0.0**: This feature is fully preserved in the v4.0.0 schema refactoring. All ADR context data (rationale, alternatives, trade-offs, related links) continues to work without changes. The schema uses `v4_decision_context` table with the same structure and functionality.
|
|
8
17
|
|
|
9
18
|
---
|
|
10
19
|
|
|
@@ -650,26 +659,39 @@ If you have old decisions that need context, add it retroactively:
|
|
|
650
659
|
|
|
651
660
|
## Key Takeaways
|
|
652
661
|
|
|
653
|
-
###
|
|
662
|
+
### ADR for AI Agents: Context + Intelligence = Complete Knowledge Repository
|
|
654
663
|
|
|
655
|
-
**
|
|
664
|
+
**sqlew transforms traditional ADR into an AI-native knowledge system:**
|
|
656
665
|
|
|
657
|
-
1. **
|
|
658
|
-
2. **Decision Intelligence** (v3.9.0) →
|
|
666
|
+
1. **ADR Data Model** (v3.2.2) → Structured storage of decisions with rationale, alternatives, and trade-offs
|
|
667
|
+
2. **Decision Intelligence** (v3.9.0) → Automatic duplicate detection and version consolidation
|
|
668
|
+
3. **AI-Native Queries** → Fast, structured access to architectural decisions across sessions
|
|
659
669
|
|
|
660
670
|
**Together they provide:**
|
|
661
|
-
- **Living
|
|
662
|
-
- **
|
|
663
|
-
- **Automatic consolidation**
|
|
664
|
-
- **
|
|
665
|
-
- **
|
|
671
|
+
- **Living ADR repository** – Decisions evolve with your project through version history
|
|
672
|
+
- **AI-queryable records** – Search by tags, layers, similarity instead of reading files
|
|
673
|
+
- **Automatic consolidation** – Prevent duplicate ADRs, maintain single source of truth
|
|
674
|
+
- **Complete context** – Capture WHY, not just WHAT (alternatives, trade-offs, consequences)
|
|
675
|
+
- **Cross-session memory** – AI agents maintain architectural understanding across days/weeks
|
|
676
|
+
|
|
677
|
+
### ADR Best Practices for AI
|
|
678
|
+
|
|
679
|
+
**Before creating a decision:**
|
|
680
|
+
1. Use `check_duplicate` to find existing related ADRs
|
|
681
|
+
2. Review similar decisions to avoid redundancy
|
|
682
|
+
3. Update existing ADR if it's the same topic
|
|
683
|
+
|
|
684
|
+
**When documenting a decision:**
|
|
685
|
+
1. Include **rationale** – Explain WHY this choice was made
|
|
686
|
+
2. Document **alternatives** – Show what was considered and rejected
|
|
687
|
+
3. Capture **trade-offs** – Honest pros/cons for future reference
|
|
688
|
+
4. Link **related entities** – Connect to tasks, files, constraints
|
|
666
689
|
|
|
667
|
-
**
|
|
668
|
-
1.
|
|
669
|
-
2.
|
|
670
|
-
3.
|
|
671
|
-
4. Query `versions` to see decision evolution
|
|
690
|
+
**After implementation:**
|
|
691
|
+
1. Track affected files to show ADR impact
|
|
692
|
+
2. Update decision status as it evolves (active → deprecated → superseded)
|
|
693
|
+
3. Query `versions` to see architectural evolution over time
|
|
672
694
|
|
|
673
|
-
**
|
|
695
|
+
**ADR transforms your codebase from "what we built" into "why we built it this way"** - making architectural decisions discoverable and understandable to AI agents across the entire project lifecycle.
|
|
674
696
|
|
|
675
|
-
**Decision Intelligence ensures
|
|
697
|
+
**Decision Intelligence ensures ADRs remain living documents** - automatically consolidated and updated rather than scattered across fragmented entries.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "sqlew",
|
|
3
|
-
"version": "4.0.3",
|
|
4
3
|
"description": "MCP server that gives AI agents a shared SQL-backed context repository for decisions, constraints, and tasks",
|
|
4
|
+
"version": "4.0.5",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"bin": {
|
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
"docs/",
|
|
16
16
|
"README.md",
|
|
17
17
|
"LICENSE",
|
|
18
|
+
"NOTICE",
|
|
18
19
|
"CHANGELOG.md",
|
|
19
20
|
"MIGRATION_v2.md",
|
|
20
21
|
"ARCHITECTURE.md"
|
|
@@ -84,18 +85,22 @@
|
|
|
84
85
|
},
|
|
85
86
|
"homepage": "https://github.com/sin5ddd/mcp-sqlew#readme",
|
|
86
87
|
"keywords": [
|
|
88
|
+
"adr",
|
|
89
|
+
"architecture-decision-record",
|
|
87
90
|
"mcp",
|
|
88
91
|
"mcp-server",
|
|
89
92
|
"model-context-protocol",
|
|
90
|
-
"
|
|
93
|
+
"ai-agents",
|
|
91
94
|
"claude-code",
|
|
92
|
-
"
|
|
95
|
+
"architectural-decisions",
|
|
96
|
+
"decision-management",
|
|
93
97
|
"sqlite",
|
|
94
|
-
"
|
|
95
|
-
"
|
|
98
|
+
"postgresql",
|
|
99
|
+
"mysql",
|
|
100
|
+
"token-efficiency"
|
|
96
101
|
],
|
|
97
102
|
"author": "sin5ddd",
|
|
98
|
-
"license": "
|
|
103
|
+
"license": "Apache-2.0",
|
|
99
104
|
"dependencies": {
|
|
100
105
|
"@modelcontextprotocol/sdk": "^1.21.1",
|
|
101
106
|
"better-sqlite3": "^12.4.1",
|