@jokerized/getresearchdone 0.4.1

package/commands/tracker-setup.md

@@ -0,0 +1,322 @@
+---
+description: Configure issue tracker integration (GitHub Issues or MCP Atlassian)
+argument-hint:
+---
+
+<purpose>
+Interactive setup for issue tracker integration. Walks the user through choosing a provider (GitHub/MCP Atlassian/None), validates prerequisites, writes config, and optionally runs initial sync.
+</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 Current Config
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js config-ensure-section
+TRACKER_CONFIG=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker get-config --raw)
+```
+
+Parse current provider (may be "none" or already configured).
+
+## Step 2: Choose Provider
+
+Use AskUserQuestion:
+
+```
+AskUserQuestion([
+  {
+    question: "Which issue tracker do you want to use?",
+    header: "Tracker",
+    multiSelect: false,
+    options: [
+      { label: "GitHub Issues (Recommended)", description: "Uses gh CLI. Issues, labels, sub-issues." },
+      { label: "MCP Atlassian (Jira)", description: "Uses mcp-atlassian MCP server. Epics, tasks, transitions." },
+      { label: "None", description: "Disable tracker integration." }
+    ]
+  }
+])
+```
+
+**If "None":** Set `tracker.provider = "none"`, write config, display confirmation, exit.
+
+## Step 3: Provider-Specific Setup
+
+### GitHub Setup
+
+**3a. Check prerequisites:**
+
+```bash
+gh --version 2>/dev/null && echo "gh_ok" || echo "gh_missing"
+gh auth status 2>/dev/null && echo "auth_ok" || echo "auth_missing"
+gh extension list 2>/dev/null | grep sub-issue && echo "subissue_ok" || echo "subissue_missing"
+```
+
+**If `gh` not installed:**
+```
+GitHub CLI (gh) is required. Install it:
+  brew install gh           # macOS
+  sudo apt install gh       # Linux
+  winget install GitHub.cli # Windows
+
+Then: gh auth login
+```
+Exit.
+
+**If not authenticated:**
+```
+Please authenticate: gh auth login
+```
+Exit.
+
+**If sub-issue extension missing:** Note as optional:
+```
+Optional: Install gh-sub-issue for parent/child issue linking:
+  gh extension install github/gh-sub-issue
+```
+
+**3b. Configure GitHub settings:**
+
+Use AskUserQuestion:
+
+```
+AskUserQuestion([
+  {
+    question: "Default assignee for created issues? (GitHub username, leave blank for none)",
+    header: "Assignee",
+    multiSelect: false,
+    options: [
+      { label: "None", description: "Don't auto-assign issues" },
+      { label: "Me", description: "Assign to current gh user" }
+    ]
+  }
+])
+```
+
+If "Me": get username from `gh api user --jq '.login'`.
+
+**3c. Write config:**
+
+```json
+{
+  "tracker": {
+    "provider": "github",
+    "auto_sync": true,
+    "github": {
+      "project_board": "",
+      "default_assignee": "{username or empty}",
+      "default_labels": ["research", "implementation", "evaluation", "integration"],
+      "auto_issues": true,
+      "pr_per_phase": false
+    }
+  }
+}
+```
+
+Merge into existing `.planning/config.json`.
+
+### MCP Atlassian Setup
+
+**3a. Validate MCP server connectivity:**
+
+Call MCP tool `get_all_projects` to verify the mcp-atlassian server is available and authenticated.
+
+**If MCP tool call fails:**
+```
+The mcp-atlassian MCP server is not available or not configured.
+
+To set up mcp-atlassian:
+1. Add the mcp-atlassian server to your Claude Code MCP configuration
+2. Configure it with your Atlassian credentials (see mcp-atlassian docs)
+3. Restart Claude Code
+4. Run /grd:tracker-setup again
+```
+Exit.
+
+**3b. Select project:**
+
+Parse the project list from `get_all_projects` response. Show available projects.
+
+Use AskUserQuestion to let user pick project_key (show up to 4 projects from the response, user can type "Other" for a different key):
+
+```
+AskUserQuestion([
+  {
+    question: "Which Jira project should GRD sync to?",
+    header: "Project",
+    multiSelect: false,
+    options: [
+      // Dynamic: up to 4 projects from MCP response
+      { label: "{KEY1} — {name1}", description: "Project key: {KEY1}" },
+      { label: "{KEY2} — {name2}", description: "Project key: {KEY2}" }
+    ]
+  }
+])
+```
+
+**3c. Configure issue types:**
+
+Use AskUserQuestion:
+
+```
+AskUserQuestion([
+  {
+    question: "Issue type for milestone Epics?",
+    header: "Epic type",
+    multiSelect: false,
+    options: [
+      { label: "Epic (Recommended)", description: "Standard Jira Epic — maps to GRD milestones" },
+      { label: "Story", description: "Use Story instead of Epic for milestones" }
+    ]
+  },
+  {
+    question: "Issue type for phase Tasks (children of milestone Epic)?",
+    header: "Task type",
+    multiSelect: false,
+    options: [
+      { label: "Task (Recommended)", description: "Standard Jira Task — maps to GRD phases" },
+      { label: "Story", description: "Use Story instead of Task for phases" }
+    ]
+  },
+  {
+    question: "Issue type for plan Sub-tasks (children of phase Task)?",
+    header: "Sub-task type",
+    multiSelect: false,
+    options: [
+      { label: "Sub-task (Recommended)", description: "Standard Jira Sub-task — maps to GRD plans" },
+      { label: "Task", description: "Use Task instead of Sub-task for plans" }
+    ]
+  }
+])
+```
+
+**3d. Configure schedule fields:**
+
+Use AskUserQuestion:
+
+```
+AskUserQuestion([
+  {
+    question: "Which Jira field stores start dates? (Jira Plans / Advanced Roadmaps uses this for timeline display)",
+    header: "Start date",
+    multiSelect: false,
+    options: [
+      { label: "customfield_10015 (Recommended)", description: "Standard Jira Cloud start date field used by most instances" },
+      { label: "startDate", description: "Newer Jira Cloud instances use this built-in field" },
+      { label: "customfield_10014", description: "Alternative custom field ID (some instances)" }
+    ]
+  },
+  {
+    question: "Default phase duration in days? (Used when **Duration:** is not specified in ROADMAP.md)",
+    header: "Duration",
+    multiSelect: false,
+    options: [
+      { label: "7 days (Recommended)", description: "One week per phase — good starting default" },
+      { label: "14 days", description: "Two weeks per phase — for longer research phases" },
+      { label: "5 days", description: "One work week per phase — compact sprints" }
+    ]
+  }
+])
+```
+
+**3e. Write config:**
+
+```json
+{
+  "tracker": {
+    "provider": "mcp-atlassian",
+    "auto_sync": true,
+    "mcp_atlassian": {
+      "project_key": "{project_key}",
+      "milestone_issue_type": "Epic",
+      "phase_issue_type": "Task",
+      "plan_issue_type": "Sub-task",
+      "start_date_field": "{start_date_field}",
+      "default_duration_days": {default_duration_days}
+    }
+  }
+}
+```
+
+Merge into existing `.planning/config.json`.
+
+## Step 4: Optional Initial Sync
+
+If ROADMAP.md exists:
+
+Use AskUserQuestion:
+
+```
+AskUserQuestion([
+  {
+    question: "ROADMAP.md found. Run initial sync now?",
+    header: "Sync",
+    multiSelect: false,
+    options: [
+      { label: "Yes", description: "Push all phases to tracker now" },
+      { label: "No", description: "Sync later with /grd:sync" }
+    ]
+  }
+])
+```
+
+If "Yes":
+
+**For GitHub:**
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker sync-roadmap --raw
+```
+
+**For mcp-atlassian:**
+Follow MCP protocol from @${CLAUDE_PLUGIN_ROOT}/references/mcp-tracker-protocol.md:
+```bash
+OPS=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker prepare-roadmap-sync --raw)
+```
+Execute MCP `create_issue` for each `"create"` operation, then `record-mapping`.
+
+Display results.
+
+## Step 5: Confirmation
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► TRACKER CONFIGURED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| Setting        | Value |
+|----------------|-------|
+| Provider       | {github/mcp-atlassian} |
+| Auto-sync      | On |
+| Auth Status    | {authenticated/mcp_server} |
+{GitHub:}
+| Assignee       | {username or none} |
+{MCP Atlassian:}
+| Project Key    | {key} |
+| Milestone Type | {milestone_issue_type} |
+| Phase Type     | {phase_issue_type} |
+| Plan Type      | {plan_issue_type} |
+| Start Date Field | {start_date_field} |
+| Default Duration | {default_duration_days}d |
+
+Tracker will auto-sync during:
+- Roadmap creation (/grd:init)
+- Phase planning (/grd:plan-phase)
+- Phase execution (/grd:execute-phase)
+- Verification (/grd:verify-phase)
+
+Manual sync: /grd:sync
+```
+
+</process>
+
+<success_criteria>
+- [ ] Provider selected (GitHub/MCP Atlassian/None)
+- [ ] Prerequisites validated (gh CLI for GitHub, MCP server connectivity for MCP Atlassian)
+- [ ] Config written to .planning/config.json
+- [ ] Optional initial sync offered and executed
+- [ ] Clear confirmation with next steps
+</success_criteria>

package/commands/update.md

@@ -0,0 +1,202 @@
+---
+description: Update GRD to latest version with changelog display
+argument-hint: ""
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+<purpose>
+Self-update GRD plugin to the latest version. Detects install method, checks for updates,
+displays changelog, backs up local modifications, and pulls latest code. Supports both
+git-clone and manual installations.
+</purpose>
+
+<context>
+CLAUDE.md rules: @CLAUDE.md
+Plugin root: ${CLAUDE_PLUGIN_ROOT}
+</context>
+
+<process>
+
+## Step 1: DETECT INSTALL METHOD AND CURRENT VERSION
+
+```bash
+cd "${CLAUDE_PLUGIN_ROOT}"
+```
+
+Read VERSION file for current version:
+```bash
+cat "${CLAUDE_PLUGIN_ROOT}/VERSION"
+```
+
+Check if installed via git:
+```bash
+cd "${CLAUDE_PLUGIN_ROOT}" && git remote -v 2>/dev/null
+```
+
+**If no git remote:** Error — manual installation detected.
+```
+GRD was installed manually (no git remote detected).
+
+To enable auto-update:
+  cd ${CLAUDE_PLUGIN_ROOT}
+  git init
+  git remote add origin https://github.com/ca1773130n/GRD.git
+  git fetch origin
+  git reset --mixed origin/main
+
+Then re-run /grd:update.
+```
+
+## Step 2: CHECK FOR UPDATES
+
+```bash
+cd "${CLAUDE_PLUGIN_ROOT}" && git fetch origin 2>&1
+```
+
+Count commits behind:
+```bash
+cd "${CLAUDE_PLUGIN_ROOT}" && git rev-list HEAD..origin/main --count 2>/dev/null
+```
+
+**If 0 commits behind:**
+```
+GRD is up to date (v{current_version}).
+```
+Exit.
+
+## Step 3: DISPLAY CHANGELOG
+
+Fetch remote CHANGELOG.md:
+```bash
+cd "${CLAUDE_PLUGIN_ROOT}" && git show origin/main:CHANGELOG.md 2>/dev/null
+```
+
+Display changes between current and latest version. Parse CHANGELOG.md to show only
+entries newer than current version.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD UPDATE AVAILABLE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Current: v{current_version}
+  Latest:  v{remote_version}
+  Commits: {N} new commits
+
+## What's New
+
+{changelog entries between current and latest}
+```
+
+## Step 4: DETECT LOCAL MODIFICATIONS
+
+Run manifest detection:
+```bash
+cd "${CLAUDE_PLUGIN_ROOT}" && node bin/grd-manifest.js detect
+```
+
+Parse JSON output. If modifications exist:
+```
+## Local Modifications Detected
+
+  {N} file(s) modified from original:
+
+  - {file1}
+  - {file2}
+
+  These will be backed up before updating.
+```
+
+## Step 5: CONFIRM UPDATE
+
+Use AskUserQuestion:
+- header: "Update"
+- question: "Update GRD from v{current} to v{latest}?"
+- options:
+  - "Update now" — Back up modifications and pull latest
+  - "Cancel" — Stay on current version
+
+**If "Cancel":** Exit.
+
+## Step 6: BACKUP MODIFICATIONS
+
+If modifications were detected in Step 4:
+```bash
+cd "${CLAUDE_PLUGIN_ROOT}" && node bin/grd-manifest.js save-patches
+```
+
+Display backup summary:
+```
+Backed up {N} modified file(s) to grd-local-patches/
+```
+
+## Step 7: PULL UPDATE
+
+```bash
+cd "${CLAUDE_PLUGIN_ROOT}" && git pull origin main
+```
+
+**If merge conflict:**
+```
+Update failed due to merge conflicts.
+
+Your local modifications have been saved to:
+  ${CLAUDE_PLUGIN_ROOT}/grd-local-patches/
+
+To resolve:
+  1. cd ${CLAUDE_PLUGIN_ROOT}
+  2. git merge --abort
+  3. git reset --hard origin/main
+  4. /grd:reapply-patches
+```
+
+## Step 8: REGENERATE MANIFEST
+
+```bash
+cd "${CLAUDE_PLUGIN_ROOT}" && node bin/grd-manifest.js generate
+```
+
+## Step 9: DISPLAY RESULT
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD UPDATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  v{old_version} → v{new_version}
+  {N} files updated
+```
+
+If patches were saved:
+```
+  Local modifications backed up to grd-local-patches/
+
+  Run /grd:reapply-patches to restore your customizations.
+```
+
+</process>
+
+<output>
+Updated plugin files via git pull. Manifest regenerated.
+Optional: grd-local-patches/ created with user modifications.
+</output>
+
+<error_handling>
+- **No git remote**: Suggest manual git init + remote add
+- **Fetch fails (network)**: Display error, suggest retry
+- **Merge conflicts**: Abort merge, point to reapply-patches
+- **Manifest missing**: Generate one before detecting modifications
+</error_handling>
+
+<success_criteria>
+- [ ] Current version detected from VERSION file
+- [ ] Git remote verified
+- [ ] Remote changes fetched and counted
+- [ ] Changelog displayed for relevant versions
+- [ ] Local modifications detected and reported
+- [ ] User confirms before proceeding
+- [ ] Modified files backed up to grd-local-patches/
+- [ ] git pull executed successfully
+- [ ] New manifest generated
+- [ ] User informed of reapply-patches if needed
+</success_criteria>