Skip to content

DOCUMENT-INDEX.md

Latest commit

 

History

History
228 lines (164 loc) · 7.4 KB

DOCUMENT-INDEX.md

File metadata and controls

228 lines (164 loc) · 7.4 KB

HCA Document Index

Holonic Compound Architecture (HCA) v0.1

This index provides the authoritative organization of all HCA specification documents.

Folder Structure

hca/
├── README.md                 ← Entry point
├── DOCUMENT-INDEX.md         ← You are here
│
├── spec/                     ← NORMATIVE (The Rules)
│   ├── SPEC.md
│   ├── GLOSSARY.md
│   ├── HCA-EXTENSIONS.md
│   └── STATE-MACHINES.md
│
├── reference/                ← INFORMATIVE (Explains & Guides)
│   ├── QUICK-REFERENCE.md
│   ├── ARCHITECTURE-DIAGRAM.md
│   ├── BUILDING-BLOCKS.md
│   └── CONFORMANCE-CRITERIA.md
│
├── guidance/                 ← INFORMATIVE (Implementation Patterns)
│   └── SECURITY-CONSIDERATIONS.md
│
└── working/                  ← PROJECT (Not Part of Spec)
    ├── ANALYSIS-SUMMARY.md
    ├── PROTOCOL-GAP-ANALYSIS.md
    └── CRITICAL-FIXES-REQUIRED.md

Document Classification

Normative vs Informative

Classification Meaning Folder
Normative Defines requirements. Uses MUST/SHALL/REQUIRED. spec/
Informative Explains or guides. Does not create requirements. reference/, guidance/
Working Project management. Not part of specification. working/

Audience Guide

Audience Start Here Then Read
Executive README QUICK-REFERENCE
Architect SPEC ARCHITECTURE-DIAGRAM, BUILDING-BLOCKS
Developer QUICK-REFERENCE HCA-EXTENSIONS, STATE-MACHINES
QA/Compliance CONFORMANCE-CRITERIA SPEC, STATE-MACHINES
Security SECURITY-CONSIDERATIONS SPEC (Section 8)

Documents by Folder

spec/ — Normative Specification

The authoritative rules. Implementations MUST follow these.

Document Description Reading Time
SPEC.md Core specification: holons, holarchy, compound loop, protocols 30 min
GLOSSARY.md Precise definitions for all HCA terminology 10 min
HCA-EXTENSIONS.md Complete JSON-RPC schemas for all hca/* methods 20 min
STATE-MACHINES.md Formal state diagrams for tasks, holons, negotiation 15 min

Dependency Order: GLOSSARY → SPEC → STATE-MACHINES → HCA-EXTENSIONS

reference/ — Reference Materials

Explains the specification. Helps understanding but doesn't add requirements.

Document Description Reading Time
QUICK-REFERENCE.md 1-page developer cheat sheet 3 min
ARCHITECTURE-DIAGRAM.md Visual Mermaid diagrams of system architecture 10 min
BUILDING-BLOCKS.md Why LSP/MCP/A2A/ACP/OpenHands were chosen 20 min
CONFORMANCE-CRITERIA.md How to certify Level 1/2/3 compliance 15 min

guidance/ — Implementation Guidance

Practical advice for building HCA systems. Non-normative.

Document Description Reading Time
SECURITY-CONSIDERATIONS.md Security patterns, trust boundaries, checklists 15 min

working/ — Working Documents

Project management and validation. Not part of the specification.

Document Description Reading Time
ANALYSIS-SUMMARY.md Executive summary of protocol validation 5 min
PROTOCOL-GAP-ANALYSIS.md Detailed validation against A2A/MCP/ACP specs 20 min
CRITICAL-FIXES-REQUIRED.md Action items before v0.1 release 5 min

Reading Paths

Path 1: "What is HCA?" (30 min)

README.md → reference/QUICK-REFERENCE.md → reference/ARCHITECTURE-DIAGRAM.md

Path 2: "I need to implement HCA" (2 hours)

reference/QUICK-REFERENCE.md → spec/SPEC.md → spec/GLOSSARY.md → spec/HCA-EXTENSIONS.md → spec/STATE-MACHINES.md

Path 3: "I need to evaluate/certify HCA compliance" (1 hour)

spec/SPEC.md (Sections 4-7, 10) → reference/CONFORMANCE-CRITERIA.md → spec/STATE-MACHINES.md

Path 4: "I'm designing an HCA system" (2 hours)

spec/SPEC.md → reference/BUILDING-BLOCKS.md → reference/ARCHITECTURE-DIAGRAM.md → guidance/SECURITY-CONSIDERATIONS.md

Path 5: "I need to review HCA protocol design" (1 hour)

working/ANALYSIS-SUMMARY.md → working/PROTOCOL-GAP-ANALYSIS.md → working/CRITICAL-FIXES-REQUIRED.md

Cross-Reference Matrix

Which documents reference which:

Document References Referenced By
spec/SPEC.md GLOSSARY All others
spec/GLOSSARY.md — SPEC, HCA-EXTENSIONS
spec/HCA-EXTENSIONS.md SPEC, GLOSSARY STATE-MACHINES
spec/STATE-MACHINES.md SPEC, HCA-EXTENSIONS CONFORMANCE-CRITERIA
reference/ARCHITECTURE-DIAGRAM.md SPEC README
reference/BUILDING-BLOCKS.md External specs SPEC (Appendix)
reference/CONFORMANCE-CRITERIA.md SPEC, STATE-MACHINES README
guidance/SECURITY-CONSIDERATIONS.md SPEC —
working/PROTOCOL-GAP-ANALYSIS.md External specs, SPEC ANALYSIS-SUMMARY
working/ANALYSIS-SUMMARY.md PROTOCOL-GAP-ANALYSIS —
working/CRITICAL-FIXES-REQUIRED.md PROTOCOL-GAP-ANALYSIS —

Document Standards

All HCA documents follow these conventions:

Header Format

# HCA [Document Title]

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

[Brief description of document purpose]

---

Document Types:

  • Normative Specification
  • Normative Reference
  • Reference Material
  • Implementation Guidance
  • Working Document

Footer Format

---

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

RFC 2119 Keywords

Only spec/ (Normative) documents use RFC 2119 keywords:

  • MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT
  • SHOULD, SHOULD NOT, RECOMMENDED
  • MAY, OPTIONAL

Version History

Version Date Changes
0.1.0 2026-01-06 Initial specification

Document Status

Document Status Location
SPEC.md Draft spec/
GLOSSARY.md Draft spec/
HCA-EXTENSIONS.md Draft spec/
STATE-MACHINES.md Draft spec/
QUICK-REFERENCE.md Draft reference/
ARCHITECTURE-DIAGRAM.md Draft reference/
BUILDING-BLOCKS.md Draft reference/
CONFORMANCE-CRITERIA.md Draft reference/
SECURITY-CONSIDERATIONS.md Draft guidance/
ANALYSIS-SUMMARY.md Working working/
PROTOCOL-GAP-ANALYSIS.md Working working/
CRITICAL-FIXES-REQUIRED.md Working working/

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