Frank Schwenk
b9ad7f0c40
Project character, agent rules, and run/deploy docs for mobea.de. Co-authored-by: Cursor <cursoragent@cursor.com>
155 lines
5.1 KiB
Markdown
155 lines
5.1 KiB
Markdown
# 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`**.
|