@karthikrajkumar.kannan/get-things-done 1.0.2 → 1.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +568 -103
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,223 +4,686 @@
|
|
|
4
4
|
|
|
5
5
|
**The first bidirectional spec-driven agentic framework for AI-assisted development.**
|
|
6
6
|
|
|
7
|
-
**Forward.**
|
|
8
|
-
**Backward.**
|
|
9
|
-
**In Sync.** Detect drift. Reconcile
|
|
7
|
+
**Forward.** Take an idea, research it, plan it, generate code, deploy it, test it.
|
|
8
|
+
**Backward.** Take existing code, analyze it deeply, generate 7 types of technical documents.
|
|
9
|
+
**In Sync.** Detect when specs and code drift apart. Reconcile automatically.
|
|
10
10
|
|
|
11
|
-
[](https://www.npmjs.com/package/get-things-done)
|
|
11
|
+
[](https://www.npmjs.com/package/@karthikrajkumar.kannan/get-things-done)
|
|
12
12
|
[](LICENSE)
|
|
13
13
|
[](tests/)
|
|
14
|
+
[]()
|
|
15
|
+
[]()
|
|
14
16
|
|
|
15
17
|
<br>
|
|
16
18
|
|
|
17
19
|
```bash
|
|
18
|
-
npx get-things-done@latest
|
|
20
|
+
npx @karthikrajkumar.kannan/get-things-done@latest
|
|
19
21
|
```
|
|
20
22
|
|
|
21
23
|
**Works with Claude Code, Gemini CLI, OpenCode, Codex, Copilot, Cursor, Windsurf, Augment, and Cline.**
|
|
22
24
|
|
|
25
|
+
**Also available as an MCP server** -- use GTD tools from Python, TypeScript, Go, Rust, or any language.
|
|
26
|
+
|
|
23
27
|
</div>
|
|
24
28
|
|
|
25
29
|
---
|
|
26
30
|
|
|
31
|
+
## Table of Contents
|
|
32
|
+
|
|
33
|
+
- [Why Get Things Done?](#why-get-things-done)
|
|
34
|
+
- [Quick Start](#quick-start)
|
|
35
|
+
- [The Three Modes](#the-three-modes)
|
|
36
|
+
- [What Makes GTD Different](#what-makes-gtd-different)
|
|
37
|
+
- [Installation](#installation)
|
|
38
|
+
- [MCP Server -- Use GTD as Tools from Any Language](#mcp-server----use-gtd-as-tools-from-any-language)
|
|
39
|
+
- [SDK for CI/CD](#sdk-for-cicd)
|
|
40
|
+
- [Architecture](#architecture)
|
|
41
|
+
- [Document Formats](#document-formats)
|
|
42
|
+
- [Scale-Adaptive Intelligence](#scale-adaptive-intelligence)
|
|
43
|
+
- [Complete Command Reference](#complete-command-reference)
|
|
44
|
+
- [Configuration](#configuration)
|
|
45
|
+
- [License](#license)
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
27
49
|
## Why Get Things Done?
|
|
28
50
|
|
|
29
|
-
|
|
51
|
+
Every AI coding tool today goes in **one direction**:
|
|
30
52
|
|
|
31
|
-
|
|
53
|
+
- **GSD, BMAD, SpecKit** take specs and generate code (forward only)
|
|
54
|
+
- **JSDoc, Swagger, Mintlify** take code and generate basic docs (backward only, limited)
|
|
55
|
+
- **Nothing** keeps specs and code in sync after changes
|
|
56
|
+
|
|
57
|
+
GTD is the first framework that does **all three**:
|
|
32
58
|
|
|
33
59
|
```
|
|
34
|
-
FORWARD >>> Idea -> Research -> Spec -> Plan -> Code -> Deploy -> Test
|
|
35
|
-
BACKWARD <<< Code -> Scan -> Analyze -> Draft -> Verify -> Finalize
|
|
36
|
-
SYNC <><> Detect Drift -> Reconcile -> Stay Aligned
|
|
60
|
+
FORWARD >>> Idea -> Research -> Spec -> Plan -> Code -> Deploy -> Test -> Verify
|
|
61
|
+
BACKWARD <<< Code -> Scan -> Analyze -> Draft -> Verify -> Finalize (7 doc types)
|
|
62
|
+
SYNC <><> Detect Drift -> Show Differences -> Reconcile -> Stay Aligned
|
|
37
63
|
```
|
|
38
64
|
|
|
65
|
+
One framework. One `.planning/` directory. One install. Both directions. Always in sync.
|
|
66
|
+
|
|
39
67
|
---
|
|
40
68
|
|
|
41
69
|
## Quick Start
|
|
42
70
|
|
|
71
|
+
### Step 1: Install
|
|
72
|
+
|
|
43
73
|
```bash
|
|
44
|
-
npx get-things-done@latest
|
|
74
|
+
npx @karthikrajkumar.kannan/get-things-done@latest
|
|
45
75
|
```
|
|
46
76
|
|
|
47
|
-
The installer
|
|
48
|
-
1. **
|
|
49
|
-
2. **
|
|
77
|
+
The installer will ask you:
|
|
78
|
+
1. **Which runtime?** -- Claude Code, Cursor, Gemini CLI, Copilot, etc. (multi-select supported)
|
|
79
|
+
2. **Global or local?** -- Global installs for all projects, local for current project only
|
|
50
80
|
|
|
51
|
-
|
|
81
|
+
### Step 2: Open your project in your AI coding tool
|
|
52
82
|
|
|
53
83
|
```bash
|
|
54
|
-
|
|
84
|
+
cd /path/to/your/project
|
|
85
|
+
cursor . # or claude, or your preferred tool
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### Step 3: Start using GTD commands in the AI chat
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
/gtd-help # See all available commands
|
|
92
|
+
|
|
93
|
+
# Document existing code (backward)
|
|
55
94
|
/gtd-scan # Map your codebase
|
|
56
|
-
/gtd-create-tdd # Generate Technical Design Document
|
|
95
|
+
/gtd-create-tdd # Generate a Technical Design Document
|
|
57
96
|
/gtd-create-all # Generate all 7 document types
|
|
58
97
|
|
|
59
|
-
#
|
|
60
|
-
/gtd-new-project #
|
|
61
|
-
/gtd-plan-phase 1 # Research + create plan
|
|
62
|
-
/gtd-execute-phase 1 # Generate code
|
|
98
|
+
# Build from an idea (forward)
|
|
99
|
+
/gtd-new-project # Start from an idea
|
|
100
|
+
/gtd-plan-phase 1 # Research + create execution plan
|
|
101
|
+
/gtd-execute-phase 1 # Generate code with atomic commits
|
|
63
102
|
/gtd-deploy-local # Deploy and test locally
|
|
64
103
|
|
|
65
|
-
#
|
|
104
|
+
# Keep everything aligned (sync)
|
|
66
105
|
/gtd-drift # Detect spec <-> code drift
|
|
67
106
|
/gtd-sync # Auto-reconcile
|
|
68
107
|
```
|
|
69
108
|
|
|
109
|
+
> **Note:** These are slash commands typed in your AI tool's chat panel, not in the terminal.
|
|
110
|
+
|
|
70
111
|
---
|
|
71
112
|
|
|
72
|
-
## Three Modes
|
|
113
|
+
## The Three Modes
|
|
73
114
|
|
|
74
115
|
### Backward Mode: Code to Documents
|
|
75
116
|
|
|
76
|
-
Already have code? Generate professional technical documentation in minutes
|
|
117
|
+
**Already have code? Generate professional technical documentation in minutes.**
|
|
118
|
+
|
|
119
|
+
The backward pipeline reads your entire codebase, performs deep analysis across 7 dimensions, and produces structured, accuracy-verified documents.
|
|
120
|
+
|
|
121
|
+
#### How It Works
|
|
77
122
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
123
|
+
```
|
|
124
|
+
/gtd-scan
|
|
125
|
+
|
|
|
126
|
+
+-- Scans all files (respects .gitignore)
|
|
127
|
+
+-- Detects languages: TypeScript, Python, Go, Rust, Java, Ruby, etc.
|
|
128
|
+
+-- Fingerprints frameworks: Next.js, Express, FastAPI, Django, Spring, etc.
|
|
129
|
+
+-- Identifies entry points, module boundaries, infrastructure
|
|
130
|
+
+-- Output: .planning/CODEBASE-MAP.md
|
|
131
|
+
|
|
132
|
+
/gtd-analyze
|
|
133
|
+
|
|
|
134
|
+
+-- 7 parallel analyzer agents examine your code:
|
|
135
|
+
| +-- Architecture Analyzer -- patterns, layers, components, communication
|
|
136
|
+
| +-- API Extractor -- endpoints, schemas, auth, errors
|
|
137
|
+
| +-- Pattern Detector -- design patterns, conventions, anti-patterns
|
|
138
|
+
| +-- Data Flow Tracer -- request lifecycle, events, transformations
|
|
139
|
+
| +-- Dependency Analyzer -- deps graph, versions, build toolchain
|
|
140
|
+
| +-- Security Scanner -- auth, encryption, validation, vulnerabilities
|
|
141
|
+
| +-- Performance Profiler -- caching, bottlenecks, scaling config
|
|
142
|
+
+-- Output: .planning/analysis/ (7 analysis artifacts)
|
|
143
|
+
|
|
144
|
+
/gtd-create-tdd (or any document type)
|
|
145
|
+
|
|
|
146
|
+
+-- Writer agent reads analysis + template
|
|
147
|
+
+-- Generates structured document with Mermaid diagrams
|
|
148
|
+
+-- Accuracy verifier cross-checks every claim against actual code
|
|
149
|
+
+-- Presents draft with verification score for your review
|
|
150
|
+
+-- Output: .planning/documents/TDD.md
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
#### 7 Document Types
|
|
154
|
+
|
|
155
|
+
| Command | Document | What It Contains |
|
|
156
|
+
|---------|----------|-----------------|
|
|
157
|
+
| `/gtd-create-tdd` | Technical Design Document | Architecture, components, data model, APIs, dependencies, testing |
|
|
158
|
+
| `/gtd-create-hld` | High-Level Design | System overview, subsystems, data flow, integrations, deployment |
|
|
159
|
+
| `/gtd-create-lld` | Low-Level Design | Module specs, function signatures, algorithms, query patterns |
|
|
160
|
+
| `/gtd-create-capacity` | Capacity Plan | Resource requirements, scaling strategy, bottleneck analysis |
|
|
161
|
+
| `/gtd-create-sysdesign` | System Design | End-to-end architecture, security, reliability, observability |
|
|
162
|
+
| `/gtd-create-api-docs` | API Documentation | Every endpoint, request/response schemas, auth, error codes |
|
|
163
|
+
| `/gtd-create-runbook` | Operations Runbook | Deployment procedures, monitoring, incident response, troubleshooting |
|
|
164
|
+
| `/gtd-create-all` | **All 7 documents** | Generates the complete suite in wave-based order |
|
|
88
165
|
|
|
89
|
-
Every document is **accuracy-verified** against your actual code before you see it. No hallucination.
|
|
166
|
+
Every document is **accuracy-verified** against your actual code before you see it. The verifier checks file paths, code snippets, dependency versions, API endpoints, and architectural claims. No hallucination.
|
|
167
|
+
|
|
168
|
+
---
|
|
90
169
|
|
|
91
170
|
### Forward Mode: Idea to Deploy
|
|
92
171
|
|
|
93
|
-
Describe what you want. GTD builds it
|
|
172
|
+
**Describe what you want. GTD builds it.**
|
|
94
173
|
|
|
95
174
|
```
|
|
96
|
-
/gtd-new-project
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
175
|
+
/gtd-new-project "A REST API for managing invoices"
|
|
176
|
+
+-- Adaptive questioning (understands your vision)
|
|
177
|
+
+-- 4 parallel research agents (stack, features, architecture, pitfalls)
|
|
178
|
+
+-- Requirements extraction (v1 must-have, v2 future, out of scope)
|
|
179
|
+
+-- Phased roadmap generation
|
|
180
|
+
+-- Output: PROJECT.md, REQUIREMENTS.md, ROADMAP.md
|
|
181
|
+
|
|
182
|
+
/gtd-plan-phase 1
|
|
183
|
+
+-- 4 parallel phase researchers investigate implementation approaches
|
|
184
|
+
+-- Planner creates detailed task list with dependencies
|
|
185
|
+
+-- Plan-checker verifies quality (up to 3 revision cycles)
|
|
186
|
+
+-- Output: PLAN files with wave-grouped tasks
|
|
187
|
+
|
|
188
|
+
/gtd-execute-phase 1
|
|
189
|
+
+-- Groups tasks into waves (independent tasks run in parallel)
|
|
190
|
+
+-- Executor agent writes code, runs tests, commits atomically per task
|
|
191
|
+
+-- Integration checkpoint between waves
|
|
192
|
+
+-- Output: Committed code + SUMMARY.md
|
|
193
|
+
|
|
194
|
+
/gtd-deploy-local
|
|
195
|
+
+-- Auto-detects: Docker Compose, Dockerfile, npm start, Python/uvicorn, Go, Rust
|
|
196
|
+
+-- Builds project, starts services, health check polling
|
|
197
|
+
+-- Output: DEPLOY-REPORT.md
|
|
198
|
+
|
|
199
|
+
/gtd-test-phase 1
|
|
200
|
+
+-- Auto-detects: Vitest, Jest, pytest, Go test, Cargo test, RSpec
|
|
201
|
+
+-- Runs tests, collects coverage, maps failures to plan tasks
|
|
202
|
+
+-- Output: TEST-REPORT.md
|
|
203
|
+
|
|
204
|
+
/gtd-ship --pr
|
|
205
|
+
+-- Creates a PR with structured description linking to requirements
|
|
102
206
|
```
|
|
103
207
|
|
|
208
|
+
**Autonomous mode:** `/gtd-autonomous 1 --to 5` runs phases 1 through 5 unattended.
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
104
212
|
### Sync Mode: Drift Detection
|
|
105
213
|
|
|
106
|
-
After building, specs and code drift apart. GTD catches it
|
|
214
|
+
**After building, specs and code inevitably drift apart. GTD catches it.**
|
|
215
|
+
|
|
216
|
+
No other framework does this. This is GTD's killer differentiator.
|
|
107
217
|
|
|
108
218
|
```
|
|
109
|
-
/gtd-drift
|
|
110
|
-
|
|
111
|
-
|
|
219
|
+
/gtd-drift
|
|
220
|
+
+-- Compares REQUIREMENTS.md against actual code
|
|
221
|
+
+-- Compares generated documents against actual code
|
|
222
|
+
+-- Categorizes: ADDITION, REMOVAL, MUTATION, STRUCTURAL
|
|
223
|
+
+-- Scores: CRITICAL, MAJOR, MINOR, INFO
|
|
224
|
+
+-- Output: DRIFT-REPORT.md
|
|
225
|
+
|
|
226
|
+
Example: "Found 3 drift items:
|
|
227
|
+
MAJOR: New /api/admin endpoint not in spec
|
|
228
|
+
MINOR: Auth uses session instead of JWT
|
|
229
|
+
INFO: Added rate limiting (improvement)"
|
|
230
|
+
|
|
231
|
+
/gtd-sync --auto
|
|
232
|
+
+-- Detect drift -> Reconcile -> Apply
|
|
233
|
+
+-- Strategies: code-wins (update specs), spec-wins (fix code), interactive
|
|
234
|
+
+-- Output: Everything back in sync
|
|
235
|
+
|
|
236
|
+
/gtd-audit
|
|
237
|
+
+-- Coverage matrix: Requirements -> Code: 94%, -> Docs: 87%, -> Tests: 72%
|
|
238
|
+
+-- Gap analysis with remediation priorities
|
|
239
|
+
+-- Output: AUDIT-REPORT.md
|
|
112
240
|
```
|
|
113
241
|
|
|
114
242
|
---
|
|
115
243
|
|
|
116
244
|
## What Makes GTD Different
|
|
117
245
|
|
|
118
|
-
| Feature | GSD | BMAD | GTD |
|
|
119
|
-
|
|
120
|
-
| Forward (spec to code) | Yes | Yes | **Yes** |
|
|
121
|
-
| Backward (code to docs) | No | No | **
|
|
122
|
-
| Bidirectional sync | No | No | **Yes** |
|
|
123
|
-
| Document accuracy verification | No | No | **
|
|
124
|
-
| Local deploy + test | No | No | **
|
|
125
|
-
| Drift detection | No | No | **
|
|
126
|
-
|
|
|
246
|
+
| Feature | GSD | BMAD | Auto-Doc Tools | **GTD** |
|
|
247
|
+
|---------|-----|------|---------------|---------|
|
|
248
|
+
| Forward (spec to code) | Yes | Yes | No | **Yes** |
|
|
249
|
+
| Backward (code to docs) | No | No | Basic only | **7 document types** |
|
|
250
|
+
| Bidirectional sync | No | No | No | **Yes (drift detection)** |
|
|
251
|
+
| Document accuracy verification | No | No | No | **Cross-checks against code** |
|
|
252
|
+
| Local deploy + test | No | No | No | **Auto-detect + health check** |
|
|
253
|
+
| Drift detection | No | No | No | **4 categories + severity** |
|
|
254
|
+
| Compliance formats | No | No | No | **SOC 2, ISO 27001, HIPAA** |
|
|
255
|
+
| MCP server | No | No | No | **19 tools via stdio** |
|
|
256
|
+
| Scale-adaptive | No | Yes | No | **5 tiers (micro to enterprise)** |
|
|
257
|
+
| Runtime support | 12 | 2 | N/A | **9 runtimes + MCP** |
|
|
127
258
|
|
|
128
259
|
---
|
|
129
260
|
|
|
130
|
-
##
|
|
261
|
+
## Installation
|
|
131
262
|
|
|
132
|
-
|
|
263
|
+
### Interactive Install
|
|
133
264
|
|
|
134
|
-
|
|
135
|
-
-
|
|
136
|
-
|
|
265
|
+
```bash
|
|
266
|
+
npx @karthikrajkumar.kannan/get-things-done@latest
|
|
267
|
+
```
|
|
137
268
|
|
|
138
|
-
|
|
269
|
+
### Non-Interactive Install
|
|
139
270
|
|
|
140
|
-
```
|
|
141
|
-
|
|
271
|
+
```bash
|
|
272
|
+
# Single runtime
|
|
273
|
+
npx @karthikrajkumar.kannan/get-things-done@latest --cursor --local
|
|
274
|
+
npx @karthikrajkumar.kannan/get-things-done@latest --claude --global
|
|
275
|
+
|
|
276
|
+
# Multiple runtimes
|
|
277
|
+
npx @karthikrajkumar.kannan/get-things-done@latest --cursor --claude --global
|
|
278
|
+
|
|
279
|
+
# All runtimes
|
|
280
|
+
npx @karthikrajkumar.kannan/get-things-done@latest --all --local
|
|
142
281
|
```
|
|
143
282
|
|
|
144
|
-
|
|
283
|
+
| Flag | Runtime | Install Path (global) |
|
|
284
|
+
|------|---------|----------------------|
|
|
285
|
+
| `--claude` | Claude Code | `~/.claude/` |
|
|
286
|
+
| `--cursor` | Cursor | `~/.cursor/` |
|
|
287
|
+
| `--gemini` | Gemini CLI | `~/.gemini/` |
|
|
288
|
+
| `--opencode` | OpenCode | `~/.config/opencode/` |
|
|
289
|
+
| `--codex` | Codex | `~/.codex/` |
|
|
290
|
+
| `--copilot` | GitHub Copilot | `~/.github/` |
|
|
291
|
+
| `--windsurf` | Windsurf | `~/.codeium/windsurf/` |
|
|
292
|
+
| `--augment` | Augment | `~/.augment/` |
|
|
293
|
+
| `--cline` | Cline | `~/.cline/` |
|
|
145
294
|
|
|
146
|
-
|
|
295
|
+
### Cursor Setup
|
|
147
296
|
|
|
148
|
-
|
|
297
|
+
```bash
|
|
298
|
+
cd /path/to/your/project
|
|
299
|
+
npx @karthikrajkumar.kannan/get-things-done@latest --cursor --local
|
|
300
|
+
```
|
|
149
301
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
| `enterprise` | 15 | Architecture review boards |
|
|
154
|
-
| `startup` | 7 | Small teams, rapid iteration |
|
|
155
|
-
| `compliance` | 18 | SOC 2, ISO 27001, HIPAA auditors |
|
|
302
|
+
Creates `.cursor/skills/gtd-*/SKILL.md` (40 skills). Open project in Cursor, type `/gtd-help`.
|
|
303
|
+
|
|
304
|
+
### Claude Code Setup
|
|
156
305
|
|
|
157
306
|
```bash
|
|
158
|
-
/
|
|
307
|
+
npx @karthikrajkumar.kannan/get-things-done@latest --claude --global
|
|
159
308
|
```
|
|
160
309
|
|
|
310
|
+
Auto-discovered by Claude Code. Type `/gtd-help` in any project.
|
|
311
|
+
|
|
161
312
|
---
|
|
162
313
|
|
|
163
|
-
##
|
|
314
|
+
## MCP Server -- Use GTD as Tools from Any Language
|
|
315
|
+
|
|
316
|
+
### What is MCP?
|
|
317
|
+
|
|
318
|
+
**MCP (Model Context Protocol)** is an open standard that lets AI applications connect to tool providers. Think of it as "USB for AI tools" -- any MCP client can use any MCP server, regardless of programming language.
|
|
319
|
+
|
|
320
|
+
GTD ships with a built-in MCP server using **stdio transport**:
|
|
321
|
+
- **No HTTP server** to deploy
|
|
322
|
+
- **No ports** to configure
|
|
323
|
+
- **No cloud** -- runs entirely local as a subprocess
|
|
324
|
+
- **Any language** can connect: Python, TypeScript, Go, Rust, Java, etc.
|
|
325
|
+
|
|
326
|
+
### 19 Tools Available
|
|
327
|
+
|
|
328
|
+
| Tool | Description | Category |
|
|
329
|
+
|------|-------------|----------|
|
|
330
|
+
| `gtd_scan` | Scan and map codebase (languages, frameworks, entry points, infrastructure) | Backward |
|
|
331
|
+
| `gtd_analyze` | Deep code analysis across 7 dimensions | Backward |
|
|
332
|
+
| `gtd_create_document` | Generate a specific document (tdd, hld, lld, capacity, system-design, api-docs, runbook) | Backward |
|
|
333
|
+
| `gtd_create_all` | Generate the complete 7-document suite | Backward |
|
|
334
|
+
| `gtd_verify_docs` | Verify document accuracy against actual code | Backward |
|
|
335
|
+
| `gtd_update_docs` | Incrementally update documents (changed sections only) | Backward |
|
|
336
|
+
| `gtd_new_project` | Initialize from idea (questioning, research, requirements, roadmap) | Forward |
|
|
337
|
+
| `gtd_plan_phase` | Research + create verified execution plan | Forward |
|
|
338
|
+
| `gtd_execute_phase` | Execute phase plans (generate code, test, commit) | Forward |
|
|
339
|
+
| `gtd_deploy_local` | Deploy locally (auto-detects Docker, npm, Python, Go, Rust) | Forward |
|
|
340
|
+
| `gtd_test` | Run test suite (auto-detects 6 frameworks) | Forward |
|
|
341
|
+
| `gtd_drift` | Detect spec-code drift (4 categories + severity scoring) | Sync |
|
|
342
|
+
| `gtd_sync` | Auto-reconcile drift (code-wins, spec-wins, interactive) | Sync |
|
|
343
|
+
| `gtd_audit` | Full alignment audit (requirements to code to docs to tests) | Sync |
|
|
344
|
+
| `gtd_status` | Pipeline status (forward + backward + sync) | Utility |
|
|
345
|
+
| `gtd_config` | Get or set configuration values | Utility |
|
|
346
|
+
| `gtd_read_document` | Read a generated document or planning artifact | Utility |
|
|
347
|
+
| `gtd_list_documents` | List all documents with status | Utility |
|
|
348
|
+
| `gtd_scale_detect` | Detect project tier and adaptive config | Utility |
|
|
349
|
+
|
|
350
|
+
### How the MCP Server Works
|
|
164
351
|
|
|
165
|
-
|
|
352
|
+
```
|
|
353
|
+
+----------------------------------------------+
|
|
354
|
+
| YOUR APPLICATION |
|
|
355
|
+
| (Python, TypeScript, Go, Rust, |
|
|
356
|
+
| React app, CLI tool, CI pipeline, |
|
|
357
|
+
| Claude Desktop, or any MCP client) |
|
|
358
|
+
+---------------------+------------------------+
|
|
359
|
+
|
|
|
360
|
+
| stdin/stdout (JSON-RPC)
|
|
361
|
+
| No network. No ports.
|
|
362
|
+
|
|
|
363
|
+
+---------------------v------------------------+
|
|
364
|
+
| GTD MCP SERVER |
|
|
365
|
+
| (Node.js subprocess) |
|
|
366
|
+
| |
|
|
367
|
+
| 19 tools: scan, analyze, create, verify, |
|
|
368
|
+
| drift, sync, audit, status, config, ... |
|
|
369
|
+
| |
|
|
370
|
+
| Reads/writes: .planning/ directory |
|
|
371
|
+
| Reads: source code (your project) |
|
|
372
|
+
+-----------------------------------------------+
|
|
373
|
+
```
|
|
166
374
|
|
|
167
|
-
|
|
168
|
-
|------|-------|----------|
|
|
169
|
-
| Micro | 1-5 | Single combined document |
|
|
170
|
-
| Small | 5-50 | Standard 7-document set |
|
|
171
|
-
| Medium | 50-500 | Full suite with cross-references |
|
|
172
|
-
| Large | 500-5K | Domain-decomposed documents |
|
|
173
|
-
| Enterprise | 5K+ | Service-level docs + integration maps |
|
|
375
|
+
Your app spawns `gtd-mcp-server.cjs` as a child process. Communication is stdin/stdout JSON-RPC. The server lives only as long as your subprocess -- no cleanup needed.
|
|
174
376
|
|
|
175
|
-
|
|
377
|
+
### Setup: Claude Desktop
|
|
176
378
|
|
|
177
|
-
|
|
379
|
+
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
|
|
380
|
+
|
|
381
|
+
```json
|
|
382
|
+
{
|
|
383
|
+
"mcpServers": {
|
|
384
|
+
"gtd": {
|
|
385
|
+
"command": "node",
|
|
386
|
+
"args": [
|
|
387
|
+
"/absolute/path/to/node_modules/@karthikrajkumar.kannan/get-things-done/mcp/gtd-mcp-server.cjs",
|
|
388
|
+
"--project",
|
|
389
|
+
"/absolute/path/to/your/project"
|
|
390
|
+
]
|
|
391
|
+
}
|
|
392
|
+
}
|
|
393
|
+
}
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
Restart Claude Desktop. GTD tools appear in the tools menu. Claude can now scan, generate docs, detect drift through natural conversation.
|
|
397
|
+
|
|
398
|
+
### Setup: Claude Code
|
|
399
|
+
|
|
400
|
+
Add to `.claude/settings.json`:
|
|
401
|
+
|
|
402
|
+
```json
|
|
403
|
+
{
|
|
404
|
+
"mcpServers": {
|
|
405
|
+
"gtd": {
|
|
406
|
+
"command": "node",
|
|
407
|
+
"args": ["./node_modules/@karthikrajkumar.kannan/get-things-done/mcp/gtd-mcp-server.cjs"]
|
|
408
|
+
}
|
|
409
|
+
}
|
|
410
|
+
}
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
### Usage: Python
|
|
178
414
|
|
|
179
415
|
```bash
|
|
180
|
-
|
|
181
|
-
|
|
416
|
+
pip install mcp
|
|
417
|
+
```
|
|
182
418
|
|
|
183
|
-
|
|
184
|
-
|
|
419
|
+
```python
|
|
420
|
+
from mcp import ClientSession, StdioServerParameters
|
|
421
|
+
from mcp.client.stdio import stdio_client
|
|
422
|
+
import asyncio
|
|
423
|
+
|
|
424
|
+
async def main():
|
|
425
|
+
server_params = StdioServerParameters(
|
|
426
|
+
command="node",
|
|
427
|
+
args=[
|
|
428
|
+
"node_modules/@karthikrajkumar.kannan/get-things-done/mcp/gtd-mcp-server.cjs",
|
|
429
|
+
"--project", "/path/to/your/project"
|
|
430
|
+
],
|
|
431
|
+
)
|
|
432
|
+
|
|
433
|
+
async with stdio_client(server_params) as (read, write):
|
|
434
|
+
async with ClientSession(read, write) as session:
|
|
435
|
+
await session.initialize()
|
|
436
|
+
|
|
437
|
+
# List all 19 tools
|
|
438
|
+
tools = await session.list_tools()
|
|
439
|
+
print(f"GTD tools: {len(tools.tools)}")
|
|
440
|
+
|
|
441
|
+
# Scan codebase
|
|
442
|
+
result = await session.call_tool("gtd_scan", arguments={})
|
|
443
|
+
print(result.content[0].text)
|
|
444
|
+
|
|
445
|
+
# Generate TDD
|
|
446
|
+
result = await session.call_tool("gtd_create_document", arguments={
|
|
447
|
+
"doc_type": "tdd", "format": "standard"
|
|
448
|
+
})
|
|
449
|
+
print(result.content[0].text)
|
|
450
|
+
|
|
451
|
+
# Check drift
|
|
452
|
+
result = await session.call_tool("gtd_drift", arguments={})
|
|
453
|
+
print(result.content[0].text)
|
|
454
|
+
|
|
455
|
+
asyncio.run(main())
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
### Usage: TypeScript / Node.js
|
|
185
459
|
|
|
186
|
-
|
|
187
|
-
|
|
460
|
+
```bash
|
|
461
|
+
npm install @modelcontextprotocol/sdk
|
|
188
462
|
```
|
|
189
463
|
|
|
464
|
+
```typescript
|
|
465
|
+
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
|
|
466
|
+
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
|
|
467
|
+
|
|
468
|
+
const transport = new StdioClientTransport({
|
|
469
|
+
command: 'node',
|
|
470
|
+
args: [
|
|
471
|
+
'node_modules/@karthikrajkumar.kannan/get-things-done/mcp/gtd-mcp-server.cjs',
|
|
472
|
+
'--project', '/path/to/project'
|
|
473
|
+
],
|
|
474
|
+
});
|
|
475
|
+
|
|
476
|
+
const client = new Client({ name: 'my-app', version: '1.0.0' }, {});
|
|
477
|
+
await client.connect(transport);
|
|
478
|
+
|
|
479
|
+
const { tools } = await client.listTools(); // 19 tools
|
|
480
|
+
const result = await client.callTool({ name: 'gtd_scan', arguments: {} });
|
|
481
|
+
console.log(result.content[0].text);
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
### Usage: Custom Chat Application
|
|
485
|
+
|
|
486
|
+
For a React + Monaco Editor + Chat app with your own orchestrator:
|
|
487
|
+
|
|
488
|
+
```typescript
|
|
489
|
+
// Backend: connect to GTD once at startup
|
|
490
|
+
const transport = new StdioClientTransport({
|
|
491
|
+
command: 'node',
|
|
492
|
+
args: ['node_modules/@karthikrajkumar.kannan/get-things-done/mcp/gtd-mcp-server.cjs',
|
|
493
|
+
'--project', projectDir],
|
|
494
|
+
});
|
|
495
|
+
const gtdClient = new Client({ name: 'my-ide', version: '1.0.0' }, {});
|
|
496
|
+
await gtdClient.connect(transport);
|
|
497
|
+
|
|
498
|
+
// Route /gtd-* commands from your chat to MCP tool calls
|
|
499
|
+
app.post('/api/chat', async (req, res) => {
|
|
500
|
+
const { message } = req.body;
|
|
501
|
+
if (message.startsWith('/gtd-')) {
|
|
502
|
+
const toolName = message.slice(1).split(' ')[0].replace(/-/g, '_');
|
|
503
|
+
const result = await gtdClient.callTool({ name: toolName, arguments: {} });
|
|
504
|
+
return res.json({ response: result.content[0].text });
|
|
505
|
+
}
|
|
506
|
+
// Normal chat -> forward to Claude/OpenAI
|
|
507
|
+
});
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
### Usage: Claude API with Tool Use
|
|
511
|
+
|
|
512
|
+
Pass GTD tools directly to the Claude API:
|
|
513
|
+
|
|
514
|
+
```python
|
|
515
|
+
import anthropic
|
|
516
|
+
from mcp import ClientSession, StdioServerParameters
|
|
517
|
+
from mcp.client.stdio import stdio_client
|
|
518
|
+
|
|
519
|
+
async def chat_with_gtd():
|
|
520
|
+
server_params = StdioServerParameters(
|
|
521
|
+
command="node",
|
|
522
|
+
args=["./node_modules/@karthikrajkumar.kannan/get-things-done/mcp/gtd-mcp-server.cjs",
|
|
523
|
+
"--project", "."],
|
|
524
|
+
)
|
|
525
|
+
|
|
526
|
+
async with stdio_client(server_params) as (read, write):
|
|
527
|
+
async with ClientSession(read, write) as session:
|
|
528
|
+
await session.initialize()
|
|
529
|
+
|
|
530
|
+
# Convert MCP tools to Claude format
|
|
531
|
+
mcp_tools = await session.list_tools()
|
|
532
|
+
claude_tools = [
|
|
533
|
+
{"name": t.name, "description": t.description, "input_schema": t.inputSchema}
|
|
534
|
+
for t in mcp_tools.tools
|
|
535
|
+
]
|
|
536
|
+
|
|
537
|
+
# Claude decides which GTD tools to call
|
|
538
|
+
client = anthropic.Anthropic()
|
|
539
|
+
response = client.messages.create(
|
|
540
|
+
model="claude-sonnet-4-20250514",
|
|
541
|
+
max_tokens=4096,
|
|
542
|
+
tools=claude_tools,
|
|
543
|
+
messages=[{"role": "user",
|
|
544
|
+
"content": "Scan this codebase and generate a TDD"}],
|
|
545
|
+
)
|
|
546
|
+
|
|
547
|
+
# Execute tool calls
|
|
548
|
+
for block in response.content:
|
|
549
|
+
if block.type == "tool_use":
|
|
550
|
+
result = await session.call_tool(block.name, arguments=block.input)
|
|
551
|
+
print(f"{block.name}: {result.content[0].text[:300]}")
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
### Usage: OpenAI API with Function Calling
|
|
555
|
+
|
|
556
|
+
Same pattern, different format:
|
|
557
|
+
|
|
558
|
+
```python
|
|
559
|
+
import openai
|
|
560
|
+
# ... connect to MCP same as above ...
|
|
561
|
+
|
|
562
|
+
# Convert to OpenAI format
|
|
563
|
+
openai_tools = [
|
|
564
|
+
{"type": "function", "function": {"name": t.name, "description": t.description, "parameters": t.inputSchema}}
|
|
565
|
+
for t in mcp_tools.tools
|
|
566
|
+
]
|
|
567
|
+
|
|
568
|
+
response = openai.chat.completions.create(
|
|
569
|
+
model="gpt-4o", tools=openai_tools,
|
|
570
|
+
messages=[{"role": "user", "content": "Analyze this project"}],
|
|
571
|
+
)
|
|
572
|
+
```
|
|
573
|
+
|
|
574
|
+
### Quick Test
|
|
575
|
+
|
|
576
|
+
```bash
|
|
577
|
+
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}
|
|
578
|
+
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node node_modules/@karthikrajkumar.kannan/get-things-done/mcp/gtd-mcp-server.cjs
|
|
579
|
+
```
|
|
580
|
+
|
|
581
|
+
You should see two JSON responses: server info + list of 19 tools.
|
|
582
|
+
|
|
190
583
|
---
|
|
191
584
|
|
|
192
585
|
## SDK for CI/CD
|
|
193
586
|
|
|
194
587
|
```bash
|
|
195
|
-
npm install get-things-done-sdk
|
|
588
|
+
npm install @karthikrajkumar.kannan/get-things-done-sdk
|
|
196
589
|
```
|
|
197
590
|
|
|
198
591
|
```typescript
|
|
199
|
-
import { GTD } from 'get-things-done-sdk';
|
|
592
|
+
import { GTD } from '@karthikrajkumar.kannan/get-things-done-sdk';
|
|
200
593
|
|
|
201
|
-
const gtd = new GTD({ projectDir: '.', autoMode: true });
|
|
594
|
+
const gtd = new GTD({ projectDir: '.', autoMode: true, format: 'enterprise' });
|
|
202
595
|
const staleness = await gtd.checkStaleness();
|
|
203
|
-
|
|
204
596
|
if (staleness.staleDocuments.length > 0) {
|
|
205
597
|
await gtd.updateAll();
|
|
206
598
|
}
|
|
207
599
|
```
|
|
208
600
|
|
|
601
|
+
See `sdk/examples/` for GitHub Actions and GitLab CI templates.
|
|
602
|
+
|
|
603
|
+
---
|
|
604
|
+
|
|
605
|
+
## Architecture
|
|
606
|
+
|
|
607
|
+
### 33 Specialized Agents
|
|
608
|
+
|
|
609
|
+
| Category | Count | Agents |
|
|
610
|
+
|----------|-------|--------|
|
|
611
|
+
| **Forward: Research** | 3 | project-researcher (x4), phase-researcher (x4), research-synthesizer |
|
|
612
|
+
| **Forward: Planning** | 3 | roadmapper, planner, plan-checker |
|
|
613
|
+
| **Forward: Execution** | 4 | executor, verifier, code-reviewer, debugger |
|
|
614
|
+
| **Forward: Deploy/Test** | 2 | deployer, test-runner |
|
|
615
|
+
| **Backward: Discovery** | 1 | codebase-mapper |
|
|
616
|
+
| **Backward: Analysis** | 7 | architecture, api, patterns, data-flow, dependencies, security, performance |
|
|
617
|
+
| **Backward: Writing** | 8 | tdd, hld, lld, capacity, sysdesign, api-docs, runbook writers + diagram generator |
|
|
618
|
+
| **Backward: Verification** | 2 | accuracy-verifier, completeness-auditor |
|
|
619
|
+
| **Sync** | 3 | drift-detector, reconciliation-planner, alignment-auditor |
|
|
620
|
+
|
|
621
|
+
### Fresh Context Per Agent
|
|
622
|
+
|
|
623
|
+
Every agent spawns with a clean context window. No context rot.
|
|
624
|
+
|
|
625
|
+
### File-Based State
|
|
626
|
+
|
|
627
|
+
All state in `.planning/` as human-readable Markdown. Git-committable. Survives session resets.
|
|
628
|
+
|
|
629
|
+
---
|
|
630
|
+
|
|
631
|
+
## Document Formats
|
|
632
|
+
|
|
633
|
+
| Format | Sections | Best For |
|
|
634
|
+
|--------|----------|----------|
|
|
635
|
+
| `standard` | 10 | Engineering teams |
|
|
636
|
+
| `enterprise` | 15 | Architecture review boards |
|
|
637
|
+
| `startup` | 7 | Small teams, MVPs |
|
|
638
|
+
| `compliance` | 18 | SOC 2, ISO 27001, HIPAA audits |
|
|
639
|
+
|
|
640
|
+
```
|
|
641
|
+
/gtd-create-tdd --format compliance
|
|
642
|
+
```
|
|
643
|
+
|
|
209
644
|
---
|
|
210
645
|
|
|
211
|
-
##
|
|
646
|
+
## Scale-Adaptive Intelligence
|
|
647
|
+
|
|
648
|
+
| Tier | Files | Analysis | Documents |
|
|
649
|
+
|------|-------|----------|-----------|
|
|
650
|
+
| **Micro** | 1-5 | Shallow, 1 agent | Single combined document |
|
|
651
|
+
| **Small** | 5-50 | Standard, 4 agents | Standard 7-document set |
|
|
652
|
+
| **Medium** | 50-500 | Standard, 6 agents | Full suite with cross-references |
|
|
653
|
+
| **Large** | 500-5K | Deep, 7 agents | Per-domain documents with index |
|
|
654
|
+
| **Enterprise** | 5K+ | Deep, 7 agents | Service-level docs + integration maps |
|
|
655
|
+
|
|
656
|
+
---
|
|
657
|
+
|
|
658
|
+
## Complete Command Reference
|
|
659
|
+
|
|
660
|
+
### Backward (15) | Forward (16) | Sync (4) | Utility (5)
|
|
661
|
+
|
|
662
|
+
**Backward:** `/gtd-scan` `/gtd-analyze` `/gtd-create-tdd` `/gtd-create-hld` `/gtd-create-lld` `/gtd-create-capacity` `/gtd-create-sysdesign` `/gtd-create-api-docs` `/gtd-create-runbook` `/gtd-create-all` `/gtd-verify-docs` `/gtd-review-docs` `/gtd-update-docs` `/gtd-diff` `/gtd-doc-status`
|
|
212
663
|
|
|
213
|
-
|
|
214
|
-
`/gtd-scan` `/gtd-analyze` `/gtd-create-tdd` `/gtd-create-hld` `/gtd-create-lld` `/gtd-create-capacity` `/gtd-create-sysdesign` `/gtd-create-api-docs` `/gtd-create-runbook` `/gtd-create-all` `/gtd-verify-docs` `/gtd-review-docs` `/gtd-update-docs` `/gtd-diff` `/gtd-doc-status`
|
|
664
|
+
**Forward:** `/gtd-new-project` `/gtd-discuss-phase` `/gtd-plan-phase` `/gtd-execute-phase` `/gtd-verify-work` `/gtd-deploy-local` `/gtd-test-phase` `/gtd-ship` `/gtd-next` `/gtd-autonomous` `/gtd-quick` `/gtd-fast` `/gtd-debug` `/gtd-code-review` `/gtd-add-phase` `/gtd-progress`
|
|
215
665
|
|
|
216
|
-
|
|
217
|
-
`/gtd-new-project` `/gtd-discuss-phase` `/gtd-plan-phase` `/gtd-execute-phase` `/gtd-verify-work` `/gtd-deploy-local` `/gtd-test-phase` `/gtd-ship` `/gtd-next` `/gtd-autonomous` `/gtd-quick` `/gtd-fast` `/gtd-debug` `/gtd-code-review` `/gtd-add-phase` `/gtd-progress`
|
|
666
|
+
**Sync:** `/gtd-drift` `/gtd-reconcile` `/gtd-sync` `/gtd-audit`
|
|
218
667
|
|
|
219
|
-
|
|
220
|
-
`/gtd-drift` `/gtd-reconcile` `/gtd-sync` `/gtd-audit`
|
|
668
|
+
**Utility:** `/gtd-help` `/gtd-status` `/gtd-settings` `/gtd-health` `/gtd-map-codebase`
|
|
221
669
|
|
|
222
|
-
|
|
223
|
-
|
|
670
|
+
---
|
|
671
|
+
|
|
672
|
+
## Configuration
|
|
673
|
+
|
|
674
|
+
```
|
|
675
|
+
/gtd-settings documents.format enterprise
|
|
676
|
+
/gtd-settings models.analyzer opus
|
|
677
|
+
```
|
|
678
|
+
|
|
679
|
+
| Setting | Default | Options |
|
|
680
|
+
|---------|---------|---------|
|
|
681
|
+
| `documents.format` | `standard` | `standard`, `enterprise`, `startup`, `compliance` |
|
|
682
|
+
| `models.analyzer` | `sonnet` | `sonnet`, `opus`, `haiku` |
|
|
683
|
+
| `models.writer` | `sonnet` | `sonnet`, `opus`, `haiku` |
|
|
684
|
+
| `analysis.depth` | `standard` | `shallow`, `standard`, `deep` |
|
|
685
|
+
| `workflow.parallelization` | `true` | `true`, `false` |
|
|
686
|
+
| `planning.granularity` | `standard` | `coarse`, `standard`, `fine` |
|
|
224
687
|
|
|
225
688
|
---
|
|
226
689
|
|
|
@@ -234,4 +697,6 @@ MIT License. See [LICENSE](LICENSE).
|
|
|
234
697
|
|
|
235
698
|
**Get Things Done.** Forward. Backward. In Sync.
|
|
236
699
|
|
|
700
|
+
*33 agents. 40 commands. 19 MCP tools. 1,030 tests. One framework.*
|
|
701
|
+
|
|
237
702
|
</div>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@karthikrajkumar.kannan/get-things-done",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.3",
|
|
4
4
|
"description": "Bidirectional spec-driven agentic framework — Forward (idea to code to deploy), Backward (code to docs), Sync (drift detection and reconciliation). The first framework that goes both ways.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ai",
|