start

What this skill does

# Start - Session Initialization and Context Compilation

Run the initialization script and prepare for a new coding session.

## Phase 0: Auto-Migration (Legacy Files)

Before anything else, check if legacy root-level harness files need migration:

1. Check if any of these files exist in the project root:
   - `feature-list.json`
   - `feature-archive.json`
   - `claude-progress.json`
   - `working-context.json`
   - `agent-context.json`
   - `agent-memory.json`
   - `init.sh`

2. If any legacy files exist AND `.claude-harness/` directory does NOT exist:
   - Create `.claude-harness/` directory
   - Move each file to `.claude-harness/`:
     - `mv feature-list.json .claude-harness/`
     - `mv feature-archive.json .claude-harness/`
     - `mv claude-progress.json .claude-harness/`
     - `mv working-context.json .claude-harness/`
     - `mv agent-context.json .claude-harness/`
     - `mv agent-memory.json .claude-harness/`
     - `mv init.sh .claude-harness/`
   - Report to user: "Migrated harness files to .claude-harness/ directory"

3. If `.claude-harness/` already exists, check for feature file migration:
   - If `feature-list.json` OR `feature-archive.json` exist at root level:
     - Create `.claude-harness/features/` directory if needed: `mkdir -p .claude-harness/features/`
     - Migrate files with renaming:
       - `mv feature-list.json .claude-harness/features/active.json` (if exists)
       - `mv feature-archive.json .claude-harness/features/archive.json` (if exists)
     - Also check for old files in `.claude-harness/` root:
       - `mv .claude-harness/feature-list.json .claude-harness/features/active.json` (if exists)
       - `mv .claude-harness/feature-archive.json .claude-harness/features/archive.json` (if exists)
     - Report to user: "Migrated feature files to .claude-harness/features/ with updated names"

4. **Create missing state files** (for plugin updates):
   - Check if each required state file exists, create with defaults if missing:
   - `.claude-harness/memory/learned/rules.json` (if missing):
     - First create directory if needed: `mkdir -p .claude-harness/memory/learned`
     - Then create file with defaults:
     ```json
     {
       "version": 3,
       "lastUpdated": "{ISO timestamp}",
       "metadata": {
         "totalRules": 0,
         "projectSpecific": 0,
         "general": 0,
         "lastReflection": null
       },
       "rules": []
     }
     ```
   - Report: "Created missing state file: {filename}"

   - `.claude-harness/config.json` verification block (if missing `acceptance` key):
     - Read existing config.json
     - If `verification` object exists but has no `acceptance` key:
       - Add `"acceptance": ""` to the verification object
       - Write updated config.json back
     - Report: "Added acceptance test config (verification.acceptance) -- configure with your E2E test command"

   **Note**: Loop state and working context are now session-scoped and created at runtime in `.claude-harness/sessions/{session-id}/`. Legacy files at `.claude-harness/loop-state.json` and `.claude-harness/working-context.json` are no longer created.

## Phase 0.5: Set Paths

1. **Set path variables**:
   - `FEATURES_FILE=".claude-harness/features/active.json"`
   - `ARCHIVE_FILE=".claude-harness/features/archive.json"`
   - `MEMORY_DIR=".claude-harness/memory/"`
   - `SESSION_DIR=".claude-harness/sessions/{session-id}/"`

**Important**: All subsequent phases must use these path variables instead of hardcoded paths.

## Phase 1: Context Compilation (Memory System)

**Session ID**: The SessionStart hook automatically generates a unique session ID and creates a session directory at `.claude-harness/sessions/{session-id}/`. All session-specific state files should use this directory. The session ID is provided in the hook output as `sessionId` and `sessionDir`.

**OPTIMIZATION**: Read all memory layers IN PARALLEL for faster startup.

1. **Initialize session context**:
   - Get session directory from SessionStart hook output (`.claude-harness/sessions/{session-id}/`)
   - Get cached GitHub owner/repo from SessionStart hook output (`github.owner`, `github.repo`)
   - Clear/initialize session context file: `.claude-harness/sessions/{session-id}/context.json`

2. **Read all memory layers IN PARALLEL** (single message with multiple Read tool calls):
   - `${FEATURES_FILE}` (to identify active feature)
   - `${MEMORY_DIR}/procedural/failures.json`
   - `${MEMORY_DIR}/procedural/successes.json`
   - `${MEMORY_DIR}/episodic/decisions.json`
   - `${MEMORY_DIR}/learned/rules.json`

   **IMPORTANT**: Use parallel tool calls - do NOT read these files sequentially.
   This reduces context compilation time by 30-40%.

3. **Process memory data** (after all reads complete):
   - **Failures to avoid**:
     - If active feature exists, filter entries where `feature` matches or `files` overlap with `relatedFiles`
     - Extract top 5 most recent relevant failures
     - Add to `relevantMemory.avoidApproaches`

   - **Successful approaches**:
     - Filter entries for similar file patterns or feature types
     - Extract top 5 most relevant successes
     - Add to `relevantMemory.projectPatterns`

   - **Recent decisions**:
     - Get entries from last 7 days or last 20 entries (whichever is smaller)
     - Add to `relevantMemory.recentDecisions`

4. **Write compiled context** (to session-scoped path):
   - Update `.claude-harness/sessions/{session-id}/context.json`:
     ```json
     {
       "version": 3,
       "computedAt": "{ISO timestamp}",
       "sessionId": "{unique-id}",
       "github": {
         "owner": "{from SessionStart hook}",
         "repo": "{from SessionStart hook}"
       },
       "activeFeature": "{feature-id or null}",
       "relevantMemory": {
         "recentDecisions": [{...}],
         "projectPatterns": [{...}],
         "avoidApproaches": [{...}]
       },
       "currentTask": {
         "description": "{feature description}",
         "files": ["{relatedFiles}"],
         "acceptanceCriteria": ["{verification}"]
       },
       "compilationLog": ["Loaded N failures", "Loaded N successes", ...]
     }
     ```

6. **Display memory summary**:
   ```
   MEMORY CONTEXT COMPILED
   Recent decisions: {N} loaded
   Success patterns: {N} loaded
   Approaches to AVOID: {N} loaded
   ```

   If `avoidApproaches` has entries, display prominently:
   ```
   APPROACHES TO AVOID (from past failures)
   - {failure.approach} - {failure.rootCause}
   - {failure.approach} - {failure.rootCause}
   ```

## Phase 1.6: Load Learned Rules

6.5. **Process learned rules** (already read in parallel in step 2):
   - Use data from `${MEMORY_DIR}/learned/rules.json` (already loaded)
   - If file exists and has active rules (`rules` array with `active: true`):

   - Filter rules for current context:
     - If active feature exists, include rules where:
       - `applicability.always` is true, OR
       - `applicability.features` includes current feature, OR
       - `applicability.filePatterns` overlap with feature's `relatedFiles`
     - If no active feature, include all active rules

   - Add rules to working context:
     - Update `.claude-harness/sessions/{session-id}/context.json`:
       ```json
       {
         "relevantMemory": {
           "recentDecisions": [...],
           "projectPatterns": [...],
           "avoidApproaches": [...],
           "learnedRules": [
             {
               "id": "rule-001",
               "title": "Always use absolute imports",
               "description": "Use @/components/... not relative paths",
               "scope": "coding-style"
             }
           ]
         }
       }
       ```

   - Display learned rules if any exist:
     ```
     LEARNED RULES (from your corrections)
     - {rule.title}
     - {rule.title}
     - {rule.title}
     {N} rules active (auto-captured at checkpoint)
     ```

   - If no learned rules exist yet, skip this section (no output)

## Ph