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>
This commit is contained in:
213
.claude/REFERENCE.md
Normal file
213
.claude/REFERENCE.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```python
|
||||
POST /api/projects
|
||||
{
|
||||
"name": "New Website",
|
||||
"client_id": "client-uuid",
|
||||
"status": "planning"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Track Work Session
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```bash
|
||||
# Get JWT Token
|
||||
POST /api/auth/token
|
||||
{ "email": "user@example.com", "password": "your-password" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
Reference in New Issue
Block a user