# AI Agent — General Instructions You are an autonomous coding agent working on **BanGUI**, a web application for monitoring, managing, and configuring fail2ban through a clean web interface. This document defines how you operate, what rules you follow, and which workflow you repeat for every task. Read this document completely before starting any work. --- ## 1. Project Context BanGUI consists of two main parts: | Layer | Stack | Docs | |---|---|---| | **Backend** | Python 3.12+, FastAPI, Pydantic v2, aiosqlite, structlog | [Backend-Development.md](Backend-Development.md) | | **Frontend** | TypeScript, React, Fluent UI v9, Vite | [Web-Development.md](Web-Development.md) | Supporting documentation you must know and respect: | Document | Purpose | |---|---| | [Features.md](Features.md) | Complete feature list and expected behaviour | | [Architekture.md](Architekture.md) | System architecture, component relationships, data flow | | [Web-Design.md](Web-Design.md) | Visual design rules, theming, layout, spacing, motion | | [Backend-Development.md](Backend-Development.md) | Backend coding rules, project structure, conventions | | [Web-Development.md](Web-Development.md) | Frontend coding rules, project structure, conventions | **Always** consult the relevant document before writing code. If your planned change contradicts any rule defined in those documents, the document wins — adjust your approach. --- ## 2. General Rules ### 2.1 Follow the Docs - Every coding convention, naming rule, project structure decision, and library choice is defined in the development docs. Do not deviate. - Backend code follows [Backend-Development.md](Backend-Development.md) — strict typing, async only, structlog, Pydantic models, layered architecture (routers → services → repositories). - Frontend code follows [Web-Development.md](Web-Development.md) — strict TypeScript, Fluent UI v9 only, `makeStyles` for styling, typed API calls, hooks for state. - Visual decisions follow [Web-Design.md](Web-Design.md) — Fluent design tokens, semantic colour slots, 4 px spacing grid, correct elevation and motion. ### 2.2 Write Production-Quality Code - Write code as if it ships today. No TODOs, no placeholders, no half-implementations. - Every function has explicit type annotations (Python) or type signatures (TypeScript). - Every public function has a docstring (Python — Google style) or JSDoc comment (TypeScript). - No `any` in TypeScript. No `Any` in Python (unless justified with a comment). - No magic numbers or strings — use named constants. - No dead code, no commented-out blocks, no unused imports. ### 2.3 Keep It Small and Focused - One function does one thing. - One component per file. - One service per domain. - If a file grows beyond ~150 lines (components) or ~200 lines (services), split it. ### 2.4 Never Break Existing Code - Before changing any file, understand what it does and who depends on it. - Run the existing test suite before and after your changes. If tests fail after your change, fix them before moving on. - Do not remove or rename public APIs without updating all callers. ### 2.5 Think Before You Code - Read the task description carefully. If it is ambiguous, check [Features.md](Features.md) and [Architekture.md](Architekture.md) for clarification. - Plan your changes before writing code. Identify which files are affected, which layers are involved, and what tests are needed. - Prefer the simplest correct solution. Do not over-engineer. --- ## 3. Task Workflow Repeat the following cycle for every task. Do not skip steps. ### Step 1 — Pick a Task - Open `tasks.md` and pick the next unfinished task (highest priority first). - Mark the task as **in progress**. - Read the task description thoroughly. Understand the expected outcome before proceeding. ### Step 2 — Plan Your Steps - Break the task into concrete implementation steps. - Identify which files need to be created, modified, or deleted. - Identify which layers are affected (router, service, repository, model, component, hook, page, type, etc.). - Identify edge cases and error scenarios. - Write down your plan before touching any code. ### Step 3 — Write Code - Implement the feature or fix following the plan. - Follow all rules from the relevant development docs: - Backend → [Backend-Development.md](Backend-Development.md) - Frontend → [Web-Development.md](Web-Development.md) - Design → [Web-Design.md](Web-Design.md) - Architecture → [Architekture.md](Architekture.md) - Write clean, well-structured, fully typed code. - Keep commits atomic — one logical change per commit. ### Step 4 — Add Logging - Add structured log statements at key points in new or modified code. - Backend: use **structlog** with contextual key-value pairs — never `print()`. - Log at appropriate levels: `info` for operational events, `warning` for recoverable issues, `error` for failures. - Never log sensitive data (passwords, tokens, session IDs). ### Step 5 — Write Tests - Write tests for every new or changed piece of functionality. - Backend: use `pytest` + `pytest-asyncio` + `httpx.AsyncClient`. See [Backend-Development.md § 9](Backend-Development.md). - Frontend: test components and hooks according to the frontend test setup. - Test the happy path **and** error/edge cases. - Mock external dependencies — tests must never touch real infrastructure. - Follow the naming pattern: `test___`. ### Step 6 — Review Your Code Run a thorough self-review before considering the task done. Check **all** of the following: #### 6.1 — Warnings and Errors - Backend: run `ruff check` and `mypy --strict` (or `pyright --strict`). Fix every warning and error. - Frontend: run `tsc --noEmit` and `eslint`. Fix every warning and error. - Zero warnings, zero errors — no exceptions. #### 6.2 — Test Coverage - Run the test suite with coverage enabled. - Aim for **>80 % line coverage** overall. - Critical paths (auth, banning, scheduling, API endpoints) must be **100 %** covered. - If coverage is below the threshold, write additional tests before proceeding. #### 6.3 — Coding Principles Verify your code against the coding principles defined in [Backend-Development.md § 13](Backend-Development.md) and [Web-Development.md](Web-Development.md): - [ ] **Clean Code** — Meaningful names, small functions, no magic values, guard clauses over deep nesting. - [ ] **Separation of Concerns** — Each module has a single, well-defined responsibility. Layers are not mixed. - [ ] **Single Responsibility Principle** — Every class and function has one reason to change. - [ ] **DRY** — No duplicated logic. Shared behaviour is extracted. - [ ] **KISS** — The simplest correct solution is used. No over-engineering. - [ ] **Type Safety** — All types are explicit. No `any` / `Any`. No `# type: ignore` without justification. #### 6.4 — Architecture Compliance Verify against [Architekture.md](Architekture.md) and the project structure rules: - [ ] Files are in the correct directories (routers in `routers/`, services in `services/`, components in `components/`, etc.). - [ ] Dependencies flow in the right direction (routers → services → repositories; pages → components → hooks). - [ ] No circular imports. - [ ] No business logic in routers or components. - [ ] No HTTP/framework concerns in services or repositories. - [ ] Pydantic models separate request, response, and domain shapes. - [ ] Frontend types live in `types/`, not scattered across components. ### Step 7 — Update Documentation - If your change introduces new features, new endpoints, new components, or changes existing behaviour, update the relevant docs: - [Features.md](Features.md) — if feature behaviour changed. - [Architekture.md](Architekture.md) — if new modules, services, or data flows were added. - [Backend-Development.md](Backend-Development.md) or [Web-Development.md](Web-Development.md) — if new conventions were established. - Keep documentation accurate and in sync with the code. Outdated docs are worse than no docs. ### Step 8 — Mark Task Complete - Open `tasks.md` and mark the task as **done**. - Add a brief summary of what was implemented or changed. ### Step 9 — Commit - Stage all changed files. - Write a commit message in **imperative tense**, max 72 characters for the subject line. - Good: `Add jail reload endpoint` - Bad: `added stuff` / `WIP` / `fix` - If the change is large, include a body explaining **why**, not just **what**. - Branch naming: `feature/`, `fix/`, `chore/`. - Ensure the commit passes: linter, type checker, all tests. ### Step 10 — Next Task - Return to **Step 1** and pick the next task. --- ## 4. Workflow Summary ``` ┌─────────────────────────────────────────┐ │ 1. Pick task from tasks.md │ │ 2. Plan your steps │ │ 3. Write code │ │ 4. Add logging │ │ 5. Write tests │ │ 6. Review your code │ │ ├── 6.1 Check warnings & errors │ │ ├── 6.2 Check test coverage │ │ ├── 6.3 Check coding principles │ │ └── 6.4 Check architecture │ │ 7. Update documentation if needed │ │ 8. Mark task complete in tasks.md │ │ 9. Git commit │ │ 10. Pick next task ──────── loop ───┐ │ │ ▲ │ │ │ └───────────────────────────┘ │ └─────────────────────────────────────────┘ ``` --- ## 5. When You Are Stuck - Re-read the task description and the relevant docs. - Search the existing codebase for similar patterns — follow established conventions. - Check the fail2ban source code in `fail2ban-master/` if you need to understand how fail2ban works internally. - If a decision is genuinely ambiguous and no document covers it, choose the simplest option that is consistent with existing code and document your reasoning in a code comment. --- ## 6. What You Must Never Do - **Never** commit code that does not compile or has type errors. - **Never** commit code without tests. - **Never** use libraries that are explicitly forbidden in the development docs. - **Never** bypass the linter or type checker with blanket ignores. - **Never** hard-code secrets, passwords, or tokens. - **Never** push directly to `main` — always use feature branches. - **Never** skip the review step — sloppy code compounds over time. - **Never** leave a task half-done — finish it or revert it.