create-agent-room 1.2.1

package/templates/.agent-room/coordination/scope-boundaries.md

@@ -0,0 +1,57 @@
+# Agent Scope Boundaries
+
+## Overview
+
+When multiple agents (or humans and agents) work in the same repository
+simultaneously, conflicts are inevitable unless scope boundaries are
+established. This protocol defines how to partition work to avoid
+stepping on toes.
+
+## The iron law
+
+```
+NEVER MODIFY FILES OUTSIDE YOUR ASSIGNED SCOPE WITHOUT EXPLICIT COORDINATION
+```
+
+If your task is to update the billing module, and you notice a typo in
+the authentication module, do not fix it in the same PR. Scope creep
+causes merge conflicts and blocks parallel work.
+
+## Conflict avoidance
+
+### 1. File-level ownership
+
+During a task, treat the files you are actively modifying as "owned" by
+your session. Before modifying a shared file (like a main router, a
+root configuration file, or `package.json`), check if another session
+might be touching it.
+
+### 2. Lock semantics for shared resources
+
+Certain operations inherently block parallel work:
+
+- **Database migrations:** Do not create a new migration if another
+  agent is currently building one. Coordinate to ensure sequential
+  migration numbering/timestamping.
+- **Dependency updates:** Do not bump a major dependency while another
+  feature branch is in progress, unless coordinated.
+
+### 3. Detect conflicts early
+
+Before starting a new feature branch, or before modifying a highly
+contested file:
+
+1.  Run `git fetch` and `git status`.
+2.  Check for open PRs that might touch the same files.
+3.  If a conflict is highly likely, communicate the overlap before
+    writing code.
+
+## Handling out-of-scope discoveries
+
+When you discover an issue outside your current scope (e.g., a bug in a
+utility function, a missing test in another module):
+
+1.  **Do not fix it immediately** (unless it directly blocks your work).
+2.  **Document it.** Write it down in a tracking issue, a TODO comment,
+    or notify the user.
+3.  **Stay focused.** Finish your assigned task first.

package/templates/.agent-room/coordination/session-log-format.md

@@ -0,0 +1,62 @@
+# Session Log Format
+
+## Overview
+
+Session logs provide observability into what agents are doing, how long
+they take, and what decisions they make. This is crucial for debugging
+agent failures and for team visibility.
+
+## Storage location
+
+Logs should be saved in `.agent-room/sessions/` using the following
+naming convention:
+
+`YYYY-MM-DD-HH-MM-<topic>.md`
+
+Example: `2025-03-15-14-30-fix-login-timeout.md`
+
+## Log format
+
+Every session log must follow this structure:
+
+```markdown
+# Session Log: [Short title]
+
+**Date:** YYYY-MM-DD HH:MM
+**Agent:** [Name/Version of the agent, e.g., Claude 3.5 Sonnet]
+**Classification:** [Bug | Enhancement | Feature | Product]
+
+## Goal
+[One sentence describing what the session aimed to achieve]
+
+## Files touched
+- Read: [list of key files read for context]
+- Created: [list of new files]
+- Modified: [list of modified files]
+
+## Actions taken
+1. [Step 1: e.g., Ran grep to find login timeout config]
+2. [Step 2: e.g., Wrote failing test in auth.test.js]
+3. [Step 3: e.g., Updated timeout value and passed test]
+
+## Tests run
+- Command: `npm test`
+- Result: [Pass | Fail | 2 errors]
+
+## Decisions made
+- [Any non-obvious architecture or design calls made during the session.
+  These should also be appended to .agent-room/decisions.md]
+
+## Outcome
+[Completed | Blocked | Handed Off]
+
+**Handoff note (if applicable):**
+[Insert the handoff note here, following handoff-protocol.md]
+```
+
+## When to write a session log
+
+- **Opt-in:** Depending on the project's `.agent-room.json` config,
+  session logging may be required or optional.
+- **Default:** Write a log at the end of any session that lasted more
+  than 15 minutes or resulted in a non-trivial code change.

package/templates/.agent-room/decisions.md

@@ -0,0 +1,17 @@
+# Decisions Log — {{PROJECT_NAME}}
+
+Short, append-only record of architecture/design decisions and why. A
+decision belongs here if a future session (or a future you) would otherwise
+have to re-derive it from scratch by reading git history.
+
+## Format
+
+```
+### YYYY-MM-DD — short title
+
+**Decision:** what was decided.
+**Why:** the constraint or trade-off that drove it.
+**Rejected:** what else was considered, and why it lost.
+```
+
+<!-- Entries go below this line, newest first. -->

package/templates/.agent-room/guardrails.json

@@ -0,0 +1,23 @@
+{
+  "protectedPaths": [
+    "infrastructure/**",
+    "**/*.tfstate",
+    ".github/workflows/**"
+  ],
+  "requireApprovalFor": [
+    "database migrations",
+    "dependency major version bumps",
+    "changes to CI/CD pipeline",
+    "changes to authentication or authorization logic"
+  ],
+  "scopeGuidance": {
+    "maxFilesPerChange": 20,
+    "maxLinesPerChange": 500
+  },
+  "forbiddenActions": [
+    "deploy to production",
+    "delete database tables in production",
+    "modify authentication middleware without security review",
+    "commit secrets, API keys, or credentials"
+  ]
+}

package/templates/.agent-room/guardrails.md

@@ -0,0 +1,56 @@
+# Agent Guardrails — {{PROJECT_NAME}}
+
+Boundaries and constraints for AI agents working in this codebase. Read
+this file before making changes to protected areas. When in doubt, ask
+the maintainer rather than proceeding.
+
+## Protected paths
+
+Files and directories that agents must not modify without explicit
+approval from the project maintainer:
+
+<!-- Add paths that require human review before agent modification.
+     Examples: infrastructure/, *.tfstate, docker-compose.prod.yml,
+     .github/workflows/, database/migrations/ -->
+
+## Approval requirements
+
+Changes that require human review, even if technically possible:
+
+- Database migrations (schema changes, data backfills)
+- Dependency major version bumps
+- Changes to CI/CD pipeline configuration
+- Changes to authentication or authorization logic
+- Modifications to production deployment configuration
+
+## Scope guidance
+
+Keep individual changes focused and reviewable:
+
+- **Aim for:** single-purpose PRs, one concern per change
+- **Watch for:** PRs touching more than 15-20 files, changes exceeding
+  ~500 lines of new code, or changes that mix refactoring with new features
+- These are guidelines, not hard limits — a migration touching 30 files
+  may be appropriate, but it deserves extra scrutiny
+
+## Forbidden actions
+
+Actions agents must never take, regardless of context:
+
+- Deploy to production without human approval
+- Delete database tables or collections in production
+- Modify authentication middleware without security review
+- Commit secrets, API keys, or credentials to the repository
+- Disable or skip tests to make a build pass
+- Suppress security audit warnings without documenting why
+
+## How to use this file
+
+1. **Before starting work:** Scan the change against protected paths. If
+   the change touches a protected area, ask the maintainer for approval.
+2. **During work:** Check scope guidance. If the change is growing beyond
+   the guidelines, consider splitting it.
+3. **Before finishing:** Verify none of the forbidden actions were taken.
+
+For machine-readable guardrails that CI and tooling can enforce, see
+`.agent-room/guardrails.json`.

package/templates/.agent-room/principles.md

@@ -0,0 +1,306 @@
+# LLM-Native Development Principles
+
+A working reference for getting predictable outcomes out of an LLM coding
+agent. The point is not to sound clever — it's to make outcomes predictable.
+
+## Quick reference
+
+| # | Principle | Default move |
+| --- | --- | --- |
+| 1 | LLMs are retrieval systems | Use precise names, types, constraints, and input context |
+| 2 | Iteration is required | Explore, constrain, refine, verify — don't one-shot |
+| 3 | Context windows forget | Write summary checkpoints to files, not just chat |
+| 4 | Explanation pressure finds weak spots | Ask it to explain, challenge, and restate the work |
+| 5 | Negative knowledge is leverage | Keep an anti-patterns file; one avoided bug beats one good example |
+| 6 | Tests are the spec | Write the test before the implementation |
+| 7 | Specific names retrieve better | Prefer clear, specific, stable names over short or sprawling ones |
+| 8 | Match process to work type | Use the lightest process that still protects quality |
+| 9 | PRD and architecture co-evolve | Let architecture discoveries simplify the requirements |
+| 10 | Serialize state | A checkpoint should let someone else resume without guesswork |
+| 11 | Delegate with rules, not vibes | Can I define correctness right now? Yes: proceed. Missing facts: research. Unclear requirement: escalate. |
+| 12 | Close the loop | Record failures and wins; feed both back into future prompts |
+
+## How they connect
+
+```
+[Foundation] -> [Quality] -> [Process]
+      ^                           |
+      |                           |
+      +-------- learning ---------+
+
+Foundation = model behavior   (1-5)
+Quality    = output quality   (6-7)
+Process    = safe delivery    (8-11)
+Learning   = feeds back in    (12)
+```
+
+---
+
+## Principle 1: LLMs Are Retrieval Systems
+
+**Rule:** Output quality depends on input context quality more than on
+"prompting skill." Fix the input, not the model.
+
+**Violation:** You ask an agent to "add caching." It invents a custom
+in-memory cache using a plain object, ignoring the Redis client already
+configured in `lib/cache.ts`, because nothing in the prompt mentioned
+existing infrastructure. The resulting PR duplicates functionality and
+introduces a cache invalidation bug.
+
+**Compliance:** You tell the agent: "Add response caching to the
+`/api/users` endpoint. The project uses Redis via `lib/cache.ts` — read
+that file first. Cache keys should follow the `resource:id:action` pattern
+established in `lib/cache.ts:L14-L22`. TTL: 5 minutes." The agent retrieves
+the right pattern and extends it.
+
+**Related:** `systematic-debugging.md` Phase 2 (pattern analysis relies on
+giving the model the right reference), `brainstorming.md` (context
+exploration step).
+
+---
+
+## Principle 2: Iteration Is Required
+
+**Rule:** Explore, constrain, refine, verify. Don't one-shot. The first
+answer is a draft, not a deliverable.
+
+**Violation:** You accept the agent's first-pass database schema without
+reviewing it. It normalizes aggressively, creating 7 join tables for what
+could be 3 tables with a JSONB column. The query complexity compounds
+through the entire codebase before anyone notices.
+
+**Compliance:** You ask the agent to propose 2-3 schema approaches, state
+the read/write ratio, then pick one. After the first implementation pass,
+you ask "what are the three most likely failure modes for this schema under
+10x current load?" and refine before committing.
+
+**Related:** `brainstorming.md` (proposes alternatives before committing),
+`writing-plans.md` (breaks work into iterable steps).
+
+---
+
+## Principle 3: Context Windows Forget
+
+**Rule:** Write summary checkpoints to files, not just chat. A decision
+that only lives in a chat message is a decision that will be re-derived
+from scratch in the next session.
+
+**Violation:** Over a 90-minute session, you and the agent agree to use
+event sourcing for the audit log, reject CQRS as overkill, and decide on
+a 30-day retention policy. None of this is written down. The next session
+starts fresh and proposes CQRS for the audit log.
+
+**Compliance:** After each significant decision, you checkpoint to
+`.agent-room/decisions.md`: "Chose event sourcing over CQRS for audit.
+Retention: 30 days. Rationale: read load is low, write-append is the
+dominant pattern." The next session reads decisions.md first.
+
+**Related:** `closing-the-loop.md` (enforces the checkpoint habit),
+`decisions.md` (the storage format).
+
+---
+
+## Principle 4: Explanation Pressure Finds Weak Spots
+
+**Rule:** Ask "explain why" and "what could fail" before shipping. Claims
+the model can't justify are claims it shouldn't make.
+
+**Violation:** The agent produces a retry mechanism with exponential
+backoff. You say "looks good" and ship. In production, the retry loop
+has no jitter, causing thundering herd failures during partial outages
+because all retries hit the same millisecond.
+
+**Compliance:** You ask: "Walk me through what happens when 1,000
+concurrent requests all fail at the same time and all start retrying." The
+agent discovers the jitter gap itself and adds randomized delay before you
+have to file the production incident.
+
+**Related:** `verification-before-completion.md` (evidence before claims),
+`brainstorming.md` (questioning step).
+
+---
+
+## Principle 5: Negative Knowledge Is Leverage
+
+**Rule:** One avoided mistake is worth more than one polished example. Keep
+an anti-patterns file; make the agent read it before every session.
+
+**Violation:** The agent fixes a timezone bug by converting to UTC at the
+API boundary. Two weeks later, a different session encounters the same
+class of bug in reporting and tries local-time comparison first — because
+nobody wrote down the root cause.
+
+**Compliance:** After fixing the timezone bug, the agent appends to
+`anti-patterns.md`: "Date comparisons must use UTC. Local time caused
+silent data corruption in reporting. Rule: all datetime comparisons
+normalized to UTC before comparison." The next session reads this entry
+and avoids the trap entirely.
+
+**Related:** `closing-the-loop.md` (the enforcement mechanism),
+`anti-patterns.md` (the storage format), `systematic-debugging.md`
+(root cause investigation feeds anti-patterns).
+
+---
+
+## Principle 6: Tests Are the Spec
+
+**Rule:** Write the test before the implementation. If the test didn't
+fail first, you don't know if it tests the right thing.
+
+**Violation:** The agent writes a user registration endpoint, then writes
+tests that assert exactly what the code does — including a bug where
+duplicate emails return 200 instead of 409. The test passes, the bug
+ships, and the test provides false confidence.
+
+**Compliance:** The agent writes the test first: `POST /register with an
+already-registered email should return 409 Conflict`. The test fails
+(no implementation yet). The agent writes the handler, the test passes.
+The spec drove the code, not the other way around.
+
+**Related:** `test-driven-development.md` (full TDD process),
+`systematic-debugging.md` Phase 4 (regression test before fix).
+
+---
+
+## Principle 7: Specific Names Retrieve Better
+
+**Rule:** Prefer clear, specific, stable names over short or sprawling
+ones. The model retrieves patterns based on naming — vague names retrieve
+vague patterns.
+
+**Violation:** A module is named `utils.js`. It grows to 400 lines
+containing date formatting, string sanitization, and HTTP helpers. The
+agent asked to "add a utility function" dumps yet another unrelated
+function into the file because the name invites everything.
+
+**Compliance:** The module is split into `date-format.js`,
+`string-sanitize.js`, and `http-helpers.js`. When the agent is asked to
+add date formatting, it finds and extends `date-format.js` without
+touching unrelated code. Retrieval matches intent.
+
+**Related:** `brainstorming.md` (naming is a design decision worth
+discussing), `writing-plans.md` (exact file paths in every task).
+
+---
+
+## Principle 8: Match Process to Work Type
+
+**Rule:** Use the lightest process that still protects quality.
+Over-process wastes time; under-process builds the wrong thing.
+
+**Violation:** A one-line typo fix goes through a full design review,
+PRD, architecture doc, and TDD cycle. Or: a new authentication system is
+built without any design discussion because "we'll figure it out as we
+code."
+
+**Compliance:** The typo fix is classified as Bug → fixed, regression
+test, done in hours. The auth system is classified as Feature → full
+brainstorm, design doc, architecture review, TDD, done in weeks. The
+process matches the risk.
+
+**Related:** `workflow-classifier.md` (the classification system),
+`brainstorming.md` (invoked for Features and Products, not Bugs).
+
+---
+
+## Principle 9: PRD and Architecture Co-Evolve
+
+**Rule:** Let architecture discoveries simplify the requirements. Don't
+treat the first draft of requirements as sacred — the best designs emerge
+when requirements and architecture inform each other.
+
+**Violation:** The PRD demands real-time collaborative editing. The team
+implements CRDTs. Mid-implementation, they discover the actual use case is
+"two people occasionally edit the same document" — last-write-wins with
+conflict detection would have been 90% simpler. But the PRD said
+"real-time collaborative editing" so nobody questioned it.
+
+**Compliance:** During architecture exploration, the agent asks: "The PRD
+says real-time collaboration. What's the expected concurrent-editor count?
+If it's typically 1-2, last-write-wins with conflict UI is dramatically
+simpler." The PRD is updated to reflect the simpler requirement.
+
+**Related:** `brainstorming.md` (propose alternatives), `writing-plans.md`
+(architecture section in plan header).
+
+---
+
+## Principle 10: Serialize State
+
+**Rule:** A checkpoint should let someone else resume without guesswork.
+If you were hit by a bus, could the next person pick up from your notes?
+
+**Violation:** An agent session ends mid-feature with code in a broken
+state. The commit message is "WIP." The decisions made during the session
+are in the chat history that the next session can't access. The next agent
+starts over from scratch.
+
+**Compliance:** Before ending the session, the agent writes a handoff note:
+"Completed: user model and migration. In progress: registration endpoint
+(handler skeleton exists, validation not started). Blocked on: email
+service config (need SMTP credentials in env). Assumptions: using bcrypt
+for passwords per decision 2025-01-15." The next session reads this and
+picks up exactly where the work stopped.
+
+**Related:** `closing-the-loop.md` (enforces serialization at turn end),
+`decisions.md` (persistent state across sessions).
+
+---
+
+## Principle 11: Delegate with Rules, Not Vibes
+
+**Rule:** Before starting work, ask: can I define correctness right now?
+Yes → proceed. Missing facts → research. Unclear requirement → escalate.
+Don't start building on "I think the user probably wants..."
+
+**Violation:** The agent is asked to "improve the search." It spends 4
+hours implementing Elasticsearch integration. The user meant "add a filter
+dropdown to the existing search results page." The work is discarded.
+
+**Compliance:** The agent asks: "Improve search could mean several things.
+Which of these: (A) add filters to existing search, (B) improve result
+relevance ranking, (C) switch to a dedicated search engine like
+Elasticsearch? I recommend starting with A — it's the lowest-risk
+improvement. What do you think?"
+
+**Related:** `brainstorming.md` (clarifying questions step),
+`workflow-classifier.md` (scope determines classification).
+
+---
+
+## Principle 12: Close the Loop
+
+**Rule:** Record failures and wins; feed both back into future prompts.
+Knowledge that isn't written down doesn't survive the session.
+
+**Violation:** The agent discovers that the ORM silently truncates strings
+longer than 255 characters in a specific column. It fixes the schema but
+doesn't record the discovery. Three months later, a different column has
+the same issue and takes another full debugging session to diagnose.
+
+**Compliance:** The agent appends to `anti-patterns.md`: "ORM silently
+truncates strings at column-defined length with no error. Root cause:
+MySQL STRICT_TRANS_TABLES was off. Rule: always enable strict mode; add
+length validation in the application layer, don't rely on the database to
+reject." Future sessions read this entry first.
+
+**Related:** `closing-the-loop.md` (the skill that enforces this
+principle), `anti-patterns.md` and `decisions.md` (the two logs).
+
+---
+
+## Why this matters
+
+Output quality depends on input context quality more than on "prompting
+skill." Most failures trace back to one of:
+
+- Vague or missing context (principle 1) — fix the input, not the model.
+- A single-shot answer treated as final (principle 2) — iterate instead.
+- A long session that silently lost an earlier decision (principle 3) —
+  checkpoint to `.agent-room/decisions.md`.
+- A claim made without forcing the model (or yourself) to explain it
+  (principle 4) — ask "what could fail here?" before shipping.
+- The same mistake repeated because nobody wrote it down (principle 5/12) —
+  log it in `.agent-room/anti-patterns.md`.
+
+> Fill the context with the right information at the right time.

package/templates/.agent-room/sessions/.gitkeep

@@ -0,0 +1,4 @@
+# Agent Sessions
+
+This directory contains session logs generated by AI agents.
+See `../coordination/session-log-format.md` for the required format.

package/templates/.agent-room/skills/brainstorming.md

@@ -0,0 +1,64 @@
+---
+name: brainstorming
+description: "Use before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores intent, requirements and design before implementation."
+---
+
+# Brainstorming Ideas Into Designs
+
+## Overview
+
+Turn an idea into a fully formed design through collaborative dialogue
+before writing any code.
+
+<HARD-GATE>
+Do NOT write code, scaffold a project, or take any implementation action
+until a design has been presented and approved. This applies to every
+project regardless of perceived simplicity.
+</HARD-GATE>
+
+## Anti-pattern: "this is too simple to need a design"
+
+A todo list, a single-function utility, a config change — all of them go
+through this process. "Simple" work is where unexamined assumptions cause
+the most wasted effort. The design can be a few sentences for truly simple
+work, but it must be presented and approved.
+
+## Process
+
+1. **Explore project context** — read `.agent-room/decisions.md`,
+   `.agent-room/anti-patterns.md`, relevant docs, recent commits.
+2. **Ask clarifying questions, one at a time** — multiple-choice preferred,
+   open-ended is fine. Focus on purpose, constraints, success criteria.
+3. **Propose 2-3 approaches** with trade-offs, leading with a recommendation
+   and why.
+4. **Present the design in sections**, scaled to complexity (a few sentences
+   if straightforward, up to 200-300 words if nuanced). Cover architecture,
+   components, data flow, error handling, testing. Ask after each section
+   whether it looks right before moving on.
+5. **Write the approved design** to `docs/plans/YYYY-MM-DD-<topic>-design.md`
+   and commit it.
+6. **Hand off to implementation** — see "After the design" below.
+
+```
+Explore context -> Ask questions (1 at a time) -> Propose 2-3 approaches
+   -> Present design (section by section, approve each) -> Write design doc
+   -> Implementation (see below)
+```
+
+## After the design
+
+- If a `writing-plans`-style skill/convention is available for this
+  project, use it to turn the design into a bite-sized task plan before
+  touching code.
+- Otherwise, proceed straight into TDD (`.agent-room/skills/test-driven-development.md`),
+  using the design doc as the spec, one task at a time, with frequent commits.
+- Do not skip straight to a broad implementation pass — even with an
+  approved design, work task-by-task.
+
+## Key principles
+
+- One question at a time — don't overwhelm with multiple questions.
+- Multiple choice preferred over open-ended when reasonable.
+- YAGNI ruthlessly — remove unnecessary features from the design.
+- Always propose alternatives before settling on one.
+- Get incremental approval; be ready to revise when something doesn't add up.

package/templates/.agent-room/skills/closing-the-loop.md

@@ -0,0 +1,67 @@
+---
+name: closing-the-loop
+description: "Use before ending any turn that fixed a bug, changed behavior, or made a design call - check whether it belongs in anti-patterns.md or decisions.md."
+---
+
+# Closing the Loop
+
+## Overview
+
+Knowledge that isn't written down doesn't survive the session. A bug's root
+cause, a rejected approach, a "this looked right but wasn't" — if it's not in
+`.agent-room/anti-patterns.md` or `.agent-room/decisions.md`, the next
+session (or the next you) re-derives it from scratch, or repeats it.
+
+## The iron law
+
+```
+NO TURN ENDS WITHOUT A LOG CHECK
+```
+
+This doesn't mean every turn needs a log entry — most don't. It means every
+turn that changed behavior or made a non-obvious call must be **checked**
+against the two questions below before you consider the work done.
+
+## The check
+
+Before finishing any turn that touched code outside `.agent-room/` or
+`docs/plans/`, ask:
+
+1. **Did I find a root cause for a bug, or learn that an approach doesn't
+   work?** → append an entry to `.agent-room/anti-patterns.md`.
+2. **Did I make an architecture/design call that wasn't forced — i.e.
+   someone could reasonably ask "why this way?"** → append an entry to
+   `.agent-room/decisions.md`.
+
+If neither applies — a routine, obvious change — say so explicitly rather
+than silently skipping the check. In a project with the Claude Code hook
+installed (see `CLAUDE.md`), state it as a one-line waiver in
+`.agent-room/decisions.md`:
+
+```
+<!-- no-log: routine change, no decision or anti-pattern worth recording -->
+```
+
+This keeps the check enforceable: "I thought about it and there was nothing
+to log" is a valid outcome, but it has to be visible, not assumed.
+
+## What belongs in each log
+
+**`anti-patterns.md`** — things that went wrong: a bug's actual root cause
+(not the symptom), an approach that seemed reasonable but wasn't, a fix that
+got reverted. Short format: what happened, root cause, the rule that would
+have prevented it.
+
+**`decisions.md`** — choices that could have gone another way: picking one
+library/pattern over another, a scope cut, a trade-off accepted under a
+constraint. Short format: the decision, why, what was rejected.
+
+**Skip both for:** typo fixes, formatting, dependency bumps with no
+surprises, anything where the "why" is fully obvious from the diff itself.
+
+## Why this is its own skill, not just advice
+
+`verification-before-completion.md` makes sure you don't claim done without
+evidence. This skill makes sure "done" also means "and I didn't let
+something worth remembering evaporate." They're both completion gates;
+they check different things.