create-agent-room 1.2.1

package/templates/adapters/clinerules.tmpl

@@ -0,0 +1,14 @@
+# Cline rules — {{PROJECT_NAME}}
+
+Read [`AGENTS.md`](AGENTS.md) and everything under
+[`.agent-room/`](.agent-room/) before making non-trivial changes:
+
+- `.agent-room/principles.md` — how to get reliable output from the model.
+- `.agent-room/workflow-classifier.md` — size the process to the work
+  (Bug / Enhancement / Feature / Product).
+- `.agent-room/skills/` — brainstorming, writing-plans, TDD, systematic
+  debugging, verification-before-completion. Follow these as procedures,
+  not suggestions.
+- `.agent-room/anti-patterns.md` and `.agent-room/decisions.md` — check
+  before repeating a past mistake; append after a new one or a notable
+  decision.

package/templates/adapters/codexrules.tmpl

@@ -0,0 +1,45 @@
+# Codex rules — {{PROJECT_NAME}}
+
+Read [`AGENTS.md`](AGENTS.md) and everything under
+[`.agent-room/`](.agent-room/) before making non-trivial changes:
+
+- `.agent-room/principles.md` — how to get reliable output from the model.
+- `.agent-room/workflow-classifier.md` — size the process to the work
+  (Bug / Enhancement / Feature / Product).
+- `.agent-room/skills/` — brainstorming, writing-plans, TDD, systematic
+  debugging, verification-before-completion. Follow these as procedures,
+  not suggestions.
+- `.agent-room/anti-patterns.md` and `.agent-room/decisions.md` — check
+  before repeating a past mistake; append after a new one or a notable
+  decision.
+
+## Core rules
+
+1. **Always read AGENTS.md first.** It's the entry point for any coder.
+
+2. **Classify the work:** Use `.agent-room/workflow-classifier.md` to size
+   the process (bug fix ≠ feature ≠ enhancement). Don't over-engineer.
+
+3. **Brainstorm before coding:** For any non-trivial change, brainstorm
+   2-3 approaches with tradeoffs before writing code.
+
+4. **Write tests first (TDD):** Failing test → implementation → passing test.
+   Then refactor. This catches bugs early.
+
+5. **Verify before handing off:** Run the full test suite and checks before
+   marking work complete. Leave the codebase in a shippable state.
+
+6. **Close the loop:** Before ending a session, append decisions and
+   anti-patterns to `.agent-room/decisions.md` and `.agent-room/anti-patterns.md`.
+   Document what you learned.
+
+## Guardrails
+
+Review `.agent-room/guardrails.md` for protected paths, approval requirements,
+and forbidden actions. Some changes require human review.
+
+## Session logs
+
+Save a session log to `.agent-room/sessions/` following the format in
+`.agent-room/coordination/session-log-format.md`. Include goal, actions,
+decisions, and outcome.

package/templates/adapters/cursorrules.tmpl

@@ -0,0 +1,14 @@
+# Cursor rules — {{PROJECT_NAME}}
+
+Read [`AGENTS.md`](../AGENTS.md) and everything under
+[`.agent-room/`](../.agent-room/) before making non-trivial changes:
+
+- `.agent-room/principles.md` — how to get reliable output from the model.
+- `.agent-room/workflow-classifier.md` — size the process to the work
+  (Bug / Enhancement / Feature / Product).
+- `.agent-room/skills/` — brainstorming, writing-plans, TDD, systematic
+  debugging, verification-before-completion. Follow these as procedures,
+  not suggestions.
+- `.agent-room/anti-patterns.md` and `.agent-room/decisions.md` — check
+  before repeating a past mistake; append after a new one or a notable
+  decision.

package/templates/adapters/git-hooks/guardrails-check.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Pre-commit hook for guardrails enforcement
+ * Prevents commits that violate project guardrails
+ *
+ * Checks:
+ * - Protected paths: blocks commits to paths requiring approval
+ * - Forbidden actions: blocks commits containing dangerous patterns (e.g., hard-coded credentials)
+ * - Minimum checks before merge
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const projectRoot = process.cwd();
+const guardrailsPath = path.join(projectRoot, '.agent-room', 'guardrails.json');
+
+// Allow override via env variable
+const ALLOW_GUARDRAILS_BYPASS = process.env.GUARDRAILS_BYPASS || process.env.SKIP_GUARDRAILS_CHECK;
+
+if (!fs.existsSync(guardrailsPath)) {
+  // No guardrails file, allow commit
+  process.exit(0);
+}
+
+let guardrails = {};
+try {
+  guardrails = JSON.parse(fs.readFileSync(guardrailsPath, 'utf8'));
+} catch (err) {
+  console.error(`⚠️  Failed to parse guardrails.json: ${err.message}`);
+  process.exit(0);
+}
+
+// Get staged files
+let stagedFiles = [];
+try {
+  const output = execSync('git diff --cached --name-only', { encoding: 'utf8' });
+  stagedFiles = output.trim().split('\n').filter(Boolean);
+} catch (err) {
+  // Not a git repo or no staged files
+  process.exit(0);
+}
+
+const protectedPaths = guardrails.protectedPaths || [];
+const forbiddenPatterns = guardrails.forbiddenActions || [];
+
+let violations = [];
+
+// Check protected paths
+for (const file of stagedFiles) {
+  for (const protectedPath of protectedPaths) {
+    if (isPathProtected(file, protectedPath)) {
+      violations.push(`Protected path violation: ${file}`);
+    }
+  }
+}
+
+// Check for forbidden patterns in staged content
+for (const file of stagedFiles) {
+  if (!fs.existsSync(file)) continue;
+
+  // Skip binary files and very large files
+  if (isBinaryFile(file) || fs.statSync(file).size > 1_000_000) {
+    continue;
+  }
+
+  try {
+    // Get staged content (not working tree)
+    const stagedContent = execSync(`git show :${file}`, { encoding: 'utf8' });
+
+    for (const pattern of forbiddenPatterns) {
+      if (pattern.match(/^\/.*\/[gimuy]*$/) || pattern.startsWith('(?:') || pattern.includes('(?:')) {
+        // It's a regex
+        try {
+          const regex = new RegExp(pattern);
+          if (regex.test(stagedContent)) {
+            violations.push(`Forbidden pattern found in ${file}: ${pattern}`);
+          }
+        } catch (regexErr) {
+          // Invalid regex, skip
+        }
+      } else {
+        // Literal string
+        if (stagedContent.includes(pattern)) {
+          violations.push(`Forbidden pattern found in ${file}: ${pattern}`);
+        }
+      }
+    }
+  } catch (err) {
+    // File might not exist in index yet
+  }
+}
+
+if (violations.length > 0) {
+  console.error('');
+  console.error('❌ Guardrails Check Failed: Commit violates project guardrails');
+  console.error('');
+  for (const violation of violations) {
+    console.error(`  - ${violation}`);
+  }
+  console.error('');
+  console.error('To bypass guardrails (requires approval), use:');
+  console.error('  GUARDRAILS_BYPASS=1 git commit');
+  console.error('');
+
+  if (!ALLOW_GUARDRAILS_BYPASS) {
+    process.exit(1);
+  }
+
+  console.warn('⚠️  Guardrails bypass enabled - proceeding with commit');
+}
+
+process.exit(0);
+
+function isPathProtected(filePath, protectedPattern) {
+  // Normalize paths for comparison
+  const normalized = filePath.replace(/\\/g, '/');
+  const pattern = protectedPattern.replace(/\\/g, '/');
+
+  // Handle glob patterns
+  if (pattern.includes('*')) {
+    const regexPattern = pattern
+      .split('*')
+      .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+      .join('.*');
+    return new RegExp(`^${regexPattern}$`).test(normalized);
+  }
+
+  // Direct match or prefix match
+  return normalized === pattern || normalized.startsWith(pattern + '/');
+}
+
+function isBinaryFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const binaryExts = ['.png', '.jpg', '.jpeg', '.gif', '.pdf', '.zip', '.tar', '.exe', '.dll', '.so', '.bin'];
+  return binaryExts.includes(ext);
+}

package/templates/adapters/git-hooks/pre-commit.tmpl

@@ -0,0 +1,43 @@
+#!/bin/sh
+# Git pre-commit hook generated by create-agent-room
+# Enforces the closing-the-loop discipline and guardrails checks for all commits.
+
+if ! [ -d ".agent-room" ]; then
+  exit 0
+fi
+
+# First, run guardrails check
+if [ -f ".agent-room/hooks/guardrails-check.js" ]; then
+  node ".agent-room/hooks/guardrails-check.js"
+  if [ $? -ne 0 ]; then
+    exit 1
+  fi
+fi
+
+# List of changed files staged for commit
+STAGED_FILES=$(git diff --cached --name-only)
+
+# Check if there are non-scaffold files changed
+HAS_SOURCE_CHANGES=false
+HAS_LOG_TOUCHED=false
+
+for file in $STAGED_FILES; do
+  case "$file" in
+    .agent-room/anti-patterns.md|.agent-room/decisions.md)
+      HAS_LOG_TOUCHED=true
+      ;;
+    AGENTS.md|CLAUDE.md|.claude/*|.cursor/*|.windsurfrules|.clinerules|docs/plans/*)
+      # Skip scaffold/plan updates
+      ;;
+    *)
+      HAS_SOURCE_CHANGES=true
+      ;;
+  esac
+done
+
+if [ "$HAS_SOURCE_CHANGES" = true ] && [ "$HAS_LOG_TOUCHED" = false ]; then
+  echo "ERROR: Close-the-loop check failed." >&2
+  echo "You changed source files but did not update .agent-room/anti-patterns.md or .agent-room/decisions.md." >&2
+  echo "To bypass, append a waiver to decisions.md, or commit with 'git commit --no-verify' (use with caution)." >&2
+  exit 1
+fi

package/templates/adapters/windsurfrules.tmpl

@@ -0,0 +1,14 @@
+# Windsurf rules — {{PROJECT_NAME}}
+
+Read [`AGENTS.md`](AGENTS.md) and everything under
+[`.agent-room/`](.agent-room/) before making non-trivial changes:
+
+- `.agent-room/principles.md` — how to get reliable output from the model.
+- `.agent-room/workflow-classifier.md` — size the process to the work
+  (Bug / Enhancement / Feature / Product).
+- `.agent-room/skills/` — brainstorming, writing-plans, TDD, systematic
+  debugging, verification-before-completion. Follow these as procedures,
+  not suggestions.
+- `.agent-room/anti-patterns.md` and `.agent-room/decisions.md` — check
+  before repeating a past mistake; append after a new one or a notable
+  decision.

package/templates/skill-packs/api-design/api-design.md

@@ -0,0 +1,152 @@
+---
+name: api-design
+description: "Use when designing, implementing, or modifying REST APIs, GraphQL schemas, or any service interface that other systems or clients consume."
+---
+
+# API Design
+
+## Overview
+
+An API is a contract. Unlike internal code, changing an API breaks other
+people's code. Design for clarity, consistency, and evolution from the
+start — retrofitting these qualities is expensive and disruptive.
+
+## The iron law
+
+```
+BREAKING CHANGES REQUIRE A VERSIONED MIGRATION PATH
+```
+
+Never remove, rename, or change the type of an existing field, endpoint,
+or response shape without a deprecation period and a documented migration
+path. "Nobody uses this endpoint" is not evidence — check access logs.
+
+## Resource naming
+
+- Use nouns, not verbs: `/users`, not `/getUsers`.
+- Use plural nouns: `/orders`, not `/order`.
+- Use kebab-case for multi-word resources: `/order-items`, not
+  `/orderItems` or `/order_items`.
+- Nest for relationships: `/users/{id}/orders`, not `/getUserOrders`.
+- Keep nesting shallow (max 2 levels). Deep nesting creates rigid
+  coupling: `/users/{id}/orders/{oid}/items/{iid}/comments` is a sign
+  the resource model needs rethinking.
+
+## HTTP verb semantics
+
+| Verb | Meaning | Idempotent | Safe |
+| --- | --- | --- | --- |
+| GET | Retrieve a resource | Yes | Yes |
+| POST | Create a new resource | No | No |
+| PUT | Replace a resource entirely | Yes | No |
+| PATCH | Partially update a resource | No* | No |
+| DELETE | Remove a resource | Yes | No |
+
+*PATCH is not inherently idempotent but can be designed to be.
+
+**Common agent mistakes:**
+- Using POST for everything (including fetches and updates).
+- Using GET with a request body (not universally supported).
+- Using DELETE to "soft delete" without documenting the behavior.
+
+## Error response contract
+
+Every API should return errors in a **consistent shape**. Don't invent a
+new error format per endpoint.
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_FAILED",
+    "message": "Email address is not valid.",
+    "details": [
+      {
+        "field": "email",
+        "reason": "Must be a valid email address.",
+        "value": "not-an-email"
+      }
+    ]
+  }
+}
+```
+
+Rules:
+- `code` is machine-readable (constant string, not a sentence).
+- `message` is human-readable (for debugging, not for end users).
+- `details` is optional, for validation errors with multiple fields.
+- HTTP status code matches the error type (see table below).
+
+| Status | When to use |
+| --- | --- |
+| 400 | Client sent invalid data (validation, malformed JSON) |
+| 401 | No valid authentication credentials |
+| 403 | Authenticated but not authorized for this resource |
+| 404 | Resource does not exist |
+| 409 | Conflict (duplicate email, version mismatch) |
+| 422 | Request is syntactically valid but semantically wrong |
+| 429 | Rate limit exceeded |
+| 500 | Server error (never expose internal details to the client) |
+
+## Pagination
+
+Never return unbounded lists. Every list endpoint must support pagination.
+
+**Cursor-based (recommended for large datasets):**
+```
+GET /orders?cursor=eyJpZCI6MTIzfQ&limit=20
+```
+Returns a `nextCursor` in the response. Stable under insertions/deletions.
+
+**Offset-based (simpler, less stable):**
+```
+GET /orders?offset=40&limit=20
+```
+Breaks when items are inserted or deleted during pagination. Acceptable
+for small, slowly-changing datasets.
+
+**Always include pagination metadata in the response:**
+```json
+{
+  "data": [...],
+  "pagination": {
+    "nextCursor": "eyJpZCI6MTQzfQ",
+    "hasMore": true
+  }
+}
+```
+
+## Versioning
+
+When a breaking change is unavoidable:
+
+1. **URL versioning** (`/api/v2/users`) — simple, explicit, easy to route.
+2. **Header versioning** (`Accept: application/vnd.api.v2+json`) — cleaner
+   URLs but harder to test in a browser.
+
+**Deprecation protocol:**
+1. Add a `Sunset` header to the old endpoint with the removal date.
+2. Log usage of deprecated endpoints (so you can notify consumers).
+3. Maintain the old version for at least one release cycle (minimum 30
+   days for internal APIs, 90 days for public APIs).
+4. Document migration steps in the changelog.
+
+## Breaking change detection
+
+Before modifying an existing endpoint, check:
+
+- [ ] Am I removing or renaming a field in the response? → Breaking.
+- [ ] Am I changing a field's type (string → number)? → Breaking.
+- [ ] Am I adding a new required field to the request? → Breaking.
+- [ ] Am I changing the HTTP status code for an existing error? → Breaking.
+- [ ] Am I changing the URL path or query parameter names? → Breaking.
+
+If any answer is "yes," use the versioning and deprecation protocol above.
+Adding new optional fields to responses or requests is generally safe.
+
+## Red flags — stop and redesign
+
+Endpoints that accept 20+ query parameters · response shapes that change
+based on the caller's role (use separate endpoints instead) · error
+responses that return HTML instead of JSON · list endpoints without
+pagination · APIs that expose internal database IDs without obfuscation ·
+PUT endpoints that silently ignore unknown fields.

package/templates/skill-packs/code-review/code-review.md

@@ -0,0 +1,113 @@
+---
+name: code-review
+description: "Use when reviewing pull requests, diffs, or code changes — whether as the reviewer or when preparing code for review."
+---
+
+# Code Review
+
+## Overview
+
+Code review is not proofreading — it's a systematic evaluation of whether
+a change is correct, safe, maintainable, and appropriately scoped. An
+agent reviewing code must follow a consistent priority order, not scan
+for whatever catches its eye first.
+
+## The iron law
+
+```
+REVIEW IN PRIORITY ORDER: SECURITY → CORRECTNESS → PERFORMANCE → STYLE
+```
+
+Security bugs that slip through review cause incidents. Correctness bugs
+cause regressions. Performance issues cause gradual degradation. Style
+issues cause friction. Review in order of impact.
+
+## The review process
+
+### 1. Understand the intent first
+
+Before reading a single line of code:
+- Read the PR description, linked issue, or design doc.
+- Understand what the change is *supposed* to do.
+- If the intent is unclear, ask before reviewing the implementation.
+
+### 2. Review in priority order
+
+**Security (blocking):**
+- Does user input flow into queries, commands, or markup unsanitized?
+- Are secrets hardcoded or logged?
+- Are authorization checks present at the data layer, not just the route?
+- Does the change introduce new attack surface (new endpoints, new file
+  uploads, new auth flows)?
+
+**Correctness (blocking):**
+- Does the code actually implement the stated intent?
+- Are edge cases handled (empty input, null, boundary values, concurrency)?
+- Are error paths handled (what happens when the network call fails, the
+  file doesn't exist, the database is down)?
+- Does it have tests? Do the tests cover the meaningful behaviors?
+
+**Performance (blocking if severe, otherwise non-blocking):**
+- N+1 queries in loops?
+- Unbounded data fetches (no pagination, no LIMIT)?
+- Large allocations in hot paths?
+- Missing indexes for new query patterns?
+
+**Style and maintainability (non-blocking):**
+- Naming clarity (would a new team member understand the intent?).
+- Duplication that could be extracted.
+- Comments that explain "why" not "what."
+
+### 3. Check scope
+
+A PR should do one thing. Red flags for scope creep:
+- The PR title says "fix login bug" but also refactors the auth module.
+- More than 500 lines changed for what should be a small fix.
+- Unrelated formatting changes mixed with functional changes.
+
+If scope is too broad, ask the author to split the PR. Don't review a
+kitchen-sink PR — it's impossible to verify correctness when 5 concerns
+are interleaved.
+
+## Writing review comments
+
+### Good comments are actionable
+
+```
+BAD:  "This could be better."
+GOOD: "This query fetches all users without pagination. With 100K users
+       this will OOM the server. Add LIMIT/OFFSET or cursor pagination."
+```
+
+### Distinguish blocking from non-blocking
+
+- **Blocking:** Must be fixed before merge. Security issues, correctness
+  bugs, missing tests for new behavior.
+- **Non-blocking (nit):** Prefix with "nit:" — style suggestions, minor
+  naming improvements, optional refactors. These should not block merge.
+
+### Explain the "why," not just the "what"
+
+```
+BAD:  "Use a Map instead of an Object."
+GOOD: "nit: Consider a Map here — the keys are user-provided strings,
+       and Object prototype pollution is a risk if keys like '__proto__'
+       are possible. Not blocking if input is validated upstream."
+```
+
+## Self-review before requesting review
+
+Before submitting code for review, run your own checklist:
+
+- [ ] Does every new function/endpoint have tests?
+- [ ] Did I remove all debugging artifacts (`console.log`, `debugger`)?
+- [ ] Are there any TODOs that should be resolved before merge?
+- [ ] Is the diff minimal? (No unrelated formatting, no leftover experiments.)
+- [ ] Does the PR description explain what changed and why?
+
+## Red flags — request changes immediately
+
+Hardcoded credentials · missing auth checks on new endpoints · raw SQL
+with string interpolation · `eval()` or `Function()` with external input ·
+tests that assert the implementation rather than the behavior ·
+catch-and-swallow error handling · PRs with no tests for new behavior.

package/templates/skill-packs/database/database-migrations.md

@@ -0,0 +1,123 @@
+---
+name: database-migrations
+description: "Use when writing database schema changes, data migrations, creating indexes, or modifying existing tables in production-facing systems."
+---
+
+# Database Migrations
+
+## Overview
+
+Database migrations are the riskiest part of most releases. Unlike code,
+a bad migration can't be reverted by redeploying the previous version —
+the data has already changed. Every migration must be backward-compatible,
+tested, and paired with a rollback plan.
+
+## The iron law
+
+```
+EVERY MIGRATION MUST BE BACKWARD-COMPATIBLE WITH THE CURRENTLY DEPLOYED CODE
+```
+
+Deploy the migration first, then deploy the new code. If the migration
+breaks the old code, you can't roll back the code deployment without also
+rolling back the migration — and data migrations often can't be rolled back.
+
+## Safe vs. unsafe operations
+
+| Operation | Safe? | Notes |
+| --- | --- | --- |
+| Add a new table | ✅ Yes | No existing code references it |
+| Add a nullable column | ✅ Yes | Old code ignores it |
+| Add a column with a default | ✅ Yes* | *Check if your DB locks the table during ALTER |
+| Add an index | ⚠️ Careful | Use CONCURRENTLY (Postgres) or equivalent |
+| Rename a column | ❌ No | Old code uses the old name |
+| Remove a column | ❌ No | Old code reads the old column |
+| Change a column type | ❌ No | Old code expects the old type |
+| Add a NOT NULL constraint | ❌ No | Existing rows may violate it |
+
+## The multi-step pattern for unsafe changes
+
+Unsafe operations must be split across multiple releases:
+
+### Renaming a column (3 releases)
+
+1. **Release 1:** Add the new column. Write to both old and new. Read
+   from old.
+2. **Release 2:** Backfill the new column from the old. Switch reads to
+   the new column. Stop writing to old.
+3. **Release 3:** Drop the old column.
+
+### Removing a column (2 releases)
+
+1. **Release 1:** Stop reading from the column in code. Stop writing to
+   it. (The column still exists in the database.)
+2. **Release 2:** Drop the column via migration.
+
+### Adding a NOT NULL constraint (2 releases)
+
+1. **Release 1:** Backfill all NULL values. Add application-level
+   validation to prevent new NULLs.
+2. **Release 2:** Add the database-level NOT NULL constraint.
+
+## Index creation
+
+Large indexes on production tables can lock writes for minutes or hours.
+
+- **PostgreSQL:** Always use `CREATE INDEX CONCURRENTLY`. It takes longer
+  but doesn't lock the table.
+- **MySQL:** Use `ALTER TABLE ... ADD INDEX` with `ALGORITHM=INPLACE,
+  LOCK=NONE` where supported.
+- **Measure impact:** On large tables (>1M rows), test the index creation
+  on a staging copy first. Note the time and lock behavior.
+- **Don't create indexes speculatively.** Add an index when you have a
+  slow query that needs it, not "in case someone queries this column
+  later."
+
+## Data backfill strategies
+
+When migrating data between columns or formats:
+
+1. **Batch, don't bulk.** Process 1,000-10,000 rows at a time, not the
+   entire table in one statement. Bulk updates lock rows and can cause
+   replication lag.
+2. **Idempotent backfills.** The backfill script should be safe to run
+   multiple times. Use `WHERE new_column IS NULL` to skip already-migrated
+   rows.
+3. **Monitor progress.** Log how many rows are processed, how many remain,
+   and the estimated time to completion.
+4. **Run during low-traffic windows** if the table is large and heavily
+   written to.
+
+## Migration testing
+
+Before deploying a migration to production:
+
+- [ ] Run the migration against a copy of production data (or a
+  representative staging dataset).
+- [ ] Verify the old code still works after the migration runs.
+- [ ] Verify the new code works after the migration runs.
+- [ ] Measure execution time. If it takes more than 30 seconds, consider
+  breaking it into smaller steps.
+- [ ] Write and test the reverse migration. If the migration is
+  irreversible, document the manual recovery procedure.
+
+## Rollback plan
+
+Every migration must document its rollback before deployment:
+
+- **Reversible migrations:** Include a `down` migration that undoes the
+  change. Test it.
+- **Irreversible migrations** (dropped columns, data transformations):
+  Document what data is lost and the manual recovery procedure. Consider
+  whether a backup should be taken before running.
+- **If in doubt, take a table snapshot** before running destructive
+  migrations. Storage is cheap; data loss is not.
+
+## Red flags — stop and reassess
+
+Migrations that take more than 5 minutes on staging · ALTER TABLE on a
+table with active write traffic without testing lock behavior · backfills
+that process the entire table in one transaction · migrations without a
+tested reverse migration · dropping a column that's still referenced in
+deployed code · adding a foreign key constraint to a large table without
+validating existing data first.