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

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:

<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:

<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.