@lifeaitools/rdc-skills 0.24.38 → 0.24.39

package/guides/infrastructure.md

@@ -1,179 +1,179 @@
-# Infrastructure Agent Guide — Base
-> Role-based context for infra/deployment/DevOps agents. Generic patterns across projects.
-
----
-
-## Rule 1: NEVER Work Around Broken Infrastructure
-
-When a service is unavailable, STOP and report BLOCKED. Do not:
-- Use curl when service APIs are down
-- Use workarounds or alternative approaches
-- Skip verification steps
-- Assume service will return to normal
-
-**Report immediately:**
-
-```
-BLOCKED: [service name] is not responding.
-
-Fix: [specific action for your project's infrastructure stack]
-
-I cannot proceed until this is resolved.
-```
-
----
-
-## Deployment Tools
-
-Check project overlay for:
-- Primary deployment platform (Coolify, Vercel, AWS, GCP, etc.)
-- MCP connectors or REST API access
-- Authentication method (API token, OAuth, etc.)
-- Credential location (clauth daemon, env vars, etc.)
-
----
-
-## Server Infrastructure
-
-The project specifies:
-- Server IP/hostname
-- Dashboard URL
-- Default region/availability zones
-- Server/environment IDs (UUIDs or identifiers)
-
----
-
-## DNS Rules
-
-The project specifies:
-- Wildcard DNS patterns vs individual records
-- Cloudflare or other DNS provider
-- Proxy rules (orange cloud, DNS-only, etc.)
-- SSL/TLS provisioning method
-
-Check overlay for **critical rules** — DNS misconfigurations break deployments.
-
----
-
-## Deployment Registry
-
-The project likely has a registry/database table tracking all deployments. Before ANY deploy, verify:
-```
-Lookup: <slug> or <domain>
-Returns: UUID, repo location, build command, build type, domain, status
-```
-
-**NEVER guess** UUIDs, domains, or build commands. Always look them up.
-
----
-
-## Watch Paths
-
-For monorepo deploys, the project specifies:
-- Watch path patterns per app type
-- Why watch paths matter (prevents unnecessary rebuilds)
-- How to set watch paths (usually via API or config)
-
-Without correct watch paths, every push triggers ALL apps to rebuild.
-
----
-
-## Build Types
-
-The project specifies supported build types:
-- Next.js monorepo
-- Vite / Node
-- Static HTML
-- Docker
-- etc.
-
-Check overlay for:
-- Build pack (nixpacks, docker, static, etc.)
-- Required environment variables
-- Node version constraints
-- Build command and install command
-
----
-
-## Environment Tiers
-
-The project specifies deployment environments:
-- **development** -- free to experiment
-- **staging** -- test before production
-- **production** -- live traffic, needs confirmation
-
-Check overlay for which tier each app is in and confirmation requirements.
-
----
-
-## Deploy Checklist
-
-Standard pattern:
-1. Check git status (divergence, unpushed commits)
-2. Confirm with user (especially for production)
-3. Push to trigger auto-deploy (if webhook configured)
-4. Verify deployment success (health check, status endpoint)
-5. Check cache headers (if behind CDN)
-
----
-
-## New App Deployment
-
-The project specifies:
-- DNS pattern (wildcard subdomains vs custom domains)
-- Coolify/deployment platform setup
-- GitHub repo connection
-- Watch paths configuration
-- Registry update requirement
-
----
-
-## Credential Safety
-
-- MCP connectors first (if available)
-- clauth daemon second (localhost:52437)
-- Never print keys to stdout
-- Never hardcode credentials
-- Never ask user for keys
-- If daemon is down: report BLOCKED
-
----
-
-## Git Workflow
-
-The project specifies:
-- Primary branch for features (develop, main, etc.)
-- Force-push rules (usually: NEVER force-push main)
-- Commit message format
-- Auto-commit patterns
-
----
-
-## Service Health Checks
-
-The project specifies how to health-check each service:
-- Ping endpoint
-- Status endpoint
-- Log location
-- Fallback if primary method fails
-
----
-
-## Troubleshooting Patterns
-
-The project specifies common issues and fixes:
-- 502/503 errors (check container logs, port mismatch)
-- Disk full (clean Docker cache)
-- SSL provisioning failures (check DNS config)
-- Build failures (check environment variables, Node version)
-
----
-
-## Specialist Context — Read Project Overlay
-
-Your task may require reading additional project-specific guides for:
-- Full deployment registry schema
-- Complete DNS rules (critical for subdomains)
-- Build type details
-- CI/CD pipeline configuration
-- Scaling and performance tuning
+# Infrastructure Agent Guide — Base
+> Role-based context for infra/deployment/DevOps agents. Generic patterns across projects.
+
+---
+
+## Rule 1: NEVER Work Around Broken Infrastructure
+
+When a service is unavailable, STOP and report BLOCKED. Do not:
+- Use curl when service APIs are down
+- Use workarounds or alternative approaches
+- Skip verification steps
+- Assume service will return to normal
+
+**Report immediately:**
+
+```
+BLOCKED: [service name] is not responding.
+
+Fix: [specific action for your project's infrastructure stack]
+
+I cannot proceed until this is resolved.
+```
+
+---
+
+## Deployment Tools
+
+Check project overlay for:
+- Primary deployment platform (Coolify, Vercel, AWS, GCP, etc.)
+- MCP connectors or REST API access
+- Authentication method (API token, OAuth, etc.)
+- Credential location (clauth daemon, env vars, etc.)
+
+---
+
+## Server Infrastructure
+
+The project specifies:
+- Server IP/hostname
+- Dashboard URL
+- Default region/availability zones
+- Server/environment IDs (UUIDs or identifiers)
+
+---
+
+## DNS Rules
+
+The project specifies:
+- Wildcard DNS patterns vs individual records
+- Cloudflare or other DNS provider
+- Proxy rules (orange cloud, DNS-only, etc.)
+- SSL/TLS provisioning method
+
+Check overlay for **critical rules** — DNS misconfigurations break deployments.
+
+---
+
+## Deployment Registry
+
+The project likely has a registry/database table tracking all deployments. Before ANY deploy, verify:
+```
+Lookup: <slug> or <domain>
+Returns: UUID, repo location, build command, build type, domain, status
+```
+
+**NEVER guess** UUIDs, domains, or build commands. Always look them up.
+
+---
+
+## Watch Paths
+
+For monorepo deploys, the project specifies:
+- Watch path patterns per app type
+- Why watch paths matter (prevents unnecessary rebuilds)
+- How to set watch paths (usually via API or config)
+
+Without correct watch paths, every push triggers ALL apps to rebuild.
+
+---
+
+## Build Types
+
+The project specifies supported build types:
+- Next.js monorepo
+- Vite / Node
+- Static HTML
+- Docker
+- etc.
+
+Check overlay for:
+- Build pack (nixpacks, docker, static, etc.)
+- Required environment variables
+- Node version constraints
+- Build command and install command
+
+---
+
+## Environment Tiers
+
+The project specifies deployment environments:
+- **development** -- free to experiment
+- **staging** -- test before production
+- **production** -- live traffic, needs confirmation
+
+Check overlay for which tier each app is in and confirmation requirements.
+
+---
+
+## Deploy Checklist
+
+Standard pattern:
+1. Check git status (divergence, unpushed commits)
+2. Confirm with user (especially for production)
+3. Push to trigger auto-deploy (if webhook configured)
+4. Verify deployment success (health check, status endpoint)
+5. Check cache headers (if behind CDN)
+
+---
+
+## New App Deployment
+
+The project specifies:
+- DNS pattern (wildcard subdomains vs custom domains)
+- Coolify/deployment platform setup
+- GitHub repo connection
+- Watch paths configuration
+- Registry update requirement
+
+---
+
+## Credential Safety
+
+- MCP connectors first (if available)
+- clauth daemon second (localhost:52437)
+- Never print keys to stdout
+- Never hardcode credentials
+- Never ask user for keys
+- If daemon is down: report BLOCKED
+
+---
+
+## Git Workflow
+
+The project specifies:
+- Primary branch for features (develop, main, etc.)
+- Force-push rules (usually: NEVER force-push main)
+- Commit message format
+- Auto-commit patterns
+
+---
+
+## Service Health Checks
+
+The project specifies how to health-check each service:
+- Ping endpoint
+- Status endpoint
+- Log location
+- Fallback if primary method fails
+
+---
+
+## Troubleshooting Patterns
+
+The project specifies common issues and fixes:
+- 502/503 errors (check container logs, port mismatch)
+- Disk full (clean Docker cache)
+- SSL provisioning failures (check DNS config)
+- Build failures (check environment variables, Node version)
+
+---
+
+## Specialist Context — Read Project Overlay
+
+Your task may require reading additional project-specific guides for:
+- Full deployment registry schema
+- Complete DNS rules (critical for subdomains)
+- Build type details
+- CI/CD pipeline configuration
+- Scaling and performance tuning

package/guides/lessons-learned-spec.md

@@ -1,153 +1,153 @@
----
-mdk_schema_version: "1.0"
-doc_type: guide
-system: claude-workflow
-status: active
-owner: infrastructure
-created: 2026-06-08
-last_reviewed: 2026-06-08
-source_of_truth: true
-supersedes: []
-depends_on:
-  - ".claude/rules/architectural-change-approval.md"
-  - ".rdc/guides/output-contract.md"
-tags: [rdc, lessons-learned, skills, housekeeping, adaptive]
----
-
-# Lessons-Learned Capture & Triage — Spec
-
-> Auto-referenced by long-running `rdc:*` skills at exit, and by `rdc:housekeeping` for triage.
-> Goal: make the fleet an **interactive adaptive modeler** — every run that teaches us
-> something writes it down, and the weekly housekeeping pass turns those lessons into
-> actual fixes (rules, skill docs, work_items).
-
----
-
-## Why this exists
-
-Lessons learned during a run (a non-obvious infra trap, a wrong assumption, a missing
-gate, a tooling gotcha) used to survive only if someone hand-wrote a memory. This system
-makes capture a **routine exit step** of every long skill, and triage a **routine phase**
-of the weekly housekeeping. Capture is cheap and append-only; triage is where fixes happen.
-
-Precedent: brochurify's `rdc-extract-verifier-rules` already does read-log → cluster →
-propose-rule for one domain. This generalizes that pattern fleet-wide.
-
----
-
-## Storage — directory of per-lesson files
-
-Lessons live in **`.rdc/lessons/`**, one markdown file per lesson:
-
-```
-.rdc/lessons/<YYYY-MM-DD>-<skill>-<short-slug>.md
-```
-
-- One file per lesson (NOT a single appended file) so parallel agents finishing at the
-  same time never collide on one file in git.
-- `<skill>` is the capturing skill (`build`, `deploy`, `overnight`, `fixit`, `plan`,
-  `preplan`, `review`, `release`, `collab`).
-- `<short-slug>` is 2–4 kebab words naming the lesson.
-
-A run that taught nothing writes nothing — **absence is the default**. Only write a lesson
-when something was genuinely learned (see § When to capture).
-
----
-
-## Lesson file schema
-
-```markdown
----
-id: <YYYY-MM-DD>-<skill>-<short-slug>
-date: "<YYYY-MM-DD>"
-skill: build | deploy | overnight | fixit | plan | preplan | review | release | collab
-session: <session-id or short ref>
-scope: simple | architectural          # triage routing — see § Scope gate
-status: open | triaged | applied | wont-fix
-area: infra | skill | guide | rule | schema | ui | content | other
-links:
-  commits: []                          # SHAs that relate to the lesson
-  memory: []                           # memory file slugs, if a memory was also written
-  work_items: []                       # work_item UUIDs spawned during triage
----
-
-## What happened
-<one paragraph — the concrete situation, with evidence (exit code, file:line, command)>
-
-## Root cause
-<one paragraph — the evidenced cause, not a guess>
-
-## The fix / rule
-<what should change so this never recurs: a rule edit, skill-doc line, code change,
-or a check. If already applied in the same run, say so and link the commit.>
-```
-
-`scope` is the single most important field — it routes triage:
-
-- **`simple`** — a doc line, a one-file fix, a config tweak, a clarifying sentence in a
-  skill, a missing grep guard. Housekeeping applies these directly.
-- **`architectural`** — anything matching `.claude/rules/architectural-change-approval.md`
-  (rule/CLAUDE.md/ARCHITECTURE.md edits, cross-cutting refactors, schema reshape, public
-  API/MCP changes, skill-contract changes affecting multiple skills). Housekeeping does
-  NOT apply these; it surfaces them via `AskUserQuestion` for explicit approval first.
-
-When unsure, mark `architectural`.
-
----
-
-## When to capture (at skill exit)
-
-Write a lesson when ANY of these were true during the run:
-
-1. A root cause turned out to be different from the first theory (a wrong assumption).
-2. The standard/documented path didn't work and you had to do something non-obvious.
-3. A gate, check, or doc was missing and its absence cost a round.
-4. A tool/infra behaved in a surprising way (exit codes, caching, serve/PM2/webhook quirks).
-5. A hook blocked you and the block revealed a real gap (not just your mistake).
-
-Do NOT capture: routine success, your own one-off typo, anything already fully documented
-in a rule/guide. If a durable user preference or correction was involved, also write a
-`memory` (this spec and memory are complementary — link them).
-
----
-
-## Capture procedure (the exit step long skills call)
-
-At the end of a long skill run, before the final verdict line:
-
-1. Decide if anything qualifies (§ When to capture). If not, write nothing and move on.
-2. For each lesson, write `.rdc/lessons/<date>-<skill>-<slug>.md` using the schema above.
-   Set `status: open` (or `applied` if you already shipped the fix in this same run, with
-   the commit linked).
-3. Set `scope` honestly (`simple` vs `architectural`).
-4. Commit the lesson file(s) on `develop` alongside the run's other commits.
-5. Mention in the verdict/summary that N lessons were captured.
-
----
-
-## Triage procedure (rdc:housekeeping, weekly)
-
-`rdc:housekeeping` adds a **Lessons triage** phase:
-
-1. Read all `.rdc/lessons/*.md` with `status: open`.
-2. Cluster by `area` + root-cause similarity (dedupe repeats into one fix).
-3. For each cluster:
-   - `scope: simple` → apply the fix directly (rule line, skill-doc edit, config, guard),
-     commit it, set the lesson(s) `status: applied` and link the commit.
-   - `scope: architectural` → do NOT edit. Present the issue + options via
-     `AskUserQuestion` (per `architectural-change-approval.md`). On approval, apply via the
-     correct lifecycle (rdc-skills tag/push for skills; cited commit for rules) and set
-     `status: applied`. If deferred, set `status: triaged` and spawn a `work_item`.
-   - Not worth fixing → `status: wont-fix` with a one-line reason.
-4. Summarize in the housekeeping report: captured / applied / escalated / deferred counts.
-
-Lessons are never silently deleted — `applied` and `wont-fix` files stay as the audit trail.
-
----
-
-## Skills that capture (the long-running set)
-
-`build` · `deploy` · `overnight` · `fixit` · `plan` · `preplan` · `review` · `release` · `collab`
-
-Each references this spec from a final "§ Capture lessons" step. A Stop-hook backstop warns
-when one of these skills ends a run with findings but no new `.rdc/lessons/` file.
+---
+mdk_schema_version: "1.0"
+doc_type: guide
+system: claude-workflow
+status: active
+owner: infrastructure
+created: 2026-06-08
+last_reviewed: 2026-06-08
+source_of_truth: true
+supersedes: []
+depends_on:
+  - ".claude/rules/architectural-change-approval.md"
+  - ".rdc/guides/output-contract.md"
+tags: [rdc, lessons-learned, skills, housekeeping, adaptive]
+---
+
+# Lessons-Learned Capture & Triage — Spec
+
+> Auto-referenced by long-running `rdc:*` skills at exit, and by `rdc:housekeeping` for triage.
+> Goal: make the fleet an **interactive adaptive modeler** — every run that teaches us
+> something writes it down, and the weekly housekeeping pass turns those lessons into
+> actual fixes (rules, skill docs, work_items).
+
+---
+
+## Why this exists
+
+Lessons learned during a run (a non-obvious infra trap, a wrong assumption, a missing
+gate, a tooling gotcha) used to survive only if someone hand-wrote a memory. This system
+makes capture a **routine exit step** of every long skill, and triage a **routine phase**
+of the weekly housekeeping. Capture is cheap and append-only; triage is where fixes happen.
+
+Precedent: brochurify's `rdc-extract-verifier-rules` already does read-log → cluster →
+propose-rule for one domain. This generalizes that pattern fleet-wide.
+
+---
+
+## Storage — directory of per-lesson files
+
+Lessons live in **`.rdc/lessons/`**, one markdown file per lesson:
+
+```
+.rdc/lessons/<YYYY-MM-DD>-<skill>-<short-slug>.md
+```
+
+- One file per lesson (NOT a single appended file) so parallel agents finishing at the
+  same time never collide on one file in git.
+- `<skill>` is the capturing skill (`build`, `deploy`, `overnight`, `fixit`, `plan`,
+  `preplan`, `review`, `release`, `collab`).
+- `<short-slug>` is 2–4 kebab words naming the lesson.
+
+A run that taught nothing writes nothing — **absence is the default**. Only write a lesson
+when something was genuinely learned (see § When to capture).
+
+---
+
+## Lesson file schema
+
+```markdown
+---
+id: <YYYY-MM-DD>-<skill>-<short-slug>
+date: "<YYYY-MM-DD>"
+skill: build | deploy | overnight | fixit | plan | preplan | review | release | collab
+session: <session-id or short ref>
+scope: simple | architectural          # triage routing — see § Scope gate
+status: open | triaged | applied | wont-fix
+area: infra | skill | guide | rule | schema | ui | content | other
+links:
+  commits: []                          # SHAs that relate to the lesson
+  memory: []                           # memory file slugs, if a memory was also written
+  work_items: []                       # work_item UUIDs spawned during triage
+---
+
+## What happened
+<one paragraph — the concrete situation, with evidence (exit code, file:line, command)>
+
+## Root cause
+<one paragraph — the evidenced cause, not a guess>
+
+## The fix / rule
+<what should change so this never recurs: a rule edit, skill-doc line, code change,
+or a check. If already applied in the same run, say so and link the commit.>
+```
+
+`scope` is the single most important field — it routes triage:
+
+- **`simple`** — a doc line, a one-file fix, a config tweak, a clarifying sentence in a
+  skill, a missing grep guard. Housekeeping applies these directly.
+- **`architectural`** — anything matching `.claude/rules/architectural-change-approval.md`
+  (rule/CLAUDE.md/ARCHITECTURE.md edits, cross-cutting refactors, schema reshape, public
+  API/MCP changes, skill-contract changes affecting multiple skills). Housekeeping does
+  NOT apply these; it surfaces them via `AskUserQuestion` for explicit approval first.
+
+When unsure, mark `architectural`.
+
+---
+
+## When to capture (at skill exit)
+
+Write a lesson when ANY of these were true during the run:
+
+1. A root cause turned out to be different from the first theory (a wrong assumption).
+2. The standard/documented path didn't work and you had to do something non-obvious.
+3. A gate, check, or doc was missing and its absence cost a round.
+4. A tool/infra behaved in a surprising way (exit codes, caching, serve/PM2/webhook quirks).
+5. A hook blocked you and the block revealed a real gap (not just your mistake).
+
+Do NOT capture: routine success, your own one-off typo, anything already fully documented
+in a rule/guide. If a durable user preference or correction was involved, also write a
+`memory` (this spec and memory are complementary — link them).
+
+---
+
+## Capture procedure (the exit step long skills call)
+
+At the end of a long skill run, before the final verdict line:
+
+1. Decide if anything qualifies (§ When to capture). If not, write nothing and move on.
+2. For each lesson, write `.rdc/lessons/<date>-<skill>-<slug>.md` using the schema above.
+   Set `status: open` (or `applied` if you already shipped the fix in this same run, with
+   the commit linked).
+3. Set `scope` honestly (`simple` vs `architectural`).
+4. Commit the lesson file(s) on `develop` alongside the run's other commits.
+5. Mention in the verdict/summary that N lessons were captured.
+
+---
+
+## Triage procedure (rdc:housekeeping, weekly)
+
+`rdc:housekeeping` adds a **Lessons triage** phase:
+
+1. Read all `.rdc/lessons/*.md` with `status: open`.
+2. Cluster by `area` + root-cause similarity (dedupe repeats into one fix).
+3. For each cluster:
+   - `scope: simple` → apply the fix directly (rule line, skill-doc edit, config, guard),
+     commit it, set the lesson(s) `status: applied` and link the commit.
+   - `scope: architectural` → do NOT edit. Present the issue + options via
+     `AskUserQuestion` (per `architectural-change-approval.md`). On approval, apply via the
+     correct lifecycle (rdc-skills tag/push for skills; cited commit for rules) and set
+     `status: applied`. If deferred, set `status: triaged` and spawn a `work_item`.
+   - Not worth fixing → `status: wont-fix` with a one-line reason.
+4. Summarize in the housekeeping report: captured / applied / escalated / deferred counts.
+
+Lessons are never silently deleted — `applied` and `wont-fix` files stay as the audit trail.
+
+---
+
+## Skills that capture (the long-running set)
+
+`build` · `deploy` · `overnight` · `fixit` · `plan` · `preplan` · `review` · `release` · `collab`
+
+Each references this spec from a final "§ Capture lessons" step. A Stop-hook backstop warns
+when one of these skills ends a run with findings but no new `.rdc/lessons/` file.