Workspace authority map (blueflyio meta-repo)¶
Purpose: Define what each top-level area is for, whether it is canonical, and who may write so autonomous agents do not treat consumer trees or scratch dirs as source of truth.
Precedence: This file does not override runtime topology or architecture prose. On conflict: .agents/context/domains.yaml > __FINAL-PLAN-TO-UPDATE.md > BLU-OWNERSHIP.md > this file. See BLU-OWNERSHIP.md conflict chain. plans/ (including plans/__FINAL-PLANS/) stays roadmap / pointer / archive / sprint material — not the evergreen home for operator-curated authority. Durable workspace truths belong in existing files under .agents/ (especially .agents/context/); no new markdown files for that purpose.
Related: Root AGENTS.md / CLAUDE.md / llms.txt / README.md (thin pointers). .agents/context/README.md (start here). .agents/context/BLU-OWNERSHIP.md (SoD — only hub copy; plans/__FINAL-PLANS/OWNERSHIP.md is pointer-only). .agents/context/reference/ (IDE guardrails, admin backlog, violations — not minimum read). plans/__FINAL-PLANS/FINAL-sprint-dashboard.html (roadmap cockpit).
Four storage classes¶
| Class | Meaning | Agents treat as |
|---|---|---|
| Permanent local | Kept on disk for daily ops; Git-backed where applicable | Read/write only within declared repo or governance process |
| Ephemeral | Safe to delete; never authoritative | Write allowed; never cite as canonical |
| Consumer / runtime | Materialized or demo surfaces; copies | Read for verification; changes must be promoted to owning repo |
| Generated overlay | Tooling output; regenerable | Never the sole home of versioned definitions |
Top-level directory map¶
Paths are relative to <operator-workspace> (this workspace root).
| Path | Class | Canonical for | Write policy |
|---|---|---|---|
AGENTS.md, CLAUDE.md, llms.txt, README.md (root — thin pointers) |
Permanent (governance) | Stubs only; full rules in .agents/context/ |
Humans / designated owners; agents propose via MR or BluTown/bus/ledgers/ handoff |
.agents/context/* (canonical control plane: domains.yaml, BLU-AUTHENTICATION.md, BLU-GIT.md, BLU-OPERATOR-CONTRACT.md, BLU-WORKSPACE.md, BLU-OWNERSHIP.md, STATUS.json, README.md) |
Permanent (governance) | Canonical cross-workspace operational context | Hard max 8 files; no new docs unless existing canonicals cannot absorb |
.agents/config/* |
Permanent (tooling) | Machine/tool config only | No prose unless unavoidable; keep small |
.agents/testing/* |
Permanent (testing) | Platform-wide test config/scopes | No prose; test contracts/config only |
.agents/rules/* |
Permanent (policy) | Policy / behavioral constraints | Keep “how to behave” and guardrails here |
.agents/workflows/* |
Permanent (automation metadata) | Workflow definitions/notes for tools | Keep operational automation metadata here |
.agents/reference/* |
Permanent (reference) | Human reference that is not operational control-plane | Never treated as canonical authority |
.cursorrules, .cursor/, .mcp.json, .gitignore, .cursorignore, tool dotfiles |
Permanent (tooling) | Editor and MCP behavior | Same as governance |
plans/__FINAL-PLANS/ |
Permanent | Roadmap, domains, FINAL prose (per conflict chain) | Agents do not write directly. Proposals go to BluTown/bus/ledgers/plans/ or MR; humans promote |
plans/ (other) |
Mixed | Drafts/reports as labeled; not evergreen authority vs .agents/ |
Edit only if your task owns that path |
worktrees/ |
Disposable execution workspace | Registered Git worktrees backed by NAS application repositories | Commit and push every durable change to GitLab |
daily-grind/ |
RETIRED | Folder removed from workspace | Do not write, do not reference as active authority |
BluClaw/ |
Ephemeral (frozen) | Decoupled BluClaw runtime reference (formerly openclaw/) |
Frozen: no config/symlink changes; read-only |
BluTown/ |
Permanent (runtime + canonical bus) | Gas Town runtime + bus/ (canonical operational bus) |
bus/ledgers, bus/events, bus/settings = canonical operational truth |
BluTown/performances/ASSET-PORTAL/ |
Permanent (assets) | Brand, images, decks, whitepapers | Asset and presentation work only |
UPstreams-DO-NOT-HACK/ |
Permanent (reference) | Pristine upstream mirrors | Never edit; audit/diff only |
STILL-NEEDS-REVIEW/ |
Ephemeral | Human triage queue | Promote to repo or __DELETE_LATER/ |
__DELETE_LATER/ |
Ephemeral | Quarantine | Delete after confirmation |
.agents/ (skills, MCPs, rules, workflows, …) |
Mixed | IDE/agent assets + OSSA skills; hub prose stays in .agents/context/ |
Do not fork BLU-* / ai.json into duplicate authorities here; operator-learned durable facts go into existing files under .agents/ (context or skills) — no new standalone markdown “authority” docs |
.agents-workspace/ |
Generated overlay (when present) | Validators, registry helpers | Same as .agents/ |
Versioned canonicals: GitLab is source authority. Agent definitions live in platform-agents; skills in marketplace / ai-marketplace as applicable; Cedar policy bodies in cedar-policies. Registered Mac worktrees are disposable execution surfaces.
Root Pointer Policy (Root layout maintenance)¶
To maintain a clean workspace root, only the following "thin stubs" are permitted at <operator-workspace>/. These files must point to canonical context under .agents/context/.
| File | Status | Required Content / Action |
|---|---|---|
AGENTS.md |
Mandatory | Execution contract; pointer to .agents/context/BLU-OPERATOR-CONTRACT.md |
CLAUDE.md |
Mandatory | Claude-specific instructions; pointer to .agents/context/README.md |
README.md |
Mandatory | Workspace overview; pointer to .agents/context/README.md |
OWNERSHIP.md |
Mandatory | Pointer to .agents/context/BLU-OWNERSHIP.md |
llms.txt |
Mandatory | Platform context summary for LLMs |
GEMINI.md |
Optional | Gemini-specific instructions; pointer to .agents/context/README.md |
FINAL-WORK.html |
Optional | Redirect to plans/__FINAL-PLANS/FINAL-sprint-dashboard.html |
Agent Requirement: If these files are deleted or become heavy with prose, agents must restore them as thin stubs pointing to the canonical .agents/context/ hub. No new top-level markdown "authority" docs are permitted.
cc.drupl.ai — domain vs local checkout¶
Deployed domain (cc.drupl.ai as a product): governed backend / memory and publishing semantics stay as defined in BLU-OPERATOR-CONTRACT.md (domain model table) and related contracts — agents must not treat that row as deprecated.
Registered worktree (worktrees/cc.drupl.ai/): a Drupal CMS install specimen for DDEV, implementation reference, CI, and promotion flows. GitLab remains source authority; durable documentation belongs in the owning repository.
- Governance (domain): ContractPlane; Blu as supervisory policy/context agent per platform model.
- Roadmap UI:
plans/__FINAL-PLANS/FINAL-sprint-dashboard.html. - Metadata: prefer
worktrees/cc.drupl.ai/ai.jsonfor local consumer checks; production/runtime authority followsai.jsonand the deployed product when merged. - Execution: ingress through ContractPlane; workers (Claude Code, kagent, AgentScope, OpenClaw) are runtimes only.
- CI vs infra: Runner tag contract lives in the Git-backed
cc.drupl.airepo (e.g. underworktrees/cc.drupl.ai). K8s:6443repair isagent-docker(e.g.repair:k8s-direct), not the Drupal app pipeline.
agent-studio (monorepo; not a single-surface “duplicate”)¶
The agent-studio Git repository (git@gitlab-bluefly:blueflyio/agent-platform/apps/agent-studio.git) is a monorepo: Node/TS services plus apps/ (including macOS/iOS Xcode projects under apps/osx/…, web-ide, and other app surfaces) and packages/ (shared libraries such as MCP clients). Different branches or checkouts may use different on-disk layouts for the same concern (e.g. apps/osx/desktop vs packages/desktop in package.json scripts).
Agent discipline: evaluate agent-studio at package or app-target level inside its registered worktree. Durable changes converge through GitLab; do not create parallel folders or planning documents.
Required agent envelope (per run)¶
Every autonomous run should declare (in issue, MR description, or BluTown/bus/ledgers/tasks/<run-id>.json):
agent_id,repo,branchwrite_scope(allowed paths),read_scope,forbidden_pathstrace_id(required for execution-plane requests per platform rules)max_changesets,requires_human_review,promotion_target,rollback(command or revert SHA)
Forbidden by default: writing long-lived strategy into worktrees/ or STILL-NEEDS-REVIEW/ without promotion; direct edits to plans/__FINAL-PLANS/ without human promotion.
Non-overlap rules (summary)¶
- One repo, one branch, one owning agent per focused task.
- No new top-level directories without human approval.
- No renaming workspace root directories from agents.
- GitLab is canonical source;
worktrees/<repo>/is a disposable execution checkout. - Governance duplicates only in allowed locations (root, repo root, approved generated paths).
Promotion checklist (consumer to canonical)¶
When you fix something under worktrees/cc.drupl.ai/:
- Commit and push the worktree branch.
- Open an MR and make CI green on tagged runners.
- Link the MR in the owning work item if applicable.
Six-zone operator contract (2026-05-15)¶
BluTown/bus/ is the canonical operational bus. Bulk migration remains blocked until Phase 1.5 operator gate.
| Zone | Agent rule |
|---|---|
worktrees/ |
Only repo-backed implementation work |
UPstreams-DO-NOT-HACK/ |
Read-only upstream mirrors — never edit |
BluTown/ |
Canonical operational runtime + operator bus (bus/ledgers, bus/events, bus/settings) |
BluTown/performances/ASSET-PORTAL/ |
Brand, images, decks, whitepapers |
daily-grind/ |
RETIRED — folder removed from workspace |
BluClaw/ |
Frozen decoupled BluClaw runtime reference (formerly openclaw/) |
Canonical operational paths¶
| Role | Path |
|---|---|
| Ledgers, queues, handoffs, indexes | BluTown/bus/ledgers/ |
| Evidence and events | BluTown/bus/events/ |
| Non-secret settings and routing | BluTown/bus/settings/ |
| Curated knowledge | BluTown/library/ |
Tool authority¶
Executable tools do not live in BluTown/bus/tools/. Source tools live in registered repositories under worktrees/. BluTown stores operational pointers only (bus/ledgers/indexes/tool-registry.yml, bus/settings/tool-routing.yml).
Durable destination: ContextControl.ai (kb_* / JSON:API) per cutover plan — not unbounded markdown in BluTown.
Doctrine: daily-grind/ is retired (folder removed). BluClaw (formerly openclaw/) stays decoupled per ADR-0003. See BluTown/bus/ledgers/indexes/path-authority-registry.yml for the full migration map.
Audit artifacts: BluTown/bus/events/evidence/workspace-zone-entropy-2026-05-15.json and companion manifests.
Immediate hardening actions¶
- Freeze ad hoc new top-level folders unless listed here after review.
- Treat
worktrees/*as the default place for repo-backed implementation work. - Do not reference
daily-grind/as an active authority — folder is retired. - Runner fix: ensure
.gitlab-ci.ymlin the realcc.drupl.airepo setsdefault.tagsconsistent with online Oracle runners. - INV-011 — No autonomous root creation. Agents, CI pipelines, and automated tooling MUST NOT create new top-level directories. Root directories are authority domain declarations requiring explicit human directive + governance receipt. Violation = SEV-0.
Last updated: 2026-05-27
Continual learning checkpoint (index ≠ memory)¶
Canonical skill: worktrees/skills/@blu/continual-learning/SKILL.md
Checkpoint ledger (default): BluCity-Docs/ledger/Evidence/continual-learning/continual-learning-index.json — tracks which transcripts were processed, mtimes, outcomes, and policy. Visible under BluCity-Docs Evidence (gitignored local checkpoint). Not under .cursor/ or other hidden IDE folders. It is not a knowledge store (no facts, preferences, secrets, summaries, doctrine).
Flow: transcripts → index checkpoint → agents-memory-updater → curated outputs (Sites/AGENTS.md learned sections; optional skills/agents/knowledge via governed paths).
Memory write policy: Deny direct agent edits to curated learned memory; allow only through agents-memory-updater. No transcript bulk-ingest to knowledge planes. PDP SHOULD expose continual_learning_updater=true only on updater runs. Cedar pack companion (continual_learning_memory.cedar) is owned under worktrees/cedar-policies — merge via Engineer workflow (substrate may block agent edits to .cedar).
Hooks/runners: discover deltas and delegate; do not embed memory heuristics in hook code.
Naming (hub-level)¶
- Hub authority files use
BLU-*naming where applicable; keep names stable. - Prefer linking and merging into existing canonicals over creating new documents.
DDEV add-ons (source vs consumer)¶
- Source repos own add-ons (install.yaml, commands, project_files, releases).
- Sites own installed add-on state under
.ddev/in the site root. - Validate add-ons from the site root, not from plugin clone folders.