@hanzlaa/rcode 2.8.0 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. package/AGENTS.md +11 -1
  2. package/CONTRIBUTING.md +7 -0
  3. package/README.md +39 -20
  4. package/cli/install.js +145 -47
  5. package/dist/rcode.js +134 -43
  6. package/package.json +2 -2
  7. package/rihal/agents/rihal-advisor-researcher.md +1 -1
  8. package/rihal/agents/rihal-assumptions-analyzer.md +1 -1
  9. package/rihal/agents/rihal-codebase-mapper.md +1 -1
  10. package/rihal/agents/rihal-docs-auditor.md +3 -3
  11. package/rihal/agents/rihal-executor.md +10 -0
  12. package/rihal/agents/rihal-integration-checker.md +1 -1
  13. package/rihal/agents/rihal-noor.md +2 -2
  14. package/rihal/agents/rihal-phase-researcher.md +1 -1
  15. package/rihal/agents/rihal-planner.md +25 -0
  16. package/rihal/agents/rihal-project-researcher.md +1 -1
  17. package/rihal/agents/rihal-research-synthesizer.md +1 -1
  18. package/rihal/agents/rihal-roadmapper.md +1 -1
  19. package/rihal/agents/rihal-sprint-checker.md +19 -1
  20. package/rihal/agents/rihal-verifier.md +1 -1
  21. package/rihal/agents/rihal-waleed.md +1 -2
  22. package/rihal/commands/code-review.md +1 -1
  23. package/rihal/commands/memory-audit.md +10 -0
  24. package/rihal/commands/memory-distill.md +11 -0
  25. package/rihal/commands/memory-init.md +12 -0
  26. package/rihal/commands/memory-update.md +12 -0
  27. package/rihal/config/model-profiles.json +5 -5
  28. package/rihal/references/karpathy-guidelines-full.md +1 -1
  29. package/rihal/references/no-unauthorized-git-ops.md +1 -1
  30. package/rihal/references/verb-dictionary.md +1 -1
  31. package/rihal/skills/actions/2-plan/rihal-frontend-design/SKILL.md +49 -139
  32. package/rihal/skills/actions/2-plan/rihal-frontend-design/references.md +79 -0
  33. package/rihal/skills/actions/4-implementation/rihal-browser-verify/SKILL.md +70 -0
  34. package/rihal/skills/actions/4-implementation/rihal-checkpoint-preview/SKILL.md +1 -1
  35. package/rihal/skills/actions/4-implementation/rihal-ci/SKILL.md +108 -0
  36. package/rihal/skills/actions/4-implementation/rihal-debug/SKILL.md +78 -0
  37. package/rihal/skills/actions/4-implementation/rihal-git-flow/SKILL.md +90 -0
  38. package/rihal/skills/actions/4-implementation/rihal-harden/SKILL.md +91 -0
  39. package/rihal/skills/actions/4-implementation/rihal-incremental/SKILL.md +50 -0
  40. package/rihal/skills/actions/4-implementation/rihal-migrate/SKILL.md +86 -0
  41. package/rihal/skills/actions/4-implementation/rihal-perf/SKILL.md +96 -0
  42. package/rihal/skills/actions/4-implementation/rihal-prove-it/SKILL.md +64 -0
  43. package/rihal/skills/actions/4-implementation/rihal-source-truth/SKILL.md +76 -0
  44. package/rihal/skills/actions/4-implementation/rihal-trim/SKILL.md +73 -0
  45. package/rihal/skills/agents/dalil-scout/SKILL.md +43 -125
  46. package/rihal/skills/agents/dalil-scout/references.md +67 -0
  47. package/rihal/skills/agents/majlis-council/SKILL.md +50 -144
  48. package/rihal/skills/agents/majlis-council/references.md +90 -0
  49. package/rihal/skills/agents/raees-orchestrator/SKILL.md +56 -117
  50. package/rihal/skills/agents/raees-orchestrator/references.md +47 -0
  51. package/rihal/skills/core/rihal-advanced-elicitation/SKILL.md +36 -136
  52. package/rihal/skills/core/rihal-advanced-elicitation/references.md +101 -0
  53. package/rihal/skills/core/rihal-auth-audit/SKILL.md +93 -0
  54. package/rihal/skills/core/rihal-brainstorming/SKILL.md +5 -0
  55. package/rihal/skills/core/rihal-client-gate/SKILL.md +91 -0
  56. package/rihal/skills/core/rihal-clone-website/SKILL.md +30 -371
  57. package/rihal/skills/core/rihal-clone-website/references.md +213 -0
  58. package/rihal/skills/core/rihal-deploy-unify/SKILL.md +87 -0
  59. package/rihal/skills/core/rihal-distillator/SKILL.md +37 -187
  60. package/rihal/skills/core/rihal-distillator/references.md +118 -0
  61. package/rihal/skills/core/rihal-editorial-review-prose/SKILL.md +5 -0
  62. package/rihal/skills/core/rihal-editorial-review-structure/SKILL.md +45 -183
  63. package/rihal/skills/core/rihal-editorial-review-structure/references.md +110 -0
  64. package/rihal/skills/core/rihal-help/SKILL.md +6 -1
  65. package/rihal/skills/core/rihal-incident-record/SKILL.md +161 -0
  66. package/rihal/skills/core/rihal-index-docs/SKILL.md +5 -0
  67. package/rihal/skills/core/rihal-init/SKILL.md +5 -0
  68. package/rihal/skills/core/rihal-memory-audit/SKILL.md +88 -0
  69. package/rihal/skills/core/rihal-memory-distill/SKILL.md +87 -0
  70. package/rihal/skills/core/rihal-memory-init/SKILL.md +77 -0
  71. package/rihal/skills/core/rihal-memory-update/SKILL.md +73 -0
  72. package/rihal/skills/core/rihal-mvp-graduate/SKILL.md +116 -0
  73. package/rihal/skills/core/rihal-ocr-consistency/SKILL.md +106 -0
  74. package/rihal/skills/core/rihal-party-mode/SKILL.md +5 -0
  75. package/rihal/skills/core/rihal-rebrand/SKILL.md +133 -0
  76. package/rihal/skills/core/rihal-review-adversarial-general/SKILL.md +5 -0
  77. package/rihal/skills/core/rihal-review-edge-case-hunter/SKILL.md +5 -0
  78. package/rihal/skills/core/rihal-shard-doc/SKILL.md +5 -0
  79. package/rihal/skills/core/rihal-theme-system/SKILL.md +113 -0
  80. package/rihal/team.yaml +3 -22
  81. package/rihal/templates/memory/INDEX.md +46 -0
  82. package/rihal/templates/memory/change-records/.gitkeep +4 -0
  83. package/rihal/templates/memory/distillates/project.distillate.md +11 -0
  84. package/rihal/templates/memory/distillates/stack.distillate.md +11 -0
  85. package/rihal/templates/memory/incidents/known-issues.md +27 -0
  86. package/rihal/templates/memory/incidents/post-mortems/.gitkeep +3 -0
  87. package/rihal/templates/memory/milestones/archive/.gitkeep +2 -0
  88. package/rihal/templates/memory/milestones/current.md +39 -0
  89. package/rihal/templates/memory/people/stakeholders.md +25 -0
  90. package/rihal/templates/memory/people/team.md +35 -0
  91. package/rihal/templates/memory/project/decisions.md +32 -0
  92. package/rihal/templates/memory/project/glossary.md +16 -0
  93. package/rihal/templates/memory/project/stack.md +46 -0
  94. package/rihal/workflows/audit.md +3 -3
  95. package/rihal/workflows/code-review.md +32 -1
  96. package/rihal/workflows/council.md +1 -1
  97. package/rihal/workflows/discuss-phase-power.md +3 -3
  98. package/rihal/workflows/do.md +1 -1
  99. package/rihal/workflows/docs-update.md +4 -4
  100. package/rihal/workflows/execute.md +61 -5
  101. package/rihal/workflows/help.md +5 -5
  102. package/rihal/workflows/karpathy-audit.md +9 -9
  103. package/rihal/workflows/memory-audit.md +83 -0
  104. package/rihal/workflows/memory-distill.md +103 -0
  105. package/rihal/workflows/memory-init.md +102 -0
  106. package/rihal/workflows/memory-update.md +83 -0
  107. package/rihal/workflows/plan.md +66 -1
  108. package/server/dashboard.js +6 -1
  109. package/server/lib/api.js +8 -2
  110. package/server/lib/html/client.js +63 -0
  111. package/server/lib/html/shell.js +5 -0
  112. package/server/lib/scanner.js +76 -1
  113. package/rihal/agents/rihal-architect.md +0 -79
  114. package/rihal/agents/rihal-tech-writer.md +0 -80
  115. package/rihal/commands/check-implementation-readiness.md +0 -8
  116. package/rihal/commands/discuss-phase-power.md +0 -11
  117. package/rihal/commands/karpathy-audit.md +0 -12
  118. package/rihal/commands/new-project-research.md +0 -11
  119. package/rihal/commands/new-project-roadmap.md +0 -11
  120. package/rihal/commands/report.md +0 -10
  121. package/rihal/commands/review-adversarial.md +0 -8
  122. package/rihal/commands/review-edge-case-hunter.md +0 -8
package/rihal/skills/actions/4-implementation/rihal-git-flow/SKILL.md ADDED
@@ -0,0 +1,90 @@
1
+ ---
2
+ name: rihal-git-flow
3
+ description: Branching, commits, conflicts, parallel work — aligned with the Rihal Epic→Feature→Task hierarchy from GITHUB_WORKFLOW.md. Use when starting a new feature, opening a PR, resolving a merge conflict, or coordinating multi-developer work. Enforces Conventional Commits, no AI attribution lines, no force-push to main.
4
+ triggers:
5
+ - "git flow"
6
+ - "branching strategy"
7
+ - "open a pr"
8
+ - "merge conflict"
9
+ - "rebase or merge"
10
+ - "feature branch"
11
+ - "commit policy"
12
+ - "branch from main"
13
+ user-invocable: true
14
+ ---
15
+
16
+ ## Overview
17
+
18
+ The Rihal git workflow: feature branches off main, Conventional Commits, PRs that close issues with `Closes #N`, no force-push to main, no AI attribution in commit messages. Aligned with the Epic→Feature→Task hierarchy in `GITHUB_WORKFLOW.md` so every branch traces back to an issue.
19
+
20
+ ## Branching
21
+
22
+ - **`main`** — always green. CI must pass. Never force-pushed.
23
+ - **`feature/<short-slug>`** — branched from latest `main` for new work.
24
+ - **`fix/<issue-N>-<slug>`** — branched from `main` for bug fixes; one branch per issue.
25
+ - **`docs/<short-slug>`** — branched from `main` for doc-only changes.
26
+
27
+ Naming: kebab-case slug, ≤40 chars after the prefix.
28
+
29
+ ## Commit policy
30
+
31
+ - **Conventional Commits:** `type(scope): subject`
32
+ - **Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
33
+ - **Scopes:** see `AGENTS.md` for the allow-list (`agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, etc.)
34
+ - **Subject:** lowercase first letter, imperative mood, no trailing period, ≤72 chars
35
+ - **Body:** explain the WHY (the diff shows the WHAT)
36
+ - **Footer:** `Closes #N` for the issue this commit completes
37
+ - **Forbidden:** AI attribution lines (`Co-Authored-By: Claude`, "Generated with..."). User does not want this.
38
+ - **Forbidden:** `--no-verify` to skip hooks. Fix the underlying issue.
39
+ - **Forbidden:** `git add -A` or `git add .` without reading the staged set first.
40
+
41
+ ## Workflow
42
+
43
+ 1. **Sync.** `git pull --rebase origin main` before starting any new work.
44
+ 2. **Branch.** `git checkout -b feature/<slug>` from latest main.
45
+ 3. **Commit small.** One logical change per commit. Run tests before committing.
46
+ 4. **Push the branch.** **`git push origin <branch>`** requires user authorization (see `AGENTS.md` push policy). Never push to main directly.
47
+ 5. **Open the PR.** `gh pr create --base main --title "<conventional-commits subject>" --body "<body>"`. Body links the issue: `Closes #N`.
48
+ 6. **Review cycle.** Address feedback as additional commits (don't rewrite history once the PR is open).
49
+ 7. **Merge.** Squash-merge by default; preserve commit history only when the chain is meaningful (rare). After merge: `git checkout main && git pull && git branch -d <branch>`.
50
+
51
+ ## Conflict resolution
52
+
53
+ 1. Don't reflexively `git pull --rebase` mid-PR. First read both sides.
54
+ 2. Use `git mergetool` or your IDE's conflict UI — manual `<<<<<<<` editing is error-prone.
55
+ 3. After resolving: run the full test suite. Conflicts often hide behavioural overlaps the tests catch.
56
+ 4. Commit message: `merge: resolve conflicts with main` (chore-type, no scope needed).
57
+
58
+ ## Output Format
59
+
60
+ For a new feature:
61
+
62
+ ```
63
+ Branch: feature/<slug> (from latest main)
64
+ Issue: #N — <title>
65
+
66
+ Commit plan:
67
+ 1. <conventional commit subject>
68
+ 2. <conventional commit subject>
69
+ ...
70
+
71
+ PR title: <type>(<scope>): <subject>
72
+ PR body footer: Closes #N
73
+
74
+ Push approval required at: branch push, PR open, post-review push (each separately).
75
+ ```
76
+
77
+ Do NOT include: force-pushes to main; commits with AI attribution; bundled commits ("feat: do everything").
78
+
79
+ ## Examples
80
+
81
+ **Happy path** — Issue #387 (refresh README counts) → branch `docs/readme-counts` → 1 commit with subject `docs(readme): refresh agent/command/skill counts and add MIGRATIONS link` → push → PR with `Closes #387` → squash-merge.
82
+
83
+ **Edge case — conflict on team.yaml** — Two branches both edit team.yaml. Resolve by: pull both versions, manually merge agent entries (preserve unique IDs), run `node --test test/agents-registry.test.cjs`, commit.
84
+
85
+ **Negative — pushing to main** — User asks "just push it to main". Refuse — feature branches + PRs are non-negotiable per `AGENTS.md`. Open a PR even for a one-line fix.
86
+
87
+ ## Memory Bank Hooks
88
+
89
+ - **Reads:** `.rihal/memory/project/decisions.md` (so prior branching decisions are loaded)
90
+ - **Writes:** none directly — the skill drives git, not Memory Bank state
package/rihal/skills/actions/4-implementation/rihal-harden/SKILL.md ADDED
@@ -0,0 +1,91 @@
1
+ ---
2
+ name: rihal-harden
3
+ description: Security hardening checklist for SaaS applications. Use before launching any feature that touches authentication, authorization, tenant data, file upload, or external integrations. Specifically opinionated about Keycloak/Active Directory sync (rcode learned this the hard way), JWT validation pitfalls, and tenant isolation in multi-org Postgres.
4
+ triggers:
5
+ - "harden this"
6
+ - "security check"
7
+ - "auth audit"
8
+ - "tenant isolation"
9
+ - "keycloak ad sync"
10
+ - "secure this endpoint"
11
+ - "owasp"
12
+ - "before we ship"
13
+ user-invocable: true
14
+ ---
15
+
16
+ ## Overview
17
+
18
+ Pre-launch security pass for SaaS code. Not a generic OWASP checklist — opinionated for the rcode-default stack (Next.js / Strapi / Postgres / Keycloak / Sentry). Especially focused on the failure modes that have actually bitten Rihal projects: Keycloak ↔ AD sync drift, multi-tenant query leaks, and JWT-as-source-of-truth bugs.
19
+
20
+ ## Workflow
21
+
22
+ 1. **Map the attack surface.** List every endpoint, file upload, third-party webhook, and background job. If you can't enumerate them, you can't audit them.
23
+ 2. **Per surface, run the checklist** below.
24
+ 3. **Triage findings:** Critical (block launch), High (fix before next sprint), Medium (track in `incidents/known-issues.md`).
25
+ 4. **Verify fixes** end-to-end — most security bugs are caught by writing the malicious test case, not by code review alone.
26
+
27
+ ## Checklist (applied per surface)
28
+
29
+ ### Authentication
30
+
31
+ - JWT verified on every request, not just `POST /login`. The token can be forged otherwise.
32
+ - Issuer (`iss`), audience (`aud`), expiry (`exp`), and signature all checked. Missing any one is a compromise.
33
+ - For Keycloak: re-fetch the JWKS keys, don't pin them — Keycloak rotates.
34
+ - AD sync: every Keycloak login should re-validate the user against AD; stale Keycloak users post-AD-deactivation is the documented Rihal incident.
35
+ - Session invalidation on password change actually clears all sessions, not just the current one.
36
+
37
+ ### Authorization
38
+
39
+ - Role checks AT the resource handler, not in the URL or query layer.
40
+ - Tenant isolation: every query that reads tenant data MUST filter by tenant_id derived from the JWT, never from a request parameter.
41
+ - "Admin" routes require role check + audit log write, in that order.
42
+
43
+ ### Input validation
44
+
45
+ - All request bodies validated at the boundary (zod / joi / strapi schema).
46
+ - File uploads: MIME-sniff the content, don't trust `Content-Type`; cap size; quarantine before processing.
47
+ - Path parameters: reject `..`, absolute paths, and URL-encoded variants.
48
+
49
+ ### Data handling
50
+
51
+ - Secrets in env vars, not in code. CI scans for committed secrets.
52
+ - PII redacted from logs and Sentry breadcrumbs (`beforeSend` filter).
53
+ - Encryption at rest on Postgres for any table holding government-sensitive data.
54
+
55
+ ### External integrations
56
+
57
+ - Webhook signatures verified on receipt; replay-attack window enforced (timestamp + nonce).
58
+ - Outbound API calls have a timeout; no infinite waits.
59
+ - Third-party SDKs pinned to a known-good version; renovate-bot PRs reviewed manually.
60
+
61
+ ## Output Format
62
+
63
+ ```
64
+ Surfaces audited: <count>
65
+
66
+ Critical (block launch):
67
+ ✗ <surface> — <issue> — <exploit path>
68
+
69
+ High (fix this sprint):
70
+ ⚠ <surface> — <issue>
71
+
72
+ Medium (track):
73
+ · <surface> — <issue>
74
+
75
+ Memory Bank update:
76
+ → wrote <count> entries to .rihal/memory/incidents/known-issues.md
77
+ → wrote audit summary to .rihal/memory/change-records/<date>-001.md
78
+ ```
79
+
80
+ ## Examples
81
+
82
+ **Happy path** — Pre-launch audit of a tenant-isolated dashboard → finds 2 queries missing `WHERE tenant_id = $1` (CRITICAL) → 1 webhook missing signature check (HIGH) → 3 medium findings. Block launch until critical findings fixed; reaudit.
83
+
84
+ **Edge case — Keycloak ↔ AD drift** — User deactivated in AD but their Keycloak token still works for 24h. Add: validate-against-AD step at every login + 5-minute Keycloak token TTL.
85
+
86
+ **Negative — "we'll add security later"** — Refuse. Security retrofits are 10× the cost of building it in. Block until at least the Critical findings have a plan.
87
+
88
+ ## Memory Bank Hooks
89
+
90
+ - **Reads:** `.rihal/memory/project/stack.md` (auth layer detection), `.rihal/memory/incidents/post-mortems/` (prior auth/security incidents)
91
+ - **Writes:** `.rihal/memory/incidents/known-issues.md` (deferred findings); `.rihal/memory/change-records/YYYYMMDD-NNN.md` (the audit itself as a change record)
package/rihal/skills/actions/4-implementation/rihal-incremental/SKILL.md ADDED
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: rihal-incremental
3
+ description: Ship code in small, atomic, verifiable steps. Use when implementing any feature, fixing any bug, or refactoring any module. Forces one logical change per commit, build-and-test gate after each step, and a rollback-ready trail. Pairs with rihal-prove-it (TDD) and rihal-code-review.
4
+ triggers:
5
+ - "ship incrementally"
6
+ - "atomic commits"
7
+ - "small steps"
8
+ - "step by step build"
9
+ - "incremental implementation"
10
+ - "one commit at a time"
11
+ - "build verifiably"
12
+ - "rollback ready"
13
+ user-invocable: true
14
+ ---
15
+
16
+ ## Overview
17
+
18
+ Treats every change as a sequence of small, verifiable steps that compile, pass tests, and revert cleanly. The unit isn't "the feature" — it's "the next 30 lines that still leave the build green." This is how rcode itself was reshaped (see `.rihal/memory/project/decisions.md`).
19
+
20
+ ## Workflow
21
+
22
+ 1. **Decompose first.** Before touching code, list the steps as a numbered checklist. Each step must end with the codebase still building and tests still passing.
23
+ 2. **One logical change per commit.** No bundled refactors. If you find yourself writing "and also" in the commit subject, split it.
24
+ 3. **Verify after each step.** Run the targeted test, the type-check, the linter — whatever the project gates require — before moving on.
25
+ 4. **Commit with intent.** Conventional Commits format (`type(scope): subject`); subject describes the WHY, not the WHAT (the diff already shows the what).
26
+ 5. **Pause at logical milestones.** After every 3–5 commits, ask whether to push, get review, or continue locally.
27
+ 6. **Revert is the first option, not the last.** If a step goes sideways, `git revert <sha>` and try a different decomposition. Never accumulate broken state.
28
+
29
+ ## Output Format
30
+
31
+ For each implementation request, return:
32
+ - **Step plan** — numbered checklist with one-line scope per step
33
+ - **Per-step commit messages** drafted in Conventional Commits format
34
+ - **Verification command** the agent will run after each step
35
+ - **Rollback note** for each step (what `git revert` undoes)
36
+
37
+ Do NOT include: bundled diffs, "and also" steps, or commits without verification.
38
+
39
+ ## Examples
40
+
41
+ **Happy path** — "Add dark mode to dashboard" → 5-step plan: (1) extract colour tokens to CSS vars, (2) add theme state + localStorage, (3) wire `data-theme` on `<html>`, (4) add toggle button, (5) screenshot regression. Each step compiles + tests pass.
42
+
43
+ **Edge case — refactor that touches 30 files** — Decompose into directory-by-directory commits. If a single commit must touch many files (e.g. an alias rename), state that in the plan and verify the codebase still parses afterwards.
44
+
45
+ **Negative — speculative future cleanup** — "Refactor the whole auth layer" without a current task driving it. Refuse. Pair this skill with a real bug fix or feature; otherwise it becomes scope creep.
46
+
47
+ ## Memory Bank Hooks
48
+
49
+ - **Reads:** `.rihal/memory/project/decisions.md` (so context for "why this approach" is loaded)
50
+ - **Writes:** append to `.rihal/memory/project/decisions.md` when a step encodes a non-obvious choice
package/rihal/skills/actions/4-implementation/rihal-migrate/SKILL.md ADDED
@@ -0,0 +1,86 @@
1
+ ---
2
+ name: rihal-migrate
3
+ description: Plan and execute the move from MVP to production-grade infrastructure without rewriting from scratch. Use when an MVP works but the next round of features hits a wall — flaky deploys, manual ops, no observability, no tests, hand-rolled auth. Specifically addresses the documented Rihal pain ("MVP delivered, hard to revamp"). Pairs with rihal-harden for security pass and rihal-ci for the new pipeline.
4
+ triggers:
5
+ - "graduate the mvp"
6
+ - "production grade infra"
7
+ - "mvp to prod"
8
+ - "scale this beyond demo"
9
+ - "harden the stack"
10
+ - "revamp the architecture"
11
+ - "from prototype to product"
12
+ - "ready for real users"
13
+ user-invocable: true
14
+ ---
15
+
16
+ ## Overview
17
+
18
+ MVPs are built to ship — corners get cut by design. Past a certain user count or revenue threshold, those cuts become tax: every new feature gets harder, every deploy is scary, every bug takes a day to root-cause. This skill plans the graduation in phases that ship continuously, never with a "we'll rewrite the whole thing" big bang.
19
+
20
+ ## Workflow
21
+
22
+ 1. **Audit the gaps.** Run a 30-minute MVP-vs-production gap report against the eight checks below.
23
+ 2. **Triage by blast radius.** Which gap, if it stays, kills the next 3 sprints? Fix that one first. Cosmetic gaps wait.
24
+ 3. **Plan in 1-week increments.** Each increment must leave the system shippable. No "we'll come back to fix this in 2 weeks" half-states.
25
+ 4. **Bring the team along.** New patterns get documented in `decisions.md` and `glossary.md` so the next dev finds them.
26
+ 5. **Each increment closes with a smoke-test deploy** and a metric showing the improvement.
27
+
28
+ ## The eight production checks
29
+
30
+ For each: pass / partial / fail. "Partial" means it exists but isn't enforced; treat as fail for planning.
31
+
32
+ 1. **Tests.** Unit + integration + at least one end-to-end happy-path test, all running in CI on every PR.
33
+ 2. **CI/CD.** Push-to-deploy on a PR-merge basis, with a manual approval gate to production.
34
+ 3. **Observability.** Errors land in Sentry (or equivalent) within 30s. Latency p95 graph exists. Logs are searchable.
35
+ 4. **Authentication.** Real provider (Keycloak, Auth0, Clerk, Firebase). No "rolled our own JWT".
36
+ 5. **Authorisation.** Tenant isolation enforced at the query layer, not just the URL.
37
+ 6. **Database backups.** Automated, tested (restore drill within the last 90 days).
38
+ 7. **Infrastructure as code.** Production reproducible from the repo (Helm + Terraform / Pulumi). No "I configured the load balancer manually".
39
+ 8. **Documentation.** README + architecture diagram + change records. New devs onboard in <1 day.
40
+
41
+ ## Gap → action mapping (defaults)
42
+
43
+ | Gap | First-week action | Skill to invoke |
44
+ |---|---|---|
45
+ | No tests | Cover the 3 most-used flows with E2E tests | `rihal-prove-it` |
46
+ | Manual deploys | Add GitHub Actions workflow that deploys on tag | `rihal-ci` |
47
+ | No Sentry | Drop in `@sentry/node` + `@sentry/nextjs`; PII redaction | `rihal-harden` |
48
+ | Hand-rolled JWT | Migrate to Keycloak / Clerk; flag old tokens for forced rotation | `rihal-harden` |
49
+ | Tenant leak risk | Add `tenant_id` to every query; enforce via Postgres RLS or middleware | `rihal-harden` |
50
+ | No backups | Configure automated `pg_dump` to S3 with 30-day retention | inline |
51
+ | Manual infra | Helm chart for the app + values per environment | `rihal-ci` |
52
+ | Stale README | Auto-generate architecture from code + write a 1-page onboarding | `rihal-trim` (for dead docs) |
53
+
54
+ ## Output Format
55
+
56
+ ```
57
+ MVP-vs-production gap report (<date>)
58
+
59
+ Pass: <count> / 8
60
+ Partial: <count>
61
+ Fail: <count>
62
+
63
+ Critical gaps (block scaling):
64
+ ✗ <gap> — <why this is critical now>
65
+
66
+ Plan (1-week increments):
67
+ Week 1: <gap to close> — owner: <persona>
68
+ Week 2: <gap to close> — owner: <persona>
69
+ ...
70
+
71
+ Each week ends with: smoke-test deploy + metric showing improvement.
72
+ Each week is reversible: if anything goes sideways, the previous week's state ships fine.
73
+ ```
74
+
75
+ ## Examples
76
+
77
+ **Happy path** — Audit shows 3 gaps: no Sentry, manual deploys, no E2E tests. Week 1: add Sentry + PII filter. Week 2: GitHub Actions deploy-on-tag. Week 3: Playwright E2E for login + main flow. Each week ships independently.
78
+
79
+ **Edge case — partial backups** — `pg_dump` exists in cron but no one has tested restore. Treat as fail. Week's action: restore drill in a staging instance; document the runbook.
80
+
81
+ **Negative — "let's rewrite in $NEW_FRAMEWORK"** — Refuse. A rewrite is not graduation. Graduation means filling specific gaps in the current system. Rewrites take 6 months and break what worked.
82
+
83
+ ## Memory Bank Hooks
84
+
85
+ - **Reads:** `.rihal/memory/project/stack.md` (current state), `.rihal/memory/incidents/known-issues.md` (operational pain), `.rihal/memory/milestones/current.md`
86
+ - **Writes:** the gap report into `.rihal/memory/change-records/YYYYMMDD-NNN.md`; each week's plan as a phase entry under `.rihal/memory/milestones/current.md`
package/rihal/skills/actions/4-implementation/rihal-perf/SKILL.md ADDED
@@ -0,0 +1,96 @@
1
+ ---
2
+ name: rihal-perf
3
+ description: Performance optimisation for the rcode-default stack — Next.js (LCP / TBT / CLS / hydration), Three.js (frame budget, draw calls, geometry uploads), Postgres (query plans, indexes), and Vercel/K8s (cold starts, memory). Use when Lighthouse scores regress, fps drops, queries get slow, or a deploy gets OOM-killed. Pairs with rihal-browser-verify for runtime measurement.
4
+ triggers:
5
+ - "optimize performance"
6
+ - "page is slow"
7
+ - "fps drop"
8
+ - "core web vitals"
9
+ - "query is slow"
10
+ - "lcp regression"
11
+ - "perf budget"
12
+ - "tune this"
13
+ user-invocable: true
14
+ ---
15
+
16
+ ## Overview
17
+
18
+ Performance work without measurement is theatre. This skill enforces measure → identify → fix → re-measure for every claim. Targets are stack-specific because optimisation moves are stack-specific. For Three.js scenes: frame budget. For Postgres: EXPLAIN ANALYZE. For Next.js: Lighthouse + bundle analyzer. Same skill, different tools.
19
+
20
+ ## Workflow
21
+
22
+ 1. **Baseline.** Capture the current number — LCP in ms, fps, query duration, RAM at peak. Quote the source (Lighthouse, Chrome perf trace, EXPLAIN ANALYZE, K8s metrics).
23
+ 2. **Set the budget.** What does "good enough" look like? E.g. LCP ≤ 2.5s, 60fps with 5% headroom, query p95 < 100ms. If there's no budget, the work has no exit condition.
24
+ 3. **Identify the bottleneck.** One number, one mechanism. "The page feels slow" isn't a bottleneck — find the specific waterfall step or render loop.
25
+ 4. **Fix.** One change. Re-measure.
26
+ 5. **Compare to budget.** Either the change cleared the budget (ship it) or it didn't (next bottleneck).
27
+ 6. **Stop when the budget is met.** Optimisation past the budget is yak-shaving.
28
+
29
+ ## Stack-specific cheat sheet
30
+
31
+ ### Next.js
32
+
33
+ - LCP: defer below-the-fold images; preload the LCP image.
34
+ - TBT: split the largest Client Component into Server Component + small Client island.
35
+ - Hydration: prefer Server Components by default; `'use client'` only where interactivity is required.
36
+ - Bundle: `next-bundle-analyzer`; per-route, find the >100KB chunks first.
37
+
38
+ ### Three.js
39
+
40
+ - Draw calls: instance any geometry rendered >50 times. `InstancedMesh`, not a loop.
41
+ - Geometry uploads: don't recreate `BufferGeometry` per frame — mutate the existing attribute.
42
+ - Materials: `MeshBasicMaterial` is 5-10× cheaper than `MeshStandardMaterial`. Use it where lighting isn't needed.
43
+ - DPR: clamp `renderer.setPixelRatio(Math.min(2, devicePixelRatio))` — 4× DPI on a Retina display kills perf.
44
+
45
+ ### Postgres
46
+
47
+ - EXPLAIN ANALYZE before touching anything. Look for `Seq Scan` on big tables.
48
+ - Index the columns in `WHERE` and `ORDER BY` first. Composite indexes for multi-column filters.
49
+ - `pg_stat_statements` for finding slow queries in production.
50
+ - For multi-tenant: ensure `tenant_id` is the leading column in indexes.
51
+
52
+ ### Vercel / K8s
53
+
54
+ - Cold start: prefer regional deploys close to users; use `runtime: 'nodejs'` for heavy SDKs.
55
+ - Memory: K8s pod memory limit + Node `--max-old-space-size` should match (don't let one exceed the other).
56
+ - Edge functions: keep cold-start work async; first response shouldn't await heavy SDK init.
57
+
58
+ ## Output Format
59
+
60
+ ```
61
+ Surface: <route / scene / query / pod>
62
+ Budget: <metric> ≤ <target>
63
+
64
+ Baseline:
65
+ <metric>: <value> (<measurement source>)
66
+
67
+ Bottleneck:
68
+ <one mechanism>
69
+
70
+ Fix:
71
+ <one change>
72
+
73
+ Post-fix:
74
+ <metric>: <value>
75
+ Budget: ✓ met | ✗ still over by <X>
76
+
77
+ Next bottleneck (if any):
78
+ <description>
79
+ ```
80
+
81
+ Do NOT include: optimisation without a baseline; "this should be faster" without measurement; broad rewrites pitched as perf fixes.
82
+
83
+ ## Examples
84
+
85
+ **Happy path — Next.js LCP** — Baseline LCP 4.2s; budget 2.5s. Bottleneck: hero image (1.8MB JPG, no preload). Fix: convert to AVIF + add `<link rel="preload" as="image">`. Post-fix LCP 2.3s. ✓
86
+
87
+ **Happy path — Three.js scene** — Baseline 28fps; budget 60fps. Bottleneck: 200 trees rendered with 200 separate draw calls. Fix: `InstancedMesh` with one geometry. Post-fix 62fps. ✓
88
+
89
+ **Edge case — query plan changed in production** — Same query is fast in staging, slow in prod. EXPLAIN ANALYZE in prod shows a `Seq Scan`; `pg_stat_user_tables` reveals a missing index in prod (drift from staging). Add the index; re-measure.
90
+
91
+ **Negative — premature optimisation** — "Add Redis caching everywhere just in case." Refuse. No measured baseline; no budget violation. Caching is a footgun (invalidation), don't ship it speculatively.
92
+
93
+ ## Memory Bank Hooks
94
+
95
+ - **Reads:** `.rihal/memory/project/stack.md` (which layer is in scope)
96
+ - **Writes:** when an optimisation establishes a long-lived pattern (e.g. "all hero images use AVIF"), append to `.rihal/memory/project/decisions.md`
package/rihal/skills/actions/4-implementation/rihal-prove-it/SKILL.md ADDED
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: rihal-prove-it
3
+ description: Test-first development. Use when implementing any new behaviour, fixing any bug, or changing existing logic. Writes a failing test first, then the minimum code to pass it, then refactors. For UI flows uses Playwright; for unit logic uses Jest or node:test. The phrase "prove it" is the activation — every claim of "this works" must have a test backing it.
4
+ triggers:
5
+ - "prove it"
6
+ - "tdd"
7
+ - "test first"
8
+ - "write a failing test"
9
+ - "red green refactor"
10
+ - "test driven"
11
+ - "regression test"
12
+ - "reproduce the bug first"
13
+ user-invocable: true
14
+ ---
15
+
16
+ ## Overview
17
+
18
+ Test-first cycle: red (failing test that captures the requirement) → green (smallest code that passes) → refactor (clean up with the test as safety net). For bugs: reproduce-the-bug-as-a-test before fixing — the test then guards against regression. The skill assumes a JS/TS project with Jest, Playwright, or node:test; the choice is detected from the project's `package.json`.
19
+
20
+ ## Workflow
21
+
22
+ 1. **Detect the test runner.** Read `package.json` `devDependencies` and `scripts.test`. Order of preference: `playwright` for E2E flows, `jest` or `vitest` for unit, `node --test` for zero-dep projects (rcode uses this).
23
+ 2. **For a new feature:** describe the behaviour in one sentence. Write the test that captures it. Run — confirm it fails for the right reason.
24
+ 3. **For a bug fix:** reproduce the bug as a failing test BEFORE looking at the code. The test must fail in the way the user reports.
25
+ 4. **Write the smallest code** that makes the test green. Resist the urge to handle cases not in the test.
26
+ 5. **Refactor with the test as safety net.** Rename, simplify, deduplicate. The test stays green.
27
+ 6. **Add edge-case tests** in a second pass. Common missing cases: empty input, boundary values, error paths, concurrent access.
28
+ 7. **Commit:** `test: add failing test for X` → `feat/fix: implement X` → optional `refactor: simplify Y`. Three commits, three diffs.
29
+
30
+ ## Output Format
31
+
32
+ ```
33
+ Detected runner: <jest|playwright|node:test|vitest>
34
+
35
+ Step 1 — Failing test
36
+ File: <path>
37
+ Behaviour: <one sentence>
38
+ Run: <command>
39
+ Expected to fail at: <line>
40
+
41
+ Step 2 — Implementation
42
+ Files: <list>
43
+ Smallest change: <one sentence>
44
+
45
+ Step 3 — Edge cases
46
+ - <empty input>
47
+ - <boundary>
48
+ - <error path>
49
+ ```
50
+
51
+ Do NOT include: tests written after the fact, "I tested manually", or coverage as a substitute for assertions.
52
+
53
+ ## Examples
54
+
55
+ **Happy path — bug** — "Login fails for usernames with Arabic characters" → test that calls login with "محمد" and asserts no exception → fix the encoding issue → test passes → ship the test alongside the fix as one commit.
56
+
57
+ **Happy path — feature** — "Add /api/memory endpoint" → test asserts 200 + JSON shape → minimal handler → green → second pass adds tests for empty Memory Bank case.
58
+
59
+ **Negative — coverage as substitute** — "We have 85% line coverage" without per-behaviour assertions. Refuse to count this as "tested". Coverage is a floor, not a ceiling.
60
+
61
+ ## Memory Bank Hooks
62
+
63
+ - **Reads:** `.rihal/memory/project/stack.md` (to detect the test runner correctly)
64
+ - **Writes:** append to `.rihal/memory/incidents/known-issues.md` if the bug is acknowledged but the fix is deferred
package/rihal/skills/actions/4-implementation/rihal-source-truth/SKILL.md ADDED
@@ -0,0 +1,76 @@
1
+ ---
2
+ name: rihal-source-truth
3
+ description: Cite official documentation before writing or recommending any framework, library, or API code. Use when working with Next.js, React, Strapi, Postgres, or any third-party tool. Forces the agent to fetch the upstream doc page (or local docs in `node_modules`) and quote the version-specific API rather than relying on training-data memory. Catches "the API changed in v15" foot-guns.
4
+ triggers:
5
+ - "cite the docs"
6
+ - "official source"
7
+ - "verify the api"
8
+ - "what does the doc say"
9
+ - "rtfm"
10
+ - "version specific"
11
+ - "from the source"
12
+ - "source-driven"
13
+ user-invocable: true
14
+ ---
15
+
16
+ ## Overview
17
+
18
+ Training data goes stale. APIs change between major versions. This skill forces a doc-fetch step before any code that uses a third-party API, so the recommendation is grounded in the version actually installed in this project, not in what was true two years ago.
19
+
20
+ ## Workflow
21
+
22
+ 1. **Detect the version** of the relevant library from `package.json`, `pyproject.toml`, `Cargo.toml`, or a similar manifest.
23
+ 2. **Fetch the doc page** for the API in question — preference order:
24
+ 1. Local `node_modules/<lib>/README.md` and `.d.ts` typings (most authoritative for what's installed)
25
+ 2. Upstream docs site for the matching version (e.g. `https://nextjs.org/docs/16/...`)
26
+ 3. The library's GitHub release notes for the major version
27
+ 3. **Quote the version-specific shape** in the output. Include the source URL or file path.
28
+ 4. **Compare to project usage.** If the project is using a deprecated pattern, flag it but don't auto-rewrite — call it out and let the user decide.
29
+ 5. **Write code** referencing only what the doc shows. No "I think this method is called X" without confirmation.
30
+ 6. **Note the doc source in the commit message** when the implementation depends on a specific API version (e.g. `feat(api): use Next.js 16 unstable_after — see https://...`).
31
+
32
+ ## Hard-listed sources for the rcode-default stack
33
+
34
+ | Layer | Authoritative source |
35
+ |---|---|
36
+ | Next.js | `https://nextjs.org/docs/<version>/` |
37
+ | React | `https://react.dev/reference/react` |
38
+ | Strapi | `https://docs.strapi.io/` (and local `node_modules/@strapi/`) |
39
+ | Postgres | `https://www.postgresql.org/docs/<version>/` |
40
+ | Three.js | `https://threejs.org/docs/` |
41
+ | Sentry | `https://docs.sentry.io/platforms/javascript/` |
42
+ | Temporal | `https://docs.temporal.io/` |
43
+ | Helm / K8s | `https://helm.sh/docs/` and `https://kubernetes.io/docs/` |
44
+
45
+ For other libraries: fetch the readme from `node_modules/<lib>/`. If the doc returns a 404 for the version you need, say so plainly — don't fabricate.
46
+
47
+ ## Output Format
48
+
49
+ ```
50
+ Library: <name> @ <version> (from package.json)
51
+ Source consulted: <URL or file path>
52
+ Relevant API shape (verbatim):
53
+ <copy-pasted from doc>
54
+
55
+ Project usage check:
56
+ ✓ in line with v<X> docs
57
+ ⚠ uses deprecated <Y>; replace with <Z>
58
+
59
+ Recommendation:
60
+ <code grounded in the source>
61
+ ```
62
+
63
+ Do NOT include: API names you did not see in the doc; "this is probably how it works"; recommendations for a version different from what's installed.
64
+
65
+ ## Examples
66
+
67
+ **Happy path** — "Add a Next.js Server Action for the contact form" → check `package.json` (`next: 16.1.6`) → fetch `https://nextjs.org/docs/16/app/building-your-application/data-fetching/server-actions-and-mutations` → quote the `'use server'` directive shape → write the action.
68
+
69
+ **Edge case — deprecated pattern** — Project is on React 19 but the codebase still uses `React.FC<>`. Flag it ("React.FC is discouraged in this project per CLAUDE.md") and recommend the function-component form, but don't auto-rewrite without permission.
70
+
71
+ **Negative — guessing** — "I think Strapi's content-type API uses `lifecycles.beforeCreate`". STOP. Fetch the actual Strapi 5 docs first. Don't ship code based on a half-remembered API.
72
+
73
+ ## Memory Bank Hooks
74
+
75
+ - **Reads:** `.rihal/memory/project/stack.md` (versions table) and `package.json`
76
+ - **Writes:** when a non-obvious version-specific API is used, append the source link to `.rihal/memory/project/decisions.md`
package/rihal/skills/actions/4-implementation/rihal-trim/SKILL.md ADDED
@@ -0,0 +1,73 @@
1
+ ---
2
+ name: rihal-trim
3
+ description: Code simplification. Reduce lines, remove dead branches, collapse abstractions, delete commented-out code. Use when a file has grown past comprehension, a function takes more than 80 lines, or a class has accumulated "while I'm here" features. Applies the rcode Distillator philosophy — lossless compression — to source code rather than documents.
4
+ triggers:
5
+ - "trim this"
6
+ - "simplify this code"
7
+ - "code is too long"
8
+ - "reduce complexity"
9
+ - "deduplicate"
10
+ - "remove dead code"
11
+ - "tighten this function"
12
+ - "extract dead branches"
13
+ user-invocable: true
14
+ ---
15
+
16
+ ## Overview
17
+
18
+ Reduces a file's surface area without changing behaviour. The skill is conservative: every removed line must be either dead, redundant, or replaceable by a tighter form that reads the same to a downstream user. No "while I'm here" rewrites — that's `rihal-incremental`'s job paired with a real task.
19
+
20
+ ## Workflow
21
+
22
+ 1. **Read the file with tests as ground truth.** If there are no tests, run `rihal-prove-it` first to capture current behaviour. Trimming without a safety net is a refactor in disguise.
23
+ 2. **Identify removable categories** in priority order:
24
+ 1. **Dead code** — unreachable branches, unused exports, commented-out blocks. Verify with grep that no other file references them.
25
+ 2. **Duplicate code** — same logic in two places. Extract carefully.
26
+ 3. **Premature abstractions** — wrappers that add a layer for one caller. Inline.
27
+ 4. **Dead arguments** — parameters that are always passed the default. Remove.
28
+ 5. **Verbose conditionals** — collapse to early returns or guard clauses.
29
+ 6. **Comments that restate the code** — delete.
30
+ 3. **Apply one category per commit.** Run tests after each. If anything goes red, the change wasn't actually safe — revert.
31
+ 4. **Stop trimming when** the file reads top-to-bottom with no "wait, why is that here?" moments. There's a floor of natural complexity; below it, you're losing intent.
32
+
33
+ ## Don't touch
34
+
35
+ - Comments that explain WHY (constraints, invariants, surprising behaviour) — these earn their lines.
36
+ - Verbose names that prevent confusion. `userIdAfterRotation` beats `id`.
37
+ - Defensive validation at system boundaries (user input, external APIs).
38
+
39
+ ## Output Format
40
+
41
+ ```
42
+ File: <path>
43
+ Before: <N> lines, <M> functions
44
+ After: <N'> lines, <M'> functions
45
+ Net change: <-X> lines
46
+
47
+ Per-category cuts:
48
+ Dead code: <count> lines
49
+ Duplicates: <count> lines (extracted to <where>)
50
+ Premature wrap: <count> lines (inlined)
51
+ Dead args: <count> arguments
52
+ Conditionals: <count> blocks collapsed
53
+ Stale comments: <count> lines
54
+
55
+ Verification:
56
+ ✓ all tests still passing
57
+ ✓ no behavioural change
58
+ ```
59
+
60
+ Do NOT include: changes that touch behaviour; "while I'm here, also..."; trimming that makes the code less clear in the name of being shorter.
61
+
62
+ ## Examples
63
+
64
+ **Happy path** — A 220-line component with 4 unused props, 2 dead useState hooks, and 30 lines of commented-out exploration code → trim to 140 lines, behaviour unchanged, tests green.
65
+
66
+ **Edge case — comment that earns its lines** — `// see issue #234 — Postgres pre-13 doesn't return rowCount on UPSERT, so we re-query`. Don't touch it. The comment captures a constraint that won't be obvious from the code alone.
67
+
68
+ **Negative — "simplify by rewriting"** — User asks to "clean up" a working module. If the rewrite is bigger than the cuts, it's not trimming — it's a refactor. Refuse and route to `rihal-incremental` with a real task.
69
+
70
+ ## Memory Bank Hooks
71
+
72
+ - **Reads:** `.rihal/memory/project/decisions.md` (so historical "why this exists" context is loaded — prevents trimming load-bearing complexity)
73
+ - **Writes:** if a trimmed pattern was load-bearing for a documented decision, update the decision's "current code reference" pointer