Operator’s Manual

This guide covers how to set up, run, and supervise the Intent Suite research automation system from day one. It assumes you are the human curator — the system’s author, editor, and strategic director.

Part 0: Initial Setup (The Wizard)

Run once per project (or when changing domains). Skip to Part 1 if already configured.

Prerequisites

• Python 3.10+ and uv installed
• Claude Code CLI installed and authenticated
• Git configured with your name and email

Install

git clone https://github.com/<your-org>/<your-repo>.git
cd clawlab-research
uv sync

Run the Wizard

uv run python scripts/wizard.py

The wizard interviews you about your research domain and configures the entire system. It asks for:

What it writes:

• obsidian/project/domain-config.yaml — machine-readable config used by all scripts
• obsidian/tenets/tenets.md — human-readable commitments every article must connect to
• Patches CLAUDE.md, templates, and evolution-state.yaml

Wizard options:

uv run python scripts/wizard.py              # Full interview + apply
uv run python scripts/wizard.py --apply      # Apply existing config without re-interviewing
uv run python scripts/wizard.py --dry-run    # Preview changes without writing
uv run python scripts/wizard.py --force      # Overwrite existing config

Verify

After the wizard completes, check:

cat obsidian/project/domain-config.yaml   # Should show your project name, sections, ples
cat obsidian/tenets/tenets.md             # Should list your commitments

Part 1: Starting the System

The Core Loop

The system runs on a continuous automation loop (evolve_loop.py) that executes AI tasks in a deterministic 24-slot cycle. Each slot is ~40 minutes by default.

uv run python scripts/evolve_loop.py --interval 2400

Keep this running. Stop it with Ctrl+C at any time — it saves state and resumes cleanly.

Speed Options

Preview the Cycle

Before starting, see the task schedule:

uv run python scripts/evolve_loop.py --describe-cycle

This shows the 24-slot sequence without running anything.

Test with One Iteration

uv run python scripts/evolve_loop.py --max-iterations 1

Runs a single slot, then exits. Use this to verify the system is working before running it continuously.

Logs

The loop writes a daily rotating log file. Check it to see what ran and whether anything failed.

Part 2: The Workflow at a Glance

Data Flow

You (ideas, priorities)
        ↓
obsidian/workflow/todo.md  ← Task queue
        ↓
evolve_loop.py  ← Automation daemon (runs Claude skills)
        ↓
obsidian/topics/  obsidian/concepts/  obsidian/gaps/  obsidian/research/
        ↓
scripts/sync.py  ← Converts Obsidian → Hugo
        ↓
hugo/content/  ← Hugo static site
        ↓
Cloudflare Pages / Netlify  ← Live site (auto-deploys on push)

What the System Does Automatically

Every ~40 minutes (one cycle slot), the loop:

1. Picks the next task from todo.md (67% of slots) or runs a system task (deep review, analysis, etc.)
2. Invokes the relevant Claude skill
3. Writes/updates files in obsidian/
4. Commits with AI authorship
5. Appends to obsidian/workflow/changelog.md

Every 4 hours, it also syncs, validates, builds Hugo, and pushes to remote.

Time-triggered tasks:

• 8am UTC daily: Features a highlight on the site (optional tweet)
• Every 45 min: Posts to the agentic social network

What You Do

• Set direction via obsidian/tenets/tenets.md
• Prioritize tasks via obsidian/workflow/todo.md
• Review AI-written content in obsidian/topics/, obsidian/concepts/, obsidian/gaps/
• Edit and curate articles you care about most
• Adjust system parameters when content drifts

The 24-Slot Cycle Breakdown

Cycle-boundary tasks (run every N completed cycles):

• Every 2 cycles: check-links
• Every 3 cycles: check-tenets
• Every 4 cycles: apex-evolve
• Every 6 cycles: tune-system

Part 3: Daily Supervision

Morning Check (5 minutes)

Open obsidian/workflow/changelog.md and skim yesterday’s activity. Look for:

• What was written or updated
• Any failed or timed-out tasks
• Section counts approaching their caps

Review AI-Written Content

AI-written files have ai_contribution: 100 in their frontmatter. Browse:

• obsidian/topics/ — main articles (800–1500 words each)
• obsidian/concepts/ — supporting definitions (400–800 words)
• obsidian/gaps/ — open questions and missing pieces (500–1000 words)

Sort by ai_modified descending in Obsidian to see what was recently written.

What to look for:

• Claims that need verification
• Missing nuance or oversimplification
• Articles that don’t connect clearly to the ples
• Tone or voice that feels off

Read Research Notes

Before articles are written, the system first generates research notes in obsidian/research/. These are raw, not published. Read them to:

• Understand what the AI is about to write
• Add corrections or direction before the article is generated
• Decide whether to queue or skip a topic

Spot-Checking Frontmatter

Use validate.py to scan for frontmatter issues:

uv run python scripts/validate.py obsidian/topics/
uv run python scripts/validate.py obsidian/concepts/

Part 4: Adding Ideas and Setting Direction

The primary human input point is obsidian/workflow/todo.md.

Task Syntax

- P1 research-topic: The role of embodied cognition in AI design
- P2 expand-topic: Why context windows are not the same as memory
- P1 refine-draft: obsidian/topics/human-ai-collaboration.md
- P0 deep-review: obsidian/topics/intent-as-infrastructure.md

Format: - P[0–3] [task-type]: [description or file path]

Priority Levels

P0 and P1 tasks bypass section caps. P2 and P3 tasks are skipped if a section is at its maximum article count.

Task Types

Automatic Queue Replenishment

If the queue drops below 3 active tasks (P0–P2), the system automatically runs replenish-queue. It generates new tasks from:

• Research notes not yet turned into articles
• Concepts referenced in articles but not defined
• Content that hasn’t been reviewed in 30+ days
• Orphaned files with no inbound links

You can always add tasks manually to override or supplement this.

Part 5: Asking Questions and Changing Direction

Ask the AI to Investigate Something

Add a research-topic task at P1:

- P1 research-topic: How do large language models handle uncertainty?

The AI will search the web, consult academic sources, and write a research note. You read the note, then optionally add an expand-topic task to turn it into a published article.

Change the Research Focus

Edit obsidian/tenets/tenets.md directly. Every article must connect to these commitments — so changing a commitment shifts the entire content direction.

You can also edit obsidian/project/domain-config.yaml to:

• Adjust section caps (raise to allow more articles, lower to force consolidation)
• Update the canonical domain
• Change author information

After editing domain-config.yaml, run the wizard in apply mode:

uv run python scripts/wizard.py --apply

This propagates your changes to all dependent infrastructure files.

Redirect the Automation

Add P1 tasks to steer what gets worked on next. The loop always processes the highest-priority available task. If you want the AI to focus on a specific area, add several P1 tasks in that direction.

Part 6: Reviewing and Editing AI Content

How to Edit

Edit any file in obsidian/ using Obsidian, VS Code, or any text editor. The sync step (sync.py) converts it to Hugo format automatically.

When you edit a file, update its human_modified timestamp in the frontmatter:

human_modified: 2026-03-10T14:30:00+00:00

Use UTC timezone for all timestamps.

Authorship Tracking

The system distinguishes human from AI edits via frontmatter timestamps:

When human_modified is more recent than ai_modified, the next commit uses your git identity. When ai_modified is more recent, it commits as the AI agent.

Committing Your Manual Edits

The loop commits AI work automatically. For your own edits, run:

uv run python scripts/commit_obsidian.py --dry-run   # Preview first
uv run python scripts/commit_obsidian.py              # Commit

Part 7: Running Skills Manually

All skills are Claude Code slash commands. Open Claude Code in the project directory to run them.

Read-Only Skills (Safe to Run Anytime)

Content-Modifying Skills

Operational Skills

Part 8: Building and Previewing Locally

Sync Obsidian to Hugo

uv run python scripts/sync.py

Converts Obsidian markdown (wikilinks, frontmatter) to Hugo format. Run this before previewing or building.

Local Preview

cd hugo && hugo server

Opens at localhost:1313. Auto-refreshes on file changes. Does not require sync to already have run — but content won’t reflect Obsidian changes until you sync.

Full Build Pipeline

uv run python scripts/build.py

Runs in sequence: sync → validate → build Hugo. Outputs to hugo/public/. Use this to catch all issues before pushing.

Skip stages if needed:

uv run python scripts/build.py --skip-sync      # Hugo build only
uv run python scripts/build.py --skip-validate  # Skip frontmatter check

Validate Frontmatter

uv run python scripts/validate.py hugo/content/       # All content
uv run python scripts/validate.py obsidian/topics/    # A specific section

Part 9: Committing and Deploying

During Automation (Automatic)

The loop commits after each task using the agent-commit skill, which generates a meaningful commit message. No action needed.

The loop also pushes to remote every 4 hours, but only after running: sync → validate → Hugo build → archive old workflow entries. If validation fails, it does not push.

For Your Manual Edits

uv run python scripts/commit_obsidian.py --dry-run   # See what will be committed
uv run python scripts/commit_obsidian.py             # Commit with correct authorship

Deployment

The site auto-deploys on push via Cloudflare Pages or Netlify. No manual deploy step needed. After the loop pushes, the live site updates within 1–2 minutes.

Part 10: Weekly and Monthly Maintenance

Weekly (15–20 minutes)

Read the changelog:

Open obsidian/workflow/changelog.md and skim the week’s activity. Look for:

• Patterns in what the AI is producing
• Tasks that keep failing (may indicate a config issue)
• Sections approaching their caps

Check section counts:

Open obsidian/workflow/evolution-state.yaml and review the cap counts. If a section is near its limit, decide whether to raise the cap or let the automation shift to improvement work.

Reprioritize the queue:

Open obsidian/workflow/todo.md. Archive completed P3 items, promote anything that’s become more important, add new ideas.

Monthly

Tune the system (runs automatically every 6 cycles, but you can trigger it manually):

/tune-system

Reviews automation parameters, cycle ratios, and content health. Suggests adjustments if warranted.

Check ple alignment:

/check-tenets

Flags articles that lack a “Relation to Site Perspective” section or whose content doesn’t connect to your commitments.

Review section caps:

Look at the actual article counts in each section vs. the caps in domain-config.yaml. Adjust if the balance feels wrong.

When Content Feels Off

Run adversarial critique on recent articles:

/pessimistic-review

Check the review history in obsidian/reviews/ to see what critiques have been raised before.

Add deep-review tasks for articles that need more attention:

- P1 deep-review: obsidian/topics/some-article.md

Part 11: Troubleshooting

The Loop Isn’t Running Tasks

1. Check the log file for errors
2. Run a single iteration to isolate the issue: --max-iterations 1
3. Check that Claude Code CLI is authenticated
4. Verify .claude/settings.json has the skills listed as allowed

Content Looks Wrong After Sync

Re-sync to refresh:

uv run python scripts/sync.py

Validate to find specific issues:

uv run python scripts/validate.py hugo/content/

The Queue Is Empty and Nothing Is Being Generated

The queue auto-replenishes when it drops below 3 items. If it’s not replenishing:

1. Check that replenish-queue isn’t being blocked by section caps
2. Manually add a few P1 or P2 tasks to todo.md
3. Check evolution-state.yaml to confirm section cap counts are correct

Hugo Build Fails

uv run python scripts/build.py

Read the error output. Common causes:

• Invalid frontmatter (run validate.py to find the offending file)
• Broken wikilink (run /check-links to find it)
• Missing Hugo config (check hugo/config.toml)

Frontmatter Errors

uv run python scripts/validate.py obsidian/topics/some-article.md

Fix the flagged fields. Required fields are listed in CLAUDE.md.

Quick Reference

Scripts

Key Files

Section Caps (Current)

Adjust caps in obsidian/project/domain-config.yaml.