@nolrm/contextkit 0.13.4 → 0.13.7
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 +65 -46
- package/bin/contextkit.js +4 -2
- package/lib/commands/analyze.js +131 -91
- package/lib/commands/check.js +24 -18
- package/lib/commands/install.js +274 -71
- package/lib/commands/note.js +12 -20
- package/lib/commands/run.js +20 -22
- package/lib/commands/status.js +61 -32
- package/lib/commands/update.js +25 -26
- package/lib/index.js +1 -1
- package/lib/integrations/aider-integration.js +1 -1
- package/lib/integrations/base-integration.js +13 -6
- package/lib/integrations/claude-integration.js +103 -41
- package/lib/integrations/continue-integration.js +5 -5
- package/lib/integrations/copilot-integration.js +1 -1
- package/lib/integrations/cursor-integration.js +70 -28
- package/lib/integrations/gemini-integration.js +13 -11
- package/lib/integrations/index.js +11 -1
- package/lib/utils/banner.js +14 -11
- package/lib/utils/download.js +3 -4
- package/lib/utils/git-hooks.js +3 -4
- package/lib/utils/migrations.js +6 -4
- package/lib/utils/migrations.md +4 -3
- package/lib/utils/notifier.js +1 -1
- package/lib/utils/project-detector.js +11 -5
- package/lib/utils/status-manager.js +6 -7
- package/lib/utils/tool-detector.js +19 -21
- package/package.json +8 -2
package/README.md
CHANGED
|
@@ -10,9 +10,10 @@ ContextKit is a CLI tool that provides **context-engineering** capabilities by c
|
|
|
10
10
|
|
|
11
11
|
## Why ContextKit?
|
|
12
12
|
|
|
13
|
-
**The problem:** LLMs are great at syntax, not at
|
|
13
|
+
**The problem:** LLMs are great at syntax, not at _your_ conventions. Generic AI output requires manual fixes for style, structure, and architecture.
|
|
14
14
|
|
|
15
15
|
**The solution:** ContextKit provides your AI with:
|
|
16
|
+
|
|
16
17
|
- **Glossary** of project terminology and domain-specific terms (e.g., your entity, feature, and module names)
|
|
17
18
|
- **Standards** for code style, testing patterns, and architecture
|
|
18
19
|
- **Templates** with canonical component shapes
|
|
@@ -30,15 +31,18 @@ Each platform gets auto-loaded bridge files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.m
|
|
|
30
31
|
## Quick Start (60s)
|
|
31
32
|
|
|
32
33
|
**1. Install the CLI**
|
|
34
|
+
|
|
33
35
|
```bash
|
|
34
36
|
npm i -g @nolrm/contextkit
|
|
35
37
|
```
|
|
36
38
|
|
|
37
39
|
**2. Set up your project**
|
|
40
|
+
|
|
38
41
|
```bash
|
|
39
42
|
cd your-project
|
|
40
43
|
contextkit install
|
|
41
44
|
```
|
|
45
|
+
|
|
42
46
|
Creates `.contextkit/` with skeleton standards files, a self-describing `README.md`, and an attribution block in `config.yml` so any developer who encounters the folder knows what manages it.
|
|
43
47
|
|
|
44
48
|
**3. Generate your standards**
|
|
@@ -77,16 +81,19 @@ Each platform generates bridge files that the AI tool auto-reads. If a bridge fi
|
|
|
77
81
|
## See the difference (before → after)
|
|
78
82
|
|
|
79
83
|
**Prompt**
|
|
84
|
+
|
|
80
85
|
```
|
|
81
86
|
"Add checkout flow for customer"
|
|
82
87
|
```
|
|
83
88
|
|
|
84
89
|
**What the AI does with ContextKit**
|
|
90
|
+
|
|
85
91
|
- Reads `glossary.md` → `checkout` = checkout process; `customer` = customer account
|
|
86
92
|
- Applies `code-style.md` → strict TS, functional components
|
|
87
93
|
- Follows `testing.md` → numbered test cases
|
|
88
94
|
|
|
89
95
|
**Result (diff)**
|
|
96
|
+
|
|
90
97
|
```diff
|
|
91
98
|
- const Checkout = () => <button>Buy</button>
|
|
92
99
|
+ export function CheckoutFlow({ customer }: { customer: string }) {
|
|
@@ -100,6 +107,7 @@ Each platform generates bridge files that the AI tool auto-reads. If a bridge fi
|
|
|
100
107
|
## Use it in your tool
|
|
101
108
|
|
|
102
109
|
**Cursor** — rules auto-load from `.cursor/rules/`, slash commands in `.cursor/prompts/`
|
|
110
|
+
|
|
103
111
|
```
|
|
104
112
|
/analyze # scan codebase and generate standards
|
|
105
113
|
/review # code review with checklist
|
|
@@ -107,6 +115,7 @@ Each platform generates bridge files that the AI tool auto-reads. If a bridge fi
|
|
|
107
115
|
```
|
|
108
116
|
|
|
109
117
|
**Claude Code** — `CLAUDE.md` uses `@` imports to auto-load all standards into context every session (no manual reads needed, saves tokens). Slash commands in `.claude/commands/`.
|
|
118
|
+
|
|
110
119
|
```bash
|
|
111
120
|
/analyze # scan codebase and generate standards
|
|
112
121
|
/review # code review with checklist
|
|
@@ -114,16 +123,19 @@ claude "create checkout flow for customer"
|
|
|
114
123
|
```
|
|
115
124
|
|
|
116
125
|
**GitHub Copilot** — reads `.github/copilot-instructions.md` automatically
|
|
126
|
+
|
|
117
127
|
```
|
|
118
128
|
@.contextkit Create checkout flow for customer
|
|
119
129
|
```
|
|
120
130
|
|
|
121
131
|
**Codex CLI** — reads `AGENTS.md` automatically
|
|
132
|
+
|
|
122
133
|
```bash
|
|
123
134
|
codex "create checkout flow for customer"
|
|
124
135
|
```
|
|
125
136
|
|
|
126
137
|
**OpenCode** — reads `AGENTS.md` automatically
|
|
138
|
+
|
|
127
139
|
```bash
|
|
128
140
|
opencode "create checkout flow for customer"
|
|
129
141
|
```
|
|
@@ -134,27 +146,27 @@ opencode "create checkout flow for customer"
|
|
|
134
146
|
|
|
135
147
|
ContextKit installs reusable slash commands for supported platforms:
|
|
136
148
|
|
|
137
|
-
| Command
|
|
138
|
-
|
|
139
|
-
| `/analyze`
|
|
140
|
-
| `/review`
|
|
141
|
-
| `/fix`
|
|
142
|
-
| `/refactor`
|
|
143
|
-
| `/test`
|
|
144
|
-
| `/doc`
|
|
145
|
-
| `/doc-arch`
|
|
146
|
-
| `/doc-feature`
|
|
147
|
-
| `/doc-component`
|
|
148
|
-
| `/spec`
|
|
149
|
-
| `/squad`
|
|
150
|
-
| `/squad-architect`
|
|
151
|
-
| `/squad-dev`
|
|
152
|
-
| `/squad-test`
|
|
153
|
-
| `/squad-review`
|
|
154
|
-
| `/squad-doc`
|
|
155
|
-
| `/squad-auto`
|
|
156
|
-
| `/squad-auto-parallel` | Auto-run the pipeline in parallel using Claude Code agents (Claude Code only)
|
|
157
|
-
| `/ck`
|
|
149
|
+
| Command | What it does |
|
|
150
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
151
|
+
| `/analyze` | Scan codebase and generate standards content |
|
|
152
|
+
| `/review` | Code review with checklist |
|
|
153
|
+
| `/fix` | Diagnose and fix bugs |
|
|
154
|
+
| `/refactor` | Refactor code with safety checks |
|
|
155
|
+
| `/test` | Generate comprehensive tests |
|
|
156
|
+
| `/doc` | Add documentation |
|
|
157
|
+
| `/doc-arch` | Generate architecture docs (`docs/architecture.md`) — stack-aware (Level 1) |
|
|
158
|
+
| `/doc-feature` | Generate feature-level docs (`docs/features/<name>.md`) — stack-aware (Level 2) |
|
|
159
|
+
| `/doc-component` | Generate component-level docs colocated with the target file — stack-aware (Level 3) |
|
|
160
|
+
| `/spec` | Write a component spec (MD-first) before any code is created |
|
|
161
|
+
| `/squad` | Kick off a squad task — one task or many (auto-detects batch mode). Pushes back with clarifying questions if the task is vague. |
|
|
162
|
+
| `/squad-architect` | Design the technical plan from the PO spec |
|
|
163
|
+
| `/squad-dev` | Implement code following the architect plan |
|
|
164
|
+
| `/squad-test` | Write and run tests against acceptance criteria |
|
|
165
|
+
| `/squad-review` | Review the full pipeline and give a verdict |
|
|
166
|
+
| `/squad-doc` | Create companion `.md` files for new/modified code after review passes |
|
|
167
|
+
| `/squad-auto` | Auto-run the full pipeline after kickoff (recommended, sequential) |
|
|
168
|
+
| `/squad-auto-parallel` | Auto-run the pipeline in parallel using Claude Code agents (Claude Code only) |
|
|
169
|
+
| `/ck` | Health check — verify setup, standards, and integrations |
|
|
158
170
|
|
|
159
171
|
**Claude Code** — available as `/analyze`, `/review`, etc. in `.claude/commands/`
|
|
160
172
|
**Cursor** — available as slash commands in Chat via `.cursor/prompts/`
|
|
@@ -169,14 +181,14 @@ The squad workflow turns a single AI session into a structured multi-role pipeli
|
|
|
169
181
|
|
|
170
182
|
### Pipeline Roles
|
|
171
183
|
|
|
172
|
-
| Step | Role
|
|
173
|
-
|
|
174
|
-
| 1
|
|
175
|
-
| 2
|
|
176
|
-
| 3
|
|
177
|
-
| 4
|
|
178
|
-
| 5
|
|
179
|
-
| 6
|
|
184
|
+
| Step | Role | Command | What it does |
|
|
185
|
+
| ---- | ------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
186
|
+
| 1 | Product Owner | `/squad` | Writes a user story, acceptance criteria, edge cases, and scope. If the task is ambiguous, asks up to 5 clarifying questions before writing the spec. Optionally captures screenshots/images as visual assets. |
|
|
187
|
+
| 2 | Architect | `/squad-architect` | Designs the technical approach, files to change, and implementation steps |
|
|
188
|
+
| 3 | Developer | `/squad-dev` | Implements the code following the architect's plan |
|
|
189
|
+
| 4 | Tester | `/squad-test` | Writes and runs tests against the PO's acceptance criteria |
|
|
190
|
+
| 5 | Reviewer | `/squad-review` | Reviews everything and gives a PASS or NEEDS-WORK verdict |
|
|
191
|
+
| 6 | Doc Writer | `/squad-doc` | Creates companion `.md` files for every new/modified code file |
|
|
180
192
|
|
|
181
193
|
### Single-Task Flow
|
|
182
194
|
|
|
@@ -218,8 +230,9 @@ Pass multiple tasks to `/squad` and it automatically runs in batch mode:
|
|
|
218
230
|
|
|
219
231
|
```markdown
|
|
220
232
|
# .contextkit/squad/config.md
|
|
233
|
+
|
|
221
234
|
checkpoint: po
|
|
222
|
-
model_routing: true
|
|
235
|
+
model_routing: true # dev + test → Haiku, architect + review → primary model
|
|
223
236
|
```
|
|
224
237
|
|
|
225
238
|
### Feedback Loop
|
|
@@ -246,24 +259,29 @@ ContextKit can optionally install Git hooks during `ck install`. Uses `git confi
|
|
|
246
259
|
|
|
247
260
|
For **Node.js projects**, a `prepare` script is automatically added to `package.json` so hooks activate for all developers after `npm install` — no need for everyone to run `ck install`.
|
|
248
261
|
|
|
249
|
-
|
|
250
|
-
|------|-------------|
|
|
251
|
-
| **pre-push** | **Quality Gates** — auto-detects your project framework and runs the appropriate checks |
|
|
252
|
-
| **commit-msg** | Enforces [Conventional Commits](https://www.conventionalcommits.org/) format |
|
|
262
|
+
If you enable the pre-push hook on a Node.js project that has no `format` or `lint` scripts, `ck install` will offer to scaffold a minimal **prettier + eslint** setup for you (adds scripts, `.prettierrc`, `.prettierignore`, `eslint.config.js`, and installs the devDependencies). Answer No to skip and set it up manually later.
|
|
253
263
|
|
|
254
|
-
|
|
264
|
+
| Hook | What it does |
|
|
265
|
+
| -------------- | --------------------------------------------------------------------------------------- |
|
|
266
|
+
| **pre-push** | **Quality Gates** — auto-detects your project framework and runs the appropriate checks |
|
|
267
|
+
| **commit-msg** | Enforces [Conventional Commits](https://www.conventionalcommits.org/) format |
|
|
255
268
|
|
|
256
|
-
|
|
269
|
+
### Framework-Aware Quality Gates
|
|
257
270
|
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
|
261
|
-
|
|
|
262
|
-
| **
|
|
263
|
-
| **
|
|
264
|
-
| **
|
|
265
|
-
| **
|
|
266
|
-
| **
|
|
271
|
+
The pre-push hook detects your project type and runs the right quality checks automatically. All gates are skipped silently when tools aren't installed.
|
|
272
|
+
|
|
273
|
+
| Framework | Checks |
|
|
274
|
+
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
275
|
+
| **Node.js** | TypeScript, ESLint, Prettier, `format` script, `lint` script, build, test, e2e — each only runs when present in `package.json` scripts or dependencies; auto-detects npm/yarn/pnpm/bun |
|
|
276
|
+
| **Python** | ruff/flake8, mypy, black/ruff format, pytest |
|
|
277
|
+
| **Rust** | cargo check, clippy, cargo test |
|
|
278
|
+
| **Go** | go vet, golangci-lint, go test |
|
|
279
|
+
| **PHP** | PHPStan, PHPUnit |
|
|
280
|
+
| **Ruby** | RuboCop, RSpec/rake test |
|
|
281
|
+
| **Java** | Maven verify / Gradle check |
|
|
282
|
+
| **Kotlin** | ktlint, Gradle test |
|
|
283
|
+
| **Swift** | SwiftLint, swift test |
|
|
284
|
+
| **.NET / C#** | dotnet build, dotnet test |
|
|
267
285
|
|
|
268
286
|
### Commit Message Format
|
|
269
287
|
|
|
@@ -276,6 +294,7 @@ When the `commit-msg` hook is enabled, all commits must follow this format:
|
|
|
276
294
|
**Types:** `feat`, `fix`, `improve`, `docs`, `refactor`, `test`, `chore`
|
|
277
295
|
|
|
278
296
|
**Examples:**
|
|
297
|
+
|
|
279
298
|
```bash
|
|
280
299
|
git commit -m "feat(auth): add login page"
|
|
281
300
|
git commit -m "fix: resolve null pointer in checkout"
|
package/bin/contextkit.js
CHANGED
|
@@ -22,7 +22,9 @@ program
|
|
|
22
22
|
// Install command
|
|
23
23
|
program
|
|
24
24
|
.command('install [platform]')
|
|
25
|
-
.description(
|
|
25
|
+
.description(
|
|
26
|
+
'Initialize ContextKit in the current project directory (run once per project, not global)'
|
|
27
|
+
)
|
|
26
28
|
.option('--no-hooks', 'Skip Git hooks installation')
|
|
27
29
|
.option('--non-interactive', 'Skip interactive prompts')
|
|
28
30
|
.action(async (platform, options) => {
|
|
@@ -256,7 +258,7 @@ program
|
|
|
256
258
|
});
|
|
257
259
|
|
|
258
260
|
// Catch-all for unknown commands
|
|
259
|
-
program.on('command:*', function(args) {
|
|
261
|
+
program.on('command:*', function (args) {
|
|
260
262
|
console.error(chalk.red(`Unknown command: ${args[0]}`));
|
|
261
263
|
console.log(chalk.yellow('Run `ck --help` to see available commands.'));
|
|
262
264
|
process.exit(1);
|