@hanzlaa/rcode 3.6.15 → 4.0.0

package/rcode/templates/projects/api-backend/PROJECT.md

@@ -0,0 +1,37 @@
+# {{project_name}} — API Backend
+
+**Template:** api-backend
+**Created:** {{date}}
+
+## What we're building
+A headless API for {{use_case}}. Consumers are other services, internal apps, or third-party integrations — not end users directly.
+
+## API surface
+- **Protocol:** REST / GraphQL / gRPC — pick one, justify in an ADR
+- **Versioning strategy:** {{versioning}} (URL-prefix vs header vs dated)
+- **Auth:** API keys + scoped tokens
+
+## Primary consumers
+- {{consumer_1}}
+- {{consumer_2}}
+
+## Performance targets
+- p50 latency: {{p50}} · p95: {{p95}} · p99: {{p99}}
+- Throughput: {{rps}} req/s sustained
+- Availability: {{slo}}
+
+## Non-negotiables
+- Every endpoint is idempotent or explicitly documented as non-idempotent
+- Breaking changes ship under a new version — never mutate existing endpoints
+- Errors follow a consistent schema (code, message, request_id)
+
+## Explicitly out of scope
+- Frontend / dashboards (separate project)
+- Self-serve signup UI
+
+## Key risks
+- Scope drift into full-product features → resist
+- Early API shape locks in; expensive to change once consumers integrate
+
+## Evolution
+_(Updated after each phase completion by `/rcode-execute`.)_

package/rcode/templates/projects/api-backend/template.yaml

@@ -0,0 +1,17 @@
+name: api-backend
+display: "API Backend"
+description: "Headless API service — authentication, data model, public API, SDK, docs"
+recommended_modules:
+  - core
+  - execution
+phases:
+  - "01 — Scaffolding (framework, DB, migrations, CI)"
+  - "02 — Auth + API keys"
+  - "03 — Core resources + REST/GraphQL contract"
+  - "04 — Rate limiting + quotas"
+  - "05 — SDK + public docs"
+  - "06 — Observability + SLOs"
+next_steps: |
+  Seeded. Common follow-ups:
+    /rcode-council REST vs GraphQL vs both for this API?
+    /rcode-plan phase 01

package/rcode/templates/projects/mobile-app/PROJECT.md

@@ -0,0 +1,37 @@
+# {{project_name}} — Mobile App
+
+**Template:** mobile-app
+**Created:** {{date}}
+
+## What we're building
+A mobile app for {{target_user}} that solves {{core_problem}}. iOS + Android from day one.
+
+## Target user
+- **Who:** {{user_segment}}
+- **Context of use:** {{context}} (commute, at-desk, on-site, one-handed, etc.)
+- **Device assumptions:** {{device_assumptions}} (min OS, connectivity, battery tolerance)
+
+## Core value loop
+_(Describe the repeatable loop — 2-4 steps — that drives retention.)_
+
+1. {{step_1}}
+2. {{step_2}}
+3. {{step_3}}
+
+## Non-negotiables
+- Works offline for the core action (mobile users drop connectivity often)
+- Respects device permissions — no surprise background GPS, no over-asking
+- Respect platform conventions (iOS HIG, Material 3) before bespoke UX
+
+## Explicitly out of scope
+- Web app in v1
+- Tablet-optimized UI (phone-first)
+- Apple Watch / Wear OS
+
+## Key risks
+- **App Store review:** a single rejection can delay launch by 1-2 weeks; plan for it
+- **Performance on low-end Android:** test on a real <$200 device early
+- **Push opt-in rate:** <30% is common; design core loop to work without push
+
+## Evolution
+_(Updated after each phase completion by `/rcode-execute`.)_

package/rcode/templates/projects/mobile-app/template.yaml

@@ -0,0 +1,17 @@
+name: mobile-app
+display: "Mobile App"
+description: "iOS + Android app — onboarding, core feature, offline, push, store submission"
+recommended_modules:
+  - core
+  - execution
+phases:
+  - "01 — Scaffolding (framework, navigation, CI, TestFlight/Internal testing)"
+  - "02 — Auth + onboarding"
+  - "03 — Core feature"
+  - "04 — Offline + sync"
+  - "05 — Push notifications + deep links"
+  - "06 — Store submission + launch"
+next_steps: |
+  Seeded. Common follow-ups:
+    /rcode-council native (Swift/Kotlin) vs React Native vs Flutter for this app?
+    /rcode-plan phase 01

package/rcode/templates/projects/saas-b2b/PROJECT.md

@@ -0,0 +1,40 @@
+# {{project_name}} — Multi-tenant B2B SaaS
+
+**Template:** saas-b2b
+**Created:** {{date}}
+
+## What we're building
+_(One-sentence description — edit me.)_
+
+A multi-tenant B2B SaaS for {{target_customer}} that solves {{core_problem}}. Paying customers are organizations, not individuals.
+
+## Target customer
+- **Segment:** {{segment}} (e.g. mid-market ops teams, compliance-heavy industries)
+- **Size:** {{company_size}}
+- **Buying trigger:** {{trigger}}
+
+## Why now
+_(Market timing, regulatory shift, technology enabler, etc.)_
+
+## Monetization
+- **Model:** Subscription (per-seat / per-org / usage-based — pick one)
+- **Target ACV:** {{acv}}
+- **Trial strategy:** {{trial_length}} with {{trial_gating}}
+
+## Non-negotiables
+- Data isolation between tenants (hard requirement, not best-effort)
+- Audit log for every mutating action (for SOC2/ISO compliance paths)
+- SSO support by launch (SAML or OIDC — most B2B buyers require this)
+
+## Explicitly out of scope
+- Consumer tier
+- Self-serve free plan beyond trial
+- Mobile apps in v1
+
+## Key risks
+- **Technical:** multi-tenancy bugs = data leak = company-ending event
+- **Business:** long B2B sales cycles may outlast runway
+- **Regulatory:** PII/data-residency constraints depending on target market
+
+## Evolution
+_(Updated after each phase completion by `/rcode-execute`.)_

package/rcode/templates/projects/saas-b2b/template.yaml

@@ -0,0 +1,18 @@
+name: saas-b2b
+display: "SaaS B2B"
+description: "Multi-tenant B2B SaaS — auth, orgs, billing, RBAC, admin console, audit log"
+recommended_modules:
+  - core
+  - execution
+  - discovery
+phases:
+  - "01 — Foundations (auth, DB, env)"
+  - "02 — Multi-tenancy + RBAC"
+  - "03 — Billing + subscription lifecycle"
+  - "04 — Admin console + audit log"
+  - "05 — Observability + incident response"
+  - "06 — Launch readiness (SLA, docs, support)"
+next_steps: |
+  Seeded. Common follow-ups:
+    /rcode-council what's the first customer segment we should focus on?
+    /rcode-plan phase 01

package/rcode/templates/settings-hooks.json

@@ -0,0 +1,75 @@
+{
+  "_comment": "pre-edit hook is currently advisory (logs warning, does not block). Full session-read tracking requires PostToolUse Read hook to write state file. Implemented in follow-up.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .rcode/bin/rcode-hooks.cjs pre-edit"
+          },
+          {
+            "type": "command",
+            "command": "node .rcode/bin/rcode-hooks.cjs compact-nudge"
+          }
+        ]
+      },
+      {
+        "matcher": "SlashCommand",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .rcode/bin/rcode-hooks.cjs pre-workflow"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .rcode/bin/rcode-hooks.cjs bash-guard"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .rcode/bin/rcode-hooks.cjs post-commit"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .rcode/bin/rcode-hooks.cjs pre-compact"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .rcode/bin/rcode-hooks.cjs stop-verify"
+          },
+          {
+            "type": "command",
+            "command": "node .rcode/bin/rcode-hooks.cjs cost-track"
+          }
+        ]
+      }
+    ]
+  }
+}

package/rcode/templates/summary.md

@@ -0,0 +1,77 @@
+# SUMMARY.md Template
+
+Each plan or sprint task produces a SUMMARY.md when it completes. The summary is the unit of work's lasting record — what was done, why, what remains, what other work it affects.
+
+## Frontmatter
+
+```yaml
+---
+phase: NN
+plan: NN.M             # if applicable
+sprint: N              # if applicable
+story_id: NN.M         # if dev-story produced this
+generated: <ISO date>
+status: complete | partial | blocked
+verified: false        # flips to true after /rcode-verify-work passes
+---
+```
+
+## Sections
+
+### One-liner
+
+A single line describing what was accomplished. Goes into `/rcode-progress` recent-work bullets, council recaps, milestone summaries. Be specific:
+
+> ❌ "Added some dashboard improvements"
+> ✅ "Wired live engagement metrics to dashboard top-3 tweets card; updates every 30s via SSE"
+
+### Outcomes
+
+What changed as a result of this work, observable from outside:
+
+- ...
+
+### Files touched
+
+```
+src/dashboard/Card.tsx        new
+src/dashboard/index.tsx       modified — added engagement subscription
+src/lib/sse.ts                new — SSE client wrapper
+test/dashboard.test.ts        new — 4 tests
+```
+
+### Decisions
+
+Decisions made during execution that aren't already in `state.decisions[]`:
+
+- **<decision>**: chose A over B because <one-line reason>. Tradeoff: <what we gave up>.
+
+### Issues encountered
+
+Problems hit during execution and how they were resolved:
+
+- **<problem>**: <one-line description>. Resolved by <action>. Time spent: <approx>.
+
+If a problem was NOT resolved, it goes here AND becomes a follow-up filed below.
+
+### Follow-ups
+
+GH issues filed (or to file) for work that this story surfaced but didn't ship:
+
+- #N — <title>
+- (to file) — <description>
+
+### Verification
+
+How a verifier confirms this story is actually done:
+
+- Run `<command>`, expect `<output>`
+- Open `<UI element>`, click `<button>`, observe `<state change>`
+
+This block feeds into UAT.md when the phase completes.
+
+### Status
+
+- **complete** — all acceptance criteria green, follow-ups filed.
+- **partial** — some AC green, others deferred. Document which AC are open.
+- **blocked** — couldn't proceed. Owner of unblock + ETA.

package/rcode/templates/verification-report.md

@@ -0,0 +1,83 @@
+# Verification Report Template
+
+Used by `/rcode-verify-phase`. Goal-backward analysis of whether the phase actually delivered the goal stated in ROADMAP.md.
+
+## Frontmatter
+
+```yaml
+---
+phase: NN
+phase_name: <slug>
+verifier: <agent / human>
+verified_at: <ISO date>
+verdict: pass | fail | partial
+goal_source: ROADMAP.md (commit-sha-at-phase-start)
+---
+```
+
+## Sections
+
+### Phase goal (verbatim)
+
+> <paste the goal statement from ROADMAP.md exactly as written when this phase was planned>
+
+### Goal decomposition
+
+The goal as one sentence is too coarse to verify against. Decompose into checkable claims:
+
+1. **Claim 1**: <one observable thing the goal implies>
+2. **Claim 2**: ...
+3. **Claim N**: ...
+
+### Evidence per claim
+
+For each claim, list:
+
+- **Source of truth**: code path / file / endpoint / behavior
+- **Verification method**: command / test name / manual step
+- **Result**: ✅ / ❌ / ⚠️
+- **Notes**: anything surprising
+
+```
+| # | Claim | Method | Result | Notes |
+|---|-------|--------|:------:|-------|
+| 1 | ... | ... | ✅ | ... |
+```
+
+### Coverage gaps
+
+What the phase goal said but no evidence-trail covered. List explicitly:
+
+- **<claim>** has no implementation that can be pointed to. Either:
+  - The goal was aspirational and the phase didn't implement it (gap to file as follow-up)
+  - The implementation exists but no test or doc covers it (gap to file as test debt)
+
+### Side-effect audit
+
+What the phase changed BEYOND the goal. Often these are silent:
+
+- New dependencies added
+- Schema changes
+- API contract changes
+- File-tree changes (new dirs, deleted files)
+
+Each side effect should be intentional and documented.
+
+### Verdict reasoning
+
+One paragraph explaining why the verdict (pass / fail / partial) was chosen. Include any judgment calls.
+
+### Follow-ups
+
+Issues filed (or to file) for gaps surfaced during verification:
+
+- #N — <title>
+- (to file) — <description>
+
+## Sign-off
+
+```
+Verifier: <name or agent id>
+Date: <ISO>
+Verdict: <verdict from frontmatter>
+```

package/rcode/workflows/add-phase.md

@@ -0,0 +1,193 @@
+<purpose>
+Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- All arguments become the phase description
+- Example: `/rcode-add-phase Add authentication` → description = "Add authentication"
+- Example: `/rcode-add-phase Fix critical performance issues` → description = "Fix critical performance issues"
+
+If no arguments provided:
+
+```
+ERROR: Phase description required
+Usage: /rcode-add-phase <description>
+Example: /rcode-add-phase Add authentication system
+```
+
+Exit.
+</step>
+
+<step name="init_context">
+Load phase operation context:
+
+```bash
+INIT=$(node ".rcode/bin/rcode-tools.cjs" init phase-op "0" 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.
+```
+
+Check `roadmap_exists` from init JSON. If false:
+```
+ERROR: No roadmap found (.planning/ROADMAP.md)
+Run /rcode-new-project to initialize.
+```
+Exit.
+</step>
+
+<step name="detect_task_list">
+**Detect bulk-task input** — when /rcode-quick or /rcode-do auto-routes a multi-task input here, the entire bug list arrives as `${description}`. Don't put it all in the phase title; extract structure.
+
+Match if `${description}` contains ANY of:
+- 5+ numbered list items (`/^\s*\d+\.\s/m` ≥ 5)
+- 5+ bullet items (`/^\s*[-*]\s/m` ≥ 5)
+- 3+ "Bug Report:" / "Issue:" / "Severity:" headers
+- Multiple newlines (> 5 lines total)
+
+If matched:
+
+1. **Phase name** = first line of `${description}` (or first 80 chars if no newline). If the first line is itself a heading like `# Phase 09 — UI Bug Cleanup`, strip the leading `#` characters.
+2. **Phase body** = the rest of the input.
+3. After the phase directory is created (next step), write the body to `.planning/phases/{NN}-{slug}/TASKS.md` with header:
+
+   ```markdown
+   # Phase {N} — {phase name} — Tasks
+
+   *Auto-extracted from /rcode-quick or /rcode-do bulk auto-route on {ISO date}.*
+
+   {original body, preserved verbatim}
+   ```
+
+4. Note in the completion message: "TASKS.md written with N tasks". The downstream /rcode-plan workflow consumes TASKS.md as the input to SPRINT.md generation — no manual re-paste needed.
+
+If NOT matched (single task), proceed normally — `${description}` is the phase name as-is.
+
+Set `BULK_MODE=true|false` for the next step.
+</step>
+
+<step name="add_phase">
+**Delegate the phase addition to rcode-tools:**
+
+```bash
+# In bulk mode, pass only the extracted phase name (not the entire body)
+PHASE_NAME=$( [ "$BULK_MODE" = "true" ] && echo "$EXTRACTED_FIRST_LINE" || echo "$description" )
+RESULT=$(node ".rcode/bin/rcode-tools.cjs" phase add "${PHASE_NAME}")
+```
+
+The CLI handles:
+- Finding the highest existing integer phase number
+- Calculating next phase number (max + 1)
+- Generating slug from description
+- Creating the phase directory (`.planning/phases/{NN}-{slug}/`)
+- Inserting the phase entry into ROADMAP.md with Goal, Depends on, and Plans sections
+
+Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
+
+**If `BULK_MODE=true`:** after the CLI returns, write the bulk body to `${directory}/TASKS.md` per the structure defined in `detect_task_list`. This step is non-destructive — it only ADDs a TASKS.md file inside the new phase directory.
+</step>
+
+<step name="update_project_state">
+Update STATE.md to reflect the new phase:
+
+1. Read `.planning/STATE.md`
+2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+   ```
+   - Phase {N} added: {description}
+   ```
+
+If "Roadmap Evolution" section doesn't exist, create it.
+</step>
+
+<step name="milestone_health_check">
+After the phase is added, run the milestone-health gauge (issue #718):
+
+```bash
+HEALTH=$(node ".rcode/bin/rcode-tools.cjs" milestone-health 2>/dev/null)
+RECOMMENDATION=$(echo "$HEALTH" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).recommendation||'unknown')}catch{console.log('unknown')}})")
+OPEN_COUNT=$(echo "$HEALTH" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).open_phases||0)}catch{console.log(0)}})")
+MILESTONE_NAME=$(echo "$HEALTH" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).milestone||'')}catch{console.log('')}})")
+```
+
+If `RECOMMENDATION` is `should-close` (≥12 open phases), surface a hard nudge:
+
+```
+⚠ Milestone health: {MILESTONE_NAME} has {OPEN_COUNT} open phases.
+
+Phase {N} is now in this milestone, but the milestone is well past the
+12-phase threshold for considering closure. Phases are accumulating without
+a milestone boundary — historically this is where roadmaps lose structure.
+
+Recommended next step:
+  /rcode-complete-milestone    close {MILESTONE_NAME} cleanly + archive done phases
+  /rcode-new-milestone         start a fresh milestone for ongoing work
+
+If you genuinely want a giant single-milestone roadmap, ignore this and
+continue. The threshold is conservative on purpose.
+```
+
+If `RECOMMENDATION` is `consider-closing` (8-11 open phases), softer nudge:
+
+```
+ℹ Milestone health: {MILESTONE_NAME} has {OPEN_COUNT} open phases — getting full.
+   Consider /rcode-complete-milestone before adding more.
+```
+
+If `RECOMMENDATION` is `healthy`, say nothing.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {N} added to current milestone:
+- Description: {description}
+- Directory: .planning/phases/{phase-num}-{slug}/
+- Status: Not planned yet
+
+Roadmap updated: .planning/ROADMAP.md
+
+---
+
+## ▶ Next Up
+
+**Phase {N}: {description}**
+
+`/clear` then:
+
+`/rcode-plan {N}`
+
+---
+
+**Also available:**
+- `/rcode-add-phase <description>` — add another phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] `rcode-tools phase add` executed successfully
+- [ ] Phase directory created
+- [ ] Roadmap updated with new phase entry
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] User informed of next steps
+</success_criteria>
+
+## Next Up
+
+- `/rcode-discuss-phase` — discuss the new phase before planning
+- `/rcode-plan` — plan the newly added phase