System Architecture
The pipeline is four agents plus shared editorial context. Each stage produces an artifact that the next stage consumes.
Source Layer
A sources.json with twenty source URLs plus five style references. Each source has a role field (vendor_docs, vendor_launch, pricing_page, competitor_critique, category_authority, community_discussion) that determines extraction depth, attribution rules, and how aggressively to weight its claims. A roles.jsonlookup encodes the universal source-handling rules so the extraction agent doesn't have to reason about source treatment piece-by-piece.
| Agent | What it does |
|---|---|
| Extraction | Reads each source, returns structured claims with evidence references back to source location. Twenty sources produced 341 claims for this piece. Schema-driven so the comparison agent gets predictable shape. |
| Comparison | Two-pass: first pass synthesizes the matrix—dimensions, editorial tensions, detected asymmetries between products, narrative payloads. Second pass scores claims by composite weight (source authority × specificity × tension relevance) so the draft agent gets prioritized material instead of all 341 claims at equal weight. |
| Draft | Composition pass writes against the matrix, the piece brief, and the selected voice anchor. Voice anchor selection uses style_references metadata (genre, subject_domain, register, primary_voice_anchor); the piece brief declares matching fields; the agent selects on exact match with primary_voice_anchor: true as fallback. |
| Revision | Rereads the composed draft against the reader test (can the reader decide, explain the differentiation, name one strength of each?) and the anti-pattern list, then revises. Produces revision notes alongside the final draft—catches false balance, duplicated paragraphs, and voice drift the composer missed. |
Shared Editorial Context
A shared_rules.mdcarries universal principles: write to the question the reader is asking, lead with code when describing programming models, paraphrase third-party voices rather than quote, don't substitute marketing copy for technical specifics. A per-piece piece_brief.md carries angle, dimensions, editorial tensions, voice anchor declaration, and scope statements specific to those subjects.
Orchestration
A run.py wires the four agents together with --status, --skip-extract, --skip-compare, --skip-draft, and --no-review flags. Every piece-specific decision (sources, dimensions, voice) lives in its own piece configuration, not the agent code—so adding a new comparison only requires a new piece_brief.md and sources.