Files

Mike Swanson ab5db78eb2 refactor: Trim CLAUDE.md and directives to reduce context window pressure

Reduced always-loaded context from ~1,570 lines to ~75 lines (-95%):
- CLAUDE.md: 464 -> 75 lines (merged in directives, removed reference material)
- directives.md: 639 -> 7 lines (now pointer to CLAUDE.md)
- AGENT_COORDINATION_RULES.md: 468 -> 32 lines (slim agent reference only)
- New REFERENCE.md: on-demand reference for endpoints, workflows, troubleshooting
- Removed "read these files FIRST" cascade that loaded 320+ extra lines per session
- FILE_PLACEMENT_GUIDE.md and CODING_GUIDELINES.md now read on-demand by agents

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-17 10:49:35 -07:00

5.4 KiB

Raw Blame History

ClaudeTools Reference Guide

Purpose: On-demand reference material for agents and deep-dive questions. Not loaded automatically - agents read this when they need project details.

Project Structure

D:\ClaudeTools/
├── api/                    # FastAPI application
│   ├── main.py            # API entry point
│   ├── models/            # SQLAlchemy models
│   ├── routers/           # API endpoints
│   ├── schemas/           # Pydantic schemas
│   ├── services/          # Business logic
│   ├── middleware/        # Auth & error handling
│   └── utils/             # Crypto utilities
├── migrations/            # Alembic database migrations
├── .claude/              # Claude Code hooks & config
│   ├── commands/         # Commands (create-spec, checkpoint)
│   ├── skills/           # Skills (frontend-design)
│   └── templates/        # Templates (app spec, prompts)
├── mcp-servers/          # MCP server implementations
│   └── feature-management/  # Feature tracking MCP server
├── scripts/              # Setup & test scripts
└── projects/             # Project workspaces

Starting the API

# Activate virtual environment
api\venv\Scripts\activate

# Start API server
python -m api.main
# OR
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

# Access documentation
http://localhost:8000/api/docs

API Endpoints

Core Entities (Phase 4)

/api/machines - Machine inventory
/api/clients - Client management
/api/projects - Project tracking
/api/sessions - Work sessions
/api/tags - Tagging system

MSP Work Tracking (Phase 5)

/api/work-items - Work item tracking
/api/tasks - Task management
/api/billable-time - Time & billing

Infrastructure (Phase 5)

/api/sites - Physical locations
/api/infrastructure - IT assets
/api/services - Application services
/api/networks - Network configs
/api/firewall-rules - Firewall documentation
/api/m365-tenants - M365 tenant management

Credentials (Phase 5)

/api/credentials - Encrypted credential storage
/api/credential-audit-logs - Audit trail (read-only)
/api/security-incidents - Incident tracking

Common Workflows

1. Create New Project

POST /api/projects
{
  "name": "New Website",
  "client_id": "client-uuid",
  "status": "planning"
}

2. Track Work Session

# Create session
POST /api/sessions
{
  "project_id": "project-uuid",
  "machine_id": "machine-uuid",
  "started_at": "2026-01-16T10:00:00Z"
}

# Log billable time
POST /api/billable-time
{
  "session_id": "session-uuid",
  "work_item_id": "work-item-uuid",
  "client_id": "client-uuid",
  "start_time": "2026-01-16T10:00:00Z",
  "end_time": "2026-01-16T12:00:00Z",
  "duration_hours": 2.0,
  "hourly_rate": 150.00,
  "total_amount": 300.00
}

3. Store Encrypted Credential

POST /api/credentials
{
  "credential_type": "api_key",
  "service_name": "OpenAI API",
  "username": "api_key",
  "password": "sk-1234567890",  # Auto-encrypted
  "client_id": "client-uuid",
  "notes": "Production API key"
}
# Password automatically encrypted with AES-256-GCM
# Audit log automatically created

Important Files

File	Purpose
`SESSION_STATE.md`	Complete project history and status
`credentials.md`	ALL infrastructure credentials (UNREDACTED)
`session-logs/`	Daily session documentation
`.env` / `.env.example`	Environment variables
`test_api_endpoints.py`	Phase 4 tests
`test_phase5_api_endpoints.py`	Phase 5 tests
`AUTOCODER_INTEGRATION.md`	AutoCoder resources guide
`TEST_PHASE5_RESULTS.md`	Phase 5 test results

Security

Authentication: JWT tokens (Argon2 password hashing)
Encryption: AES-256-GCM (Fernet) for credentials
Audit Logging: All credential operations logged

# Get JWT Token
POST /api/auth/token
{ "email": "user@example.com", "password": "your-password" }

Troubleshooting

# API won't start - check port
netstat -ano | findstr :8000
# Check database connection
python test_db_connection.py

# Database migration issues
alembic current        # Check current revision
alembic history        # Show migration history
alembic upgrade head   # Upgrade to latest

MCP Servers

See MCP_SERVERS.md for complete details.

GitHub MCP - Repository and PR management (requires token)
Filesystem MCP - Enhanced file operations (D:\ClaudeTools access)
Sequential Thinking MCP - Structured problem-solving

Config: .mcp.json | Setup: bash scripts/setup-mcp-servers.sh

Next Steps (Optional Phase 7)

File Changes API - Track file modifications
Command Runs API - Command execution history
Problem Solutions API - Knowledge base
Failure Patterns API - Error pattern recognition
Environmental Insights API - Contextual learning

These are optional - the system is fully functional without them.

Session Log Locations

Project-Specific:

Dataforth DOS: projects/dataforth-dos/session-logs/YYYY-MM-DD-session.md
ClaudeTools API: projects/claudetools-api/session-logs/YYYY-MM-DD-session.md

Client-Specific: clients/[client-name]/session-logs/YYYY-MM-DD-session.md General/Mixed: session-logs/YYYY-MM-DD-session.md (root)

See PROJECT_ORGANIZATION.md for complete structure.

5.4 KiB Raw Blame History