# Brownfield Adoption Guide: Anchor Protocol (APS-1)

**Organization:** [VorteXpert Labs](https://github.com/vortexpert-labs) | **Author:** [Sabber Ahamad Emon](https://github.com/sabber-ahamad-emon)

## 1. Overview
This guide provides the standard operating procedure for adopting **Anchor Protocol** in existing ("brownfield") repositories with large codebases (50k–500k+ LOC), years of Git history, and existing documentation.

### The Core Philosophy
Anchor Protocol is a **forward-looking orientation vector**, not an archaeological survey. Adopting Anchor Protocol does **not** mean documenting everything that happened in the past. It means capturing the **active constraints, current project stage, and non-negotiable boundaries** needed to keep humans and AI agents aligned.

---

## 2. The 3-Step Brownfield Bootstrap Protocol

```
Step 1: Passive Repo Scan ──► Step 2: Genesis Anchors (3-5) ──► Step 3: Adapter Injection
  (Zero Code Execution)         (Crystallize Active Truths)        (Non-Destructive Markers)
```

### Step 1: Passive Repository Scan
Perform a deterministic static scan of the codebase to identify foundational technology choices:
- **Language & Runtime:** Inspect package manifests (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `mise.toml`).
- **Data Layer:** Inspect ORM schemas, migration directories, and database drivers.
- **Infrastructure:** Inspect Dockerfiles, CI workflows, and deployment descriptors.
- **Linters & Formatters:** Inspect strict typing flags and linter rules.
- **Existing ADRs:** Scan `docs/adr/` for currently binding decisions.

### Step 2: Genesis Anchor Crystallization
Create `.anchors/` and generate **exactly 3 to 5 active anchors**. Do not exceed 5 anchors during initial bootstrap.

#### Genesis Anchor Set:
1. **`ANC-0001-project-stage.md`** (`type: STAGE`): Active project phase (`PRODUCTION`, `ALPHA`, `MAINTENANCE`) and stability invariants.
2. **`ANC-0002-core-architecture.md`** (`type: DECISION`): Primary framework, persistence engine, and deployment model.
3. **`ANC-0003-architectural-invariants.md`** (`type: CONSTRAINT`): Structural constraints (e.g. strict module boundaries, tenant isolation).
4. **`ANC-0004-historical-rejected-paths.md`** (`type: BOUNDARY`): Known anti-patterns, failed library experiments, and banned practices.
5. **`ANC-0005-[critical-domain].md`** (`type: BOUNDARY`, Optional): Deep constraints for the highest-risk module (e.g., Billing, Auth).

#### Generate `.anchors/INDEX.md`:
Create the lightweight pre-flight manifest (~150–250 tokens):
```markdown
# Project Orientation Index ⚓

## Project Stage
- **STAGE:** `PRODUCTION`
- **Policy:** Zero downtime migrations, strict semantic versioning, 100% backward compatibility.

## Active Strategic Goals
- **GOAL-01:** Modernize service boundaries while maintaining sub-50ms p99 latency.

## Active Anchor Registry

| ID | Type | Title | Scope | Status |
|---|---|---|---|---|
| [ANC-0001](ANC-0001-project-stage.md) | STAGE | Production Operational Posture | global | `ACTIVE` |
| [ANC-0002](ANC-0002-core-architecture.md) | DECISION | Core Service Architecture Baseline | core | `ACTIVE` |
| [ANC-0003](ANC-0003-architectural-invariants.md) | CONSTRAINT | Multi-Tenant Database Isolation | backend/db | `ACTIVE` |
| [ANC-0004](ANC-0004-historical-rejected-paths.md) | BOUNDARY | Prohibited Patterns & Historical Pitfalls | global | `ACTIVE` |
```

### Step 3: Non-Destructive Tool Adapter Injection
Inject the standard Anchor Protocol adapter block into existing agent configuration files (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/anchor-protocol.mdc`, `.github/copilot-instructions.md`, `.windsurfrules`, `.clinerules`).

#### The Delimited Marker Block:
```markdown
<!-- ANCHOR-PROTOCOL-ADAPTER: START -->
## Project Orientation & Anchor Protocol
This repository uses the **Anchor Protocol** for persistent project orientation.
- **Canonical Index:** `.anchors/INDEX.md`
- **Pre-flight Sequence:** Inspect `.anchors/INDEX.md` before executing multi-file architectural changes.
- **Invariant Rules:** Obey all `ACTIVE` constraints and never re-attempt `REJECTED_PATH` anchors.
- **Crystallization:** When establishing a consequential architectural decision or discovering a fatal flaw in an approach, draft an anchor in `.anchors/ANC-XXXX-[slug].md` with `status: PROPOSED`.
- **Anti-Pollution:** Never write raw conversation transcripts, bug stack traces, or temporary logs to `.anchors/`.
<!-- ANCHOR-PROTOCOL-ADAPTER: END -->
```

*Note: All pre-existing developer notes, test instructions, and runbook entries outside these comment markers remain completely untouched.*

---

## 3. Conflict Resolution with Legacy Documentation

When adopting Anchor Protocol in a repository with years of existing documentation, apply the **Epistemic Authority Hierarchy**:

```
Level 1: Source Code & Tests    ──► Sole authority on WHAT IS currently running.
Level 2: .anchors/ Layer         ──► Sole authority on ACTIVE CONSTRAINTS & INTENT.
Level 3: Agent & Tool Configs   ──► Sole authority on HOW AGENTS OPERATE.
Level 4: Legacy Docs / Wikis    ──► Descriptive and historical background only.
```

### Resolution Rules:
1. **Code Supremacy:** If a legacy `README.md` or wiki page contradicts running source code, the code is authoritative. Never mutate working code to match obsolete documentation.
2. **Legacy ADRs:** Do not mass-convert existing ADRs. Keep them in `docs/adr/`. If an ADR represents an active invariant, reference its path in an anchor's `evidence` field.
3. **Quarantine Stale Docs:** Add a one-line disclaimer to obsolete architecture directories:  
   `> NOTE: For active architectural invariants and constraints, refer to .anchors/INDEX.md.`