# marcelorodrigo/development-crew architecture

> Architecture diagram of the GitHub repository marcelorodrigo/development-crew, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marcelorodrigo/development-crew
- Repository: https://github.com/marcelorodrigo/development-crew

## Overview

1. **What this repository is**
   - This is not an application runtime; it is a **developer workflow toolkit** packaged as an **opencode plugin**.
   - Its main product is a coordinated set of AI agents and process artifacts that help a repo move from idea → spec → implementation → review → archive.

2. **Primary architectural idea**
   - The repo treats **OpenSpec** as the durable source of truth for change design.
   - Chat is used for reasoning and handoffs, but the actual specification lives on disk under `openspec/changes/<name>/`.
   - That boundary is central to the architecture: **conversation for coordination, files for authority**.

3. **Agent pipeline subsystem**
   - The core workflow is a six-role pipeline:
     - Orchestrator
     - Repo Scout
     - Rubber Duck
     - Architect
     - Implementer
     - Code Reviewer
   - Each role has a narrow responsibility and a specific artifact it produces or consumes.
   - The Orchestrator coordinates the whole flow, while the others are specialized workers.

4. **Data flow between stages**
   - A request enters the Orchestrator.
   - Repo Scout can generate `PROJECT_CONTEXT.md`, a repository-level context snapshot.
   - Rubber Duck produces a Brainstorm Brief.
   - Architect converts that into a durable OpenSpec change under `openspec/changes/<name>/`.
   - Implementer reads that change and applies the tasks to the codebase.
   - Code Reviewer compares the implementation against the spec and the default branch.
   - On success, the Orchestrator archives the change and syncs spec deltas.

5. **Repository-scoped context boundary**
   - `PROJECT_CONTEXT.md` is a shared, read-only context artifact used by downstream agents.
   - It prevents every agent from re-deriving the stack and conventions independently.
   - This creates a clear boundary between **discovery** (`Repo Scout`) and **execution** (`Architect`, `Implementer`, `Reviewer`).

6. **OpenSpec change management**
   - The `openspec/` directory is the durable spec layer.
   - `openspec/config.yaml` and `openspec/changes/...` define how change proposals are structured and archived.
   - The presence of `openspec/changes/drop-claude-and-copilot-support/` shows the repo uses OpenSpec not only as documentation, but as an active change-tracking mechanism.

7. **Plugin/runtime integration layer**
   - `src/opencode/` is the code that turns the repo’s agent definitions into an installable opencode plugin.
   - `src/opencode/parse-agent-md.ts` and `src/opencode/agents.ts` indicate the plugin reads agent markdown files and converts them into structured runtime metadata.
   - `src/opencode/index.ts` is the package entrypoint, and `src/opencode/md.d.ts` supports importing markdown as typed content.
   - This layer is the bridge between the markdown-defined agent system and the opencode host environment.

8. **Agent definitions as source assets**
   - The `agents/` directory contains the actual agent role definitions in markdown form.
   - The `.opencode/agents` and `.opencode/skills` trees contain the install-time assets for opencode’s agent and skill system.
   - `.opencode/commands` defines user-facing command shortcuts such as `opsx-apply`, `opsx-archive`, `opsx-explore`, `opsx-propose`, and `opsx-sync`.

9. **Skill and command boundary**
   - Skills are the procedural layer that the agents invoke for OpenSpec operations.
   - The repo explicitly separates:
     - **agent behavior** in `agents/`
     - **command entrypoints** in `.opencode/commands`
     - **task-specific skills** in `.opencode/skills`
   - This makes the system extensible without embedding workflow logic directly into the agent personas.

10. **Validation and enforcement**
   - `validation/validate_agents.py` and `scripts/verify-agents.mjs` suggest there is automated checking that agent definitions and package metadata stay consistent.
   - GitHub Actions reinforce this with dedicated workflows for build, plugin validation, PR-title validation, and release automation.
   - That makes the repo’s governance part of the architecture, not an afterthought.

11. **Documentation and process artifacts**
   - `README.md` is the operational overview and pipeline contract.
   - `getting-started.md` provides practical workflow guidance.
   - `doc/adr/` and `doc/spec/` capture architectural decisions and specs for the system itself.
   - This repository therefore documents both the product it ships and the process by which it evolves.

12. **Build/package shape**
   - The project is a TypeScript package managed with `pnpm`.
   - `tsup.config.ts`, `tsconfig.json`, `package.json`, and `pnpm-workspace.yaml` indicate a small distributable package rather than a monolithic application.
   - CI and release automation (`release-please`, Dependabot, manifest/config files) show it is meant to be versioned and published like a reusable tool.

13. **How to diagram the system**
   - A good architecture diagram would show:
     - User input entering the Orchestrator
     - A context-prep branch through Repo Scout into `PROJECT_CONTEXT.md`
     - A spec-authoring branch into OpenSpec changes
     - An implementation branch applying tasks to the repo
     - A review gate feeding back to the Architect if needed
     - An archive/sync step closing the loop
   - The main external boundary is the **opencode host** plus the **OpenSpec CLI**, which the repository relies on for plugin execution and spec lifecycle management.

14. **Key takeaway**
   - The repository’s architecture is a **workflow engine for AI-assisted development**, built around markdown-defined agents, OpenSpec-backed change records, and command/skill automation.
   - Its most important design boundary is that **design lives on disk, execution is staged, and review is a separate gate**.

Main entry points: [`agents/orchestrator.agent.md`](https://github.com/marcelorodrigo/development-crew/blob/master/agents/orchestrator.agent.md) (Orchestrator), [`agents/architect.agent.md`](https://github.com/marcelorodrigo/development-crew/blob/master/agents/architect.agent.md) (Architect), [`agents/code-reviewer.agent.md`](https://github.com/marcelorodrigo/development-crew/blob/master/agents/code-reviewer.agent.md) (Code Reviewer), [`openspec/config.yaml`](https://github.com/marcelorodrigo/development-crew/blob/master/openspec/config.yaml) (OpenSpec config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Agent pipeline"]
  node_orchestrator["Orchestrator<br/>agent coordinator"]
  node_repo_scout["Repo Scout<br/>discovery agent"]
  node_rubber_duck["Rubber Duck<br/>ideation agent"]
  node_architect["Architect<br/>spec author<br/>[architect.agent.md]"]
  node_implementer["Implementer<br/>executor agent"]
  node_code_reviewer["Code Reviewer<br/>review gate"]
end

subgraph group_spec["OpenSpec layer"]
  node_openspec_config["OpenSpec config<br/>[config.yaml]"]
  node_change_proposal["Proposal<br/>change spec<br/>[proposal.md]"]
  node_change_design["Design<br/>[design.md]"]
  node_change_tasks["Tasks<br/>[tasks.md]"]
end

subgraph group_plugin["opencode plugin"]
  node_opencode_index["Plugin entry<br/>package entrypoint<br/>[index.ts]"]
  node_agent_parser["Agent parser<br/>markdown parser<br/>[parse-agent-md.ts]"]
  node_agent_registry["Agent registry<br/>metadata registry<br/>[agents.ts]"]
  node_markdown_types["MD types<br/>type support<br/>[md.d.ts]"]
  node_agent_sources["Agent sources<br/>agent markdown"]
  node_command_surface["Commands<br/>[commands]"]
  node_skill_layer["Skills<br/>[skills]"]
end

subgraph group_governance["Validation and CI"]
  node_validate_agents["Agent validation<br/>check script<br/>[validate_agents.py]"]
  node_verify_script["Verify agents<br/>build check<br/>[verify-agents.mjs]"]
  node_github_actions["CI workflows<br/>automation<br/>[workflows]"]
end

subgraph group_docs["Documentation"]
  node_readme["README<br/>overview doc<br/>[README.md]"]
  node_getting_started["Getting started<br/>usage guide<br/>[getting-started.md]"]
  node_adr["ADR<br/>decision record"]
  node_spec_doc["Repo spec<br/>design spec"]
end

node_orchestrator -->|"discover context"| node_repo_scout
node_repo_scout -->|"handoff context"| node_rubber_duck
node_rubber_duck -->|"brief to spec"| node_architect
node_architect -->|"author"| node_change_proposal
node_architect -->|"detail design"| node_change_design
node_architect -->|"plan tasks"| node_change_tasks
node_change_tasks -->|"execute"| node_implementer
node_implementer -->|"submit"| node_code_reviewer
node_code_reviewer -.->|"request fixes"| node_architect
node_code_reviewer -->|"approve"| node_orchestrator
node_orchestrator -->|"archive/sync"| node_change_tasks
node_orchestrator -->|"invoke commands"| node_command_surface
node_command_surface -->|"run skills"| node_skill_layer
node_agent_sources -->|"parse markdown"| node_agent_parser
node_agent_parser -->|"register agents"| node_agent_registry
node_agent_registry -->|"expose plugin"| node_opencode_index
node_markdown_types -->|"type imports"| node_agent_parser
node_openspec_config -->|"govern rules"| node_change_proposal
node_openspec_config -->|"govern rules"| node_change_design
node_validate_agents -->|"check consistency"| node_agent_sources
node_verify_script -->|"verify package"| node_agent_registry
node_github_actions -->|"run"| node_validate_agents
node_github_actions -->|"run"| node_verify_script
node_readme -->|"describe flow"| node_orchestrator
node_getting_started -->|"guide usage"| node_command_surface
node_adr -->|"record decision"| node_openspec_config
node_spec_doc -->|"frame process"| node_orchestrator

click node_orchestrator "https://github.com/marcelorodrigo/development-crew/blob/master/agents/orchestrator.agent.md"
click node_repo_scout "https://github.com/marcelorodrigo/development-crew/blob/master/agents/repo-scout.agent.md"
click node_rubber_duck "https://github.com/marcelorodrigo/development-crew/blob/master/agents/rubber-duck.agent.md"
click node_architect "https://github.com/marcelorodrigo/development-crew/blob/master/agents/architect.agent.md"
click node_implementer "https://github.com/marcelorodrigo/development-crew/blob/master/agents/implementer.agent.md"
click node_code_reviewer "https://github.com/marcelorodrigo/development-crew/blob/master/agents/code-reviewer.agent.md"
click node_openspec_config "https://github.com/marcelorodrigo/development-crew/blob/master/openspec/config.yaml"
click node_change_proposal "https://github.com/marcelorodrigo/development-crew/blob/master/openspec/changes/drop-claude-and-copilot-support/proposal.md"
click node_change_design "https://github.com/marcelorodrigo/development-crew/blob/master/openspec/changes/drop-claude-and-copilot-support/design.md"
click node_change_tasks "https://github.com/marcelorodrigo/development-crew/blob/master/openspec/changes/drop-claude-and-copilot-support/tasks.md"
click node_opencode_index "https://github.com/marcelorodrigo/development-crew/blob/master/src/opencode/index.ts"
click node_agent_parser "https://github.com/marcelorodrigo/development-crew/blob/master/src/opencode/parse-agent-md.ts"
click node_agent_registry "https://github.com/marcelorodrigo/development-crew/blob/master/src/opencode/agents.ts"
click node_markdown_types "https://github.com/marcelorodrigo/development-crew/blob/master/src/opencode/md.d.ts"
click node_agent_sources "https://github.com/marcelorodrigo/development-crew/tree/master/agents"
click node_command_surface "https://github.com/marcelorodrigo/development-crew/blob/master/.opencode/commands"
click node_skill_layer "https://github.com/marcelorodrigo/development-crew/blob/master/.opencode/skills"
click node_validate_agents "https://github.com/marcelorodrigo/development-crew/blob/master/validation/validate_agents.py"
click node_verify_script "https://github.com/marcelorodrigo/development-crew/blob/master/scripts/verify-agents.mjs"
click node_github_actions "https://github.com/marcelorodrigo/development-crew/blob/master/.github/workflows"
click node_readme "https://github.com/marcelorodrigo/development-crew/blob/master/README.md"
click node_getting_started "https://github.com/marcelorodrigo/development-crew/blob/master/getting-started.md"
click node_adr "https://github.com/marcelorodrigo/development-crew/blob/master/doc/adr/0001-record-architecture-decisions.md"
click node_spec_doc "https://github.com/marcelorodrigo/development-crew/blob/master/doc/spec/001-generic-pipeline-migration.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_orchestrator,node_repo_scout,node_rubber_duck,node_architect,node_implementer,node_code_reviewer toneBlue
class node_openspec_config,node_change_proposal,node_change_design,node_change_tasks toneAmber
class node_opencode_index,node_agent_parser,node_agent_registry,node_markdown_types,node_agent_sources,node_command_surface,node_skill_layer toneMint
class node_validate_agents,node_verify_script,node_github_actions toneRose
class node_readme,node_getting_started,node_adr,node_spec_doc toneIndigo
```

## Components

### Agent pipeline

Role-based workflow from discovery through review and archive.

- [Orchestrator](https://github.com/marcelorodrigo/development-crew/blob/master/agents/orchestrator.agent.md): agent coordinator · Coordinates the end-to-end change workflow and handoffs. · `agents/orchestrator.agent.md`
- [Repo Scout](https://github.com/marcelorodrigo/development-crew/blob/master/agents/repo-scout.agent.md): discovery agent · Builds repository context and surfaces conventions for downstream agents. · `agents/repo-scout.agent.md`
- [Rubber Duck](https://github.com/marcelorodrigo/development-crew/blob/master/agents/rubber-duck.agent.md): ideation agent · Turns the request into a brainstorm brief and exploratory reasoning. · `agents/rubber-duck.agent.md`
- [Architect](https://github.com/marcelorodrigo/development-crew/blob/master/agents/architect.agent.md): spec author · Converts the brief into a durable OpenSpec change proposal. · `agents/architect.agent.md`
- [Implementer](https://github.com/marcelorodrigo/development-crew/blob/master/agents/implementer.agent.md): executor agent · Applies the accepted change tasks to the codebase. · `agents/implementer.agent.md`
- [Code Reviewer](https://github.com/marcelorodrigo/development-crew/blob/master/agents/code-reviewer.agent.md): review gate · Checks implementation against the spec and default branch. · `agents/code-reviewer.agent.md`

### OpenSpec layer

Durable change records and spec governance on disk.

- [OpenSpec config](https://github.com/marcelorodrigo/development-crew/blob/master/openspec/config.yaml): spec config · Defines how change proposals and archives are structured. · `openspec/config.yaml`
- [Proposal](https://github.com/marcelorodrigo/development-crew/blob/master/openspec/changes/drop-claude-and-copilot-support/proposal.md): change spec · Authoritative proposal for the active change. · `openspec/changes/drop-claude-and-copilot-support/proposal.md`
- [Design](https://github.com/marcelorodrigo/development-crew/blob/master/openspec/changes/drop-claude-and-copilot-support/design.md): change design · Detailed solution design for the active OpenSpec change. · `openspec/changes/drop-claude-and-copilot-support/design.md`
- [Tasks](https://github.com/marcelorodrigo/development-crew/blob/master/openspec/changes/drop-claude-and-copilot-support/tasks.md): change tasks · Execution checklist consumed by implementation. · `openspec/changes/drop-claude-and-copilot-support/tasks.md`

### opencode plugin

Markdown agents, commands, and skill adapters used by the host runtime.

- [Plugin entry](https://github.com/marcelorodrigo/development-crew/blob/master/src/opencode/index.ts): package entrypoint · Entry module that exposes the plugin to opencode. · `src/opencode/index.ts`
- [Agent parser](https://github.com/marcelorodrigo/development-crew/blob/master/src/opencode/parse-agent-md.ts): markdown parser · Parses agent markdown into structured runtime metadata. · `src/opencode/parse-agent-md.ts`
- [Agent registry](https://github.com/marcelorodrigo/development-crew/blob/master/src/opencode/agents.ts): metadata registry · Collects agent definitions into a plugin-ready catalog. · `src/opencode/agents.ts`
- [MD types](https://github.com/marcelorodrigo/development-crew/blob/master/src/opencode/md.d.ts): type support · Typed markdown import support for the plugin build. · `src/opencode/md.d.ts`
- [Agent sources](https://github.com/marcelorodrigo/development-crew/tree/master/agents): agent markdown · Source definitions for the six workflow roles. · `agents`
- [Commands](https://github.com/marcelorodrigo/development-crew/blob/master/.opencode/commands): opencode commands · User-facing shortcuts for proposing, applying, syncing, and archiving changes. · `.opencode/commands`
- [Skills](https://github.com/marcelorodrigo/development-crew/blob/master/.opencode/skills): opencode skills · Procedural implementations invoked by commands and agents. · `.opencode/skills`

### Validation and CI

Checks and automation that keep the plugin and agent metadata consistent.

- [Agent validation](https://github.com/marcelorodrigo/development-crew/blob/master/validation/validate_agents.py): check script · Verifies agent definitions and plugin metadata stay aligned. · `validation/validate_agents.py`
- [Verify agents](https://github.com/marcelorodrigo/development-crew/blob/master/scripts/verify-agents.mjs): build check · Node-based validation for agent packaging consistency. · `scripts/verify-agents.mjs`
- [CI workflows](https://github.com/marcelorodrigo/development-crew/blob/master/.github/workflows): automation · Build, plugin validation, PR title checks, and release automation. · `.github/workflows`

### Documentation

Operational and architectural guidance for the workflow.

- [README](https://github.com/marcelorodrigo/development-crew/blob/master/README.md): overview doc · Primary operational overview and workflow contract. · `README.md`
- [Getting started](https://github.com/marcelorodrigo/development-crew/blob/master/getting-started.md): usage guide · Practical onboarding for the workflow toolkit. · `getting-started.md`
- [ADR](https://github.com/marcelorodrigo/development-crew/blob/master/doc/adr/0001-record-architecture-decisions.md): decision record · Architecture decisions for the repository itself. · `doc/adr/0001-record-architecture-decisions.md`
- [Repo spec](https://github.com/marcelorodrigo/development-crew/blob/master/doc/spec/001-generic-pipeline-migration.md): design spec · Higher-level specification for the repository's pipeline evolution. · `doc/spec/001-generic-pipeline-migration.md`

## Connections

- Orchestrator → Repo Scout: discover context · Orchestrator sends discovery work to the repo scout.
- Repo Scout → Rubber Duck: handoff context · Discovered repo context feeds ideation.
- Rubber Duck → Architect: brief to spec · Brainstorm output becomes a durable OpenSpec proposal.
- Architect → Proposal: author · Architect writes the proposal into OpenSpec.
- Architect → Design: detail design · Architect refines the change design artifact.
- Architect → Tasks: plan tasks · Architect defines execution steps for implementer consumption.
- Tasks → Implementer: execute · Implementation follows the task list.
- Implementer → Code Reviewer: submit · Completed work is gated by review.
- Code Reviewer → Architect: request fixes · Review feedback can route back for spec or plan adjustments.
- Code Reviewer → Orchestrator: approve · Approved changes return to the coordinator for closeout.
- Orchestrator → Tasks: archive/sync · Coordinator closes the loop by archiving and syncing spec deltas.
- Orchestrator → Commands: invoke commands · User-facing commands enter the workflow through opencode.
- Commands → Skills: run skills · Commands dispatch OpenSpec procedures via skills.
- Agent sources → Agent parser: parse markdown · Agent markdown is transformed into structured definitions.
- Agent parser → Agent registry: register agents · Parsed metadata is assembled into the plugin registry.
- Agent registry → Plugin entry: expose plugin · Registry contents are exported by the package entrypoint.
- MD types → Agent parser: type imports · Typed markdown imports support agent parsing at build time.
- OpenSpec config → Proposal: govern rules · OpenSpec config defines how changes are shaped and stored.
- OpenSpec config → Design: govern rules · OpenSpec config also governs design documents.
- Agent validation → Agent sources: check consistency · Validation ensures agent files remain coherent with package metadata.
- Verify agents → Agent registry: verify package · Build-time verification checks the generated plugin surface.
- CI workflows → Agent validation: run · CI invokes validation jobs.
- CI workflows → Verify agents: run · CI runs script-level checks.
- README → Orchestrator: describe flow · README explains the workflow contract around the pipeline.
- Getting started → Commands: guide usage · Onboarding documents how to use the command surface.
- ADR → OpenSpec config: record decision · Architecture decisions inform the spec layer and process boundaries.
- Repo spec → Orchestrator: frame process · Repository spec documents the intended pipeline shape.
