gsd-remix 1.0.0

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

@@ -0,0 +1,302 @@
+<purpose>
+Create a pull request from completed phase/milestone work, generate a rich PR body from planning artifacts, optionally run code review, and prepare for merge. Closes the plan → execute → verify → ship loop.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="initialize">
+Parse arguments and load project state:
+
+```bash
+INIT=$(gsd-remix-sdk query init.phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse from init JSON: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `commit_docs`.
+
+Also load config for branching strategy:
+```bash
+CONFIG=$(gsd-remix-sdk query state.load)
+```
+
+Extract: `branching_strategy`, `branch_name`.
+
+Detect base branch for PRs and merges:
+```bash
+BASE_BRANCH=$(gsd-remix-sdk query config-get git.base_branch 2>/dev/null || echo "")
+if [ -z "$BASE_BRANCH" ] || [ "$BASE_BRANCH" = "null" ]; then
+  BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||')
+  BASE_BRANCH="${BASE_BRANCH:-main}"
+fi
+```
+</step>
+
+<step name="preflight_checks">
+Verify the work is ready to ship:
+
+1. **Verification passed?**
+   ```bash
+   VERIFICATION=$(cat ${PHASE_DIR}/*-VERIFICATION.md 2>/dev/null)
+   ```
+   Check for `status: passed` or `status: human_needed` (with human approval).
+   If no VERIFICATION.md or status is `gaps_found`: warn and ask user to confirm.
+
+2. **Clean working tree?**
+   ```bash
+   git status --short
+   ```
+   If uncommitted changes exist: ask user to commit or stash first.
+
+3. **On correct branch?**
+   ```bash
+   CURRENT_BRANCH=$(git branch --show-current)
+   ```
+   If on `${BASE_BRANCH}`: warn — should be on a feature branch.
+   If branching_strategy is `none`: offer to create a branch now.
+
+4. **Remote configured?**
+   ```bash
+   git remote -v | head -2
+   ```
+   Detect `origin` remote. If no remote: error — can't create PR.
+
+5. **`gh` CLI available?**
+   ```bash
+   which gh && gh auth status 2>&1
+   ```
+   If `gh` not found or not authenticated: provide setup instructions and exit.
+</step>
+
+<step name="push_branch">
+Push the current branch to remote:
+
+```bash
+git push origin ${CURRENT_BRANCH} 2>&1
+```
+
+If push fails (e.g., no upstream): set upstream:
+```bash
+git push --set-upstream origin ${CURRENT_BRANCH} 2>&1
+```
+
+Report: "Pushed `{branch}` to origin ({commit_count} commits ahead of ${BASE_BRANCH})"
+</step>
+
+<step name="generate_pr_body">
+Auto-generate a rich PR body from planning artifacts:
+
+**1. Title:**
+```
+Phase {phase_number}: {phase_name}
+```
+Or for milestone: `Milestone {version}: {name}`
+
+**2. Summary section:**
+Read ROADMAP.md for phase goal. Read VERIFICATION.md for verification status.
+
+```markdown
+## Summary
+
+**Phase {N}: {Name}**
+**Goal:** {goal from ROADMAP.md}
+**Status:** Verified ✓
+
+{One paragraph synthesized from SUMMARY.md files — what was built}
+```
+
+**3. Changes section:**
+For each SUMMARY.md in the phase directory:
+```markdown
+## Changes
+
+### Plan {plan_id}: {plan_name}
+{one_liner from SUMMARY.md frontmatter}
+
+**Key files:**
+{key-files.created and key-files.modified from SUMMARY.md frontmatter}
+```
+
+**4. Requirements section:**
+```markdown
+## Requirements Addressed
+
+{REQ-IDs from plan frontmatter, linked to REQUIREMENTS.md descriptions}
+```
+
+**5. Testing section:**
+```markdown
+## Verification
+
+- [x] Automated verification: {pass/fail from VERIFICATION.md}
+- {human verification items from VERIFICATION.md, if any}
+```
+
+**6. Decisions section:**
+```markdown
+## Key Decisions
+
+{Decisions from STATE.md accumulated context relevant to this phase}
+```
+</step>
+
+<step name="create_pr">
+Create the PR using the generated body:
+
+```bash
+gh pr create \
+  --title "Phase ${PHASE_NUMBER}: ${PHASE_NAME}" \
+  --body "${PR_BODY}" \
+  --base ${BASE_BRANCH}
+```
+
+If `--draft` flag was passed: add `--draft`.
+
+Report: "PR #{number} created: {url}"
+</step>
+
+<step name="optional_review">
+
+**External code review command (automated sub-step):**
+
+Before prompting the user, check if an external review command is configured:
+
+```bash
+REVIEW_CMD=$(gsd-remix-sdk query config-get workflow.code_review_command 2>/dev/null | jq -r '.' 2>/dev/null || echo "")
+```
+
+If `REVIEW_CMD` is non-empty and not `"null"`, run the external review:
+
+1. **Generate diff and stats:**
+   ```bash
+   DIFF=$(git diff ${BASE_BRANCH}...HEAD)
+   DIFF_STATS=$(git diff --stat ${BASE_BRANCH}...HEAD)
+   ```
+
+2. **Load phase context from STATE.md:**
+   ```bash
+   STATE_STATUS=$(gsd-remix-sdk query state.load 2>/dev/null | head -20)
+   ```
+
+3. **Build review prompt and pipe to command via stdin:**
+   Construct a review prompt containing the diff, diff stats, and phase context, then pipe it to the configured command:
+   ```bash
+   REVIEW_PROMPT="You are reviewing a pull request.\n\nDiff stats:\n${DIFF_STATS}\n\nPhase context:\n${STATE_STATUS}\n\nFull diff:\n${DIFF}\n\nRespond with JSON: { \"verdict\": \"APPROVED\" or \"REVISE\", \"confidence\": 0-100, \"summary\": \"...\", \"issues\": [{\"severity\": \"...\", \"file\": \"...\", \"line_range\": \"...\", \"description\": \"...\", \"suggestion\": \"...\"}] }"
+   REVIEW_OUTPUT=$(echo "${REVIEW_PROMPT}" | timeout 120 ${REVIEW_CMD} 2>/tmp/gsd-review-stderr.log)
+   REVIEW_EXIT=$?
+   ```
+
+4. **Handle timeout (120s) and failure:**
+   If `REVIEW_EXIT` is non-zero or the command times out:
+   ```bash
+   if [ $REVIEW_EXIT -ne 0 ]; then
+     REVIEW_STDERR=$(cat /tmp/gsd-review-stderr.log 2>/dev/null)
+     echo "WARNING: External review command failed (exit ${REVIEW_EXIT}). stderr: ${REVIEW_STDERR}"
+     echo "Continuing with manual review flow..."
+   fi
+   ```
+   On failure, warn with stderr output and fall through to the manual review flow below.
+
+5. **Parse JSON result:**
+   If the command succeeded, parse the JSON output and report the verdict:
+   ```bash
+   # Parse verdict and summary from REVIEW_OUTPUT JSON
+   VERDICT=$(echo "${REVIEW_OUTPUT}" | node -e "
+     let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>{
+       try { const r=JSON.parse(d); console.log(r.verdict); }
+       catch(e) { console.log('INVALID_JSON'); }
+     });
+   ")
+   ```
+   - If `verdict` is `"APPROVED"`: report approval with confidence and summary.
+   - If `verdict` is `"REVISE"`: report issues found, list each issue with severity, file, line_range, description, and suggestion.
+   - If JSON is invalid (`INVALID_JSON`): warn "External review returned invalid JSON" with stderr and continue.
+
+   Regardless of the external review result, fall through to the manual review options below.
+
+---
+
+**Manual review options:**
+
+Ask if user wants to trigger a code review:
+
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+
+```
+AskUserQuestion:
+  question: "PR created. Run a code review before merge?"
+  options:
+    - label: "Skip review"
+      description: "PR is ready — merge when CI passes"
+    - label: "Self-review"
+      description: "I'll review the diff in the PR myself"
+    - label: "Request review"
+      description: "Request review from a teammate"
+```
+
+**If "Request review":**
+```bash
+gh pr edit ${PR_NUMBER} --add-reviewer "${REVIEWER}"
+```
+
+**If "Self-review":**
+Report the PR URL and suggest: "Review the diff at {url}/files"
+</step>
+
+<step name="track_shipping">
+Update STATE.md to reflect the shipping action:
+
+```bash
+gsd-remix-sdk query state.update "Last Activity" "$(date +%Y-%m-%d)"
+gsd-remix-sdk query state.update "Status" "Phase ${PHASE_NUMBER} shipped — PR #${PR_NUMBER}"
+```
+
+If `commit_docs` is true:
+```bash
+gsd-remix-sdk query commit "docs(${padded_phase}): ship phase ${PHASE_NUMBER} — PR #${PR_NUMBER}" .planning/STATE.md
+```
+</step>
+
+<step name="report">
+```
+───────────────────────────────────────────────────────────────
+
+## ✓ Phase {X}: {Name} — Shipped
+
+PR: #{number} ({url})
+Branch: {branch} → ${BASE_BRANCH}
+Commits: {count}
+Verification: ✓ Passed
+Requirements: {N} REQ-IDs addressed
+
+Next steps:
+- Review/approve PR
+- Merge when CI passes
+- /gsd-complete-milestone (if last phase in milestone)
+- /gsd-progress (to see what's next)
+
+───────────────────────────────────────────────────────────────
+```
+</step>
+
+</process>
+
+<offer_next>
+After shipping:
+
+- /gsd-complete-milestone — if all phases in milestone are done
+- /gsd-progress — see overall project state
+- /gsd-execute-phase {next} — continue to next phase
+</offer_next>
+
+<success_criteria>
+- [ ] Preflight checks passed (verification, clean tree, branch, remote, gh)
+- [ ] Branch pushed to remote
+- [ ] PR created with rich auto-generated body
+- [ ] STATE.md updated with shipping status
+- [ ] User knows PR number and next steps
+</success_criteria>

package/get-shit-done/workflows/sketch-wrap-up.md

@@ -0,0 +1,283 @@
+<purpose>
+Curate sketch design findings and package them into a persistent project skill for future
+UI implementation. Reads from `.planning/sketches/`, writes skill to `./.claude/skills/sketch-findings-[project]/`
+(project-local) and summary to `.planning/sketches/WRAP-UP-SUMMARY.md`.
+Companion to `/gsd-sketch`.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="banner">
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► SKETCH WRAP-UP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</step>
+
+<step name="gather">
+## Gather Sketch Inventory
+
+1. Read `.planning/sketches/MANIFEST.md` for the design direction and reference points
+2. Glob `.planning/sketches/*/README.md` and parse YAML frontmatter from each
+3. Check if `./.claude/skills/sketch-findings-*/SKILL.md` exists for this project
+   - If yes: read its `processed_sketches` list and filter those out
+   - If no: all sketches are candidates
+
+If no unprocessed sketches exist:
+```
+No unprocessed sketches found in `.planning/sketches/`.
+Run `/gsd-sketch` first to create design explorations.
+```
+Exit.
+
+Check `commit_docs` config:
+```bash
+COMMIT_DOCS=$(gsd-remix-sdk query config-get commit_docs 2>/dev/null || echo "true")
+```
+</step>
+
+<step name="curate">
+## Curate Sketches One-at-a-Time
+
+Present each unprocessed sketch in ascending order. For each sketch, show:
+
+- **Sketch number and name**
+- **Design question:** from frontmatter
+- **Winner:** which variant was selected (if any)
+- **Tags:** from frontmatter
+- **Key decisions:** summarize what was decided visually
+
+Then ask the user:
+
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: Decision Required                               ║
+╚══════════════════════════════════════════════════════════════╝
+
+Sketch {NNN}: {name} — Winner: Variant {X}
+
+{key design decisions summary}
+
+──────────────────────────────────────────────────────────────
+→ Include / Exclude / Partial / Let me look at it
+──────────────────────────────────────────────────────────────
+
+**If "Let me look at it":**
+1. Provide: `open .planning/sketches/NNN-name/index.html`
+2. Remind them which variant won and what to look for
+3. After they've looked, return to the include/exclude/partial decision
+
+**If "Partial":**
+Ask what specifically to include or exclude from this sketch's decisions.
+</step>
+
+<step name="group">
+## Auto-Group by Design Area
+
+After all sketches are curated:
+
+1. Read all included sketches' tags, names, and content
+2. Propose design-area groupings, e.g.:
+   - "**Layout & Navigation** — sketches 001, 004"
+   - "**Form Controls** — sketches 002, 005"
+   - "**Color & Typography** — sketches 003"
+3. Present the grouping for approval — user may merge, split, rename, or rearrange
+
+Each group becomes one reference file in the generated skill.
+</step>
+
+<step name="skill_name">
+## Determine Output Skill Name
+
+Derive from the project directory name: `./.claude/skills/sketch-findings-[project-dir-name]/`
+
+If a skill already exists at that path (append mode), update in place.
+</step>
+
+<step name="copy_sources">
+## Copy Source Files
+
+For each included sketch:
+
+1. Copy the winning variant's HTML file (or the full index.html with all variants) into `sources/NNN-sketch-name/`
+2. Copy the winning theme.css into `sources/themes/`
+3. Exclude node_modules, build artifacts, .DS_Store
+</step>
+
+<step name="synthesize">
+## Synthesize Reference Files
+
+For each design-area group, write a reference file at `references/[design-area-name].md`:
+
+```markdown
+# [Design Area Name]
+
+## Design Decisions
+[For each validated decision: what was chosen, why it won over alternatives, the key visual properties (colors, spacing, border radius, typography)]
+
+## CSS Patterns
+[Key CSS snippets from winning variants — layout structures, component patterns, animation patterns. Extracted and cleaned up for reference.]
+
+## HTML Structures
+[Key HTML patterns from winning variants — page layout, component markup, navigation structures.]
+
+## What to Avoid
+[Design directions that were tried and rejected. Why they didn't work.]
+
+## Origin
+Synthesized from sketches: NNN, NNN
+Source files available in: sources/NNN-sketch-name/
+```
+</step>
+
+<step name="write_skill">
+## Write SKILL.md
+
+Create (or update) the generated skill's SKILL.md:
+
+```markdown
+---
+name: sketch-findings-[project-dir-name]
+description: Validated design decisions, CSS patterns, and visual direction from sketch experiments. Auto-loaded during UI implementation on [project-dir-name].
+---
+
+<context>
+## Project: [project-dir-name]
+
+[Design direction paragraph from MANIFEST.md]
+[Reference points mentioned during intake]
+
+Sketch sessions wrapped: [date(s)]
+</context>
+
+<design_direction>
+## Overall Direction
+
+[Summary of the validated visual direction: palette, typography, spacing system, layout approach, interaction patterns]
+</design_direction>
+
+<findings_index>
+## Design Areas
+
+| Area | Reference | Key Decision |
+|------|-----------|--------------|
+| [Name] | references/[name].md | [One-line summary] |
+
+## Theme
+
+The winning theme file is at `sources/themes/default.css`.
+
+## Source Files
+
+Original sketch HTML files are preserved in `sources/` for complete reference.
+</findings_index>
+
+<metadata>
+## Processed Sketches
+
+[List of sketch numbers wrapped up]
+
+- 001-sketch-name
+- 002-sketch-name
+</metadata>
+```
+</step>
+
+<step name="write_summary">
+## Write Planning Summary
+
+Write `.planning/sketches/WRAP-UP-SUMMARY.md` for project history:
+
+```markdown
+# Sketch Wrap-Up Summary
+
+**Date:** [date]
+**Sketches processed:** [count]
+**Design areas:** [list]
+**Skill output:** `./.claude/skills/sketch-findings-[project]/`
+
+## Included Sketches
+| # | Name | Winner | Design Area |
+|---|------|--------|-------------|
+
+## Excluded Sketches
+| # | Name | Reason |
+|---|------|--------|
+
+## Design Direction
+[consolidated design direction summary]
+
+## Key Decisions
+[layout, palette, typography, spacing, interaction patterns]
+```
+</step>
+
+<step name="update_claude_md">
+## Update Project CLAUDE.md
+
+Add an auto-load routing line:
+
+```
+- **Sketch findings for [project]** (design decisions, CSS patterns, visual direction) → `Skill("sketch-findings-[project-dir-name]")`
+```
+
+If this routing line already exists (append mode), leave it as-is.
+</step>
+
+<step name="commit">
+Commit all artifacts (if `COMMIT_DOCS` is true):
+
+```bash
+gsd-remix-sdk query commit "docs(sketch-wrap-up): package [N] sketch findings into project skill" .planning/sketches/WRAP-UP-SUMMARY.md
+```
+</step>
+
+<step name="report">
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► SKETCH WRAP-UP COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Curated:** {N} sketches ({included} included, {excluded} excluded)
+**Design areas:** {list}
+**Skill:** `./.claude/skills/sketch-findings-[project]/`
+**Summary:** `.planning/sketches/WRAP-UP-SUMMARY.md`
+**CLAUDE.md:** routing line added
+
+The sketch-findings skill will auto-load when building the UI.
+```
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Start building** — implement the validated design
+
+`/gsd-plan-phase`
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/gsd-ui-phase` — generate a UI design contract for a frontend phase
+- `/gsd-sketch` — sketch additional design areas
+- `/gsd-explore` — continue exploring
+
+───────────────────────────────────────────────────────────────
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Every unprocessed sketch presented for individual curation
+- [ ] Design-area grouping proposed and approved
+- [ ] Sketch-findings skill exists at `./.claude/skills/` with SKILL.md, references/, sources/
+- [ ] Winning theme.css copied into skill sources
+- [ ] Reference files contain design decisions, CSS patterns, HTML structures, anti-patterns
+- [ ] `.planning/sketches/WRAP-UP-SUMMARY.md` written for project history
+- [ ] Project CLAUDE.md has auto-load routing line
+- [ ] Summary presented with next-step routing
+</success_criteria>