Skill: somacosf/ghost-catalog (version 0.0.1)

--- name: ghost-catalog description: >- Scan, tag, validate, and catalog files using the Ghost Catalog semantic file header system (SOM-XXX-NNNN-vX.X.X). Use when: discovering untagged files, onboarding to a new codebase, maintaining catalog compliance, searching for files by category/tag/agent, or generating compliance reports. Operates on the local file system with a SQLite catalog database. user-invocable: true disable-model-invocation: false --- # Ghost Catalog Skill Manage semantic file headers and maintain the Ghost Catalog database for any workspace. ## Header Format (SOM File ID) Every cataloged file gets a semantic header in the first 20 lines: ``` # file_id: SOM-XXX-NNNN-vX.X.X # name: filename.ext # description: What this file does # project_id: PROJECT-NAME # category: script | doc | config | schema | component | test | data | style # tags: [tag1, tag2, tag3] # created: YYYY-MM-DD # modified: YYYY-MM-DD # version: X.X.X # agent_id: AGENT-DROID-001 ``` Comment style adapts to file type: - Python/Shell/YAML/TOML: `#` prefix - JavaScript/TypeScript/Go/Rust/C: `//` prefix inside `/* ... */` block - HTML/XML: `<!-- ... -->` block - Markdown: `<!-- ... -->` HTML comment block - CSS: `/* ... */` block - SQL: `--` prefix ### File ID Schema: `SOM-XXX-NNNN-vX.X.X` | Segment | Meaning | Examples | |---------|---------|----------| | `SOM` | Somacosf namespace (constant) | `SOM` | | `XXX` | 3-letter category code | `SCR` (script), `DOC` (doc), `CFG` (config), `SCH` (schema), `CMP` (component), `TST` (test), `DAT` (data), `STY` (style), `LIB` (library), `API` (api route), `UTL` (utility), `HKS` (hooks) | | `NNNN` | 4-digit sequential number | `0001`, `0042`, `0338` | | `vX.X.X` | Semantic version | `v1.0.0`, `v2.1.3` | ### Category Codes | Code | Category | File Types | |------|----------|------------| | `SCR` | Script | `.py`, `.sh`, `.ps1`, `.bat` | | `DOC` | Document | `.md`, `.txt`, `.rst` | | `CFG` | Config | `.json`, `.yaml`, `.yml`, `.toml`, `.env`, `.ini` | | `SCH` | Schema | `.prisma`, `.graphql`, `.sql` | | `CMP` | Component | `.tsx`, `.jsx`, `.vue`, `.svelte` | | `TST` | Test | `*.test.*`, `*.spec.*` | | `DAT` | Data | `.csv`, `.json` (data files), `.db` | | `STY` | Style | `.css`, `.scss`, `.less` | | `LIB` | Library | `.ts`, `.js` (lib modules) | | `API` | API Route | `route.ts`, `route.js` (Next.js API routes) | | `UTL` | Utility | Helper/utility modules | | `HKS` | Hooks | React hooks, git hooks | ## Catalog Database The catalog lives at `data/ghost-catalog.db` (SQLite). Schema: ```sql CREATE TABLE IF NOT EXISTS file_catalog ( file_id TEXT PRIMARY KEY, name TEXT NOT NULL, description TEXT, path TEXT NOT NULL, project_id TEXT, category TEXT, version TEXT, created TEXT, modified TEXT, agent_id TEXT, execution TEXT, checksum TEXT, last_synced TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE IF NOT EXISTS file_tags ( file_id TEXT, tag TEXT, PRIMARY KEY (file_id, tag), FOREIGN KEY (file_id) REFERENCES file_catalog(file_id) ON DELETE CASCADE ); CREATE TABLE IF NOT EXISTS agent_registry ( id TEXT PRIMARY KEY, name TEXT, model TEXT, first_seen TIMESTAMP DEFAULT CURRENT_TIMESTAMP, last_active TIMESTAMP ); CREATE INDEX IF NOT EXISTS idx_category ON file_catalog(category); CREATE INDEX IF NOT EXISTS idx_project ON file_catalog(project_id); CREATE INDEX IF NOT EXISTS idx_agent ON file_catalog(agent_id); CREATE INDEX IF NOT EXISTS idx_tags ON file_tags(tag); ``` ## Commands When the user invokes `/ghost-catalog`, determine which operation to perform based on their request. Default to `scan` if no specific command is given. ### 1. `scan` (default) Scan the workspace for all source files. For each file: 1. Check if it already has a SOM header (look for `file_id: SOM-` in first 20 lines) 2. If header exists: parse and validate it, update the catalog DB 3. If no header: report it as untagged Output a summary table: ``` Scanned: 150 files Tagged: 42 files (28%) Untagged: 108 files Errors: 0 ``` **Ignore system** (layered, merged at scan time): 1. `.ghost_ignore` (primary) -- Ghost Catalog's own ignore file, lives at project root. Follows `.gitignore` syntax. This is the canonical source of what to skip. 2. `.gitignore` (inherited) -- automatically merged; anything git ignores, Ghost Catalog ignores too. 3. Hardcoded fallbacks -- if neither file exists, use: `.git/`, `node_modules/`, `.next/`, `.vercel/`, `__pycache__/`, `.venv/`, `dist/`, `build/`, `.factory/` When scanning, parse `.ghost_ignore` and `.gitignore` into a combined exclusion set. Only scan files that survive both filters. The goal: **catalog project files only** -- no dependencies, no build artifacts, no binaries, no secrets, no lock files. ### 2. `tag <path|pattern>` Apply a Ghost Catalog header to one or more files: 1. Read the file content 2. Determine the category from file extension and location 3. Query the catalog DB for the next available sequence number in that category 4. Generate the header with appropriate comment syntax 5. Prepend the header to the file (preserve existing content) 6. Insert into the catalog DB When tagging multiple files, show a preview table first and ask for confirmation before applying. ### 3. `validate` Check all tagged files for header compliance: - Required fields present: `file_id`, `name`, `description`, `category`, `version`, `created`, `modified` - File ID format valid: `SOM-XXX-NNNN-vX.X.X` - Version in file_id matches version field - Filename in header matches actual filename - No duplicate file IDs Output a validation report with pass/warn/fail for each file. ### 4. `search <query>` Search the catalog by any field: - `search proxy` - fuzzy match on name/description - `search --category script` - filter by category - `search --tag opentelemetry` - filter by tag - `search --agent AGENT-CLAUDE-002` - filter by agent Display results as a formatted table with file_id, name, category, and path. ### 5. `info <file_id>` Show detailed metadata for a specific file from the catalog DB. ### 6. `stats` Show catalog statistics: - Total files, tagged vs untagged - Breakdown by category - Top tags - Agent activity - Last sync time ### 7. `report` Generate a full compliance report in markdown format, saved to `docs/ghost-catalog-report.md`. ## Implementation Notes - Use Python 3 with `sqlite3` stdlib for database operations - For scanning, use the Glob and Read tools rather than spawning processes - When generating headers, always check what comment style the file uses - Sequence numbers are global per category (not per project) - The catalog DB should be created at `data/ghost-catalog.db` if it doesn't exist - Always use `AGENT-DROID-001` as the agent_id when this skill applies headers - Version starts at `v1.0.0` for new files - `modified` date is always today's date when applying or updating headers - `created` date is preserved if already set, otherwise today's date ## Verification After any write operation (tag, validate --fix), re-read the modified files to confirm headers were applied correctly. Report any failures. ## Auto-Invocation Guidance This skill should be considered when: - The user asks about file organization, cataloging, or headers - A scan reveals many untagged files and the user wants to fix compliance - The user creates new files and wants them cataloged - The user asks "what files are in this project" or "show me the catalog"

path: ghost-catalog/category-codes.md
content: # Ghost Catalog Category Codes

Quick reference for the 3-letter category codes used in `SOM-XXX-NNNN-vX.X.X` file IDs.

| Code | Category | Extensions / Patterns | Comment Style |
|------|----------|----------------------|---------------|
| `SCR` | Script | `.py`, `.sh`, `.ps1`, `.bat`, `.rb` | `#` |
| `DOC` | Document | `.md`, `.txt`, `.rst`, `.adoc` | `<!-- -->` for md, `#` for rst |
| `CFG` | Config | `.json`, `.yaml`, `.yml`, `.toml`, `.env`, `.ini`, `.config.js`, `.config.ts` | varies |
| `SCH` | Schema | `.prisma`, `.graphql`, `.sql`, `.xsd` | `--` for sql, `#` for prisma |
| `CMP` | Component | `.tsx`, `.jsx`, `.vue`, `.svelte` | `//` or `{/* */}` |
| `TST` | Test | `*.test.*`, `*.spec.*`, `*_test.*` | matches source lang |
| `DAT` | Data | `.csv`, `.json` (data), `.db`, `.sqlite` | N/A (skip binary) |
| `STY` | Style | `.css`, `.scss`, `.less`, `.sass` | `/* */` |
| `LIB` | Library | `.ts`, `.js` (lib/ modules) | `//` |
| `API` | API Route | `route.ts`, `route.js` in `app/api/` | `//` |
| `UTL` | Utility | Helper modules, shared utils | `//` |
| `HKS` | Hooks | React hooks (`use*.ts`), git hooks | `//` or `#` |
| `MDW` | Middleware | `middleware.ts`, `middleware.js` | `//` |
| `LAY` | Layout | `layout.tsx`, `layout.jsx` | `//` |
| `PAG` | Page | `page.tsx`, `page.jsx` | `//` |

## Determining Category

Priority rules (first match wins):

1. **Filename patterns**: `route.ts` -> `API`, `page.tsx` -> `PAG`, `layout.tsx` -> `LAY`, `middleware.ts` -> `MDW`
2. **Test patterns**: `*.test.*` or `*.spec.*` -> `TST`
3. **Hook patterns**: `use*.ts` in hooks/ -> `HKS`
4. **Directory context**: `lib/` -> `LIB`, `app/api/` -> `API`, `components/` -> `CMP`, `scripts/` -> `SCR`
5. **Extension fallback**: `.py` -> `SCR`, `.md` -> `DOC`, `.css` -> `STY`, etc.


path: ghost-catalog/header-templates.md
content: # Ghost Catalog Header Templates

## Python / Shell / YAML / Ruby

```python
# ==============================================================================
# file_id: SOM-XXX-NNNN-vX.X.X
# name: filename.py
# description: Brief description of what this file does
# project_id: PROJECT-NAME
# category: script
# tags: [tag1, tag2, tag3]
# created: YYYY-MM-DD
# modified: YYYY-MM-DD
# version: X.X.X
# agent_id: AGENT-DROID-001
# ==============================================================================
```

## JavaScript / TypeScript

```typescript
// =============================================================================
// file_id: SOM-XXX-NNNN-vX.X.X
// name: filename.ts
// description: Brief description of what this file does
// project_id: PROJECT-NAME
// category: library
// tags: [tag1, tag2, tag3]
// created: YYYY-MM-DD
// modified: YYYY-MM-DD
// version: X.X.X
// agent_id: AGENT-DROID-001
// =============================================================================
```

## CSS / SCSS

```css
/* =============================================================================
 * file_id: SOM-XXX-NNNN-vX.X.X
 * name: filename.css
 * description: Brief description of what this file does
 * project_id: PROJECT-NAME
 * category: style
 * tags: [tag1, tag2, tag3]
 * created: YYYY-MM-DD
 * modified: YYYY-MM-DD
 * version: X.X.X
 * agent_id: AGENT-DROID-001
 * ============================================================================= */
```

## Markdown

```markdown
<!--
file_id: SOM-XXX-NNNN-vX.X.X
name: filename.md
description: Brief description of what this file does
project_id: PROJECT-NAME
category: doc
tags: [tag1, tag2, tag3]
created: YYYY-MM-DD
modified: YYYY-MM-DD
version: X.X.X
agent_id: AGENT-DROID-001
-->
```

## SQL

```sql
-- =============================================================================
-- file_id: SOM-XXX-NNNN-vX.X.X
-- name: filename.sql
-- description: Brief description of what this file does
-- project_id: PROJECT-NAME
-- category: schema
-- tags: [tag1, tag2, tag3]
-- created: YYYY-MM-DD
-- modified: YYYY-MM-DD
-- version: X.X.X
-- agent_id: AGENT-DROID-001
-- =============================================================================
```

## HTML / XML

```html
<!--
  file_id: SOM-XXX-NNNN-vX.X.X
  name: filename.html
  description: Brief description of what this file does
  project_id: PROJECT-NAME
  category: component
  tags: [tag1, tag2, tag3]
  created: YYYY-MM-DD
  modified: YYYY-MM-DD
  version: X.X.X
  agent_id: AGENT-DROID-001
-->
```

## JSON (as top-level `_catalog` key)

JSON does not support comments. For JSON files that support arbitrary keys,
add a `_catalog` object at the top level:

```json
{
  "_catalog": {
    "file_id": "SOM-CFG-NNNN-vX.X.X",
    "name": "config.json",
    "description": "Application configuration",
    "project_id": "PROJECT-NAME",
    "category": "config",
    "tags": ["config", "settings"],
    "created": "YYYY-MM-DD",
    "modified": "YYYY-MM-DD",
    "version": "X.X.X",
    "agent_id": "AGENT-DROID-001"
  }
}
```

For JSON files where adding keys would break the schema (e.g., `package.json`, `tsconfig.json`),
skip the header and register the file in the catalog DB only (no inline header).


path: ghost-catalog/schema.sql
content: -- Ghost Catalog Database Schema
-- Version: 1.0.0
-- Database: data/ghost-catalog.db

CREATE TABLE IF NOT EXISTS file_catalog (
    file_id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    description TEXT,
    path TEXT NOT NULL,
    project_id TEXT,
    category TEXT,
    version TEXT,
    created TEXT,
    modified TEXT,
    agent_id TEXT,
    execution TEXT,
    checksum TEXT,
    last_synced TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS file_tags (
    file_id TEXT,
    tag TEXT,
    PRIMARY KEY (file_id, tag),
    FOREIGN KEY (file_id) REFERENCES file_catalog(file_id) ON DELETE CASCADE
);

CREATE TABLE IF NOT EXISTS agent_registry (
    id TEXT PRIMARY KEY,
    name TEXT,
    model TEXT,
    first_seen TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_active TIMESTAMP
);

CREATE TABLE IF NOT EXISTS file_dependencies (
    file_id TEXT,
    depends_on_file_id TEXT,
    dependency_type TEXT DEFAULT 'import',
    PRIMARY KEY (file_id, depends_on_file_id),
    FOREIGN KEY (file_id) REFERENCES file_catalog(file_id) ON DELETE CASCADE,
    FOREIGN KEY (depends_on_file_id) REFERENCES file_catalog(file_id) ON DELETE CASCADE
);

CREATE INDEX IF NOT EXISTS idx_category ON file_catalog(category);
CREATE INDEX IF NOT EXISTS idx_project ON file_catalog(project_id);
CREATE INDEX IF NOT EXISTS idx_agent ON file_catalog(agent_id);
CREATE INDEX IF NOT EXISTS idx_modified ON file_catalog(modified);
CREATE INDEX IF NOT EXISTS idx_tags ON file_tags(tag);


path: ghost-catalog/somaco-unification.md
content: # .somaco -> Factory Droid Unification Map

How the existing `.somaco` directive system maps to Factory skills and droids.

## Current .somaco Commands -> Factory Skills

| .somaco Command | SOM ID | Factory Skill | Status |
|----------------|--------|---------------|--------|
| `/preflight-check` | SOM-CMD-0004 | **ghost-catalog** (scan + validate) | REPLACED - Ghost Catalog's scan/validate covers header compliance; agent registration handled by skill auto-invocation |
| `/stats` | SOM-CMD-0006 | **ghost-catalog** (stats command) | REPLACED - catalog stats + git status + project structure in one skill |
| `/project-status` | SOM-CMD-0001 | **ghost-catalog** (stats + report) | REPLACED - catalog DB provides richer project health than file-by-file inspection |
| `/db-inspect` | SOM-CMD-0003 | Keep as standalone skill | MIGRATE - useful for any SQLite DB, not just catalog |
| `/new-project` | SOM-CMD-0002 | Keep as standalone skill | MIGRATE - scaffolding with auto-catalog registration |
| `/think` | SOM-CMD-0005 | N/A | DROP - Factory Droid has its own thinking mode |

## Current .somaco Rule Modules -> Factory Configuration

| Module | SOM ID | Factory Equivalent | Action |
|--------|--------|-------------------|--------|
| `file-headers.md` | SOM-DOC-0010 | **ghost-catalog** skill | ABSORBED - the skill IS the header system |
| `coding-standards.md` | SOM-DOC-0011 | `CLAUDE.md` / `AGENTS.md` | KEEP - belongs in project-level agent instructions |
| `agent-context.md` | SOM-DOC-0012 | Factory Droid memory system | SUPERSEDED - Factory handles session continuity via summaries |
| `failure-prevention.md` | SOM-DOC-0013 | Custom droid config | MIGRATE - encode as droid behavioral constraints |

## Current .somaco Stack Rules -> Factory Droids

| Stack | Projects | Factory Approach |
|-------|----------|-----------------|
| `nextjs.md` | aqua_attack, astro_chart, austinsays | Project-level `CLAUDE.md` already handles this |
| `flask.md` | gyst_02s | Project-level `CLAUDE.md` |
| `godot.md` | hxodot | Project-level `CLAUDE.md` |
| `python-cli.md` | Oligarchology, dossier | Project-level `CLAUDE.md` |

## Recommended Factory Skill Portfolio

### Tier 1: Built (This Session)
- **ghost-catalog** — Scan, tag, validate, search, stats, report

### Tier 2: Migrate from .somaco
- **db-inspect** — SQLite inspection (port from SOM-CMD-0003)
- **new-project** — Scaffold new project with catalog registration (port from SOM-CMD-0002)

### Tier 3: New Skills from Protocol
- **gyst-uuid** — Generate/parse/validate GYST UUID v8 identifiers
- **data-weave** — Scan workspace, map projects, discover cross-domain relationships
- **molting** — 5-stage structured analysis workflow


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)