docs: add README and AGENTS project guidance
This commit is contained in:
mwiegand
parent
03764f7930
commit
5dc7f47a82
2 changed files with 147 additions and 0 deletions
83
AGENTS.md
Normal file
83
AGENTS.md
Normal file
|
|
@ -0,0 +1,83 @@
|
|||
# AGENTS.md
|
||||
|
||||
Guidance for coding agents working in this repository.
|
||||
|
||||
## Mission
|
||||
|
||||
Build `left4me` according to the two implementation plans:
|
||||
|
||||
- `docs/superpowers/plans/2026-04-22-l4d2-host-lib-v1.md`
|
||||
- `docs/superpowers/plans/2026-04-23-l4d2-web-app-v1.md`
|
||||
|
||||
Do not invent architecture outside these plans unless explicitly requested.
|
||||
|
||||
## Current Project State
|
||||
|
||||
- Repo is newly initialized.
|
||||
- Only planning docs exist right now.
|
||||
- Implementation directories are planned, not yet created.
|
||||
|
||||
## Non-Negotiable Constraints
|
||||
|
||||
### Naming and boundaries
|
||||
|
||||
- Use `l4d2` naming consistently.
|
||||
- Keep host library and web app as separate components.
|
||||
- Do not collapse them into one package.
|
||||
|
||||
### Host library (`l4d2host` / `l4d2ctl`)
|
||||
|
||||
- Exposed CLI command set is fixed:
|
||||
- `install`
|
||||
- `initialize <name> -f <spec.yaml>`
|
||||
- `start <name>`
|
||||
- `stop <name>`
|
||||
- `delete <name>`
|
||||
- Hard-coded paths under `/opt/l4d2`.
|
||||
- Overlays are external directories (no overlay content management here).
|
||||
- Fail-fast subprocess behavior; pass raw stderr; propagate return code.
|
||||
- No lock manager, no rollback, no preflight runtime checks.
|
||||
- Delete missing instance/runtime dirs must succeed (no-op).
|
||||
- Read APIs required for web app integration:
|
||||
- `get_instance_status(name)`
|
||||
- `stream_instance_logs(name, lines=200, follow=True)`
|
||||
|
||||
### Web app (`l4d2-web-app`)
|
||||
|
||||
- Flask + server-rendered templates + vendored HTMX.
|
||||
- No external frontend framework/dependencies.
|
||||
- Custom CSS with consistent link color `#0F766E`.
|
||||
- Local username/password auth and `admin` flag.
|
||||
- Persist command logs in `job_logs` table (retain indefinitely).
|
||||
- Desired vs actual server state model.
|
||||
- Live logs in UI for both jobs and servers.
|
||||
- Blueprint semantics (locked):
|
||||
- private per user in v1
|
||||
- live-linked to servers
|
||||
- no server-level overrides
|
||||
- deleting in-use blueprint is blocked
|
||||
- updates apply on next action
|
||||
- servers can reassign blueprint anytime
|
||||
|
||||
## Delivery Workflow
|
||||
|
||||
1. Read both plan files fully before coding.
|
||||
2. Execute plan tasks in order.
|
||||
3. Keep changes scoped to one task at a time.
|
||||
4. Run task-level tests before moving forward.
|
||||
5. Do not claim completion without command evidence.
|
||||
6. Keep docs updated when behavior/contracts change.
|
||||
|
||||
## Verification Expectations
|
||||
|
||||
Before claiming success on any step, run the relevant command and report actual output status.
|
||||
|
||||
Typical commands (once components exist):
|
||||
|
||||
- `pytest components/l4d2-host-lib/tests -q`
|
||||
- `pytest components/l4d2-web-app/tests -q`
|
||||
|
||||
## Change Control
|
||||
|
||||
- If a requested change conflicts with this file, follow explicit user instruction.
|
||||
- If plans and code diverge, update plans or flag the mismatch clearly.
|
||||
64
README.md
Normal file
64
README.md
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
# left4me
|
||||
|
||||
`left4me` is a local L4D2 server management platform with two planned components:
|
||||
|
||||
1. `l4d2host` + `l4d2ctl` (host library + CLI)
|
||||
2. `l4d2-web-app` (Flask web app for users, blueprints, servers, jobs, and logs)
|
||||
|
||||
## Status
|
||||
|
||||
This repository is currently in planning phase.
|
||||
Implementation plans are the source of truth:
|
||||
|
||||
- `docs/superpowers/plans/2026-04-22-l4d2-host-lib-v1.md`
|
||||
- `docs/superpowers/plans/2026-04-23-l4d2-web-app-v1.md`
|
||||
|
||||
## Locked v1 Decisions
|
||||
|
||||
- Naming is strictly `l4d2` (not `l4d`).
|
||||
- Host library and web app are separate components.
|
||||
- Host CLI commands are fixed to:
|
||||
- `install`
|
||||
- `initialize <name> -f <spec.yaml>`
|
||||
- `start <name>`
|
||||
- `stop <name>`
|
||||
- `delete <name>`
|
||||
- Runtime paths are hard-coded under `/opt/l4d2`.
|
||||
- Overlay handling is directory-based and externally populated.
|
||||
- No lock manager, no rollback, no preflight checks in host library.
|
||||
- CLI propagates subprocess failures via stderr and return code.
|
||||
- `delete` on missing instance is no-op success.
|
||||
- Blueprint model (web app):
|
||||
- user-private in v1
|
||||
- servers are live-linked to blueprint
|
||||
- no per-server overrides
|
||||
- delete blueprint blocked when linked servers exist
|
||||
- blueprint changes apply on next action
|
||||
- server can reassign blueprint anytime
|
||||
|
||||
## Planned Repository Layout
|
||||
|
||||
- `components/l4d2-host-lib/`
|
||||
- `components/l4d2-web-app/`
|
||||
- `docs/superpowers/plans/`
|
||||
|
||||
## Tech Stack (planned)
|
||||
|
||||
- Python 3.12+
|
||||
- Typer, PyYAML, pytest
|
||||
- Flask, SQLAlchemy, Alembic
|
||||
- HTMX (vendored locally), custom CSS, SSE
|
||||
- systemd user units, fuse-overlayfs, steamcmd
|
||||
|
||||
## Recommended Implementation Order
|
||||
|
||||
1. Implement `components/l4d2-host-lib` plan first.
|
||||
2. Implement `components/l4d2-web-app` plan second.
|
||||
3. Keep tests green task-by-task (TDD flow from plans).
|
||||
4. Keep commits small and aligned with plan tasks.
|
||||
|
||||
## Contributing Notes
|
||||
|
||||
- Follow plan task order unless explicitly re-planned.
|
||||
- Keep contracts above unchanged unless the user asks to change them.
|
||||
- Update plan docs when scope or behavior changes.
|
||||
Loading…
Reference in a new issue