\n\n# EngineeringTeam\n\n[](https://github.com/daeon/EngineeringTeam/actions/workflows/validate.yml)\n[](LICENSE)\n\n\n\n\n\n**Give your AI coding agent an expert software engineering team.**\n\nEngineeringTeam is a repo-first workflow layer that makes one coding agent operate like a coordinated panel of software engineering experts. For each task, a lead engineer frames the problem, selects the smallest useful set of specialists, gets them oriented on the repo and affected contracts, gates the decision with evidence, and only then makes the targeted implementation or hands back a diagnosis.\n\n> Stop asking one agent to guess. Give it the right expert panel, shared repo understanding, and an evidence gate before it edits.\n\n## ⚡ In thirty seconds\n\nMost coding agents are fast, but speed is not judgment. Real engineering work needs the right mix of skills: someone to map ownership, someone to test the contract, someone to challenge weak evidence, and domain specialists for security, performance, migration, architecture, or release risk when those risks are real.\n\nEngineeringTeam turns that team habit into a reusable skill that works across the agent you already use. It does not add a runtime service, network calls, or session-start magic. You invoke `engineering-team` when a task deserves expert coordination: it chooses the right panel, makes the panel understand the problem from source evidence, and produces compact, human-reviewable artifacts as it goes.\n\nWhen ambiguity itself is the first risk, EngineeringTeam can run an optional unknowns-first pre-intake pass before normal classification. That pass is for non-trivial ambiguous, risky, unfamiliar, architecture-sensitive, security-sensitive, production-impacting, or assumption-heavy work. It stays lightweight and feeds the existing Intake, Alignment, Evidence, Gate, Run Ledger, and Final Report artifacts.\n\nThat panel can deliver a PR-ready implementation, a read-only diagnosis, a repo map, a hypothesis matrix, a log report, a performance probe plan, or a handoff for another session. The point is not “change code” versus “understand code.” The point is: assemble the right experts, establish shared understanding, then make the smallest safe move.\n\nRead-only mode means **no edits**; it does not mean low rigor. Trivial local explanations can use L0, while broad codebase analysis, root-cause work, performance analysis, protected-boundary review, migration review, release planning, and multi-component PR review still use L2-L5 depth according to complexity and risk.\n\nUse `engineering-team` in handoff mode when you want the current task transferred to another agent or a fresh session. It compacts the work into a continuation document with decisions, evidence, open questions, artifact links, suggested skills, and next actions.\n\nSpecialist routing is mandatory for non-trivial work when the harness supports subagents. EngineeringTeam does not spawn a fixed committee; it forms the smallest expert panel that covers the task's distinct risks, then routes those selected specialists through bounded subagents.\n\n## 🧠 How it works\n\n```mermaid\nflowchart LR\n request[User request] --> ambiguity{Ambiguity risky?}\n ambiguity -->|Optional| unknowns[Unknowns-first pre-intake]\n ambiguity -->|No| lead{Lead engineer intake}\n unknowns --> lead\n\n lead --> mode{Outcome needed?}\n mode -->|Fix / feature / refactor| impl[Implementation mode]\n mode -->|Understand / debug / logs / perf| analysis[Read-only analysis mode]\n mode -->|Continue elsewhere| handoff[Handoff mode]\n\n impl --> panel[Select expert panel]\n analysis --> panel\n panel --> depth[Assign L0-L5 depth]\n\n depth --> atlas[Repo Atlas]\n atlas --> brief[Component Brief]\n brief --> contracts[Contract Graph]\n contracts --> evidence[Evidence Ledger]\n evidence --> gate{Implementation Gate}\n gate -->|Pass| patch[Small safe patch]\n gate -->|Read-only| report[Diagnosis / report / next probes]\n patch --> verify[Verification Report]\n report --> closeout[Run Ledger / Context GC]\n verify --> closeout\n\n handoff --> capsule[Continuation document]\n```\n\n## 🧭 Pick the right workflow\n\n| I need to... | Use | Typical output |\n|---|---|---|\n| Fix, implement, refactor, or prepare a PR | `engineering-team` | Lead + implementation + verification experts; Repo Atlas → Component Brief → Contract Graph → Evidence Ledger → Implementation Gate → Verification Report → Final Report |\n| Understand an unfamiliar repository | `engineering-team` read-only codebase route | Lead + codebase investigator; component map, call paths, contracts, findings, confidence, unknowns |\n| Investigate a bug without patching yet | `engineering-team` read-only debugging route | Lead + debugging/evidence/test panel; hypothesis matrix, supporting/counter evidence, falsifying probes, fix readiness |\n| Analyze logs or noisy failure output | `engineering-team` read-only log route | Lead + log forensics lens; timeline, signals, findings, redactions, ruled-out claims, next probes |\n| Investigate latency, throughput, memory, or locking | `engineering-team` read-only performance route | Lead + optimization/verification experts; measurement frame, hot-path map, bottleneck hypotheses, probe-first recommendations |\n| Transfer work to another agent or fresh session | `engineering-team` handoff route | Continuation document with decisions, evidence, risks, suggested skills, and next actions |\n\nThe main `engineering-team` skill is the lead engineer. It decides whether the task needs implementation, read-only analysis, or handoff, then assembles the right panel around the risk: codebase investigation, debugging forensics, log forensics, performance, security, architecture, migration, release, verification, evidence skepticism, or advisory review. If an investigation uncovers a likely fix, the agent should hand off an evidence-backed diagnosis and verification strategy before editing unless you explicitly ask it to implement.\n\n### L0 fast path boundary\n\nUse L0 only for trivial local explanation, simple summary, or obvious one-file inspection with no cross-file, behavior, contract, performance, migration, release, production, or protected-boundary claims. Read-only investigations are classified by depth, not by edit posture.\n\nUnknowns-first is skipped for tiny obvious work. It is a pre-intake aid, not a second router; `engineering-team` still owns routing and `references/intake-risk.md` still owns final autonomy and risk mode.\n\n## 🧪 One agent vs an expert engineering team\n\n| A lone coding agent often does this | EngineeringTeam makes it work like a team |\n|---|---|\n| Guesses which file to edit | Lead engineer routes a codebase investigator to find ownership and the call path |\n| Explains after the patch | Evidence skeptic forces claims to be backed before the patch |\n| Treats tests as optional cleanup | Verification engineer defines proof before implementation |\n| Changes behavior without tracing consumers | System/design lens builds a contract graph for behavior changes |\n| Misses domain-specific risk | Security, performance, migration, release, or architecture experts join only when relevant |\n| Dumps long reasoning or loses context | The team returns compact, reviewable artifacts and handoff capsules |\n\n## 📏 The team rule\n\nNo non-trivial edit or broad read-only claim until the agent has mapped the relevant repo context, named the affected contract or uncertainty, tied its recommendation to evidence, and described verification or next probes. The canonical gate details live in [`skills/engineering-team/SKILL.md`](skills/engineering-team/SKILL.md) and [`skills/engineering-team/references/implementation-gate.md`](skills/engineering-team/references/implementation-gate.md); this README keeps the public promise short.\n\n## 🛑 When your agent should not edit yet\n\nHold off on editing when the root cause, owning component, call path, affected contract, evidence, or verification path is still unclear. Let EngineeringTeam keep mapping, probing, or challenging assumptions instead of patching prematurely.\n\n## 🚀 Quick start\n\n```bash\ngit clone https://github.com/daeon/EngineeringTeam\ncd EngineeringTeam\npython3 scripts/doctor.py\nnpm run validate\n```\n\nThen, in your coding agent:\n\n```text\nUse engineering-team to investigate this bug. Pick the right expert panel, make the panel map the repo and affected contracts first, then propose the smallest safe fix with verification.\n```\n\nFor read-only analysis:\n\n```text\nUse engineering-team in read-only analysis mode to understand this repository. Assemble the right analysis panel, map the main components and contracts, and return an evidence-backed report without editing files. Assign L2-L4 depth based on breadth; do not classify broad analysis as L0.\n```\n\nTo transfer work to another agent or session:\n\n```text\nUse engineering-team in handoff mode to summarize this task for a fresh agent. Focus the next session on finishing verification and preparing the PR.\n```\n\n## 🧑💻 Expert panel routing\n\n```mermaid\nflowchart TD\n risk[Intake risk] --> route{Which experts are needed?}\n\n route -->|Unknown ownership| investigator[Codebase Investigator]\n route -->|Protected boundary| security[Security Analyst]\n route -->|Public API/module boundary| architect[System Design Architect]\n route -->|Latency / memory / throughput| perf[Optimization Engineer]\n route -->|Weak evidence| skeptic[Evidence Skeptic]\n route -->|No| lead[Lead Engineer only]\n\n investigator --> capsule[Context capsule]\n security --> capsule\n architect --> capsule\n perf --> capsule\n skeptic --> capsule\n capsule --> lead\n lead --> decision[Evidence-backed decision]\n```\n\nSpecialists receive bounded briefs and return compact context capsules, not transcripts. The lead engineer stays responsible for the final decision and only brings in experts that cover distinct risks.\n\n## 🎬 Demo\n\nSee the worked, runnable example and the talking points:\n\n- `examples/buggy-python-service/` — a small service with a real bug, the raw-agent prompt, the EngineeringTeam prompt, and filled-in expected artifacts.\n- `docs/demo-script.md` — 60-second and 5-minute demo scripts, plus a lone-agent vs expert-team comparison.\n- `docs/prompt-cards.md` — copy-paste prompts for implementation, read-only codebase analysis, debugging forensics, log forensics, performance forensics, protected-boundary review, migration, release, architecture, test strategy, and handoff.\n\n## 🔌 Supported harnesses\n\n| Harness | Reads | Status |\n|---|---|---|\n| Claude Code | `.claude-plugin/plugin.json`, `agents/*.md`, `skills/` | Supported |\n| Codex | `.codex-plugin/plugin.json`, `.codex/agents/*.toml`, `skills/` | Supported |\n| Cursor | `.cursor-plugin/plugin.json`, `agents/*.md`, `skills/` | Supported |\n| Gemini CLI | `gemini-extension.json`, `GEMINI.md`, `AGENTS.md` | Supported |\n| OpenCode | `.opencode/plugins/engineering-team.js` | Supported |\n| GitHub Copilot | `.github/agents/*.md` | Experimental |\n\nAll harnesses point at the same canonical skill bundle under `skills/`. `skills/engineering-team/SKILL.md` is the only discoverable skill; focused route references inside that bundle provide the read-only and handoff procedures. Native agent definitions are generated from one source of truth (`agents-src/*.yaml`) — see `docs/harness-support.md`.\n\n## 🗂️ Artifact gallery\n\nEngineeringTeam makes the expert panel produce compact, reviewable artifacts before and after implementation or investigation:\n\n| Artifact | What it proves | Example |\n|---|---|---|\n| Repo Atlas | The agent understands the repo shape, entry points, tests, generated-code rules, and risky areas | [`repo-atlas.md`](examples/buggy-python-service/expected-artifacts/repo-atlas.md) |\n| Component Brief | The agent found the owner, key files, symbols, call path, inputs, outputs, and side effects | [`component-brief.md`](examples/buggy-python-service/expected-artifacts/component-brief.md) |\n| Contract Graph | The agent traced producer, contract/data shape, consumer, failure mode, coverage, and risk | [`contract-graph.md`](examples/buggy-python-service/expected-artifacts/contract-graph.md) |\n| Evidence Ledger | Major claims are backed by source paths, tests, logs, runtime observations, schemas, or docs | [`evidence-ledger.md`](examples/buggy-python-service/expected-artifacts/evidence-ledger.md) |\n| Verification Report | Success was checked and residual risk was reported instead of assumed away | [`verification-report.md`](examples/buggy-python-service/expected-artifacts/verification-report.md) |\n| Run Ledger | Risky or handoff-heavy runs have a task-scoped trace of route decisions, evidence, probes, verification, and residual risk | `templates/run-ledger.md` |\n| Memory Candidates | Reusable findings are separated from task-only run details before promotion to repo memory | `templates/memory-candidates.md` |\n| Codebase Analysis Report | Read-only analysis produced scope, component map, call paths, contracts, findings, confidence, and unknowns | `engineering-team` codebase route output |\n| Debugging Hypothesis Matrix | Bug work is ranked by evidence, counter-evidence, falsifying probes, and fix readiness | `engineering-team` debugging route output |\n| Log Forensics Report | Logs become a timeline with signals, findings, redactions, ruled-out claims, and next probes | `engineering-team` log route output |\n| Performance Forensics Report | Performance work starts with a measurement frame, hot-path map, bottleneck hypotheses, and probes | `engineering-team` performance route output |\n| Handoff Document | Another agent or session can continue with decisions, evidence, open questions, risks, suggested skills, and next actions | `engineering-team` handoff route output |\n| Unknowns-First Route | Ambiguous or risky tasks expose assumptions before intake, then map findings into existing artifacts | `references/unknowns-first/router.md` |\n\nThese make the team's reasoning inspectable: a reviewer can see which experts were needed, what they understood about the code path, and why the resulting diff or diagnosis is trustworthy.\n\n## 📦 Install\n\n`python3 scripts/install.py --target ` is the single entry point. Two targets **copy files**; the rest **print the exact manual setup steps** for their marketplace / extension / plugin model (nothing is copied).\n\n| Harness | What `install.py` does | Mechanism |\n|---|---|---|\n| Codex | Copies `.codex/agents/*.toml` into the project or user config | File copy (idempotent; `--force` to overwrite) |\n| GitHub Copilot | Copies `.github/agents/*.md` into the target repo | File copy (idempotent; `--force` to overwrite) |\n| Claude Code | Prints the local-marketplace commands to run | `/plugin marketplace add .` |\n| Cursor | Prints the local plugin-source steps | Reads `.cursor-plugin/plugin.json`, `skills/`, `agents/` |\n| Gemini CLI | Prints the extension install command | `gemini extensions install .` |\n| OpenCode | Prints the plugin path + points to `.opencode/INSTALL.md` | Loads `.opencode/plugins/engineering-team.js` |\n\n### Codex custom agents (file copy)\n\n```bash\npython3 scripts/install.py --target codex --scope project --repo .\n# or globally:\npython3 scripts/install.py --target codex --scope user\n```\n\n### GitHub Copilot custom agents (file copy)\n\n```bash\npython3 scripts/install.py --target github --scope project --repo /path/to/repo\n```\n\n### Claude Code (local marketplace)\n\n```bash\n/plugin marketplace add .\n/plugin install engineering-team@engineering-team-dev\n```\n\n### Cursor / Gemini CLI / OpenCode (manual setup — prints steps, copies nothing)\n\n```bash\npython3 scripts/install.py --target cursor --scope project --repo .\npython3 scripts/install.py --target gemini --scope project --repo .\npython3 scripts/install.py --target opencode --scope project --repo .\n```\n\nGemini CLI installs as an extension:\n\n```bash\ngemini extensions install .\n```\n\nFile-copy installs (Codex, GitHub) are idempotent: existing files are skipped unless you pass `--force`.\n\n## Keeping main context clean\n\nEngineeringTeam uses the main agent as the Lead Engineer. For non-trivial L2+ work on harnesses with subagent support, selected specialists are delegated to subagents. A typo/formatting-only L2 edit may remain in the main session but still passes a compact Implementation Gate. Specialists receive bounded briefs and return compact context capsules, not transcripts. This keeps the main session focused on expert routing, evidence, decisions, implementation gates, and final handoff.\n\n## ✅ Validation\n\n```bash\nnpm run validate\npython3 scripts/doctor.py\n```\n\n`npm run validate` runs the same checks as CI: JSON manifests, TOML agents, generated-agent drift including stale generated files, version consistency, OpenCode JS syntax, package structure, no session-start hook regression, memory contracts, and the worked example test suite. The same command runs in GitHub Actions via `.github/workflows/validate.yml`.\n\n## 📚 Documentation\n\n- `docs/routing-matrix.md` — when to use the fast path, normal EngineeringTeam routing, or optional unknowns-first.\n- `docs/unknowns-first-integration.md` — how the gapfinder-style layer maps into EngineeringTeam artifacts.\n- `docs/examples/unknowns-first-fused-workflow.md` — compact example of unknowns-first fused into normal gates.\n\nFull docs page: https://github.com/daeon/EngineeringTeam/tree/main/docs\n\n- `docs/design.md` — architecture, design principles, harness boundaries, and adoption model.\n- `docs/why-engineeringteam.md` — product value, target users, positioning.\n- `docs/getting-started.md` — install, first prompts, expected outputs.\n- `docs/workflow.md` — public workflow rationale and links to canonical skill/reference files.\n- `docs/specialists.md` — public specialist role catalog with links to canonical routing guidance.\n- `docs/harness-support.md` — per-harness packaging notes.\n- `docs/demo-script.md` — demo scripts and comparison.\n- `docs/prompt-cards.md` — copy-paste prompts by task type.\n\n## 🤝 Contributing\n\nSee `CONTRIBUTING.md` for how to edit agent sources, regenerate native agents, and validate changes. Security posture is documented in `SECURITY.md`. Planned work is in `ROADMAP.md`.\n\n## ⚖️ License\n\nMIT License. See `LICENSE`.\n",
"bytes": 19313,
"sha": "7cf6bd5935b12bbd0069750db406b50a2970153dfc7d882292ccbd10a5a9604f",
"repo_slug": "daeon/engineeringteam",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_daeon_engineeringteam_535c2112/readme"
}
![\"EngineeringTeam](\"docs/assets/engineering-team-hero-light.svg\")
\n