Atlas-Audit Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build /atlas-audit — Atlas's comprehensive fleet efficiency audit skill with SSOT-grounded metrics, structural improvements, and monitoring.

Architecture: Five sequential tasks: SSOT Guide (documentation), fleet_rules insertion (CLI-first rule), Supabase metrics tables (DDL), the skill itself (SKILL.md + measurement script), and Arsenal distribution (symlinks).

Tech Stack: Markdown (guide + skill), SQL (Supabase DDL), Bash (measurement script), PostgREST (metrics writes via curl)

Spec: docs/superpowers/specs/2026-04-15-atlas-audit-design.md

View: https://mockups.test/2026-04-15-atlas-audit-design/

Task 1: Write the SSOT Guide

The SSOT Guide is the reference document that defines the system. The atlas-audit skill references it for classification decisions. Every agent in the fleet should be able to read this and understand how facts flow.

Files:

• Create: docs/ssot/GUIDE.md

• [ ] Step 1: Create the directory

mkdir -p docs/ssot

• [ ] Step 2: Write the SSOT Guide

The guide must cover these sections. Source the content from existing artifacts — do NOT invent new definitions:

Structure:

# SSOT Guide — Pantheon Fleet Single Source of Truth

## The Principle
{Operator's exact words from fleet_rules s6#8 + NEXT-SESSION-SSOT-SCOPE.md}

## Fact vs Statement
{Classification rule with examples}

## Trust Levels
| Level | Where it lives | Example |
...

## Four Layers
### Storage
### Injection
### Retrieval
### Recording

## CLI-First Protocol
{Rule text + efficiency data from 2026-04-15 benchmarks}

## Fleet Tables
{Table inventory with what each answers}

## Tool Reference
{fleet CLI subcommands, fleet-path, when to use each}

## Anti-Patterns
{What NOT to do}

Keep it under 300 lines. This is a reference, not a narrative. Facts, tables, commands.

• [ ] Step 3: Verify the guide is self-consistent

Read the guide back. Check:

• Every fleet_rules reference can be verified with fleet rule <title>
• Every table name matches what's in fleet-ssot-ddl.sql
• Every CLI command works (fleet –help lists it)
• No hardcoded Supabase project IDs or URLs (SSOT guide must follow its own rules)

• [ ] Step 4: Commit

git add docs/ssot/GUIDE.md
git commit -m "docs(ssot): SSOT Guide — fleet single source of truth reference"

Task 2: Insert CLI-First Rule into fleet_rules

The CLI-first protocol was defined as a fleet-wide architectural decision in the 2026-04-15 war room. It needs to exist in fleet_rules before the skill can reference it.

Files:

• None (Supabase table write)

Prerequisite: PANTHEON_SUPABASE_SERVICE_ROLE_KEY or SUPABASE_DB_PASSWORD_PANTHEON must be available. If not, this task must be dispatched to Proteus who has write access.

• [ ] Step 1: Check write access

echo "Service key: ${PANTHEON_SUPABASE_SERVICE_ROLE_KEY:+SET}"

If SET, proceed. If not, write the INSERT statement to a file and dispatch to Proteus.

• [ ] Step 2: Insert the rule

curl -sf "${PANTHEON_SUPABASE_URL}/rest/v1/fleet_rules" \
  -H "apikey: ${PANTHEON_SUPABASE_SERVICE_ROLE_KEY}" \
  -H "Authorization: Bearer ${PANTHEON_SUPABASE_SERVICE_ROLE_KEY}" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '[{
    "section": 6,
    "rule_number": 9,
    "title": "cli-first-tool-protocol",
    "description": "CLI tools are the primary interface for fleet operations. MCP tools are fallback only — used when Bash is unavailable (sandboxed subagents, forked skills). For every MCP server in the fleet, a CLI equivalent must exist and must be the documented first-choice path. Agent harnesses (CLAUDE.md, skills) must reference CLI commands, not MCP tool names. Measured: CLI costs ~140 tokens per SSOT lookup vs ~970 for MCP (~7x difference).",
    "severity": "critical",
    "applies_to": "all",
    "origin": "operator-directive-2026-04-15"
  }]'

• [ ] Step 3: Verify

fleet rule cli-first-tool-protocol

Expected output includes severity=critical and applies_to=all.

• [ ] Step 4: Regenerate OPS.md section 6

fleet generate ops

This updates OPS.md §6 to include the new rule. Verify the rule appears in OPS.md.

• [ ] Step 5: Commit OPS.md if changed

git add OPS.md
git commit -m "ops: add CLI-first tool protocol rule (s6#9) — generated from fleet_rules"

Task 3: Create Metrics Tables

Three tables on Pantheon Supabase. These store the measurements that atlas-audit writes and the Atlas UI page reads.

Files:

• Create: docs/supabase/fleet-metrics-ddl.sql (the DDL for version control)

Prerequisite: Requires Proteus (has service_role key for Pantheon Supabase). If running as Atlas, write the DDL file and dispatch to Proteus for execution.

• [ ] Step 1: Write the DDL

-- Fleet Context Metrics — per-repo context efficiency measurements
CREATE TABLE IF NOT EXISTS fleet_context_metrics (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    repo TEXT NOT NULL,
    measured_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    measured_by TEXT NOT NULL,
    claude_md_chars INT DEFAULT 0,
    repo_rules_chars INT DEFAULT 0,
    global_rules_chars INT DEFAULT 0,
    memory_index_chars INT DEFAULT 0,
    memory_files_chars INT DEFAULT 0,
    memory_file_count INT DEFAULT 0,
    skills_count INT DEFAULT 0,
    skills_frontmatter_chars INT DEFAULT 0,
    agents_count INT DEFAULT 0,
    agents_chars INT DEFAULT 0,
    always_loaded_total INT DEFAULT 0,
    est_tokens INT DEFAULT 0,
    context_files_chars INT DEFAULT 0,
    audit_type TEXT NOT NULL DEFAULT 'full' CHECK (audit_type IN ('full', 'monitor'))
);

COMMENT ON TABLE fleet_context_metrics IS 'Per-repo context efficiency measurements from /atlas-audit';

-- RLS: anon can read, service_role can write
ALTER TABLE fleet_context_metrics ENABLE ROW LEVEL SECURITY;
CREATE POLICY "anon_read_context_metrics" ON fleet_context_metrics FOR SELECT TO anon USING (true);
CREATE POLICY "service_write_context_metrics" ON fleet_context_metrics FOR ALL TO service_role USING (true);

-- Fleet SSOT Compliance — per-repo alignment scores
CREATE TABLE IF NOT EXISTS fleet_ssot_compliance (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    repo TEXT NOT NULL,
    measured_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    hardcoded_facts INT DEFAULT 0,
    ssot_references INT DEFAULT 0,
    duplicate_rules INT DEFAULT 0,
    stale_memory_files INT DEFAULT 0,
    unverified_facts INT DEFAULT 0,
    compliance_score NUMERIC(5,2) DEFAULT 0 CHECK (compliance_score >= 0 AND compliance_score <= 100)
);

COMMENT ON TABLE fleet_ssot_compliance IS 'Per-repo SSOT alignment scores from /atlas-audit';

ALTER TABLE fleet_ssot_compliance ENABLE ROW LEVEL SECURITY;
CREATE POLICY "anon_read_ssot_compliance" ON fleet_ssot_compliance FOR SELECT TO anon USING (true);
CREATE POLICY "service_write_ssot_compliance" ON fleet_ssot_compliance FOR ALL TO service_role USING (true);

-- Fleet Tool Efficiency — session-level tool usage patterns
CREATE TABLE IF NOT EXISTS fleet_tool_efficiency (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    repo TEXT,
    session_id TEXT,
    measured_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    cli_lookups INT DEFAULT 0,
    mcp_lookups INT DEFAULT 0,
    toolsearch_calls INT DEFAULT 0,
    total_tool_calls INT DEFAULT 0,
    transcript_chars INT DEFAULT 0,
    cli_first_ratio NUMERIC(5,4) DEFAULT 0 CHECK (cli_first_ratio >= 0 AND cli_first_ratio <= 1)
);

COMMENT ON TABLE fleet_tool_efficiency IS 'Session-level tool usage patterns for CLI-first compliance';

ALTER TABLE fleet_tool_efficiency ENABLE ROW LEVEL SECURITY;
CREATE POLICY "anon_read_tool_efficiency" ON fleet_tool_efficiency FOR SELECT TO anon USING (true);
CREATE POLICY "service_write_tool_efficiency" ON fleet_tool_efficiency FOR ALL TO service_role USING (true);

Save to docs/supabase/fleet-metrics-ddl.sql.

• [ ] Step 2: Execute DDL on Pantheon Supabase

If you have SUPABASE_DB_PASSWORD_PANTHEON:

psql "postgresql://postgres:${SUPABASE_DB_PASSWORD_PANTHEON}@db.${PANTHEON_SUPABASE_REF}.supabase.co:5432/postgres" -f docs/supabase/fleet-metrics-ddl.sql

If not, dispatch to Proteus: "Execute docs/supabase/fleet-metrics-ddl.sql on Pantheon Supabase. Three new tables: fleet_context_metrics, fleet_ssot_compliance, fleet_tool_efficiency."

• [ ] Step 3: Verify tables exist

fleet query fleet_context_metrics "limit=0" "*" 2>&1
fleet query fleet_ssot_compliance "limit=0" "*" 2>&1
fleet query fleet_tool_efficiency "limit=0" "*" 2>&1

Each should return [] (empty array, no error).

• [ ] Step 4: Commit the DDL

git add docs/supabase/fleet-metrics-ddl.sql
git commit -m "schema(ssot): metrics tables DDL — context, compliance, tool efficiency"

Task 4: Build the atlas-audit Skill

The skill itself. This is the main deliverable. It lives in Arsenal and gets symlinked fleet-wide.

Files:

• Create: ~/Dev/_K4120S/arsenal/skills/atlas-audit/SKILL.md
• Create: ~/Dev/_K4120S/arsenal/skills/atlas-audit/scripts/measure.sh

• [ ] Step 1: Create the skill directory

mkdir -p ~/Dev/_K4120S/arsenal/skills/atlas-audit/scripts

• [ ] Step 2: Write the measurement script

scripts/measure.sh wraps the existing context-audit/scripts/scan.sh and adds SSOT compliance checks. It outputs JSON that the skill parses.

The script must:

1. Run scan.sh from Arsenal's context-audit skill against the target repo (reuse, don't rewrite)
2. Add SSOT compliance measurements:

• grep -c for hardcoded Supabase project IDs ([a-z]{20}\.supabase\.co) in CLAUDE.md + rules
• grep -c for fleet CLI references (correct SSOT usage)
• Count memory files that duplicate content from global rules (compare hashes or key phrases)

1. Output combined JSON to stdout

#!/usr/bin/env bash
# measure.sh — Context + SSOT compliance measurement for /atlas-audit
# Usage: measure.sh <repo-path> [--json]
set -euo pipefail

REPO="${1:?Usage: measure.sh <repo-path>}"
REPO="$(cd "$REPO" && pwd)"
ARSENAL="${ARSENAL_PATH:-$HOME/Dev/_K4120S/arsenal}"

# Phase 1: Context measurement (delegate to scan.sh)
CONTEXT_JSON=$("$ARSENAL/skills/context-audit/scripts/scan.sh" "$REPO" 2>/dev/null)

# Phase 2: SSOT compliance
CLAUDE_MD="$REPO/CLAUDE.md"
HARDCODED=0
SSOT_REFS=0
DUPLICATE_RULES=0

if [ -f "$CLAUDE_MD" ]; then
    # Hardcoded Supabase project IDs (20-char lowercase alpha strings followed by .supabase.co)
    HARDCODED=$(grep -cE '[a-z]{20}\.supabase\.co' "$CLAUDE_MD" 2>/dev/null || echo 0)
    # Also check for bare project IDs
    HARDCODED=$((HARDCODED + $(grep -cE 'https?://[a-z]{20}\.' "$CLAUDE_MD" 2>/dev/null || echo 0)))
    # Correct SSOT references
    SSOT_REFS=$(grep -cE 'fleet (agent|service|repo|daemon|path|rule|brief|query|list)' "$CLAUDE_MD" 2>/dev/null || echo 0)
fi

# Check rules for duplication with global rules
GLOBAL_RULES_DIR="$HOME/.claude/rules"
REPO_RULES_DIR="$REPO/.claude/rules"
if [ -d "$REPO_RULES_DIR" ] && [ -d "$GLOBAL_RULES_DIR" ]; then
    for rf in "$REPO_RULES_DIR"/*.md; do
        [ -f "$rf" ] || continue
        BASENAME=$(basename "$rf")
        for gf in "$GLOBAL_RULES_DIR"/*.md; do
            [ -f "$gf" ] || continue
            # Check if >50% of repo rule lines appear in global rule
            OVERLAP=$(comm -12 <(sort "$rf") <(sort "$gf") | wc -l | tr -d ' ')
            TOTAL=$(wc -l < "$rf" | tr -d ' ')
            if [ "$TOTAL" -gt 0 ] && [ "$OVERLAP" -gt $((TOTAL / 2)) ]; then
                DUPLICATE_RULES=$((DUPLICATE_RULES + 1))
            fi
        done
    done
fi

# Memory file staleness (count files >1KB as potential bloat)
MEMORY_DIR=$(find "$HOME/.claude/projects" -maxdepth 2 -name "memory" -type d 2>/dev/null | while read d; do
    if echo "$d" | grep -q "$(basename "$REPO")"; then echo "$d"; break; fi
done)
STALE_MEMORY=0
if [ -n "$MEMORY_DIR" ] && [ -d "$MEMORY_DIR" ]; then
    STALE_MEMORY=$(find "$MEMORY_DIR" -name "*.md" -not -name "MEMORY.md" -size +1k 2>/dev/null | wc -l | tr -d ' ')
fi

# Combine into output JSON
python3 -c "
import json, sys
context = json.loads('''$CONTEXT_JSON''')
context['ssot_compliance'] = {
    'hardcoded_facts': $HARDCODED,
    'ssot_references': $SSOT_REFS,
    'duplicate_rules': $DUPLICATE_RULES,
    'stale_memory_files': $STALE_MEMORY
}
json.dump(context, sys.stdout, indent=2)
"

Make it executable:

chmod +x ~/Dev/_K4120S/arsenal/skills/atlas-audit/scripts/measure.sh

• [ ] Step 3: Test the measurement script

~/Dev/_K4120S/arsenal/skills/atlas-audit/scripts/measure.sh ~/Dev/_K4120S/constellation-atlas | python3 -m json.tool | head -30

Verify it outputs valid JSON with both context measurements and ssot_compliance section.

• [ ] Step 4: Write SKILL.md

The skill file. This is what the agent reads when /atlas-audit is invoked. It must reference the SSOT Guide, use the measurement script, write to the metrics tables, and follow the four-phase protocol from the spec (Measure, Plan, Execute, Verify).

Structure the SKILL.md with:

• Frontmatter: name, description, user-invocable, argument-hint, allowed-tools
• Mode detection: full audit vs monitor (from argument)
• Phase 1 (Measure): run measure.sh, parse JSON, write to fleet_context_metrics via curl
• Phase 2 (Plan): present findings grouped by type, compute impact, ask operator to approve
• Phase 3 (Execute): apply approved changes (facts→fleet tables, statements→Aion, duplicates→remove, stale→archive)
• Phase 4 (Verify): re-run measure.sh, compute delta, write post-audit metrics
• Monitor mode: measure only, compare to last fleet_context_metrics row, flag drift >10%

Key rules to embed in the skill:

• All SSOT lookups use fleet CLI (CLI-first, per fleet_rules s6#9)
• Classification uses fleet_rules s6#8 (fact vs statement)
• Operator approves Phase 2 before Phase 3 executes
• Archive, never delete
• Reference the SSOT Guide: "Read docs/ssot/GUIDE.md for classification rules"

The SKILL.md should be 200-300 lines. The measurement script does the heavy lifting; the skill orchestrates the protocol.

---
name: atlas-audit
description: "Comprehensive fleet efficiency audit — measures context costs, SSOT compliance, and tool efficiency. Writes metrics to fleet tables. Full audit restructures repos; monitor mode flags drift. Atlas-owned, run per-repo or fleet-wide. Keywords: audit, efficiency, context, SSOT compliance, metrics, measure, monitor, drift."
user-invocable: true
argument-hint: "[<repo-path> | monitor <repo-path> | monitor --fleet]"
allowed-tools: Bash, Read, Edit, Write, Grep, Glob
---

Write the full SKILL.md content following the spec's four-phase protocol. Every phase must reference exact commands:

• measure.sh for Phase 1
• fleet rule ssot-fact-vs-statement for classification in Phase 2
• fleet CLI for all SSOT lookups
• curl POST to fleet_context_metrics and fleet_ssot_compliance for metrics writes

• [ ] Step 5: Test the skill invocation

The skill won't be callable via /atlas-audit until the next session (new skills aren't visible mid-session). But verify the files are correct:

# Check SKILL.md parses (frontmatter is valid)
head -10 ~/Dev/_K4120S/arsenal/skills/atlas-audit/SKILL.md

# Check measure.sh runs
~/Dev/_K4120S/arsenal/skills/atlas-audit/scripts/measure.sh ~/Dev/_K4120S/constellation-hades | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'Always-loaded: {d.get(\"total_always_loaded_chars\", \"?\")} chars')"

• [ ] Step 6: Commit

cd ~/Dev/_K4120S/arsenal
git add skills/atlas-audit/
git commit -m "feat(skills): atlas-audit — fleet efficiency audit with SSOT-grounded metrics"

Task 5: Fleet Distribution

Symlink the skill from Arsenal to Atlas and all constellation repos.

Files:

• Symlinks in each repo's .claude/skills/

• [ ] Step 1: Symlink to Atlas (primary)

ln -sf ~/Dev/_K4120S/arsenal/skills/atlas-audit ~/Dev/_K4120S/constellation-atlas/.claude/skills/atlas-audit

• [ ] Step 2: Verify symlink

ls -la ~/Dev/_K4120S/constellation-atlas/.claude/skills/atlas-audit
# Should show -> /Users/k4120s/Dev/_K4120S/arsenal/skills/atlas-audit

• [ ] Step 3: Decide on broader distribution

atlas-audit is Atlas-owned and Atlas-run. Other agents don't invoke it — Atlas runs it against their repos. Therefore, it only NEEDS to be in Atlas's skill directory.

However, if agents should be able to see the skill exists (for awareness), symlink to all constellation repos:

for repo in constellation-hades constellation-proteus constellation-mnemosyne \
            constellation-athena constellation-hermes constellation-hephaistos \
            constellation-apollo constellation-metis constellation-plutus pantheon; do
  TARGET="$HOME/Dev/_K4120S/$repo/.claude/skills/atlas-audit"
  [ -e "$TARGET" ] || ln -sf ~/Dev/_K4120S/arsenal/skills/atlas-audit "$TARGET"
done

• [ ] Step 4: Run first audit on Atlas repo

# Manual invocation of the skill protocol since /atlas-audit won't be callable yet
~/Dev/_K4120S/arsenal/skills/atlas-audit/scripts/measure.sh ~/Dev/_K4120S/constellation-atlas

Review the output. This is the fleet's first official baseline measurement.

• [ ] Step 5: Write baseline to fleet_context_metrics

Parse the measure.sh output and POST to the metrics table. This requires the service_role key — dispatch to Proteus if not available:

# Extract values from measure.sh JSON output and POST
METRICS_JSON=$(~/Dev/_K4120S/arsenal/skills/atlas-audit/scripts/measure.sh ~/Dev/_K4120S/constellation-atlas)

python3 -c "
import json, sys, subprocess, os

data = json.loads('''$(~/Dev/_K4120S/arsenal/skills/atlas-audit/scripts/measure.sh ~/Dev/_K4120S/constellation-atlas)''')

row = {
    'repo': 'constellation-atlas',
    'measured_by': 'atlas-audit-v1',
    'claude_md_chars': data.get('claude_md_chars', 0),
    'repo_rules_chars': data.get('repo_rules_chars', 0),
    'global_rules_chars': data.get('global_rules_chars', 0),
    'memory_index_chars': data.get('memory_index_chars', 0),
    'memory_files_chars': data.get('memory_files_chars', 0),
    'memory_file_count': data.get('memory_file_count', 0),
    'skills_count': data.get('skills_count', 0),
    'skills_frontmatter_chars': data.get('skills_frontmatter_chars', 0),
    'agents_count': data.get('agents_count', 0),
    'agents_chars': data.get('agents_chars', 0),
    'always_loaded_total': data.get('total_always_loaded_chars', 0),
    'est_tokens': data.get('total_always_loaded_chars', 0) // 4,
    'context_files_chars': data.get('context_files_chars', 0),
    'audit_type': 'full'
}
print(json.dumps([row]))
" | curl -sf "${PANTHEON_SUPABASE_URL}/rest/v1/fleet_context_metrics" \
  -H "apikey: ${PANTHEON_SUPABASE_SERVICE_ROLE_KEY}" \
  -H "Authorization: Bearer ${PANTHEON_SUPABASE_SERVICE_ROLE_KEY}" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d @-

• [ ] Step 6: Commit Atlas symlink

cd ~/Dev/_K4120S/constellation-atlas
git add .claude/skills/atlas-audit
git commit -m "feat: symlink atlas-audit skill from Arsenal"

Execution Notes

• Task 1 (SSOT Guide) can be done by Atlas alone — it's documentation.
• Task 2 (fleet_rules INSERT) requires service_role key. If Atlas doesn't have it, dispatch to Proteus.
• Task 3 (DDL) requires direct DB access or service_role key. Dispatch to Proteus.
• Task 4 (Skill) is Atlas work — writing the SKILL.md and measurement script.
• Task 5 (Distribution) is Atlas work — Arsenal symlinks.

Tasks 2 and 3 can run in parallel if dispatched to Proteus. Tasks 1 and 4 are sequential (guide must exist before skill references it).

Task 1 (SSOT Guide) ──→ Task 4 (Skill) ──→ Task 5 (Distribution)
                    \
Task 2 (fleet_rules) ──→ (parallel)
Task 3 (DDL)        ──→ (parallel, dispatch to Proteus)