projecta-rrr 1.9.6 → 1.9.8

package/bin/install.js

@@ -603,6 +603,38 @@ function addNpmScripts(targetDir, installedScripts, bashAvailable = true) {
   return { added, skipped };
 }
 
+/**
+ * Run external skills bootstrap script (non-blocking)
+ * Installs skills from skills.sh ecosystem into ~/.claude/skills
+ */
+function runExternalSkillsBootstrap() {
+  const bootstrapScript = path.join(__dirname, '..', 'scripts', 'bootstrap-external-skills.js');
+
+  if (!fs.existsSync(bootstrapScript)) {
+    return;
+  }
+
+  // Spawn the bootstrap script without waiting for it to complete
+  // This allows the install to finish while skills install in background
+  try {
+    const { spawn } = require('child_process');
+
+    // On Windows, use node directly; on Unix, we can use background execution
+    const child = spawn(process.execPath, [bootstrapScript], {
+      detached: true,
+      stdio: 'ignore',
+      cwd: path.join(__dirname, '..')
+    });
+
+    child.unref();
+
+    console.log(`  ${dim}External skills bootstrap started in background${reset}`);
+  } catch (e) {
+    // Silently ignore bootstrap failures - skills are optional
+    console.log(`  ${dim}External skills bootstrap skipped${reset}`);
+  }
+}
+
 /**
  * Install to the specified directory
  */
@@ -687,6 +719,11 @@ function install(isGlobal) {
     }
   }
 
+  // Bootstrap external skills from skills.sh ecosystem (only for global install)
+  if (isGlobal) {
+    console.log(`  ${green}✓${reset} Preparing external skills bootstrap`);
+  }
+
   // Copy CHANGELOG.md
   const changelogSrc = path.join(src, 'CHANGELOG.md');
   const changelogDest = path.join(claudeDir, 'rrr', 'CHANGELOG.md');
@@ -1104,6 +1141,8 @@ if (hasGlobal && hasLocal) {
   handleStatusline(settings, false, (shouldInstallStatusline) => {
     handleNotifications(settings, false, (shouldInstallNotify) => {
       finishInstall(settingsPath, settings, statuslineCommand, notifyCommand, claudeDir, shouldInstallStatusline, shouldInstallNotify, localDirName, isGlobal, bashAvailable);
+      // Run external skills bootstrap for global installs (non-blocking)
+      runExternalSkillsBootstrap();
     });
   });
 } else if (hasLocal) {

package/commands/rrr/execute-plan.md

@@ -241,6 +241,28 @@ Plan path: $ARGUMENTS
 
    Skills are injected into executor prompt as `<skills>` block.
 
+4.5. **Suggest skills from stack (optional)**
+
+   After loading skills, check for stack-based suggestions:
+
+   **On macOS/Linux:**
+   ```bash
+   node ~/.claude/rrr/lib/load-skills.js --suggest "$plan_path" 2>/dev/null || echo ""
+   ```
+
+   **On Windows:**
+   Use the loaded skills result's `suggested` field (if using loadSkillsForPlan programmatically).
+
+   **If suggestions exist:**
+   ```
+   ---
+   Skills suggested from stack: projecta.shadcn-ui, projecta.mcp-stack
+   To include: add to PLAN frontmatter `skills: [projecta.shadcn-ui, projecta.mcp-stack]`
+   ---
+   ```
+
+   If no stack field in plan or `skills_mode: minimal`, skip silently.
+
 5. **Pre-execution summary (interactive mode only)**
    Check config.json for mode. Skip this step if mode=yolo.
 

package/commands/rrr/help.md

@@ -433,6 +433,29 @@ Search for skills on skillsmp.com marketplace.
 
 Usage: `/rrr:search-skills react patterns`
 
+### Stack-Aware Skill Suggestions
+
+Skills can suggest themselves based on your plan's `stack:` field:
+
+**Add stack to PLAN.md frontmatter:**
+```yaml
+---
+stack: [nextjs, typescript, tailwind, stripe]
+---
+```
+
+**When you run `/rrr:execute-plan`:**
+```
+Skills suggested from stack: projecta.shadcn-ui, projecta.mcp-stack
+To include: add to PLAN frontmatter `skills: [projecta.shadcn-ui, projecta.mcp-stack]`
+```
+
+**How it works:**
+- RRR matches stack keywords (e.g., `nextjs`, `stripe`) against skill registry tags
+- Suggestions appear during execute-plan preflight
+- Add to `skills:` array in frontmatter to persist
+- Skipped if `skills_mode: minimal` or no stack field
+
 ### Utility Commands
 
 **`/rrr:help`**
@@ -932,6 +955,99 @@ skills:
         └── (vendor with scripts/vendor-droid-tings-skills.sh)
 ```
 
+## External Skills (skills.sh Ecosystem)
+
+RRR automatically installs and manages external skills from the skills.sh ecosystem using the `add-skill` CLI.
+
+### What Are External Skills?
+
+Skills from the broader AI/developer community that RRR can discover and load during execution. Unlike vendored skills (included in npm package), external skills are fetched on-demand from GitHub repos.
+
+### Where Skills Are Installed
+
+| Platform | Location |
+|----------|----------|
+| macOS/Linux | `~/.claude/skills/` |
+| Windows | `%USERPROFILE%\.claude\skills\` |
+
+### Installed Sources
+
+On first global install, RRR bootstraps skills from configured sources in `projecta.defaults.json`:
+
+| Source | Skills |
+|--------|--------|
+| `vercel-labs/agent-skills` | vercel-react-best-practices, web-design-guidelines |
+| `expo/skills` | building-ui, api-routes, data-fetching, deployment, tailwind-setup |
+| `anthropics/skills` | frontend-design, webapp-testing, mcp-builder |
+| `vercel-labs/agent-browser` | agent-browser |
+| `callstackincubator/agent-skills` | react-native-best-practices |
+| `coreyhaines31/marketingskills` | signup-flow-cro, page-cro, seo-audit, copywriting |
+| `dmmulroy/cloudflare-skill` | cloudflare |
+
+### How Discovery Works
+
+1. **Bootstrap** — On `npx projecta-rrr --global`, runs `npx add-skill <repo> --skill <name>` for configured skills
+2. **Manifest** — Records installed skills in `~/.claude/rrr/external-skills.lock.json`
+3. **Rate-Limit** — Only re-installs if 24+ hours since last check (configurable)
+4. **Discovery** — During execute-plan, scans `~/.claude/skills/` for SKILL.md files not in registry
+
+### Loading External Skills
+
+External skills are auto-discovered and loaded just like registered skills:
+
+```yaml
+---
+skills:
+  - frontend-design       # From anthropics/skills (registry)
+  - vercel-react-best-practices  # From vercel-labs/agent-skills (filesystem discovery)
+---
+```
+
+### Configuration
+
+Add to `projecta.defaults.json` in project or `~/.claude/rrr/`:
+
+```json
+{
+  "external_skills": {
+    "enabled": true,
+    "auto_update": true,
+    "check_interval_hours": 24,
+    "sources": [
+      { "source": "owner/repo", "skills": ["skill-name"] }
+    ]
+  }
+}
+```
+
+### Manual Commands
+
+```bash
+# Force re-install all external skills
+node ~/.claude/rrr/scripts/bootstrap-external-skills.js --force
+
+# Dry-run (show what would install)
+node ~/.claude/rrr/scripts/bootstrap-external-skills.js --dry-run
+```
+
+### Troubleshooting
+
+```bash
+# Check manifest
+cat ~/.claude/rrr/external-skills.lock.json
+
+# List installed external skills
+ls ~/.claude/skills/
+
+# Windows PowerShell
+Get-ChildItem -Recurse "$env:USERPROFILE\.claude\skills" -Filter SKILL.md | Select-Object FullName
+```
+
+**If skills don't load:**
+1. Check manifest exists: `~/.claude/rrr/external-skills.lock.json`
+2. Verify SKILL.md files in `~/.claude/skills/<skill-name>/`
+3. Ensure skill has `name:` in frontmatter matching skill ID
+
 **Vendoring Community Skills:**
 
 ```bash

package/commands/rrr/plan-phase.md

@@ -174,6 +174,159 @@ Use AskUserQuestion:
 
 **If script not found:** Continue without warning.
 
+## 3.2. Discover and Ingest Pending TODOs (Cross-Platform)
+
+**Before planning, check for pending TODOs that could inform this phase.**
+
+### Step 3.2.1: Discover TODOs
+
+**On macOS/Linux:**
+```bash
+TODO_FILES=$(ls -t .planning/todos/pending/*.md 2>/dev/null | head -10)
+TODO_COUNT=$(echo "$TODO_FILES" | wc -l | tr -d ' ')
+```
+
+**On Windows:**
+Use Glob tool: `Glob pattern: ".planning/todos/pending/*.md"` — limit to 10 most recent.
+
+**If TODO_COUNT = 0:** Skip to step 4 (no pending TODOs).
+
+### Step 3.2.2: Parse and Display TODOs
+
+For each TODO file (up to 10, newest first), extract frontmatter:
+
+**On macOS/Linux:**
+```bash
+for file in $TODO_FILES; do
+  created=$(grep "^created:" "$file" 2>/dev/null | cut -d' ' -f2 | xargs)
+  title=$(grep "^title:" "$file" 2>/dev/null | cut -d':' -f2- | xargs)
+  area=$(grep "^area:" "$file" 2>/dev/null | cut -d' ' -f2)
+  echo "$created|$title|$area|$file"
+done
+```
+
+**On Windows:**
+Use Read tool to read each TODO file, extract frontmatter fields.
+
+**Display as numbered list (max 10):**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PENDING TODOs ({N} found)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. [title] ([area], [created])
+2. [title] ([area], [created])
+...
+
+Reply with numbers to select (e.g., "1,3" or "all"), or:
+- "skip" to ignore for this phase
+- "attach" to link to phase context
+- "convert" to create plan(s) from selected
+- "done" to mark selected as already handled
+```
+
+### Step 3.2.3: Present Action Options
+
+Use AskUserQuestion:
+```yaml
+header: "TODOs Found"
+question: "You have {N} pending TODOs. How would you like to handle them for this phase?"
+options:
+  - label: "Ignore for this phase"
+    description: "Continue planning without these TODOs"
+  - label: "Attach to phase context"
+    description: "Link TODOs to {PHASE}-CONTEXT.md (keep in pending/)"
+  - label: "Convert to plan(s)"
+    description: "Generate PLAN.md stub(s) from selected TODOs"
+  - label: "Mark as done"
+    description: "Move selected TODOs to done/ (already handled)"
+  - label: "Review in /rrr:check-todos"
+    description: "Exit and review TODOs more thoroughly"
+```
+
+### Step 3.2.4: Handle Selection
+
+**"Ignore for this phase":**
+- Display: `Skipping TODO ingestion. Run /rrr:check-todos to review later.`
+- Continue to step 4 (research)
+
+**"Attach to phase context":**
+
+1. Get selected TODO indices from user response
+2. Read selected TODO files, extract title and problem/solution
+3. Update or create `${PHASE_DIR}/${PHASE}-CONTEXT.md`:
+   - If file exists, append "## Ingested TODOs" section
+   - If new, create with ingested TODOs section
+4. Add bullet list:
+   ```markdown
+   ## Ingested TODOs
+
+   - **[Title]** — [.planning/todos/pending/filename.md](path)
+     - Problem: [1-line summary]
+     - Status: Pending, linked for planning
+   ```
+5. Display: `Linked {N} TODOs to ${PHASE}-CONTEXT.md`
+6. Continue to step 4 (research)
+
+**"Convert to plan(s)":**
+
+1. Get selected TODO indices from user response
+2. Determine next plan number for phase:
+   - On macOS/Linux: `ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null | sed 's/.*\///' | cut -d'-' -f1 | sort -n | tail -1`
+   - On Windows: Glob `*.md` files, parse plan numbers, find max
+3. For each selected TODO:
+   - Create PLAN stub: `${PHASE_DIR}/${NEXT_PLAN}-${SLUG}-PLAN.md`
+   - Frontmatter:
+     ```yaml
+     ---
+     wave: 1
+     depends_on: []
+     files_modified: []
+     autonomous: true
+     ---
+     ```
+   - Body:
+     ```markdown
+     # [TODO Title]
+
+     **Source TODO:** [.planning/todos/pending/filename.md](path)
+
+     ## Objective
+
+     [From TODO Problem section]
+
+     ## Tasks
+
+     <!-- Generated from TODO: convert to actionable tasks -->
+
+     ## Verification
+
+     - TODO converted from pending idea
+     - Original context preserved in source TODO file
+     ```
+   - Increment plan number
+4. Move converted TODO files to `done/`:
+   ```bash
+   mv .planning/todos/pending/[filename].md .planning/todos/done/
+   ```
+5. Display: `Created {N} plan stub(s) from TODOs, moved originals to done/`
+6. Continue to step 4 (research)
+
+**"Mark as done":**
+
+1. Get selected TODO indices from user response
+2. Move selected files:
+   ```bash
+   mv .planning/todos/pending/[filename].md .planning/todos/done/
+   ```
+3. Display: `Marked {N} TODOs as done`
+4. Continue to step 4 (research)
+
+**"Review in /rrr:check-todos":**
+- Display: `Run /rrr:check-todos to review and manage your TODOs`
+- Exit command
+
 ## 4. Ensure Phase Directory Exists (Cross-Platform)
 
 **On macOS/Linux:**
@@ -521,7 +674,7 @@ Task(
 )
 ```
 
-- After planner returns → spawn checker again (step 10)
+- After planner returns → spawn checker again (step 11)
 - Increment iteration_count
 
 **If iteration_count >= 3:**
@@ -585,11 +738,12 @@ Verification: {Passed | Passed with override | Skipped}
 <success_criteria>
 - [ ] .planning/ directory validated
 - [ ] Phase validated against roadmap
+- [ ] Pending TODOs discovered and handled (or skipped)
 - [ ] Phase directory created if needed
 - [ ] Research completed (unless --skip-research or --gaps or exists)
 - [ ] rrr-phase-researcher spawned if research needed
 - [ ] Existing plans checked
-- [ ] rrr-planner spawned with context (including RESEARCH.md if available)
+- [ ] rrr-planner spawned with context (including RESEARCH.md and CONTEXT.md if available)
 - [ ] Plans created (PLANNING COMPLETE or CHECKPOINT handled)
 - [ ] rrr-plan-checker spawned (unless --skip-verify)
 - [ ] Verification passed OR user override OR max iterations with user decision

package/commands/rrr/progress.md

@@ -165,7 +165,10 @@ CONTEXT: [✓ if CONTEXT.md exists | - if not]
 
 ## What's Next
 [Next phase/plan objective from ROADMAP]
-```
+
+**If TODO_COUNT > 0:**
+- Pending ideas found → `/rrr:plan-phase {current or next phase}` will offer to ingest them
+
 
 </step>
 

package/docs/CHEATSHEET-BROWNFIELD.md

@@ -0,0 +1,296 @@
+# RRR Cheat Sheet: Brownfield Projects
+
+**For:** Adding RRR to an existing codebase with code already written.
+
+---
+
+## 1. One-Minute Mental Model
+
+```
+Milestone (v1.0) → Phases (1, 2, 3...) → Plans (01, 02...) → SUMMARY → UAT (optional)
+```
+
+| Concept | What it is | Why it matters |
+|---------|------------|----------------|
+| **Milestone** | A shipped version (v1.0, v1.1) | Your release target |
+| **Phase** | Chunk of related work (Foundation, Auth, API) | Breaks milestone into manageables |
+| **Plan** | Single executable task file | Your work unit |
+| **SUMMARY** | Receipt after executing a plan | Proves you did the work |
+| **verify-work --audit** | Non-interactive integrity check | Confirms PLAN + SUMMARY + git evidence exist |
+
+**Core insight:** Plans are contracts. SUMMARYs are receipts. `verify-work --audit` checks the paperwork.
+
+**Where artifacts live:**
+```
+.planning/
+├── PROJECT.md      # What you're building
+├── ROADMAP.md      # Phases and progress
+├── STATE.md        # Current position + decisions
+├── SCOPE_CACHE.md  # Git-backed state for drift detection
+└── phases/         # Plans and summaries per phase
+```
+
+**RRR ignores:** architect-private paths (GSDWatcher/, upstreams/, reports/) — RRR won't scan or modify them.
+
+---
+
+## 2. Install / Update
+
+### First-Time Install
+```bash
+npx projecta-rrr
+```
+Creates `~/.claude/` with all commands and workflows.
+
+### Update to Latest
+```bash
+npx projecta-rrr@latest
+```
+Run this weekly or when `/rrr:update` tells you there's a new version.
+
+### After Update
+**Always restart Claude Code** for commands to reload:
+1. Type `exit` in terminal
+2. Run `claude` to restart
+3. Verify with `/rrr:help`
+
+### Windows Notes
+- Core commands work without bash (Read, Glob, Grep)
+- Hooks (statusline, notifications) need Git Bash or WSL2
+- npm scripts (`npm run pushpa`, `npm run e2e`) require bash
+
+### Commands Not Working?
+
+| Problem | Fix |
+|---------|-----|
+| "Unknown skill: rrr:help" | Exit Claude Code (`exit`), restart (`claude`), then `/rrr:help` |
+| Commands still missing | Reinstall: `npx projecta-rrr@latest`, restart Claude Code |
+| Verify install worked | Run `/rrr:help` — should show command list |
+
+---
+
+## 3. Start Here: Brownfield Flow
+
+You have an **existing repo** with code already written. Follow these steps:
+
+1. **Audit existing structure**
+   ```
+   /rrr:brownfield-audit
+   ```
+   Scans for planning docs, detects conflicts, suggests cleanup
+
+2. **If docs say X but code is Y → Investigate**
+   ```
+   /rrr:map-codebase
+   ```
+   Example: docs say "Supabase/Netlify" but code uses "Neon/Render" → run map-codebase to refresh planning truth
+
+3. **Initialize project**
+   ```
+   /clear
+   /rrr:new-project
+   ```
+   Answers questions → creates PROJECT.md, ROADMAP.md, STATE.md
+   (Existing code preserved; RRR adds planning layer)
+
+4. **Plan first phase**
+   ```
+   /clear
+   /rrr:plan-phase 1
+   ```
+
+5. **Execute phase**
+   ```
+   /clear
+   /rrr:execute-phase 1
+   ```
+
+6. **Verify implementation**
+   ```
+   /rrr:verify-work --audit 1
+   ```
+
+7. **Check progress, repeat**
+   ```
+   /rrr:progress
+   ```
+
+### Brownfield-Specific Notes
+
+- **Existing tests?** RRR will detect and use them
+- **No e2e setup?** `/rrr:brownfield-audit` offers to scaffold Playwright
+- **Existing docs?** Audit detects conflicts with RRR structure
+- **Legacy code?** RRR plans work alongside existing code
+- **Codebase doesn't match docs?** Run `/rrr:map-codebase` to update planning truth
+
+---
+
+## 4. Daily Driver (After Repo Is Set Up)
+
+### Morning Loop (5 minutes)
+
+```
+/rrr:progress
+```
+Decide: execute next plan OR plan next phase?
+
+| If... | Then run... |
+|-------|-------------|
+| Plan exists, not executed | `/rrr:execute-plan <path>` |
+| Plans done, phase complete | `/rrr:plan-phase <next>` |
+| Between milestones | `/rrr:discuss-milestone` |
+
+### Mid-Work Loop (During Coding)
+
+**"I just thought of a new feature..."**
+
+| Situation | Action |
+|-----------|--------|
+| Within current scope | Continue plan, capture as TODO later |
+| Entirely new feature | `/rrr:add-todo "Feature name"` |
+| Scope drift detected | `/rrr:progress` → shows drift warning |
+
+### End-of-Day Loop (3 minutes)
+
+```
+/rrr:progress
+/rrr:verify-work --audit  # current phase or milestone
+```
+
+Quick health check before wrapping up.
+
+---
+
+## 5. Verification: Audit vs UAT
+
+RRR has **two verification modes**:
+
+### Audit Mode (Default, Non-Interactive)
+```
+/rrr:verify-work --audit           # current milestone
+/rrr:verify-work --audit 05        # phase 05 only
+/rrr:verify-work --audit v1.9      # entire milestone
+```
+- Checks: PLAN exists, SUMMARY exists, git commit hash in SUMMARY
+- Output: `.planning/artifacts/VERIFY_WORK_AUDIT.md`
+- **Never touches UAT files**
+
+### UAT Mode (Interactive, Optional)
+```
+/rrr:verify-work --uat 01          # interactive testing for phase 01
+```
+- Creates/updates `*-UAT.md` files
+- Walks through testable deliverables one by one
+- User confirms: "pass" or describes issue
+- Only use when you want manual testing
+
+### Quick Reference
+```
+/rrr:verify-work           # audit (default - no UAT files touched)
+/rrr:verify-work --audit   # explicit audit
+/rrr:verify-work --uat 05  # interactive UAT for phase 05
+```
+
+---
+
+## 6. Common Scenarios
+
+| Symptom | Command | Expected Outcome |
+|---------|---------|------------------|
+| "I don't know what to run next" | `/rrr:mvp` | Detects state, tells you exactly what to run |
+| "My phase executed but progress looks wrong" | `/rrr:progress` | Shows actual completion; check for missing SUMMARYs |
+| "Unknown command /rrr:*" | Exit Claude Code, run `claude` again | Commands reload from ~/.claude/ |
+| "Verification failed" | `/rrr:fix-visual-failure` | Analyzes failure, suggests fixes |
+| "No Playwright / no e2e setup" | `bash scripts/scaffold-e2e.sh` | Creates minimal Playwright config |
+| "I'm in a backend-only repo" | Set `frontend_impact: false` in plans | Skips visual proof, runs unit tests only |
+| "Brownfield audit found conflicts" | Review audit report, resolve manually | Then run `/rrr:new-project` |
+| "Docs don't match code" | `/rrr:map-codebase` | Updates planning truth |
+
+---
+
+## 7. Pushpa Mode (Overnight Automation)
+
+**What:** Runs phases automatically while you sleep.
+
+**Commands:**
+```bash
+# Run in a SEPARATE terminal (not inside Claude Code)
+bash scripts/pushpa-mode.sh
+
+# Or via npm
+npm run pushpa
+```
+
+**Safety:**
+- Run in separate terminal
+- Ensure tests pass first
+- Review `.planning/PUSHPA_REPORT.md` in the morning
+
+---
+
+## 8. Quick Reference
+
+| Command | When |
+|---------|------|
+| `/rrr:progress` | Daily compass — where am I, what's next |
+| `/rrr:mvp` | Not sure what to run? Start here |
+| `/rrr:brownfield-audit` | Scan existing repo before initializing |
+| `/rrr:map-codebase` | Update planning truth when docs mismatch code |
+| `/rrr:plan-phase <N>` | Create plans for phase N |
+| `/rrr:execute-phase <N>` | Execute all plans in phase N |
+| `/rrr:verify-work --audit` | Check implementation integrity |
+| `/rrr:verify-work --uat` | Interactive testing (optional) |
+| `/rrr:add-todo` | Capture ideas while working |
+| `/rrr:help` | Full command reference |
+
+---
+
+## 9. External Skills (skills.sh Ecosystem)
+
+RRR automatically installs and manages external skills from the skills.sh ecosystem.
+
+### Where Skills Are Installed
+
+| Platform | Location |
+|----------|----------|
+| macOS/Linux | `~/.claude/skills/` |
+| Windows | `%USERPROFILE%\.claude\skills\` |
+
+### What Gets Installed
+
+On first global install (`npx projecta-rrr --global`), RRR bootstraps skills from:
+- `vercel-labs/agent-skills` - React best practices, web design
+- `expo/skills` - Expo/React Native UI, API routes, deployment
+- `anthropics/skills` - MCP builder, frontend design, testing
+- `vercel-labs/agent-browser` - Browser automation
+- And more (see `projecta.defaults.json`)
+
+### Updating External Skills
+
+External skills are updated when you run:
+```bash
+npx projecta-rrr@latest --global
+```
+
+Updates are rate-limited (check every 24h by default).
+
+### Disabling External Skills
+
+Add to `projecta.defaults.json` in your project or `~/.claude/rrr/`:
+```json
+{
+  "external_skills": {
+    "enabled": false
+  }
+}
+```
+
+### Finding External Skills
+
+```bash
+# macOS/Linux
+ls ~/.claude/skills/
+
+# Windows PowerShell
+Get-ChildItem "$env:USERPROFILE\.claude\skills" | Select-Object Name
+```