Let me go deep on this. The problem space is "how do autonomous AI agents maintain project context across sessions" — which is a well-trodden problem in the agent ecosystem. Let me find out what's already been built and whether your proposal is reinventing or innovating.Now I have comprehensive research across five major dimensions. Let me synthesize this into a thorough assessment. --- ## Architecture Assessment: File-Based Project Registry **Verdict: Not reinventing a worse wheel. This is the right family of solution, and your specific implementation has design choices that are genuinely better than most community alternatives. But there are three existing systems worth understanding that either solve pieces of this problem or validate your approach — and one critical gap in the proposal that none of them solve either.** --- ### The Problem Is Universal and Well-Documented You're not alone in this pain. OpenClaw Issue #12333 describes the exact same problem: OpenClaw uses a single workspace directory for all agent context, and developers working on multiple projects need to manually manage context or use separate agent instances. That issue is three weeks old and open, which tells you the core platform hasn't solved it yet. The community has converged on three categories of response, which I'll map against your proposal. --- ### Category 1: Multi-Workspace Switchers (solve the "where am I?" problem) The **`multi-workplace` skill** on ClawHub is the closest existing community solution to what you're building. It manages multiple project workplaces with per-workspace agents, isolated memory, and multi-agent orchestration, auto-detecting git repositories as workplaces and storing workspace context in a local registry and a per-project `.workplace/` directory. It has a registry pattern: a central registry tracks known workplaces and the current active workspace; switching updates `current.json` and loads the chosen workspace config. Commands include `workplace init`, `workplace list`, `workplace switch`, `workplace scan`, and `workplace status`. **How your proposal compares:** The multi-workplace skill assumes each project is its own git repo with its own workspace — it's a *switcher*, not a *registry*. It answers "let me change which project I'm in" but not "show me all projects and their states at once." Your approach — all projects live under one directory with a unified `_registry.json` — is fundamentally different. You're building a **portfolio view**, not a context switcher. That's a better primitive for your use case (one human, one agent, many concurrent projects). The multi-workplace skill is designed for "I'm working on Project A now, switch me," while your architecture is designed for "what's the state of everything, and what should I work on next?" The **`project-tree` skill** is another relevant piece: it generates a visual project tree from `~/projects` and updates `MEMORY.md` with the result, showing folders and `.md` files only with smart grouping for consecutive numbered items. It even hooks into session resets to auto-update. This solves the "MarkBot wakes up with no map" problem by injecting a snapshot into memory at session start. Your `_registry.json` is a more structured version of this same idea. --- ### Category 2: Agent Project Management Frameworks (solve the "how do agents maintain project context?" problem) **APM (Agentic Project Management)** is the most mature framework here. APM uses a Dynamic Markdown File System, organized as a layered directory structure that mirrors the phases and tasks in the Implementation Plan — this progressive "Dynamic Memory Bank" is maintained by the Manager Agent, who creates the overall structure, while individual documents are populated by Implementation Agents. The APM memory structure: ``` .apm/Memory/ ├── Memory_Root.md # High-level project state ├── Phase_01_Foundation/ │ ├── Task_1_1_Setup.md # Atomic task log │ └── Task_1_2_Database.md └── Phase_02_Core/ ``` APM uses lightweight YAML front matter at the top of important documents to deliver structured metadata — the YAML layer provides structured metadata for immediate filtering and context scaffolding while the Markdown layer delivers detailed instructions and nuances via hierarchical text. **How your proposal compares:** Your README.md frontmatter spec (id, status, phase, priority, tags) is exactly the same pattern as APM's YAML frontmatter. You arrived at the same solution independently, which is a good sign. The difference: APM is designed for a *single project* with multiple agents working on phases and tasks. Your system is designed for *multiple projects* with a single agent working across them. APM goes deep on one project; your registry goes wide across many. They're complementary, not competing. **CCPM (Claude Code PM)** takes a different angle: it stores project context in `.claude/context/` with epics, PRDs, and task files, maintaining a structured context hierarchy where agents read from `.claude/context/` and update locally before syncing. The insight here is separating *plans* (PRDs, epics) from *state* (progress, blockers). Your README.md vs STATE.md separation does the same thing. --- ### Category 3: Context Engineering Theory (validates the architectural principles) Google's ADK framework articulates the theory behind what you're doing. ADK's core thesis is that context is a dynamic, engineered resource requiring active management — the working context sent to the LLM is not raw history, it is a compiled view. Their three design principles are directly relevant: Separate storage from presentation: distinguish between durable state and per-call views. Explicit transformations: context is built through named, ordered processors, not ad-hoc string concatenation. Scope by default: every model call sees the minimum context required. **How this maps to your proposal:** Your `_registry.json` is a "compiled view" — it's generated from scanning README.md frontmatter, not hand-maintained. That's ADK's "separate storage from presentation" principle. Your README.md files are storage; the registry is the presentation layer. Your STATE.md is the "per-call view" — it's what the agent reads on each session to get the current working context for a specific project, not the full history. Your LOG.md is the "durable state" — append-only, never edited, full history when needed. These are sound architectural separations that mirror what production systems are doing. --- ### What Your Proposal Gets Right That Others Miss **1. The folder IS the identity.** This is genuinely better than most alternatives. The multi-workplace skill uses UUIDs and a registry file. APM uses numeric task IDs. Your approach — `workspace/projects/bookkeeping/` *is* the bookkeeping project, no indirection — is the simplest possible addressing scheme. An agent can `ls workspace/projects/` and immediately know every project that exists. No registry parsing required; the registry is an optimization, not a dependency. **2. README + STATE + LOG is the right decomposition.** You've separated three things that change at different rates: README (changes on project creation/milestones — architecture, identity, config), STATE (changes every session — what's in flight, blockers, next action), LOG (only ever appends — decisions, history). This prevents the common failure mode where a monolithic PROJECT.md file becomes a mix of stale architecture docs and current status, and the agent can't tell which parts are current. **3. `_registry.json` as a generated artifact, not a source of truth.** Making this auto-generated from scanning README frontmatter means it can never drift from reality. If someone (or something) modifies a README, the registry self-heals on next scan. Most alternatives make the registry the source of truth and the individual files secondary, which creates the exact drift problem you're solving. **4. Explicit separation of tools and project state.** The "skills live in `workspace/skills/`, project state lives in `workspace/projects/`" rule directly addresses the `qbo/` problem where tool code and project state were mixed. This is a convention that prevents a real class of bugs (skill update overwrites project state). --- ### Gaps and Risks **Gap 1 (Critical): The "update STATE.md before closing" rule is a prompt instruction, not enforcement.** You learned this lesson in the multi-session architecture discussion. The AGENTS.md rule "Every session that touches a project: update STATE.md before closing" is exactly the kind of instruction LLMs can and do skip. Under token pressure, during compaction, or when the session ends abruptly (crash, timeout, context limit), the STATE.md update doesn't happen. The APM framework addresses this explicitly: when an agent's context window fills, APM employs a Two-Artifact Handover System where the outgoing agent generates both a handover file and a bootstrap prompt for the successor. But this is still agent-initiated — if the agent crashes, the handover doesn't happen. **Recommended fix:** Use OpenClaw's `hooks` system. Create a `before_session_end` or `on_compaction` hook that diffs the workspace and auto-commits any STATE.md changes. This moves the enforcement from "the agent remembers to do it" to "the system does it regardless." If OpenClaw doesn't support a session-end hook, a cron job that checks for uncommitted STATE.md changes every 5 minutes and commits them is a fallback. The git-track-everything pattern from your previous architecture session applies here too. **Gap 2: Projects with code outside the workspace need more than a pointer.** Your proposal handles this with README.md noting `code_location: ~/lifeos/`. But there's a subtle problem: when MarkBot spawns Claude Code on the LifeOS project and passes `workspace/projects/lifeos/` as the working context root, Claude Code can read the README and STATE... but its actual working directory for code operations needs to be `~/lifeos/`. The project folder contains the *context*, but the *work* happens elsewhere. **Recommended fix:** Your sub-agent spawning rule should be: "read context from `workspace/projects/{name}/`, but set cwd to `code_location` from the README frontmatter." This is a two-path pattern: context path (always `workspace/projects/`) and work path (either same, or from `code_location`). Make this explicit in AGENTS.md rather than leaving it for the agent to figure out. **Gap 3: `_registry.json` generator needs to be a hook, not a manual script.** If the registry is generated by running a script, someone has to remember to run it. Use a `before_prompt_build` hook or a file watcher that regenerates on any README.md change. Otherwise you'll have the same drift problem you're solving — Mission Control reads stale data because someone forgot to run the generator after updating a README. **Gap 4: No project archival lifecycle.** Your status field has `active | paused | blocked | complete`, but there's no convention for what happens to completed projects. Do they stay in `workspace/projects/` forever? That's fine for 6 projects; it's a problem at 30. Consider a `workspace/projects/_archive/` directory with the convention: completed projects get moved there. They're still scannable, still in git history, but they don't appear in the active registry or get injected into the agent's orientation context. **Gap 5: STATE.md has no schema, which means cross-project queries are fragile.** Your README.md has YAML frontmatter — machine-parseable, queryable, consistent. Your STATE.md is free-form markdown. This means "show me all projects with blockers" requires the agent to read and interpret every STATE.md individually. Consider adding minimal YAML frontmatter to STATE.md too: ```yaml --- last_session: 2026-03-04 blocker: true blocker_owner: mark next_action: "Reverse JEs 21254-21259" --- ``` Then your registry generator can include `has_blocker: true` and `next_action` in `_registry.json`, and Mission Control can show a blockers dashboard without parsing free-form markdown. --- ### Production Comparison: Where This Sits | System | Scope | Storage | Registry | Multi-project | Session continuity | |--------|-------|---------|----------|---------------|-------------------| | **Your proposal** | Portfolio-wide | Files (README+STATE+LOG) | Auto-generated JSON | Yes (core design) | Prompt rule (needs enforcement upgrade) | | **multi-workplace** | Per-project switching | `.workplace/` per repo | `current.json` + scan | Partial (switch, not overview) | Per-workspace agents | | **APM** | Single project, deep | `.apm/Memory/` hierarchy | Memory_Root.md | No | Handover protocol | | **CCPM** | Single project, PM-focused | `.claude/` hierarchy | Epics/PRDs | No | Issue-based state | | **Google ADK** | Framework-level | Session + Memory services | Compiled views | Yes (via sessions) | Session persistence | Your proposal occupies a niche that the community tools don't: **multi-project, portfolio-level, file-based, convention-over-configuration, with a live dashboard reader.** The closest thing is the `openclaw-workspace-structure` skill, which has a `workspace/projects/` directory with per-project README.md, sprint tracking, and shared knowledge files. But that skill is a template, not an operational system — it describes what folders should exist, not how they interact with a dashboard or how an agent uses them. --- ### Final Assessment **This is not reinventing a worse wheel.** The community has fragments of this solution — multi-workplace switching, project tree generation, APM-style memory banks — but nobody has assembled them into a coherent portfolio-level registry that's both agent-readable and dashboard-connected. Your proposal is the right shape. **What would make it best-in-class:** 1. **Hook-based STATE.md commits** — don't rely on the agent remembering to update state before session close. Use a file watcher or cron that auto-commits state changes. 2. **YAML frontmatter on STATE.md** — make cross-project queries machine-parseable, not dependent on free-form markdown interpretation. 3. **Hook-based registry regeneration** — `_registry.json` should auto-regenerate on any README.md change, not require manual script execution. 4. **Two-path spawning convention** — context path (`workspace/projects/{name}/`) vs. work path (`code_location` from frontmatter) as an explicit, documented pattern. 5. **Archive lifecycle** — `_archive/` directory for completed projects to keep the active set small and the orientation context bounded. The one-line summary holds: folders + markdown + one JSON index. The implementation details above are what separate "works in demo" from "works at 3am when the agent crashes mid-session."