# Extension Architecture Decision Records

Lightweight ADRs for every extension and package. Format: [Nygard Lightweight ADR](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).

## Index

### Internal Extensions (`extensions/`)

| ADR                                   | Extension                   | Dimension                                      |
| ------------------------------------- | --------------------------- | ---------------------------------------------- |
| [0002](adr-0002-enhanced-edit.md)     | `enhanced-edit/`            | Tool Systems (Edit)                            |
| [0003](adr-0003-code-intel.md)        | `code-intel/`               | Tool Systems (Code Intelligence — tree-sitter) |
| [0004](adr-0004-toon-transformer.md)  | `toon-transformer/index.ts` | Context Management                             |
| [0005](adr-0005-project-context.md)   | `project-context/index.ts`  | Context Management                             |
| [0006](adr-0006-questionnaire.md)     | `questionnaire/index.ts`    | UX & Interaction                               |
| [0007](adr-0007-todo.md)              | `todo/index.ts`             | UX & State Persistence                         |
| ~~[0008](adr-0008-cn3-indicator.md)~~ | ~~`cn3-indicator/`~~        | ~~UX & Observability~~ (superseded → 0021)     |
| ~~[0011](adr-0011-splash-screen.md)~~ | ~~`splash-screen/`~~        | ~~UX & Branding~~ (superseded → 0021)          |
| [0021](adr-0021-cosmetics.md)         | `cosmetics/`                | UX & Observability — unified persona system    |

### External Packages (`settings.json` → `packages[]`)

| ADR                                        | Package                                       | Version | Last Published | Maintainer  |
| ------------------------------------------ | --------------------------------------------- | ------- | -------------- | ----------- |
| [0012](adr-0012-powerline-footer.md)       | `pi-powerline-footer`                         | 0.5.4   | 1 day ago      | @nicobailon |
| [0013](adr-0013-subagents.md)              | `pi-subagents`                                | 0.24.2  | 2 days ago     | @nicobailon |
| [0014](adr-0014-web-access.md)             | `pi-web-access`                               | 0.10.7  | 10 days ago    | @nicobailon |
| [0018](adr-0018-code-search.md)            | ~~`search-helpers/`~~ (superseded → ADR-0003) | —       | —              | —           |
| [0015](adr-0015-pi-lens.md)                | `pi-lens`                                     | 3.8.43  | 2 days ago     | @apmantza   |
| [0016](adr-0016-mcp-adapter.md)            | `pi-mcp-adapter`                              | 2.6.1   | today          | @nicobailon |
| [0017](adr-0017-model-aware-compaction.md) | `pi-model-aware-compaction`                   | 0.1.5   | 6 days ago     | @w-winter   |

### Shared Infrastructure (`extensions/shared/`)

| Module                   | Purpose                                     |
| ------------------------ | ------------------------------------------- |
| `design-system.ts`       | Layout primitives, box drawing, padding     |
| `paths.ts`               | Single source of truth for `piAgentDir()`   |
| `global-state.ts`        | Typed cross-extension state registry        |
| `animations.ts`          | Animation frame utilities                   |
| `colors.ts`              | Color constants and helpers                 |
| `glyphs.ts`              | Unicode glyph constants                     |
| `text.ts`                | Text formatting utilities                   |
| `questionnaire-types.ts` | Type definitions for questionnaire          |
| `questionnaire-ui.ts`    | Rendering logic for questionnaire           |
| `todo-component.ts`      | Todo list rendering component               |
| `noise-dirs.ts`          | Noise directory/file exclusions (SKIP_DIRS) |
| `lang-registry.ts`       | File ext → language ID, grammar files       |
| `exec.ts`                | Shell exec, rg resolution, search helpers   |

## Harness Design Dimensions

From ["Architectural Design Decisions in AI Agent Harnesses"](https://arxiv.org/abs/2604.18071) (70-project empirical study):

| Dimension             | Our Approach                                                  |
| --------------------- | ------------------------------------------------------------- |
| Subagent Architecture | `pi-subagents` + custom agents + chains                       |
| Context Management    | `project-context`, `toon-transformer`, model-aware compaction |
| Tool Systems          | `enhanced-edit`, `code-intel`, `pi-lens`, MCP adapter         |
| Safety Mechanisms     | LSP diagnostics, atomic edits                                 |
| Orchestration         | `pi-subagents` chains, `todo`, `questionnaire`                |

Paper finding: corpus favors file-persistent/hybrid context + registry-oriented tool systems with emerging MCP. Matches our stack.
