EngineeringTeam

Give your AI coding agent an expert software engineering team.

EngineeringTeam 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.

Stop asking one agent to guess. Give it the right expert panel, shared repo understanding, and an evidence gate before it edits.

Most 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.

EngineeringTeam 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.

When 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.

That 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.

Read-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.

Use 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.

Specialist 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.

flowchart LR
    request[User request] --> ambiguity{Ambiguity risky?}
    ambiguity -->|Optional| unknowns[Unknowns-first pre-intake]
    ambiguity -->|No| lead{Lead engineer intake}
    unknowns --> lead

    lead --> mode{Outcome needed?}
    mode -->|Fix / feature / refactor| impl[Implementation mode]
    mode -->|Understand / debug / logs / perf| analysis[Read-only analysis mode]
    mode -->|Continue elsewhere| handoff[Handoff mode]

    impl --> panel[Select expert panel]
    analysis --> panel
    panel --> depth[Assign L0-L5 depth]

    depth --> atlas[Repo Atlas]
    atlas --> brief[Component Brief]
    brief --> contracts[Contract Graph]
    contracts --> evidence[Evidence Ledger]
    evidence --> gate{Implementation Gate}
    gate -->|Pass| patch[Small safe patch]
    gate -->|Read-only| report[Diagnosis / report / next probes]
    patch --> verify[Verification Report]
    report --> closeout[Run Ledger / Context GC]
    verify --> closeout

    handoff --> capsule[Continuation document]

The 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.

Use 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.

Unknowns-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.

No 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 and skills/engineering-team/references/implementation-gate.md; this README keeps the public promise short.

Hold 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.

git clone https://github.com/daeon/EngineeringTeam
cd EngineeringTeam
python3 scripts/doctor.py
npm run validate

Then, in your coding agent:

Use 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.

For read-only analysis:

Use 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.

To transfer work to another agent or session:

Use engineering-team in handoff mode to summarize this task for a fresh agent. Focus the next session on finishing verification and preparing the PR.

flowchart TD
    risk[Intake risk] --> route{Which experts are needed?}

    route -->|Unknown ownership| investigator[Codebase Investigator]
    route -->|Protected boundary| security[Security Analyst]
    route -->|Public API/module boundary| architect[System Design Architect]
    route -->|Latency / memory / throughput| perf[Optimization Engineer]
    route -->|Weak evidence| skeptic[Evidence Skeptic]
    route -->|No| lead[Lead Engineer only]

    investigator --> capsule[Context capsule]
    security --> capsule
    architect --> capsule
    perf --> capsule
    skeptic --> capsule
    capsule --> lead
    lead --> decision[Evidence-backed decision]

Specialists 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.

See the worked, runnable example and the talking points:

• examples/buggy-python-service/ — a small service with a real bug, the raw-agent prompt, the EngineeringTeam prompt, and filled-in expected artifacts.
• docs/demo-script.md — 60-second and 5-minute demo scripts, plus a lone-agent vs expert-team comparison.
• 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.

All 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.

EngineeringTeam makes the expert panel produce compact, reviewable artifacts before and after implementation or investigation:

These 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.

python3 scripts/install.py --target <harness> 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).

python3 scripts/install.py --target codex --scope project --repo .
# or globally:
python3 scripts/install.py --target codex --scope user

python3 scripts/install.py --target github --scope project --repo /path/to/repo

/plugin marketplace add .
/plugin install engineering-team@engineering-team-dev

python3 scripts/install.py --target cursor --scope project --repo .
python3 scripts/install.py --target gemini --scope project --repo .
python3 scripts/install.py --target opencode --scope project --repo .

Gemini CLI installs as an extension:

gemini extensions install .

File-copy installs (Codex, GitHub) are idempotent: existing files are skipped unless you pass --force.

EngineeringTeam 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.

npm run validate
python3 scripts/doctor.py

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.

• docs/routing-matrix.md — when to use the fast path, normal EngineeringTeam routing, or optional unknowns-first.
• docs/unknowns-first-integration.md — how the gapfinder-style layer maps into EngineeringTeam artifacts.
• docs/examples/unknowns-first-fused-workflow.md — compact example of unknowns-first fused into normal gates.

Full docs page: https://github.com/daeon/EngineeringTeam/tree/main/docs

• docs/design.md — architecture, design principles, harness boundaries, and adoption model.
• docs/why-engineeringteam.md — product value, target users, positioning.
• docs/getting-started.md — install, first prompts, expected outputs.
• docs/workflow.md — public workflow rationale and links to canonical skill/reference files.
• docs/specialists.md — public specialist role catalog with links to canonical routing guidance.
• docs/harness-support.md — per-harness packaging notes.
• docs/demo-script.md — demo scripts and comparison.
• docs/prompt-cards.md — copy-paste prompts by task type.

See 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.

MIT License. See LICENSE.