bab-backend-ansible/CLAUDE.md

CLAUDE.md

Session Start

Check docs/summaries/ for a handoff file. If one exists, read it and the files it references — not all summaries. State: what you understand the project state to be, what you plan to do, and open questions.

If no handoff exists, determine session type before proceeding:

• Quick task: single-session, self-contained work (adding a task, fixing a bug, writing a role) → proceed without setup overhead
• Sustained work: multi-session project or significant design work → ask: what is the goal and what is the target deliverable

Identity

You work with Patrick, a Solutions Architect. This repo is Ansible automation for the BAB (Borrow a Boat) backend — an Appwrite-based service on a single RHEL 9 host (bab1.mgmt.toal.ca). Automation runs via Ansible Automation Platform (AAP) in production, ansible-navigator locally. Patrick has expert-level Ansible knowledge — do not explain Ansible basics.

Project

Repo: Ansible playbooks and EDA rulebooks managing a full Appwrite backend lifecycle on RHEL 9. Host: bab1.mgmt.toal.ca Run locally: ansible-navigator run playbooks/<name>.yml --mode stdout Run with extra vars: ansible-navigator run playbooks/deploy_application.yml --mode stdout -e artifact_url=<url> Lint: ansible-navigator lint playbooks/ --mode stdout Collections: ansible-galaxy collection install -r requirements.yml

Load docs/context/architecture.md when working on playbooks, EDA rulebooks, or Appwrite API tasks.

Rules

1. Do not mix unrelated project contexts in one session.
2. For sustained work: write state to disk after completing meaningful work. Use templates from templates/claude-templates.md. Include: decisions with rationale, exact numbers, file paths, open items.
3. For sustained work: before compaction or session end, write to disk — every number, every decision with rationale, every open question, every file path, exact next action.
4. For sustained work: when switching work types (development → documentation → review), write a handoff to docs/summaries/handoff-[date]-[topic].md and suggest a new session.
5. Do not silently resolve open questions. Mark them OPEN or ASSUMED.
6. Do not bulk-read documents. Process one at a time: read, summarize to disk, release from context before reading next. For the detailed protocol, read docs/context/processing-protocol.md.
7. Sub-agent returns must be structured, not free-form prose. Use output contracts from templates/claude-templates.md.

Ansible Conventions

• Never embed vars in playbooks. All variables go in the inventory at /home/ptoal/Dev/inventories/bab-inventory — in host_vars/<host>/ or group_vars/<group>/ as appropriate.

Where Things Live

• templates/claude-templates.md — summary, handoff, decision, analysis, task, output contract templates (read on demand)
• docs/summaries/ — active session state (latest handoff + decision records + source summaries)
• docs/context/ — reusable domain knowledge, loaded only when relevant
  • architecture.md — playbook inventory, EDA rulebooks, Appwrite API pattern, collections
  • processing-protocol.md — full document processing steps
  • archive-rules.md — summary lifecycle and file archival rules
  • subagent-rules.md — when to use subagents vs. main agent
• .claude/agents/ — specialized subagents (ansible-idempotency-reviewer — use before adding tasks or before production runs)
• docs/archive/ — processed raw files. Do not read unless explicitly told.
• output/deliverables/ — final outputs

For cross-project user preferences, recurring constraints, or tool preferences: use Claude Code's native memory system, not docs/summaries/.

Error Recovery

If context degrades or auto-compact fires unexpectedly: write current state to docs/summaries/recovery-[date].md, tell the user what may have been lost, suggest a fresh session.

Before Delivering Output

Verify: exact numbers preserved, open questions marked OPEN, output matches what was requested (not assumed), no Ansible idempotency regressions introduced.

All Ansible files (playbooks, task files, templates, vars) must end with a trailing newline.