Vibe-coding guard rails

# AGENTS.md: working agreement

How to work in this repository, whatever the stack. Project-specific rules, if any, take precedence.

## Before you start
- Read the README and any `NOTES.md` handoff file first.
- For anything bigger than a small fix (more than ~3 files, a new feature, a refactor, a dependency change),
  use the `plan-then-build` skill: write a short plan and wait for the human to agree.
- If the request is ambiguous, ask one focused question rather than guessing big.

## While you work
- **Small steps.** Make one change that works, verify it, then the next. Prefer several small diffs to one huge one.
- **Stay in scope.** Do not reformat, rename or "tidy" code you were not asked to touch. Mention improvements instead.
- **Follow what is there.** Match the existing structure, naming, libraries and patterns before introducing new ones.
- **Check, don't guess, APIs.** If you are not certain a function or option exists in the installed version, look it up:
  check `package.json`/lockfile for the version, read the library's docs (the Context7 MCP server helps), or read the source in `node_modules`.
- **Commit after each working step** if the human uses git that way, with a message saying what and why.

## Hard rules
- Never delete, skip or weaken a test to make it pass. If a test is wrong, say so and explain why before changing it.
- Never silence errors to make something "work": no empty `catch`, no `// @ts-ignore`, no `# type: ignore`, no `eslint-disable` without a reason in the comment.
- Never add a dependency without saying so and why. Prefer what the platform or existing deps already provide.
- Never run destructive commands (`rm -rf`, `git reset --hard`, `git push --force`, dropping databases) without explicit permission.
- Never commit secrets or `.env` files.
- Never claim something works without running it. If you could not run it, say "not run" plainly.

## When you finish
- Run the project's checks (lint, type-check, tests, build — whatever exists).
- Summarise in a few lines: what changed, how you verified it, anything left undone or risky, and what the human should try.
- For long sessions, use `session-handoff` to update `NOTES.md`.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `plan-then-build`, `session-handoff`. Use them when their description matches the task.
- MCP servers for this project are in `.mcp.json`. If a server is not connected, tell the human rather than working around it.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Vibe-coding guard rails" v1.0.0 — https://loadout.jnw-it.com/loadouts/vibe-coding-guardrails/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `plan-then-build`, `session-handoff`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Vibe-coding guard rails" v1.0.0 — https://loadout.jnw-it.com/loadouts/vibe-coding-guardrails/ -->

---
description: Hard guard rails for agent changes
alwaysApply: true
---

- Never delete, skip or weaken tests to get a green run. Explain if you think a test is wrong.
- No empty catch blocks, `@ts-ignore`, `type: ignore` or lint disables without a written reason.
- Do not add dependencies without saying which and why.
- Do not run destructive shell or git commands without explicit permission.
- Do not touch files unrelated to the task. Mention suggested clean-ups instead.
- Verify before claiming success; say "not run" if you could not run something.
- For multi-file or architectural changes, propose a short plan first.

---
name: plan-then-build
description: Write a short implementation plan and get approval before building. Use for new features, refactors, multi-file changes, dependency changes, or whenever the request is big or vague.
---

# Plan, then build

## 1. Look before planning (keep it quick)
Read the files you expect to change and their neighbours. Find the existing pattern for this kind of change
(how other routes, components or commands are structured). Check installed versions of anything you will rely on.

## 2. Write the plan
Keep it under ~20 lines. Use this shape:

```
Goal: <one sentence, in the human's terms>
Approach: <two or three sentences>
Changes:
  1. <file> — <what and why>
  2. <file> — <what and why>
New dependencies: none | <name> (<why>)
Out of scope: <things you will deliberately not do>
Risks / questions: <anything you are unsure of; at most three>
How I'll verify: <commands or manual checks>
```

If there is a real choice to make (two reasonable approaches), give both in one line each with your recommendation.

## 3. Stop and wait
Ask: "Shall I go ahead?" Do not start editing until the human agrees or adjusts the plan.
If they say "just do it" for this kind of task in future, you may skip waiting for similar small tasks in the same session.

## 4. Build in the order of the plan
- Do the steps in order, verifying as you go.
- If you discover the plan is wrong (a hidden dependency, a bigger change than expected), stop, explain, and re-plan.
  Do not quietly expand the scope.

## 5. Close out
Report against the plan: each step done or not, how it was verified, and anything that changed from the plan.

---
name: session-handoff
description: Write or update NOTES.md so the next session or another agent can continue the work. Use at the end of a long session, before context runs out, or when the user says they are stopping for now.
---

# Session handoff

Update (or create) `NOTES.md` at the repository root. Replace the "Current state" section; append to "Log".
Keep the whole file short enough to read in a minute. Do not include secrets, tokens or personal data.

```markdown
# Notes

## Current state (updated <YYYY-MM-DD>)
- Working on: <the feature/bug, one line>
- Done this session: <bullets, with file paths>
- In progress: <what is half-finished and where; say if the build is currently broken>
- Next steps: <ordered list, small enough to start immediately>
- Decisions: <choices made and why, so they are not relitigated>
- Gotchas: <surprising things learned: env quirks, flaky tests, API oddities>

## How to run
<the commands that actually work right now: install, dev, test, build>

## Log
- <YYYY-MM-DD>: <one line per session>
```

Then:
1. Run `git status` and mention any uncommitted changes. Suggest a commit message, but do not commit unless asked.
2. Tell the human, in two or three lines, where things stand and what the next session should start with.

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}