Read this codebase and write a CLAUDE.md that captures:
  - How to build and run the project
  - The architecture (only what isn't obvious from the code)
  - Coding conventions and non-obvious constraints
  - Anything a developer would need that can't be inferred

Keep it under 100 lines. Only include non-inferable information.

# library-service

## Build & Run
./gradlew quarkusDev   # live reload on :8080

## Stack
Java 21 · Quarkus 3 · JAX-RS · CDI · Jackson · Gradle 8

## Architecture
LibraryResource → LibraryService → LibraryStore (ConcurrentHashMap)
Records: Book, Loan — immutable, use with*() helpers for state transitions.

## Coding Standards
- NEVER use plain HashMap in @ApplicationScoped beans — always ConcurrentHashMap
- Tests: Given-When-Then, no eq() matchers in Mockito

## Known Gotchas
- Borrow availability: use ConcurrentHashMap.replace() — NOT get-then-put.
  Plain put() after get() has a race condition under concurrent requests.
- JAX-RS paths: @Path("/search") BEFORE @Path("/{id}").
  If /{id} comes first, "search" matches as an ID — no compile-time error.

# library-service

## Build & Run ...
## Stack ...
## Architecture ...
## Coding Standards ...         ← 15 lines
## Testing Standards ...        ← 20 lines
## Known Gotchas ...            ← 12 lines
## Task Workflow ...            ← 30 lines
## Roles ...                    ← 25 lines
## Workflow Prompts ...         ← 20 lines
## Tech Debt ...                ← 10 lines

CLAUDE.md (20 lines — @-imports only)
    @.ai/knowledge.md          ← tribal knowledge, loaded every session
    @.ai/context/stack.md      ← build, run, dependencies

.ai/skills/                    ← domain knowledge, workflow phases, and roles
    java-standards/            → /java-standards
    testing-standard/          → /testing-standard
    pre-flight/                → /pre-flight TASK-001
    build-plan/                → /build-plan TASK-001
    execute/                   → /execute TASK-001 "Stage 1"
    close-task/                → /close-task TASK-001
    architect/                 → /architect

.ai/hooks/verify-build.sh      ← quality gate
.ai/tasks/TASK-001/            ← per-task working memory

---
name: testing-standard
description: Testing standards — Given-When-Then, Mockito patterns, domain
             record deserialization tests. Load when writing or reviewing any test.
---

- NEVER use `eq()` matchers in Mockito — use raw values directly
- ALWAYS use ConcurrentHashMap.replace() for availability updates
- NEVER skip the layer boundary: Resource → Service → Store

Structure: Given / When / Then
New domain records require a JSON deserialization test.

---
name: pre-flight
description: Deep codebase analysis before planning. Always run before build-plan.
---

## Live context
- Recent commits: !`git log --oneline -5`       ← runs at invocation, always current
- Modified files: !`git diff --name-only HEAD`

## Instructions
1. Load the task folder (.ai/tasks/[TASK-ID]/)
2. Trace method chains affected by this task
3. Cross-check knowledge.md — flag applicable gotchas
4. Identify risks: concurrency, layer boundaries, records needing tests
5. Update findings.md — do NOT implement anything

Task ID: $ARGUMENTS

.ai/tasks/TASK-001/
├── context.md    ← what and why (set at kickoff, static after)
├── task-plan.md  ← phases, design decisions, files to touch
├── checklist.md  ← executable steps with stage checkboxes
├── findings.md   ← discoveries during work (append-only, raw)
├── tracker.md    ← Current Focus updated every session
└── summary.md    ← written before the knowledge flush

## Current Focus
**Last action**: Pre-flight complete — borrow race condition documented in findings.md
**Next action**: Run /build-plan TASK-001 to generate staged plan
**Open decision**: Should partial failure be rolled back? (non-blocking — log as tech debt)

| Active Role | Architect    |
| Stage       | Pre-planning |

Task starts         → task folder created (context.md, findings.md)
     ↓
Pre-flight finds race condition
                    → findings.md (written at time of discovery)
     ↓
Implementation confirms the fix
                    → findings.md updated
     ↓
Task closes         → summary.md written → flush to knowledge.md
     ↓
knowledge.md loaded at every future session in this repo
     ↓
Wiki ingest         → promoted to wiki/gotcha/
                       available across all repos and all future engineers

[repo]/
├── AGENTS.md                  ← canonical (≤150 lines, non-inferable only)
├── CLAUDE.md                  ← adapter: @-imports from .ai/
├── .junie/guidelines.md       ← adapter: @-imports from .ai/
└── .ai/                       ← the actual source of truth

# library-service — Agent Context

## Build
./gradlew clean build test
Quality gate: .ai/hooks/verify-build.sh

## Non-obvious constraints
- NEVER plain HashMap in @ApplicationScoped — ALWAYS ConcurrentHashMap
- Borrow flip: NEVER get-then-put — ALWAYS ConcurrentHashMap.replace()
- JAX-RS: @Path("/search") BEFORE @Path("/{id}") — or "search" matches as an ID
- Records are immutable — use with*() helpers, never add setters

## Task workflow
Folders: .ai/tasks/[TASK-ID]/ — context.md, checklist.md, findings.md,
         tracker.md, task-plan.md, summary.md
Workflow: /new-task → /pre-flight → /build-plan → /execute → /close-task

## Full context
.ai/knowledge.md, .ai/context/, .ai/skills/

personal-wiki/
├── schema.md     ← the spec: page types, frontmatter, naming rules
│                    the LLM reads this to know what to write and where
├── CLAUDE.md     ← loads schema + wiki structure (Claude Code)
├── JUNIE.md      ← same for Junie — any tool, same wiki
└── wiki/
    ├── index.md  ← content catalog — updated on every ingest
    ├── log.md    ← append-only activity log
    ├── repo/     ← per-repo architecture and patterns
    ├── debug/    ← root causes, symptoms, fixes
    ├── gotcha/   ← traps documented once, searchable forever
    ├── decision/ ← architectural choices and their rationale
    └── reference/← runbooks, command references, API summaries

Read this codebase and write a CLAUDE.md (or AGENTS.md) that captures:
- How to build and run the project
- The architecture — only what is not obvious from reading the source
- Coding standards and non-obvious constraints
- Anything a developer needs to know that cannot be inferred

Rules:
- Keep it under 100 lines
- Inferrable facts (stack, test framework) can be one-liners
- Non-obvious constraints need the full detail — include the "why" and
  the failure mode, not just the rule
- If something can be read from the code, leave it out

The current guidelines file has grown past ~80 lines.
Restructure it into a .ai/ folder:

1. .ai/knowledge.md — architectural facts, gotchas, non-obvious constraints
2. .ai/context/     — narrow reference sheets for specific concerns
                      (stack, deployment, key patterns). Each file ≤50 lines.
3. .ai/skills/      — repeated workflows and behavioral rules as skill files
                      (testing approach, task lifecycle, code review rules).
                      One topic per file.
4. Rewrite CLAUDE.md as a manifest of @-imports only — under 30 lines,
   no duplicated content, just pointers to .ai/ files.

Do not write any files yet. Propose the folder structure and
show me what goes where. I will confirm before you create anything.

We use more than one AI coding tool in this repo.
Create a vendor-agnostic context layer:

1. Create AGENTS.md at the repo root (≤150 lines):
   - Non-inferable information only — build commands, architecture,
     constraints, key gotchas
   - No tool-specific syntax

2. Make existing tool-specific files thin adapters:
   - CLAUDE.md      → @-imports from .ai/ + Claude-specific settings only
   - .junie/        → @-imports from .ai/ + Junie-specific settings only
   - Nothing should be duplicated across tool files — .ai/ is the source

Show me the proposed AGENTS.md and updated adapter files before writing.

Level up the AI setup with automated verification and task-based planning:

1. Audit .ai/knowledge.md for prose rules that could be enforced by a script.
   For each one, propose a hook in .ai/hooks/ that exits non-zero on violation.

2. Create .ai/hooks/verify-build.sh — runs the build and tests, prints a
   clear error on failure. Wire it into AGENTS.md: agent must run it before
   marking any task complete.

3. Create a task folder template at .ai/tasks/TEMPLATE/:
   - context.md   — background, links, session protocol
   - checklist.md — implementation steps
   - findings.md  — gotchas discovered during work
   - tracker.md   — last action / next action / open decisions
   - summary.md   — post-task writeup before flushing to knowledge.md

   Add a rule to AGENTS.md: every non-trivial task gets a folder.
   The task is not closed until findings are promoted to knowledge.md.

Propose before writing. Show me the hook scripts and folder template first.

Create a personal engineering wiki in this directory.
The wiki follows the Karpathy LLM Wiki pattern — knowledge is compiled
once and kept current, not re-derived on every query.

Structure:
  wiki/
  ├── index.md      — content catalog, one line per page
  ├── log.md        — append-only activity log
  ├── repo/         — per-repository knowledge pages
  ├── decision/     — architectural and technical decisions
  ├── debug/        — debugging sessions and root causes
  ├── gotcha/       — non-obvious traps and constraints
  ├── concept/      — established technical concepts
  └── note/         — freeform captures

Rules:
- Every page has YAML frontmatter: type, repo, tags, created, updated
- index.md is always up to date — update it on every change
- log.md is append-only — never edit past entries
- Cross-links use [[category/slug]] Obsidian format
- You (the LLM) write the wiki. I curate the sources.

Create the folder structure, index.md, and log.md now.
Do not create placeholder pages — only real structure.

Ingest the following source into the wiki.

[paste notes, debug log, meeting MoM, ticket, code snippet, or screenshot]

Steps:
1. Read the source and identify the type:
   repo · decision · debug · gotcha · concept · note
2. Write a wiki page in the correct wiki/ subdirectory with full frontmatter
3. Update any existing pages that are touched by this new information
4. Flag any contradictions with existing pages in both pages
5. Update wiki/index.md with all new or significantly changed pages
6. Append a one-line entry to wiki/log.md

Do not invent facts not present in the source.
Mark gaps and open questions directly in the page under ## Open Questions.

Do a full scan of this repo's AI setup and produce a prioritised
list of improvements.

Scan: AGENTS.md, CLAUDE.md, .claude/, .junie/, .ai/ (knowledge.md,
context/, skills/, hooks/, tasks/), and any other agent context files.

For each area assess:
- Presence     — what exists vs what is missing from the four-level framework
- Lean-ness    — inferrable facts wasting context? Non-obvious constraints missing?
- Skills       — repeated workflows codified, or re-explained every session?
- Verification — quality gates enforced as runnable hooks, or just prose advice?
- Task workflow — task folder structure present? Complex enough to need one?
- Vendor layer — does AGENTS.md exist? Do tool files duplicate or delegate?
- Knowledge    — mechanism to promote discoveries into knowledge.md?

Output format:
  ## Current state
  ## P1 — High impact, quick to fix
  ## P2 — High impact, requires more work
  ## P3 — Nice to have
  ## Suggested next step

Do not modify any files. Audit and report only.