project-standalo-sonic-cloud/.claude/commands/guardrail/analyze.md

description	allowed-tools
Analyze codebase and generate project manifest from existing code	Read, Write, Bash, Glob, Grep, Task, AskUserQuestion

Analyze Codebase and Generate Manifest

Analyze the current codebase and generate all files needed for the guardrail workflow system.

Arguments

• $ARGUMENTS - Optional flags:
  • --force - Overwrite existing manifest without asking
  • --dry-run - Preview manifest without writing
  • --deep - Use AI agent for deeper analysis
  • <name> - Custom project name

Generated Files

This command creates:

1. project_manifest.json - Entity definitions and dependencies
2. .workflow/index.yml - Version tracking index
3. .workflow/versions/ - Directory for version snapshots

Quick Execution (Default)

Step 1: Run the Python analyzer script

python3 skills/guardrail-orchestrator/scripts/analyze_codebase.py --path . $ARGUMENTS

If the script succeeds, continue to Step 2.

Step 2: Initialize Workflow Directory Structure [MANDATORY]

# Create workflow directory structure
mkdir -p .workflow/versions

# Create index.yml if it doesn't exist
if [ ! -f .workflow/index.yml ]; then
  cat > .workflow/index.yml << 'EOF'
versions: []
latest_version: null
total_versions: 0
EOF
  echo "Created .workflow/index.yml"
fi

Step 3: Display Summary

╔══════════════════════════════════════════════════════════════╗
║ ✅ GUARDRAIL INITIALIZED                                     ║
╠══════════════════════════════════════════════════════════════╣
║ Files Created:                                               ║
║   ✓ project_manifest.json                                    ║
║   ✓ .workflow/index.yml                                      ║
║   ✓ .workflow/versions/                                      ║
╠══════════════════════════════════════════════════════════════╣
║ Ready to use:                                                ║
║   /workflow:spawn <feature>     Start a new feature          ║
║   /guardrail:status             Check project status         ║
╚══════════════════════════════════════════════════════════════╝

Deep Analysis Mode (--deep flag)

Use the Task tool to spawn an Explore agent for comprehensive codebase analysis

Use Task tool with: subagent_type: "Explore" prompt: | Analyze this codebase thoroughly and return structured information about:

1. **Pages** (Next.js App Router):
   - Find all page.tsx files in app/ directory
   - Extract route paths from file locations
   - Identify components imported/used
   - Identify API dependencies (fetch calls)

2. **Components**:
   - Find all .tsx files in app/components/
   - Extract component names and exports
   - Extract prop interfaces/types
   - Identify child component dependencies

3. **API Routes**:
   - Find all route.ts files in app/api/
   - Extract HTTP methods (GET, POST, PUT, DELETE, PATCH)
   - Identify request/response types
   - Extract path parameters

4. **Database/Types**:
   - Find type definitions in app/lib/
   - Extract interfaces and type aliases
   - Identify database schemas/tables

5. **Dependencies**:
   - Which components are used by which pages
   - Which APIs are called by which components
   - Which database tables are used by which APIs

Return the analysis as structured JSON sections.

Phase 2: Generate Manifest

Based on the analysis, create project_manifest.json with this structure:

{
  "project": {
    "name": "<project-name>",
    "version": "1.0.0",
    "created_at": "<ISO timestamp>",
    "description": "<inferred from package.json or README>"
  },
  "state": {
    "current_phase": "IMPLEMENTATION_PHASE",
    "approval_status": {
      "manifest_approved": true,
      "approved_by": "analyzer",
      "approved_at": "<ISO timestamp>"
    },
    "revision_history": [
      {
        "action": "MANIFEST_GENERATED",
        "timestamp": "<ISO timestamp>",
        "details": "Generated from existing codebase analysis"
      }
    ]
  },
  "entities": {
    "pages": [
      {
        "id": "page_<name>",
        "path": "/<route>",
        "file_path": "app/<path>/page.tsx",
        "status": "IMPLEMENTED",
        "description": "<inferred>",
        "components": ["comp_<name>", ...],
        "data_dependencies": ["api_<name>", ...]
      }
    ],
    "components": [
      {
        "id": "comp_<name>",
        "name": "<ComponentName>",
        "file_path": "app/components/<Name>.tsx",
        "status": "IMPLEMENTED",
        "description": "<inferred from component>",
        "props": {
          "<propName>": {
            "type": "<type>",
            "optional": true|false,
            "description": "<if available>"
          }
        }
      }
    ],
    "api_endpoints": [
      {
        "id": "api_<action>_<resource>",
        "path": "/api/<path>",
        "method": "GET|POST|PUT|DELETE|PATCH",
        "file_path": "app/api/<path>/route.ts",
        "status": "IMPLEMENTED",
        "description": "<inferred>",
        "request": {
          "params": {},
          "query": {},
          "body": {}
        },
        "response": {
          "type": "<type>",
          "description": "<description>"
        }
      }
    ],
    "database_tables": [
      {
        "id": "table_<name>",
        "name": "<tableName>",
        "file_path": "app/lib/db.ts",
        "status": "IMPLEMENTED",
        "description": "<description>",
        "columns": {}
      }
    ]
  },
  "dependencies": {
    "component_to_page": {},
    "api_to_component": {},
    "table_to_api": {}
  },
  "types": {}
}

Phase 3: Entity Naming Conventions

Use these ID formats:

• Pages: page_<name> (e.g., page_home, page_tasks, page_task_detail)
• Components: comp_<snake_case> (e.g., comp_task_list, comp_filter_bar)
• APIs: api_<action>_<resource> (e.g., api_list_tasks, api_create_task)
• Tables: table_<name> (e.g., table_tasks, table_users)

Phase 4: Write Manifest

1. Write the generated manifest to project_manifest.json
2. Validate JSON syntax
3. Display summary:

╔══════════════════════════════════════════════════════════════╗
║              📊 MANIFEST GENERATED                            ║
╠══════════════════════════════════════════════════════════════╣
║ Project: <name>                                               ║
║ Generated: <timestamp>                                        ║
╠══════════════════════════════════════════════════════════════╣
║ ENTITIES DISCOVERED                                           ║
║   📄 Pages:      X                                            ║
║   🧩 Components: X                                            ║
║   🔌 APIs:       X                                            ║
║   🗄️  Tables:     X                                            ║
╠══════════════════════════════════════════════════════════════╣
║ Status: All entities marked as IMPLEMENTED                    ║
║ Phase:  IMPLEMENTATION_PHASE                                  ║
╚══════════════════════════════════════════════════════════════╝

Options

If manifest already exists, ask user:

1. Overwrite - Replace existing manifest
2. Merge - Add new entities, keep existing
3. Cancel - Abort operation

Notes

• All discovered entities are marked as IMPLEMENTED since they already exist
• Project starts in IMPLEMENTATION_PHASE since code exists
• Use this command to bring existing projects under guardrail management
• After generation, use /guardrail:validate to verify manifest accuracy