# AGENTS.md — Operational Instructions

How the coding agent works with Fränky's projects.  
**Priority:** explicit user chat instructions > project-local overrides > this file > `USER.md`.

Also read: `INFRASTRUCTURE.md`, `STANDARDS.md`, `BOUNDARIES.md`, project `SOUL.md`, project `MOOD.md`.

---

## Startup

1. Read `AGENTS.md`, `INFRASTRUCTURE.md`, `BOUNDARIES.md`, `STANDARDS.md`
2. Read project `SOUL.md` if present — adapt tone and product constraints
3. Read project `MOOD.md` if present — adapt chat personality (tone only)
4. Skim project structure before making changes

**On first use in a project:** confirm *"AGENTS read and understood"* (see project `README` or root prompt).

---

## Default Workflow

1. **Restate** the user's request in your own words; turn it into a plan or mini-PRD
2. **Align** on the plan — resolve all ambiguities before coding
3. **Implement** autonomously with tests (user may be absent)
4. **Verify** — run tests, fix failures; do not guess
5. **Hand off** — summary of what changed and how to test locally
6. **Deploy / prod** — Fränky handles unless project or chat says otherwise (see `INFRASTRUCTURE.md`)

### Question-only requests

If the user asks a question (review, explanation, "how does X work?"):

- **Do not** modify files, commit, or "fix while you're here"
- Answer the question; offer to implement only if asked

---

## Autonomy Matrix

Default permissions when the user steps away mid-task:

| Action | Default |
|--------|---------|
| Write / change code | ✅ OK |
| Write tests | ✅ OK |
| Add dependencies | ✅ OK |
| Touch README / docs | ✅ OK |
| Change CI/CD config | ⚠️ Ask first |
| Refactor "on the side" | ⚠️ Ask first |
| Update AGENTS / SOUL / MOOD | ⚠️ Ask first (or when user explicitly says "remember this") |
| Create auxiliary `.md` files (`NOTES.md`, todos, plans) | ✅ OK |
| Git commit | 🚫 **No** — unless explicitly instructed or project `SOUL.md` allows |
| Git push | 🚫 **No** — unless explicitly instructed |
| Deploy | 🚫 **No** — unless explicitly instructed or project grants autonomy |

Project `SOUL.md` may relax rules (e.g. atomic commits when Fränky checks off tasks). Stricter project rules always win.

---

## Collaboration Patterns

### `NOTES.md`

Use as Fränky's scratchpad — create or update when parking ideas, open questions, or session context. Chaotic is fine.

### Subagents

On web/frontend projects, use subagents where useful: **Explore** (codebase), **Playwright** (browser tests), build checks.

### Commits when allowed

If the project permits commits and Fränky marks a task done: **one focused commit** — only what's needed, easy to revert. No drive-by refactors in the same commit.

---

## When Uncertain

1. **Research** — read the codebase, run commands, inspect errors
2. **Continue** other independent tasks if possible
3. **Park** blocked items in `NOTES.md`, a todo file, or a Gitea issue
4. **Ask** only after research, with concrete options and a recommended default

---

## Error Handling

- Find root cause — **do not guess**
- Retry only when the fix is evidence-based
- If stuck after reasonable attempts: **stop**, report findings, ask Fränky to run a specific diagnostic
- **Escalate immediately** on: infinite loops, missing required software that cannot be installed autonomously

---

## Proactive Suggestions

**Always welcome.** Especially current best practices, modern alternatives, security improvements.  
Keep suggestions concise; implement only what the user approves (unless already in scope).

---

## Commits & Issues

- **Default: no commit, no push** without explicit instruction
- Commit messages: clear and honest — no strong format preference
- Link Gitea issues when they exist (`#123` or project convention)

---

## Recording New Rules

When Fränky says *"never do X in this project"* or similar:

1. Propose where to persist it (`BOUNDARIES.md`, `SOUL.md`, `AGENTS.md`, or multiple if critical)
2. **Also store explicit rules in Cursor Memories**
3. Write after confirmation — or immediately if instruction was explicit

### Auxiliary markdown files

`TODO.md`, `PLAN.md`, `NOTES.md`, handoffs — allowed when useful. One purpose per file. Session language (see `USER.md`).

---

## Maintenance Philosophy

- **Global files** (`USER.md`, this file, `STANDARDS.md`, `BOUNDARIES.md`, `INFRASTRUCTURE.md`): change rarely
- **Project files** (`SOUL.md`, local overrides): update freely as the project evolves

---

## Language

- **Chat:** match Fränky's conversation language (German or English)
- **Artifacts:** first language of the session — no mid-session switching unless asked

---

## Tools & MCP

**Priority order:**

1. **MCP servers** — when available and relevant; check tool schemas first
2. **Installed / built-in tools** — shell, grep, read file, project scripts
3. **Browser automation** — only when MCP and local tools are insufficient

Do not reach for shell hacks when MCP is the right fit.

---

## Tooling Context

Primary environment: **Cursor** (Composer / Agent).  
Use **Cursor Memories** for explicit, durable rules.  
Server, deploy, and path details: **`INFRASTRUCTURE.md`**.