@jokerized/getresearchdone 0.4.1

package/commands/autoplan.md

@@ -0,0 +1,55 @@
+---
+description: Automatically generate milestones from evolve discoveries or fresh codebase analysis
+argument-hint: "[--dry-run] [--pick-pct N] [--name <name>] [--timeout N]"
+---
+
+Run the autoplan command to automatically generate a new milestone from evolve discovery results:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js autoplan $ARGUMENTS
+```
+
+Autoplan bridges the gap between evolve's discovery and autopilot's execution. It takes discovered improvement groups (from evolve's discovery engine or from the current evolve state) and creates a structured milestone complete with phases, requirements, and a roadmap -- entirely autonomously.
+
+The autoplan workflow:
+1. Loads evolve state (or runs fresh discovery if no state exists)
+2. Selects priority groups based on --pick-pct
+3. Builds a prompt that instructs claude -p to create a milestone using /grd:new-milestone
+4. Spawns the subprocess which creates the milestone artifacts
+5. Returns the result with status and prompt used
+
+### Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--dry-run` | Preview the prompt without spawning subprocess | false |
+| `--pick-pct N` | Percentage of groups to use (only if running fresh discovery) | 50 |
+| `--name <name>` | Override the derived milestone name | auto |
+| `--timeout N` | Subprocess timeout in minutes | 120 |
+| `--max-turns N` | Max turns for claude -p subprocess | -- |
+| `--model <model>` | Model override for subprocess | -- |
+
+### Pre-flight Context
+
+To get pre-flight context for autoplan (evolve state, current milestone):
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js init autoplan
+```
+
+### Examples
+
+```bash
+# Preview what autoplan would create
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js autoplan --dry-run
+
+# Run autoplan with custom milestone name
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js autoplan --name "Performance Improvements"
+
+# Run autoplan with fresh discovery at 30% pick rate
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js autoplan --pick-pct 30
+```
+
+IMPORTANT: This command spawns a Claude subprocess. 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.
+
+Report the JSON results. If autoplan created a milestone, suggest running `/grd:autopilot` to execute it.

package/commands/check-todos.md

@@ -0,0 +1,87 @@
+---
+description: List pending todos, view details, and route to appropriate action
+---
+
+<purpose>
+List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
+</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: `todo_count`, `todos`, `pending_dir`, `todos_dir`.
+
+If `todo_count` is 0:
+```
+No pending todos.
+
+Todos are captured during work sessions with /grd:add-todo.
+
+---
+
+Would you like to:
+
+1. Continue with current phase (/grd:progress)
+2. Add a todo now (/grd:add-todo)
+```
+Exit.
+</step>
+
+<step name="list_todos">
+Display as numbered list with title, area, and relative age.
+
+```
+Pending Todos:
+
+1. Add auth token refresh (api, 2d ago)
+2. Fix modal z-index issue (ui, 1d ago)
+
+---
+
+Reply with a number to view details, or `q` to exit.
+```
+</step>
+
+<step name="handle_selection">
+Wait for user to reply with a number. Load selected todo, display full context.
+</step>
+
+<step name="offer_actions">
+**If todo maps to a roadmap phase:** Offer Work on it now / Add to phase plan / Brainstorm / Put it back.
+
+**If no roadmap match:** Offer Work on it now / Create a phase / Brainstorm / Put it back.
+</step>
+
+<step name="execute_action">
+**Work on it now:** Move to done/, update STATE.md, begin work.
+**Add to phase plan:** Note reference, keep in pending.
+**Create a phase:** Display `/grd:add-phase [description]`.
+**Brainstorm approach:** Start discussion.
+**Put it back:** Return to list.
+</step>
+
+<step name="git_commit">
+If todo was moved to done/:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "docs: start work on todo - [title]" --files ${todos_dir}/done/[filename] .planning/STATE.md
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] All pending todos listed with title, area, age
+- [ ] Selected todo's full context loaded
+- [ ] Appropriate actions offered
+- [ ] Selected action executed
+- [ ] STATE.md updated if todo count changed
+- [ ] Changes committed to git (if todo moved to done/)
+</success_criteria>

package/commands/compare-methods.md

@@ -0,0 +1,262 @@
+---
+description: Compare research methods/approaches from LANDSCAPE.md with performance/complexity matrix
+argument-hint: [method1, method2, ...] or "all"
+---
+
+<purpose>
+Orchestrate comparison of methods from LANDSCAPE.md. Build a structured comparison matrix
+covering performance, complexity, production readiness, and trade-offs. Helps decide which
+approach to pursue before committing to feasibility analysis or implementation.
+</purpose>
+
+<context>
+CLAUDE.md rules: @CLAUDE.md
+
+**Research directory structure** (paths resolved via init):
+- `${research_dir}/LANDSCAPE.md` — source of methods to compare
+- `${research_dir}/deep-dives/` — detailed analyses (if available)
+- `${research_dir}/COMPARISON-{topic}.md` — output comparison matrix
+- `${research_dir}/PAPERS.md` — paper index with verdicts
+- `.planning/config.json` — GRD configuration
+
+**This workflow does NOT spawn a dedicated agent.** It synthesizes existing research
+artifacts (LANDSCAPE.md, deep-dives) into a comparison matrix. The orchestrator itself
+performs the analysis using structured reasoning.
+</context>
+
+<process>
+
+## Step 0: INITIALIZE — Load Research Context
+
+0. **Run initialization**:
+   ```bash
+   INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js init survey "compare-methods")
+   ```
+   Parse JSON for: `research_dir`, `landscape_exists`, `deep_dives`, `autonomous_mode`, `research_gates`.
+
+1. **Check LANDSCAPE.md exists**:
+   - Path: `${research_dir}/LANDSCAPE.md`
+   - If missing: STOP and suggest `/grd:survey {topic}` first
+   - If present: parse methods table
+
+2. **Extract available methods** from LANDSCAPE.md:
+   - Parse the `## Methods` section
+   - Build list: `METHOD_NAME | paper | year | approach_type | key_metric`
+   - Count total methods available
+
+3. **Load deep-dives** (if any exist):
+   - Scan `${research_dir}/deep-dives/` for completed analyses
+   - Map deep-dive verdicts to method names
+   - Note which methods have deep-dives and which do not
+
+4. **Parse arguments**:
+   - If specific methods listed: validate they exist in LANDSCAPE.md
+   - If "all" or empty: prepare to compare all methods
+   - If methods not in landscape: WARN and suggest survey first
+
+**STEP_0_CHECKPOINT:**
+- [ ] LANDSCAPE.md loaded and parsed
+- [ ] Methods list extracted
+- [ ] Deep-dives mapped to methods
+- [ ] Comparison set determined
+
+---
+
+## Step 1: SELECT METHODS TO COMPARE
+
+**If not specified in arguments, present selection to user:**
+
+```
+Available methods from LANDSCAPE.md:
+
+  1. {method_1} ({year}) — {approach_type} [deep-dive: yes/no]
+  2. {method_2} ({year}) — {approach_type} [deep-dive: yes/no]
+  3. {method_3} ({year}) — {approach_type} [deep-dive: yes/no]
+  ...
+
+Options:
+  a) Compare ALL methods
+  b) Enter numbers to compare (e.g., "1,2,4")
+  c) Compare by category (e.g., "all supervised methods")
+
+Which methods to compare?
+```
+
+**In autonomous mode** (`autonomous_mode: true`): Compare all methods automatically.
+
+**GATE**: If `research_gates.comparison_approval` is true, confirm selection with user.
+
+---
+
+## Step 2: DISPLAY BANNER
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  GRD >>> COMPARE METHODS                                    ║
+║                                                             ║
+║  Comparing: {N} methods                                     ║
+║  Methods: {method_1}, {method_2}, ...                       ║
+║  Deep-dives available: {M}/{N}                              ║
+║  Source: LANDSCAPE.md ({survey_date})                        ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Step 3: BUILD COMPARISON DIMENSIONS
+
+For each selected method, evaluate across these axes:
+
+### 3a. Performance Matrix
+
+| Method | Benchmark_1 | Benchmark_2 | ... | Best_Reported |
+|--------|-------------|-------------|-----|---------------|
+| {m1}   | {score}     | {score}     |     | {metric}      |
+| {m2}   | {score}     | {score}     |     | {metric}      |
+
+- Source: LANDSCAPE.md metrics + deep-dive reported results
+- Mark cells with `*` if from deep-dive, `~` if from survey only
+- Mark `?` if metric not available
+
+### 3b. Complexity Matrix
+
+| Method | Training_Cost | Inference_Latency | Memory | Data_Required | Impl_Complexity |
+|--------|---------------|-------------------|--------|---------------|-----------------|
+| {m1}   | {est}         | {est}             | {est}  | {est}         | {1-5}           |
+
+- Use relative scale: LOW / MEDIUM / HIGH / VERY_HIGH
+- Note: estimates from papers, may not reflect production reality
+
+### 3c. Production Readiness
+
+| Method | Code_Available | License | Dependencies | Maintenance | Docs |
+|--------|----------------|---------|--------------|-------------|------|
+| {m1}   | {yes/partial/no} | {license} | {framework} | {active/stale} | {good/minimal/none} |
+
+### 3d. Trade-off Analysis
+
+For each pair of methods, identify key trade-offs:
+
+```
+{method_1} vs {method_2}:
+  Performance: {m1} wins by {margin} on {benchmark}
+  Complexity:  {m2} is simpler — {reason}
+  Production:  {m1} has code, {m2} is paper-only
+  Trade-off:   {summary of key decision factor}
+```
+
+### 3e. Risk Assessment
+
+| Method | Technical_Risk | Data_Risk | Scale_Risk | Overall |
+|--------|---------------|-----------|------------|---------|
+| {m1}   | {L/M/H}       | {L/M/H}   | {L/M/H}    | {L/M/H} |
+
+---
+
+## Step 4: SYNTHESIZE RECOMMENDATION
+
+Using extended thinking, synthesize all dimensions:
+
+```
+RECOMMENDATION MATRIX:
+
+  Best performance:        {method} — {reason}
+  Best simplicity:         {method} — {reason}
+  Best production-ready:   {method} — {reason}
+  Best risk profile:       {method} — {reason}
+
+  OVERALL RECOMMENDATION:  {method}
+  Rationale: {2-3 sentences explaining the recommendation}
+
+  RUNNER-UP:               {method}
+  When to prefer runner-up: {condition}
+```
+
+---
+
+## Step 5: DISPLAY COMPARISON SUMMARY
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  COMPARISON RESULTS                                         ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                             ║
+║  Methods compared: {N}                                      ║
+║                                                             ║
+║  WINNER: {method_name}                                      ║
+║    Performance:  {score_summary}                            ║
+║    Complexity:   {complexity_summary}                       ║
+║    Production:   {readiness_summary}                        ║
+║    Risk:         {risk_summary}                             ║
+║                                                             ║
+║  RUNNER-UP: {method_name}                                   ║
+║    Prefer when: {condition}                                 ║
+║                                                             ║
+║  GAPS: {methods_without_deep_dives} methods need deep-dives ║
+║                                                             ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Step 6: WRITE COMPARISON FILE
+
+1. **Determine topic slug** from LANDSCAPE.md header or user topic
+2. **Write comparison matrix**:
+   - Path: `${research_dir}/COMPARISON-{topic-slug}.md`
+   - Include all matrices from Step 3
+   - Include recommendation from Step 4
+   - Include metadata: date, methods compared, data sources
+
+3. **Also display full comparison to console** for immediate review
+
+---
+
+## Step 7: COMMIT (optional)
+
+**Ask user** if they want to commit the comparison file:
+- In autonomous mode: commit automatically
+
+```bash
+git add ${research_dir}/COMPARISON-{topic-slug}.md
+git commit -m "research: compare {N} methods for {topic} — recommend {winner}"
+```
+
+---
+
+## Step 8: ROUTE NEXT ACTION
+
+| Condition | Suggestion |
+|-----------|------------|
+| Winner lacks deep-dive | `/grd:deep-dive {winner_paper}` |
+| Winner needs feasibility check | `/grd:feasibility {winner}` |
+| Methods too close to call | `/grd:deep-dive` both, then re-compare |
+| Gaps in deep-dives | `/grd:deep-dive {method_without_dive}` |
+| Ready to proceed | `/grd:product-plan` or `/grd:plan-phase` |
+
+</process>
+
+<output>
+**FILES_WRITTEN:**
+- `${research_dir}/COMPARISON-{topic}.md` — full comparison matrix
+
+**DISPLAY**: Comparison summary to console with winner, runner-up, and gaps
+
+**GIT**: Optional commit: `research: compare {N} methods for {topic} — recommend {winner}`
+</output>
+
+<error_handling>
+- **LANDSCAPE.md missing**: STOP, direct to `/grd:survey` first
+- **No methods in landscape**: STOP, landscape may be malformed, suggest re-survey
+- **Selected method not in landscape**: WARN, offer to add or survey for it
+- **Insufficient data for comparison**: Mark cells as `?`, note data gaps prominently
+- **All methods score equally**: Report tie, suggest deep-dives for differentiators
+</error_handling>
+
+<success_criteria>
+- Comparison covers all 5 dimensions (performance, complexity, production, trade-offs, risk)
+- Recommendation is specific with rationale
+- Data gaps are clearly marked, not silently filled
+- Comparison is traceable to LANDSCAPE.md and deep-dive sources
+- Output is immediately actionable (clear winner or clear next step)
+</success_criteria>

package/commands/complete-milestone.md

@@ -0,0 +1,225 @@
+---
+description: Mark a milestone version as complete and archive it
+argument-hint: [--name milestone-name]
+---
+
+<purpose>
+Mark a shipped version as complete. First runs an automated milestone audit (cross-phase integration checks, requirements coverage, tech debt aggregation), then creates historical record in MILESTONES.md, performs full PROJECT.md evolution review, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.
+</purpose>
+
+<required_reading>
+1. templates/milestone.md
+2. templates/milestone-archive.md
+3. `.planning/ROADMAP.md`
+4. `.planning/REQUIREMENTS.md`
+5. `.planning/PROJECT.md`
+</required_reading>
+
+<process>
+
+<step name="init_context" priority="first">
+```bash
+INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js init milestone-op)
+```
+
+Parse JSON for: `phases_dir`, `commit_docs`, `milestone_version`, `milestone_name`.
+</step>
+
+<step name="audit_milestone">
+**Run milestone audit as first step of completion.**
+
+This step replaces the standalone `/grd:audit-milestone` command by integrating it directly.
+
+1. Determine milestone scope from init context
+2. Read all phase VERIFICATION.md files
+3. Spawn integration checker for cross-phase wiring:
+
+```
+Task(
+  prompt="Check cross-phase integration and E2E flows.
+Phases: {phase_dirs}
+Phase exports: {from SUMMARYs}
+API routes: {routes created}
+Verify cross-phase wiring and E2E user flows.",
+  subagent_type="grd:grd-integration-checker",
+  model="{integration_checker_model}"
+)
+```
+
+4. Aggregate results: phase-level gaps/tech debt + integration checker report
+5. Check requirements coverage: satisfied | partial | unsatisfied
+
+**Route by audit result:**
+
+- **If passed:** Continue to `verify_readiness` step
+- **If gaps_found:**
+  Present gap summary. Offer:
+  - "Continue anyway" — proceed to verify_readiness
+  - "Fix first" — offer `/grd:plan-milestone-gaps`, stop completion
+- **If tech_debt:**
+  Present tech debt summary. Offer:
+  - "Accept debt" — proceed to verify_readiness
+  - "Plan cleanup" — offer cleanup phase, stop completion
+
+<if mode="yolo">
+Auto-approve: if passed or tech_debt_only, proceed. If gaps_found, still proceed but log gaps.
+</if>
+</step>
+
+<step name="verify_readiness">
+```bash
+ROADMAP=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js roadmap analyze)
+```
+
+Verify all phases complete (`disk_status === 'complete'`), `progress_percent` should be 100%.
+
+Present milestone summary with phase/plan breakdown.
+
+<if mode="yolo">
+Auto-approve: proceed to gather_stats.
+</if>
+
+<if mode="interactive">
+Confirm: "Ready to mark this milestone as shipped? (yes / wait / adjust scope)"
+</if>
+</step>
+
+<step name="gather_stats">
+Calculate milestone statistics: phases, plans, tasks, files modified, LOC, timeline, git range.
+</step>
+
+<step name="extract_accomplishments">
+```bash
+for summary in ${phases_dir}/*-*/*-SUMMARY.md; do
+  node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js summary-extract "$summary" --fields one_liner | jq -r '.one_liner'
+done
+```
+
+Extract 4-6 key accomplishments.
+</step>
+
+<step name="evolve_project_full_review">
+Full PROJECT.md evolution review: "What This Is" accuracy, Core Value check, Requirements audit (move shipped to Validated, add new to Active), Context update, Key Decisions audit, Constraints check.
+</step>
+
+<step name="archive_milestone">
+```bash
+ARCHIVE=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js milestone complete "v[X.Y]" --name "[Milestone Name]")
+```
+
+The CLI handles: creating milestones directory, archiving ROADMAP.md and REQUIREMENTS.md, **archiving all phase directories** to `.planning/milestones/v[X.Y]-phases/`, creating/appending MILESTONES.md entry, updating STATE.md.
+
+After archival, handle: reorganize ROADMAP.md, full PROJECT.md evolution, delete originals.
+</step>
+
+<step name="handle_branches">
+The `milestone complete` CLI command automatically merges the milestone branch into the base branch (e.g., main) when `branching_strategy` is not `"none"`.
+
+Check the `git_merge` field from the `ARCHIVE` result:
+
+**If `git_merge.merged: true`:**
+```
+Milestone branch `${git_merge.milestone_branch}` merged into `${git_merge.base_branch}` and deleted.
+```
+
+**If `git_merge.error`:**
+```
+## Merge Conflict
+
+The milestone branch could not be automatically merged into ${git_merge.base_branch}.
+Resolve manually:
+1. `git checkout ${git_merge.base_branch}`
+2. `git merge ${git_merge.milestone_branch}`
+3. Resolve conflicts, then `git commit`
+4. `git branch -d ${git_merge.milestone_branch}`
+```
+
+**If `git_merge.skipped`:**
+```
+Milestone branch merge skipped: ${git_merge.reason}
+```
+
+**If no `git_merge` field:** Branching strategy is `"none"`, no branch handling needed.
+</step>
+
+<step name="bump_versions">
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js version bump v[X.Y]
+```
+
+Bump VERSION, package.json, and .claude-plugin/plugin.json to match the milestone version.
+</step>
+
+<step name="git_tag">
+```bash
+git tag -a v[X.Y] -m "v[X.Y] [Name] ..."
+```
+Ask: "Push tag to remote? (y/n)"
+</step>
+
+<step name="git_commit_milestone">
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "chore: complete v[X.Y] milestone" --files .planning/milestones/v[X.Y]-ROADMAP.md .planning/milestones/v[X.Y]-REQUIREMENTS.md .planning/MILESTONES.md .planning/PROJECT.md .planning/STATE.md VERSION package.json .claude-plugin/plugin.json
+```
+</step>
+
+<step name="update_lt_roadmap">
+Check if LONG-TERM-ROADMAP.md exists and update LT milestone status:
+
+```bash
+LT_LIST=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap list --raw 2>/dev/null || true)
+```
+
+**If LT roadmap exists:**
+1. Check if v[X.Y] is linked to any LT milestone
+2. If linked, check if all normal milestones in that LT milestone are now shipped
+3. If all shipped, update LT milestone status to `completed`:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap update --id [LT-N] --status completed
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap history --action "Completed LT-N" --details "All normal milestones shipped"
+```
+4. If the next LT milestone exists and is `planned`, update to `active`:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap update --id [LT-N+1] --status active
+```
+5. Commit changes:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "docs: update LT roadmap after v[X.Y] completion" --files .planning/LONG-TERM-ROADMAP.md
+```
+</step>
+
+<step name="offer_next">
+```
+Milestone v[X.Y] [Name] complete
+
+---
+
+## Next Up
+
+**Start Next Milestone** — questioning -> research -> requirements -> roadmap
+
+`/grd:new-milestone`
+
+<sub>`/clear` first -> fresh context window</sub>
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Milestone audit completed (integration checks, requirements coverage)
+- [ ] MILESTONES.md entry created
+- [ ] PROJECT.md full evolution review completed
+- [ ] ROADMAP.md reorganized with milestone grouping
+- [ ] Archives created
+- [ ] Phase directories archived to .planning/milestones/v[X.Y]-phases/
+- [ ] ${phases_dir}/ directory is empty
+- [ ] REQUIREMENTS.md deleted (fresh for next milestone)
+- [ ] STATE.md updated
+- [ ] Git tag created
+- [ ] Milestone commit made
+- [ ] LT roadmap status updated (if applicable)
+- [ ] User knows next step (/grd:new-milestone)
+</success_criteria>