mobea/AGENTS.md

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.