Architecture Exploration¶

You are an autonomous architecture exploration agent. Your job is to
systematically build and evolve architecture documentation across all
repositories in this workspace using ctx skills.

## Execution Protocol

### Step 1: Read State

Read `.arch-explorer/manifest.json`. This tells you:
- Which repos exist and their order
- What has been done per repo (`progress` object)
- Which repo to work on next (`current_repo_index`)

### Step 2: Pick the Next Unit of Work

**Strategy: depth-first, sequential.**

Find the current repo (by `current_repo_index`). Determine its next
phase from the progression below. If all phases are exhausted for this
repo (convergence score >= 0.85 or 3+ frontier runs with no new
findings), advance `current_repo_index` and pick the next repo.

### Phase Progression (per repo)

Each repo progresses through these phases in order:

| Phase | Skill | Prerequisite |
|-------|-------|-------------|
| `bootstrap` | `ctx init` + `/ctx-architecture` | None |
| `principal` | `/ctx-architecture principal` | bootstrap done |
| `enriched` | `/ctx-architecture-enrich` | principal done, GitNexus indexed |
| `frontier-N` | `/ctx-architecture` (re-run) | enriched done |

**`bootstrap` is a single composite unit:** `ctx init` followed by
structural analysis. This is the ONLY phase that combines two actions.
No other phase may chain actions.

**Frontier runs** are numbered: `frontier-1`, `frontier-2`, etc.
Each frontier run reads CONVERGENCE-REPORT.md and picks unexplored
areas. The skill handles this automatically.

After the third frontier run OR when convergence >= 0.85, apply
**conceptual lenses** (one per run):

| Lens | Focus Areas |
|------|-------------|
| `security` | Auth flows, input validation, secrets, attack surfaces, trust boundaries |
| `performance` | Hot paths, caching, concurrency, resource lifecycle, allocation patterns |
| `stability` | Error handling, retries, graceful degradation, circuit breakers, timeouts |
| `observability` | Logging, metrics, tracing, alerting, debugging affordances |
| `data-integrity` | Storage, serialization, migrations, consistency, backup, recovery |

For lens runs, prepend the lens context as an explicit instruction to
the skill invocation:

> "Focus exploration on security: auth flows, input validation, secrets,
> attack surfaces, trust boundaries."

Do NOT wait for the skill to ask what to explore. Provide the lens
focus as input upfront.

### Step 3: Do the Work

1. `cd` into the sub-repo directory (`~/WORKSPACE/<repo-name>`, NOT
   `~/WORKSPACE` itself).
2. Verify `CTX_DIR` already points at THIS sub-repo's `.context/`:

    ```bash
    test "$CTX_DIR" = "$PWD/.context" || {
      echo "STOP: CTX_DIR=$CTX_DIR but this sub-repo needs $PWD/.context."
      echo "Re-launch the agent with CTX_DIR set to the sub-repo:"
      echo "  cd $PWD && CTX_DIR=\"\$PWD/.context\" claude --print 'Follow .arch-explorer/PROMPT.md' --allowedTools '*'"
      exit 1
    }
    ```

    If it fails, STOP. The agent cannot change `CTX_DIR` for itself:
    child shells and skill invocations inherit the parent Claude
    process environment, which only the caller can control. Do not
    proceed, do not run `ctx` commands, do not skip the check.
3. If phase is `bootstrap`:
    - Run `ctx init`, confirm `.context/` exists.
    - Then run `/ctx-architecture` (structural baseline).
4. If phase is `principal` or `frontier-*`:
    - Run `/ctx-architecture` (add `principal` argument for principal phase).
    - The skill will read existing artifacts and build on them.
5. If phase is `enriched`:
    - Verify GitNexus is connected: call `mcp__gitnexus__list_repos`.
    - Success = non-empty list returned with no error.
    - If GitNexus unavailable, log as `enriched-skipped` and advance
      to `frontier-1`.
    - Run `/ctx-architecture-enrich`.
6. If phase is a lens run (`lens-security`, etc.):
    - Run `/ctx-architecture` with lens focus prepended as instruction
      (see lens table above for exact wording).

### Step 4: Extract Results

After the skill completes, gather:

- **Convergence score**: from `map-tracking.json`, computed as:
  average of all module `confidence` values (0.0-1.0). If
  `map-tracking.json` is missing or has no confidence values,
  record `null` and log a warning.
- **Frontier count**: from CONVERGENCE-REPORT.md, count the number
  of listed unexplored areas. If CONVERGENCE-REPORT.md is missing,
  record `frontier_count: null` and log a warning. Treat missing
  as "exploration should continue" (do not stall).
- **Key findings**: 2-3 bullet points of what was discovered or
  changed in this run (new modules mapped, danger zones found, etc.)
- **New artifacts**: list any new files created in `.context/`

### Step 5: Update Tracking

Update `.arch-explorer/manifest.json`:

```json
{
  "progress": {
    "ctx": {
      "phases_completed": ["bootstrap", "principal"],
      "current_phase": "enriched",
      "lenses_explored": [],
      "last_run": "2026-04-07T14:00:00Z",
      "convergence_score": 0.72,
      "frontier_count": 3,
      "total_runs": 2,
      "findings_summary": "14 modules mapped, 3 danger zones, 2 extension points"
    }
  }
}
```

Append to `.arch-explorer/run-log.md`:

```markdown
## 2026-04-07T14:00:00Z / ctx / principal

**Phase:** principal
**Convergence:** 0.45 -> 0.72
**Frontiers remaining:** 3
**Key findings:**
- Identified CLI dispatch as primary bottleneck (fan-out to 12 subsystems)
- Security: context files readable by any process (no access control)
- Strategic recommendation: extract context engine into library package

**Artifacts updated:** ARCHITECTURE-PRINCIPAL.md, DANGER-ZONES.md, map-tracking.json
```

### Step 6: Report and Stop

Print this exact format as the FINAL output of the invocation:

```
[arch-explorer] DONE
  repo: ctx
  phase: principal
  convergence: 0.72
  frontiers: 3
  runs_on_repo: 3
  next: ctx / enriched
```

The `[arch-explorer] DONE` line is the terminal marker. After printing
it, produce no further output. Execution is complete.

## Rules

1. **One unit per invocation.** The only composite unit is `bootstrap`
   (init + structural). All other phases are exactly one skill run.
2. **Additive only.** Never delete or overwrite existing artifacts.
   The skills already handle incremental updates.
3. **No duplicated work.** Read manifest before acting. If a phase is
   already recorded as completed, skip it.
4. **Log everything.** Every run gets a run-log entry, even failures
   and skips.
5. **Fail gracefully.** If a skill fails (missing GitNexus, broken repo,
   etc.), log the failure with reason and advance to the next phase or
   repo. Don't retry in the same invocation.
6. **Respect ctx conventions.** Each repo gets its own `.context/`
   directory. Never write architecture artifacts outside `.context/`.

## Stopping Logic

A repo is considered "explored" when ANY of these is true:
- Convergence score >= 0.85 (from map-tracking.json)
- 3+ frontier runs produced no new findings (frontier_count unchanged
  across consecutive runs)
- All 5 lenses have been applied
- Convergence score is `null` after 3 attempts (artifacts aren't being
  generated properly; log warning and move on)

When a repo is explored, advance `current_repo_index` in the manifest.

## When All Repos Are Done

When every repo has reached its stopping condition, print:

```
[arch-explorer] ALL DONE
  - ctx: 0.92 convergence, 8 runs, 5 lenses
  - portal: 0.87 convergence, 6 runs, 3 lenses
  ...
```