create-agent-room 1.2.1

package/templates/skill-packs/security/security-principles.md

@@ -0,0 +1,127 @@
+---
+name: security-principles
+description: "Use when dealing with database operations, authentication, user input parsing, secrets management, API security, or any code that handles untrusted data."
+---
+
+# Security Principles
+
+## Overview
+
+Secure coding is not an afterthought — it's a default. Agents must write
+secure code from the first line. A security bug that ships is orders of
+magnitude more expensive than one caught during development.
+
+## The iron law
+
+```
+ALL CLIENT DATA IS UNTRUSTED UNTIL VALIDATED ON THE SERVER
+```
+
+This applies to query parameters, request bodies, headers, cookies, file
+uploads, and URL paths. No exceptions. "The frontend validates it" is not
+a security control — it's a convenience for the user.
+
+## The threat model
+
+### 1. Injection attacks
+
+**Rule:** Never construct queries, commands, or markup by concatenating
+user input.
+
+- **SQL:** Always use parameterized queries or ORMs. Never build query
+  strings with template literals or concatenation.
+  ```
+  BAD:  db.query(`SELECT * FROM users WHERE id = ${req.params.id}`)
+  GOOD: db.query('SELECT * FROM users WHERE id = $1', [req.params.id])
+  ```
+- **NoSQL:** Same rule applies. MongoDB's `$gt`, `$ne` operators in
+  user input can bypass authentication. Validate input types explicitly.
+- **OS commands:** Never pass user input to `exec()` or `system()`. Use
+  `execFile()` with an argument array. If shell execution is unavoidable,
+  use an allowlist of permitted values.
+- **HTML/XSS:** Sanitize all user-generated content before rendering.
+  Use the framework's built-in escaping (React's JSX, Django's template
+  engine). If inserting raw HTML, use a sanitization library with an
+  allowlist, not a denylist.
+
+### 2. Secret exposure
+
+**Rule:** Never check in API keys, passwords, tokens, or credentials.
+
+- Store secrets in environment variables. Reference them via
+  `process.env`, `os.environ`, or equivalent.
+- Add files containing secrets to `.gitignore` immediately.
+- Use `.env.example` with placeholder values, never `.env` with real
+  values committed to the repo.
+- **If a secret is committed by accident:**
+  1. Rotate the secret immediately — assume it's compromised.
+  2. Remove from git history using `git filter-branch` or BFG Repo Cleaner.
+  3. Append to `.agent-room/anti-patterns.md`: what happened, how it
+     slipped through, what rule prevents recurrence.
+  4. Force-push the cleaned history (coordinate with the team).
+
+### 3. Authentication and authorization
+
+**Rule:** Validate the user session and permissions on the server side
+for every request, not just in the UI.
+
+- **Token lifecycle:** Access tokens should be short-lived (15-60
+  minutes). Use refresh tokens for re-authentication. Implement token
+  revocation for logout and password changes.
+- **Password storage:** Use bcrypt, scrypt, or Argon2 with appropriate
+  work factors. Never use MD5, SHA-1, or SHA-256 alone for password
+  hashing — they're too fast.
+- **Session management:** Regenerate session IDs after login. Set
+  cookies with `HttpOnly`, `Secure`, and `SameSite=Strict` flags.
+- **Authorization checks:** Check permissions at the data layer, not
+  just the route layer. A user should not be able to access another
+  user's data by guessing the resource ID (IDOR vulnerability).
+
+### 4. Input validation and sanitization
+
+**Rule:** Parse and validate schemas explicitly. Reject what you don't
+expect rather than trying to clean what you don't understand.
+
+- Define expected input shapes using validation libraries (Joi, Zod,
+  Pydantic, serde). Reject requests that don't match the schema.
+- Validate types, lengths, ranges, and formats. A "name" field that
+  accepts 10MB of text is a denial-of-service vector.
+- File uploads: validate MIME type (by content, not just extension),
+  enforce size limits, store outside the web root, generate random
+  filenames.
+
+### 5. Dependency security
+
+**Rule:** Audit dependencies regularly. A vulnerability in a dependency
+is a vulnerability in your application.
+
+- Run `npm audit`, `pip audit`, `cargo audit`, or equivalent as part of
+  CI. Fail the build on high/critical severity findings.
+- Review new dependencies before adding them: maintenance status, known
+  vulnerabilities, transitive dependency count, license compatibility.
+- Pin dependency versions in production. Use lockfiles (`package-lock.json`,
+  `Pipfile.lock`, `Cargo.lock`) and commit them.
+- **When an audit finds a vulnerability:**
+  1. Check if the vulnerable code path is actually reachable in your app.
+  2. If yes, update immediately. If no, document and schedule.
+  3. Don't suppress audit warnings without documenting why.
+
+### 6. Transport and configuration security
+
+**Rule:** Enforce HTTPS. Configure security headers. Don't trust defaults.
+
+- **CORS:** Use an explicit allowlist of permitted origins. Never use
+  `Access-Control-Allow-Origin: *` with credentials. Misconfigured CORS
+  is one of the most common agent-introduced security bugs.
+- **CSP:** Set `Content-Security-Policy` headers. Start restrictive and
+  loosen only as needed, with documentation for each exception.
+- **Rate limiting:** Apply rate limits to authentication endpoints, API
+  endpoints, and any resource-intensive operations.
+
+## Red flags — stop and review
+
+"We'll add security later" · skipping input validation because "it's an
+internal API" · storing secrets in config files committed to git · using
+`eval()` or `Function()` with user input · disabling HTTPS for local
+convenience and forgetting to re-enable · "the frontend prevents this" as
+a security justification.

package/templates/skill-packs/testing/integration-testing.md

@@ -0,0 +1,127 @@
+---
+name: integration-testing
+description: "Use when implementing integration, API, or database-driven tests, or when deciding the right test type for a cross-boundary behavior."
+---
+
+# Integration Testing
+
+## Overview
+
+Integration tests verify that components work together correctly across
+real boundaries — HTTP, databases, message queues, file systems. They
+answer: "do these pieces actually connect?" Unit tests can't answer that
+question because they mock the boundaries away.
+
+## The iron law
+
+```
+NO CROSS-BOUNDARY BEHAVIOR SHIPS WITHOUT AN INTEGRATION TEST
+```
+
+If two components talk to each other and you only have unit tests,
+you've tested that each component works alone — not that they work
+together. That's where production bugs live.
+
+## The test pyramid — when to use what
+
+```
+         /  E2E  \        Few, slow, expensive, high confidence
+        /----------\
+       / Integration \    Moderate count, real boundaries, focused
+      /----------------\
+     /    Unit Tests     \  Many, fast, isolated, one behavior each
+    /--------------------\
+```
+
+- **Unit tests:** One function, one behavior, no I/O. Fast. Write many.
+- **Integration tests:** Real database, real HTTP, real file system. Test
+  the boundary, not the business logic behind it. Write enough to cover
+  every boundary.
+- **E2E tests:** Full user flow through the running application. Write
+  sparingly — they're slow and brittle.
+
+**Default rule:** if the behavior crosses a process, network, or storage
+boundary, it needs an integration test. If it doesn't, a unit test is
+sufficient.
+
+## Core principles
+
+### 1. Isolated state
+
+Each test runs against a clean state. Techniques:
+
+- **Database:** Use transactions that roll back after each test, or
+  truncate tables in `beforeEach`. Never rely on insertion order from
+  a previous test.
+- **File system:** Use a temporary directory created in `beforeEach`,
+  removed in `afterEach`.
+- **External services:** Use dedicated test instances or containers,
+  never shared staging environments.
+
+### 2. Real over mocks
+
+Use actual databases (Docker containers, SQLite in-memory, test
+instances) and real file systems where possible. Mock only what you
+cannot control:
+
+- **Mock:** Third-party APIs with rate limits, payment gateways, email
+  services.
+- **Don't mock:** Your own database, your own file system, your own
+  message queue. If you mock your own infrastructure, you're testing
+  your assumptions about it, not the infrastructure itself.
+
+### 3. No flakiness
+
+Flaky tests are worse than no tests — they train the team to ignore
+failures.
+
+- **Never use** `sleep(N)` or arbitrary timeouts. Use wait-for-condition,
+  polling with backoff, or event listeners.
+- **Network tests:** Use retry with assertion (poll until the expected
+  state appears, with a hard timeout that fails explicitly).
+- **Ordering:** Tests must not depend on execution order. If test B
+  fails only when test A runs first, the tests share state — fix the
+  isolation.
+
+### Investigating flaky tests
+
+When a test flakes:
+
+1. **Don't "just retry."** Retrying masks the problem.
+2. **Reproduce locally** — run the test 50 times in a loop. If it passes
+   every time locally, the flakiness is environmental (timing, resources,
+   network).
+3. **Check for shared state** — is another test leaving data behind?
+4. **Check for timing assumptions** — is the test assuming an operation
+   completes within a specific time?
+5. **If genuinely non-deterministic** (rare), add deterministic assertions
+   with explicit timeouts and document why in a comment.
+
+## Contract testing for API boundaries
+
+When your service calls another service (or is called by one), unit tests
+and integration tests aren't enough. Contract tests verify that the
+**interface** between services stays compatible:
+
+- **Consumer-driven contracts:** The consumer defines what it expects
+  (request shape, response shape). The provider runs the contract as a
+  test. If the provider changes break the contract, the test fails before
+  deployment.
+- **Use when:** You own both sides of an API, or when a third-party API
+  has a versioning scheme you need to track.
+
+## Coverage guidance
+
+- **Don't chase 100% integration test coverage.** Integration tests are
+  expensive to run. Cover every boundary, every error path at the
+  boundary (timeouts, connection failures, malformed responses), and the
+  critical happy path.
+- **Meaningful coverage:** "Every database query is exercised against a
+  real database" is a better target than "95% line coverage."
+- **Unmockable code is a smell:** If you can't test a component without
+  mocking 6 dependencies, the component has too many responsibilities.
+  Refactor before adding more tests.
+
+## Commands
+
+* Run integration tests: `{{TEST_COMMAND}}`

package/templates/stacks/python/.agent-room/skills/python-testing.md

@@ -0,0 +1,59 @@
+---
+name: python-testing
+description: "Python testing best practices: pytest patterns, fixtures, mocking, and TDD workflows"
+---
+
+# Python Testing Best Practices
+
+## Test discovery and structure
+
+- Store tests in `tests/` or adjacent to source files as `*_test.py` or `test_*.py`
+- Use pytest fixtures for setup/teardown
+- Group related tests in test classes with a `Test` prefix
+
+## Pytest essentials
+
+```python
+import pytest
+
+@pytest.fixture
+def example_resource():
+    resource = setup()
+    yield resource
+    teardown(resource)
+
+def test_with_fixture(example_resource):
+    result = example_resource.do_work()
+    assert result == expected
+```
+
+## Mocking and isolation
+
+Use `unittest.mock` or `pytest-mock`:
+
+```python
+from unittest.mock import Mock, patch
+
+def test_with_mock(mocker):
+    mock_service = mocker.patch('module.Service')
+    mock_service.return_value = Mock(status='ok')
+    assert your_code_using_service()
+```
+
+## Red-Green-Refactor cycle
+
+1. **Red:** Write a failing test; ensure it fails for the right reason
+2. **Green:** Implement the minimal code to pass the test
+3. **Refactor:** Improve code quality without changing behavior
+
+```bash
+pytest tests/ --tb=short
+```
+
+## Coverage
+
+```bash
+pytest --cov=src tests/
+```
+
+Aim for >80% coverage, but prioritize testing critical paths.

package/templates/stacks/python/AGENTS.md.tmpl

@@ -0,0 +1,35 @@
+# Agent Instructions — {{PROJECT_NAME}} (Python)
+
+This file supplements the base AGENTS.md with Python-specific guidance.
+
+## Python-specific workflow
+
+1. **Virtual Environment:** Always operate within a virtual environment (venv, poetry, pipenv, or similar).
+2. **Type Hints:** Use type hints for function signatures (not required but encouraged for clarity).
+3. **Testing:** Use pytest for unit tests; write tests first (TDD), then implement.
+4. **Linting:** Run flake8 or ruff; fix all linting errors before committing.
+5. **Dependencies:** Pin versions in requirements.txt or pyproject.toml; review security advisories.
+
+## Language-specific principles
+
+- **PEP 8 compliance:** Follow Python's style guide (4-space indentation, line length ≤ 79 for code).
+- **Readability > Cleverness:** Prefer explicit over implicit; write code for the next human.
+- **Avoid Dynamic Features:** Minimize use of `__getattr__`, `eval()`, `exec()` unless absolutely necessary.
+- **Async/Await:** If using asyncio, be consistent; don't mix sync and async without clear boundaries.
+
+## Common pitfalls
+
+- ❌ Mixing dependency managers (e.g., pip and poetry)
+- ❌ Hardcoding paths; use `pathlib.Path` instead
+- ❌ Catching bare `Exception`; catch specific exceptions
+- ❌ Importing * (`from module import *`)
+- ✅ Always use context managers (`with` statements) for file/resource handling
+
+## Stack detection
+
+This room was scaffolded for Python. Detected configuration:
+- **Package Manager:** {{PACKAGE_MANAGER}}
+- **Test Command:** {{TEST_COMMAND}}
+- **Lint Command:** {{LINT_COMMAND}}
+
+See `.agent-room/principles.md` and `workflow-classifier.md` for the full playbook.

package/templates/stacks/react/.agent-room/skills/react-component-testing.md

@@ -0,0 +1,76 @@
+---
+name: react-component-testing
+description: "React component testing with React Testing Library: user-centric tests, async, and mocking"
+---
+
+# React Component Testing
+
+## Testing user interactions, not implementation
+
+```typescript
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('submits form when user clicks button', async () => {
+  const user = userEvent.setup();
+  const handleSubmit = jest.fn();
+
+  render(<MyForm onSubmit={handleSubmit} />);
+
+  const input = screen.getByLabelText('Name');
+  await user.type(input, 'John');
+
+  const button = screen.getByRole('button', { name: /submit/i });
+  await user.click(button);
+
+  expect(handleSubmit).toHaveBeenCalledWith('John');
+});
+```
+
+## Async patterns
+
+```typescript
+test('displays data after loading', async () => {
+  render(<DataComponent />);
+
+  // Component starts with loading state
+  expect(screen.getByText(/loading/i)).toBeInTheDocument();
+
+  // Wait for data to appear
+  const element = await screen.findByText('Data loaded');
+  expect(element).toBeInTheDocument();
+});
+```
+
+## Mocking hooks and context
+
+```typescript
+jest.mock('./hooks', () => ({
+  useCustomHook: () => ({ data: 'mocked' })
+}));
+
+test('uses mocked hook', () => {
+  render(<ComponentUsingHook />);
+  expect(screen.getByText('mocked')).toBeInTheDocument();
+});
+```
+
+## Avoid testing implementation details
+
+- ❌ Testing internal state directly
+- ❌ Testing component hierarchy
+- ❌ Querying by TestID (except as last resort)
+- ✅ Query by accessible roles, labels, text
+
+## Red-Green-Refactor
+
+1. Write test that describes user behavior (red)
+2. Implement component to pass test (green)
+3. Refactor component for clarity (refactor)
+
+```bash
+npm test -- --watch
+npm test -- --coverage
+```
+
+Target >80% coverage, prioritizing critical user flows.

package/templates/stacks/react/AGENTS.md.tmpl

@@ -0,0 +1,37 @@
+# Agent Instructions — {{PROJECT_NAME}} (React)
+
+This file supplements the base AGENTS.md with React-specific guidance.
+
+## React-specific workflow
+
+1. **Component API:** Start with props and state; avoid lifting state too early.
+2. **Hooks:** Use React hooks (useState, useEffect, useContext); avoid class components.
+3. **Testing:** Test behavior, not implementation; use React Testing Library.
+4. **Styling:** Prefer CSS Modules or Tailwind; avoid inline styles except for dynamic values.
+5. **State Management:** Use Context API for app state; Redux only if complexity warrants.
+
+## Component design principles
+
+- **Single Responsibility:** One component = one concern
+- **Props Over State:** Push state up only when necessary
+- **Avoid Prop Drilling:** Use Context API to avoid passing props through many levels
+- **Controlled Components:** Form inputs should be controlled by React state
+- **Fragment Use:** Use `<>` for wrapper-less grouping
+
+## Common pitfalls
+
+- ❌ State mutations (e.g., `array.push()` instead of `[...array, item]`)
+- ❌ Missing dependencies in useEffect
+- ❌ Render functions inside render (creates new function every render)
+- ❌ Inline object literals as props (creates new object every render)
+- ✅ Use React DevTools profiler to find performance issues
+- ✅ Memoize expensive calculations with `useMemo`
+
+## Stack detection
+
+This room was scaffolded for React. Detected configuration:
+- **Package Manager:** {{PACKAGE_MANAGER}}
+- **Test Command:** {{TEST_COMMAND}}
+- **Lint Command:** {{LINT_COMMAND}}
+
+See `.agent-room/principles.md` and `workflow-classifier.md` for the full playbook.

package/templates/stacks/typescript/.agent-room/skills/typescript-testing.md

@@ -0,0 +1,63 @@
+---
+name: typescript-testing
+description: "TypeScript testing best practices: Jest/Vitest, mocking, async patterns, and TDD"
+---
+
+# TypeScript Testing Best Practices
+
+## Test structure and discovery
+
+- Store tests in `tests/` or co-locate as `.test.ts` / `.spec.ts`
+- Use Jest or Vitest; configure in `jest.config.ts` or `vitest.config.ts`
+- Group related tests using `describe()` blocks
+
+## Jest/Vitest basics
+
+```typescript
+describe('MyFunction', () => {
+  it('should return expected value', () => {
+    const result = myFunction(input);
+    expect(result).toBe(expected);
+  });
+
+  it('should handle async work', async () => {
+    const result = await asyncFunction();
+    expect(result).toEqual({ data: 'value' });
+  });
+});
+```
+
+## Mocking in TypeScript
+
+```typescript
+jest.mock('./module');
+import { myExport } from './module';
+
+const mockFunction = myExport as jest.MockedFunction<typeof myExport>;
+mockFunction.mockReturnValue('mocked');
+```
+
+## Async testing
+
+```typescript
+it('should handle promises', () => {
+  return expect(asyncFunction()).resolves.toBe(expected);
+});
+
+it('should handle rejections', () => {
+  return expect(asyncFunction()).rejects.toThrow(Error);
+});
+```
+
+## Red-Green-Refactor
+
+1. Write a failing test (red)
+2. Implement minimal code to pass (green)
+3. Refactor for quality (refactor)
+
+```bash
+npm test -- --watch
+npm test -- --coverage
+```
+
+Target >80% coverage on critical paths.

package/templates/stacks/typescript/AGENTS.md.tmpl

@@ -0,0 +1,36 @@
+# Agent Instructions — {{PROJECT_NAME}} (TypeScript)
+
+This file supplements the base AGENTS.md with TypeScript-specific guidance.
+
+## TypeScript-specific workflow
+
+1. **Strict Mode:** Always compile with `"strict": true` in tsconfig.json.
+2. **Type Safety:** Write types for public APIs; use `unknown` before `any`.
+3. **Testing:** Use Jest or Vitest; write tests first (TDD), then implement.
+4. **Linting:** Run ESLint with TypeScript plugin; fix all errors before committing.
+5. **Build:** Compile TypeScript before running; catch type errors in CI.
+
+## Language-specific principles
+
+- **Explicit over implicit:** Declare types, don't rely on inference alone
+- **Interfaces for contracts:** Define interfaces for API boundaries
+- **Discriminated unions:** Use discriminated unions for type-safe variant handling
+- **Avoid `any`:** Use generics or `unknown` instead
+- **Strict null checks:** Enable strictNullChecks to prevent null reference errors
+
+## Common pitfalls
+
+- ❌ Leaving `any` in production code
+- ❌ Not checking for null/undefined (nullish coalescing is your friend)
+- ❌ Over-using generics; keep types readable
+- ❌ Ignoring TypeScript errors with `@ts-ignore`
+- ✅ Use `.ts` for backend, `.tsx` for React components
+
+## Stack detection
+
+This room was scaffolded for TypeScript. Detected configuration:
+- **Package Manager:** {{PACKAGE_MANAGER}}
+- **Test Command:** {{TEST_COMMAND}}
+- **Lint Command:** {{LINT_COMMAND}}
+
+See `.agent-room/principles.md` and `workflow-classifier.md` for the full playbook.