@hanzlaa/rcode 3.6.16 → 4.1.0

package/rcode/references/workstream-flag.md

@@ -0,0 +1,166 @@
+# Workstream Flag — When to Use Workspace Isolation
+
+This reference explains when to use `--workspace` flag vs. sequential phases in `.planning/`.
+
+## Sequential Phases (Default)
+
+Use the standard planning pipeline (`.planning/phases/`) for:
+
+- **Linear work** — Phase 1, Phase 2, Phase 3 in order
+- **Dependent phases** — Phase 2 cannot start until Phase 1 is done
+- **Single focus** — One team/project working on one thing
+- **Milestone-driven** — All phases contribute to the same goal
+
+**Example:**
+```
+/rcode-plan Build authentication system
+/rcode-plan Add user profile pages (depends on auth from Phase 1)
+/rcode-plan Write deployment guide (depends on both phases complete)
+```
+
+These run sequentially, each depending on the previous phase's completion.
+
+## Workspace Isolation (Parallel)
+
+Use workspaces (`--workspace` flag) for:
+
+- **Parallel work** — Multiple initiatives happening at the same time
+- **Independent goals** — Each workspace has its own ROADMAP
+- **Context switching** — "I need to pause Q2 roadmap and fix critical bugs"
+- **Team separation** — Team A works on Feature X, Team B works on Feature Y
+- **Risk isolation** — "Keep the hotfix separate from experimental work"
+- **Deadline urgency** — "Fast-track this in a separate workspace while main work continues"
+
+**Example:**
+```
+# Main workspace (Q2 roadmap)
+/rcode-plan Build search feature
+
+# Parallel workspace (critical bug)
+/rcode-new-workspace Critical Hotfix
+/rcode-plan Fix data corruption --workspace=Critical Hotfix
+
+# Both run independently
+# Query progress:
+/rcode-list-workspaces
+```
+
+## Decision Matrix
+
+| Scenario | Use | Why |
+|----------|-----|-----|
+| "Build feature A then feature B then feature C" | Sequential | Linear, dependent work |
+| "Build feature A AND debug production issue simultaneously" | Workspace | Parallel, independent |
+| "Phase 2 requires Phase 1 to be 100% done first" | Sequential | Depends-on relationship |
+| "Two teams working on unrelated features" | Workspace | No dependency, separate concerns |
+| "One-sprint roadmap with 5 tasks" | Sequential | Single focused initiative |
+| "Pause roadmap, fix urgent bug, resume roadmap" | Workspace | Context switch without losing state |
+| "Research + implementation of same feature" | Sequential | Both parts of one deliverable |
+| "Experiment in parallel with stable features" | Workspace | Risk isolation |
+
+## State Management
+
+### Sequential (default)
+
+- Single `.planning/STATE.md` — tracks all phases
+- Single `.planning/ROADMAP.md` — one set of goals
+- Phases inherit context from previous phases
+
+### Workspaces (parallel)
+
+- Each workspace has its own `STATE.md`
+- Each workspace has its own `ROADMAP.md`
+- No shared context between workspaces (intentional isolation)
+
+## Switching Context
+
+### Sequential phases
+
+```bash
+# View current phase
+/rcode-status
+
+# Execute next phase
+/rcode-execute <phase>
+
+# Switch to different task within same milestone
+/rcode-quick <small task>
+```
+
+### Workspaces
+
+```bash
+# List all workspaces
+/rcode-list-workspaces
+
+# Work within a workspace
+/rcode-plan <task> --workspace=Hotfix
+
+# Switch to another workspace's context
+/rcode-workstream switch --name <name>
+
+# Return to main planning
+/rcode-workstream switch --name main
+```
+
+## Merging Workspaces Back
+
+If you started a workspace but it should merge back into main planning:
+
+1. Complete the work in the workspace
+2. Create a phase in main planning that incorporates the workspace's findings
+3. Archive the workspace: `/rcode-remove-workspace <name> --archive`
+4. Continue in main planning with unified context
+
+## Common Patterns
+
+### Pattern: Feature branch + hotfix
+
+```bash
+# Main work (Q2 roadmap)
+/rcode-plan Implement real-time notifications
+
+# Critical bug emerges
+/rcode-new-workspace Critical
+/rcode-plan Fix payment processing --workspace=Critical
+
+# Two parallel tracks
+/rcode-list-workspaces
+
+# When bug is fixed
+/rcode-complete-workspace Critical
+# Resume main work
+/rcode-execute <Q2 phase>
+```
+
+### Pattern: Research + implementation
+
+```bash
+# Sequential phases (both parts of same feature)
+/rcode-plan Research WebSocket libraries and trade-offs
+/rcode-plan Implement chosen library with tests
+# Phase 2 reads Phase 1 findings
+```
+
+### Pattern: Experimental feature
+
+```bash
+# Keep experiments separate
+/rcode-new-workspace Experiment: Dark Mode
+/rcode-plan Build dark mode UI --workspace=Experiment
+/rcode-plan Test across 10 browsers --workspace=Experiment
+
+# Main work continues unaffected
+/rcode-plan Improve search relevance
+
+# If experiment succeeds, merge into main
+# If it fails, just archive and delete
+/rcode-remove-workspace --archive Experiment
+```
+
+## Summary
+
+- **Default (sequential):** Linear work, dependencies, single focus
+- **Workspaces (parallel):** Independent initiatives, context switching, risk isolation
+- Use sequential for 95% of work
+- Reach for workspaces when you truly have parallel, independent tracks

package/rcode/skills/SKILLS_INDEX.md

@@ -0,0 +1,144 @@
+# rcode — Skills Index
+
+All 86 skills in rcode, organized by category: 23 agent skills, 38 action skills, 25 core skills, plus 2 shared modules.
+
+## Agent Skills (23)
+
+Each agent has a persona, principles, and a capabilities table that lists which action skills it can invoke.
+
+| rcode Name | Arabic | Role | Skill Path |
+|---|---|---|---|
+| **Waleed** | وليد | System Architect / CTO | `agents/waleed-architect/` |
+| **Sadiq** | صادق | Business Analyst / Strategy | `agents/sadiq-analyst/` |
+| **Hussain (PM)** | حسين | Product Manager | `agents/hussain-pm/` |
+| **Hussain (SM)** | حسين | Scrum Master | `agents/hussain-sm/` |
+| **Layla** | ليلى | UX Designer | `agents/layla-designer/` |
+| **Hanzla** | حنظلة | Senior Developer | `agents/hanzla-engineer/` |
+| **Fatima** | فاطمة | Test Architect (QA) | `agents/fatima-qa/` |
+| **Noor** | نور | Technical Writer | `agents/noor-writer/` |
+| **Ahmed Al Hassani** | أحمد الحسني | Technology & Development Director | `agents/ahmed-hassani-director/` |
+| **Haitham** | هيثم | Senior Frontend Engineer | `agents/haitham-frontend/` |
+| **Mariam** | مريم | Marketing Lead | `agents/mariam-marketing/` |
+| **Nasser** | ناصر | Engineering Manager | `agents/nasser-eng-manager/` |
+| **Yousef** | يوسف | Senior Backend Engineer | `agents/yousef-backend/` |
+| **Zahra** | زهرة | Branding & Creative Director | `agents/zahra-branding/` |
+| **Zayd** | زيد | Senior ML Engineer | `agents/zayd-ml/` |
+| **Raees** | رئيس | Orchestrator | `agents/raees-orchestrator/` |
+| **Majlis** | مجلس | Multi-Agent Council | `agents/majlis-council/` |
+| **Dalil** | دليل | Codebase Scout | `agents/dalil-scout/` |
+| **Cross-Platform Auditor** | — | Cross-Platform Auditor | `agents/rcode-cross-platform-auditor/` |
+| **Dep Auditor** | — | Dependency Health Auditor | `agents/rcode-dep-auditor/` |
+| **Deviation Analyzer** | — | Deviation Analyzer | `agents/rcode-deviation-analyzer/` |
+| **i18n Auditor** | — | i18n / L10n Auditor | `agents/rcode-i18n-auditor/` |
+| **Observability Auditor** | — | Observability Auditor | `agents/rcode-observability-auditor/` |
+
+Note: Hussain has two hats — **PM** (strategic product management) and **SM** (scrum master / sprint ops). Real teams often combine these.
+
+---
+
+## Action Skills (38)
+
+Invoked by agents via the capabilities table in their SKILL.md. Organized by SDLC phase.
+
+### 1 — Analysis (6)
+- `actions/1-analysis/research/rcode-domain-research` — domain-specific research
+- `actions/1-analysis/research/rcode-market-research` — market and competitive research
+- `actions/1-analysis/research/rcode-technical-research` — technical deep-dive research
+- `actions/1-analysis/rcode-product-brief` — write product brief
+- `actions/1-analysis/rcode-prfaq` — Amazon Working Backwards PRFAQ challenge
+- `actions/1-analysis/rcode-document-project` — document an existing codebase (brownfield)
+
+### 2 — Planning (8)
+- `actions/2-plan/rcode-create-prd` — create product requirements doc
+- `actions/2-plan/rcode-edit-prd` — edit existing PRD
+- `actions/2-plan/rcode-validate-prd` — validate PRD completeness
+- `actions/2-plan/rcode-create-ux-design` — create UX design
+- `actions/2-plan/rcode-frontend-design` — typography, colours, motion, spatial design
+- `actions/2-plan/rcode-create-epics-and-stories` — break down PRD into epics and stories
+- `actions/2-plan/rcode-create-story` — prepare a dev-ready user story
+- `actions/2-plan/rcode-create-milestone` — create milestone definition
+
+### 3 — Solutioning (3)
+- `actions/3-solutioning/rcode-create-architecture` — architectural decision record (ADR)
+- `actions/3-solutioning/rcode-check-implementation-readiness` — verify PRD/UX/arch alignment
+- `actions/3-solutioning/rcode-generate-project-context` — generate project-context.md
+
+### 4 — Implementation (21)
+- `actions/4-implementation/rcode-dev-story` — execute a story (write tests + code)
+- `actions/4-implementation/rcode-review` — comprehensive code review
+- `actions/4-implementation/rcode-qa-generate-e2e-tests` — generate e2e test suite
+- `actions/4-implementation/rcode-sprint-planning` — plan a sprint
+- `actions/4-implementation/rcode-sprint-status` — sprint status report
+- `actions/4-implementation/rcode-retrospective` — retro workflow
+- `actions/4-implementation/rcode-correct-course` — course-correction for off-track stories
+- `actions/4-implementation/rcode-scaffold-project` — scaffold new project from rcode template
+- `actions/4-implementation/rcode-checkpoint-preview` — LLM-assisted human-in-the-loop review
+- `actions/4-implementation/rcode-browser-verify` — verify browser behaviour via Chrome DevTools MCP
+- `actions/4-implementation/rcode-ci` — CI/CD setup and quality gates
+- `actions/4-implementation/rcode-debug` — root-cause debugging via the scientific method
+- `actions/4-implementation/rcode-git-flow` — branching, commits, conflicts, parallel work
+- `actions/4-implementation/rcode-harden` — security hardening checklist for SaaS apps
+- `actions/4-implementation/rcode-incremental` — ship code in small, atomic, verifiable steps
+- `actions/4-implementation/rcode-migrate` — move from MVP to production-grade infrastructure
+- `actions/4-implementation/rcode-perf` — performance optimisation (LCP / TBT / CLS / hydration)
+- `actions/4-implementation/rcode-prove-it` — test-first development
+- `actions/4-implementation/rcode-source-truth` — cite official docs before writing framework code
+- `actions/4-implementation/rcode-trim` — code simplification
+- `actions/4-implementation/rcode-herdr-orchestration` — orchestrate parallel cld agents in herdr; single-shot fan-out OR long-running autonomous wave-based fix campaign with durable backlog + integration branch + heartbeat
+
+---
+
+## Core Skills (25)
+
+Shared utilities used across agents and workflows.
+
+- `core/rcode-init` — INTERNAL config loader (installs to .rcode/skills/, not .claude/skills/)
+- `core/rcode-help` — meta-help on available skills
+- `core/rcode-brainstorming` — structured brainstorming workflow
+- `core/rcode-advanced-elicitation` — advanced requirements elicitation
+- `core/rcode-distillator` — distill information into concise summaries
+- `core/rcode-index-docs` — index documentation for search
+- `core/rcode-shard-doc` — shard large documents into linked sections
+- `core/rcode-clone-website` — reverse-engineer and clone a website
+- `core/rcode-editorial-review-prose` — editorial review for prose quality
+- `core/rcode-editorial-review-structure` — editorial review for structural quality
+- `core/rcode-review-adversarial-general` — adversarial review for robustness
+- `core/rcode-review-edge-case-hunter` — edge case hunting and boundary testing
+- `core/rcode-party-mode` — multi-agent collaboration mode
+- `core/rcode-auth-audit` — audit Keycloak ↔ AD sync, JWT validation, tenant isolation
+- `core/rcode-client-gate` — client requirement freeze gates and async-comm patterns
+- `core/rcode-deploy-unify` — detect and unify multiple deployment paths
+- `core/rcode-incident-record` — generate a change record + post-mortem
+- `core/rcode-memory-init` — bootstrap the Memory Bank for a project
+- `core/rcode-memory-update` — surgical update of specific Memory Bank files
+- `core/rcode-memory-audit` — audit the Memory Bank for stale entries and contradictions
+- `core/rcode-memory-distill` — regenerate token-optimised Memory Bank distillates
+- `core/rcode-mvp-graduate` — move an MVP to production-grade infrastructure incrementally
+- `core/rcode-ocr-consistency` — OCR pipeline determinism + ground-truth validation
+- `core/rcode-rebrand` — stack-wide rebranding migration
+- `core/rcode-theme-system` — audit a frontend's design tokens before launch
+
+---
+
+## How Skills Work
+
+1. **Agent skills** give a persona and list capabilities
+2. **Action skills** are the actual capabilities that do work
+3. **Core skills** are shared utilities
+
+Agents reference actions by their skill name in their Capabilities table:
+
+```markdown
+| Code | Description | Skill |
+|------|-------------|-------|
+| DS | Write the next story's tests and code | rcode-dev-story |
+| CR | Comprehensive code review | rcode-review |
+```
+
+When a user picks capability `DS`, Claude invokes the `rcode-dev-story` skill.
+
+---
+
+## Licensing
+
+Free to use and adapt.

package/rcode/skills/_shared/no-autonomous-bypass.md

@@ -0,0 +1,37 @@
+# No Autonomous-Mode Bypass
+
+This fragment is referenced by every step-file workflow that enforces halt-at-menu. Do not inline its contents into individual step files — reference this file so the rule stays single-sourced.
+
+## The Rule
+
+Step-file skills (`rcode-create-prd`, `rcode-sprint-planning`, `rcode-create-epics-and-stories`, etc.) halt at every menu and wait for user input. **This is invariant.** The agent MUST NOT invent an "autonomous mode", "research mode", or any other self-declared bypass that skips discovery questions.
+
+Phrases like *"just write it autonomously"*, *"create the full thing ready to execute"*, *"skip the questions"*, or *"use research mode"* from the user are **not** authorization to bypass halt. They are signals that the user wants the skill to move efficiently — answer by running the next step's questions compactly, not by skipping them.
+
+## The Only Sanctioned Bypass Paths
+
+There are exactly two ways to legitimately run a skill without halting at menus:
+
+1. **Project-wide:** `.rcode/config.yaml` → `mode: yolo`. The config loader flags `yoloMode=true` in the runtime context; step files check this flag and may auto-advance.
+2. **Per-invocation:** `/rcode-do --auto <question>` on the router. The router sets `autoMode=true` and passes it to the dispatched skill.
+
+If **neither** flag is set, halt is mandatory regardless of what the user's prompt text says.
+
+## Required Behavior When Asked to Bypass Without a Flag
+
+1. Acknowledge the user's intent in one sentence.
+2. Show the current step's menu anyway.
+3. Tell the user the two sanctioned paths (config flag or `--auto`) if they want fully hands-off execution.
+4. Do not generate any output artifact (PRD, sprint plan, roadmap, etc.) until the user either selects a menu option or sets one of the sanctioned flags.
+
+## Anti-Example (What NOT to Do)
+
+> User: *"use rcode research skills and create best PRD ready to execute"*
+>
+> ❌ Agent: *"Switching to autonomous mode — researching the domain and drafting a complete execution-ready PRD."* *(then writes full PRD)*
+
+That response invents a mode that does not exist and violates the halt invariant.
+
+## Correct Response
+
+> ✅ Agent: *"I hear you want the PRD written end-to-end. The halt rule applies unless you set `mode: yolo` in `.rcode/config.yaml` or re-invoke via `/rcode-do --auto`. Here is the step-01 menu — pick Continue and I will drive each step concisely."*

package/rcode/skills/_shared/research-citation-rule.md

@@ -0,0 +1,39 @@
+# Research & Citation Rule
+
+Referenced by any step-file workflow that writes content derived from external sources (competitor pricing, API tiers, market sizing, benchmark numbers, vendor claims, etc.).
+
+## The Rule
+
+If an output artifact (PRD, research note, architecture doc, roadmap) contains a specific external claim — a price, a percentage, a named competitor feature, an API limit — then **every such claim must be traceable to a `WebFetch` (or equivalent document-fetch) call made in the same session**. `WebSearch` snippets alone are not sufficient evidence because snippets are paraphrased and may be stale.
+
+## What This Means in Practice
+
+Before writing a claim like *"Competitor X costs $12.50/mo"*:
+
+1. Run `WebFetch` on the source URL (not just `WebSearch` for a snippet).
+2. Quote the exact sentence from the fetched content in your internal reasoning.
+3. Include the URL in the citations block of the artifact.
+4. If the URL is paywalled, login-walled, or returns a different claim than expected, drop the number — do not paraphrase from memory or search-result previews.
+
+## The Trap to Avoid
+
+Observed failure pattern (rcode session, social-poster-x PRD generation):
+
+- Agent ran two `WebSearch` calls.
+- Agent wrote a PRD citing four specific URLs with specific dollar amounts.
+- Agent never ran `WebFetch` on any of the four URLs.
+- Numbers may be accurate-looking hallucinations.
+
+This pattern is forbidden. A citation block without `WebFetch` evidence is a lie to the reader.
+
+## If the User Is Running Autonomously
+
+`mode: yolo` and `/rcode-do --auto` bypass halt-at-menu, but they do **not** bypass this rule. A fully-autonomous run still has to fetch every cited URL before writing the claim.
+
+## Checklist Before Writing a Citation
+
+- [ ] `WebFetch` was called on this URL in this session.
+- [ ] The fetched content contains the specific number / claim being cited.
+- [ ] The claim in the artifact matches the fetched content verbatim (or is a clearly labeled summary).
+
+If any box is unchecked: remove the claim, replace with *"(needs source)"*, and flag to the user.

package/rcode/skills/_shared/state-sync-rule.md

@@ -0,0 +1,43 @@
+# State Sync Rule
+
+Referenced by skills that write `ROADMAP.md`, `epics.md`, or sprint artifacts. These artifacts are not authoritative on their own — downstream workflows (`/rcode-status`, `/rcode-progress`, `/rcode-execute`) read `.rcode/state.json`. If you write a planning artifact and skip state sync, the project ends up with two divergent pictures.
+
+## The Rule
+
+Immediately after appending content to any of:
+
+- `.planning/ROADMAP.md` — milestones and phases
+- `.planning/epics.md` — epics and stories
+- `.rcode/phases/{phase}/sprint-{N}.md` — sprint commitments
+
+Call the state-sync helper:
+
+```bash
+node .rcode/bin/rcode-tools.cjs state sync --from-disk
+```
+
+or, for a more targeted write, use the JSON-API helpers exposed by `rcode-tools.cjs`:
+
+```bash
+node .rcode/bin/rcode-tools.cjs state upsert-milestone <json>
+node .rcode/bin/rcode-tools.cjs state upsert-phase <json>
+node .rcode/bin/rcode-tools.cjs state upsert-epic <json>
+```
+
+If `rcode-tools.cjs` does not yet expose the needed subcommand, fall back to `state sync --from-disk` which re-parses `ROADMAP.md` + `epics.md` and rebuilds the relevant sections of `state.json`.
+
+## Verification After Sync
+
+- `node .rcode/bin/rcode-tools.cjs state read` returns a phase count that matches the phase table in `ROADMAP.md`.
+- `/rcode-status` and `/rcode-progress`, run back-to-back, agree on the current milestone name and phase count.
+
+## Why This Matters
+
+Observed failure (rcode, social-poster-x install, Apr 2026):
+
+- User ran `/rcode-create-epics-and-stories`.
+- `ROADMAP.md` gained 10 phases; `epics.md` gained 62 stories.
+- `.rcode/state.json` remained at the initial bootstrap with 1 phase.
+- `/rcode-status` showed 1 phase; `/rcode-progress` showed 10.
+
+That divergence is what this rule exists to prevent.

package/rcode/skills/actions/1-analysis/rcode-document-project/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: rcode-document-project
+internal: true
+description: >
+  Analyze an existing codebase and produce documentation for both human and
+  LLM consumption (brownfield analysis). Activates when the user says
+  "document this project", "analyze this codebase", "generate docs for
+  existing code", "brownfield analysis", or "create LLM-friendly docs". Do
+  NOT use for writing net-new docs (use write-document prompt).
+triggers:
+  - "document this project"
+  - "analyze this codebase"
+  - "generate docs for
+  existing code"
+  - "brownfield analysis"
+  - "create LLM-friendly docs"
+user-invocable: true
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+## Overview
+
+Analyze an existing codebase and produce documentation for both human and LLM consumption (brownfield analysis).
+
+## Workflow
+
+Follow the instructions in ./workflow.md.
+
+## When NOT to use this skill
+
+Do NOT use for writing net-new documentation from scratch (use a write-document prompt).
+Do NOT invoke when the user wants to document a single file or function — scope this skill
+to whole-codebase or whole-module brownfield analysis only.
+
+## Output Format
+
+- Produces multi-file documentation: README summary, ARCHITECTURE.md, CONVENTIONS.md, project-context.md
+- Scans code to detect actual patterns (not what docs claim)
+- Do NOT fabricate patterns not present in code
+- Do NOT skip sections — if data is missing, flag it explicitly
+
+## Examples
+
+### Happy Path
+**Input:** "Document this repo"
+**Expected behavior:** Scan repo structure, detect stack, identify patterns, produce multi-file docs with actual findings.
+
+### Edge Case: Inconsistent Patterns
+**Input:** (codebase has multiple competing patterns)
+**Expected behavior:** Document each pattern with location and flag the inconsistency for the team to resolve.

package/rcode/skills/actions/1-analysis/rcode-document-project/templates/index-template.md

@@ -0,0 +1,169 @@
+# {{project_name}} Documentation Index
+
+**Type:** {{repository_type}}{{#if is_multi_part}} with {{parts_count}} parts{{/if}}
+**Primary Language:** {{primary_language}}
+**Architecture:** {{architecture_type}}
+**Last Updated:** {{date}}
+
+## Project Overview
+
+{{project_description}}
+
+{{#if is_multi_part}}
+
+## Project Structure
+
+This project consists of {{parts_count}} parts:
+
+{{#each project_parts}}
+
+### {{part_name}} ({{part_id}})
+
+- **Type:** {{project_type}}
+- **Location:** `{{root_path}}`
+- **Tech Stack:** {{tech_stack_summary}}
+- **Entry Point:** {{entry_point}}
+  {{/each}}
+
+## Cross-Part Integration
+
+{{integration_summary}}
+
+{{/if}}
+
+## Quick Reference
+
+{{#if is_single_part}}
+
+- **Tech Stack:** {{tech_stack_summary}}
+- **Entry Point:** {{entry_point}}
+- **Architecture Pattern:** {{architecture_pattern}}
+- **Database:** {{database}}
+- **Deployment:** {{deployment_platform}}
+  {{else}}
+  {{#each project_parts}}
+
+### {{part_name}} Quick Ref
+
+- **Stack:** {{tech_stack_summary}}
+- **Entry:** {{entry_point}}
+- **Pattern:** {{architecture_pattern}}
+  {{/each}}
+  {{/if}}
+
+## Generated Documentation
+
+### Core Documentation
+
+- [Project Overview](./project-overview.md) - Executive summary and high-level architecture
+- [Source Tree Analysis](./source-tree-analysis.md) - Annotated directory structure
+
+{{#if is_single_part}}
+
+- [Architecture](./architecture.md) - Detailed technical architecture
+- [Component Inventory](./component-inventory.md) - Catalog of major components{{#if has_ui_components}} and UI elements{{/if}}
+- [Development Guide](./development-guide.md) - Local setup and development workflow
+  {{#if has_api_docs}}- [API Contracts](./api-contracts.md) - API endpoints and schemas{{/if}}
+  {{#if has_data_models}}- [Data Models](./data-models.md) - Database schema and models{{/if}}
+  {{else}}
+
+### Part-Specific Documentation
+
+{{#each project_parts}}
+
+#### {{part_name}} ({{part_id}})
+
+- [Architecture](./architecture-{{part_id}}.md) - Technical architecture for {{part_name}}
+  {{#if has_components}}- [Components](./component-inventory-{{part_id}}.md) - Component catalog{{/if}}
+- [Development Guide](./development-guide-{{part_id}}.md) - Setup and dev workflow
+  {{#if has_api}}- [API Contracts](./api-contracts-{{part_id}}.md) - API documentation{{/if}}
+  {{#if has_data}}- [Data Models](./data-models-{{part_id}}.md) - Data architecture{{/if}}
+  {{/each}}
+
+### Integration
+
+- [Integration Architecture](./integration-architecture.md) - How parts communicate
+- [Project Parts Metadata](./project-parts.json) - Machine-readable structure
+  {{/if}}
+
+### Optional Documentation
+
+{{#if has_deployment_guide}}- [Deployment Guide](./deployment-guide.md) - Deployment process and infrastructure{{/if}}
+{{#if has_contribution_guide}}- [Contribution Guide](./contribution-guide.md) - Contributing guidelines and standards{{/if}}
+
+## Existing Documentation
+
+{{#if has_existing_docs}}
+{{#each existing_docs}}
+
+- [{{title}}]({{path}}) - {{description}}
+  {{/each}}
+  {{else}}
+  No existing documentation files were found in the project.
+  {{/if}}
+
+## Getting Started
+
+{{#if is_single_part}}
+
+### Prerequisites
+
+{{prerequisites}}
+
+### Setup
+
+```bash
+{{setup_commands}}
+```
+
+### Run Locally
+
+```bash
+{{run_commands}}
+```
+
+### Run Tests
+
+```bash
+{{test_commands}}
+```
+
+{{else}}
+{{#each project_parts}}
+
+### {{part_name}} Setup
+
+**Prerequisites:** {{prerequisites}}
+
+**Install & Run:**
+
+```bash
+cd {{root_path}}
+{{setup_command}}
+{{run_command}}
+```
+
+{{/each}}
+{{/if}}
+
+## For AI-Assisted Development
+
+This documentation was generated specifically to enable AI agents to understand and extend this codebase.
+
+### When Planning New Features:
+
+**UI-only features:**
+{{#if is_multi_part}}→ Reference: `architecture-{{ui_part_id}}.md`, `component-inventory-{{ui_part_id}}.md`{{else}}→ Reference: `architecture.md`, `component-inventory.md`{{/if}}
+
+**API/Backend features:**
+{{#if is_multi_part}}→ Reference: `architecture-{{api_part_id}}.md`, `api-contracts-{{api_part_id}}.md`, `data-models-{{api_part_id}}.md`{{else}}→ Reference: `architecture.md`{{#if has_api_docs}}, `api-contracts.md`{{/if}}{{#if has_data_models}}, `data-models.md`{{/if}}{{/if}}
+
+**Full-stack features:**
+→ Reference: All architecture docs{{#if is_multi_part}} + `integration-architecture.md`{{/if}}
+
+**Deployment changes:**
+{{#if has_deployment_guide}}→ Reference: `deployment-guide.md`{{else}}→ Review CI/CD configs in project{{/if}}
+
+---
+
+_Documentation generated by rcode `document-project` workflow_