Initial commit
This commit is contained in:
Zhongwei Li
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!
|
||||
Reference in New Issue
Block a user