gsd-code-first 1.0.0

package/get-shit-done/workflows/new-workspace.md

@@ -0,0 +1,237 @@
+<purpose>
+Create an isolated workspace directory with git repo copies (worktrees or clones) and an independent `.planning/` directory. Supports multi-repo orchestration and single-repo feature branch isolation.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+## 1. Setup
+
+**MANDATORY FIRST STEP — Execute init command:**
+
+```bash
+INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init new-workspace)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `default_workspace_base`, `child_repos`, `child_repo_count`, `worktree_available`, `is_git_repo`, `cwd_repo_name`, `project_root`.
+
+## 2. Parse Arguments
+
+Extract from $ARGUMENTS:
+- `--name` → `WORKSPACE_NAME` (required)
+- `--repos` → `REPO_LIST` (comma-separated paths or names)
+- `--path` → `TARGET_PATH` (defaults to `$default_workspace_base/$WORKSPACE_NAME`)
+- `--strategy` → `STRATEGY` (defaults to `worktree`)
+- `--branch` → `BRANCH_NAME` (defaults to `workspace/$WORKSPACE_NAME`)
+- `--auto` → skip interactive questions
+
+**If `--name` is missing and not `--auto`:**
+
+Use AskUserQuestion:
+- header: "Workspace Name"
+- question: "What should this workspace be called?"
+- requireAnswer: true
+
+## 3. Select Repos
+
+**If `--repos` is provided:** Parse comma-separated values. For each value:
+- If it's an absolute path, use it directly
+- If it's a relative path or name, resolve against `$project_root`
+- Special case: `.` means current repo (use `$project_root`, name it `$cwd_repo_name`)
+
+**If `--repos` is NOT provided and not `--auto`:**
+
+**If `child_repo_count` > 0:**
+
+Present child repos for selection:
+
+Use AskUserQuestion:
+- header: "Select Repos"
+- question: "Which repos should be included in the workspace?"
+- options: List each child repo from `child_repos` array by name
+- multiSelect: true
+
+**If `child_repo_count` is 0 and `is_git_repo` is true:**
+
+Use AskUserQuestion:
+- header: "Current Repo"
+- question: "No child repos found. Create a workspace with the current repo?"
+- options:
+  - "Yes — create workspace with current repo" → use current repo
+  - "Cancel" → exit
+
+**If `child_repo_count` is 0 and `is_git_repo` is false:**
+
+Error:
+```
+No git repos found in the current directory and this is not a git repo.
+
+Run this command from a directory containing git repos, or specify repos explicitly:
+  /gsd:new-workspace --name my-workspace --repos /path/to/repo1,/path/to/repo2
+```
+Exit.
+
+**If `--auto` and `--repos` is NOT provided:**
+
+Error:
+```
+Error: --auto requires --repos to specify which repos to include.
+
+Usage:
+  /gsd:new-workspace --name my-workspace --repos repo1,repo2 --auto
+```
+Exit.
+
+## 4. Select Strategy
+
+**If `--strategy` is provided:** Use it (validate: must be `worktree` or `clone`).
+
+**If `--strategy` is NOT provided and not `--auto`:**
+
+Use AskUserQuestion:
+- header: "Strategy"
+- question: "How should repos be copied into the workspace?"
+- options:
+  - "Worktree (recommended) — lightweight, shares .git objects with source repo" → `worktree`
+  - "Clone — fully independent copy, no connection to source repo" → `clone`
+
+**If `--auto`:** Default to `worktree`.
+
+## 5. Validate
+
+Before creating anything, validate:
+
+1. **Target path** — must not exist or must be empty:
+```bash
+if [ -d "$TARGET_PATH" ] && [ "$(ls -A "$TARGET_PATH" 2>/dev/null)" ]; then
+  echo "Error: Target path already exists and is not empty: $TARGET_PATH"
+  echo "Choose a different --name or --path."
+  exit 1
+fi
+```
+
+2. **Source repos exist and are git repos** — for each repo path:
+```bash
+if [ ! -d "$REPO_PATH/.git" ]; then
+  echo "Error: Not a git repo: $REPO_PATH"
+  exit 1
+fi
+```
+
+3. **Worktree availability** — if strategy is `worktree` and `worktree_available` is false:
+```
+Error: git is not available. Install git or use --strategy clone.
+```
+
+Report all validation errors at once, not one at a time.
+
+## 6. Create Workspace
+
+```bash
+mkdir -p "$TARGET_PATH"
+```
+
+### For each repo:
+
+**Worktree strategy:**
+```bash
+cd "$SOURCE_REPO_PATH"
+git worktree add "$TARGET_PATH/$REPO_NAME" -b "$BRANCH_NAME" 2>&1
+```
+
+If `git worktree add` fails because the branch already exists, try with a timestamped branch:
+```bash
+TIMESTAMP=$(date +%Y%m%d%H%M%S)
+git worktree add "$TARGET_PATH/$REPO_NAME" -b "${BRANCH_NAME}-${TIMESTAMP}" 2>&1
+```
+
+If that also fails, report the error and continue with remaining repos.
+
+**Clone strategy:**
+```bash
+git clone "$SOURCE_REPO_PATH" "$TARGET_PATH/$REPO_NAME" 2>&1
+cd "$TARGET_PATH/$REPO_NAME"
+git checkout -b "$BRANCH_NAME" 2>&1
+```
+
+Track results: which repos succeeded, which failed, what branch was used.
+
+## 7. Write WORKSPACE.md
+
+Write the workspace manifest at `$TARGET_PATH/WORKSPACE.md`:
+
+```markdown
+# Workspace: $WORKSPACE_NAME
+
+Created: $DATE
+Strategy: $STRATEGY
+
+## Member Repos
+
+| Repo | Source | Branch | Strategy |
+|------|--------|--------|----------|
+| $REPO_NAME | $SOURCE_PATH | $BRANCH | $STRATEGY |
+...for each repo...
+
+## Notes
+
+[Add context about what this workspace is for]
+```
+
+## 8. Initialize .planning/
+
+```bash
+mkdir -p "$TARGET_PATH/.planning"
+```
+
+## 9. Report and Next Steps
+
+**If all repos succeeded:**
+
+```
+Workspace created: $TARGET_PATH
+
+  Repos: $REPO_COUNT
+  Strategy: $STRATEGY
+  Branch: $BRANCH_NAME
+
+Next steps:
+  cd $TARGET_PATH
+  /gsd:new-project    # Initialize GSD in the workspace
+```
+
+**If some repos failed:**
+
+```
+Workspace created with $SUCCESS_COUNT of $TOTAL_COUNT repos: $TARGET_PATH
+
+  Succeeded: repo1, repo2
+  Failed: repo3 (branch already exists), repo4 (not a git repo)
+
+Next steps:
+  cd $TARGET_PATH
+  /gsd:new-project    # Initialize GSD in the workspace
+```
+
+**Offer to initialize GSD (if not `--auto`):**
+
+Use AskUserQuestion:
+- header: "Initialize GSD"
+- question: "Would you like to initialize a GSD project in the new workspace?"
+- options:
+  - "Yes — run /gsd:new-project" → tell user to `cd $TARGET_PATH` first, then run `/gsd:new-project`
+  - "No — I'll set it up later" → done
+
+</process>
+
+<success_criteria>
+- [ ] Workspace directory created at target path
+- [ ] All specified repos copied (worktree or clone) into workspace
+- [ ] WORKSPACE.md manifest written with correct repo table
+- [ ] `.planning/` directory initialized at workspace root
+- [ ] User informed of workspace path and next steps
+</success_criteria>

package/get-shit-done/workflows/next.md

@@ -0,0 +1,97 @@
+<purpose>
+Detect current project state and automatically advance to the next logical GSD workflow step.
+Reads project state to determine: discuss → plan → execute → verify → complete progression.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="detect_state">
+Read project state to determine current position:
+
+```bash
+# Get state snapshot
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state json 2>/dev/null || echo "{}"
+```
+
+Also read:
+- `.planning/STATE.md` — current phase, progress, plan counts
+- `.planning/ROADMAP.md` — milestone structure and phase list
+
+Extract:
+- `current_phase` — which phase is active
+- `plan_of` / `plans_total` — plan execution progress
+- `progress` — overall percentage
+- `status` — active, paused, etc.
+
+If no `.planning/` directory exists:
+```
+No GSD project detected. Run `/gsd:new-project` to get started.
+```
+Exit.
+</step>
+
+<step name="determine_next_action">
+Apply routing rules based on state:
+
+**Route 1: No phases exist yet → discuss**
+If ROADMAP has phases but no phase directories exist on disk:
+→ Next action: `/gsd:discuss-phase <first-phase>`
+
+**Route 2: Phase exists but has no CONTEXT.md or RESEARCH.md → discuss**
+If the current phase directory exists but has neither CONTEXT.md nor RESEARCH.md:
+→ Next action: `/gsd:discuss-phase <current-phase>`
+
+**Route 3: Phase has context but no plans → plan**
+If the current phase has CONTEXT.md (or RESEARCH.md) but no PLAN.md files:
+→ Next action: `/gsd:plan-phase <current-phase>`
+
+**Route 4: Phase has plans but incomplete summaries → execute**
+If plans exist but not all have matching summaries:
+→ Next action: `/gsd:execute-phase <current-phase>`
+
+**Route 5: All plans have summaries → verify and complete**
+If all plans in the current phase have summaries:
+→ Next action: `/gsd:verify-work` then `/gsd:complete-phase`
+
+**Route 6: Phase complete, next phase exists → advance**
+If the current phase is complete and the next phase exists in ROADMAP:
+→ Next action: `/gsd:discuss-phase <next-phase>`
+
+**Route 7: All phases complete → complete milestone**
+If all phases are complete:
+→ Next action: `/gsd:complete-milestone`
+
+**Route 8: Paused → resume**
+If STATE.md shows paused_at:
+→ Next action: `/gsd:resume-work`
+</step>
+
+<step name="show_and_execute">
+Display the determination:
+
+```
+## GSD Next
+
+**Current:** Phase [N] — [name] | [progress]%
+**Status:** [status description]
+
+▶ **Next step:** `/gsd:[command] [args]`
+  [One-line explanation of why this is the next step]
+```
+
+Then immediately invoke the determined command via SlashCommand.
+Do not ask for confirmation — the whole point of `/gsd:next` is zero-friction advancement.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Project state correctly detected
+- [ ] Next action correctly determined from routing rules
+- [ ] Command invoked immediately without user confirmation
+- [ ] Clear status shown before invoking
+</success_criteria>

package/get-shit-done/workflows/node-repair.md

@@ -0,0 +1,92 @@
+<purpose>
+Autonomous repair operator for failed task verification. Invoked by execute-plan when a task fails its done-criteria. Proposes and attempts structured fixes before escalating to the user.
+</purpose>
+
+<inputs>
+- FAILED_TASK: Task number, name, and done-criteria from the plan
+- ERROR: What verification produced — actual result vs expected
+- PLAN_CONTEXT: Adjacent tasks and phase goal (for constraint awareness)
+- REPAIR_BUDGET: Max repair attempts remaining (default: 2)
+</inputs>
+
+<repair_directive>
+Analyze the failure and choose exactly one repair strategy:
+
+**RETRY** — The approach was right but execution failed. Try again with a concrete adjustment.
+- Use when: command error, missing dependency, wrong path, env issue, transient failure
+- Output: `RETRY: [specific adjustment to make before retrying]`
+
+**DECOMPOSE** — The task is too coarse. Break it into smaller verifiable sub-steps.
+- Use when: done-criteria covers multiple concerns, implementation gaps are structural
+- Output: `DECOMPOSE: [sub-task 1] | [sub-task 2] | ...` (max 3 sub-tasks)
+- Sub-tasks must each have a single verifiable outcome
+
+**PRUNE** — The task is infeasible given current constraints. Skip with justification.
+- Use when: prerequisite missing and not fixable here, out of scope, contradicts an earlier decision
+- Output: `PRUNE: [one-sentence justification]`
+
+**ESCALATE** — Repair budget exhausted, or this is an architectural decision (Rule 4).
+- Use when: RETRY failed more than once with different approaches, or fix requires structural change
+- Output: `ESCALATE: [what was tried] | [what decision is needed]`
+</repair_directive>
+
+<process>
+
+<step name="diagnose">
+Read the error and done-criteria carefully. Ask:
+1. Is this a transient/environmental issue? → RETRY
+2. Is the task verifiably too broad? → DECOMPOSE
+3. Is a prerequisite genuinely missing and unfixable in scope? → PRUNE
+4. Has RETRY already been attempted with this task? Check REPAIR_BUDGET. If 0 → ESCALATE
+</step>
+
+<step name="execute_retry">
+If RETRY:
+1. Apply the specific adjustment stated in the directive
+2. Re-run the task implementation
+3. Re-run verification
+4. If passes → continue normally, log `[Node Repair - RETRY] Task [X]: [adjustment made]`
+5. If fails again → decrement REPAIR_BUDGET, re-invoke node-repair with updated context
+</step>
+
+<step name="execute_decompose">
+If DECOMPOSE:
+1. Replace the failed task inline with the sub-tasks (do not modify PLAN.md on disk)
+2. Execute sub-tasks sequentially, each with its own verification
+3. If all sub-tasks pass → treat original task as succeeded, log `[Node Repair - DECOMPOSE] Task [X] → [N] sub-tasks`
+4. If a sub-task fails → re-invoke node-repair for that sub-task (REPAIR_BUDGET applies per sub-task)
+</step>
+
+<step name="execute_prune">
+If PRUNE:
+1. Mark task as skipped with justification
+2. Log to SUMMARY "Issues Encountered": `[Node Repair - PRUNE] Task [X]: [justification]`
+3. Continue to next task
+</step>
+
+<step name="execute_escalate">
+If ESCALATE:
+1. Surface to user via verification_failure_gate with full repair history
+2. Present: what was tried (each RETRY/DECOMPOSE attempt), what the blocker is, options available
+3. Wait for user direction before continuing
+</step>
+
+</process>
+
+<logging>
+All repair actions must appear in SUMMARY.md under "## Deviations from Plan":
+
+| Type | Format |
+|------|--------|
+| RETRY success | `[Node Repair - RETRY] Task X: [adjustment] — resolved` |
+| RETRY fail → ESCALATE | `[Node Repair - RETRY] Task X: [N] attempts exhausted — escalated to user` |
+| DECOMPOSE | `[Node Repair - DECOMPOSE] Task X split into [N] sub-tasks — all passed` |
+| PRUNE | `[Node Repair - PRUNE] Task X skipped: [justification]` |
+</logging>
+
+<constraints>
+- REPAIR_BUDGET defaults to 2 per task. Configurable via config.json `workflow.node_repair_budget`.
+- Never modify PLAN.md on disk — decomposed sub-tasks are in-memory only.
+- DECOMPOSE sub-tasks must be more specific than the original, not synonymous rewrites.
+- If config.json `workflow.node_repair` is `false`, skip directly to verification_failure_gate (user retains original behavior).
+</constraints>

package/get-shit-done/workflows/note.md

@@ -0,0 +1,156 @@
+<purpose>
+Zero-friction idea capture. One Write call, one confirmation line. No questions, no prompts.
+Runs inline — no Task, no AskUserQuestion, no Bash.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="storage_format">
+**Note storage format.**
+
+Notes are stored as individual markdown files:
+
+- **Project scope**: `.planning/notes/{YYYY-MM-DD}-{slug}.md` — used when `.planning/` exists in cwd
+- **Global scope**: `~/.claude/notes/{YYYY-MM-DD}-{slug}.md` — fallback when no `.planning/`, or when `--global` flag is present
+
+Each note file:
+
+```markdown
+---
+date: "YYYY-MM-DD HH:mm"
+promoted: false
+---
+
+{note text verbatim}
+```
+
+**`--global` flag**: Strip `--global` from anywhere in `$ARGUMENTS` before parsing. When present, force global scope regardless of whether `.planning/` exists.
+
+**Important**: Do NOT create `.planning/` if it doesn't exist. Fall back to global scope silently.
+</step>
+
+<step name="parse_subcommand">
+**Parse subcommand from $ARGUMENTS (after stripping --global).**
+
+| Condition | Subcommand |
+|-----------|------------|
+| Arguments are exactly `list` (case-insensitive) | **list** |
+| Arguments are exactly `promote <N>` where N is a number | **promote** |
+| Arguments are empty (no text at all) | **list** |
+| Anything else | **append** (the text IS the note) |
+
+**Critical**: `list` is only a subcommand when it's the ENTIRE argument. `/gsd:note list of groceries` saves a note with text "list of groceries". Same for `promote` — only a subcommand when followed by exactly one number.
+</step>
+
+<step name="append">
+**Subcommand: append — create a timestamped note file.**
+
+1. Determine scope (project or global) per storage format above
+2. Ensure the notes directory exists (`.planning/notes/` or `~/.claude/notes/`)
+3. Generate slug: first ~4 meaningful words of the note text, lowercase, hyphen-separated (strip articles/prepositions from the start)
+4. Generate filename: `{YYYY-MM-DD}-{slug}.md`
+   - If a file with that name already exists, append `-2`, `-3`, etc.
+5. Write the file with frontmatter and note text (see storage format)
+6. Confirm with exactly one line: `Noted ({scope}): {note text}`
+   - Where `{scope}` is "project" or "global"
+
+**Constraints:**
+- **Never modify the note text** — capture verbatim, including typos
+- **Never ask questions** — just write and confirm
+- **Timestamp format**: Use local time, `YYYY-MM-DD HH:mm` (24-hour, no seconds)
+</step>
+
+<step name="list">
+**Subcommand: list — show notes from both scopes.**
+
+1. Glob `.planning/notes/*.md` (if directory exists) — project notes
+2. Glob `~/.claude/notes/*.md` (if directory exists) — global notes
+3. For each file, read frontmatter to get `date` and `promoted` status
+4. Exclude files where `promoted: true` from active counts (but still show them, dimmed)
+5. Sort by date, number all active entries sequentially starting at 1
+6. If total active entries > 20, show only the last 10 with a note about how many were omitted
+
+**Display format:**
+
+```
+Notes:
+
+Project (.planning/notes/):
+  1. [2026-02-08 14:32] refactor the hook system to support async validators
+  2. [promoted] [2026-02-08 14:40] add rate limiting to the API endpoints
+  3. [2026-02-08 15:10] consider adding a --dry-run flag to build
+
+Global (~/.claude/notes/):
+  4. [2026-02-08 10:00] cross-project idea about shared config
+
+{count} active note(s). Use `/gsd:note promote <N>` to convert to a todo.
+```
+
+If a scope has no directory or no entries, show: `(no notes)`
+</step>
+
+<step name="promote">
+**Subcommand: promote — convert a note into a todo.**
+
+1. Run the **list** logic to build the numbered index (both scopes)
+2. Find entry N from the numbered list
+3. If N is invalid or refers to an already-promoted note, tell the user and stop
+4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a GSD project. Run `/gsd:new-project` to initialize one."
+5. Ensure `.planning/todos/pending/` directory exists
+6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text
+7. Extract the note text from the source file (body after frontmatter)
+8. Create `.planning/todos/pending/{id}.md`:
+
+```yaml
+---
+title: "{note text}"
+status: pending
+priority: P2
+source: "promoted from /gsd:note"
+created: {YYYY-MM-DD}
+theme: general
+---
+
+## Goal
+
+{note text}
+
+## Context
+
+Promoted from quick note captured on {original date}.
+
+## Acceptance Criteria
+
+- [ ] {primary criterion derived from note text}
+```
+
+9. Mark the source note file as promoted: update its frontmatter to `promoted: true`
+10. Confirm: `Promoted note {N} to todo {id}: {note text}`
+</step>
+
+</process>
+
+<edge_cases>
+1. **"list" as note text**: `/gsd:note list of things` saves note "list of things" (subcommand only when `list` is the entire arg)
+2. **No `.planning/`**: Falls back to global `~/.claude/notes/` — works in any directory
+3. **Promote without project**: Warns that todos require `.planning/`, suggests `/gsd:new-project`
+4. **Large files**: `list` shows last 10 when >20 active entries
+5. **Duplicate slugs**: Append `-2`, `-3` etc. to filename if slug already used on same date
+6. **`--global` position**: Stripped from anywhere — `--global my idea` and `my idea --global` both save "my idea" globally
+7. **Promote already-promoted**: Tell user "Note {N} is already promoted" and stop
+8. **Empty note text after stripping flags**: Treat as `list` subcommand
+</edge_cases>
+
+<success_criteria>
+- [ ] Append: Note file written with correct frontmatter and verbatim text
+- [ ] Append: No questions asked — instant capture
+- [ ] List: Both scopes shown with sequential numbering
+- [ ] List: Promoted notes shown but dimmed
+- [ ] Promote: Todo created with correct format
+- [ ] Promote: Source note marked as promoted
+- [ ] Global fallback: Works when no `.planning/` exists
+</success_criteria>