agent-workspace ~ %
← Docs

// agent workspace template · the story

Stop rebuilding your AI setup.

Every time Claude Code evolves, most developers rebuild from scratch: new agent files, new automation, new knowledge store, new conventions. This template ends that loop. Clone it once. The agents, the automation, the knowledge pipeline, the health monitoring — all wired, all running, all self-checking.

Clone on GitHub ↗ See what you get ↓

// what you get

Six outcomes, zero setup debt

Everything below is in the repo on day one. Not a starter — a complete operating environment.

A pre-wired agent team

Five scoped subagents — architect, coder, eng-manager, archivist, curator — each confined to their domain, each with a hand-off matrix. The orchestrator dispatches; agents execute. No prompt-pasting, no context bleed.

.claude/agents/ 5 agents

Skill orchestration

The master-orchestrator skill routes 40+ installed skills to the right agent automatically. A launchd sync job watches ~/.agents/skills/ and pushes new skills to ~/.claude/skills/ hourly, flagging any unindexed arrivals.

master-orchestrator 40+ skills hourly sync

A Second Brain that indexes itself

Web clips land in Vault_Brain/sources/. A headless Claude distills each one into a structured wiki page. Content-hash dedup means byte-identical clips are skipped. Your Obsidian vault — or VS Code+Foam — is the viewing layer; the store is plain Markdown.

Vault_Brain/ daily 07:00 Obsidian or Foam

A system that checks itself

An 8-layer health check probes delivery, automation, knowledge base, persistence, active projects, documentation currency, repo hygiene, and decision hygiene. It runs at login and every four hours, writing a status page you can open in the browser.

8 layers every 4h status_page.html

A pluggable KB layer

The knowledge backend is a first-class configuration choice, not an assumption. Obsidian is the default. VS Code+Foam is the lightweight alternative. The choice is written to System_Config/config.sh during bootstrap.sh and honored by every script that touches the vault.

Obsidian default Foam alternative config.sh

Git discipline built in

A readme-currency-check hook fires on every Write or Edit, warning when a README is older than the files it documents. The health check’s Layer F flags stale docs at the system level. Convention and automation combine so documentation lag can’t hide.

PostToolUse hook Layer F auto-warning

// a day in the life

What it actually looks like to use this

This is a representative day. The automation runs whether you’re at your desk or not.

  • 07:00 — automated

    Daily ingest fires

    The launchd job wakes, scans Vault_Brain/sources/ for new clips, and runs a headless claude -p call per clip. By the time you open your laptop, last night’s reading is already indexed as structured wiki pages.

  • Morning — you

    Open a project, pick up where you left off

    Open the workspace in Claude Code. The orchestrator reads .AGENT.MD for the workspace map and routes your first task — architect for design, coder for implementation, eng-manager if it’s a project milestone. No context-setting, no re-explaining the stack.

  • Afternoon — you

    Clip an article, ship a feature

    Save a web clip to sources/ via the browser extension. The clipper template writes structured frontmatter automatically. Meanwhile the coder agent builds against the architect’s spec; the archivist files the shipped artifact to Final_Products/ with the right naming convention.

  • End of day — automated

    Health check runs

    Every four hours the health check probes all eight layers and rewrites status_page.html. If a README went stale when you edited a script this afternoon, Layer F catches it. You see the amber flag next time you open the status page.

  • Friday 19:00 — automated

    Friday close-out runs

    The Friday process writes a 1–2 sentence summary to your Master Note, builds wiki cross-references across the week’s new pages, and regenerates the microsite’s agent table and job cards from the live source files. You review on Monday.

// before & after

What actually changes when you use this

Six workflow comparisons. The left column is the default state of the art; the right is what this template delivers.

Without
With this template
Agent setup You paste agent descriptions into every conversation. Each session starts cold; nothing carries.
Agent setup Five scoped agents live in .claude/agents/. Invoke by name. Context, constraints, and hand-off matrix are persistent.
persistentscoped
Without
With this template
Knowledge capture Interesting articles stay in browser tabs or a read-later list. They never make it into your workflow.
Knowledge capture Clips go to sources/ via a one-click extension. Claude distills them into wiki pages every morning at 07:00.
automateddaily
Without
With this template
System health You discover that a script broke when something downstream fails. Debugging takes longer than the original task.
System health An 8-layer health check runs every four hours. Status is always visible at status_page.html. Failures surface fast.
8 layersevery 4h
Without
With this template
Documentation READMEs drift from the code within weeks. You can’t trust them; you read the source instead.
Documentation A PostToolUse hook warns on every Write/Edit when a README is older than the files it documents. Layer F flags it at the system level.
hook-enforcedLayer F
Without
With this template
MCP configuration MCP servers are configured once globally. When you have multiple workspaces, they share credentials and can interfere.
MCP configuration .mcp.json is workspace-scoped. Credentials never cross projects. .mcp.json.example is tracked; the real file is git-ignored.
workspace-scopedgit-ignored
Without
With this template
Skill management Skills accumulate in ~/.claude/skills/ manually. New installs don’t reach the orchestrator without manual index updates.
Skill management The sync-skills launchd job watches ~/.agents/skills/ and syncs to ~/.claude/skills/ hourly, flagging unindexed arrivals automatically.
hourly syncauto-index

// get started

Clone, bootstrap, operate

Three commands. The health check at the end tells you everything is working.

bash — agent-workspace
$ git clone https://github.com/Classiccottrell/Agent_Workspace_Template.git agent-workspace
$ cd agent-workspace
$ ./bootstrap.sh
→ scripts made executable, logs/ created
→ .mcp.json seeded from example
Install background automation? [y/N] y
→ daily ingest installed ✓
→ healthcheck installed ✓
→ friday process installed ✓
→ skill sync installed ✓
$ bash System_Config/healthcheck.sh
Layer A (Orchestration) … PASS
Layer B (Automation) …… PASS
Layer C (Knowledge) …… PASS
Layer D (Persistence) …… PASS
Layer E (Projects) ……… PASS
Layer F (Doc Currency) … PASS
Layer G (Repo Hygiene) … PASS
Layer H (Decisions) …… PASS
→ All layers healthy. Open status_page.html to review.

One-time prerequisite: grant Full Disk Access to /bin/bash in System Preferences → Privacy & Security. The background automation needs it to read your workspace under ~/Documents.

Further reading