---
name: github-elements-tracking
description: This skill should be used when the user asks to "track work across sessions", "create an epic", "manage issue waves", "post a checkpoint", "claim an issue", "recover from compaction", "coordinate multiple agents", "update memory bank", "store large documents", or mentions GitHub Issues as persistent memory, multi-session work, context survival, agent collaboration, SERENA MCP memory, or project-level context. Provides complete protocols for using GitHub Issues as permanent memory that survives context exhaustion, with integrated SERENA MCP memory bank for project-level context and large document storage.
---

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

| Setting | Effect on This Skill |
|---------|---------------------|
| `enabled` | If false, skip all GitHub Elements operations |
| `enforcement_level` | strict/standard/lenient - affects rule strictness |
| `serena_sync` | If false, skip SERENA memory bank integration |
| `auto_worktree` | If true, auto-create git worktree on claim |
| `checkpoint_interval_minutes` | Reminder interval for checkpoints |
| `notification_level` | verbose/normal/quiet output |

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

---

## Related GHE Skills

For specific operations, GHE provides specialized skills:

| Skill | Purpose |
|-------|---------|
| **ghe-requirements** | Create, version, and link requirements files. Use when starting features. |
| **ghe-changelog** | Maintain version history with git-diff. Track code, requirements, and design changes. |
| **ghe-status** | Check thread status and context |
| **ghe-claim** | Claim a thread for work |
| **ghe-checkpoint** | Post progress checkpoints |
| **ghe-transition** | Request phase transitions |
| **ghe-report** | Generate status reports |

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

| Agent | Handles Bug Reports? | Handles Test Writing? | Renders Verdicts? |
|-------|---------------------|----------------------|-------------------|
| **DEV** | NO (creates new branches for validated bugs) | YES | NO |
| **TEST** | NO (only runs existing tests) | NO | NO |
| **REVIEW** | YES (triages ALL bug reports) | NO | YES |

**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:

| Term | Definition |
|------|------------|
| **Issue** | A GitHub Issue - the container/ticket that holds all work history |
| **Thread** | A phase-specific issue. A "DEV thread" is an issue labeled `phase:dev` |
| **Comment** | A reply within an issue - holds checkpoints, decisions, work logs |
| **Element** | A comment containing Knowledge, Action, and/or Judgement facets |

**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:

| Thread Type | Title Format | Example |
|-------------|--------------|---------|
| **DEV** | `[DEV] #ISSUE - Short Description` | `[DEV] #201 - JWT Authentication` |
| **TEST** | `[TEST] #ISSUE - Short Description` | `[TEST] #201 - JWT Authentication` |
| **REVIEW** | `[REVIEW] #ISSUE - Short Description` | `[REVIEW] #201 - JWT Authentication` |
| **DEV (iteration)** | `[DEV] #ISSUE - Description (Iteration N)` | `[DEV] #201 - JWT Auth (Iteration 2)` |

**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](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:

| Section | Content | How to Update |
|---------|---------|---------------|
| **Objective** | What this thread accomplishes | Rarely changes |
| **Scope** | Files to modify, files NOT to modify | Add items, don't remove |
| **Checklist** | Tasks with checkboxes | Check boxes as completed, add new tasks |
| **Key References** | Links to significant replies | Add links as contributions arrive |
| **Artifacts** | Links to PRs, reports, docs, scripts | Add links when created |

**First Message Template:**
```markdown
## 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:

```markdown
## [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.

| Action | What to Do |
|--------|------------|
| Mark checkbox complete | 1. Edit first message to check box 2. **Post reply** explaining what was completed |
| Add new task to checklist | 1. Edit first message to add task 2. **Post reply** explaining why task was added |
| Add link to contribution | 1. Edit first message to add link 2. **Post reply** explaining the contribution |
| Add artifact link (PR, report) | 1. Edit first message to add link 2. **Post reply** announcing the artifact |
| Work progress | **Post reply** with details |
| Checkpoint | **Post reply** with state snapshot |
| Decision made | **Post reply** documenting decision and rationale |
| Blocker encountered | **Post reply** explaining blocker |
| Test results | **Post reply** with results |

**Example - Completing a Task:**

```markdown
## 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

| Tool | Purpose | Installation |
|------|---------|--------------|
| `gh` | GitHub CLI - all issue/PR operations | `brew install gh` then `gh auth login` |
| `git` | Version control, worktrees, branches | Usually pre-installed |
| `jq` | JSON parsing for `gh` command output | `brew install jq` |

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

```bash
#!/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**
```bash
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

```bash
# 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}/`

```bash
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:**

```bash
# 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)

```bash
# 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

| Thread Type | Branch Pattern | Example |
|-------------|----------------|---------|
| DEV | `feature/<issue>-<slug>` | `feature/201-jwt-auth` |
| TEST | `testing/<issue>-<slug>` | `testing/201-jwt-auth` |
| REVIEW | `review/<issue>-<slug>` | `review/201-jwt-auth` |

### Worktree Commands for Agents

**DEV Agent starting work:**
```bash
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:**
```bash
# 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:**
```bash
# 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

| Phase Transition | Worktree Action |
|------------------|-----------------|
| Claim DEV | `git worktree add ../ghe-worktrees/issue-N -b issue-N main` |
| DEV → TEST | Stay in same worktree (same branch) |
| TEST → REVIEW | Stay in same worktree (same branch) |
| REVIEW PASS | 1. Save review to `GHE_REPORTS/` 2. Commit 3. Create PR 4. Merge 5. Remove worktree |
| REVIEW FAIL | 1. Save review to `GHE_REPORTS/` 2. Commit 3. Stay in worktree 4. Back to DEV |

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

```bash
# 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/`