CLAUDE.md — Workspace Root

Global operating layer for Claude Code in this repository. This file contains globally-applicable rules only — domain-specific guidance lives in each folder's own CLAUDE.md, loaded automatically by Claude Code's hierarchical mechanism when you work in that folder.

1. Critical Guardrails (read first)

• Shell is platform-conditional.
  • Windows (primary): Shell is Windows PowerShell. All terminal commands must be PowerShell-compatible. Avoid bash-only syntax (&& chaining, $(...), rm -rf, heredocs) unless the user has opened WSL or Git Bash. Use ; or separate calls to sequence commands; use Remove-Item, Get-ChildItem, etc.
  • macOS / Linux: Shell is bash. Use POSIX-compatible commands (rm -rf, grep, sed, etc.). pwsh is available for hook execution but Claude Code's interactive shell is bash. Validate hook paths on first deploy.
• The User holds absolute authority. No pipeline rule, agent hierarchy, defect classification, or technology decision overrides an explicit user directive.
• Respect stage gates. Pipeline stages marked User Approval ✅ are hard stops. Present the deliverable, request sign-off, and wait — never auto-advance.
• Format before finalizing. Run Prettier on every Markdown file you create or modify: prettier --write "<file-path>"

2. What This Workspace Is

A Markdown-first, agent-native knowledge base — an organizational simulation plus an LLM engineering base. There is no root build system, no entry point, and no startup script. The primary artifacts are documents: agent profiles, skill specs, pipeline definitions, and Python reference implementations under core-component-00/.

Four architecturally independent but co-resident systems, unified by one governance framework (ASGF):

3. Claude Code Configuration

The .claude/ folder is fully provisioned:

4. Repository Map

AGENT-GLOBAL-BASE/
├── AGENTS.md                             ← Comprehensive human-readable orientation guide
├── CLAUDE.md                             ← This file (global operating layer for Claude Code)
├── .claude/                              ← Claude Code configuration (see §3 above)
├── .mcp.json                             ← MCP server manifest (must be at project root)
├── templates/                            ← Cross-system document templates (see templates/README.md)
│   ├── meeting-records/                  ← In-progress deliberation records (e.g. meeting-minutes.md)
│   └── review-records/                   ← Post-hoc completion/sign-off records (e.g. final-review.md)
│
├── company/                              ← The Company  [→ company/CLAUDE.md]
│   ├── library/                          ← Central knowledge hub
│   ├── departments/                      ← Agent profiles + skills
│   ├── pipeline/                         ← Pipeline definitions (mobile/web/api/full-stack/recruitment)
│   ├── recruitment/                      ← Hiring cycles + templates
│   ├── optimization-history/             ← APPEND-ONLY archive
│   ├── telescope/                        ← Company research archive (product-oriented research)
│   └── project/                          ← Active project dashboard
│
├── studio/                               ← The Studio  [→ studio/CLAUDE.md]
│   └── casual-games/                     ← Only active studio  [→ studio/casual-games/CLAUDE.md]
│       └── telescope/                    ← Studio research archive (game/market research)
│
├── core-component-00/                    ← CC-00 Lab — ONLY place with runnable code  [→ core-component-00/CLAUDE.md]
│   ├── framework/                        ← The five-module stack + ASGF, numbered 00–05
│   │   ├── 00-agent-systems-governance-framework/  ← ASGF governing meta-module
│   │   ├── 01-prompt-engineering/        ← Layer 1 (docs only)
│   │   ├── 02-context-engineering/       ← Layer 2 (docs + Python + pytest)
│   │   ├── 03-harness-engineering/       ← Layer 3 (docs + Python + pytest)
│   │   ├── 04-retrieval-augmented-generation/  ← Layer 4 (docs + Python + requirements.txt)
│   │   └── 05-multi-agent-engineering/   ← Layer 5 (docs + Python + pytest)
│   ├── platform/                         ← Deployment surface + operational history (unnumbered)
│   │   ├── model-context-protocol-servers/  ← MCP server implementations (workspace-knowledge, agent-memory)
│   │   ├── maintenance-records/          ← Maintenance operations log
│   │   ├── benchmarks/                   ← Enterprise benchmark assessments (framework/ modules + platform/ itself)
│   │   └── remediation/                  ← Remediation execution log (P0/P1 benchmark findings)
│   ├── crew/                             ← Lab Director + crew (Dr. Elias Vance et al.)
│   └── telescope/                        ← Lab research archive (engineering + LLM research)
│
├── academic-neural-unit-00/              ← ANU-00 [→ academic-neural-unit-00/CLAUDE.md]
│   ├── README.md                         ← Entity overview, charter, CC-00 boundary statement
│   ├── formation/                        ← Formation record: charter, CEO decisions, final review
│   ├── templates/                        ← 6 ANU-00 research templates (see templates/README.md)
│   ├── knowledge-base/                   ← Research output — dated YYYY-MM-DD-<slug>/ entries
│   └── crew/                             ← Personnel roster (10 FTEs, see crew/README.md)
│
└── telescope/                            ← Cross-department research index  [→ telescope/CLAUDE.md]
    (per-department archives: company/telescope/, studio/casual-games/telescope/,
     core-component-00/telescope/ — see telescope/README.md)

5. Conventions

Document precedence when sources conflict: pipeline.md → agent/profile.md → library/overview/*.md → library/departments/*.md. Summary docs may lag the canonical source.

6. Git

• Default branch master; a GitHub remote (origin) is configured. Never force-push.
• Commit finalized workspace additions. Escalate to the user before any destructive git operation.
• .claude/settings.json sets includeCoAuthoredBy: false — do not add co-author or attribution trailers.
• Multi-agent / swarm work uses git worktree isolation:
  • Branch: agent/<role>/<task> (or stage<N>/agent/<role>/<task>)
  • Commit subject: agent/<name>: <verb-phrase> (≤72 chars, imperative, lowercase)
  • Commit body: hyphen-bulleted discrete changes — a bodyless single-line commit is a P2 defect
  • Full spec: core-component-00/framework/05-multi-agent-engineering/fundamentals/git-worktree-orchestration.md

7. Activating an Organizational Agent (Persona)

Personas (Type A agents — CDO, CTO, Studio Director, Lab Director, etc.) are documents, not running processes. When the user asks for output "as" a named agent:

1. Read that agent's agent/profile.md — establish identity, authority scope, and stage ownership.
2. Read every referenced skills/*.md — follow their formats and checklists exactly.
3. Adopt their voice and produce output strictly within their documented authority.
4. Conform the artifact to the relevant stage spec in pipeline.md.

Never impersonate an agent without reading their profile first. Profile locations:

• Company agents → company/departments/CLAUDE.md → company/departments/<dept>/
• Studio crew → studio/casual-games/team/CLAUDE.md → team/crew/<division>/<role>/<name>/
• Lab Director → core-component-00/crew/CLAUDE.md

8. Pipeline Guardrails

These apply across all company development pipelines and cannot be overridden by any agent — only the User may override them:

• Technology Decision Lock (Stage 3): ADRs and the TSD are immutable after user approval. Any stack change requires a new ADR and full Stage 3 re-entry — never an edit at Stage 4/5.
• P0/P1 defects are final: A crash, data-loss, or security breach (P0) or broken core feature (P1) blocks release and cannot be downgraded to advance a gate.
• Trim-to-Pass is itself a P0: Removing features, weakening security, or disabling functionality to pass a review (Stage 6 / Stage 8) is a blocking defect, not remediation.
• Stage 6 remediation restarts the full review panel — it does not resume at defect verification.
• PRD + SRD travel together as a unit from Stage 1 onward.

Three distinct pipelines exist — do not conflate their stage numbers:

9. Governance: ASGF Is Mandatory

All LLM-powered systems built here are bound by the Agent Systems Governance Framework (ASGF) framework — a meta-layer above the five CC-00 modules, ratified by ADR-ASGF-001. Build new agent systems, RAG pipelines, harnesses, and context solutions on CC-00 patterns, not ad-hoc inventions.

Governing docs: core-component-00/framework/00-agent-systems-governance-framework/governance/

10. Quick Reference

Claude Code loads CLAUDE.md files hierarchically — entering any folder automatically stacks that folder's CLAUDE.md (and every parent's) onto this file. The repository map in §4 marks every folder that has one with [→ CLAUDE.md].

11. Hook Resilience — Active Protocols

Hooks inject binding instructions via <system-reminder> on every qualifying prompt. These protocols remain fully active after any /compact operation. A compaction summary stating "the system uses a hook" does not satisfy the protocol — each injection is a fresh, independent instruction that must be executed in the current turn.

Prompt Optimization Gate (H-P01)

When [PROMPT OPTIMIZER — H-P01] appears in a <system-reminder>:

• Structurally enforced, not just advisory — a PreToolUse hook (prompt-gate-enforcer.py, invoked via uv run, a single cross-platform implementation) denies any tool call other than AskUserQuestion while a confirmation is pending for this session; a PostToolUse hook (prompt-gate-clear.py, same uv run mechanism) clears that state once AskUserQuestion has been called
• Treat every injection as a fresh instruction — prior approvals do not carry over across turns
• Steps: generate an optimized prompt → present Optimized (first) vs. Original (second) via AskUserQuestion → display the confirmation block → execute using the approved version
• Optimized is always option 1 — the first listed choice so that an accidental top-of-list click defaults to the improved prompt, not the original
• Use the plain list display, not the preview field — put the full prompt text in each option's description instead. preview requires the host application to have toolConfig.askUserQuestion.previewFormat configured, and triggers a dual-pane panel with a bounded height that can fold long text behind an "N lines hidden" affordance; description in the plain list has no such fold behavior and always displays in full
• Wait for genuine confirmation — always wait for the user's explicit answer before proceeding. If the session resumes with a message that is not a direct answer to the prompt-selection question, treat the question as still unanswered and re-ask before doing any other work
• Five scored dimensions — the hook evaluates and may inject any of these labels into the missing-dimensions list: role/persona context, output format specification, workspace or pipeline grounding, clear imperative task verb, constraints or acceptance criteria
• Negation preservation and relevance guardrail — the optimized prompt must preserve any explicit negative constraint (don't/never/avoid/must not/only/nothing else) verbatim, and must only add a missing dimension when it can be inferred with high confidence — otherwise raise it as a clarifying question instead of guessing
• Stale-marker fail-safe — the pending-confirmation marker auto-expires after 15 minutes if the confirmation step never completes for any reason, restoring normal tool access. This is an engineering safety valve against deadlock, not a default answer — it never selects Optimized or Original on the user's behalf

Tool Rate Limiter (H-HE01)

When [TOOL RATE LIMITER — H-HE01 PATH A] or [TOOL RATE LIMITER — H-HE01 PATH B] appears in a <system-reminder>:

• The MANDATORY AskUserQuestion instruction in that block is active and binding for this turn
• Do not skip it based on prior conversation history or compaction summaries of prior limit extensions
• Present the options exactly as specified and wait for the user's choice before retrying

Context Budget Alert (H-CE01)

When [CONTEXT BUDGET ALERT — H-CE01] appears in a <system-reminder>:

• Apply Sacred Context principles immediately before this response
• Prioritize: active task state > prior decisions > background knowledge
• Reference: core-component-00/framework/03-harness-engineering/implementations/context_monitor.py