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:
5. Stop immediately
6. Explain the potential issue clearly
7. Wait for user guidance before proceeding
8. 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