Soulfield Agent Instructions (Claude Code / Sentinel)

Purpose: Developer instructions for Claude Code CLI when working with Soulfield OS codebase. Last Updated: 2025-11-10 Scope: Development workflows, tool usage, testing protocols

LENS FRAMEWORK ENFORCED

All outputs and code changes MUST pass the 6-lens validation framework documented in CLAUDE-LENS-CONTRACT.md:

Truth Lens (MANDATORY)

Cite file:line for all factual claims about code
Mark unknowns as [UNKNOWN] - never guess or fill gaps
Separate DATA (observable) / INTERPRETATION (reasoning) / SPECULATION (hypotheses)
Replace "I think/believe" with "Code shows" / "Tests verify"

Causality Lens (MANDATORY)

Every recommendation includes mechanism:

IF: [Action]
THEN: [Result]
BECAUSE: [Mechanism - file/line/function showing why]
DEPENDS ON: [Prerequisites with file paths]
FAILURE MODES: [Conditions causing breakage]

Contradiction Lens (MANDATORY)

Surface conflicts immediately (cite specific files/lines)
Format: "CONTRADICTION: Requirement A (file X:line Y) conflicts with B (file Z:line W)"
Request user decision before attempting resolution

Rights Lens (MANDATORY)

Refuse without softening:

Code violating privacy/security/rights
Unsafe shell operations (rm -rf, unvalidated execSync)
Credential exposure or exfiltration
Format: "Rejected. Violates [specific right/rule]. Alternative: [safer approach]"

Structure Lens (MANDATORY)

All plans include:

PRECONDITIONS: What must exist before starting
POSTCONDITIONS: Guaranteed state after completion
ERROR HANDLING: Failure modes and recovery
VERIFICATION: Shell commands to test success
ROLLBACK: Exact commands to revert if fails

Extrapolation Lens (When Applicable)

Timeline predictions cite historical data (git log, test runs)
Confidence qualifiers for estimates: "Based on X, likely Y"
No absolute predictions without evidence

DEVELOPMENT WORKFLOW

Task Management (CRITICAL)

Use TodoWrite proactively for any multi-step task:

Michael values progress visibility
Mark tasks in_progress BEFORE starting work
Mark tasks completed IMMEDIATELY after finishing
Never batch multiple completions - update in real-time

Proactive Tool Usage

Use these tools automatically without asking:

Built-In Specialized Agents (via Task tool):

doc-writer → After ANY feature completion (before marking done)
lens-validator → Before committing docs or merging code
test-runner → After code modifications (run tests immediately)
code-reviewer → After significant code changes (quality check)
security-auditor → When touching auth, data access, or before deployment
architecture-analyzer → When planning system changes
lens-enforcer → For critical output validation (stricter than lens-validator)

CLI Sub-Agents (for token management): Pattern: "Use a sub agent. [task]. Don't report back."

Vault organization (file moving, linking, consolidation)
Frontend builds (HTML/CSS/JS, React components)
Database setup (Supabase config, schema creation)
Batch generation (multiple files, templates, content)

MCP Servers (when relevant):

Supabase MCP → Database queries, inspection
Google Workspace MCP → Calendar/Docs/Sheets/Gmail/Drive
Playwright → Browser automation, testing, scraping
Perplexity → Research requiring citations
Apify → Web scraping, data collection
Ref → Documentation lookup
Sequential Thinking → Complex multi-step reasoning

Local Graph + Memory Prompts (Codex-ready):

python3 -c "import sqlite3; conn = sqlite3.connect('workspace/data/knowledge-graph.db'); print(conn.execute(\"SELECT title FROM search_index WHERE search_index MATCH 'daily task' LIMIT 5\").fetchall())" for knowledge-graph sweeps
node backend/scripts/test-graph-analysis.cjs "[text]" for InfraNodus-style insights (quality, concepts, gaps)
node tools/test-all-graphs.cjs to query vector memory (workspace/data/memory.db), the knowledge graph, and local graph analysis in one pass

File Operations

ALWAYS prefer Edit over Write for existing files
Read file before editing (tool requirement)
Use Grep/Glob to search before making changes
Preserve exact indentation (tabs/spaces) from Read output

📊 Knowledge Graph Onboarding (2025-11-13)

Purpose: Hybrid vector + relational knowledge base for semantic code search, entity extraction, and architectural analysis.

Location: workspace/data/knowledge-graph.db (SQLite with FTS5 + vec0 extensions) Database Stats (2025-11-14): 610 documents (521 Obsidian), 1,811 entities, 17,158 relationships, 0 isolated nodes MCP Server: soulfield-kg (available in Codex CLI for strategic consultations)

Quick Start Commands

Enable Knowledge Graph Features:

# .env configuration (already set)
USE_KG_EMBEDDINGS=true          # Vector embeddings via embedding-service.cjs
USE_KG_LLM_ENTITIES=true        # Entity extraction via Claude Haiku
USE_KG_PIPELINE=true            # Document processing pipeline
USE_KG_RAG=true                 # Retrieval-augmented generation
USE_KG_GRAPH_COMPLETION=true   # Graph-based query expansion
USE_KG_INSIGHTS=true            # Gap analysis and insights

Verify Database:

# Check entity count
sqlite3 workspace/data/knowledge-graph.db \
  "SELECT COUNT(*) FROM entities"
# Expected: 1811

# Check relationship count
sqlite3 workspace/data/knowledge-graph.db \
  "SELECT COUNT(*) FROM relationships"
# Expected: 17158

# Inspect entity types
sqlite3 workspace/data/knowledge-graph.db \
  "SELECT type, COUNT(*) FROM entities GROUP BY type"

Test Knowledge Graph:

# Run comprehensive test suite
node backend/tests/kg-*.test.cjs

# Test entity extraction
node backend/tests/kg-entity-extraction.test.cjs

# Test relationship extraction
node backend/tests/kg-relationship-extraction.test.cjs

# Test embeddings with lazy load
node backend/tests/kg-embedding-lazy-load.test.cjs

# Test pipeline integrity
node backend/tests/pipeline.test.cjs

# End-to-end MCP + InfraNodus verification
node backend/scripts/demo-mcp-search.cjs
node backend/scripts/verify-infranodus-features.cjs

Automation Scripts (backend/scripts/obsidian-automation/):

generate-topic-clusters.cjs → Graph-derived topic groupings (workspace/docs/Obsidian-v2/topics/TOPIC-CLUSTERS.md)
identify-documentation-gaps.cjs → MCP INSIGHTS gap report (workspace/docs/Obsidian-v2/reports/DOCUMENTATION-GAPS.md)
enrich-frontmatter.cjs → Injects related_* metadata into Obsidian YAML frontmatter

Run these after large documentation changes to keep KG and Obsidian metadata synchronized.

Search Types & When to Use

1. Hybrid Search (FTS5 + Vector)

const { searchDocuments } = require('./backend/services/knowledge-graph/kg-sqlite.cjs');

// Conceptual query with semantic understanding
const results = await searchDocuments('lens validation enforcement', {
  limit: 10,
  useVector: true,  // Enable vector similarity
  useFTS: true      // Enable full-text search
});
// Returns: Documents about LensMiddleware, enforcement modes, auto-fix

When to use:

Conceptual queries ("how does X work?")
Topic discovery across codebase
Finding related components by meaning (not exact keywords)

2. Entity Retrieval

const { getEntity } = require('./backend/services/knowledge-graph/kg-sqlite.cjs');

// Get specific agent details
const entity = await getEntity('agent:marketing');
// Returns: Type, properties, relationships, handler path

// Get with relationships
const entity = await getEntity('service:agent-service-bridge', {
  includeRelationships: true
});
// Returns: Entity + all connected components

When to use:

Deep dive on specific component
Understanding agent/service/lens structure
Exploring relationships and dependencies

3. Relationship Queries

const { getRelationships } = require('./backend/services/knowledge-graph/kg-sqlite.cjs');

// Find what depends on a service
const deps = await getRelationships({
  from: 'service:agent-service-bridge',
  type: 'depends_on'
});

// Find all agent handlers
const handlers = await getRelationships({
  to_type: 'agent',
  type: 'implements'
});

When to use:

Dependency analysis ("what breaks if I change X?")
Architectural understanding ("what connects to Y?")
Impact assessment before refactoring

4. Graph Completion (RAG)

const { graphCompletion } = require('./backend/services/knowledge-graph/kg-sqlite.cjs');

// Augment query with graph context
const completion = await graphCompletion('Explain @metrics operational telemetry', {
  maxEntities: 5,
  includeRelationships: true
});
// Returns: Enhanced prompt with relevant entities/relationships from graph

When to use:

Providing context to LLM queries
Augmenting agent prompts with system knowledge
Ensuring accurate answers from knowledge base

Example Queries (JavaScript)

Find all agents with full lens pipeline:

const { searchDocuments } = require('./backend/services/knowledge-graph/kg-sqlite.cjs');

const agents = await searchDocuments('agent lens pipeline full', {
  limit: 20,
  filters: { type: 'agent' }
});
// Returns: @marketing, @finance, @seo (all using 6-lens validation)

Locate code implementing auto-fix:

const { searchDocuments } = require('./backend/services/knowledge-graph/kg-sqlite.cjs');

const code = await searchDocuments('adaptive auto-fix violations', {
  limit: 5,
  filters: { type: 'code' }
});
// Returns: backend/lenses/LensMiddleware.js with context snippets

Analyze service dependencies:

const { getRelationships } = require('./backend/services/knowledge-graph/kg-sqlite.cjs');

const deps = await getRelationships({
  from: 'service:memory',
  type: 'depends_on'
});
// Returns: Supabase connection, embedding service, namespace isolation

Graph-enhanced agent query:

const { graphCompletion } = require('./backend/services/knowledge-graph/kg-sqlite.cjs');

const enhancedPrompt = await graphCompletion(
  '@marketing Create Q1 campaign',
  { maxEntities: 3, includeRelationships: true }
);
// Returns: Original prompt + context about marketing agent capabilities,
// AFS integration, lens validation, available templates

Integration with Agent Service Bridge

Location: backend/services/agent-service-bridge.cjs:197-208

All agents can access knowledge graph via service bridge:

const services = require('../../services/agent-service-bridge.cjs');

// In agent handler
const context = await services.graph.search('lens validation', { limit: 5 });
const entity = await services.graph.getEntity('agent:marketing');
const deps = await services.graph.getRelationships({ from: 'service:afs' });

Migration & Maintenance Scripts

Backfill embeddings:

node backend/scripts/backfill-embeddings.cjs
# Generates vector embeddings for all documents in knowledge graph

Re-extract entities:

node backend/scripts/reextract-entities.cjs
# Uses Claude Haiku to extract entities from all documents

Rebuild relationships:

node backend/scripts/rebuild-relationships.cjs
# Analyzes entity co-occurrence and semantic similarity to rebuild graph

Verify database health:

node backend/scripts/verify-kg-health.cjs
# Checks entity/relationship counts, orphaned nodes, schema integrity

Performance Characteristics

Query Speed:

FTS5 search: <10ms for 1000+ documents
Vector similarity: ~50-100ms (lazy load optimization)
Entity retrieval: <5ms (indexed lookups)
Relationship queries: 10-50ms (depends on graph size)

Memory Usage:

Database: 28MB on disk
Embeddings: Lazy loaded (only when needed)
In-memory cache: ~5-10MB active queries

Cost:

Storage: $0 (local SQLite)
Embeddings: Cached (regenerate only on updates)
Entity extraction: ~$0.01 per 100 documents (Claude Haiku)

Runbook Reference

Full migration guide: workspace/docs/Obsidian-v2/plans/active/WEEK-1-COGNEE-PARITY-PROGRESS.md:222-289

Implementation details:

Embedding service: backend/services/knowledge-graph/embedding-service.cjs:1-272
Entity extraction: backend/services/knowledge-graph/kg-sqlite.cjs:252-394
Pipeline: backend/services/knowledge-graph/pipeline.cjs:1-471

Test coverage:

Pipeline tests: backend/tests/pipeline.test.cjs:1-356 (100% passing)
Summary generation: backend/tests/summary-generation.test.cjs:1-200
Insights: backend/tests/insights.test.cjs

Feature Flags (2025-11-10)

All Track 4 features guarded by flags in .env:

USE_KG_RAG=true - Retrieval-augmented generation
USE_KG_GRAPH_COMPLETION=true - Graph context injection
USE_KG_INSIGHTS=true - Gap analysis and recommendations

Toggle features by setting to false in .env and restarting backend.

SOULFIELD AGENT SYSTEM

Agent Directory

Source: backend/data/agents.json, CLAUDE.md:43-79

Agent ID	Alias	Focus	Lens Pipeline	AFS Integration
governor	@aiden	Chief orchestrator, strategic planning	Strategy (3-lens)	⏭️ Planned
marketing	@marketing	Campaigns, funnels, growth	Full (6-lens)	✅ Complete
finance	@finance	Financial models, burn rate	Full (6-lens)	✅ Complete
seo	@seo	SEO strategy, keywords	Full (6-lens)	✅ Complete
builder	@builder	MVP development (Cove 72h)	Strategy (3-lens)	✅ Complete
distributor	@distributor	Distribution strategy	Strategy (3-lens)	✅ Complete
metrics	@metrics	Analytics, KPI tracking, operational telemetry	Truth-only	✅ Complete
content	@content	Content strategy	Full (6-lens)	⏭️ Planned
legal	@legal	Legal review, compliance	Full (6-lens)	⏭️ Planned
visionary	@visionary	Business strategy	Full (6-lens)	⏭️ Planned
strategy	@strategy	Strategic planning	Strategy (3-lens)	⏭️ Planned
operations	@operations	Process optimization	Strategy (3-lens)	⏭️ Planned
prompter	@prompter	Prompt engineering	Truth-only	⏭️ Planned
scraper	@scraper	Web scraper (Bright Data)	Minimal	N/A (tool)
jina	@jina	Semantic reranking	Truth-only	N/A (tool)

Metrics Agent Usage (2025-11-06)

The @metrics agent supports both business metrics (revenue, engagement, Kill/Keep/Scale decisions) and operational metrics (routing performance, telemetry, MTTR/MTTD).

Operational Metrics (Telemetry): Automatically routes to metrics-operational.cjs when keywords like daily, weekly, summary, telemetry, routing, mttr, mttd, operational, or system are detected.

# Daily operational summary (last 24 hours)
curl -X POST http://localhost:8791/chat -H "Content-Type: application/json" \
  -d '{"prompt":"@metrics daily summary"}'

# Weekly operational summary (last 7 days)
curl -X POST http://localhost:8791/chat -H "Content-Type: application/json" \
  -d '{"prompt":"@metrics weekly summary"}'

# Agent-specific operational metrics
curl -X POST http://localhost:8791/chat -H "Content-Type: application/json" \
  -d '{"prompt":"@metrics @marketing daily summary"}'

# Hourly operational summary (last hour)
curl -X POST http://localhost:8791/chat -H "Content-Type: application/json" \
  -d '{"prompt":"@metrics hourly summary"}'

Business Metrics (Revenue, Engagement): Routes to metrics.cjs for business intelligence, Kill/Keep/Scale decisions, and revenue analysis.

# Kill/Keep/Scale decision
curl -X POST http://localhost:8791/chat -H "Content-Type: application/json" \
  -d '{"prompt":"@metrics Analyze: 150 units sold, $4500 revenue, 12% refund rate. KILL/KEEP/SCALE?"}'

# Revenue analysis
curl -X POST http://localhost:8791/chat -H "Content-Type: application/json" \
  -d '{"prompt":"@metrics revenue analysis for Q4"}'

# Launch performance
curl -X POST http://localhost:8791/chat -H "Content-Type: application/json" \
  -d '{"prompt":"@metrics analyze launch performance: 500 signups, 200 sales, 40% conversion"}'

Output Locations:

Operational reports: workspace/agent-workspace/agents/metrics/reports/{date}-{timeframe}-ops-metrics.md
Business reports: Varies by analysis type (dashboard, decision, revenue, etc.)
Auto-sync to Google Drive: Enabled by default

Backend Routing & Lens Enforcement (2025-11-06)

AgentRouter registers marketing/finance/seo handlers before lens bootstrapping, so routing failures here block middleware escalation (backend/council.js:60-backend/council.js:67).
LensOrchestrator and LensMiddleware initialize with agent-specific overrides: marketing/seo/builder adaptive auto-fix, governor/legal strict, metrics/prompter soft (backend/council.js:85-backend/council.js:151, backend/lenses/LensMiddleware.js:20-backend/lenses/LensMiddleware.js:76).
LensMiddleware enforces critical vs warning lenses and manages adaptive auto-fix hashing to prevent oscillation during revalidation (backend/lenses/LensMiddleware.js:79-backend/lenses/LensMiddleware.js:200).
Local graph analysis run (2025-11-06) highlighted marketing/metrics as bridge nodes across orchestration and telemetry clusters; leverage the service implementation for diagnostics (backend/services/local-graph-analysis.cjs:84-backend/services/local-graph-analysis.cjs:182).

Service Bridge (2025-11-06)

Location: backend/services/agent-service-bridge.cjs Purpose: Unified API gateway for agent handlers to access Google Workspace, Memory, Graph Analysis, and File System.

Import in agent handlers:

const services = require('../../services/agent-service-bridge.cjs');

Google Workspace Operations:

services.googleWorkspace.createCalendarEvent({summary, description, start, end})
services.googleWorkspace.createDocument({title, content})
services.googleWorkspace.createSpreadsheet({title, headers, rows})
services.googleWorkspace.sendEmail({to, subject, body})

Memory Operations:

services.memory.query({text, topK, filter})
services.memory.store({text, metadata})

Graph Analysis:

services.graph.analyzeForAgent(agentId, text, options)

File System:

services.fileSystem.writeFile(agentId, filename, content, options)
services.fileSystem.readFile(agentId, filename)

Telemetry:

services.telemetry.log(telemetryData)

Error Handling: All operations return {success, ...data, error} with graceful error handling.

Availability Checks:

if (services.isAvailable.googleWorkspace) {
  // Use Google services
}

Test Coverage: backend/tests/agent-service-bridge.test.cjs (16 test cases, 100% passing)

Ethical Pipeline (Rights → Causality → Truth):

Governor agent uses "ethical" pipeline: 3-lens validation prioritizing Rights enforcement (backend/lenses/LensOrchestrator.js:85-backend/lenses/LensOrchestrator.js:104).
Rights violations trigger critical halts in strict mode (governor/legal agents) before Causality/Truth checks (backend/lenses/LensMiddleware.js:142-backend/lenses/LensMiddleware.js:183).
Telemetry captures lens critical halts, provider fallbacks (Anthropic/ZAI), and middleware enforcement stats via /lens-audit endpoint (backend/council.js:1969, backend/council.js:1988, backend/council.js:2471).
Middleware stats include totalValidations, criticalHalts, autoFixes, autoFixFailures, successRate, autoFixRate per agent (backend/lenses/LensMiddleware.js:562-backend/lenses/LensMiddleware.js:572).

Agent Workspaces

Per-agent: workspace/agent-workspace/agents/{agent-name}/
Multi-agent projects: workspace/agent-workspace/projects/
Auto-sync to Google Drive via AFS

TESTING PROTOCOLS

Automated Testing

# Full test suite
npm test

# Specific lens tests
node backend/tests/truth-lens.test.cjs
node backend/tests/lens-middleware.test.cjs
node backend/tests/causality-lens.test.cjs

# Integration tests
node backend/tests/observability-options123.test.cjs
node backend/tests/graphlens-integration.test.cjs

# Service-specific tests
node backend/tests/local-graph-analysis-*.test.cjs

# Provider fallback tests (Priority 1A)
node backend/tests/provider-fallback.test.cjs

# Meta-tests (test-the-tests validation, Priority 1B)
npm run test:meta
# Runs: test-tests-routing.test.cjs, test-tests-red-team.test.cjs, test-tests-chaos.test.cjs

Test-Driven Development

Run tests BEFORE making changes (baseline)
Make code changes
Run tests IMMEDIATELY after changes
Fix failures before marking task complete
Use test-runner agent for automated test execution

Production Readiness Checks

Lens framework: All 6 base lenses + 2 enhanced lenses operational
Test coverage: 37+ test files, comprehensive validation
Integration: 17/21 passing (81% - timing issues non-critical)
Deployment: DEPLOYMENT.md procedures validated

DOCUMENTATION STRUCTURE

Atomic Reference System

Location: workspace/docs/Obsidian-v2/docs/reference/

Categories:

agents/ (16 files) - Agent references (@marketing, @finance, @seo, etc.)
lenses/ (10 files) - Lens validation components
services/ (15 files) - System services (memory, AFS, Google, etc.)
frameworks/ (4 files) - Architectural frameworks

Master Index: workspace/docs/Obsidian-v2/docs/reference/INDEX.md

Obsidian Search Patterns

tag:#marketing          → All marketing-related files
type:agent              → All 16 agent references
category:lens           → All 10 lens references
status:active           → Active components only

Documentation Updates (MANDATORY)

After completing ANY feature:

Use doc-writer agent (proactive, don't wait)
Update relevant reference files in docs/reference/
Update CHANGELOG.md with changes
Update README.md if user-facing
Create session summary in docs/Obsidian-v2/daily/{date}.md

GIT DISCIPLINE

Commit Workflow

Before commit:
- Run tests: npm test
- Lens validation: lens-check (pre-commit hook)
- Review changes: git diff
Commit message format:

git commit -m "$(cat <<'EOF'
feat(component): description

Detailed explanation of changes.

VERIFICATION:
- Tests passing (npm test)
- Lens validation passed
- No regressions detected

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

Post-commit:
- Update CHANGELOG.md if not done
- Create session summary if significant work

Branch Strategy

Branch from main: git checkout -b feat/<topic>
Push with tracking: git push -u origin <branch>
Auto-delete head branches enabled (merged PRs disappear)
Resolve conflicts by rebasing onto origin/main

ENVIRONMENT & DEPLOYMENT

Development Environment

# Backend server
npm start                    # Soulfield backend :8791

# Observability hub (Phase 3)
cd tools/observability-hub
GRAPHLENS_AUTH_SECRET=xxx node index.js  # Hub :3000

# Health checks
curl http://localhost:8791/health
curl http://localhost:3000/health

Environment Variables

See .env file and CLAUDE.md:Environment Variables section.

Critical variables:

ANTHROPIC_API_KEY - Claude API (primary LLM)
SUPABASE_URL, SUPABASE_SERVICE_KEY - Vector memory
GRAPHLENS_AUTH_SECRET - Observability hub HMAC (Phase 3)
GRAPHLENS_DISTRIBUTED - Enable/disable hook integration

Cost Monitoring

Current: ~$175-180/month (Claude Code CLI, Soulfield agents, ChatGPT Pro) Alert threshold: $245/month

DECISION AUTHORITY MATRIX

✅ Do Without Asking

Run tests after code changes
Update CHANGELOG.md after features
Use doc-writer after completion
Create git commits when user requests
Fix lint/type errors
Add missing file:line citations
Invoke test-runner, code-reviewer, lens-validator proactively

⚠️ Ask First

Modify high-risk zones (backend/council.js:275-342 core routing)
Change API contracts or schemas
Delete files outside archive system
Modify production environment variables
Force-push to main branch

🛑 Never Do

Skip lens validation in strict mode
Commit secrets or credentials
Modify .gitignore to expose sensitive files
Execute destructive commands without explicit request
Bypass security checks (HMAC, authentication)

RECENT UPDATES

2025-10-31: Phase 3 GraphLens Complete

Distributed observability system operational
Hub server :3000 with HMAC auth, SQLite WAL, WebSocket
Dashboard rendering live metrics (7 events, 42.9% pass rate)
40 files committed, 7959 lines added
Comprehensive test coverage (200+ tests across 12 suites)

2025-11-10: Knowledge Graph Parity Week 1 Delivered

Local SQLite knowledge graph now mirrors Cognee workflows: embeddings service (backend/services/knowledge-graph/embedding-service.cjs:1-272), Claude Haiku entity extraction (backend/services/knowledge-graph/kg-sqlite.cjs:252-394), transaction pipeline with rollback plus auto-summaries (backend/services/knowledge-graph/pipeline.cjs:1-471).
Data migration complete (186 docs → 186 embeddings, 2,117 entities, 15,394 relationships) via CLI scripts (backend/scripts/backfill-embeddings.cjs:1-120, backend/scripts/reextract-entities.cjs, backend/scripts/rebuild-relationships.cjs) with runbook in workspace/docs/Obsidian-v2/plans/active/WEEK-1-COGNEE-PARITY-PROGRESS.md:222-289.
Track 4 features live: RAG completion, graph completion, insights search guarded by feature flags (USE_KG_EMBEDDINGS, USE_KG_LLM_ENTITIES, USE_KG_PIPELINE, USE_KG_RAG, USE_KG_GRAPH_COMPLETION, USE_KG_INSIGHTS) and test suites (backend/tests/pipeline.test.cjs:1-356, backend/tests/summary-generation.test.cjs:1-200, backend/tests/insights.test.cjs).

2025-10-30: GraphLens Integration

Enhanced lenses operational (CausalQualityLens, StructureLensV2)
Local graph analysis complete (8 test suites)
LensOrchestrator: 7 pipeline types operational

2025-10-29: Governor Refactor

Cove Framework extracted to standalone workflow
Governor now orchestration-focused
Workflow documentation updated

VERIFICATION CHECKLIST

Before marking ANY task as complete:

Tests passing (npm test)
Lens validation passed (pre-commit hook or manual check)
Documentation updated (README, CHANGELOG, reference files)
TodoWrite tasks marked completed
No regressions detected
Session summary created (if significant work)
Git commit created (if code changes)

QUICK REFERENCE

Key Files:

Technical architecture: CLAUDE.md
Strategic context: CODEX-AGENTS.md
Lens contract: CLAUDE-LENS-CONTRACT.md
Operations playbook: workspace/docs/Obsidian-v2/plans/active/AGENT-OPERATIONS-PLAYBOOK.md
Changelog: CHANGELOG.md
Deployment: tools/observability-hub/DEPLOYMENT.md

Key Commands:

Tests: npm test
Start backend: npm start
Routing regression: node backend/tests/routing-regression.test.cjs
Red-team adversarial: node backend/tests/routing-red-team.test.cjs
Observability spans: node backend/tests/observability-spans.test.cjs
Chaos handler outage: node backend/tests/chaos-handler-outage.test.cjs
Chaos telemetry disruption: node backend/tests/chaos-telemetry-disruption.test.cjs
Chaos config tamper: node backend/tests/chaos-config-tamper.test.cjs
Lens check: lens-check <file>
Health checks: curl http://localhost:8791/health
Trace debugging: node backend/scripts/print-latest-traces.cjs 10

Emergency Rollback:

# Disable Phase 3
unset GRAPHLENS_DISTRIBUTED
pkill -f observability-hub

# Revert code
git checkout <file>

# Restore database
cp tools/observability-hub/telemetry.db.backup \
   tools/observability-hub/telemetry.db

REMINDER: This file is auto-loaded by Agent Context Manager plugin on session start. Keep it updated with latest workflows and conventions.

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

Soulfield Agent Instructions (Claude Code / Sentinel)

LENS FRAMEWORK ENFORCED

Truth Lens (MANDATORY)

Causality Lens (MANDATORY)

Contradiction Lens (MANDATORY)

Rights Lens (MANDATORY)

Structure Lens (MANDATORY)

Extrapolation Lens (When Applicable)

DEVELOPMENT WORKFLOW

Task Management (CRITICAL)

Proactive Tool Usage

File Operations

📊 Knowledge Graph Onboarding (2025-11-13)

Quick Start Commands

Search Types & When to Use

Example Queries (JavaScript)

Integration with Agent Service Bridge

Migration & Maintenance Scripts

Performance Characteristics

Runbook Reference

Feature Flags (2025-11-10)

SOULFIELD AGENT SYSTEM

Agent Directory

Metrics Agent Usage (2025-11-06)

Backend Routing & Lens Enforcement (2025-11-06)

Service Bridge (2025-11-06)

Agent Workspaces

TESTING PROTOCOLS

Automated Testing

Test-Driven Development

Production Readiness Checks

DOCUMENTATION STRUCTURE

Atomic Reference System

Obsidian Search Patterns

Documentation Updates (MANDATORY)

GIT DISCIPLINE

Commit Workflow

Branch Strategy

ENVIRONMENT & DEPLOYMENT

Development Environment

Environment Variables

Cost Monitoring

DECISION AUTHORITY MATRIX

✅ Do Without Asking

⚠️ Ask First

🛑 Never Do

RECENT UPDATES

2025-10-31: Phase 3 GraphLens Complete

2025-11-10: Knowledge Graph Parity Week 1 Delivered

2025-10-30: GraphLens Integration

2025-10-29: Governor Refactor

VERIFICATION CHECKLIST

QUICK REFERENCE