433 lines
13 KiB
Markdown
433 lines
13 KiB
Markdown
---
|
|
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!
|