Skip to content

CLAUDE.md

Latest commit

 

History

History
193 lines (149 loc) · 6.74 KB

CLAUDE.md

File metadata and controls

193 lines (149 loc) · 6.74 KB

CLAUDE.md - AI Assistant Context for HCA

This file provides context for AI assistants (Claude, etc.) working with the HCA specification repository.

What is HCA?

Holonic Compound Architecture (HCA) is a protocol specification for building autonomous, composable, and continuously-improving agentic systems.

Key concepts:

  • Holons: Agents that are both autonomous wholes AND cooperative parts
  • Holarchy: Recursive tree structure of holons (authority down, results up)
  • Compound Loop: PLAN → WORK → REVIEW → REVISE with learning extraction
  • Protocol Boundaries: A2A (coordination), MCP (tools), ACP (northbound)

Repository Structure

hca/
├── README.md                 # Entry point, accessible overview
├── DOCUMENT-INDEX.md         # Navigation, reading paths, classification
├── CLAUDE.md                 # This file - AI assistant context
├── .gitignore
│
├── spec/                     # NORMATIVE - The Rules (MUST implement)
│   ├── SPEC.md               # Core specification (~37KB)
│   ├── GLOSSARY.md           # Term definitions (~20KB)
│   ├── HCA-EXTENSIONS.md     # JSON-RPC method schemas (~37KB)
│   └── STATE-MACHINES.md     # Formal state diagrams (~32KB)
│
├── reference/                # INFORMATIVE - Explains & Guides
│   ├── QUICK-REFERENCE.md    # 1-page cheat sheet
│   ├── ARCHITECTURE-DIAGRAM.md  # Visual Mermaid diagrams
│   ├── BUILDING-BLOCKS.md    # Protocol rationale
│   └── CONFORMANCE-CRITERIA.md  # Certification requirements
│
├── guidance/                 # INFORMATIVE - Implementation Patterns
│   └── SECURITY-CONSIDERATIONS.md
│
└── working/                  # PROJECT - Not Part of Spec
    ├── ANALYSIS-SUMMARY.md   # Validation summary
    ├── PROTOCOL-GAP-ANALYSIS.md
    └── CRITICAL-FIXES-REQUIRED.md

Document Classification

Classification Folder Uses RFC 2119? Creates Requirements?
Normative spec/ Yes Yes
Informative reference/, guidance/ No No
Working working/ No No

Key Specification Concepts

Holon Types

  • Root Holon: Top-level, no parent, mission control, external interface
  • Domain Holon: Intermediate, coordinates specialty area, delegates
  • Leaf Holon: No children, executes concrete work, invokes tools

Compound Loop Phases

  1. PLAN (~40% effort): Query knowledge base, create plan, allocate budget
  2. WORK: Execute plan, invoke tools via MCP, produce artifacts
  3. REVIEW (~40% effort): Separate evaluator holon, produce verdict
  4. REVISE: On failure with retries remaining, loop back to PLAN
  5. COMPOUND: Extract lessons for knowledge base (outer loop)

Protocol Methods (hca/* namespace)

All HCA methods use JSON-RPC 2.0 with hca/ prefix:

Task Management:

  • hca/task/delegate, hca/task/negotiate, hca/task/status
  • hca/task/complete, hca/task/escalate
  • hca/task/checkpoint, hca/task/resume, hca/task/transfer

Review:

  • hca/review/request, hca/review/verdict

Knowledge:

  • hca/knowledge/contribute, hca/knowledge/query
  • hca/knowledge/deprecate, hca/knowledge/attest, hca/knowledge/conflict

Anti-Patterns:

  • hca/antipattern/register, hca/antipattern/check

Human Intervention:

  • hca/human/request-approval, hca/human/override, hca/human/release

Holon Lifecycle:

  • hca/holon/register, hca/holon/deregister
  • hca/holon/evolve, hca/holon/promote, hca/holon/reputation

Artifacts:

  • hca/artifact/store, hca/artifact/retrieve

Conformance Levels

  • Level 1 (Minimal): Holons + delegation + artifacts + review
  • Level 2 (Standard): + Full compound loop + iteration + negotiation
  • Level 3 (Full): + Knowledge base + cross-task learning

Working with This Repository

When Editing Specs

  • Use RFC 2119 keywords (MUST, SHOULD, MAY) only in spec/ documents
  • Keep cross-references up to date
  • Update GLOSSARY.md when adding new terms
  • Add state diagrams to STATE-MACHINES.md for new protocol flows
  • Add JSON-RPC schemas to HCA-EXTENSIONS.md for new methods

When Adding New Sections

  1. Update table of contents in the document
  2. Add to DOCUMENT-INDEX.md if significant
  3. Update related documents that reference it
  4. Consider if GLOSSARY.md needs new terms

Cross-Reference Format

  • Within same folder: [GLOSSARY](GLOSSARY.md)
  • To other folders: [SPEC](../spec/SPEC.md) or [SPEC](spec/SPEC.md) from root

Document Header Format

# HCA [Document Title]

**Holonic Compound Architecture (HCA) v0.1 - [Document Type]**

[Brief description]

---

Document Footer Format

---

*This document is part of the Holonic Compound Architecture (HCA) Specification v0.1*

Important Invariants

Task Invariants

  1. Task is in exactly one state at any time
  2. Producer and reviewer MUST be different holons
  3. Iteration MUST be bounded (max retries + budget)
  4. Escalation MUST include evidence of what was attempted

Knowledge Invariants

  1. Query knowledge during PLAN phase
  2. Contribute lessons during COMPOUND phase
  3. Both success AND failure produce lessons
  4. Lessons have lifecycle (Active → Deprecated → Archived)

Authority Invariants

  1. Authority is constraint-based, not command-based
  2. Authority flows DOWN (constraints, goals, budgets)
  3. Results flow UP (artifacts, verdicts, status)
  4. Children MAY refuse or negotiate tasks

Version History

Version Date Status
0.1.0 2026-01-06 Draft

External References

Common Tasks

"Add a new protocol method"

  1. Define in spec/HCA-EXTENSIONS.md with full JSON-RPC schema
  2. Add state diagram to spec/STATE-MACHINES.md if new flow
  3. Add terms to spec/GLOSSARY.md
  4. Update reference/QUICK-REFERENCE.md method list
  5. Consider conformance level implications

"Add a new concept"

  1. Define in spec/SPEC.md with normative requirements
  2. Add to spec/GLOSSARY.md
  3. Update spec/STATE-MACHINES.md if stateful
  4. Update DOCUMENT-INDEX.md if major addition

"Fix a cross-reference"

  1. Check DOCUMENT-INDEX.md for authoritative paths
  2. Use relative paths from document location
  3. Verify link works (file exists at path)

This context file helps AI assistants work effectively with the HCA specification.