diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..94d256b9 --- /dev/null +++ b/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` diff --git a/CLAUDE.md b/CLAUDE.md index 4dcd6a44..43c994c2 100644 --- a/CLAUDE.md +++ b/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 - : -``` - -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 diff --git a/hyperfleet/components/CLAUDE.md b/hyperfleet/components/CLAUDE.md index 7fe142c3..123a7407 100644 --- a/hyperfleet/components/CLAUDE.md +++ b/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