| 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. Use when this capability is needed. |
| metadata | {"author":"emasoft"} |
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 agent 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
Examples:
20251206143000GMT+01_epic_15_wave_launched_(Athena).md20251206143022GMT+01_issue_42_dev_complete_(Hephaestus).md20251206150000GMT+01_issue_42_tests_passed_(Artemis).md20251206160000GMT+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:
- Use ghe-requirements to create REQ file
- Link requirements to DEV issue
- Use ghe-claim to claim the thread
- Follow TDD workflow from DEV manager
Tracking Changes:
- Use ghe-changelog after significant commits
- 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:
- Strike 1: Politely ask for more details
- Strike 2: Politely ask again with specific questions
- 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 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:
## 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.
| 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:
## 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:
#!/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
| 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:
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
| 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
# 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:
- Create report in feature branch (
issue-{N})
- Commit report to the feature branch
- Push branch to remote
- If PASS: Create PR, merge to main (report travels with code)
- If FAIL: Report stays in rejected branch (doesn't pollute main)
Why Before Merge?
| Timing | Pros | Cons |
|---|
| Before merge (in feature branch) | Report travels with code; rejected reports don't pollute main; complete audit trail | Requires commit before merge |
| After merge (in main) | Simpler workflow | Rejected reviews pollute main; breaks audit trail |
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:
- Race Conditions: Two agents try to merge at the same moment
- Merge Conflicts: Agent-B's merge fails because Agent-A just changed main
- 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:
- Priority = REVIEW PASS timestamp (first to pass reviews, first to merge)
- No cutting in line - later PASS waits for earlier PASS to merge
- Timeout protection - if an agent holds lock > 15 min, lock is force-released
Merge Coordination Summary
| Scenario | Action |
|---|
| Branch is up-to-date with main | Proceed to merge |
| Branch is behind main | Rebase → Re-run TEST → Then merge |
| Rebase has conflicts | DEMOTE TO DEV (cannot auto-resolve) |
| Tests fail after rebase | DEMOTE TO DEV (rebase broke something) |
| Max attempts exceeded | DEMOTE TO DEV (high contention) |
| Another merge in progress | Wait for lock release (max 15 min) |
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
| Anti-Pattern | Problem | Correct Approach |
|---|
| Merge without checking main | Creates merge conflicts | Always git fetch first |
| Skip TEST after rebase | Reviewed code ≠ merged code | RE-RUN TEST after ANY rebase |
| Force push without lease | Can overwrite others' work | Use --force-with-lease |
| Ignore rebase conflicts | Broken code reaches main | DEMOTE TO DEV on conflicts |
| No merge lock in high traffic | Race conditions | Use merge:active label |
| Hold merge lock indefinitely | Blocks other agents | 15 min timeout max |
| Retry forever on conflicts | Infinite loop | Max 3 attempts then demote |
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 | Tool | Lifetime | Size Limit | Use Case |
|---|
| 1. Transient | TodoWrite | Session only | ~50 items | Current task tracking, local state |
| 2. Persistent | GitHub Elements | Forever | 64KB/comment | Decisions, checkpoints, coordination |
| 3. Archive | SERENA MCP | Project lifetime | No practical limit | Large docs, reports, references |
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:
| Element | Limit | Notes |
|---|
| Issue/Comment body | 65,536 characters (64KB) | Hard limit, no exceptions |
| Issue title | 256 characters | Keep titles concise |
| Labels per issue | 50 | Use sparingly |
| API calls | 5,000/hour (authenticated) | Rarely a problem |
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 | Purpose | Update Timing |
|---|
activeContext.md | Currently ongoing tasks | Task start/progress |
progress.md | Completed work history | Task completion |
projectBrief.md | Project overview | Scope changes |
techContext.md | Technical decisions | Tech stack changes |
dataflow.md | System data flow | Data structure changes |
test_results/ | Test reports | After test runs |
File Purposes:
-
activeContext.md
- Record details of currently ongoing tasks
- Only record in-progress tasks
- Move completed tasks to
progress.md with summary
-
progress.md
- Record project progress chronologically
- Add summary when major tasks complete
- Reverse chronological order (newest on top)
-
projectBrief.md
- Overall project overview
- Update when goals or scope change
- Core features and objectives
-
techContext.md
- Technical context and decisions
- Libraries, architecture patterns
- Decision rationale
-
dataflow.md
- System data flow documentation
- Input/output structure
- Data transformation processes
-
test_results/
- Store test reports and validation data
- Phase-specific reports
- Performance benchmarks
Issue-Specific vs Project-Level Memory
| Memory Type | Storage | Naming Convention | Use Case |
|---|
| Project context | Standard files | activeContext.md, progress.md | Spans all issues |
| Issue-specific | Custom files | issue-201-checkpoint.md | Single issue data |
| Large documents | Custom files | report-201-full.md | Exceeds GitHub 64KB |
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?
| Question | Yes → Use | No → Next Question |
|---|
| Needed only this session? | TodoWrite | ↓ |
| Fits in 60KB? | GitHub Elements | ↓ |
| Larger than 60KB? | SERENA MCP | N/A |
| Question | Yes → Use | No → Use |
|---|
| Needs collaboration? | GitHub or SERENA | TodoWrite |
| Must survive compaction? | GitHub or SERENA | TodoWrite |
| Other agents need access? | GitHub or SERENA | TodoWrite |
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
| Thread Event | Memory Files to Update | Content |
|---|
| DEV claim | activeContext.md | Add: Issue #, scope, objectives |
| DEV checkpoint | activeContext.md | Update: progress, blockers |
| DEV decision | techContext.md | Add: technical decision + rationale |
| DEV architecture | dataflow.md | Update: data flow changes |
| DEV complete | progress.md, activeContext.md | Move task summary to progress |
| TEST start | activeContext.md | Add: TEST phase for issue # |
| TEST results | test_results/ | Save: test-<issue>-<date>.md |
| TEST complete | progress.md, activeContext.md | Move test summary to progress |
| REVIEW complete | progress.md | Add: REVIEW verdict, merge status |
| REVIEW fail | activeContext.md | Add: DEV iteration with issues to fix |
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
| Work Type | Memory Files |
|---|
| New feature work | progress.md |
| Tech stack changes | techContext.md |
| Data structure changes | dataflow.md, techContext.md |
| Test execution | test_results/ |
| Project scope changes | projectBrief.md |
| Task in progress | activeContext.md |
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:
| Trigger | Memory Update Required |
|---|
| Thread claimed | activeContext.md |
| Checkpoint posted | Consider activeContext.md |
| Technical decision made | techContext.md |
| Architecture changed | dataflow.md |
| Thread closed | progress.md, activeContext.md |
| Tests executed | test_results/ |
| Feature merged | progress.md |
| Project scope changed | projectBrief.md |
Preventing Information Duplication
Before updating any memory file:
-
Check if content already exists
mcp__serena__read_memory("progress.md")
# Search for issue number to avoid duplicates
-
Place information in ONE file only
- Technical decisions →
techContext.md (not progress.md)
- Completed work summary →
progress.md (not activeContext.md)
- Current work →
activeContext.md (move to progress.md when done)
-
Use cross-references, not copies
## Issue #201 Complete
See test results: test_results/test-201-2025-01-15.md
See technical decisions: techContext.md (JWT section)
Agent Resource Access
Each agent type needs access to specific resources. Verify access before starting work.
DEV Agent Resources
| Resource | How to Access | Verify Command |
|---|
| Issue thread | gh issue view $ISSUE --comments | Should return issue content |
| Git repository | git status | Should show repo status |
| Feature branch | git checkout feature/$FEATURE | Should switch branches |
| DEV worktree | cd worktrees/dev-$FEATURE | Directory should exist |
| SERENA memories | mcp__serena__list_memories | Should list memories |
Memory Bank Operations (DEV):
| When | Memory File | Operation |
|---|
| Claim issue | activeContext.md | Add issue entry |
| Make tech decision | techContext.md | Document decision + rationale |
| Change architecture | dataflow.md | Update data flow |
| Complete DEV | progress.md | Move from active to progress |
TEST Agent Resources
| Resource | How to Access | Verify Command |
|---|
| TEST thread | gh issue view $TEST_ISSUE --comments | Should return issue content |
| DEV thread (read) | gh issue view $DEV_ISSUE --comments | Need to read DEV decisions |
| Testing branch | git checkout testing/$FEATURE | Should switch branches |
| TEST worktree | cd worktrees/test-$FEATURE | Directory should exist |
| Test framework | npm test or pytest | Should run tests |
| SERENA memories | mcp__serena__list_memories | Should list memories |
Memory Bank Operations (TEST):
| When | Memory File | Operation |
|---|
| Start TEST | activeContext.md | Update phase to TEST |
| Run tests | test_results/ | Save test report |
| Complete TEST | progress.md | Add test summary |
REVIEW Agent Resources
| Resource | How to Access | Verify Command |
|---|
| REVIEW thread | gh issue view $REVIEW_ISSUE --comments | Should return issue content |
| DEV thread (read) | gh issue view $DEV_ISSUE --comments | Understand what was built |
| TEST thread (read) | gh issue view $TEST_ISSUE --comments | Verify tests passed |
| Review branch | git checkout review/$FEATURE | Should switch branches |
| REVIEW worktree | cd worktrees/review-$FEATURE | Directory should exist |
| Coverage tools | npm run coverage | Should generate coverage |
| SERENA memories | mcp__serena__list_memories | Should list memories |
Memory Bank Operations (REVIEW):
| When | Memory File | Operation |
|---|
| PASS verdict | progress.md | Add merge record |
| FAIL verdict | progress.md, activeContext.md | Add demotion + new DEV iteration |
Access Verification Script
Run before starting any thread work:
#!/bin/bash
# verify-agent-access.sh
ISSUE=$1
FEATURE=$2
THREAD_TYPE=$3 # dev, test, or review
echo "Verifying $THREAD_TYPE agent access for issue #$ISSUE..."
echo ""
# Check GitHub access
echo -n "[1/5] GitHub CLI: "
gh issue view $ISSUE > /dev/null 2>&1 && echo "✓ OK" || echo "✗ FAIL"
# Check Git access
echo -n "[2/5] Git repository: "
git status > /dev/null 2>&1 && echo "✓ OK" || echo "✗ FAIL"
# Check worktree
WORKTREE="worktrees/${THREAD_TYPE}-${FEATURE}"
echo -n "[3/5] Worktree ($WORKTREE): "
[ -d "$WORKTREE" ] && echo "✓ OK" || echo "✗ MISSING"
# Check SERENA memories directory
echo -n "[4/5] SERENA memories: "
[ -d ".serena/memories" ] && echo "✓ OK" || echo "✗ MISSING (run SERENA setup)"
# Check required memory files
echo -n "[5/5] Memory bank files: "
MISSING=""
[ ! -f ".serena/memories/activeContext.md" ] && MISSING="$MISSING activeContext.md"
[ ! -f ".serena/memories/progress.md" ] && MISSING="$MISSING progress.md"
[ ! -f ".serena/memories/techContext.md" ] && MISSING="$MISSING techContext.md"
[ -z "$MISSING" ] && echo "✓ OK" || echo "✗ MISSING:$MISSING"
echo ""
echo "Verification complete."
Memory Bank Initialization
If memory bank files don't exist, initialize them:
# Initialize memory bank structure
mkdir -p .serena/memories/test_results
# Create activeContext.md
cat > .serena/memories/activeContext.md << 'EOF'
# Active Context
## In Progress
<!-- Current tasks go here -->
EOF
# Create progress.md
cat > .serena/memories/progress.md << 'EOF'
# Progress Log
<!-- Completed work entries go here, newest first -->
EOF
# Create techContext.md
cat > .serena/memories/techContext.md << 'EOF'
# Technical Context
## Tech Stack
<!-- Libraries, frameworks, tools -->
## Architecture Decisions
<!-- Decision records with rationale -->
EOF
# Create dataflow.md
cat > .serena/memories/dataflow.md << 'EOF'
# Data Flow
## System Overview
<!-- Data flow diagrams and descriptions -->
EOF
# Create projectBrief.md
cat > .serena/memories/projectBrief.md << 'EOF'
# Project Brief
## Overview
<!-- Project description and goals -->
## Core Features
<!-- Main features and objectives -->
EOF
Core Philosophy
Order matters. Time does not.
- ETA is always "when it's done"
- Issues are not tickets with urgency levels
- Waves are ordered checklists, not kanban boards
- Messages can be answered 10 years later - order preserved, timing irrelevant
- Strict sequence: each step must complete before the next begins
Quick Start: Select the Appropriate Playbook
Recovering from Compaction
Follow the recovery protocol: P4-compaction-recovery-walkthrough.md
Multiple Agents Working Together
Coordination protocols: P5-multi-instance-protocol.md
Thread Types and Phase Gates
Two Levels of Order
| Level | What | Order |
|---|
| Threads/Issues | DEV, TEST, REVIEW | ORDERED (circular sequence) |
| Elements inside threads | KNOWLEDGE, ACTION, JUDGEMENT | UNORDERED (any order) |
Threads follow strict sequence. Comments within threads can mix knowledge, action, and judgement freely.
Thread Types
| Thread Type | Purpose | ALLOWED | NOT ALLOWED |
|---|
| Dev Thread | Development work | Code, structural changes, DESIGN & WRITE TESTS | Definitive verdicts, final reviews, PASS/FAIL |
| Test Thread | Run tests & bug fixes | RUN tests, bug reports, bug fixes only | Writing new tests, structural changes, rewrites |
| Review Thread | Evaluation & verdicts | Verdicts, PASS/FAIL, ESTIMATE COVERAGE | New development, writing tests |
Key insight: Tests are CODE. Writing tests is DEVELOPMENT. TEST threads only RUN existing tests.
Circular Phase Order
┌──────────────────────────────────────────────┐
│ │
▼ │
DEV THREAD ───► TEST THREAD ───► REVIEW THREAD ───┘
│ │ │
│ │ ▼
│ │ PASS? → main/close
│ │ │
│ │ FAIL? ──┘ (back to DEV)
│ │
│ Bug fixes only
│ (NO structural changes)
│
New features,
structural changes,
rewrites
Key Rules:
- ONE thread open at a time per feature/solution
- Opening DEV = closing REVIEW (if returning from review)
- TEST can only fix bugs, NOT rewrite functionality
- Review decides if rewrite needed → demotes to DEV (never to TEST)
- Cycle repeats until REVIEW passes
Demotion Rules
| From | Can Demote To | What Happens |
|---|
| REVIEW | DEV only | Review thread closes, dev thread reopens |
| REVIEW | TEST | NEVER - changes need dev first |
| TEST | DEV | If bugs reveal structural issues |
Why Review → DEV only? Because fixing issues found in review requires development work. Testing validates existing code; it cannot create structural fixes. Only after DEV completes the fixes can TEST validate them again.
PR Branch Flow
feature branch ──► testing branch ──► review branch ──► main
│ │ │
│ │ ▼
│ │ PASS? → merge to main
│ │ │
│ │ FAIL? ──┴──► demote to feature branch
│ │ (back to DEV thread)
│ Bug fixes only
│ (test thread)
│
Development work
(dev thread)
Self-approval is NOT allowed. "I tested it myself" and "I reviewed my own code" are phase bypasses.
Thread Lifecycle Mechanics
Each thread (DEV, TEST, REVIEW) is a separate GitHub issue with the appropriate phase: label. Here's how threads transition:
Thread Creation
| When | Action |
|---|
| New feature starts | Create DEV issue with phase:dev label |
| DEV completes | Close DEV issue, create TEST issue with phase:test label |
| TEST completes | Close TEST issue, create REVIEW issue with phase:review label |
Thread Transitions
# DEV → TEST (DEV work complete)
gh issue close $DEV_ISSUE
gh issue create --title "Feature X - TEST" \
--label "phase:test" --label "in-progress" --label "epic:$EPIC" \
--body "TEST thread for Feature X.
Source DEV thread: #$DEV_ISSUE
Linked PR: #$PR_NUMBER"
# TEST → REVIEW (all tests pass)
gh issue close $TEST_ISSUE
gh issue create --title "Feature X - REVIEW" \
--label "phase:review" --label "in-progress" --label "epic:$EPIC" \
--body "REVIEW thread for Feature X.
Source DEV thread: #$DEV_ISSUE
Source TEST thread: #$TEST_ISSUE"
# REVIEW → DEV (demotion - REVIEW fails)
gh issue close $REVIEW_ISSUE
gh issue reopen $DEV_ISSUE # Or create new DEV iteration
gh issue edit $DEV_ISSUE --add-label "in-progress"
gh issue comment $DEV_ISSUE --body "Demoted from REVIEW #$REVIEW_ISSUE. Issues: ..."
# REVIEW → main (PASS - merge and close)
gh pr merge $PR_NUMBER --squash
gh issue close $REVIEW_ISSUE --comment "PASS - merged to main"
Thread States
| Issue State | Label State | Meaning |
|---|
| OPEN | in-progress | Active work happening |
| OPEN | needs-input | Blocked, waiting for decision |
| CLOSED | phase:dev | DEV phase complete |
| CLOSED | phase:test | TEST phase complete |
| CLOSED | completed | REVIEW passed, merged |
| CLOSED | phase:dev | REVIEW failed, back to DEV |
Critical Rule: One Thread At A Time
At any moment, only ONE thread (DEV, TEST, or REVIEW) should be OPEN for a feature:
# Check for violations (should return at most 1 result)
gh issue list --label "epic:$EPIC" --state open --json number,labels | \
jq '[.[] | select(.labels[].name | startswith("phase:"))]'
If this returns more than one issue, there's a phase order violation.
Thread Initialization
Every new thread MUST declare required skills:
## Thread: <Title>
### Required Skills
Agents participating in this thread should activate:
- `skill-name-1` - <why needed>
- `skill-name-2` - <why needed>
### Thread Type
<dev | test | review>
### Scope
<what this thread covers>
Epic Threads (Meta-Level)
Epic threads follow the same circular order but operate on batches:
| Epic Thread Type | Purpose |
|---|
| Epic DEV Thread | Development of a batch of issue solutions |
| Epic TEST Thread | Testing of a batch of issue solutions |
| Epic REVIEW Thread | Review of a batch of issue solutions |
Same rules apply: one epic thread open at a time, circular demotion to DEV, TEST for bug fixes only.
Core Protocol Summary
Session Start
# Find active work
gh issue list --assignee @me --label "in-progress"
# If found: read thread, inherit state, post resumption comment
# If empty: claim new issue from "ready" queue
During Session
- Checkpoint at each meaningful state change (milestone completed, blocker hit, decision made)
- Post State Snapshot with: Completed, In Progress, Pending, Next Action
Session End
- Post final checkpoint with complete state
- Verify: "Recovery possible with ONLY this issue thread?" (all items = yes)
State Snapshot Format
Every checkpoint includes this structure:
## [Session N] DATE TIME UTC - @agent-id
### Work Log
- [HH:MM] Action taken
- [HH:MM] Decision made
### State Snapshot
#### Thread Type
<dev | test | review>
#### Completed
- [x] Finished task 1
- [x] Finished task 2
#### In Progress
- [ ] Current work
#### Pending
- [ ] Future task 1
- [ ] Future task 2
#### Blockers
- Description + resolver
#### Files Changed
| File | Changes |
|------|---------|
| path/to/file | +50 lines |
#### Commits
| Hash | Message |
|------|---------|
| abc1234 | Description |
#### Branch
`feature/issue-number-slug`
#### Next Action
Specific action for resumption
#### Scope Reminder (for TEST threads)
- I CAN: <allowed actions for this thread type>
- I CANNOT: <disallowed actions for this thread type>
Note: Thread Type is critical for recovery - agents must know which phase they're resuming into.
GitHub Elements vs TodoWrite Decision
| Condition | GitHub Elements | TodoWrite |
|---|
| Context needed in 2 weeks | Yes | No |
| Context may get compacted | Yes | No |
| Multiple contributors | Yes | No |
| Dependencies or blockers exist | Yes | No |
Default: Use GitHub Elements. Persistent memory without need is preferable to lost context.
Essential Commands
All coordination uses gh CLI only. No external scripts.
# Find active work
gh issue list --assignee @me --label "in-progress"
# Read issue with full history (order matters)
gh issue view 123 --comments
# Post checkpoint (at meaningful state changes)
gh issue comment 123 --body "## Checkpoint..."
# Claim new issue (strict sequence: claim → scope → work)
gh issue edit 123 --add-assignee @me --add-label "in-progress" --remove-label "ready"
# Mark needs input (waiting for decision/clarification)
gh issue edit 123 --add-label "needs-input"
# Input received, continue
gh issue edit 123 --remove-label "needs-input"
# Ready for review (after work complete)
gh issue edit 123 --remove-label "in-progress" --add-label "review-needed"
# Check wave completion
gh issue list --label "wave:1" --label "epic:200" --state open
# Wave complete when this returns empty
# Link PR to issue (closes issue when PR merges)
gh pr create --title "Fix #123 - Description" --body "Closes #123"
# Or add to existing PR
gh pr edit 456 --body "$(gh pr view 456 --json body --jq .body)
Closes #123"
PR-Issue Linking Best Practices
Always link PRs to their source issues for traceability:
| Method | Syntax | Effect |
|---|
| Auto-close on merge | Closes #123 in PR body | Issue closes when PR merges |
| Reference without close | Relates to #123 | Creates link, doesn't close |
| Multiple issues | Closes #123, closes #124 | Closes both on merge |
Include in PR body:
## Source Issue
Closes #123
## Thread Context
- DEV thread: #123
- Epic: #100
Query Optimization
Use activeContext.md as Index
Instead of searching all issues, check activeContext.md first for current work:
# SLOW: Search all issues
gh issue list --label "in-progress" --json number,title,body --limit 100
# FAST: Check SERENA memory for current context
# Use mcp__serena__read_memory("activeContext.md") first
# Only query GitHub for specific issue numbers found in activeContext
Efficient Thread Discovery
| Need | Efficient Query |
|---|
| My current work | gh issue list --assignee @me --label "in-progress" --json number |
| Specific epic issues | gh issue list --label "epic:123" --json number,title |
| Find specific issue | gh issue view 123 (direct lookup, no search) |
Batch Operations
When checking multiple issues, batch queries:
# SLOW: Query each issue separately
for issue in 101 102 103; do gh issue view $issue; done
# FAST: Single query with multiple numbers
gh issue list --json number,title,state | jq '.[] | select(.number | IN(101,102,103))'
Key Concepts
Element = Reply with Three Facets
Every issue reply contains:
- Knowledge: Decisions, plans, requirements
- Action: Code, commits, PRs
- Judgement: Reviews, test results, feedback
Epic = Meta-Issue with Waves
Epics coordinate sub-issues through three phases:
- Meta-Knowledge: Planning, architecture
- Meta-Action: Launch waves of implementation issues
- Meta-Judgement: Evaluation waves assess success
Wave = Sprint Equivalent
Waves mark the transition from planning to implementation:
- All issues in a wave run in parallel
- Wave completes when all issues close
- Evaluation wave gates the next wave
The House Analogy: Waves are like floors of a house. You cannot build the second floor while the first floor has missing walls. Wave N+1 cannot start until Wave N is 100% complete.
Wave 1: Foundation
┌─────────────────────────────┐
│ [x] A [x] B [x] C │ ← ALL must be complete
└─────────────────────────────┘
│
▼ ONLY THEN
Wave 2: First Floor
┌─────────────────────────────┐
│ [ ] D [ ] E │ ← Can start
└─────────────────────────────┘
No exceptions. "95% done" is not done. One incomplete issue blocks the entire next wave.
Labels
Status Labels
| Label | Meaning |
|---|
ready | Available for claiming |
in-progress | Being worked on |
needs-input | Waiting for external input (decision, clarification) |
review-needed | Ready for review |
wave:N | Part of wave N |
epic:N | Part of epic N |
completed | Review passed, issue closed |
Thread Type Labels
| Label | Meaning |
|---|
phase:dev | Development thread (no verdicts allowed) |
phase:test | Testing thread (no feature opinions allowed) |
phase:review | Review thread (verdicts allowed) |
Violation Labels
| Label | Meaning |
|---|
violation:phase | Posted verdict/opinion in wrong thread type |
violation:wave-order | Started Wave N+1 before Wave N complete |
violation:self-approval | Attempted to test/review own work |
violation:scope | Work started before scope declaration |
Note: No priority labels. No time-based labels. Order is determined by wave membership and dependencies documented in issue bodies.
Argos Panoptes Labels
Argos Panoptes is the 24/7 GitHub Actions automation that triages incoming work while agents are offline. Argos uses specific labels to queue work for the appropriate specialist agents.
Session Startup: Check Argos-Queued Work FIRST
When starting any session, check for Argos-queued work before handling existing in-progress threads:
# Find all Argos-queued work (ready for processing)
gh issue list --state open --label "ready" --json number,title,labels | \
jq -r '.[] | "\(.number): \(.title) [\(.labels | map(.name) | join(", "))]"'
# Priority order:
# 1. URGENT + security → Hephaestus (DEV) immediately
# 2. ci-failure → Chronos
# 3. needs-moderation → Ares (enforcement)
# 4. source:pr + review → Hera (REVIEW)
# 5. bug + review → Hera (REVIEW)
# 6. feature + dev → Hephaestus (DEV)
Argos Label Reference
| Label | Set By | Meaning | Route To |
|---|
ready | Argos | Validated, ready for work | Check phase label for specialist |
dev | Argos | Needs development work | Hephaestus (dev-thread-manager) |
review | Argos | Needs review/triage | Hera (review-thread-manager) |
source:pr | Argos | Originated from a PR | Hera (review-thread-manager) |
source:ci | Argos | Originated from CI failure | Chronos (ci-issue-opener) |
needs-info | Argos | Awaiting user response | Wait for response |
needs-moderation | Argos | Policy violation flagged | Ares (enforcement) |
urgent | Argos | High priority work | Handle immediately |
security | Argos | Security vulnerability | Hephaestus + urgent |
ci-failure | Argos | CI/CD workflow failed | Chronos |
bot-pr | Argos | PR from Dependabot | Hera (may auto-merge) |
blocked | Argos | Critical severity | Escalate to orchestrator |
feature / enhancement | Argos | Feature request validated | Hephaestus |
bug | Argos | Bug report validated | Hera |
Recognizing Argos Comments
Argos Panoptes signs all comments with its identity:
Argos Panoptes (The All-Seeing)
Avatar: ../../assets/avatars/argos.png
When you see an Argos comment, the issue has been triaged. Proceed with your phase-specific duties.
Argos Does NOT:
- Claim issues (only queues them)
- Post checkpoints (only triages)
- Transition phases (only labels)
- Write code (only validates)
- Render verdicts (only flags)
Argos queues. Specialists execute.
Safeguards System
GHE includes a comprehensive safeguards system to prevent errors and enable recovery.
Loading Safeguards
# Source at the beginning of any operation
source plugins/ghe/scripts/safeguards.sh
Available Functions
| Function | Purpose | When to Use |
|---|
pre_flight_check <issue> | All safety checks | Before starting any work |
verify_worktree_health <path> | Check worktree validity | Before worktree operations |
safe_worktree_cleanup <path> [force] | Safe removal | When cleaning up worktrees |
acquire_merge_lock_safe <issue> | Get lock with TTL | Before merge attempts |
release_merge_lock_safe <issue> | Release lock | After merge (always!) |
wait_for_merge_lock <issue> [timeout] | Wait for lock | When lock is held by others |
heartbeat_merge_lock <issue> | Keep lock alive | During long operations |
atomic_commit_push <branch> <msg> <files> | Safe commit+push | For critical commits |
reconcile_ghe_state | Fix state desync | On startup, after errors |
validate_with_retry <script> <file> | Validation with retries | For flaky validations |
recover_from_merge_crash <issue> | Crash recovery | After interruptions |
Configuration (Environment Variables)
| Variable | Default | Description |
|---|
LOCK_TTL | 900 | Lock timeout in seconds (15 min) |
MAX_RETRIES | 3 | Retry attempts for validation |
RETRY_DELAY | 2 | Seconds between retries |
GHE_WORKTREES_DIR | ../ghe-worktrees | Worktrees directory |
Pre-Flight Check Output
Running pre-flight checks for issue #123
==================================================
[1/6] Issue #123 status: OPEN
[2/6] Worktree exists: YES
[3/6] Worktree health: HEALTHY
[4/6] Branch check: issue-123
[5/6] Merge lock: FREE
[6/6] GitHub auth: OK
==================================================
All pre-flight checks passed
Recovery Procedures
Recovery: Crashed Merge Operation
If a merge was interrupted (agent crashed, network failure, etc.):
source plugins/ghe/scripts/safeguards.sh
# Automatic recovery
recover_from_merge_crash "$ISSUE_NUM"
# This will:
# 1. Release any held merge locks
# 2. Abort any in-progress rebase or merge
# 3. Reconcile ghe.local.md state
Recovery: Orphaned Worktree
If a worktree exists but its issue is closed:
source plugins/ghe/scripts/safeguards.sh
# Check and cleanup all orphaned worktrees
reconcile_ghe_state
# Or cleanup specific worktree
safe_worktree_cleanup "../ghe-worktrees/issue-123" true
Recovery: Stale Merge Lock
If a merge lock is held longer than TTL (15 min):
# The safeguards system automatically detects and releases stale locks
# Just attempt to acquire the lock normally:
acquire_merge_lock_safe "$ISSUE_NUM"
# If old lock is stale, it will be released automatically
Recovery: Corrupted Worktree
If worktree is in an invalid state (detached HEAD, missing .git, etc.):
source plugins/ghe/scripts/safeguards.sh
# Check health
if ! verify_worktree_health "../ghe-worktrees/issue-123"; then
echo "Worktree corrupted - recreating..."
# Force remove corrupted worktree
safe_worktree_cleanup "../ghe-worktrees/issue-123" true
# Recreate from main
git worktree add ../ghe-worktrees/issue-123 -b issue-123 main
fi
Recovery: State Desync
If ghe.local.md references closed issues or wrong phase:
source plugins/ghe/scripts/safeguards.sh
# Automatic reconciliation
reconcile_ghe_state ".claude/ghe.local.md"
Recovery Decision Matrix
| Symptom | Recovery Function |
|---|
| Worktree operations fail | verify_worktree_health → safe_worktree_cleanup |
| Merge lock stuck | acquire_merge_lock_safe (auto-releases stale) |
| ghe.local.md wrong issue | reconcile_ghe_state |
| Rebase left incomplete | recover_from_merge_crash |
| Push failed mid-operation | atomic_commit_push (rollback) |
| Validation flaky | validate_with_retry |
Startup Reconciliation
Run on every startup/session to ensure clean state:
source plugins/ghe/scripts/safeguards.sh
# Full state reconciliation
reconcile_ghe_state
# Prune any stale git worktrees
git worktree prune
Anti-Patterns
| Anti-Pattern | Problem | Correct Approach |
|---|
| Work without checkpoints | Context lost on compaction | Checkpoint at state changes |
| Skip scope declaration | File conflicts | Declare files on claim |
| Skip session end checkpoint | Recovery impossible | Always post final state |
| Vague "Next Action" | Cannot resume | Specific single action |
| Silent decisions | Coordination failure | Document in thread |
| Skip steps in sequence | Order violation | Complete each step before next |
| Start Wave N+1 before Wave N done | Dependency violation | All items in wave must complete first |
| Add urgency/priority labels | Philosophy violation | Order only, no urgency |
| Post verdict in dev thread | Phase violation | Wait for review thread |
| Skip testing phase | Order violation | Dev → Test → Review sequence |
| "I tested it myself" | Self-approval bypass | Independent tester required |
| "I reviewed my own code" | Self-approval bypass | Independent reviewer required |
| PR direct to main | Skip branch phases | feature → testing → review → main |
| Open thread without skills list | Coordination failure | Always list required skills first |
| Two threads open simultaneously | Order violation | Only ONE of DEV/TEST/REVIEW at a time |
| Demote REVIEW → TEST | Phase bypass | REVIEW always demotes to DEV (never TEST) |
| Structural changes in TEST | Scope violation | TEST = bug fixes only, demote to DEV |
| Rewrite in TEST thread | Scope violation | Only DEV can do rewrites |
| Write new tests in TEST thread | Scope violation |
Documentation Map
This map shows ALL available documentation. Read only what you need for your current situation.
Progressive Disclosure: Scan these situational titles. When you encounter a matching situation, read that reference.
When you are implementing features, writing tests, or doing structural work.
| What to do... | Read |
|---|
| ...if I don't understand the workflow approach | Core Philosophy |
| ...if I'm unsure which thread type applies | Thread Types and Phase Gates |
| ...if I'm wondering if two threads can be open at once | One Thread At A Time Rule |
| ...when a REVIEW just failed | Demotion Rules |
| ...when a new feature has no DEV thread yet | Thread Initialization Protocol |
| ...when I just started a new session | SESSION START PROTOCOL |
| ...if I don't know what work is assigned to me | Step 1: Find Your Work |
| ...if this is a continuation of previous work | Step 2: Resume Existing Work |
| ...when there's unclaimed work in the queue | Step 3: Claim New Work |
| ...if I made progress and wonder if a checkpoint is needed | Checkpoint Triggers |
| ...when I need to write a checkpoint | Checkpoint Format |
| ...if I can't continue without external input | Handling Need-Input Situations |
| ...when input I was waiting for just arrived | When Input Is Received |
| ...when I'm done working for now | SESSION END PROTOCOL |
| ...if a task is too complex for one issue | Creating Sub-Tasks |
| ...if another agent might be working on the same files | Scope Conflict Detection |
| ...when I need checkpoint templates | Templates |
When you are running existing tests and fixing simple bugs.
| What to do... | Read |
|---|
| ...if I don't understand what TEST is supposed to do | Core Philosophy |
| ...if I'm unsure what TEST can and cannot do | What You Can Do / What You CANNOT Do |
| ...if I'm about to start TEST but DEV might still be open | Phase Entry Verification |
| ...when there's TEST work available in the queue | Step 1: Find Available TEST Work |
| ...when a TEST thread is ready and unclaimed | TEST Thread Claiming |
| ...when tests need to be run | TEST Execution Protocol |
| ...when tests finished and results need documenting | Documenting Test Results |
| ...when a test failed | Bug Fix Protocol |
| ...if I fixed a bug but I'm unsure if it was allowed in TEST | Allowed Fixes |
| ...if a bug fix requires structural changes | Demotion Protocol |
| ...when all tests pass | TEST Completion Protocol |
| ...when I need to write a TEST checkpoint | Checkpoint Format |
| ...to avoid common TEST mistakes | Anti-Patterns |
When you are evaluating code, rendering verdicts, or triaging bug reports.
| What to do... | Read |
|---|
| ...if I don't understand what REVIEW's authority is | Core Philosophy |
| ...if I'm about to start REVIEW but TEST might still be open | Step 0: Verify Phase Order |
| ...when a REVIEW thread is ready and unclaimed | Step 1: Claim Review Issue |
| ...if I don't have context about what DEV and TEST did | Step 2: Gather Context |
| ...when I'm reviewing code and need a checklist | Code Review Checklist |
| ...when I'm checking for security issues | Security Audit Checklist |
| ...when I'm checking for performance issues | Performance Review Checklist |
| ...when I found issues and need to document them | Step 4: Document Findings |
| ...when no blocking issues were found | PASS Verdict |
| ...when blocking issues were found | FAIL Verdict / DEMOTION PROTOCOL |
| ...if I don't know if test coverage is sufficient | TEST COVERAGE ESTIMATION |
| ...when I'm looking for common coverage gaps | Common Coverage Gaps |
| ...if I found an issue but don't know its severity | Severity Definitions |
| ...if something is unclear and DEV needs to explain | Requesting Clarification |
| ...if an issue is beyond my authority | Escalating to Epic |
When you are planning, coordinating waves, or orchestrating multiple agents.
| What to do... | Read |
|---|
| ...if I don't understand epic-level coordination | Core Philosophy |
| ...when a large feature has no epic issue yet | Step 1: Create the Epic Issue |
| ...when an epic exists but has no plan | Step 2: Planning Session |
| ...when work needs to be broken into waves | Step 3: Define Waves |
| ...when a wave has no issues yet | Step 4: Create Wave Issues |
| ...when a wave is ready to start | Step 5: Post Wave Launch |
| ...when a wave is in progress | Step 6: Monitor Wave Progress |
| ...when an agent is blocked waiting for input | Step 7: Handle Input Requests |
| ...when all issues in a wave are closed | Step 8: Wave Completion |
| ...when a wave completed and needs evaluation | Step 9: Spawn Evaluation Issues |
| ...when verdicts arrived from evaluation | Step 11: Process Verdicts |
| ...when all waves completed and passed evaluation | Step 12: Close Epic |
| ...when a wave order violation was detected | Wave Order Violation Response |
When context was compacted and you need to resume work.
| What to do... | Read |
|---|
| ...if I don't understand recovery philosophy | Core Philosophy |
| ...when context was just compacted and I don't know my assignment | Step 1: Find Assigned Work |
| ...if I found my issue but don't know what was done | Step 2: Read the Issue |
| ...if I don't know if local git state matches the checkpoint | Step 3: Verify Local State |
| ...when local TodoWrite is empty after compaction | Step 4: Build Local TodoWrite |
| ...when I recovered and need to document it | Step 5: Post Recovery Comment |
| ...when recovery is complete | Step 6: Continue Work |
| ...when I'm recovering in a TEST thread | TEST Thread Recovery Scenario |
| ...when I'm recovering in a REVIEW thread | REVIEW Thread Recovery Scenario |
| ...when recovery revealed work is done and phase should change | Thread Transition During Recovery |
| ...to avoid common recovery mistakes | Anti-Patterns in Recovery |
When multiple agents work on the same project simultaneously.
| What to do... | Read |
|---|
| ...if I don't understand multi-agent challenges | The Challenge |
| ...when an issue is unclaimed and I want it | Protocol 1: Issue Claiming |
| ...when I claimed an issue and need to declare my scope | Protocol 2: Scope Declaration |
| ...if another agent might be working on the same files | Checking for Scope Conflicts |
| ...when a scope conflict was detected | Handling Scope Conflicts |
| ...when I'm done with an assignment and releasing it | Protocol 3: Assignment Management |
| ...when I made a decision that affects other agents | Protocol 4: Decision Broadcasting |
| ...when another agent broadcast a decision | Acknowledging Broadcasts |
| ...if merge conflicts might occur | Protocol 5: Merge Conflict Prevention |
| ...when multiple agents need the same resource | Protocol 6: Shared Resource Locking |
| ...when a PR is ready to merge | Protocol 7: PR Merge Flow |
| ...if I don't understand branch phase flow | The Branch Flow |
| ...when my self-approval was rejected | Self-Approval Rejection |
When you need to see the full DEV → TEST → REVIEW cycle in action.
| I want to see an example of... | Section |
|---|
| A DEV thread being created | Day 1, 09:00 - DEV Thread Created |
| An agent claiming a DEV thread | 09:15 - Agent-A Claims DEV Thread |
| A session end checkpoint | 12:30 - Session 1 End Checkpoint |
| DEV completing and TEST starting | 17:45 - DEV Complete, Ready for TEST |
| TEST thread execution | PHASE 2: TEST THREAD |
| Tests finding a bug | 18:30 - Tests Run, Bug Found |
| REVIEW failing and demoting to DEV | 11:30 - REVIEW Complete - FAIL |
| A second DEV iteration after demotion | PHASE 4: DEV THREAD (Second Iteration) |
| REVIEW passing and merging to main | PHASE 7: MERGE TO MAIN |
| What goes wrong when demotion goes to TEST | What If Demotion Went to TEST? (Anti-Pattern) |
When you need automated enforcement of workflow rules.
| What to do... | Read |
|---|
| ...when the project has no enforcement yet | Quick Setup Checklist |
| ...when required labels don't exist | Step 1: Create Required Labels |
| ...when issues are created without validation | Step 2: Issue Validation Workflow |
| ...when scope conflicts are not being detected | Step 3: Scope Conflict Detector |
