@karthikrajkumar.kannan/get-things-done 1.0.2 → 1.0.4

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