Content-as-Code: A Git-Native Filesystem Architecture for Auctor

The Core Thesis

Claude Code is the most sophisticated file-manipulation agent ever built. It reads, writes, edits, searches, diffs, and versions files with precision that exceeds most human developers. Yet when applied to content creation inside Auctor, it is forced to operate through database abstractions that strip away every native advantage. Content lives in PostgreSQL rows. The agent's most powerful tools sit idle while every operation flows through MCP wrappers, HTTP round-trips, and SQL queries.

This document argues that content creation is structurally isomorphic to software development, and proposes an architecture where content lives on the filesystem under git version control — with PostgreSQL serving as a materialized view for the web UI rather than the source of truth.

The result: every git primitive becomes a content operation, and every capability that makes Claude Code exceptional at writing software transfers directly to creating, editing, reviewing, and publishing content.

1. The Problem: Database Rows Are the Wrong Abstraction

1.1 Current State

Auctor is a multi-agent content operations platform with substantial infrastructure already built:

• Desktop app (~90% complete): Full bootstrap sequence, SQLite store, Claude Code SDK integration with session management, MCP server bridge (14 tools), tool policy, scheduler with 4 cron cycles, file watcher, Next.js + Python sidecar management, IPC handlers (13/15 implemented).
• Frontend (~95% complete): Harness with 5 subagents (Explorer, Researcher, Writer, Editor, Validator) across 3 modes, 3 Mastra workflows with human suspension gates, 9 content engine agents, 28 tools, full CRUD API routes, agent window UI with dual transport, publishing pipeline.
• Data layer (substantially complete): Supabase dual-client, 30+ tables across 4 schemas, live sync for Consul posts, Firecrawl competitor crawling, DataForSEO keyword/SERP research, LangExtract document extraction, Google Analytics/GSC API.

The content lifecycle flows through well-defined stages, each stored as a database row:

A ContentBrief is a JSON blob with fields like angle, outline, keywordMapping. A BlogPostDraft is a row containing markdownBody (the entire article as a single text field), metaTitle, metaDescription, faqBlocks, internalLinks, schemaGraph.

1.2 The Impedance Mismatch

When a Claude Code session runs in the workspace, these native tools are available:

Instead, every content operation routes through: MCP server → HTTP POST → Next.js API → repository function → SQL → PostgreSQL. The agent calls mcp__auctor__loadApprovedBrief({ briefId }) and receives a JSON blob. It calls mcp__auctor__formatForCms({ title, slug, markdownBody, metadata }) to push content back.

1.3 What Is Lost

No surgical editing. The markdownBody field is a single text column. To change paragraph 3 of a 2,000-word article, the agent must rewrite the entire field. The Edit tool cannot be used because the content isn't in a file.

No cross-content search. No MCP tool searches across all published articles. If the agent needs "every article mentioning competitor X" or "all places linking to a specific URL," it cannot. Grep would do this trivially with files.

No change tracking. EditorReview stores edits as a JSON array of { location, type, severity, suggestion } objects. There is no way to see what actually changed between revision 1 and revision 2. git diff would provide this for free.

No revision history. The database stores current state only. When a draft is revised, the previous version is overwritten. git log would preserve every intermediate state.

No parallel experimentation. No way to try two angles for the same article and compare them. Git branches exist for exactly this.

No content-aware validation. Bash is fully disallowed. The agent cannot run scripts against content. Every validation check requires a custom MCP tool implementation.

No template compliance. No way to diff a draft against its expected structure template. git diff between a template and content would show exactly where the draft diverges.

2. The Code-Content Isomorphism

2.1 The Structural Parallel

This is not a superficial analogy. It is a structural isomorphism that holds at every level:

2.2 The Agent's Native Language

What Claude Code does for software:

What the agent does for content today:

The first workflow is natural, composable, and leverages the agent's full capability. The second is constrained, monolithic, and forces every operation through a narrow API.

2.3 Git Primitives as Content Operations

3. Architecture

3.1 Design Principles

1. The filesystem is the source of truth for content. PostgreSQL is a materialized view for the web UI.
2. Every content artifact is a file. Briefs are Markdown. Drafts are Markdown. Research notes are Markdown. Metadata is YAML. Reports are JSON.
3. Git provides the content lifecycle. Branches are workstreams. Commits are revisions. Merges are review gates. Hooks are validation pipelines.
4. The agent uses its native tools. No MCP wrappers for content operations. Read, Edit, Grep, Glob, git — the same tools it uses for code.
5. The sync engine is invisible. Content appears in the web UI automatically. Changes from the web UI appear in files automatically.

3.2 Workspace Directory Structure

3.3 The Content Piece as a Directory

A single content piece is a directory containing multiple files — analogous to a software module. The "source code" (draft.md), the "spec" (brief.md), the "test results" (validation/seo-report.json), the "code review" (reviews/review-001.md), and the "documentation" (research/).

Brief format — Markdown with YAML frontmatter:

Draft format — Markdown with minimal frontmatter, plus a separate metadata file:

draft.md:

meta.yaml:

This separation is the key advantage over the database model: each file can be edited independently. The agent can Edit the draft body without touching metadata. It can update SEO fields in meta.yaml without rewriting content. The Edit tool's surgical precision is fully leveraged.

3.4 Commit Message Convention

Structured messages create a machine-parseable, human-readable history:

3.5 Branch Strategy

• main — Canonical published state. The web UI reads from here via sync. Merging to main is the content equivalent of deploying to production.
• content/<slug> — In-progress content piece. Created when a plan item is approved. All work happens here. Merged to main when published.
• experiment/<slug>/<variant> — Experimental alternative. Fork from a content branch, try a different angle, compare with git diff, merge the winner.
• project/<name> — Coordinated multi-piece effort (pillar + cluster). All pieces developed together, cross-linked, published as a unit.
• hotfix/<slug> — Quick corrections to published content (typo, broken link, outdated stat).

4. The Agent's New Capabilities

4.1 Surgical Content Editing

Before: The Writer generates an entire markdownBody field. To revise, it regenerates everything — even if one paragraph needs to change.

After:

One paragraph changed. The rest of the 2,847-word article untouched. The Editor agent can directly Edit the draft — making the exact change it recommends, in place, with git diff showing precisely what it did.

4.2 Cross-Content Intelligence

Before: No tool searches across all content.

After:

Internal linking — one of the highest-impact SEO activities — becomes a trivial Grep instead of an impossible operation.

4.3 Full Revision History

Before: Current state only. Previous versions overwritten.

After:

4.4 Branch-Based Experimentation

The operator says: "Try a more provocative take."

Impossible in the database model without duplicating rows, building custom diffing UI, and adding a "variant" concept to the schema.

4.5 Multi-Piece Content Projects

A pillar page strategy with 5 supporting articles — all developed on a single project/ branch. The agent Greps across all pieces to ensure consistent terminology, no keyword cannibalization, proper cross-linking. The project ships as a single merge to main.

4.6 Template Compliance

Shows exactly where the draft diverges from expected structure — missing sections, extra sections, wrong order. The template becomes a contract; the diff is the compliance check.

4.7 Emergent Properties

These arise naturally from git without any custom engineering:

• Time travel: git checkout HEAD~5 -- content/ai-agents/draft.md
• Blame: git blame content/ai-agents/draft.md — which session wrote each line
• Bisect: Binary search through history to find which commit caused an SEO regression
• Cherry-pick: Pull a great paragraph from an experimental branch
• Stash: Pause mid-draft for a higher-priority interrupt
• Hooks as middleware: Add any validation, notification, or transformation without touching agent code
• Submodules: Shared glossary or brand voice across multiple sites

5. Sync Engine: Bridging Two Worlds

5.1 The Core Challenge

Content must exist in two places: on the filesystem for the agent's native tools, and in PostgreSQL for the web UI (calendar, content library, Kanban, dashboards, review interfaces).

This is solvable because of a crucial asymmetry: the agent and the operator operate on different aspects of content at different times. The agent produces content body, structure, metadata, and research. The operator makes approval decisions, sets schedule dates, assigns priorities, and gives inline feedback. These rarely overlap.

5.2 Source of Truth Split

The agent produces and refines content → lives in files. The operator makes decisions → lives in the database. The database reflects current content state → synced from files. The files reflect current decisions → synced from database.

5.3 Outbound Sync (Filesystem → Database)

Triggered by the post-commit git hook:

The hook delegates to a Next.js API endpoint (/api/content-engine/sync/outbound), which reads workspace files via AUCTOR_WORKSPACE_ROOT env var and upserts to the database. Incremental, idempotent, fast.

5.4 Inbound Sync (Database → Filesystem)

A polling daemon in the Electron main process checks for DB changes every 30 seconds:

Handles a limited set of operations — primarily status changes, schedule dates, inline feedback — because those are what operators change through the web UI.

5.5 Conflict Resolution

• Filesystem wins for content body changes (agent is the authoritative producer)
• Database wins for operational state (operator is the authoritative decision-maker)
• Conflicts are logged in .auctor/sync/conflicts.json for review
• The agent reads the conflict log on its next cycle and adjusts

5.6 The Manifest

.auctor/manifest.json maintains the mapping between filesystem paths and database IDs:

6. Subagent Evolution

Each Harness subagent transitions from MCP-tool-dependent to filesystem-native:

MCP tools are retained only for operations that remain database-only: external API calls (webSearch, keyword research), CMS upload, indexing API, and database-specific queries (extractions, graph edges) that don't have natural file representations.

7. Scheduler Cycles (Updated)

Morning

Midday

Evening

Weekly

8. What Stays in PostgreSQL

Not everything belongs in files. The following remain database-only:

The line is clean: content artifacts (things the agent reads, writes, edits, searches) move to the filesystem. Operational data (things the system queries, aggregates, reports on) stays in the database.

9. Git Hooks: The Validation Pipeline

Pre-commit

Validates every staged content file before it can be committed:

• YAML syntax validation on all .yaml files
• Frontmatter presence check on brief.md and draft.md
• Minimum word count warning on drafts
• Internal link verification against library/

Failures block the commit. New validations are added by dropping a script into .auctor/scripts/ and calling it from the hook — no agent code changes, no MCP tool implementation, no API endpoint. The same extensibility model that powers CI/CD pipelines.

Prepare-commit-msg

Auto-detects content type from staged files and formats the commit message using the type(slug): description convention. Only activates for fresh commits (not amends or merges), and skips if the message already follows the convention.

Post-commit

Triggers outbound sync. Detects whether content-related files changed (anything under content/, plan/, library/, strategy/, competitors/), delegates to the sync endpoint, runs in the background so the commit returns immediately.

10. Build Plan

Phase 0: Foundation — Close Existing Gaps

Goal: Close gaps in the existing architecture before adding the filesystem layer.

• MCP tool proxy route (frontend/app/api/content-engine/mcp-tool/route.ts): Accepts { tool, args }, dispatches to matching content-engine tool function, returns JSON. Unblocks desktop Claude Code sessions from using any content engine tool.
• IPC stubs (desktop/src/ipc/handlers.ts): Implement WORKSPACE_LIST (recursive readdir) and WORKSPACE_READ (readFile with path validation). Enables renderer to browse workspace files.

Phase 1: Workspace Filesystem Structure

Goal: Create the directory layout, initialize git, install hooks, seed scripts and templates.

• Extend ensure-dirs.ts with the full directory tree (replacing old workspace/drafts, workspace/briefs, workspace/sites/consul)
• Git init in workspace root with .gitignore (excluding .auctor/sync/)
• Symlink .auctor/hooks/ to .git/hooks/
• Seed validation scripts (.auctor/scripts/validate-seo.sh, check-links.sh, readability.sh, structure-check.sh)
• Seed content templates (blog-post, comparison, pillar, how-to)
• Seed manifest.json and strategy/active.yaml from defaults

New file: desktop/src/bootstrap/seed-scripts.ts Modified: desktop/src/bootstrap/ensure-dirs.ts, desktop/src/workspace/templates.ts

Phase 2: Content Serializer

Goal: Bidirectional conversion between database row shapes and filesystem file shapes.

New file: desktop/src/sync/content-serializer.ts

Functions for each content type:

• planItemToYaml / yamlToPlanItem
• briefToFiles / filesToBrief
• draftToFiles / filesToDraft
• reviewToFile / fileToReview
• seoReportToFile / fileToSeoReport
• consulPostToFiles, competitorToFiles, strategyToYaml / yamlToStrategy
• toSlug (kebab-case, deduped)

Verified by round-trip unit tests: serialize(deserialize(input)) === input for every type.

Dependency: yaml (js-yaml) added to desktop/package.json.

Phase 3: Data Population (DB → Filesystem)

Goal: One-time migration — read all existing content from the database and write it to the workspace.

• New script desktop/src/sync/populate-workspace.ts — runs during bootstrap if manifest.lastFullSync === null
• Fetches all plan items, briefs, drafts, reviews, SEO reports, consul posts, competitors, strategy via Next.js API
• Writes each to the appropriate filesystem location using the serializer
• Builds the manifest contentIndex
• Creates initial git commit
• Bulk-fetch GET endpoints added as needed (plan-items, briefs, consul-posts, competitors, strategy)

Hooked into: desktop/src/main.ts as Step 8.5 (after servers started, before file watcher).

Phase 4: Outbound Sync (Filesystem → Database)

Goal: When the agent commits content changes, push to PostgreSQL so the web UI stays current.

• Post-commit hook (seeded by seed-scripts.ts): Detects changed content files, POSTs to sync endpoint
• Sync endpoint (frontend/app/api/content-engine/sync/outbound/route.ts): Reads workspace files via AUCTOR_WORKSPACE_ROOT env var, parses with serializer, upserts to database
• Route dispatches based on file path: plan/ → upsert plan items, content/*/brief.md → save brief, content/*/draft.md → save draft, etc.

Phase 5: Inbound Sync (Database → Filesystem)

Goal: When the operator changes things in the web UI, those changes appear in workspace files.

• Daemon (desktop/src/sync/inbound-sync.ts): Polls every 30 seconds for DB changes since last check
• Inbound API (frontend/app/api/content-engine/sync/inbound/route.ts): Returns changes since a given timestamp by querying updatedAt columns
• Handles: brief status changes, draft status changes, plan item updates, draft body edits
• Writes file updates and commits with sync(inbound): prefix

Hooked into: desktop/src/main.ts as Step 9.5, with stop() in shutdown.

Phase 6: Tool Policy & CLAUDE.md Update

Goal: Enable the agent to use native tools for content work.

• Tool policy (tool-policy.ts): Remove Bash from disallowedTools. Add case-by-case evaluation — auto-allow git commands and .auctor/scripts/ execution; require approval for everything else.
• CLAUDE.md template (templates.ts): Full rewrite documenting the filesystem workflow — directory structure, file formats, content lifecycle as file operations, validation scripts, git conventions, commit message format. Retains MCP tool references for database-only operations.
• Runtime manager (runtime-manager.ts): Remove 'Bash' from disallowedTools array.

Phase 7: Scheduler Prompt Updates

Goal: Make autonomous cycles filesystem-native.

Rewrite all four cycle prompts in scheduler.ts to use git log, git status, git branch, Grep across content directories, and .auctor/scripts/ validation — as described in Section 7.

Phase 8: Git Hooks — Pre-commit Validation

Goal: Automated quality gates on every commit.

• Pre-commit hook: YAML validation, frontmatter checks, word count warnings
• Prepare-commit-msg hook: Auto-format commit messages using type(slug): description convention

Both seeded by seed-scripts.ts.

Phase 9: Integration & End-to-End Testing

Three manual E2E tests:

1. Agent creates content: Plan item → scaffold from template → research → write brief → commit → outbound sync → appears in web UI → operator approves → inbound sync → agent reads approved status → starts drafting
2. Agent edits existing content: Read draft → surgical Edit → run validation script → commit → verify git diff shows minimal change → verify DB reflects update
3. Cross-content search: Agent working on new article → Grep library for internal link opportunities → adds links to meta.yaml → verify links reference real published content

Dependency Order

Phases 0 and 1 can run in parallel. Phase 8 can run alongside Phases 4–7.

11. File Inventory

New Files

Modified Files

12. Risks & Mitigations

13. The Deeper Thesis

The argument is not merely "content should live in files." It is a stronger claim: the optimal architecture for agentic content creation is one where the agent operates in its native medium.

Claude Code was built to work with files under version control. Its Read, Edit, Grep, Glob tools are the product of intensive optimization for file-based workflows. Its git integration provides versioning, branching, diffing, and collaboration for free. Its Bash access enables arbitrary scripting and validation.

When content is forced through database abstractions, it is the equivalent of asking a master carpenter to work with oven mitts on. The skills are there. The tools are there. But the interface between the agent and the material strips away every advantage.

Content-as-Code removes the oven mitts. Content becomes the same kind of artifact the agent already knows how to work with. Every file operation that makes Claude Code exceptional at software engineering transfers directly to content creation. And the emergent properties of git — time travel, blame, bisect, branching, hooks — create a content operations infrastructure that no purpose-built CMS can match.