How marcelorodrigo/development-crew works
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: orchestrator.agent.md Orchestrator · architect.agent.md Architect · code-reviewer.agent.md Code Reviewer · config.yaml OpenSpec config
Components 24
Agent pipeline
Role-based workflow from discovery through review and archive.
- Orchestrator · Coordinates the end-to-end change workflow and handoffs.
agents/orchestrator.agent.md - Repo Scout · Builds repository context and surfaces conventions for downstream agents.
agents/repo-scout.agent.md - Rubber Duck · Turns the request into a brainstorm brief and exploratory reasoning.
agents/rubber-duck.agent.md - Architect · Converts the brief into a durable OpenSpec change proposal.
agents/architect.agent.md - Implementer · Applies the accepted change tasks to the codebase.
agents/implementer.agent.md - Code Reviewer · 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 · Defines how change proposals and archives are structured.
openspec/config.yaml - Proposal · Authoritative proposal for the active change.
openspec/changes/drop-claude-and-copilot-support/proposal.md - Design · Detailed solution design for the active OpenSpec change.
openspec/changes/drop-claude-and-copilot-support/design.md - 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 · Entry module that exposes the plugin to opencode.
src/opencode/index.ts - Agent parser · Parses agent markdown into structured runtime metadata.
src/opencode/parse-agent-md.ts - Agent registry · Collects agent definitions into a plugin-ready catalog.
src/opencode/agents.ts - MD types · Typed markdown import support for the plugin build.
src/opencode/md.d.ts - Agent sources · Source definitions for the six workflow roles.
agents - Commands · User-facing shortcuts for proposing, applying, syncing, and archiving changes.
.opencode/commands - 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 · Verifies agent definitions and plugin metadata stay aligned.
validation/validate_agents.py - Verify agents · Node-based validation for agent packaging consistency.
scripts/verify-agents.mjs - CI workflows · Build, plugin validation, PR title checks, and release automation.
.github/workflows
Documentation
Operational and architectural guidance for the workflow.
- README · Primary operational overview and workflow contract.
README.md - Getting started · Practical onboarding for the workflow toolkit.
getting-started.md - ADR · Architecture decisions for the repository itself.
doc/adr/0001-record-architecture-decisions.md - Repo spec · Higher-level specification for the repository's pipeline evolution.
doc/spec/001-generic-pipeline-migration.md
Connections 27
- 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.