@jokerized/getresearchdone 0.4.1

package/bin/postinstall.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+require('tsx/cjs');
+require('./postinstall.ts');

package/bin/postinstall.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * GRD Post-install Script
+ *
+ * Creates the .planning/ directory structure and default config.json
+ * when not already present. Idempotent: does nothing if .planning/ exists.
+ *
+ * This script MUST never fail — postinstall failures block npm install.
+ * All errors are caught and printed to stderr; exit code is always 0.
+ */
+
+
+const fs = require('fs') as typeof import('fs');
+const path = require('path') as typeof import('path');
+
+const PLANNING_DIR: string = path.join(process.cwd(), '.planning');
+
+const DIRECTORIES: readonly string[] = [
+  '.planning',
+  '.planning/milestones',
+  '.planning/milestones/anonymous',
+  '.planning/milestones/anonymous/phases',
+  '.planning/milestones/anonymous/research',
+  '.planning/milestones/anonymous/research/deep-dives',
+  '.planning/milestones/anonymous/codebase',
+  '.planning/milestones/anonymous/todos',
+  '.planning/milestones/anonymous/quick',
+] as const;
+
+interface DefaultConfig {
+  model_profile: string;
+  commit_docs: boolean;
+  autonomous_mode: boolean;
+  research_gates: Record<string, never>;
+  confirmation_gates: Record<string, never>;
+  eval_config: {
+    default_metrics: string[];
+    baseline_tracking: boolean;
+  };
+}
+
+const DEFAULT_CONFIG: DefaultConfig = {
+  model_profile: 'balanced',
+  commit_docs: true,
+  autonomous_mode: false,
+  research_gates: {},
+  confirmation_gates: {},
+  eval_config: {
+    default_metrics: ['test_coverage_pct', 'lint_error_count'],
+    baseline_tracking: true,
+  },
+};
+
+try {
+  // Idempotency: if .planning/ already exists, exit silently
+  if (fs.existsSync(PLANNING_DIR)) {
+    process.exit(0);
+  }
+
+  // Create all directories
+  const cwd: string = process.cwd();
+  for (const dir of DIRECTORIES) {
+    const fullPath: string = path.join(cwd, dir);
+    fs.mkdirSync(fullPath, { recursive: true });
+  }
+
+  // Create default config.json
+  const configPath: string = path.join(PLANNING_DIR, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    fs.writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + '\n');
+  }
+
+  console.log('GRD: Created .planning/ directory structure');
+} catch (err: unknown) {
+  // Never fail postinstall — print warning and exit cleanly
+  process.stderr.write(`GRD postinstall warning: ${(err as Error).message}\n`);
+  process.exit(0);
+}

package/commands/add-phase.md

@@ -0,0 +1,123 @@
+---
+description: Add a new phase to the end of the current milestone
+argument-hint: <phase name and goal>
+---
+
+<purpose>
+Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- All arguments become the phase description
+- Example: `/grd:add-phase Add authentication` -> description = "Add authentication"
+
+If no arguments provided:
+```
+ERROR: Phase description required
+Usage: /grd:add-phase <description>
+Example: /grd:add-phase Add authentication system
+```
+Exit.
+
+If the user provided substantial context beyond a short name (multi-line text, goals, constraints, decisions, or background), capture it as `context` text for the `--context` flag. Short single-phrase descriptions do not need context capture.
+</step>
+
+<step name="init_context">
+```bash
+INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js init phase-op "0")
+```
+
+Parse JSON for: `roadmap_exists`, `phases_dir`, `commit_docs`.
+
+Check `roadmap_exists` from init JSON. If false:
+```
+ERROR: No roadmap found (.planning/ROADMAP.md)
+Run /grd:init to initialize.
+```
+Exit.
+</step>
+
+<step name="add_phase">
+If `context` was captured:
+```bash
+RESULT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js phase add "${description}" --context "${context}")
+```
+
+Otherwise:
+```bash
+RESULT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js phase add "${description}")
+```
+
+Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
+</step>
+
+<step name="update_project_state">
+Update STATE.md under "## Accumulated Context" -> "### Roadmap Evolution":
+```
+- Phase {N} added: {description}
+```
+</step>
+
+<step name="reschedule_check">
+If `schedule_affected` is true in the result:
+
+1. Check tracker config:
+```bash
+TRACKER_CONFIG=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker get-config --raw)
+```
+
+2. If `provider` is `"mcp-atlassian"` and `auto_sync` is true:
+   - Run reschedule automatically:
+   ```bash
+   OPS=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker prepare-reschedule --raw)
+   ```
+   - Parse `start_date_field` and `operations` from JSON
+   - For each operation with `action: "update"`: call MCP tool `update_issue` with `issue_key` and `additional_fields: {[start_date_field]: start_date, "duedate": due_date}`
+   - Display count of updated issues
+
+3. If `provider` is `"mcp-atlassian"` but `auto_sync` is false:
+   - Notify: `Schedule affected. Run /grd:sync reschedule to update Jira dates.`
+
+4. Otherwise: skip (no tracker or GitHub provider — dates not applicable).
+</step>
+
+<step name="completion">
+```
+Phase {N} added to current milestone:
+- Description: {description}
+- Directory: ${phases_dir}/{phase-num}-{slug}/
+- Duration: 7d (default — edit in ROADMAP.md to adjust)
+- Status: Not planned yet
+{If reschedule ran: "- Jira dates updated: {count} issues rescheduled"}
+
+---
+
+## Next Up
+
+**Phase {N}: {description}**
+
+`/grd:plan-phase {N}`
+
+<sub>`/clear` first -> fresh context window</sub>
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] `grd-tools phase add` executed successfully
+- [ ] Phase directory created
+- [ ] CONTEXT.md created if substantial context was provided
+- [ ] Roadmap updated with new phase entry
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] User informed of next steps
+</success_criteria>

package/commands/add-todo.md

@@ -0,0 +1,87 @@
+---
+description: Capture an idea or task as a structured todo for later work
+argument-hint: <brief description of the todo>
+---
+
+<purpose>
+Capture an idea, task, or issue that surfaces during a GRD session as a structured todo for later work. Enables "thought -> capture -> continue" flow without losing context.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="init_context">
+```bash
+INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js init todos)
+```
+
+Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos`, `pending_dir`, `todos_dir`, `todos_dir_exists`.
+
+```bash
+mkdir -p ${todos_dir}/pending ${todos_dir}/done
+```
+</step>
+
+<step name="extract_content">
+**With arguments:** Use as the title/focus.
+**Without arguments:** Analyze recent conversation to extract the specific problem, idea, or task.
+
+Formulate: `title`, `problem`, `solution`, `files`.
+</step>
+
+<step name="infer_area">
+Infer area from file paths (api, ui, auth, database, testing, docs, planning, tooling, general).
+</step>
+
+<step name="check_duplicates">
+```bash
+grep -l -i "[key words from title]" ${todos_dir}/pending/*.md 2>/dev/null
+```
+
+If potential duplicate found: offer Skip/Replace/Add anyway.
+</step>
+
+<step name="create_file">
+```bash
+slug=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js generate-slug "$title" --raw)
+```
+
+Write to `${todos_dir}/pending/-.md` with frontmatter and Problem/Solution sections.
+</step>
+
+<step name="git_commit">
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "docs: capture todo - [title]" --files ${todos_dir}/pending/[filename] .planning/STATE.md
+```
+</step>
+
+<step name="confirm">
+```
+Todo saved: ${todos_dir}/pending/[filename]
+
+  [title]
+  Area: [area]
+  Files: [count] referenced
+
+---
+
+Would you like to:
+
+1. Continue with current work
+2. Add another todo
+3. View all todos (/grd:check-todos)
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Todo file created with valid frontmatter
+- [ ] Problem section has enough context for future Claude
+- [ ] No duplicates (checked and resolved)
+- [ ] STATE.md updated if exists
+- [ ] Todo and state committed to git
+</success_criteria>

package/commands/assess-baseline.md

@@ -0,0 +1,289 @@
+---
+description: Assess current code/model quality with quantitative metrics and establish performance baseline
+argument-hint: [scope: "full" | "quick" | specific component]
+---
+
+<purpose>
+Assess current code quality and establish a quantitative performance baseline. Runs
+analysis across code health, test coverage, performance metrics, and domain-specific
+quality measures. Creates or updates .planning/BASELINE.md — the reference point against
+which all future improvements are measured.
+</purpose>
+
+<context>
+CLAUDE.md rules: @CLAUDE.md
+
+**Project structure:**
+- `.planning/BASELINE.md` — baseline assessment output (created or updated)
+- `.planning/BENCHMARKS.md` — historical benchmark tracking
+- `.planning/ROADMAP.md` — project roadmap (may reference baseline)
+- `.planning/config.json` — GRD configuration
+- `package.json` / `pyproject.toml` / `Cargo.toml` / etc. — project manifest
+
+**Agent available:**
+- `grd-baseline-assessor` — specialized code/system quality assessment agent
+</context>
+
+<process>
+
+## Step 0: INITIALIZE — Detect Project and Scope
+
+1. **Parse arguments**: Determine assessment scope from `$ARGUMENTS`
+   - `full`: comprehensive assessment of all dimensions
+   - `quick`: code health + test coverage only (skip expensive benchmarks)
+   - Specific component: focus assessment on named module/directory
+   - Empty: default to `full`
+
+2. **Detect project type**:
+   - Scan for manifest files (package.json, pyproject.toml, Cargo.toml, go.mod, etc.)
+   - Identify language, framework, package manager
+   - Identify test framework and runner
+   - Identify linting/formatting tools
+   - Identify build system
+
+3. **Load existing BASELINE.md** (if present):
+   - Parse previous assessment metrics
+   - Store as `PREVIOUS_BASELINE` for trend comparison
+   - Note timestamp of last assessment
+
+4. **Inventory available tooling**:
+   - What static analysis tools are installed/configured?
+   - What test suites exist?
+   - What benchmark scripts are available?
+   - What CI/CD pipeline checks are defined?
+
+**STEP_0_CHECKPOINT:**
+- [ ] Assessment scope determined
+- [ ] Project type and toolchain identified
+- [ ] Previous baseline loaded (or noted as first assessment)
+- [ ] Available tooling inventoried
+
+---
+
+## Step 1: DISPLAY BANNER
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  GRD >>> ASSESS BASELINE                                    ║
+║                                                             ║
+║  Scope: {full | quick | component}                          ║
+║  Project: {language} / {framework}                          ║
+║  Previous baseline: {date | "first assessment"}             ║
+║  Tools detected: {linter, test runner, ...}                 ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Step 2: SPAWN BASELINE ASSESSOR AGENT
+
+**Launch `grd-baseline-assessor` agent via Task tool:**
+
+Use Task tool with `subagent_type="grd:grd-baseline-assessor"`:
+
+```
+Assess current code quality and performance baseline.
+
+PROJECT TYPE: {language} / {framework}
+MANIFEST: {manifest file contents}
+SCOPE: {full | quick | component: {name}}
+
+PREVIOUS BASELINE:
+{Previous BASELINE.md content, or "First assessment"}
+
+AVAILABLE TOOLS:
+{List of detected static analysis, test, and benchmark tools}
+
+ASSESS THE FOLLOWING DIMENSIONS:
+
+## 1. CODE HEALTH
+Run available static analysis and report:
+- Lint errors/warnings count (by severity)
+- Type errors count (if typed language)
+- Code style violations
+- Cyclomatic complexity (top 10 most complex functions)
+- Dead code / unused imports
+- Dependency health (outdated, vulnerable, deprecated)
+- Tech debt indicators (TODO/FIXME/HACK counts)
+
+Commands to try:
+- {linter} (e.g., eslint, ruff, clippy, golint)
+- {type checker} (e.g., tsc --noEmit, mypy, cargo check)
+- Dependency audit (npm audit, pip-audit, cargo audit)
+
+## 2. TEST HEALTH
+Run test suite and report:
+- Total tests count
+- Pass/fail/skip breakdown
+- Test coverage percentage (line, branch, function)
+- Test runtime
+- Flaky test detection (if multiple runs feasible)
+- Test-to-code ratio
+
+Commands to try:
+- {test runner} with coverage flag
+- Coverage report generation
+
+## 3. BUILD HEALTH
+- Build success/failure
+- Build time
+- Bundle size (if applicable)
+- Artifact count and sizes
+- Build warnings
+
+## 4. ARCHITECTURE METRICS
+- Total source files count
+- Total lines of code (excluding tests, generated)
+- Module/package count
+- Dependency count (direct and transitive)
+- Circular dependency detection
+- API surface area (exported functions/classes)
+
+## 5. PERFORMANCE METRICS (if applicable and scope=full)
+- Startup time / cold start
+- Key operation latency (if benchmarks exist)
+- Memory usage baseline
+- Resource utilization patterns
+- Known performance bottlenecks
+
+## 6. DOMAIN-SPECIFIC METRICS (if applicable)
+- Model accuracy/quality metrics (if ML project)
+- API response times (if web service)
+- UI render performance (if frontend)
+- Throughput measurements
+- Custom benchmark results
+
+OUTPUT FORMAT:
+Return structured assessment with:
+- Summary scorecard (dimension: score/grade)
+- Detailed metrics per dimension (tables)
+- Trend comparison vs previous baseline (if available)
+- Top 5 improvement opportunities ranked by impact
+- Risk areas requiring attention
+```
+
+**STEP_2_CHECKPOINT:**
+- [ ] Baseline assessor agent launched
+- [ ] All applicable dimensions assessed
+- [ ] Quantitative metrics captured
+- [ ] Comparison with previous baseline computed (if available)
+
+---
+
+## Step 3: DISPLAY BASELINE SCORECARD
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  BASELINE ASSESSMENT                                        ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                             ║
+║  Code Health:       {score}/10  {trend_arrow}               ║
+║    Lint issues:     {count} ({delta})                       ║
+║    Type errors:     {count} ({delta})                       ║
+║    Tech debt:       {count} TODOs/FIXMEs                    ║
+║                                                             ║
+║  Test Health:       {score}/10  {trend_arrow}               ║
+║    Tests:           {pass}/{total} passing                  ║
+║    Coverage:        {pct}% ({delta})                        ║
+║    Runtime:         {time}                                  ║
+║                                                             ║
+║  Build Health:      {score}/10  {trend_arrow}               ║
+║    Status:          {success/failure}                       ║
+║    Time:            {time}                                  ║
+║    Warnings:        {count}                                 ║
+║                                                             ║
+║  Architecture:      {score}/10  {trend_arrow}               ║
+║    Source files:    {count}                                  ║
+║    LOC:            {count}                                   ║
+║    Dependencies:   {count}                                   ║
+║                                                             ║
+║  OVERALL:          {score}/10  {trend_arrow}                ║
+║                                                             ║
+║  Top improvement opportunities:                             ║
+║    1. {opportunity_1}                                       ║
+║    2. {opportunity_2}                                       ║
+║    3. {opportunity_3}                                       ║
+║                                                             ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Trend arrows: up-arrow for improvement, down-arrow for regression, dash for stable.
+
+---
+
+## Step 4: WRITE BASELINE.md
+
+1. **Write baseline assessment**:
+   - Path: `.planning/BASELINE.md`
+   - Include timestamp and scope
+   - Include YAML frontmatter:
+     ```yaml
+     ---
+     assessed: {YYYY-MM-DD}
+     scope: {full|quick|component}
+     overall_score: {N}/10
+     project_type: {language/framework}
+     ---
+     ```
+   - Include all dimension details with metric tables
+   - Include improvement opportunities
+   - Include risk areas
+
+2. **Append to BENCHMARKS.md** (if exists):
+   - Add baseline data point for historical tracking
+   - Format: `| baseline | {date} | {metric} | {value} |`
+
+3. **If previous baseline exists**:
+   - Include `## Change Log` section showing delta from previous
+   - Highlight regressions in bold
+
+---
+
+## Step 5: COMMIT
+
+```bash
+git add .planning/BASELINE.md
+git add .planning/BENCHMARKS.md 2>/dev/null
+git commit -m "baseline: assess {scope} — overall {score}/10"
+```
+
+---
+
+## Step 6: ROUTE NEXT ACTION
+
+| Condition | Suggestion |
+|-----------|------------|
+| First baseline, project starting | `/grd:product-plan` — plan with baseline context |
+| Baseline established, research done | `/grd:eval-plan` — design evaluation with baseline refs |
+| Regressions found vs previous | Address regressions before new work |
+| Poor code health | Consider code health phase before research work |
+| Ready for next phase | `/grd:plan-phase` with baseline awareness |
+
+</process>
+
+<output>
+**FILES_WRITTEN:**
+- `.planning/BASELINE.md` — comprehensive baseline assessment
+- `.planning/BENCHMARKS.md` — updated with baseline data point (if exists)
+
+**DISPLAY**: Baseline scorecard with per-dimension scores and improvement opportunities
+
+**GIT**: Committed: `baseline: assess {scope} — overall {score}/10`
+</output>
+
+<error_handling>
+- **No test suite found**: Report 0 coverage, 0 tests — note this as critical gap
+- **Lint tool not installed**: Skip dimension, note as unavailable
+- **Build fails**: Record failure as baseline data point, proceed with other dimensions
+- **Previous BASELINE.md parse error**: Back up, create fresh baseline
+- **Large project timeout**: Reduce scope to `quick`, note incomplete assessment
+- **No manifest file**: Try to detect project type from file extensions, ask user if unclear
+</error_handling>
+
+<success_criteria>
+- Quantitative metrics captured for all applicable dimensions
+- Scores are reproducible (same assessment on same code yields same results)
+- Baseline serves as reference for future eval-plan and eval-report
+- Improvement opportunities are specific and actionable
+- BASELINE.md is self-contained (explains methodology and measurements)
+</success_criteria>

package/commands/autopilot.md

@@ -0,0 +1,100 @@
+---
+description: Plan and execute multiple phases on autopilot with fresh context per step
+argument-hint: "[--phase-from N] [--phase-to N] [--milestone] [--dry-run] [--skip-post-pipeline] [--max-milestones N]"
+---
+
+Run the autopilot command to plan and execute phases with dependency-aware parallel planning and execution:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js autopilot $ARGUMENTS
+```
+
+Phases are grouped into dependency waves. Independent phases within each wave are planned AND executed in parallel using git worktrees for filesystem isolation. Each phase gets its own worktree, and after execution, a post-phase pipeline runs: simplify -> create PR -> code review -> rebase & merge.
+
+Auto-resume is always on: completed phases are skipped, partially-done phases resume from the correct step.
+
+IMPORTANT: This command is long-running (spawns multiple Claude subprocesses). You MUST run it in the background using `run_in_background: true` on the Bash tool to avoid hitting the Bash tool's default timeout. Use `TaskOutput` with `block: false` to check progress periodically.
+
+Report the JSON results including wave grouping. If any phase failed, explain what happened. Auto-resume will pick up from the failed phase on the next run.
+
+### Autopilot Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--phase-from N` | Start from phase N | -- (all phases) |
+| `--phase-to N` | Stop at phase N | -- (all phases) |
+| `--milestone` | Explicit milestone mode (runs wireup after all phases) | true when no phase range |
+| `--dry-run` | Preview what would happen without executing | false |
+| `--skip-plan` | Skip planning step | false |
+| `--skip-execute` | Skip execution step | false |
+| `--skip-post-pipeline` | Skip post-phase pipeline (simplify, PR, review, merge) | false |
+| `--timeout N` | Per-subprocess timeout in minutes | 120 |
+| `--max-turns N` | Max turns per claude -p subprocess | -- |
+| `--model <model>` | Model override for claude -p | -- |
+
+### Post-Phase Pipeline
+
+After each phase execution completes, the following steps run on the phase's worktree branch:
+
+1. **Simplify** — Code quality review and simplification
+2. **Create PR** — Push branch and create pull request
+3. **Code Review** — Review PR diff, fix BLOCKER/WARNING findings
+4. **Rebase & Merge** — Rebase on main, auto-resolve conflicts, merge PR
+
+Use `--skip-post-pipeline` to bypass this pipeline (useful for debugging or local-only runs).
+
+### Milestone Mode
+
+When no `--phase-from`/`--phase-to` is specified (or `--milestone` is passed), autopilot runs in milestone mode:
+- Processes all phases in the current milestone
+- After all phases complete and merge, runs a **wireup step** to discover unwired features
+
+## Multi-Milestone Mode
+
+To orchestrate work across milestone boundaries -- completing one milestone and automatically starting the next -- use the multi-milestone autopilot command:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js multi-milestone-autopilot $ARGUMENTS
+```
+
+This extends single-milestone autopilot to process multiple milestones in sequence. The loop: completes all phases in the current milestone, archives the milestone, resolves the next milestone from LONG-TERM-ROADMAP.md, creates it, and continues.
+
+### Multi-Milestone Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--max-milestones N` | Maximum milestones to process (safety cap) | 10 |
+| `--dry-run` | Preview what would happen without executing | false |
+| `--timeout N` | Per-subprocess timeout in minutes | 120 |
+| `--max-turns N` | Max turns per claude -p subprocess | -- |
+| `--model <model>` | Model override for claude -p | -- |
+| `--skip-plan` | Skip planning step | false |
+| `--skip-execute` | Skip execution step | false |
+| `--skip-post-pipeline` | Skip post-phase pipeline | false |
+
+### Multi-Milestone Examples
+
+```bash
+# Run multi-milestone autopilot (processes up to 10 milestones)
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js multi-milestone-autopilot
+
+# Preview without executing
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js multi-milestone-autopilot --dry-run
+
+# Limit to 3 milestones
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js multi-milestone-autopilot --max-milestones 3
+```
+
+### Pre-flight Context
+
+To get pre-flight context for multi-milestone autopilot (LT roadmap state, current milestone, next milestone):
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js init multi-milestone-autopilot
+```
+
+### Requirements
+
+- LONG-TERM-ROADMAP.md must exist in .planning/ for cross-milestone resolution
+- Claude CLI must be available for subprocess spawning
+- Autonomous mode recommended for unattended operation