Add: LLM harness MANIFEST, CLAUDE entry point, LOADER, and templates

2026-04-25 23:15:58 +02:00
parent 421945c9e5
commit dd0cdfdc13
5 changed files with 726 additions and 0 deletions
@@ -0,0 +1,190 @@
+# MODULE STRUCTURE TEMPLATE
+
+**Standard structure for any module within a project harness.**
+
+---
+
+## Module Anatomy
+
+```
+modules/[module-name]/
+├── APPROACH.md       ← How to execute this phase
+├── CHECKLIST.md      ← What to verify
+├── SPEC.md           ← What to build (input for agent)
+└── [outputs]/        ← Generated by agent
+    ├── DESIGN.md
+    ├── SCHEMA.md
+    └── ...
+```
+
+---
+
+## APPROACH.md
+
+**Purpose:** Tell agents HOW to execute this phase.
+
+```markdown
+# [Phase Name] Approach
+
+## Goal
+[What should be accomplished]
+
+## Process
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Constraints to Respect
+- [Constraint 1]
+- [Constraint 2]
+
+## Success Criteria
+- [Criterion 1]
+- [Criterion 2]
+
+## Output Files
+- [file1.md]
+- [file2.md]
+```
+
+---
+
+## CHECKLIST.md
+
+**Purpose:** Verify the phase completed correctly.
+
+```markdown
+# [Phase Name] Checklist
+
+## Functional
+- [ ] All requirements from SPEC.md are met
+- [ ] All constraints are satisfied
+- [ ] No blocking open questions
+
+## Quality
+- [ ] Follows code/design standards
+- [ ] Performance targets met
+- [ ] Security considerations addressed
+
+## Documentation
+- [ ] All decisions documented
+- [ ] Rationales explained
+- [ ] Ambiguities clarified
+
+## Ready for Next Phase?
+- [ ] All checkboxes above passed
+- [ ] No blockers remain
+```
+
+---
+
+## SPEC.md (Example)
+
+**Purpose:** Define requirements for the agent.
+
+```markdown
+# [Module] Specification
+
+## Overview
+[What problem does this solve?]
+
+## Requirements
+1. [Functional requirement 1]
+2. [Functional requirement 2]
+3. [Non-functional requirement]
+
+## Constraints (from project CONSTRAINTS.md)
+- [Constraint 1]
+- [Constraint 2]
+
+## Acceptance Criteria
+- [Criterion 1]
+- [Criterion 2]
+
+## Related Files
+- Architecture: [link]
+- Database: [link]
+- Testing: [link]
+```
+
+---
+
+## Module Loading Example
+
+When bribing Claude Code for "design" phase:
+
+```bash
+# Load these files (and ONLY these):
+- ~/workspace/[project]/HARNESS.md (project structure)
+- ~/workspace/[project]/modules/design/APPROACH.md (how to execute)
+- ~/workspace/[project]/modules/design/SPEC.md (what to build)
+- ~/workspace/[project]/modules/design/CHECKLIST.md (success criteria)
+- ~/workspace/gravl/modules/design/CONSTRAINTS.md (from parent)
+
+# Output expected:
+- ~/workspace/[project]/modules/design/ARCHITECTURE.md
+- ~/workspace/[project]/modules/design/ER-DIAGRAM.md
+- ~/workspace/[project]/modules/design/DECISION_LOG.md
+```
+
+---
+
+## Minimal Data Principle
+
+✅ **DO load:**
+- Module specs for THIS phase
+- Related specs from same project
+- Constraints that affect THIS phase
+
+❌ **DON'T load:**
+- Future phase modules
+- Implementation code
+- Test files
+- Other projects
+- Unused historical context
+
+**Goal:** Agent has EXACTLY what it needs, nothing more.
+
+---
+
+## Example: Design Module
+
+```
+modules/design/
+├── APPROACH.md              ← "Design system architecture"
+├── CHECKLIST.md             ← "All constraints verified?"
+├── SPEC.md                  ← "Build database schema + API spec"
+├── CONSTRAINTS.md           ← "Performance, security, scaling"
+├── EXISTING_ARCHITECTURE.md ← "Current system overview"
+└── [outputs]/
+    ├── SCHEMA.md            ← Agent creates this
+    ├── API_SPEC.md          ← Agent creates this
+    ├── DECISIONS.md         ← Agent creates this
+    └── ER_DIAGRAM.md        ← Agent creates this
+```
+
+When bribing agent for design:
+```
+Load:
+- APPROACH.md
+- SPEC.md
+- CONSTRAINTS.md
+- EXISTING_ARCHITECTURE.md
+
+Don't load:
+- implementation/
+- testing/
+- docs/
+```
+
+---
+
+## Best Practices
+
+1. **Keep specs focused** — One module = one task
+2. **Document decisions** — Why, not just what
+3. **Version constraints** — Tag major constraint changes
+4. **Link related modules** — Show dependencies
+5. **Checkpoint at boundaries** — Save state between phases
+
+This keeps context minimal and agents focused.