froxxxy/mobea
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refresh context files and add project URLS

Browse Source
This commit is contained in:
Frank Schwenk
2026-10-01 20:23:20 +02:00
parent b9ad7f0c40
commit 9e9fbe7be2
8 changed files with 509 additions and 231 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+224 -74
View File
@@ -1,60 +1,167 @@
<!-- vibesoul-updated: 2026-09-25T11:00:00+02:00 -->
# 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`.
How the coding agent works with Fränky's projects.
Also read: `INFRASTRUCTURE.md`, `STANDARDS.md`, `BOUNDARIES.md`, project `SOUL.md`, project `MOOD.md`.
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).
**Context files (audience):** **`SOUL.md`** + this file → agents (character, ops). **`README.md`** → humans (run/test/deploy). **`URLS.md`** → project URLs for humans and an external opener script (Markdown parser — no special formatting; keep URLs there, not scattered in SOUL).
---
## Startup
## Rule Priority
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
Highest wins. One line per source:
**On first use in a project:** confirm *"AGENTS read and understood"* (see project `README` or root prompt).
| 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.
---
## Default Workflow
## Startup (Tier 1 / Tier 2)
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`)
Agents do not auto-load context. Use two tiers:
### Question-only requests
### Tier 1 — always (light)
If the user asks a question (review, explanation, "how does X work?"):
At the start of any substantive task, without waiting for ack:
- **Do not** modify files, commit, or "fix while you're here"
- Answer the question; offer to implement only if asked
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:** If file edits are blocked, **abort and wait** — never circumvent via shell. See `BOUNDARIES.md`.
### Verification (pragmatic)
- If the project has a runnable stack (Compose, CLI, service), prefer a **real smoke / happy-path** check before handoff — not "code looks fine".
- Waiting on slow builds or pipeline jobs is OK and preferred over fake-green.
- Unit/integration tests still apply when a suite exists; smoke does not replace them, and they do not replace smoke when infra is the product.
### Unattended / Away — extra rules
- **Monitoring:** Built-in 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
- Include **one short line on where the time went** (e.g. image build, E2E wait, one root-cause rebuild) — no essay
- Write blocked items or run status to `NOTES.md` when useful
- **Notify** via `ntfyschwenkonline` when the task finishes (see [Notifications](#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](#notifications)).
---
## Autonomy Matrix
Default permissions when the user steps away mid-task:
See also `USER.md` **Work Style** table for Fränky's preference scores.
| Action | Default |
|--------|---------|
| Write / change code | ✅ OK |
| Write tests | ✅ 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 / 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 |
| 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 |
Project `SOUL.md` may relax rules (e.g. atomic commits when Fränky checks off tasks). Stricter project rules always win.
---
## 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
### Concision
Keep `AGENTS.md` lean:
- Stay under ~300 lines / ~150 instructions.
- Do not duplicate linter, formatter, or type-checker rules — enforce those with deterministic tooling.
- Prefer hooks, CI checks, and project infrastructure over "please remember" instructions.
- If a rule is tool-specific or task-specific, move it to `SKILL.md`, `TOOLS.md`, or the relevant `--emit-*` target rather than adding it here.
---
## Commits & Issues
- **Default: no commit, no push** without explicit instruction
- **Format:** [Conventional Commits](https://www.conventionalcommits.org/) (`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
---
@@ -62,93 +169,136 @@ Project `SOUL.md` may relax rules (e.g. atomic commits when Fränky checks off t
### `NOTES.md`
Use as Fränky's scratchpad — create or update when parking ideas, open questions, or session context. Chaotic is fine.
Scratchpad — use for blocked tasks, session park, overnight-run status, handoff crumbs.
### Subagents
### Subagents & context budget
On web/frontend projects, use subagents where useful: **Explore** (codebase), **Playwright** (browser tests), build checks.
**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
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.
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`.
Public/staging/repo/wiki URLs belong in **project `URLS.md`** (external opener script uses Markdown parsing — write URLs normally in that file).
Example SOUL section:
```markdown
## 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 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
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
- 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
- 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
---
## Proactive Suggestions
## Notifications
**Always welcome.** Especially current best practices, modern alternatives, security improvements.
Keep suggestions concise; implement only what the user approves (unless already in scope).
Fränky's machines have **`/usr/local/bin/ntfyschwenkonline`** — push to [ntfy.schwenk.online](https://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
## Commits & Issues
Send a notification when a **long-running agent task** completes or fails:
- **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)
- **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
```bash
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
```bash
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 in this project"* or similar:
When Fränky says *"never do X"*:
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
1. Propose file (`BOUNDARIES.md`, `SOUL.md`, `AGENTS.md`, or multiple)
2. Store in **agent memory** for explicit rules
3. Write after confirmation — or immediately if explicit
---
## Language
- **Chat:** match Fränky's conversation language (German or English)
- **Artifacts:** first language of the session — no mid-session switching unless asked
- **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
**Priority order:**
1. MCP when available and relevant
2. Built-in tools (shell, grep, read)
3. Browser automation last resort
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.
Check MCP schemas before calling.
---
## Tooling Context
Primary environment: **Cursor** (Composer / Agent).
Use **Cursor Memories** for explicit, durable rules.
Server, deploy, and path details: **`INFRASTRUCTURE.md`**.
Primary: **Cursor** (Composer 2.5+) for this session. Treat it as an effectively unlimited resource; use it as a subagent for exploration, broad searches, or any task where delegating saves tokens — including via `cursor-agent` CLI.
Server/deploy: **`INFRASTRUCTURE.md`**. Persona: **`USER.md`**.
---
[You have received this identical output 3 times. Re-reading '/home/frank/git/froxxxy/vibesoul/AGENTS.md:raw' will not change it — use a narrower selector (path:A-B), or proceed with the edit.]
[Showing lines 1-300 of 305. Use :301 to continue]