From Manual Commands to Intent-Driven Maintenance: The Agentic Workflow

#agents #ai #automation #llm

Here's a maintenance loop that every wiki eventually produces.

A source document gets updated. The wiki page derived from it goes stale. You run synthadoc ingest to reprocess the file. You wait. You run lint to check if the page passes quality checks. You wait again. If it passes, lint promotes it to active. If it doesn't, you diagnose the issue and repeat. Now multiply that by twelve stale pages.

It's a well-defined sequence. It's also tedious — each step blocks on the previous one, you have to stay present for the whole thing, and the surface area for forgetting a step is real.

Synthadoc v1.2 ships an agentic maintenance workflow that replaces this loop with a single prompt.

What the agent actually does

When you send "re-ingest stale pages," the ActionAgent doesn't just parse your intent and hand it to a fixed function. It runs a tool-call loop: the model emits a structured tool call, the agent executes it, returns the result to the model, and the model decides what to call next. This continues until the model produces a plain-text summary with no pending tool calls.

For the stale-page workflow, the sequence looks like this:

find_stale_pages : returns every stale page with its source file path
confirm : sends a confirmation request to the UI listing the scope; blocks until you approve or decline
ingest_source (×N) : force-reingests one source at a time, polling until each job reaches a terminal state
run_lint : enqueues a full lint pass
poll_job : waits for the lint job to complete
get_page_states : checks the final lifecycle state of every reingested page
Plain-text summary with every outcome, lint result, and page states

The model drives all of it. If one ingest fails mid-workflow, the agent continues with the remaining pages and reports the failure in the summary. No hardcoded branching, the failure handling comes from the system prompt the model operates under.

The confirmation gate

The confirm tool is not a courtesy. Before the agent writes anything, it sends a confirm_request event to the UI carrying the full scope — which pages, which source files — and blocks until you respond. The 120-second timeout defaults to declined rather than approved.

This matters because "re-ingest stale pages" and "re-ingest all pages, including ones I deliberately left stale" look identical to a system without a confirmation step. The gate keeps you in control of what gets rewritten.

Real-time progress

A workflow that takes three minutes and shows output only at the end feels like it hung. The agentic workflow emits tool_progress SSE events at each tool step — "Re-ingesting: alan-turing.md", "Ingest running... (7s)", "✓ alan-turing re-ingested", "Running lint check..." — so the UI stays live throughout.

The same events surface in the Obsidian plugin's query modal. After the workflow completes, the web UI pre-fills the chat textarea with the logical next action — "Run lint to promote re-ingested pages" — so the next step is one click, not a typed command.

Works from anywhere

The same agentic loop runs regardless of where you initiate it:

Web UI: type the prompt in the chat interface, watch progress stream in. Or from the knowledge graph, right-click any stale page node and trigger a per-slug reingest directly from the graph view
CLI: synthadoc query "re-ingest stale pages" runs the same agent, same confirmation prompt, same result

The CLI path surfaces tool_progress events as terminal lines and handles the confirm gate interactively with a [Yes/Cancel] prompt, so the workflow is fully usable without a browser.

Pluggable by design

The workflow is built on an abstract interface: AgenticWorkflow declares build_system_prompt(), build_initial_message(), and get_tool_fns(). The loop machinery — tool dispatch, result injection, termination detection, the 30-call limit, the confirmation timeout — lives in the action agent and is inherited by every workflow.

Adding a new workflow means implementing three methods and writing a system prompt. The existing infrastructure handles the rest.

See it running

The walkthrough below covers the full loop end to end: two stale pages, the confirmation gate, per-page ingest progress, lint auto-run, and the content snapshot diff in Obsidian showing exactly what changed between versions.

📺 Synthadoc Agentic Maintenance Workflow — YouTube

What we learned building this

System prompts are the policy layer. The rules governing the workflow — discover scope first, always confirm before writing, process pages one at a time, run lint after all ingests — live in the system prompt, not in code. When we needed to adjust the ordering for the per-slug path, it was four lines of text, not a code change.

Per-step progress makes everything feel faster. The actual duration doesn't change. The perceived latency does.

One failure shouldn't stop the batch. If a source file disappears between discovery and ingest, the workflow reports the failure and keeps going. Wiring that in from the start saved a real debugging session later.

Synthadoc CE v1.2.0 is open source. The agentic workflow, the pluggable interface, and the full SSE protocol are all in the repo.