dev_agent_team/docs/REPOSITORY_INTELLIGENCE.md

# Repository Intelligence Bootstrap

This document explains the Repository Intelligence Bootstrap system: what it is,
how it works, how agents use it, and how to maintain it.

## Overview

When the Orchestrator starts work on an unfamiliar repository, it first checks
whether a local `.opencode/` knowledge layer exists and is current. If not, it
generates or refreshes it. Every agent then reads this pre-analyzed context
instead of re-discovering repository fundamentals from scratch.

**Repository intelligence is a knowledge accelerator, not a substitute for
source-of-truth code.** Agents still verify claims against the actual repository.

## Bootstrap flow

```text
Orchestrator starts task
  ↓
detect repo root
  ↓
repo-bootstrap.sh status → fresh | stale | missing
  ↓
  ┌────────────────────────────────────┐
  │ missing or stale? (exit code ≠ 0) │──yes──→ repo-bootstrap.sh bootstrap
  └──────────┬─────────────────────────┘         → scaffold .opencode/ structure
             │ no                                → Orchestrator/Explorer enrich content
             ↓
  read .opencode/AGENTS.md + relevant skills
             ↓
  build task plan with repo context
             ↓
  dispatch specialized agents
             ↓
  agents update knowledge when durable discoveries are made
             ↓
  Reviewer verifies repo intelligence consistency
```

The bootstrap is **idempotent**: running it multiple times does not overwrite
manually enriched content. Only files generated by the bootstrap tool are
regenerated, and only when the staleness fingerprint changes.

## Bootstrap tool (fallback procedure)

The accompanying script `"${OPENCODE_DEV_AGENT_TEAM:-$HOME/.config/opencode/dev-agent-team}"/bin/repo-bootstrap.sh` (in this team's distribution)
performs the mechanical work: scaffolding `.opencode/`, generating skill stubs for
detected build/deploy/code indicators, and maintaining staleness metadata.

If the script is not available at the expected path, perform the equivalent steps
inline: check `.opencode/.bootstrap-meta` for fingerprint freshness, create
missing skill directories, and never overwrite manually enriched files.

## .opencode structure

After a successful bootstrap, the repository looks like this:

```text
<repository root>/
├── AGENTS.md                          # opencode auto-loads this from project root
└── .opencode/
    ├── AGENTS.md                      # full intelligence entry point
    ├── .bootstrap-meta                # staleness metadata (key=value)
    └── skills/
        ├── repo-context/SKILL.md      # purpose, structure, modules
        ├── architecture/SKILL.md      # components, boundaries, rules (if code detected)
        ├── build-and-test/SKILL.md    # build, test, lint commands (if build indicators detected)
        ├── conventions/SKILL.md       # coding, naming, workflow conventions
        └── deployment/SKILL.md        # deploy/runtime info (if deploy indicators detected)
```

### Relevance detection

The bootstrap does not blindly create every directory. It detects repository
type from manifest files and top-level structure:

| Indicator      | Skill generated                | Detection signals                             |
|----------------|--------------------------------|-----------------------------------------------|
| Always         | repo-context, conventions      | (always relevant)                             |
| `has_code`     | architecture                   | `src/`, `lib/`, `packages/`, or build files   |
| `has_build`    | build-and-test                 | `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Makefile`, etc. |
| `has_deploy`   | deployment                     | `Dockerfile`, `.github/workflows/`, `*.tf`, etc. |

### Idempotency rules

- Generated files carry a marker comment: `<!-- GENERATED-SCAFFOLD dev_agent_team repo-bootstrap ... -->`
- The bootstrap never overwrites files without this marker (manual content is
  preserved).
- A second run with unchanged fingerprints produces zero changes.
- Agents strip the marker when they substantially enrich a generated file,
  freezing it as manual content.

### Backward compatibility

- Repositories without `.opencode/` continue to work — bootstrap creates it.
- Repositories with existing manually written `.opencode/` files are handled
  safely — the bootstrap never destroys or silently replaces them.

## Staleness detection

The bootstrap writes `.opencode/.bootstrap-meta` (key=value, POSIX-compatible,
no JSON parser required) containing:

- `schema` — metadata format version
- `tool`, `version` — bootstrap tool identity
- `generated_at` — ISO 8601 timestamp
- `git_head` — current HEAD sha (informational, not a staleness trigger)
- `manifest_fingerprint` — SHA-256 of all build/test/deploy config file contents
- `top_level_fingerprint` — SHA-256 of sorted top-level directory listing
- `signals` — detected capabilities (build/deploy/code)

**Staleness signals:** the metadata is stale when the manifest fingerprint
changes (dependency or build config updated), the top-level structure changes
materially, or the meta file is missing/corrupted. A changed git HEAD alone
does not force refresh — dependency and structure changes are the meaningful
signals.

## Orchestrator responsibility

The Orchestrator's "Repository Intelligence Bootstrap" stage runs on every task
start, before task classification and agent dispatch:

1. Detect repo root.
2. Check `.opencode/` existence and freshness via `repo-bootstrap.sh status`.
3. If missing/stale: run `repo-bootstrap.sh bootstrap`, then enrich content.
4. Read the generated context.
5. Build the task plan using that context.
6. Dispatch agents with relevant skill references in their briefs.

The Orchestrator also controls ownership rules and refresh decisions.

## Agent responsibilities

### Consumption rules (all agents)

1. Read `.opencode/AGENTS.md` at task start (or receive it via orchestrator brief).
2. Read the relevant skill for the agent's domain.
3. Treat repo intelligence as context, not truth — verify against the repository.
4. Avoid rediscovery: if knowledge exists in `.opencode/`, do not re-explore it.
5. Add durable discoveries only to role-owned files.
6. Never fill `.opencode/` with task-specific noise.

### Ownership rules

| Skill                    | Primary owner    | Role                                            |
|--------------------------|------------------|-------------------------------------------------|
| repo-context             | Explorer         | verify/enrich purpose, structure, dependencies   |
| architecture             | Architect        | verify/enrich components, boundaries, rules      |
| build-and-test           | Builder + Tester | verify/enrich build, test, lint, validation      |
| conventions              | Maintainer       | verify/enrich coding, naming, workflow standards  |
| deployment               | (no permanent)   | enriched by whoever handles deployment           |
| AGENTS.md (root + .opencode/) | Orchestrator | lifecycle, structural references                 |
| All .opencode/ (validate) | Reviewer        | verify consistency against source; reports findings |
| All .opencode/ (audit)   | Maintainer       | detect staleness, dedup, cleanup                 |

### How agents enrich generated content

When an agent makes a durable discovery that should persist beyond the session:

1. Verify the fact against the actual repository.
2. Edit the relevant skill file in `.opencode/skills/`.
3. Strip the `GENERATED-SCAFFOLD` marker comment from the file.
4. This freezes the file as manual content — future bootstrap runs will not
   overwrite it.

## Knowledge lifecycle

Repository knowledge must be concise, evidence-backed, discoverable, updateable,
versionable, and resistant to staleness.

- Knowledge lives in `.opencode/` skills (e.g. `architecture`, `build-and-test`,
  `conventions` play the role of the `knowledge/architecture.md`,
  `knowledge/build.md`, `knowledge/conventions.md` files). Do NOT create separate
  `knowledge/` or `state/` directories unless a concrete need appears — the
  existing skills + `AgentsReport/` already separate durable repo knowledge from
  task state.
- When new durable facts are discovered: (1) decide whether they belong in
  repository knowledge, (2) identify the correct knowledge owner (ownership
  table), (3) update only that document, (4) preserve valid existing
  information, (5) never record temporary task details as permanent knowledge.
- Stale `.opencode/` content is detected by the bootstrap fingerprints; when a
  manual fact is disproven by the repository, the owning agent corrects it
  (Maintainer for conventions, Architect for architecture, Explorer for context,
  Builder/Tester for build-and-test).

## Example: freshly initialized repository

Running `repo-bootstrap.sh bootstrap` in a Node.js project with Docker:

```text
<repository root>/
├── AGENTS.md                    # pointer to .opencode/AGENTS.md
├── .opencode/
│   ├── AGENTS.md                # full entry: purpose, structure, skills pointers
│   ├── .bootstrap-meta          # freshness metadata
│   └── skills/
│       ├── repo-context/SKILL.md    # purpose, structure, dependencies
│       ├── architecture/SKILL.md    # components, boundaries (code detected)
│       ├── build-and-test/SKILL.md  # npm, jest, eslint (package.json detected)
│       ├── conventions/SKILL.md     # style, naming, workflow
│       └── deployment/SKILL.md      # Docker, CI/CD (Dockerfile detected)
```

The generated files contain scaffold sections with placeholders. Agents
(Explorer, Architect, Builder, Tester, etc.) then enrich each skill with
verified facts, strip the marker, and the knowledge becomes durable.

## Tests

The test suite is at `scripts/test-repo-bootstrap.sh`. It covers all 10
acceptance criteria:

1. `.opencode` created for new repository
2. Bootstrap is idempotent
3. Existing manual content is preserved
4. Relevant repository skills are generated
5. Orchestrator loads repo context before dispatch (structural)
6. Every agent references `.opencode` (structural)
7. Stale knowledge is detectable
8. Unrelated repositories do not inherit hardcoded assumptions
9. Existing agent workflows still work
10. Malformed/incomplete intelligence is handled safely

Run with: `bash scripts/test-repo-bootstrap.sh`

## Design decisions

- **Script handles mechanics, LLM handles intelligence**: `repo-bootstrap.sh`
  performs deterministic scaffolding and metadata; agents (Orchestrator,
  Explorer, Architect, etc.) enrich with semantic understanding.
- **Key=value metadata (no JSON parser)**: avoids `jq` dependency; POSIX-portable.
- **Marker-based manual protection**: simple, reliable, no complex versioning.
- **Skills format follows opencode conventions**: `.opencode/skills/<name>/SKILL.md`
  with `name` + `description` frontmatter — works with opencode's native skill
  loader wherever `skill: allow` is set.
- **Agents consume via file reads** (not skill tool): compatible with the current
  `skill: deny` permission on subagents; also opencode-version-agnostic.