@hanzlaa/rcode 4.3.2 → 4.4.0

package/rcode/commands/lens-audit.md

@@ -12,22 +12,24 @@ triggers:
   - run performance lens
   - run testability lens
   - run all lenses
-  - 15 lens audit
+  - 16 lens audit
+  - yagni lens
+  - over-engineering audit
 not-for:
   - phase audit (use /rcode-audit phase)
   - milestone audit (use /rcode-audit milestone)
   - karpathy audit without lens context (use /rcode-review --karpathy)
-description: Run a structured 15-lens code audit. Picks one lens or all 15 sequentially. Prints findings and ready-to-paste GitHub issue bodies. Never auto-fixes — audit-first.
-argument-hint: "[<1-15> | <lens-name> | all]"
+description: Run a structured 16-lens code audit. Picks one lens or all 16 sequentially. Prints findings and ready-to-paste GitHub issue bodies. Never auto-fixes — audit-first.
+argument-hint: "[<1-16> | <lens-name> | all]"
 allowed-tools: Read, Write, Bash, AskUserQuestion
 ---
 
 ## Overview
 
-15-lens audit entry point. Each lens is an independent inspection angle:
+16-lens audit entry point. Each lens is an independent inspection angle:
 security, performance, testability, extensibility, dep-health, error-recovery,
 state-machine, i18n, documentation, cross-platform, karpathy, sxo,
-observability, naming, coverage.
+observability, naming, coverage, yagni.
 
 Runs the selected lens(es), prints labelled findings, outputs GH issue bodies
 for each lens with findings. Never modifies files — audit-first, fix-second.
@@ -66,5 +68,5 @@ foldable GitHub issue bodies ready to copy-paste or pipe to `gh issue create`.
 **Negative — wrong lens number:**
 ```
 /rcode-lens-audit 99
-→ Error: lens must be 1-15 or a lens name. Run /rcode-lens-audit --help.
+→ Error: lens must be 1-16 or a lens name. Run /rcode-lens-audit --help.
 ```

package/rcode/data/intent-table.json

@@ -0,0 +1,87 @@
+[
+  {
+    "intent": "new-project",
+    "keywords": ["set up a new project", "initialize a new project", "start a new project", "create a new project"],
+    "command": "/rcode-new-project"
+  },
+  {
+    "intent": "map-codebase",
+    "keywords": ["map the codebase", "map this codebase", "analyze the codebase", "analyse the codebase", "map existing codebase"],
+    "command": "/rcode-map-codebase"
+  },
+  {
+    "intent": "debug",
+    "keywords": ["bug", "getting an error", "throwing an error", "error in the", "fix the error", "debug this", "crash", "failure", "broken", "not working", "fails", "exception", "traceback"],
+    "command": "/rcode-debug"
+  },
+  {
+    "intent": "audit-karpathy",
+    "keywords": ["audit", "review changes", "check my diff", "karpathy", "too complex", "complexity", "code review"],
+    "command": "/rcode-review --karpathy"
+  },
+  {
+    "intent": "lazy",
+    "keywords": ["be lazy", "lazy mode", "simplest solution", "yagni", "over-engineered", "over-engineering", "kam code likho"],
+    "command": "/rcode-lazy"
+  },
+  {
+    "intent": "checkpoint",
+    "keywords": ["checkpoint", "explain this diff", "human review", "walk through the change", "walk through this change"],
+    "command": "/rcode-checkpoint-preview"
+  },
+  {
+    "intent": "brainstorm",
+    "keywords": ["brainstorm", "generate ideas", "explore options", "what could we do", "ideate", "ideas for"],
+    "command": "/rcode-brainstorm"
+  },
+  {
+    "intent": "explore",
+    "keywords": ["explore", "research phase", "do some research", "comparing", "investigate", "look into", "understand how"],
+    "command": "/rcode-research-phase"
+  },
+  {
+    "intent": "discuss",
+    "keywords": ["which one", "better ux", "how should", "still have confusion", "conflicting", "discuss the scope", "design this", "architect this"],
+    "command": "/rcode-discuss-phase"
+  },
+  {
+    "intent": "add-phase",
+    "keywords": ["refactor", "migration", "multi-file", "system redesign", "multi file", "large refactor", "architectural", "integration", "integrate"],
+    "command": "/rcode-add-phase"
+  },
+  {
+    "intent": "sprint-planning",
+    "keywords": ["sprint planning", "plan the sprint", "next sprint", "what's in this sprint"],
+    "command": "/rcode-sprint-planning"
+  },
+  {
+    "intent": "execute-sprint",
+    "keywords": ["run the sprint", "start sprint", "execute sprint", "work on sprint"],
+    "command": "/rcode-execute-sprint"
+  },
+  {
+    "intent": "plan",
+    "keywords": ["let's plan", "plan phase", "plan this", "let me plan", "planning phase", "create a plan", "please plan", "plan and think", "scope this", "scope the feature"],
+    "command": "/rcode-plan"
+  },
+  {
+    "intent": "new-milestone",
+    "keywords": ["create milestones", "plan milestones", "create roadmap", "break project into milestones", "new milestone", "what milestones"],
+    "command": "/rcode-new-milestone"
+  },
+  {
+    "intent": "epics-stories",
+    "keywords": ["create epics", "user stories", "create stories", "epics and stories", "break into epics"],
+    "command": "/rcode-create-epics-and-stories"
+  },
+  {
+    "intent": "feature-drift",
+    "keywords": ["out of date", "out-of-date", "verify docs", "audit feature docs", "fill out existing", "prd drift", "docs vs code"],
+    "command": "/rcode-feature-drift"
+  },
+  {
+    "intent": "audit",
+    "keywords": ["re-audit", "extend the audit", "fill out the", "expand the", "re audit"],
+    "command": "/rcode-audit"
+  }
+]

package/rcode/modules/seo.yaml

@@ -0,0 +1,22 @@
+name: seo
+version: "1.0"
+description: "Full-spectrum SEO skills — content factory, growth orchestrator, audits, writer, site builder, local SEO, on-page and technical auditors"
+requires:
+  - core
+agents: []
+workflows: []
+commands:
+  - seo-content-factory
+  - seo-growth-orchestrator
+  - seo-audit
+  - on-page-seo-auditor
+  - technical-seo-checker
+  - seo-content-writer
+  - seo-site-builder
+  - rank-and-rent-local-seo
+references:
+  # claude-seo plugin agents — NOT bundled. Install separately: npx @hanzlaa/claude-seo install
+  # Routing rules in do.md reference: seo-cluster, seo-programmatic, seo-schema, seo-geo,
+  # seo-local, seo-sxo, seo-technical, seo-content, seo-backlinks, seo-ecommerce,
+  # seo-maps, seo-page, seo-performance, seo-sitemap, seo-drift, seo-dataforseo
+  - claude-seo-plugin-agents.md

package/rcode/references/project-types.yaml

@@ -268,3 +268,78 @@ dev-tool:
     - "What are the minimum dependency versions?"
     - "How will developers discover and install this?"
     - "Do you need a community or plugin ecosystem?"
+
+content-site:
+  display_name: "Content / SEO / Programmatic Site"
+  signals:
+    - rank-and-rent
+    - lead-gen
+    - lead gen
+    - landing pages
+    - programmatic seo
+    - programmatic pages
+    - service pages
+    - location pages
+    - content site
+    - seo site
+    - affiliate site
+    - affiliate
+    - local seo
+    - content farm
+    - niche site
+    - rank and rent
+    - local lead gen
+    - city pages
+    - service area pages
+    - editorial site
+    - blog site
+    - publisher
+    - content marketing
+    - link building
+    - backlink
+    - keyword research
+    - keyword cluster
+    - topic cluster
+    - E-E-A-T
+    - google business profile
+    - gbp
+    - citations
+    - nap audit
+    - schema markup
+    - structured data
+    - rich results
+    - AI overview
+    - AI search
+    - GEO SEO
+    - llms.txt
+    - programmatic seo site
+    - doorway page
+    - thin content
+    - content refresh
+    - crawl budget
+    - indexation
+    - core web vitals
+    - technical seo
+    - on-page seo
+    - digital pr
+    - guest posts
+    - seo content
+    - content strategy
+    - topical authority
+  required_sections:
+    - keyword-strategy
+    - programmatic-page-matrix
+    - internal-link-plan
+    - schema-plan
+    - content-quality-gates
+  skip_sections:
+    - authentication
+    - state-management
+    - authorization
+  discovery_questions:
+    - "What are your 3–5 primary target keywords (and their search intent)?"
+    - "What is the programmatic page matrix? (e.g. 50 services × 20 cities = 1,000 pages, or editorial only)"
+    - "Who are your top 3 organic competitors? (needed for cluster gap analysis)"
+    - "Do you have Google Search Console / analytics access for this domain?"
+    - "What is your content quality gate — minimum word count, E-E-A-T signals, author attribution?"
+    - "What schema types are needed? (LocalBusiness, FAQPage, BreadcrumbList, Product)"

package/rcode/skills/SKILLS_INDEX.md

@@ -1,6 +1,6 @@
 # rcode — Skills Index
 
-All 86 skills in rcode, organized by category: 23 agent skills, 38 action skills, 25 core skills, plus 2 shared modules.
+All 87 skills in rcode, organized by category: 23 agent skills, 38 action skills, 26 core skills, plus 2 shared modules.
 
 ## Agent Skills (23)
 
@@ -88,11 +88,12 @@ Invoked by agents via the capabilities table in their SKILL.md. Organized by SDL
 
 ---
 
-## Core Skills (25)
+## Core Skills (26)
 
 Shared utilities used across agents and workflows.
 
 - `core/rcode-init` — INTERNAL config loader (installs to .rcode/skills/, not .claude/skills/)
+- `core/rcode-lazy` — always-on YAGNI/simplicity lens; prevents bloat before code is written (rcode-trim removes it after)
 - `core/rcode-help` — meta-help on available skills
 - `core/rcode-brainstorming` — structured brainstorming workflow
 - `core/rcode-advanced-elicitation` — advanced requirements elicitation
@@ -139,6 +140,23 @@ When a user picks capability `DS`, Claude invokes the `rcode-dev-story` skill.
 
 ---
 
+## SEO Module (8)
+
+Full-spectrum SEO skills — content factory, growth orchestrator, audits, writer, site builder, local SEO, on-page and technical auditors.
+
+| Skill | Path | Description |
+|---|---|---|
+| **seo-content-factory** | `rcode/skills/seo/seo-content-factory/` | Continuous organic-traffic growth via produced SEO pages; the production line for content-driven strategies |
+| **seo-growth-orchestrator** | `rcode/skills/seo/seo-growth-orchestrator/` | Strategic SEO orchestrator across five plays: local, affiliate, technical, content-factory, and e-commerce |
+| **seo-audit** | `rcode/skills/seo/seo-audit/` | Full-spectrum SEO audit covering on-page, technical, content, and backlink signals |
+| **on-page-seo-auditor** | `rcode/skills/seo/on-page-seo-auditor/` | On-page analysis covering title tags, meta, headings, keyword integration, and CTR optimization |
+| **technical-seo-checker** | `rcode/skills/seo/technical-seo-checker/` | Technical SEO audit covering crawlability, robots.txt, sitemaps, Core Web Vitals, and indexability |
+| **seo-content-writer** | `rcode/skills/seo/seo-content-writer/` | SEO-optimized content writing with natural keyword integration and E-E-A-T quality signals |
+| **seo-site-builder** | `rcode/skills/seo/seo-site-builder/` | End-to-end affiliate content site builder: niche discovery, keyword analysis, competitor intel, and site build |
+| **rank-and-rent-local-seo** | `rcode/skills/seo/rank-and-rent-local-seo/` | Rank-and-rent local SEO business playbook: niche selection, long-tail targeting, multi-city expansion |
+
+---
+
 ## Licensing
 
 Free to use and adapt.

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/SKILL.md

@@ -2,39 +2,22 @@
 name: rcode-herdr-orchestration
 description: Orchestrate parallel cld agents in herdr — fan-out or autonomous wave campaign.
 triggers:
-  # English — single-shot orchestration
   - "orchestrate agents"
   - "run agents in herdr"
   - "parallel audit"
   - "spin up agents"
-  - "use herdr to do"
-  - "split work across panes"
   - "fan out work in herdr"
   - "multi-agent in herdr"
-  # English — autonomous campaign mode
   - "autonomous fix campaign"
-  - "auto mode"
-  - "auto loop"
   - "run waves of agents"
-  - "dispatch waves"
-  - "100+ commits"
   - "keep working until done"
-  - "complete site audit and fix"
-  # Roman Urdu / Hindi
   - "herdr mein chalao"
-  - "parallel agents lagao"
-  - "panes mein todo"
-  - "ek saath kai agents"
-  - "auto mode chalao"
-  - "waves mein fix karo"
-  - "campaign chalao"
-  # Arabic native
   - "شغّل وكلاء بالتوازي"
-  - "وزّع العمل على عدة وكلاء"
-  - "استخدم herdr"
   - "حملة إصلاح تلقائية"
-  - "موجات من الوكلاء"
-  - "وضع تلقائي"
+not-for:
+  - single-agent or single-file tasks (run directly, no herdr overhead)
+  - interactive step-through work (use /rcode-execute --interactive)
+  - deployment or push operations (herdr only commits locally)
 user-invocable: true
 ---
 
@@ -74,6 +57,16 @@ independent agents.
 
 ---
 
+## Safety — blast radius of skip-permissions agents
+
+Every orchestrated agent runs `cld` (= `claude --dangerously-skip-permissions`). There is **no human gate** on local destructive commands — an agent can `rm`, `git reset --hard`, overwrite files, or run any shell command without asking. So:
+
+- **Scope each agent prompt to its own worktree + area only.** State the worktree path and branch explicitly, and tell the agent to stay inside it.
+- **Worktree isolation is the only containment.** With permissions skipped, a per-agent git worktree is the single boundary that keeps one agent's mistakes from touching another's work or the main tree.
+- **Never point an autonomous agent at a shared or important tree** (your main checkout, a production clone, anything you can't afford to lose). Always a throwaway worktree.
+
+---
+
 ## herdr CLI reference
 
 ```bash
@@ -118,6 +111,8 @@ Full Phase 0-3 protocol, integration-branch rules, wave cadence, and anti-patter
 in **`references.md`** (sibling file). Key constraints:
 
 - Maintain one `campaign-integration` branch; sub-agents fork from it, never master.
+- Each wave agent reads `.planning/campaign/SHARED.md` first and appends a one-line claim
+  (`area — agent N — status`) so same-wave agents don't duplicate work.
 - Wave size: 3-5 agents, 10-15 min per wave. ScheduleWakeup ends EVERY turn.
 - Phase 3: show user the full diff + ask explicitly how to land (PR / merge / squash / leave).
 - Never push to origin master without an explicit yes — per campaign, not per session.

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/backlog-building.md

@@ -52,6 +52,19 @@ git commit -m "chore(campaign): backlog snapshot at wave <N>"
 ```
 The `-f` is required if `.planning/` is gitignored (common in Rihal projects).
 
+### Campaign retro (optional)
+At campaign end, append a short `.planning/campaign/RETRO.md` so the *next* campaign on this repo starts smarter:
+- Wave sizes actually used (and which felt right vs too big).
+- What stalled — areas that needed re-dispatch, conflict hotspots, agents that went silent.
+- What merged clean on the first pass.
+
+```bash
+git add -f .planning/campaign/RETRO.md
+git commit -m "chore(campaign): retro notes for next campaign"
+```
+
+**YAGNI tension (be honest)**: this is speculative tooling — a second campaign on the same repo may never happen, and a RETRO doc no one reads is exactly the kind of over-engineering Lens 16 flags. Write it only when a follow-up campaign is genuinely likely; for a one-off campaign, skip it.
+
 ## Examples
 
 ### Building backlog from audit docs

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/merge-strategy.md

@@ -27,6 +27,23 @@ fi
 ```
 **Never compound regressions across waves.**
 
+### Per-agent verification gate (beyond compile)
+A passing TSC count proves the tree compiles — it does NOT prove the agent did the work it claimed. Before merging a branch, verify **inside the worktree**:
+
+1. **Task/audit doc exists and claims the work.** The agent's `.planning/audits/AUDIT-<area>.md` (or task doc) must exist and describe what it changed. No doc → no merge.
+2. **`pnpm test` (or the project test command) passes for the affected area.** Run the scoped suite, not just the type-checker.
+3. **Lint is clean or unchanged.** Run the project linter; a new lint regression blocks the merge the same way a TSC regression does.
+4. **The diff is non-trivial and on-topic.** `git diff campaign-integration..<branch> --stat` — an empty diff, a whitespace-only diff, or edits outside the agent's area mean the agent didn't actually do the work. Reject and re-dispatch.
+
+Only after all four pass does the branch enter the smallest-first merge order.
+
+### Resolvable provenance
+A wave is NOT "verified" until each claimed change has an **openable evidence reference** — a passing test name you can run, a diff hunk you can read, a real `file:line` you can open. A self-declared boolean (`verified: true`, `confidence: 0.94`) is not provenance; it's a claim about provenance.
+
+**If provenance can't resolve, the gate FAILS** — treat the change as unverified and block the merge.
+
+Failure mode to watch for: a verifier that stamps `"verified / 94% confidence"` while its citation layer actually renders `[object Object]` has verified *nothing*. The boolean looks green; the evidence underneath is broken. Always click through to the citation — if the reference doesn't open to the thing it claims, the verification is void regardless of the confidence number.
+
 ### Conflict resolution (delegates to herdr-orchestration)
 - Content conflicts: read both sides, keep the **more-complete superset side**, remove markers, syntax-check, stage, commit. (See herdr-orchestration rules.)
 - AA conflicts (add/add): peek both versions; if nearly identical, keep the canonical owner's version. The "owner" is the branch whose audit doc claimed the feature.

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/orchestrator-rhythm.md

@@ -56,6 +56,9 @@ If the user picks (c) or skips: NEVER claim "Scheduling 20-min wakeup" in chat
 | Phase 3 (draining last waves) | 270s | Sub-agents finishing close to each other; don't miss the last |
 | Idle (waiting on stuck pane) | 1200s | Sub-agent stuck — give it room or surface it |
 
+### Cost ceiling — estimate before dispatch
+Before dispatching a wave, the orchestrator estimates `agents × wave-duration` (and, across the campaign, the running sum of all waves) as a rough cost proxy. If a planned campaign exceeds a ceiling — by default **~20 agent-waves** or any explicit token/budget cap the user gave — the orchestrator STOPS and asks the user to confirm before continuing rather than burning budget silently. A 17-wave × 4-agent campaign is ~68 agent-runs; surface that number up front so the user can scope it down.
+
 ### Stop conditions
 The heartbeat should stop ONLY when ALL three are true:
 - Every herdr pane is `idle` or `done`
@@ -96,6 +99,12 @@ If the orchestrator hits auto-compact mid-campaign, the first turn after must:
 
 ## Anti-Patterns
 
+### Pane status is text-scraping — trust it loosely
+
+**Problem**: `agent_status` (`working`/`blocked`/`idle`) is *inferred from the pane's visible text*, not a real process signal. A stuck agent — frozen mid-output, hung on a network call, or wedged in a loop — leaves its last tokens on screen and can read `working` indefinitely. A green `working` is not proof of progress.
+**Rule (timeout heuristic, now mandatory)**: if a pane reads `working` for **25 min straight**, `herdr pane read <id>` and inspect the actual output. If there's no new progress since the last peek (no new commit, same last line), `C-c` the pane and re-dispatch the item in the next wave. Do not wait out a silently-dead agent on the strength of its status string.
+**Optional reinforcement**: have each agent emit a heartbeat marker line periodically (e.g. `echo "[hb] wave-3 still alive $(date -u +%T)"`); then "no new `[hb]` line in N min" is a far more reliable stuck-signal than the scraped status.
+
 ### Polling every 60s
 
 **Problem**: Wakeup interval shorter than 270s burns the Anthropic prompt cache repeatedly without any real work happening (sub-agents need minutes between commits).

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/wave-design.md

@@ -13,6 +13,13 @@ A campaign with too few agents underuses parallelism; too many causes merge conf
 - **Maximum: 5.** Above 5 the merge stage becomes painful and TSC regressions compound across simultaneous changes.
 - **Sequential or concurrent waves?** Concurrent only if you have >8 distinct unrelated areas AND the merge bookkeeping is automated. Default is sequential: dispatch wave → merge → dispatch wave.
 
+### Shared coordination doc
+Every wave agent reads `.planning/campaign/SHARED.md` **before starting**, and appends a one-line claim the moment it picks up an area:
+```
+<area> — agent <N> — <status>
+```
+e.g. `crm-pipeline — agent 2 — claimed`. This stops two parallel agents in the same wave from silently grabbing the same area or file domain. The orchestrator seeds the file at wave dispatch; agents only append, never rewrite. Statuses progress `claimed` → `working` → `done` (or `skipped: <reason>`). If an agent finds its target area already claimed, it stops and reports back instead of duplicating work.
+
 ### Wave scope rules
 Each agent in a wave must:
 - Own a **distinct audit area** (no two agents touching the same file domain).
@@ -46,6 +53,20 @@ For each backlog item, score before assigning to a wave:
 - Past 25 min: peek at all panes, identify stuck agents, decide kill-or-wait.
 - Hard stop: 45 min. If a wave hasn't produced commits in 45 min, something is wrong — abort and re-dispatch.
 
+### Log cost per wave
+After each wave dispatch, append a one-line cost/agent-count note to `.planning/campaign/STATE.md` so the running campaign total stays visible (and the cost ceiling in `orchestrator-rhythm.md` can be checked against it):
+```
+wave 3: 4 agents dispatched, ~12 min target — running total: 11 agent-runs
+```
+
+### Optional reviewer agent
+For waves that touch **overlapping areas**, or campaigns running **more than 3 waves**, add one reviewer agent that runs *after* the wave's coders finish but *before* the merge step. The reviewer:
+- Reads all branch diffs for the wave (`git diff campaign-integration..<branch>` per branch).
+- Flags conflicts, scope drift, and duplicated work across the branches.
+- Reports to `.planning/campaign/STATE.md` (or a `REVIEW-wave-<N>.md`) — it does NOT merge.
+
+Keep it **optional**. For small bounded work (3-4 distinct, non-overlapping areas), the flat fan-out stays the default — a reviewer agent there is pure overhead. Add it only when the conflict surface or campaign length justifies the extra agent-run.
+
 ## Examples
 
 ### Good wave-1 composition (from real session)

package/rcode/skills/actions/4-implementation/rcode-scaffold-project/SKILL.md

@@ -74,6 +74,53 @@ Then proceed to `./steps/step-01-target.md`.
 | 3b | Brownfield Init | Overlay rcode structure into existing project *(brownfield only)* | `steps/step-03-brownfield.md` |
 | 4 | Post-Setup | Rename, init git, suggest next steps | `steps/step-04-post-setup.md` |
 
+## Post-Clone Checklist (Greenfield)
+
+After cloning the template and before handing off to the user, run these steps in order:
+
+### 1. pnpm-first — Install Dependencies with pnpm
+
+**Never use `npm install`.** Always install with pnpm:
+
+```bash
+corepack enable pnpm   # ensure pnpm is available via corepack
+pnpm install           # install all dependencies
+```
+
+If `package.json` contains a `packageManager` field, verify it is set to a `pnpm@x.y.z` string. If it is missing or set to `npm`, update it to `pnpm` before installing.
+
+### 2. Node.js 20+ Verification
+
+Check `.nvmrc` (if present) and the `engines.node` field in `package.json`. If either targets Node 16 or Node 18, update to `>=20.0.0`:
+
+- `.nvmrc`: change content to `20`
+- `package.json` `engines.node`: change `>=16.0.0` or `>=18.0.0` to `>=20.0.0`
+
+Report the result to the user: "Node target verified: 20+" or "Node target updated from X to 20+".
+
+### 3. Modern Dependency Check
+
+Scan the scaffolded `package.json` for known deprecated packages and flag them to the user:
+
+| Found | Suggestion |
+|-------|-----------|
+| `moment` | Replace with `date-fns` (tree-shakeable, no-timezone footgun) |
+| `axios` | Native `fetch` is available in Node 18+; only keep `axios` if fetch polyfill is needed |
+| `request` | Unmaintained — use native `fetch` or `undici` |
+
+Do **not** auto-remove these; surface the finding and let the user decide.
+
+### 4. rcode Config Scaffold
+
+After cloning, create `.rcode/config.yaml` with starter content if it does not already exist:
+
+```yaml
+project_name: "{PROJECT_NAME}"
+current_phase: 1
+```
+
+Replace `{PROJECT_NAME}` with the actual project name supplied by the user. Do not overwrite an existing `.rcode/config.yaml`.
+
 ## Design Decisions
 
 - **Always clone fresh** — never cache template locally. Template updates are free.
@@ -81,12 +128,24 @@ Then proceed to `./steps/step-01-target.md`.
 - **Safety first** — never touch a non-empty directory without user approval.
 - **Brownfield never overwrites** — in `--here` mode, existing files are never modified.
 - **Minimal assumptions** — ask before acting on any ambiguity.
+- **pnpm always** — never use npm or yarn for installs; always use pnpm via corepack.
+
+### Safety Check: What "non-empty" means
+
+A directory is considered **non-empty** (and therefore protected) if it contains **any files or directories other than**:
+- `.git/` (git metadata only)
+- `README.md` (bare readme with no project code)
+
+Everything else — including `package.json`, `src/`, `.rcode/`, `node_modules/`, dotfiles like `.env` — counts as content. If any such file is present, the safety check triggers and the user must explicitly consent before the skill proceeds.
 
 ## Output Format
 
 - New project directory scaffolded at the specified path
 - Fresh git history (template history stripped, new `git init` applied)
-- `.rcode/config.json` initialized with project name and user preferences
+- `.rcode/config.yaml` initialized with project name and current phase
+- Dependencies installed via `pnpm install`
+- Node.js target verified or updated to 20+
+- Deprecated dependency findings reported (if any)
 - Console summary: path created, files scaffolded, next steps
 
 ## Examples