@hanzlaa/rcode 3.6.16 → 4.0.0

package/rcode/workflows/ship.md

@@ -0,0 +1,284 @@
+<purpose>
+Push a verified feature branch and open a pull request with an auto-generated
+body drawn from planning artifacts (ROADMAP, VERIFICATION, SUMMARY). Closes
+the plan → execute → verify → **ship** loop.
+
+**What this command does:**
+1. Runs preflight: clean tree, on a feature branch, VERIFICATION.md passed, gh CLI authenticated
+2. Pushes the branch to origin
+3. Generates a rich PR body — phase goal, list of changes, requirements addressed, verification status
+4. Creates the PR via `gh pr create`
+5. Optionally requests a reviewer
+6. Updates STATE.md with shipping status
+
+**Preconditions (all must be true before running):**
+- `/rcode-execute <phase>` completed
+- `/rcode-verify-phase <phase>` passed (VERIFICATION.md exists with `status: passed`)
+- You are on a feature branch (not main/develop directly)
+- `gh` CLI is authenticated (`gh auth status`)
+
+@.rcode/references/karpathy-guidelines.md
+
+**This command is NOT for:**
+- Publishing npm packages → use `npm publish`
+- Creating git release tags → use `git tag -a vX.Y.Z && git push --tags`
+- Repos that commit directly to main (`git.branching_strategy: none`)
+- The rcode framework repo itself (no phases exist there)
+
+**Typical usage:**
+```
+/rcode-plan 1          → plan the phase
+/rcode-execute 1       → build it
+/rcode-verify-phase 1  → prove it works
+/rcode-ship 1          → PR it ← you are here
+```
+</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=$(node ".rcode/bin/rcode-tools.cjs" init phase-op "${PHASE_ARG}" 2>/dev/null)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+If `INIT` is empty or `INIT.ok` is false, print error and exit:
+```
+Error: rcode-tools init failed. Verify .rcode/ is installed and state.json is valid.
+```
+
+Parse from init JSON: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `commit_docs`.
+
+Also load config for branching strategy:
+```bash
+CONFIG=$(node ".rcode/bin/rcode-tools.cjs" state load)
+```
+
+Extract: `branching_strategy`, `branch_name`.
+
+Detect base branch for PRs and merges:
+```bash
+BASE_BRANCH=$(node ".rcode/bin/rcode-tools.cjs" 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.
+
+   **If running in a git worktree** (`.git` is a file, not a directory): remotes are shared with the main repo. Run `git remote -v` from the main repo root to confirm — if the main repo has `origin`, run `git remote add origin <url>` in the worktree context or add the remote in the main repo, then retry `/rcode-ship`.
+
+   **If not in a worktree:** Run `git remote add origin <url>` to add a remote, then retry `/rcode-ship`.
+
+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">
+Ask if user wants to trigger a code review:
+
+```
+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
+node ".rcode/bin/rcode-tools.cjs" state update "Last Activity" "$(date +%Y-%m-%d)"
+node ".rcode/bin/rcode-tools.cjs" state update "Status" "Phase ${PHASE_NUMBER} shipped — PR #${PR_NUMBER}"
+```
+
+If `commit_docs` is true:
+```bash
+node ".rcode/bin/rcode-tools.cjs" commit "docs(${padded_phase}): ship phase ${PHASE_NUMBER} — PR #${PR_NUMBER}" --files .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
+- /rcode-complete-milestone (if last phase in milestone)
+- /rcode-progress (to see what's next)
+
+───────────────────────────────────────────────────────────────
+```
+</step>
+
+</process>
+
+<offer_next>
+After shipping:
+
+- /rcode-complete-milestone — if all phases in milestone are done
+- /rcode-progress — see overall project state
+- /rcode-execute {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>
+
+## Next Up
+
+- `/rcode-complete-milestone` — mark the milestone done if all phases are now shipped
+- `/rcode-execute` — continue to the next phase after shipping this one
+- `/rcode-progress` — check overall project state after the PR is merged

package/rcode/workflows/show.md

@@ -0,0 +1,74 @@
+<purpose>
+Print a specific SPRINT.md file or all plans in a phase, with execution status from state.json.
+</purpose>
+
+## Step 0: Usage Check
+
+Verify argument was provided:
+- If empty: `Usage: /rcode-show <phase-id|plan-id> (e.g., /rcode-show 01 or /rcode-show 01-01)`
+- Proceed to Step 1
+
+## Step 1: Resolve ID
+
+Run: `node .rcode/bin/rcode-tools.cjs state resolve-id "$ARGUMENTS"`
+
+Expected output:
+```json
+{
+  "type": "phase" | "plan" | "unknown",
+  "id": "01" | "01-01",
+  "path": "/full/path/to/dir-or-file"
+}
+```
+
+If `type === "unknown"`: Return error `ID not found: $ARGUMENTS. Try /rcode-show 01 for phase, 01-01 for specific plan.`
+
+## Step 2: Phase or Plan?
+
+If `type === "phase"`:
+- Walk `.planning/phases/{phase-dir}/` for all `*.md` files matching `[0-9]{2}-[0-9]{2}-SPRINT.md`
+- Read each SPRINT.md frontmatter + body
+- Continue to Step 3
+
+If `type === "plan"`:
+- Read the single SPRINT.md at `{path}/SPRINT.md`
+- Continue to Step 3
+
+## Step 3: Display with Status
+
+For each SPRINT.md:
+
+1. Print frontmatter as YAML block (title, wave, description)
+2. Print body in full
+3. Read `.rcode/state.json` and extract `executions[].plan_id` matching this plan
+4. If found, append:
+   ```
+   Last execution: {timestamp}, {duration_ms}ms, commit {commit_sha}
+   ```
+   If not found: `Status: Not yet executed`
+
+Separate multiple plans with `---\n`
+
+## Success Criteria
+
+- [ ] ID resolves correctly
+- [ ] Full SPRINT.md content displayed (frontmatter + body)
+- [ ] Execution status appended
+- [ ] Multiple plans separated cleanly
+
+## On Error
+
+- ID unresolvable → Show resolve-id error message
+- SPRINT.md missing → "File not found: {path}"
+- state.json corrupt → Omit execution status, continue
+
+## On Completion
+
+/rcode-execute {phase} — execute this phase
+/rcode-plan {phase} — revise the plan
+/rcode-progress — see full roadmap
+
+## Next Up
+
+- `/rcode-execute` — execute the displayed phase plan
+- `/rcode-plan` — revise the plan if it needs changes before execution

package/rcode/workflows/sprint-planning.md

@@ -0,0 +1,208 @@
+# Workflow: rcode-sprint-planning
+
+<purpose>
+Plan the next sprint. Authoritative implementation lives in the
+`rcode-sprint-planning` skill — this workflow delegates to it so every
+safety rail (capacity gate per #127, halt-at-menu per #124, state-sync
+per #198) fires identically whether the user invokes the slash command
+or the phrase-activated skill.
+
+The skill MUST be loaded before the in-line steps below run. If the skill
+file is missing (broken install), report and stop — do not silently fall
+back to the in-line implementation.
+</purpose>
+
+<delegate_to_skill>
+Required skill: `rcode-sprint-planning`
+Path:           `.claude/skills/rcode-sprint-planning/SKILL.md`
+Workflow ref:   `.claude/skills/rcode-sprint-planning/workflow.md`
+
+Behaviour:
+1. Load the skill's `SKILL.md` and `workflow.md`. Apply every Critical
+   Rule from the workflow's `## CRITICAL RULES (NO EXCEPTIONS)` block,
+   including the capacity gate (step n="0") which MUST halt for
+   numeric capacity inputs before any story is committed.
+2. Run the skill's step files in order. The in-line steps below this
+   block are a fallback summary for legacy installs that lack the skill;
+   they are NOT the authoritative behaviour.
+3. After SPRINT.md is written, ALWAYS run:
+   `node .rcode/bin/rcode-tools.cjs state sync --from-disk`
+   so state.sprints[] reflects the new sprint.
+
+If skill files are missing: print
+"Sprint-planning skill not installed. Run: npx @hanzlaa/rcode install"
+and exit non-zero. Do not proceed with the legacy in-line steps because
+they bypass the capacity gate.
+</delegate_to_skill>
+
+<required_reading>
+@.rcode/references/output-format.md
+@.rcode/brain/best-practices/no-autonomous-bypass.md
+@.rcode/brain/best-practices/state-sync-rule.md
+@.rcode/references/karpathy-guidelines.md
+</required_reading>
+
+<output_format>
+Open with banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► PLANNING SPRINT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+TaskCreate: "Load phase scope + velocity", "Capacity gate (halt for numbers)", "Curate stories with user", "Register sprint + stories in state", "Write SPRINT.md", "Sync state", "Start sprint".
+Closure: `rcode ► SPRINT {NN.S} READY ✓ ({N} stories, {M} points)`
+Next Up: `/rcode-execute .planning/phases/{phase}/SPRINT.md`
+</output_format>
+
+<process>
+## Step 0 — Usage check
+
+If `$ARGUMENTS` contains `--help` or `-h`:
+
+```
+/rcode-sprint-planning [--phase <NN>] [--velocity <points>] [--goal "Sprint goal"]
+```
+
+**Examples:**
+```
+/rcode-sprint-planning
+/rcode-sprint-planning --phase 01 --goal "Auth system MVP"
+/rcode-sprint-planning --velocity 13
+```
+
+STOP — do not proceed.
+
+## Step 1 — Load context
+
+```bash
+STATE=$(node .rcode/bin/rcode-tools.cjs state read)
+VELOCITY=$(node .rcode/bin/rcode-tools.cjs state sprint velocity)
+```
+
+Extract:
+- Current phase from state
+- Velocity history + average from velocity output
+- Phase scope from `.planning/phases/{phase}/REQUIREMENTS.md` (preferred) or `SCOPE.md` (legacy alias) — both are acceptable; REQUIREMENTS.md is the file created by the standard planning pipeline
+
+If no phases in state:
+```
+No phases found. If you have a ROADMAP.md, sync state first:
+  node .rcode/bin/rcode-tools.cjs state sync --from-disk
+Otherwise run /rcode-new-project first to create a roadmap.
+```
+Exit.
+
+## Step 2 — Determine capacity
+
+**If velocity history exists:**
+- Use rolling 3-sprint average as capacity baseline
+- Commit max 80% of average (buffer for interrupts + unknowns)
+
+**If no velocity history (first sprint):**
+- Ask user: "This is your first sprint. How many story points can you commit to? (Typical: 8-13 for solo dev + AI)"
+- Or use `--velocity` flag
+
+Store as `velocity_target`.
+
+## Step 3 — Curate stories
+
+Read phase scope (REQUIREMENTS.md preferred, fall back to SCOPE.md or the ROADMAP.md phase section).
+
+For each requirement/feature in scope:
+1. Break into stories: `As a [user], I want [action] so that [outcome]`
+2. Estimate: XS(1) / S(2) / M(3) / L(5) / XL(8)
+3. Stories > 8 points → split immediately
+4. Prioritize: must-have first, nice-to-have last
+
+Present story table to user:
+
+```markdown
+| # | Story | Points | Priority | Acceptance |
+|---|-------|--------|----------|------------|
+| 1 | Login endpoint | 5 | must | Returns JWT on valid creds |
+| 2 | Register endpoint | 3 | must | Creates user, hashes password |
+| 3 | Rate limiting | 2 | should | 429 after 10 req/min |
+```
+
+**Capacity check:** Total committed points <= velocity_target.
+If over: "We're at {N} points vs {target} capacity. Move story #{X} to next sprint?"
+
+Wait for user confirmation before proceeding.
+
+## Step 4 — Create sprint
+
+After user confirms stories:
+
+```bash
+# Register sprint in state
+node .rcode/bin/rcode-tools.cjs state sprint add \
+  --phase "{phase_name}" \
+  --goal "{sprint_goal}" \
+  --velocity {velocity_target}
+
+# Register each story
+node .rcode/bin/rcode-tools.cjs state story add \
+  --title "{story_title}" \
+  --points {points}
+```
+
+Write SPRINT.md to `.planning/phases/{phase_slug}/SPRINT.md`. Use `.rcode/templates/sprint.md` as a template if it exists; otherwise produce the file inline with these sections (the template file may be absent in this install). Fill in:
+- Sprint goal
+- Stories table (from user-confirmed list)
+- Capacity section (velocity target, average, buffer)
+- Dependencies
+- Risks (if identified during estimation)
+
+## Step 5 — Start sprint
+
+```bash
+# Extract the sprint id written by state sprint add in Step 4 (format: NN.S, e.g. "1.1")
+node .rcode/bin/rcode-tools.cjs state sprint start --sprint "{sprint_id}"
+```
+
+If `sprint_id` is unavailable, omit the flag — the tool will attempt to start the most recently added sprint. The `--sprint NN.S` flag is required when no sprint is marked active.
+
+## Step 6 — Summary
+
+```
+Sprint {sprint_id} created and started.
+
+Goal: {sprint_goal}
+Stories: {count} ({total_points} points)
+Capacity: {velocity_target} points ({buffer}% buffer)
+
+Next:
+  /rcode-execute .planning/phases/{phase}/SPRINT.md   ← execute the sprint
+  /rcode-sprint-status                                ← check progress anytime
+```
+
+## Output Format
+
+- SPRINT.md at `.planning/phases/{phase_slug}/SPRINT.md`
+- Sprint + stories registered in `.rcode/state.json`
+- Console summary with next-step commands
+
+## Examples
+
+### Happy Path
+**Input:** `/rcode-sprint-planning --phase 01 --goal "Auth MVP"`
+**Expected:** Load phase scope, estimate stories, present table, confirm, create SPRINT.md + register in state, start sprint.
+
+### Edge Case: Over capacity
+**Input:** 15 points of stories but velocity avg is 10
+**Expected:** Flag over-commitment, suggest deferring lowest-priority story.
+
+### Edge Case: No scope
+**Input:** Phase has no SCOPE.md or requirements
+**Expected:** "No scope found for this phase. Run /rcode-new-project or write a SCOPE.md first."
+
+### Negative Test
+**Input:** `/rcode-sprint-planning` with no phases in state
+**Expected:** Graceful exit suggesting /rcode-new-project.
+
+</process>
+
+## Next Up
+
+- `/rcode-execute-sprint` — execute the planned sprint
+- `/rcode-sprint-status` — check sprint progress during execution

package/rcode/workflows/sprint-status.md

@@ -0,0 +1,129 @@
+# Workflow: rcode-sprint-status
+
+<purpose>
+Display current sprint progress: stories by status, points done vs remaining, velocity comparison, and burndown. Quick situational awareness without starting execution.
+</purpose>
+
+<output_format>
+Open with banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► SPRINT {NN.S} STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+Use status symbols (✓ done, ◆ in_progress, ○ todo) in story board.
+Show sprint progress bar: `Sprint 01.1: 8/13 points ████████░░░░░ 61%`.
+Show velocity line: `Velocity: avg 11 pts (last 3 sprints)`.
+End with Next Up routing based on sprint state.
+</output_format>
+
+<required_reading>
+@.rcode/references/output-format.md
+</required_reading>
+
+<process>
+## Step 0 — Usage check
+
+If `$ARGUMENTS` contains `--help` or `-h`:
+
+```
+/rcode-sprint-status [--sprint <NN.S>]
+```
+
+**Examples:**
+```
+/rcode-sprint-status              # current sprint
+/rcode-sprint-status --sprint 01.2
+```
+
+STOP — do not proceed.
+
+## Step 1 — Load sprint data
+
+```bash
+SPRINT_STATUS=$(node .rcode/bin/rcode-tools.cjs state sprint status 2>/dev/null || echo "")
+VELOCITY=$(node .rcode/bin/rcode-tools.cjs state sprint velocity 2>/dev/null || echo "0")
+STORIES=$(node .rcode/bin/rcode-tools.cjs state story list 2>/dev/null || echo "")
+```
+
+If `SPRINT_STATUS` is empty:
+```
+No active sprint. Run /rcode-sprint-planning to create one.
+```
+Exit.
+
+## Step 2 — Display
+
+Print a compact status board:
+
+```
+Sprint {sprint_id} — {goal}
+Status: {active|planned|completed}
+
+Stories                         Points
+  todo:        {n}              done:      {done_pts}/{total_pts}
+  in_progress: {n}              remaining: {rem_pts}
+  review:      {n}              target:    {velocity_target}
+  done:        {n}
+  ────────────                  ────────────
+  total:       {total}          progress:  {pct}%
+
+Velocity
+  This sprint: {velocity_actual or "in progress"}
+  Average:     {avg_velocity} (last {sprint_count} sprints)
+  Trend:       {up/down/stable}
+```
+
+## Step 3 — Story board
+
+Show stories grouped by status:
+
+```
+IN PROGRESS
+  {id} {title} ({points}pts)
+
+TODO
+  {id} {title} ({points}pts)
+
+DONE
+  {id} {title} ({points}pts) ✓
+
+REVIEW
+  {id} {title} ({points}pts)
+```
+
+## Step 4 — Recommendations
+
+Based on data, suggest next action:
+
+- **All stories done:** "Sprint ready to close. Run `/rcode-sprint-planning` for next sprint."
+- **In progress stories exist:** "Continue executing. Run `/rcode-execute` to pick up next story."
+- **Over capacity (committed > velocity avg):** "Over-committed by {N} points. Consider deferring lowest-priority story."
+- **No stories moved today:** "No progress since last check. Blockers?"
+
+## Output Format
+
+- Compact terminal-friendly status board (no markdown tables, just aligned text)
+- Story board grouped by status
+- One-line recommendation with actionable command
+
+## Examples
+
+### Happy Path
+**Input:** `/rcode-sprint-status`
+**Expected:** Board showing 3 done / 1 in_progress / 2 todo, 8/13 points, velocity trend stable.
+
+### Edge Case: No sprint
+**Input:** `/rcode-sprint-status` (no active sprint)
+**Expected:** "No active sprint" + suggestion to run sprint-planning.
+
+### Negative Test
+**Input:** `/rcode-sprint-status --sprint 99.9`
+**Expected:** "Sprint 99.9 not found."
+
+</process>
+
+## Next Up
+
+- `/rcode-execute-sprint` — continue sprint execution
+- `/rcode-do` — take action on blocked or at-risk stories