zhongwei/gh-varaku1012-aditi-code-plugins-steering-context-generator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d7ebdd481993a37db53e7805bf1ce5c62377ff8f
gh-varaku1012-aditi-code-pl…/commands/steering-generate.md
Zhongwei Li d7ebdd4819 Initial commit
2025-11-30 09:04:23 +08:00

13 KiB
Raw Blame History

description
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

/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:

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

# 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:

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

# 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:

{
  "focus_areas": ["architecture", "security", "performance"]
}

Excluded Patterns

Skip certain files/directories:

{
  "excluded_patterns": [
    "node_modules/**",
    ".git/**",
    "dist/**",
    "*.test.ts"
  ]
}

Parallel Execution

Disable parallel execution if needed:

{
  "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:

# Check for checkpoint
ls .claude/memory/orchestration/current_session.json

# Resume from checkpoint
/steering-resume

Agents Not Found

Ensure plugin is properly installed:

/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:

{
  "focus_areas": ["cms", "api"],
  "agents": ["payload-cms-detector", "api-design-analyst"]
}

Multi-Project Analysis

Analyze multiple projects:

# 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 View Git Blame Copy Permalink