convez.ai
MCP ServerAutomaçãoAvançado
jimy-r

Agent Workspace Architecture

jimy-r/agent-workspace-architecture

Arquitetura prod-ready para agentes confiáveis que trabalham sem supervisão

Ver no GitHub
BomPluginScore · de 0 a 100

Blueprint completo de arquitetura para agentes de IA autônomos, com padrões de orquestração multi-agente, memória persistente, roles especializadas, auditorias agendadas e controle de token. Desenhado para ser usado em Claude Code, mas portável para Cursor, Cline e outros runtimes.

Instalação

$npx convez-ai jimy-r/agent-workspace-architecture

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
16
Forks
1
Acompanhando
0
Saúde
100%
Último commit
há 2 semanas
Versão
v1.23.0
Issues abertas
0
Contribuidores
2

Casos de uso

  • Construir agentes que rodam tarefas complexas enquanto você está ausente
  • Implementar orquestração multi-agente com roles especializadas (auditor, pesquisador, editor)
  • Adicionar memória persistente, auditorias automáticas e gating por impacto em workflows de IA

Veredito

Projeto sólido e bem documentado que resolve problemas reais de produção em agentes autônomos (memória, auditoria, orquestração). A implementação é específica a Claude Code, mas a arquitetura é agnóstica e portável—valiosa como referência para quem quer construir sistemas de agentes confiáveis.

README

A tradução para o português deste README ainda está na fila.

agent-workspace-architecture

A worked blueprint for a personal agent workspace: the roles, routines, hooks, skills, memory, and task coordination that turn a coding agent into a system you can hand work to and trust to make progress while you're away.

A 30-second pass through the interactive tour: the layered architecture, the load-bearing patterns, and one task moving through the system

▶ Take the interactive tour — the clickable five-minute version: the layered architecture, the nine load-bearing patterns, and one task moving through the system end to end.

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, classify-then-act heartbeat, 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.

What's inside

  • Roles library. 17 pure expert personas (security-auditor, researcher, accountant, developmental-editor, and more) that compose with project CONTEXT.md files through thin bindings.
  • Heartbeat + audit subagents. A 2-hourly project manager that classifies and advances the task queue, and a 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, review-queue, terse-mode, verify-completion, systematic-debugging, role-pressure-test.
  • 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 by MEMORY.md, pointing at sources rather than copying them.
  • Hardening. A PreToolUse file-and-command guard, a password-manager credential law, encrypted restic backups, and container sandboxing for web-facing agents.
  • 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.

Start with the why

If you read one thing past this page, read PATTERNS.md — the nine 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:

QuadrantDocRead it for
ExplanationPATTERNS.mdwhy the shape is the way it is
ReferenceMETA_ARCHITECTURE.mdthe full structural map, with diagrams
TutorialADOPTION.mda 5-step build, minimum-viable at each step
How-tosamples/scaffold files to fork and adapt

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.

Who built this

James Ross. I design agent workspaces and AI-orchestration systems, and this is the reference version of my own. If you're standing up something similar inside an organisation, or want these patterns adapted to your stack, the practice site is jamesross.ai.

Using it

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 Brisbane weather).

This is a curated solo reference, maintained best-effort. 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.

Caveats

  • 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, Brisbane weather) is a template to localise, not a default.

Related

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.

Also here

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.

License

MIT. Reuse freely.


Last verified against the repo structure on 2026-06-10.

Ver o original no GitHub

Bom para

Relacionados