GitHub Elements Setup Command

This command creates .claude/ghe.local.md with project configuration.

CRITICAL: repo_path Is Sacred

The repo_path field is the MOST IMPORTANT setting. All agents, hooks, and scripts use this path to find:

• REQUIREMENTS/ - Feature specifications
• GHE_REPORTS/ - Agent reports (FLAT, no subfolders)
• GitHub labels, issues, branches

If repo_path is wrong, folders get created in the WRONG location.

The setup flow ensures repo_path is saved FIRST before any folder creation.

Core Principles

GHE follows these non-negotiable principles:

• No time, only order: Workflow is phase-gated (DEV->TEST->REVIEW), never time-gated
• Parallel agents: Multiple agents work simultaneously on different issues/branches
• SERENA integration: Memory bank sync is always enabled for context survival
• Auto worktrees: Always enabled - required for parallel agent isolation

Step 1: Detect Git Repositories

Find all git repositories in current directory and subdirectories:

# Find all .git directories (repos and submodules)
find . -name ".git" -type d 2>/dev/null | head -20

Parse the output to identify:

• Main repo (if .git exists in current directory)
• Sub-projects (nested .git directories)
• Submodules (.git files pointing to worktree)

For each found repo, get its remote URL:

git -C <repo-path> remote get-url origin 2>/dev/null

Step 2: Select Target Repository

If multiple repos found, ask user which one to configure:

{
  "questions": [
    {
      "question": "Which repository should GHE track?",
      "header": "Repository",
      "multiSelect": false,
      "options": [
        {"label": "<repo-name-1>", "description": "<remote-url-1>"},
        {"label": "<repo-name-2>", "description": "<remote-url-2>"}
      ]
    }
  ]
}

If only one repo found, use it automatically and inform user.

Step 3: Check Existing Configuration

Check if .claude/ghe.local.md already exists in the selected repo:

• If exists, read current settings and show them
• Ask if user wants to modify or keep current settings

Step 4: Configure Enforcement

The only meaningful user choice - how many warnings before blocking:

{
  "questions": [
    {
      "question": "Enable GHE workflow tracking for this repository?",
      "header": "Enable",
      "multiSelect": false,
      "options": [
        {"label": "Yes", "description": "Activate GHE with DEV->TEST->REVIEW workflow"},
        {"label": "No", "description": "Disable GHE for this repository"}
      ]
    },
    {
      "question": "How many warnings before enforcing phase rules?",
      "header": "Warnings",
      "multiSelect": false,
      "options": [
        {"label": "1 warning", "description": "Strict - block after first warning"},
        {"label": "3 warnings", "description": "Standard - progressive enforcement (recommended)"},
        {"label": "5 warnings", "description": "Lenient - more flexibility before blocking"}
      ]
    }
  ]
}

Step 5: Get Repository Owner

Get the GitHub username for the repo owner (used for PR assignments):

gh api user --jq '.login'

Step 6: Create Settings File

Create .claude/ directory in the selected repo if needed:

mkdir -p <repo-path>/.claude

Write settings file to <repo-path>/.claude/ghe.local.md:

---
# GHE Configuration - Auto-generated by /ghe:setup
enabled: true
repo_path: "<absolute-path-to-repo>"
repo_remote: "<github-remote-url>"

# Enforcement: progressive warnings before blocking
# After this many warnings, violations will block the action
warnings_before_enforce: 3
violation_count: 0

# Owner info (for PR assignments, not for reviews)
repo_owner: "<github-username>"

# Review is handled by Hera agent, not human reviewers
review_agent: "ghe:review-thread-manager"

# These are ALWAYS enabled - core to GHE functionality
serena_sync: true
auto_worktree: true
auto_transcribe: true

# Requirements settings
require_requirements: true        # Block DEV without requirements file
requirements_folder: REQUIREMENTS # Folder for REQ files
auto_serena_backup: true         # Backup requirements to SERENA

# Parallel processing
autonomous_mode: false           # Enable auto-dispatch
max_concurrent_dev: 3
max_concurrent_test: 2
max_concurrent_review: 2

# TDD enforcement
enforce_tdd: true               # Require tests before code
min_coverage: 80                # Minimum test coverage %

# Current tracking state
current_issue: null
current_phase: null
epic_label_prefix: "epic:"
---

# GHE Configuration

This repository is configured for GHE (GitHub-Elements) workflow tracking.

## Workflow

DEV --> TEST --> REVIEW --> (PASS) --> merge | v (FAIL) --> back to DEV

**Phases are ORDER-based, not time-based.** Work progresses through phases when criteria are met, not after time passes.

## Automatic Features

These are always enabled (core GHE functionality):

| Feature | Description |
|---------|-------------|
| **SERENA Sync** | Checkpoints auto-saved to `.serena/memories/` |
| **Auto Worktree** | Each issue gets isolated git worktree for parallel work |
| **Auto Transcribe** | All exchanges posted to issue thread |
| **Review Agent** | Hera (`ghe:review-thread-manager`) handles REVIEW phase |

## Enforcement

- **Warnings before block**: <N>
- **Current violations**: 0

After <N> warnings, phase violations will block the action until resolved.

## Commands

| Phrase | Action |
|--------|--------|
| "lets work on issue #123" | Claim and activate issue |
| "lets work on this new issue" | Create new issue and activate |
| "checkpoint" | Post progress to issue thread |
| "transition to TEST" | Move to next phase (if criteria met) |

## Agents

| Phase | Agent | Role |
|-------|-------|------|
| DEV | Hephaestus | Builds and shapes the work |
| TEST | Artemis | Runs tests, hunts bugs |
| REVIEW | Hera | Evaluates quality, renders verdict |
| Orchestrator | Athena | Coordinates workflow |

## Modifying Settings

Edit this file directly. Changes take effect on Claude Code restart.

To disable GHE: set `enabled: false` in frontmatter.
To re-run setup: `/ghe:setup`

Step 7: Create Required GitHub Labels

Create labels in the selected repository:

cd <repo-path>

# Phase labels
gh label create "phase:dev" --color "0E8A16" --description "Development phase" --force
gh label create "phase:test" --color "FBCA04" --description "Testing phase" --force
gh label create "phase:review" --color "1D76DB" --description "Review phase" --force

# Status labels
gh label create "ready" --color "C2E0C6" --description "Available for claiming" --force
gh label create "in-progress" --color "FEF2C0" --description "Work in progress" --force
gh label create "blocked" --color "D93F0B" --description "Has blocker" --force
gh label create "needs-input" --color "D4C5F9" --description "Waiting for input" --force

# Completion label
gh label create "completed" --color "0E8A16" --description "Review passed - merged" --force

# Violation labels
gh label create "violation:phase" --color "B60205" --description "Phase order violation" --force
gh label create "violation:scope" --color "B60205" --description "Scope violation" --force

# CI labels
gh label create "ci-failure" --color "D93F0B" --description "CI/CD failure" --force
gh label create "source:ci" --color "C5DEF5" --description "Auto-created from CI" --force

# Epic label
gh label create "epic" --color "5319E7" --description "Epic thread - orchestrates WAVES" --force

echo "GitHub Elements labels created."

Step 7.5: Create Required Folder Structure

Create the REQUIREMENTS and GHE_REPORTS folders in the target repository:

# CRITICAL: Change to the selected repository first!
cd <repo-path>

# Create REQUIREMENTS folder structure
echo "Creating REQUIREMENTS folder structure in <repo-path>..."
mkdir -p REQUIREMENTS/_templates
mkdir -p REQUIREMENTS/standalone

# Create GHE_REPORTS folder (FLAT structure, no subfolders!)
echo "Creating GHE_REPORTS folder in <repo-path>..."
mkdir -p GHE_REPORTS

# Copy template if not exists
if [ ! -f "REQUIREMENTS/_templates/REQ-TEMPLATE.md" ]; then
  cat > "REQUIREMENTS/_templates/REQ-TEMPLATE.md" << 'TEMPLATE_EOF'
---
req_id: REQ-XXX
version: 1.0.0
status: draft
created: $(date +%Y-%m-%d)
updated: $(date +%Y-%m-%d)
epic: null
wave: null
linked_issues: []
author: @$(gh api user --jq '.login')
---

# REQ-XXX: [Feature Name]

## 1. Overview
[Brief description]

## 2. User Story
**As a** [user type], **I want** [goal], **So that** [benefit].

## 3. Acceptance Criteria
- [ ] **AC-1**: [Criterion]
- [ ] **AC-2**: [Criterion]

## 4. Technical Requirements
### 4.1 Functional
- **FR-1**: [Requirement]

### 4.2 Non-Functional
- **NFR-1**: [Requirement]

## 5. Atomic Changes
1. **CHANGE-1**: [Description]

## 6. Test Requirements
- **TEST-1** for CHANGE-1: [Test description]

## 7. Dependencies
None.

## 8. Revision History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0.0 | $(date +%Y-%m-%d) | @author | Initial |
TEMPLATE_EOF
  echo "Created REQUIREMENTS template"
fi

# Create CHANGELOG if not exists
if [ ! -f "CHANGELOG.md" ]; then
  cat > "CHANGELOG.md" << 'CHANGELOG_EOF'
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Initial project setup

### Changed

### Deprecated

### Removed

### Fixed

### Security

### Requirements

### Design

CHANGELOG_EOF
  echo "Created CHANGELOG.md"
fi

# Create .gitkeep files to ensure folders are tracked in git
touch REQUIREMENTS/_templates/.gitkeep
touch REQUIREMENTS/standalone/.gitkeep
touch GHE_REPORTS/.gitkeep

echo "Folder structure created in <repo-path>:"
echo "  - REQUIREMENTS/"
echo "  - REQUIREMENTS/_templates/"
echo "  - REQUIREMENTS/standalone/"
echo "  - GHE_REPORTS/"

Step 8: Copy GHE Automation Workflows

Copy the GHE GitHub Action workflows to the user's repository. These workflows enable 24/7 automation via Argos Panoptes:

cd <repo-path>

# Create workflows directory if needed
mkdir -p .github/workflows

# Copy GHE automation workflows from plugin templates
# ${CLAUDE_PLUGIN_ROOT} points to plugins/ghe/ within the installed plugin
cp "${CLAUDE_PLUGIN_ROOT}/templates/workflows/ghe-"*.yml .github/workflows/

# Verify copy
echo "Copied GHE workflows:"
ls -la .github/workflows/ghe-*.yml

Workflows copied:

Workflow	Trigger	Function
ghe-bug-triage.yml	Issue opened with bug label	Validates bug reports for Hera
ghe-feature-triage.yml	Issue opened with enhancement label	Validates feature requests
ghe-pr-review.yml	PR opened	Creates REVIEW queue issue
ghe-ci-failure.yml	Workflow failed	Creates CI failure issue for Chronos
ghe-security-alert.yml	Dependabot alert	Creates security issue
ghe-spam-detection.yml	Issue/comment created	Detects obvious spam
ghe-moderation.yml	Comment created	Monitors for policy violations

Important: These workflows require the CLAUDE_CODE_OAUTH_TOKEN secret. The /install-github-app command will configure this automatically.

Step 8.5: Copy Avatar Assets (Optional)

For self-contained deployments, copy avatar images to user's repo:

cd <repo-path>

# Create assets directory
mkdir -p assets/ghe/avatars

# Copy avatar images from plugin
cp "${CLAUDE_PLUGIN_ROOT}/assets/avatars/"*.png assets/ghe/avatars/

# Verify copy
echo "Copied avatars:"
ls -la assets/ghe/avatars/

Note: Avatar images are also hosted at: https://raw.githubusercontent.com/Emasoft/ghe-marketplace/main/plugins/ghe/assets/avatars/

The workflows use the hosted URLs by default, so copying is optional. Copy only if you need offline/self-contained operation.

Step 9: Update .gitignore

Add local settings to gitignore (settings are per-machine):

cd <repo-path>
if ! grep -q ".claude/\*.local.md" .gitignore 2>/dev/null; then
  echo "" >> .gitignore
  echo "# GHE plugin settings (user-local, per-machine)" >> .gitignore
  echo ".claude/*.local.md" >> .gitignore
fi

Step 9: Confirm to User

Display summary:

GHE Setup Complete!

Repository: <repo-name>
Path: <repo-path>
Remote: <remote-url>

Configuration:
- Enabled: Yes
- Warnings before enforce: 3
- SERENA sync: Always on
- Auto worktree: Always on
- Review agent: Hera (ghe:review-thread-manager)

Folder Structure (in <repo-path>):
- REQUIREMENTS/: Feature specifications and design docs
- REQUIREMENTS/_templates/: REQ-TEMPLATE.md created
- GHE_REPORTS/: Agent reports (FLAT, no subfolders)
- CHANGELOG.md created

Requirements Management:
- Requirements required: Yes
- Auto SERENA backup: Yes

TDD Enforcement:
- Tests required before code: Yes
- Minimum coverage: 80%

Parallel Processing:
- Autonomous mode: Disabled
- Max concurrent DEV: 3
- Max concurrent TEST: 2
- Max concurrent REVIEW: 2

Labels created: dev, test, review, ready, in-progress,
               blocked, needs-input, completed,
               violation:phase, violation:scope, ci-failure, epic

Settings saved to: <repo-path>/.claude/ghe.local.md

Next steps:
1. Create requirements: Use REQUIREMENTS/_templates/REQ-TEMPLATE.md
2. Agent reports will be saved to: GHE_REPORTS/
3. Say "lets work on issue #123" to start tracking an issue
4. Or "lets work on this new issue" to create and track a new one

IMPORTANT: All paths are relative to <repo-path>
The plugin stores this path in .claude/ghe.local.md

Step 10: Claude GitHub Action Setup

Ask user if they want to enable Claude GitHub Action for @claude mentions:

{
  "questions": [
    {
      "question": "Enable Claude GitHub Action for @claude mentions in issues/PRs?",
      "header": "Claude Action",
      "multiSelect": false,
      "options": [
        {"label": "Yes", "description": "Recommended - enables @claude in issues and auto PR reviews"},
        {"label": "Skip", "description": "Can be set up later with /install-github-app"}
      ]
    }
  ]
}

If user selects "Yes", display:

Claude GitHub Action Setup
==========================

To enable @claude mentions in issues and PRs, you need to run
a special command that only YOU (the repo owner) can execute:

  /install-github-app https://github.com/<owner>/<repo>

This command will:
1. Guide you through GitHub App authentication
2. Create workflow files (.github/workflows/claude.yml)
3. Automatically configure secrets based on your subscription
4. Create a PR for you to review and merge

IMPORTANT: The assistant cannot run this command for you.
You must type it yourself in the chat.

After running the command:
1. Review the PR it creates
2. Merge the PR
3. @claude mentions will be active!

If user selects "Skip", display:

Skipping Claude GitHub Action setup.
You can enable it later by typing: /install-github-app <your-repo-url>

Error Handling

• If no git repos found: Tell user to initialize a repo first
• If gh CLI not authenticated: Tell user to run gh auth login
• If label creation fails: Continue setup, warn user to create labels manually
• If user cancels: Don't create partial settings file