Writer Agent¶

Thinklio Built-in Agent Specification Version 0.1 | March 2026

1. Purpose and Problem Statement¶

The Writer Agent is a consumer-and-producer agent. It consumes a structured source list from the Research Agent (or other structured input) and produces a written draft. It does not retrieve sources, verify facts, or make layout decisions — those belong to the Research Agent, Fact Checker, and Report Writer respectively.

Its core responsibility is synthesis: taking structured material and producing coherent, appropriately voiced prose in a defined format.

The Writer Agent must handle two distinct voice concerns:

Org voice — the tone, style, and personality of the organisation publishing the content. This is workspace-level configuration and applies consistently across all content produced under that org.
User voice — the individual author's style, where the content is attributed to or ghostwritten for a specific person. This may override or modulate org voice in defined ways (e.g. a CEO's newsletter column sounds like the CEO, within the org's broader register).

These are not mutually exclusive. Most content will use org voice. Some will layer user voice on top. The configuration model must support both.

2. Position in the Pipeline¶

Research Agent  →  [Writer Agent]  →  Fact Checker  →  Report Writer

The Writer Agent receives a SourceList (or multiple) and produces a Draft. It may be invoked multiple times within a single pipeline run — once per section, for example — with outputs assembled by a coordinator agent.

3. Invocation Modes¶

Programmatic (agent-to-agent) A coordinator passes a source list, format template, section brief, and voice configuration. The Writer Agent returns a structured draft. No UI is shown unless the coordinator requests a progress view.

Standalone (user-initiated) A user opens the Writer Agent directly, pastes or selects a source list, configures voice and format, and receives a draft they can review and save.

4. Configuration¶

4.1 Admin Configuration¶

Setting	Description
Org voice profile	Workspace-level style guide: tone descriptors, prohibited language, preferred constructions, reading level target, example passages
Default language	BCP 47 tag for output language
Max output tokens	Hard ceiling on generated content length per run
Permitted models	Which underlying LLM(s) the Writer Agent may use

4.2 Run-time Parameters¶

Parameter	Type	Description
`source_list`	SourceList \| SourceList[]	One or more source lists from the Research Agent. If multiple, the writer draws across all.
`section_brief`	string	Instructions for this specific piece: what to cover, what to emphasise, what to exclude.
`format_template`	reference \| inline	A named format template or inline format spec. See section 5.
`voice`	enum	`org`, `user`, or `org_with_user_modulation`.
`user_voice_profile`	reference	If voice includes user, a reference to the user's voice profile.
`word_limit`	integer	Target word count. Treated as a soft limit with a ±10% tolerance.
`heading_style`	enum	`none`, `minimal`, `structured`. Controls whether the output includes headings.
`image_placeholders`	boolean	If true, the writer inserts `{{IMAGE: description}}` tags where visuals would strengthen the piece.
`language`	string	BCP 47 tag. Defaults to admin setting.
`output_format`	enum	`markdown`, `plain`. Default: `markdown`.
`save_to`	reference	Optional record to attach the draft to.

5. Format Templates¶

A format template defines the structural expectations for the output. Templates are created and managed in the workspace and referenced by name.

A template specifies:

Sections — ordered list of named sections with individual word limits and tone notes
Required elements — e.g. "must include a call to action", "must open with a hook"
Prohibited elements — e.g. "no bullet lists in body copy", "no rhetorical questions"
Reading level — target Flesch-Kincaid grade or equivalent descriptor
Citation style — how sources are referenced inline (footnote, hyperlink, author-date, none)

Example template definition (stored as structured data, shown here for clarity):

template: newsletter_main_feature
sections:
  - name: hook
    words: 80–120
    tone: conversational, surprising
  - name: body
    words: 400–600
    tone: informative, org voice
  - name: closing
    words: 60–80
    tone: forward-looking, warm
required: [hook, call_to_action]
prohibited: [bullet_lists_in_body, rhetorical_questions]
reading_level: grade_10
citation_style: hyperlink

6. Voice Profiles¶

Org Voice Profile¶

Defined at workspace level by an admin. Includes: - Tone descriptors (e.g. "authoritative but approachable", "plain language preferred") - Prohibited words or phrases - Preferred constructions (e.g. active voice, second person) - One or more example passages the model uses as style anchors - Reading level target

User Voice Profile¶

Defined per user, optionally. Includes: - Sample writing (uploaded or pasted) from which a style fingerprint is derived - Explicit style notes (e.g. "uses short sentences", "favours rhetorical questions", "often opens with an anecdote") - Deference rules — which org voice constraints the user voice may override (e.g. reading level is fixed; bullet list preference may be overridden)

Voice Resolution¶

When voice: org_with_user_modulation, the system applies org voice as the base and overlays user voice preferences within the bounds of the deference rules. Conflicts are resolved in favour of org voice unless the deference rule explicitly permits override.

7. Image Placeholders¶

When image_placeholders: true, the Writer Agent inserts structured tags at points where an image would strengthen the content:

{{IMAGE: alt="Chart showing growth trend" suggestion="Line chart of key metric over 12 months" placement="after_paragraph_2"}}

These tags are: - Preserved in markdown output for downstream handling - Rendered as visible placeholder blocks in the Report Writer UI - Replaceable by a user or a future Image Agent with an actual asset reference

The writer does not source or generate images. It only suggests where they belong and what they should convey.

8. Output Structure¶

The Writer Agent returns a Draft object:

Draft
├── draft_id            UUID
├── source_list_ids     UUID[]
├── format_template     string
├── voice_applied       string
├── language            string
├── word_count          integer
├── generated_at        timestamp
├── sections[]
│   ├── section_id      UUID
│   ├── name            string
│   ├── content         string (markdown or plain)
│   └── word_count      integer
└── image_placeholders[]
    ├── tag             string
    ├── suggestion      string
    └── placement       string

The full assembled content is also available as a flat content field for downstream agents that do not need section-level structure.

9. User Interface¶

9.1 Configuration Screen¶

Source input: select from saved source lists or paste a Research Agent output reference
Section brief: multiline text field
Format template: dropdown of workspace templates, with a preview pane
Voice: segmented control (Org / User / Org + User)
User voice profile: shown only if voice includes user; dropdown of saved profiles
Word limit: numeric input
Image placeholders: toggle
Language: dropdown
Output format: segmented control (Markdown / Plain)
Save to: optional record picker

9.2 Progress View¶

Status messages ("Analysing sources…", "Writing section 2 of 3…")
Cancel button

9.3 Draft Review View¶

Full rendered preview of the draft with section boundaries visible
Section-level controls: regenerate individual section, adjust word count, change tone note
Image placeholder blocks shown inline with suggestion text
Source attribution panel: shows which sources were drawn on for each section
Actions: approve and save, send to Fact Checker, export as markdown, edit manually
Word count summary vs. target

10. Data Model Integration¶

Data Object	Interaction
Note	Draft saved as a Note, attached to any record
Task	Writing task can be tracked as a Task with draft as attachment
Item	Draft in response to an enquiry or support item
Organisation	Org voice profile stored against the Organisation record
Person	User voice profile stored against the Person record

11. Use Cases¶

UC-1: Pipeline write from research¶

A coordinator passes a facts_list source list, a newsletter_main_feature template, org voice, and a section brief. The Writer Agent produces a structured draft with image placeholder suggestions. The coordinator passes the draft to the Fact Checker.

UC-2: Ghostwritten column¶

A user invokes the Writer Agent standalone. They select a source list, choose org_with_user_modulation, select their voice profile, and set a 500-word limit. The agent produces a column in their voice, within org style guidelines.

UC-3: Multi-section assembly¶

A coordinator invokes the Writer Agent three times — once per newsletter section, each with a different source list and section brief. The three drafts are returned and assembled into a single document by the coordinator before passing to the Fact Checker.

UC-4: Responsive item reply¶

A user opens an Item (enquiry) and initiates a Writer Agent run from within it. The agent draws on a source list already attached to the Item and produces a sourced reply draft in org voice.

12. Open Questions¶

Should the Writer Agent be able to draw on multiple source lists from different source_type runs, or should the coordinator always pre-merge them via the Data Agent?
User voice profile derivation from sample writing — is this done once at profile creation, or re-derived on each use? Re-derivation is more accurate but slower.
Should section-level regeneration in the UI submit a new API call per section, or is the whole draft resubmitted with a constraint? The former is cheaper; the latter produces more coherent output.
How are inline citations rendered when citation_style: none is set but the Fact Checker needs to trace claims back to sources? A hidden source map may be needed in the output object even when citations are not shown to the reader.

Previous: Research Agent | Next: Fact Checker Agent