Arcanea Meta

---
name: arcanea-meta
description: "Arcanea ecosystem self-description. Use when asked about the system map, where things live, canonical locations, how to add a skill/command/agent/hook, how to absorb a repo, or what's installed. Trigger phrases: arcanea meta, system map, where does X live, add a skill, absorb a repo, what's installed, ecosystem inventory."
---

# Arcanea Meta

The system describing itself with the same primitives it uses to build everything else. This skill is the load-bearing meta layer — the place to start when you don't know where something lives.

## Mental model

Arcanea is **not one repo**. It is an ecosystem of ~90 repos at github.com/frankxai, plus four installed plugins, plus a hierarchy of skills/commands/agents/hooks at three scopes:

```
GLOBAL  (~/.claude/)               ← user-scope, every project sees this
PROJECT (<repo>/.claude/)           ← per-repo overrides + additions
PLUGIN  (~/.claude/plugins/cache/)  ← marketplace-installed (read-only)
```

Most failures come from forgetting which scope a thing lives in. Default rule: **if it's reusable across repos, put it global. If it's Arcanea-specific, put it project. Never duplicate across both.**

## Canonical locations (verified 2026-04-15, see `references/canonical-locations.md` for full table)

| Concern | Canonical | Why |
|---|---|---|
| Memory | `~/.claude/projects/C--Users-frank-Arcanea/memory/` | Auto-loaded via MEMORY.md every turn |
| ACOS source | `~/agentic-creator-os/` | Has FRANK_DNA.md + memory.db (irreplaceable) |
| ACOS runtime | `~/.claude/acos/` | What the harness actually invokes |
| Arcanea monorepo | `~/Arcanea/` | Web app + packages + lore + book |
| Validation contract | `~/Arcanea/CLAUDE.md` § Cached-Belief Validation Protocol | Loads every turn |
| Hooks (project) | `~/Arcanea/.claude/hooks/` | 9 hooks, project-scope |
| Hooks (global) | `~/.claude/hooks/` | 3 hooks, user-scope |
| Skills | scattered (see `references/installed-stack.md`) | Migration ongoing |
| Source clones (for absorption) | `~/sources/` | Pre-integration staging |

When in doubt, read `references/canonical-locations.md`.

## What's installed (verified 2026-04-15)

- **4 Claude plugins** (typescript-lsp, vercel, superpowers v5.0.7, superpowers-lab v0.4.0)
- **2 marketplaces** (anthropics/claude-plugins-official, obra/superpowers-marketplace)
- **42 global agents**, **84 global commands** (~/.claude/{agents,commands}/)
- **~100+ skill directories** (~/.claude/skills/ + ~/Arcanea/.claude/skills/)
- **9 project hooks + 3 global hooks** (no overlap by name yet)

Update by re-running the verification commands in `references/installed-stack.md`. Treat the numbers as stale after 7 days.

## Meta-rules (the contract)

1. **Disk-first, memory-as-history.** Any claim about current state (versions, ship status, file paths, architecture, deploy state) requires same-turn verification OR explicit "unverified, from memory:" prefix. Memory authoritative only for intent, strategy, preferences, decision history. (See `references/validation-contract.md`.)

2. **Canonical wins.** When two copies exist, the canonical (per `canonical-locations.md`) is truth. Drift copies get `DEPRECATED_DELETE_AFTER_VERIFY.md` markers, never silent edits.

3. **Absorption is provenance.** Claiming "absorbed pattern X from repo Y" requires entry in `references/absorption-log.md` with source URL, commit SHA, integrated-at path, date, verifier. No vague "we took inspiration from" allowed.

4. **Scope before content.** Before adding a skill/command/agent/hook, decide scope (global vs project vs plugin). Wrong-scope additions create the duplication that broke ACOS.

5. **Progressive disclosure.** SKILL.md stays under 3K words and contains the mental model + workflow skeleton. Depth lives in `references/`. Skills that violate this become unreadable monoliths (the original acos-meta did this — it teaches progressive disclosure but didn't use it).

## How to add a skill

```
1. Decide scope:
   - Global (multi-repo use)  → ~/.claude/skills/<name>/
   - Project (Arcanea-only)   → ~/Arcanea/.claude/skills/<name>/
2. Create SKILL.md with YAML frontmatter (name + description with trigger phrases)
3. Keep SKILL.md under 3000 words. Mental model + workflow + key principles.
4. Create references/ subdirectory for depth content.
5. Test: invoke the trigger phrase, verify activation.
```

## How to add a command

```
1. ~/.claude/commands/<name>.md (global) or project-scope equivalent
2. YAML frontmatter: description, optional argument-hint
3. Body is a markdown workflow — no code, pure instructions
4. Reference skills/agents by name; the harness wires them
5. Test: /<name> [args]
```

## How to add an agent

```
1. ~/.claude/agents/<name>.md
2. Frontmatter: description with usage examples, model preference (optional)
3. Body = the agent's system prompt (role, capabilities, constraints, output format)
4. Invoke via Agent tool with subagent_type=<name>
```

## How to add a hook

```
1. Decide event: SessionStart | UserPromptSubmit | PreToolUse | PostToolUse | Stop | SessionEnd | Notification
2. Write ~/.claude/hooks/<name>.sh (global) or ~/Arcanea/.claude/hooks/ (project)
3. Register in settings.json (or settings.local.json) under "hooks": { "<Event>": [...] }
4. Test: trigger the event, check the hook ran (logs at ~/.arcanea/sessions/current/)
```

Hook count discipline: stay under 12 total. When two hooks share >30% logic, extract a shared lib.

## How to absorb a repo

The contract (no exceptions):

```
1. git clone --depth=1 <url> ~/sources/<name>/
2. Capture HEAD SHA, list 3-5 specific patterns/files you want
3. Add entry to references/absorption-log.md (source, SHA, patterns, target paths, date, verifier)
4. Integrate the patterns at the target paths (separate session/PR)
5. Update absorption-log.md status: cloned → integrated → verified
6. After integration verified, decide: keep clone for reference or rm -rf ~/sources/<name>
```

Vague "inspired by" or "we took ideas from" is not absorption. Either it's logged with provenance or it didn't happen.

## Validation contract integration

This skill is the home for the validation contract designed in 2026-04-15 session:
- L0 Authority Registry → `.arcanea/AUTHORITY.md` (deferred, Week 2)
- L1 Memory frontmatter → migration plan in `references/validation-contract.md` (deferred, Week 2)
- L2 CLAUDE.md protocol → root `CLAUDE.md` § Cached-Belief Validation Protocol (Week 1 ship target)
- L3 `/verify-status` skill → deferred Week 3
- L4 Stop-hook claim audit → deferred Week 4

Status of Week-1 ship: **designed, Guardian-approved, not yet shipped to disk.**

## When this skill activates

Use when:
- "What's installed?" / "What do we have?"
- "Where does X live?" / "Where should I add Y?"
- "How do I add a skill/command/agent/hook?"
- "How does absorption work?" / "Did we absorb repo X?"
- "What's the canonical version of Z?"
- Onboarding a new tool, repo, or capability
- Auditing for drift, duplication, or stale claims

Don't use for: domain work (code, content, design, lore). Route to domain skills/agents.

## References

- `references/ecosystem-map.md` — full repo inventory + spot-check freshness
- `references/installed-stack.md` — verified plugin/skill/agent/command/hook counts + how to re-verify
- `references/canonical-locations.md` — which copy wins for every concern, archival plan for drift
- `references/absorption-log.md` — strict-format provenance table
- `references/validation-contract.md` — full 5-layer contract spec + rollout plan