left4me/AGENTS.md

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.