@karthikrajkumar.kannan/get-things-done 1.0.0

package/lib/template.cjs

@@ -0,0 +1,218 @@
+/**
+ * GTD Template Engine — Variable substitution, conditionals, file includes.
+ *
+ * Template syntax:
+ *   {{variable_name}}                 — Replaced with context value
+ *   {{#section_name}} ... {{/section_name}} — Conditional section (included if truthy)
+ *   {{^section_name}} ... {{/section_name}} — Inverted section (included if falsy)
+ *   {{@file:path}}                    — Inline file content
+ *
+ * @module lib/template
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Resolve templates directory relative to package root
+const TEMPLATES_DIR = path.resolve(__dirname, '..', 'templates');
+
+/**
+ * Fill a template with variables.
+ *
+ * @param {string} templateContent - Raw template string
+ * @param {object} variables - Key-value pairs for substitution
+ * @returns {string} Filled template
+ */
+function fill(templateContent, variables) {
+  let result = templateContent;
+
+  // 1. Process conditional sections: {{#flag}} ... {{/flag}}
+  result = result.replace(
+    /\{\{#(\w+)\}\}([\s\S]*?)\{\{\/\1\}\}/g,
+    (_match, key, content) => {
+      return variables[key] ? content : '';
+    },
+  );
+
+  // 2. Process inverted sections: {{^flag}} ... {{/flag}}
+  result = result.replace(
+    /\{\{\^(\w+)\}\}([\s\S]*?)\{\{\/\1\}\}/g,
+    (_match, key, content) => {
+      return !variables[key] ? content : '';
+    },
+  );
+
+  // 3. Process file includes: {{@file:path}}
+  result = result.replace(/\{\{@file:(.*?)\}\}/g, (_match, filePath) => {
+    try {
+      const resolved = path.isAbsolute(filePath)
+        ? filePath
+        : path.resolve(process.cwd(), filePath);
+      return fs.readFileSync(resolved, 'utf8');
+    } catch (_) {
+      return `<!-- File not found: ${filePath} -->`;
+    }
+  });
+
+  // 4. Process variable substitution: {{variable_name}}
+  result = result.replace(/\{\{(\w[\w.]*)\}\}/g, (_match, key) => {
+    const value = getNestedValue(variables, key);
+    if (value === undefined || value === null) return _match; // Preserve unresolved
+    return String(value);
+  });
+
+  return result;
+}
+
+/**
+ * Load and fill a template by type and format.
+ *
+ * @param {string} type - Template type ('tdd', 'hld', 'lld', etc.)
+ * @param {string} [format='standard'] - Format variant ('standard', 'enterprise', 'startup', 'compliance')
+ * @param {object} variables - Variables for substitution
+ * @returns {string} Filled template
+ */
+function loadAndFill(type, format, variables) {
+  const templatePath = resolveTemplate(type, format);
+  const content = fs.readFileSync(templatePath, 'utf8');
+  return fill(content, variables);
+}
+
+/**
+ * Resolve a template file path by type and format.
+ * Resolution chain: format-specific → standard → default
+ *
+ * @param {string} type - Template type
+ * @param {string} [format='standard'] - Format variant
+ * @returns {string} Absolute path to template file
+ * @throws {Error} If no template found
+ */
+function resolveTemplate(type, format) {
+  const formatName = format || 'standard';
+
+  // Check backward templates first, then forward
+  const candidates = [
+    path.join(TEMPLATES_DIR, 'backward', type, `${formatName}.md`),
+    path.join(TEMPLATES_DIR, 'backward', type, 'standard.md'),
+    path.join(TEMPLATES_DIR, 'backward', type, 'default.md'),
+    path.join(TEMPLATES_DIR, 'forward', type, `${formatName}.md`),
+    path.join(TEMPLATES_DIR, 'forward', type, 'standard.md'),
+    path.join(TEMPLATES_DIR, type, `${formatName}.md`),
+    path.join(TEMPLATES_DIR, type, 'standard.md'),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+
+  throw new Error(
+    `Template not found for type="${type}", format="${formatName}". ` +
+      `Searched: ${candidates.map((c) => path.relative(TEMPLATES_DIR, c)).join(', ')}`,
+  );
+}
+
+/**
+ * List all available template types and their formats.
+ *
+ * @returns {Array<{type: string, formats: string[]}>}
+ */
+function listTemplates() {
+  const result = [];
+
+  for (const subdir of ['backward', 'forward']) {
+    const dir = path.join(TEMPLATES_DIR, subdir);
+    if (!fs.existsSync(dir)) continue;
+
+    for (const typeDir of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!typeDir.isDirectory()) continue;
+
+      const typePath = path.join(dir, typeDir.name);
+      const formats = fs.readdirSync(typePath)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => f.replace('.md', ''));
+
+      if (formats.length > 0) {
+        result.push({ type: typeDir.name, category: subdir, formats });
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Validate a template for syntax errors.
+ *
+ * @param {string} content - Template content
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateTemplate(content) {
+  const errors = [];
+
+  // Check for unclosed conditional sections
+  const opens = content.match(/\{\{#(\w+)\}\}/g) || [];
+  const closes = content.match(/\{\{\/(\w+)\}\}/g) || [];
+
+  const openNames = opens.map((m) => m.match(/\{\{#(\w+)\}\}/)[1]);
+  const closeNames = closes.map((m) => m.match(/\{\{\/(\w+)\}\}/)[1]);
+
+  for (const name of openNames) {
+    if (!closeNames.includes(name)) {
+      errors.push(`Unclosed section: {{#${name}}} has no matching {{/${name}}}`);
+    }
+  }
+
+  for (const name of closeNames) {
+    if (!openNames.includes(name)) {
+      errors.push(`Orphaned close: {{/${name}}} has no matching {{#${name}}}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// --- Utility ---
+
+function getNestedValue(obj, dotPath) {
+  const keys = dotPath.split('.');
+  let current = obj;
+  for (const key of keys) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return undefined;
+    }
+    current = current[key];
+  }
+  return current;
+}
+
+// CLI handler
+function run(args) {
+  const subcommand = args[0];
+
+  if (subcommand === 'list') {
+    process.stdout.write(JSON.stringify(listTemplates(), null, 2));
+  } else if (subcommand === 'resolve' && args[1]) {
+    try {
+      const resolved = resolveTemplate(args[1], args[2]);
+      process.stdout.write(resolved);
+    } catch (err) {
+      process.stderr.write(err.message + '\n');
+      process.exit(1);
+    }
+  } else {
+    process.stderr.write('Usage: gtd-tools.cjs template <list|resolve> [type] [format]\n');
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  fill,
+  loadAndFill,
+  resolveTemplate,
+  listTemplates,
+  validateTemplate,
+  TEMPLATES_DIR,
+  run,
+};

package/lib/test-runner.cjs

@@ -0,0 +1,202 @@
+/**
+ * GTD Test Runner Module — Test framework detection, discovery, and execution.
+ * @module lib/test-runner
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { fileExists } = require('./file-ops.cjs');
+
+/**
+ * Test framework detection rules.
+ */
+const TEST_FRAMEWORKS = [
+  {
+    name: 'vitest',
+    detect: (root) => {
+      const pkg = loadPkg(root);
+      return (pkg?.devDependencies?.vitest || pkg?.dependencies?.vitest) ? true : false;
+    },
+    runCmd: 'npx vitest run',
+    coverageCmd: 'npx vitest run --coverage',
+    filePattern: '**/*.test.{ts,js,tsx,jsx}',
+    configFiles: ['vitest.config.ts', 'vitest.config.js'],
+  },
+  {
+    name: 'jest',
+    detect: (root) => {
+      const pkg = loadPkg(root);
+      return (pkg?.devDependencies?.jest || pkg?.dependencies?.jest) ? true : false;
+    },
+    runCmd: 'npx jest',
+    coverageCmd: 'npx jest --coverage',
+    filePattern: '**/*.test.{ts,js,tsx,jsx}',
+    configFiles: ['jest.config.ts', 'jest.config.js'],
+  },
+  {
+    name: 'pytest',
+    detect: (root) =>
+      fileExists(path.join(root, 'pytest.ini')) ||
+      fileExists(path.join(root, 'pyproject.toml')) ||
+      fileExists(path.join(root, 'conftest.py')) ||
+      fs.existsSync(path.join(root, 'tests')) && hasFiles(path.join(root, 'tests'), 'test_*.py'),
+    runCmd: 'pytest',
+    coverageCmd: 'pytest --cov',
+    filePattern: '**/test_*.py',
+    configFiles: ['pytest.ini', 'pyproject.toml', 'setup.cfg'],
+  },
+  {
+    name: 'go-test',
+    detect: (root) =>
+      fileExists(path.join(root, 'go.mod')) &&
+      hasFiles(root, '*_test.go'),
+    runCmd: 'go test ./...',
+    coverageCmd: 'go test ./... -cover',
+    filePattern: '**/*_test.go',
+    configFiles: [],
+  },
+  {
+    name: 'cargo-test',
+    detect: (root) => fileExists(path.join(root, 'Cargo.toml')),
+    runCmd: 'cargo test',
+    coverageCmd: 'cargo tarpaulin',
+    filePattern: '**/tests/**/*.rs',
+    configFiles: ['Cargo.toml'],
+  },
+  {
+    name: 'rspec',
+    detect: (root) =>
+      fileExists(path.join(root, 'Gemfile')) &&
+      fs.existsSync(path.join(root, 'spec')),
+    runCmd: 'bundle exec rspec',
+    coverageCmd: 'bundle exec rspec',
+    filePattern: 'spec/**/*_spec.rb',
+    configFiles: ['.rspec', 'spec/spec_helper.rb'],
+  },
+];
+
+/**
+ * Detect the test framework for a project.
+ * @param {string} projectRoot - Project root directory
+ * @returns {{ name: string, runCmd: string, coverageCmd: string, filePattern: string }|null}
+ */
+function detectTestFramework(projectRoot) {
+  for (const fw of TEST_FRAMEWORKS) {
+    if (fw.detect(projectRoot)) {
+      return {
+        name: fw.name,
+        runCmd: fw.runCmd,
+        coverageCmd: fw.coverageCmd,
+        filePattern: fw.filePattern,
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Count test files in a project.
+ * @param {string} projectRoot - Project root directory
+ * @param {string} [pattern] - Glob pattern for test files
+ * @returns {number}
+ */
+function countTestFiles(projectRoot, pattern) {
+  const fw = detectTestFramework(projectRoot);
+  if (!fw && !pattern) return 0;
+
+  const searchPattern = pattern || fw.filePattern;
+  let count = 0;
+
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === 'dist') continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (matchesTestPattern(entry.name, searchPattern)) {
+        count++;
+      }
+    }
+  }
+
+  walk(projectRoot);
+  return count;
+}
+
+/**
+ * Get test infrastructure summary.
+ * @param {string} projectRoot - Project root directory
+ * @returns {{ framework: string|null, testFiles: number, hasConfig: boolean, runCmd: string|null }}
+ */
+function getTestSummary(projectRoot) {
+  const fw = detectTestFramework(projectRoot);
+  if (!fw) {
+    return { framework: null, testFiles: 0, hasConfig: false, runCmd: null };
+  }
+
+  const testFiles = countTestFiles(projectRoot, fw.filePattern);
+  const hasConfig = fw.configFiles
+    ? fw.configFiles.some((cf) => fileExists(path.join(projectRoot, cf)))
+    : false;
+
+  return {
+    framework: fw.name,
+    testFiles,
+    hasConfig,
+    runCmd: fw.runCmd,
+    coverageCmd: fw.coverageCmd,
+  };
+}
+
+// --- Helpers ---
+
+function loadPkg(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+function hasFiles(dir, pattern) {
+  try {
+    return fs.readdirSync(dir).some((f) => matchesTestPattern(f, pattern));
+  } catch (_) {
+    return false;
+  }
+}
+
+function matchesTestPattern(filename, pattern) {
+  // Simple pattern matching: *.test.js, test_*.py, *_test.go
+  if (pattern.includes('test_*.py')) return filename.startsWith('test_') && filename.endsWith('.py');
+  if (pattern.includes('*_test.go')) return filename.endsWith('_test.go');
+  if (pattern.includes('*_spec.rb')) return filename.endsWith('_spec.rb');
+  if (pattern.includes('*.test.')) return filename.includes('.test.');
+  return false;
+}
+
+// CLI handler
+function run(args) {
+  const projectRoot = process.cwd();
+  const subcommand = args[0] || 'detect';
+
+  if (subcommand === 'detect') {
+    process.stdout.write(JSON.stringify(getTestSummary(projectRoot), null, 2));
+  } else if (subcommand === 'count') {
+    process.stdout.write(JSON.stringify(countTestFiles(projectRoot)));
+  } else {
+    process.stderr.write('Usage: gtd-tools.cjs test <detect|count>\n');
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  TEST_FRAMEWORKS,
+  detectTestFramework,
+  countTestFiles,
+  getTestSummary,
+  run,
+};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@karthikrajkumar.kannan/get-things-done",
+  "version": "1.0.0",
+  "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.",
+  "keywords": [
+    "ai",
+    "agentic",
+    "spec-driven",
+    "documentation",
+    "code-generation",
+    "claude",
+    "claude-code",
+    "llm",
+    "technical-design",
+    "reverse-engineering",
+    "drift-detection",
+    "bidirectional",
+    "gemini",
+    "copilot",
+    "cursor",
+    "windsurf",
+    "codex"
+  ],
+  "author": "GTD Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/get-things-done/get-things-done"
+  },
+  "bin": {
+    "get-things-done": "./bin/install.js"
+  },
+  "main": "./bin/gtd-tools.cjs",
+  "files": [
+    "bin/",
+    "lib/",
+    "agents/",
+    "commands/",
+    "workflows/",
+    "references/",
+    "templates/",
+    "contexts/",
+    "hooks/"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "quality": "npm run lint && npm run format:check && npm run test",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "vitest": "^3.1.0",
+    "@vitest/coverage-v8": "^3.1.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.5.0",
+    "husky": "^9.1.0",
+    "lint-staged": "^15.4.0"
+  },
+  "lint-staged": {
+    "*.{js,cjs,ts}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{md,json,yml,yaml}": [
+      "prettier --write"
+    ]
+  }
+}

package/references/agent-contracts.md

@@ -0,0 +1,157 @@
+# Agent Contracts
+
+> Formal interface definitions between orchestrators and agents in the forward pipeline.
+
+---
+
+## Contract Overview
+
+Every agent interaction follows this lifecycle:
+
+```
+Orchestrator --> [Spawn] --> Agent
+Orchestrator --> [Context Bundle] --> Agent
+Agent --> [File Artifacts] --> Orchestrator
+Agent --> [Status Signal] --> Orchestrator
+```
+
+---
+
+## Spawn Protocol
+
+### How Orchestrators Spawn Agents
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `agent_type` | Yes | One of: `research`, `planning`, `execution`, `gate` |
+| `agent_id` | Yes | Unique identifier, format: `{{agent_type}}-{{sequence}}` |
+| `task_description` | Yes | One-line description of what the agent must do |
+| `context_files` | Yes | List of file paths the agent must read before starting |
+| `output_files` | Yes | List of file paths the agent must produce |
+| `timeout_ms` | No | Override default timeout (see defaults below) |
+| `max_retries` | No | Override default retry count |
+
+### Example Spawn
+
+```json
+{
+  "agent_type": "research",
+  "agent_id": "research-1",
+  "task_description": "Analyze technology stack options for a React + Node.js SaaS app",
+  "context_files": [
+    "PROJECT.md",
+    "REQUIREMENTS.md"
+  ],
+  "output_files": [
+    "research/STACK.md"
+  ],
+  "timeout_ms": 120000,
+  "max_retries": 1
+}
+```
+
+---
+
+## Context Bundle
+
+What the agent receives when spawned.
+
+| Agent Type | Always Receives | Conditionally Receives |
+|-----------|----------------|----------------------|
+| Research | PROJECT.md, REQUIREMENTS.md | Prior research outputs (if re-running) |
+| Planning | PROJECT.md, REQUIREMENTS.md, research/* | User feedback (if revision) |
+| Execution | PROJECT.md, phase CONTEXT.md, phase PROMPT.md | Prior phase artifacts |
+| Gate | Phase output files, REQUIREMENTS.md | ROADMAP.md (for cross-phase gates) |
+
+### Context Size Rules
+
+- Total context bundle must fit within the agent's allocated token budget
+- If context exceeds budget, orchestrator must summarize or truncate
+- Priority order for truncation: research files > context files > requirements > project
+
+---
+
+## Result Protocol
+
+### How Agents Return Results
+
+Agents communicate results through file artifacts, not return values.
+
+| Signal | Mechanism | Description |
+|--------|-----------|-------------|
+| Success | All `output_files` exist and are non-empty | Agent completed its task |
+| Partial | Some `output_files` exist | Agent completed partially |
+| Failure | No `output_files` created OR error marker file | Agent could not complete |
+| Escalation | `ESCALATION.md` file created | Agent needs human decision |
+
+### Result File Requirements
+
+- Every output file must have a YAML-style header with `agent_id` and `timestamp`
+- Files must be valid Markdown
+- Files must not exceed 500 lines (split into multiple files if needed)
+- Agent must not modify files outside its `output_files` list
+
+---
+
+## Timeout Handling
+
+| Agent Type | Default Timeout | Max Timeout | On Timeout |
+|-----------|----------------|-------------|------------|
+| Research | 120s | 300s | Retry once, then mark partial |
+| Planning | 180s | 300s | Retry once, then escalate |
+| Execution | 300s | 600s | Retry once, then pause pipeline |
+| Gate | 60s | 120s | Auto-fail the gate |
+
+### Timeout Behavior
+
+1. Orchestrator sends a soft cancellation signal at `timeout - 30s`
+2. Agent should wrap up and write partial results
+3. At timeout, orchestrator force-terminates the agent
+4. Partial output files (if any) are preserved
+5. Retry uses the same context bundle plus partial output as additional context
+
+---
+
+## Retry Policy
+
+| Condition | Retry | Max Retries | Backoff |
+|-----------|-------|-------------|---------|
+| Timeout | Yes | 1 | None (immediate) |
+| Output file missing | Yes | 1 | None |
+| Output file empty | Yes | 1 | None |
+| Agent error (crash) | Yes | 2 | 5s between retries |
+| Escalation signal | No | - | Route to user |
+| Gate failure | No | - | Route to revision |
+
+### Retry Context
+
+On retry, the agent receives the original context bundle plus:
+- `_retry_reason`: Why the previous attempt failed
+- `_partial_output`: Any files the previous attempt produced
+- `_attempt_number`: Current attempt (1-indexed)
+
+---
+
+## Inter-Agent Communication
+
+Agents do NOT communicate directly. All coordination flows through the orchestrator.
+
+| Allowed | Not Allowed |
+|---------|-------------|
+| Agent writes to its output files | Agent reads another agent's in-progress files |
+| Agent reads files listed in context_files | Agent spawns sub-agents |
+| Agent creates ESCALATION.md | Agent modifies orchestrator state |
+| Agent logs to its designated log path | Agent writes to shared directories |
+
+---
+
+## Escalation Protocol
+
+When an agent encounters a decision it cannot make:
+
+1. Create `ESCALATION.md` in the phase directory
+2. Include: question, options, recommendation, impact of each option
+3. Set status to `escalated`
+4. Orchestrator pauses the pipeline and presents to user
+5. User decision is recorded in CONTEXT.md
+6. Agent is re-spawned with the decision in context