Somacosf Workspace: AI Agent Rules & Directives

🔴 CRITICAL: Backup Before Edit

MANDATORY: ALWAYS create .bk backup before editing ANY file

# BEFORE editing any file:
Copy-Item example.py example.py.bk
Copy-Item config.json config.json.bk
Copy-Item script.ps1 script.ps1.bk

NO EXCEPTIONS. This is non-negotiable.

File Header Catalog System

Every file MUST include a versioned header with catalog metadata.

Markdown/Documentation Files

<!--
===============================================================================
file_id: SOM-XXX-NNNN-vX.X.X
name: filename.md
description: What this file does
project_id: PROJECT-TYPE
category: category_name
tags: [tag1, tag2, tag3]
created: YYYY-MM-DD
modified: YYYY-MM-DD
version: X.X.X
agent:
  id: AGENT-XXX-NNN
  name: agent_name
  model: model_id
execution:
  type: type_of_file
  invocation: how to use/run this file
===============================================================================
-->

Python Files

# ==============================================================================
# file_id: SOM-SCR-NNNN-vX.X.X
# name: script.py
# description: What this script does
# project_id: PROJECT-TYPE
# category: script
# tags: [tag1, tag2]
# created: YYYY-MM-DD
# modified: YYYY-MM-DD
# version: X.X.X
# agent_id: AGENT-XXX-NNN
# execution: python script.py [args]
# ==============================================================================

PowerShell Files

# ==============================================================================
# file_id: SOM-SCR-NNNN-vX.X.X
# name: script.ps1
# description: What this script does
# project_id: PROJECT-TYPE
# category: script
# tags: [tag1, tag2]
# created: YYYY-MM-DD
# modified: YYYY-MM-DD
# version: X.X.X
# agent_id: AGENT-XXX-NNN
# execution: .\script.ps1 [-Param value]
# ==============================================================================

File ID Format

SOM-<CATEGORY>-<SEQUENCE>-v<VERSION>

Code	Category
CMD	Slash commands
SCR	Scripts
DOC	Documentation
CFG	Configuration
REG	Registry files
TST	Tests
TMP	Templates
DTA	Data/schemas
LOG	Logs/diaries

Mandatory Coding Standards

1. Virtual Environments

ALWAYS use uv for Python package management. NEVER use bare pip.

# Create venv
uv venv .venv

# Activate
.venv\Scripts\activate.ps1

# Install packages
uv pip install package-name

2. Command Chaining (Windows)

Use semicolons (;) NEVER use (&&)

# CORRECT:
mkdir logs; cd logs; New-Item log.txt

# WRONG - DO NOT USE:
mkdir logs && cd logs && New-Item log.txt

3. Check Before Doing

Verify state before making changes:

Check if file exists before creating
Check if directory exists before writing
Read file content before editing
Check database schema before queries (PRAGMA table_info())
Check venv is activated before installing

4. Logging

All scripts must include proper logging:

import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('logs/script_name.log'),
        logging.StreamHandler()
    ]
)
logger = logging.getLogger(__name__)

5. Test-Driven Development

Create tests/ directory in each project
Write tests BEFORE implementation
Use pytest for Python projects
Name test files test_<module>.py
Run tests before committing

6. Development Diary

Maintain development_diary.md in each project root:

## YYYY-MM-DD

### Session: [Brief description]
- **Agent**: AGENT-XXX-NNN
- **Tasks completed**: [list]
- **Decisions made**: [list]
- **Issues encountered**: [list]
- **Next steps**: [list]

Agent Context Logging Protocol

CRITICAL: All agents MUST log activity to SQLite databases for crash recovery.

Context Databases

Located in: <project>/database/context/

Database	Purpose
`agent_context.db`	Agent registry, activity windows, action log, context snapshots
`project_tasks.db`	Task management (CRUD, soft-delete only, full history)

Session Start (MANDATORY)

-- 1. Register agent
INSERT OR REPLACE INTO agents (id, name, model, role, last_active_at, status)
VALUES ('AGENT-XXX-NNN', 'agent_name', 'model_id', 'role', datetime('now'), 'active');

-- 2. Create activity window
INSERT INTO activity_windows (agent_id, session_summary, status)
VALUES ('AGENT-XXX-NNN', 'Brief description of planned work', 'active');
-- Store returned window_id

Action Logging (During Session)

INSERT INTO action_log (window_id, agent_id, action_type, action_summary, target, result, context)
VALUES (
    <window_id>,
    'AGENT-XXX-NNN',
    'read_file',  -- read_file, edit_file, bash_command, search, decision, thought, error
    'Read CLAUDE.md to understand workspace standards',
    'D:\somacosf\CLAUDE.md',
    'success',    -- success, failure, partial
    '{"reasoning": "Needed to understand file header format"}'
);

Context Snapshots

Create every 10-15 actions or at major milestones:

INSERT INTO context_snapshots (window_id, agent_id, current_task, pending_items, files_modified, decisions_made, blockers, next_steps)
VALUES (
    <window_id>,
    'AGENT-XXX-NNN',
    'Current task description',
    '["item1", "item2"]',
    '["file1.py", "file2.ts"]',
    '["Used X instead of Y because..."]',
    '["Waiting on user input for..."]',
    '["Next: implement Z", "Then: test"]'
);

Session End

UPDATE activity_windows
SET ended_at = datetime('now'),
    status = 'completed',
    session_summary = 'Final summary of work done'
WHERE id = <window_id>;

Task Management

NEVER hard delete - soft-delete only:

-- Check out task
UPDATE tasks SET
    checked_out_at = datetime('now'),
    checked_out_by = 'AGENT-XXX-NNN',
    status = 'in_progress'
WHERE id = <task_id> AND checked_out_by IS NULL;

-- Complete task
UPDATE tasks SET
    status = 'completed',
    completed_at = datetime('now'),
    completed_by = 'AGENT-XXX-NNN',
    checked_out_by = NULL
WHERE id = <task_id>;

-- Soft-delete task (NEVER DELETE)
UPDATE tasks SET
    is_deleted = 1,
    deleted_at = datetime('now'),
    deleted_by = 'AGENT-XXX-NNN'
WHERE id = <task_id>;

Failure Prevention Framework

Based on research: "How Do LLMs Fail In Agentic Scenarios?" (Kamiwaza AI, 2025)

"Recovery capability, not initial correctness, best predicts overall success."

The Four Failure Archetypes

Archetype	Description	Prevention
Premature Action	Acting on assumptions instead of verifying	ALWAYS inspect before acting
Over-Helpfulness	Substituting/inventing when data is missing	Return 0/null, ASK user
Context Pollution	Errors from distractor information	Exact name matching, curate context
Fragile Execution	Generation loops, coherence loss under load	Checkpoint every 3 actions

Grounding Protocol (MANDATORY)

BEFORE any critical action, verify:

Action Category	REQUIRED Verification
`db_query`	`PRAGMA table_info()` or `sqlite_get_schema`
`file_edit`	Read file first, understand structure
`api_call`	Check documentation or test endpoint
`schema_change`	Backup AND read existing schema

NEVER:

Guess table/column names
Assume file structure
Execute queries without schema verification

Over-Helpfulness Prevention

WRONG: "Company X not found, using Company XYZ instead"
RIGHT: "Company X not found. 0 results returned."

WRONG: "Status 'inactive' not found, using STATUS != 'active'"
RIGHT: "Status value 'inactive' does not exist. Available values: active, pending, closed"

WRONG: Create a file that doesn't exist when asked to edit it
RIGHT: "File not found at path. Should I create it?"

Rule: If uncertain, ASK - do not substitute or invent.

Context Pollution Prevention

Prevention Checklist:

Verify entity names match EXACTLY (similar names are distractors)
At each step, re-verify operating on correct target
When reading files, note similar-named entities that could confuse
Curate context aggressively - more is NOT better

Fragile Execution Prevention

Mandatory Checkpoints:

Every 3 actions for complex tasks (>5 steps)
Every 20 actions regardless of task complexity
After any error recovery attempt

Triggers to Watch:

Data Inlining: NEVER embed large CSV/text in code - use file I/O
Extended Error Recovery: >3 consecutive failures = STOP and reassess
Generation Loops: Repeated similar output = coherence degrading

Recovery Protocol:

Diagnose Root Cause - Don't just retry blindly
Inspect/Verify - Go back to grounding (schema, file content, etc.)
Correct Approach - Fix the actual issue
Validate Result - Confirm the fix worked

NEVER: Repeat the same failed action more than twice without changing approach.

Claude Code Slash Commands

Located in: .claude/commands/

1. `/project-status` (SOM-CMD-0001)

Analyze current project status and health

Lists key project files with modified dates
Checks environment (.venv status)
Shows database tables and row counts
Displays recent logs
Reports test status

2. `/new-project <name>` (SOM-CMD-0002)

Create new project with standard structure

Creates directory in outputs/<project-name>/
Initializes: README.md, development_diary.md, .venv, logs/, tests/
Generates standard file headers
Updates agent_registry.md

3. `/db-inspect [query]` (SOM-CMD-0003)

Inspect SQLite databases in current project

No args: Show database overview (tables, schemas, row counts)
Query provided: Execute SQL query
Table name: Show schema and sample rows
Safety: SELECT-only by default, warns before modifications

4. `/preflight-check` (SOM-CMD-0004)

Agent alignment verification - 12-point compliance checklist

Agent registration verification
File ID system understanding
Standard headers compliance
Backup before edit (.bk)
Virtual environments (uv)
Command chaining (semicolons)
Check before doing
Logging requirements
Test-driven development
Development diary updates
Catalog registration
Session logging

Reports: GREEN/YELLOW/RED status for each check.

5. `/think` (SOM-CMD-0005)

Toggle extended thinking mode

Modifies ~/.claude/settings.json
Toggles alwaysThinkingEnabled flag
Provides visual feedback on state change

6. `/stats` (SOM-CMD-0006)

Detailed project statistics and report

Reads and summarizes understandings.md
Shows last 3 development diary entries
Reports project structure (file counts, directories)
Displays git status and recent commits
Shows agent activity from agent_context.db

Cursor AI Agents

Located in: .cursor/agents/

1. Code Reviewer Agent

Role: Review code changes for quality, security, and standards

Checklist:

Standards compliance (headers, .bk backups, uv usage, semicolons, venv)
Code quality (no secrets, error handling, single responsibility, no dead code)
Security (OWASP Top 10: SQL injection, command injection, XSS, input validation)
Documentation (complex logic comments, API docs, README updates)

Output: Critical / Warning / Suggestion

2. Test Writer Agent

Role: Write comprehensive tests following TDD principles

Standards:

Framework: pytest
Location: tests/ directory
Naming: test_<module>.py, test_<behavior>()
Structure: Arrange-Act-Assert pattern

Coverage:

Unit tests (isolated, mocked, <100ms)
Integration tests (component interactions, real DB)
Edge cases (empty inputs, null, boundaries, invalid, large inputs)

3. Database Expert Agent

Role: Database schema design, queries, migrations, optimization

CRITICAL: Grounding Protocol

-- ALWAYS verify schema before queries:
PRAGMA table_info(table_name);
SELECT name FROM sqlite_master WHERE type='table';

Standards:

Parameterized queries (prevent SQL injection)
Soft-delete only (set is_deleted=1, NEVER DELETE)
Transactions for multi-statement operations
Context DBs: agent_context.db, project_tasks.db

4. Refactor Agent

Role: Improve code structure without changing behavior

Before Refactoring:

Ensure tests exist
Create backup (.bk)
Understand the code thoroughly
Small steps (one refactoring at a time)

Common Refactorings:

Extract function (code blocks with single purpose, duplicates)
Rename (unclear names)
Simplify conditionals (guard clauses, early returns)
Remove duplication (DRY, but don't over-abstract)

What NOT to Do:

Add features during refactoring
Fix bugs during refactoring
Change public interfaces without plan
Refactor without tests

5. AEGIS Project Agent

Role: Multi-agent coordination for AEGIS system

Responsibilities:

Session management (register agents, create activity windows)
Context logging (action log, snapshots every 10-15 actions)
Task coordination (check out, complete, soft-delete only)
Failure prevention (4 archetypes)

Databases:

agent_context.db - Agent sessions and activity
project_tasks.db - Task management

Grounding: Always PRAGMA table_info() before queries

Configuration Files Reference

Claude Code Settings

C:\Users\Phoenix\.claude\settings.local.json

Permission policies for whitelisted Bash commands
Allowed: gh CLI, curl, npm, pip3, uv, aws, psql, mysql, redis-cli, git config

D:\somacosf\.claude\settings.local.json

Workspace-specific permissions
Whitelisted: mkdir, dir, Everything CLI search

Cursor AI Settings

D:\somacosf\.cursor\mcp.json

MCP server configuration
Sub-agents MCP server with agent directory: D:/somacosf/.cursor/agents

Environment Standards

Component	Standard
Platform	Windows 10/11
PowerShell	7.0+
Python	3.12+
Package Manager	uv (NEVER pip)
Command Chaining	; (NEVER &&)
File Search	Everything CLI: `C:\Program Files\Everything\es.exe`

Quick Reference: Critical Mandates

Before...	ALWAYS...
Editing ANY file	Create `.bk` backup
SQL query	`PRAGMA table_info()` or schema read
File edit	Read file content first
API call	Check docs or test endpoint
Complex task	Create checkpoint every 3 actions
Python install	Use `uv pip install`, NEVER bare `pip`
Command chain	Use `;`, NEVER use `&&`

When...	DO...
Entity not found	Return 0/null, report missing
Ambiguous request	ASK for clarification
>3 consecutive errors	STOP, reassess approach
Similar names in context	Flag as high distractor risk
Creating ANY file	Add catalog header with file_id
Session start	Register agent, create activity window
Session end	Update activity window status

Path Patterns to Exclude

When searching or processing, ALWAYS exclude:

**/node_modules/**
**/.git/**
**/.venv/**, **/venv/**, **/cleanup_env/lib/**
**/__pycache__/**
**/*.bk (backup files)

Remember the 12 Mandates

Backup before edit (.bk)
Headers on all files (catalog schema)
Work in venv (uv, not pip)
Use uv, not pip
Log everything (logging module)
Test first (TDD)
Update diary (development_diary.md)
Check then do (verify state first)
LOG CONTEXT TO DATABASE (agent_context.db)
Register agent session on start
GROUND BEFORE ACTION (verify schema/file/API)
NEVER SUBSTITUTE (if missing, return 0/null or ASK)

Generated: 2025-12-27 Source: Somacosf Workspace (D:\somacosf) Primary Reference: D:\somacosf\CLAUDE.md (SOM-DOC-0001-v1.3.0)

SoMaCoSF/somacosf-ai-rules-directives.md