A reference implementation of agent-ready knowledge architecture: the roles, routines, hooks, skills, memory, and task coordination that make a body of working knowledge legible to AI agents, and turn a coding agent into a system you can hand work to and trust to make progress while you're away.
The diagram above is the whole system — click it for the full-page map with legend, a thirty-second read.
▶ Take the interactive tour — the clickable five-minute version: the layered architecture, the eighteen load-bearing patterns, and one task moving through the system end to end.
Feeding this to a model instead? llms.txt is the link map, and llms-full.txt inlines the whole reference in a single fetch.
New work ships irregularly: patterns, teardowns, tools, and the occasional essay. The newest teardown is Superpowers. Follow along at Agent Workspaces, or watch the repo.
One runnable artefact ships here: a single-file, read-only linter that scores a workspace against the checkable patterns and prints one evidence line per check. No install, no dependencies beyond Python 3.9+, and it writes nothing.
curl -sSLO https://raw.githubusercontent.com/jimy-r/agent-workspace-architecture/main/tools/workspace_check.py
python3 workspace_check.py /path/to/your/workspaceWhat you see (this repo's own score, abbreviated):
[PASS] context-budget — 4.7 KB across 1 always-loaded file(s) (pattern 9)
[FAIL] secrets-in-files — 2 hit(s) (pattern 6)
Score 6.4/10 — maturing (7 scored, 5 not applicable)
Scored at 34ddd30 on 2026-09-13; full table: docs/self-score.md. That page
also explains the [FAIL], which is the audit canaries doing their job, and why the check was left
with its teeth in rather than excluded into a higher number. CI re-runs the linter and fails if the
score line moves.
Each check names the pattern it comes from, so a [FAIL] is a link into PATTERNS.md rather than a scolding. Post your score in Show and tell if you want a second read on it.
The example runs in Claude Code, so the file conventions you'll see (CLAUDE.md, .claude/skills/, MCP config) are Claude-Code-specific. The architecture is not. The roles library, memory hygiene, audit cadence, explicit-delegation task board, dead-man's switch, and tier-by-impact gating port to Cursor, Cline, Continue, Windsurf, or a custom Agent-SDK build. Pick your runtime; the decisions translate.
This is one person's actual setup, redacted and published as a reference. Not a framework, not a product. A documented working arrangement of the pieces Claude Code already gives you, with the reasoning attached. It is also the reference version of the agent-ready knowledge architecture I build for organisations, running at one-person scale.
The scale is real: 18 expert roles, 18 load-bearing patterns, an explicit-delegation task board that succeeded a retired 2-hourly heartbeat, a weekly self-audit with synthetic canaries, a dead-man's switch over scheduled jobs, and typed memory that points at sources instead of copying them — all of it running in one person's daily workspace.
The eighteen patterns, by title. Each links to its reasoning in PATTERNS.md.
- Pure roles, composed with project facts
- Classify-then-act, not ask-then-wait
- Make silent failure loud (the dead-man's switch)
- Tier by mechanical impact, not by tone
- Memory points, it doesn't mirror
- Credentials live in one place, never in files
- A cheap hook beats a careful agent
- Audit the workspace like a fitness function
- Context is a budget, not a constant
- A skill is editable weights — never adopt a self-edit without a gate
- A scaffold is a hypothesis — gate it behind a measurable signal
- Loop selection: not everything should be a loop
- Challenge half-formed ideas with a different lens
- Delegation is a queue you fill, not work the agent finds
- Price the lane before you migrate it
- A claim carries its provenance, or it is a guess
- One canonical copy, and pointers from everywhere else
- Position is price — a token costs more the earlier you add it
- Roles library. 18 pure expert personas (security-auditor, researcher, accountant, developmental-editor, and more) that compose with project
CONTEXT.mdfiles through thin bindings. - Task board + audit subagent. One canonical markdown card store rendered to a local served view, with an explicit delegation queue. The operator marks a card queued, a short intake interview captures what done looks like and which folders may be written, and a drain skill actions the queue inside a live session. The close-out ritual logs a per-task token record, so the metrics page charts capacity from finished work rather than from a schedule. A 2-hourly classify-then-act heartbeat held this job until August 2026. It was retired, and its design stays in
samples/tasks/as the studied predecessor. Alongside sits the weekly upgrade audit, whose first job is finding improvements (public-source research plus a module-by-module critique against current best practice), with configs, security, and drift checked in the same sweep. - Custom skills.
orient,wrap,tasks,audit-workthrough,terse-mode,verify-completion,systematic-debugging,role-pressure-test. Two more samples are kept as retired designs.review-queuewent with the heartbeat in August 2026, andgoal-designwas cut at the September 2026 scaffold review after three months without a single invocation. - Scheduled routines. A daily morning brief (calendar, weather, AI news, task state) and a memory-consolidation pass, fired by the OS scheduler.
- Memory system. Typed files (
user/feedback/project/reference) indexed byMEMORY.md, pointing at sources rather than copying them. - Hardening. A
PreToolUsefile-and-command guard, a password-manager credential law, encryptedresticbackups, and container sandboxing for web-facing agents. - Evaluation. A golden set of frozen cases, each one an already-burned failure turned into a regression test, replayed K times and reported as a pass-rate with variance. Deterministic checks only, never an LLM judge, so a drop in the rate is a real regression rather than judge noise. See EVALUATION.md.
- Workspace check. A single-file, read-only linter (
tools/workspace_check.py) that scores your own workspace against the mechanically-checkable patterns (context budget, hook shape, permission floor, credential hygiene, skill and agent frontmatter, duplicated instruction blocks) and prints one evidence line per check. - The ecosystem map. A separately maintained curated index of the wider tooling space: awesome-agent-workspaces — memory systems, evaluation, guardrails, observability, with a stated inclusion bar and a public rejection log.
- Token budget. A deterministic preflight gate that skips no-op scheduled cycles, a model-tier policy for unattended work, and daily spend telemetry feeding the weekly audit.
Tables throughout mark each component [stock] / [plugin] / [local] / [custom], so you can see what ships with Claude Code versus what someone had to write.
If you read one thing past this page, read PATTERNS.md — the eighteen load-bearing architectural decisions, each as problem → pattern → why it beats the obvious alternative → what it costs. That's where the actual thinking lives.
The rest of the docs follow Diátaxis:
| Quadrant | Doc | Read it for |
|---|---|---|
| Explanation | PATTERNS.md | why the shape is the way it is |
| Evidence | teardowns/ | published architectures read against the patterns |
| Evidence | experiments/ | pre-registered experiments on the workspace's own cost and quality, with failed hypotheses published beside passed ones |
| Reference | META_ARCHITECTURE.md | the full structural map, with diagrams |
| Tutorial | ADOPTION.md | a 5-step build, minimum-viable at each step |
| Tutorial | learn/ | a guided track through the patterns, by capability, with exercises |
| Explanation | EVALUATION.md | how to tell whether a workspace change actually helped |
| How-to | samples/ | scaffold files to fork and adapt |
| How-to | tools/workspace_check.py | run a scored check of your own workspace |
Two more views. WORKFLOW.md shows a day of actually using it: session discipline, phone dispatch, how a task moves thought-to-done, and the open structured-vs-autonomous tension the whole design sits inside. And you can hand the repo to your own agent:
"Tour this repo. Read PATTERNS.md, then META_ARCHITECTURE.md, then WORKFLOW.md, then scan samples/. Summarise the patterns most applicable to my workspace."
The repo's CLAUDE.md auto-loads on session start, so your agent inherits the conventions before it answers.
James Ross. I work as an AI Knowledge Architect; the practice is Agent-Ready Knowledge Architecture — making an organisation's knowledge legible to AI agents. This workspace is the reference version of my own agent-ready memory layer: the source-of-truth conventions, context architecture, and memory governance the practice teaches, running daily in production. If you're standing up something similar inside an organisation, or want these patterns adapted to your stack, the practice site is jamesross.ai.
Fork freely (MIT); that's what it's for. Adapt the samples, lift the patterns, localise the domain-flavoured bits (the accountant role is Australian-CPA shaped, the morning brief fetches local weather).
This is a curated solo reference, maintained best-effort. Questions, comparisons with your own setup, and "does this hold at team scale" go to Discussions, the canonical Q&A home, where answers stay findable. If you spot a privacy leak, a broken link, or a pattern that's plainly wrong, open an issue and I'll get to it when time allows. Substantial PRs are welcome, but a good one can still be declined if it pulls the doc off its shape: it stays one coherent worked example, not a grab-bag.
One hard rule for anything you send: no personal identifiers, no credentials, no business / health / financial specifics. Every commit is safe for a public audience. Full guidance in CONTRIBUTING.md.
- Paths are generic (
<workspace>,<home>); a real setup substitutes its own. - Nothing here executes on its own. The repo describes structure and ships sample code; it isn't a runnable product.
- Domain-flavoured content (Australian tax terms, local weather) is a template to localise, not a default.
signal-sweep: the human-gated presence tooling that grew out of this workspace's thread-sweep module, generalized to config-driven form and co-maintained as a standalone project. Its worked-example config is this repo's own topic set.
agent-workspace-starter: the runnable template version of this workspace. A minimal scaffold with the session discipline and two safety hooks already running, to start a new workspace from rather than read about one.
dead-mans-switch: a freshness checker for scheduled agent jobs. It watches for the absence of success rather than for errors, the failure mode pattern 3 describes.
redaction-check-action: a reusable GitHub Action version of a redaction gate. Scans a pull request's added lines for the shapes of private content before merge.
Discussions (Q&A, and Show and tell for your own workspace score) · AGENTS.md (instructions for an agent working in this repo) · SUPPORT.md (where to go for what) · STYLE_GUIDE.md · SECURITY.md (privacy-leak and workflow-vuln reporting) · CHANGELOG.md · ATTRIBUTION.md (patterns this borrows from) · CODE_OF_CONDUCT.md
The repo was renamed from claude-workspace-architecture on 2026-05-28; the old URL 301-redirects, so external links keep working.
MIT. Reuse freely.
Last verified against the repo structure on 2026-10-12.