Add Repository Intelligence Bootstrap: repo-bootstrap.sh, all 13 agents updated, docs, tests
- scripts/repo-bootstrap.sh: generic idempotent bootstrap tool (status/bootstrap/refresh) - creates .opencode/ with repo-context, architecture, build-and-test, conventions, deployment skills - relevance-based skill generation (only creates what the repo actually has) - staleness detection via .bootstrap-meta (key=value, SHA-256 fingerprints) - marker-based manual protection (never overwrites unmarked files) - accepts --root flag for explicit repo targeting - scripts/test-repo-bootstrap.sh: 11 tests covering all 10 acceptance criteria - creation, idempotency, manual preservation, relevance detection - orchestrator/agent structural checks, staleness, genericness - install.sh workflow compatibility, malformed handling - agents/orchestrator.md: first-class Repository Intelligence Bootstrap stage - 10-step workflow, ownership rules table, staleness signals - consumption rules, backward compatibility, fallback procedure - All 12 subagent files: role-adapted Repository Intelligence section - architect: owns architecture skill - builder/tester: own build-and-test skill (shared) - explorer: owns repo-context skill - maintainer: owns conventions skill + audits .opencode/ - reviewer: validates consistency (consumer/reporter) - designer/detective/philosopher/toolsmith/workflow-architect/writer: consume-only - docs/REPOSITORY_INTELLIGENCE.md: full architecture documentation - README.md: updated layout, bootstrap usage, requirements - 13/13 agents installed, permission-engine verifier PASS
This commit is contained in:
Your Name
@@ -0,0 +1,208 @@
|
||||
# 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.
|
||||
|
||||
## .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.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user