@jokerized/getresearchdone 0.4.1

package/commands/survey.md

@@ -0,0 +1,242 @@
+---
+description: SoTA survey — scan arXiv, GitHub, benchmarks for a research topic and update LANDSCAPE.md
+argument-hint: <research topic or question>
+---
+
+<purpose>
+Survey state-of-the-art for a research topic. Scans papers, GitHub repos, benchmarks and
+updates the research LANDSCAPE.md with a structured landscape of methods, results,
+and open problems. This is the entry point for any research-driven development workflow.
+</purpose>
+
+<context>
+CLAUDE.md rules: @CLAUDE.md
+
+**Research directory structure** (paths resolved via init):
+- `${research_dir}/LANDSCAPE.md` — master landscape of methods, papers, repos
+- `${research_dir}/deep-dives/` — individual paper analyses
+- `${research_dir}/PAPERS.md` — index of all reviewed papers
+- `${research_dir}/COMPARISON-*.md` — method comparison matrices
+- `.planning/config.json` — GRD configuration (research_gates, autonomous_mode)
+
+**Agent available:**
+- `grd-surveyor` — specialized research survey agent with web search, paper parsing, repo analysis
+</context>
+
+<process>
+
+## Step 0: INITIALIZE — Validate Input and Environment
+
+1. **Parse arguments**: Extract topic from `$ARGUMENTS`
+   - If empty: use conversation context or ASK user for topic
+   - If URL: treat as seed paper/repo and derive topic
+
+2. **Run initialization**:
+   ```bash
+   INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js init survey "$TOPIC")
+   ```
+
+   Parse JSON for: `research_dir`, `landscape_exists`, `papers_exists`, `benchmarks_exists`, `knowhow_exists`, `researcher_model`, `autonomous_mode`, `research_gates`.
+
+3. **Ensure research directory exists**:
+   ```bash
+   mkdir -p ${research_dir}/deep-dives
+   ```
+
+4. **Read existing LANDSCAPE.md** (if present):
+   - Parse current methods, papers, benchmarks
+   - Store as `EXISTING_LANDSCAPE` for later diff
+   - Note timestamp of last survey
+
+5. **Read config**:
+   - Load `.planning/config.json` for research_gates and autonomous_mode
+   - Check `research_gates.survey_approval` — if true, confirm topic with user before proceeding
+
+**STEP_0_CHECKPOINT:**
+- [ ] Topic extracted and validated
+- [ ] Research directory exists
+- [ ] Existing landscape captured (or noted as first survey)
+- [ ] Config loaded
+
+---
+
+## Step 1: DISPLAY BANNER
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  GRD >>> SURVEYING                                          ║
+║                                                             ║
+║  Topic: {topic}                                             ║
+║  Scope: papers, repos, benchmarks, datasets                 ║
+║  Prior: {N methods known | "first survey"}                  ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Step 2: SPAWN SURVEYOR AGENT
+
+**Launch `grd-surveyor` agent via Task tool:**
+
+Use Task tool with `subagent_type="grd:grd-surveyor"`:
+
+```
+Survey the state-of-the-art for: {topic}
+
+PATHS:
+research_dir: ${research_dir}
+
+EXISTING LANDSCAPE (diff against this):
+{EXISTING_LANDSCAPE or "No prior survey — this is a fresh scan."}
+
+SEARCH SCOPE:
+1. PAPERS: arXiv, Semantic Scholar, Google Scholar — last 2 years priority
+   - Find seminal works and most recent advances
+   - Extract: title, authors, year, venue, key contribution, reported metrics
+   - Note: method type (supervised/unsupervised/hybrid/etc.)
+
+2. CODE: GitHub repos with >50 stars implementing relevant methods
+   - Extract: repo URL, stars, language, last commit date, license
+   - Note: production-readiness signals (tests, docs, CI, releases)
+
+3. BENCHMARKS: Standard evaluation datasets and leaderboards
+   - Extract: benchmark name, task, metrics, current SOTA numbers
+   - Note: which methods hold top positions
+
+4. DATASETS: Available training/eval data
+   - Extract: name, size, format, license, download URL
+   - Note: quality signals and known issues
+
+OUTPUT FORMAT:
+Return a structured LANDSCAPE.md with these sections:
+- ## Overview (2-3 paragraph summary of the field)
+- ## Methods (table: method | paper | year | approach | key_metric | code_available)
+- ## Benchmarks (table: benchmark | task | metric | SOTA_method | SOTA_score)
+- ## Datasets (table: dataset | size | format | license | notes)
+- ## Open Problems (bulleted list of unsolved challenges)
+- ## Recommendations (which methods to investigate further and why)
+- ## Survey Metadata (date, query terms used, sources checked)
+```
+
+**STEP_2_CHECKPOINT:**
+- [ ] Surveyor agent launched with full context
+- [ ] Agent returned structured LANDSCAPE.md content
+- [ ] Content includes all required sections
+
+---
+
+## Step 3: PROCESS RESULTS
+
+1. **Parse agent output**: Extract structured landscape data
+2. **Compute diff** against EXISTING_LANDSCAPE:
+   - New methods found
+   - Updated metrics
+   - New benchmarks discovered
+   - Removed/deprecated entries
+3. **Validate completeness**:
+   - At least 5 methods documented
+   - At least 2 benchmarks identified
+   - Recommendations section is non-empty
+   - All table rows have complete data (no TBD placeholders)
+
+**If validation fails**: Log warning but proceed — partial survey is better than none
+
+---
+
+## Step 4: DISPLAY FINDINGS SUMMARY
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  SURVEY RESULTS                                             ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                             ║
+║  Methods found:     {N total} ({M new})                     ║
+║  Benchmarks:        {B total}                               ║
+║  Datasets:          {D total}                               ║
+║  Code available:    {C}/{N} methods have implementations    ║
+║                                                             ║
+║  Top recommendation: {method_name}                          ║
+║    Reason: {one-line rationale}                              ║
+║                                                             ║
+║  DIFF vs previous survey:                                   ║
+║    + {count} new methods                                    ║
+║    ~ {count} updated entries                                ║
+║    - {count} removed/deprecated                             ║
+║                                                             ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+If this is the first survey, show "INITIAL SURVEY" instead of diff.
+
+---
+
+## Step 5: WRITE LANDSCAPE.md
+
+1. **Write updated LANDSCAPE.md**:
+   - Path: `${research_dir}/LANDSCAPE.md`
+   - Include survey metadata header with timestamp
+   - Preserve any user annotations from previous version (lines starting with `> NOTE:`)
+
+2. **Update PAPERS.md index** (if it exists):
+   - Add any newly discovered papers to the index
+   - Format: `| title | authors | year | status | deep-dive |`
+   - Status: `surveyed` (not yet deep-dived)
+
+---
+
+## Step 6: COMMIT
+
+1. **Stage research files**:
+   ```bash
+   git add ${research_dir}/LANDSCAPE.md
+   git add ${research_dir}/PAPERS.md 2>/dev/null
+   ```
+
+2. **Commit with descriptive message**:
+   ```bash
+   git commit -m "research: survey {topic} — {N} methods, {B} benchmarks"
+   ```
+
+3. **Handle commit failure**: If nothing to commit (no changes), inform user
+
+---
+
+## Step 7: ROUTE NEXT ACTION
+
+Based on survey results, suggest next steps:
+
+| Condition | Suggestion |
+|-----------|------------|
+| Strong candidate method found | `/grd:deep-dive {paper}` — analyze top recommendation |
+| Multiple viable methods | `/grd:compare-methods` — build comparison matrix |
+| Production readiness unclear | `/grd:feasibility {method}` — analyze paper-to-prod gap |
+| Baseline needed first | `/grd:assess-baseline` — establish current performance |
+| Ready to plan | `/grd:product-plan` — create development roadmap |
+
+</process>
+
+<output>
+**FILES_WRITTEN:**
+- `${research_dir}/LANDSCAPE.md` — full survey landscape (created or updated)
+- `${research_dir}/PAPERS.md` — paper index (updated if exists)
+
+**DISPLAY**: Survey results summary with diff, recommendations, and next-step routing
+
+**GIT**: Committed with message: `research: survey {topic} — {N} methods, {B} benchmarks`
+</output>
+
+<error_handling>
+- **No results found**: Broaden search terms, try alternative phrasings, report partial results
+- **Agent timeout**: Save partial results, suggest re-running with narrower scope
+- **Existing LANDSCAPE.md parse error**: Back up corrupted file, create fresh landscape
+- **Git commit fails**: Report files written but uncommitted, suggest manual commit
+- **Config missing**: Use defaults (all gates off, balanced profile)
+</error_handling>
+
+<success_criteria>
+- LANDSCAPE.md contains structured, actionable research overview
+- At least 5 methods documented with papers and metrics
+- Diff clearly shows what changed from previous survey
+- Next action routing is specific and contextual
+- All data is traceable to sources (papers, repos, benchmarks)
+</success_criteria>

package/commands/sync.md

@@ -0,0 +1,246 @@
+---
+description: Sync GRD project state to issue tracker (GitHub Issues or MCP Atlassian)
+argument-hint: [roadmap | phase <N> | status]
+---
+
+<purpose>
+Manually sync GRD project state to the configured issue tracker. Pushes roadmap phases, plan tasks, and status updates. GRD is always source of truth — this is a one-way push.
+</purpose>
+
+<context>
+Tracker integration reference: @${CLAUDE_PLUGIN_ROOT}/references/tracker-integration.md
+MCP protocol reference: @${CLAUDE_PLUGIN_ROOT}/references/mcp-tracker-protocol.md
+</context>
+
+<process>
+
+## Step 1: Load Tracker Config
+
+```bash
+TRACKER_CONFIG=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker get-config --raw)
+```
+
+Parse JSON for: `provider`, `auth_status`, `auto_sync`.
+
+**If `provider` is `"none"`:**
+```
+No tracker configured. Run /grd:tracker-setup to configure GitHub or MCP Atlassian integration.
+```
+Exit.
+
+**If auth not ready** (GitHub: `not_authenticated`):
+```
+Tracker configured (${provider}) but authentication incomplete.
+
+GitHub: Run `gh auth login`
+```
+Exit.
+
+Note: `mcp-atlassian` auth_status is always `"mcp_server"` — the MCP server handles authentication transparently.
+
+## Step 2: Parse Arguments
+
+Parse `$ARGUMENTS`:
+- Empty or `"roadmap"` → sync-roadmap mode
+- `"phase <N>"` or `"phase N"` → sync-phase mode for phase N
+- `"status"` → show sync status
+- `"reschedule"` → reschedule mode (cascade date updates)
+
+## Step 3: Execute Sync
+
+### Mode: sync-roadmap
+
+**If provider is `"github"`:**
+
+```bash
+RESULT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker sync-roadmap --raw)
+```
+
+Parse `created`, `updated`, `skipped`, `errors` from result.
+
+**If provider is `"mcp-atlassian"`:**
+
+```bash
+OPS=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker prepare-roadmap-sync --raw)
+```
+
+Parse JSON for `project_key`, `start_date_field`, `milestone_issue_type`, `phase_issue_type`, and `operations` array.
+
+Initialize counters: created=0, skipped=0, errors=0.
+
+Process operations in order — milestones first, then phases:
+
+For each operation:
+- If `action` is `"skip"`: increment skipped counter.
+- If `action` is `"create"` and `type` is `"milestone"`:
+  1. Build `additional_fields` object:
+     - If operation has `start_date`: add `{[start_date_field]: start_date}`
+     - If operation has `due_date`: add `{"duedate": due_date}`
+  2. Call MCP tool `create_issue`:
+     - `project_key`: from response `project_key`
+     - `summary`: from operation `summary`
+     - `issue_type`: from response `milestone_issue_type` (default: "Epic")
+     - `description`: from operation `description`
+     - `additional_fields`: the built object (if any date fields present)
+  3. If MCP call succeeds, record mapping:
+     ```bash
+     node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker record-mapping --type milestone --milestone {version} --key {issue_key} --url {issue_url} 2>/dev/null || true
+     ```
+     Increment created counter.
+  4. If MCP call fails: increment errors counter, continue.
+- If `action` is `"create"` and `type` is `"phase"`:
+  1. Build `additional_fields` object:
+     - If `parent_key` present: `{"parent": {"key": "{parent_key}"}}`
+     - If operation has `start_date`: add `{[start_date_field]: start_date}`
+     - If operation has `due_date`: add `{"duedate": due_date}`
+  2. Call MCP tool `create_issue`:
+     - `project_key`: from response `project_key`
+     - `summary`: from operation `summary`
+     - `issue_type`: from response `phase_issue_type` (default: "Task")
+     - `additional_fields`: the built object
+  3. If MCP call succeeds, record mapping:
+     ```bash
+     node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker record-mapping --type phase --phase {phase} --key {issue_key} --url {issue_url} --parent {parent_key} 2>/dev/null || true
+     ```
+     Increment created counter.
+  4. If MCP call fails: increment errors counter, continue.
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► TRACKER SYNC — ROADMAP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Provider: {provider}
+
+| Action  | Count |
+|---------|-------|
+| Created | {created} |
+| Skipped | {skipped} (already synced) |
+| Errors  | {errors} |
+
+Mapping saved to .planning/TRACKER.md
+```
+
+### Mode: sync-phase
+
+**If provider is `"github"`:**
+
+```bash
+RESULT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker sync-phase "${PHASE}" --raw)
+```
+
+**If provider is `"mcp-atlassian"`:**
+
+```bash
+OPS=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker prepare-phase-sync "${PHASE}" --raw)
+```
+
+Parse JSON for `project_key`, `plan_issue_type`, `parent_key`, and `operations` array.
+
+Initialize counters: created=0, skipped=0, errors=0.
+
+For each operation:
+- If `action` is `"skip"`: increment skipped counter.
+- If `action` is `"create"`:
+  1. Call MCP tool `create_issue`:
+     - `project_key`: from response `project_key`
+     - `summary`: from operation `summary`
+     - `issue_type`: from response `plan_issue_type` (default: "Sub-task")
+     - `additional_fields`: `{"parent": {"key": "{parent_key}"}}` (links Sub-task to phase Task)
+  2. If MCP call succeeds, record mapping:
+     ```bash
+     node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker record-mapping --type plan --phase {phase} --plan {plan} --key {issue_key} --url {issue_url} --parent {parent_key} 2>/dev/null || true
+     ```
+     Increment created counter.
+  3. If MCP call fails: increment errors counter, continue.
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► TRACKER SYNC — PHASE {N}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Provider: {provider}
+
+| Action  | Count |
+|---------|-------|
+| Created | {created} |
+| Skipped | {skipped} (already synced) |
+| Errors  | {errors} |
+```
+
+### Mode: reschedule
+
+**Only available for `"mcp-atlassian"` provider.** Cascades updated dates to all synced Jira issues after phase add/insert operations shift the schedule.
+
+```bash
+OPS=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker prepare-reschedule --raw)
+```
+
+Parse JSON for `start_date_field` and `operations` array.
+
+Initialize counters: updated=0, skipped=0, errors=0.
+
+For each operation:
+- If `action` is `"update"`:
+  1. Build `additional_fields`:
+     - `{[start_date_field]: operation.start_date, "duedate": operation.due_date}`
+  2. Call MCP tool `update_issue`:
+     - `issue_key`: from operation `issue_key`
+     - `additional_fields`: the built object
+  3. If MCP call succeeds: increment updated counter.
+  4. If MCP call fails: increment errors counter, continue.
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► TRACKER RESCHEDULE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Provider: mcp-atlassian
+
+| Action  | Count |
+|---------|-------|
+| Updated | {updated} |
+| Errors  | {errors} |
+
+Dates recomputed from milestone start + cumulative phase durations.
+```
+
+### Mode: sync-status
+
+```bash
+RESULT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker sync-status --raw)
+```
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► TRACKER STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Provider: {provider}
+Last Synced: {last_synced}
+
+Phases: {synced_phases}/{total_phases} synced
+Plans: {plan_count} tracked
+
+{If unsynced phases exist:}
+Unsynced phases: {unsynced list}
+Run `/grd:sync roadmap` to push them.
+```
+
+</process>
+
+<success_criteria>
+- [ ] Tracker config loaded and validated
+- [ ] Auth status checked before attempting operations
+- [ ] Correct subcommand routed based on arguments
+- [ ] GitHub path uses direct grd-tools.js sync commands
+- [ ] MCP Atlassian path uses prepare → MCP tool → record pattern
+- [ ] Date fields (start_date, due_date) included in additional_fields when present
+- [ ] Reschedule mode updates synced issues with recomputed dates
+- [ ] Results displayed with created/skipped/error counts
+- [ ] Clear guidance when tracker not configured
+</success_criteria>