@jokerized/getresearchdone 0.4.1

package/commands/long-term-roadmap.md

@@ -0,0 +1,202 @@
+---
+description: Create or display long-term roadmap
+argument-hint: [list | add | remove | update | refine | link | unlink | display | init]
+---
+
+<purpose>
+Manage the flat, ordered list of long-term (LT) milestones. Each LT milestone groups 1+ normal milestones from ROADMAP.md with full traceability. Supports CRUD operations, linking/unlinking normal milestones, and protection of completed work.
+</purpose>
+
+<process>
+
+## Step 0: Detect State
+
+Check if LONG-TERM-ROADMAP.md exists:
+
+```bash
+PARSED=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap parse --raw 2>&1)
+```
+
+Parse `$ARGUMENTS` for subcommand:
+- `list` — **List Flow**
+- `add` — **Add Flow**
+- `remove` — **Remove Flow**
+- `update` — **Update Flow**
+- `refine` — **Refine Flow**
+- `link` — **Link Flow**
+- `unlink` — **Unlink Flow**
+- `display` — **Display Flow** (default when no subcommand)
+- `init` — **Init Flow**
+- No subcommand — **Display or Init Flow**
+
+---
+
+## Display or Init Flow
+
+### If LONG-TERM-ROADMAP.md exists:
+
+**Display the current roadmap:**
+
+```bash
+DISPLAY=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap display --raw)
+```
+
+Present the formatted output to the user, then offer actions:
+
+```
+---
+
+## Actions
+
+- `/grd:long-term-roadmap add` — add a new LT milestone
+- `/grd:long-term-roadmap update` — update a milestone's name, goal, or status
+- `/grd:long-term-roadmap link` — link a normal milestone to an LT milestone
+- `/grd:long-term-roadmap refine` — discuss and refine a milestone
+- `/grd:new-milestone` — start executing the active milestone
+
+---
+```
+
+Done.
+
+### If no LONG-TERM-ROADMAP.md:
+
+**Auto-initialize from existing ROADMAP.md:**
+
+```bash
+INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap init --project "<project_name>" --raw)
+```
+
+If ROADMAP.md exists, this auto-groups all existing milestones into LT-1. Write the result to `.planning/LONG-TERM-ROADMAP.md`.
+
+If no ROADMAP.md either, ask the user to create their first milestone with `/grd:init`.
+
+**Then offer to add more LT milestones:**
+
+Use AskUserQuestion:
+- header: "Milestones"
+- question: "Would you like to add more long-term milestones beyond the auto-grouped LT-1?"
+- options:
+  - "Yes" — Ask for milestone details
+  - "No" — Keep LT-1 only for now
+
+If "Yes", ask inline (freeform) for each milestone's name and goal. Use the `add` subcommand for each:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap add --name "<name>" --goal "<goal>"
+```
+
+**Validate and commit:**
+
+```bash
+VALID=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap validate --raw)
+```
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap history \
+  --action "Initial roadmap" \
+  --details "Created <N> LT milestones"
+```
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "docs: create long-term roadmap" --files .planning/LONG-TERM-ROADMAP.md
+```
+
+---
+
+## List Flow
+
+```bash
+LIST=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap list --raw)
+```
+
+Present the list to the user.
+
+---
+
+## Add Flow
+
+Ask inline (freeform) for the milestone name and goal (if not provided as arguments).
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap add --name "<name>" --goal "<goal>"
+```
+
+Write the returned content to `.planning/LONG-TERM-ROADMAP.md`. Log history and commit.
+
+---
+
+## Remove Flow
+
+Parse `$ARGUMENTS` for `--id LT-N`.
+
+```bash
+RESULT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap remove --id "<LT-N>")
+```
+
+**Protection:** The command refuses if the LT milestone has any completed (shipped) normal milestones. Present the error to the user if so.
+
+If successful, write the returned content and commit.
+
+---
+
+## Update Flow
+
+Parse `$ARGUMENTS` for `--id LT-N` and optional `--name`, `--goal`, `--status`.
+
+```bash
+RESULT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap update \
+  --id "<LT-N>" [--name "<name>"] [--goal "<goal>"] [--status "<status>"])
+```
+
+Valid statuses: `completed`, `active`, `planned`. Write result and commit.
+
+---
+
+## Refine Flow
+
+Parse `$ARGUMENTS` for `--id LT-N`.
+
+```bash
+CONTEXT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap refine --id "<LT-N>" --raw)
+```
+
+Present the milestone context to the user. Discuss refinements. After gathering updates, use the `update` subcommand to apply changes. Log history and commit.
+
+---
+
+## Link Flow
+
+Parse `$ARGUMENTS` for `--id LT-N` and `--version vX.Y.Z`.
+
+```bash
+RESULT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap link --id "<LT-N>" --version "<version>")
+```
+
+Write result and commit.
+
+---
+
+## Unlink Flow
+
+Parse `$ARGUMENTS` for `--id LT-N` and `--version vX.Y.Z`.
+
+```bash
+RESULT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap unlink --id "<LT-N>" --version "<version>")
+```
+
+**Protection:** Refuses to unlink shipped versions. Present error if so. Write result and commit.
+
+---
+
+</process>
+
+<success_criteria>
+- [ ] Init creates LONG-TERM-ROADMAP.md from existing ROADMAP.md milestones
+- [ ] Display shows formatted LT milestone list with status icons
+- [ ] Add/Remove/Update CRUD operations work with protection rules
+- [ ] Link/Unlink manages normal milestone associations
+- [ ] Shipped milestones cannot be removed or unlinked
+- [ ] All changes committed with history logged
+- [ ] Validation passes after any modification
+</success_criteria>

package/commands/map-codebase.md

@@ -0,0 +1,111 @@
+---
+description: Analyze codebase architecture with parallel mapper agents
+---
+
+<purpose>
+Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in the codebase directory
+
+Each agent has fresh context, explores a specific focus area, and writes documents directly. The orchestrator only receives confirmation + line counts, then writes a summary.
+
+Output: ${codebase_dir}/ folder with 7 structured documents about the codebase state.
+</purpose>
+
+<shell_safety>
+NEVER use inline `node -e` or `python3 -c` with `!=` or `!==` — zsh escapes `!` and breaks them.
+Use `grd-tools.js` pre-formatted output directly. Do NOT pipe `--raw` JSON through inline one-liners.
+If JSON field extraction is needed, write a temp .js file or use inverted equality (`=== "x"` + negate).
+</shell_safety>
+
+<process>
+
+<step name="init_context" priority="first">
+```bash
+INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js init map-codebase)
+```
+
+Extract: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`.
+</step>
+
+<step name="check_existing">
+If `codebase_dir_exists` is true: Offer Refresh/Update/Skip.
+If doesn't exist: Continue to create_structure.
+</step>
+
+<step name="create_structure">
+```bash
+mkdir -p ${codebase_dir}
+```
+
+Expected: STACK.md, INTEGRATIONS.md, ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, CONCERNS.md
+</step>
+
+<step name="spawn_agents">
+Spawn 4 parallel grd-codebase-mapper agents:
+
+**Agent 1: Tech Focus** — STACK.md, INTEGRATIONS.md
+**Agent 2: Architecture Focus** — ARCHITECTURE.md, STRUCTURE.md
+**Agent 3: Quality Focus** — CONVENTIONS.md, TESTING.md
+**Agent 4: Concerns Focus** — CONCERNS.md
+
+Each uses `subagent_type="grd:grd-codebase-mapper"`, `model="{mapper_model}"`, `run_in_background=true`.
+
+Each agent prompt includes:
+```
+PATHS:
+codebase_dir: ${codebase_dir}
+```
+</step>
+
+<step name="verify_output">
+```bash
+ls -la ${codebase_dir}/
+wc -l ${codebase_dir}/*.md
+```
+
+All 7 documents exist, no empty documents.
+</step>
+
+<step name="scan_for_secrets">
+```bash
+grep -E '(sk-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36}|AKIA[A-Z0-9]{16}|-----BEGIN.*PRIVATE KEY)' ${codebase_dir}/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
+```
+
+If SECRETS_FOUND: Alert and pause before commit.
+</step>
+
+<step name="commit_codebase_map">
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "docs: map existing codebase" --files ${codebase_dir}/*.md
+```
+</step>
+
+<step name="offer_next">
+```
+Codebase mapping complete.
+
+Created ${codebase_dir}/:
+- STACK.md, ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, INTEGRATIONS.md, CONCERNS.md
+
+---
+
+## Next Up
+
+**Initialize project** — use codebase context for planning
+
+`/grd:init`
+
+<sub>`/clear` first -> fresh context window</sub>
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- ${codebase_dir}/ directory created
+- 4 parallel grd-codebase-mapper agents spawned
+- All 7 codebase documents exist
+- Clear completion summary with line counts
+- User offered clear next steps
+</success_criteria>

package/commands/migrate.md

@@ -0,0 +1,159 @@
+---
+description: Migrate legacy flat .planning/ layout to milestone-scoped hierarchy
+---
+
+<purpose>
+Migrate a legacy flat `.planning/` layout (phases/, research/, todos/, quick/ at root) to the milestone-scoped hierarchy (`.planning/milestones/{milestone}/...`). Note: `codebase/` is project-level and stays at `.planning/codebase/`. Handles both trivial cases (standard dirs) via the deterministic `migrate-dirs` CLI and complex cases (orphan files, flat milestone files, legacy phase dirs) via the `grd-migrator` agent.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+**Step 1: Load context**
+
+```bash
+INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js state load)
+```
+
+Parse JSON for: `milestone`, `planning_exists`.
+
+**If `planning_exists` is false:** Error — no `.planning/` directory found. Nothing to migrate.
+
+---
+
+**Step 2: Scan for migration needs**
+
+Scan `.planning/` for items that need migration:
+
+**Trivial items** (handled by `migrate-dirs` CLI):
+- Old-style root dirs: `phases/`, `research/`, `todos/`, `quick/`
+- Note: `codebase/` is project-level and stays at `.planning/codebase/` — not migrated
+
+**Complex items** (need agent):
+- Orphan files at `.planning/` root that aren't standard (not STATE.md, ROADMAP.md, PROJECT.md, BASELINE.md, PRODUCT-QUALITY.md, REQUIREMENTS.md, config.json, TRACKER.md, LONG-TERM-ROADMAP.md)
+- Flat milestone files in `milestones/` (e.g., `v0.X-ROADMAP.md`, `v0.X-REQUIREMENTS.md`)
+- Legacy `v0.X-phases/` dirs in `milestones/`
+
+Classify each item as `trivial` or `complex`.
+
+---
+
+**Step 3: Trivial-only path**
+
+If only trivial items exist (or nothing to migrate):
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js migrate-dirs --raw
+```
+
+If output shows `already_migrated: true` or all dirs moved successfully, report success and exit.
+
+---
+
+**Step 4: Complex items — present migration plan**
+
+If complex items were found, build a migration plan table and present to user:
+
+```
+AskUserQuestion(
+  header: "Migration",
+  question: "The following items need migration. Proceed?",
+  options: [
+    { label: "Yes, migrate all", description: "Run trivial migration + spawn agent for complex items" },
+    { label: "Trivial only", description: "Only migrate standard directories, skip complex items" },
+    { label: "Cancel", description: "Don't migrate anything" }
+  ]
+)
+```
+
+Display table of items:
+
+| Item | Type | Action |
+|------|------|--------|
+| phases/ | trivial | Move to milestones/{milestone}/phases/ |
+| milestones/v0.1-ROADMAP.md | complex | Move to milestones/v0.1/ROADMAP.md |
+| ... | ... | ... |
+
+---
+
+**Step 5: Execute trivial migration**
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js migrate-dirs --raw
+```
+
+---
+
+**Step 6: Spawn grd-migrator for complex items**
+
+If user chose to migrate complex items:
+
+```
+Task(
+  prompt="
+<migration_context>
+
+**Milestone:** ${milestone}
+**Complex items to migrate:**
+${complex_items_list}
+
+**Project State:**
+@.planning/STATE.md
+
+</migration_context>
+
+<constraints>
+- Move flat milestone files to their proper milestone subdirectories
+- Move legacy phase dirs to proper milestone structure
+- For orphan docs: read content, infer milestone from content, flag low-confidence for user decision
+- Non-standard files: flag for user (keep/move/delete)
+- Commit atomically after all moves
+- Do NOT modify file contents — only move files
+</constraints>
+",
+  subagent_type="grd:grd-migrator",
+  description="Migrate complex .planning/ items"
+)
+```
+
+---
+
+**Step 7: Validate and commit**
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js validate consistency
+```
+
+If validation passes, commit migration results:
+
+```bash
+git add .planning/
+git commit -m "chore: migrate .planning/ to milestone-scoped hierarchy"
+```
+
+Display completion output:
+```
+---
+
+GRD > MIGRATION COMPLETE
+
+Milestone: ${milestone}
+Trivial items: ${trivial_count} migrated
+Complex items: ${complex_count} migrated
+
+Validation: PASSED
+
+---
+```
+
+</process>
+
+<success_criteria>
+- [ ] `.planning/` scanned for migration needs
+- [ ] Trivial dirs migrated via `migrate-dirs` CLI
+- [ ] Complex items handled by `grd-migrator` agent (if any)
+- [ ] `validate consistency` passes after migration
+- [ ] Changes committed atomically
+</success_criteria>

package/commands/new-milestone.md

@@ -0,0 +1,169 @@
+---
+description: Start a new milestone cycle with research, requirements, and roadmap
+---
+
+<purpose>
+Start a new milestone cycle for an existing project. Loads project context, gathers milestone goals (from MILESTONE-CONTEXT.md or conversation), updates PROJECT.md and STATE.md, optionally runs parallel research, defines scoped requirements with REQ-IDs, spawns the roadmapper to create phased execution plan, and commits all artifacts. Brownfield equivalent of new-project.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+## 1. Load Context
+
+- Read PROJECT.md (existing project, validated requirements, decisions)
+- Read MILESTONES.md (what shipped previously)
+- Read STATE.md (pending todos, blockers)
+- Check for MILESTONE-CONTEXT.md (from /grd:discuss-milestone)
+
+## 2. Gather Milestone Goals
+
+**If MILESTONE-CONTEXT.md exists:** Use features and scope, present for confirmation.
+**If no context file:** Present what shipped, ask: "What do you want to build next?"
+
+## 3. Determine Milestone Version
+
+Parse last version from MILESTONES.md. Suggest next version. Confirm with user.
+
+## 4. Update PROJECT.md
+
+Add Current Milestone section with goal and target features. Update Active requirements.
+
+## 5. Update STATE.md
+
+Reset position to "Not started (defining requirements)".
+
+## 6. Cleanup and Commit
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
+```
+
+## 7. Load Context and Resolve Models
+
+```bash
+INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js init new-milestone)
+```
+
+Extract: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `suggested_start_phase`, `research_dir`.
+
+If `gate_failed` is true, stop and report the gate errors to the user before proceeding.
+
+## 8. Research Decision
+
+AskUserQuestion: "Research the domain ecosystem for new features before defining requirements?"
+
+**If "Research first":** Spawn 4 parallel grd-project-researcher agents (Stack, Features, Architecture, Pitfalls), then synthesizer. Use subsequent milestone context (focus on NEW features, not existing system).
+
+```bash
+mkdir -p ${research_dir}
+```
+
+**If "Skip research":** Continue to Step 9.
+
+## 9. Define Requirements
+
+Read PROJECT.md, existing validated requirements. Present features by category via research or conversation. Scope each category via AskUserQuestion.
+
+Generate REQUIREMENTS.md with REQ-IDs continuing from existing numbering.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
+```
+
+## 10. Create Roadmap
+
+Start phase numbering from `suggested_start_phase` (computed by `init new-milestone` from archived and current phase directories).
+
+```
+Task(prompt="
+<planning_context>
+@.planning/PROJECT.md
+@.planning/REQUIREMENTS.md
+@${research_dir}/SUMMARY.md (if exists)
+@.planning/config.json
+@.planning/MILESTONES.md
+</planning_context>
+
+<instructions>
+Create roadmap for milestone v[X.Y]:
+1. Start phase numbering from {suggested_start_phase}
+2. Derive phases from THIS MILESTONE's requirements only
+3. Map every requirement to exactly one phase
+4. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
+5. Return ROADMAP CREATED with summary
+</instructions>
+", subagent_type="grd:grd-roadmapper", model="{roadmapper_model}", description="Create roadmap")
+```
+
+Handle return (BLOCKED or CREATED), present inline, get approval, commit.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+```
+
+## 10.5. Link to Long-Term Roadmap
+
+Check if LONG-TERM-ROADMAP.md exists:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap list --raw 2>/dev/null
+```
+
+**If LT roadmap exists:**
+
+Find the active LT milestone and offer to link:
+
+Use AskUserQuestion:
+- header: "LT Link"
+- question: "Link this milestone to an LT milestone?"
+- options:
+  - "Link to [active LT milestone name]" — Associate v[X.Y] with the active LT milestone
+  - "Skip" — Don't link to long-term roadmap
+
+**If "Link":**
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js long-term-roadmap link --id [LT-N] --version v[X.Y]
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "docs: link v[X.Y] to [LT-N]" --files .planning/LONG-TERM-ROADMAP.md
+```
+
+**If no LT roadmap exists:** Skip silently.
+
+## 11. Done
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► MILESTONE INITIALIZED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Milestone v[X.Y]: [Name]**
+
+**[N] phases** | **[X] requirements** | Ready to build
+
+## Next Up
+
+**Phase [N]: [Phase Name]** — [Goal]
+
+`/grd:discuss-phase [N]` — gather context and clarify approach
+
+<sub>`/clear` first -> fresh context window</sub>
+
+Also: `/grd:plan-phase [N]` — skip discussion, plan directly
+```
+
+</process>
+
+<success_criteria>
+- [ ] PROJECT.md updated with Current Milestone section
+- [ ] STATE.md reset for new milestone
+- [ ] Research completed (if selected) — 4 parallel agents, milestone-aware
+- [ ] REQUIREMENTS.md created with REQ-IDs
+- [ ] grd-roadmapper spawned with phase numbering context
+- [ ] ROADMAP.md phases continue from previous milestone
+- [ ] All commits made
+- [ ] LT roadmap link offered (if LONG-TERM-ROADMAP.md exists)
+- [ ] User knows next step: `/grd:discuss-phase [N]`
+</success_criteria>