System Architecture
Technical view of the ecosystem layers, repositories, flows, and boundaries.
The architecture is organized as a local layered system. Each layer has distinct responsibilities and communicates with the others through files, commands, skills, prompts, or MCP tools.
Layers
| Layer | Responsibility | Examples |
|---|---|---|
| Conversational | Interpret intent and coordinate actions | Coordinator Agent, Research Worker |
| Construction | Implement, review, and modify code | Coding Assistant |
| Tooling | Execute actions deterministically | Python CLIs, shell scripts |
| Context | Load local rules and knowledge | AGENTS.md, SKILL.md, .agents/skills |
| Memory | Preserve continuity across sessions | MEMORY.md, journals, notes |
| Orchestration | Split long tasks into phases | Research Framework |
| Artifacts | Persist verifiable results | phase.json, candidates.json, final_report.md |
| Operations | Diagnose and maintain the system | cheatsheets, audits, health checks |
Logical Source Areas
| Logical area | Role |
|---|---|
| Tooling Layer | Base toolkit, tool template, and background worker documentation. |
| Media Automation Tools | Search and media-management tools. |
| Research Framework | Structured phase-based research. |
| Project Templates | Repository starters with skills and docs. |
| Memory and Context | Agent memory, identity, and operating rules. |
| MCP Research Adapter | External research through Model Context Protocol. |
| Terminal Workflow Notes | Local operations and cheatsheets. |
| Audits | State reviews and known gaps. |
| Test Reports | Real or semi-real pipeline outputs used for documentation. |
Design Decisions
Separate Agents by Role
The coordinator does not try to do everything. It coordinates, decides, and preserves continuity. The coding assistant implements. The research worker specializes in research and media workflows. This separation reduces coupling and prevents one session from accumulating too many responsibilities.
Prefer Small CLI Tools
When a task is repeatable, it becomes a script. The agent does not need to reason from scratch every time; it only decides when to run the tool.
Write Intermediate Artifacts
Long pipelines do not depend on volatile memory. They write files with state and partial results, which makes the process easier to audit, resume, and debug.
Put External Research Behind an Adapter
The research pipeline can call an MCP-based external research adapter when a task needs broader source discovery or citation-oriented research. The adapter boundary keeps provider-specific behavior outside the pipeline phases. Perplexity can back this role in the current architecture, but it is one replaceable external capability, not a dependency for the whole system.
Treat Documentation as Part of the System
Documentation is not a final cleanup phase. New templates start with docs/, AGENTS.md, and update rules already in place.