Github Elements Tracking

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 agent 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

Examples:

• 20251206143000GMT+01_epic_15_wave_launched_(Athena).md
• 20251206143022GMT+01_issue_42_dev_complete_(Hephaestus).md
• 20251206150000GMT+01_issue_42_tests_passed_(Artemis).md
• 20251206160000GMT+01_issue_42_review_complete_(Hera).md

ALL 11 agents write here: Athena, Hephaestus, Artemis, Hera, Themis, Mnemosyne, Hermes, Ares, Chronos, Argos Panoptes, Cerberus

REQUIREMENTS/ is SEPARATE - permanent design documents with legal validity, NEVER deleted.

Deletion Policy:

• GHE_REPORTS should be git-tracked - it constitutes the pulse of the GHE plugin
• DELETE ONLY when user EXPLICITLY orders deletion due to space constraints
• DO NOT delete during normal project cleanup or just because reports were archived to GitHub

Project Settings

This skill respects settings in .claude/ghe.local.md. Run /ghe:setup to configure.

Defaults (no settings file): enabled=true, enforcement=standard, serena_sync=true

Related GHE Skills

For specific operations, GHE provides specialized skills:

Key Workflows

Starting a New Feature:

1. Use ghe-requirements to create REQ file
2. Link requirements to DEV issue
3. Use ghe-claim to claim the thread
4. Follow TDD workflow from DEV manager

Tracking Changes:

1. Use ghe-changelog after significant commits
2. Updates automatically track requirements and code changes

Requirements-First Development: All DEV threads MUST link to a requirements file. The DEV manager (Hephaestus) enforces:

• Requirements breakdown into atomic changes
• TDD cycle for each atomic change (RED-GREEN-REFACTOR)
• Test coverage verification before transition

GitHub Elements Tracking

GitHub Issues as permanent memory for AI agents. Survives compaction, enables collaboration, provides complete traceability.

Integrated with SERENA MCP memory bank for project-level context and large document storage beyond GitHub's limits.

FUNDAMENTAL PRINCIPLES (READ FIRST)

These principles are non-negotiable. Violating them corrupts the entire workflow.

1. THE SACRED ORDER: One Branch, One Phase at a Time

Each branch goes through phases in strict circular order:

DEV ───► TEST ───► REVIEW ───► DEV ───► ... (until REVIEW passes)
         │           │
         │           └─► PASS? → merge to main
         │
    Bug fixes ONLY (no structural changes, no new tests)

Critical Rules:

• ONE phase thread open at a time per branch
• Opening TEST = closing DEV
• Opening REVIEW = closing TEST
• REVIEW fail → back to DEV (NEVER to TEST)
• REVIEW pass → merge to main

2. NEW BUG REPORT = NEW BRANCH (ALWAYS)

When a bug report is posted as a new GitHub issue:

• ALWAYS create a NEW branch with NEW DEV → TEST → REVIEW cycle
• NEVER merge it into an existing review thread, even if related
• Mixing issues violates the Sacred Order

Exception: Comments posted directly IN an existing thread are handled within that thread.

3. RESPONSIBILITY BOUNDARIES

REVIEW handles ALL bug reports and quality evaluation. TEST only runs existing tests.

4. THE 3-STRIKE RULE FOR BUG REPORTS

When a bug report cannot be reproduced:

1. Strike 1: Politely ask for more details
2. Strike 2: Politely ask again with specific questions
3. Strike 3: Politely close as "cannot-reproduce"

ALWAYS be polite, even when closing. Thank the reporter for their effort.

5. EVERY CONTRIBUTION IS VALUED

• Never dismiss a contribution as "nitpick" or "pedantic"
• Verify everything, assume nothing
• If valid, thank the contributor regardless of size
• Reply respectfully even when rejecting

Terminology

Understanding the relationship between GitHub entities and workflow concepts:

Key insight: Every thread IS an issue. The terms describe the same GitHub entity from different perspectives:

• "Issue" emphasizes the GitHub container (the thing with a number like #201)
• "Thread" emphasizes the phase role (DEV, TEST, or REVIEW work)

Example: Issue #201 labeled phase:dev is the "DEV thread" for JWT authentication. When DEV completes, issue #201 closes and issue #202 (labeled phase:test) opens as the "TEST thread" for the same feature.

One thread per phase: Each phase (DEV, TEST, REVIEW) gets its own issue. When phase transitions occur, the old issue closes and a new issue opens with the new phase label.

Thread Naming Convention

All thread titles MUST follow this standard format:

Rules:

• Prefix with phase in brackets: [DEV], [TEST], [REVIEW]
• Include original issue number after prefix
• Keep description short (under 50 chars)
• For iterations after demotion, append iteration number

Thread Message Structure

Reference: See references/templates/issue-comment-format.md for detailed comment formatting templates with avatar URLs and examples.

CRITICAL: The first message (issue body) is an INDEX, not a changelog. Updates go in REPLIES.

First Message (Issue Body) = Living Index

The first message should contain:

First Message Template:

## Objective
<what this thread accomplishes>

## Scope
Files to modify:
- [ ] path/to/file1.ts
- [ ] path/to/file2.ts

Files NOT to modify:
- path/to/other.ts (belongs to #203)

## Progress Checklist
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3

## Key Contributions
| What | Where | By |
|------|-------|-----|
| Initial design | [#comment-1](#issuecomment-XXX) | @agent-1 |
| Implementation | [#comment-5](#issuecomment-YYY) | @agent-2 |

## Artifacts
- PR: (pending)
- Test report: (pending)
- Documentation: (pending)

Replies = Chronological Updates

All work updates go in replies, NOT in edits to the first message:

## [Session N] 2025-01-15 14:30 UTC - @agent-name

### Work Completed
- Implemented validateToken function
- Added unit tests for edge cases

### Files Changed
| File | Changes |
|------|---------|
| src/auth/jwt.ts | +45 lines (new function) |

### Commits
- abc1234: Add JWT validation

### References
- Relates to decision in [#comment-3](#issuecomment-XXX)

### Next Action
Integrate with middleware

Every Change Gets a Reply

CRITICAL: Every action must be documented in a reply. The thread is the complete record of the endeavor - like a chat history. Subscribers must be able to follow along by reading replies.

Example - Completing a Task:

## Task Completed

Marked `[x] Implement validateToken function` in the index.

### What Was Done
- Added validateToken() to src/auth/jwt.ts
- Handles RS256 signature verification
- Returns decoded payload or throws AuthError

### Commit
- abc1234: Add JWT token validation

### Next
Proceeding to integrate with middleware.

Golden Rule: The thread is the single source of truth. Every change, including index edits, gets announced in a reply so subscribers can follow along.

Prerequisites and Tools

Required Tools

Required: SERENA MCP

SERENA MCP is required for large document storage and project memory. Without it, agents cannot store documents exceeding GitHub's 64KB limit or maintain project-level context.

SERENA MCP Installation

Step 1: Create Installation Script

Create install-serena.sh in the project root:

#!/bin/bash
# SERENA MCP Installation Script
set -e

PROJECT_DIR=$(pwd)
echo "Installing SERENA MCP for project: $PROJECT_DIR"
echo ""

# Step 1: Add SERENA MCP server to Claude Code
echo "[1/4] Adding SERENA MCP server..."
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project "$PROJECT_DIR"
echo "✓ Complete"
echo ""

# Step 2: Create SERENA project configuration
echo "[2/4] Creating SERENA project configuration..."
echo "Supported: csharp, python, rust, java, kotlin, typescript, go, ruby, dart, cpp, php, r, perl, clojure, elixir, elm, terraform, swift, bash, zig, lua, nix, erlang, al, rego, scala, julia, fortran, haskell, markdown, yaml"
echo ""
read -p "Enter languages to index (space-separated): " languages

lang_flags=""
for lang in $languages; do
    lang_flags="$lang_flags --language $lang"
done

uvx --from git+https://github.com/oraios/serena serena project create $lang_flags
echo "✓ Complete"
echo ""

# Step 3: Index the project codebase
echo "[3/4] Indexing project codebase..."
uvx --from git+https://github.com/oraios/serena serena project index
echo "✓ Complete"
echo ""

echo "=========================================="
echo "Installation Complete!"
echo "=========================================="
echo ""
echo "Next steps:"
echo "1. RESTART Claude Code"
echo "2. After restart, tell Claude: 'Activate the current dir as project using serena mcp'"
echo ""

Step 2: Run Installation

chmod +x install-serena.sh
# Exit Claude Code first!
./install-serena.sh
# Restart Claude Code

Step 3: Activate SERENA

After restarting Claude Code, tell Claude:

Activate the current dir as project using serena mcp

Verify Installation

# Check all tools are available
gh --version && git --version && jq --version

# Verify GitHub authentication
gh auth status

# Verify SERENA is active (after activation)
# The mcp__serena__* tools should be available

MANDATORY: Git Worktrees for All Phase Work

Why Worktrees Are REQUIRED

CRITICAL: ALL phase work (DEV, TEST, REVIEW) MUST happen in isolated git worktrees. Working on main is FORBIDDEN.

When multiple agents work on different phases (DEV, TEST, REVIEW), they need separate working directories to avoid conflicts. Git worktrees allow multiple checkouts from a single repository.

Problem without worktrees:

Agent-1 (DEV): Working on feature/auth branch
Agent-2 (TEST): Needs to checkout testing/auth branch
→ CONFLICT: Only one branch can be checked out at a time

Solution with worktrees:

main-repo/           ← Main repository (can be on main branch)
├── .git/
└── worktrees/
    ├── dev-auth/    ← DEV thread: feature/auth branch
    ├── test-auth/   ← TEST thread: testing/auth branch
    └── review-auth/ ← REVIEW thread: review/auth branch

Worktree Setup for Threads

Standard Worktree Location: ../ghe-worktrees/issue-{N}/

ISSUE_NUM=<issue number>

# Step 1: Create worktree directory
mkdir -p ../ghe-worktrees

# Step 2: Create worktree with new branch
git worktree add ../ghe-worktrees/issue-${ISSUE_NUM} -b issue-${ISSUE_NUM} main

# Step 3: Switch to worktree
cd ../ghe-worktrees/issue-${ISSUE_NUM}

# Step 4: Verify branch
git branch --show-current  # Should output: issue-${ISSUE_NUM}

MANDATORY: Verify Worktree Before Any Work

Every agent MUST run this check before starting any work:

# Check current branch
CURRENT_BRANCH=$(git branch --show-current)

# BLOCK if on main
if [ "$CURRENT_BRANCH" == "main" ]; then
  echo "ERROR: Work on main is FORBIDDEN!"
  echo "Create worktree: git worktree add ../ghe-worktrees/issue-N -b issue-N main"
  exit 1
fi

# Verify we're in a worktree
if [ ! -f .git ]; then
  echo "WARNING: Not in a worktree. Should be in ../ghe-worktrees/issue-N/"
fi

echo "Phase work running in branch: $CURRENT_BRANCH"

Legacy Worktree Setup (Alternative)

# Initial setup: Create worktrees directory
mkdir -p worktrees

# Create worktree for DEV thread
git worktree add worktrees/dev-$FEATURE feature/$FEATURE

# Create worktree for TEST thread (after DEV completes)
git worktree add worktrees/test-$FEATURE testing/$FEATURE

# Create worktree for REVIEW thread (after TEST completes)
git worktree add worktrees/review-$FEATURE review/$FEATURE

# List all worktrees
git worktree list

# Remove worktree when phase is complete
git worktree remove worktrees/dev-$FEATURE

Branch Naming Convention

Worktree Commands for Agents

DEV Agent starting work:

ISSUE=201
SLUG="jwt-auth"
FEATURE="${ISSUE}-${SLUG}"

# Create feature branch and worktree
git checkout -b feature/$FEATURE main
git worktree add worktrees/dev-$FEATURE feature/$FEATURE

# Work in the worktree
cd worktrees/dev-$FEATURE
# ... do development work ...

TEST Agent claiming TEST thread:

# Verify DEV worktree is removed (phase complete)
git worktree list | grep dev-$FEATURE && echo "ERROR: DEV worktree still exists"

# Create testing branch from feature branch
git checkout feature/$FEATURE
git checkout -b testing/$FEATURE
git worktree add worktrees/test-$FEATURE testing/$FEATURE

# Work in TEST worktree
cd worktrees/test-$FEATURE
# ... run tests, fix bugs ...

REVIEW Agent starting review:

# Create review branch from testing branch
git checkout testing/$FEATURE
git checkout -b review/$FEATURE
git worktree add worktrees/review-$FEATURE review/$FEATURE

# Work in REVIEW worktree (read-only, no code changes)
cd worktrees/review-$FEATURE
# ... evaluate code ...

Worktree Lifecycle

Key insight: All phases (DEV, TEST, REVIEW) work in the SAME worktree/branch. The worktree is only removed after REVIEW PASS and successful merge to main.

Cleanup Commands

# Prune stale worktrees (after worktree directory deleted)
git worktree prune

# Force remove a worktree
git worktree remove --force worktrees/dev-$FEATURE

# List and clean all worktrees for a feature
for wt in dev test review; do
  git worktree remove worktrees/${wt}-$FEATURE 2>/dev/null
done

GHE_REPORTS Directory

Purpose

The GHE_REPORTS/ directory stores all REVIEW phase verdict reports. These reports:

• Document the quality evaluation process
• Travel with the code (committed to feature branch)
• Provide audit trail for approvals/rejections
• Merge with approved code or stay in rejected branches

Directory Location

project-root/
├── GHE_REPORTS/
│   ├── README.md
│   ├── issue-1-review.md
│   ├── issue-2-review.md
│   └── ...

Report Naming Convention

issue-{N}-review.md

Where {N} is the original issue number being reviewed.

Report Template

# REVIEW Report: Issue #{N}

## Metadata
- **Issue**: #{N} - {Title}
- **Reviewer**: {Agent/User}
- **Date**: {YYYY-MM-DD}
- **Branch**: issue-{N}

## Verdict: {PASS | FAIL}

## Requirements Checklist
- [x] Requirement 1
- [x] Requirement 2
- [ ] Requirement 3 (if FAIL)

## Code Quality Assessment

### Architecture
{Assessment}

### Testing
{Assessment}

### Security
{Assessment}

### Performance
{Assessment}

## Test Results Summary
| Suite | Passed | Failed | Coverage |
|-------|--------|--------|----------|
| Unit | X | Y | Z% |
| Integration | X | Y | Z% |

## Issues Found
{If FAIL: List all issues requiring attention}

## Reviewer Notes
{Any additional observations}

## Approval Status
{If PASS: Approved for merge}
{If FAIL: Requires return to DEV with issues listed above}

Report Timing (Critical)

IMPORTANT: Reviews are created BEFORE the merge decision:

1. Create report in feature branch (issue-{N})
2. Commit report to the feature branch
3. Push branch to remote
4. If PASS: Create PR, merge to main (report travels with code)
5. If FAIL: Report stays in rejected branch (doesn't pollute main)

Why Before Merge?

Decision: Save reviews in feature branch BEFORE merge. This ensures:

• Only approved code AND its review reach main
• Rejected code's review stays with the rejected branch
• Complete traceability of what was approved and why

REVIEW PASS Workflow with Report

ISSUE_NUM=<issue number>
REVIEW_DATE=$(date +%Y-%m-%d)

# 1. Verify in correct worktree
cd ../ghe-worktrees/issue-${ISSUE_NUM}

# 2. Create GHE_REPORTS directory if needed
mkdir -p GHE_REPORTS

# 3. Write review report
cat > GHE_REPORTS/issue-${ISSUE_NUM}-review.md << 'EOF'
# REVIEW Report: Issue #${ISSUE_NUM}
...
## Verdict: PASS
...
EOF

# 4. Commit the review
git add GHE_REPORTS/issue-${ISSUE_NUM}-review.md
git commit -m "Add REVIEW report for issue #${ISSUE_NUM} - PASS"

# 5. Push feature branch
git push origin issue-${ISSUE_NUM}

# 6. Create PR
gh pr create --title "Issue #${ISSUE_NUM} - Feature Implementation" \
  --body "Closes #${ISSUE_NUM}

## Review Report
See: GHE_REPORTS/issue-${ISSUE_NUM}-review.md

## Verdict: PASS"

# 7. Merge PR
gh pr merge --squash

# 8. Clean up worktree
cd ..
git worktree remove issue-${ISSUE_NUM}

Merge Coordination Protocol

The Problem: Parallel Agents Completing Simultaneously

When multiple agents finish REVIEW with PASS verdicts at similar times, they may all attempt to merge to main simultaneously. This creates:

1. Race Conditions: Two agents try to merge at the same moment
2. Merge Conflicts: Agent-B's merge fails because Agent-A just changed main
3. Cascading Failures: Failed merges require rebase, which invalidates the REVIEW PASS

The Critical Insight

REVIEW PASS (before rebase) ≠ REVIEW PASS (after rebase)

Why? Rebasing changes the code context. The code that was reviewed is NOT the same code after rebase. New conflicts may introduce bugs, logic changes, or break assumptions that led to PASS.

Therefore: Any rebase MUST be followed by re-running TEST validations before merge.

Pre-Merge Protocol (MANDATORY)

Before any merge to main, execute this protocol:

ISSUE_NUM=<issue number>
MAX_ATTEMPTS=3
attempt=0

while [ $attempt -lt $MAX_ATTEMPTS ]; do
    # Step 1: Fetch latest main
    git fetch origin main

    # Step 2: Check if behind main
    BEHIND=$(git rev-list --count HEAD..origin/main)

    if [ "$BEHIND" -eq 0 ]; then
        echo "Branch is up to date with main - safe to merge"
        break
    fi

    echo "Branch is $BEHIND commits behind main - rebasing..."

    # Step 3: Attempt rebase
    if ! git rebase origin/main; then
        git rebase --abort
        echo "REBASE CONFLICT: Manual resolution required"
        echo "DEMOTE TO DEV: Cannot auto-resolve conflicts"
        exit 1
    fi

    echo "Rebase successful - RE-RUNNING TEST validations..."

    # Step 4: RE-RUN TEST (CRITICAL - code context changed!)
    # Run project-specific tests here
    if ! ./run-tests.sh; then
        echo "TESTS FAILED after rebase"
        echo "DEMOTE TO DEV: Code no longer passes tests after rebase"
        exit 1
    fi

    # Step 5: Force push the rebased branch
    if ! git push origin issue-${ISSUE_NUM} --force-with-lease; then
        echo "Push failed - another change occurred, retrying..."
        attempt=$((attempt + 1))
        continue
    fi

    echo "Branch rebased and pushed successfully"
    break
done

if [ $attempt -ge $MAX_ATTEMPTS ]; then
    echo "DEMOTE TO DEV: Max rebase attempts ($MAX_ATTEMPTS) exceeded"
    echo "High contention detected - requires manual coordination"
    exit 1
fi

Merge Lock Mechanism (Optional - For High Contention)

For repositories with frequent parallel merges, use a lock mechanism:

# Check if merge lock exists
check_merge_lock() {
    gh issue list --label "merge:active" --state open --json number | jq '. | length'
}

# Wait for lock (with timeout)
wait_for_lock() {
    local timeout=900  # 15 minutes
    local start=$(date +%s)

    while [ $(check_merge_lock) -gt 0 ]; do
        local now=$(date +%s)
        local elapsed=$((now - start))

        if [ $elapsed -gt $timeout ]; then
            echo "Lock timeout exceeded - forcing lock release"
            release_stale_locks
            break
        fi

        echo "Merge in progress by another agent, waiting... ($elapsed/$timeout sec)"
        sleep 30
    done
}

# Acquire lock
acquire_lock() {
    gh issue edit $ISSUE_NUM --add-label "merge:active"
    echo "Merge lock acquired for issue #$ISSUE_NUM"
}

# Release lock
release_lock() {
    gh issue edit $ISSUE_NUM --remove-label "merge:active"
    echo "Merge lock released for issue #$ISSUE_NUM"
}

Priority: First-Come-First-Served (FCFS)

When multiple agents have REVIEW PASS:

1. Priority = REVIEW PASS timestamp (first to pass reviews, first to merge)
2. No cutting in line - later PASS waits for earlier PASS to merge
3. Timeout protection - if an agent holds lock > 15 min, lock is force-released

Merge Coordination Summary

Loop Prevention

• Max 3 rebase attempts per merge session
• After 3 failed attempts → DEMOTE TO DEV
• Prevents infinite rebase loops when main is highly active

Merge Anti-Patterns

Storage Tiering: Where to Store What

Agents need to store information at different scales and lifetimes. Use the appropriate tier:

Three-Tier Storage Hierarchy

Tier 1: TodoWrite (Transient)

When to use:

• Tracking current session tasks
• Local progress tracking
• Items that don't need to survive compaction
• Quick scratch notes

Characteristics:

• Lost on session end or compaction
• Fast to read/write
• No collaboration (single agent only)
• No external dependencies

Example:

[x] Read issue thread
[x] Verify branch exists
[ ] Fix bug in jwt.service.ts
[ ] Run tests
[ ] Post checkpoint

Tier 2: GitHub Elements (Persistent)

When to use:

• Checkpoints that must survive compaction
• Decisions that affect other agents
• State that needs collaboration
• Content < 64KB per comment

Characteristics:

• Permanent (survives everything)
• Collaborative (multiple agents can read/write)
• Ordered history preserved
• Has size limits (see below)

GitHub Limits:

When approaching limits:

## Checkpoint - Content Split Required

This checkpoint exceeds GitHub's 64KB limit.

### Summary (in GitHub)
<brief summary here>

### Full Content (in SERENA)
See SERENA memory: `checkpoint-201-session-5.md`

### Index
- Part 1: Test results (SERENA: test-results-201.md)
- Part 2: Coverage report (SERENA: coverage-201.md)
- Part 3: File changes (in this comment, below)

Tier 3: SERENA MCP Memory (Archive)

When to use:

• Documents > 60KB (leave 4KB buffer for GitHub)
• Large test reports
• Extensive code examples
• Reference documentation
• Multi-part documents
• Project-level context that spans multiple issues

Characteristics:

• No practical size limit
• Project-scoped (persists with project)
• Requires SERENA MCP setup
• Slightly slower access

Memory Bank File Structure

The .serena/memories/ folder contains structured files for different purposes:

File Purposes:

1. activeContext.md

   • Record details of currently ongoing tasks
   • Only record in-progress tasks
   • Move completed tasks to progress.md with summary

2. progress.md

   • Record project progress chronologically
   • Add summary when major tasks complete
   • Reverse chronological order (newest on top)

3. projectBrief.md

   • Overall project overview
   • Update when goals or scope change
   • Core features and objectives

4. techContext.md

   • Technical context and decisions
   • Libraries, architecture patterns
   • Decision rationale

5. dataflow.md

   • System data flow documentation
   • Input/output structure
   • Data transformation processes

6. test_results/

   • Store test reports and validation data
   • Phase-specific reports
   • Performance benchmarks

Issue-Specific vs Project-Level Memory

SERENA Memory Commands:

# Write a memory (from agent perspective, use MCP tools)
# Tool: mcp__serena__write_memory
# Parameters:
#   memory_file_name: "checkpoint-201-full.md"
#   content: "<full content>"

# Read a memory
# Tool: mcp__serena__read_memory
# Parameters:
#   memory_file_name: "checkpoint-201-full.md"

# List available memories
# Tool: mcp__serena__list_memories

# Edit a memory (regex replacement)
# Tool: mcp__serena__edit_memory
# Parameters:
#   memory_file_name: "checkpoint-201-full.md"
#   needle: "old text"
#   repl: "new text"
#   mode: "literal"

Document Splitting Protocol

When a document exceeds GitHub's 64KB limit:

Step 1: Create Index in GitHub

## Large Document: <Title>

### Summary
<2-3 sentence summary>

### Document Index
| Part | Content | Location |
|------|---------|----------|
| 1 | Executive Summary | This comment |
| 2 | Detailed Analysis | SERENA: `analysis-201-part2.md` |
| 3 | Test Results | SERENA: `test-results-201.md` |
| 4 | Recommendations | SERENA: `recommendations-201.md` |

### Part 1: Executive Summary
<content that fits in GitHub>

Step 2: Store Parts in SERENA

# For each part that doesn't fit:
mcp__serena__write_memory(
  memory_file_name="analysis-201-part2.md",
  content="## Part 2: Detailed Analysis\n\n<full content>"
)

Step 3: Cross-Reference

• GitHub comment references SERENA memories
• SERENA memories reference GitHub issue number
• Never more than ONE level of indirection

Decision Matrix: Which Tier?

Memory Bank Integration with Thread Lifecycle

The memory bank (.serena/memories/) is updated at specific points during the DEV → TEST → REVIEW cycle. This ensures project context stays synchronized with issue progress.

Thread Lifecycle → Memory Updates

Memory Update Workflow

After completing meaningful work, follow this sequence:

Step 1: Analyze Current Task

• What was completed?
• Were there technical decisions?
• Were there data flow changes?
• Are there test results?

Step 2: Determine Files to Update

Step 3: Update Each File

Use SERENA MCP tools:

# Read current content
mcp__serena__read_memory("activeContext.md")

# Edit with new content
mcp__serena__edit_memory(
  memory_file_name="activeContext.md",
  needle="## In Progress",
  repl="## In Progress\n\n### Issue #201 - JWT Authentication\n- Phase: DEV\n- Started: 2025-01-15\n- Scope: Implement JWT token validation",
  mode="literal"
)

Step 4: Verify No Duplication

• Same content should not appear in multiple files
• Each piece of information in the most appropriate file
• progress.md is reverse chronological (newest on top)

Phase-Specific Memory Operations

DEV Thread Start

# Update activeContext.md
mcp__serena__edit_memory(
  memory_file_name="activeContext.md",
  needle="## In Progress",
  repl="""## In Progress

### Issue #${ISSUE} - ${TITLE}
- **Phase**: DEV
- **Started**: ${DATE}
- **Branch**: feature/${ISSUE}-${SLUG}
- **Scope**: ${SCOPE_DESCRIPTION}

#### Objectives
- ${OBJECTIVE_1}
- ${OBJECTIVE_2}
""",
  mode="literal"
)

DEV Thread Complete

# 1. Read current active context
content = mcp__serena__read_memory("activeContext.md")

# 2. Move completed task to progress.md (prepend - newest first)
mcp__serena__edit_memory(
  memory_file_name="progress.md",
  needle="# Progress Log",
  repl="""# Progress Log

## ${DATE} - Issue #${ISSUE} DEV Complete
- **Feature**: ${TITLE}
- **Commits**: ${COMMIT_COUNT}
- **Files Changed**: ${FILE_COUNT}
- **Tests Written**: ${TEST_COUNT}
- **Status**: Ready for TEST

""",
  mode="literal"
)

# 3. Remove from activeContext.md
mcp__serena__edit_memory(
  memory_file_name="activeContext.md",
  needle="### Issue #${ISSUE}...(entire section)",
  repl="",
  mode="regex"
)

TEST Thread Complete

# 1. Save test results
mcp__serena__write_memory(
  memory_file_name="test_results/test-${ISSUE}-${DATE}.md",
  content="""# Test Results - Issue #${ISSUE}

## Summary
| Suite | Passed | Failed | Skipped |
|-------|--------|--------|---------|
| Unit | ${UNIT_PASS} | ${UNIT_FAIL} | 0 |
| Integration | ${INT_PASS} | ${INT_FAIL} | 0 |

## Coverage
- Statement: ${STATEMENT_COV}%
- Branch: ${BRANCH_COV}%

## Bugs Fixed
${BUG_LIST}
"""
)

# 2. Update progress.md
mcp__serena__edit_memory(
  memory_file_name="progress.md",
  needle="# Progress Log",
  repl="""# Progress Log

## ${DATE} - Issue #${ISSUE} TEST Complete
- **All tests pass**: YES
- **Coverage**: ${COVERAGE}%
- **Bugs fixed**: ${BUG_COUNT}
- **Status**: Ready for REVIEW

""",
  mode="literal"
)

REVIEW Thread Complete (PASS)

# Update progress.md with final status
mcp__serena__edit_memory(
  memory_file_name="progress.md",
  needle="# Progress Log",
  repl="""# Progress Log

## ${DATE} - Issue #${ISSUE} MERGED
- **Feature**: ${TITLE}
- **PR**: #${PR_NUMBER}
- **Review Verdict**: PASS
- **Merged to**: main
- **Total Cycle Time**: DEV(${DEV_SESSIONS}) → TEST(${TEST_SESSIONS}) → REVIEW(${REVIEW_SESSIONS})

""",
  mode="literal"
)

REVIEW Thread Complete (FAIL)

# 1. Update progress.md with demotion
mcp__serena__edit_memory(
  memory_file_name="progress.md",
  needle="# Progress Log",
  repl="""# Progress Log

## ${DATE} - Issue #${ISSUE} DEMOTED to DEV
- **Review Verdict**: FAIL
- **Reason**: ${FAILURE_REASON}
- **Issues Found**: ${ISSUE_COUNT}
- **Next**: DEV iteration required

""",
  mode="literal"
)

# 2. Add to activeContext.md for new DEV iteration
mcp__serena__edit_memory(
  memory_file_name="activeContext.md",
  needle="## In Progress",
  repl="""## In Progress

### Issue #${ISSUE} - ${TITLE} (Iteration ${N})
- **Phase**: DEV (demoted from REVIEW)
- **Demotion Date**: ${DATE}
- **Issues to Fix**:
  - ${ISSUE_1}
  - ${ISSUE_2}

""",
  mode="literal"
)

Memory Bank Activation Triggers

Update the memory bank when ANY of these events occur:

…(truncated)