A comprehensive framework for maintaining clean, organized, and recoverable AI-assisted development projects. This system provides standardized file headers, agent tracking, slash commands, and failure prevention protocols.
flowchart TB
subgraph Workspace["Workspace Root"]
CLAUDE["CLAUDE.md<br/>(Rules & Standards)"]
subgraph Commands[".claude/commands/"]
CMD1["/project-status"]
CMD2["/stats"]
CMD3["/db-inspect"]
CMD4["/new-project"]
CMD5["/preflight-check"]
CMD6["/think"]
end
subgraph Projects["outputs/"]
subgraph Project1["project-name/"]
README["README.md"]
DIARY["development_diary.md"]
UNDERSTAND["understandings.md"]
VENV[".venv/"]
TESTS["tests/"]
LOGS["logs/"]
subgraph DB["database/context/"]
AGENT_DB["agent_context.db"]
TASKS_DB["project_tasks.db"]
end
end
end
end
CLAUDE --> Commands
CLAUDE --> Projects
Commands --> Project1
flowchart LR
subgraph Problems["Common AI Development Issues"]
P1["Lost Context<br/>Between Sessions"]
P2["No File<br/>Provenance"]
P3["No Crash<br/>Recovery"]
P4["Inconsistent<br/>Structure"]
P5["Untracked<br/>AI Changes"]
end
P1 --> CHAOS["Project Chaos"]
P2 --> CHAOS
P3 --> CHAOS
P4 --> CHAOS
P5 --> CHAOS
flowchart LR
subgraph Solutions["Framework Components"]
S1["File Headers<br/>(Ghost Catalog)"]
S2["Agent IDs<br/>(Tracking)"]
S3["SQLite DBs<br/>(Recovery)"]
S4["Slash Commands<br/>(Automation)"]
S5["Failure Protocols<br/>(Prevention)"]
end
S1 --> ORDER["Organized<br/>Projects"]
S2 --> ORDER
S3 --> ORDER
S4 --> ORDER
S5 --> ORDER
The "Ghost Catalog" is a metadata system embedded in every file header, creating a searchable index without a separate database.
classDiagram
class FileHeader {
+string file_id
+string name
+string description
+string project_id
+string category
+array tags
+date created
+date modified
+string version
+Agent agent
+Execution execution
}
class Agent {
+string id
+string name
+string model
}
class Execution {
+string type
+string invocation
}
FileHeader --> Agent
FileHeader --> Execution
SOM-<CATEGORY>-<SEQUENCE>-v<VERSION>
│ │ │ │
│ │ │ └── Semantic version (1.0.0)
│ │ └── Sequential number (0001-9999)
│ └── Category code (CMD, SCR, DOC, etc.)
└── Namespace prefix (Somacosf)
flowchart LR
subgraph FileID["File ID: SOM-CMD-0005-v1.2.0"]
NS["SOM"]
CAT["CMD"]
SEQ["0005"]
VER["v1.2.0"]
end
NS --- |"Namespace"| CAT
CAT --- |"Category"| SEQ
SEQ --- |"Sequence"| VER
graph TB
subgraph Categories["File Categories"]
CMD["CMD<br/>Slash Commands"]
SCR["SCR<br/>Scripts"]
DOC["DOC<br/>Documentation"]
CFG["CFG<br/>Configuration"]
TST["TST<br/>Tests"]
DTA["DTA<br/>Data/Schemas"]
LOG["LOG<br/>Logs/Diaries"]
REG["REG<br/>Registry Files"]
TMP["TMP<br/>Templates"]
end
Markdown/Documentation:
<!--
===============================================================================
file_id: SOM-DOC-0001-v1.0.0
name: README.md
description: Project overview and setup instructions
project_id: MY-PROJECT
category: documentation
tags: [readme, setup, overview]
created: 2025-01-19
modified: 2025-01-19
version: 1.0.0
agent:
id: AGENT-PRIME-001
name: agent_prime
model: claude-sonnet-4-5-20250929
execution:
type: documentation
invocation: Read for project context
===============================================================================
-->Python:
# ==============================================================================
# file_id: SOM-SCR-0042-v2.1.0
# name: data_processor.py
# description: ETL pipeline for customer data
# project_id: DATA-PIPELINE
# category: script
# tags: [etl, data, processing]
# created: 2025-01-15
# modified: 2025-01-19
# version: 2.1.0
# agent_id: AGENT-WORKER-003
# execution: python data_processor.py --input data.csv
# ==============================================================================PowerShell:
# ==============================================================================
# file_id: SOM-SCR-0010-v1.0.0
# name: setup.ps1
# description: Environment setup script
# project_id: DEVOPS
# category: script
# tags: [setup, powershell, automation]
# created: 2025-01-19
# modified: 2025-01-19
# version: 1.0.0
# agent_id: AGENT-PRIME-001
# execution: .\setup.ps1 -Environment dev
# ==============================================================================flowchart TB
subgraph Benefits["Why Ghost Catalog?"]
B1["Instant Search<br/>grep -r 'file_id:'"]
B2["AI Attribution<br/>Track agent work"]
B3["Version History<br/>In-file versioning"]
B4["Tag Discovery<br/>Find related files"]
B5["Audit Trail<br/>Created/modified dates"]
end
B1 --> USE["Practical<br/>Daily Use"]
B2 --> USE
B3 --> USE
B4 --> USE
B5 --> USE
flowchart TB
subgraph AgentTypes["Agent Designations"]
PRIME["AGENT-PRIME-NNN<br/>Primary orchestrators"]
WORKER["AGENT-WORKER-NNN<br/>Task specialists"]
REVIEW["AGENT-REVIEW-NNN<br/>Code reviewers"]
TEST["AGENT-TEST-NNN<br/>Test writers"]
end
subgraph Sessions["Session Tracking"]
REG["Register Agent"]
WINDOW["Create Activity Window"]
LOG["Log Actions"]
SNAP["Context Snapshots"]
END["End Session"]
end
PRIME --> REG
WORKER --> REG
REVIEW --> REG
TEST --> REG
REG --> WINDOW --> LOG --> SNAP --> END
AGENT-<DESIGNATION>-<SEQUENCE>
│ │ │
│ │ └── Sequential number (001-999)
│ └── Role designation (PRIME, WORKER, REVIEW, etc.)
└── Fixed prefix
erDiagram
agents ||--o{ activity_windows : "has"
activity_windows ||--o{ action_log : "contains"
activity_windows ||--o{ context_snapshots : "has"
agents {
string id PK "AGENT-PRIME-001"
string name "agent_prime"
string model "claude-opus-4-5"
string role "Primary orchestrator"
datetime last_active_at
string status "active|inactive"
}
activity_windows {
int id PK
string agent_id FK
datetime started_at
datetime ended_at
string session_summary
string status "active|completed|interrupted"
}
action_log {
int id PK
int window_id FK
string agent_id FK
string action_type "read_file|edit_file|bash_command"
string action_summary
string target
string result "success|failure|partial"
json context
datetime timestamp
}
context_snapshots {
int id PK
int window_id FK
string agent_id FK
string current_task
json pending_items
json files_modified
json decisions_made
json blockers
json next_steps
datetime timestamp
}
erDiagram
tasks ||--o{ handoffs : "may have"
tasks {
int id PK
string project_id
string title
string description
string priority "critical|high|medium|low"
string status "pending|in_progress|completed"
string created_by
string checked_out_by
datetime checked_out_at
string completed_by
datetime completed_at
boolean is_deleted
datetime deleted_at
}
handoffs {
int id PK
string from_agent
string to_agent
string message_type "task_delegation|status_update|error_report"
string message
datetime timestamp
datetime acknowledged_at
}
sequenceDiagram
participant Agent as New Agent Session
participant DB as agent_context.db
participant User as User/System
Agent->>DB: Check for interrupted sessions
DB-->>Agent: Found: window_id=42, status='active'
Agent->>DB: Get last context snapshot
DB-->>Agent: Snapshot: task="Implementing auth", files=["auth.py"]
Agent->>DB: Get recent actions
DB-->>Agent: Last 20 actions with targets and results
Agent->>User: "Found interrupted session. Resume?"
User-->>Agent: "Yes, continue"
Agent->>DB: Update window status, continue work
Agent->>DB: Log new actions
Based on research: "How Do LLMs Fail In Agentic Scenarios?" (Kamiwaza AI, 2025)
flowchart TB
subgraph Failures["Four Failure Archetypes"]
F1["PREMATURE ACTION<br/>Acting without verifying"]
F2["OVER-HELPFULNESS<br/>Inventing missing data"]
F3["CONTEXT POLLUTION<br/>Similar name confusion"]
F4["FRAGILE EXECUTION<br/>Loops & coherence loss"]
end
subgraph Preventions["Prevention Protocols"]
P1["GROUND BEFORE ACTION<br/>Read before edit<br/>Schema before query"]
P2["NEVER SUBSTITUTE<br/>Return null/0<br/>ASK if uncertain"]
P3["EXACT MATCHING<br/>Flag similar names<br/>Verify targets"]
P4["CHECKPOINT OFTEN<br/>Every 3 actions<br/>Stop after 3 failures"]
end
F1 --> P1
F2 --> P2
F3 --> P3
F4 --> P4
flowchart LR
subgraph Ground["Before Any Action"]
A1["DB Query?"] --> V1["Check Schema First"]
A2["File Edit?"] --> V2["Read File First"]
A3["API Call?"] --> V3["Check Docs First"]
A4["Using Name?"] --> V4["Verify Exact Match"]
end
V1 --> PROCEED["Proceed with Action"]
V2 --> PROCEED
V3 --> PROCEED
V4 --> PROCEED
flowchart TB
ERROR["Error Occurred"] --> DIAGNOSE["1. Diagnose Root Cause"]
DIAGNOSE --> VERIFY["2. Re-verify/Ground"]
VERIFY --> CORRECT["3. Correct Approach"]
CORRECT --> VALIDATE["4. Validate Result"]
VALIDATE --> |"Success"| CONTINUE["Continue Work"]
VALIDATE --> |"Fail (attempt < 3)"| DIAGNOSE
VALIDATE --> |"Fail (attempt >= 3)"| STOP["STOP & Reassess"]
flowchart TB
subgraph Commands["Available Commands"]
C1["/project-status<br/>Quick health check"]
C2["/stats<br/>Detailed report"]
C3["/db-inspect<br/>Database queries"]
C4["/new-project<br/>Scaffold project"]
C5["/preflight-check<br/>Agent alignment"]
C6["/think<br/>Toggle thinking"]
end
USER["User types /command"] --> CLAUDE["Claude reads<br/>.claude/commands/command.md"]
CLAUDE --> EXECUTE["Executes instructions"]
EXECUTE --> OUTPUT["Formatted output"]
flowchart TB
subgraph Workspace["somacosf/"]
CLAUDE_MD["CLAUDE.md"]
subgraph DotClaude[".claude/"]
subgraph Cmds["commands/"]
C1["project-status.md"]
C2["stats.md"]
C3["db-inspect.md"]
C4["new-project.md"]
C5["preflight-check.md"]
C6["think.md"]
end
end
subgraph Outputs["outputs/"]
subgraph Proj["project-name/"]
README["README.md"]
DIARY["development_diary.md"]
UNDER["understandings.md"]
subgraph DBDir["database/context/"]
ADB["agent_context.db"]
TDB["project_tasks.db"]
end
VENV[".venv/"]
TESTS["tests/"]
LOGS["logs/"]
end
end
end
sequenceDiagram
participant User
participant Agent
participant CtxDB as agent_context.db
participant TaskDB as project_tasks.db
Note over Agent: Session Start
Agent->>CtxDB: Register/update agent
Agent->>CtxDB: Create activity_window
Agent->>CtxDB: Check interrupted sessions
loop Work Loop
User->>Agent: Request task
Agent->>CtxDB: Log action (read_file)
Agent->>Agent: Process
Agent->>CtxDB: Log action (edit_file)
alt Every 10-15 actions
Agent->>CtxDB: Create context_snapshot
end
end
Note over Agent: Session End
Agent->>CtxDB: Update window (completed)
Agent->>User: Session summary
- Copy
CLAUDE.mdto your workspace root - Create
.claude/commands/directory - Copy slash commands to the commands directory
- Initialize databases (optional):
python database/context/init_context_db.py
- Run preflight at session start:
/preflight-check
| File | Purpose |
|---|---|
README.md |
This guide with diagrams |
CLAUDE.md |
Main rules and standards |
commands/project-status.md |
Quick project health check |
commands/stats.md |
Detailed project report |
commands/db-inspect.md |
Database inspection |
commands/new-project.md |
Project scaffolding |
commands/preflight-check.md |
Agent alignment |
commands/think.md |
Toggle thinking mode |
MIT - Use freely, attribution appreciated.
Developed for the Somacosf workspace with Claude Code assistance.
Failure prevention protocols based on: "How Do LLMs Fail In Agentic Scenarios?" (Kamiwaza AI, 2025)