Architecture Decisions

Architecture Decision Records (ADRs) document significant technical decisions made during the development of DevSquad Copilot. Each records the context, priorities, options evaluated, and the chosen decision with trade-offs.

ADR 0011 is now historical context. ADR 0012 documents the current nested sub-agent architecture.

ADR 0001: Agent Orchestration Accepted

Problem: Coordinate 10+ specialized agents across distinct delivery phases.

Priorities: (1) Failure resilience, (2) Low maintenance, (3) Usage flexibility, (4) Cross-phase context.

Decision: Conductor (Mediated Coordinator-Worker) with dual-mode. Central conductor has no domain logic, delegates to specialists. If conductor fails, agents remain accessible directly.

Trade-off: Higher token overhead and latency vs simpler patterns. Gains failure resilience and independent agent accessibility.

ADR 0002: Communication Protocol Accepted

Problem: Sub-agents must function in two modes (via conductor and direct) without code duplication.

Decision: Prefix protocol with structured actions. [CONDUCTOR] prefix detection triggers structured output ([ASK], [CREATE], [BOARD], [CHECKPOINT], [DONE]). Single codebase handles both.

Trade-off: Sub-agents need dual output format handling.

ADR 0003: Context Management Accepted

Problem: Assumptions from one phase contaminate subsequent phases.

Decision: Disk artifacts + Handoff Envelope. Each phase starts with clean context, reads from disk. Explicit transfer via envelope with inherited assumptions, pending decisions, discarded info.

Trade-off: Token cost to re-read files. Gains isolation, persistence (git), and auditability.

ADR 0004: Activation Model Accepted

Problem: Distribute knowledge without overloading agent context.

Decision: Differentiated model. Instructions (deterministic glob, fewer than 50 lines), Skills (semantic, 50–200 lines), Agents (explicit, more than 200 lines), Hooks (event-triggered, zero LLM cost), MCP Servers (tool calls).

Trade-off: Greater cognitive complexity for extension authors. Mitigated by decision tree and devsquad.extend.

ADR 0005: Socratic AI Accepted

Problem: AI-assisted development risks passive automation and knowledge debt.

Priorities: (1) Knowledge transfer, (2) Speed for experienced, (3) Decision quality, (4) Traceability.

Decision: Adaptive Socratic approach. Low-impact tasks are fast-tracked. High-impact tasks require comprehension checkpoints with Socratic questions.

Trade-off: Lower initial speed perception. Better long-term velocity through reduced rework and knowledge retention.

ADR 0006: Estimation and Risk Management Accepted

Problem: Numerical estimates (story points, hours) don’t reveal uncertainty or generate actions.

Decision: Complexity analysis by unknown work. Separate known work from risks. 2-3 scenarios with trade-offs. High/Medium/Low risk classification.

Anti-patterns: Number without justification, ignoring risks, single scenario as “the solution”, false confidence.

ADR 0007: Work Decomposition Accepted

Problem: Without defined structure, decompositions follow inconsistent criteria.

Decision: Mandatory phases. Setup, Foundational, User Stories (P1/P2/P3), Polish. Within each story: Models, Services, Endpoints, Integration. Tasks marked [P] when parallelizable.

ADR 0008: Testing Strategy Accepted

Problem: Separate test tasks create board bloat and postpone testing to the end.

Decision: Tests integrated as acceptance criteria. No separate test tasks. Task only “Done” when code + tests are ready.

ADR 0009: Developer Capacity Accepted

Problem: Developers accumulate in-progress tasks. AI lowers the perceived cost of starting new work.

Decision: One task at a time with soft limit of 3 in-progress. Warning signal, not a hard block.

ADR 0010: Agent Tool Extension Proposed

Problem: Consumers need to inject MCP tools into plugin agents. Plugin tools: is static after install.

Decision: Agent overlay generation via sync script. Consumer YAML patches merged with plugin agents. sessionStart hook detects staleness.

ADR 0011: Sub-Agent Nesting Resolution Superseded

Problem: Earlier GitHub Copilot releases limited sub-agent nesting to 1 level, which blocked conductor to specialist to worker chains.

Decision: Convert L2 sub-agents to skills as a temporary workaround. Standalone agent files remained available for direct invocation.

Trade-off: Guided mode worked within the platform limit, but worker isolation and parallel execution were deferred.

ADR 0012: Nested Subagent Architecture Proposed

Problem: The framework had monolithic hotspot agents for plan, implement, and review, even after native nested sub-agent support became available.

Decision: Use coordinator + worker patterns for complex agents. plan, implement, review, and refine delegate to focused worker sub-agents with isolated context and parallel fan-out where tasks are independent.

Trade-off: More agent files and orchestration logic in exchange for cleaner context boundaries, lower bias during validation, and lower latency for independent checks.

ADR 0013: Harness Learnings Proposed

Problem: Agents repeat the same self-correction loop session after session because there is no mechanism to capture and consult codebase-specific operational knowledge across sessions.

Priorities: (1) Zero-friction capture, (2) Immediate availability, (3) Whole-lifecycle coverage, (4) Self-curation, (5) Path to durability, (6) Low context cost, (7) Consistency with existing patterns.

Decision: Store learnings in .memory/harness-learnings.md (workspace-local, structured markdown) via a new harness-learnings skill. Two-tier lifecycle: Tier 1 captures with confidence scoring and auto-pruning; Tier 2 promotes proven learnings to permanent harness controls (instructions, hooks, skill amendments) via devsquad.extend.

Trade-off: Workspace-local file means learnings do not automatically propagate across team members; the Tier 2 promotion path is the mechanism for sharing. Accepted in exchange for zero-friction capture and immediate availability without release cycles.

ADR 0014: Agent Intent Governance Accepted

Problem: Framework agents had no declared behavioral envelope; consumer specs describing AI-agent capabilities had no template fragment for the same; failures accumulated as prompt patches rather than structural amendments.

Priorities: (1) Preserve the existing SDD spine (no phase rename), (2) Close the agent-class governance gap both internally and externally, (3) Avoid ceremony for non-agent specs, (4) Keep changes additive and non-breaking, (5) Make failures diagnosable by upstream artifact.

Decision: Selective adoption from “The Architecture of Intent” (Marcel Aldecoa). ## Behavioral Constraints body section on user-facing agents (rules tools: cannot enforce). ## Composition body section with cross-component invariants on coordinators. Spec Evolution Log in feature and migration spec templates. Gated AI Cost Posture block in the feature spec template (model-tier, latency budget, prompt stability, cost ceiling, escalation) for specs that embed AI behavior. Three-category upstream-artifact failure taxonomy (spec, validation, agent) in debugging-recovery.

Trade-off: Imports the load-bearing AoI principles for agent-class governance without adopting the four AoI signal metrics, custom frontmatter scalars, pattern taxonomy, or phase rename. Non-agent specs are unaffected.