@hanzlaa/rcode 3.6.16 → 4.0.0

package/rcode/skills/core/rcode-memory-update/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: rcode-memory-update
+description: >
+  Surgical update of specific Memory Bank files from conversation context.
+  Adds an entry to decisions.md, appends a known issue, updates the current
+  milestone, or extends the stakeholder list — without rewriting whole files.
+  Activates when the user says "remember this decision", "log this decision",
+  "add this to memory bank", "update memory bank", "/rcode-memory-update",
+  "save this to memory", "yeh memory mein add karo", or after a council
+  session that produced a clear decision. Do NOT use for: initial bootstrap
+  (use rcode-memory-init), regenerating distillates (use rcode-memory-distill),
+  or general note-taking (use the existing rcode-note workflow).
+triggers:
+  # English
+  - "remember this decision"
+  - "log this decision"
+  - "add this to memory bank"
+  - "update memory bank"
+  - "save this to memory"
+  - "/rcode-memory-update"
+  - "/rcode-memory-update"
+  # Roman Urdu / Hindi
+  - "yeh memory mein add karo"
+  - "memory mein save karo"
+  - "yeh decision yaad rakho"
+  - "memory bank update karo"
+  # Arabic native
+  - "احفظ هذا القرار"
+  - "أضف إلى الذاكرة"
+  - "تذكّر هذا"
+  - "حدّث بنك الذاكرة"
+  - "سجّل هذا القرار"
+user-invocable: false
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+## Overview
+
+Append or update a single Memory Bank file based on the current conversation context. Surgical: never rewrites a whole file, never deletes existing content. Auto-routes the update to the right file based on what's being saved (decision → `decisions.md`, issue → `known-issues.md`, etc.).
+
+## Workflow
+
+1. **Detect target file.** Read the user's intent and pick the destination:
+   - "decision" / "we chose" / "ADR" → `project/decisions.md`
+   - "issue" / "bug" / "workaround" → `incidents/known-issues.md`
+   - "stakeholder" / "client" / "contact" → `people/stakeholders.md`
+   - "milestone" / "sprint" / "phase" → `milestones/current.md`
+   - "stack" / "we're using" / "switched to" → `project/stack.md`
+   - "term" / "what does X mean" / "glossary" → `project/glossary.md`
+   - "team" / "who owns" → `people/team.md`
+2. **Confirm target with user.** Show the file path and the entry to be added. Wait for ack.
+3. **Append using the file's documented format.** Each Memory Bank file documents its own entry format at the top — follow it exactly.
+4. **Never overwrite.** If the user wants to *change* an existing entry, refuse and direct them to edit the file directly. This skill is append-only for safety.
+5. **Stamp with date** in `YYYY-MM-DD` format.
+6. **Suggest distillate refresh** if the update was substantive (`/rcode-memory-distill`).
+
+## Output Format
+
+```
+✓ Appended to .rcode/memory/project/decisions.md
+
+  ### 2026-04-26 — Switch to Postgres 16 from Postgres 14
+  **Decision:** Upgrade primary database to Postgres 16.4.
+  **Rationale:** ...
+
+Tip: run /rcode-memory-distill to refresh the project distillate.
+```
+
+## Examples
+
+**Happy path — decision**
+User: `remember this decision: we picked Temporal over BullMQ because we need durable workflows`
+Skill: detects decision intent, formats entry, confirms, appends to `decisions.md`.
+
+**Happy path — known issue**
+User: `add to memory bank: SSO login fails on Safari 16, workaround is Chrome`
+Skill: detects issue intent, formats entry, appends to `incidents/known-issues.md`.
+
+**Negative — destructive request**
+User: `update memory bank: change the milestone goal to X`
+Skill: refuses ("this skill is append-only"). Suggests editing `milestones/current.md` directly.
+
+## Memory Bank Hooks
+
+- **Reads:** the target file's existing format header (to preserve structure)
+- **Writes:** exactly one append to one file per invocation

package/rcode/skills/core/rcode-mvp-graduate/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: rcode-mvp-graduate
+description: Move an MVP to production-grade infrastructure incrementally.
+triggers:
+  - "graduate this mvp"
+  - "mvp to prod plan"
+  - "real users now"
+  - "scale beyond demo"
+  - "post-mvp infrastructure"
+  - "revamp mvp"
+  - "hardening pass"
+  - "ready for production"
+user-invocable: true
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+## Overview
+
+This skill is the strategic version of `rcode-migrate`: same gap analysis, but framed as a multi-week plan with stakeholder sequencing rather than a one-week-per-gap engineering checklist. Use this when the conversation starts with the founder/CEO; use `rcode-migrate` when the conversation starts with the engineer.
+
+## The graduation framework
+
+### Phase A — Stop the bleeding (week 1)
+
+If any of these are missing, ship them first. Skip the "feature factory" until they're in place.
+
+1. **Sentry (or equivalent).** Until you can see what's breaking in production, every bug is a guess.
+2. **Automated backups.** Daily. Tested restore. No "we have backups but never tried to use them".
+3. **CI on every PR.** Even just "the tests pass". Manual deploys with no test gate is shipping blind.
+4. **Single source of truth for env vars.** No "Hanzla has the prod env in his Notion".
+
+### Phase B — Lock down auth + tenant isolation (weeks 2-3)
+
+The rcode incident makes this non-negotiable for anything multi-org.
+
+1. Real auth provider (Keycloak / Clerk / Auth0). Drop hand-rolled JWT.
+2. Tenant isolation enforced at the query layer (RLS or middleware), not the URL.
+3. Run `rcode-auth-audit` end-to-end before declaring this phase done.
+
+### Phase C — Operational maturity (weeks 4-5)
+
+1. Healthchecks → liveness + readiness, distinct.
+2. Resource limits → memory request = limit, no overcommit.
+3. PodDisruptionBudget for replica > 1 deployments.
+4. Logs are structured (JSON) and searchable.
+
+### Phase D — Documentation + onboarding (week 6)
+
+1. README that gets a new dev to a working local environment in < 1 day.
+2. Architecture diagram (Mermaid in `docs/`, regenerated, not hand-drawn).
+3. Runbooks for the 5 most common ops events (deploy, rollback, restart, restore, scale).
+4. `.rcode/memory/` populated — this skill writes the project-summary as the deliverable.
+
+### Phase E — Performance + cost (weeks 7-8)
+
+Run `rcode-perf` against the top 5 slowest pages / queries. Do the cost math: which K8s pods are over-provisioned? Which queries are scanning when they could index?
+
+## Stakeholder sequencing
+
+Each phase has a different audience:
+
+- Phase A: founder/CEO buy-in (it's not features, but it stops the bleeding)
+- Phase B: legal / compliance / security (especially for government clients)
+- Phase C: ops on-call (whoever wakes up at 3am)
+- Phase D: future hires / external contributors
+- Phase E: finance + perf-sensitive users
+
+Sequence the conversations accordingly.
+
+## Workflow
+
+1. **Run `rcode-migrate`'s 8-check audit.** Output is the gap report.
+2. **Map gaps to A-E phases.** Phase A first, no exceptions.
+3. **Calendar the phases.** 1-2 weeks each, no parallel phases unless they're truly independent.
+4. **Each week ends with a demo to the relevant stakeholder** — not just a Slack post.
+5. **Persist the plan** to `.rcode/memory/milestones/current.md` so future sessions track progress.
+
+## Output Format
+
+```
+MVP graduation plan — <project name>
+
+Current state (MVP→prod gap report from rcode-migrate):
+  Pass: <count> / 8
+  Critical gaps: <list>
+
+Plan:
+  Phase A (week 1) — Stop the bleeding
+    Owner: <stakeholder>
+    Tasks: <list>
+
+  Phase B (weeks 2-3) — Auth + tenant isolation
+    ...
+
+  Phase C-E ...
+
+Risk register:
+  - <risk> — <mitigation>
+
+Demo schedule:
+  Week 1: Sentry + backups working — demo to founder
+  Week 3: tenant-isolation audit clean — demo to legal/security
+  Week 6: new-dev onboarding < 1 day — demo with a real new dev
+```
+
+## Examples
+
+**Happy path — government client product** — MVP shipped 6 months ago, 3 government clients now. Gap report: missing Sentry, hand-rolled JWT, no automated backups, no Helm chart. Phases A→D mapped over 6 weeks. Each phase signs off with a stakeholder.
+
+**Edge case — pivoting MVP** — Founder wants to pivot. Run gap report anyway — even a pivoted MVP needs the same foundation. The pivot doesn't reset the technical floor.
+
+**Negative — "let's just rewrite in $NEW_FRAMEWORK"** — Refuse. A rewrite isn't graduation, it's restart. Ship the foundation against the existing codebase first; rewrites can come later if the pivot demands it.
+
+## Memory Bank Hooks
+
+- **Reads:** `.rcode/memory/project/stack.md`, `.rcode/memory/incidents/known-issues.md`, `.rcode/memory/people/stakeholders.md` (for sequencing)
+- **Writes:** `.rcode/memory/milestones/current.md` (the graduation plan); `.rcode/memory/change-records/YYYYMMDD-NNN.md` (the kickoff change record)

package/rcode/skills/core/rcode-ocr-consistency/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: rcode-ocr-consistency
+description: OCR pipeline determinism + ground-truth validation.
+triggers:
+  - "ocr inconsistency"
+  - "ocr pipeline"
+  - "text extraction"
+  - "pdf ocr"
+  - "siglip routing"
+  - "triton ocr"
+  - "ground truth"
+  - "ocr accuracy regression"
+user-invocable: true
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+## Overview
+
+OCR is non-deterministic by default — same input, different output across runs, model versions, and infrastructure. This skill encodes the discipline needed to ship OCR that doesn't silently regress. Default stack: SigLIP2 language router + LightOnOCR / PaddleOCR / Triton; adapt to whatever's in use. The skill assumes Python + Temporal workflows (rcode's verified rcode stack).
+
+## The 6 consistency checks
+
+### 1. Language routing
+
+- [ ] Router (e.g. SigLIP2) classifies document language **before** OCR.
+- [ ] Confidence threshold for routing decisions — below threshold, surface for human review, don't pick a default.
+- [ ] Routing decisions logged with the document hash for replay.
+- [ ] Arabic/English boundary cases tested explicitly — bilingual documents trip naive routers.
+
+### 2. Model determinism
+
+- [ ] OCR model version pinned in code, not "whatever's loaded in Triton".
+- [ ] Triton config pinned (no auto-update). Model swaps surface as deploys, not silent drift.
+- [ ] Temperature / sampling parameters set to deterministic values (temperature=0 for greedy decoding).
+
+### 3. Ground truth
+
+- [ ] A ground-truth dataset exists — at least 20 documents per language with verified text.
+- [ ] Accuracy is measured on every model upgrade and every infra change (Triton config, GPU change).
+- [ ] Regression threshold defined: e.g. ≥95% character accuracy on the ground-truth set; below blocks deploy.
+
+### 4. Routing tests
+
+- [ ] PyMuPDF text-layer routing is correctly bypassing OCR for text-native PDFs.
+- [ ] English page misclassification tests (the documented rcode incident — text-layer English pages routed to Arabic OCR).
+- [ ] Mixed-language documents have an explicit handler.
+
+### 5. Pipeline observability
+
+- [ ] Every document passes through with a trace ID.
+- [ ] Routing decision, model used, confidence score, and final output all logged.
+- [ ] Failures (OCR returns empty, confidence below threshold) trigger Sentry alerts, not silent retries.
+
+### 6. Replay capability
+
+- [ ] Any production document can be re-OCR'd from the archived input, deterministically.
+- [ ] Temporal workflows have idempotency — replays don't double-process or skip.
+- [ ] Source documents archived with hash → output mapping.
+
+## Workflow
+
+1. **Run the 6 checks.** Cite file/path for each pass / fail.
+2. **For accuracy regression:** capture the ground-truth diff. Which documents changed output? Which characters?
+3. **Bisect the regression** — was it the model? the Triton config? the routing? Don't ship "we'll figure it out next sprint".
+4. **Persist findings** to `.rcode/memory/incidents/known-issues.md` for unresolved drift, or `.rcode/memory/incidents/post-mortems/` for resolved incidents.
+
+## Output Format
+
+```
+OCR pipeline audit — <date>
+
+Language routing:
+  ✓/✗ findings
+
+Model determinism:
+  ✓/✗ findings
+
+Ground truth:
+  Accuracy on ground-truth set: <X%>
+  Regressions vs last run: <count>
+
+Routing tests:
+  ✓/✗ findings
+
+Observability:
+  ✓/✗ findings
+
+Replay capability:
+  ✓/✗ findings
+
+Critical: <count>
+High: <count>
+Memory Bank update: → .rcode/memory/incidents/...
+```
+
+## Examples
+
+**Happy path — text-layer routing fix** — Audit shows English text-layer PDFs misclassified as Arabic by SigLIP2 (the documented rcode bug). Fix: route text-layer PDFs to PyMuPDF extraction, bypass OCR entirely. Re-run ground truth: accuracy stable, throughput up.
+
+**Edge case — Triton silent upgrade** — Triton image was bumped from 25.02 to 25.06 in the Helm chart; ground-truth accuracy dropped 4%. Roll back Triton, pin the version, re-run audit. Add a CI check that fails the build on accuracy regression.
+
+**Negative — "OCR is fuzzy by nature, accept the variance"** — Refuse. Variance without measurement is just regression in disguise. Pin the model, pin the infra, measure on ground truth, surface confidence.
+
+## Memory Bank Hooks
+
+- **Reads:** `.rcode/memory/project/stack.md` (OCR layer detection), `.rcode/memory/incidents/post-mortems/` (prior OCR incidents)
+- **Writes:** `.rcode/memory/incidents/known-issues.md` (deferred drift); ground-truth accuracy results into `.rcode/memory/change-records/YYYYMMDD-NNN.md`

package/rcode/skills/core/rcode-party-mode/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: rcode-party-mode
+description: >
+  Orchestrates group discussions between all installed rcode agents, enabling
+  natural multi-agent conversations with maintained personalities. Activates
+  when the user says "party mode", "activate party mode", "start party mode",
+  "group discussion", "team discussion", "talk to everyone", "bring all agents",
+  "multi-agent chat", or "let's have a party". Do NOT use for: formal council
+  decisions (use rcode-majlis-council), single-agent questions where one
+  specialist is clearly the right owner (invoke that agent directly), or
+  sprint ceremonies (use rcode-hussain-sm).
+triggers:
+  - "party mode"
+  - "activate party mode"
+  - "start party mode"
+  - "group discussion"
+  - "team discussion"
+  - "talk to everyone"
+  - "bring all agents"
+  - "multi-agent chat"
+  - "let's have a party"
+user-invocable: true
+---
+
+## Overview
+
+Orchestrates group discussions between all installed rcode agents, enabling natural multi-agent conversations with maintained personalities.
+
+# Party Mode
+
+Brings together the full rcode agent team for natural multi-agent conversations. Each agent maintains their unique personality and expertise while a facilitator manages flow, relevance-based agent selection, and cross-talk.
+
+## Workflow
+
+Follow the instructions in ./workflow.md.
+
+## Output Format
+
+Interactive conversation where each agent speaks in character with their emoji prefix. The facilitator selects 3-5 relevant agents per round based on the topic. Conversation continues until the user exits party mode.
+
+```
+🎯 Sadiq: [strategic perspective]
+🏗️ Waleed: [technical perspective]
+📋 Ahmed: [delivery perspective]
+...
+```
+
+## Examples
+
+### Happy path
+**User:** "party mode — should we build a mobile app?"
+**Result:** Facilitator loads team.yaml → selects Sadiq, Waleed, Hussain, Mariam → each speaks in character → user steers discussion
+
+### Edge case
+**User:** "party mode" (no topic)
+**Result:** Facilitator asks what topic to discuss, then selects relevant agents
+
+### Negative boundary
+**User:** "convene the majlis for a formal decision"
+**Result:** Not party mode → route to `rcode-majlis-council` for structured consensus with voting
+
+## Output Format
+
+Each party mode turn follows this pattern:
+
+```
+🎉 PARTY MODE — {topic}
+
+**{Agent Emoji} {Agent Name} ({Role}):**
+{Agent's response in their documented communication style}
+
+**{Agent Emoji} {Agent Name} ({Role}):**
+{Response, may reference previous agent's point}
+
+---
+@.rcode/references/karpathy-guidelines.md
+
+💬 What would you like to discuss next? (say "exit" to end party mode)
+```
+
+## Examples
+
+### Happy path
+**User:** "party mode — should we build a mobile app?"
+**Result:** Facilitator activates party mode, selects Sadiq (strategy), Waleed (CTO), Hussain (PM), and Mariam (marketing). Each gives perspective in-character. User can steer the conversation, address specific agents, or ask follow-ups.
+
+### Edge case
+**User:** "party mode" (no topic)
+**Result:** Facilitator introduces the agent roster and asks "What would you like to discuss with the team today?"
+
+### Negative boundary
+**User:** "party mode — approve this PR"
+**Result:** Redirects to `/rcode-review` — code review needs structured evaluation, not open discussion.
+
+## Memory Bank Hooks
+
+- **Reads:** `rcode/team.yaml`, every consulted persona's SKILL.md, `.rcode/memory/people/team.md` (so the casual chat respects active team availability)
+- **Writes:** transcript saved to `.rcode/progress/party-{date}.md` for audit; does NOT update Memory Bank decision log (use `rcode-memory-update` if the chat surfaced a real decision)

package/rcode/skills/core/rcode-party-mode/steps/step-01-agent-loading.md

@@ -0,0 +1,138 @@
+# Step 1: Agent Loading and Party Mode Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A PARTY MODE FACILITATOR, not just a workflow executor
+- 🎯 CREATE ENGAGING ATMOSPHERE for multi-agent collaboration
+- 📋 LOAD COMPLETE AGENT ROSTER from manifest with merged personalities
+- 🔍 PARSE AGENT DATA for conversation orchestration
+- 💬 INTRODUCE DIVERSE AGENT SAMPLE to kick off discussion
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show agent loading process before presenting party activation
+- ⚠️ Present [C] continue option after agent roster is loaded
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to start conversation until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Agent manifest CSV is available at `{project-root}/.rcode/team.yaml`
+- User configuration from config.yaml is loaded and resolved
+- Party mode is standalone interactive workflow
+- All agent data is available for conversation orchestration
+
+## YOUR TASK:
+
+Load the complete agent roster from manifest and initialize party mode with engaging introduction.
+
+## AGENT LOADING SEQUENCE:
+
+### 1. Load Agent Manifest
+
+Begin agent loading process:
+
+"Now initializing **Party Mode** with our complete rcode agent roster! Let me load up all our talented agents and get them ready for an amazing collaborative discussion.
+
+**Agent Manifest Loading:**"
+
+Load and parse the agent manifest CSV from `{project-root}/.rcode/team.yaml`
+
+### 2. Extract Agent Data
+
+Parse CSV to extract complete agent information for each entry:
+
+**Agent Data Points:**
+
+- **name** (agent identifier for system calls)
+- **displayName** (agent's persona name for conversations)
+- **title** (formal position and role description)
+- **icon** (visual identifier emoji)
+- **role** (capabilities and expertise summary)
+- **identity** (background and specialization details)
+- **communicationStyle** (how they communicate and express themselves)
+- **principles** (decision-making philosophy and values)
+- **module** (source module organization)
+- **path** (file location reference)
+
+### 3. Build Agent Roster
+
+Create complete agent roster with merged personalities:
+
+**Roster Building Process:**
+
+- Combine manifest data with agent file configurations
+- Merge personality traits, capabilities, and communication styles
+- Validate agent availability and configuration completeness
+- Organize agents by expertise domains for intelligent selection
+
+### 4. Party Mode Activation
+
+Generate enthusiastic party mode introduction:
+
+"🎉 PARTY MODE ACTIVATED! 🎉
+
+Welcome {{user_name}}! I'm excited to facilitate an incredible multi-agent discussion with our complete rcode team. All our specialized agents are online and ready to collaborate, bringing their unique expertise and perspectives to whatever you'd like to explore.
+
+**Our Collaborating Agents Include:**
+
+[Display 3-4 diverse agents to showcase variety]:
+
+- [Icon Emoji] **[Agent Name]** ([Title]): [Brief role description]
+- [Icon Emoji] **[Agent Name]** ([Title]): [Brief role description]
+- [Icon Emoji] **[Agent Name]** ([Title]): [Brief role description]
+
+**[Total Count] agents** are ready to contribute their expertise!
+
+**What would you like to discuss with the team today?**"
+
+### 5. Present Continue Option
+
+After agent loading and introduction:
+
+"**Agent roster loaded successfully!** All our rcode experts are excited to collaborate with you.
+
+**Ready to start the discussion?**
+[C] Continue - Begin multi-agent conversation
+
+### 6. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- Update frontmatter: `stepsCompleted: [1]`
+- Set `agents_loaded: true` and `party_active: true`
+- Load: `./step-02-discussion-orchestration.md`
+
+## SUCCESS METRICS:
+
+✅ Agent manifest successfully loaded and parsed
+✅ Complete agent roster built with merged personalities
+✅ Engaging party mode introduction created
+✅ Diverse agent sample showcased for user
+✅ [C] continue option presented and handled correctly
+✅ Frontmatter updated with agent loading status
+✅ Proper routing to discussion orchestration step
+
+## FAILURE MODES:
+
+❌ Failed to load or parse agent manifest CSV
+❌ Incomplete agent data extraction or roster building
+❌ Generic or unengaging party mode introduction
+❌ Not showcasing diverse agent capabilities
+❌ Not presenting [C] continue option after loading
+❌ Starting conversation without user selection
+
+## AGENT LOADING PROTOCOLS:
+
+- Validate CSV format and required columns
+- Handle missing or incomplete agent entries gracefully
+- Cross-reference manifest with actual agent files
+- Prepare agent selection logic for intelligent conversation routing
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-02-discussion-orchestration.md` to begin the interactive multi-agent conversation with intelligent agent selection and natural conversation flow.
+
+Remember: Create an engaging, party-like atmosphere while maintaining professional expertise and intelligent conversation orchestration!