Initial commit
This commit is contained in:
Zhongwei Li
196
commands/steering-clean.md
Normal file
196
commands/steering-clean.md
Normal file
@@ -0,0 +1,196 @@
|
||||
---
|
||||
description: Clean up old archives, logs, and temporary files to free disk space
|
||||
---
|
||||
|
||||
# Steering Context Generator - Clean
|
||||
|
||||
Remove old archives and temporary files to free up disk space.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
/steering-clean
|
||||
```
|
||||
|
||||
This will:
|
||||
- Archive current context (backup)
|
||||
- Remove archives older than 7 days
|
||||
- Clean logs older than 30 days
|
||||
- Remove cache files
|
||||
- Delete temporary files
|
||||
|
||||
## What Gets Cleaned
|
||||
|
||||
| Item | Location | Retention | Impact |
|
||||
|------|----------|-----------|--------|
|
||||
| Old archives | `.claude/memory/archives/` | 7 days | Can regenerate |
|
||||
| Old logs | `.claude/logs/` | 30 days | Lost history |
|
||||
| Cache files | `.claude/steering/v2.0/cache/` | All | Rebuilt on next use |
|
||||
| Temp files | `.claude/memory/**/*.tmp` | All | Safe to delete |
|
||||
|
||||
## Implementation
|
||||
|
||||
```bash
|
||||
bash scripts/cleanup.sh
|
||||
```
|
||||
|
||||
## Expected Output
|
||||
|
||||
```
|
||||
🧹 Cleaning Steering Context Generator artifacts...
|
||||
|
||||
Artifacts to clean:
|
||||
Archives: 450 MB
|
||||
Logs: 23 MB
|
||||
Cache: 12 MB
|
||||
|
||||
Continue? (y/N) y
|
||||
|
||||
Archiving current context to .claude/memory/archives/backup_20251102_120000...
|
||||
✓ Archived 9 files
|
||||
|
||||
Cleaning old archives (>7 days)...
|
||||
✓ Removed 3 old archives (380 MB freed)
|
||||
|
||||
Cleaning old logs (>30 days)...
|
||||
✓ Removed 145 log files (18 MB freed)
|
||||
|
||||
Cleaning cache...
|
||||
✓ Cleared cache (12 MB freed)
|
||||
|
||||
Cleaning temporary files...
|
||||
✓ Removed 23 temp files (2 MB freed)
|
||||
|
||||
Cleanup complete!
|
||||
Current usage:
|
||||
Archives: 70 MB
|
||||
Logs: 5 MB
|
||||
Total: 250 MB
|
||||
|
||||
Total freed: 412 MB
|
||||
```
|
||||
|
||||
## Safety Features
|
||||
|
||||
**Automatic Backup**:
|
||||
Before cleaning, current context is archived:
|
||||
```
|
||||
.claude/memory/archives/backup_YYYYMMDD_HHMMSS/
|
||||
├── ARCHITECTURE.md
|
||||
├── AI_CONTEXT.md
|
||||
├── CODEBASE_GUIDE.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
**Confirmation Prompt**:
|
||||
Interactive mode asks for confirmation before deleting.
|
||||
|
||||
**Dry Run**:
|
||||
See what would be cleaned without actually deleting:
|
||||
```bash
|
||||
bash scripts/cleanup.sh --dry-run
|
||||
```
|
||||
|
||||
## Cleanup Options
|
||||
|
||||
### Aggressive Cleanup
|
||||
|
||||
Remove all archives (not recommended):
|
||||
```bash
|
||||
# Manual aggressive cleanup
|
||||
rm -rf .claude/memory/archives/*
|
||||
rm -rf .claude/logs/*
|
||||
```
|
||||
|
||||
### Selective Cleanup
|
||||
|
||||
Clean specific areas only:
|
||||
|
||||
**Archives only**:
|
||||
```bash
|
||||
find .claude/memory/archives -type d -mtime +7 -exec rm -rf {} +
|
||||
```
|
||||
|
||||
**Logs only**:
|
||||
```bash
|
||||
find .claude/logs -type f -mtime +30 -delete
|
||||
```
|
||||
|
||||
**Cache only**:
|
||||
```bash
|
||||
rm -rf .claude/steering/v2.0/cache/*
|
||||
```
|
||||
|
||||
### Custom Retention
|
||||
|
||||
Edit `scripts/cleanup.sh` to change retention periods:
|
||||
```bash
|
||||
# Archives: Change from 7 to 30 days
|
||||
find .claude/memory/archives -type d -mtime +30 -exec rm -rf {} +
|
||||
|
||||
# Logs: Change from 30 to 90 days
|
||||
find .claude/logs -type f -mtime +90 -delete
|
||||
```
|
||||
|
||||
## When to Clean
|
||||
|
||||
**Regular Maintenance**:
|
||||
- Weekly: For active projects
|
||||
- Monthly: For stable projects
|
||||
- Before: Major releases
|
||||
- When: Low disk space warnings
|
||||
|
||||
**Signs You Need Cleaning**:
|
||||
- ⚠ Archive size > 500 MB
|
||||
- ⚠ Total .claude/ size > 2 GB
|
||||
- ⚠ Disk space warnings
|
||||
- ⚠ Slow operations
|
||||
|
||||
## Recovering Cleaned Data
|
||||
|
||||
**Recent Backup**:
|
||||
```bash
|
||||
# List available backups
|
||||
ls -lh .claude/memory/archives/backup_*/
|
||||
|
||||
# Restore latest backup
|
||||
LATEST=$(ls -t .claude/memory/archives/backup_* | head -1)
|
||||
cp -r $LATEST/*.md .claude/steering/
|
||||
```
|
||||
|
||||
**From Git**:
|
||||
If context files are committed:
|
||||
```bash
|
||||
git log -- .claude/steering/
|
||||
git checkout HEAD~1 -- .claude/steering/
|
||||
```
|
||||
|
||||
**Regenerate**:
|
||||
If no backups available:
|
||||
```bash
|
||||
/steering-generate
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Permission denied" errors
|
||||
```bash
|
||||
chmod +x scripts/cleanup.sh
|
||||
```
|
||||
|
||||
### Cleanup doesn't free space
|
||||
Check hidden or locked files:
|
||||
```bash
|
||||
lsof | grep .claude
|
||||
```
|
||||
|
||||
### Accidentally deleted current context
|
||||
```bash
|
||||
# Restore from latest backup
|
||||
LATEST=$(ls -t .claude/memory/archives/backup_* | head -1)
|
||||
cp -r $LATEST/*.md .claude/steering/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Free up space:** Run `/steering-clean` regularly!
|
||||
132
commands/steering-config.md
Normal file
132
commands/steering-config.md
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
description: View and modify Steering Context Generator configuration settings
|
||||
---
|
||||
|
||||
# Steering Context Generator - Configuration
|
||||
|
||||
View and customize system configuration.
|
||||
|
||||
## Quick Start
|
||||
|
||||
**View config**:
|
||||
```bash
|
||||
cat .claude/steering/config.json | jq '.'
|
||||
```
|
||||
|
||||
**Edit config**:
|
||||
```bash
|
||||
vim .claude/steering/config.json
|
||||
```
|
||||
|
||||
## Default Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"initialized": true,
|
||||
"created": "2025-11-02T12:00:00Z",
|
||||
"excluded_patterns": [
|
||||
"node_modules/**",
|
||||
".git/**",
|
||||
"dist/**",
|
||||
"build/**",
|
||||
".next/**",
|
||||
"__pycache__/**",
|
||||
"*.pyc",
|
||||
"*.log"
|
||||
],
|
||||
"focus_areas": [
|
||||
"architecture",
|
||||
"security",
|
||||
"performance",
|
||||
"testing"
|
||||
],
|
||||
"output_format": "markdown",
|
||||
"parallel_execution": true,
|
||||
"incremental_updates": true
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### Excluded Patterns
|
||||
|
||||
**Files/directories to skip**:
|
||||
```json
|
||||
"excluded_patterns": [
|
||||
"node_modules/**", // Dependencies
|
||||
".git/**", // Version control
|
||||
"dist/**", "build/**", // Build outputs
|
||||
"coverage/**", // Test coverage
|
||||
"*.min.js", // Minified files
|
||||
"vendor/**" // Third-party code
|
||||
]
|
||||
```
|
||||
|
||||
### Focus Areas
|
||||
|
||||
**Analysis priorities**:
|
||||
```json
|
||||
"focus_areas": [
|
||||
"architecture", // System design
|
||||
"security", // Vulnerabilities
|
||||
"performance", // Bottlenecks
|
||||
"testing", // Test coverage
|
||||
"documentation" // Code docs
|
||||
]
|
||||
```
|
||||
|
||||
### Execution Options
|
||||
|
||||
```json
|
||||
"parallel_execution": true, // Run agents in parallel (55% faster)
|
||||
"incremental_updates": true // Enable delta updates
|
||||
```
|
||||
|
||||
## Common Customizations
|
||||
|
||||
### For Large Monorepos
|
||||
|
||||
```json
|
||||
{
|
||||
"excluded_patterns": [
|
||||
"packages/*/node_modules/**",
|
||||
"apps/*/dist/**",
|
||||
"*.lock"
|
||||
],
|
||||
"parallel_execution": true
|
||||
}
|
||||
```
|
||||
|
||||
### For Security-Focused Analysis
|
||||
|
||||
```json
|
||||
{
|
||||
"focus_areas": ["security", "quality"],
|
||||
"deep_scan_enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
### For Fast Iterations
|
||||
|
||||
```json
|
||||
{
|
||||
"excluded_patterns": [
|
||||
"**/*.test.ts",
|
||||
"**/*.spec.ts",
|
||||
"**/__tests__/**"
|
||||
],
|
||||
"parallel_execution": true
|
||||
}
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
After editing, validate config:
|
||||
```bash
|
||||
jq empty .claude/steering/config.json && echo "✓ Valid JSON" || echo "✗ Invalid JSON"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Customize your analysis:** Edit `.claude/steering/config.json`
|
||||
137
commands/steering-export.md
Normal file
137
commands/steering-export.md
Normal file
@@ -0,0 +1,137 @@
|
||||
---
|
||||
description: Export steering context to different formats (JSON, YAML, HTML, PDF - Coming Soon)
|
||||
---
|
||||
|
||||
# Steering Context Generator - Export
|
||||
|
||||
Export generated documentation to different formats.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
/steering-export --format json
|
||||
```
|
||||
|
||||
## Supported Formats (v1.0)
|
||||
|
||||
### Markdown (Default)
|
||||
|
||||
Already generated in `.claude/steering/*.md`
|
||||
|
||||
### JSON
|
||||
|
||||
Export as structured JSON:
|
||||
|
||||
```bash
|
||||
# Export all documents
|
||||
cat > .claude/steering/export/context.json << 'EOF'
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"generated": "$(date -Iseconds)",
|
||||
"project": {
|
||||
"name": "$(basename $(pwd))",
|
||||
"tech_stack": "$(jq -r '.tech_stack' .claude/memory/orchestration/detection.json 2>/dev/null || echo 'Unknown')"
|
||||
},
|
||||
"documents": {
|
||||
"architecture": "$(cat .claude/steering/ARCHITECTURE.md | base64)",
|
||||
"ai_context": "$(cat .claude/steering/AI_CONTEXT.md | base64)",
|
||||
"codebase_guide": "$(cat .claude/steering/CODEBASE_GUIDE.md | base64)"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
|
||||
echo "Exported to: .claude/steering/export/context.json"
|
||||
```
|
||||
|
||||
### Plain Text
|
||||
|
||||
Strip markdown formatting:
|
||||
|
||||
```bash
|
||||
# Convert markdown to plain text
|
||||
for file in .claude/steering/*.md; do
|
||||
BASENAME=$(basename "$file" .md)
|
||||
pandoc "$file" -t plain -o ".claude/steering/export/${BASENAME}.txt" 2>/dev/null || \
|
||||
sed 's/[#*`]//g' "$file" > ".claude/steering/export/${BASENAME}.txt"
|
||||
done
|
||||
|
||||
echo "Exported to: .claude/steering/export/*.txt"
|
||||
```
|
||||
|
||||
## Coming Soon (v1.1+)
|
||||
|
||||
### HTML
|
||||
|
||||
```bash
|
||||
# Will generate interactive HTML documentation
|
||||
/steering-export --format html
|
||||
```
|
||||
|
||||
### PDF
|
||||
|
||||
```bash
|
||||
# Will generate PDF documentation
|
||||
/steering-export --format pdf
|
||||
```
|
||||
|
||||
### YAML
|
||||
|
||||
```bash
|
||||
# Will generate YAML configuration
|
||||
/steering-export --format yaml
|
||||
```
|
||||
|
||||
## Export Directory
|
||||
|
||||
Exports are saved to:
|
||||
```
|
||||
.claude/steering/export/
|
||||
├── context.json
|
||||
├── ARCHITECTURE.txt
|
||||
├── AI_CONTEXT.txt
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Share with Team
|
||||
|
||||
```bash
|
||||
# Export and compress
|
||||
/steering-export --format json
|
||||
tar -czf context-export.tar.gz .claude/steering/export/
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
```bash
|
||||
# Export as JSON for automated processing
|
||||
/steering-export --format json
|
||||
cat .claude/steering/export/context.json | jq '.documents.architecture'
|
||||
```
|
||||
|
||||
### Documentation Website
|
||||
|
||||
```bash
|
||||
# Convert to HTML (v1.1+)
|
||||
/steering-export --format html
|
||||
# Publish to docs site
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Export fails
|
||||
|
||||
Ensure documents are generated:
|
||||
```bash
|
||||
/steering-status
|
||||
```
|
||||
|
||||
If missing, generate first:
|
||||
```bash
|
||||
/steering-generate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Share your context:** Export with `/steering-export`
|
||||
432
commands/steering-generate.md
Normal file
432
commands/steering-generate.md
Normal file
@@ -0,0 +1,432 @@
|
||||
---
|
||||
description: Generate comprehensive steering context documentation by analyzing your codebase with specialized AI agents
|
||||
---
|
||||
|
||||
# Steering Context Generator - Full Generation
|
||||
|
||||
Analyze your entire codebase and generate comprehensive AI-readable documentation.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
/steering-generate
|
||||
```
|
||||
|
||||
That's it! The system will:
|
||||
1. 🔍 Detect your project type and tech stack
|
||||
2. 📊 Assess complexity and select workflow
|
||||
3. 🤖 Execute specialized agents in parallel
|
||||
4. 📝 Generate comprehensive documentation
|
||||
5. ✅ Validate and save outputs
|
||||
|
||||
## What Gets Generated
|
||||
|
||||
The following documents are created in `.claude/steering/`:
|
||||
|
||||
### Core Documents (Always Generated)
|
||||
|
||||
| Document | Purpose | Typical Size |
|
||||
|----------|---------|--------------|
|
||||
| `ARCHITECTURE.md` | System architecture, components, data flow | 200-400 KB |
|
||||
| `AI_CONTEXT.md` | Bootstrap context for AI agents | 100-200 KB |
|
||||
| `CODEBASE_GUIDE.md` | Developer onboarding guide | 150-300 KB |
|
||||
|
||||
### Extended Documents (Based on Project Type)
|
||||
|
||||
| Document | Generated When | Purpose |
|
||||
|----------|----------------|---------|
|
||||
| `DOMAIN_CONTEXT.md` | Complex projects | Business logic and rules |
|
||||
| `QUALITY_REPORT.md` | Always | Security, performance analysis |
|
||||
| `UI_DESIGN_SYSTEM.md` | Frontend detected | Component catalog, design tokens |
|
||||
| `TESTING_GUIDE.md` | Tests found | Testing patterns, coverage |
|
||||
| `DATABASE_CONTEXT.md` | Database detected | Schema, DAL patterns |
|
||||
| `MESSAGING_GUIDE.md` | Queues/events found | Event catalog, pub/sub |
|
||||
| `API_DESIGN_GUIDE.md` | API endpoints found | REST standards, error handling |
|
||||
| `STRIPE_PAYMENT_CONTEXT.md` | Stripe integration found | Payment flows, webhook handlers, PCI compliance |
|
||||
| `AUTH0_OAUTH_CONTEXT.md` | Auth0 integration found | OAuth flows, configuration, security assessment |
|
||||
| `PAYLOAD_CMS_CONTEXT.md` | Payload CMS detected | CMS architecture, content models, API configuration |
|
||||
| `PAYLOAD_CMS_CONFIG.md` | Payload CMS detected | Configuration analysis, security audit, compliance |
|
||||
| `DESIGN_SYSTEM_ARCHITECTURE.md` | Design tokens/components detected | Design token analysis, component library structure, maturity |
|
||||
| `UI_FRAMEWORK_GUIDE.md` | UI framework detected (React, Vue, etc.) | Framework configuration, component patterns, best practices |
|
||||
| `WEB_UI_DESIGN_CONTEXT.md` | Frontend pages/components detected | Web UI design analysis, accessibility, UX flows, responsive design |
|
||||
|
||||
## How It Works
|
||||
|
||||
### Phase 1: Project Detection
|
||||
|
||||
The system automatically detects:
|
||||
|
||||
**Tech Stack**:
|
||||
- Package managers (npm, pnpm, pip, cargo, go, maven, gradle)
|
||||
- Frameworks (Next.js, React, Django, FastAPI, etc.)
|
||||
- Databases (Prisma, Drizzle, TypeORM, MongoDB, etc.)
|
||||
- Testing frameworks (Jest, Vitest, pytest, etc.)
|
||||
- **UI frameworks** (React, Vue, Angular, Svelte - if detected)
|
||||
- **Design system tools** (Tailwind, Shadcn, Storybook, design tokens)
|
||||
- **Auth0 OAuth integration** (if @auth0 SDK detected)
|
||||
- **Payload CMS integration** (if @payloadcms packages detected)
|
||||
|
||||
**Project Structure**:
|
||||
- Monorepo vs single-package
|
||||
- Microservices vs monolith
|
||||
- Frontend, backend, or full-stack
|
||||
- File count and directory depth
|
||||
|
||||
**Complexity Assessment**:
|
||||
```
|
||||
Simple: < 50 files, < 3 levels deep → 20 min
|
||||
Moderate: 50-200 files, 3-6 levels deep → 45 min
|
||||
Complex: 200+ files, 6+ levels deep → 85 min
|
||||
```
|
||||
|
||||
### Phase 2: Agent Selection
|
||||
|
||||
Based on detection, the system selects appropriate agents:
|
||||
|
||||
**Foundation Agents** (Always Run):
|
||||
- `structure-analyst`: Map file system and dependencies
|
||||
- `pattern-detective`: Identify architectural patterns
|
||||
- `quality-auditor`: Security and quality analysis
|
||||
|
||||
**Domain-Specific Agents** (Conditional):
|
||||
- `ui-specialist`: If frontend components found
|
||||
- **`design-system-architect`**: If design tokens/component library detected
|
||||
- **`ui-framework-analyzer`**: If UI framework detected (React, Vue, Angular, Svelte)
|
||||
- **`web-ui-design-analyzer`**: If frontend pages/components found
|
||||
- `test-strategist`: If test files found
|
||||
- `database-analyst`: If database schemas found
|
||||
- `messaging-architect`: If queues/events found
|
||||
- `api-design-analyst`: If API routes found
|
||||
- **`auth0-detector`**: If Auth0 SDK imports or configuration found
|
||||
- **`oauth-security-auditor`**: If Auth0 integration found (runs after auth0-detector)
|
||||
- **`payload-cms-detector`**: If Payload CMS packages detected
|
||||
- **`payload-cms-config-analyzer`**: If Payload CMS detected (runs after payload-cms-detector)
|
||||
|
||||
**Synthesis Agent** (Always Final):
|
||||
- `context-synthesizer`: Generate final documentation
|
||||
|
||||
### Phase 3: Parallel Execution
|
||||
|
||||
Agents execute in intelligent parallel groups:
|
||||
|
||||
```mermaid
|
||||
Group 1 (Foundation):
|
||||
structure-analyst ───────┐
|
||||
integration-mapper ──────┤ Run in parallel
|
||||
ui-specialist ───────────┘
|
||||
|
||||
Group 2 (Analysis) - Depends on Group 1:
|
||||
domain-expert ──────────┐
|
||||
pattern-detective ──────┤
|
||||
test-strategist ────────┤ Run in parallel
|
||||
database-analyst ───────┤
|
||||
design-system-architect ┘
|
||||
|
||||
Group 3 (UI/Framework/Design) - Depends on Groups 1 & 2:
|
||||
ui-framework-analyzer ──┐
|
||||
web-ui-design-analyzer ─┤ Run in parallel
|
||||
messaging-architect ────┤
|
||||
api-design-analyst ─────┤
|
||||
stripe-payment-expert ──├ Run in parallel
|
||||
auth0-detector ─────────┤
|
||||
payload-cms-detector ───┤
|
||||
quality-auditor ────────┘
|
||||
|
||||
Group 3B (Security & Config Audits) - Depends on Group 3:
|
||||
oauth-security-auditor (sequential, after auth0-detector, if Auth0 detected)
|
||||
payload-cms-config-analyzer (sequential, after payload-cms-detector, if Payload CMS detected)
|
||||
|
||||
Group 4 (Synthesis) - Depends on all:
|
||||
context-synthesizer (sequential)
|
||||
```
|
||||
|
||||
**Time Savings**: Parallel execution is 55% faster than sequential!
|
||||
**Note**: UI/Framework/Design analysis adds ~30-40 minutes for comprehensive analysis if UI detected.
|
||||
**Note**: Auth0 security audit runs automatically after Auth0 detection, adding ~10 minutes if Auth0 is present.
|
||||
**Note**: Payload CMS config analysis runs automatically after CMS detection, adding ~10 minutes if Payload CMS is present.
|
||||
|
||||
### Phase 4: Output Generation
|
||||
|
||||
Each agent contributes to final documents:
|
||||
|
||||
```
|
||||
structure-analyst → ARCHITECTURE.md (structure section)
|
||||
domain-expert → DOMAIN_CONTEXT.md (complete)
|
||||
pattern-detective → ARCHITECTURE.md (patterns section)
|
||||
ui-specialist → UI_DESIGN_SYSTEM.md (complete)
|
||||
design-system-architect → DESIGN_SYSTEM_ARCHITECTURE.md (complete, if design system found)
|
||||
ui-framework-analyzer → UI_FRAMEWORK_GUIDE.md (complete, if UI framework found)
|
||||
web-ui-design-analyzer → WEB_UI_DESIGN_CONTEXT.md (complete, if frontend pages found)
|
||||
test-strategist → TESTING_GUIDE.md (complete)
|
||||
database-analyst → DATABASE_CONTEXT.md (complete)
|
||||
messaging-architect → MESSAGING_GUIDE.md (complete)
|
||||
api-design-analyst → API_DESIGN_GUIDE.md (complete)
|
||||
stripe-payment-expert → STRIPE_PAYMENT_CONTEXT.md (complete, if Stripe found)
|
||||
auth0-detector → AUTH0_OAUTH_CONTEXT.md (complete, if Auth0 found)
|
||||
oauth-security-auditor → AUTH0_SECURITY_AUDIT.md (complete, if Auth0 found)
|
||||
payload-cms-detector → PAYLOAD_CMS_CONTEXT.md (complete, if Payload CMS found)
|
||||
payload-cms-config-analyzer → PAYLOAD_CMS_CONFIG.md (complete, if Payload CMS found)
|
||||
quality-auditor → QUALITY_REPORT.md (complete)
|
||||
context-synthesizer → AI_CONTEXT.md, CODEBASE_GUIDE.md
|
||||
```
|
||||
|
||||
## Execution Workflow
|
||||
|
||||
The system uses the Task tool to invoke agents in parallel:
|
||||
|
||||
### Step 1: Initialize Session
|
||||
|
||||
```bash
|
||||
# Create session ID for tracking
|
||||
SESSION_ID="gen_$(date +%Y%m%d_%H%M%S)"
|
||||
|
||||
# Initialize execution state
|
||||
cat > .claude/memory/orchestration/current_session.json << EOF
|
||||
{
|
||||
"session_id": "$SESSION_ID",
|
||||
"started": "$(date -Iseconds)",
|
||||
"status": "running",
|
||||
"phase": "detection"
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
### Step 2: Detect and Assess
|
||||
|
||||
Analyze project characteristics:
|
||||
|
||||
```markdown
|
||||
Detecting project type...
|
||||
✓ Tech Stack: Node.js/TypeScript
|
||||
✓ Framework: Next.js 14 (App Router)
|
||||
✓ Package Manager: pnpm (monorepo detected)
|
||||
✓ Database: Prisma + PostgreSQL
|
||||
✓ Testing: Vitest + Playwright
|
||||
✓ CMS: Payload CMS v2.x detected
|
||||
|
||||
Assessing complexity...
|
||||
Files: 387
|
||||
Directories: 45 (max depth: 6)
|
||||
Dependencies: 73
|
||||
Estimated LOC: ~25,000
|
||||
|
||||
Complexity: Moderate
|
||||
Estimated Time: 55 minutes (includes Payload CMS analysis)
|
||||
Workflow: Standard (3 parallel phases + security audits)
|
||||
```
|
||||
|
||||
### Step 3: Execute Foundation Agents (Group 1)
|
||||
|
||||
Use the Task tool to run agents in parallel:
|
||||
|
||||
**Critical**: Execute ALL agents in Group 1 in a SINGLE message with multiple Task tool calls.
|
||||
|
||||
### Step 4: Execute Analysis Agents (Group 2)
|
||||
|
||||
**Depends on**: Group 1 outputs
|
||||
|
||||
### Step 5: Execute Architecture Agents (Group 3)
|
||||
|
||||
**Depends on**: Groups 1 & 2 outputs
|
||||
|
||||
### Step 5B: Execute Security Audits (Group 3B, Sequential)
|
||||
|
||||
**Depends on**: Group 3 outputs
|
||||
|
||||
Automatically executes after:
|
||||
- Auth0 detection (if Auth0 found)
|
||||
- Payload CMS detection (if Payload CMS found)
|
||||
|
||||
### Step 6: Final Synthesis (Group 4)
|
||||
|
||||
**Depends on**: All previous outputs
|
||||
|
||||
### Step 7: Validation and Completion
|
||||
|
||||
```bash
|
||||
# Validate generated files
|
||||
bash scripts/validate.sh
|
||||
|
||||
# Display summary
|
||||
echo "✅ Steering context generation complete!"
|
||||
echo ""
|
||||
echo "Generated Files (.claude/steering/):"
|
||||
ls -lh .claude/steering/*.md | awk '{print " ✓", $9, "(" $5 ")"}'
|
||||
echo ""
|
||||
echo "Next Steps:"
|
||||
echo " 1. Review: /steering-status"
|
||||
echo " 2. Load context: Reference .claude/steering/*.md in prompts"
|
||||
echo " 3. Update later: /steering-update (incremental)"
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### Focus Areas
|
||||
|
||||
Prioritize specific analysis areas in `.claude/steering/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"focus_areas": ["architecture", "security", "performance"]
|
||||
}
|
||||
```
|
||||
|
||||
### Excluded Patterns
|
||||
|
||||
Skip certain files/directories:
|
||||
|
||||
```json
|
||||
{
|
||||
"excluded_patterns": [
|
||||
"node_modules/**",
|
||||
".git/**",
|
||||
"dist/**",
|
||||
"*.test.ts"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Parallel Execution
|
||||
|
||||
Disable parallel execution if needed:
|
||||
|
||||
```json
|
||||
{
|
||||
"parallel_execution": false
|
||||
}
|
||||
```
|
||||
|
||||
## Expected Output
|
||||
|
||||
After successful completion:
|
||||
|
||||
```
|
||||
✅ Steering context generation complete! (55 minutes)
|
||||
|
||||
Generated Files (.claude/steering/):
|
||||
✓ ARCHITECTURE.md (342 KB) - System architecture
|
||||
✓ AI_CONTEXT.md (156 KB) - AI agent bootstrap
|
||||
✓ CODEBASE_GUIDE.md (278 KB) - Developer guide
|
||||
✓ DOMAIN_CONTEXT.md (189 KB) - Business logic
|
||||
✓ QUALITY_REPORT.md (134 KB) - Quality analysis
|
||||
✓ PAYLOAD_CMS_CONTEXT.md (203 KB) - CMS architecture
|
||||
✓ PAYLOAD_CMS_CONFIG.md (187 KB) - CMS configuration
|
||||
|
||||
Total: 2.1 MB of context documentation
|
||||
|
||||
Performance:
|
||||
Total tokens: ~165,000
|
||||
Agents executed: 16
|
||||
Parallel efficiency: 52% time saved
|
||||
|
||||
Next Steps:
|
||||
1. Review: /steering-status
|
||||
2. Load context: Reference .claude/steering/*.md in prompts
|
||||
3. Update later: /steering-update (incremental)
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Generation Interrupted
|
||||
|
||||
If generation is interrupted:
|
||||
|
||||
```bash
|
||||
# Check for checkpoint
|
||||
ls .claude/memory/orchestration/current_session.json
|
||||
|
||||
# Resume from checkpoint
|
||||
/steering-resume
|
||||
```
|
||||
|
||||
### Agents Not Found
|
||||
|
||||
Ensure plugin is properly installed:
|
||||
|
||||
```bash
|
||||
/plugin list
|
||||
# Should show "steering-context-generator"
|
||||
|
||||
# Reinstall if needed
|
||||
/plugin uninstall steering-context-generator@aditi.code
|
||||
/plugin install steering-context-generator@aditi.code
|
||||
```
|
||||
|
||||
### Out of Memory
|
||||
|
||||
For very large codebases:
|
||||
|
||||
1. Disable parallel execution
|
||||
2. Run selective analysis
|
||||
3. Increase excluded patterns
|
||||
4. Use incremental approach
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Selective Analysis
|
||||
|
||||
Analyze only specific areas:
|
||||
|
||||
```json
|
||||
{
|
||||
"focus_areas": ["cms", "api"],
|
||||
"agents": ["payload-cms-detector", "api-design-analyst"]
|
||||
}
|
||||
```
|
||||
|
||||
### Multi-Project Analysis
|
||||
|
||||
Analyze multiple projects:
|
||||
|
||||
```bash
|
||||
# Project A
|
||||
cd /path/to/project-a
|
||||
/steering-generate
|
||||
|
||||
# Project B
|
||||
cd /path/to/project-b
|
||||
/steering-generate
|
||||
|
||||
# Compare
|
||||
diff .claude/steering/ARCHITECTURE.md ../project-a/.claude/steering/ARCHITECTURE.md
|
||||
```
|
||||
|
||||
## Performance Tips
|
||||
|
||||
**Faster Generation**:
|
||||
- ✅ Use parallel execution (enabled by default)
|
||||
- ✅ Exclude large generated directories
|
||||
- ✅ Use Haiku model for simple projects
|
||||
- ✅ Enable incremental updates
|
||||
|
||||
**Better Quality**:
|
||||
- ✅ Use Sonnet model (default)
|
||||
- ✅ Use Opus model for complex analysis
|
||||
- ✅ Provide clear focus areas
|
||||
- ✅ Review and refine outputs
|
||||
|
||||
## Success Metrics
|
||||
|
||||
Your generation is successful when:
|
||||
|
||||
- ✅ All expected files generated
|
||||
- ✅ Files are valid markdown
|
||||
- ✅ File sizes are reasonable (not empty, not too large)
|
||||
- ✅ Validation passes
|
||||
- ✅ Content is relevant and accurate
|
||||
|
||||
## Next Steps
|
||||
|
||||
After generation:
|
||||
|
||||
1. **Review Output**: `/steering-status`
|
||||
2. **Load Context**: Reference `.claude/steering/*.md` in AI prompts
|
||||
3. **Incremental Updates**: `/steering-update` when code changes
|
||||
4. **Export**: `/steering-export` for different formats
|
||||
5. **Clean Up**: `/steering-clean` to remove old archives
|
||||
|
||||
---
|
||||
|
||||
**Ready to generate?** Just run: `/steering-generate`
|
||||
|
||||
The system handles everything automatically!
|
||||
136
commands/steering-resume.md
Normal file
136
commands/steering-resume.md
Normal file
@@ -0,0 +1,136 @@
|
||||
---
|
||||
description: Resume an interrupted generation from the last checkpoint
|
||||
---
|
||||
|
||||
# Steering Context Generator - Resume
|
||||
|
||||
Continue a generation that was interrupted or failed.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
/steering-resume
|
||||
```
|
||||
|
||||
## When to Use
|
||||
|
||||
- ⚠ Generation was interrupted (Ctrl+C, timeout, crash)
|
||||
- ⚠ Agent execution failed mid-way
|
||||
- ⚠ System resources exhausted
|
||||
- ⚠ Network connectivity issues
|
||||
|
||||
## How It Works
|
||||
|
||||
### Checkpoint System
|
||||
|
||||
The system automatically saves checkpoints:
|
||||
|
||||
```
|
||||
.claude/memory/orchestration/
|
||||
├── current_session.json # Current execution state
|
||||
├── checkpoint_group1.json # After Group 1 completes
|
||||
├── checkpoint_group2.json # After Group 2 completes
|
||||
└── checkpoint_group3.json # After Group 3 completes
|
||||
```
|
||||
|
||||
### Resume Logic
|
||||
|
||||
```bash
|
||||
# Check for checkpoint
|
||||
if [ -f ".claude/memory/orchestration/current_session.json" ]; then
|
||||
PHASE=$(jq -r '.phase' .claude/memory/orchestration/current_session.json)
|
||||
STATUS=$(jq -r '.status' .claude/memory/orchestration/current_session.json)
|
||||
|
||||
if [ "$STATUS" == "running" ] || [ "$STATUS" == "failed" ]; then
|
||||
echo "Found interrupted session at phase: $PHASE"
|
||||
echo "Resuming from checkpoint..."
|
||||
|
||||
# Resume from last completed phase
|
||||
case $PHASE in
|
||||
"group1")
|
||||
# Restart Group 1 or skip if completed
|
||||
;;
|
||||
"group2")
|
||||
# Skip Group 1, resume Group 2
|
||||
;;
|
||||
"group3")
|
||||
# Skip Groups 1 & 2, resume Group 3
|
||||
;;
|
||||
"synthesis")
|
||||
# Run final synthesis only
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
## Expected Output
|
||||
|
||||
```
|
||||
🔄 Checking for interrupted session...
|
||||
|
||||
Found Session: gen_20251102_120000
|
||||
Status: interrupted
|
||||
Phase: group2 (60% complete)
|
||||
Last Activity: 2025-11-02 12:45:00
|
||||
|
||||
Agents Completed:
|
||||
✓ structure-analyst (Group 1)
|
||||
✓ integration-mapper (Group 1)
|
||||
✓ ui-specialist (Group 1)
|
||||
✓ domain-expert (Group 2)
|
||||
⏳ pattern-detective (Group 2) - INTERRUPTED
|
||||
|
||||
Resuming from Group 2...
|
||||
|
||||
────────────────────────────────────────
|
||||
|
||||
Phase 2/3: Deep Analysis (Resumed)
|
||||
✓ domain-expert: Already complete
|
||||
⏳ pattern-detective: Resuming analysis...
|
||||
⏳ test-strategist: Starting fresh...
|
||||
⏳ database-analyst: Starting fresh...
|
||||
|
||||
[Continue with normal execution...]
|
||||
```
|
||||
|
||||
## Manual Resume
|
||||
|
||||
If automatic resume fails:
|
||||
|
||||
```bash
|
||||
# Check what's completed
|
||||
ls .claude/memory/*/
|
||||
|
||||
# Manually continue with remaining agents
|
||||
# Use Task tool to invoke specific agents that didn't complete
|
||||
```
|
||||
|
||||
## Clearing Failed State
|
||||
|
||||
To start fresh (discard interrupted session):
|
||||
|
||||
```bash
|
||||
# Remove checkpoint
|
||||
rm .claude/memory/orchestration/current_session.json
|
||||
|
||||
# Run full generation
|
||||
/steering-generate
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "No checkpoint found"
|
||||
The session completed or never started. Run `/steering-generate`.
|
||||
|
||||
### Resume keeps failing
|
||||
Clear state and start fresh:
|
||||
```bash
|
||||
rm .claude/memory/orchestration/*.json
|
||||
/steering-setup
|
||||
/steering-generate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Recover from interruptions:** Run `/steering-resume`
|
||||
289
commands/steering-status.md
Normal file
289
commands/steering-status.md
Normal file
@@ -0,0 +1,289 @@
|
||||
---
|
||||
description: Check the status of Steering Context Generator installation, last generation, and generated files
|
||||
---
|
||||
|
||||
# Steering Context Generator - Status
|
||||
|
||||
View system status, generated files, and recommendations.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
/steering-status
|
||||
```
|
||||
|
||||
## Expected Output
|
||||
|
||||
```
|
||||
📊 Steering Context Generator - Status
|
||||
|
||||
═══════════════════════════════════════════════════════════
|
||||
|
||||
INSTALLATION
|
||||
Plugin Version: 1.0.0
|
||||
Installed: 2025-11-01 14:00:00
|
||||
Status: ✓ Ready
|
||||
|
||||
CONFIGURATION
|
||||
Config File: .claude/steering/config.json
|
||||
Parallel Execution: ✓ Enabled
|
||||
Incremental Updates: ✓ Enabled
|
||||
Output Format: markdown
|
||||
|
||||
LAST GENERATION
|
||||
Date: 2025-11-01 15:30:45 (1 day ago)
|
||||
Duration: 44 minutes
|
||||
Workflow: Standard (Moderate complexity)
|
||||
Agents: 7 executed
|
||||
Status: ✓ Complete
|
||||
|
||||
GENERATED FILES (.claude/steering/)
|
||||
✓ ARCHITECTURE.md 342 KB Fresh
|
||||
✓ AI_CONTEXT.md 156 KB Fresh
|
||||
✓ CODEBASE_GUIDE.md 278 KB Fresh
|
||||
✓ DOMAIN_CONTEXT.md 189 KB Fresh
|
||||
✓ QUALITY_REPORT.md 134 KB Fresh
|
||||
✓ TESTING_GUIDE.md 167 KB Fresh
|
||||
✓ UI_DESIGN_SYSTEM.md 203 KB Fresh
|
||||
|
||||
MEMORY USAGE
|
||||
Total: 1.2 MB
|
||||
Structure: 127 KB
|
||||
Domain: 189 KB
|
||||
Patterns: 98 KB
|
||||
Quality: 134 KB
|
||||
UI: 203 KB
|
||||
Testing: 167 KB
|
||||
Archives: 450 KB (2 previous runs)
|
||||
|
||||
CODEBASE STATUS
|
||||
Files Tracked: 387
|
||||
Last Change: 1 day ago (12 files modified)
|
||||
Tech Stack: Node.js/TypeScript, Next.js 14
|
||||
Complexity: Moderate
|
||||
|
||||
═══════════════════════════════════════════════════════════
|
||||
|
||||
RECOMMENDATIONS
|
||||
⚠ Context may be outdated (12 files changed)
|
||||
→ Run: /steering-update
|
||||
|
||||
💡 Archive size growing (450 KB)
|
||||
→ Run: /steering-clean
|
||||
|
||||
═══════════════════════════════════════════════════════════
|
||||
|
||||
QUICK ACTIONS
|
||||
/steering-update Update with latest changes
|
||||
/steering-generate Full regeneration
|
||||
/steering-clean Clean up archives
|
||||
/steering-export Export to other formats
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
echo "📊 Steering Context Generator - Status"
|
||||
echo ""
|
||||
echo "═══════════════════════════════════════════════════════════"
|
||||
echo ""
|
||||
|
||||
# Check installation
|
||||
if [ ! -f ".claude/steering/config.json" ]; then
|
||||
echo "❌ NOT INSTALLED"
|
||||
echo ""
|
||||
echo "Run: /steering-setup"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Plugin version
|
||||
echo "INSTALLATION"
|
||||
echo " Plugin Version: 1.0.0"
|
||||
if [ -f ".claude/memory/orchestration/state.json" ]; then
|
||||
INSTALLED=$(jq -r '.timestamp' .claude/memory/orchestration/state.json)
|
||||
echo " Installed: $INSTALLED"
|
||||
echo " Status: ✓ Ready"
|
||||
else
|
||||
echo " Status: ⚠ Incomplete setup"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Configuration
|
||||
echo "CONFIGURATION"
|
||||
echo " Config File: .claude/steering/config.json"
|
||||
PARALLEL=$(jq -r '.parallel_execution' .claude/steering/config.json)
|
||||
INCREMENTAL=$(jq -r '.incremental_updates' .claude/steering/config.json)
|
||||
FORMAT=$(jq -r '.output_format' .claude/steering/config.json)
|
||||
echo " Parallel Execution: $([ "$PARALLEL" == "true" ] && echo "✓ Enabled" || echo "✗ Disabled")"
|
||||
echo " Incremental Updates: $([ "$INCREMENTAL" == "true" ] && echo "✓ Enabled" || echo "✗ Disabled")"
|
||||
echo " Output Format: $FORMAT"
|
||||
echo ""
|
||||
|
||||
# Last generation
|
||||
echo "LAST GENERATION"
|
||||
if [ -f ".claude/memory/orchestration/state.json" ]; then
|
||||
LAST_RUN=$(jq -r '.last_run' .claude/memory/orchestration/state.json)
|
||||
if [ "$LAST_RUN" != "null" ]; then
|
||||
echo " Date: $LAST_RUN"
|
||||
echo " Status: ✓ Complete"
|
||||
else
|
||||
echo " Status: ⚠ Never run"
|
||||
echo " → Run: /steering-generate"
|
||||
fi
|
||||
else
|
||||
echo " Status: ⚠ No generation data"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Generated files
|
||||
echo "GENERATED FILES (.claude/steering/)"
|
||||
if [ -d ".claude/steering" ]; then
|
||||
for file in .claude/steering/*.md; do
|
||||
if [ -f "$file" ]; then
|
||||
BASENAME=$(basename "$file")
|
||||
SIZE=$(du -h "$file" | cut -f1)
|
||||
AGE=$(find "$file" -mtime -1 2>/dev/null && echo "Fresh" || echo "Stale")
|
||||
echo " ✓ $BASENAME$(printf '%*s' $((30-${#BASENAME})) '')$SIZE $AGE"
|
||||
fi
|
||||
done
|
||||
else
|
||||
echo " ⚠ No files generated"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Memory usage
|
||||
echo "MEMORY USAGE"
|
||||
if [ -d ".claude/memory" ]; then
|
||||
TOTAL=$(du -sh .claude 2>/dev/null | cut -f1)
|
||||
echo " Total: $TOTAL"
|
||||
else
|
||||
echo " No memory data"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Codebase status
|
||||
echo "CODEBASE STATUS"
|
||||
FILE_COUNT=$(find . -type f \
|
||||
-not -path "*/node_modules/*" \
|
||||
-not -path "*/.git/*" \
|
||||
-not -path "*/dist/*" \
|
||||
2>/dev/null | wc -l | tr -d ' ')
|
||||
echo " Files Tracked: $FILE_COUNT"
|
||||
|
||||
if git rev-parse --git-dir > /dev/null 2>&1; then
|
||||
LAST_COMMIT=$(git log -1 --format=%cd --date=relative)
|
||||
echo " Last Change: $LAST_COMMIT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
echo "═══════════════════════════════════════════════════════════"
|
||||
echo ""
|
||||
|
||||
# Recommendations
|
||||
echo "RECOMMENDATIONS"
|
||||
# Check if update needed
|
||||
if [ -f ".claude/steering/ARCHITECTURE.md" ]; then
|
||||
CHANGED=$(find . -newer .claude/steering/ARCHITECTURE.md -type f \
|
||||
-not -path "*/node_modules/*" \
|
||||
-not -path "*/.git/*" \
|
||||
2>/dev/null | wc -l | tr -d ' ')
|
||||
if [ "$CHANGED" -gt 10 ]; then
|
||||
echo " ⚠ Context may be outdated ($CHANGED files changed)"
|
||||
echo " → Run: /steering-update"
|
||||
echo ""
|
||||
fi
|
||||
fi
|
||||
|
||||
# Check archive size
|
||||
if [ -d ".claude/memory/archives" ]; then
|
||||
ARCHIVE_SIZE=$(du -sm .claude/memory/archives 2>/dev/null | cut -f1)
|
||||
if [ "$ARCHIVE_SIZE" -gt 100 ]; then
|
||||
echo " 💡 Archive size growing (${ARCHIVE_SIZE}MB)"
|
||||
echo " → Run: /steering-clean"
|
||||
echo ""
|
||||
fi
|
||||
fi
|
||||
|
||||
echo "═══════════════════════════════════════════════════════════"
|
||||
echo ""
|
||||
|
||||
echo "QUICK ACTIONS"
|
||||
echo " /steering-update Update with latest changes"
|
||||
echo " /steering-generate Full regeneration"
|
||||
echo " /steering-clean Clean up archives"
|
||||
echo " /steering-export Export to other formats"
|
||||
```
|
||||
|
||||
## Status Indicators
|
||||
|
||||
**Installation Status**:
|
||||
- ✓ Ready: Fully installed and configured
|
||||
- ⚠ Incomplete: Missing files or configuration
|
||||
- ❌ Not Installed: Run `/steering-setup`
|
||||
|
||||
**Generation Status**:
|
||||
- ✓ Complete: Successfully generated
|
||||
- ⏳ Running: Generation in progress
|
||||
- ⚠ Never run: No generation yet
|
||||
- ❌ Failed: Last generation failed
|
||||
|
||||
**File Freshness**:
|
||||
- Fresh: Modified within 24 hours
|
||||
- Stale: Modified >24 hours ago
|
||||
- Missing: Expected file not found
|
||||
|
||||
## Checking Specific Information
|
||||
|
||||
### Installation Details
|
||||
```bash
|
||||
cat .claude/steering/config.json | jq '.'
|
||||
```
|
||||
|
||||
### Generation History
|
||||
```bash
|
||||
cat .claude/memory/orchestration/state.json | jq '.'
|
||||
```
|
||||
|
||||
### Memory Breakdown
|
||||
```bash
|
||||
du -sh .claude/memory/*/ | sort -h
|
||||
```
|
||||
|
||||
### File Details
|
||||
```bash
|
||||
ls -lh .claude/steering/*.md
|
||||
```
|
||||
|
||||
### Agent Status
|
||||
```bash
|
||||
cat .claude/memory/orchestration/agents.json | jq '.agents'
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Not Installed" Message
|
||||
```bash
|
||||
/steering-setup
|
||||
```
|
||||
|
||||
### Missing Files
|
||||
```bash
|
||||
# Regenerate
|
||||
/steering-generate
|
||||
|
||||
# Or validate
|
||||
bash scripts/validate.sh
|
||||
```
|
||||
|
||||
### Incorrect Status
|
||||
```bash
|
||||
# Reset state
|
||||
rm .claude/memory/orchestration/state.json
|
||||
bash scripts/init.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Quick check:** Run `/steering-status` anytime!
|
||||
457
commands/steering-update.md
Normal file
457
commands/steering-update.md
Normal file
@@ -0,0 +1,457 @@
|
||||
---
|
||||
description: Incrementally update steering context based on code changes since last generation (80% faster than full regeneration)
|
||||
---
|
||||
|
||||
# Steering Context Generator - Incremental Update
|
||||
|
||||
Efficiently update your steering context documentation when code changes.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
/steering-update
|
||||
```
|
||||
|
||||
The system will:
|
||||
1. 🔍 Detect changed files since last generation
|
||||
2. 📊 Identify affected domains
|
||||
3. 🤖 Run only relevant agents
|
||||
4. 📝 Update specific documents
|
||||
5. ✅ Merge with existing context
|
||||
|
||||
## How It Works
|
||||
|
||||
### Change Detection
|
||||
|
||||
The system uses Git (if available) or file timestamps to detect changes:
|
||||
|
||||
```bash
|
||||
# Check last generation time
|
||||
LAST_GEN=$(jq -r '.last_run' .claude/memory/orchestration/state.json)
|
||||
|
||||
# Detect changes via Git
|
||||
git diff --name-only $LAST_GEN..HEAD
|
||||
|
||||
# Or via file timestamps
|
||||
find . -newer .claude/steering/ARCHITECTURE.md -type f
|
||||
```
|
||||
|
||||
### Domain Mapping
|
||||
|
||||
Changed files are mapped to affected domains:
|
||||
|
||||
| Files Changed | Affected Domains | Agents to Run |
|
||||
|---------------|------------------|---------------|
|
||||
| `*.tsx, *.jsx` | UI Components | `ui-specialist` |
|
||||
| `app/api/*.ts` | API Routes | `api-design-analyst` |
|
||||
| `prisma/schema.prisma` | Database | `database-analyst` |
|
||||
| `*.test.ts` | Testing | `test-strategist` |
|
||||
| `lib/events/*.ts` | Messaging | `messaging-architect` |
|
||||
|
||||
### Selective Agent Execution
|
||||
|
||||
Only affected agents run:
|
||||
|
||||
```
|
||||
Changes:
|
||||
✓ UI: 4 files modified
|
||||
✓ API: 6 files changed
|
||||
✓ Database: 2 schema updates
|
||||
|
||||
Running agents:
|
||||
⏳ ui-specialist (updating UI_DESIGN_SYSTEM.md)
|
||||
⏳ api-design-analyst (updating API_DESIGN_GUIDE.md)
|
||||
⏳ database-analyst (updating DATABASE_CONTEXT.md)
|
||||
```
|
||||
|
||||
### Document Merging
|
||||
|
||||
Updated sections are merged with existing documents:
|
||||
|
||||
```markdown
|
||||
Before:
|
||||
UI_DESIGN_SYSTEM.md (203 KB, 45 components)
|
||||
|
||||
Changes:
|
||||
+ 2 new components
|
||||
~ 3 modified components
|
||||
|
||||
After:
|
||||
UI_DESIGN_SYSTEM.md (237 KB, 47 components)
|
||||
```
|
||||
|
||||
## Execution Workflow
|
||||
|
||||
### Step 1: Detect Changes
|
||||
|
||||
```bash
|
||||
# Load last generation timestamp
|
||||
LAST_RUN=$(jq -r '.last_run' .claude/memory/orchestration/state.json)
|
||||
|
||||
if [ "$LAST_RUN" == "null" ]; then
|
||||
echo "❌ No previous generation found. Run /steering-generate first."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Detect changed files
|
||||
echo "🔍 Detecting changes since $LAST_RUN..."
|
||||
|
||||
if git rev-parse --git-dir > /dev/null 2>&1; then
|
||||
# Use Git if available
|
||||
CHANGED_FILES=$(git diff --name-only $LAST_RUN..HEAD)
|
||||
else
|
||||
# Use file timestamps
|
||||
CHANGED_FILES=$(find . -newer .claude/steering/ARCHITECTURE.md -type f \
|
||||
-not -path "*/node_modules/*" \
|
||||
-not -path "*/.git/*")
|
||||
fi
|
||||
|
||||
if [ -z "$CHANGED_FILES" ]; then
|
||||
echo "✓ No changes detected. Context is up-to-date."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo "Found $(echo "$CHANGED_FILES" | wc -l) changed files"
|
||||
```
|
||||
|
||||
### Step 2: Analyze Change Scope
|
||||
|
||||
```bash
|
||||
# Categorize changes
|
||||
UI_CHANGES=$(echo "$CHANGED_FILES" | grep -E '\.(tsx|jsx|css|scss)$' | wc -l)
|
||||
API_CHANGES=$(echo "$CHANGED_FILES" | grep -E 'api/.*\.(ts|js)$' | wc -l)
|
||||
DB_CHANGES=$(echo "$CHANGED_FILES" | grep -E '(schema|migration)' | wc -l)
|
||||
TEST_CHANGES=$(echo "$CHANGED_FILES" | grep -E '\.(test|spec)\.' | wc -l)
|
||||
|
||||
echo "Change analysis:"
|
||||
echo " UI components: $UI_CHANGES files"
|
||||
echo " API routes: $API_CHANGES files"
|
||||
echo " Database: $DB_CHANGES files"
|
||||
echo " Tests: $TEST_CHANGES files"
|
||||
```
|
||||
|
||||
### Step 3: Select Agents
|
||||
|
||||
```bash
|
||||
AGENTS_TO_RUN=()
|
||||
|
||||
if [ $UI_CHANGES -gt 0 ]; then
|
||||
AGENTS_TO_RUN+=("ui-specialist")
|
||||
fi
|
||||
|
||||
if [ $API_CHANGES -gt 0 ]; then
|
||||
AGENTS_TO_RUN+=("api-design-analyst")
|
||||
fi
|
||||
|
||||
if [ $DB_CHANGES -gt 0 ]; then
|
||||
AGENTS_TO_RUN+=("database-analyst")
|
||||
fi
|
||||
|
||||
if [ $TEST_CHANGES -gt 0 ]; then
|
||||
AGENTS_TO_RUN+=("test-strategist")
|
||||
fi
|
||||
|
||||
# Always run quality auditor for affected areas
|
||||
AGENTS_TO_RUN+=("quality-auditor")
|
||||
|
||||
echo "Selected agents: ${AGENTS_TO_RUN[@]}"
|
||||
```
|
||||
|
||||
### Step 4: Execute Agents in Parallel
|
||||
|
||||
Use the Task tool to run selected agents:
|
||||
|
||||
```markdown
|
||||
For UI changes - Invoke ui-specialist:
|
||||
Update UI_DESIGN_SYSTEM.md with new/modified components
|
||||
Focus only on changed files: $UI_CHANGED_FILES
|
||||
Merge with existing: .claude/memory/ui/
|
||||
|
||||
For API changes - Invoke api-design-analyst:
|
||||
Update API_DESIGN_GUIDE.md with new/modified endpoints
|
||||
Focus only on changed files: $API_CHANGED_FILES
|
||||
Merge with existing: .claude/memory/api-design/
|
||||
|
||||
For Database changes - Invoke database-analyst:
|
||||
Update DATABASE_CONTEXT.md with schema changes
|
||||
Focus only on migrations/schema: $DB_CHANGED_FILES
|
||||
Merge with existing: .claude/memory/database/
|
||||
|
||||
For Test changes - Invoke test-strategist:
|
||||
Update TESTING_GUIDE.md with new test patterns
|
||||
Focus only on changed tests: $TEST_CHANGED_FILES
|
||||
Merge with existing: .claude/memory/testing/
|
||||
```
|
||||
|
||||
### Step 5: Validate and Merge
|
||||
|
||||
```bash
|
||||
# Validate updated documents
|
||||
bash scripts/validate.sh
|
||||
|
||||
# Update architecture document with changes
|
||||
# (context-synthesizer runs lightweight merge)
|
||||
|
||||
# Update state
|
||||
cat > .claude/memory/orchestration/state.json << EOF
|
||||
{
|
||||
"phase": "ready",
|
||||
"timestamp": "$(date -Iseconds)",
|
||||
"initialized": true,
|
||||
"last_run": "$(date -Iseconds)",
|
||||
"last_update": "$(date -Iseconds)",
|
||||
"agents_status": {
|
||||
$(for agent in "${AGENTS_TO_RUN[@]}"; do
|
||||
echo "\"$agent\": \"updated\","
|
||||
done | sed '$ s/,$//')
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
### Step 6: Display Summary
|
||||
|
||||
```bash
|
||||
echo "✅ Update complete!"
|
||||
echo ""
|
||||
echo "Updated Files:"
|
||||
for agent in "${AGENTS_TO_RUN[@]}"; do
|
||||
case $agent in
|
||||
ui-specialist)
|
||||
echo " ↻ UI_DESIGN_SYSTEM.md (+${UI_CHANGES} changes)"
|
||||
;;
|
||||
api-design-analyst)
|
||||
echo " ↻ API_DESIGN_GUIDE.md (+${API_CHANGES} changes)"
|
||||
;;
|
||||
database-analyst)
|
||||
echo " ↻ DATABASE_CONTEXT.md (+${DB_CHANGES} changes)"
|
||||
;;
|
||||
test-strategist)
|
||||
echo " ↻ TESTING_GUIDE.md (+${TEST_CHANGES} changes)"
|
||||
;;
|
||||
quality-auditor)
|
||||
echo " ↻ QUALITY_REPORT.md (revalidated)"
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "Time saved vs full regeneration: ~$(echo "$((45 - 8))" minutes)"
|
||||
echo "Tokens used: ~18,000 (vs ~145,000 full)"
|
||||
```
|
||||
|
||||
## Expected Output
|
||||
|
||||
```
|
||||
🔄 Checking for changes since last generation...
|
||||
|
||||
Last Generated: 2025-11-01 15:30:45 (1 day ago)
|
||||
|
||||
Changes Detected (git diff):
|
||||
Modified: 12 files
|
||||
Added: 3 files
|
||||
Deleted: 1 file
|
||||
|
||||
Change Analysis:
|
||||
UI components: 4 files
|
||||
API routes: 6 files
|
||||
Database schema: 2 files
|
||||
|
||||
Selected Agents:
|
||||
✓ ui-specialist
|
||||
✓ api-design-analyst
|
||||
✓ database-analyst
|
||||
✓ quality-auditor
|
||||
|
||||
────────────────────────────────────────
|
||||
|
||||
Running Incremental Analysis:
|
||||
⏳ ui-specialist: Updating UI_DESIGN_SYSTEM.md...
|
||||
⏳ api-design-analyst: Updating API_DESIGN_GUIDE.md...
|
||||
⏳ database-analyst: Updating DATABASE_CONTEXT.md...
|
||||
⏳ quality-auditor: Revalidating affected areas...
|
||||
|
||||
────────────────────────────────────────
|
||||
|
||||
✅ Update complete! (8 minutes)
|
||||
|
||||
Updated Files:
|
||||
↻ UI_DESIGN_SYSTEM.md (+34 KB, 2 new components)
|
||||
↻ API_DESIGN_GUIDE.md (+12 KB, 3 endpoints modified)
|
||||
↻ DATABASE_CONTEXT.md (+8 KB, 1 table added)
|
||||
✓ ARCHITECTURE.md (revalidated)
|
||||
✓ QUALITY_REPORT.md (revalidated)
|
||||
|
||||
Performance:
|
||||
Time: 8 minutes (vs 45 full)
|
||||
Time saved: 37 minutes (82% faster)
|
||||
Tokens: ~18,000 (vs ~145,000 full)
|
||||
Efficiency: 87% token savings
|
||||
|
||||
Next Steps:
|
||||
/steering-status - View updated context
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Update Threshold
|
||||
|
||||
Set minimum changes to trigger update:
|
||||
|
||||
```json
|
||||
// .claude/steering/config.json
|
||||
{
|
||||
"update_threshold": 5 // Minimum files changed
|
||||
}
|
||||
```
|
||||
|
||||
### Force Full Regeneration
|
||||
|
||||
Skip incremental and force full regeneration:
|
||||
|
||||
```bash
|
||||
/steering-generate --force
|
||||
```
|
||||
|
||||
### Selective Update
|
||||
|
||||
Update only specific domains:
|
||||
|
||||
```bash
|
||||
# Update only UI (not yet implemented - use config)
|
||||
{
|
||||
"update_domains": ["ui"]
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "No changes detected" but files changed
|
||||
|
||||
**Causes**:
|
||||
1. Files in excluded patterns
|
||||
2. Git not tracking changes
|
||||
3. Files outside analysis scope
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check excluded patterns
|
||||
cat .claude/steering/config.json | jq '.excluded_patterns'
|
||||
|
||||
# Force full regeneration
|
||||
/steering-generate --force
|
||||
|
||||
# Update excluded patterns if needed
|
||||
```
|
||||
|
||||
### Merge conflicts
|
||||
|
||||
If updates conflict with manual edits:
|
||||
|
||||
**Option 1**: Backup and regenerate
|
||||
```bash
|
||||
cp .claude/steering/ARCHITECTURE.md .claude/steering/ARCHITECTURE.md.backup
|
||||
/steering-update
|
||||
# Manually merge if needed
|
||||
```
|
||||
|
||||
**Option 2**: Force full regeneration
|
||||
```bash
|
||||
/steering-generate --force
|
||||
```
|
||||
|
||||
### Agent execution fails
|
||||
|
||||
Check agent status:
|
||||
```bash
|
||||
cat .claude/memory/orchestration/state.json | jq '.agents_status'
|
||||
```
|
||||
|
||||
Retry specific agent:
|
||||
```bash
|
||||
# Run agent manually with Task tool
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
**When to Use Update**:
|
||||
- ✅ Small to medium changes (<20% of files)
|
||||
- ✅ Focused changes in specific domains
|
||||
- ✅ Regular maintenance updates
|
||||
- ✅ After feature additions
|
||||
|
||||
**When to Use Full Regeneration**:
|
||||
- ✅ Major refactoring (>20% of files)
|
||||
- ✅ Architecture changes
|
||||
- ✅ First-time generation
|
||||
- ✅ After long periods without updates
|
||||
|
||||
**Update Frequency**:
|
||||
- Daily: For active development
|
||||
- Weekly: For stable projects
|
||||
- After features: After completing features
|
||||
- Before releases: Ensure docs current
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Automated Updates
|
||||
|
||||
Set up Git hooks for automatic updates:
|
||||
|
||||
```bash
|
||||
# .git/hooks/post-commit
|
||||
#!/bin/bash
|
||||
if [ -f ".claude/steering/config.json" ]; then
|
||||
/steering-update
|
||||
fi
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
Add to CI pipeline:
|
||||
|
||||
```yaml
|
||||
# .github/workflows/update-context.yml
|
||||
name: Update Steering Context
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
jobs:
|
||||
update:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Update Context
|
||||
run: claude /steering-update
|
||||
```
|
||||
|
||||
### Diff Analysis
|
||||
|
||||
Compare before/after:
|
||||
|
||||
```bash
|
||||
# Before update
|
||||
cp .claude/steering/ARCHITECTURE.md /tmp/arch-before.md
|
||||
|
||||
# Run update
|
||||
/steering-update
|
||||
|
||||
# Compare
|
||||
diff /tmp/arch-before.md .claude/steering/ARCHITECTURE.md
|
||||
```
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
Typical incremental update performance:
|
||||
|
||||
| Changes | Time | Tokens | vs Full |
|
||||
|---------|------|--------|---------|
|
||||
| 1-5 files | 3-5 min | 5K | 90% faster |
|
||||
| 6-15 files | 5-8 min | 15K | 82% faster |
|
||||
| 16-30 files | 8-12 min | 25K | 73% faster |
|
||||
| 31-50 files | 12-20 min | 40K | 56% faster |
|
||||
| 50+ files | Consider full regeneration | - | - |
|
||||
|
||||
---
|
||||
|
||||
**Keep your context fresh:** Run `/steering-update` regularly!
|
||||
Reference in New Issue
Block a user