feat: Authelia SSO stack for auth.schwenk.online
Compose + Traefik ForwardAuth middleware, Redis sessions, SMTP via 0012.de, TOTP and ACL for consumer apps (e.g. pi.schwenk.online). Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Frank Schwenk
@@ -0,0 +1,278 @@
|
||||
<!-- vibesoul-updated: 2026-07-24T09:12:40+02:00 -->
|
||||
# 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](#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
|
||||
|
||||
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](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
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
|
||||
```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 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](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
|
||||
|
||||
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
|
||||
|
||||
```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"*:
|
||||
|
||||
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`**.
|
||||
Reference in New Issue
Block a user