# 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.