create-agent-room 1.2.1

package/templates/skill-packs/documentation/documentation.md

@@ -0,0 +1,155 @@
+---
+name: documentation
+description: "Use when writing inline comments, doc comments, READMEs, API documentation, architecture decision records, or operational runbooks."
+---
+
+# Documentation
+
+## Overview
+
+Documentation is not an afterthought — it's a deliverable. Code without
+documentation is code that the next person (human or agent) will
+misunderstand, misuse, or rewrite from scratch. But bad documentation is
+worse than no documentation — it creates false confidence.
+
+## The iron law
+
+```
+DOCUMENT THE WHY, NOT THE WHAT
+```
+
+Code shows *what* happens. Documentation explains *why* it happens that
+way, *what alternatives were rejected*, and *what assumptions hold.* If
+the documentation just restates the code, it adds maintenance burden
+without value.
+
+## When to document what
+
+### Inline comments
+
+Use for non-obvious logic — the "why" behind a decision.
+
+```
+BAD:  // increment counter
+      counter++;
+
+GOOD: // Rate limiter uses a sliding window. We increment here rather than
+      // in the middleware because failed auth attempts should count against
+      // the limit even if the request is rejected before reaching the handler.
+      counter++;
+```
+
+**Don't comment obvious code.** If the code is so unclear that it needs a
+comment explaining *what* it does, refactor the code to be clearer instead.
+
+### Doc comments (JSDoc, typedoc, docstrings)
+
+Use for every public function, class, and module that other code consumes.
+
+```javascript
+/**
+ * Resolves a user's effective permissions by merging role-based
+ * permissions with any user-specific overrides.
+ *
+ * @param {string} userId - The user ID to resolve permissions for.
+ * @param {string} resourceId - The resource being accessed.
+ * @returns {Permission[]} Merged permissions, with user overrides
+ *   taking precedence over role defaults.
+ * @throws {NotFoundError} If the user does not exist.
+ */
+```
+
+Include:
+- What the function does (one sentence).
+- Parameter descriptions with types.
+- Return value description.
+- Exceptions/errors thrown and when.
+- Any side effects (writes to database, sends email, modifies global
+  state).
+
+### README sections
+
+Every project's README should contain at minimum:
+1. **What it is** — one paragraph explaining the project's purpose.
+2. **Quick start** — how to install, configure, and run.
+3. **Development setup** — how to set up a local development environment.
+4. **Testing** — how to run the test suite.
+5. **Architecture overview** — high-level description of the system
+   structure (link to a diagram if complex).
+
+### Architecture Decision Records (ADRs)
+
+Use for significant architecture or design decisions that someone could
+reasonably ask "why did you do it this way?"
+
+**Format** (stored in `docs/decisions/` or `.agent-room/decisions.md`):
+
+```markdown
+### YYYY-MM-DD — Short title
+
+**Status:** Accepted / Superseded by [link] / Deprecated
+
+**Context:** What situation or problem prompted this decision?
+
+**Decision:** What was decided and how?
+
+**Consequences:** What are the trade-offs? What becomes easier? What
+becomes harder?
+
+**Alternatives considered:**
+- Option A: description. Rejected because...
+- Option B: description. Rejected because...
+```
+
+### Operational runbooks
+
+For any system that runs in production, document the operational
+procedures:
+
+```markdown
+## Runbook: [Service/Component Name]
+
+### Health check
+- URL: `GET /health`
+- Expected: 200 with `{"status": "ok"}`
+- If failing: Check database connectivity, then check [dependency].
+
+### Common failure modes
+1. **High memory usage:** Usually caused by [X]. Fix: [Y].
+2. **Slow response times:** Check [Z] dashboard. If [metric] > [threshold],
+   scale horizontally.
+
+### Deployment
+- Deploy via: `[command]`
+- Rollback via: `[command]`
+- Post-deploy verification: `[check]`
+```
+
+## API documentation
+
+For services that expose APIs:
+
+- Use OpenAPI/Swagger for REST APIs. Keep the spec in sync with the code
+  (generate from annotations, or validate the spec in CI).
+- Document every endpoint, every parameter, every response shape, every
+  error code.
+- Include example requests and responses for each endpoint.
+- Document authentication requirements and rate limits.
+
+## Documentation anti-patterns
+
+| Anti-pattern | Problem | Fix |
+| --- | --- | --- |
+| "Self-documenting code" as an excuse | Not all "why" is visible in code | Write the comments the code can't express |
+| Documentation in a wiki nobody reads | Out of sync within weeks | Keep docs next to the code they describe |
+| Stale README | Worse than no README — misleads people | Update README as part of the PR that changes behavior |
+| TODO comments without owners or dates | They accumulate forever | Format: `TODO(username, YYYY-MM-DD): description` |
+| Generated docs with no curation | Noise overwhelms signal | Write summaries, examples, and guides on top of generated reference |
+
+## Red flags — stop and document
+
+A new team member asks "how does X work?" and nobody can point to a
+document · a production incident requires reading source code to diagnose ·
+a function has 8 parameters and no doc comment · the README's "quick start"
+doesn't work · an ADR is missing for a decision that took the team a week
+to make.

package/templates/skill-packs/observability/observability.md

@@ -0,0 +1,128 @@
+---
+name: observability
+description: "Use when adding logging, metrics, tracing, alerting, or error handling to applications — or when deciding what to observe and how."
+---
+
+# Observability
+
+## Overview
+
+Observability is not "add console.log everywhere." It's a disciplined
+approach to making systems understandable in production — where you can't
+attach a debugger, set breakpoints, or reproduce bugs on demand. Good
+observability answers: "What happened, where, when, and why?" from the
+logs and metrics alone, without needing to read the source code.
+
+## The iron law
+
+```
+EVERY PRODUCTION ERROR MUST BE TRACEABLE TO A ROOT CAUSE WITHOUT READING SOURCE CODE
+```
+
+If an error fires in production and the on-call engineer needs to read
+the codebase to understand what went wrong, the observability is
+insufficient. The log entry, metric, or trace should contain enough
+context to diagnose the issue.
+
+## The three pillars
+
+### 1. Logs — what happened
+
+Use structured logging (JSON), not unstructured strings.
+
+```
+BAD:  console.log("User login failed")
+GOOD: logger.warn({ event: "auth.login_failed", userId: "u_123",
+        reason: "invalid_password", ip: req.ip, requestId: req.id })
+```
+
+**What to log:**
+- Business events: user signup, order placed, payment processed.
+- Errors with full context: what was attempted, what failed, what input
+  caused it.
+- Security events: failed login attempts, permission denials, token
+  expirations.
+
+**What NOT to log:**
+- Secrets, passwords, tokens, full credit card numbers. Ever.
+- Success cases for high-frequency operations (every successful health
+  check, every cache hit). Use metrics for these.
+- Full request/response bodies in production (unless explicitly in a
+  debug mode with PII scrubbing).
+
+**Correlation IDs:** Generate a unique `requestId` at the entry point of
+every request. Pass it through every function call, every service-to-
+service call, and include it in every log entry. This lets you trace a
+single user action across multiple services and log entries.
+
+### 2. Metrics — how much
+
+Metrics are aggregated numbers over time. Use them for trends, alerting,
+and dashboards — not for debugging individual requests.
+
+**The four golden signals (from Google SRE):**
+- **Latency:** How long requests take. Track p50, p95, p99.
+- **Traffic:** How many requests per second (or per minute).
+- **Errors:** How many requests fail (as a rate, not a count).
+- **Saturation:** How full are your resources (CPU, memory, disk, queue
+  depth).
+
+**Naming convention:** Use dot-separated namespaces.
+```
+api.users.request_duration_ms
+api.users.error_count
+db.connections.active
+queue.orders.depth
+```
+
+### 3. Traces — where it went
+
+Distributed traces show the path of a request across services. Use them
+when a single user action touches multiple services and you need to find
+which one is slow or failing.
+
+- Instrument service boundaries (HTTP calls, queue publishes, database
+  queries).
+- Include trace IDs in log entries so you can correlate logs with traces.
+- Don't trace everything in production — sample at 1-10% for normal
+  traffic, 100% for errors.
+
+## Error classification
+
+Not all errors are equal. Classify them to determine the response:
+
+| Category | Meaning | Response |
+| --- | --- | --- |
+| Transient | Temporary failure (network timeout, rate limit) | Retry with backoff |
+| Permanent | Will never succeed (invalid input, missing resource) | Return error to caller, don't retry |
+| Fatal | System cannot continue (out of memory, corrupt state) | Alert immediately, escalate |
+
+**Anti-pattern:** Retrying permanent errors. If the input is invalid, it
+will be invalid on the next attempt too. Check the error type before
+retrying.
+
+## Alert design
+
+Alerts should be **actionable, not noisy.**
+
+**Good alert:** "API error rate exceeded 5% for 5 consecutive minutes.
+Dashboard: [link]. Runbook: [link]."
+
+**Bad alert:** "Error occurred." (Which error? Where? What should I do?)
+
+**Rules for alerts:**
+- Every alert must have a runbook (even if it's one paragraph).
+- Alert on symptoms (error rate, latency), not causes (CPU usage — unless
+  it's at 95%+).
+- Use severity levels: critical (wake someone up), warning (investigate
+  during business hours), info (no action needed, for dashboards only).
+- If an alert fires more than 3 times without action, it's noise — fix
+  the underlying issue or tune the threshold.
+
+## Red flags — stop and rethink
+
+`console.log(error)` without context · logging PII or secrets ·
+alerting on every single error instead of error rates · no correlation
+IDs across services · metrics without dashboards (data collected but
+never reviewed) · catch-and-swallow error handling (`catch (e) {}`) ·
+"we'll add observability later."

package/templates/skill-packs/performance/performance-optimization.md

@@ -0,0 +1,150 @@
+---
+name: performance-optimization
+description: "Use when investigating slow code, optimizing queries, reducing load times, or making architectural decisions that affect throughput and latency."
+---
+
+# Performance Optimization
+
+## Overview
+
+Performance optimization without measurement is superstition. The most
+common performance mistake agents make is optimizing code that isn't slow
+while ignoring code that is. Measure first, optimize the bottleneck,
+measure again.
+
+## The iron law
+
+```
+MEASURE BEFORE AND AFTER EVERY OPTIMIZATION
+```
+
+If you can't measure the improvement, you don't know if you improved
+anything. Optimizations that aren't measured are guesses — and guesses
+frequently make things worse by adding complexity without benefit.
+
+## The optimization protocol
+
+### Step 1: Define the metric
+
+Before optimizing, define what "fast enough" means:
+- **API latency:** p50, p95, p99 response times. p95 matters more than
+  average — averages hide tail latency.
+- **Page load:** Time to First Byte (TTFB), Largest Contentful Paint
+  (LCP), Time to Interactive (TTI).
+- **Throughput:** Requests per second the system can sustain.
+- **Resource usage:** Memory, CPU, disk I/O under expected load.
+
+### Step 2: Profile, don't guess
+
+- Use profiling tools (flame graphs, query analyzers, Chrome DevTools
+  Performance tab), not intuition.
+- Find the actual bottleneck. Common surprise: "I thought the API was
+  slow but the bottleneck was a DNS lookup, not the database query."
+- Profile under realistic conditions (production-like data volumes, not
+  10 rows in a test database).
+
+### Step 3: Optimize the bottleneck
+
+Fix the measured bottleneck. Don't optimize adjacent code "while you're
+in there."
+
+### Step 4: Measure again
+
+Run the same benchmark. Compare results. If the improvement is
+statistically insignificant, revert — the optimization added complexity
+without value.
+
+## Common performance problems and fixes
+
+### N+1 queries
+
+**The problem:** A loop fetches related data one row at a time.
+```
+users = db.query("SELECT * FROM users")
+for user in users:
+    orders = db.query("SELECT * FROM orders WHERE user_id = ?", user.id)
+```
+100 users = 101 queries. 10,000 users = 10,001 queries.
+
+**The fix:** Eager load or batch fetch.
+```
+users = db.query("SELECT * FROM users")
+user_ids = [u.id for u in users]
+orders = db.query("SELECT * FROM orders WHERE user_id IN (?)", user_ids)
+```
+100 users = 2 queries. 10,000 users = 2 queries.
+
+### Unbounded queries
+
+**The problem:** A query fetches all rows without a LIMIT.
+```
+SELECT * FROM events  -- 50 million rows
+```
+
+**The fix:** Always paginate. Use LIMIT/OFFSET for small datasets,
+cursor-based pagination for large ones. Every list query must have a
+bound.
+
+### Missing indexes
+
+**The problem:** A WHERE clause or JOIN on an unindexed column causes a
+full table scan.
+
+**The fix:** Add an index on columns used in WHERE, JOIN, and ORDER BY
+clauses. But don't add indexes speculatively — each index slows writes
+and uses storage. Add when you have a measured slow query.
+
+### Premature caching
+
+**The problem:** Caching added before measuring whether the underlying
+operation is actually slow. The cache adds invalidation complexity,
+stale data risks, and memory pressure — for a query that takes 5ms.
+
+**The fix:** Cache only when:
+1. The operation is measurably slow (>100ms for user-facing, >1s for
+   background).
+2. The data changes infrequently relative to read frequency.
+3. Staleness is acceptable for the use case.
+
+When caching:
+- Set explicit TTLs. Never cache without an expiration.
+- Document the invalidation strategy. "Cache invalidation" is where most
+  caching bugs live.
+- Monitor hit rates. A cache with <80% hit rate is probably not worth the
+  complexity.
+
+### Frontend bundle bloat
+
+**The problem:** A 2MB JavaScript bundle for a page that needs 200KB of
+logic.
+
+**The fix:**
+- Audit with `webpack-bundle-analyzer`, `source-map-explorer`, or
+  equivalent.
+- Code-split by route. Users shouldn't download the admin dashboard code
+  when viewing the login page.
+- Lazy-load below-the-fold components.
+- Replace heavy libraries with lighter alternatives when the full feature
+  set isn't needed.
+
+## Performance budgets
+
+Set budgets and enforce them in CI:
+
+| Metric | Budget | Enforcement |
+| --- | --- | --- |
+| API p95 latency | <200ms | Load test in CI, alert on regression |
+| Bundle size | <250KB gzipped | Build step fails if exceeded |
+| Database query count per request | <10 | Logging + review |
+| LCP | <2.5s | Lighthouse CI |
+
+Budgets prevent gradual degradation. Without them, performance erodes
+one "small" addition at a time until the system is unusably slow.
+
+## Red flags — stop and measure
+
+"This should be faster" without data · optimizing code that profiling
+shows isn't in the hot path · adding a cache for a 5ms operation ·
+"premature optimization is the root of all evil" used to justify never
+measuring · rewriting in a "faster language" before profiling the current
+implementation.

package/templates/skill-packs/release/release-management.md

@@ -0,0 +1,145 @@
+---
+name: release-management
+description: "Use when preparing release commits, tagging, bumping version numbers, compiling changelogs, or deciding whether a change is safe to release."
+---
+
+# Release Management
+
+## Overview
+
+Releasing software should be automated, reproducible, and traceably
+documented. A release is not "push to main and hope" — it's a controlled
+process with validation gates, a rollback plan, and post-release
+verification.
+
+## The iron law
+
+```
+NO RELEASE WITHOUT A ROLLBACK PLAN
+```
+
+Before tagging a release, you must be able to answer: "If this breaks
+production, what do we do in the next 5 minutes?" If the answer is "I
+don't know," the release is not ready.
+
+## Release process
+
+### 1. Pre-release validation checklist
+
+Before bumping the version, confirm:
+
+- [ ] All tests pass on the release branch (not just locally — in CI)
+- [ ] Linter is clean with zero warnings
+- [ ] No high/critical dependency audit findings
+- [ ] Breaking changes are documented with migration instructions
+- [ ] Database migrations are backward-compatible (see below)
+- [ ] Feature flags for incomplete features are defaulted to off
+- [ ] The changelog is complete and reviewed
+
+If any box is unchecked, the release is not ready. Don't ship with
+"we'll fix it in the next release."
+
+### 2. Version bump
+
+Increment the version in configuration files (`package.json`, `setup.py`,
+`Cargo.toml`, etc.) according to Semantic Versioning:
+
+| Change type | Version bump | Example |
+| --- | --- | --- |
+| Bug fixes, patches | PATCH | 1.2.3 → 1.2.4 |
+| New features (backward-compatible) | MINOR | 1.2.3 → 1.3.0 |
+| Breaking changes | MAJOR | 1.2.3 → 2.0.0 |
+
+**When in doubt, it's a MINOR.** PATCH is only for pure bug fixes with
+no new behavior. If you added a flag, an option, a new endpoint — it's
+MINOR, even if it "feels small."
+
+### 3. Changelog generation
+
+Compile changes into `CHANGELOG.md`, grouped by type:
+
+```markdown
+## [1.3.0] - 2025-03-15
+
+### Added
+- Webhook notification support for order status changes (#142)
+
+### Changed
+- Increased default pagination limit from 20 to 50 (#138)
+
+### Fixed
+- Timezone conversion error in reporting module (#145)
+
+### Breaking
+- Removed deprecated `/api/v1/users` endpoint (#130). Use `/api/v2/users`.
+```
+
+Write entries for humans, not for commit logs. "Fixed #145" is not a
+changelog entry. "Fixed timezone conversion error that caused incorrect
+daily totals in the reporting module" is.
+
+### 4. Release commit and tag
+
+```bash
+git add CHANGELOG.md package.json  # (or equivalent version files)
+git commit -m "chore(release): version {{VERSION}}"
+git tag -a v{{VERSION}} -m "Version {{VERSION}}"
+```
+
+### 5. Merge to main
+
+Ensure all release updates are merged into the default branch
+`{{DEFAULT_BRANCH}}`. The tagged commit must be reachable from the
+default branch.
+
+## Rollback plan
+
+Every release must document its rollback strategy before shipping:
+
+- **Stateless services:** Rollback is redeploying the previous version.
+  Confirm the previous Docker image / artifact is still available.
+- **Database migrations included:** Rollback requires a reverse
+  migration. Write and test the reverse migration *before* releasing.
+  If the migration is not reversible (dropped column, data transformation),
+  document the manual recovery procedure.
+- **Breaking API changes:** Rollback may require client-side changes.
+  Use API versioning to maintain the old endpoint during the transition
+  period.
+
+## Database migration safety
+
+Migrations are the riskiest part of most releases. Rules:
+
+1. **Forward-only in production.** Never hand-edit a production database.
+2. **Backward-compatible by default.** The old code should still work
+   after the migration runs (deploy migration first, then new code).
+3. **Additive changes are safe:** new tables, new columns (nullable or
+   with defaults), new indexes.
+4. **Destructive changes require a multi-step release:**
+   - Release 1: Add the new column, start writing to both old and new.
+   - Release 2: Backfill data, switch reads to new column.
+   - Release 3: Remove the old column.
+5. **Index creation:** Use `CREATE INDEX CONCURRENTLY` (Postgres) or
+   equivalent. Large indexes on production tables can lock writes.
+
+## Feature flag coordination
+
+When releasing behind feature flags:
+
+- Default new flags to **off** in production.
+- The release changelog should note which flags are included and their
+  default state.
+- Remove flags promptly after the feature is fully rolled out. Stale
+  flags are technical debt that compounds — each flag doubles the number
+  of code paths to test.
+
+## Post-release monitoring
+
+After deploying:
+
+1. Watch error rates for 15 minutes. Any spike → investigate immediately.
+2. Check key metrics (latency, throughput, error rate) against the
+   pre-release baseline.
+3. If metrics degrade beyond acceptable thresholds, execute the rollback
+   plan. Don't debug in production under pressure — roll back first,
+   investigate second.