aiskillstore/ghe-requirements

IRON LAW: User Specifications Are Sacred

THIS LAW IS ABSOLUTE AND ADMITS NO EXCEPTIONS.

1. Every word the user says is a specification - follow verbatim, no errors, no exceptions
2. Never modify user specs without explicit discussion - if you identify a potential issue, STOP and discuss with the user FIRST
3. Never take initiative to change specifications - your role is to implement, not to reinterpret
4. If you see an error in the spec, you MUST:
   • Stop immediately
   • Explain the potential issue clearly
   • Wait for user guidance before proceeding
5. 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:

1. GitHub Issue Thread - Full report text (NOT just a link!)
2. 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