244 lines
8.7 KiB
Markdown
244 lines
8.7 KiB
Markdown
---
|
|
description: Analyze codebase and generate project manifest from existing code
|
|
allowed-tools: 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
|
|
```bash
|
|
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]
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"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
|