@hanzlaa/rcode 3.6.15 → 4.0.0

package/rcode/skills/actions/2-plan/rcode-edit-prd/workflow.md

@@ -0,0 +1,63 @@
+---
+main_config: '{project-root}/.rcode/config.json'
+---
+
+# PRD Edit Workflow
+
+**Goal:** Edit and improve existing PRDs through structured enhancement workflow.
+
+**Your Role:** PRD improvement specialist.
+
+You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from {main_config} and resolve:
+
+- `project_name`, `output_folder`, `planning_artifacts`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as system-generated current datetime
+
+✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`.
+✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`.
+
+### 2. Route to Edit Workflow
+
+"**Edit Mode: Improving an existing PRD.**"
+
+Prompt for PRD path: "Which PRD would you like to edit? Please provide the path to the PRD.md file."
+
+Then read fully and follow: `./steps-e/step-e-01-discovery.md`

package/rcode/skills/actions/2-plan/rcode-frontend-design/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: rcode-frontend-design
+internal: true
+description: >
+  Create distinctive, production-grade frontend interfaces with a committed
+  aesthetic direction — typography, colour, motion, spatial composition,
+  backgrounds, visual details — that avoid generic "AI slop". Activates when
+  the user says "design this UI", "build a beautiful frontend", "distinctive
+  design", "creative UI", "unforgettable interface", "award-winning design",
+  "not generic", "bold aesthetic", "brutalist", "editorial", "maximalist",
+  "minimalist luxury", "design a landing page", "standout hero section",
+  "make this look amazing", or "frontend design". Pairs with rcode-clone-website
+  (for copying) and rcode-agent-zahra (branding). Do NOT use for: cloning
+  existing sites (use rcode-clone-website), pure backend, or documentation.
+triggers:
+  - "AI slop"
+  - "design this UI"
+  - "build a beautiful frontend"
+  - "distinctive design"
+  - "creative UI"
+  - "unforgettable interface"
+  - "award-winning design"
+  - "not generic"
+  - "bold aesthetic"
+  - "brutalist"
+  - "editorial"
+  - "maximalist"
+license: Adapted from Anthropic's frontend-design skill
+user-invocable: true
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+## Overview
+
+Builds **original** frontend interfaces with a committed aesthetic direction. Goal: interfaces someone actually remembers. Different from `rcode-clone-website` (which replicates existing sites pixel-for-pixel). Pairs with `rcode-agent-zahra` for brand alignment. Detailed aesthetic guidelines, type pair recommendations, "what to avoid" list, and rcode-specific RTL guidance live in [`references.md`](references.md).
+
+## Design Thinking — commit before coding
+
+Before writing any code, lock these:
+
+- **Purpose** — what problem does this UI solve? Who uses it?
+- **Tone** — pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic, luxury-refined, playful, editorial, brutalist, art-deco, soft pastel, industrial, Omani-modern. **Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.**
+- **Constraints** — framework, performance, accessibility, Arabic RTL support.
+- **Differentiation** — what's the one thing someone will remember?
+
+Then implement code that is production-grade, visually striking, cohesive, refined in detail, and bilingual-ready (RTL from day one for rcode work).
+
+## Workflow
+
+1. **Understand context** — ask about purpose, audience, constraints, brand alignment.
+2. **Commit to a direction** — state the aesthetic in one sentence before writing code.
+3. **Check brand alignment** — if rcode branding matters, invoke Zahra (`rcode-agent-zahra`) for brand tokens.
+4. **Select type pair** — display + body, with Arabic companion if bilingual.
+5. **Define colour system** — dominant + accents, not a rainbow.
+6. **Design motion choreography** — what animates when, what's the hero moment.
+7. **Implement with precision** — every detail refined, every pixel intentional.
+8. **Verify at all viewports** — desktop, tablet, mobile, RTL.
+9. **Stress-test content** — long names, empty states, error states, loading states.
+
+## Output Format
+
+- Markdown explanation + fenced code blocks (language-tagged)
+- Start with a one-sentence aesthetic statement before any code
+- Show complete files, not fragments
+- React / Next.js: Server Components by default, Client Components only when needed
+- Tailwind: custom config extensions, not raw class spam
+- CSS: variables for tokens
+
+Do NOT include: Inter or Space Grotesk as default fonts, generic purple/blue gradients, centred cookie-cutter layouts, "looks fine" designs, undifferentiated shadcn/ui. Do NOT ship without a specified type pair, colour system, and motion direction.
+
+## Examples
+
+**Happy path — original landing**
+"Design a landing page for an Omani heritage tourism startup" → aesthetic: "editorial-magazine with Islamic geometric motifs, warm desert palette, slow cinematic type reveals" → type pair GT Sectra Display + Tajawal → colours `#2C1810 / #D4A574 / #0F3B3C / #F5EFE0` → hero h1 staggered per-word → asymmetric grid → Arabic RTL mirrored → complete Next.js + Tailwind code.
+
+**Happy path — dashboard**
+"Ministry of Energy analytics dashboard" → "authoritative Omani-modern, deep navy + desert gold, IBM Plex for gravitas, zero playfulness" → IBM Plex Sans + Arabic → restrained motion → dense grid → AAA contrast + keyboard navigation.
+
+**Edge case — brand conflict**
+"Build a playful colourful landing for a rcode government client" → flag the conflict. Government audiences expect restraint. Offer alternatives or invoke Zahra to verify brand fit.
+
+**Edge case — generic request**
+"Design a landing page, modern and clean" — refuse. Ask the user to pick an extreme or describe a site they love.
+
+**Negative — wrong skill**
+"Clone https://linear.app" → cloning is `rcode-clone-website`'s job, redirect.
+
+## Memory Bank Hooks
+
+- **Reads:** `.rcode/memory/project/stack.md` (frontend framework), brand tokens from Zahra if available
+- **Writes:** the implemented frontend files; consider noting design system choices in `.rcode/memory/project/decisions.md`
+
+## Detailed reference
+
+See [`references.md`](references.md) for: typography pairings (Latin + Arabic), colour philosophy, motion principles, spatial composition rules, the "what to avoid" list, and rcode-specific RTL + government-client guidelines.

package/rcode/skills/actions/2-plan/rcode-frontend-design/references.md

@@ -0,0 +1,79 @@
+# Frontend Design — Detailed Reference
+
+Detailed aesthetic guidelines for [`SKILL.md`](SKILL.md).
+
+---
+
+## Typography
+
+Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt for distinctive, characterful choices that elevate the frontend's aesthetics. Pair a distinctive display font with a refined body font.
+
+For rcode / Omani work, consider Latin + Arabic pairs that work together:
+
+**Latin display & body:** PP Neue Montreal, IBM Plex, Söhne, Editorial New, GT Sectra, Tiempos, Recoleta.
+**Arabic companions:** IBM Plex Arabic, Adelle Sans Arabic, Readex Pro, Tajawal, Cairo, El Messiri, Noto Naskh Arabic.
+
+---
+
+## Colour & theme
+
+Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colours with sharp accents outperform timid, evenly-distributed palettes.
+
+rcode's official palette (when brand alignment matters): rcode blue `#1e3a8a`, gold `#f59e0b`. For original work, use these as optional anchors — don't force them.
+
+---
+
+## Motion
+
+Use animation for effects and micro-interactions. Prioritise CSS-only solutions for HTML; use Motion library for React when available. Focus on high-impact moments: **one well-orchestrated page load with staggered reveals (`animation-delay`) creates more delight than scattered micro-interactions.** Use scroll-triggering and hover states that surprise.
+
+---
+
+## Spatial composition
+
+Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density — pick a philosophy and execute it.
+
+---
+
+## Backgrounds & visual details
+
+Create atmosphere and depth instead of defaulting to solid colours. Add contextual effects and textures that match the aesthetic: gradient meshes, noise textures, geometric patterns (Islamic geometric art fits well for Omani work), layered transparencies, dramatic shadows, decorative borders, custom cursors, grain overlays.
+
+---
+
+## What to avoid
+
+Never use generic AI-generated aesthetics:
+
+- Overused fonts: Inter, Roboto, Arial, system fonts. **Space Grotesk is extremely overused — never use as default.**
+- Clichéd colour schemes: purple gradients on white, "AI blue" defaults.
+- Predictable layouts: hero + three-column features + CTA.
+- Cookie-cutter Tailwind defaults without customisation.
+- Cookie-cutter shadcn/ui without restyling.
+- Centred stacks with identical spacing.
+- Emoji as primary visual element.
+
+**Interpret creatively.** Make unexpected choices that feel genuinely designed for the context. No two designs should be the same. Vary between light and dark, fonts, aesthetics. **Never converge on common choices across generations.**
+
+---
+
+## Implementation philosophy
+
+Match implementation complexity to the aesthetic vision:
+- Maximalist designs need elaborate code with extensive animations and effects.
+- Minimalist or refined designs need restraint, precision, careful attention to spacing, typography, subtle details.
+- Elegance comes from executing the vision well, not from decorating a weak idea.
+
+Don't hold back — show what can be created when committing fully to a distinctive vision.
+
+---
+
+## rcode-specific guidelines
+
+When designing for rcode (government clients, enterprise dashboards, Arabic audiences):
+
+1. **RTL is foundational, not retrofitted.** Use logical CSS properties (`padding-inline-start`, not `padding-left`) from day one.
+2. **Arabic typography needs different scale.** Arabic glyphs are visually denser; bump line-height +10%, let letter-spacing breathe.
+3. **Cultural context.** Islamic geometric patterns; Omani colours (desert sand, turquoise, gold, deep blue); bilingual parity — not token gestures.
+4. **Government dashboards** favour authoritative restraint over playful chaos. Enterprise dashboards can be more confident.
+5. **Never compromise accessibility** for aesthetic impact. WCAG AA minimum, AAA where feasible.

package/rcode/skills/actions/2-plan/rcode-validate-prd/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: rcode-validate-prd
+internal: true
+description: >
+  Validate an existing PRD for comprehensiveness, leanness, organization,
+  and internal consistency. Activates when the user says "validate the PRD",
+  "review the PRD", "check the PRD", "is the PRD ready", "PRD quality
+  check", or "audit the PRD". Do NOT use to create or edit a PRD.
+triggers:
+  - "validate the PRD"
+  - "review the PRD"
+  - "check the PRD"
+  - "is the PRD ready"
+  - "PRD quality
+  check"
+  - "audit the PRD"
+user-invocable: true
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+## Overview
+
+Validate an existing PRD for comprehensiveness, leanness, organization, and internal consistency.
+
+## Workflow
+
+Follow the instructions in ./workflow.md.
+
+## Output Format
+
+- Produces a validation report with severity per issue: Critical / Warning / Info
+- Report table: Section | Issue | Severity | Suggested Fix
+- Final verdict: READY / NEEDS REVISION / REWRITE
+- Do NOT silently fix issues — report them for the user to decide
+
+## Examples
+
+### Happy Path
+**Input:** "Validate the PRD at .rcode/phases/phase-02/prd.md"
+**Expected behavior:** Read PRD, check against rubric (problem clarity, measurable success, explicit scope, kill criteria, owner attribution), produce report, deliver verdict.
+
+### Edge Case: PRD Missing Sections
+**Input:** (PRD is missing Kill Criteria section)
+**Expected behavior:** Report as Critical: "Missing Kill Criteria section. Without this, the project has no exit strategy. Recommended fix: [template snippet]."

package/rcode/skills/actions/2-plan/rcode-validate-prd/data/prd-purpose.md

@@ -0,0 +1,197 @@
+# rcode PRD Purpose
+
+**The PRD is the top of the required funnel that feeds all subsequent product development work in rhw rcode.**
+
+---
+
+## What is a rcode PRD?
+
+A dual-audience document serving:
+1. **Human Product Managers and builders** - Vision, strategy, stakeholder communication
+2. **LLM Downstream Consumption** - UX Design → Architecture → Epics → Development AI Agents
+
+Each successive document becomes more AI-tailored and granular.
+
+---
+
+## Core Philosophy: Information Density
+
+**High Signal-to-Noise Ratio**
+
+Every sentence must carry information weight. LLMs consume precise, dense content efficiently.
+
+**Anti-Patterns (Eliminate These):**
+- ❌ "The system will allow users to..." → ✅ "Users can..."
+- ❌ "It is important to note that..." → ✅ State the fact directly
+- ❌ "In order to..." → ✅ "To..."
+- ❌ Conversational filler and padding → ✅ Direct, concise statements
+
+**Goal:** Maximum information per word. Zero fluff.
+
+---
+
+## The Traceability Chain
+
+**PRD starts the chain:**
+```
+Vision → Success Criteria → User Journeys → Functional Requirements → (future: User Stories)
+```
+
+**In the PRD, establish:**
+- Vision → Success Criteria alignment
+- Success Criteria → User Journey coverage
+- User Journey → Functional Requirement mapping
+- All requirements traceable to user needs
+
+**Why:** Each downstream artifact (UX, Architecture, Epics, Stories) must trace back to documented user needs and business objectives. This chain ensures we build the right thing.
+
+---
+
+## What Makes Great Functional Requirements?
+
+### FRs are Capabilities, Not Implementation
+
+**Good FR:** "Users can reset their password via email link"
+**Bad FR:** "System sends JWT via email and validates with database" (implementation leakage)
+
+**Good FR:** "Dashboard loads in under 2 seconds for 95th percentile"
+**Bad FR:** "Fast loading time" (subjective, unmeasurable)
+
+### SMART Quality Criteria
+
+**Specific:** Clear, precisely defined capability
+**Measurable:** Quantifiable with test criteria
+**Attainable:** Realistic within constraints
+**Relevant:** Aligns with business objectives
+**Traceable:** Links to source (executive summary or user journey)
+
+### FR Anti-Patterns
+
+**Subjective Adjectives:**
+- ❌ "easy to use", "intuitive", "user-friendly", "fast", "responsive"
+- ✅ Use metrics: "completes task in under 3 clicks", "loads in under 2 seconds"
+
+**Implementation Leakage:**
+- ❌ Technology names, specific libraries, implementation details
+- ✅ Focus on capability and measurable outcomes
+
+**Vague Quantifiers:**
+- ❌ "multiple users", "several options", "various formats"
+- ✅ "up to 100 concurrent users", "3-5 options", "PDF, DOCX, TXT formats"
+
+**Missing Test Criteria:**
+- ❌ "The system shall provide notifications"
+- ✅ "The system shall send email notifications within 30 seconds of trigger event"
+
+---
+
+## What Makes Great Non-Functional Requirements?
+
+### NFRs Must Be Measurable
+
+**Template:**
+```
+"The system shall [metric] [condition] [measurement method]"
+```
+
+**Examples:**
+- ✅ "The system shall respond to API requests in under 200ms for 95th percentile as measured by APM monitoring"
+- ✅ "The system shall maintain 99.9% uptime during business hours as measured by cloud provider SLA"
+- ✅ "The system shall support 10,000 concurrent users as measured by load testing"
+
+### NFR Anti-Patterns
+
+**Unmeasurable Claims:**
+- ❌ "The system shall be scalable" → ✅ "The system shall handle 10x load growth through horizontal scaling"
+- ❌ "High availability required" → ✅ "99.9% uptime as measured by cloud provider SLA"
+
+**Missing Context:**
+- ❌ "Response time under 1 second" → ✅ "API response time under 1 second for 95th percentile under normal load"
+
+---
+
+## Domain-Specific Requirements
+
+**Auto-Detect and Enforce Based on Project Context**
+
+Certain industries have mandatory requirements that must be present:
+
+- **Healthcare:** HIPAA Privacy & Security Rules, PHI encryption, audit logging, MFA
+- **Fintech:** PCI-DSS Level 1, AML/KYC compliance, SOX controls, financial audit trails
+- **GovTech:** NIST framework, Section 508 accessibility (WCAG 2.1 AA), FedRAMP, data residency
+- **E-Commerce:** PCI-DSS for payments, inventory accuracy, tax calculation by jurisdiction
+
+**Why:** Missing these requirements in the PRD means they'll be missed in architecture and implementation, creating expensive rework. During PRD creation there is a step to cover this - during validation we want to make sure it was covered. For this purpose steps will utilize a domain-complexity.csv and project-types.csv.
+
+---
+
+## Document Structure (Markdown, Human-Readable)
+
+### Required Sections
+1. **Executive Summary** - Vision, differentiator, target users
+2. **Success Criteria** - Measurable outcomes (SMART)
+3. **Product Scope** - MVP, Growth, Vision phases
+4. **User Journeys** - Comprehensive coverage
+5. **Domain Requirements** - Industry-specific compliance (if applicable)
+6. **Innovation Analysis** - Competitive differentiation (if applicable)
+7. **Project-Type Requirements** - Platform-specific needs
+8. **Functional Requirements** - Capability contract (FRs)
+9. **Non-Functional Requirements** - Quality attributes (NFRs)
+
+### Formatting for Dual Consumption
+
+**For Humans:**
+- Clear, professional language
+- Logical flow from vision to requirements
+- Easy for stakeholders to review and approve
+
+**For LLMs:**
+- ## Level 2 headers for all main sections (enables extraction)
+- Consistent structure and patterns
+- Precise, testable language
+- High information density
+
+---
+
+## Downstream Impact
+
+**How the PRD Feeds Next Artifacts:**
+
+**UX Design:**
+- User journeys → interaction flows
+- FRs → design requirements
+- Success criteria → UX metrics
+
+**Architecture:**
+- FRs → system capabilities
+- NFRs → architecture decisions
+- Domain requirements → compliance architecture
+- Project-type requirements → platform choices
+
+**Epics & Stories (created after architecture):**
+- FRs → user stories (1 FR could map to 1-3 stories potentially)
+- Acceptance criteria → story acceptance tests
+- Priority → sprint sequencing
+- Traceability → stories map back to vision
+
+**Development AI Agents:**
+- Precise requirements → implementation clarity
+- Test criteria → automated test generation
+- Domain requirements → compliance enforcement
+- Measurable NFRs → performance targets
+
+---
+
+## Summary: What Makes a Great rcode PRD?
+
+✅ **High Information Density** - Every sentence carries weight, zero fluff
+✅ **Measurable Requirements** - All FRs and NFRs are testable with specific criteria
+✅ **Clear Traceability** - Each requirement links to user need and business objective
+✅ **Domain Awareness** - Industry-specific requirements auto-detected and included
+✅ **Zero Anti-Patterns** - No subjective adjectives, implementation leakage, or vague quantifiers
+✅ **Dual Audience Optimized** - Human-readable AND LLM-consumable
+✅ **Markdown Format** - Professional, clean, accessible to all stakeholders
+
+---
+
+**Remember:** The PRD is the foundation. Quality here ripples through every subsequent phase. A dense, precise, well-traced PRD makes UX design, architecture, epic breakdown, and AI development dramatically more effective.

package/rcode/skills/actions/2-plan/rcode-validate-prd/data/project-types.csv

@@ -0,0 +1,11 @@
+project_type,detection_signals,key_questions,required_sections,skip_sections,web_search_triggers,innovation_signals
+api_backend,"API,REST,GraphQL,backend,service,endpoints","Endpoints needed?;Authentication method?;Data formats?;Rate limits?;Versioning?;SDK needed?","endpoint_specs;auth_model;data_schemas;error_codes;rate_limits;api_docs","ux_ui;visual_design;user_journeys","framework best practices;OpenAPI standards","API composition;New protocol"
+mobile_app,"iOS,Android,app,mobile,iPhone,iPad","Native or cross-platform?;Offline needed?;Push notifications?;Device features?;Store compliance?","platform_reqs;device_permissions;offline_mode;push_strategy;store_compliance","desktop_features;cli_commands","app store guidelines;platform requirements","Gesture innovation;AR/VR features"
+saas_b2b,"SaaS,B2B,platform,dashboard,teams,enterprise","Multi-tenant?;Permission model?;Subscription tiers?;Integrations?;Compliance?","tenant_model;rbac_matrix;subscription_tiers;integration_list;compliance_reqs","cli_interface;mobile_first","compliance requirements;integration guides","Workflow automation;AI agents"
+developer_tool,"SDK,library,package,npm,pip,framework","Language support?;Package managers?;IDE integration?;Documentation?;Examples?","language_matrix;installation_methods;api_surface;code_examples;migration_guide","visual_design;store_compliance","package manager best practices;API design patterns","New paradigm;DSL creation"
+cli_tool,"CLI,command,terminal,bash,script","Interactive or scriptable?;Output formats?;Config method?;Shell completion?","command_structure;output_formats;config_schema;scripting_support","visual_design;ux_principles;touch_interactions","CLI design patterns;shell integration","Natural language CLI;AI commands"
+web_app,"website,webapp,browser,SPA,PWA","SPA or MPA?;Browser support?;SEO needed?;Real-time?;Accessibility?","browser_matrix;responsive_design;performance_targets;seo_strategy;accessibility_level","native_features;cli_commands","web standards;WCAG guidelines","New interaction;WebAssembly use"
+game,"game,player,gameplay,level,character","REDIRECT TO USE THE rcode Method Game Module Agent and Workflows - HALT","game-brief;GDD","most_sections","game design patterns","Novel mechanics;Genre mixing"
+desktop_app,"desktop,Windows,Mac,Linux,native","Cross-platform?;Auto-update?;System integration?;Offline?","platform_support;system_integration;update_strategy;offline_capabilities","web_seo;mobile_features","desktop guidelines;platform requirements","Desktop AI;System automation"
+iot_embedded,"IoT,embedded,device,sensor,hardware","Hardware specs?;Connectivity?;Power constraints?;Security?;OTA updates?","hardware_reqs;connectivity_protocol;power_profile;security_model;update_mechanism","visual_ui;browser_support","IoT standards;protocol specs","Edge AI;New sensors"
+blockchain_web3,"blockchain,crypto,DeFi,NFT,smart contract","Chain selection?;Wallet integration?;Gas optimization?;Security audit?","chain_specs;wallet_support;smart_contracts;security_audit;gas_optimization","traditional_auth;centralized_db","blockchain standards;security patterns","Novel tokenomics;DAO structure"