Architecture Decisions

This page records the decisions that explain why the system is built this way. They are not universal truths; they are choices made for this personal learning project.

ADR-001: Separate the Main Agent and Specialized Agents

Decision: The coordinator coordinates, the coding assistant implements, and the research worker executes specialized domains.

Reason: A single agent with too many responsibilities becomes hard to audit. Separating roles makes permissions, context, tools, and failures easier to reason about.

Consequence: There are more pieces to maintain, but each piece is clearer.

ADR-002: Prefer CLI Tools Over Opaque Automations

Decision: Repeatable capabilities are implemented as small CLI scripts.

Reason: A CLI can be executed, tested, logged, and documented. A human can also use it when the agent fails.

Consequence: The system gains traceability, but each tool needs more documentation.

ADR-003: Write TOOL.md Before Code

Decision: Each new tool should have a technical specification before implementation starts.

Reason: The spec reduces ambiguity, improves the prompt given to the coding assistant, and makes it possible to review whether the result satisfies the request.

Consequence: Implementation starts a little later, but usually needs fewer corrections.

ADR-004: Use Skills as Activatable Context

Decision: Use SKILL.md and .agents/skills so agents know when and how to use a capability.

Reason: Context should not depend only on the user remembering to include it in every prompt.

Consequence: Skills become part of the maintenance contract.

ADR-005: Persist Artifacts in Long Pipelines

Decision: The research framework writes intermediate artifacts by phase.

Reason: Long research tasks need checkpoints, traceability, and resumability.

Consequence: There are more files, but the system becomes easier to audit.

ADR-006: Accept Partial Success

Decision: succeeded_partial is a valid state.

Reason: In real research, some sources fail or return incomplete data. The system should produce useful results without hiding degradation.

Consequence: Reports must explain limitations and coverage.

ADR-007: Require Documentation in Templates

Decision: New repositories start with AGENTS.md and docs/.

Reason: Agent context and technical documentation are infrastructure, not final chores.

Consequence: Projects start with more structure, but scale better.

ADR-008: Make Context Boundaries Explicit

Decision: Prompts, skills, memory files, worker queues, and CLI tools should declare what context they consume and what artifacts they produce.

Reason: Clear boundaries make it easier to audit behavior, reproduce workflows, and identify which component is responsible when a result changes.

Consequence: The system requires more explicit contracts, but failures and handoffs become easier to reason about.

ADR-009: Put External Providers Behind Adapters

Decision: External research services are accessed through adapters instead of being hardcoded into agent logic or pipeline phases.

Reason: Provider adapters improve replaceability, testing, and traceability. The agent asks for research through a stable boundary, while the provider-specific implementation remains isolated.

Consequence: External research becomes another callable capability. The adapter adds a small integration layer, but it keeps provider changes from spreading through the worker or research pipeline.