IRON LAW: User Specifications Are Sacred
THIS LAW IS ABSOLUTE AND ADMITS NO EXCEPTIONS.
- Every word the user says is a specification - follow verbatim, no errors, no exceptions
- Never modify user specs without explicit discussion - if you identify a potential issue, STOP and discuss with the user FIRST
- Never take initiative to change specifications - your role is to implement, not to reinterpret
- If you see an error in the spec, you MUST:
- Stop immediately
- Explain the potential issue clearly
- Wait for user guidance before proceeding
- No silent "improvements" - what seems like an improvement to you may break the user's intent
Violation of this law invalidates all work produced.
Background Agent Boundaries
When running as a background agent, you may ONLY write to:
- The project directory and its subdirectories
- The parent directory (for sub-git projects)
- ~/.claude (for plugin/settings fixes)
- /tmp
Do NOT write outside these locations.
GHE_REPORTS Rule (MANDATORY)
ALL reports MUST be posted to BOTH locations:
- GitHub Issue Thread - Full report text (NOT just a link!)
- GHE_REPORTS/ - Same full report text (FLAT structure, no subfolders!)
Report naming: <TIMESTAMP>_<title or description>_(<AGENT>).md
Timestamp format: YYYYMMDDHHMMSSTimezone
ALL 11 agents write here: Athena, Hephaestus, Artemis, Hera, Themis, Mnemosyne, Hermes, Ares, Chronos, Argos Panoptes, Cerberus
REQUIREMENTS/ is SEPARATE - permanent design documents, never deleted.
Deletion Policy: DELETE ONLY when user EXPLICITLY orders deletion due to space constraints.
GHE Requirements Management
Overview
Requirements in GHE are versioned markdown files stored in REQUIREMENTS/ that serve as the source of truth for feature implementation. Every DEV thread MUST link to a requirements file before work begins.
Folder Structure
REQUIREMENTS/
├── _templates/
│ └── REQ-TEMPLATE.md # Template for new requirements
├── epic-{N}/ # Requirements grouped by epic
│ ├── wave-{W}/ # Further grouped by wave
│ │ ├── REQ-001-feature.md
│ │ └── REQ-002-feature.md
│ └── REQ-003-standalone.md # Epic-level (not wave-specific)
├── standalone/ # Requirements without epic
│ └── REQ-xxx-feature.md
└── CHANGELOG.md # Requirements version history
Requirements File Format
Each REQ file MUST follow this structure:
---
req_id: REQ-XXX
version: 1.0.0
status: draft|approved|implemented|deprecated
created: YYYY-MM-DD
updated: YYYY-MM-DD
epic: N (optional)
wave: W (optional)
linked_issues: [#N, #M] (filled by system)
---
# REQ-XXX: Feature Name
## 1. Overview
Brief description of the feature.
## 2. User Story
As a [user type], I want [goal] so that [benefit].
## 3. Acceptance Criteria
- [ ] AC-1: Specific, testable criterion
- [ ] AC-2: Another criterion
- [ ] AC-3: Third criterion
## 4. Technical Requirements
### 4.1 Functional
- FR-1: Functional requirement
- FR-2: Another functional requirement
### 4.2 Non-Functional
- NFR-1: Performance, security, etc.
## 5. Atomic Changes
Break down into smallest implementable units:
1. **CHANGE-1**: Description (creates: file.py, modifies: other.py)
2. **CHANGE-2**: Description (creates: test_file.py)
3. **CHANGE-3**: Description (modifies: config.yaml)
## 6. Test Requirements
For each atomic change, define tests:
- TEST-1 for CHANGE-1: What to test
- TEST-2 for CHANGE-2: What to test
## 7. Dependencies
- Requires: REQ-XXX (if any)
- Blocks: REQ-YYY (if any)
## 8. Revision History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0.0 | YYYY-MM-DD | @user | Initial version |
Creating Requirements
Step 1: Create REQ File
# Determine next REQ number
LAST_REQ=$(find REQUIREMENTS -name "REQ-*.md" | sed 's/.*REQ-\([0-9]*\).*/\1/' | sort -n | tail -1)
NEXT_REQ=$(printf "%03d" $((LAST_REQ + 1)))
# Create from template
cp REQUIREMENTS/_templates/REQ-TEMPLATE.md "REQUIREMENTS/epic-${EPIC}/wave-${WAVE}/REQ-${NEXT_REQ}-${FEATURE_NAME}.md"
Step 2: Fill Requirements
Use the orchestrator (Athena) to analyze the feature request and fill:
- User story
- Acceptance criteria
- Technical requirements
- Atomic changes breakdown
- Test requirements
Step 3: Approve Requirements
# Change status from draft to approved
sed -i 's/status: draft/status: approved/' "$REQ_FILE"
# Commit with version tag
git add "$REQ_FILE"
git commit -m "REQ-${NEXT_REQ} v1.0.0: ${FEATURE_NAME} - approved"
Step 4: Link to Issue
When creating a DEV thread, the issue body MUST include:
## Requirements
- **Primary**: [REQ-XXX](../REQUIREMENTS/path/to/REQ-XXX.md) v1.0.0
- **Related**: [REQ-YYY](../REQUIREMENTS/path/to/REQ-YYY.md) (optional)
Versioning Requirements
Requirements use semantic versioning:
- MAJOR.MINOR.PATCH
- PATCH: Typos, clarifications (no functional change)
- MINOR: Added criteria, new atomic changes
- MAJOR: Breaking changes to acceptance criteria
Version Update Protocol
# Read current version
CURRENT_VERSION=$(grep "^version:" "$REQ_FILE" | cut -d' ' -f2)
# Bump version (example: minor bump)
NEW_VERSION=$(echo $CURRENT_VERSION | awk -F. '{print $1"."$2+1".0"}')
# Update file
sed -i "s/version: $CURRENT_VERSION/version: $NEW_VERSION/" "$REQ_FILE"
sed -i "s/updated: .*/updated: $(date +%Y-%m-%d)/" "$REQ_FILE"
# Add to revision history (manual step)
# Commit
git add "$REQ_FILE"
git commit -m "REQ-XXX v${NEW_VERSION}: Description of changes"
SERENA Backup
Requirements are automatically backed up to SERENA memory:
# Backup all requirements to SERENA
mkdir -p .serena/memories/requirements
for req in REQUIREMENTS/**/*.md; do
if [[ "$req" != *"_templates"* && "$req" != *"CHANGELOG"* ]]; then
cp "$req" ".serena/memories/requirements/$(basename $req)"
fi
done
When to sync:
- After any REQ file is created or updated
- After any DEV thread is claimed
- Before any context compaction
Linking Requirements to Issues
At Issue Creation
gh issue create \
--title "[${EPIC}][DEV] Feature Name" \
--label "phase:dev,epic:${EPIC},wave:${WAVE}" \
--body "$(cat <<EOF
## Requirements
**Primary Requirement**: [REQ-${REQ_NUM}](REQUIREMENTS/epic-${EPIC}/wave-${WAVE}/REQ-${REQ_NUM}-name.md) v${VERSION}
### Acceptance Criteria (from REQ file)
- [ ] AC-1: Criterion
- [ ] AC-2: Criterion
### Atomic Changes
1. CHANGE-1: Description
2. CHANGE-2: Description
EOF
)"
Updating Linked Issues
When requirements change, update all linked issues:
# Find issues linked to a requirement
LINKED_ISSUES=$(grep -l "REQ-${REQ_NUM}" .git/*) # Or use GitHub search
# Post update notice
for issue in $LINKED_ISSUES; do
gh issue comment "$issue" --body "## Requirements Updated
REQ-${REQ_NUM} updated to v${NEW_VERSION}.
### Changes
${CHANGE_DESCRIPTION}
### Impact
Review your implementation against the updated acceptance criteria."
done
Validation Commands
Check Requirements Linked
# Verify issue has requirements link
ISSUE_BODY=$(gh issue view $ISSUE --json body --jq '.body')
if ! echo "$ISSUE_BODY" | grep -q "REQUIREMENTS/.*REQ-"; then
echo "ERROR: Issue #$ISSUE has no requirements linked!"
exit 1
fi
Verify Requirements File Exists
# Extract REQ path from issue
REQ_PATH=$(echo "$ISSUE_BODY" | grep -oP 'REQUIREMENTS/[^\s\)]+\.md' | head -1)
if [ ! -f "$REQ_PATH" ]; then
echo "ERROR: Requirements file not found: $REQ_PATH"
exit 1
fi
Check Requirements Version
# Get version from issue link
LINKED_VERSION=$(echo "$ISSUE_BODY" | grep -oP 'v[0-9]+\.[0-9]+\.[0-9]+' | head -1)
# Get current version from file
CURRENT_VERSION=$(grep "^version:" "$REQ_PATH" | cut -d' ' -f2)
if [ "$LINKED_VERSION" != "$CURRENT_VERSION" ]; then
echo "WARNING: Issue links to v$LINKED_VERSION but current is v$CURRENT_VERSION"
fi
Integration with Thread Managers
DEV Manager (Hephaestus)
- MUST verify requirements linked before claiming
- MUST break down into atomic changes from REQ file
- MUST write tests for each atomic change BEFORE implementation
TEST Manager (Artemis)
- MUST verify all tests from REQ file are passing
- MUST check test coverage against atomic changes
REVIEW Manager (Hera)
- MUST verify each acceptance criterion is met
- MUST check implementation matches technical requirements
- MUST verify atomic changes are complete
Settings Awareness
Respects .claude/ghe.local.md:
requirements_folder: REQUIREMENTS # Default folder name
require_requirements: true # Block DEV without requirements
auto_serena_backup: true # Auto-backup to SERENA