Add: LLM harness MANIFEST, CLAUDE entry point, LOADER, and templates
This commit is contained in:
LLM Harness
@@ -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.
|
||||
@@ -0,0 +1,139 @@
|
||||
# PROJECT HARNESS TEMPLATE
|
||||
|
||||
**Copy this to your project and customize.**
|
||||
|
||||
---
|
||||
|
||||
## [Project Name] Structure
|
||||
|
||||
```
|
||||
~/workspace/[project]/
|
||||
├── HARNESS.md ← This file (project-specific)
|
||||
├── modules/
|
||||
│ ├── design/ ← Architecture & planning phase
|
||||
│ │ ├── SPEC.md ← What to build
|
||||
│ │ ├── CONSTRAINTS.md ← Non-functional requirements
|
||||
│ │ ├── SCHEMA.md ← Data model (if applicable)
|
||||
│ │ └── ARCHITECTURE.md ← System design
|
||||
│ │
|
||||
│ ├── implementation/ ← Building phase
|
||||
│ │ ├── GUIDE.md ← How to build
|
||||
│ │ ├── CHECKLIST.md ← What to verify
|
||||
│ │ └── CODE_STANDARDS.md ← Style & patterns
|
||||
│ │
|
||||
│ ├── testing/ ← QA phase
|
||||
│ │ ├── TEST_PLAN.md ← What to test
|
||||
│ │ ├── CASES.md ← Test cases
|
||||
│ │ └── COVERAGE.md ← Coverage targets
|
||||
│ │
|
||||
│ └── docs/ ← Documentation phase
|
||||
│ ├── USER_GUIDE.md ← For end users
|
||||
│ ├── API.md ← For developers
|
||||
│ └── DEPLOYMENT.md ← For ops
|
||||
│
|
||||
├── [project files/directories]
|
||||
└── README.md ← Project overview
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phases
|
||||
|
||||
### Phase 1: Design
|
||||
- **Agent:** claude-code (opus model)
|
||||
- **Module:** design/
|
||||
- **Input:** SPEC.md, CONSTRAINTS.md
|
||||
- **Output:** ARCHITECTURE.md, SCHEMA.md
|
||||
- **Validation:** All constraints addressed
|
||||
|
||||
### Phase 2: Implementation
|
||||
- **Agent:** claude-code (sonnet model)
|
||||
- **Module:** implementation/
|
||||
- **Input:** ARCHITECTURE.md from Phase 1
|
||||
- **Output:** Working code
|
||||
- **Validation:** Passes CODE_STANDARDS.md
|
||||
|
||||
### Phase 3: Review
|
||||
- **Agent:** cursor (opus model)
|
||||
- **Module:** [code to review]
|
||||
- **Input:** Implementation from Phase 2
|
||||
- **Output:** Review report, approved/rejected
|
||||
- **Validation:** Critical feedback addressed
|
||||
|
||||
### Phase 4: Testing
|
||||
- **Agent:** claude-code (sonnet model)
|
||||
- **Module:** testing/
|
||||
- **Input:** TEST_PLAN.md
|
||||
- **Output:** Test code, coverage report
|
||||
- **Validation:** Coverage targets met
|
||||
|
||||
### Phase 5: Documentation
|
||||
- **Agent:** claude-code (sonnet model)
|
||||
- **Module:** docs/
|
||||
- **Input:** Code + ARCHITECTURE.md
|
||||
- **Output:** USER_GUIDE.md, API.md, DEPLOYMENT.md
|
||||
- **Validation:** Complete, accurate, usable
|
||||
|
||||
---
|
||||
|
||||
## Key Constraints
|
||||
|
||||
**[List your project's non-functional requirements]**
|
||||
|
||||
- Performance: [e.g., API responses <100ms p95]
|
||||
- Scalability: [e.g., support 10k concurrent users]
|
||||
- Security: [e.g., encryption at rest/transit]
|
||||
- Availability: [e.g., 99.9% uptime SLA]
|
||||
- Compatibility: [e.g., Node.js 20+, PostgreSQL 14+]
|
||||
|
||||
---
|
||||
|
||||
## Technology Stack
|
||||
|
||||
**Backend:** [e.g., Node.js + Express]
|
||||
**Database:** [e.g., PostgreSQL + Redis]
|
||||
**Frontend:** [e.g., React + Tailwind]
|
||||
**DevOps:** [e.g., Docker + Kubernetes]
|
||||
|
||||
---
|
||||
|
||||
## Module Loading Rules
|
||||
|
||||
When briering agents:
|
||||
- Only load the CURRENT phase's module
|
||||
- Don't load future phases
|
||||
- Include CONSTRAINTS.md in every brief
|
||||
- Include project README for context
|
||||
|
||||
Example: When designing, DON'T load implementation/ or testing/
|
||||
|
||||
---
|
||||
|
||||
## Checkpoint & Recovery
|
||||
|
||||
Each phase saves checkpoint:
|
||||
```json
|
||||
{
|
||||
"phase": "design",
|
||||
"status": "completed|in_progress|blocked|error",
|
||||
"timestamp": "2026-04-25T23:00:00Z",
|
||||
"agent": "claude-code",
|
||||
"model": "opus",
|
||||
"result_file": "modules/design/ARCHITECTURE.md",
|
||||
"next_phase": "implementation"
|
||||
}
|
||||
```
|
||||
|
||||
If phase fails, save error and replan.
|
||||
|
||||
---
|
||||
|
||||
## Customization
|
||||
|
||||
Change this template to fit YOUR project:
|
||||
- Add/remove phases
|
||||
- Change agent assignments
|
||||
- Define your own constraints
|
||||
- Add project-specific workflows
|
||||
|
||||
Just keep the structure PSR-4 compatible.
|
||||
Reference in New Issue
Block a user