Jeroen SchweitzerandClaude Opus 4.5
2b2ddc1b1b
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
97 lines
4.6 KiB
Markdown
97 lines
4.6 KiB
Markdown
# LLM Agent Instructions
|
|
|
|
This document contains instructions and documentation references for AI assistants working with this codebase.
|
|
|
|
> **📖 Important**: Before working on this project, read [PHILOSOPHY.md](PHILOSOPHY.md) to understand the system vision, architectural patterns, and design goals. All development should work towards realizing those patterns.
|
|
# AGENTS.md
|
|
|
|
> **Start every session by reading this file.**
|
|
> This file outlines the operational protocols, coding standards, and architectural decisions for this Flutter project.
|
|
|
|
## 1. Agent Operational Protocols
|
|
|
|
### 🧠 Work Patterns (Plan-Act-Reflect)
|
|
* **Plan:** Before writing code, briefly outline your plan. Identify which files you will touch and what the side effects might be.
|
|
* **Act:** Execute the changes in small, atomic steps.
|
|
* **Reflect:** After coding, verify your work. Did you break existing tests? Did you add new tests?
|
|
|
|
### 🌐 Internal Service Access
|
|
* **git.schweitz.net**: Access via `http://localhost:3002` (direct Gitea) to bypass Authentik SSO
|
|
* Example: `curl http://localhost:3002/jpmschweitzer/library-desk/raw/branch/main/README.md`
|
|
* Public repos are readable without authentication
|
|
* Related repos: , `core-api`, `tatlock`, `library-desk`, `scheduler`, `portainer-core`
|
|
|
|
### 🐳 Deployment & Infrastructure
|
|
|
|
**⚠️ IMPORTANT: Service Port Reference**
|
|
| Service | LAN Port | External URL | Notes |
|
|
|---------|----------|--------------|-------|
|
|
| **Core API** | 8083 | `api.schweitz.net` | FastAPI backend for this UI |
|
|
| **Tatlock API** | 8000 | `tatlock.schweitz.net` | Legacy Python API (Ollama proxy) |
|
|
| **Tatlock UI** | 9999 | `home.schweitz.net` | This Flutter app |
|
|
|
|
* **Full stack documentation**: Available in the `portainer-core` repo
|
|
* Access: `curl http://192.168.86.149:3002/jpmschweitzer/portainer-core/raw/branch/main/CONTAINERS.md`
|
|
* Contains: All service ports, URLs, Redis DB allocations, external domains
|
|
* **Health checks**:
|
|
* Core API: `curl http://192.168.86.149:8083/health`
|
|
* Tatlock API: `curl http://192.168.86.149:8000/health`
|
|
|
|
### 🛡️ Git Discipline
|
|
* **Commit Messages:** Use the [Conventional Commits](https://www.conventionalcommits.org/) format.
|
|
* `feat: add user login endpoint`
|
|
* `fix: resolve database connection timeout`
|
|
* `refactor: split monolith dependency file`
|
|
* **Atomic Commits:** Keep commits small. One logical change = one commit.
|
|
* **Version Tagging:** Every version increment (major.minor.patch, not build count) must have a corresponding git tag.
|
|
* Format: `v{major}.{minor}.{patch}` (e.g., `v0.3.0`)
|
|
* Tag after updating `pubspec.yaml` version and CHANGELOG
|
|
* Push tags with `git push --tags`
|
|
|
|
### 🚀 Release Procedure
|
|
|
|
This project uses version-tag-based CI/CD. Releases trigger automated Docker builds and deployments.
|
|
|
|
**Release Steps:**
|
|
|
|
1. Update version in `pubspec.yaml` (bump major.minor.patch, not build number)
|
|
2. Update `CHANGELOG.md` with changes under `## [x.x.x] - YYYY-MM-DD`
|
|
3. Commit changes: `git commit -m "chore: release vX.X.X"`
|
|
4. Create git tag: `git tag vX.X.X`
|
|
5. Push with tags: `git push origin master --tags`
|
|
|
|
CI/CD auto-triggers when a tag starting with `v` is pushed.
|
|
|
|
**What happens on release:**
|
|
|
|
* Gitea CI builds Flutter web app in Docker
|
|
* Image pushed to `git.schweitz.internal/jpmschweitzer/tatlock-ui:latest` and `:vX.X.X`
|
|
* Watchtower detects new image and auto-updates running container
|
|
* App available at `http://tower:8092` (and eventually `home.schweitz.net`)
|
|
|
|
**Rollback:**
|
|
|
|
* In Portainer, update image tag to previous version (e.g., `:v0.2.0`)
|
|
* Or: `docker pull git.schweitz.internal/jpmschweitzer/tatlock-ui:v0.2.0`
|
|
|
|
### 🧪 Testing Requirements
|
|
|
|
* **Always add tests for new code before committing.** No exceptions.
|
|
* Tests should cover the happy path and key edge cases.
|
|
* Run `flutter test` before committing to ensure all tests pass.
|
|
* For widgets: use widget tests. For business logic: use unit tests.
|
|
* Code coverage should not decrease with new commits.
|
|
|
|
### 📝 Changelog Maintenance
|
|
|
|
* **Update `CHANGELOG.md`** with every user-facing change.
|
|
* Format: `## [Unreleased] - YYYY-MM-DD` followed by `### Added`, `### Changed`, or `### Fixed`.
|
|
|
|
### 🎨 UI Patterns (MUST READ BEFORE CHANGES)
|
|
|
|
* **Before modifying the widget tree**, read `docs/UI_LAYOUT.md` to understand established patterns.
|
|
* Investigate existing implementations in the codebase before creating new components.
|
|
* **DO NOT** reinvent wheels - check if shared components already exist in `lib/shared/components/`.
|
|
* Look at similar features for reference patterns (e.g., how other list views, forms, or CRUD screens are built).
|
|
* Deviating from established patterns creates inconsistency and technical debt.
|