How to Use This Research Framework

This framework is a self-managing generative research platform — a combination of Obsidian, Hugo, and AI automation that continuously researches, writes, reviews, and improves content in your chosen domain. A human curator sets direction; the AI handles volume and consistency.

What This Framework Is

The framework has three layers:

1. Content layer — Obsidian vault (obsidian/) — where all articles live as Markdown files
2. Presentation layer — Hugo static site (hugo/) — converts the vault to a public website
3. Automation layer — Python scripts + Claude skills (.claude/skills/) — the AI system that runs research, writing, and review cycles

The human role is to:

• Set the domain and its core commitments (foundational perspectives)
• Prioritise the task queue (workflow/todo.md)
• Review and approve drafts before they publish
• Tune the system when something isn’t working

Everything else — research, writing, reviewing, linking, condensing — the automation handles.

The Content Hierarchy

Research notes (obsidian/research/)
    ↓ research-topic skill generates these
Topics (obsidian/topics/)           ← explorations of domain questions
Concepts (obsidian/concepts/)       ← definitions of building blocks
Arguments (obsidian/arguments/)     ← criticism and counterarguments
    ↓ expand-topic, deep-review skills develop these
Apex articles (obsidian/apex/)      ← synthesis deliverables
Voids (obsidian/voids/)             ← mapped limits of knowability

Research notes are raw AI-generated inputs — not published, used to queue expand-topic tasks.

Topics and concepts are the working content — regularly reviewed, improved, and cross-linked.

Arguments challenge the framework’s commitments — steel-manning opposing views.

Apex articles are the synthesis deliverables — curated, thesis-driven, polished.

Voids map the limits — what the domain cannot resolve and why.

The Automation Loop

The evolution loop (scripts/evolve_loop.py) runs continuously and picks tasks from a deterministic 24-slot cycle:

Every N complete cycles, additional tasks run:

• Every 2 cycles: check-links (find broken internal links)
• Every 3 cycles: check-tenets (verify content aligns with commitments)
• Every 4 cycles: apex-evolve (create or refine synthesis articles)
• Every 6 cycles: tune-system (meta-review of automation performance)

Speed control is set by the --interval flag (seconds between sessions):

Running the Framework Locally

# 1. Install dependencies
uv sync

# 2. Sync Obsidian vault to Hugo content
uv run python scripts/sync.py

# 3. Build the static site
uv run python scripts/build.py

# 4. Preview locally
cd hugo && hugo server

# 5. Run the automation loop (Ctrl+C to stop)
uv run python scripts/evolve_loop.py --interval 2400

# 6. Test with a single iteration
uv run python scripts/evolve_loop.py --max-iterations 1

# 7. Validate frontmatter
uv run python scripts/validate.py hugo/content/

The Task Queue

Human + AI collaboration happens through obsidian/workflow/todo.md.

Priority levels:

• P0 — urgent: blocking issues, broken content
• P1 — high: important improvements, gap-filling
• P2 — normal: standard content work (automation picks these)
• P3 — low: nice to have, backlog

The automation loop picks tasks at P0–P2. When active tasks drop below 3, replenish-queue runs automatically to generate new tasks from:

• Unconsumed research notes awaiting articles
• Content gaps (concepts referenced but not defined)
• Stale AI-generated content (not reviewed in 30+ days)
• Orphaned files (no inbound links)

Task types:

The Skills (Slash Commands)

Skills are invoked by the automation loop or manually via /skill-name.

Domain Configuration

The framework’s domain is configured in two places:

obsidian/tenets/tenets.md — the foundational commitments. Every article must relate to these. The /check-tenets skill verifies this alignment automatically.

obsidian/project/domain-config.yaml — machine-readable domain settings used by skills and the automation loop (section names, caps, author info). This file is generated by the intake wizard.

Reconfiguring for a New Domain

Run the intake wizard to configure the framework for a new research domain:

uv run python scripts/wizard.py

The wizard collects:

• Project name, description, and domain
• Author information
• Content section names and caps
• Domain commitments (equivalent to tenets)
• Audience and writing style

Then it generates all domain-specific files and patches the infrastructure files.

Deploying

The site is a standard Hugo static site deployable to Cloudflare Pages or Netlify.

Cloudflare Pages:

1. Connect GitHub repo
2. Build command: uv run python scripts/build.py
3. Output directory: hugo/public

Netlify:

1. Connect GitHub repo
2. Build command: uv run python scripts/build.py
3. Publish directory: hugo/public

The commit_obsidian.py script handles git authorship attribution (human vs AI edits):

# Preview what would be committed
uv run python scripts/commit_obsidian.py --dry-run

# Commit with correct authorship
uv run python scripts/commit_obsidian.py

Section Caps

To prevent runaway content generation, each section has a maximum article count configured in obsidian/workflow/evolution-state.yaml. When a section is full, automation shifts to improving existing content rather than creating new articles.

Default caps:

• Primary section (topics/explorations): 200
• Secondary section (concepts/patterns): 200
• Tertiary section (voids/gaps): 100

Adjust caps in evolution-state.yaml under section_caps.

Tagging Workflow

Tags provide a free, bottom-up vocabulary for content discovery. They are distinct from the controlled topics and concepts fields.

The Three Vocabulary Layers

Tag Format

• Lowercase kebab-case only: human-ai-collaboration, not HumanAI or Human AI
• 3–8 tags per article — prefer specificity over generality
• Tags are plural themes, not titles or sentences

When to Add Tags

• During expand-topic — tag new articles at creation time
• During refine-draft — add missing tags when improving existing articles
• During deep-review — review and correct tags alongside content

The Harvest Path

Tags accumulate bottom-up. When a tag appears on 5+ articles, consider:

1. Is there already a concept or topic article covering this theme?
2. If not, add an expand-topic task to create one
3. Once the article exists, add its slug to the concepts or topics array on relevant articles

This is how controlled vocabulary grows organically from actual usage rather than top-down design.

Further Reading

• AI Automation System — detailed automation documentation
• Human Supervision — the curator’s role and review protocols
• Writing Style Guide — how articles should be written
• Workflow — task queue and evolution loop details
• Domain Commitments — the foundational perspectives