authschwenkonline/AGENTS.md

AGENTS.md — Operational Instructions

How the coding agent works with Fränky's projects.

Also read (project root, next to this file): INFRASTRUCTURE.md, STANDARDS.md, BOUNDARIES.md, project SOUL.md, project MOOD.md.
Persona & preferences: USER.md (Tier 2).

---

Rule Priority

Highest wins. One line per source:

Priority	Source
1	Explicit chat instruction from Fränky
2	Project SOUL.md / project-local BOUNDARIES.md / project AGENTS snippets
3	BOUNDARIES.md
4	AGENTS.md (this file)
5	STANDARDS.md
6	INFRASTRUCTURE.md
7	MOOD.md — tone only, never overrides safety or ops rules
8	USER.md — persona & preferences, not operational overrides

UI/UX: project SOUL.md overrides global STANDARDS.md when they conflict.

---

Startup (Tier 1 / Tier 2)

Cursor does not auto-load context. Use two tiers:

Tier 1 — always (light)

At the start of any substantive task, without waiting for ack:

1. Project SOUL.md — Agent Quick Start section (or full file if no Quick Start)
2. BOUNDARIES.md — Never Ever section

Tier 2 — full load

On @AGENTS.md ack, first chat in a project, or when Fränky says context was lost:

1. AGENTS.md, BOUNDARIES.md, STANDARDS.md, INFRASTRUCTURE.md
2. USER.md — persona, work-style table, communication prefs
3. Project SOUL.md (full), project MOOD.md if present
4. Skim project structure

Command: AGENTS.md ack

Fränky schreibt AGENTS.md ack.

Agent: Tier-2 read, then reply with this compact template (one block, no code changes):

AGENTS ack ✓
· Pipeline: [1-line what this project is]
· Non-goals: [from SOUL, or "SOUL missing"]
· Commit policy: [no commit unless … / project override]
· MOOD: [active session character]
· Paths: [key workdirs / mounts from SOUL or INFRA snippet]
· Conflict: [1 sentence if SOUL vs STANDARDS disagree, else "none"]

---

Work Modes

Mode	Trigger	Behavior
Question-only	Question, review, "how does X work?"	No file changes, commit, or drive-by fixes
Standard	Default	Restate → align on plan → implement → verify → hand off
Unattended / Away	"wenn ich zurück bin", "mach ohne mich", "overnight", explicit away	Skip plan alignment — proceed with best judgment; justify in handoff

Plan Mode (Cursor): If file edits are blocked, abort and wait — never circumvent via shell. See BOUNDARIES.md.

Unattended / Away — extra rules

• Monitoring: Cursor background shell + polling — not external wrapper scripts as default
• Handoff must include: log paths, PIDs if relevant, how to recognize success, next command for Fränky
• Write blocked items or run status to NOTES.md when useful
• Notify via ntfyschwenkonline when the task finishes (see Notifications)

---

Default Workflow (Standard mode)

1. Restate the request; turn into plan or mini-PRD
2. Align on the plan — resolve ambiguities before coding
3. Implement (see Testing below)
4. Verify — run tests when appropriate; do not guess
5. Hand off — summary, how to test locally, log paths for long jobs
6. Deploy / prod — Fränky handles unless project or chat says otherwise

After long-running work: send push notification (see Notifications).

---

Autonomy Matrix

See also USER.md Work Style table for Fränky's preference scores.

Action	Default
Write / change code	✅ OK
Write tests	✅ OK when non-trivial or suite exists
Add dependencies	✅ OK
Touch README / docs	✅ OK
Change CI/CD config	⚠️ Ask first
Refactor "on the side"	⚠️ Ask first
Update AGENTS / SOUL / BOUNDARIES	⚠️ Ask first (or explicit "remember this")
Update MOOD.md on disk	🚫 Only on persist MOOD or explicit instruction
Create auxiliary .md (NOTES.md, todos)	✅ OK
Git commit / push / deploy	🚫 Unless explicit or project SOUL.md allows
ntfyschwenkonline after long-running task	✅ OK

---

MOOD: Session vs. Persist

	Session	Persist to MOOD.md
Trigger	mood "XY" in chat	persist MOOD or explicit "save mood to file"
Effect	Tone for this chat only	Updates ## Aktueller Mood in file
Default	Yes — mood "XY" does not edit the file

---

Testing

Fränky's bar is pragmatic, not TDD-by-default (USER.md: tests score 2/5).

• Run tests when a suite exists and the change is non-trivial
• Follow project SOUL.md if stricter (e.g. pytest before handoff)
• Do not block small fixes on missing test infrastructure

---

Commits & Issues

• Default: no commit, no push without explicit instruction
• Format: Conventional Commits (feat:, fix:, docs:, …) when committing
• Forge: Gitea (gitea.schwenk.online) unless project says otherwise — not GitLab
• Link Gitea issues when they exist (#123)
• Do not mix unrelated changes (e.g. MOOD switch + feature) in one commit

---

Collaboration Patterns

NOTES.md

Scratchpad — use for blocked tasks, session park, overnight-run status, handoff crumbs.

Subagents & context budget

Keep main context small. Delegate instead of dumping large outputs into parent chat:

Task	Subagent
Unknown codebase or many files to scan	Explore
Browser / E2E / web UI	Playwright
Broad research	generalPurpose or Explore
Shell / git batch ops	shell

Explore for any project type when orientation is unclear — not only web. Playwright only when there is a web UI to test.

Commits when allowed

One focused commit per completed task — easy to revert. No drive-by refactors.

---

Project Infrastructure Snippet

Machine-specific paths (workdirs, external mounts, local service ports) belong in project SOUL.md, not global INFRASTRUCTURE.md.

Example SOUL section:

## Infrastructure (project-local)
- Workdir: ~/.local/share/myapp
- Mounts: check MegaB before scan
- Local Immich: :2283 (downstream, not core)

See INFRASTRUCTURE.md → Project-local overrides.

---

When Uncertain

1. Research — read code, run commands
2. Continue other independent tasks if possible
3. Park in NOTES.md, todo file, or Gitea issue
4. Ask after research, with options + recommended default

---

Error Handling

• Root cause first — do not guess
• Escalate on: debug loops, missing uninstallable software
• Long-running jobs: no arbitrary timeout unless Fränky or SOUL says so; name progress.log when applicable

---

Notifications

Fränky's machines have /usr/local/bin/ntfyschwenkonline — push to ntfy.schwenk.online. Topic = short hostname (hostname -s); phone subscribes per machine. Auth is in the installed script — never copy tokens into repos or chat.

When to notify

Send a notification when a long-running agent task completes or fails:

• Unattended / Away mode — always on finish (success or failure)
• Background shell jobs you started (scans, builds, batch ops, overnight runs)
• Any task Fränky left with an expectation of „meld dich wenn fertig"
• Rough guide: expected runtime > ~2 minutes or explicit away/unattended context

Do not notify for quick edits, short test runs, or question-only chats.

How

ntfyschwenkonline "OK <project>: <one-line result>"
# or on failure:
ntfyschwenkonline "FAIL <project>: <one-line error>, see <log-path>"

• English message body (CLI/ops convention)
• One line, ~120 chars — project name, outcome, log path or next step if relevant
• Run after handoff summary; notification is in addition to chat handoff, not a replacement
• If ntfyschwenkonline is missing or fails: note in chat handoff, do not block

Examples

ntfyschwenkonline "OK imagetool: scan done 142 dirs, log ~/.local/share/imagetool/progress.log"
ntfyschwenkonline "FAIL ytrecap: pytest 3 failed, see /tmp/test.log"
ntfyschwenkonline "OK schwenkonline: build+deploy done"

---

Recording New Rules

When Fränky says "never do X":

1. Propose file (BOUNDARIES.md, SOUL.md, AGENTS.md, or multiple)
2. Store in Cursor Memories for explicit rules
3. Write after confirmation — or immediately if explicit

---

Language

• Chat: match Fränky's language (German or English)
• CLI / terminal / shell: always English (unless client project — ask)
• Other artifacts: first language of session

---

Tools & MCP

1. MCP when available and relevant
2. Built-in tools (shell, grep, read)
3. Browser automation last resort

Check MCP schemas before calling.

---

Tooling Context

Primary: Cursor (Composer / Agent).
Server/deploy: INFRASTRUCTURE.md. Persona: USER.md.