HYPERFLEET-930 - docs: replace CLAUDE.md with AGENTS.md

AGENTS.md

@@ -0,0 +1,90 @@
+# HyperFleet Architecture Repository
+
+Documentation-only repository. Single source of truth for all HyperFleet architectural documentation. No application code.
+
+## Validation
+
+| Script | Checks |
+|--------|--------|
+| `./hack/markdownlint.sh` | Markdown formatting |
+| `./hack/yamllint.sh` | YAML formatting |
+| `./hack/linkcheck.sh` | Internal links |
+
+Many markdownlint rules are disabled — see `.markdownlint-cli2.yaml` for the active set.
+
+## Source of Truth
+
+| Topic | Location |
+|-------|----------|
+| System architecture overview | `hyperfleet/README.md` |
+| Component design docs | `hyperfleet/components/` |
+| Component doc requirements | `hyperfleet/components/CLAUDE.md` |
+| Engineering standards | `hyperfleet/standards/` |
+| Standards doc requirements | `hyperfleet/standards/CLAUDE.md` |
+| Implementation guides | `hyperfleet/docs/` |
+| Architecture Decision Records | `hyperfleet/adrs/` (see `hyperfleet/adrs/README.md` for template) |
+| Glossary / terminology | `hyperfleet/docs/glossary.md` |
+| Document templates | `hyperfleet/docs/templates/` |
+| Deprecated / archived docs | `hyperfleet/deprecated/` |
+
+## Document Rules
+
+### Metadata Header
+
+Every document starts with:
+
+```markdown
+---
+Status: Active
+Owner: Team Name
+Last Updated: YYYY-MM-DD
+---
+```
+
+Update "Last Updated" only for meaningful changes (design decisions, new sections, trade-offs modified) — not typos or formatting.
+
+### Status Filtering
+
+**IMPORTANT:** Unless explicitly asked otherwise, ignore any document with Status other than `Active` or located under a `deprecated/` directory.
+
+### Required Sections by Document Type
+
+**Component docs** (`hyperfleet/components/`): MUST include Trade-offs AND Alternatives Considered sections. Full template and required section list in `hyperfleet/components/CLAUDE.md`.
+
+**Standards docs** (`hyperfleet/standards/`): MUST follow Overview, Standard, Examples, Enforcement, References pattern with RFC 2119 language. Full details in `hyperfleet/standards/CLAUDE.md`.
+
+### Diagrams
+
+Use Mermaid syntax for new diagrams. Avoid adding image files; some legacy images exist.
+
+### Writing Quality
+
+Quantify architectural claims. See `README.md` Writing Guidelines for examples.
+
+### Glossary
+
+**IMPORTANT:** Before introducing new terms, check `hyperfleet/docs/glossary.md`. Add new terms in the same change.
+
+## Gotchas
+
+- Markdownlint is very lenient — 32+ rules disabled in `.markdownlint-cli2.yaml`. Don't assume formatting checks are comprehensive.
+- Legacy PNG images exist in the repo despite Mermaid-first policy. Don't flag or delete them.
+- Trade-offs, Alternatives Considered, and metadata header requirements are prompt-only — no mechanical validator exists yet. Easy to miss.
+
+## Boundaries
+
+### DO NOT
+
+1. **Create code files** — documentation only, no exceptions
+2. **Skip Trade-offs or Alternatives Considered** in component docs
+3. **Create docs without metadata header** (`Status`, `Owner`, `Last Updated`)
+4. **Use vague language** — quantify impact, be specific
+5. **Put documents in wrong directories** — check Source of Truth table above
+6. **Surface deprecated documents** unless explicitly asked
+
+### DO
+
+1. Read existing docs in target directory before creating new ones
+2. Check glossary before introducing new terms
+3. Use `hyperfleet/components/sentinel/sentinel.md` as reference example for component docs
+4. Validate changes with `./hack/markdownlint.sh` and `./hack/yamllint.sh`

CLAUDE.md

@@ -1,111 +1 @@
-# Claude Code Guidelines for HyperFleet Architecture Repository
-
-## Repository Purpose
-
-This is a **documentation-only repository** - the single source of truth for all HyperFleet architectural documentation. There is no application code here.
-
-All documents are **living documents** that evolve with design and implementation. Git tracks change history.
-
-## Repository Structure
-
-```
-├── README.md                      # Main guide - required reading
-├── hyperfleet/
-│   ├── README.md                  # System overview (30,000 feet view)
-│   ├── components/                # Component design decisions
-│   │   ├── adapter/               # Adapter architecture
-│   │   ├── api-service/           # API service design
-│   │   ├── broker/                # Message broker design
-│   │   ├── claude-code-plugin/    # Claude Code plugin
-│   │   └── sentinel/              # Sentinel service design
-│   ├── adrs/                       # Architecture Decision Records
-│   ├── deprecated/                # Archived documents (MVP, old adapters, deployment)
-│   ├── docs/                      # Implementation guides
-│   ├── standards/                 # Prescriptive standards (must follow)
-```
-
-## Document Status Values
-
-- **Draft**: Initial design, still being refined
-- **Active**: Current implementation
-- **Deprecated**: No longer used (link to replacement)
-
-## Use only Active status pages
-
-Unless asked explicitly otherwise, discard any document with `Status` field different than `Active`
-
-Unless asked explicitly otherwise, discard any document with "deprecated" in the name or under a folder with "deprecated" in the name
-
-## Document Header Format
-
-All documents must start with metadata fields, at the beginning of the file
-
-```markdown
----
-Status: Active
-Owner: Team Name
-Last Updated: YYYY-MM-DD
----
-
-# Document Title
-```
-
-Update "Last Updated" only for meaningful changes (design changes, new sections, trade-offs modified), not typos or formatting.
-
-## Required Diagram Format
-
-Use **Mermaid diagrams** in all architecture and component documents:
-- Text-based, version control friendly
-- Renders natively in GitHub markdown
-- Consistent across all docs
-
-## Key Navigation Files
-
-| I want to...                    | Start here                                    |
-|---------------------------------|-----------------------------------------------|
-| Understand HyperFleet           | `hyperfleet/README.md` |
-| Design a new component          | `hyperfleet/components/` + see README         |
-| Write an implementation guide   | `hyperfleet/docs/`                            |
-| Find trade-offs                 | Component docs → "Trade-offs" section         |
-| Track technical debt            | Search "Technical Debt Incurred"              |
-| See complete component example  | `hyperfleet/components/sentinel/sentinel.md`  |
-
-## Commit Message Format
-
-```
-HYPERFLEET-XXX - <type>: <subject>
-```
-
-Examples:
-- `HYPERFLEET-123 - docs: add sentinel component design`
-- `HYPERFLEET-456 - docs: update API trade-offs section`
-
-More info on [commit-standard.md](./hyperfleet/standards/commit-standard.md)
-
-## What Claude Should NOT Do
-
-1. **Do not create code files** - This is a documentation-only repo
-2. **Do not skip Trade-offs section** - Every component doc MUST have Trade-offs
-3. **Do not skip Alternatives Considered** - Required alongside Trade-offs
-4. **Do not add unnecessary files** - No README duplicates, no extra config files
-5. **Do not use vague language** - Be specific and quantify impact
-6. **Do not create documentation without required sections** - Check README for requirements
-
-## Writing Guidelines
-
-### Be Specific
-- Bad: "This makes things faster"
-- Good: "This reduces API latency from 200ms to 50ms"
-
-### Quantify Impact
-- Bad: "This improves performance"
-- Good: "This reduces memory usage by 40%"
-
-### Document Trade-offs Honestly
-- Bad: "This is better in every way"
-- Good: "This simplifies code but increases latency by 10ms"
-
-## Related CLAUDE.md Files
-
-- `hyperfleet/standards/CLAUDE.md` - Standards document conventions
-- `hyperfleet/components/CLAUDE.md` - Component design requirements
+@AGENTS.md

hyperfleet/components/CLAUDE.md

@@ -124,7 +124,7 @@ See `sentinel/sentinel.md` for an example with:
 - Detailed How section with diagrams
 - Test scenarios documented
 
-**Note**: sentinel.md predates these guidelines and does not yet include Trade-offs or Alternatives Considered sections.
+**Note**: sentinel.md now includes Trade-offs and Alternatives Considered sections and can be used as a reference for the full component document pattern.
 
 ## Common Mistakes to Avoid