dev_agent_team/README.md

dev_agent_team

A distributable package of 14 opencode agent definitions plus a one-command installer, so the same agent team can be set up identically on any machine.

What this is

This repository packages a complete multi-agent team for opencode — 14 role-specialized agents that work as one system:

architect, builder, breakdowner, designer, detective, explorer, maintainer, orchestrator (primary), philosopher, reviewer, tester, toolsmith, workflow-architect, writer.

The agent definitions live in agents/ and are copied verbatim into your opencode config directory by scripts/install.sh. The installer is idempotent: re-running it is safe, and it backs up any pre-existing files it would overwrite into a timestamped folder under <target>/.backup/, keeping only the 5 most recent backup folders.

Repository Intelligence Bootstrap

The team includes a Repository Intelligence Bootstrap system: when the Orchestrator starts work on an unfamiliar repository, it automatically analyzes the repository and generates a local .opencode/ knowledge layer (context, architecture, build/test, conventions, deployment). Every agent then reads this pre-analyzed context instead of re-discovering repository fundamentals.

The bootstrap is idempotent, language-agnostic, and preserves manually enriched content. See docs/REPOSITORY_INTELLIGENCE.md for the full architecture.

Adaptive, Evidence-Driven Orchestration

The team is architected as a decision engine: the Orchestrator recalls project memory, understands the task, estimates complexity, loads repository intelligence, chooses the next best action from an explicit action catalog, verifies outcomes independently, re-plans when evidence changes, stores durable findings, and stops when sufficiently verified. Every agent produces structured evidence-state records and knows when to stop and escalate.

See docs/AGENT_ARCHITECTURE.md for the full architecture, and docs/EVALUATION_SCENARIOS.md for the 12 runtime evaluation scenarios used to measure the team's own quality.

Project Memory & Skills

The team includes cross-session project memory (memory/) for persisting decisions, lessons, failures, architecture notes, and session state. A lifecycle script (scripts/memory-lifecycle.sh) provides deterministic recall, store, list, search, and cleanup operations.

The team also includes 12 reusable skills (skills/) — specialized methodologies for TDD, debugging, architecture, code review, security review, and more. Agents load relevant skills when dispatched.

Both systems require human approval for changes to core agent behavior (improvements/).

Repository layout

dev_agent_team/
├── README.md                          # this file
├── .gitignore
├── agents/                            # the 14 agent definitions (*.md)
├── .tasks/                            # per-project Task Breakdown (gitignored; created by breakdowner, never committed)
├── memory/                            # cross-session project memory
│   ├── MEMORY.md                      # index with lifecycle rules
│   ├── decisions/                     # architectural/technical choices
│   ├── lessons/                       # reusable knowledge
│   ├── failures/                      # root causes + prevention
│   ├── architecture/                  # system structure documentation
│   └── sessions/                      # work-in-progress state
├── skills/                            # 12 reusable specialized methodologies
│   ├── SKILLS.md                      # index with loading rules
│   ├── tdd/SKILL.md                   # Test-Driven Development
│   ├── systematic-debugging/SKILL.md  # debugging methodology
│   ├── architecture-design/SKILL.md   # architecture decisions
│   ├── code-review/SKILL.md           # code review process
│   ├── security-review/SKILL.md       # security review
│   ├── repository-analysis/SKILL.md   # repo exploration
│   ├── failure-analysis/SKILL.md      # failure investigation
│   ├── refactoring/SKILL.md           # safe code restructuring
│   ├── test-analysis/SKILL.md         # test quality assessment
│   ├── incident-investigation/SKILL.md # production incidents
│   ├── browser-automation/SKILL.md    # web interaction patterns
│   └── research/SKILL.md              # information gathering
├── improvements/                      # proposal-based improvement system
│   ├── README.md                      # proposal format and lifecycle
│   ├── pending/                       # proposals awaiting approval
│   ├── applied/                       # approved and implemented
│   └── rejected/                      # not approved
├── scripts/
│   ├── install.sh                     # one-command installer (agents + runtime tree; --uninstall/--migrate/--self-test)
│   ├── repo-bootstrap.sh              # repository intelligence bootstrap tool
│   ├── memory-lifecycle.sh            # memory CRUD operations
│   ├── test-all.sh                    # single entry point that runs all 8 test suites
│   ├── test-repo-bootstrap.sh         # test suite for the bootstrap
│   ├── test-agent-architecture.sh     # structural tests for the agent architecture
│   ├── test-memory-system.sh          # structural tests for memory/skills/improvements
│   ├── test-integration.sh            # end-to-end memory/skills/lifecycle integration tests
│   ├── test-install.sh                # runtime-tree install + idempotency tests
│   ├── test-runtime.sh                # runtime-after-source-deletion + bootstrap tests
│   ├── test-path-resolution.sh        # prompt/skills/improvements path-resolution tests
│   ├── test-memory-isolation.sh       # per-project memory isolation tests
│   └── verify-permission-patterns.sh  # permission engine verifier
└── docs/
    ├── PROMPT_INSTALL.md              # paste-ready prompt for installing from inside opencode
    ├── REPOSITORY_INTELLIGENCE.md     # bootstrap architecture documentation
    ├── AGENT_ARCHITECTURE.md          # adaptive/evidence-driven architecture documentation
    └── EVALUATION_SCENARIOS.md        # runtime evaluation scenarios for the team itself

Quickstart

git clone git@gitea.skink-platy.ts.net:admin/dev_agent_team.git
cd dev_agent_team
./scripts/install.sh

To install somewhere other than the default location:

OPENCODE_AGENTS_DIR=/path/to/opencode/agents ./scripts/install.sh

The installer also installs the self-contained runtime tree (scripts bin/, 12 general-purpose skills skills/, improvements store, and an install-manifest.json) under $OPENCODE_DEV_AGENT_TEAM (default $XDG_CONFIG_HOME/opencode/dev-agent-team, fallback ~/.config/opencode/dev-agent-team). After installation the source checkout may be deleted; the agents and runtime keep working from any project.

Runtime-aware operations:

./scripts/install.sh               # install agents + full runtime tree (idempotent)
./scripts/install.sh --uninstall   # remove manifest-tracked agents + runtime (keeps backups; preserves improvements/ unless --purge)
./scripts/install.sh --uninstall --purge   # also remove improvements/ user data
./scripts/install.sh --migrate     # one-time import of pending improvement proposals (no-op today)
./scripts/install.sh --self-test   # run runtime test suites in a throwaway temp HOME

--uninstall never touches project memory/, .opencode/, AgentsReport/, or ~/.config/opencode/opencode.json.

Repository bootstrap

After installing the agents, the bootstrap tool is available at scripts/repo-bootstrap.sh. From inside any target repository:

# Check freshness (exit 0=fresh, 1=stale/missing)
repo-bootstrap.sh status

# Create/update .opencode/ knowledge layer
repo-bootstrap.sh bootstrap

# Force regenerate generated files
repo-bootstrap.sh refresh

Run all test suites with a single command (aggregates the eight suites below):

bash scripts/test-all.sh

105 individual checks across 8 suites (17 architecture + 16 memory + 11 bootstrap

• 12 integration + 15 install + 10 runtime + 12 path-resolution + 12 memory-isolation). Any suite failing makes the overall exit code non-zero.

Individual suites:

• test-agent-architecture.sh — architecture contains the required adaptive/evidence-driven elements (17 structural tests).
• test-memory-system.sh — memory, skills, and improvement systems are structurally sound (16 tests).
• test-repo-bootstrap.sh — bootstrap behavior and idempotency (11 tests covering all 10 acceptance criteria).
• test-integration.sh — end-to-end memory/skills/improvements integration (12 tests).
• test-install.sh — runtime-tree install, manifest, rc export, backups, and idempotency (15 tests).
• test-runtime.sh — runtime survives after source deletion and works from any unrelated project (10 tests).
• test-path-resolution.sh — prompt/skills/improvements resolve to the runtime root; project-scoped refs stay project-relative (12 tests).
• test-memory-isolation.sh — per-project memory isolation via OPENCODE_MEMORY_DIR (12 tests).

Manual install alternative

Prefer to do it yourself? A plain copy achieves the same result:

mkdir -p ~/.config/opencode/agents
cp -p agents/*.md ~/.config/opencode/agents/

(You will not get the automatic backup of pre-existing files that scripts/install.sh provides.)

Prompt-based install

Already inside an opencode session? Copy a ready-made prompt that instructs the primary agent to clone this repo, run the installer, and verify the result: see docs/PROMPT_INSTALL.md.

Requirements

• opencode installed (needed to actually use the agents)
• bash and coreutils (cp, mkdir, date, sha256sum or cksum)
• SSH access to the gitea host for cloning (or an HTTPS remote, if mirrored)

Verification

After installing:

1. Restart any running opencode sessions so they pick up the new agents.

2. Run:

   opencode agent list
   

3. You should see exactly 14 agents: architect, builder, breakdowner, designer, detective, explorer, maintainer, orchestrator, philosopher, reviewer, tester, toolsmith, workflow-architect, writer.