ai-apps
/
project-standalo-sonic-cloud
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Initial commit for Eureka deployment

This commit is contained in:
mazemaze 2025-12-18 14:30:03 +09:00
parent 946e0d94a0
commit 1a39be31ee
77 changed files with 23417 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
.claude/commands/eureka/deploy-flow.md Normal file
View File

@ -0,0 +1,70 @@
# Eureka Deploy Flow Agent
You are an autonomous deployment agent for the Eureka platform. Execute the complete deployment workflow.
## Workflow Steps
Execute these steps in order:
### Step 1: Check Git Status
```bash
git status
git branch --show-current
```
- Identify current branch
- Check for uncommitted changes
- Check for untracked files
### Step 2: Stage Changes
If there are changes to commit:
```bash
git add -A
```
### Step 3: Commit Changes
If there are staged changes:
```bash
git commit -m "Deploy: $(date +%Y-%m-%d_%H:%M:%S)"
```
Use a descriptive commit message if the user provided context.
### Step 4: Push to Eureka Remote
```bash
git push eureka $(git branch --show-current)
```
If push fails, try:
```bash
git push -u eureka $(git branch --show-current)
```
### Step 5: Trigger Deployment
```bash
eureka deploy trigger --yes
```
### Step 6: Monitor Status
```bash
eureka deploy status
```
Wait a few seconds and check status again if still building.
## Error Handling
- **No eureka remote**: Run `eureka init` first
- **Push rejected**: Check if remote has changes, pull first if needed
- **Deploy failed**: Check `eureka deploy logs` for details
- **No app_id**: Run `eureka setup` to configure
## Success Criteria
- All changes committed and pushed
- Deployment triggered successfully
- Status shows "building" or "deployed"
## Output
Report:
1. Files changed/committed
2. Push result
3. Deployment status
4. Deployed URL (when available)

63
.claude/commands/eureka/deploy-logs.md Normal file
View File

@ -0,0 +1,63 @@
---
description: View deployment logs from Eureka platform
allowed-tools: Read, Bash, Glob
---
# Eureka Deploy Logs
**Input**: "$ARGUMENTS"
---
## PURPOSE
View the deployment logs from the Eureka platform to debug issues or monitor progress.
---
## EXECUTION FLOW
### ═══════════════════════════════════════════════════════════════
### PHASE 1: Fetch Logs
### ═══════════════════════════════════════════════════════════════
#### 1.1: Run Logs Command
```bash
# Default: last 100 lines
eureka deploy logs
# Custom tail count
eureka deploy logs --tail 200
```
#### 1.2: Parse Arguments
If `$ARGUMENTS` contains a number, use it as tail count:
```bash
TAIL_COUNT="${ARGUMENTS:-100}"
eureka deploy logs --tail "$TAIL_COUNT"
```
---
## ARGUMENTS
| Argument | Default | Description |
|----------|---------|-------------|
| `[tail]` | `100` | Number of log lines to show |
| `--id <deploymentId>` | Latest | Specific deployment ID |
| `--follow` | `false` | Follow logs in real-time |
## EXAMPLES
```bash
# View last 100 lines
/eureka:deploy-logs
# View last 500 lines
/eureka:deploy-logs 500
# View specific deployment
/eureka:deploy-logs --id dep_abc123
```

55
.claude/commands/eureka/deploy-status.md Normal file
View File

@ -0,0 +1,55 @@
---
description: Check deployment status on Eureka platform
allowed-tools: Read, Bash, Glob
---
# Eureka Deploy Status
**Input**: "$ARGUMENTS"
---
## PURPOSE
Check the current deployment status of the application on the Eureka platform.
---
## EXECUTION FLOW
### ═══════════════════════════════════════════════════════════════
### PHASE 1: Check Status
### ═══════════════════════════════════════════════════════════════
#### 1.1: Run Status Command
```bash
eureka deploy status --verbose
```
#### 1.2: Display Results
The command will show:
- Current deployment status (pending, building, deploying, deployed, failed)
- Version information
- Environment
- Timestamps
- Deployment URL (if deployed)
---
## ARGUMENTS
| Argument | Default | Description |
|----------|---------|-------------|
| `--verbose` | `false` | Show detailed logs |
## EXAMPLES
```bash
# Check current deployment status
/eureka:deploy-status
# Check with verbose output
/eureka:deploy-status --verbose
```

279
.claude/commands/eureka/deploy.md Normal file
View File

@ -0,0 +1,279 @@
---
description: Deploy application to Eureka platform (creates app if needed)
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---
# Eureka Deploy
**Input**: "$ARGUMENTS"
---
## PURPOSE
Deploy the current project to the Eureka platform. If no `app_id` is configured, automatically creates a new directory app first, then triggers the deployment.
---
## ⛔ CRITICAL RULES
### MUST DO
1. **MUST** check for existing `app_id` in `.claude/eureka-factory.yaml` first
2. **MUST** create a new app via API if no `app_id` exists
3. **MUST** save the new `app_id` to config after creation
4. **MUST** display deployment status after triggering
### CANNOT DO
1. **CANNOT** deploy without valid API key
2. **CANNOT** skip app creation if `app_id` is missing
3. **CANNOT** proceed if API calls fail
---
## EXECUTION FLOW
### ═══════════════════════════════════════════════════════════════
### PHASE 1: Configuration Check
### ═══════════════════════════════════════════════════════════════
#### 1.1: Display Start Banner
```
╔══════════════════════════════════════════════════════════════╗
║ 🚀 EUREKA DEPLOY ║
╠══════════════════════════════════════════════════════════════╣
║ Deploying to Eureka Platform... ║
╚══════════════════════════════════════════════════════════════╝
```
#### 1.2: Check Configuration
Read the configuration file:
```bash
# Check if config exists
cat .claude/eureka-factory.yaml 2>/dev/null || cat .claude/eureka-factory.yml 2>/dev/null || echo "NO_CONFIG"
```
**Extract from config:**
- `api_key` - Required for all operations
- `app_id` - If exists, skip app creation
- `api_endpoint` - Optional custom endpoint
#### 1.3: Validate API Key
If no `api_key` found:
```
╔══════════════════════════════════════════════════════════════╗
║ ❌ NO API KEY CONFIGURED ║
╠══════════════════════════════════════════════════════════════╣
║ Run `eureka setup` to configure your credentials. ║
╚══════════════════════════════════════════════════════════════╝
```
**STOP EXECUTION**
---
### ═══════════════════════════════════════════════════════════════
### PHASE 2: App Creation (if needed)
### ═══════════════════════════════════════════════════════════════
#### 2.1: Check for app_id
If `app_id` exists in config → **SKIP TO PHASE 3**
If `app_id` is missing:
```
╔══════════════════════════════════════════════════════════════╗
║ 📁 CREATING DIRECTORY APP ║
╠══════════════════════════════════════════════════════════════╣
║ No app_id found. Creating new app on Eureka... ║
╚══════════════════════════════════════════════════════════════╝
```
#### 2.2: Determine App Name
Use the project directory name as the default app name:
```bash
APP_NAME=$(basename $(pwd))
echo "App name: $APP_NAME"
```
Or use argument if provided: `$ARGUMENTS` as app name
#### 2.3: Create App via API
```bash
# Create app using eureka CLI
eureka deploy trigger --name "$APP_NAME" --type other --yes
```
**If the command is not available, use direct API call:**
```bash
API_KEY="<from config>"
API_ENDPOINT="<from config or default>"
curl -X POST "${API_ENDPOINT}/v1/apps" \
-H "Content-Type: application/json" \
-H "X-API-Key: ${API_KEY}" \
-d "{\"name\": \"${APP_NAME}\", \"type\": \"other\"}"
```
#### 2.4: Save app_id to Config
Extract `app_id` from API response and update config:
```yaml
# .claude/eureka-factory.yaml
api_key: <existing>
project_id: <existing>
repo_id: <existing>
app_id: <NEW_APP_ID> # Add this line
```
```
╔══════════════════════════════════════════════════════════════╗
║ ✅ APP CREATED ║
╠══════════════════════════════════════════════════════════════╣
║ App ID: <app_id> ║
║ Saved to: .claude/eureka-factory.yaml ║
╚══════════════════════════════════════════════════════════════╝
```
---
### ═══════════════════════════════════════════════════════════════
### PHASE 3: Trigger Deployment
### ═══════════════════════════════════════════════════════════════
#### 3.1: Trigger Deploy
```bash
# Using eureka CLI
eureka deploy trigger --yes
# Or direct API call
curl -X POST "${API_ENDPOINT}/v1/apps/${APP_ID}/deployments" \
-H "Content-Type: application/json" \
-H "X-API-Key: ${API_KEY}" \
-d '{"environment": "production"}'
```
#### 3.2: Display Deployment Status
```
╔══════════════════════════════════════════════════════════════╗
║ ✅ DEPLOYMENT TRIGGERED ║
╠══════════════════════════════════════════════════════════════╣
║ Deployment ID: <deployment_id> ║
║ Status: PENDING ║
║ Environment: production ║
║ Version: <version> ║
╠══════════════════════════════════════════════════════════════╣
║ Use `/eureka:deploy-status` to check progress ║
║ Use `/eureka:deploy-logs` to view logs ║
╚══════════════════════════════════════════════════════════════╝
```
---
## ARGUMENTS
| Argument | Default | Description |
|----------|---------|-------------|
| `[app-name]` | Directory name | Name for new app (only used if creating) |
| `--env <environment>` | `production` | Deployment environment |
| `--branch <branch>` | Current branch | Git branch to deploy |
| `--force` | `false` | Force deploy even if already deploying |
## EXAMPLES
```bash
# Deploy current project (creates app if needed)
/eureka:deploy
# Deploy with custom app name
/eureka:deploy my-awesome-app
# Deploy specific branch to staging
/eureka:deploy --env staging --branch develop
# Force redeploy
/eureka:deploy --force
```
---
## ERROR HANDLING
### No Configuration
```
❌ No configuration found.
Run `eureka setup` to configure credentials.
```
### App Creation Failed
```
❌ Failed to create app: <error message>
Check your API key and try again.
```
### Deployment Failed
```
❌ Deployment failed: <error message>
Use `/eureka:deploy-logs` to see details.
```
---
## FLOW DIAGRAM
```
┌─────────────────────────────────────────────────────────────────┐
│ /eureka:deploy │
├─────────────────────────────────────────────────────────────────┤
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Check Config │ │
│ └────────┬────────┘ │
│ │ │
│ ┌─────────▼─────────┐ │
│ │ Has API Key? │ │
│ └─────────┬─────────┘ │
│ │ │
│ NO │ YES │
│ ┌────────────────────┼────────────────────┐ │
│ ▼ ▼ │
│ ┌───────────┐ ┌─────────────────┐ │
│ │ ERROR │ │ Has app_id? │ │
│ │ No Key │ └────────┬────────┘ │
│ └───────────┘ │ │
│ NO │ YES │
│ ┌───────────────────┼──────────┐ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌──────────────┐
│ │ Create App │ │ │
│ │ via API │ │ │
│ └────────┬────────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────────┐ │ │
│ │ Save app_id │ │ │
│ │ to Config │ │ │
│ └────────┬────────┘ │ │
│ │ │ │
│ └───────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Trigger Deploy │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Show Status │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

595
.claude/commands/eureka/index.md Normal file
View File

@ -0,0 +1,595 @@
---
description: Generate comprehensive project documentation for engineers and non-engineers
allowed-tools: Read, Write, Edit, Bash, Task, TodoWrite, Glob, Grep
---
# Eureka Index - Project Documentation Generator
**Input**: "$ARGUMENTS"
---
## PURPOSE
Generate comprehensive, dual-audience documentation by analyzing the current project structure using **parallel agent execution**. The output is designed to be understandable for **both engineers and non-engineers**.
### Documentation Layers
| Layer | Audience | Content |
|-------|----------|---------|
| Executive Summary | Everyone | Project purpose, value, capabilities |
| Architecture Overview | Everyone | Visual diagrams, technology stack |
| Getting Started | Semi-technical | Setup, basic usage, configuration |
| Feature Guide | Non-engineers | Plain-language feature descriptions |
| API Reference | Engineers | Endpoints, schemas, authentication |
| Component Catalog | Engineers | Props, interfaces, usage examples |
| Data Models | Both | ER diagrams + plain descriptions |
| Glossary | Non-engineers | Technical terms explained |
---
## EXECUTION ARCHITECTURE
```
┌─────────────────────────────────────────────────────────────────────┐
│ PARALLEL EXECUTION PIPELINE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ PHASE 1: PARALLEL ANALYSIS (run_in_background: true) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Structure │ │ API │ │ Components │ │ Models │ │
│ │ Analyzer │ │ Analyzer │ │ Analyzer │ │ Analyzer │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └─────┬──────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ PHASE 2: SYNCHRONIZATION │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Merge & Create Unified Analysis │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ PHASE 3: PARALLEL DOCUMENTATION (run_in_background: true) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Main Doc │ │ API Docs │ │ Components │ │ Quick │ │
│ │ Generator │ │ Generator │ │ Generator │ │ Reference │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └─────┬──────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ PHASE 4: FINALIZATION │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ HTML Generation + Validation + Summary │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## ⛔ CRITICAL RULES
### MUST DO
1. **MUST** launch analysis agents in parallel using `run_in_background: true`
2. **MUST** wait for all analysis agents before synchronization
3. **MUST** launch documentation agents in parallel after synchronization
4. **MUST** include both technical and non-technical descriptions
5. **MUST** validate generated documentation against actual code
### CANNOT DO
1. **CANNOT** make up features that don't exist
2. **CANNOT** skip the parallel analysis phase
3. **CANNOT** generate docs without synchronizing analysis results
---
## EXECUTION FLOW
### ═══════════════════════════════════════════════════════════════
### PHASE 1: Parallel Analysis
### ═══════════════════════════════════════════════════════════════
#### 1.1: Display Start Banner & Setup
```
╔══════════════════════════════════════════════════════════════╗
║ 📚 EUREKA INDEX - Parallel Documentation Generator ║
╠══════════════════════════════════════════════════════════════╣
║ Launching parallel analysis agents... ║
║ Output: Dual-audience documentation (Engineer + Non-Engineer)║
╚══════════════════════════════════════════════════════════════╝
```
```bash
OUTPUT_DIR="${ARGUMENTS:-docs}"
mkdir -p "$OUTPUT_DIR"
echo "📁 Output directory: $OUTPUT_DIR"
```
#### 1.2: Launch Parallel Analysis Agents
**CRITICAL: Launch ALL four agents in a SINGLE message with multiple Task tool calls:**
```
Launch these 4 Task agents IN PARALLEL (single message, multiple tool calls):
┌─────────────────────────────────────────────────────────────────┐
│ AGENT 1: Structure Analyzer │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "Explore" │
│ run_in_background: true │
│ prompt: | │
│ # PROJECT STRUCTURE ANALYSIS │
│ │
│ Analyze the project structure and return findings. │
│ │
│ ## Tasks │
│ 1. Identify project type (package.json, requirements.txt, │
│ Cargo.toml, go.mod, pom.xml) │
│ 2. Extract metadata (name, version, description) │
│ 3. Map directory structure with purposes │
│ 4. Identify tech stack (language, framework, database) │
│ 5. List key dependencies with plain English purposes │
│ │
│ ## Output Format (YAML) │
│ ```yaml │
│ project: │
│ name: "..." │
│ version: "..." │
│ description: "..." │
│ type: "node|python|rust|go|java|other" │
│ tech_stack: │
│ language: "..." │
│ framework: "..." │
│ database: "..." │
│ structure: │
│ directories: │
│ - path: "..." │
│ purpose: "..." │
│ file_count: N │
│ dependencies: │
│ - name: "..." │
│ purpose: "plain English" │
│ ``` │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ AGENT 2: API Analyzer │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "Explore" │
│ run_in_background: true │
│ prompt: | │
│ # API ENDPOINTS ANALYSIS │
│ │
│ Find and analyze all API endpoints in the project. │
│ │
│ ## Search Patterns │
│ - Next.js App Router: app/api/**/route.ts │
│ - Next.js Pages: pages/api/**/*.ts │
│ - Express: router.get/post/put/delete │
│ - FastAPI: @app.get/post/put/delete │
│ - GraphQL: Query/Mutation resolvers │
│ │
│ ## Output Format (YAML) │
│ ```yaml │
│ api_endpoints: │
│ - method: "GET|POST|PUT|DELETE" │
│ path: "/api/..." │
│ handler_file: "path/to/file.ts" │
│ description: "plain English" │
│ request_body: "schema if POST/PUT" │
│ response: "schema summary" │
│ auth_required: true|false │
│ ``` │
│ │
│ If no APIs found, return: api_endpoints: [] │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ AGENT 3: Components Analyzer │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "Explore" │
│ run_in_background: true │
│ prompt: | │
│ # UI COMPONENTS ANALYSIS │
│ │
│ Find and analyze all UI components in the project. │
│ │
│ ## Search Patterns │
│ - React: components/**/*.tsx, function Component() │
│ - Vue: components/**/*.vue, <script setup> │
│ - Angular: *.component.ts, @Component │
│ - Svelte: **/*.svelte │
│ │
│ ## Output Format (YAML) │
│ ```yaml │
│ components: │
│ - id: "component_name" │
│ name: "ComponentName" │
│ path: "path/to/Component.tsx" │
│ description: "what it does in plain English" │
│ props: │
│ - name: "propName" │
│ type: "string|number|boolean|..." │
│ required: true|false │
│ description: "what it controls" │
│ events: ["onClick", "onChange"] │
│ dependencies: ["OtherComponent"] │
│ ``` │
│ │
│ If no components found, return: components: [] │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ AGENT 4: Data Models Analyzer │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "Explore" │
│ run_in_background: true │
│ prompt: | │
│ # DATA MODELS ANALYSIS │
│ │
│ Find and analyze all data models in the project. │
│ │
│ ## Search Patterns │
│ - Prisma: prisma/schema.prisma, model X {} │
│ - TypeORM: @Entity(), entities/**/*.ts │
│ - Mongoose: new Schema(), models/**/*.ts │
│ - SQLAlchemy: class X(Base), models/**/*.py │
│ - TypeScript: interface/type definitions │
│ │
│ ## Output Format (YAML) │
│ ```yaml │
│ data_models: │
│ - name: "ModelName" │
│ source: "prisma|typeorm|mongoose|typescript" │
│ file_path: "path/to/model" │
│ description: "what data it represents" │
│ fields: │
│ - name: "fieldName" │
│ type: "String|Int|Boolean|..." │
│ description: "plain English" │
│ constraints: "unique|optional|default" │
│ relations: │
│ - type: "hasMany|belongsTo|hasOne" │
│ target: "OtherModel" │
│ glossary_terms: │
│ - term: "technical term found" │
│ definition: "plain English definition" │
│ ``` │
│ │
│ If no models found, return: data_models: [] │
└─────────────────────────────────────────────────────────────────┘
```
#### 1.3: Wait for All Analysis Agents
```
Use TaskOutput tool to wait for each agent:
- TaskOutput with task_id from Agent 1, block: true
- TaskOutput with task_id from Agent 2, block: true
- TaskOutput with task_id from Agent 3, block: true
- TaskOutput with task_id from Agent 4, block: true
Collect all results for synchronization.
```
---
### ═══════════════════════════════════════════════════════════════
### PHASE 2: Synchronization
### ═══════════════════════════════════════════════════════════════
#### 2.1: Merge Analysis Results
Combine outputs from all 4 agents into a unified analysis:
```yaml
# $OUTPUT_DIR/analysis.yml - Merged from parallel agents
project:
# From Agent 1: Structure Analyzer
name: "..."
version: "..."
description: "..."
type: "..."
tech_stack:
# From Agent 1: Structure Analyzer
language: "..."
framework: "..."
database: "..."
key_dependencies: [...]
structure:
# From Agent 1: Structure Analyzer
directories: [...]
api_endpoints:
# From Agent 2: API Analyzer
[...]
components:
# From Agent 3: Components Analyzer
[...]
data_models:
# From Agent 4: Data Models Analyzer
[...]
glossary_terms:
# Merged from all agents
[...]
```
#### 2.2: Write Unified Analysis File
```bash
# Write merged analysis to file
Write the unified YAML to: $OUTPUT_DIR/analysis.yml
```
---
### ═══════════════════════════════════════════════════════════════
### PHASE 3: Parallel Documentation Generation
### ═══════════════════════════════════════════════════════════════
#### 3.1: Launch Parallel Documentation Agents
**CRITICAL: Launch ALL four doc agents in a SINGLE message with multiple Task tool calls:**
```
Launch these 4 Task agents IN PARALLEL (single message, multiple tool calls):
┌─────────────────────────────────────────────────────────────────┐
│ DOC AGENT 1: Main Documentation │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "technical-writer" │
│ run_in_background: true │
│ prompt: | │
│ # Generate PROJECT_DOCUMENTATION.md │
│ │
│ Using the analysis from $OUTPUT_DIR/analysis.yml, │
│ generate comprehensive main documentation. │
│ │
│ ## Sections Required │
│ 1. Executive Summary (plain English, no jargon) │
│ 2. Quick Start (installation, basic usage) │
│ 3. Architecture Overview (ASCII diagrams) │
│ 4. Features (dual-audience: plain + technical details) │
│ 5. Glossary (all technical terms explained) │
│ │
│ ## Rules │
│ - Plain English FIRST, technical in <details> tags │
│ - Include ASCII architecture diagrams │
│ - Use tables for structured data │
│ - Code blocks with language hints │
│ │
│ Write to: $OUTPUT_DIR/PROJECT_DOCUMENTATION.md │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ DOC AGENT 2: API Reference │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "technical-writer" │
│ run_in_background: true │
│ prompt: | │
│ # Generate API_REFERENCE.md │
│ │
│ Using api_endpoints from $OUTPUT_DIR/analysis.yml, │
│ generate detailed API documentation. │
│ │
│ ## Format per Endpoint │
│ ### [METHOD] /path │
│ **Description**: Plain English │
│ **Authentication**: Required/Optional │
│ │
│ <details> │
│ <summary>Technical Details</summary> │
│ Request body, response schema, example │
│ </details> │
│ │
│ If no APIs exist, write brief note explaining this. │
│ │
│ Write to: $OUTPUT_DIR/API_REFERENCE.md │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ DOC AGENT 3: Components Catalog │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "technical-writer" │
│ run_in_background: true │
│ prompt: | │
│ # Generate COMPONENTS.md │
│ │
│ Using components from $OUTPUT_DIR/analysis.yml, │
│ generate component catalog documentation. │
│ │
│ ## Format per Component │
│ ### ComponentName │
│ **Purpose**: Plain English description │
│ **Location**: `path/to/file` │
│ │
│ <details> │
│ <summary>Props & Usage</summary> │
│ Props table, usage example, dependencies │
│ </details> │
│ │
│ If no components exist, write brief note explaining this. │
│ │
│ Write to: $OUTPUT_DIR/COMPONENTS.md │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ DOC AGENT 4: Quick Reference │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "technical-writer" │
│ run_in_background: true │
│ prompt: | │
│ # Generate QUICK_REFERENCE.md │
│ │
│ Using $OUTPUT_DIR/analysis.yml, create a one-page │
│ quick reference card. │
│ │
│ ## Sections (tables only, minimal text) │
│ - Commands (npm scripts, make targets) │
│ - Key Files (important files and purposes) │
│ - API Endpoints (method, path, purpose) │
│ - Environment Variables │
│ - Common Patterns │
│ │
│ Keep it to ONE PAGE - scannable, dense, useful. │
│ │
│ Write to: $OUTPUT_DIR/QUICK_REFERENCE.md │
└─────────────────────────────────────────────────────────────────┘
```
#### 3.2: Wait for All Documentation Agents
```
Use TaskOutput tool to wait for each doc agent:
- TaskOutput with task_id from Doc Agent 1, block: true
- TaskOutput with task_id from Doc Agent 2, block: true
- TaskOutput with task_id from Doc Agent 3, block: true
- TaskOutput with task_id from Doc Agent 4, block: true
```
---
### ═══════════════════════════════════════════════════════════════
### PHASE 4: Finalization
### ═══════════════════════════════════════════════════════════════
#### 4.1: Generate HTML Documentation (Optional)
```bash
# If Python scripts exist, generate HTML
if [ -f "skills/documentation-generator/scripts/generate_html.py" ]; then
python3 skills/documentation-generator/scripts/generate_html.py \
$OUTPUT_DIR/analysis.yml \
skills/documentation-generator/templates/documentation.html \
$OUTPUT_DIR/index.html
fi
```
#### 4.2: Validate Generated Documentation
Verify all documentation files exist and are non-empty:
- `$OUTPUT_DIR/analysis.yml`
- `$OUTPUT_DIR/PROJECT_DOCUMENTATION.md`
- `$OUTPUT_DIR/API_REFERENCE.md`
- `$OUTPUT_DIR/COMPONENTS.md`
- `$OUTPUT_DIR/QUICK_REFERENCE.md`
#### 4.3: Display Completion Banner
```
╔══════════════════════════════════════════════════════════════╗
║ ✅ PARALLEL DOCUMENTATION COMPLETE ║
╠══════════════════════════════════════════════════════════════╣
║ Execution: 4 analysis agents → sync → 4 doc agents ║
╠══════════════════════════════════════════════════════════════╣
║ Output Directory: $OUTPUT_DIR ║
╠══════════════════════════════════════════════════════════════╣
║ Files Created: ║
║ 📊 analysis.yml (Merged analysis data) ║
║ 📄 PROJECT_DOCUMENTATION.md (Main documentation) ║
║ 📄 API_REFERENCE.md (API details) ║
║ 📄 COMPONENTS.md (Component catalog) ║
║ 📄 QUICK_REFERENCE.md (One-page reference) ║
║ 🌐 index.html (HTML version - if generated) ║
╠══════════════════════════════════════════════════════════════╣
║ Performance: ║
║ ⚡ Analysis: 4 agents in parallel ║
║ ⚡ Documentation: 4 agents in parallel ║
║ ⚡ Total: ~2x faster than sequential execution ║
╚══════════════════════════════════════════════════════════════╝
```
---
## ARGUMENTS
| Argument | Default | Description |
|----------|---------|-------------|
| `[output_dir]` | `docs` | Output directory for documentation |
| `--format` | `markdown` | Output format: markdown, html |
| `--sections` | `all` | Sections to include: all, api, components, models |
| `--audience` | `both` | Target: both, technical, non-technical |
## EXAMPLES
```bash
# Generate full documentation with parallel agents
/eureka:index
# Generate in custom directory
/eureka:index my-docs
# Generate API-only documentation
/eureka:index --sections api
# Generate non-technical documentation only
/eureka:index --audience non-technical
```
---
## PARALLEL EXECUTION BENEFITS
| Metric | Sequential | Parallel | Improvement |
|--------|-----------|----------|-------------|
| Analysis Phase | 4x agent time | 1x agent time | 75% faster |
| Doc Generation | 4x agent time | 1x agent time | 75% faster |
| Total Time | ~8 units | ~2 units | **4x faster** |
---
## DUAL-AUDIENCE WRITING GUIDELINES
### For Non-Engineers (Primary)
- Lead with "What" and "Why", not "How"
- Use analogies and real-world comparisons
- Avoid acronyms; spell them out first time
- Use bullet points over paragraphs
- Include visual diagrams
### For Engineers (Secondary)
- Include in collapsible `<details>` sections
- Provide code examples
- Reference file paths and line numbers
- Include type definitions
- Link to source files
### Balance Example
```markdown
## User Authentication
**What it does**: Allows users to securely log into the application
using their email and password.
**How it works** (simplified):
1. User enters credentials
2. System verifies them
3. User receives access
<details>
<summary>Technical Implementation</summary>
- **Strategy**: JWT-based authentication
- **Token Storage**: HTTP-only cookies
- **Session Duration**: 24 hours
- **Refresh Logic**: Automatic refresh 1 hour before expiry
**Key Files**:
- `src/auth/jwt.service.ts` - Token generation
- `src/auth/auth.guard.ts` - Route protection
</details>
```

660
.claude/commands/eureka/landing.md Normal file
View File

@ -0,0 +1,660 @@
---
description: Generate a designer-quality landing page from project documentation with AI-generated images
allowed-tools: Read, Write, Edit, Bash, Task, TodoWrite, Glob, Grep, mcp__eureka-imagen__generate_hero_image, mcp__eureka-imagen__generate_feature_icon, mcp__eureka-imagen__generate_illustration, mcp__eureka-imagen__generate_og_image, mcp__eureka-imagen__generate_logo_concept, mcp__eureka-imagen__list_available_models, mcp__eureka-imagen__check_status
---
# Eureka Landing - Landing Page Generator
**Input**: "$ARGUMENTS"
---
## PURPOSE
Generate a **designer-quality landing page** with concept branding and Q&A section based on existing project documentation. This command requires documentation to be generated first via `/eureka:index`.
### Output Features
| Feature | Description |
|---------|-------------|
| Hero Section | Compelling headline, tagline, CTA buttons |
| Features Grid | Visual feature cards with icons |
| How It Works | Step-by-step visual flow |
| Screenshots/Demo | Placeholder for app visuals |
| Q&A/FAQ | Common questions answered |
| Concept Branding | Colors, typography, visual style |
| Responsive Design | Mobile-first, works on all devices |
| Dark Mode | Automatic system preference detection |
| **AI Images** | AI-generated hero, icons, illustrations (ImageRouter) |
### Image Generation (Optional)
When `--with-images` flag is used and IMAGEROUTER_API_KEY is set, the command will:
- Generate a hero banner image
- Generate feature icons
- Generate how-it-works illustrations
- Generate OG image for social sharing
```bash
# With AI-generated images
/eureka:landing --with-images
# Without images (default)
/eureka:landing
```
---
## PREREQUISITES
```
╔══════════════════════════════════════════════════════════════╗
║ ⚠️ REQUIRES DOCUMENTATION FIRST ║
╠══════════════════════════════════════════════════════════════╣
║ ║
║ This command uses data from /eureka:index output. ║
║ ║
║ Required files: ║
║ ✓ docs/analysis.yml (or custom output dir) ║
║ ✓ docs/PROJECT_DOCUMENTATION.md ║
║ ║
║ If missing, run first: ║
║ /eureka:index ║
║ ║
╚══════════════════════════════════════════════════════════════╝
```
---
## EXECUTION FLOW
### ═══════════════════════════════════════════════════════════════
### PHASE 1: Validate Prerequisites
### ═══════════════════════════════════════════════════════════════
#### 1.1: Check for Documentation
```bash
DOCS_DIR="${ARGUMENTS:-docs}"
# Check if documentation exists
if [ ! -f "$DOCS_DIR/analysis.yml" ] && [ ! -f "$DOCS_DIR/PROJECT_DOCUMENTATION.md" ]; then
echo "❌ ERROR: Documentation not found!"
echo ""
echo "Required: $DOCS_DIR/analysis.yml or $DOCS_DIR/PROJECT_DOCUMENTATION.md"
echo ""
echo "Run first: /eureka:index"
exit 1
fi
echo "✅ Documentation found in $DOCS_DIR"
```
#### 1.2: Display Start Banner
```
╔══════════════════════════════════════════════════════════════╗
║ 🎨 EUREKA LANDING - Designer Landing Page Generator ║
╠══════════════════════════════════════════════════════════════╣
║ Creating: Hero + Features + How It Works + Q&A ║
║ Style: Modern, professional, conversion-optimized ║
╚══════════════════════════════════════════════════════════════╝
```
---
### ═══════════════════════════════════════════════════════════════
### PHASE 2: Parallel Content Generation
### ═══════════════════════════════════════════════════════════════
#### 2.1: Launch Content Generation Agents in Parallel
**CRITICAL: Launch ALL agents in a SINGLE message:**
```
Launch these 4 Task agents IN PARALLEL:
┌─────────────────────────────────────────────────────────────────┐
│ AGENT 1: Branding Concept Generator │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "frontend-architect" │
│ run_in_background: true │
│ prompt: | │
│ # CONCEPT BRANDING GENERATION │
│ │
│ Read $DOCS_DIR/analysis.yml and create a branding concept. │
│ │
│ ## Output: branding.json │
│ ```json │
│ { │
│ "brand": { │
│ "name": "Project Name", │
│ "tagline": "Compelling one-liner", │
│ "value_proposition": "What makes it special" │
│ }, │
│ "colors": { │
│ "primary": "#hex - main brand color", │
│ "secondary": "#hex - accent color", │
│ "accent": "#hex - CTA/highlight color", │
│ "background": "#hex - light bg", │
│ "background_dark": "#hex - dark mode bg", │
│ "text": "#hex - primary text", │
│ "text_muted": "#hex - secondary text" │
│ }, │
│ "typography": { │
│ "heading_font": "Inter, system-ui, sans-serif", │
│ "body_font": "Inter, system-ui, sans-serif", │
│ "mono_font": "JetBrains Mono, monospace" │
│ }, │
│ "style": { │
│ "border_radius": "12px", │
│ "shadow": "0 4px 6px -1px rgba(0,0,0,0.1)", │
│ "gradient": "linear-gradient(...)" │
│ }, │
│ "icons": { │
│ "style": "lucide|heroicons|phosphor", │
│ "feature_icons": ["icon1", "icon2", ...] │
│ } │
│ } │
│ ``` │
│ │
│ Base colors on project type: │
│ - Developer tools: Blues, purples │
│ - Business apps: Blues, greens │
│ - Creative tools: Vibrant, gradients │
│ - Data/Analytics: Teals, blues │
│ │
│ Write to: $DOCS_DIR/branding.json │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ AGENT 2: Hero & Features Content │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "technical-writer" │
│ run_in_background: true │
│ prompt: | │
│ # HERO & FEATURES CONTENT │
│ │
│ Read $DOCS_DIR/analysis.yml and create marketing content. │
│ │
│ ## Output: content.json │
│ ```json │
│ { │
│ "hero": { │
│ "headline": "Powerful, benefit-focused headline", │
│ "subheadline": "Explain the value in one sentence", │
│ "cta_primary": "Get Started", │
│ "cta_secondary": "Learn More", │
│ "social_proof": "Used by X developers" │
│ }, │
│ "features": [ │
│ { │
│ "title": "Feature Name", │
│ "description": "Benefit-focused description", │
│ "icon": "suggested-icon-name" │
│ } │
│ ], │
│ "how_it_works": [ │
│ { │
│ "step": 1, │
│ "title": "Step Title", │
│ "description": "What happens" │
│ } │
│ ], │
│ "stats": [ │
│ { "value": "10x", "label": "Faster" } │
│ ] │
│ } │
│ ``` │
│ │
│ Writing Rules: │
│ - Headlines: Benefit-focused, action-oriented │
│ - Features: Max 6, each with clear benefit │
│ - How It Works: 3-4 steps maximum │
│ - Use numbers and specifics when possible │
│ │
│ Write to: $DOCS_DIR/content.json │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ AGENT 3: Q&A / FAQ Generator │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "technical-writer" │
│ run_in_background: true │
│ prompt: | │
│ # Q&A / FAQ GENERATION │
│ │
│ Read $DOCS_DIR/analysis.yml and PROJECT_DOCUMENTATION.md │
│ to generate comprehensive Q&A. │
│ │
│ ## Output: faq.json │
│ ```json │
│ { │
│ "categories": [ │
│ { │
│ "name": "Getting Started", │
│ "questions": [ │
│ { │
│ "q": "How do I install [Project]?", │
│ "a": "Clear, step-by-step answer" │
│ } │
│ ] │
│ }, │
│ { │
│ "name": "Features", │
│ "questions": [...] │
│ }, │
│ { │
│ "name": "Technical", │
│ "questions": [...] │
│ }, │
│ { │
│ "name": "Pricing & Support", │
│ "questions": [...] │
│ } │
│ ] │
│ } │
│ ``` │
│ │
│ Q&A Guidelines: │
│ - 3-5 questions per category │
│ - Anticipate real user questions │
│ - Answers should be concise but complete │
│ - Include code snippets where helpful │
│ - Address common concerns and objections │
│ │
│ Write to: $DOCS_DIR/faq.json │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ AGENT 4: SEO & Meta Content │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "technical-writer" │
│ run_in_background: true │
│ prompt: | │
│ # SEO & META CONTENT │
│ │
│ Read $DOCS_DIR/analysis.yml and create SEO content. │
│ │
│ ## Output: seo.json │
│ ```json │
│ { │
│ "title": "Project Name - Tagline | Category", │
│ "description": "150-160 char meta description", │
│ "keywords": ["keyword1", "keyword2"], │
│ "og": { │
│ "title": "Open Graph title", │
│ "description": "OG description", │
│ "type": "website" │
│ }, │
│ "twitter": { │
│ "card": "summary_large_image", │
│ "title": "Twitter title", │
│ "description": "Twitter description" │
│ }, │
│ "structured_data": { │
│ "@type": "SoftwareApplication", │
│ "name": "...", │
│ "description": "..." │
│ } │
│ } │
│ ``` │
│ │
│ Write to: $DOCS_DIR/seo.json │
└─────────────────────────────────────────────────────────────────┘
```
#### 2.2: Wait for All Content Agents
```
Use TaskOutput tool to wait for each agent:
- TaskOutput with task_id from Agent 1 (branding), block: true
- TaskOutput with task_id from Agent 2 (content), block: true
- TaskOutput with task_id from Agent 3 (faq), block: true
- TaskOutput with task_id from Agent 4 (seo), block: true
```
---
### ═══════════════════════════════════════════════════════════════
### PHASE 3: Generate Landing Page HTML
### ═══════════════════════════════════════════════════════════════
#### 3.1: Generate Designer-Quality Landing Page
**Use Task tool with frontend-architect agent:**
```
Task tool with:
subagent_type: "frontend-architect"
prompt: |
# GENERATE LANDING PAGE HTML
Read these files and generate a stunning landing page:
- $DOCS_DIR/branding.json (colors, typography, style)
- $DOCS_DIR/content.json (hero, features, how-it-works)
- $DOCS_DIR/faq.json (Q&A sections)
- $DOCS_DIR/seo.json (meta tags)
## Output: $DOCS_DIR/landing.html
## Design Requirements
### Structure
```html
<!DOCTYPE html>
<html lang="en">
<head>
<!-- SEO meta tags from seo.json -->
<!-- Fonts: Google Fonts or system fonts -->
<!-- Inline critical CSS -->
</head>
<body>
<!-- Navigation (sticky) -->
<nav>Logo | Links | CTA Button</nav>
<!-- Hero Section -->
<section class="hero">
<h1>Headline</h1>
<p>Subheadline</p>
<div class="cta-buttons">Primary | Secondary</div>
<!-- Optional: Animated gradient background -->
</section>
<!-- Social Proof / Stats -->
<section class="stats">
<div class="stat">Value + Label</div>
</section>
<!-- Features Grid -->
<section class="features">
<h2>Features</h2>
<div class="feature-grid">
<!-- 3-column grid of feature cards -->
</div>
</section>
<!-- How It Works -->
<section class="how-it-works">
<h2>How It Works</h2>
<div class="steps">
<!-- Numbered steps with visual flow -->
</div>
</section>
<!-- Q&A / FAQ -->
<section class="faq">
<h2>Frequently Asked Questions</h2>
<div class="faq-accordion">
<!-- Expandable Q&A items -->
</div>
</section>
<!-- CTA Section -->
<section class="cta-final">
<h2>Ready to Get Started?</h2>
<button>Primary CTA</button>
</section>
<!-- Footer -->
<footer>
Links | Copyright | Social
</footer>
<!-- Inline JavaScript for interactions -->
<script>
// FAQ accordion
// Smooth scroll
// Dark mode toggle
</script>
</body>
</html>
```
### Visual Design Standards
**Hero Section**:
- Full viewport height or 80vh minimum
- Gradient or subtle pattern background
- Large, bold headline (48-72px)
- Clear visual hierarchy
- Floating elements or subtle animation
**Feature Cards**:
- Icon + Title + Description
- Subtle hover effects (scale, shadow)
- Consistent spacing (24-32px gaps)
- 3-column on desktop, 1 on mobile
**How It Works**:
- Visual step indicators (1, 2, 3)
- Connecting lines or arrows
- Icons or illustrations per step
- Horizontal on desktop, vertical on mobile
**FAQ Accordion**:
- Click to expand/collapse
- Smooth animation (max-height transition)
- Plus/minus or chevron indicator
- Category grouping
**Micro-interactions**:
- Button hover: scale(1.02) + shadow
- Card hover: translateY(-4px) + shadow
- Smooth scroll for anchor links
- Fade-in on scroll (intersection observer)
### CSS Requirements
```css
/* CSS Custom Properties from branding.json */
:root {
--color-primary: ...;
--color-secondary: ...;
--font-heading: ...;
--radius: ...;
}
/* Dark mode */
@media (prefers-color-scheme: dark) {
:root {
--color-bg: var(--color-bg-dark);
...
}
}
/* Responsive breakpoints */
/* Mobile: < 640px */
/* Tablet: 640-1024px */
/* Desktop: > 1024px */
```
### JavaScript Requirements
- FAQ accordion functionality
- Smooth scroll for navigation
- Optional: Scroll-triggered animations
- Dark mode toggle (optional)
- Mobile menu toggle
### Performance
- Single HTML file (no external dependencies)
- Inline critical CSS
- Minimal JavaScript
- Optimized for Core Web Vitals
- < 100KB total size
Write complete HTML to: $DOCS_DIR/landing.html
```
---
### ═══════════════════════════════════════════════════════════════
### PHASE 4: Finalization
### ═══════════════════════════════════════════════════════════════
#### 4.1: Validate Generated Files
Verify all files exist:
- `$DOCS_DIR/branding.json`
- `$DOCS_DIR/content.json`
- `$DOCS_DIR/faq.json`
- `$DOCS_DIR/seo.json`
- `$DOCS_DIR/landing.html`
#### 4.2: Display Completion Banner
```
╔══════════════════════════════════════════════════════════════╗
║ ✅ LANDING PAGE GENERATED SUCCESSFULLY ║
╠══════════════════════════════════════════════════════════════╣
║ Output Directory: $DOCS_DIR ║
╠══════════════════════════════════════════════════════════════╣
║ Files Created: ║
║ 🎨 branding.json (Colors, typography, style guide) ║
║ 📝 content.json (Hero, features, how-it-works) ║
║ ❓ faq.json (Q&A content by category) ║
║ 🔍 seo.json (Meta tags, Open Graph, Schema) ║
║ 🌐 landing.html (Designer-quality landing page) ║
╠══════════════════════════════════════════════════════════════╣
║ Landing Page Features: ║
║ ✅ Hero with compelling headline + CTAs ║
║ ✅ Feature grid with icons ║
║ ✅ How It Works visual flow ║
║ ✅ Interactive FAQ accordion ║
║ ✅ Responsive (mobile-first) ║
║ ✅ Dark mode support ║
║ ✅ SEO optimized ║
║ ✅ Single file, no dependencies ║
╠══════════════════════════════════════════════════════════════╣
║ Next Steps: ║
║ → Open landing.html in browser to preview ║
║ → Customize colors in branding.json ║
║ → Add real screenshots/images ║
║ → Deploy to your hosting ║
╚══════════════════════════════════════════════════════════════╝
```
---
## ARGUMENTS
| Argument | Default | Description |
|----------|---------|-------------|
| `[docs_dir]` | `docs` | Directory containing documentation from /eureka:index |
| `--style` | `modern` | Design style: modern, minimal, bold, corporate |
| `--theme` | `auto` | Color theme: auto, light, dark |
## EXAMPLES
```bash
# Generate landing page from default docs directory
/eureka:landing
# Generate from custom documentation directory
/eureka:landing my-docs
# Generate with specific style
/eureka:landing --style minimal
# Generate dark-only theme
/eureka:landing --theme dark
```
---
## DESIGN STYLE OPTIONS
### Modern (Default)
- Gradient backgrounds
- Rounded corners (12-16px)
- Soft shadows
- Vibrant accent colors
- Floating elements
### Minimal
- Clean white space
- Thin borders
- Muted colors
- Typography-focused
- Subtle interactions
### Bold
- Strong colors
- Large typography
- High contrast
- Geometric shapes
- Impactful CTAs
### Corporate
- Professional blues/grays
- Structured layout
- Trust indicators
- Clean lines
- Conservative animations
---
## OUTPUT STRUCTURE
```
docs/
├── analysis.yml (from /eureka:index)
├── PROJECT_DOCUMENTATION.md
├── API_REFERENCE.md
├── COMPONENTS.md
├── QUICK_REFERENCE.md
├── index.html (documentation HTML)
│
├── branding.json (NEW - concept branding)
├── content.json (NEW - marketing content)
├── faq.json (NEW - Q&A content)
├── seo.json (NEW - SEO metadata)
└── landing.html (NEW - landing page)
```
---
## BRANDING SYSTEM
The generated branding.json provides a complete design system:
```json
{
"brand": {
"name": "Project Name",
"tagline": "Your compelling tagline",
"value_proposition": "What makes it unique"
},
"colors": {
"primary": "#6366f1",
"secondary": "#8b5cf6",
"accent": "#f59e0b",
"background": "#ffffff",
"background_dark": "#0f172a",
"text": "#1e293b",
"text_muted": "#64748b"
},
"typography": {
"heading_font": "Inter, system-ui, sans-serif",
"body_font": "Inter, system-ui, sans-serif",
"mono_font": "JetBrains Mono, Consolas, monospace"
},
"style": {
"border_radius": "12px",
"shadow_sm": "0 1px 2px rgba(0,0,0,0.05)",
"shadow_md": "0 4px 6px -1px rgba(0,0,0,0.1)",
"shadow_lg": "0 10px 15px -3px rgba(0,0,0,0.1)",
"gradient": "linear-gradient(135deg, #6366f1 0%, #8b5cf6 100%)"
}
}
```
This can be used to:
- Maintain consistent branding across all pages
- Generate CSS custom properties
- Create Figma/design tool exports
- Build component libraries

243
.claude/commands/guardrail/analyze.md Normal file
View File

@ -0,0 +1,243 @@
---
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

47
.claude/commands/guardrail/approve.md Normal file
View File

@ -0,0 +1,47 @@
---
description: Approve design and transition to IMPLEMENTATION_PHASE (Reviewer mode)
allowed-tools: Read, Write, Bash
---
# Approve Design (Reviewer Mode)
✅ **REVIEWER MODE ACTIVATED**
Approve the current design and enable implementation.
## CRITICAL RULES
You are acting as the **REVIEWER AGENT**.
✅ **ALLOWED**:
- Read any file
- Update approval status in manifest
- Transition phases
❌ **BLOCKED**:
- Write ANY code files
- You cannot implement anything
## Steps
1. **Verify Phase**: Must be in `DESIGN_REVIEW`
2. **Run Full Validation**:
```bash
python3 "$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_manifest.py" --strict
```
3. **If Valid**, update manifest:
- Set `state.approval_status.manifest_approved = true`
- Set `state.approval_status.approved_by = "reviewer"`
- Set `state.approval_status.approved_at = <current timestamp>`
4. **Transition to Implementation**:
```bash
python3 "$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/transition_phase.py" --to IMPLEMENTATION_PHASE
```
5. **Show Results**:
- List all entities now with status `APPROVED`
- Explain that code can now be written for these entities
- Suggest `/guardrail:implement` to start

81
.claude/commands/guardrail/design.md Normal file
View File

@ -0,0 +1,81 @@
---
description: Design a new feature by adding entities to manifest (Architect mode)
allowed-tools: Read, Write, Bash
---
# Design Feature (Architect Mode)
🏗️ **ARCHITECT MODE ACTIVATED**
Design the feature: "$ARGUMENTS"
## CRITICAL RULES
You are now acting as the **ARCHITECT AGENT**.
✅ **ALLOWED**:
- Read any file
- Write to `project_manifest.json` ONLY
- Run validation scripts
❌ **BLOCKED**:
- Write ANY code files (.ts, .tsx, .css, .sql, .js, .jsx)
- You CANNOT write implementation code yet
## Workflow
1. **Verify Phase**: Check `project_manifest.json` - must be in `DESIGN_PHASE`
2. **Analyze Requirements**: Break down "$ARGUMENTS" into:
- Pages needed (routes/screens)
- Components needed (UI elements)
- API endpoints needed (backend routes)
- Database tables needed (data storage)
3. **Define Each Entity** in manifest with:
- Unique ID following naming convention
- Complete specification (props, schemas, columns)
- `status: "DEFINED"`
- File path where it will be implemented
4. **Update Manifest**: Add all entities to `project_manifest.json`
5. **Validate**: Run `python3 skills/guardrail-orchestrator/scripts/validate_manifest.py`
6. **Summarize**: List what was added and suggest `/guardrail:review`
## Entity Templates
### Page
```json
{
"id": "page_[name]",
"path": "/[route]",
"file_path": "src/pages/[name]/index.tsx",
"status": "DEFINED",
"components": [],
"data_dependencies": []
}
```
### Component
```json
{
"id": "comp_[name]",
"name": "[PascalCase]",
"file_path": "src/components/[Name]/index.tsx",
"status": "DEFINED",
"props": {}
}
```
### API Endpoint
```json
{
"id": "api_[action]_[resource]",
"path": "/api/v1/[resource]",
"method": "GET|POST|PUT|DELETE",
"file_path": "src/api/[resource]/[action].ts",
"status": "DEFINED"
}
```

74
.claude/commands/guardrail/implement.md Normal file
View File

@ -0,0 +1,74 @@
---
description: Implement an approved entity from the manifest
allowed-tools: Read, Write, Bash
---
# Implement Entity
Implement the entity: "$ARGUMENTS"
## CRITICAL RULES
⚠️ **GUARDRAIL ENFORCEMENT ACTIVE**
You can ONLY write to files that:
1. Are defined in `project_manifest.json`
2. Have status = `APPROVED`
3. Match the `file_path` in the manifest EXACTLY
## Steps
1. **Verify Phase**: Must be in `IMPLEMENTATION_PHASE`
2. **Find Entity** in manifest:
- If "$ARGUMENTS" is `--all`: implement all APPROVED entities
- Otherwise: find the specific entity by ID
3. **For Each Entity**:
a. **Load Definition** from manifest
b. **Verify Status** is `APPROVED`
c. **Generate Code** matching the specification:
- Props must match manifest exactly
- Types must match manifest exactly
- File path must match `file_path` in manifest
d. **Write File** to the exact path in manifest
e. **Run Validations**:
```bash
npm run lint --if-present
npm run type-check --if-present
```
4. **Status Updates** (handled by post-hook):
- Entity status changes to `IMPLEMENTED`
- Timestamp recorded
## Code Templates
### Component (Frontend)
```tsx
import React from 'react';
interface [Name]Props {
// From manifest.props
}
export const [Name]: React.FC<[Name]Props> = (props) => {
return (
// Implementation
);
};
```
### API Endpoint (Backend)
```typescript
import { Request, Response } from 'express';
export async function handler(req: Request, res: Response) {
// From manifest.request/response schemas
}
```

67
.claude/commands/guardrail/init.md Normal file
View File

@ -0,0 +1,67 @@
---
description: Initialize a new guardrailed project with manifest
allowed-tools: Bash, Write, Read
---
# Initialize Guardrailed Project
Initialize a new project called "$ARGUMENTS" with guardrail enforcement and workflow system.
## 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
## Steps
### Step 1: Run the initialization script
```bash
python3 skills/guardrail-orchestrator/scripts/init_project.py --name "$ARGUMENTS" --path .
```
### 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
fi
```
### Step 3: Verify and Display Summary
```bash
# Verify files exist
ls project_manifest.json .workflow/index.yml
```
Display:
```
╔══════════════════════════════════════════════════════════════╗
║ ✅ PROJECT INITIALIZED ║
╠══════════════════════════════════════════════════════════════╣
║ Project: $ARGUMENTS ║
║ Phase: DESIGN_PHASE ║
╠══════════════════════════════════════════════════════════════╣
║ Files Created: ║
║ ✓ project_manifest.json ║
║ ✓ .workflow/index.yml ║
║ ✓ .workflow/versions/ ║
╠══════════════════════════════════════════════════════════════╣
║ Next Steps: ║
║ /guardrail:design Design features in manifest ║
║ /workflow:spawn <feat> Start automated workflow ║
╚══════════════════════════════════════════════════════════════╝
```
## Notes
- Project starts in **DESIGN_PHASE** (manifest edits only)
- Use `/guardrail:design` for manual design workflow
- Use `/workflow:spawn` for automated design + implementation

32
.claude/commands/guardrail/review.md Normal file
View File

@ -0,0 +1,32 @@
---
description: Request design review and transition to DESIGN_REVIEW phase
allowed-tools: Read, Write, Bash
---
# Request Design Review
Transition the project from DESIGN_PHASE to DESIGN_REVIEW.
## Steps
1. **Validate Manifest**:
```bash
python3 "$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_manifest.py" --strict
```
2. **If Valid**, transition phase:
```bash
python3 "$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/transition_phase.py" --to DESIGN_REVIEW
```
3. **Show Review Checklist**:
- [ ] All pages have at least one component
- [ ] All components have defined props with types
- [ ] All APIs have request/response schemas
- [ ] All database tables have primary keys
- [ ] No orphan components
- [ ] No circular dependencies
4. **Explain Next Steps**:
- Use `/guardrail:approve` to approve and move to implementation
- Use `/guardrail:reject <feedback>` to send back for fixes

27
.claude/commands/guardrail/status.md Normal file
View File

@ -0,0 +1,27 @@
---
description: Show current project phase, entity counts, and pending work
allowed-tools: Read, Bash
---
# Guardrail Status
Display the current guardrail project status.
## Steps
1. Read `project_manifest.json`
2. Display:
- **Current Phase**: `state.current_phase`
- **Approval Status**: `state.approval_status.manifest_approved`
- **Entity Counts**:
- Pages: count by status (DEFINED/APPROVED/IMPLEMENTED)
- Components: count by status
- API Endpoints: count by status
- Database Tables: count by status
- **Recent History**: last 5 items from `state.revision_history`
3. Show available actions for current phase:
- DESIGN_PHASE: Can use `/guardrail:design`, then `/guardrail:review`
- DESIGN_REVIEW: Can use `/guardrail:approve` or `/guardrail:reject`
- IMPLEMENTATION_PHASE: Can use `/guardrail:implement`

29
.claude/commands/guardrail/validate.md Normal file
View File

@ -0,0 +1,29 @@
---
description: Validate manifest integrity and completeness
allowed-tools: Bash, Read
---
# Validate Manifest
Run validation checks on `project_manifest.json`.
## Command
```bash
python3 "$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_manifest.py" $ARGUMENTS
```
## Options
- No arguments: Basic validation
- `--strict`: Treat warnings as errors
## What It Checks
1. **Structure**: Required top-level keys exist
2. **Pages**: Have paths, components, file_paths
3. **Components**: Have props with types, valid dependencies
4. **APIs**: Have methods, paths, request/response schemas
5. **Database**: Tables have primary keys, valid foreign keys
6. **Dependencies**: No orphans, no circular references
7. **Naming**: Follows conventions

57
.claude/commands/guardrail/verify.md Normal file
View File

@ -0,0 +1,57 @@
---
description: Verify implementation matches manifest specifications
allowed-tools: Bash, Read
---
# Verify Implementation
Run verification to ensure all implemented code matches the manifest specifications.
## Command
```bash
python3 "$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/verify_implementation.py" --project-root "$CLAUDE_PROJECT_DIR" $ARGUMENTS
```
## Options
- No arguments: Basic verification
- `--verbose` or `-v`: Include warnings
- `--json`: Output as JSON for programmatic use
## What It Checks
For each entity in the manifest:
### Components
- File exists at specified `file_path`
- Component name is exported
- Props interface matches manifest definition
### Pages
- File exists at specified `file_path`
- Has `export default` (Next.js requirement)
- Uses specified component dependencies
### API Endpoints
- File exists at specified `file_path`
- HTTP method handler exists (GET, POST, PUT, DELETE)
- Request parameters are handled
### Database Tables
- File exists at specified `file_path`
- Column definitions present
- CRUD operations implemented
## Example Output
```
✅ [component] comp_button
File: app/components/Button.tsx
❌ [component] comp_missing
File: app/components/Missing.tsx
❌ ERROR: File not found
SUMMARY: 17/18 passed, 1 failed, 3 warnings
```

87
.claude/commands/workflow/approve.md Normal file
View File

@ -0,0 +1,87 @@
---
description: Approve a workflow gate (design or implementation)
allowed-tools: Read, Write, Bash
---
# Approve Workflow Gate
Approve gate: "$ARGUMENTS"
## Valid Gates
- `design` - Approve the design phase (entities + tasks)
- `implementation` - Approve the implementation phase (all code)
## Steps
### 1. Validate Gate
- If "$ARGUMENTS" is not `design` or `implementation`: STOP and show usage
### 2. Check Workflow State
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py exists
```
If no active workflow:
```
❌ No active workflow found.
Start a new workflow with: /workflow:spawn "feature name"
```
### 3. Verify Current Phase
**For design approval**:
- Current phase must be `AWAITING_DESIGN_APPROVAL`
- If not: Report error with current phase
**For implementation approval**:
- Current phase must be `AWAITING_IMPL_APPROVAL`
- If not: Report error with current phase
### 4. Execute Approval
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py approve $ARGUMENTS
```
### 5. Transition to Next Phase
**If design approved**:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition DESIGN_APPROVED
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition IMPLEMENTING
```
**If implementation approved**:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition IMPL_APPROVED
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition COMPLETING
```
### 6. Report
**Design Approved**:
```
╔══════════════════════════════════════════════════════════════╗
║ ✅ DESIGN APPROVED ║
╠══════════════════════════════════════════════════════════════╣
║ The design has been approved. Implementation will begin. ║
║ ║
║ Next steps: ║
║ /workflow:frontend --next Start frontend tasks ║
║ /workflow:backend --next Start backend tasks ║
║ /workflow:resume Auto-continue workflow ║
╚══════════════════════════════════════════════════════════════╝
```
**Implementation Approved**:
```
╔══════════════════════════════════════════════════════════════╗
║ ✅ IMPLEMENTATION APPROVED ║
╠══════════════════════════════════════════════════════════════╣
║ All implementations have been approved. ║
║ ║
║ Next steps: ║
║ /workflow:complete --all Mark all tasks as done ║
║ /workflow:resume Auto-complete workflow ║
╚══════════════════════════════════════════════════════════════╝
```

85
.claude/commands/workflow/backend.md Normal file
View File

@ -0,0 +1,85 @@
---
description: Implement backend tasks (Backend agent)
allowed-tools: Read, Write, Edit, Bash
---
# Backend Agent - Implementation Mode
⚙️ **BACKEND AGENT ACTIVATED**
Implement task: "$ARGUMENTS"
## CRITICAL RULES
You are now the **BACKEND AGENT**.
✅ **ALLOWED**:
- Read any file
- Write new files (API routes, DB)
- Edit existing backend files
- Run Bash (build, lint, type-check, tests)
✅ **ALLOWED FILES**:
- `app/api/**/*`
- `app/lib/**/*`
- `prisma/**/*`
- `db/**/*`
## Workflow
### Step 1: Load Task
First, get the version-specific tasks directory:
```bash
TASKS_DIR=$(python3 skills/guardrail-orchestrator/scripts/version_manager.py tasks-dir)
```
Read the task file: `$TASKS_DIR/$ARGUMENTS.yml`
- If "$ARGUMENTS" is `--next`: find first task with `agent: backend` and `status: pending`
### Step 2: Update Workflow State
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> in_progress
```
### Step 3: Verify Prerequisites
- Check entity is `APPROVED` in `project_manifest.json`
- Check all `dependencies` tasks are `completed`
- If blocked:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> blocked
```
Stop and report blocker.
### Step 4: Implement
For each file in `file_paths`:
1. Read manifest entity specification
2. Generate code matching spec exactly:
- HTTP methods must match manifest
- Request params must match manifest
- Response types must match manifest
3. Follow existing project patterns
### Step 5: Validate
Run validations:
```bash
npm run lint
npm run build
```
### Step 6: Update Task Status
Update the task file:
```yaml
status: review
completed_at: <current timestamp>
```
Update workflow state:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> review
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py progress --tasks-impl <count>
```
### Step 7: Report
- List implemented files
- Show validation results
- Suggest: `/workflow:review $ARGUMENTS`

66
.claude/commands/workflow/complete.md Normal file
View File

@ -0,0 +1,66 @@
---
description: Mark approved task as completed
allowed-tools: Read, Write, Bash
---
# Complete Task
Mark task "$ARGUMENTS" as completed.
## Prerequisites
- Task must have `status: approved`
- All acceptance criteria verified by reviewer
## Steps
### 1. Read Task
First, get the version-specific tasks directory:
```bash
TASKS_DIR=$(python3 skills/guardrail-orchestrator/scripts/version_manager.py tasks-dir)
```
Read `$TASKS_DIR/$ARGUMENTS.yml`
### 2. Verify Status
- If `status` is NOT `approved`: STOP and report error
- If `status` is `approved`: proceed
### 3. Update Task
Update the task file with:
```yaml
status: completed
completed_at: <current timestamp>
```
### 4. Update Workflow State
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> completed
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py progress --tasks-completed <count>
```
### 5. Update Manifest (if applicable)
For each entity in `entity_ids`:
- Update entity status to `IMPLEMENTED` in `project_manifest.json`
### 6. Check Workflow Completion
Check if all tasks are now completed:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py status
```
If all tasks completed, transition to implementation approval:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition AWAITING_IMPL_APPROVAL
```
### 7. Report
```
✅ Task completed: $ARGUMENTS
Entities implemented:
- <entity_id_1>
- <entity_id_2>
Next: /workflow:status to see remaining tasks
/workflow:complete --all to complete all approved tasks
```

476
.claude/commands/workflow/design.md Normal file
View File

@ -0,0 +1,476 @@
---
description: Design system architecture with ER diagram, API contracts, and UI structure
allowed-tools: Read, Write, Edit, Bash, Task, TodoWrite
---
# Workflow Design - System Architecture Phase
**Input**: "$ARGUMENTS"
---
## PURPOSE
This command creates a comprehensive **design document** that serves as the source of truth for implementation. It defines:
1. **Data Layer** - ER diagram with models, fields, relations
2. **API Layer** - REST endpoints with request/response contracts
3. **UI Layer** - Pages and components with data requirements
4. **Dependency Graph** - Layered execution order for parallel tasks
---
## ⛔ CRITICAL RULES
### MUST DO
1. **MUST** create `design_document.yml` with ALL layers defined
2. **MUST** run `validate_design.py` to generate dependency graph
3. **MUST** verify no circular dependencies before proceeding
4. **MUST** show layered execution plan to user
### CANNOT DO
1. **CANNOT** create tasks without design document
2. **CANNOT** skip validation step
3. **CANNOT** proceed if validation fails
---
## EXECUTION FLOW
### ═══════════════════════════════════════════════════════════════
### STEP 1: Initialize Design Session
### ═══════════════════════════════════════════════════════════════
#### 1.1: Get Current Version
```bash
# Get active version from workflow
VERSION_ID=$(cat .workflow/current.yml 2>/dev/null | grep "active_version:" | awk '{print $2}')
if [ -z "$VERSION_ID" ]; then
echo "ERROR: No active workflow. Run /workflow:spawn first"
exit 1
fi
echo "VERSION_ID=$VERSION_ID"
```
#### 1.2: Create Design Directory
```bash
mkdir -p .workflow/versions/$VERSION_ID/design
mkdir -p .workflow/versions/$VERSION_ID/contexts
mkdir -p .workflow/versions/$VERSION_ID/tasks
```
#### 1.3: Display Design Start Banner
```
╔══════════════════════════════════════════════════════════════╗
║ 📐 SYSTEM DESIGN PHASE ║
╠══════════════════════════════════════════════════════════════╣
║ Feature: $ARGUMENTS ║
║ Version: $VERSION_ID ║
╠══════════════════════════════════════════════════════════════╣
║ You will define: ║
║ Layer 1: Data Models (ER Diagram) ║
║ Layer 2: API Endpoints (REST Contracts) ║
║ Layer 3: Pages & Components (UI Structure) ║
╚══════════════════════════════════════════════════════════════╝
```
---
### ═══════════════════════════════════════════════════════════════
### STEP 2: Analyze Requirements & Design System
### ═══════════════════════════════════════════════════════════════
**Use Task tool with system-architect agent:**
```
Use Task tool with:
subagent_type: "system-architect"
prompt: |
# SYSTEM ARCHITECT - Design Document Creation
## INPUT
Feature: "$ARGUMENTS"
Version: $VERSION_ID
Output: .workflow/versions/$VERSION_ID/design/design_document.yml
## YOUR MISSION
Create a comprehensive design document following the schema in:
skills/guardrail-orchestrator/schemas/design_document.yml
## ANALYSIS PROCESS
### Phase A: Understand Requirements
1. Read the feature description carefully
2. Identify the core user flows
3. Determine what data needs to be stored
4. Identify what APIs are needed
5. Plan the UI structure
### Phase B: Design Data Layer (ER Diagram)
For each entity needed:
- Define fields with types and constraints
- Define relations to other entities
- Define validations
- Consider indexes for performance
### Phase C: Design API Layer
For each endpoint needed:
- Define HTTP method and path
- Define request body schema (for POST/PUT/PATCH)
- Define response schemas for all status codes
- Define authentication requirements
- Link to data models used
### Phase D: Design UI Layer
For each page needed:
- Define route path
- List data requirements (which APIs)
- List components used
- Define auth requirements
For each component needed:
- Define props interface
- Define events emitted
- List child components
- List APIs called directly (if any)
## OUTPUT FORMAT
Create `.workflow/versions/$VERSION_ID/design/design_document.yml`:
```yaml
# Design Document
workflow_version: "$VERSION_ID"
feature: "$ARGUMENTS"
created_at: <timestamp>
status: draft
revision: 1
# LAYER 1: DATA MODELS
data_models:
- id: model_<name>
name: <PascalCase>
description: "<what this model represents>"
table_name: <snake_case>
fields:
- name: id
type: uuid
constraints: [primary_key]
- name: <field_name>
type: <string|integer|boolean|datetime|uuid|json|text|float|enum>
constraints: [<unique|not_null|indexed|default>]
# If enum:
enum_values: [<value1>, <value2>]
relations:
- type: <has_one|has_many|belongs_to|many_to_many>
target: model_<other>
foreign_key: <fk_field>
on_delete: <cascade|set_null|restrict>
timestamps: true
validations:
- field: <field_name>
rule: "<validation_rule>"
message: "<error message>"
# LAYER 2: API ENDPOINTS
api_endpoints:
- id: api_<verb>_<resource>
method: <GET|POST|PUT|PATCH|DELETE>
path: /api/<path>
summary: "<short description>"
description: "<detailed description>"
# For POST/PUT/PATCH:
request_body:
content_type: application/json
schema:
type: object
properties:
- name: <field>
type: <type>
required: <true|false>
validations: [<rules>]
responses:
- status: 200
description: "Success"
schema:
type: object
properties:
- name: <field>
type: <type>
- status: 400
description: "Validation error"
schema:
type: object
properties:
- name: error
type: string
depends_on_models: [model_<name>]
auth:
required: <true|false>
roles: [<role1>, <role2>]
# LAYER 3: PAGES
pages:
- id: page_<name>
name: "<Human Name>"
path: /<route>
layout: <layout_component>
data_needs:
- api_id: api_<name>
purpose: "<why needed>"
on_load: <true|false>
components: [component_<name1>, component_<name2>]
auth:
required: <true|false>
roles: []
redirect: /login
# LAYER 3: COMPONENTS
components:
- id: component_<name>
name: <PascalCaseName>
props:
- name: <propName>
type: <TypeScript type>
required: <true|false>
description: "<what this prop does>"
events:
- name: <onEventName>
payload: "<payload type>"
description: "<when this fires>"
uses_apis: []
uses_components: [component_<child>]
variants: [<variant1>, <variant2>]
```
## DESIGN PRINCIPLES
1. **Start with Data**: What data is needed? Design models first.
2. **APIs Serve UI**: What operations does UI need? Design APIs next.
3. **UI Consumes APIs**: Pages/Components use APIs. Design UI last.
4. **Explicit Dependencies**: Every relation must be clearly defined.
5. **Contracts First**: API request/response schemas are contracts.
## VERIFICATION
After creating the design document, verify:
1. Every API references existing models
2. Every page references existing APIs and components
3. Every component references existing child components
4. No circular dependencies
## OUTPUT
After creating the file, output:
```
=== DESIGN DOCUMENT CREATED ===
Data Models: X
API Endpoints: X
Pages: X
Components: X
File: .workflow/versions/$VERSION_ID/design/design_document.yml
```
```
---
### ═══════════════════════════════════════════════════════════════
### STEP 3: Validate Design & Generate Dependency Graph
### ═══════════════════════════════════════════════════════════════
#### 3.1: Run Design Validation [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/validate_design.py \
.workflow/versions/$VERSION_ID/design/design_document.yml \
--output-dir .workflow/versions/$VERSION_ID
```
**This generates:**
- `.workflow/versions/$VERSION_ID/dependency_graph.yml` - Layered execution order
- `.workflow/versions/$VERSION_ID/contexts/*.yml` - Per-entity context snapshots
- `.workflow/versions/$VERSION_ID/tasks/*.yml` - Tasks with full context
#### 3.2: Check Validation Result
```bash
VALIDATION_EXIT=$?
if [ $VALIDATION_EXIT -ne 0 ]; then
echo "❌ Design validation failed. Fix errors and re-run."
exit 1
fi
```
**BLOCK IF**: Validation fails → Display errors, do not proceed
---
### ═══════════════════════════════════════════════════════════════
### STEP 4: Display Layered Execution Plan
### ═══════════════════════════════════════════════════════════════
Read the generated dependency graph and display:
```
╔══════════════════════════════════════════════════════════════╗
║ 📊 DEPENDENCY GRAPH - EXECUTION LAYERS ║
╠══════════════════════════════════════════════════════════════╣
║ ║
║ Layer 1: DATA MODELS (Parallel) ║
║ ───────────────────────────────────────────── ║
║ 📦 model_user → backend ║
║ 📦 model_post → backend ║
║ ║
║ Layer 2: API ENDPOINTS (Parallel, after Layer 1) ║
║ ───────────────────────────────────────────── ║
║ 🔌 api_create_user → backend (needs: model_user) ║
║ 🔌 api_list_users → backend (needs: model_user) ║
║ 🔌 api_create_post → backend (needs: model_user, model_post)║
║ ║
║ Layer 3: UI (Parallel, after Layer 2) ║
║ ───────────────────────────────────────────── ║
║ 🧩 component_user_card → frontend ║
║ 📄 page_users → frontend (needs: api_list_users) ║
║ ║
╠══════════════════════════════════════════════════════════════╣
║ EXECUTION SUMMARY ║
║ Total entities: X ║
║ Total layers: X ║
║ Max parallelism: X (tasks can run simultaneously) ║
║ Critical path: X layers deep ║
╚══════════════════════════════════════════════════════════════╝
```
---
### ═══════════════════════════════════════════════════════════════
### STEP 5: Display Design Summary for Approval
### ═══════════════════════════════════════════════════════════════
```
╔══════════════════════════════════════════════════════════════╗
║ 🛑 DESIGN APPROVAL REQUIRED ║
╠══════════════════════════════════════════════════════════════╣
║ Feature: $ARGUMENTS ║
║ Version: $VERSION_ID ║
╠══════════════════════════════════════════════════════════════╣
║ DESIGN DOCUMENT ║
║ 📦 Data Models: X ║
║ 🔌 API Endpoints: X ║
║ 📄 Pages: X ║
║ 🧩 Components: X ║
╠══════════════════════════════════════════════════════════════╣
║ GENERATED ARTIFACTS ║
║ ✅ Dependency graph calculated ║
║ ✅ Context snapshots created (X files) ║
║ ✅ Implementation tasks created (X tasks) ║
╠══════════════════════════════════════════════════════════════╣
║ EXECUTION PLAN ║
║ Layer 1: X tasks (parallel) → backend ║
║ Layer 2: X tasks (parallel) → backend ║
║ Layer 3: X tasks (parallel) → frontend ║
╠══════════════════════════════════════════════════════════════╣
║ FILES CREATED ║
║ .workflow/versions/$VERSION_ID/design/design_document.yml ║
║ .workflow/versions/$VERSION_ID/dependency_graph.yml ║
║ .workflow/versions/$VERSION_ID/contexts/*.yml ║
║ .workflow/versions/$VERSION_ID/tasks/*.yml ║
╠══════════════════════════════════════════════════════════════╣
║ NEXT STEPS ║
║ Review the design above, then: ║
║ /workflow:approve - Proceed to implementation ║
║ /workflow:reject - Request design changes ║
╚══════════════════════════════════════════════════════════════╝
```
---
### ═══════════════════════════════════════════════════════════════
### STEP 6: Transition Workflow State
### ═══════════════════════════════════════════════════════════════
```bash
# Update progress
TASK_COUNT=$(ls .workflow/versions/$VERSION_ID/tasks/*.yml 2>/dev/null | wc -l)
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py progress \
--tasks-created $TASK_COUNT
# Transition to awaiting approval
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition AWAITING_DESIGN_APPROVAL
```
---
## CONTEXT SNAPSHOT EXAMPLE
Each task gets a context file like `.workflow/versions/$VERSION_ID/contexts/api_create_user.yml`:
```yaml
task_id: task_create_api_create_user
entity_id: api_create_user
workflow_version: v001
target:
type: api
definition:
method: POST
path: /api/users
request_body:
properties:
- name: email
type: string
required: true
validations: [email]
- name: password
type: string
required: true
validations: [min:8]
responses:
- status: 201
schema: { id, email, name, created_at }
- status: 400
schema: { error, details }
- status: 409
schema: { error }
related:
models:
- id: model_user
definition:
name: User
fields:
- { name: id, type: uuid }
- { name: email, type: string }
- { name: password_hash, type: string }
dependencies:
entity_ids: [model_user]
files:
to_create:
- app/api/users/route.ts
reference:
- path: app/api/health/route.ts
purpose: "API route pattern"
acceptance:
- criterion: "POST /api/users returns 201 on success"
verification: "curl -X POST /api/users with valid data"
- criterion: "Returns 409 if email exists"
verification: "Test with duplicate email"
```
---
## USAGE
```bash
# After /workflow:spawn, run design:
/workflow:design
# This will:
# 1. Create comprehensive design document
# 2. Validate and generate dependency graph
# 3. Create tasks with full context
# 4. Wait for approval before implementation
```

193
.claude/commands/workflow/diff.md Normal file
View File

@ -0,0 +1,193 @@
---
description: Compare workflow versions and show manifest changes
allowed-tools: Read, Bash
---
# Workflow Version Diff
Compare workflow versions to see what changed in the project manifest.
## EXECUTION PROTOCOL
### Step 1: Parse Arguments
```
IF "$ARGUMENTS" = "":
MODE = "current" (diff latest version with current)
ELSE IF "$ARGUMENTS" matches "v\d+ v\d+":
MODE = "versions" (diff two specific versions)
ELSE IF "$ARGUMENTS" matches "v\d+":
MODE = "single" (diff specific version with current)
ELSE IF "$ARGUMENTS" = "--changelog" or "--log":
MODE = "changelog" (show all version changelogs)
ELSE IF "$ARGUMENTS" contains "--json":
OUTPUT = "json"
```
### Step 2: Get Available Versions
```bash
python3 skills/guardrail-orchestrator/scripts/manifest_diff.py versions
```
### Step 3: Execute Diff Based on Mode
**MODE: current (default)**
```bash
# Get latest version
LATEST=$(ls -1 .workflow/versions/ 2>/dev/null | tail -1)
# Diff with current manifest
python3 skills/guardrail-orchestrator/scripts/manifest_diff.py diff $LATEST current
```
**MODE: versions (e.g., "v001 v002")**
```bash
# Diff two specific versions
python3 skills/guardrail-orchestrator/scripts/manifest_diff.py diff v001 v002
```
**MODE: single (e.g., "v001")**
```bash
# Diff specific version with current
python3 skills/guardrail-orchestrator/scripts/manifest_diff.py diff v001
```
**MODE: changelog**
```bash
# Show all changelogs
python3 skills/guardrail-orchestrator/scripts/manifest_diff.py changelog
```
**JSON output**
```bash
# Add --json for programmatic use
python3 skills/guardrail-orchestrator/scripts/manifest_diff.py diff v001 --json
```
### Step 4: Display Results
The script outputs:
```
╔══════════════════════════════════════════════════════════════════════╗
║ MANIFEST DIFF: v001 → v002 ║
╠══════════════════════════════════════════════════════════════════════╣
║ SUMMARY ║
║ + Added: 3 ║
║ ~ Modified: 2 ║
║ - Removed: 1 ║
║ = Unchanged: 5 ║
╠══════════════════════════════════════════════════════════════════════╣
║ BY TYPE ║
║ pages: +1 ║
║ components: +2 ~1 ║
║ api_endpoints: ~1 -1 ║
╠══════════════════════════════════════════════════════════════════════╣
║ ➕ ADDED ║
║ + 📄 Profile (app/profile/page.tsx) ║
║ + 🧩 Button (app/components/Button.tsx) ║
║ + 🧩 Modal (app/components/Modal.tsx) ║
╠══════════════════════════════════════════════════════════════════════╣
║ 📝 MODIFIED ║
║ ~ 🧩 Header (app/components/Header.tsx) ║
║ dependencies: [] → ['Button'] ║
║ ~ 🔌 users (app/api/users/route.ts) ║
║ status: PENDING → IMPLEMENTED ║
╠══════════════════════════════════════════════════════════════════════╣
║ ➖ REMOVED ║
║ - 🔌 legacy (app/api/legacy/route.ts) ║
╚══════════════════════════════════════════════════════════════════════╝
```
---
## USAGE EXAMPLES
```bash
# Compare latest version with current manifest
/workflow:diff
# Compare two specific versions
/workflow:diff v001 v002
# Compare specific version with current
/workflow:diff v003
# Show all version changelogs
/workflow:diff --changelog
# Output as JSON
/workflow:diff v001 --json
```
---
## WHAT IT SHOWS
### Entity Changes
- **Added**: New pages, components, API endpoints, etc.
- **Modified**: Status changes, dependency updates, path changes
- **Removed**: Deleted entities from manifest
### Entity Type Icons
- 📄 page
- 🧩 component
- 🔌 api_endpoint
- 📚 lib
- 🪝 hook
- 📝 type
- ⚙️ config
### Change Details
- Entity name and file path
- Specific field changes with before/after values
- Summary statistics by type
---
## CHANGELOG MODE
Show version history with changes:
```bash
/workflow:diff --changelog
```
Output:
```
╔══════════════════════════════════════════════════════════════════════╗
║ CHANGELOG: v001 ║
╠══════════════════════════════════════════════════════════════════════╣
║ Feature: User authentication ║
║ Status: completed ║
║ Started: 2025-01-15 10:30:00 ║
║ Completed: 2025-01-15 14:45:00 ║
╠══════════════════════════════════════════════════════════════════════╣
║ CHANGES ║
║ + Added page: Login ║
║ + Added page: Register ║
║ + Added component: AuthForm ║
║ + Added api_endpoint: auth ║
╚══════════════════════════════════════════════════════════════════════╝
```
---
## INTEGRATION
### Uses Version Snapshots
The diff tool uses snapshots created by version_manager.py:
- `snapshot_before/manifest.json` - Manifest at version start
- `snapshot_after/manifest.json` - Manifest at version completion
These are automatically created when:
- `/workflow:spawn` initializes a new version
- `/workflow:complete` marks a version as done
### Related Commands
- `/workflow:history` - List all workflow versions
- `/workflow:status` - Show current workflow state
- `/workflow:changelog <version>` - Alias for `--changelog`

85
.claude/commands/workflow/frontend.md Normal file
View File

@ -0,0 +1,85 @@
---
description: Implement frontend tasks (Frontend agent)
allowed-tools: Read, Write, Edit, Bash
---
# Frontend Agent - Implementation Mode
🎨 **FRONTEND AGENT ACTIVATED**
Implement task: "$ARGUMENTS"
## CRITICAL RULES
You are now the **FRONTEND AGENT**.
✅ **ALLOWED**:
- Read any file
- Write new files (components, pages)
- Edit existing UI files
- Run Bash (build, lint, type-check)
✅ **ALLOWED FILES**:
- `app/components/**/*`
- `app/**/page.tsx`
- `app/**/layout.tsx`
- `app/globals.css`
## Workflow
### Step 1: Load Task
First, get the version-specific tasks directory:
```bash
TASKS_DIR=$(python3 skills/guardrail-orchestrator/scripts/version_manager.py tasks-dir)
```
Read the task file: `$TASKS_DIR/$ARGUMENTS.yml`
- If "$ARGUMENTS" is `--next`: find first task with `agent: frontend` and `status: pending`
### Step 2: Update Workflow State
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> in_progress
```
### Step 3: Verify Prerequisites
- Check entity is `APPROVED` in `project_manifest.json`
- Check all `dependencies` tasks are `completed`
- If blocked:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> blocked
```
Stop and report blocker.
### Step 4: Implement
For each file in `file_paths`:
1. Read manifest entity specification
2. Generate code matching spec exactly:
- Props must match manifest
- Types must match manifest
- File path must match manifest
3. Follow existing project patterns
### Step 5: Validate
Run validations:
```bash
npm run lint
npm run build
```
### Step 6: Update Task Status
Update the task file:
```yaml
status: review
completed_at: <current timestamp>
```
Update workflow state:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> review
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py progress --tasks-impl <count>
```
### Step 7: Report
- List implemented files
- Show validation results
- Suggest: `/workflow:review $ARGUMENTS`

94
.claude/commands/workflow/history.md Normal file
View File

@ -0,0 +1,94 @@
---
description: Show workflow version history
allowed-tools: Read, Bash
---
# Workflow History
Display version history of all workflow sessions.
## Usage
```
/workflow:history # List all versions
/workflow:history v001 # Show details for specific version
/workflow:history --changelog # Show changelog for current version
```
## Steps
### 1. List All Versions (default)
```bash
python3 skills/guardrail-orchestrator/scripts/version_manager.py history
```
### 2. Show Version Details
If "$ARGUMENTS" is a version (e.g., `v001`):
```bash
python3 skills/guardrail-orchestrator/scripts/version_manager.py changelog $ARGUMENTS
```
### 3. Display Format
**Version List**:
```
╔══════════════════════════════════════════════════════════════════════╗
║ WORKFLOW VERSION HISTORY ║
╠══════════════════════════════════════════════════════════════════════╣
║ ✅ v003: Dashboard with analytics ║
║ Started: 2025-01-16T16:00:00 | Tasks: 12 | Ops: 45 ║
║ ────────────────────────────────────────────────────────────────── ║
║ ✅ v002: Task filters and search ║
║ Started: 2025-01-16T14:00:00 | Tasks: 8 | Ops: 28 ║
║ ────────────────────────────────────────────────────────────────── ║
║ ✅ v001: User authentication ║
║ Started: 2025-01-16T10:00:00 | Tasks: 5 | Ops: 18 ║
╚══════════════════════════════════════════════════════════════════════╝
```
**Version Changelog**:
```
╔══════════════════════════════════════════════════════════════════════╗
║ CHANGELOG: v001 ║
╠══════════════════════════════════════════════════════════════════════╣
║ Feature: User authentication ║
║ Status: completed ║
╠══════════════════════════════════════════════════════════════════════╣
║ CREATED ║
║ + [page] page_login ║
║ app/login/page.tsx ║
║ + [component] component_LoginForm ║
║ app/components/LoginForm.tsx ║
║ + [api] api_auth ║
║ app/api/auth/route.ts ║
║ UPDATED ║
║ ~ [component] component_Header ║
║ DELETED ║
║ (none) ║
╠══════════════════════════════════════════════════════════════════════╣
║ SUMMARY ║
║ Entities: +3 ~1 -0 ║
║ Files: +4 ~2 -0 ║
╚══════════════════════════════════════════════════════════════════════╝
```
### 4. Show Task Sessions
If `$ARGUMENTS` includes `--tasks`:
List all task sessions for the version with their operations:
```
Task Sessions for v001:
─────────────────────────────────────────────────
🎨 task_create_LoginPage (frontend)
Status: completed | Duration: 5m 32s
Operations:
+ CREATE file: app/login/page.tsx
~ UPDATE manifest: project_manifest.json
Review: ✅ approved
⚙️ task_create_AuthAPI (backend)
Status: completed | Duration: 8m 15s
Operations:
+ CREATE file: app/api/auth/route.ts
+ CREATE file: app/lib/auth.ts
Review: ✅ approved
```

113
.claude/commands/workflow/reject.md Normal file
View File

@ -0,0 +1,113 @@
---
description: Reject a workflow gate and request changes
allowed-tools: Read, Write, Bash
---
# Reject Workflow Gate
Reject gate with reason: "$ARGUMENTS"
## Usage
```
/workflow:reject design "Need more API endpoints for authentication"
/workflow:reject implementation "Login form missing validation"
```
## Steps
### 1. Parse Arguments
Extract:
- `gate`: First word (design | implementation)
- `reason`: Remaining text in quotes
If invalid format:
```
❌ Usage: /workflow:reject <gate> "reason"
Examples:
/workflow:reject design "Need user profile page"
/workflow:reject implementation "Missing error handling"
```
### 2. Check Workflow State
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py exists
```
If no active workflow:
```
❌ No active workflow found.
```
### 3. Verify Current Phase
**For design rejection**:
- Current phase must be `AWAITING_DESIGN_APPROVAL`
**For implementation rejection**:
- Current phase must be `AWAITING_IMPL_APPROVAL`
### 4. Execute Rejection
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py reject <gate> "<reason>"
```
### 5. Transition to Revision Phase
**If design rejected**:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition DESIGN_REJECTED
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition DESIGNING
```
**If implementation rejected**:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition IMPL_REJECTED
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition IMPLEMENTING
```
### 6. Report
**Design Rejected**:
```
╔══════════════════════════════════════════════════════════════╗
║ ❌ DESIGN REJECTED ║
╠══════════════════════════════════════════════════════════════╣
║ Reason: <rejection_reason> ║
║ ║
║ The workflow has returned to the DESIGNING phase. ║
║ Revision count: X ║
║ ║
║ Next steps: ║
║ /workflow:design --revise Revise the design ║
║ /workflow:resume Auto-revise and continue ║
╚══════════════════════════════════════════════════════════════╝
```
**Implementation Rejected**:
```
╔══════════════════════════════════════════════════════════════╗
║ ❌ IMPLEMENTATION REJECTED ║
╠══════════════════════════════════════════════════════════════╣
║ Reason: <rejection_reason> ║
║ ║
║ The workflow has returned to the IMPLEMENTING phase. ║
║ Revision count: X ║
║ ║
║ Tasks requiring fixes will be marked as 'pending'. ║
║ ║
║ Next steps: ║
║ /workflow:frontend --next Fix frontend tasks ║
║ /workflow:backend --next Fix backend tasks ║
║ /workflow:resume Auto-fix and continue ║
╚══════════════════════════════════════════════════════════════╝
```
### 7. Update Related Tasks (Implementation Rejection)
If implementation was rejected, identify tasks related to the rejection reason and mark them as pending:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <affected_task_id> pending
```

159
.claude/commands/workflow/resume.md Normal file
View File

@ -0,0 +1,159 @@
---
description: Resume an interrupted workflow from saved state
allowed-tools: Read, Write, Edit, Bash, AskUserQuestion, TodoWrite
---
# Workflow Orchestrator - Resume
Resume a previously interrupted or paused workflow.
## EXECUTION PROTOCOL
### Step 1: Load Workflow State
Read `.workflow/current.yml`:
- If not found: Report "No workflow to resume" and exit
- If found: Load state and continue
### Step 2: Display Resume Summary
```
╔══════════════════════════════════════════════════════════════╗
║ 🔄 RESUMING WORKFLOW ║
╠══════════════════════════════════════════════════════════════╣
║ Workflow ID: <id> ║
║ Feature: <feature> ║
║ Started: <started_at> ║
║ Last Updated: <updated_at> ║
╠══════════════════════════════════════════════════════════════╣
║ CURRENT STATE ║
║ Phase: <current_phase> ║
║ Resume Point: <resume_point.action> ║
╠══════════════════════════════════════════════════════════════╣
║ PROGRESS ║
║ Entities Designed: <progress.entities_designed> ║
║ Tasks Created: <progress.tasks_created> ║
║ Tasks Implemented: <progress.tasks_implemented> ║
║ Tasks Reviewed: <progress.tasks_reviewed> ║
║ Tasks Completed: <progress.tasks_completed> ║
╠══════════════════════════════════════════════════════════════╣
║ LAST ERROR (if any): <last_error> ║
╚══════════════════════════════════════════════════════════════╝
```
### Step 3: Confirm Resume
**Ask user**:
- Option 1: "Continue - Resume from current point"
- Option 2: "Restart Phase - Redo current phase from beginning"
- Option 3: "Abort - Cancel workflow entirely"
### Step 4: Resume Based on Phase
**INITIALIZING**:
→ Continue to DESIGNING phase
**DESIGNING**:
→ Continue architect work
→ Resume creating entities/tasks
**AWAITING_DESIGN_APPROVAL**:
→ Present design summary again
→ Ask for approval
**DESIGN_APPROVED**:
→ Continue to IMPLEMENTING phase
**DESIGN_REJECTED**:
→ Show rejection reason
→ Return to DESIGNING with feedback
**IMPLEMENTING**:
→ Find incomplete tasks
→ Continue implementation from next pending task
**REVIEWING**:
→ Find tasks awaiting review
→ Continue review process
**SECURITY_REVIEW**:
→ Continue security scanning
→ Run: `python3 skills/guardrail-orchestrator/scripts/security_scan.py --project-dir . --severity HIGH`
→ Run: `python3 skills/guardrail-orchestrator/scripts/validate_api_contract.py --project-dir .`
→ If passed: Transition to AWAITING_IMPL_APPROVAL
→ If critical issues: Return to IMPLEMENTING with security feedback
**AWAITING_IMPL_APPROVAL**:
→ Present implementation summary again
→ Ask for approval
**IMPL_APPROVED**:
→ Continue to COMPLETING phase
**IMPL_REJECTED**:
→ Show rejection reason
→ Return to IMPLEMENTING with feedback
**COMPLETING**:
→ Continue marking tasks complete
**PAUSED**:
→ Resume from `resume_point.phase`
**FAILED**:
→ Show error details
→ Ask user how to proceed:
- Retry failed operation
- Skip and continue
- Abort workflow
### Step 5: Continue Workflow
Execute remaining phases following `/workflow:spawn` protocol.
## TASK-LEVEL RESUME
If resuming during IMPLEMENTING phase:
1. **Identify incomplete tasks**:
```yaml
# Resume from first task not in 'completed' or 'approved'
resume_task: tasks.pending[0] || tasks.in_progress[0] || tasks.review[0]
```
2. **Skip completed work**:
- Don't recreate files that exist and are valid
- Don't re-run validations that passed
3. **Continue from failure point**:
- If task failed mid-implementation, restart that task
- If validation failed, show error and retry
## STATE RECOVERY
If `.workflow/current.yml` is corrupted:
1. **Check for backup**: `.workflow/current.yml.bak`
2. **Attempt recovery from manifest**:
- Read `project_manifest.json` for entity status
- Scan version-specific tasks directory for task status
- Reconstruct workflow state
3. **If unrecoverable**:
- Report error
- Suggest starting fresh with `/workflow:spawn`
## ABORT WORKFLOW
If user chooses to abort:
1. **Confirm abort**:
"This will cancel the workflow. Files already created will remain. Continue?"
2. **If confirmed**:
- Archive state to `.workflow/history/<id>_aborted.yml`
- Clear `.workflow/current.yml`
- Report: "Workflow aborted. Created files remain in place."
3. **Cleanup options**:
- Offer to rollback created files (if git available)
- Offer to keep partial implementation

526
.claude/commands/workflow/review.md Normal file
View File

@ -0,0 +1,526 @@
---
description: Review implementation (Reviewer agent)
allowed-tools: Read, Bash
---
# Reviewer Agent - Review Mode
**Input**: "$ARGUMENTS"
---
## CRITICAL ENFORCEMENT RULES
**YOU ARE IN READ-ONLY MODE. VIOLATIONS WILL BE BLOCKED.**
### MUST DO (Non-Negotiable)
1. **MUST** run all validation checks (build, typecheck, lint, test, API contract)
2. **MUST** verify every file in task's `file_paths` exists
3. **MUST** read and analyze each implemented file
4. **MUST** check against acceptance_criteria in task file
5. **MUST** output structured review report (format below)
6. **MUST** run workflow_manager.py to update task status
### CANNOT DO (Strictly Forbidden)
1. **CANNOT** create files (Write tool blocked)
2. **CANNOT** modify files (Edit tool blocked)
3. **CANNOT** fix issues yourself - only report them
4. **CANNOT** approve tasks with missing files
5. **CANNOT** approve if ANY validation check fails
6. **CANNOT** skip any validation check
### ALLOWED ACTIONS
- Read any file
- Run Bash commands (build, lint, test, typecheck, ls, cat, grep)
- Output review reports
- Update task status via workflow_manager.py
---
## VALIDATION CHECKS MATRIX
| Check | Command | Blocks Approval | When |
|-------|---------|-----------------|------|
| Build | `npm run build` | YES | Always |
| TypeScript | `npx tsc --noEmit` | YES | Always |
| Async/Await | `python3 verify_async.py` | YES | Always |
| Lint | `npm run lint` | YES (if --strict) | --strict mode |
| Unit Tests | `npm test -- --passWithNoTests` | YES (if --strict) | --strict mode |
| API Contract | `python3 validate_api_contract.py` | YES | Always |
| Security Scan | `python3 security_scan.py` | YES (critical) | Always |
| Files Exist | `ls -la` each file | YES | Always |
**Note:** For comprehensive security audit, use `/workflow:security --full`
---
## ARGUMENT PARSING
```
IF "$ARGUMENTS" contains "--auto":
MODE = AUTO (batch review all tasks)
STRICT = "$ARGUMENTS" contains "--strict"
FULL = "$ARGUMENTS" contains "--full"
ELSE IF "$ARGUMENTS" = "--next":
MODE = SINGLE (next pending task)
ELSE:
MODE = SINGLE (specific task: "$ARGUMENTS")
```
---
## MODE: AUTO REVIEW (--auto)
### Step A1: Get Active Version [MANDATORY]
```bash
VERSION_ID=$(python3 skills/guardrail-orchestrator/scripts/version_manager.py current)
TASKS_DIR=".workflow/versions/$VERSION_ID/tasks"
```
### Step A2: Run Global Validations [MANDATORY]
#### 2.1 Build Check
```bash
npm run build 2>&1
BUILD_EXIT=$?
echo "BUILD_EXIT=$BUILD_EXIT"
```
#### 2.2 TypeScript Strict Check
```bash
npx tsc --noEmit 2>&1
TS_EXIT=$?
echo "TS_EXIT=$TS_EXIT"
```
#### 2.3 Async/Await Check [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/verify_async.py --path . 2>&1
ASYNC_EXIT=$?
echo "ASYNC_EXIT=$ASYNC_EXIT"
```
This catches runtime errors at build time:
- `fetch()` without `await`
- `.json()` without `await`
- `Promise.all()` without `await`
- Floating promises (unawaited async calls)
**Exit codes:**
- 0 = PASS (no high-severity issues)
- 1 = HIGH severity issues found (blocks approval)
#### 2.4 Lint Check (if --strict or --full)
```bash
npm run lint 2>&1
LINT_EXIT=$?
echo "LINT_EXIT=$LINT_EXIT"
```
#### 2.5 Unit Tests (if --strict or --full)
```bash
npm test -- --passWithNoTests 2>&1
TEST_EXIT=$?
echo "TEST_EXIT=$TEST_EXIT"
```
#### 2.6 API Contract Validation [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/validate_api_contract.py --project-dir . 2>&1
API_EXIT=$?
echo "API_EXIT=$API_EXIT"
```
This validates:
- Frontend API calls have matching backend endpoints
- HTTP methods match (GET, POST, PUT, DELETE)
- Request bodies are sent where expected
- Response handling matches backend output
#### 2.7 Security Scan [MANDATORY]
```bash
# Run comprehensive security scanner
python3 skills/guardrail-orchestrator/scripts/security_scan.py \
--project-dir . \
--severity HIGH
SECURITY_EXIT=$?
echo "SECURITY_EXIT=$SECURITY_EXIT"
```
**Security scan checks:**
- Hardcoded secrets (API keys, passwords, tokens)
- SQL injection vulnerabilities
- XSS risks (dangerouslySetInnerHTML, innerHTML)
- Command injection patterns
- Path traversal vulnerabilities
- NoSQL injection risks
- SSRF vulnerabilities
- Prototype pollution
- Insecure authentication patterns
- CORS misconfigurations
- Sensitive data exposure
- Debug code in production
**Exit codes:**
- 0 = PASS (no critical/high issues)
- 1 = HIGH issues found (warning)
- 2 = CRITICAL issues found (blocks approval)
**For full security audit, run:** `/workflow:security --full`
### Step A3: Gather All Tasks [MANDATORY]
```bash
ls $TASKS_DIR/*.yml 2>/dev/null
```
**MUST process ALL task files found**
### Step A4: Review Each Task [MANDATORY]
For EACH task file:
```bash
# Extract file_paths from task
TASK_FILES=$(grep -A 20 "file_paths:" "$TASK_FILE" | grep -E "^\s+-" | sed 's/.*- //')
```
**Check each file exists**:
```bash
for file in $TASK_FILES; do
if [ -f "$file" ]; then
echo "EXISTS: $file"
else
echo "MISSING: $file"
MISSING_COUNT=$((MISSING_COUNT + 1))
fi
done
```
**Determine task verdict**:
```
IF all files exist
AND BUILD_EXIT = 0
AND TS_EXIT = 0
AND ASYNC_EXIT = 0
AND API_EXIT = 0
AND SECURITY_EXIT != 2 (no critical security issues)
AND (not --strict OR (LINT_EXIT = 0 AND TEST_EXIT = 0)):
-> TASK_VERDICT = APPROVED
ELSE:
-> TASK_VERDICT = REJECTED
-> Record reason (missing files / build failure / type error / async issue / API mismatch / security issue)
```
**Security exit codes:**
- 0 = PASS
- 1 = HIGH issues (warning, doesn't block unless --strict)
- 2 = CRITICAL issues (always blocks)
### Step A5: Batch Update [MANDATORY]
For APPROVED tasks:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> approved
```
For REJECTED tasks:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task <task_id> pending
```
### Step A6: Auto Review Report [MANDATORY]
**MUST output this exact format**:
```
+======================================================================+
| REVIEW COMPLETE |
+======================================================================+
| Version: $VERSION_ID |
| Mode: AUTO [STRICT if --strict] [FULL if --full] |
+======================================================================+
| VALIDATION RESULTS |
+----------------------------------------------------------------------+
| Build: PASS (exit 0) / FAIL (exit $BUILD_EXIT) |
| TypeScript: PASS (exit 0) / FAIL (exit $TS_EXIT) |
| Async/Await: PASS / FAIL (X high, Y medium issues) |
| Lint: PASS / FAIL / SKIPPED |
| Tests: PASS / FAIL / SKIPPED |
| API Contract: PASS / FAIL (X errors, Y warnings) |
| Security: PASS / WARNING / CRITICAL |
| (C:X H:X M:X L:X issues) |
+======================================================================+
| API CONTRACT DETAILS |
+----------------------------------------------------------------------+
| Frontend calls: X matched, Y unmatched |
| Backend endpoints: X defined, Y unused |
| Method mismatches: X |
| Body mismatches: X |
+======================================================================+
| TASK RESULTS |
+----------------------------------------------------------------------+
| Total: X tasks |
| Approved: X tasks |
| Rejected: X tasks |
| Skipped: X tasks (already completed) |
+======================================================================+
| APPROVED TASKS |
| - task_create_Button |
| - task_create_Form |
+----------------------------------------------------------------------+
| REJECTED TASKS |
| - task_create_Modal |
| Reason: Missing file app/components/Modal.tsx |
| - task_update_API |
| Reason: API contract error - endpoint not found |
+======================================================================+
| SECURITY WARNINGS |
| - src/lib/api.ts:15 - Possible hardcoded API key |
| - app/page.tsx:42 - dangerouslySetInnerHTML usage |
+======================================================================+
```
### Step A7: Next Steps [MANDATORY]
**IF all approved**:
```
All tasks approved.
Next: Run `/workflow:approve implementation` to continue.
```
**IF any rejected**:
```
Some tasks need fixes.
API Contract Issues:
For frontend issues: Fix the API call URL or method
For backend issues: Create or fix the API endpoint
For each rejected task, run:
/workflow:frontend <task_id> (for frontend tasks)
/workflow:backend <task_id> (for backend tasks)
Then re-run: /workflow:review --auto
```
---
## MODE: SINGLE TASK REVIEW (--next or task_id)
### Step S1: Get Task [MANDATORY]
```bash
VERSION_ID=$(python3 skills/guardrail-orchestrator/scripts/version_manager.py current)
TASKS_DIR=".workflow/versions/$VERSION_ID/tasks"
```
**IF --next**:
```bash
# Find first task with status: pending or status: implemented
TASK_FILE=$(grep -l "status: pending\|status: implemented" $TASKS_DIR/*.yml 2>/dev/null | head -1)
```
**IF specific task_id**:
```bash
TASK_FILE="$TASKS_DIR/$ARGUMENTS.yml"
```
**BLOCK IF**: Task file does not exist -> Error: "Task not found: $ARGUMENTS"
### Step S2: Read Task Spec [MANDATORY]
```bash
cat "$TASK_FILE"
```
Extract:
- `id`: Task identifier
- `file_paths`: List of files to verify
- `acceptance_criteria`: List of requirements to check
### Step S3: Run All Validations [MANDATORY]
```bash
# Build
npm run build 2>&1
BUILD_EXIT=$?
# TypeScript
npx tsc --noEmit 2>&1
TS_EXIT=$?
# API Contract
python3 skills/guardrail-orchestrator/scripts/validate_api_contract.py --project-dir . 2>&1
API_EXIT=$?
```
**MUST capture and report all exit codes**
### Step S4: Verify Files Exist [MANDATORY]
For each path in `file_paths`:
```bash
ls -la "$path" 2>/dev/null && echo "EXISTS" || echo "MISSING"
```
**Record**:
- FILES_EXIST = true/false
- MISSING_FILES = list of missing paths
### Step S5: Read and Analyze Files [MANDATORY]
For each EXISTING file:
1. Read file content
2. Check against acceptance_criteria:
- [ ] File exports correct components/functions
- [ ] Props/types match manifest spec
- [ ] Code follows project patterns
- [ ] No obvious bugs or issues
3. Check API contract compliance:
- [ ] Frontend calls use correct endpoints
- [ ] HTTP methods are appropriate
- [ ] Request bodies are properly structured
- [ ] Response handling is correct
### Step S6: Determine Verdict [MANDATORY]
```
IF BUILD_EXIT = 0
AND TS_EXIT = 0
AND API_EXIT = 0
AND FILES_EXIST = true
AND acceptance_criteria met:
-> VERDICT = APPROVED
ELSE:
-> VERDICT = REQUEST_CHANGES
-> Record all issues found
```
### Step S7: Update Task Status [MANDATORY]
**IF APPROVED**:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task $TASK_ID approved
```
**IF REQUEST_CHANGES**:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py task $TASK_ID pending
```
### Step S8: Output Review Report [MANDATORY]
**MUST output this exact format**:
```
+======================================================================+
| TASK REVIEW |
+======================================================================+
| Task: $TASK_ID |
| Version: $VERSION_ID |
+======================================================================+
| VALIDATION CHECKS |
+----------------------------------------------------------------------+
| Build: PASS / FAIL |
| TypeScript: PASS / FAIL |
| API Contract: PASS / FAIL |
| Files exist: PASS / FAIL (X/Y files) |
| Acceptance criteria: PASS / PARTIAL / FAIL |
| Code quality: PASS / ISSUES |
+======================================================================+
| API CONTRACT STATUS |
+----------------------------------------------------------------------+
| Endpoint calls: X found, Y matched |
| Method correctness: PASS / X mismatches |
| Request bodies: PASS / X issues |
| Response handling: PASS / ISSUES |
+======================================================================+
| VERDICT: APPROVED / REQUEST_CHANGES |
+======================================================================+
| [If REQUEST_CHANGES, list all issues:] |
| 1. Missing file: app/components/Button.tsx |
| 2. TypeScript error: Type 'string' not assignable to 'number' |
| 3. API contract: POST /api/users called but endpoint expects GET |
| 4. API contract: Frontend sends body but backend ignores it |
| 5. Acceptance criterion not met: "Must support dark mode" |
+======================================================================+
```
### Step S9: Next Steps [MANDATORY]
**IF APPROVED**:
```
Task approved.
Next: Run `/workflow:complete $TASK_ID` to mark as done.
Or run `/workflow:review --next` to review next task.
```
**IF REQUEST_CHANGES**:
```
Changes requested.
Issues to fix:
[List specific issues with file locations]
For API contract issues:
- If frontend issue: Fix the fetch/axios call in [file:line]
- If backend issue: Update the API route handler in [file]
Fix issues and re-run:
/workflow:frontend $TASK_ID (for frontend tasks)
/workflow:backend $TASK_ID (for backend tasks)
Then: /workflow:review $TASK_ID
```
---
## USAGE EXAMPLES
```bash
# Review specific task
/workflow:review task_create_Button
# Review next pending task
/workflow:review --next
# Auto-review all tasks (standard - build + types + API)
/workflow:review --auto
# Auto-review all tasks (strict - includes lint + tests)
/workflow:review --auto --strict
# Full review with all checks
/workflow:review --auto --full
```
---
## API CONTRACT VALIDATION DETAILS
The API contract validator checks:
### Frontend Analysis
- **fetch()** calls with `/api/` paths
- **axios** requests (get, post, put, delete)
- **useSWR** data fetching hooks
- **Custom API clients** (api.get, api.post, etc.)
### Backend Analysis
- **Next.js App Router**: `app/api/*/route.ts` exports (GET, POST, PUT, DELETE)
- **Next.js Pages Router**: `pages/api/*.ts` with req.method checks
- **Express-style**: router.get/post/etc patterns
### Validation Rules
1. **Endpoint Existence**: Every frontend call must have a matching backend route
2. **Method Match**: GET calls must hit GET endpoints, POST to POST, etc.
3. **Body Alignment**: POST/PUT calls should send bodies, GET should not
4. **Unused Endpoints**: Backend routes not called by frontend (warnings)
---
## ENFORCEMENT CHECKLIST
Before completing this command, verify:
- [ ] Build command executed and exit code captured
- [ ] TypeScript check executed and exit code captured
- [ ] API contract validation executed and exit code captured
- [ ] All file_paths verified with ls command
- [ ] Security scan completed
- [ ] Structured review report output (exact format above)
- [ ] Task status updated via workflow_manager.py
- [ ] Next steps clearly stated

342
.claude/commands/workflow/security.md Normal file
View File

@ -0,0 +1,342 @@
---
description: Run comprehensive security audit (Security Reviewer agent)
allowed-tools: Read, Bash, Grep, Task
---
# Security Reviewer Agent - Security Audit Mode
**Input**: "$ARGUMENTS"
---
## CRITICAL CONSTRAINTS
**YOU ARE IN READ-ONLY MODE FOR ANALYSIS.**
### MUST DO (Non-Negotiable)
1. **MUST** run automated security scanner
2. **MUST** analyze all CRITICAL and HIGH findings
3. **MUST** check dependency vulnerabilities
4. **MUST** review security configurations
5. **MUST** output structured security report
6. **MUST** provide remediation guidance
### CANNOT DO (Strictly Forbidden)
1. **CANNOT** modify source files
2. **CANNOT** fix issues directly
3. **CANNOT** approve with CRITICAL issues
4. **CANNOT** skip any security category
---
## ARGUMENT PARSING
```
IF "$ARGUMENTS" contains "--quick":
MODE = QUICK (scanner only)
ELSE IF "$ARGUMENTS" contains "--full":
MODE = FULL (scanner + deep analysis + deps + config)
ELSE:
MODE = STANDARD (scanner + deps)
SEVERITY = extract from --severity [critical|high|medium|low]
OUTPUT = extract from --json (JSON output) or text
```
---
## EXECUTION FLOW
### Step 1: Run Automated Security Scanner [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/security_scan.py \
--project-dir . \
--severity ${SEVERITY:-LOW} \
${OUTPUT:+--json}
```
**Capture output and exit code:**
```bash
SCAN_EXIT=$?
echo "SCAN_EXIT=$SCAN_EXIT"
```
**Exit codes:**
- 0 = PASS (no critical/high issues)
- 1 = HIGH issues found
- 2 = CRITICAL issues found
### Step 2: Dependency Audit [MANDATORY unless --quick]
```bash
echo "=== Dependency Audit ==="
npm audit --json 2>/dev/null || echo '{"vulnerabilities":{}}'
```
**Parse npm audit results:**
- Count critical, high, moderate, low vulnerabilities
- List affected packages and versions
- Note if fixes available (`npm audit fix`)
### Step 3: Deep Analysis [FULL mode only]
For each CRITICAL/HIGH finding from scanner:
#### 3.1 Data Flow Tracing
Use Task agent with security-engineer subagent:
```
Analyze data flow for vulnerability at [file:line].
Trace user input from source to sink.
Identify all potential attack vectors.
Assess exploitability and impact.
```
#### 3.2 Attack Vector Analysis
For each vulnerability type:
- SQL Injection → Check if input reaches query without sanitization
- XSS → Check if input reaches DOM without encoding
- Command Injection → Check if input reaches shell without escaping
- Path Traversal → Check if input reaches file system without validation
### Step 4: Configuration Review [FULL mode only]
#### 4.1 CORS Configuration
```bash
grep -rn "cors\|Access-Control" app/ src/ pages/ --include="*.ts" --include="*.tsx" --include="*.js"
```
Check for:
- Wildcard origins (`*`)
- Credentials with permissive origins
- Missing CORS on sensitive endpoints
#### 4.2 Security Headers
```bash
grep -rn "helmet\|Content-Security-Policy\|X-Frame-Options\|X-XSS-Protection" . --include="*.ts" --include="*.js"
```
Check for:
- Helmet middleware usage
- CSP configuration
- X-Frame-Options
- X-Content-Type-Options
#### 4.3 Authentication Configuration
```bash
grep -rn "jwt\|session\|auth\|cookie" app/ src/ pages/ --include="*.ts" --include="*.tsx"
```
Check for:
- JWT algorithm (avoid 'none', prefer RS256)
- Session configuration
- Cookie flags (httpOnly, secure, sameSite)
#### 4.4 Environment Variables
```bash
# Check .env files are gitignored
cat .gitignore 2>/dev/null | grep -E "\.env"
# Check for env var usage
grep -rn "process\.env\." app/ src/ --include="*.ts" --include="*.tsx" | head -20
```
### Step 5: Manual Review Checklist [FULL mode only]
Read each file modified in current workflow and verify:
**Input Validation**
- [ ] All user inputs validated
- [ ] Type checking enforced
- [ ] Length limits applied
- [ ] Format validation (email, URL, etc.)
**Output Encoding**
- [ ] HTML encoding for DOM insertion
- [ ] URL encoding for URLs
- [ ] JSON encoding for API responses
**Database Security**
- [ ] Parameterized queries used
- [ ] No string concatenation in queries
- [ ] Proper ORM usage
**Authentication/Authorization**
- [ ] Auth checks on protected routes
- [ ] Role-based access control
- [ ] Session validation
**Error Handling**
- [ ] Generic error messages to users
- [ ] No stack traces in production
- [ ] No sensitive data in logs
### Step 6: Generate Security Report [MANDATORY]
**MUST output this exact format:**
```
+======================================================================+
| SECURITY AUDIT REPORT |
+======================================================================+
| Mode: QUICK / STANDARD / FULL |
| Date: [current date] |
| Project: [project name from package.json] |
+======================================================================+
| RISK ASSESSMENT |
+----------------------------------------------------------------------+
| Overall Risk: CRITICAL / HIGH / MEDIUM / LOW / PASS |
| |
| Static Analysis: X issues (C:X H:X M:X L:X) |
| Dependencies: X vulnerabilities |
| Configuration: X concerns |
+======================================================================+
| CRITICAL ISSUES (Immediate Action Required) |
+----------------------------------------------------------------------+
| [1] [CATEGORY] Title |
| Location: file:line |
| CWE: CWE-XXX |
| OWASP: A0X:2021-Category |
| Evidence: [code snippet] |
| Impact: [description of potential attack] |
| Fix: [specific remediation steps] |
| |
| [2] ... |
+======================================================================+
| HIGH ISSUES (Fix Before Production) |
+----------------------------------------------------------------------+
| [3] ... |
+======================================================================+
| MEDIUM ISSUES (Should Fix) |
+----------------------------------------------------------------------+
| [4] ... |
+======================================================================+
| DEPENDENCY VULNERABILITIES |
+----------------------------------------------------------------------+
| Package Version Severity Fix Available |
| lodash 4.17.20 HIGH npm audit fix |
| axios 0.21.0 MEDIUM npm audit fix |
+======================================================================+
| CONFIGURATION CONCERNS |
+----------------------------------------------------------------------+
| - CORS: Wildcard origin detected in src/middleware.ts |
| - Session: Missing httpOnly flag on auth cookie |
| - Headers: No CSP header configured |
+======================================================================+
| REMEDIATION PRIORITY |
+----------------------------------------------------------------------+
| 1. [CRITICAL] Rotate exposed API key in src/lib/api.ts |
| 2. [CRITICAL] Fix SQL injection in app/api/users/route.ts |
| 3. [HIGH] Update lodash to 4.17.21 |
| 4. [HIGH] Add input validation to user registration |
| 5. [MEDIUM] Configure CSP headers |
+======================================================================+
| VERDICT |
+----------------------------------------------------------------------+
| FAIL - X critical issues must be fixed before deployment |
| or |
| PASS - No blocking security issues found |
+======================================================================+
```
---
## VERDICT DETERMINATION
### FAIL Conditions
- Any CRITICAL issue found
- 3+ HIGH issues found
- Critical npm vulnerabilities without fix
- Exposed secrets or credentials
### PASS WITH WARNINGS
- Only MEDIUM/LOW issues
- All HIGH issues have accepted risk
- Dependencies have fixes available
### PASS
- No CRITICAL/HIGH issues
- Dependencies up to date
- Configurations reviewed
---
## POST-AUDIT ACTIONS
### If FAIL:
```
SECURITY AUDIT FAILED
Blocking issues must be fixed:
1. [List critical issues]
For each issue:
/workflow:frontend <task_id> - if frontend issue
/workflow:backend <task_id> - if backend issue
Then re-run: /workflow:security
```
### If PASS:
```
SECURITY AUDIT PASSED
Proceed with: /workflow:review --auto
```
---
## USAGE EXAMPLES
```bash
# Quick scan (automated scanner only)
/workflow:security --quick
# Standard scan (scanner + dependencies)
/workflow:security
# Full audit (all checks)
/workflow:security --full
# Filter by severity
/workflow:security --severity high
# JSON output for CI/CD
/workflow:security --json
```
---
## INTEGRATION WITH CI/CD
### Pre-commit Hook
```bash
python3 skills/guardrail-orchestrator/scripts/security_scan.py \
--project-dir . --severity HIGH --strict
```
### GitHub Actions
```yaml
- name: Security Scan
run: |
python3 skills/guardrail-orchestrator/scripts/security_scan.py \
--project-dir . --json > security-report.json
if [ $? -ne 0 ]; then
echo "Security issues found!"
cat security-report.json
exit 1
fi
```
---
## ENFORCEMENT CHECKLIST
Before completing this command, verify:
- [ ] Automated scanner executed
- [ ] All categories analyzed
- [ ] Dependencies audited (unless --quick)
- [ ] Structured report output
- [ ] Remediation guidance provided
- [ ] Clear verdict stated

1542
.claude/commands/workflow/spawn.md Normal file
View File

File diff suppressed because it is too large Load Diff

119
.claude/commands/workflow/status.md Normal file
View File

@ -0,0 +1,119 @@
---
description: Show workflow status and task summary
allowed-tools: Read, Bash
---
# Workflow Status
Display current workflow status and task breakdown.
## Steps
### 1. Check Active Workflow
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py status
```
If active workflow exists, display workflow state.
If no workflow, continue with manual task scan.
### 2. Read Project Manifest
Check `project_manifest.json` for:
- Current phase
- Entity counts by status
### 3. Scan Tasks
Get the version-specific tasks directory:
```bash
TASKS_DIR=$(python3 skills/guardrail-orchestrator/scripts/version_manager.py tasks-dir)
```
Read all `$TASKS_DIR/*.yml` files and count by:
- Status (pending, in_progress, review, approved, completed, blocked)
- Agent (frontend, backend, reviewer)
- Type (create, update, delete, review)
### 4. Display Summary
```
╔══════════════════════════════════════════════════════════════╗
║ WORKFLOW STATUS ║
╠══════════════════════════════════════════════════════════════╣
║ Active Workflow: <workflow_id> | None ║
║ Feature: <feature_name> ║
║ Phase: <current_phase> ║
╠══════════════════════════════════════════════════════════════╣
║ APPROVAL GATES ║
║ 🛑 Design: <pending|approved|rejected> ║
║ 🛑 Implementation: <pending|approved|rejected> ║
╠══════════════════════════════════════════════════════════════╣
║ TASKS BY STATUS ║
║ ⏳ Pending: X ║
║ 🔄 In Progress: X ║
║ 🔍 Review: X ║
║ ✅ Approved: X ║
║ ✓ Completed: X ║
║ 🚫 Blocked: X ║
╠══════════════════════════════════════════════════════════════╣
║ TASKS BY AGENT ║
║ 🎨 Frontend: X pending, X completed ║
║ ⚙️ Backend: X pending, X completed ║
║ 🔍 Reviewer: X pending ║
╠══════════════════════════════════════════════════════════════╣
║ NEXT ACTIONS ║
║ /workflow:frontend --next (X tasks available) ║
║ /workflow:backend --next (X tasks available) ║
║ /workflow:review --next (X tasks to review) ║
║ /workflow:resume (continue workflow) ║
╚══════════════════════════════════════════════════════════════╝
```
### 5. Show Design Visualization
**If in DESIGNING or AWAITING_DESIGN_APPROVAL phase**, display visual design:
```bash
python3 skills/guardrail-orchestrator/scripts/visualize_design.py --manifest project_manifest.json
```
This shows:
- 📱 Page flow diagram
- 📄 Page details with components
- 🧩 Component hierarchy
- 🔌 API endpoints
- 🔄 Data flow architecture
### 5b. Show Implementation Visualization
**If in REVIEWING, SECURITY_REVIEW, or AWAITING_IMPL_APPROVAL phase**, display what was built:
```bash
python3 skills/guardrail-orchestrator/scripts/visualize_implementation.py --manifest project_manifest.json
```
This shows:
- 📱 Page structure with routes
- 🧩 Component hierarchy and relationships
- 🔌 API endpoints with HTTP methods
- 📊 Implementation statistics (lines, hooks, types)
- 🌳 Component tree view
### 6. List Pending Tasks
Show table of tasks ready to work on:
| Task ID | Type | Agent | Priority | Dependencies |
|---------|------|-------|----------|--------------|
### 7. Show Approval Instructions
**If AWAITING_DESIGN_APPROVAL**:
```
🛑 Design approval required. Review the entities and tasks, then:
- Approve: /workflow:approve design
- Reject: /workflow:reject design "reason"
```
**If AWAITING_IMPL_APPROVAL**:
```
🛑 Implementation approval required. Review the code, then:
- Approve: /workflow:approve implementation
- Reject: /workflow:reject implementation "reason"
```

4
.claude/eureka-factory.yaml Normal file
View File

@ -0,0 +1,4 @@
api_key: pk_user_8d080a1a699dc2a1769ca99ded0ca39fa80324b8713cf55ea7fecc1c372379a6
project_id: ""
repo_id: ""
app_id: cmjb04ana0001qp0tijyy9emq

225
.claude/settings.json Normal file
View File

@ -0,0 +1,225 @@
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_bash.py\" --command \"$TOOL_INPUT_COMMAND\""
}
]
},
{
"matcher": "Task",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation task --input \"$TOOL_INPUT\""
}
]
},
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation write --file \"$TOOL_INPUT_FILE_PATH\""
},
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_FILE_PATH\""
}
]
},
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation edit --file \"$TOOL_INPUT_FILE_PATH\""
},
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_FILE_PATH\""
}
]
},
{
"matcher": "MultiEdit",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation edit --file \"$TOOL_INPUT_FILE_PATH\""
},
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_FILE_PATH\""
}
]
},
{
"matcher": "NotebookEdit",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation edit --file \"$TOOL_INPUT_NOTEBOOK_PATH\""
},
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_NOTEBOOK_PATH\""
}
]
},
{
"matcher": "mcp__serena__create_text_file",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation write --input \"$TOOL_INPUT\""
},
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_FILE_PATH\""
}
]
},
{
"matcher": "mcp__serena__replace_content",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation edit --input \"$TOOL_INPUT\""
},
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_FILE_PATH\""
}
]
},
{
"matcher": "mcp__serena__replace_symbol_body",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation edit --input \"$TOOL_INPUT\""
},
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_FILE_PATH\""
}
]
},
{
"matcher": "mcp__morphllm-fast-apply__write_file",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation write --input \"$TOOL_INPUT\""
},
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_FILE_PATH\""
}
]
},
{
"matcher": "mcp__morphllm-fast-apply__tiny_edit_file",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation edit --input \"$TOOL_INPUT\""
},
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_FILE_PATH\""
}
]
},
{
"matcher": "mcp__filesystem__write_file",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation write --input \"$TOOL_INPUT\""
},
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_PATH\""
}
]
},
{
"matcher": "mcp__filesystem__edit_file",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation edit --input \"$TOOL_INPUT\""
},
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_PATH\""
}
]
},
{
"matcher": "mcp__filesystem__create_directory",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation write --input \"$TOOL_INPUT\""
}
]
},
{
"matcher": "mcp__filesystem__move_file",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/validate_workflow.py\" --operation write --input \"$TOOL_INPUT\""
}
]
}
],
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/post_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_FILE_PATH\""
}
]
},
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/post_write.py\" --manifest \"$CLAUDE_PROJECT_DIR/project_manifest.json\" --file \"$TOOL_INPUT_FILE_PATH\""
}
]
},
{
"matcher": "Task",
"hooks": [
{
"type": "command",
"command": "echo '🔄 Agent task completed. Verify outputs before proceeding.'"
}
]
}
],
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/skills/guardrail-orchestrator/scripts/workflow_manager.py\" status 2>/dev/null || echo '🛡️ Session complete (no active workflow)'"
}
]
}
]
}
}

16
.mcp.json Normal file
View File

@ -0,0 +1,16 @@
{
"mcpServers": {
"eureka-docs": {
"command": "npx",
"args": ["eureka-docs-server"],
"env": {}
},
"eureka-imagen": {
"command": "npx",
"args": ["eureka-imagen-server"],
"env": {
"IMAGEROUTER_API_KEY": "${IMAGEROUTER_API_KEY}"
}
}
}
}

1182
CLAUDE.md Normal file
View File

File diff suppressed because it is too large Load Diff

152
skills/documentation-generator/agents/doc-writer.yml Normal file
View File

@ -0,0 +1,152 @@
# Documentation Writer Agent
# Specialized agent for generating dual-audience documentation
name: doc-writer
role: Documentation Specialist
description: |
Expert in creating comprehensive documentation that serves both technical
and non-technical audiences. Specializes in translating complex technical
concepts into accessible language while maintaining technical accuracy.
capabilities:
- Analyze project structure and extract key information
- Generate visual ASCII diagrams for architecture
- Write plain-language descriptions of technical features
- Create technical reference documentation
- Build glossaries for technical terms
- Structure documentation for multiple audience levels
allowed_tools:
- Read
- Write
- Edit
- Glob
- Grep
- Bash
blocked_tools:
- Task # Should not spawn sub-agents
allowed_files:
- "docs/**/*"
- "*.md"
- "package.json"
- "project_manifest.json"
- "tsconfig.json"
- "requirements.txt"
- "pyproject.toml"
- "Cargo.toml"
- "go.mod"
responsibilities:
- Analyze source code to understand functionality
- Extract API endpoints and document them
- Document components with props and usage
- Create ER diagrams for data models
- Write executive summaries for stakeholders
- Build glossaries for technical terms
- Generate quick reference cards
outputs:
- PROJECT_DOCUMENTATION.md (main documentation)
- QUICK_REFERENCE.md (one-page summary)
- API_REFERENCE.md (detailed API docs)
- COMPONENTS.md (component catalog)
- GLOSSARY.md (term definitions)
cannot_do:
- Modify source code
- Change project configuration
- Run tests or builds
- Deploy or publish
writing_principles:
non_technical:
- Lead with "What" and "Why", not "How"
- Use analogies and real-world comparisons
- Avoid acronyms; spell them out first time
- Use bullet points over paragraphs
- Include visual diagrams
- Focus on value and outcomes
technical:
- Include in collapsible <details> sections
- Provide code examples with syntax highlighting
- Reference file paths and line numbers
- Include type definitions and interfaces
- Link to source files
- Document edge cases and error handling
documentation_sections:
executive_summary:
audience: everyone
purpose: Project purpose, value proposition, key capabilities
format: Plain English, no jargon
architecture_overview:
audience: everyone
purpose: Visual system understanding
format: ASCII diagrams, technology tables
getting_started:
audience: semi-technical
purpose: Quick onboarding
format: Step-by-step with explanations
feature_guide:
audience: non-technical
purpose: Feature documentation
format: What/Why/How (simplified)
api_reference:
audience: developers
purpose: API documentation
format: Endpoints, schemas, examples
component_catalog:
audience: developers
purpose: UI component documentation
format: Props, events, usage examples
data_models:
audience: both
purpose: Data structure documentation
format: ER diagrams + plain descriptions
glossary:
audience: non-technical
purpose: Term definitions
format: Term -> Plain English definition
ascii_diagram_templates:
system_architecture: |
┌─────────────────────────────────────────────────────────┐
│ [System Name] │
├─────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ [Layer] │───▶│ [Layer] │───▶│ [Layer] │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────┘
entity_relationship: |
┌──────────────┐ ┌──────────────┐
│ [Entity] │ │ [Entity] │
├──────────────┤ ├──────────────┤
│ id (PK) │──────▶│ id (PK) │
│ field │ │ foreign_key │
└──────────────┘ └──────────────┘
data_flow: |
[Source] ──▶ [Process] ──▶ [Output]
│ │ │
▼ ▼ ▼
[Storage] [Transform] [Display]
quality_checklist:
- All referenced files exist
- All code examples are syntactically correct
- No broken internal links
- Technical details wrapped in <details>
- Plain English explanations for all features
- Glossary includes all technical terms used
- ASCII diagrams render correctly in markdown

274
skills/documentation-generator/schemas/documentation_output.yml Normal file
View File

@ -0,0 +1,274 @@
# Documentation Output Schema
# Defines the structure for generated documentation
version: "1.0"
description: Schema for dual-audience project documentation
output_files:
main_documentation:
filename: PROJECT_DOCUMENTATION.md
required: true
sections:
- executive_summary
- quick_start
- architecture_overview
- features
- for_developers
- glossary
quick_reference:
filename: QUICK_REFERENCE.md
required: true
sections:
- commands
- key_files
- api_endpoints
- environment_variables
api_reference:
filename: API_REFERENCE.md
required: false
condition: has_api_endpoints
sections:
- authentication
- endpoints_by_resource
- error_codes
- rate_limiting
components:
filename: COMPONENTS.md
required: false
condition: has_ui_components
sections:
- component_index
- component_details
- usage_examples
section_schemas:
executive_summary:
description: High-level project overview for all audiences
fields:
project_name:
type: string
required: true
tagline:
type: string
required: true
max_length: 100
description: One-line description in plain English
what_it_does:
type: string
required: true
description: 2-3 sentences, no technical jargon
who_its_for:
type: string
required: true
description: Target audience in plain English
key_capabilities:
type: array
items:
capability: string
description: string
min_items: 3
max_items: 8
quick_start:
description: Getting started guide for new users
fields:
prerequisites:
type: array
items:
tool: string
purpose: string # Plain English explanation
install_command: string
installation_steps:
type: array
items:
step: integer
command: string
explanation: string # What this does
basic_usage:
type: string
description: Simple example of how to use
architecture_overview:
description: Visual system architecture
fields:
system_diagram:
type: string
format: ascii_art
required: true
technology_stack:
type: array
items:
layer: string
technology: string
purpose: string # Plain English
directory_structure:
type: string
format: tree
required: true
features:
description: Feature documentation for all audiences
fields:
features:
type: array
items:
name: string
what_it_does: string # Plain English
how_to_use: string # Simple instructions
example: string # Code or usage example
technical_notes: string # For engineers, optional
api_endpoint:
description: Single API endpoint documentation
fields:
method:
type: enum
values: [GET, POST, PUT, PATCH, DELETE]
path:
type: string
pattern: "^/api/"
summary:
type: string
description: Plain English description
description:
type: string
description: Detailed explanation
authentication:
type: object
fields:
required: boolean
type: string # bearer, api_key, session
request:
type: object
fields:
content_type: string
body_schema: object
query_params: array
path_params: array
responses:
type: array
items:
status: integer
description: string
schema: object
examples:
type: array
items:
name: string
request: object
response: object
component:
description: UI component documentation
fields:
name:
type: string
pattern: "^[A-Z][a-zA-Z]*$" # PascalCase
path:
type: string
description:
type: string
description: Plain English purpose
props:
type: array
items:
name: string
type: string
required: boolean
default: any
description: string
events:
type: array
items:
name: string
payload: string
description: string
usage_example:
type: string
format: code
dependencies:
type: array
items: string
data_model:
description: Data model documentation
fields:
name:
type: string
description:
type: string
description: What data it represents (plain English)
table_name:
type: string
fields:
type: array
items:
name: string
type: string
description: string # Plain English
constraints: array
relations:
type: array
items:
type: enum
values: [has_one, has_many, belongs_to, many_to_many]
target: string
description: string
glossary_term:
description: Technical term definition
fields:
term:
type: string
required: true
definition:
type: string
required: true
description: Plain English definition
see_also:
type: array
items: string
description: Related terms
audience_markers:
non_technical:
indicator: "📖"
description: "For all readers"
technical:
indicator: "🔧"
description: "For developers"
wrapper: "<details><summary>🔧 Technical Details</summary>...content...</details>"
formatting_rules:
headings:
h1: "# Title"
h2: "## Section"
h3: "### Subsection"
code_blocks:
language_hints: required
max_lines: 30
tables:
alignment: left
max_columns: 5
diagrams:
format: ascii_art
max_width: 80
links:
internal: "[text](#anchor)"
external: "[text](url)"
file_reference: "`path/to/file`"
validation_rules:
- name: no_broken_links
description: All internal links must resolve
- name: code_syntax
description: All code blocks must be syntactically valid
- name: file_references
description: All referenced files must exist
- name: glossary_coverage
description: All technical terms must be in glossary
- name: diagram_rendering
description: ASCII diagrams must render correctly

272
skills/documentation-generator/schemas/project_analysis.yml Normal file
View File

@ -0,0 +1,272 @@
# Project Analysis Schema
# Defines the structure for project analysis output
version: "1.0"
description: Schema for analyzing project structure before documentation generation
project_analysis:
project:
type: object
required: true
fields:
name:
type: string
required: true
source: package.json/name or directory name
version:
type: string
required: false
source: package.json/version
description:
type: string
required: false
source: package.json/description or README.md first paragraph
type:
type: enum
values: [node, python, rust, go, java, dotnet, ruby, php, other]
detection:
node: package.json
python: requirements.txt, pyproject.toml, setup.py
rust: Cargo.toml
go: go.mod
java: pom.xml, build.gradle
dotnet: "*.csproj, *.sln"
ruby: Gemfile
php: composer.json
repository:
type: string
source: package.json/repository or .git/config
tech_stack:
type: object
required: true
fields:
language:
type: string
description: Primary programming language
framework:
type: string
description: Main application framework
detection:
next: "next" in dependencies
react: "react" in dependencies without "next"
vue: "vue" in dependencies
angular: "@angular/core" in dependencies
express: "express" in dependencies
fastapi: "fastapi" in requirements
django: "django" in requirements
flask: "flask" in requirements
rails: "rails" in Gemfile
database:
type: string
description: Database system if any
detection:
prisma: "@prisma/client" in dependencies
mongoose: "mongoose" in dependencies
typeorm: "typeorm" in dependencies
sequelize: "sequelize" in dependencies
sqlalchemy: "sqlalchemy" in requirements
ui_framework:
type: string
description: UI component framework if any
detection:
tailwind: "tailwindcss" in devDependencies
mui: "@mui/material" in dependencies
chakra: "@chakra-ui/react" in dependencies
shadcn: "shadcn" patterns in components
key_dependencies:
type: array
items:
name: string
version: string
purpose: string # Plain English explanation
categorization:
core: Framework, runtime dependencies
database: ORM, database clients
auth: Authentication libraries
ui: UI component libraries
testing: Test frameworks
build: Build tools, bundlers
utility: Helper libraries
structure:
type: object
required: true
fields:
source_dir:
type: string
description: Main source code directory
detection:
- src/
- app/
- lib/
- source/
directories:
type: array
items:
path: string
purpose: string # Plain English description
file_count: integer
key_files: array
common_mappings:
src/components: "UI components"
src/pages: "Application pages/routes"
src/api: "API route handlers"
src/lib: "Utility functions and shared code"
src/hooks: "Custom React hooks"
src/context: "React context providers"
src/store: "State management"
src/types: "TypeScript type definitions"
src/styles: "Global styles and themes"
prisma/: "Database schema and migrations"
public/: "Static assets"
tests/: "Test files"
__tests__/: "Test files (Jest convention)"
features:
type: array
description: Main features/capabilities of the project
items:
name: string
description: string # Plain English
technical_notes: string # For engineers
files: array # Key file paths
detection_patterns:
authentication:
keywords: [auth, login, logout, session, jwt, oauth]
files: ["**/auth/**", "**/login/**"]
user_management:
keywords: [user, profile, account, register, signup]
files: ["**/user/**", "**/users/**"]
api:
keywords: [api, endpoint, route, handler]
files: ["**/api/**", "**/routes/**"]
database:
keywords: [model, entity, schema, migration, prisma]
files: ["**/models/**", "**/prisma/**"]
file_upload:
keywords: [upload, file, storage, s3, blob]
files: ["**/upload/**", "**/storage/**"]
search:
keywords: [search, filter, query]
files: ["**/search/**"]
notifications:
keywords: [notification, email, sms, push]
files: ["**/notification/**", "**/email/**"]
components:
type: array
description: UI components found in the project
items:
id: string # component_<name>
name: string # PascalCase
path: string
description: string
props: string # Props summary
dependencies: array # Imported components
detection:
react: "export (default )?(function|const) [A-Z]"
vue: "<template>.*<script>"
angular: "@Component"
api_endpoints:
type: array
description: API endpoints found in the project
items:
method: enum [GET, POST, PUT, PATCH, DELETE]
path: string
handler_file: string
description: string
technical_notes: string
detection:
next_app_router: "app/api/**/route.ts exports GET, POST, etc."
next_pages_router: "pages/api/**/*.ts"
express: "router.get/post/put/delete"
fastapi: "@app.get/post/put/delete"
data_models:
type: array
description: Data models/entities found
items:
name: string
description: string # Plain English
fields: array
relations: array
detection:
prisma: "model [A-Z][a-z]+ {"
typeorm: "@Entity"
mongoose: "new Schema"
sqlalchemy: "class.*Base"
glossary_terms:
type: array
description: Technical terms that need definitions
items:
term: string
definition: string # Plain English
auto_detection:
- Acronyms (all caps words)
- Framework-specific terms
- Domain-specific terminology
- Technical jargon from code comments
analysis_process:
steps:
1_identify_type:
description: Determine project type from config files
files_to_check:
- package.json
- requirements.txt
- pyproject.toml
- Cargo.toml
- go.mod
- pom.xml
2_scan_structure:
description: Map directory structure
actions:
- List all directories
- Count files per directory
- Identify purpose from names
3_extract_metadata:
description: Get project metadata
sources:
- package.json (name, version, description, dependencies)
- README.md (description, usage)
- project_manifest.json (if exists)
4_identify_features:
description: Detect main features
methods:
- Keyword scanning in file names
- Pattern matching in code
- Directory structure analysis
5_map_components:
description: Catalog UI components
methods:
- Scan component directories
- Extract props from TypeScript
- Find usage patterns
6_document_apis:
description: Document API endpoints
methods:
- Scan API routes
- Extract request/response schemas
- Find authentication requirements
7_model_data:
description: Document data models
methods:
- Parse Prisma schema
- Extract TypeORM entities
- Find Mongoose schemas
8_collect_terms:
description: Build glossary
methods:
- Extract acronyms
- Find domain terms
- Look for jargon in comments

489
skills/documentation-generator/scripts/analyze_project.py Normal file
View File

@ -0,0 +1,489 @@
#!/usr/bin/env python3
"""
Project Analyzer for Documentation Generation
Analyzes project structure and outputs YAML for documentation generation.
"""
import os
import sys
import json
import re
from pathlib import Path
from typing import Dict, List, Any, Optional
from datetime import datetime
# Try to import yaml, but provide fallback
try:
import yaml
except ImportError:
yaml = None
def detect_project_type(root_path: Path) -> Dict[str, Any]:
"""Detect project type from config files."""
indicators = {
'node': ['package.json'],
'python': ['requirements.txt', 'pyproject.toml', 'setup.py', 'Pipfile'],
'rust': ['Cargo.toml'],
'go': ['go.mod'],
'java': ['pom.xml', 'build.gradle', 'build.gradle.kts'],
'dotnet': list(root_path.glob('*.csproj')) + list(root_path.glob('*.sln')),
'ruby': ['Gemfile'],
'php': ['composer.json'],
}
for lang, files in indicators.items():
if isinstance(files, list) and isinstance(files[0], str):
for f in files:
if (root_path / f).exists():
return {'type': lang, 'config_file': f}
elif files: # Already Path objects from glob
return {'type': lang, 'config_file': str(files[0].name)}
return {'type': 'other', 'config_file': None}
def parse_package_json(root_path: Path) -> Dict[str, Any]:
"""Parse package.json for Node.js projects."""
pkg_path = root_path / 'package.json'
if not pkg_path.exists():
return {}
with open(pkg_path, 'r') as f:
data = json.load(f)
deps = data.get('dependencies', {})
dev_deps = data.get('devDependencies', {})
# Detect framework
framework = None
if 'next' in deps:
framework = 'Next.js'
elif 'react' in deps:
framework = 'React'
elif 'vue' in deps:
framework = 'Vue.js'
elif '@angular/core' in deps:
framework = 'Angular'
elif 'express' in deps:
framework = 'Express'
elif 'fastify' in deps:
framework = 'Fastify'
# Detect database
database = None
if '@prisma/client' in deps:
database = 'Prisma (PostgreSQL/MySQL/SQLite)'
elif 'mongoose' in deps:
database = 'MongoDB (Mongoose)'
elif 'typeorm' in deps:
database = 'TypeORM'
elif 'sequelize' in deps:
database = 'Sequelize'
# Detect UI framework
ui_framework = None
if 'tailwindcss' in dev_deps or 'tailwindcss' in deps:
ui_framework = 'Tailwind CSS'
if '@mui/material' in deps:
ui_framework = 'Material UI'
elif '@chakra-ui/react' in deps:
ui_framework = 'Chakra UI'
# Categorize dependencies
key_deps = []
dep_categories = {
'core': ['react', 'next', 'vue', 'angular', 'express', 'fastify'],
'database': ['@prisma/client', 'mongoose', 'typeorm', 'sequelize', 'pg', 'mysql2'],
'auth': ['next-auth', 'passport', 'jsonwebtoken', '@auth0/nextjs-auth0'],
'ui': ['@mui/material', '@chakra-ui/react', 'antd', '@radix-ui'],
'state': ['zustand', 'redux', '@reduxjs/toolkit', 'recoil', 'jotai'],
'testing': ['jest', 'vitest', '@testing-library/react', 'cypress'],
}
for dep, version in {**deps, **dev_deps}.items():
category = 'utility'
for cat, patterns in dep_categories.items():
if any(p in dep for p in patterns):
category = cat
break
if category != 'utility' or dep in ['axios', 'zod', 'date-fns', 'lodash']:
key_deps.append({
'name': dep,
'version': version.replace('^', '').replace('~', ''),
'category': category,
'purpose': get_dep_purpose(dep)
})
return {
'name': data.get('name', 'Unknown'),
'version': data.get('version', '0.0.0'),
'description': data.get('description', ''),
'framework': framework,
'database': database,
'ui_framework': ui_framework,
'key_dependencies': key_deps[:15], # Limit to 15 most important
'scripts': data.get('scripts', {})
}
def get_dep_purpose(dep_name: str) -> str:
"""Get plain English purpose for common dependencies."""
purposes = {
'react': 'UI component library',
'next': 'Full-stack React framework',
'vue': 'Progressive UI framework',
'express': 'Web server framework',
'fastify': 'High-performance web framework',
'@prisma/client': 'Database ORM and query builder',
'mongoose': 'MongoDB object modeling',
'typeorm': 'TypeScript ORM',
'sequelize': 'SQL ORM',
'next-auth': 'Authentication for Next.js',
'passport': 'Authentication middleware',
'jsonwebtoken': 'JWT token handling',
'@mui/material': 'Material Design components',
'@chakra-ui/react': 'Accessible component library',
'tailwindcss': 'Utility-first CSS framework',
'zustand': 'State management',
'redux': 'Predictable state container',
'@reduxjs/toolkit': 'Redux development toolkit',
'axios': 'HTTP client',
'zod': 'Schema validation',
'date-fns': 'Date utility functions',
'lodash': 'Utility functions',
'jest': 'Testing framework',
'vitest': 'Fast unit testing',
'@testing-library/react': 'React component testing',
'cypress': 'End-to-end testing',
}
return purposes.get(dep_name, 'Utility library')
def scan_directory_structure(root_path: Path) -> Dict[str, Any]:
"""Scan and categorize directory structure."""
ignore_dirs = {
'node_modules', '.git', '.next', '__pycache__', 'venv',
'.venv', 'dist', 'build', '.cache', 'coverage', '.turbo'
}
common_purposes = {
'src': 'Main source code directory',
'app': 'Application code (Next.js App Router)',
'pages': 'Page components (Next.js Pages Router)',
'components': 'Reusable UI components',
'lib': 'Shared utilities and libraries',
'utils': 'Utility functions',
'hooks': 'Custom React hooks',
'context': 'React context providers',
'store': 'State management',
'styles': 'CSS and styling',
'types': 'TypeScript type definitions',
'api': 'API route handlers',
'services': 'Business logic services',
'models': 'Data models/entities',
'prisma': 'Database schema and migrations',
'public': 'Static assets',
'tests': 'Test files',
'__tests__': 'Jest test files',
'test': 'Test files',
'spec': 'Test specifications',
'docs': 'Documentation',
'scripts': 'Build and utility scripts',
'config': 'Configuration files',
}
directories = []
source_dir = None
# Find main source directory
for candidate in ['src', 'app', 'lib', 'source']:
if (root_path / candidate).is_dir():
source_dir = candidate
break
# Scan directories
for item in sorted(root_path.iterdir()):
if item.is_dir() and item.name not in ignore_dirs and not item.name.startswith('.'):
file_count = sum(1 for _ in item.rglob('*') if _.is_file())
key_files = [
f.name for f in item.iterdir()
if f.is_file() and f.suffix in ['.ts', '.tsx', '.js', '.jsx', '.py', '.rs', '.go']
][:5]
directories.append({
'path': item.name,
'purpose': common_purposes.get(item.name, 'Project directory'),
'file_count': file_count,
'key_files': key_files
})
return {
'source_dir': source_dir or '.',
'directories': directories
}
def detect_features(root_path: Path) -> List[Dict[str, Any]]:
"""Detect main features from code patterns."""
features = []
feature_patterns = {
'authentication': {
'keywords': ['auth', 'login', 'logout', 'session', 'jwt', 'oauth'],
'description': 'User authentication and session management',
'technical_notes': 'Handles user login, logout, and session tokens'
},
'user_management': {
'keywords': ['user', 'profile', 'account', 'register', 'signup'],
'description': 'User account creation and profile management',
'technical_notes': 'CRUD operations for user data'
},
'api': {
'keywords': ['api', 'endpoint', 'route'],
'description': 'REST API endpoints for data operations',
'technical_notes': 'HTTP handlers for client-server communication'
},
'database': {
'keywords': ['prisma', 'model', 'entity', 'schema', 'migration'],
'description': 'Database storage and data persistence',
'technical_notes': 'ORM-based data layer with migrations'
},
'file_upload': {
'keywords': ['upload', 'file', 'storage', 's3', 'blob'],
'description': 'File upload and storage functionality',
'technical_notes': 'Handles file uploads and cloud storage'
},
'search': {
'keywords': ['search', 'filter', 'query'],
'description': 'Search and filtering capabilities',
'technical_notes': 'Full-text search or database queries'
},
}
# Scan for features
all_files = list(root_path.rglob('*.ts')) + list(root_path.rglob('*.tsx')) + \
list(root_path.rglob('*.js')) + list(root_path.rglob('*.jsx'))
file_names = [f.stem.lower() for f in all_files]
file_paths = [str(f.relative_to(root_path)).lower() for f in all_files]
for feature_name, config in feature_patterns.items():
found_files = []
for keyword in config['keywords']:
found_files.extend([
str(f.relative_to(root_path)) for f in all_files
if keyword in str(f).lower()
])
if found_files:
features.append({
'name': feature_name.replace('_', ' ').title(),
'description': config['description'],
'technical_notes': config['technical_notes'],
'files': list(set(found_files))[:5]
})
return features
def find_components(root_path: Path) -> List[Dict[str, Any]]:
"""Find UI components in the project."""
components = []
component_dirs = ['components', 'src/components', 'app/components']
for comp_dir in component_dirs:
comp_path = root_path / comp_dir
if comp_path.exists():
for file in comp_path.rglob('*.tsx'):
if file.name.startswith('_') or file.name == 'index.tsx':
continue
name = file.stem
if name[0].isupper(): # Component names are PascalCase
components.append({
'id': f'component_{name.lower()}',
'name': name,
'path': str(file.relative_to(root_path)),
'description': f'{name} component',
'props': 'See source file'
})
return components[:20] # Limit to 20 components
def find_api_endpoints(root_path: Path) -> List[Dict[str, Any]]:
"""Find API endpoints in the project."""
endpoints = []
# Next.js App Router: app/api/**/route.ts
api_dir = root_path / 'app' / 'api'
if api_dir.exists():
for route_file in api_dir.rglob('route.ts'):
path_parts = route_file.parent.relative_to(api_dir).parts
api_path = '/api/' + '/'.join(path_parts)
# Read file to detect methods
content = route_file.read_text()
methods = []
for method in ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']:
if f'export async function {method}' in content or f'export function {method}' in content:
methods.append(method)
for method in methods:
endpoints.append({
'method': method,
'path': api_path.replace('[', ':').replace(']', ''),
'handler_file': str(route_file.relative_to(root_path)),
'description': f'{method} {api_path}',
'technical_notes': 'Next.js App Router endpoint'
})
# Next.js Pages Router: pages/api/**/*.ts
pages_api = root_path / 'pages' / 'api'
if pages_api.exists():
for api_file in pages_api.rglob('*.ts'):
path_parts = api_file.relative_to(pages_api).with_suffix('').parts
api_path = '/api/' + '/'.join(path_parts)
endpoints.append({
'method': 'MULTIPLE',
'path': api_path.replace('[', ':').replace(']', ''),
'handler_file': str(api_file.relative_to(root_path)),
'description': f'API endpoint at {api_path}',
'technical_notes': 'Next.js Pages Router endpoint'
})
return endpoints
def find_data_models(root_path: Path) -> List[Dict[str, Any]]:
"""Find data models in the project."""
models = []
# Prisma schema
prisma_schema = root_path / 'prisma' / 'schema.prisma'
if prisma_schema.exists():
content = prisma_schema.read_text()
model_pattern = re.compile(r'model\s+(\w+)\s*\{([^}]+)\}', re.MULTILINE)
for match in model_pattern.finditer(content):
model_name = match.group(1)
model_body = match.group(2)
# Extract fields
fields = []
for line in model_body.strip().split('\n'):
line = line.strip()
if line and not line.startswith('@@') and not line.startswith('//'):
parts = line.split()
if len(parts) >= 2:
fields.append({
'name': parts[0],
'type': parts[1],
'description': f'{parts[0]} field'
})
models.append({
'name': model_name,
'description': f'{model_name} data model',
'fields': fields[:10] # Limit fields
})
return models
def collect_glossary_terms(features: List, components: List, endpoints: List) -> List[Dict[str, str]]:
"""Collect technical terms that need definitions."""
common_terms = {
'API': 'Application Programming Interface - a way for different software to communicate',
'REST': 'Representational State Transfer - a standard way to design web APIs',
'Component': 'A reusable piece of the user interface',
'Endpoint': 'A specific URL that the application responds to',
'ORM': 'Object-Relational Mapping - connects code to database tables',
'JWT': 'JSON Web Token - a secure way to transmit user identity',
'CRUD': 'Create, Read, Update, Delete - basic data operations',
'Props': 'Properties passed to a component to customize it',
'State': 'Data that can change and affects what users see',
'Hook': 'A way to add features to React components',
'Migration': 'A controlled change to database structure',
'Schema': 'The structure/shape of data',
'Route': 'A URL path that maps to specific functionality',
'Handler': 'Code that responds to a specific request',
}
return [{'term': k, 'definition': v} for k, v in common_terms.items()]
def generate_analysis(root_path: Path) -> Dict[str, Any]:
"""Generate complete project analysis."""
project_info = detect_project_type(root_path)
pkg_info = parse_package_json(root_path) if project_info['type'] == 'node' else {}
structure = scan_directory_structure(root_path)
features = detect_features(root_path)
components = find_components(root_path)
endpoints = find_api_endpoints(root_path)
models = find_data_models(root_path)
glossary = collect_glossary_terms(features, components, endpoints)
return {
'analysis_timestamp': datetime.now().isoformat(),
'project': {
'name': pkg_info.get('name', root_path.name),
'version': pkg_info.get('version', '0.0.0'),
'description': pkg_info.get('description', ''),
'type': project_info['type'],
},
'tech_stack': {
'language': 'TypeScript' if project_info['type'] == 'node' else project_info['type'],
'framework': pkg_info.get('framework'),
'database': pkg_info.get('database'),
'ui_framework': pkg_info.get('ui_framework'),
'key_dependencies': pkg_info.get('key_dependencies', []),
},
'structure': structure,
'features': features,
'components': components,
'api_endpoints': endpoints,
'data_models': models,
'glossary_terms': glossary,
}
def output_yaml(data: Dict[str, Any], output_path: Optional[Path] = None):
"""Output analysis as YAML."""
if yaml:
output = yaml.dump(data, default_flow_style=False, allow_unicode=True, sort_keys=False)
else:
# Fallback to JSON if yaml not available
output = json.dumps(data, indent=2)
if output_path:
output_path.write_text(output)
print(f"Analysis written to: {output_path}")
else:
print(output)
def main():
"""Main entry point."""
root_path = Path.cwd()
if len(sys.argv) > 1:
root_path = Path(sys.argv[1])
if not root_path.exists():
print(f"Error: Path does not exist: {root_path}", file=sys.stderr)
sys.exit(1)
output_path = None
if len(sys.argv) > 2:
output_path = Path(sys.argv[2])
analysis = generate_analysis(root_path)
output_yaml(analysis, output_path)
if __name__ == '__main__':
main()

491
skills/documentation-generator/scripts/generate_html.py Normal file
View File

@ -0,0 +1,491 @@
#!/usr/bin/env python3
"""
HTML Documentation Generator
Generates beautiful HTML documentation from project analysis.
"""
import os
import sys
import json
import re
from pathlib import Path
from datetime import datetime
from typing import Dict, List, Any, Optional
# Try to import yaml
try:
import yaml
except ImportError:
yaml = None
def load_template(template_path: Path) -> str:
"""Load the HTML template."""
with open(template_path, 'r', encoding='utf-8') as f:
return f.read()
def load_analysis(analysis_path: Path) -> Dict[str, Any]:
"""Load project analysis from YAML or JSON."""
with open(analysis_path, 'r', encoding='utf-8') as f:
content = f.read()
if yaml and (analysis_path.suffix in ['.yml', '.yaml']):
return yaml.safe_load(content)
return json.loads(content)
def escape_html(text: str) -> str:
"""Escape HTML special characters."""
if not text:
return ''
return (str(text)
.replace('&', '&amp;')
.replace('<', '&lt;')
.replace('>', '&gt;')
.replace('"', '&quot;')
.replace("'", '&#39;'))
def generate_capabilities_html(capabilities: List[Dict]) -> str:
"""Generate HTML for capabilities cards."""
icons = ['✨', '⚡', '🔐', '📊', '🚀', '💡', '🎯', '🔧']
html_parts = []
for i, cap in enumerate(capabilities[:8]):
icon = icons[i % len(icons)]
html_parts.append(f'''
<div class="card">
<div class="card-header">
<div class="card-icon">{icon}</div>
<div class="card-title">{escape_html(cap.get('capability', cap.get('name', 'Feature')))}</div>
</div>
<p>{escape_html(cap.get('description', ''))}</p>
</div>''')
return '\n'.join(html_parts)
def generate_prerequisites_html(prerequisites: List[Dict]) -> str:
"""Generate HTML for prerequisites table rows."""
html_parts = []
for prereq in prerequisites:
tool = prereq.get('tool', prereq.get('name', ''))
purpose = prereq.get('purpose', prereq.get('description', ''))
html_parts.append(f'''
<tr>
<td><code>{escape_html(tool)}</code></td>
<td>{escape_html(purpose)}</td>
</tr>''')
return '\n'.join(html_parts) if html_parts else '''
<tr>
<td><code>Node.js</code></td>
<td>JavaScript runtime environment</td>
</tr>'''
def generate_tech_stack_html(tech_stack: Dict) -> str:
"""Generate HTML for technology stack table rows."""
html_parts = []
stack_items = [
('Language', tech_stack.get('language')),
('Framework', tech_stack.get('framework')),
('Database', tech_stack.get('database')),
('UI Framework', tech_stack.get('ui_framework')),
]
purposes = {
'TypeScript': 'Type-safe JavaScript for better code quality',
'JavaScript': 'Programming language for web applications',
'Python': 'General-purpose programming language',
'Next.js': 'Full-stack React framework with SSR',
'React': 'Component-based UI library',
'Vue.js': 'Progressive JavaScript framework',
'Express': 'Minimal web server framework',
'Prisma': 'Type-safe database ORM',
'MongoDB': 'NoSQL document database',
'PostgreSQL': 'Relational database',
'Tailwind CSS': 'Utility-first CSS framework',
'Material UI': 'React component library',
}
for layer, tech in stack_items:
if tech:
purpose = purposes.get(tech, f'{tech} for {layer.lower()}')
html_parts.append(f'''
<tr>
<td>{escape_html(layer)}</td>
<td><span class="badge badge-primary">{escape_html(tech)}</span></td>
<td>{escape_html(purpose)}</td>
</tr>''')
# Add key dependencies
for dep in tech_stack.get('key_dependencies', [])[:5]:
html_parts.append(f'''
<tr>
<td>Dependency</td>
<td><span class="badge badge-info">{escape_html(dep.get('name', ''))}</span></td>
<td>{escape_html(dep.get('purpose', ''))}</td>
</tr>''')
return '\n'.join(html_parts)
def generate_directory_structure(structure: Dict) -> str:
"""Generate directory structure text."""
lines = ['project/']
for i, dir_info in enumerate(structure.get('directories', [])[:10]):
prefix = '└── ' if i == len(structure.get('directories', [])) - 1 else '├── '
path = dir_info.get('path', '')
purpose = dir_info.get('purpose', '')
lines.append(f"{prefix}{path}/ # {purpose}")
return '\n'.join(lines)
def generate_features_html(features: List[Dict]) -> str:
"""Generate HTML for features section."""
icons = ['🔐', '👤', '🔌', '💾', '📁', '🔍', '📧', '⚙️']
html_parts = []
for i, feature in enumerate(features[:8]):
icon = icons[i % len(icons)]
name = feature.get('name', 'Feature')
description = feature.get('description', '')
technical_notes = feature.get('technical_notes', '')
files = feature.get('files', [])
files_html = '\n'.join([f'<li><code>{escape_html(f)}</code></li>' for f in files[:3]])
html_parts.append(f'''
<div class="feature-item">
<div class="feature-icon">{icon}</div>
<div class="feature-content">
<h4>{escape_html(name)}</h4>
<p>{escape_html(description)}</p>
<details>
<summary>
🔧 Technical Details
<span class="tech-badge">For Engineers</span>
</summary>
<div>
<p>{escape_html(technical_notes)}</p>
<p><strong>Key Files:</strong></p>
<ul>
{files_html}
</ul>
</div>
</details>
</div>
</div>''')
return '\n'.join(html_parts) if html_parts else '''
<div class="feature-item">
<div class="feature-icon">✨</div>
<div class="feature-content">
<h4>Core Functionality</h4>
<p>Main features of the application.</p>
</div>
</div>'''
def generate_api_endpoints_html(endpoints: List[Dict]) -> str:
"""Generate HTML for API endpoints."""
if not endpoints:
return '''
<p>No API endpoints detected. This project may use a different API pattern or may not have an API layer.</p>'''
html_parts = ['<table>', '<thead>', '<tr>', '<th>Method</th>', '<th>Endpoint</th>', '<th>Description</th>', '</tr>', '</thead>', '<tbody>']
for endpoint in endpoints[:15]:
method = endpoint.get('method', 'GET')
method_class = f'method-{method.lower()}'
path = endpoint.get('path', '')
description = endpoint.get('description', '')
html_parts.append(f'''
<tr>
<td><span class="method {method_class}">{escape_html(method)}</span></td>
<td><code>{escape_html(path)}</code></td>
<td>{escape_html(description)}</td>
</tr>''')
html_parts.extend(['</tbody>', '</table>'])
return '\n'.join(html_parts)
def generate_components_html(components: List[Dict]) -> str:
"""Generate HTML for component catalog."""
if not components:
return '''
<p>No UI components detected. This project may not have a frontend layer or uses a different component pattern.</p>'''
html_parts = []
for comp in components[:10]:
name = comp.get('name', 'Component')
description = comp.get('description', f'{name} component')
path = comp.get('path', '')
props = comp.get('props', 'See source file')
html_parts.append(f'''
<div class="card">
<div class="card-header">
<div class="card-icon">🧩</div>
<div class="card-title">{escape_html(name)}</div>
</div>
<p>{escape_html(description)}</p>
<p><code>{escape_html(path)}</code></p>
<details>
<summary>
🔧 Props & Usage
<span class="tech-badge">Technical</span>
</summary>
<div>
<p><strong>Props:</strong> {escape_html(props)}</p>
<h4>Usage Example</h4>
<pre><code>&lt;{escape_html(name)} /&gt;</code></pre>
</div>
</details>
</div>''')
return '\n'.join(html_parts)
def generate_data_models_html(models: List[Dict]) -> str:
"""Generate HTML for data models."""
if not models:
return '''
<p>No data models detected. This project may not use a database or uses a different data pattern.</p>'''
html_parts = []
for model in models[:10]:
name = model.get('name', 'Model')
description = model.get('description', f'{name} data model')
fields = model.get('fields', [])
fields_html = ''
if fields:
fields_html = '<table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody>'
for field in fields[:10]:
field_name = field.get('name', '')
field_type = field.get('type', 'unknown')
field_desc = field.get('description', '')
fields_html += f'''
<tr>
<td><code>{escape_html(field_name)}</code></td>
<td><code>{escape_html(field_type)}</code></td>
<td>{escape_html(field_desc)}</td>
</tr>'''
fields_html += '</tbody></table>'
html_parts.append(f'''
<h3>{escape_html(name)}</h3>
<p><strong>What it represents:</strong> {escape_html(description)}</p>
{fields_html}''')
return '\n'.join(html_parts)
def generate_er_diagram(models: List[Dict]) -> str:
"""Generate ASCII ER diagram."""
if not models:
return '''┌─────────────────────────────────────┐
│ No data models detected │
└─────────────────────────────────────┘'''
lines = []
for model in models[:4]:
name = model.get('name', 'Model')
fields = model.get('fields', [])[:4]
width = max(len(name) + 4, max([len(f.get('name', '')) + len(f.get('type', '')) + 5 for f in fields] or [20]))
lines.append('┌' + '─' * width + '┐')
lines.append('│' + f' {name} '.center(width) + '│')
lines.append('├' + '─' * width + '┤')
for field in fields:
field_str = f" {field.get('name', '')} : {field.get('type', '')}"
lines.append('│' + field_str.ljust(width) + '│')
lines.append('└' + '─' * width + '┘')
lines.append('')
return '\n'.join(lines)
def generate_glossary_html(terms: List[Dict]) -> str:
"""Generate HTML for glossary."""
html_parts = []
for term in terms:
word = term.get('term', '')
definition = term.get('definition', '')
html_parts.append(f'''
<div class="glossary-term">
<span class="glossary-word">{escape_html(word)}</span>
<span class="glossary-definition">{escape_html(definition)}</span>
</div>''')
return '\n'.join(html_parts)
def generate_system_diagram(tech_stack: Dict, structure: Dict) -> str:
"""Generate ASCII system architecture diagram."""
framework = tech_stack.get('framework', 'Application')
database = tech_stack.get('database', '')
ui = tech_stack.get('ui_framework', 'UI')
diagram = f'''┌─────────────────────────────────────────────────────────────┐
│ Application Architecture │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Client │───▶│ API │───▶│ Database │ │
│ │ ({ui or 'UI'}) │ │ ({framework or 'Server'}) │ │ ({database or 'Storage'}) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘'''
return diagram
def generate_html(analysis: Dict, template: str) -> str:
"""Generate final HTML from analysis and template."""
project = analysis.get('project', {})
tech_stack = analysis.get('tech_stack', {})
structure = analysis.get('structure', {})
features = analysis.get('features', [])
components = analysis.get('components', [])
endpoints = analysis.get('api_endpoints', [])
models = analysis.get('data_models', [])
glossary = analysis.get('glossary_terms', [])
# Basic replacements
replacements = {
'{{PROJECT_NAME}}': escape_html(project.get('name', 'Project')),
'{{VERSION}}': escape_html(project.get('version', '1.0.0')),
'{{TAGLINE}}': escape_html(project.get('description', 'Project documentation')),
'{{DESCRIPTION}}': escape_html(project.get('description', 'This project provides various features and capabilities.')),
'{{AUDIENCE}}': 'Developers, stakeholders, and anyone interested in understanding this project.',
'{{GENERATED_DATE}}': datetime.now().strftime('%Y-%m-%d'),
}
# Generate complex sections
html = template
# Replace simple placeholders
for key, value in replacements.items():
html = html.replace(key, value)
# Replace capabilities section
capabilities = [{'capability': cap.get('name'), 'description': cap.get('description')}
for cap in features[:4]] if features else [
{'capability': 'Core Features', 'description': 'Main application functionality'},
{'capability': 'Easy Integration', 'description': 'Simple setup and configuration'}
]
# Find and replace the capabilities placeholder section
cap_html = generate_capabilities_html(capabilities)
html = re.sub(
r'<!-- CAPABILITIES_PLACEHOLDER -->.*?</div>\s*</div>',
f'<!-- Generated Capabilities -->\n{cap_html}',
html,
flags=re.DOTALL
)
# Replace technology stack
html = re.sub(
r'<!-- TECH_STACK_PLACEHOLDER -->.*?</tr>',
generate_tech_stack_html(tech_stack),
html,
flags=re.DOTALL
)
# Generate and replace diagrams
html = html.replace('{{SYSTEM_DIAGRAM}}', generate_system_diagram(tech_stack, structure))
html = html.replace('{{DIRECTORY_STRUCTURE}}', generate_directory_structure(structure))
html = html.replace('{{ER_DIAGRAM}}', generate_er_diagram(models))
# Replace features section
html = re.sub(
r'<!-- FEATURES_PLACEHOLDER -->.*?</div>\s*</div>\s*</div>',
f'<!-- Generated Features -->\n{generate_features_html(features)}',
html,
flags=re.DOTALL
)
# Replace API endpoints
html = re.sub(
r'<!-- API_ENDPOINTS_PLACEHOLDER -->.*?</details>',
f'<h3>API Endpoints</h3>\n{generate_api_endpoints_html(endpoints)}',
html,
flags=re.DOTALL
)
# Replace components
html = re.sub(
r'<!-- COMPONENTS_PLACEHOLDER -->.*?</div>\s*</div>',
f'<!-- Generated Components -->\n{generate_components_html(components)}',
html,
flags=re.DOTALL
)
# Replace data models
html = re.sub(
r'<!-- DATA_MODELS_PLACEHOLDER -->.*?</table>',
f'<!-- Generated Data Models -->\n{generate_data_models_html(models)}',
html,
flags=re.DOTALL
)
# Replace glossary
html = re.sub(
r'<!-- GLOSSARY_PLACEHOLDER -->.*?</div>',
f'<!-- Generated Glossary -->\n{generate_glossary_html(glossary)}\n</div>',
html,
flags=re.DOTALL
)
# Clean up remaining placeholders
html = re.sub(r'\{\{[A-Z_]+\}\}', '', html)
return html
def main():
"""Main entry point."""
if len(sys.argv) < 3:
print("Usage: generate_html.py <analysis.yml> <template.html> [output.html]")
sys.exit(1)
analysis_path = Path(sys.argv[1])
template_path = Path(sys.argv[2])
output_path = Path(sys.argv[3]) if len(sys.argv) > 3 else Path('documentation.html')
if not analysis_path.exists():
print(f"Error: Analysis file not found: {analysis_path}", file=sys.stderr)
sys.exit(1)
if not template_path.exists():
print(f"Error: Template file not found: {template_path}", file=sys.stderr)
sys.exit(1)
analysis = load_analysis(analysis_path)
template = load_template(template_path)
html = generate_html(analysis, template)
output_path.write_text(html, encoding='utf-8')
print(f"HTML documentation generated: {output_path}")
if __name__ == '__main__':
main()

97
skills/documentation-generator/skill.yml Normal file
View File

@ -0,0 +1,97 @@
# Documentation Generator Skill
# Generates comprehensive dual-audience documentation
name: documentation-generator
version: "1.0.0"
description: |
Analyzes project structure and generates comprehensive documentation
that serves both technical (engineers) and non-technical audiences.
triggers:
commands:
- "/eureka:index"
- "/eureka:docs"
keywords:
- "generate documentation"
- "create docs"
- "document project"
- "project documentation"
- "index project"
agents:
- doc-writer
schemas:
- documentation_output.yml
- project_analysis.yml
scripts:
- analyze_project.py
- generate_html.py
templates:
- documentation.html
capabilities:
- Project structure analysis
- Dual-audience documentation generation
- ASCII diagram creation
- API documentation
- Component cataloging
- Glossary generation
outputs:
primary:
- index.html # Beautiful HTML for non-engineers
- PROJECT_DOCUMENTATION.md
- QUICK_REFERENCE.md
optional:
- API_REFERENCE.md
- COMPONENTS.md
- GLOSSARY.md
data:
- analysis.yml # Project analysis data
audience_support:
non_technical:
- Executive Summary
- Feature Guide
- Glossary
- Visual Diagrams
technical:
- API Reference
- Component Catalog
- Data Models
- Code Examples
configuration:
default_output_dir: docs
supported_formats:
- markdown
- html
default_sections:
- executive_summary
- architecture_overview
- getting_started
- features
- api_reference
- component_catalog
- data_models
- glossary
dependencies:
required:
- Read tool (file access)
- Write tool (file creation)
- Glob tool (file discovery)
- Grep tool (pattern search)
optional:
- Bash tool (script execution)
- Task tool (agent delegation)
quality_gates:
- All referenced files must exist
- All code examples must be syntactically valid
- All internal links must resolve
- Technical details wrapped in collapsible sections
- Glossary covers all technical terms used

962
skills/documentation-generator/templates/documentation.html Normal file
View File

@ -0,0 +1,962 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{PROJECT_NAME}} - Documentation</title>
<style>
/* ===== CSS Variables ===== */
:root {
--color-primary: #2563eb;
--color-primary-light: #3b82f6;
--color-primary-dark: #1d4ed8;
--color-secondary: #7c3aed;
--color-success: #10b981;
--color-warning: #f59e0b;
--color-danger: #ef4444;
--color-info: #06b6d4;
--color-bg: #ffffff;
--color-bg-alt: #f8fafc;
--color-bg-code: #f1f5f9;
--color-text: #1e293b;
--color-text-light: #64748b;
--color-text-muted: #94a3b8;
--color-border: #e2e8f0;
--font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
--font-mono: 'JetBrains Mono', 'Fira Code', Consolas, monospace;
--shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
--radius-sm: 0.375rem;
--radius-md: 0.5rem;
--radius-lg: 0.75rem;
}
/* Dark mode */
@media (prefers-color-scheme: dark) {
:root {
--color-bg: #0f172a;
--color-bg-alt: #1e293b;
--color-bg-code: #334155;
--color-text: #f1f5f9;
--color-text-light: #94a3b8;
--color-text-muted: #64748b;
--color-border: #334155;
}
}
/* ===== Reset & Base ===== */
*, *::before, *::after {
box-sizing: border-box;
margin: 0;
padding: 0;
}
html {
scroll-behavior: smooth;
font-size: 16px;
}
body {
font-family: var(--font-sans);
background: var(--color-bg);
color: var(--color-text);
line-height: 1.7;
min-height: 100vh;
}
/* ===== Layout ===== */
.layout {
display: flex;
min-height: 100vh;
}
/* Sidebar */
.sidebar {
position: fixed;
top: 0;
left: 0;
width: 280px;
height: 100vh;
background: var(--color-bg-alt);
border-right: 1px solid var(--color-border);
overflow-y: auto;
padding: 2rem 0;
z-index: 100;
}
.sidebar-header {
padding: 0 1.5rem 1.5rem;
border-bottom: 1px solid var(--color-border);
margin-bottom: 1rem;
}
.sidebar-logo {
font-size: 1.25rem;
font-weight: 700;
color: var(--color-primary);
text-decoration: none;
display: flex;
align-items: center;
gap: 0.5rem;
}
.sidebar-version {
font-size: 0.75rem;
color: var(--color-text-muted);
margin-top: 0.25rem;
}
.sidebar-nav {
padding: 0 1rem;
}
.nav-section {
margin-bottom: 1.5rem;
}
.nav-section-title {
font-size: 0.75rem;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 0.05em;
color: var(--color-text-muted);
padding: 0 0.5rem;
margin-bottom: 0.5rem;
}
.nav-link {
display: block;
padding: 0.5rem;
color: var(--color-text-light);
text-decoration: none;
border-radius: var(--radius-sm);
font-size: 0.9rem;
transition: all 0.15s ease;
}
.nav-link:hover {
background: var(--color-border);
color: var(--color-text);
}
.nav-link.active {
background: var(--color-primary);
color: white;
}
.nav-link-icon {
margin-right: 0.5rem;
}
/* Main content */
.main {
flex: 1;
margin-left: 280px;
padding: 3rem 4rem;
max-width: 900px;
}
/* ===== Typography ===== */
h1, h2, h3, h4, h5, h6 {
font-weight: 600;
line-height: 1.3;
margin-top: 2rem;
margin-bottom: 1rem;
}
h1 {
font-size: 2.5rem;
margin-top: 0;
padding-bottom: 1rem;
border-bottom: 2px solid var(--color-border);
}
h2 {
font-size: 1.75rem;
color: var(--color-primary);
}
h3 {
font-size: 1.25rem;
}
p {
margin-bottom: 1rem;
}
a {
color: var(--color-primary);
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
/* ===== Components ===== */
/* Hero section */
.hero {
background: linear-gradient(135deg, var(--color-primary) 0%, var(--color-secondary) 100%);
color: white;
padding: 3rem;
border-radius: var(--radius-lg);
margin-bottom: 3rem;
}
.hero h1 {
color: white;
border-bottom: none;
padding-bottom: 0;
margin-bottom: 0.5rem;
}
.hero-tagline {
font-size: 1.25rem;
opacity: 0.9;
}
/* Cards */
.card {
background: var(--color-bg);
border: 1px solid var(--color-border);
border-radius: var(--radius-lg);
padding: 1.5rem;
margin-bottom: 1.5rem;
box-shadow: var(--shadow-sm);
}
.card-header {
display: flex;
align-items: center;
gap: 0.75rem;
margin-bottom: 1rem;
}
.card-icon {
width: 2.5rem;
height: 2.5rem;
background: var(--color-primary);
color: white;
border-radius: var(--radius-md);
display: flex;
align-items: center;
justify-content: center;
font-size: 1.25rem;
}
.card-title {
font-size: 1.1rem;
font-weight: 600;
margin: 0;
}
/* Grid */
.grid {
display: grid;
gap: 1.5rem;
}
.grid-2 {
grid-template-columns: repeat(2, 1fr);
}
.grid-3 {
grid-template-columns: repeat(3, 1fr);
}
@media (max-width: 768px) {
.grid-2, .grid-3 {
grid-template-columns: 1fr;
}
}
/* Tables */
table {
width: 100%;
border-collapse: collapse;
margin: 1.5rem 0;
font-size: 0.9rem;
}
th, td {
padding: 0.75rem 1rem;
text-align: left;
border-bottom: 1px solid var(--color-border);
}
th {
background: var(--color-bg-alt);
font-weight: 600;
color: var(--color-text-light);
text-transform: uppercase;
font-size: 0.75rem;
letter-spacing: 0.05em;
}
tr:hover {
background: var(--color-bg-alt);
}
/* Code blocks */
code {
font-family: var(--font-mono);
font-size: 0.875em;
background: var(--color-bg-code);
padding: 0.2em 0.4em;
border-radius: var(--radius-sm);
}
pre {
background: var(--color-bg-code);
border-radius: var(--radius-md);
padding: 1.25rem;
overflow-x: auto;
margin: 1.5rem 0;
border: 1px solid var(--color-border);
}
pre code {
background: none;
padding: 0;
font-size: 0.875rem;
line-height: 1.6;
}
/* Diagrams */
.diagram {
background: var(--color-bg-alt);
border: 1px solid var(--color-border);
border-radius: var(--radius-md);
padding: 1.5rem;
overflow-x: auto;
margin: 1.5rem 0;
font-family: var(--font-mono);
font-size: 0.8rem;
line-height: 1.4;
white-space: pre;
}
/* Badges */
.badge {
display: inline-flex;
align-items: center;
padding: 0.25rem 0.75rem;
font-size: 0.75rem;
font-weight: 500;
border-radius: 9999px;
text-transform: uppercase;
letter-spacing: 0.025em;
}
.badge-primary {
background: rgba(37, 99, 235, 0.1);
color: var(--color-primary);
}
.badge-success {
background: rgba(16, 185, 129, 0.1);
color: var(--color-success);
}
.badge-warning {
background: rgba(245, 158, 11, 0.1);
color: var(--color-warning);
}
.badge-info {
background: rgba(6, 182, 212, 0.1);
color: var(--color-info);
}
/* Collapsible technical details */
details {
background: var(--color-bg-alt);
border: 1px solid var(--color-border);
border-radius: var(--radius-md);
margin: 1rem 0;
}
summary {
padding: 1rem 1.25rem;
cursor: pointer;
font-weight: 500;
display: flex;
align-items: center;
gap: 0.5rem;
color: var(--color-text-light);
}
summary:hover {
color: var(--color-text);
}
summary::marker {
content: '';
}
summary::before {
content: '▶';
font-size: 0.75rem;
transition: transform 0.2s ease;
}
details[open] summary::before {
transform: rotate(90deg);
}
details > div {
padding: 0 1.25rem 1.25rem;
border-top: 1px solid var(--color-border);
}
.tech-badge {
background: var(--color-primary);
color: white;
padding: 0.125rem 0.5rem;
border-radius: var(--radius-sm);
font-size: 0.7rem;
margin-left: auto;
}
/* API Methods */
.method {
display: inline-block;
padding: 0.25rem 0.5rem;
border-radius: var(--radius-sm);
font-size: 0.75rem;
font-weight: 600;
font-family: var(--font-mono);
}
.method-get { background: #dcfce7; color: #166534; }
.method-post { background: #dbeafe; color: #1e40af; }
.method-put { background: #fef3c7; color: #92400e; }
.method-patch { background: #fce7f3; color: #9d174d; }
.method-delete { background: #fee2e2; color: #991b1b; }
/* Alerts / Callouts */
.callout {
padding: 1rem 1.25rem;
border-radius: var(--radius-md);
margin: 1.5rem 0;
border-left: 4px solid;
}
.callout-info {
background: rgba(6, 182, 212, 0.1);
border-color: var(--color-info);
}
.callout-tip {
background: rgba(16, 185, 129, 0.1);
border-color: var(--color-success);
}
.callout-warning {
background: rgba(245, 158, 11, 0.1);
border-color: var(--color-warning);
}
.callout-title {
font-weight: 600;
margin-bottom: 0.5rem;
display: flex;
align-items: center;
gap: 0.5rem;
}
/* Lists */
ul, ol {
margin: 1rem 0;
padding-left: 1.5rem;
}
li {
margin-bottom: 0.5rem;
}
/* Glossary */
.glossary-term {
display: flex;
padding: 1rem 0;
border-bottom: 1px solid var(--color-border);
}
.glossary-term:last-child {
border-bottom: none;
}
.glossary-word {
font-weight: 600;
min-width: 150px;
color: var(--color-primary);
}
.glossary-definition {
color: var(--color-text-light);
}
/* Feature list */
.feature-item {
display: flex;
gap: 1rem;
padding: 1.25rem;
border: 1px solid var(--color-border);
border-radius: var(--radius-md);
margin-bottom: 1rem;
transition: all 0.2s ease;
}
.feature-item:hover {
border-color: var(--color-primary);
box-shadow: var(--shadow-md);
}
.feature-icon {
width: 3rem;
height: 3rem;
background: linear-gradient(135deg, var(--color-primary) 0%, var(--color-secondary) 100%);
color: white;
border-radius: var(--radius-md);
display: flex;
align-items: center;
justify-content: center;
font-size: 1.25rem;
flex-shrink: 0;
}
.feature-content h4 {
margin: 0 0 0.5rem 0;
font-size: 1rem;
}
.feature-content p {
margin: 0;
color: var(--color-text-light);
font-size: 0.9rem;
}
/* Responsive */
@media (max-width: 1024px) {
.sidebar {
transform: translateX(-100%);
transition: transform 0.3s ease;
}
.sidebar.open {
transform: translateX(0);
}
.main {
margin-left: 0;
padding: 2rem 1.5rem;
}
.mobile-menu-btn {
display: block;
position: fixed;
top: 1rem;
left: 1rem;
z-index: 101;
background: var(--color-primary);
color: white;
border: none;
padding: 0.75rem;
border-radius: var(--radius-md);
cursor: pointer;
}
}
@media (min-width: 1025px) {
.mobile-menu-btn {
display: none;
}
}
/* Print styles */
@media print {
.sidebar {
display: none;
}
.main {
margin-left: 0;
max-width: 100%;
}
details {
display: block !important;
}
details > div {
display: block !important;
}
}
</style>
</head>
<body>
<button class="mobile-menu-btn" onclick="toggleSidebar()">☰</button>
<div class="layout">
<!-- Sidebar Navigation -->
<aside class="sidebar" id="sidebar">
<div class="sidebar-header">
<a href="#" class="sidebar-logo">
📚 {{PROJECT_NAME}}
</a>
<div class="sidebar-version">Version {{VERSION}}</div>
</div>
<nav class="sidebar-nav">
<div class="nav-section">
<div class="nav-section-title">Overview</div>
<a href="#executive-summary" class="nav-link">
<span class="nav-link-icon">📋</span> Executive Summary
</a>
<a href="#quick-start" class="nav-link">
<span class="nav-link-icon">🚀</span> Quick Start
</a>
<a href="#architecture" class="nav-link">
<span class="nav-link-icon">🏗️</span> Architecture
</a>
</div>
<div class="nav-section">
<div class="nav-section-title">Features</div>
<a href="#features" class="nav-link">
<span class="nav-link-icon">✨</span> Feature Guide
</a>
</div>
<div class="nav-section">
<div class="nav-section-title">For Developers</div>
<a href="#api-reference" class="nav-link">
<span class="nav-link-icon">🔌</span> API Reference
</a>
<a href="#components" class="nav-link">
<span class="nav-link-icon">🧩</span> Components
</a>
<a href="#data-models" class="nav-link">
<span class="nav-link-icon">💾</span> Data Models
</a>
</div>
<div class="nav-section">
<div class="nav-section-title">Reference</div>
<a href="#glossary" class="nav-link">
<span class="nav-link-icon">📖</span> Glossary
</a>
</div>
</nav>
</aside>
<!-- Main Content -->
<main class="main">
<!-- Hero Section -->
<section class="hero">
<h1>{{PROJECT_NAME}}</h1>
<p class="hero-tagline">{{TAGLINE}}</p>
</section>
<!-- Executive Summary -->
<section id="executive-summary">
<h2>📋 Executive Summary</h2>
<h3>What is {{PROJECT_NAME}}?</h3>
<p>{{DESCRIPTION}}</p>
<h3>Who is it for?</h3>
<p>{{AUDIENCE}}</p>
<h3>Key Capabilities</h3>
<div class="grid grid-2">
<!-- CAPABILITIES_PLACEHOLDER -->
<div class="card">
<div class="card-header">
<div class="card-icon">✨</div>
<div class="card-title">{{CAPABILITY_1_NAME}}</div>
</div>
<p>{{CAPABILITY_1_DESCRIPTION}}</p>
</div>
<div class="card">
<div class="card-header">
<div class="card-icon">⚡</div>
<div class="card-title">{{CAPABILITY_2_NAME}}</div>
</div>
<p>{{CAPABILITY_2_DESCRIPTION}}</p>
</div>
</div>
</section>
<!-- Quick Start -->
<section id="quick-start">
<h2>🚀 Quick Start</h2>
<h3>Prerequisites</h3>
<table>
<thead>
<tr>
<th>Tool</th>
<th>Purpose</th>
</tr>
</thead>
<tbody>
<!-- PREREQUISITES_PLACEHOLDER -->
<tr>
<td><code>{{PREREQ_1_TOOL}}</code></td>
<td>{{PREREQ_1_PURPOSE}}</td>
</tr>
</tbody>
</table>
<h3>Installation</h3>
<pre><code>{{INSTALLATION_COMMANDS}}</code></pre>
<h3>Basic Usage</h3>
<pre><code>{{BASIC_USAGE}}</code></pre>
</section>
<!-- Architecture -->
<section id="architecture">
<h2>🏗️ Architecture Overview</h2>
<h3>System Diagram</h3>
<div class="diagram">{{SYSTEM_DIAGRAM}}</div>
<h3>Technology Stack</h3>
<table>
<thead>
<tr>
<th>Layer</th>
<th>Technology</th>
<th>Purpose</th>
</tr>
</thead>
<tbody>
<!-- TECH_STACK_PLACEHOLDER -->
<tr>
<td>{{TECH_LAYER}}</td>
<td><span class="badge badge-primary">{{TECH_NAME}}</span></td>
<td>{{TECH_PURPOSE}}</td>
</tr>
</tbody>
</table>
<h3>Directory Structure</h3>
<pre><code>{{DIRECTORY_STRUCTURE}}</code></pre>
</section>
<!-- Features -->
<section id="features">
<h2>✨ Features</h2>
<!-- FEATURES_PLACEHOLDER -->
<div class="feature-item">
<div class="feature-icon">🔐</div>
<div class="feature-content">
<h4>{{FEATURE_NAME}}</h4>
<p>{{FEATURE_DESCRIPTION}}</p>
<details>
<summary>
🔧 Technical Details
<span class="tech-badge">For Engineers</span>
</summary>
<div>
<p>{{FEATURE_TECHNICAL_NOTES}}</p>
<p><strong>Key Files:</strong></p>
<ul>
<li><code>{{FEATURE_FILE_1}}</code></li>
</ul>
</div>
</details>
</div>
</div>
</section>
<!-- API Reference -->
<section id="api-reference">
<h2>🔌 API Reference</h2>
<div class="callout callout-info">
<div class="callout-title">ℹ️ About the API</div>
<p>This section is primarily for developers who need to integrate with or extend the application.</p>
</div>
<!-- API_ENDPOINTS_PLACEHOLDER -->
<h3>{{API_GROUP_NAME}}</h3>
<table>
<thead>
<tr>
<th>Method</th>
<th>Endpoint</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><span class="method method-get">GET</span></td>
<td><code>{{API_PATH}}</code></td>
<td>{{API_DESCRIPTION}}</td>
</tr>
</tbody>
</table>
<details>
<summary>
📖 Request & Response Details
<span class="tech-badge">Technical</span>
</summary>
<div>
<h4>Request</h4>
<pre><code>{{API_REQUEST_EXAMPLE}}</code></pre>
<h4>Response</h4>
<pre><code>{{API_RESPONSE_EXAMPLE}}</code></pre>
</div>
</details>
</section>
<!-- Components -->
<section id="components">
<h2>🧩 Component Catalog</h2>
<!-- COMPONENTS_PLACEHOLDER -->
<div class="card">
<div class="card-header">
<div class="card-icon">🧩</div>
<div class="card-title">{{COMPONENT_NAME}}</div>
</div>
<p>{{COMPONENT_DESCRIPTION}}</p>
<p><code>{{COMPONENT_PATH}}</code></p>
<details>
<summary>
🔧 Props & Usage
<span class="tech-badge">Technical</span>
</summary>
<div>
<table>
<thead>
<tr>
<th>Prop</th>
<th>Type</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>{{PROP_NAME}}</code></td>
<td><code>{{PROP_TYPE}}</code></td>
<td>{{PROP_REQUIRED}}</td>
<td>{{PROP_DESCRIPTION}}</td>
</tr>
</tbody>
</table>
<h4>Usage Example</h4>
<pre><code>{{COMPONENT_USAGE_EXAMPLE}}</code></pre>
</div>
</details>
</div>
</section>
<!-- Data Models -->
<section id="data-models">
<h2>💾 Data Models</h2>
<h3>Entity Relationship Diagram</h3>
<div class="diagram">{{ER_DIAGRAM}}</div>
<!-- DATA_MODELS_PLACEHOLDER -->
<h3>{{MODEL_NAME}}</h3>
<p><strong>What it represents:</strong> {{MODEL_DESCRIPTION}}</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>{{FIELD_NAME}}</code></td>
<td><code>{{FIELD_TYPE}}</code></td>
<td>{{FIELD_DESCRIPTION}}</td>
</tr>
</tbody>
</table>
</section>
<!-- Glossary -->
<section id="glossary">
<h2>📖 Glossary</h2>
<div class="callout callout-tip">
<div class="callout-title">💡 Tip</div>
<p>This glossary explains technical terms in plain English. Perfect for non-technical stakeholders!</p>
</div>
<div class="card">
<!-- GLOSSARY_PLACEHOLDER -->
<div class="glossary-term">
<span class="glossary-word">{{TERM}}</span>
<span class="glossary-definition">{{DEFINITION}}</span>
</div>
</div>
</section>
<!-- Footer -->
<footer style="margin-top: 4rem; padding-top: 2rem; border-top: 1px solid var(--color-border); color: var(--color-text-muted); text-align: center;">
<p>Generated by <strong>Eureka Index</strong> · {{GENERATED_DATE}}</p>
</footer>
</main>
</div>
<script>
// Mobile menu toggle
function toggleSidebar() {
document.getElementById('sidebar').classList.toggle('open');
}
// Active nav highlighting
const sections = document.querySelectorAll('section[id]');
const navLinks = document.querySelectorAll('.nav-link');
window.addEventListener('scroll', () => {
let current = '';
sections.forEach(section => {
const sectionTop = section.offsetTop;
if (scrollY >= sectionTop - 100) {
current = section.getAttribute('id');
}
});
navLinks.forEach(link => {
link.classList.remove('active');
if (link.getAttribute('href') === '#' + current) {
link.classList.add('active');
}
});
});
// Close sidebar when clicking a link (mobile)
navLinks.forEach(link => {
link.addEventListener('click', () => {
if (window.innerWidth < 1025) {
document.getElementById('sidebar').classList.remove('open');
}
});
});
</script>
</body>
</html>

38
skills/guardrail-orchestrator/agents/architect.yml Normal file
View File

@ -0,0 +1,38 @@
# Architect Agent Definition
# Responsible for manifest design and task creation
name: architect
role: System Designer & Task Planner
description: |
The Architect designs the system by defining entities in the manifest
and breaking down implementation into discrete tasks for other agents.
allowed_tools:
- Read # Read any file for context
- Write # Write to manifest and task files ONLY
blocked_tools:
- Bash # Cannot execute commands
- Edit # Cannot modify existing code
allowed_files:
- project_manifest.json
- "tasks/*.yml"
- "tasks/**/*.yml"
responsibilities:
- Design system architecture in manifest
- Define entities (pages, components, APIs, tables)
- Create implementation tasks for frontend/backend agents
- Set task priorities and dependencies
- Ensure no orphan entities or circular dependencies
outputs:
- Updated project_manifest.json with new entities
- Task files in tasks/ directory
cannot_do:
- Implement any code
- Run build/test commands
- Modify existing source files

45
skills/guardrail-orchestrator/agents/backend.yml Normal file
View File

@ -0,0 +1,45 @@
# Backend Agent Definition
# Responsible for API endpoints and database implementation
name: backend
role: Backend Developer
description: |
The Backend agent implements API endpoints, database schemas,
and server-side logic based on approved entities and assigned tasks.
allowed_tools:
- Read # Read files for context
- Write # Create new files
- Edit # Modify existing files
- Bash # Run build, lint, type-check, tests
blocked_tools: [] # Full access for implementation
allowed_files:
- "app/api/**/*"
- "app/lib/**/*"
- "prisma/**/*"
- "db/**/*"
- "*.config.*"
responsibilities:
- Implement API route handlers (GET, POST, PUT, DELETE)
- Create database schemas and migrations
- Implement data access layer (CRUD operations)
- Ensure request/response match manifest specs
- Handle errors appropriately
- Run lint/type-check before marking complete
task_types:
- create # New API/DB entity
- update # Modify existing backend
- refactor # Improve code quality
- delete # Remove deprecated endpoints
workflow:
1. Read assigned task from tasks/*.yml
2. Verify entity is APPROVED in manifest
3. Implement code matching manifest spec
4. Run validation (lint, type-check)
5. Update task status to "review"

44
skills/guardrail-orchestrator/agents/frontend.yml Normal file
View File

@ -0,0 +1,44 @@
# Frontend Agent Definition
# Responsible for UI component and page implementation
name: frontend
role: Frontend Developer
description: |
The Frontend agent implements UI components and pages based on
approved entities in the manifest and assigned tasks.
allowed_tools:
- Read # Read files for context
- Write # Create new files
- Edit # Modify existing files
- Bash # Run build, lint, type-check
blocked_tools: [] # Full access for implementation
allowed_files:
- "app/components/**/*"
- "app/**/page.tsx"
- "app/**/layout.tsx"
- "app/globals.css"
- "*.config.*"
responsibilities:
- Implement UI components matching manifest specs
- Create pages with correct routing
- Ensure props match manifest definitions
- Follow existing code patterns and styles
- Run lint/type-check before marking complete
task_types:
- create # New component/page
- update # Modify existing UI
- refactor # Improve code quality
- delete # Remove deprecated UI
workflow:
1. Read assigned task from tasks/*.yml
2. Verify entity is APPROVED in manifest
3. Implement code matching manifest spec
4. Run validation (lint, type-check)
5. Update task status to "review"

85
skills/guardrail-orchestrator/agents/orchestrator.yml Normal file
View File

@ -0,0 +1,85 @@
# Orchestrator Agent Definition
# Coordinates the entire workflow and delegates to specialized agents
name: orchestrator
role: Workflow Coordinator
description: |
The Orchestrator manages the end-to-end workflow, delegating tasks
to specialized agents based on task type and current phase.
workflow_phases:
1_design:
description: Design system entities in manifest
agent: architect
inputs: Feature requirements
outputs: Updated manifest with DEFINED entities
2_plan:
description: Create implementation tasks
agent: architect
inputs: Approved manifest entities
outputs: Task files in tasks/*.yml
3_implement:
description: Implement tasks by type
agents:
frontend: UI components, pages
backend: API endpoints, database
inputs: Tasks with status "pending"
outputs: Implemented code, tasks with status "review"
4_review:
description: Review implementations
agent: reviewer
inputs: Tasks with status "review"
outputs: Approved tasks or change requests
5_complete:
description: Mark tasks as done
agent: orchestrator
inputs: Tasks with status "approved"
outputs: Tasks with status "completed"
delegation_rules:
# Task assignment by entity type
entity_routing:
pages: frontend
components: frontend
api_endpoints: backend
database_tables: backend
# Task assignment by task type
task_routing:
create: frontend | backend # Based on entity type
update: frontend | backend # Based on entity type
delete: frontend | backend # Based on entity type
refactor: frontend | backend # Based on entity type
review: reviewer
test: reviewer
status_transitions:
pending:
- in_progress # When agent starts work
- blocked # If dependencies not met
in_progress:
- review # When implementation complete
- blocked # If blocked by issue
review:
- approved # Reviewer accepts
- in_progress # Reviewer requests changes
approved:
- completed # Final state
blocked:
- pending # When blocker resolved
commands:
- /workflow:start <feature> # Start new feature workflow
- /workflow:plan # Create tasks from manifest
- /workflow:assign # Assign tasks to agents
- /workflow:status # Show workflow status
- /workflow:next # Process next available task

52
skills/guardrail-orchestrator/agents/reviewer.yml Normal file
View File

@ -0,0 +1,52 @@
# Reviewer Agent Definition
# Responsible for code review and quality assurance
name: reviewer
role: Code Reviewer & QA
description: |
The Reviewer agent reviews implementations, runs tests,
and approves or requests changes. Cannot modify code directly.
allowed_tools:
- Read # Read any file for review
- Bash # Run tests, lint, type-check, verify
blocked_tools:
- Write # Cannot create files
- Edit # Cannot modify files
allowed_files:
- "*" # Can read everything
responsibilities:
- Review implementations match manifest specs
- Verify acceptance criteria are met
- Run tests and validation commands
- Check code quality and patterns
- Approve or request changes with feedback
task_types:
- review # Review completed implementation
review_checklist:
- File exists at manifest file_path
- Exports match manifest definitions
- Props/types match manifest specs
- Follows project code patterns
- Lint passes
- Type-check passes
- Tests pass (if applicable)
workflow:
1. Read task with status "review"
2. Read implementation files
3. Run verification commands
4. Compare against manifest specs
5. Either:
- APPROVE: Update task status to "approved"
- REQUEST_CHANGES: Add review_notes, set status to "in_progress"
outputs:
- review_notes in task file
- status update (approved | in_progress)

216
skills/guardrail-orchestrator/agents/security-reviewer.md Normal file
View File

@ -0,0 +1,216 @@
# Security Reviewer Agent
**Role**: Security-focused code review and vulnerability assessment
**Trigger**: `/workflow:security` command or security review phase
---
## Agent Capabilities
### Primary Functions
1. **Static Security Analysis**: Pattern-based vulnerability detection
2. **OWASP Top 10 Assessment**: Check for common web vulnerabilities
3. **Dependency Audit**: Identify vulnerable packages
4. **Configuration Review**: Check security settings and configurations
5. **Secret Detection**: Find hardcoded credentials and sensitive data
### Security Categories Analyzed
| Category | CWE | OWASP | Severity |
|----------|-----|-------|----------|
| Hardcoded Secrets | CWE-798 | A07 | CRITICAL |
| SQL Injection | CWE-89 | A03 | CRITICAL |
| Command Injection | CWE-78 | A03 | CRITICAL |
| XSS | CWE-79 | A03 | HIGH |
| Path Traversal | CWE-22 | A01 | HIGH |
| NoSQL Injection | CWE-943 | A03 | HIGH |
| SSRF | CWE-918 | A10 | HIGH |
| Prototype Pollution | CWE-1321 | A03 | HIGH |
| Insecure Auth | CWE-287 | A07 | HIGH |
| CORS Misconfiguration | CWE-942 | A01 | MEDIUM |
| Sensitive Data Exposure | CWE-200 | A02 | MEDIUM |
| Insecure Dependencies | CWE-1104 | A06 | MEDIUM |
| Insecure Randomness | CWE-330 | A02 | LOW |
| Debug Code | CWE-489 | A05 | LOW |
---
## Agent Constraints
### READ-ONLY MODE
- **CANNOT** modify files
- **CANNOT** fix issues directly
- **CAN** only read, analyze, and report
### Output Requirements
- Must produce structured security report
- Must categorize issues by severity
- Must provide remediation guidance
- Must reference CWE/OWASP standards
---
## Execution Flow
### Step 1: Run Automated Scanner
```bash
python3 skills/guardrail-orchestrator/scripts/security_scan.py --project-dir . --json
```
### Step 2: Deep Analysis (Task Agent)
For each CRITICAL/HIGH issue, perform deeper analysis:
- Trace data flow from source to sink
- Identify attack vectors
- Assess exploitability
- Check for existing mitigations
### Step 3: Dependency Audit
```bash
npm audit --json 2>/dev/null || echo "{}"
```
### Step 4: Configuration Review
Check security-relevant configurations:
- CORS settings
- CSP headers
- Authentication configuration
- Session management
- Cookie settings
### Step 5: Manual Code Review Checklist
For implemented features, verify:
- [ ] Input validation on all user inputs
- [ ] Output encoding for XSS prevention
- [ ] Parameterized queries for database access
- [ ] Proper error handling (no sensitive data in errors)
- [ ] Authentication/authorization checks
- [ ] HTTPS enforcement
- [ ] Secure cookie flags
- [ ] Rate limiting on sensitive endpoints
### Step 6: Generate Report
Output comprehensive security report with:
- Executive summary
- Issue breakdown by severity
- Detailed findings with code locations
- Remediation recommendations
- Risk assessment
---
## Report Format
```
+======================================================================+
| SECURITY REVIEW REPORT |
+======================================================================+
| Project: $PROJECT_NAME |
| Scan Date: $DATE |
| Agent: security-reviewer |
+======================================================================+
| EXECUTIVE SUMMARY |
+----------------------------------------------------------------------+
| Risk Level: CRITICAL / HIGH / MEDIUM / LOW / PASS |
| Total Issues: X |
| Critical: X (immediate action required) |
| High: X (fix before production) |
| Medium: X (should fix) |
| Low: X (consider fixing) |
+======================================================================+
| CRITICAL FINDINGS |
+----------------------------------------------------------------------+
| [1] Hardcoded API Key |
| File: src/lib/api.ts:15 |
| CWE: CWE-798 |
| Code: apiKey = "sk-..." |
| Risk: Credentials can be extracted from source |
| Fix: Use environment variable: process.env.API_KEY |
+----------------------------------------------------------------------+
| [2] SQL Injection |
| File: app/api/users/route.ts:42 |
| CWE: CWE-89 |
| Code: query(`SELECT * FROM users WHERE id = ${userId}`) |
| Risk: Attacker can manipulate database queries |
| Fix: Use parameterized query: query($1, [userId]) |
+======================================================================+
| HIGH FINDINGS |
+----------------------------------------------------------------------+
| [3] XSS Vulnerability |
| File: app/components/Comment.tsx:28 |
| ... |
+======================================================================+
| DEPENDENCY VULNERABILITIES |
+----------------------------------------------------------------------+
| lodash@4.17.20 - Prototype Pollution (HIGH) |
| axios@0.21.0 - SSRF Risk (MEDIUM) |
| Fix: npm audit fix |
+======================================================================+
| RECOMMENDATIONS |
+----------------------------------------------------------------------+
| 1. Immediately rotate any exposed credentials |
| 2. Fix SQL injection before deploying |
| 3. Add input validation layer |
| 4. Update vulnerable dependencies |
| 5. Add security headers middleware |
+======================================================================+
| VERDICT: FAIL - X critical issues must be fixed |
+======================================================================+
```
---
## Integration with Workflow
### In Review Phase
The security agent is automatically invoked during `/workflow:review`:
1. Review command runs security_scan.py
2. If CRITICAL issues found → blocks approval
3. Report included in review output
### Standalone Security Audit
Use `/workflow:security` for dedicated security review:
- More thorough analysis
- Deep code inspection
- Dependency audit
- Configuration review
### Remediation Flow
After security issues are identified:
1. Issues added to task queue as blockers
2. Implementation agents fix issues
3. Security agent re-validates fixes
4. Approval only after clean scan
---
## Tool Usage
### Primary Tools
- `Bash`: Run security_scan.py, npm audit
- `Read`: Analyze suspicious code patterns
- `Grep`: Search for vulnerability patterns
### Blocked Tools
- `Write`: Cannot create files
- `Edit`: Cannot modify files
- `Task`: Cannot delegate to other agents
---
## Exit Conditions
### PASS
- No CRITICAL or HIGH issues
- All dependencies up to date or acknowledged
- Security configurations reviewed
### FAIL
- Any CRITICAL issue present
- Multiple HIGH issues present
- Critical dependencies vulnerable
### WARNING
- Only MEDIUM/LOW issues
- Some dependencies outdated
- Minor configuration concerns

347
skills/guardrail-orchestrator/schemas/api_contract.yml Normal file
View File

@ -0,0 +1,347 @@
# API Contract Schema
# The binding agreement between frontend and backend implementations
# Generated during design phase, validated during review phase
#
# This contract ensures:
# 1. Backend implements exactly the endpoints frontend expects
# 2. Frontend calls endpoints with correct methods/bodies
# 3. Both use the same TypeScript types from shared file
# ============================================================================
# CONTRACT METADATA
# ============================================================================
api_contract:
# Links to workflow
workflow_version: string # e.g., v001
design_document_revision: integer
# Timestamps
generated_at: timestamp
validated_at: timestamp | null
# Contract status
status: draft | active | violated
# ============================================================================
# SHARED TYPES (Source of truth for both agents)
# ============================================================================
# These types are generated into app/types/api.ts
# Both frontend and backend MUST import from this file
types:
description: "TypeScript interfaces shared between frontend and backend"
type_schema:
# Identity
id: string # type_<Name> (e.g., type_User, type_CreateUserRequest)
name: string # PascalCase type name (exported interface name)
# Type definition
definition:
type: object | array | enum | union
# For object types
properties:
- name: string # Property name (camelCase)
type: string # TypeScript type (string, number, boolean, other type name)
required: boolean
description: string
validation: string # Optional validation rule
# For enum types
enum_values: [string]
# For union types
union_members: [string] # Array of type names or literal types
# For array types
array_item_type: string # Type of array items
# Usage tracking
used_by:
requests: [string] # endpoint_ids that use this as request body
responses: [string] # endpoint_ids that use this as response
models: [string] # model_ids this type represents
# Example
example_type:
id: type_User
name: User
definition:
type: object
properties:
- name: id
type: string
required: true
description: "Unique user identifier"
- name: email
type: string
required: true
description: "User email address"
validation: email
- name: name
type: string
required: true
description: "Display name"
- name: createdAt
type: Date
required: true
description: "Account creation timestamp"
used_by:
responses: [api_get_user, api_create_user, api_list_users]
models: [model_user]
# ============================================================================
# ENDPOINT CONTRACTS (Binding specifications)
# ============================================================================
endpoints:
description: "API endpoint contracts with strict request/response typing"
endpoint_schema:
# Identity
id: string # api_<verb>_<resource> from design_document
# HTTP Specification
method: GET | POST | PUT | PATCH | DELETE
path: string # Exact path with params (e.g., /api/users/:id)
# Path parameters (extracted from path)
path_params:
- name: string
type: string # TypeScript type
description: string
# Query parameters (for GET requests)
query_params:
- name: string
type: string
required: boolean
default: any
description: string
# Request body (for POST/PUT/PATCH)
request_body:
type_id: string # Reference to types section (e.g., type_CreateUserRequest)
content_type: application/json
# Response specification
response:
# Success response
success:
status: integer # 200, 201, 204
type_id: string # Reference to types section
is_array: boolean # If response is array of type
# Error responses
errors:
- status: integer # 400, 401, 403, 404, 500
type_id: string # Error response type (usually type_ApiError)
description: string
# Authentication
auth:
required: boolean
roles: [string] # Required roles (empty = any authenticated)
# Contract version for compatibility
version: string # Semantic version of this endpoint spec
# Example
example_endpoint:
id: api_create_user
method: POST
path: /api/users
path_params: []
query_params: []
request_body:
type_id: type_CreateUserRequest
content_type: application/json
response:
success:
status: 201
type_id: type_User
is_array: false
errors:
- status: 400
type_id: type_ValidationError
description: "Invalid request body"
- status: 409
type_id: type_ApiError
description: "Email already exists"
auth:
required: false
roles: []
version: "1.0.0"
# ============================================================================
# FRONTEND USAGE CONTRACTS (What frontend expects to call)
# ============================================================================
frontend_calls:
description: "Expected API calls from frontend components/pages"
call_schema:
# Identity
id: string # call_<component>_<action>
# Source
source:
entity_id: string # page_xxx or component_xxx
file_path: string # Expected file location
# Target endpoint
endpoint_id: string # Reference to endpoints section
# Call context
purpose: string # Why this call is made
trigger: string # What triggers this call (onLoad, onClick, onSubmit)
# Data mapping
request_mapping:
# How component data maps to request
from_props: [string] # Props used in request
from_state: [string] # State used in request
from_form: [string] # Form fields used in request
response_handling:
# How response is handled
success_action: string # What happens on success
error_action: string # What happens on error
# Example
example_call:
id: call_signup_form_submit
source:
entity_id: component_signup_form
file_path: app/components/SignupForm.tsx
endpoint_id: api_create_user
purpose: "Submit registration form"
trigger: onSubmit
request_mapping:
from_form: [email, name, password]
response_handling:
success_action: "Redirect to dashboard"
error_action: "Display error message"
# ============================================================================
# BACKEND IMPLEMENTATION CONTRACTS (What backend must provide)
# ============================================================================
backend_routes:
description: "Required backend route implementations"
route_schema:
# Identity
id: string # route_<verb>_<path>
# Target endpoint
endpoint_id: string # Reference to endpoints section
# Implementation location
file_path: string # Expected file (e.g., app/api/users/route.ts)
export_name: string # Exported function name (GET, POST, etc.)
# Dependencies
uses_models: [string] # model_ids this route uses
uses_services: [string] # Service files this route depends on
# Implementation requirements
must_validate:
- field: string
rule: string
must_authenticate: boolean
must_authorize: [string] # Role checks required
# Example
example_route:
id: route_post_users
endpoint_id: api_create_user
file_path: app/api/users/route.ts
export_name: POST
uses_models: [model_user]
uses_services: [lib/auth.ts, lib/db.ts]
must_validate:
- field: email
rule: email
- field: password
rule: min:8
must_authenticate: false
must_authorize: []
# ============================================================================
# VALIDATION RULES
# ============================================================================
validation_rules:
contracts:
- "Every frontend_call must reference existing endpoint_id"
- "Every backend_route must reference existing endpoint_id"
- "Request body type_id must exist in types section"
- "Response type_id must exist in types section"
- "Path params in endpoint must match :param patterns in path"
types:
- "Every type must have unique id"
- "Type references (nested types) must exist"
- "Required properties cannot have default values"
implementation:
- "Frontend must import types from shared types file"
- "Backend must import types from shared types file"
- "HTTP methods must match contract specification"
- "Response shapes must conform to type definitions"
# ============================================================================
# GENERATED FILES
# ============================================================================
generated_files:
shared_types:
path: app/types/api.ts
description: "TypeScript interfaces for all API types"
template: |
// AUTO-GENERATED - DO NOT EDIT
// Source: .workflow/versions/vXXX/contracts/api_contract.yml
// Generated: {timestamp}
// === Types ===
{type_definitions}
// === API Paths (for type-safe fetch calls) ===
export const API_PATHS = {
{path_constants}
} as const;
// === API Response Types ===
{response_type_helpers}
api_client:
path: app/lib/api-client.ts
description: "Type-safe API client (optional)"
template: |
// AUTO-GENERATED - DO NOT EDIT
// Type-safe API client generated from contract
import type { * } from '@/types/api';
{api_client_methods}
# ============================================================================
# CONTRACT VIOLATION HANDLING
# ============================================================================
violations:
severity_levels:
critical:
- "Endpoint exists in frontend but not backend"
- "Method mismatch (frontend calls POST, backend has GET)"
- "Required field missing in implementation"
high:
- "Response type mismatch"
- "Missing error handling for documented errors"
medium:
- "Extra undocumented endpoint in backend"
- "Type property order differs"
low:
- "Description mismatch"
- "Optional field handling differs"
on_violation:
critical: "Block deployment, require immediate fix"
high: "Warn in review, require acknowledgment"
medium: "Report in review, fix recommended"
low: "Log for tracking"

340
skills/guardrail-orchestrator/schemas/dependency_graph.yml Normal file
View File

@ -0,0 +1,340 @@
# Dependency Graph Schema
# Auto-generated from design_document.yml
# Determines execution order for parallel task distribution
# ============================================================================
# GRAPH METADATA
# ============================================================================
dependency_graph:
# Links to design document
design_version: string # design_document revision this was generated from
workflow_version: string # v001, v002, etc.
# Generation info
generated_at: timestamp
generator: string # Script that generated this
# Statistics
stats:
total_entities: integer
total_layers: integer
max_parallelism: integer # Max items that can run in parallel
critical_path_length: integer # Longest dependency chain
# ============================================================================
# EXECUTION LAYERS
# ============================================================================
layers:
description: "Ordered layers for parallel execution within each layer"
layer_schema:
layer: integer # 1, 2, 3...
name: string # Human-readable name
description: string # What this layer contains
# Items in this layer (can run in parallel)
items:
- id: string # Entity ID (model_*, api_*, page_*, component_*)
type: enum # model | api | page | component
name: string # Human-readable name
# Dependencies (all must be in lower layers)
depends_on: [string] # Entity IDs this depends on
# Task mapping
task_id: string # task_* ID for implementation
agent: enum # frontend | backend
# Estimated complexity
complexity: enum # low | medium | high
# Layer constraints
requires_layers: [integer] # Layer numbers that must complete first
parallel_count: integer # Number of items that can run in parallel
# Example layers
example:
- layer: 1
name: "Data Layer"
description: "Database models - no external dependencies"
items:
- id: model_user
type: model
name: User
depends_on: []
task_id: task_create_model_user
agent: backend
complexity: medium
- id: model_post
type: model
name: Post
depends_on: []
task_id: task_create_model_post
agent: backend
complexity: low
requires_layers: []
parallel_count: 2
- layer: 2
name: "API Layer"
description: "REST endpoints - depend on models"
items:
- id: api_create_user
type: api
name: "Create User"
depends_on: [model_user]
task_id: task_create_api_create_user
agent: backend
complexity: medium
- id: api_list_users
type: api
name: "List Users"
depends_on: [model_user]
task_id: task_create_api_list_users
agent: backend
complexity: low
requires_layers: [1]
parallel_count: 2
- layer: 3
name: "UI Layer"
description: "Pages and components - depend on APIs"
items:
- id: component_user_card
type: component
name: UserCard
depends_on: []
task_id: task_create_component_user_card
agent: frontend
complexity: low
- id: page_users
type: page
name: "Users Page"
depends_on: [api_list_users, component_user_card]
task_id: task_create_page_users
agent: frontend
complexity: medium
requires_layers: [2]
parallel_count: 2
# ============================================================================
# FULL DEPENDENCY MAP
# ============================================================================
dependency_map:
description: "Complete dependency relationships for visualization"
entry_schema:
entity_id:
type: enum # model | api | page | component
layer: integer # Which layer this belongs to
depends_on: [string] # What this entity needs
depended_by: [string] # What entities need this
# Example
example:
model_user:
type: model
layer: 1
depends_on: []
depended_by: [model_post, api_create_user, api_list_users, api_get_user]
api_create_user:
type: api
layer: 2
depends_on: [model_user]
depended_by: [page_user_create, component_user_form]
page_users:
type: page
layer: 3
depends_on: [api_list_users, component_user_card]
depended_by: []
# ============================================================================
# TASK GENERATION MAP
# ============================================================================
task_map:
description: "Maps entities to implementation tasks with context"
task_entry_schema:
entity_id: string # model_user, api_create_user, etc.
task_id: string # task_create_model_user
layer: integer # Execution layer
agent: enum # frontend | backend
# Context to pass to subagent (snapshot from design_document)
context:
# For models
model_definition:
fields: [object]
relations: [object]
validations: [object]
# For APIs
api_contract:
method: string
path: string
request_body: object
responses: [object]
auth: object
# For pages
page_definition:
path: string
data_needs: [object]
components: [string]
auth: object
# For components
component_definition:
props: [object]
events: [object]
uses_apis: [string]
# Shared context
related_models: [object] # Models this entity interacts with
related_apis: [object] # APIs this entity needs/provides
# Dependencies as task IDs
depends_on_tasks: [string] # Task IDs that must complete first
# Output definition
outputs:
files: [string] # Files this task will create
provides: [string] # Entity IDs this task provides
# ============================================================================
# EXECUTION PLAN
# ============================================================================
execution_plan:
description: "Concrete execution order for workflow orchestrator"
phase_schema:
phase: integer # 1, 2, 3... (maps to layers)
# Parallel batch within phase
parallel_batch:
- task_id: string
entity_id: string
agent: enum
# Full context blob for subagent
context_file: string # Path to context snapshot file
# Expected outputs
expected_files: [string]
# Validation to run after completion
validation:
- type: enum # file_exists | lint | typecheck | test
target: string
# Example
example:
- phase: 1
parallel_batch:
- task_id: task_create_model_user
entity_id: model_user
agent: backend
context_file: .workflow/versions/v001/contexts/model_user.yml
expected_files: [prisma/schema.prisma, app/models/user.ts]
validation:
- type: typecheck
target: app/models/user.ts
- task_id: task_create_model_post
entity_id: model_post
agent: backend
context_file: .workflow/versions/v001/contexts/model_post.yml
expected_files: [prisma/schema.prisma, app/models/post.ts]
validation:
- type: typecheck
target: app/models/post.ts
- phase: 2
parallel_batch:
- task_id: task_create_api_create_user
entity_id: api_create_user
agent: backend
context_file: .workflow/versions/v001/contexts/api_create_user.yml
expected_files: [app/api/users/route.ts]
validation:
- type: lint
target: app/api/users/route.ts
- type: typecheck
target: app/api/users/route.ts
# ============================================================================
# CONTEXT SNAPSHOT SCHEMA
# ============================================================================
context_snapshot:
description: "Schema for per-task context files passed to subagents"
snapshot_schema:
# Metadata
task_id: string
entity_id: string
generated_at: timestamp
workflow_version: string
# The entity being implemented
target:
type: enum # model | api | page | component
definition: object # Full definition from design_document
# Related entities (for reference)
related:
models: [object] # Model definitions this task needs to know about
apis: [object] # API contracts this task needs to know about
components: [object] # Component definitions this task needs
# Dependency chain
dependencies:
completed: [string] # Entity IDs already implemented
pending: [string] # Entity IDs not yet implemented (shouldn't depend on)
# File context
files:
to_create: [string] # Files this task should create
to_modify: [string] # Files this task may modify
reference: [string] # Files to read for context
# Acceptance criteria
acceptance:
- criterion: string # What must be true
validation: string # How to verify
# Implementation hints
hints:
patterns: [string] # Patterns to follow (from existing codebase)
avoid: [string] # Anti-patterns to avoid
examples: [string] # Example file paths to reference
# ============================================================================
# GRAPH GENERATION RULES
# ============================================================================
generation_rules:
layer_assignment:
- "Models with no relations → Layer 1"
- "Models with relations to Layer 1 models → Layer 1 (parallel)"
- "APIs depending only on models → Layer 2"
- "Components with no API deps → Layer 3 (parallel with pages)"
- "Pages and components with API deps → Layer 3+"
- "Recursive: if all deps in Layer N, assign to Layer N+1"
parallelism:
- "Items in same layer with no inter-dependencies can run in parallel"
- "Max parallelism = min(layer_item_count, configured_max_agents)"
- "Group by agent type for efficient batching"
context_generation:
- "Include full definition of target entity"
- "Include definitions of all direct dependencies"
- "Include one-level of indirect dependencies for context"
- "Exclude unrelated entities to minimize context size"
validation:
- "No circular dependencies (would prevent layer assignment)"
- "All dependency targets must exist in design_document"
- "Each entity must be in exactly one layer"
- "Layer numbers must be consecutive starting from 1"

463
skills/guardrail-orchestrator/schemas/design_document.yml Normal file
View File

@ -0,0 +1,463 @@
# Design Document Schema
# The source of truth for system design - all tasks derive from this
# Created during DESIGNING phase, approved before IMPLEMENTING
# ============================================================================
# DOCUMENT METADATA
# ============================================================================
design_document:
# Links to workflow
workflow_version: string # e.g., v001
feature: string # Feature being implemented
# Timestamps
created_at: timestamp
updated_at: timestamp
approved_at: timestamp | null
# Design status
status: draft | review | approved | rejected
# Revision tracking
revision: integer # Increments on changes
revision_notes: string # What changed in this revision
# ============================================================================
# LAYER 1: DATA MODELS (ER Diagram)
# ============================================================================
data_models:
description: "Database entities and their relationships"
model_schema:
# Identity
id: string # model_<name> (e.g., model_user, model_post)
name: string # PascalCase entity name (e.g., User, Post)
description: string # What this model represents
# Table/Collection info
table_name: string # snake_case (e.g., users, posts)
# Fields
fields:
- name: string # snake_case field name
type: enum # string | integer | boolean | datetime | uuid | json | text | float | decimal | enum
constraints: [enum] # primary_key | foreign_key | unique | not_null | indexed | auto_increment | default
default: any # Default value if constraint includes 'default'
enum_values: [string] # If type is 'enum', list valid values
description: string # Field purpose
# Relations to other models
relations:
- type: enum # has_one | has_many | belongs_to | many_to_many
target: string # Target model_id (e.g., model_post)
foreign_key: string # FK field name
through: string # Junction table for many_to_many
on_delete: enum # cascade | set_null | restrict | no_action
# Indexes
indexes:
- fields: [string] # Fields in index
unique: boolean # Is unique index
name: string # Index name
# Timestamps (common pattern)
timestamps: boolean # Auto-add created_at, updated_at
soft_delete: boolean # Add deleted_at for soft deletes
# Validation rules (business logic)
validations:
- field: string # Field to validate
rule: string # Validation rule (e.g., "email", "min:8", "max:100")
message: string # Error message
# Example
example_model:
id: model_user
name: User
description: "Application user account"
table_name: users
fields:
- name: id
type: uuid
constraints: [primary_key]
description: "Unique identifier"
- name: email
type: string
constraints: [unique, not_null, indexed]
description: "User email address"
- name: name
type: string
constraints: [not_null]
description: "Display name"
- name: password_hash
type: string
constraints: [not_null]
description: "Bcrypt hashed password"
- name: role
type: enum
enum_values: [user, admin, moderator]
constraints: [not_null, default]
default: user
description: "User role for authorization"
relations:
- type: has_many
target: model_post
foreign_key: user_id
on_delete: cascade
timestamps: true
soft_delete: false
validations:
- field: email
rule: email
message: "Invalid email format"
- field: password_hash
rule: min:60
message: "Invalid password hash"
# ============================================================================
# LAYER 2: API ENDPOINTS
# ============================================================================
api_endpoints:
description: "REST API endpoints with request/response contracts"
endpoint_schema:
# Identity
id: string # api_<verb>_<resource> (e.g., api_create_user)
# HTTP
method: enum # GET | POST | PUT | PATCH | DELETE
path: string # URL path (e.g., /api/users/:id)
# Description
summary: string # Short description
description: string # Detailed description
# Tags for grouping
tags: [string] # e.g., [users, authentication]
# Path parameters
path_params:
- name: string # Parameter name (e.g., id)
type: string # Data type
description: string
# Query parameters (for GET)
query_params:
- name: string # Parameter name
type: string # Data type
required: boolean
default: any
description: string
# Request body (for POST/PUT/PATCH)
request_body:
content_type: string # application/json
schema:
type: object | array
properties:
- name: string
type: string
required: boolean
validations: [string] # Validation rules
description: string
example: object # Example request body
# Response schemas by status code
responses:
- status: integer # HTTP status code
description: string
schema:
type: object | array
properties:
- name: string
type: string
example: object
# Dependencies
depends_on_models: [string] # model_ids this endpoint uses
depends_on_apis: [string] # api_ids this endpoint calls (internal)
# Authentication/Authorization
auth:
required: boolean
roles: [string] # Required roles (empty = any authenticated)
# Rate limiting
rate_limit:
requests: integer # Max requests
window: string # Time window (e.g., "1m", "1h")
# Example
example_endpoint:
id: api_create_user
method: POST
path: /api/users
summary: "Create a new user"
description: "Register a new user account with email and password"
tags: [users, authentication]
request_body:
content_type: application/json
schema:
type: object
properties:
- name: email
type: string
required: true
validations: [email]
description: "User email address"
- name: name
type: string
required: true
validations: [min:1, max:100]
description: "Display name"
- name: password
type: string
required: true
validations: [min:8]
description: "Password (will be hashed)"
example:
email: "user@example.com"
name: "John Doe"
password: "securepass123"
responses:
- status: 201
description: "User created successfully"
schema:
type: object
properties:
- name: id
type: uuid
- name: email
type: string
- name: name
type: string
- name: created_at
type: datetime
example:
id: "550e8400-e29b-41d4-a716-446655440000"
email: "user@example.com"
name: "John Doe"
created_at: "2025-01-16T10:00:00Z"
- status: 400
description: "Validation error"
schema:
type: object
properties:
- name: error
type: string
- name: details
type: array
example:
error: "Validation failed"
details: ["Email is invalid", "Password too short"]
- status: 409
description: "Email already exists"
schema:
type: object
properties:
- name: error
type: string
example:
error: "Email already registered"
depends_on_models: [model_user]
depends_on_apis: []
auth:
required: false
roles: []
# ============================================================================
# LAYER 3: UI PAGES
# ============================================================================
pages:
description: "Application pages/routes"
page_schema:
# Identity
id: string # page_<name> (e.g., page_users, page_user_detail)
name: string # Human-readable name
# Routing
path: string # URL path (e.g., /users, /users/[id])
layout: string # Layout component to use
# Data requirements
data_needs:
- api_id: string # API endpoint to call
purpose: string # Why this data is needed
on_load: boolean # Fetch on page load
# Components used
components: [string] # component_ids used on this page
# SEO
seo:
title: string
description: string
# Auth requirements
auth:
required: boolean
roles: [string]
redirect: string # Where to redirect if not authorized
# State management
state:
local: [string] # Local state variables
global: [string] # Global state dependencies
# Example
example_page:
id: page_users
name: "Users List"
path: /users
layout: layout_dashboard
data_needs:
- api_id: api_list_users
purpose: "Display user list"
on_load: true
components: [component_user_list, component_user_card, component_pagination]
seo:
title: "Users"
description: "View all users"
auth:
required: true
roles: [admin]
redirect: /login
# ============================================================================
# LAYER 3: UI COMPONENTS
# ============================================================================
components:
description: "Reusable UI components"
component_schema:
# Identity
id: string # component_<name> (e.g., component_user_card)
name: string # PascalCase component name
# Props (input)
props:
- name: string # Prop name
type: string # TypeScript type
required: boolean
default: any
description: string
# Events (output)
events:
- name: string # Event name (e.g., onClick, onSubmit)
payload: string # Payload type
description: string
# API calls (if component fetches data)
uses_apis: [string] # api_ids this component calls directly
# Child components
uses_components: [string] # component_ids used inside this component
# State
internal_state: [string] # Internal state variables
# Styling
variants: [string] # Style variants (e.g., primary, secondary)
# Example
example_component:
id: component_user_card
name: UserCard
props:
- name: user
type: User
required: true
description: "User object to display"
- name: showActions
type: boolean
required: false
default: true
description: "Show edit/delete buttons"
events:
- name: onEdit
payload: "User"
description: "Fired when edit button clicked"
- name: onDelete
payload: "string"
description: "Fired when delete confirmed, payload is user ID"
uses_apis: []
uses_components: [component_avatar, component_button]
internal_state: [isDeleting]
variants: [default, compact]
# ============================================================================
# DEPENDENCY GRAPH (Auto-generated from above)
# ============================================================================
dependency_graph:
description: "Execution order based on dependencies - auto-generated"
# Layers for parallel execution
layers:
- layer: 1
name: "Data Models"
description: "Database schema - no dependencies"
items:
- id: string # Entity ID
type: model # model | api | page | component
dependencies: [] # Empty for layer 1
- layer: 2
name: "API Endpoints"
description: "Backend APIs - depend on models"
items:
- id: string
type: api
dependencies: [string] # model_ids
- layer: 3
name: "UI Layer"
description: "Pages and components - depend on APIs"
items:
- id: string
type: page | component
dependencies: [string] # api_ids, component_ids
# Full dependency map for visualization
dependency_map:
model_user:
depends_on: []
depended_by: [api_create_user, api_list_users, api_get_user]
api_create_user:
depends_on: [model_user]
depended_by: [page_user_create, component_user_form]
page_users:
depends_on: [api_list_users, component_user_list]
depended_by: []
# ============================================================================
# DESIGN VALIDATION RULES
# ============================================================================
validation_rules:
models:
- "Every model must have a primary_key field"
- "Foreign keys must reference existing models"
- "Relation targets must exist in data_models"
- "Enum types must have enum_values defined"
apis:
- "Every API must have at least one response defined"
- "POST/PUT/PATCH must have request_body"
- "depends_on_models must reference existing models"
- "Path params must match :param patterns in path"
pages:
- "data_needs must reference existing api_ids"
- "components must reference existing component_ids"
- "auth.redirect must be a valid path"
components:
- "uses_apis must reference existing api_ids"
- "uses_components must reference existing component_ids"
- "No circular component dependencies"
graph:
- "No circular dependencies in dependency_graph"
- "All entities must be assigned to a layer"
- "Layer N items can only depend on Layer < N items"

364
skills/guardrail-orchestrator/schemas/task_template.yml Normal file
View File

@ -0,0 +1,364 @@
# Implementation Task Template Schema
# Used by the Architect agent to create implementation tasks
# Tasks are generated from design_document.yml with full context
# ============================================================================
# TASK DEFINITION
# ============================================================================
task:
# Required fields
id: task_<type>_<entity> # e.g., task_create_model_user, task_create_api_users
type: create | update | delete | refactor | test | review
title: string # Human-readable title
agent: frontend | backend # Which agent implements this
entity_id: string # Primary entity ID from design_document
entity_ids: [string] # All entity IDs this task covers (for multi-entity tasks)
status: pending | in_progress | review | approved | completed | blocked
# Execution layer (from dependency_graph)
layer: integer # Which layer this task belongs to (1, 2, 3...)
parallel_group: string # Group ID for parallel execution
# Optional fields
description: string # Detailed implementation notes
file_paths: [string] # Files to create/modify
dependencies: [string] # Task IDs that must complete first
acceptance_criteria: [string] # Checklist for completion
priority: low | medium | high # Task priority
complexity: low | medium | high # Estimated complexity
# Tracking (set by system)
created_at: datetime
assigned_at: datetime
completed_at: datetime
reviewed_by: string
review_notes: string
# ============================================================================
# CONTEXT SECTION (Passed to subagent)
# ============================================================================
# This is the critical section that provides full context to subagents
# Generated from design_document.yml during task creation
context:
# Source reference
design_version: string # design_document revision
workflow_version: string # Workflow version (v001, etc.)
context_snapshot_path: string # Path to full context file
# TARGET: What this task implements
target:
entity_id: string # model_user, api_create_user, etc.
entity_type: model | api | page | component
definition: object # Full definition from design_document
# For models
model:
name: string
table_name: string
fields: [field_definition]
relations: [relation_definition]
validations: [validation_rule]
indexes: [index_definition]
# For APIs
api:
method: string
path: string
summary: string
path_params: [param_definition]
query_params: [param_definition]
request_body: object
responses: [response_definition]
auth: object
# For pages
page:
path: string
layout: string
data_needs: [data_requirement]
components: [string]
seo: object
auth: object
# For components
component:
name: string
props: [prop_definition]
events: [event_definition]
uses_apis: [string]
uses_components: [string]
variants: [string]
# DEPENDENCIES: What this task needs
dependencies:
# Models this task interacts with
models:
- id: string # model_user
definition:
name: string
fields: [field_definition]
relations: [relation_definition]
# APIs this task needs
apis:
- id: string # api_get_user
definition:
method: string
path: string
request_body: object
responses: [object]
# Components this task uses
components:
- id: string # component_button
definition:
props: [prop_definition]
events: [event_definition]
# CONTRACTS: Input/Output specifications
contracts:
# What this task receives from previous tasks
inputs:
- from_task: string # task_create_model_user
provides: string # model_user
type: model | api | component | file
# What this task provides to later tasks
outputs:
- entity_id: string # api_create_user
type: model | api | component | file
consumers: [string] # [page_user_create, component_user_form]
# FILES: File operations
files:
# Files to create
create: [string]
# Files to modify
modify: [string]
# Files to read for patterns/context
reference:
- path: string
purpose: string # "Similar component pattern", "API route pattern"
# VALIDATION: How to verify completion
validation:
# Required checks
checks:
- type: file_exists | lint | typecheck | test | build
target: string # File or test pattern
required: boolean
# Acceptance criteria (human-readable)
criteria:
- criterion: string
verification: string # How to verify this
# HINTS: Implementation guidance
hints:
# Patterns to follow
patterns:
- pattern: string # "Use existing API route pattern"
reference: string # "app/api/health/route.ts"
# Things to avoid
avoid:
- issue: string
reason: string
# Code examples
examples:
- description: string
file: string
# ============================================================================
# TASK GENERATION RULES
# ============================================================================
generation_rules:
from_model:
task_id: "task_create_model_{model_name}"
type: create
agent: backend
file_paths:
- "prisma/schema.prisma" # Add model to schema
- "app/models/{model_name}.ts" # TypeScript types
acceptance_criteria:
- "Model defined in Prisma schema"
- "TypeScript types exported"
- "Relations properly configured"
- "Migrations generated"
from_api:
task_id: "task_create_api_{endpoint_name}"
type: create
agent: backend
file_paths:
- "app/api/{path}/route.ts"
acceptance_criteria:
- "Endpoint responds to {method} requests"
- "Request validation implemented"
- "Response matches contract"
- "Auth requirements enforced"
- "Error handling complete"
from_page:
task_id: "task_create_page_{page_name}"
type: create
agent: frontend
file_paths:
- "app/{path}/page.tsx"
acceptance_criteria:
- "Page renders at {path}"
- "Data fetching implemented"
- "Components integrated"
- "Auth protection active"
- "SEO metadata set"
from_component:
task_id: "task_create_component_{component_name}"
type: create
agent: frontend
file_paths:
- "app/components/{ComponentName}.tsx"
acceptance_criteria:
- "Component renders correctly"
- "Props typed and documented"
- "Events emitted properly"
- "Variants implemented"
- "Accessible (a11y)"
# ============================================================================
# VALID STATUS TRANSITIONS
# ============================================================================
status_transitions:
pending:
- in_progress # Start work
- blocked # Dependencies not met
in_progress:
- review # Ready for review
- blocked # Hit blocker
review:
- approved # Review passed
- in_progress # Changes requested
approved:
- completed # Final completion
blocked:
- pending # Blocker resolved
- in_progress # Resume after unblock
# ============================================================================
# EXAMPLE: Complete Task with Context
# ============================================================================
example_task:
id: task_create_api_create_user
type: create
title: "Create User API Endpoint"
agent: backend
entity_id: api_create_user
entity_ids: [api_create_user]
status: pending
layer: 2
parallel_group: "layer_2_apis"
description: "Implement POST /api/users endpoint for user registration"
file_paths:
- app/api/users/route.ts
dependencies:
- task_create_model_user
acceptance_criteria:
- "POST /api/users returns 201 on success"
- "Validates email format"
- "Returns 409 if email exists"
- "Hashes password before storage"
- "Returns user object without password"
priority: high
complexity: medium
context:
design_version: "rev_3"
workflow_version: "v001"
context_snapshot_path: ".workflow/versions/v001/contexts/api_create_user.yml"
target:
entity_id: api_create_user
entity_type: api
api:
method: POST
path: /api/users
summary: "Create a new user"
request_body:
type: object
properties:
email: { type: string, required: true, validation: email }
name: { type: string, required: true, validation: "min:1,max:100" }
password: { type: string, required: true, validation: "min:8" }
responses:
- status: 201
schema: { id: uuid, email: string, name: string, created_at: datetime }
- status: 400
schema: { error: string, details: array }
- status: 409
schema: { error: string }
auth:
required: false
dependencies:
models:
- id: model_user
definition:
name: User
table_name: users
fields:
- { name: id, type: uuid, constraints: [primary_key] }
- { name: email, type: string, constraints: [unique, not_null] }
- { name: name, type: string, constraints: [not_null] }
- { name: password_hash, type: string, constraints: [not_null] }
- { name: created_at, type: datetime, constraints: [not_null] }
contracts:
inputs:
- from_task: task_create_model_user
provides: model_user
type: model
outputs:
- entity_id: api_create_user
type: api
consumers: [page_signup, component_signup_form]
files:
create:
- app/api/users/route.ts
reference:
- path: app/api/health/route.ts
purpose: "API route pattern"
- path: app/lib/db.ts
purpose: "Database connection"
- path: app/lib/auth.ts
purpose: "Password hashing"
validation:
checks:
- { type: typecheck, target: "app/api/users/route.ts", required: true }
- { type: lint, target: "app/api/users/route.ts", required: true }
- { type: test, target: "app/api/users/*.test.ts", required: false }
criteria:
- criterion: "Returns 201 with user object on success"
verification: "curl -X POST /api/users with valid data"
- criterion: "Returns 409 if email exists"
verification: "curl -X POST /api/users with duplicate email"
hints:
patterns:
- pattern: "Use NextResponse for responses"
reference: "app/api/health/route.ts"
- pattern: "Use Prisma for database operations"
reference: "app/lib/db.ts"
avoid:
- issue: "Don't store plain text passwords"
reason: "Security vulnerability - always hash with bcrypt"
- issue: "Don't return password_hash in response"
reason: "Sensitive data exposure"
examples:
- description: "Similar API endpoint"
file: "app/api/health/route.ts"

116
skills/guardrail-orchestrator/schemas/workflow_state.yml Normal file
View File

@ -0,0 +1,116 @@
# Workflow State Schema
# Tracks automated workflow progress with approval gates
workflow_state:
# Unique workflow run ID
id: string # workflow_<timestamp>
# Feature/task being implemented
feature: string
# Current phase in the workflow
current_phase:
enum:
- INITIALIZING # Starting workflow
- DESIGNING # Architect creating entities/tasks
- AWAITING_DESIGN_APPROVAL # Gate 1: User approval needed
- DESIGN_APPROVED # User approved design
- DESIGN_REJECTED # User rejected, needs revision
- IMPLEMENTING # Frontend/Backend working
- REVIEWING # Reviewer checking implementation
- AWAITING_IMPL_APPROVAL # Gate 2: User approval needed
- IMPL_APPROVED # User approved implementation
- IMPL_REJECTED # User rejected, needs fixes
- COMPLETING # Marking tasks as done
- COMPLETED # Workflow finished
- PAUSED # User paused workflow
- FAILED # Workflow encountered error
# Approval gates status
gates:
design_approval:
status: pending | approved | rejected
approved_at: timestamp | null
approved_by: string | null
rejection_reason: string | null
revision_count: integer
implementation_approval:
status: pending | approved | rejected
approved_at: timestamp | null
approved_by: string | null
rejection_reason: string | null
revision_count: integer
# Progress tracking
progress:
entities_designed: integer
tasks_created: integer
tasks_implemented: integer
tasks_reviewed: integer
tasks_approved: integer
tasks_completed: integer
# Task tracking
tasks:
pending: [task_id]
in_progress: [task_id]
review: [task_id]
approved: [task_id]
completed: [task_id]
blocked: [task_id]
# Timestamps
started_at: timestamp
updated_at: timestamp
completed_at: timestamp | null
# Error tracking
last_error: string | null
# Resumability
resume_point:
phase: string
task_id: string | null
action: string # What to do when resuming
# Example workflow state file
example:
id: workflow_20250116_143022
feature: "User authentication with OAuth"
current_phase: AWAITING_DESIGN_APPROVAL
gates:
design_approval:
status: pending
approved_at: null
approved_by: null
rejection_reason: null
revision_count: 0
implementation_approval:
status: pending
approved_at: null
approved_by: null
rejection_reason: null
revision_count: 0
progress:
entities_designed: 5
tasks_created: 8
tasks_implemented: 0
tasks_reviewed: 0
tasks_approved: 0
tasks_completed: 0
tasks:
pending: [task_create_LoginPage, task_create_AuthAPI]
in_progress: []
review: []
approved: []
completed: []
blocked: []
started_at: "2025-01-16T14:30:22Z"
updated_at: "2025-01-16T14:35:00Z"
completed_at: null
last_error: null
resume_point:
phase: AWAITING_DESIGN_APPROVAL
task_id: null
action: "await_user_approval"

323
skills/guardrail-orchestrator/schemas/workflow_version.yml Normal file
View File

@ -0,0 +1,323 @@
# Workflow Versioning Schema
# Links workflow sessions with task sessions and operations
# ============================================================================
# WORKFLOW SESSION (Top Level)
# ============================================================================
workflow_session:
# Unique version identifier
version: string # v001, v002, v003...
# Feature being implemented
feature: string
# Session metadata
session_id: string # workflow_<timestamp>
parent_version: string | null # If this is a continuation/fix
# Status
status: pending | in_progress | completed | failed | rolled_back
# Timestamps
started_at: timestamp
completed_at: timestamp | null
# Approval records
approvals:
design:
status: pending | approved | rejected
approved_by: string | null
approved_at: timestamp | null
rejection_reason: string | null
implementation:
status: pending | approved | rejected
approved_by: string | null
approved_at: timestamp | null
rejection_reason: string | null
# Linked task sessions
task_sessions: [task_session_id]
# Aggregate summary
summary:
total_tasks: integer
tasks_completed: integer
entities_created: integer
entities_updated: integer
entities_deleted: integer
files_created: integer
files_updated: integer
files_deleted: integer
# ============================================================================
# TASK SESSION (Per Task)
# ============================================================================
task_session:
# Unique identifier
session_id: string # tasksession_<task_id>_<timestamp>
# Link to parent workflow
workflow_version: string # v001
# Task reference
task_id: string
task_type: create | update | delete | refactor | test
# Agent info
agent: frontend | backend | reviewer | architect
# Timestamps
started_at: timestamp
completed_at: timestamp | null
duration_ms: integer | null
# Status
status: pending | in_progress | review | approved | completed | failed | blocked
# Operations performed in this session
operations: [operation]
# Review link (if reviewed)
review_session: review_session | null
# Error tracking
errors: [error_record]
# Retry info
attempt_number: integer # 1, 2, 3...
previous_attempts: [session_id]
# ============================================================================
# OPERATION (Atomic Change)
# ============================================================================
operation:
# Unique operation ID
id: string # op_<timestamp>_<sequence>
# Operation type
type: CREATE | UPDATE | DELETE | RENAME | MOVE
# Target
target_type: file | entity | task | manifest
target_id: string # entity_id or file path
target_path: string | null # file path if applicable
# Change details
changes:
before: string | null # Previous state/content hash
after: string | null # New state/content hash
diff_summary: string # Human-readable summary
# Timestamp
performed_at: timestamp
# Reversibility
reversible: boolean
rollback_data: object | null # Data needed to reverse
# ============================================================================
# REVIEW SESSION
# ============================================================================
review_session:
session_id: string # review_<task_id>_<timestamp>
# Links
task_session_id: string
workflow_version: string
# Reviewer
reviewer: string # "reviewer" agent or user
# Timing
started_at: timestamp
completed_at: timestamp
# Decision
decision: approved | rejected | needs_changes
# Checks performed
checks:
file_exists: pass | fail | skip
manifest_compliance: pass | fail | skip
code_quality: pass | fail | skip
lint: pass | fail | skip
build: pass | fail | skip
tests: pass | fail | skip
# Feedback
notes: string
issues_found: [string]
suggestions: [string]
# ============================================================================
# ERROR RECORD
# ============================================================================
error_record:
timestamp: timestamp
phase: string # Which step failed
error_type: string
message: string
stack_trace: string | null
resolved: boolean
resolution: string | null
# ============================================================================
# VERSION INDEX (Quick Lookup)
# ============================================================================
version_index:
versions:
- version: v001
feature: "User authentication"
status: completed
started_at: timestamp
completed_at: timestamp
tasks_count: 8
operations_count: 15
- version: v002
feature: "Task filters"
status: in_progress
started_at: timestamp
completed_at: null
tasks_count: 5
operations_count: 7
latest_version: v002
total_versions: 2
# ============================================================================
# TASK SESSION DIRECTORY STRUCTURE
# ============================================================================
task_session_directory:
description: "Each task session has its own directory with full context"
path_pattern: ".workflow/versions/{version}/task_sessions/{task_id}/"
files:
session.yml:
description: "Task session metadata (existing schema)"
schema: task_session
task.yml:
description: "Snapshot of task definition at execution time"
fields:
id: string
type: create | update | delete | refactor | test
title: string
agent: frontend | backend | reviewer | architect
status_at_snapshot: string
entity_ids: [string]
file_paths: [string]
dependencies: [string]
description: string
acceptance_criteria: [string]
snapshotted_at: timestamp
source_path: string
operations.log:
description: "Chronological audit trail of all operations"
format: text
entry_pattern: "[{timestamp}] {operation_type} {target_type}: {target_id} ({path})"
# ============================================================================
# EXAMPLE: Complete Workflow Session
# ============================================================================
example_workflow_session:
version: v001
feature: "User authentication with OAuth"
session_id: workflow_20250116_143022
parent_version: null
status: completed
started_at: "2025-01-16T14:30:22Z"
completed_at: "2025-01-16T15:45:00Z"
approvals:
design:
status: approved
approved_by: user
approved_at: "2025-01-16T14:45:00Z"
rejection_reason: null
implementation:
status: approved
approved_by: user
approved_at: "2025-01-16T15:40:00Z"
rejection_reason: null
task_sessions:
- tasksession_task_create_LoginPage_20250116_144501
- tasksession_task_create_AuthAPI_20250116_145001
- tasksession_task_update_Header_20250116_150001
summary:
total_tasks: 3
tasks_completed: 3
entities_created: 2
entities_updated: 1
entities_deleted: 0
files_created: 3
files_updated: 2
files_deleted: 0
example_task_session:
session_id: tasksession_task_create_LoginPage_20250116_144501
workflow_version: v001
task_id: task_create_LoginPage
task_type: create
agent: frontend
started_at: "2025-01-16T14:45:01Z"
completed_at: "2025-01-16T14:55:00Z"
duration_ms: 599000
status: completed
operations:
- id: op_20250116_144502_001
type: CREATE
target_type: file
target_id: page_login
target_path: app/login/page.tsx
changes:
before: null
after: "sha256:abc123..."
diff_summary: "Created login page with email/password form"
performed_at: "2025-01-16T14:45:02Z"
reversible: true
rollback_data:
action: delete_file
path: app/login/page.tsx
- id: op_20250116_144503_002
type: UPDATE
target_type: manifest
target_id: project_manifest
target_path: project_manifest.json
changes:
before: "sha256:def456..."
after: "sha256:ghi789..."
diff_summary: "Added page_login entity, set status to IMPLEMENTED"
performed_at: "2025-01-16T14:45:03Z"
reversible: true
rollback_data:
action: restore_content
content_hash: "sha256:def456..."
review_session:
session_id: review_task_create_LoginPage_20250116_145501
task_session_id: tasksession_task_create_LoginPage_20250116_144501
workflow_version: v001
reviewer: reviewer
started_at: "2025-01-16T14:55:01Z"
completed_at: "2025-01-16T14:58:00Z"
decision: approved
checks:
file_exists: pass
manifest_compliance: pass
code_quality: pass
lint: pass
build: pass
tests: skip
notes: "Login page implementation matches manifest spec"
issues_found: []
suggestions:
- "Consider adding loading state for form submission"
errors: []
attempt_number: 1
previous_attempts: []

274
skills/guardrail-orchestrator/scripts/MIGRATION_GUIDE.md Normal file
View File

@ -0,0 +1,274 @@
# Task Session Migration Guide
## Overview
This guide explains how to migrate task sessions from the old flat file structure to the new directory-based structure.
## Background
### Old Structure (Flat Files)
```
.workflow/versions/v001/task_sessions/
├── task_design.yml
├── task_implementation.yml
└── task_review.yml
```
### New Structure (Directories)
```
.workflow/versions/v001/task_sessions/
├── task_design/
│ ├── session.yml # Session data (execution info)
│ ├── task.yml # Task snapshot (definition at execution time)
│ └── operations.log # Human-readable operation log
├── task_implementation/
│ ├── session.yml
│ ├── task.yml
│ └── operations.log
└── task_review/
├── session.yml
├── task.yml
└── operations.log
```
## Benefits of New Structure
1. **Better Organization**: Each task session has its own directory
2. **Snapshot Preservation**: Task definitions are captured at execution time
3. **Human-Readable Logs**: Operations log provides easy-to-read history
4. **Extensibility**: Easy to add attachments, artifacts, or outputs per task
5. **Backwards Compatible**: Old code can still read from either structure
## Migration Script
### Location
```
skills/guardrail-orchestrator/scripts/migrate_task_sessions.py
```
### Usage
#### Dry Run (Recommended First Step)
```bash
python3 skills/guardrail-orchestrator/scripts/migrate_task_sessions.py --dry-run
```
This will:
- Find all flat task session files
- Report what would be migrated
- Show actions that would be taken
- **NOT make any changes**
#### Live Migration
```bash
python3 skills/guardrail-orchestrator/scripts/migrate_task_sessions.py
```
This will:
- Create directory for each task session
- Move session data to `session.yml`
- Create `task.yml` snapshot
- Generate `operations.log`
- Delete original flat files
## Migration Process
### What the Script Does
For each flat task session file (e.g., `task_design.yml`):
1. **Create Directory**: `task_sessions/task_design/`
2. **Move Session Data**:
- Read original `task_design.yml`
- Save to `task_design/session.yml`
- Delete original file
3. **Create Task Snapshot**:
- Look for `tasks/task_design.yml`
- If found: Copy and add snapshot metadata
- If not found: Create minimal task.yml from session data
- Save to `task_design/task.yml`
4. **Create Operations Log**:
- Initialize `task_design/operations.log`
- Add migration note
- If session has operations array, convert to log format
- Human-readable format with timestamps
### Task Snapshot Metadata
When a task definition is found, these fields are added:
```yaml
snapshotted_at: '2025-12-16T12:00:00'
source_path: 'tasks/task_design.yml'
status_at_snapshot: 'completed'
migration_note: 'Created during migration from flat file structure'
```
### Operations Log Format
```
# Operations Log for task_design
# Migrated: 2025-12-16T12:00:00
# Format: [timestamp] OPERATION target_type: target_id (path)
======================================================================
[2025-12-16T12:00:00] MIGRATION: Converted from flat file structure
# Historical operations from session data:
[2025-12-16T11:00:00] CREATE file: auth.ts (app/lib/auth.ts)
Summary: Created authentication module
[2025-12-16T11:15:00] UPDATE entity: User (app/lib/types.ts)
Summary: Added email field to User type
```
## Migration Results
### Success Output
```
======================================================================
Migration Summary
======================================================================
Total files processed: 3
Successful migrations: 3
Failed migrations: 0
Migration completed successfully!
Next steps:
1. Verify migrated files in .workflow/versions/*/task_sessions/
2. Check that each task has session.yml, task.yml, and operations.log
3. Test the system to ensure compatibility
```
### Dry Run Output
```
Processing: v001/task_design.yml
----------------------------------------------------------------------
Would create directory: .workflow/versions/v001/task_sessions/task_design
Would move task_design.yml to .workflow/versions/v001/task_sessions/task_design/session.yml
Would create .workflow/versions/v001/task_sessions/task_design/task.yml (if source exists)
Would create .workflow/versions/v001/task_sessions/task_design/operations.log
This was a DRY RUN. No files were modified.
Run without --dry-run to perform the migration.
```
## Verification Steps
After migration, verify the structure:
```bash
# Check directory structure
ls -la .workflow/versions/v001/task_sessions/task_design/
# Should show:
# session.yml
# task.yml
# operations.log
# Verify session data
cat .workflow/versions/v001/task_sessions/task_design/session.yml
# Verify task snapshot
cat .workflow/versions/v001/task_sessions/task_design/task.yml
# Check operations log
cat .workflow/versions/v001/task_sessions/task_design/operations.log
```
## Backwards Compatibility
The `version_manager.py` module includes backwards-compatible loading:
```python
def load_task_session(version: str, task_id: str) -> Optional[dict]:
"""Load a task session from directory or flat file (backwards compatible)."""
# Try new directory structure first
session_dir = get_version_dir(version) / 'task_sessions' / task_id
session_path = session_dir / 'session.yml'
if session_path.exists():
return load_yaml(str(session_path))
# Fallback to old flat file structure
old_path = get_version_dir(version) / 'task_sessions' / f'{task_id}.yml'
if old_path.exists():
return load_yaml(str(old_path))
return None
```
This means:
- New code works with both structures
- No breaking changes for existing workflows
- Migration can be done gradually
- Rollback is possible if needed
## Troubleshooting
### No Files Found
If the script reports "No flat task session files found":
- Check that `.workflow/versions/` exists
- Verify that task sessions are in expected location
- Confirm files have `.yml` or `.yaml` extension
- May indicate all sessions are already migrated
### Task File Not Found
If `tasks/task_id.yml` doesn't exist:
- Script creates minimal task.yml from session data
- Warning is logged but migration continues
- Check `task.yml` has `migration_note` field
### Migration Errors
If migration fails:
- Review error message in output
- Check file permissions
- Verify disk space
- Try dry-run mode to diagnose
### Rollback (If Needed)
To rollback a migration:
1. Stop any running workflows
2. For each migrated directory:
```bash
# Copy session.yml back to flat file
cp .workflow/versions/v001/task_sessions/task_design/session.yml \
.workflow/versions/v001/task_sessions/task_design.yml
# Remove directory
rm -rf .workflow/versions/v001/task_sessions/task_design/
```
## Best Practices
1. **Always dry-run first**: Use `--dry-run` to preview changes
2. **Backup before migration**: Copy `.workflow/` directory
3. **Migrate per version**: Test one version before migrating all
4. **Verify after migration**: Check files and run system tests
5. **Keep old backups**: Don't delete backups immediately
## Integration with Workflow System
After migration, all workflow operations work seamlessly:
```python
# Start task session (creates directory structure)
session = create_workflow_session("new feature", None)
task_session = create_task_session(session, "task_api", "create", "backend")
# Load task session (works with both structures)
task = load_task_session("v001", "task_design")
# Log operations (appends to operations.log)
log_operation(task, "CREATE", "file", "api.ts", target_path="app/api/api.ts")
```
## Additional Resources
- `version_manager.py`: Core versioning system
- `workflow_manager.py`: Workflow orchestration
- `.workflow/operations.log`: Global operations log
- `.workflow/index.yml`: Version index

486
skills/guardrail-orchestrator/scripts/analyze_codebase.py Executable file
View File

@ -0,0 +1,486 @@
#!/usr/bin/env python3
"""Analyze codebase and generate project manifest from existing code."""
import argparse
import json
import os
import re
import sys
from datetime import datetime
from pathlib import Path
from typing import Any, Optional
def find_files(base_path: str, pattern: str) -> list[str]:
"""Find files matching a glob pattern."""
base = Path(base_path)
return [str(p.relative_to(base)) for p in base.glob(pattern)]
def read_file(filepath: str) -> str:
"""Read file contents."""
try:
with open(filepath, 'r', encoding='utf-8') as f:
return f.read()
except Exception:
return ""
def extract_component_name(filepath: str) -> str:
"""Extract component name from file path."""
name = Path(filepath).stem
return name
def to_snake_case(name: str) -> str:
"""Convert PascalCase to snake_case."""
s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)
return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
def extract_props_from_content(content: str) -> dict:
"""Extract props interface from component content."""
props = {}
# Look for interface Props or type Props
interface_match = re.search(
r'(?:interface|type)\s+\w*Props\w*\s*(?:=\s*)?\{([^}]+)\}',
content,
re.DOTALL
)
if interface_match:
props_block = interface_match.group(1)
# Parse individual props
prop_matches = re.findall(
r'(\w+)(\?)?:\s*([^;,\n]+)',
props_block
)
for name, optional, prop_type in prop_matches:
props[name] = {
"type": prop_type.strip(),
"optional": bool(optional)
}
return props
def extract_imports(content: str) -> list[str]:
"""Extract component imports from file."""
imports = []
# Look for imports from components directory
import_matches = re.findall(
r"import\s+\{?\s*([^}]+)\s*\}?\s+from\s+['\"]\.\.?/components/(\w+)['\"]",
content
)
for imported, component in import_matches:
imports.append(component)
# Also check for direct component imports
direct_imports = re.findall(
r"import\s+(\w+)\s+from\s+['\"]\.\.?/components/(\w+)['\"]",
content
)
for imported, component in direct_imports:
imports.append(component)
return list(set(imports))
def extract_api_methods(content: str) -> list[str]:
"""Extract HTTP methods from API route file."""
methods = []
method_patterns = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']
for method in method_patterns:
if re.search(rf'export\s+(?:async\s+)?function\s+{method}\s*\(', content):
methods.append(method)
return methods
def extract_fetch_calls(content: str) -> list[str]:
"""Extract API fetch calls from content."""
apis = []
# Look for fetch('/api/...') patterns - handle static paths
fetch_matches = re.findall(
r"fetch\s*\(\s*['\"`]/api/([^'\"`\?\$\{]+)",
content
)
apis.extend(fetch_matches)
# Look for fetch(`/api/tasks`) or similar template literals with static paths
template_matches = re.findall(
r"fetch\s*\(\s*`/api/(\w+)`",
content
)
apis.extend(template_matches)
# Clean up: remove trailing slashes and normalize
cleaned = []
for api in apis:
api = api.rstrip('/')
if api and not api.startswith('$'):
cleaned.append(api)
return list(set(cleaned))
def extract_types_from_db(content: str) -> dict:
"""Extract type definitions from db.ts or similar."""
types = {}
# Extract interfaces
interface_matches = re.findall(
r'export\s+interface\s+(\w+)\s*\{([^}]+)\}',
content,
re.DOTALL
)
for name, body in interface_matches:
fields = {}
field_matches = re.findall(r'(\w+)(\?)?:\s*([^;,\n]+)', body)
for field_name, optional, field_type in field_matches:
fields[field_name] = field_type.strip()
types[name] = fields
# Extract type aliases
type_matches = re.findall(
r"export\s+type\s+(\w+)\s*=\s*([^;]+);",
content
)
for name, type_def in type_matches:
types[name] = type_def.strip()
return types
def path_to_route(filepath: str) -> str:
"""Convert file path to route path."""
# Remove app/ prefix and page.tsx suffix
route = filepath.replace('app/', '').replace('/page.tsx', '').replace('page.tsx', '')
if route == '' or route == '/':
return '/'
# Handle dynamic segments [id] -> [id]
route = re.sub(r'\[([^\]]+)\]', r'[\1]', route)
# Ensure starts with /
if not route.startswith('/'):
route = '/' + route
return route
def analyze_pages(base_path: str) -> list[dict]:
"""Analyze all page files."""
pages = []
page_files = find_files(base_path, 'app/**/page.tsx')
for filepath in page_files:
full_path = os.path.join(base_path, filepath)
content = read_file(full_path)
route = path_to_route(filepath)
# Generate page ID
if route == '/' or filepath == 'app/page.tsx':
page_id = 'page_home'
name = 'Home'
route = '/'
else:
name = route.strip('/').replace('/', '_').replace('[', '').replace(']', '')
page_id = f'page_{name}'
# Extract component imports
components = extract_imports(content)
comp_ids = [f"comp_{to_snake_case(c)}" for c in components]
# Extract API dependencies
api_calls = extract_fetch_calls(content)
api_ids = [f"api_{a.replace('/', '_')}" for a in api_calls]
pages.append({
"id": page_id,
"path": route,
"file_path": filepath,
"status": "IMPLEMENTED",
"description": f"Page at {route}",
"components": comp_ids,
"data_dependencies": api_ids
})
return pages
def analyze_components(base_path: str) -> list[dict]:
"""Analyze all component files."""
components = []
component_files = find_files(base_path, 'app/components/*.tsx')
for filepath in component_files:
full_path = os.path.join(base_path, filepath)
content = read_file(full_path)
name = extract_component_name(filepath)
comp_id = f"comp_{to_snake_case(name)}"
# Extract props
props = extract_props_from_content(content)
components.append({
"id": comp_id,
"name": name,
"file_path": filepath,
"status": "IMPLEMENTED",
"description": f"{name} component",
"props": props
})
return components
def analyze_apis(base_path: str) -> list[dict]:
"""Analyze all API route files."""
apis = []
api_files = find_files(base_path, 'app/api/**/route.ts')
for filepath in api_files:
full_path = os.path.join(base_path, filepath)
content = read_file(full_path)
# Extract path from file location
path = '/' + filepath.replace('app/', '').replace('/route.ts', '')
# Extract HTTP methods
methods = extract_api_methods(content)
for method in methods:
# Generate action name from method
action_map = {
'GET': 'list' if '[' not in path else 'get',
'POST': 'create',
'PUT': 'update',
'DELETE': 'delete',
'PATCH': 'patch'
}
action = action_map.get(method, method.lower())
# Generate resource name from path
resource = path.replace('/api/', '').replace('/', '_').replace('[', '').replace(']', '')
if not resource:
resource = 'root'
api_id = f"api_{action}_{resource}"
apis.append({
"id": api_id,
"path": path,
"method": method,
"file_path": filepath,
"status": "IMPLEMENTED",
"description": f"{method} {path}",
"request": {},
"response": {
"type": "object",
"description": "Response data"
}
})
return apis
def analyze_database(base_path: str) -> tuple[list[dict], dict]:
"""Analyze database/type files."""
tables = []
types = {}
# Check for db.ts file
db_path = os.path.join(base_path, 'app/lib/db.ts')
if os.path.exists(db_path):
content = read_file(db_path)
types = extract_types_from_db(content)
# Look for table/collection definitions
if 'tasks' in content.lower():
tables.append({
"id": "table_tasks",
"name": "tasks",
"file_path": "app/lib/db.ts",
"status": "IMPLEMENTED",
"description": "Tasks storage",
"columns": types.get('Task', {})
})
return tables, types
def build_dependencies(pages: list, components: list, apis: list) -> dict:
"""Build dependency mappings."""
component_to_page = {}
api_to_component = {}
# Build component to page mapping
for page in pages:
for comp_id in page.get('components', []):
if comp_id not in component_to_page:
component_to_page[comp_id] = []
component_to_page[comp_id].append(page['id'])
# API to component would require deeper analysis
# For now, we'll leave it based on page dependencies
return {
"component_to_page": component_to_page,
"api_to_component": {},
"table_to_api": {}
}
def generate_manifest(
base_path: str,
project_name: Optional[str] = None
) -> dict:
"""Generate complete project manifest."""
# Determine project name
if not project_name:
# Try to get from package.json
pkg_path = os.path.join(base_path, 'package.json')
if os.path.exists(pkg_path):
try:
with open(pkg_path) as f:
pkg = json.load(f)
project_name = pkg.get('name', Path(base_path).name)
except Exception:
project_name = Path(base_path).name
else:
project_name = Path(base_path).name
# Analyze codebase
pages = analyze_pages(base_path)
components = analyze_components(base_path)
apis = analyze_apis(base_path)
tables, types = analyze_database(base_path)
dependencies = build_dependencies(pages, components, apis)
now = datetime.now().isoformat()
manifest = {
"project": {
"name": project_name,
"version": "1.0.0",
"created_at": now,
"description": f"Project manifest for {project_name}"
},
"state": {
"current_phase": "IMPLEMENTATION_PHASE",
"approval_status": {
"manifest_approved": True,
"approved_by": "analyzer",
"approved_at": now
},
"revision_history": [
{
"action": "MANIFEST_GENERATED",
"timestamp": now,
"details": "Generated from existing codebase analysis"
}
]
},
"entities": {
"pages": pages,
"components": components,
"api_endpoints": apis,
"database_tables": tables
},
"dependencies": dependencies,
"types": types
}
return manifest
def main():
parser = argparse.ArgumentParser(
description='Analyze codebase and generate project manifest'
)
parser.add_argument(
'--path',
default='.',
help='Path to project root'
)
parser.add_argument(
'--name',
help='Project name (defaults to package.json name or directory name)'
)
parser.add_argument(
'--output',
default='project_manifest.json',
help='Output file path'
)
parser.add_argument(
'--dry-run',
action='store_true',
help='Print manifest without writing to file'
)
parser.add_argument(
'--force',
action='store_true',
help='Overwrite existing manifest'
)
args = parser.parse_args()
base_path = os.path.abspath(args.path)
output_path = os.path.join(base_path, args.output)
# Check for existing manifest
if os.path.exists(output_path) and not args.force and not args.dry_run:
print(f"Error: {args.output} already exists. Use --force to overwrite.")
sys.exit(1)
print(f"Analyzing codebase at: {base_path}")
print()
# Generate manifest
manifest = generate_manifest(base_path, args.name)
# Count entities
pages = len(manifest['entities']['pages'])
components = len(manifest['entities']['components'])
apis = len(manifest['entities']['api_endpoints'])
tables = len(manifest['entities']['database_tables'])
if args.dry_run:
print(json.dumps(manifest, indent=2))
else:
with open(output_path, 'w') as f:
json.dump(manifest, f, indent=2)
print(f"Manifest written to: {output_path}")
print()
print("╔══════════════════════════════════════════════════════════════╗")
print("║ 📊 MANIFEST GENERATED ║")
print("╠══════════════════════════════════════════════════════════════╣")
print(f"║ Project: {manifest['project']['name']:<51} ║")
print("╠══════════════════════════════════════════════════════════════╣")
print("║ ENTITIES DISCOVERED ║")
print(f"║ 📄 Pages: {pages:<43} ║")
print(f"║ 🧩 Components: {components:<43} ║")
print(f"║ 🔌 APIs: {apis:<43} ║")
print(f"║ 🗄️ Tables: {tables:<43} ║")
print("╠══════════════════════════════════════════════════════════════╣")
print("║ Status: All entities marked as IMPLEMENTED ║")
print("║ Phase: IMPLEMENTATION_PHASE ║")
print("╚══════════════════════════════════════════════════════════════╝")
if __name__ == '__main__':
main()

615
skills/guardrail-orchestrator/scripts/generate_api_contract.py Normal file
View File

@ -0,0 +1,615 @@
#!/usr/bin/env python3
"""
Generate API Contract and Shared Types from Design Document
This script:
1. Reads the design_document.yml
2. Extracts all API endpoints and their types
3. Generates api_contract.yml with strict typing
4. Generates app/types/api.ts with shared TypeScript interfaces
Both frontend and backend agents MUST use these generated files
to ensure contract compliance.
"""
import os
import sys
import json
from pathlib import Path
from datetime import datetime
from typing import Dict, List, Any, Optional, Set
try:
import yaml
except ImportError:
yaml = None
def load_yaml(path: Path) -> Dict:
"""Load YAML file."""
if yaml:
with open(path) as f:
return yaml.safe_load(f)
else:
# Fallback: simple YAML parser for basic cases
with open(path) as f:
content = f.read()
# Try JSON first (YAML is superset of JSON)
try:
return json.loads(content)
except:
print(f"Warning: yaml module not available, using basic parser", file=sys.stderr)
return {}
def save_yaml(data: Dict, path: Path) -> None:
"""Save data as YAML."""
if yaml:
with open(path, 'w') as f:
yaml.dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
else:
# Fallback: JSON format
with open(path, 'w') as f:
json.dump(data, f, indent=2)
def ts_type_from_field(field: Dict) -> str:
"""Convert design document field type to TypeScript type."""
type_map = {
'string': 'string',
'text': 'string',
'integer': 'number',
'float': 'number',
'decimal': 'number',
'boolean': 'boolean',
'datetime': 'Date',
'date': 'Date',
'uuid': 'string',
'json': 'Record<string, unknown>',
'array': 'unknown[]',
}
field_type = field.get('type', 'string')
# Handle enum type
if field_type == 'enum':
enum_values = field.get('enum_values', [])
if enum_values:
return ' | '.join([f"'{v}'" for v in enum_values])
return 'string'
return type_map.get(field_type, 'unknown')
def generate_type_from_model(model: Dict) -> Dict:
"""Generate TypeScript type definition from model."""
type_id = f"type_{model['name']}"
properties = []
for field in model.get('fields', []):
# Skip internal fields like password_hash
if field['name'].endswith('_hash'):
continue
constraints = field.get('constraints', [])
required = 'not_null' in constraints or 'primary_key' in constraints
properties.append({
'name': to_camel_case(field['name']),
'type': ts_type_from_field(field),
'required': required,
'description': field.get('description', ''),
})
return {
'id': type_id,
'name': model['name'],
'definition': {
'type': 'object',
'properties': properties,
},
'used_by': {
'models': [model['id']],
'responses': [],
'requests': [],
}
}
def generate_request_type(endpoint: Dict) -> Optional[Dict]:
"""Generate request body type from endpoint definition."""
request_body = endpoint.get('request_body', {})
if not request_body:
return None
schema = request_body.get('schema', {})
if not schema:
return None
# Generate type name from endpoint
parts = endpoint['id'].replace('api_', '').split('_')
type_name = ''.join([p.capitalize() for p in parts]) + 'Request'
type_id = f"type_{type_name}"
properties = []
for prop in schema.get('properties', []):
properties.append({
'name': to_camel_case(prop['name']),
'type': ts_type_from_field(prop),
'required': prop.get('required', False),
'description': prop.get('description', ''),
'validation': ','.join(prop.get('validations', [])) if prop.get('validations') else None,
})
return {
'id': type_id,
'name': type_name,
'definition': {
'type': 'object',
'properties': properties,
},
'used_by': {
'models': [],
'responses': [],
'requests': [endpoint['id']],
}
}
def generate_response_type(endpoint: Dict, models: Dict[str, Dict]) -> Optional[Dict]:
"""Generate response type from endpoint definition - may reference model types."""
responses = endpoint.get('responses', [])
success_response = None
for resp in responses:
status = resp.get('status', 0)
if 200 <= status < 300:
success_response = resp
break
if not success_response:
return None
# Check if this response references a model
depends_on = endpoint.get('depends_on_models', [])
if depends_on:
# Response likely uses model type
primary_model = depends_on[0]
if primary_model in models:
return None # Will use model type directly
# Generate custom response type
schema = success_response.get('schema', {})
if not schema or schema.get('type') != 'object':
return None
parts = endpoint['id'].replace('api_', '').split('_')
type_name = ''.join([p.capitalize() for p in parts]) + 'Response'
type_id = f"type_{type_name}"
properties = []
for prop in schema.get('properties', []):
properties.append({
'name': to_camel_case(prop['name']),
'type': ts_type_from_field(prop),
'required': True,
'description': '',
})
return {
'id': type_id,
'name': type_name,
'definition': {
'type': 'object',
'properties': properties,
},
'used_by': {
'models': [],
'responses': [endpoint['id']],
'requests': [],
}
}
def to_camel_case(snake_str: str) -> str:
"""Convert snake_case to camelCase."""
components = snake_str.split('_')
return components[0] + ''.join(x.capitalize() for x in components[1:])
def generate_endpoint_contract(endpoint: Dict, types: Dict[str, Dict], models: Dict[str, Dict]) -> Dict:
"""Generate endpoint contract from design document endpoint."""
# Determine request body type
request_body = None
if endpoint.get('request_body'):
# Generate request type name
parts = endpoint['id'].replace('api_', '').split('_')
type_name = ''.join([p.capitalize() for p in parts]) + 'Request'
request_body = {
'type_id': f"type_{type_name}",
'content_type': 'application/json',
}
# Determine response type
response_type_id = None
is_array = False
responses = endpoint.get('responses', [])
success_response = None
for resp in responses:
if 200 <= resp.get('status', 0) < 300:
success_response = resp
break
if success_response:
# Check if referencing a model
depends_on = endpoint.get('depends_on_models', [])
if depends_on:
model_id = depends_on[0]
if model_id in models:
model_name = models[model_id].get('name', model_id.replace('model_', '').capitalize())
response_type_id = f"type_{model_name}"
# Check if response is array
schema = success_response.get('schema', {})
if schema.get('type') == 'array':
is_array = True
if not response_type_id:
parts = endpoint['id'].replace('api_', '').split('_')
type_name = ''.join([p.capitalize() for p in parts]) + 'Response'
response_type_id = f"type_{type_name}"
# Extract path params
path_params = []
for param in endpoint.get('path_params', []):
path_params.append({
'name': param['name'],
'type': ts_type_from_field(param),
'description': param.get('description', ''),
})
# Extract query params
query_params = []
for param in endpoint.get('query_params', []):
query_params.append({
'name': param['name'],
'type': ts_type_from_field(param),
'required': param.get('required', False),
'default': param.get('default'),
'description': param.get('description', ''),
})
# Build error responses
error_responses = []
for resp in responses:
status = resp.get('status', 0)
if status >= 400:
error_responses.append({
'status': status,
'type_id': 'type_ApiError',
'description': resp.get('description', ''),
})
return {
'id': endpoint['id'],
'method': endpoint['method'],
'path': endpoint['path'],
'path_params': path_params,
'query_params': query_params,
'request_body': request_body,
'response': {
'success': {
'status': success_response.get('status', 200) if success_response else 200,
'type_id': response_type_id,
'is_array': is_array,
},
'errors': error_responses,
},
'auth': endpoint.get('auth', {'required': False, 'roles': []}),
'version': '1.0.0',
}
def generate_frontend_calls(pages: List[Dict], components: List[Dict], endpoints: Dict[str, Dict]) -> List[Dict]:
"""Generate frontend call contracts from pages and components."""
calls = []
# From pages
for page in pages:
for data_need in page.get('data_needs', []):
api_id = data_need.get('api_id')
if api_id and api_id in endpoints:
calls.append({
'id': f"call_{page['id']}_{api_id}",
'source': {
'entity_id': page['id'],
'file_path': f"app{page['path']}/page.tsx",
},
'endpoint_id': api_id,
'purpose': data_need.get('purpose', 'Load data'),
'trigger': 'onLoad' if data_need.get('on_load') else 'onDemand',
'request_mapping': {
'from_props': [],
'from_state': [],
'from_form': [],
},
'response_handling': {
'success_action': 'Update state',
'error_action': 'Show error',
},
})
# From components
for component in components:
for api_id in component.get('uses_apis', []):
if api_id in endpoints:
endpoint = endpoints[api_id]
method = endpoint.get('method', 'GET')
trigger = 'onSubmit' if method in ['POST', 'PUT', 'PATCH'] else 'onDemand'
calls.append({
'id': f"call_{component['id']}_{api_id}",
'source': {
'entity_id': component['id'],
'file_path': f"app/components/{component['name']}.tsx",
},
'endpoint_id': api_id,
'purpose': f"Call {api_id}",
'trigger': trigger,
'request_mapping': {
'from_props': [],
'from_state': [],
'from_form': [],
},
'response_handling': {
'success_action': 'Handle response',
'error_action': 'Show error',
},
})
return calls
def generate_backend_routes(endpoints: List[Dict]) -> List[Dict]:
"""Generate backend route contracts from endpoints."""
routes = []
for endpoint in endpoints:
# Determine file path from endpoint path
api_path = endpoint['path'].replace('/api/', '')
# Handle dynamic segments like /users/:id
parts = api_path.split('/')
file_parts = []
for part in parts:
if part.startswith(':'):
file_parts.append(f"[{part[1:]}]")
else:
file_parts.append(part)
file_path = f"app/api/{'/'.join(file_parts)}/route.ts"
routes.append({
'id': f"route_{endpoint['method'].lower()}_{api_path.replace('/', '_')}",
'endpoint_id': endpoint['id'],
'file_path': file_path,
'export_name': endpoint['method'],
'uses_models': endpoint.get('depends_on_models', []),
'uses_services': [],
'must_validate': [],
'must_authenticate': endpoint.get('auth', {}).get('required', False),
'must_authorize': endpoint.get('auth', {}).get('roles', []),
})
return routes
def generate_typescript_types(types: List[Dict]) -> str:
"""Generate TypeScript type definitions."""
lines = [
"// AUTO-GENERATED - DO NOT EDIT",
"// Source: .workflow/versions/vXXX/contracts/api_contract.yml",
f"// Generated: {datetime.now().isoformat()}",
"",
"// ============================================================================",
"// Shared API Types",
"// Both frontend and backend MUST import from this file",
"// ============================================================================",
"",
]
# Add standard error types
lines.extend([
"// === Error Types ===",
"",
"export interface ApiError {",
" error: string;",
" message?: string;",
" code?: string;",
"}",
"",
"export interface ValidationError {",
" error: string;",
" details: string[];",
"}",
"",
])
# Generate interfaces for each type
lines.append("// === Domain Types ===")
lines.append("")
for type_def in types:
name = type_def['name']
definition = type_def['definition']
if definition['type'] == 'object':
lines.append(f"export interface {name} {{")
for prop in definition.get('properties', []):
optional = '' if prop.get('required') else '?'
desc = prop.get('description', '')
if desc:
lines.append(f" /** {desc} */")
lines.append(f" {prop['name']}{optional}: {prop['type']};")
lines.append("}")
lines.append("")
elif definition['type'] == 'enum':
values = definition.get('enum_values', [])
quoted_values = [f"'{v}'" for v in values]
lines.append(f"export type {name} = {' | '.join(quoted_values)};")
lines.append("")
elif definition['type'] == 'union':
members = definition.get('union_members', [])
lines.append(f"export type {name} = {' | '.join(members)};")
lines.append("")
return '\n'.join(lines)
def generate_api_paths(endpoints: List[Dict]) -> str:
"""Generate API path constants for type-safe calls."""
lines = [
"",
"// === API Paths ===",
"",
"export const API_PATHS = {",
]
for endpoint in endpoints:
# Generate constant name: api_get_users -> GET_USERS
const_name = endpoint['id'].replace('api_', '').upper()
lines.append(f" {const_name}: '{endpoint['path']}' as const,")
lines.append("} as const;")
lines.append("")
return '\n'.join(lines)
def main():
"""Main entry point."""
if len(sys.argv) < 2:
print("Usage: generate_api_contract.py <design_document.yml> [--output-dir <dir>]", file=sys.stderr)
sys.exit(1)
design_doc_path = Path(sys.argv[1])
# Parse output directory
output_dir = design_doc_path.parent.parent # .workflow/versions/vXXX/
if '--output-dir' in sys.argv:
idx = sys.argv.index('--output-dir')
output_dir = Path(sys.argv[idx + 1])
if not design_doc_path.exists():
print(f"Error: Design document not found: {design_doc_path}", file=sys.stderr)
sys.exit(1)
# Load design document
design_doc = load_yaml(design_doc_path)
if not design_doc:
print("Error: Failed to load design document", file=sys.stderr)
sys.exit(1)
# Extract entities
models = {m['id']: m for m in design_doc.get('data_models', [])}
endpoints = design_doc.get('api_endpoints', [])
pages = design_doc.get('pages', [])
components = design_doc.get('components', [])
workflow_version = design_doc.get('workflow_version', 'unknown')
revision = design_doc.get('revision', 1)
# Generate types from models
types = []
for model in models.values():
type_def = generate_type_from_model(model)
types.append(type_def)
# Generate request/response types from endpoints
endpoints_dict = {e['id']: e for e in endpoints}
for endpoint in endpoints:
req_type = generate_request_type(endpoint)
if req_type:
types.append(req_type)
resp_type = generate_response_type(endpoint, models)
if resp_type:
types.append(resp_type)
# Generate types dictionary for lookup
types_dict = {t['id']: t for t in types}
# Generate endpoint contracts
endpoint_contracts = []
for endpoint in endpoints:
contract = generate_endpoint_contract(endpoint, types_dict, models)
endpoint_contracts.append(contract)
# Generate frontend calls
frontend_calls = generate_frontend_calls(pages, components, endpoints_dict)
# Generate backend routes
backend_routes = generate_backend_routes(endpoints)
# Build API contract
api_contract = {
'api_contract': {
'workflow_version': workflow_version,
'design_document_revision': revision,
'generated_at': datetime.now().isoformat(),
'validated_at': None,
'status': 'draft',
},
'types': types,
'endpoints': endpoint_contracts,
'frontend_calls': frontend_calls,
'backend_routes': backend_routes,
}
# Create output directories
contracts_dir = output_dir / 'contracts'
contracts_dir.mkdir(parents=True, exist_ok=True)
# Save API contract
contract_path = contracts_dir / 'api_contract.yml'
save_yaml(api_contract, contract_path)
print(f"Generated: {contract_path}")
# Generate TypeScript types
ts_types = generate_typescript_types(types)
ts_paths = generate_api_paths(endpoint_contracts)
# Find project root (look for package.json)
project_root = output_dir
while project_root != project_root.parent:
if (project_root / 'package.json').exists():
break
project_root = project_root.parent
if not (project_root / 'package.json').exists():
project_root = output_dir.parent.parent.parent # Assume .workflow is in project root
# Create types directory and file
types_dir = project_root / 'app' / 'types'
types_dir.mkdir(parents=True, exist_ok=True)
types_file = types_dir / 'api.ts'
types_file.write_text(ts_types + ts_paths)
print(f"Generated: {types_file}")
# Summary
print("\n=== API CONTRACT GENERATED ===")
print(f"Types: {len(types)}")
print(f"Endpoints: {len(endpoint_contracts)}")
print(f"Frontend calls: {len(frontend_calls)}")
print(f"Backend routes: {len(backend_routes)}")
print(f"\nContract file: {contract_path}")
print(f"Types file: {types_file}")
print("\nBoth agents MUST import from app/types/api.ts")
if __name__ == '__main__':
main()

73
skills/guardrail-orchestrator/scripts/init_project.py Normal file
View File

@ -0,0 +1,73 @@
#!/usr/bin/env python3
"""Initialize a guardrailed project with manifest."""
import argparse
import json
import os
from datetime import datetime
def create_manifest(name: str, path: str) -> dict:
"""Create initial project manifest structure."""
return {
"project": {
"name": name,
"version": "0.1.0",
"created_at": datetime.now().isoformat(),
"description": f"{name} - A guardrailed project"
},
"state": {
"current_phase": "DESIGN_PHASE",
"approval_status": {
"manifest_approved": False,
"approved_by": None,
"approved_at": None
},
"revision_history": [
{
"action": "PROJECT_INITIALIZED",
"timestamp": datetime.now().isoformat(),
"details": f"Project {name} created"
}
]
},
"entities": {
"pages": [],
"components": [],
"api_endpoints": [],
"database_tables": []
},
"dependencies": {
"component_to_page": {},
"api_to_component": {},
"table_to_api": {}
}
}
def main():
parser = argparse.ArgumentParser(description="Initialize guardrailed project")
parser.add_argument("--name", required=True, help="Project name")
parser.add_argument("--path", required=True, help="Project path")
args = parser.parse_args()
manifest_path = os.path.join(args.path, "project_manifest.json")
if os.path.exists(manifest_path):
print(f"Warning: Manifest already exists at {manifest_path}")
print("Use --force to overwrite (not implemented)")
return 1
manifest = create_manifest(args.name, args.path)
with open(manifest_path, "w") as f:
json.dump(manifest, f, indent=2)
print(f"Initialized guardrailed project: {args.name}")
print(f"Manifest created at: {manifest_path}")
print(f"Current phase: DESIGN_PHASE")
return 0
if __name__ == "__main__":
exit(main())

530
skills/guardrail-orchestrator/scripts/manifest_diff.py Normal file
View File

@ -0,0 +1,530 @@
#!/usr/bin/env python3
"""
Manifest diffing and changelog generation between workflow versions.
Compares project_manifest.json snapshots to show:
- Added entities (pages, components, API endpoints)
- Removed entities
- Modified entities (status changes, path changes)
- Dependency changes
"""
import argparse
import json
import os
import sys
from datetime import datetime
from pathlib import Path
from typing import Dict, List, Optional, Set, Tuple, Any
# Try to import yaml
try:
import yaml
HAS_YAML = True
except ImportError:
HAS_YAML = False
# ============================================================================
# File Helpers
# ============================================================================
def load_json(filepath: str) -> dict:
"""Load JSON file."""
if not os.path.exists(filepath):
return {}
with open(filepath, 'r') as f:
return json.load(f)
def load_yaml(filepath: str) -> dict:
"""Load YAML file."""
if not os.path.exists(filepath):
return {}
with open(filepath, 'r') as f:
content = f.read()
if not content.strip():
return {}
if HAS_YAML:
return yaml.safe_load(content) or {}
return {}
# ============================================================================
# Path Helpers
# ============================================================================
def get_workflow_dir() -> Path:
return Path('.workflow')
def get_version_dir(version: str) -> Path:
return get_workflow_dir() / 'versions' / version
def get_snapshot_path(version: str, snapshot_type: str) -> Path:
"""Get path to manifest snapshot for a version."""
return get_version_dir(version) / f'snapshot_{snapshot_type}' / 'manifest.json'
def get_current_manifest_path() -> Path:
return Path('project_manifest.json')
def get_versions_list() -> List[str]:
"""Get list of all versions."""
versions_dir = get_workflow_dir() / 'versions'
if not versions_dir.exists():
return []
return sorted([d.name for d in versions_dir.iterdir() if d.is_dir()])
# ============================================================================
# Entity Extraction
# ============================================================================
def extract_entities(manifest: dict) -> Dict[str, Dict[str, Any]]:
"""
Extract all entities from manifest into a flat dict keyed by ID.
Returns dict like:
{
"page_home": {"type": "page", "name": "Home", "status": "APPROVED", ...},
"component_Button": {"type": "component", "name": "Button", ...},
...
}
"""
entities = {}
entity_types = manifest.get('entities', {})
for entity_type, entity_list in entity_types.items():
if not isinstance(entity_list, list):
continue
for entity in entity_list:
entity_id = entity.get('id')
if entity_id:
entities[entity_id] = {
'type': entity_type.rstrip('s'), # pages -> page
**entity
}
return entities
# ============================================================================
# Diff Computation
# ============================================================================
def compute_diff(before: dict, after: dict) -> dict:
"""
Compute the difference between two manifests.
Returns:
{
"added": [list of added entities],
"removed": [list of removed entities],
"modified": [list of modified entities with changes],
"unchanged": [list of unchanged entity IDs]
}
"""
before_entities = extract_entities(before)
after_entities = extract_entities(after)
before_ids = set(before_entities.keys())
after_ids = set(after_entities.keys())
added_ids = after_ids - before_ids
removed_ids = before_ids - after_ids
common_ids = before_ids & after_ids
diff = {
'added': [],
'removed': [],
'modified': [],
'unchanged': []
}
# Added entities
for entity_id in sorted(added_ids):
entity = after_entities[entity_id]
diff['added'].append({
'id': entity_id,
'type': entity.get('type'),
'name': entity.get('name'),
'file_path': entity.get('file_path'),
'status': entity.get('status')
})
# Removed entities
for entity_id in sorted(removed_ids):
entity = before_entities[entity_id]
diff['removed'].append({
'id': entity_id,
'type': entity.get('type'),
'name': entity.get('name'),
'file_path': entity.get('file_path'),
'status': entity.get('status')
})
# Modified entities
for entity_id in sorted(common_ids):
before_entity = before_entities[entity_id]
after_entity = after_entities[entity_id]
changes = []
# Check each field for changes
for field in ['name', 'file_path', 'status', 'description', 'dependencies']:
before_val = before_entity.get(field)
after_val = after_entity.get(field)
if before_val != after_val:
changes.append({
'field': field,
'before': before_val,
'after': after_val
})
if changes:
diff['modified'].append({
'id': entity_id,
'type': before_entity.get('type'),
'name': after_entity.get('name'),
'file_path': after_entity.get('file_path'),
'changes': changes
})
else:
diff['unchanged'].append(entity_id)
return diff
def compute_summary(diff: dict) -> dict:
"""Compute summary statistics from diff."""
return {
'total_added': len(diff['added']),
'total_removed': len(diff['removed']),
'total_modified': len(diff['modified']),
'total_unchanged': len(diff['unchanged']),
'by_type': {
'pages': {
'added': len([e for e in diff['added'] if e['type'] == 'page']),
'removed': len([e for e in diff['removed'] if e['type'] == 'page']),
'modified': len([e for e in diff['modified'] if e['type'] == 'page'])
},
'components': {
'added': len([e for e in diff['added'] if e['type'] == 'component']),
'removed': len([e for e in diff['removed'] if e['type'] == 'component']),
'modified': len([e for e in diff['modified'] if e['type'] == 'component'])
},
'api_endpoints': {
'added': len([e for e in diff['added'] if e['type'] == 'api_endpoint']),
'removed': len([e for e in diff['removed'] if e['type'] == 'api_endpoint']),
'modified': len([e for e in diff['modified'] if e['type'] == 'api_endpoint'])
}
}
}
# ============================================================================
# Display Functions
# ============================================================================
def format_entity(entity: dict, prefix: str = '') -> str:
"""Format an entity for display."""
type_icon = {
'page': '📄',
'component': '🧩',
'api_endpoint': '🔌',
'lib': '📚',
'hook': '🪝',
'type': '📝',
'config': '⚙️'
}.get(entity.get('type', ''), '•')
name = entity.get('name', entity.get('id', 'Unknown'))
file_path = entity.get('file_path', '')
return f"{prefix}{type_icon} {name} ({file_path})"
def display_diff(diff: dict, summary: dict, from_version: str, to_version: str):
"""Display diff in a formatted way."""
print()
print("╔" + "═" * 70 + "╗")
print("║" + f" MANIFEST DIFF: {from_version} → {to_version}".ljust(70) + "║")
print("╠" + "═" * 70 + "╣")
# Summary
print("║" + " SUMMARY".ljust(70) + "║")
print("║" + f" + Added: {summary['total_added']}".ljust(70) + "║")
print("║" + f" ~ Modified: {summary['total_modified']}".ljust(70) + "║")
print("║" + f" - Removed: {summary['total_removed']}".ljust(70) + "║")
print("║" + f" = Unchanged: {summary['total_unchanged']}".ljust(70) + "║")
# By type
print("╠" + "═" * 70 + "╣")
print("║" + " BY TYPE".ljust(70) + "║")
for type_name, counts in summary['by_type'].items():
changes = []
if counts['added'] > 0:
changes.append(f"+{counts['added']}")
if counts['modified'] > 0:
changes.append(f"~{counts['modified']}")
if counts['removed'] > 0:
changes.append(f"-{counts['removed']}")
if changes:
print("║" + f" {type_name}: {' '.join(changes)}".ljust(70) + "║")
# Added
if diff['added']:
print("╠" + "═" * 70 + "╣")
print("║" + " ➕ ADDED".ljust(70) + "║")
for entity in diff['added']:
line = format_entity(entity, ' + ')
print("║" + line[:70].ljust(70) + "║")
# Modified
if diff['modified']:
print("╠" + "═" * 70 + "╣")
print("║" + " 📝 MODIFIED".ljust(70) + "║")
for entity in diff['modified']:
line = format_entity(entity, ' ~ ')
print("║" + line[:70].ljust(70) + "║")
for change in entity['changes']:
field = change['field']
before = str(change['before'])[:20] if change['before'] else '(none)'
after = str(change['after'])[:20] if change['after'] else '(none)'
change_line = f" {field}: {before} → {after}"
print("║" + change_line[:70].ljust(70) + "║")
# Removed
if diff['removed']:
print("╠" + "═" * 70 + "╣")
print("║" + " ➖ REMOVED".ljust(70) + "║")
for entity in diff['removed']:
line = format_entity(entity, ' - ')
print("║" + line[:70].ljust(70) + "║")
print("╚" + "═" * 70 + "╝")
def display_changelog(version: str, session: dict, diff: dict, summary: dict):
"""Display changelog for a single version."""
print()
print("╔" + "═" * 70 + "╗")
print("║" + f" CHANGELOG: {version}".ljust(70) + "║")
print("╠" + "═" * 70 + "╣")
print("║" + f" Feature: {session.get('feature', 'Unknown')[:55]}".ljust(70) + "║")
print("║" + f" Status: {session.get('status', 'unknown')}".ljust(70) + "║")
if session.get('started_at'):
print("║" + f" Started: {session['started_at'][:19]}".ljust(70) + "║")
if session.get('completed_at'):
print("║" + f" Completed: {session['completed_at'][:19]}".ljust(70) + "║")
print("╠" + "═" * 70 + "╣")
print("║" + " CHANGES".ljust(70) + "║")
if not diff['added'] and not diff['modified'] and not diff['removed']:
print("║" + " No entity changes".ljust(70) + "║")
else:
for entity in diff['added']:
line = f" + Added {entity['type']}: {entity['name']}"
print("║" + line[:70].ljust(70) + "║")
for entity in diff['modified']:
line = f" ~ Modified {entity['type']}: {entity['name']}"
print("║" + line[:70].ljust(70) + "║")
for entity in diff['removed']:
line = f" - Removed {entity['type']}: {entity['name']}"
print("║" + line[:70].ljust(70) + "║")
print("╚" + "═" * 70 + "╝")
def output_json(data: dict):
"""Output data as JSON."""
print(json.dumps(data, indent=2))
# ============================================================================
# Commands
# ============================================================================
def diff_versions(version1: str, version2: str, output_format: str = 'text') -> int:
"""Diff two specific versions."""
# Load snapshots
before_path = get_snapshot_path(version1, 'after')
if not before_path.exists():
before_path = get_snapshot_path(version1, 'before')
after_path = get_snapshot_path(version2, 'after')
if not after_path.exists():
after_path = get_snapshot_path(version2, 'before')
if not before_path.exists():
print(f"Error: No snapshot found for version {version1}")
return 1
if not after_path.exists():
print(f"Error: No snapshot found for version {version2}")
return 1
before = load_json(str(before_path))
after = load_json(str(after_path))
diff = compute_diff(before, after)
summary = compute_summary(diff)
if output_format == 'json':
output_json({
'from_version': version1,
'to_version': version2,
'diff': diff,
'summary': summary
})
else:
display_diff(diff, summary, version1, version2)
return 0
def diff_with_current(version: str, output_format: str = 'text') -> int:
"""Diff a version with current manifest."""
# Load version snapshot
snapshot_path = get_snapshot_path(version, 'before')
if not snapshot_path.exists():
print(f"Error: No snapshot found for version {version}")
return 1
before = load_json(str(snapshot_path))
# Load current manifest
current_path = get_current_manifest_path()
if not current_path.exists():
print("Error: No current manifest found")
return 1
after = load_json(str(current_path))
diff = compute_diff(before, after)
summary = compute_summary(diff)
if output_format == 'json':
output_json({
'from_version': version,
'to_version': 'current',
'diff': diff,
'summary': summary
})
else:
display_diff(diff, summary, version, 'current')
return 0
def show_changelog(version: str = None, output_format: str = 'text') -> int:
"""Show changelog for a version or all versions."""
versions = get_versions_list()
if not versions:
print("No workflow versions found.")
return 1
if version:
versions = [v for v in versions if v == version]
if not versions:
print(f"Version {version} not found.")
return 1
for i, v in enumerate(versions):
# Load session info
session_path = get_version_dir(v) / 'session.yml'
session = load_yaml(str(session_path)) if session_path.exists() else {}
# Get before/after snapshots
before_path = get_snapshot_path(v, 'before')
after_path = get_snapshot_path(v, 'after')
before = load_json(str(before_path)) if before_path.exists() else {}
after = load_json(str(after_path)) if after_path.exists() else {}
if not after:
after = before # Use before if no after exists
diff = compute_diff(before, after)
summary = compute_summary(diff)
if output_format == 'json':
output_json({
'version': v,
'session': session,
'diff': diff,
'summary': summary
})
else:
display_changelog(v, session, diff, summary)
return 0
# ============================================================================
# CLI Interface
# ============================================================================
def main():
parser = argparse.ArgumentParser(description="Manifest diffing and changelog generation")
subparsers = parser.add_subparsers(dest='command', help='Commands')
# diff command
diff_parser = subparsers.add_parser('diff', help='Diff two versions')
diff_parser.add_argument('version1', help='First version')
diff_parser.add_argument('version2', nargs='?', help='Second version (or "current")')
diff_parser.add_argument('--json', action='store_true', help='Output as JSON')
# changelog command
changelog_parser = subparsers.add_parser('changelog', help='Show version changelog')
changelog_parser.add_argument('version', nargs='?', help='Specific version (or all)')
changelog_parser.add_argument('--json', action='store_true', help='Output as JSON')
# versions command
subparsers.add_parser('versions', help='List all versions')
args = parser.parse_args()
if args.command == 'diff':
output_format = 'json' if args.json else 'text'
if args.version2:
if args.version2 == 'current':
sys.exit(diff_with_current(args.version1, output_format))
else:
sys.exit(diff_versions(args.version1, args.version2, output_format))
else:
# Diff with current by default
sys.exit(diff_with_current(args.version1, output_format))
elif args.command == 'changelog':
output_format = 'json' if args.json else 'text'
sys.exit(show_changelog(args.version, output_format))
elif args.command == 'versions':
versions = get_versions_list()
if versions:
print("\nAvailable versions:")
for v in versions:
print(f" - {v}")
else:
print("No versions found.")
else:
parser.print_help()
if __name__ == "__main__":
main()

265
skills/guardrail-orchestrator/scripts/migrate_task_sessions.py Executable file
View File

@ -0,0 +1,265 @@
#!/usr/bin/env python3
"""
Migration script to convert flat task session files to directory structure.
This script migrates task sessions from the old flat file structure:
.workflow/versions/v001/task_sessions/task_design.yml
To the new directory structure:
.workflow/versions/v001/task_sessions/task_design/
session.yml
task.yml
operations.log
Usage:
python3 migrate_task_sessions.py [--dry-run]
Options:
--dry-run Show what would be done without making changes
"""
from __future__ import annotations
import sys
import argparse
from pathlib import Path
from datetime import datetime
from typing import Optional
# Add parent to path for imports
sys.path.insert(0, str(Path(__file__).parent))
from version_manager import load_yaml, save_yaml, get_workflow_dir
# ============================================================================
# Discovery Functions
# ============================================================================
def find_flat_task_sessions() -> list[tuple[Path, str]]:
"""
Find all flat task session YAML files.
Returns:
List of tuples: (file_path, version_name)
"""
workflow_dir = get_workflow_dir()
versions_dir = workflow_dir / 'versions'
flat_sessions = []
if versions_dir.exists():
for version_dir in versions_dir.iterdir():
if version_dir.is_dir():
task_sessions_dir = version_dir / 'task_sessions'
if task_sessions_dir.exists():
for item in task_sessions_dir.iterdir():
# Check if it's a YAML file (not a directory)
if item.is_file() and item.suffix in ['.yml', '.yaml']:
flat_sessions.append((item, version_dir.name))
return flat_sessions
# ============================================================================
# Migration Functions
# ============================================================================
def migrate_task_session(file_path: Path, version: str, dry_run: bool = False) -> dict:
"""
Migrate a single flat task session to directory structure.
Args:
file_path: Path to the flat YAML file
version: Version identifier (e.g., 'v001')
dry_run: If True, only report what would be done
Returns:
Dictionary with migration results and actions taken
"""
task_id = file_path.stem # e.g., "task_design" from "task_design.yml"
parent_dir = file_path.parent
new_dir = parent_dir / task_id
result = {
'task_id': task_id,
'version': version,
'original_path': str(file_path),
'new_path': str(new_dir),
'success': False,
'actions': []
}
if dry_run:
result['actions'].append(f"Would create directory: {new_dir}")
result['actions'].append(f"Would move {file_path.name} to {new_dir}/session.yml")
result['actions'].append(f"Would create {new_dir}/task.yml (if source exists)")
result['actions'].append(f"Would create {new_dir}/operations.log")
result['success'] = True
return result
try:
# Create directory
new_dir.mkdir(exist_ok=True)
result['actions'].append(f"Created directory: {new_dir}")
# Move session file
session_data = load_yaml(str(file_path))
save_yaml(str(new_dir / 'session.yml'), session_data)
file_path.unlink() # Delete original
result['actions'].append(f"Moved session data to: {new_dir}/session.yml")
# Create task.yml snapshot (try to find original task)
task_file = Path('tasks') / f'{task_id}.yml'
if task_file.exists():
task_data = load_yaml(str(task_file))
task_data['snapshotted_at'] = datetime.now().isoformat()
task_data['source_path'] = str(task_file)
task_data['status_at_snapshot'] = task_data.get('status', 'migrated')
task_data['migration_note'] = 'Created during migration from flat file structure'
save_yaml(str(new_dir / 'task.yml'), task_data)
result['actions'].append(f"Created task snapshot: {new_dir}/task.yml")
else:
# Create minimal task.yml from session data
minimal_task = {
'id': task_id,
'type': session_data.get('task_type', 'unknown'),
'agent': session_data.get('agent', 'unknown'),
'snapshotted_at': datetime.now().isoformat(),
'source_path': 'N/A - reconstructed from session',
'status_at_snapshot': 'migrated',
'migration_note': 'Task file not found - reconstructed from session data'
}
save_yaml(str(new_dir / 'task.yml'), minimal_task)
result['actions'].append(f"Warning: Task file not found at {task_file}")
result['actions'].append(f"Created minimal task snapshot: {new_dir}/task.yml")
# Create operations.log
log_content = f"# Operations Log for {task_id}\n"
log_content += f"# Migrated: {datetime.now().isoformat()}\n"
log_content += "# Format: [timestamp] OPERATION target_type: target_id (path)\n"
log_content += "=" * 70 + "\n\n"
log_content += f"[{datetime.now().isoformat()}] MIGRATION: Converted from flat file structure\n"
# If session has operations, add them to the log
if 'operations' in session_data and session_data['operations']:
log_content += f"\n# Historical operations from session data:\n"
for op in session_data['operations']:
timestamp = op.get('performed_at', 'unknown')
op_type = op.get('type', 'UNKNOWN')
target_type = op.get('target_type', 'unknown')
target_id = op.get('target_id', 'unknown')
target_path = op.get('target_path', '')
entry = f"[{timestamp}] {op_type} {target_type}: {target_id}"
if target_path:
entry += f" ({target_path})"
diff_summary = op.get('changes', {}).get('diff_summary', '')
if diff_summary:
entry += f"\n Summary: {diff_summary}"
log_content += entry + "\n"
(new_dir / 'operations.log').write_text(log_content)
result['actions'].append(f"Created operations log: {new_dir}/operations.log")
result['success'] = True
except Exception as e:
result['error'] = str(e)
result['actions'].append(f"Error: {e}")
return result
# ============================================================================
# Main Entry Point
# ============================================================================
def main():
"""Main migration script entry point."""
parser = argparse.ArgumentParser(
description='Migrate task session files from flat structure to directories',
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=__doc__
)
parser.add_argument(
'--dry-run',
action='store_true',
help='Show what would be done without making changes'
)
args = parser.parse_args()
dry_run = args.dry_run
# Header
print("=" * 70)
print("Task Session Migration Script".center(70))
print(f"Mode: {'DRY RUN' if dry_run else 'LIVE MIGRATION'}".center(70))
print("=" * 70)
print()
# Find flat sessions
flat_sessions = find_flat_task_sessions()
if not flat_sessions:
print("No flat task session files found. Nothing to migrate.")
print()
print("This could mean:")
print(" 1. All task sessions are already migrated")
print(" 2. No task sessions exist yet")
print(" 3. .workflow directory doesn't exist")
return
print(f"Found {len(flat_sessions)} flat task session file(s) to migrate:")
print()
# Process each file
results = []
for file_path, version in flat_sessions:
print(f"Processing: {version}/{file_path.name}")
print("-" * 70)
result = migrate_task_session(file_path, version, dry_run)
results.append(result)
for action in result['actions']:
print(f" {action}")
if not result['success'] and 'error' in result:
print(f" ERROR: {result['error']}")
print()
# Summary
successful = sum(1 for r in results if r['success'])
failed = len(results) - successful
print("=" * 70)
print("Migration Summary".center(70))
print("=" * 70)
print(f"Total files processed: {len(results)}")
print(f"Successful migrations: {successful}")
print(f"Failed migrations: {failed}")
print()
if dry_run:
print("This was a DRY RUN. No files were modified.")
print("Run without --dry-run to perform the migration.")
else:
if successful > 0:
print("Migration completed successfully!")
print()
print("Next steps:")
print(" 1. Verify migrated files in .workflow/versions/*/task_sessions/")
print(" 2. Check that each task has session.yml, task.yml, and operations.log")
print(" 3. Test the system to ensure compatibility")
if failed > 0:
print()
print(f"WARNING: {failed} migration(s) failed. Review the errors above.")
print()
if __name__ == '__main__':
main()

79
skills/guardrail-orchestrator/scripts/post_write.py Normal file
View File

@ -0,0 +1,79 @@
#!/usr/bin/env python3
"""Post-write hook to update entity status in manifest."""
import argparse
import json
import os
from datetime import datetime
def load_manifest(manifest_path: str) -> dict | None:
"""Load manifest if it exists."""
if not os.path.exists(manifest_path):
return None
with open(manifest_path) as f:
return json.load(f)
def save_manifest(manifest_path: str, manifest: dict):
"""Save manifest to file."""
with open(manifest_path, "w") as f:
json.dump(manifest, f, indent=2)
def find_entity_by_path(manifest: dict, file_path: str) -> tuple:
"""Find entity by file path, return (entity_type, index, entity)."""
entities = manifest.get("entities", {})
for entity_type in ["pages", "components", "api_endpoints", "database_tables"]:
for idx, entity in enumerate(entities.get(entity_type, [])):
if entity.get("file_path") == file_path:
return (entity_type, idx, entity)
return (None, None, None)
def main():
parser = argparse.ArgumentParser(description="Post-write hook")
parser.add_argument("--manifest", required=True, help="Path to manifest")
parser.add_argument("--file", help="File that was written")
args = parser.parse_args()
manifest = load_manifest(args.manifest)
if manifest is None:
return 0
# If file provided, update entity status
if args.file:
# Normalize the file path
file_path = args.file.lstrip('./')
entity_type, idx, entity = find_entity_by_path(manifest, args.file)
# Try without leading ./
if not entity:
entity_type, idx, entity = find_entity_by_path(manifest, file_path)
if entity and entity.get("status") == "APPROVED":
manifest["entities"][entity_type][idx]["status"] = "IMPLEMENTED"
manifest["entities"][entity_type][idx]["implemented_at"] = datetime.now().isoformat()
# Add to history (ensure it exists)
if "state" not in manifest:
manifest["state"] = {}
if "revision_history" not in manifest["state"]:
manifest["state"]["revision_history"] = []
manifest["state"]["revision_history"].append({
"action": "ENTITY_IMPLEMENTED",
"timestamp": datetime.now().isoformat(),
"details": f"Implemented {entity.get('id', 'unknown')}"
})
save_manifest(args.manifest, manifest)
print(f"GUARDRAIL: Updated {entity.get('id')} to IMPLEMENTED")
return 0
if __name__ == "__main__":
exit(main())

601
skills/guardrail-orchestrator/scripts/security_scan.py Normal file
View File

@ -0,0 +1,601 @@
#!/usr/bin/env python3
"""
Comprehensive Security Scanner for guardrail workflow.
Performs static security analysis on codebase:
- Hardcoded secrets and credentials
- SQL injection vulnerabilities
- XSS vulnerabilities
- Path traversal risks
- Insecure dependencies
- Authentication/Authorization issues
- OWASP Top 10 patterns
Usage:
python3 security_scan.py --project-dir . [--severity critical|high|medium|low]
"""
import argparse
import json
import os
import re
import sys
from pathlib import Path
from typing import NamedTuple
from dataclasses import dataclass, field
@dataclass
class SecurityIssue:
"""Security vulnerability finding."""
severity: str # CRITICAL, HIGH, MEDIUM, LOW, INFO
category: str
title: str
description: str
file_path: str
line_number: int | None
code_snippet: str
recommendation: str
cwe_id: str | None = None
owasp_category: str | None = None
@dataclass
class ScanResult:
"""Complete scan results."""
issues: list[SecurityIssue] = field(default_factory=list)
files_scanned: int = 0
scan_duration: float = 0.0
# Security patterns organized by category
SECURITY_PATTERNS = {
'hardcoded_secrets': {
'severity': 'CRITICAL',
'cwe': 'CWE-798',
'owasp': 'A07:2021-Identification and Authentication Failures',
'patterns': [
# API Keys
(r'''(?:api[_-]?key|apikey)\s*[:=]\s*['"]((?!process\.env)[^'"]{10,})['"']''', 'Hardcoded API key'),
(r'''(?:api[_-]?secret|apisecret)\s*[:=]\s*['"]((?!process\.env)[^'"]{10,})['"']''', 'Hardcoded API secret'),
# Passwords
(r'''(?:password|passwd|pwd)\s*[:=]\s*['"]([^'"]{4,})['"']''', 'Hardcoded password'),
# Private keys
(r'''-----BEGIN (?:RSA |EC |DSA )?PRIVATE KEY-----''', 'Embedded private key'),
# AWS credentials
(r'''(?:aws[_-]?access[_-]?key[_-]?id|aws[_-]?secret)\s*[:=]\s*['"]([A-Z0-9]{16,})['"']''', 'AWS credential'),
(r'''AKIA[0-9A-Z]{16}''', 'AWS Access Key ID'),
# JWT secrets
(r'''(?:jwt[_-]?secret|token[_-]?secret)\s*[:=]\s*['"]([^'"]{8,})['"']''', 'Hardcoded JWT secret'),
# Database connection strings
(r'''(?:mongodb|postgres|mysql|redis):\/\/[^:]+:[^@]+@''', 'Database credentials in connection string'),
# Generic secrets
(r'''(?:secret|token|auth)[_-]?(?:key)?\s*[:=]\s*['"]([^'"]{8,})['"']''', 'Potential hardcoded secret'),
]
},
'sql_injection': {
'severity': 'CRITICAL',
'cwe': 'CWE-89',
'owasp': 'A03:2021-Injection',
'patterns': [
# String concatenation in queries
(r'''(?:query|sql|execute)\s*\(\s*[`'"].*\$\{''', 'SQL injection via template literal'),
(r'''(?:query|sql|execute)\s*\(\s*['"].*\+\s*(?:req\.|params\.|body\.|query\.)''', 'SQL injection via concatenation'),
(r'''(?:SELECT|INSERT|UPDATE|DELETE|FROM|WHERE).*\$\{''', 'Raw SQL with template interpolation'),
# Raw queries
(r'''\.raw\s*\(\s*[`'"].*\$\{''', 'Raw query with interpolation'),
(r'''prisma\.\$queryRaw\s*`[^`]*\$\{''', 'Prisma raw query with interpolation'),
]
},
'xss': {
'severity': 'HIGH',
'cwe': 'CWE-79',
'owasp': 'A03:2021-Injection',
'patterns': [
# React dangerouslySetInnerHTML
(r'''dangerouslySetInnerHTML\s*=\s*\{\s*\{__html:\s*(?!DOMPurify|sanitize)''', 'Unsanitized dangerouslySetInnerHTML'),
# innerHTML assignment
(r'''\.innerHTML\s*=\s*(?!['"`]<)''', 'Direct innerHTML assignment'),
# document.write
(r'''document\.write\s*\(''', 'document.write usage'),
# eval with user input
(r'''eval\s*\(\s*(?:req\.|params\.|body\.|query\.|props\.)''', 'eval with user input'),
# jQuery html() with user input
(r'''\$\([^)]+\)\.html\s*\(\s*(?!['"`])''', 'jQuery html() with dynamic content'),
]
},
'path_traversal': {
'severity': 'HIGH',
'cwe': 'CWE-22',
'owasp': 'A01:2021-Broken Access Control',
'patterns': [
# File operations with user input
(r'''(?:readFile|writeFile|readFileSync|writeFileSync|createReadStream)\s*\(\s*(?:req\.|params\.|body\.|query\.)''', 'File operation with user input'),
(r'''(?:readFile|writeFile)\s*\(\s*[`'"].*\$\{(?:req\.|params\.|body\.|query\.)''', 'File path with user input interpolation'),
# Path.join with user input (without validation)
(r'''path\.(?:join|resolve)\s*\([^)]*(?:req\.|params\.|body\.|query\.)''', 'Path operation with user input'),
]
},
'command_injection': {
'severity': 'CRITICAL',
'cwe': 'CWE-78',
'owasp': 'A03:2021-Injection',
'patterns': [
# exec/spawn with user input
(r'''(?:exec|execSync|spawn|spawnSync)\s*\(\s*[`'"].*\$\{''', 'Command injection via template literal'),
(r'''(?:exec|execSync|spawn|spawnSync)\s*\(\s*(?:req\.|params\.|body\.|query\.)''', 'Command execution with user input'),
# child_process with concatenation
(r'''child_process.*\(\s*['"].*\+\s*(?:req\.|params\.|body\.|query\.)''', 'Command injection via concatenation'),
]
},
'insecure_auth': {
'severity': 'HIGH',
'cwe': 'CWE-287',
'owasp': 'A07:2021-Identification and Authentication Failures',
'patterns': [
# Weak JWT algorithms
(r'''algorithm\s*[:=]\s*['"](?:none|HS256)['"']''', 'Weak JWT algorithm'),
# No password hashing
(r'''password\s*===?\s*(?:req\.|body\.|params\.)''', 'Plain text password comparison'),
# Disabled security
(r'''(?:verify|secure|https|ssl)\s*[:=]\s*false''', 'Security feature disabled'),
# Cookie without security flags
(r'''cookie\s*\([^)]*\)\s*(?!.*(?:httpOnly|secure|sameSite))''', 'Cookie without security flags'),
]
},
'sensitive_data_exposure': {
'severity': 'MEDIUM',
'cwe': 'CWE-200',
'owasp': 'A02:2021-Cryptographic Failures',
'patterns': [
# Logging sensitive data
(r'''console\.(?:log|info|debug)\s*\([^)]*(?:password|secret|token|key|credential)''', 'Logging sensitive data'),
# Error messages with sensitive info
(r'''(?:throw|Error)\s*\([^)]*(?:password|secret|token|key|sql|query)''', 'Sensitive info in error message'),
# HTTP instead of HTTPS
(r'''['"]http:\/\/(?!localhost|127\.0\.0\.1)''', 'HTTP URL (should be HTTPS)'),
]
},
'insecure_dependencies': {
'severity': 'MEDIUM',
'cwe': 'CWE-1104',
'owasp': 'A06:2021-Vulnerable and Outdated Components',
'patterns': [
# Known vulnerable patterns
(r'''require\s*\(\s*['"](?:serialize-javascript|lodash\.template|node-serialize)['"]\s*\)''', 'Known vulnerable package'),
# Outdated crypto
(r'''crypto\.createCipher\s*\(''', 'Deprecated crypto.createCipher'),
(r'''md5\s*\(|createHash\s*\(\s*['"]md5['"]''', 'MD5 hash usage (weak)'),
(r'''sha1\s*\(|createHash\s*\(\s*['"]sha1['"]''', 'SHA1 hash usage (weak)'),
]
},
'cors_misconfiguration': {
'severity': 'MEDIUM',
'cwe': 'CWE-942',
'owasp': 'A01:2021-Broken Access Control',
'patterns': [
# Wildcard CORS
(r'''(?:Access-Control-Allow-Origin|origin)\s*[:=]\s*['"]\*['"']''', 'Wildcard CORS origin'),
(r'''cors\s*\(\s*\{[^}]*origin\s*:\s*true''', 'CORS allows all origins'),
# Credentials with wildcard
(r'''credentials\s*:\s*true[^}]*origin\s*:\s*['"]\*['"']''', 'CORS credentials with wildcard origin'),
]
},
'insecure_randomness': {
'severity': 'LOW',
'cwe': 'CWE-330',
'owasp': 'A02:2021-Cryptographic Failures',
'patterns': [
# Math.random for security
(r'''Math\.random\s*\(\s*\)[^;]*(?:token|secret|password|key|id|session)''', 'Math.random for security-sensitive value'),
(r'''(?:token|secret|key|session)[^=]*=\s*Math\.random''', 'Math.random for security-sensitive value'),
]
},
'debug_code': {
'severity': 'LOW',
'cwe': 'CWE-489',
'owasp': 'A05:2021-Security Misconfiguration',
'patterns': [
# Debug statements
(r'''console\.(?:log|debug|info|warn)\s*\(''', 'Console statement (remove in production)'),
(r'''debugger\s*;''', 'Debugger statement'),
# TODO/FIXME security notes
(r'''(?:TODO|FIXME|HACK|XXX).*(?:security|auth|password|secret|vulnerable)''', 'Security-related TODO'),
]
},
'nosql_injection': {
'severity': 'HIGH',
'cwe': 'CWE-943',
'owasp': 'A03:2021-Injection',
'patterns': [
# MongoDB injection
(r'''\.find\s*\(\s*\{[^}]*\$(?:where|regex|gt|lt|ne|in|nin|or|and).*(?:req\.|params\.|body\.|query\.)''', 'NoSQL injection risk'),
(r'''\.find\s*\(\s*(?:req\.|params\.|body\.|query\.)''', 'Direct user input in query'),
]
},
'prototype_pollution': {
'severity': 'HIGH',
'cwe': 'CWE-1321',
'owasp': 'A03:2021-Injection',
'patterns': [
# Deep merge without protection
(r'''(?:merge|extend|assign)\s*\([^)]*(?:req\.|params\.|body\.|query\.)''', 'Potential prototype pollution via merge'),
(r'''Object\.assign\s*\(\s*\{\}[^)]*(?:req\.|params\.|body\.|query\.)''', 'Object.assign with user input'),
# __proto__ access
(r'''__proto__''', 'Direct __proto__ access'),
(r'''constructor\s*\[\s*['"]prototype['"]''', 'Prototype access via constructor'),
]
},
'ssrf': {
'severity': 'HIGH',
'cwe': 'CWE-918',
'owasp': 'A10:2021-Server-Side Request Forgery',
'patterns': [
# Fetch/axios with user URL
(r'''(?:fetch|axios\.get|axios\.post|http\.get|https\.get)\s*\(\s*(?:req\.|params\.|body\.|query\.)''', 'SSRF via user-controlled URL'),
(r'''(?:fetch|axios)\s*\(\s*[`'"].*\$\{(?:req\.|params\.|body\.|query\.)''', 'SSRF via URL interpolation'),
]
},
}
# File extensions to scan
SCAN_EXTENSIONS = {'.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'}
# Directories to skip
SKIP_DIRS = {'node_modules', '.next', 'dist', 'build', '.git', 'coverage', '__pycache__'}
def find_source_files(project_dir: str) -> list[str]:
"""Find all source files to scan."""
files = []
for root, dirs, filenames in os.walk(project_dir):
# Skip excluded directories
dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
for filename in filenames:
ext = os.path.splitext(filename)[1]
if ext in SCAN_EXTENSIONS:
files.append(os.path.join(root, filename))
return files
def scan_file(file_path: str) -> list[SecurityIssue]:
"""Scan a single file for security issues."""
issues = []
try:
with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
content = f.read()
lines = content.split('\n')
except (IOError, OSError):
return []
for category, config in SECURITY_PATTERNS.items():
for pattern, title in config['patterns']:
try:
for match in re.finditer(pattern, content, re.IGNORECASE | re.MULTILINE):
# Find line number
line_start = content[:match.start()].count('\n') + 1
line_content = lines[line_start - 1] if line_start <= len(lines) else ''
# Skip if in comment
stripped = line_content.strip()
if stripped.startswith('//') or stripped.startswith('*') or stripped.startswith('/*'):
continue
# Skip if looks like env var reference
if 'process.env' in line_content or 'import.meta.env' in line_content:
continue
issues.append(SecurityIssue(
severity=config['severity'],
category=category,
title=title,
description=get_description(category),
file_path=file_path,
line_number=line_start,
code_snippet=line_content.strip()[:100],
recommendation=get_recommendation(category),
cwe_id=config.get('cwe'),
owasp_category=config.get('owasp')
))
except re.error:
continue
return issues
def get_description(category: str) -> str:
"""Get detailed description for category."""
descriptions = {
'hardcoded_secrets': 'Credentials or secrets hardcoded in source code can be extracted by attackers.',
'sql_injection': 'User input directly in SQL queries allows attackers to manipulate database operations.',
'xss': 'Unsanitized user input rendered in HTML allows attackers to inject malicious scripts.',
'path_traversal': 'User input in file paths allows attackers to access arbitrary files.',
'command_injection': 'User input in system commands allows attackers to execute arbitrary commands.',
'insecure_auth': 'Weak authentication mechanisms can be bypassed by attackers.',
'sensitive_data_exposure': 'Sensitive information may be exposed through logs or errors.',
'insecure_dependencies': 'Known vulnerable packages or weak cryptographic functions.',
'cors_misconfiguration': 'Overly permissive CORS allows unauthorized cross-origin requests.',
'insecure_randomness': 'Predictable random values can be guessed by attackers.',
'debug_code': 'Debug code in production may expose sensitive information.',
'nosql_injection': 'User input in NoSQL queries allows attackers to manipulate database operations.',
'prototype_pollution': 'Modifying object prototypes can lead to code execution.',
'ssrf': 'User-controlled URLs allow attackers to make requests to internal services.',
}
return descriptions.get(category, 'Security vulnerability detected.')
def get_recommendation(category: str) -> str:
"""Get remediation recommendation for category."""
recommendations = {
'hardcoded_secrets': 'Use environment variables (process.env) or a secrets manager.',
'sql_injection': 'Use parameterized queries or ORM methods. Never concatenate user input.',
'xss': 'Sanitize user input with DOMPurify or escape HTML entities.',
'path_traversal': 'Validate and sanitize file paths. Use path.basename() and whitelist allowed paths.',
'command_injection': 'Avoid shell commands with user input. Use execFile with argument arrays.',
'insecure_auth': 'Use strong algorithms (RS256), hash passwords with bcrypt, enable all security flags.',
'sensitive_data_exposure': 'Remove sensitive data from logs. Use generic error messages.',
'insecure_dependencies': 'Update to latest secure versions. Use crypto.createCipheriv and SHA-256+.',
'cors_misconfiguration': 'Specify exact allowed origins. Do not use wildcard with credentials.',
'insecure_randomness': 'Use crypto.randomBytes() or crypto.randomUUID() for security-sensitive values.',
'debug_code': 'Remove console statements and debugger in production builds.',
'nosql_injection': 'Sanitize input and use schema validation. Avoid $where operators.',
'prototype_pollution': 'Use Object.create(null) or validate/sanitize object keys.',
'ssrf': 'Validate URLs against allowlist. Block internal IP ranges.',
}
return recommendations.get(category, 'Review and remediate the security issue.')
def check_package_json(project_dir: str) -> list[SecurityIssue]:
"""Check package.json for security issues."""
issues = []
pkg_path = os.path.join(project_dir, 'package.json')
if not os.path.exists(pkg_path):
return []
try:
with open(pkg_path, 'r') as f:
pkg = json.load(f)
except (json.JSONDecodeError, IOError):
return []
# Known vulnerable packages (simplified check)
vulnerable_packages = {
'lodash': '< 4.17.21',
'axios': '< 0.21.1',
'node-fetch': '< 2.6.1',
'minimist': '< 1.2.6',
'serialize-javascript': '< 3.1.0',
}
all_deps = {}
all_deps.update(pkg.get('dependencies', {}))
all_deps.update(pkg.get('devDependencies', {}))
for pkg_name in vulnerable_packages:
if pkg_name in all_deps:
issues.append(SecurityIssue(
severity='MEDIUM',
category='insecure_dependencies',
title=f'Potentially vulnerable package: {pkg_name}',
description=f'Package {pkg_name} may have known vulnerabilities. Run npm audit for details.',
file_path=pkg_path,
line_number=None,
code_snippet=f'"{pkg_name}": "{all_deps[pkg_name]}"',
recommendation='Run `npm audit` and update to the latest secure version.',
cwe_id='CWE-1104',
owasp_category='A06:2021-Vulnerable and Outdated Components'
))
return issues
def check_env_files(project_dir: str) -> list[SecurityIssue]:
"""Check for exposed environment files."""
issues = []
env_files = ['.env', '.env.local', '.env.production', '.env.development']
for env_file in env_files:
env_path = os.path.join(project_dir, env_file)
if os.path.exists(env_path):
# Check if in .gitignore
gitignore_path = os.path.join(project_dir, '.gitignore')
in_gitignore = False
if os.path.exists(gitignore_path):
try:
with open(gitignore_path, 'r') as f:
gitignore_content = f.read()
if env_file in gitignore_content or '.env*' in gitignore_content:
in_gitignore = True
except IOError:
pass
if not in_gitignore:
issues.append(SecurityIssue(
severity='HIGH',
category='sensitive_data_exposure',
title=f'Environment file not in .gitignore: {env_file}',
description='Environment files containing secrets may be committed to version control.',
file_path=env_path,
line_number=None,
code_snippet=env_file,
recommendation=f'Add {env_file} to .gitignore immediately.',
cwe_id='CWE-200',
owasp_category='A02:2021-Cryptographic Failures'
))
return issues
def run_scan(project_dir: str, min_severity: str = 'LOW') -> ScanResult:
"""Run full security scan."""
import time
start_time = time.time()
severity_order = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO']
min_severity_index = severity_order.index(min_severity.upper()) if min_severity.upper() in severity_order else 3
result = ScanResult()
# Find and scan source files
files = find_source_files(project_dir)
result.files_scanned = len(files)
for file_path in files:
issues = scan_file(file_path)
result.issues.extend(issues)
# Additional checks
result.issues.extend(check_package_json(project_dir))
result.issues.extend(check_env_files(project_dir))
# Filter by severity
result.issues = [
i for i in result.issues
if severity_order.index(i.severity) <= min_severity_index
]
# Sort by severity
result.issues.sort(key=lambda x: severity_order.index(x.severity))
result.scan_duration = time.time() - start_time
return result
def format_report(result: ScanResult, format_type: str = 'text') -> str:
"""Format scan results."""
if format_type == 'json':
return json.dumps({
'files_scanned': result.files_scanned,
'scan_duration': result.scan_duration,
'total_issues': len(result.issues),
'by_severity': {
'CRITICAL': len([i for i in result.issues if i.severity == 'CRITICAL']),
'HIGH': len([i for i in result.issues if i.severity == 'HIGH']),
'MEDIUM': len([i for i in result.issues if i.severity == 'MEDIUM']),
'LOW': len([i for i in result.issues if i.severity == 'LOW']),
},
'issues': [
{
'severity': i.severity,
'category': i.category,
'title': i.title,
'description': i.description,
'file_path': i.file_path,
'line_number': i.line_number,
'code_snippet': i.code_snippet,
'recommendation': i.recommendation,
'cwe_id': i.cwe_id,
'owasp_category': i.owasp_category,
}
for i in result.issues
]
}, indent=2)
# Text format
lines = []
# Header
lines.append("")
lines.append("=" * 80)
lines.append(" SECURITY SCAN REPORT")
lines.append("=" * 80)
lines.append("")
# Summary
critical = len([i for i in result.issues if i.severity == 'CRITICAL'])
high = len([i for i in result.issues if i.severity == 'HIGH'])
medium = len([i for i in result.issues if i.severity == 'MEDIUM'])
low = len([i for i in result.issues if i.severity == 'LOW'])
lines.append("SUMMARY")
lines.append("-" * 80)
lines.append(f" Files scanned: {result.files_scanned}")
lines.append(f" Scan duration: {result.scan_duration:.2f}s")
lines.append(f" Total issues: {len(result.issues)}")
lines.append("")
lines.append(" By Severity:")
lines.append(f" CRITICAL: {critical}")
lines.append(f" HIGH: {high}")
lines.append(f" MEDIUM: {medium}")
lines.append(f" LOW: {low}")
lines.append("")
# Issues by severity
if result.issues:
for severity in ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW']:
severity_issues = [i for i in result.issues if i.severity == severity]
if severity_issues:
icon = {'CRITICAL': '!!!', 'HIGH': '!!', 'MEDIUM': '!', 'LOW': '.'}[severity]
lines.append(f"{icon} {severity} SEVERITY ISSUES ({len(severity_issues)})")
lines.append("-" * 80)
for idx, issue in enumerate(severity_issues, 1):
lines.append(f" [{idx}] {issue.title}")
lines.append(f" Category: {issue.category}")
if issue.file_path:
loc = f"{issue.file_path}:{issue.line_number}" if issue.line_number else issue.file_path
lines.append(f" Location: {loc}")
if issue.code_snippet:
lines.append(f" Code: {issue.code_snippet[:60]}...")
if issue.cwe_id:
lines.append(f" CWE: {issue.cwe_id}")
if issue.owasp_category:
lines.append(f" OWASP: {issue.owasp_category}")
lines.append(f" Fix: {issue.recommendation}")
lines.append("")
else:
lines.append("No security issues found!")
lines.append("")
# Result
lines.append("=" * 80)
if critical > 0:
lines.append(f" RESULT: CRITICAL ({critical} critical issues require immediate attention)")
elif high > 0:
lines.append(f" RESULT: FAIL ({high} high severity issues found)")
elif medium > 0:
lines.append(f" RESULT: WARNING ({medium} medium severity issues found)")
elif low > 0:
lines.append(f" RESULT: PASS WITH NOTES ({low} low severity issues)")
else:
lines.append(" RESULT: PASS (no security issues detected)")
lines.append("=" * 80)
return "\n".join(lines)
def main():
parser = argparse.ArgumentParser(description="Security scanner for codebase")
parser.add_argument("--project-dir", default=".", help="Project directory to scan")
parser.add_argument("--severity", default="LOW",
choices=['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'],
help="Minimum severity to report")
parser.add_argument("--json", action="store_true", help="Output as JSON")
parser.add_argument("--strict", action="store_true", help="Fail on any HIGH or above")
args = parser.parse_args()
result = run_scan(args.project_dir, args.severity)
format_type = 'json' if args.json else 'text'
print(format_report(result, format_type))
# Exit code
critical = len([i for i in result.issues if i.severity == 'CRITICAL'])
high = len([i for i in result.issues if i.severity == 'HIGH'])
if critical > 0:
return 2 # Critical issues
if args.strict and high > 0:
return 1 # High issues in strict mode
return 0
if __name__ == "__main__":
sys.exit(main())

363
skills/guardrail-orchestrator/scripts/task_manager.py Normal file
View File

@ -0,0 +1,363 @@
#!/usr/bin/env python3
"""Task management utilities for the guardrail workflow."""
import argparse
import os
import sys
from datetime import datetime
from pathlib import Path
# Try to import yaml, fall back to basic parsing if not available
try:
import yaml
HAS_YAML = True
except ImportError:
HAS_YAML = False
def parse_yaml_simple(content: str) -> dict:
"""Simple YAML parser for basic task files."""
result = {}
current_key = None
current_list = None
for line in content.split('\n'):
line = line.rstrip()
if not line or line.startswith('#'):
continue
# Handle list items
if line.startswith(' - '):
if current_list is not None:
current_list.append(line[4:].strip())
continue
# Handle key-value pairs
if ':' in line and not line.startswith(' '):
key, _, value = line.partition(':')
key = key.strip()
value = value.strip()
if value:
result[key] = value
current_list = None
else:
result[key] = []
current_list = result[key]
current_key = key
return result
def load_yaml(filepath: str) -> dict:
"""Load YAML file."""
with open(filepath, 'r') as f:
content = f.read()
if HAS_YAML:
return yaml.safe_load(content) or {}
return parse_yaml_simple(content)
def save_yaml(filepath: str, data: dict):
"""Save data to YAML file."""
if HAS_YAML:
with open(filepath, 'w') as f:
yaml.dump(data, f, default_flow_style=False, sort_keys=False)
else:
# Simple YAML writer
lines = []
for key, value in data.items():
if isinstance(value, list):
lines.append(f"{key}:")
for item in value:
lines.append(f" - {item}")
elif isinstance(value, str) and '\n' in value:
lines.append(f"{key}: |")
for line in value.split('\n'):
lines.append(f" {line}")
else:
lines.append(f"{key}: {value}")
with open(filepath, 'w') as f:
f.write('\n'.join(lines))
# ============================================================================
# Version-Aware Task Directory
# ============================================================================
def get_workflow_dir() -> Path:
"""Get the .workflow directory path."""
return Path('.workflow')
def get_current_tasks_dir() -> str:
"""Get the tasks directory for the currently active workflow version.
Returns the version-specific tasks directory if a workflow is active,
otherwise falls back to 'tasks' for backward compatibility.
"""
current_path = get_workflow_dir() / 'current.yml'
if not current_path.exists():
return 'tasks' # Fallback for no active workflow
current = load_yaml(str(current_path))
version = current.get('active_version')
if not version:
return 'tasks' # Fallback
tasks_dir = get_workflow_dir() / 'versions' / version / 'tasks'
tasks_dir.mkdir(parents=True, exist_ok=True)
return str(tasks_dir)
# ============================================================================
# Task Operations
# ============================================================================
def find_tasks(tasks_dir: str, filters: dict = None) -> list:
"""Find all task files matching filters."""
tasks = []
tasks_path = Path(tasks_dir)
if not tasks_path.exists():
return tasks
for filepath in tasks_path.glob('**/*.yml'):
try:
task = load_yaml(str(filepath))
task['_filepath'] = str(filepath)
# Apply filters
if filters:
match = True
for key, value in filters.items():
if task.get(key) != value:
match = False
break
if not match:
continue
tasks.append(task)
except Exception as e:
print(f"Warning: Could not parse {filepath}: {e}", file=sys.stderr)
return tasks
def list_tasks(tasks_dir: str, status: str = None, agent: str = None):
"""List tasks with optional filtering."""
filters = {}
if status:
filters['status'] = status
if agent:
filters['agent'] = agent
tasks = find_tasks(tasks_dir, filters)
if not tasks:
print("No tasks found.")
return
# Group by status
by_status = {}
for task in tasks:
s = task.get('status', 'unknown')
if s not in by_status:
by_status[s] = []
by_status[s].append(task)
print("\n" + "=" * 60)
print("TASK LIST")
print("=" * 60)
status_order = ['pending', 'in_progress', 'review', 'approved', 'completed', 'blocked']
for s in status_order:
if s in by_status:
print(f"\n{s.upper()} ({len(by_status[s])})")
print("-" * 40)
for task in by_status[s]:
agent = task.get('agent', '?')
priority = task.get('priority', 'medium')
print(f" [{agent}] {task.get('id', 'unknown')} ({priority})")
print(f" {task.get('title', 'No title')}")
def get_next_task(tasks_dir: str, agent: str) -> dict:
"""Get next available task for an agent."""
tasks = find_tasks(tasks_dir, {'agent': agent, 'status': 'pending'})
if not tasks:
return None
# Sort by priority (high > medium > low)
priority_order = {'high': 0, 'medium': 1, 'low': 2}
tasks.sort(key=lambda t: priority_order.get(t.get('priority', 'medium'), 1))
# Check dependencies
for task in tasks:
deps = task.get('dependencies', [])
if not deps:
return task
# Check if all dependencies are completed
all_deps_done = True
for dep_id in deps:
dep_tasks = find_tasks(tasks_dir, {'id': dep_id})
if dep_tasks and dep_tasks[0].get('status') != 'completed':
all_deps_done = False
break
if all_deps_done:
return task
return None
def update_task_status(tasks_dir: str, task_id: str, new_status: str, notes: str = None):
"""Update task status."""
tasks = find_tasks(tasks_dir, {'id': task_id})
if not tasks:
print(f"Error: Task {task_id} not found")
return False
task = tasks[0]
filepath = task['_filepath']
# Remove internal field
del task['_filepath']
# Update status
task['status'] = new_status
if new_status == 'completed':
task['completed_at'] = datetime.now().isoformat()
if notes:
task['review_notes'] = notes
save_yaml(filepath, task)
print(f"Updated {task_id} to {new_status}")
return True
def complete_all_tasks(tasks_dir: str):
"""Mark all non-completed tasks as completed."""
tasks = find_tasks(tasks_dir)
completed_count = 0
for task in tasks:
if task.get('status') != 'completed':
filepath = task['_filepath']
del task['_filepath']
task['status'] = 'completed'
task['completed_at'] = datetime.now().isoformat()
save_yaml(filepath, task)
completed_count += 1
print(f" Completed: {task.get('id', 'unknown')}")
print(f"\nMarked {completed_count} task(s) as completed.")
return completed_count
def show_status(tasks_dir: str, manifest_path: str):
"""Show overall workflow status."""
tasks = find_tasks(tasks_dir)
# Count by status
status_counts = {}
agent_counts = {'frontend': {'pending': 0, 'completed': 0},
'backend': {'pending': 0, 'completed': 0},
'reviewer': {'pending': 0}}
for task in tasks:
s = task.get('status', 'unknown')
status_counts[s] = status_counts.get(s, 0) + 1
agent = task.get('agent', 'unknown')
if agent in agent_counts:
if s == 'pending':
agent_counts[agent]['pending'] += 1
elif s == 'completed':
if 'completed' in agent_counts[agent]:
agent_counts[agent]['completed'] += 1
print("\n" + "╔" + "═" * 58 + "╗")
print("║" + "WORKFLOW STATUS".center(58) + "║")
print("╠" + "═" * 58 + "╣")
print("║" + " TASKS BY STATUS".ljust(58) + "║")
print("║" + f" ⏳ Pending: {status_counts.get('pending', 0)}".ljust(58) + "║")
print("║" + f" 🔄 In Progress: {status_counts.get('in_progress', 0)}".ljust(58) + "║")
print("║" + f" 🔍 Review: {status_counts.get('review', 0)}".ljust(58) + "║")
print("║" + f" ✅ Approved: {status_counts.get('approved', 0)}".ljust(58) + "║")
print("║" + f" ✓ Completed: {status_counts.get('completed', 0)}".ljust(58) + "║")
print("║" + f" 🚫 Blocked: {status_counts.get('blocked', 0)}".ljust(58) + "║")
print("╠" + "═" * 58 + "╣")
print("║" + " TASKS BY AGENT".ljust(58) + "║")
print("║" + f" 🎨 Frontend: {agent_counts['frontend']['pending']} pending, {agent_counts['frontend']['completed']} completed".ljust(58) + "║")
print("║" + f" ⚙️ Backend: {agent_counts['backend']['pending']} pending, {agent_counts['backend']['completed']} completed".ljust(58) + "║")
print("║" + f" 🔍 Reviewer: {agent_counts['reviewer']['pending']} pending".ljust(58) + "║")
print("╚" + "═" * 58 + "╝")
def main():
parser = argparse.ArgumentParser(description="Task management for guardrail workflow")
subparsers = parser.add_subparsers(dest='command', help='Commands')
# list command
list_parser = subparsers.add_parser('list', help='List tasks')
list_parser.add_argument('--status', help='Filter by status')
list_parser.add_argument('--agent', help='Filter by agent')
list_parser.add_argument('--tasks-dir', default=None, help='Tasks directory (defaults to current version)')
# next command
next_parser = subparsers.add_parser('next', help='Get next task for agent')
next_parser.add_argument('agent', choices=['frontend', 'backend', 'reviewer'])
next_parser.add_argument('--tasks-dir', default=None, help='Tasks directory (defaults to current version)')
# update command
update_parser = subparsers.add_parser('update', help='Update task status')
update_parser.add_argument('task_id', help='Task ID')
update_parser.add_argument('status', choices=['pending', 'in_progress', 'review', 'approved', 'completed', 'blocked'])
update_parser.add_argument('--notes', help='Review notes')
update_parser.add_argument('--tasks-dir', default=None, help='Tasks directory (defaults to current version)')
# status command
status_parser = subparsers.add_parser('status', help='Show workflow status')
status_parser.add_argument('--tasks-dir', default=None, help='Tasks directory (defaults to current version)')
status_parser.add_argument('--manifest', default='project_manifest.json', help='Manifest path')
# complete-all command
complete_all_parser = subparsers.add_parser('complete-all', help='Mark all tasks as completed')
complete_all_parser.add_argument('--tasks-dir', default=None, help='Tasks directory (defaults to current version)')
args = parser.parse_args()
# Resolve tasks_dir to version-specific directory if not explicitly provided
if hasattr(args, 'tasks_dir') and args.tasks_dir is None:
args.tasks_dir = get_current_tasks_dir()
if args.command == 'list':
list_tasks(args.tasks_dir, args.status, args.agent)
elif args.command == 'next':
task = get_next_task(args.tasks_dir, args.agent)
if task:
print(f"Next task for {args.agent}: {task.get('id')}")
print(f" Title: {task.get('title')}")
print(f" Files: {task.get('file_paths', [])}")
else:
print(f"No pending tasks for {args.agent}")
elif args.command == 'update':
update_task_status(args.tasks_dir, args.task_id, args.status, args.notes)
elif args.command == 'status':
show_status(args.tasks_dir, args.manifest)
elif args.command == 'complete-all':
complete_all_tasks(args.tasks_dir)
else:
parser.print_help()
if __name__ == "__main__":
main()

715
skills/guardrail-orchestrator/scripts/task_state_manager.py Normal file
View File

@ -0,0 +1,715 @@
#!/usr/bin/env python3
"""
Task State Manager for parallel execution and dependency tracking.
Manages task-level states independently from workflow phase, enabling:
- Multiple tasks in_progress simultaneously (if no blocking dependencies)
- Dependency validation before task execution
- Task grouping by agent type for parallel frontend/backend work
"""
import argparse
import json
import os
import sys
from datetime import datetime
from pathlib import Path
from typing import Dict, List, Optional, Set, Tuple
# Try to import yaml
try:
import yaml
HAS_YAML = True
except ImportError:
HAS_YAML = False
# ============================================================================
# YAML Helpers
# ============================================================================
def load_yaml(filepath: str) -> dict:
"""Load YAML file."""
if not os.path.exists(filepath):
return {}
with open(filepath, 'r') as f:
content = f.read()
if not content.strip():
return {}
if HAS_YAML:
return yaml.safe_load(content) or {}
return parse_simple_yaml(content)
def parse_simple_yaml(content: str) -> dict:
"""Parse simple YAML without PyYAML dependency."""
result = {}
current_key = None
current_list = None
for line in content.split('\n'):
stripped = line.strip()
if not stripped or stripped.startswith('#'):
continue
if stripped.startswith('- '):
if current_list is not None:
value = stripped[2:].strip()
if (value.startswith('"') and value.endswith('"')) or \
(value.startswith("'") and value.endswith("'")):
value = value[1:-1]
current_list.append(value)
continue
if ':' in stripped:
key, _, value = stripped.partition(':')
key = key.strip()
value = value.strip()
if value == '' or value == '[]':
current_key = key
current_list = []
result[key] = current_list
elif value == '{}':
result[key] = {}
current_list = None
elif value == 'null' or value == '~':
result[key] = None
current_list = None
elif value == 'true':
result[key] = True
current_list = None
elif value == 'false':
result[key] = False
current_list = None
elif value.isdigit():
result[key] = int(value)
current_list = None
else:
if (value.startswith('"') and value.endswith('"')) or \
(value.startswith("'") and value.endswith("'")):
value = value[1:-1]
result[key] = value
current_list = None
return result
def save_yaml(filepath: str, data: dict):
"""Save data to YAML file."""
os.makedirs(os.path.dirname(filepath), exist_ok=True)
if HAS_YAML:
with open(filepath, 'w') as f:
yaml.dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
else:
with open(filepath, 'w') as f:
json.dump(data, f, indent=2)
# ============================================================================
# Path Helpers
# ============================================================================
def get_workflow_dir() -> Path:
return Path('.workflow')
def get_current_state_path() -> Path:
return get_workflow_dir() / 'current.yml'
def get_active_version() -> Optional[str]:
"""Get the currently active workflow version."""
current_path = get_current_state_path()
if not current_path.exists():
return None
current = load_yaml(str(current_path))
return current.get('active_version')
def get_tasks_dir() -> Optional[Path]:
"""Get the tasks directory for the active version."""
version = get_active_version()
if not version:
return None
tasks_dir = get_workflow_dir() / 'versions' / version / 'tasks'
tasks_dir.mkdir(parents=True, exist_ok=True)
return tasks_dir
# ============================================================================
# Task State Constants
# ============================================================================
TASK_STATES = ['pending', 'in_progress', 'review', 'approved', 'completed', 'blocked']
VALID_TASK_TRANSITIONS = {
'pending': ['in_progress', 'blocked'],
'in_progress': ['review', 'blocked', 'pending'], # Can go back if paused
'review': ['approved', 'in_progress'], # Can go back if changes needed
'approved': ['completed'],
'completed': [], # Terminal state
'blocked': ['pending'] # Unblocked when dependencies resolve
}
# ============================================================================
# Task Loading
# ============================================================================
def load_all_tasks() -> Dict[str, dict]:
"""Load all tasks from the current version's tasks directory."""
tasks_dir = get_tasks_dir()
if not tasks_dir or not tasks_dir.exists():
return {}
tasks = {}
for task_file in tasks_dir.glob('*.yml'):
task_id = task_file.stem
task = load_yaml(str(task_file))
if task:
tasks[task_id] = task
return tasks
def load_task(task_id: str) -> Optional[dict]:
"""Load a single task by ID."""
tasks_dir = get_tasks_dir()
if not tasks_dir:
return None
task_path = tasks_dir / f"{task_id}.yml"
if not task_path.exists():
return None
return load_yaml(str(task_path))
def save_task(task: dict):
"""Save a task to the tasks directory."""
tasks_dir = get_tasks_dir()
if not tasks_dir:
print("Error: No active workflow")
return
task_id = task.get('id', task.get('task_id'))
if not task_id:
print("Error: Task has no ID")
return
task['updated_at'] = datetime.now().isoformat()
save_yaml(str(tasks_dir / f"{task_id}.yml"), task)
# ============================================================================
# Dependency Resolution
# ============================================================================
def get_task_dependencies(task: dict) -> List[str]:
"""Get the list of task IDs that this task depends on."""
return task.get('dependencies', []) or []
def check_dependencies_met(task_id: str, all_tasks: Dict[str, dict]) -> Tuple[bool, List[str]]:
"""
Check if all dependencies for a task are completed.
Returns:
Tuple of (all_met, unmet_dependency_ids)
"""
task = all_tasks.get(task_id)
if not task:
return False, [f"Task {task_id} not found"]
dependencies = get_task_dependencies(task)
unmet = []
for dep_id in dependencies:
dep_task = all_tasks.get(dep_id)
if not dep_task:
unmet.append(f"{dep_id} (not found)")
elif dep_task.get('status') not in ['completed', 'approved']:
unmet.append(f"{dep_id} (status: {dep_task.get('status', 'unknown')})")
return len(unmet) == 0, unmet
def get_dependency_graph(all_tasks: Dict[str, dict]) -> Dict[str, Set[str]]:
"""Build a dependency graph for all tasks."""
graph = {}
for task_id, task in all_tasks.items():
deps = get_task_dependencies(task)
graph[task_id] = set(deps)
return graph
def detect_circular_dependencies(all_tasks: Dict[str, dict]) -> List[List[str]]:
"""Detect circular dependencies using DFS."""
graph = get_dependency_graph(all_tasks)
cycles = []
visited = set()
rec_stack = set()
def dfs(node: str, path: List[str]) -> bool:
visited.add(node)
rec_stack.add(node)
path.append(node)
for neighbor in graph.get(node, set()):
if neighbor not in visited:
if dfs(neighbor, path):
return True
elif neighbor in rec_stack:
# Found cycle
cycle_start = path.index(neighbor)
cycles.append(path[cycle_start:] + [neighbor])
return True
path.pop()
rec_stack.remove(node)
return False
for node in graph:
if node not in visited:
dfs(node, [])
return cycles
def get_execution_order(all_tasks: Dict[str, dict]) -> List[str]:
"""Get topologically sorted execution order respecting dependencies."""
graph = get_dependency_graph(all_tasks)
# Kahn's algorithm for topological sort
in_degree = {task_id: 0 for task_id in all_tasks}
for deps in graph.values():
for dep in deps:
if dep in in_degree:
in_degree[dep] += 1
queue = [t for t, d in in_degree.items() if d == 0]
result = []
while queue:
node = queue.pop(0)
result.append(node)
for other, deps in graph.items():
if node in deps:
in_degree[other] -= 1
if in_degree[other] == 0:
queue.append(other)
# Reverse since we want dependencies first
return list(reversed(result))
# ============================================================================
# Parallel Execution Support
# ============================================================================
def get_parallel_candidates(all_tasks: Dict[str, dict]) -> Dict[str, List[str]]:
"""
Get tasks that can be executed in parallel, grouped by agent.
Returns:
Dict mapping agent type to list of task IDs ready for parallel execution
"""
candidates = {'frontend': [], 'backend': [], 'other': []}
for task_id, task in all_tasks.items():
status = task.get('status', 'pending')
# Only consider pending tasks
if status != 'pending':
continue
# Check if dependencies are met
deps_met, _ = check_dependencies_met(task_id, all_tasks)
if not deps_met:
continue
# Group by agent
agent = task.get('agent', 'other')
if agent in candidates:
candidates[agent].append(task_id)
else:
candidates['other'].append(task_id)
return candidates
def get_active_tasks() -> Dict[str, List[str]]:
"""
Get currently active (in_progress) tasks grouped by agent.
Returns:
Dict mapping agent type to list of active task IDs
"""
all_tasks = load_all_tasks()
active = {'frontend': [], 'backend': [], 'other': []}
for task_id, task in all_tasks.items():
if task.get('status') == 'in_progress':
agent = task.get('agent', 'other')
if agent in active:
active[agent].append(task_id)
else:
active['other'].append(task_id)
return active
def can_start_task(task_id: str, max_per_agent: int = 1) -> Tuple[bool, str]:
"""
Check if a task can be started given current active tasks.
Args:
task_id: Task to check
max_per_agent: Maximum concurrent tasks per agent type
Returns:
Tuple of (can_start, reason)
"""
all_tasks = load_all_tasks()
task = all_tasks.get(task_id)
if not task:
return False, f"Task {task_id} not found"
status = task.get('status', 'pending')
if status != 'pending':
return False, f"Task is not pending (status: {status})"
# Check dependencies
deps_met, unmet = check_dependencies_met(task_id, all_tasks)
if not deps_met:
return False, f"Dependencies not met: {', '.join(unmet)}"
# Check concurrent task limit per agent
agent = task.get('agent', 'other')
active = get_active_tasks()
if len(active.get(agent, [])) >= max_per_agent:
return False, f"Max concurrent {agent} tasks reached ({max_per_agent})"
return True, "Ready to start"
# ============================================================================
# State Transitions
# ============================================================================
def transition_task(task_id: str, new_status: str) -> Tuple[bool, str]:
"""
Transition a task to a new status with validation.
Returns:
Tuple of (success, message)
"""
task = load_task(task_id)
if not task:
return False, f"Task {task_id} not found"
current_status = task.get('status', 'pending')
# Validate transition
valid_next = VALID_TASK_TRANSITIONS.get(current_status, [])
if new_status not in valid_next:
return False, f"Invalid transition: {current_status} → {new_status}. Valid: {valid_next}"
# For in_progress, check dependencies
if new_status == 'in_progress':
all_tasks = load_all_tasks()
deps_met, unmet = check_dependencies_met(task_id, all_tasks)
if not deps_met:
# Block instead
task['status'] = 'blocked'
task['blocked_by'] = unmet
task['blocked_at'] = datetime.now().isoformat()
save_task(task)
return False, f"Dependencies not met, task blocked: {', '.join(unmet)}"
# Perform transition
task['status'] = new_status
task[f'{new_status}_at'] = datetime.now().isoformat()
# Clear blocked info if unblocking
if current_status == 'blocked' and new_status == 'pending':
task.pop('blocked_by', None)
task.pop('blocked_at', None)
save_task(task)
return True, f"Task {task_id}: {current_status} → {new_status}"
def update_blocked_tasks():
"""Check and unblock tasks whose dependencies are now met."""
all_tasks = load_all_tasks()
unblocked = []
for task_id, task in all_tasks.items():
if task.get('status') != 'blocked':
continue
deps_met, _ = check_dependencies_met(task_id, all_tasks)
if deps_met:
success, msg = transition_task(task_id, 'pending')
if success:
unblocked.append(task_id)
return unblocked
# ============================================================================
# Status Report
# ============================================================================
def get_status_summary() -> dict:
"""Get summary of task statuses."""
all_tasks = load_all_tasks()
summary = {
'total': len(all_tasks),
'by_status': {status: 0 for status in TASK_STATES},
'by_agent': {},
'blocked_details': [],
'ready_for_parallel': get_parallel_candidates(all_tasks)
}
for task_id, task in all_tasks.items():
status = task.get('status', 'pending')
agent = task.get('agent', 'other')
summary['by_status'][status] = summary['by_status'].get(status, 0) + 1
if agent not in summary['by_agent']:
summary['by_agent'][agent] = {'total': 0, 'by_status': {}}
summary['by_agent'][agent]['total'] += 1
summary['by_agent'][agent]['by_status'][status] = \
summary['by_agent'][agent]['by_status'].get(status, 0) + 1
if status == 'blocked':
summary['blocked_details'].append({
'task_id': task_id,
'blocked_by': task.get('blocked_by', []),
'blocked_at': task.get('blocked_at')
})
return summary
def show_status():
"""Display task status summary."""
summary = get_status_summary()
print()
print("╔" + "═" * 60 + "╗")
print("║" + "TASK STATE MANAGER STATUS".center(60) + "║")
print("╠" + "═" * 60 + "╣")
print("║" + f" Total Tasks: {summary['total']}".ljust(60) + "║")
print("╠" + "═" * 60 + "╣")
print("║" + " BY STATUS".ljust(60) + "║")
status_icons = {
'pending': '⏳', 'in_progress': '🔄', 'review': '🔍',
'approved': '✅', 'completed': '✓', 'blocked': '🚫'
}
for status, count in summary['by_status'].items():
icon = status_icons.get(status, '•')
print("║" + f" {icon} {status}: {count}".ljust(60) + "║")
print("╠" + "═" * 60 + "╣")
print("║" + " BY AGENT".ljust(60) + "║")
for agent, data in summary['by_agent'].items():
print("║" + f" {agent}: {data['total']} tasks".ljust(60) + "║")
for status, count in data['by_status'].items():
if count > 0:
print("║" + f" └─ {status}: {count}".ljust(60) + "║")
# Show parallel candidates
parallel = summary['ready_for_parallel']
has_parallel = any(len(v) > 0 for v in parallel.values())
if has_parallel:
print("╠" + "═" * 60 + "╣")
print("║" + " 🔀 READY FOR PARALLEL EXECUTION".ljust(60) + "║")
for agent, tasks in parallel.items():
if tasks:
print("║" + f" {agent}: {', '.join(tasks[:3])}".ljust(60) + "║")
if len(tasks) > 3:
print("║" + f" (+{len(tasks) - 3} more)".ljust(60) + "║")
# Show blocked tasks
if summary['blocked_details']:
print("╠" + "═" * 60 + "╣")
print("║" + " 🚫 BLOCKED TASKS".ljust(60) + "║")
for blocked in summary['blocked_details'][:5]:
deps = ', '.join(blocked['blocked_by'][:2])
if len(blocked['blocked_by']) > 2:
deps += f" (+{len(blocked['blocked_by']) - 2})"
print("║" + f" {blocked['task_id']}".ljust(60) + "║")
print("║" + f" Blocked by: {deps}".ljust(60) + "║")
print("╚" + "═" * 60 + "╝")
# ============================================================================
# CLI Interface
# ============================================================================
def main():
parser = argparse.ArgumentParser(description="Task state management for parallel execution")
subparsers = parser.add_subparsers(dest='command', help='Commands')
# status command
subparsers.add_parser('status', help='Show task status summary')
# transition command
trans_parser = subparsers.add_parser('transition', help='Transition task status')
trans_parser.add_argument('task_id', help='Task ID')
trans_parser.add_argument('status', choices=TASK_STATES, help='New status')
# can-start command
can_start_parser = subparsers.add_parser('can-start', help='Check if task can start')
can_start_parser.add_argument('task_id', help='Task ID')
can_start_parser.add_argument('--max-per-agent', type=int, default=1,
help='Max concurrent tasks per agent')
# parallel command
subparsers.add_parser('parallel', help='Show tasks ready for parallel execution')
# deps command
deps_parser = subparsers.add_parser('deps', help='Show task dependencies')
deps_parser.add_argument('task_id', nargs='?', help='Task ID (optional)')
# check-deps command
check_deps_parser = subparsers.add_parser('check-deps', help='Check if dependencies are met')
check_deps_parser.add_argument('task_id', help='Task ID')
# unblock command
subparsers.add_parser('unblock', help='Update blocked tasks whose deps are now met')
# order command
subparsers.add_parser('order', help='Show execution order respecting dependencies')
# cycles command
subparsers.add_parser('cycles', help='Detect circular dependencies')
args = parser.parse_args()
if args.command == 'status':
show_status()
elif args.command == 'transition':
success, msg = transition_task(args.task_id, args.status)
print(msg)
if not success:
sys.exit(1)
elif args.command == 'can-start':
can_start, reason = can_start_task(args.task_id, args.max_per_agent)
print(f"{'✅ Yes' if can_start else '❌ No'}: {reason}")
sys.exit(0 if can_start else 1)
elif args.command == 'parallel':
all_tasks = load_all_tasks()
candidates = get_parallel_candidates(all_tasks)
print("\n🔀 Tasks Ready for Parallel Execution:\n")
for agent, tasks in candidates.items():
if tasks:
print(f" {agent}:")
for task_id in tasks:
task = all_tasks.get(task_id, {})
print(f" - {task_id}: {task.get('title', 'No title')}")
if not any(candidates.values()):
print(" No tasks ready for parallel execution")
elif args.command == 'deps':
all_tasks = load_all_tasks()
if args.task_id:
task = all_tasks.get(args.task_id)
if task:
deps = get_task_dependencies(task)
print(f"\n{args.task_id} depends on:")
if deps:
for dep_id in deps:
dep = all_tasks.get(dep_id, {})
status = dep.get('status', 'unknown')
print(f" - {dep_id} ({status})")
else:
print(" (no dependencies)")
else:
print(f"Task {args.task_id} not found")
else:
# Show all dependencies
graph = get_dependency_graph(all_tasks)
print("\nDependency Graph:\n")
for task_id, deps in graph.items():
if deps:
print(f" {task_id} ← {', '.join(deps)}")
elif args.command == 'check-deps':
all_tasks = load_all_tasks()
deps_met, unmet = check_dependencies_met(args.task_id, all_tasks)
if deps_met:
print(f"✅ All dependencies met for {args.task_id}")
else:
print(f"❌ Unmet dependencies for {args.task_id}:")
for dep in unmet:
print(f" - {dep}")
sys.exit(0 if deps_met else 1)
elif args.command == 'unblock':
unblocked = update_blocked_tasks()
if unblocked:
print(f"✅ Unblocked {len(unblocked)} tasks:")
for task_id in unblocked:
print(f" - {task_id}")
else:
print("No tasks to unblock")
elif args.command == 'order':
all_tasks = load_all_tasks()
# Check for cycles first
cycles = detect_circular_dependencies(all_tasks)
if cycles:
print("⚠️ Cannot determine order - circular dependencies detected!")
for cycle in cycles:
print(f" Cycle: {' → '.join(cycle)}")
sys.exit(1)
order = get_execution_order(all_tasks)
print("\n📋 Execution Order (respecting dependencies):\n")
for i, task_id in enumerate(order, 1):
task = all_tasks.get(task_id, {})
status = task.get('status', 'pending')
agent = task.get('agent', '?')
print(f" {i}. [{agent}] {task_id} ({status})")
elif args.command == 'cycles':
all_tasks = load_all_tasks()
cycles = detect_circular_dependencies(all_tasks)
if cycles:
print("⚠️ Circular dependencies detected:\n")
for cycle in cycles:
print(f" {' → '.join(cycle)}")
else:
print("✅ No circular dependencies detected")
else:
parser.print_help()
if __name__ == "__main__":
main()

75
skills/guardrail-orchestrator/scripts/transition_phase.py Normal file
View File

@ -0,0 +1,75 @@
#!/usr/bin/env python3
"""Transition project between phases."""
import argparse
import json
import os
from datetime import datetime
VALID_PHASES = ["DESIGN_PHASE", "DESIGN_REVIEW", "IMPLEMENTATION_PHASE"]
VALID_TRANSITIONS = {
"DESIGN_PHASE": ["DESIGN_REVIEW"],
"DESIGN_REVIEW": ["DESIGN_PHASE", "IMPLEMENTATION_PHASE"],
"IMPLEMENTATION_PHASE": ["DESIGN_PHASE"]
}
def load_manifest(manifest_path: str) -> dict:
"""Load manifest."""
with open(manifest_path) as f:
return json.load(f)
def save_manifest(manifest_path: str, manifest: dict):
"""Save manifest."""
with open(manifest_path, "w") as f:
json.dump(manifest, f, indent=2)
def main():
parser = argparse.ArgumentParser(description="Transition project phase")
parser.add_argument("--to", required=True, choices=VALID_PHASES, help="Target phase")
parser.add_argument("--manifest", default="project_manifest.json", help="Manifest path")
args = parser.parse_args()
manifest_path = args.manifest
if not os.path.isabs(manifest_path):
manifest_path = os.path.join(os.getcwd(), manifest_path)
if not os.path.exists(manifest_path):
print(f"Error: Manifest not found at {manifest_path}")
return 1
manifest = load_manifest(manifest_path)
current_phase = manifest["state"]["current_phase"]
target_phase = args.to
if target_phase not in VALID_TRANSITIONS.get(current_phase, []):
print(f"Error: Cannot transition from {current_phase} to {target_phase}")
print(f"Valid transitions: {VALID_TRANSITIONS.get(current_phase, [])}")
return 1
# Update phase
manifest["state"]["current_phase"] = target_phase
# Add to history
manifest["state"]["revision_history"].append({
"action": "PHASE_TRANSITION",
"timestamp": datetime.now().isoformat(),
"details": f"Transitioned from {current_phase} to {target_phase}"
})
# If transitioning to implementation, mark entities as approved
if target_phase == "IMPLEMENTATION_PHASE":
for entity_type in ["pages", "components", "api_endpoints", "database_tables"]:
for entity in manifest["entities"].get(entity_type, []):
if entity.get("status") == "DEFINED":
entity["status"] = "APPROVED"
save_manifest(manifest_path, manifest)
print(f"Transitioned to {target_phase}")
return 0
if __name__ == "__main__":
exit(main())

381
skills/guardrail-orchestrator/scripts/validate_against_contract.py Normal file
View File

@ -0,0 +1,381 @@
#!/usr/bin/env python3
"""
Validate Implementation Against API Contract
This script verifies that both backend and frontend implementations
comply with the generated API contract.
Checks performed:
1. Backend routes exist and export correct HTTP methods
2. Frontend components import from shared types file
3. API calls use correct paths and methods
4. Types are properly imported (not recreated locally)
Exit codes:
0 = All validations pass
1 = Warnings found (non-critical violations)
2 = Critical violations (missing routes, type mismatches)
"""
import os
import sys
import re
import json
from pathlib import Path
from typing import Dict, List, Any, Tuple, Optional
try:
import yaml
except ImportError:
yaml = None
def load_yaml(path: Path) -> Dict:
"""Load YAML file."""
if yaml:
with open(path) as f:
return yaml.safe_load(f)
else:
with open(path) as f:
content = f.read()
try:
return json.loads(content)
except:
return {}
def find_project_root(start_dir: Path) -> Path:
"""Find project root by looking for package.json."""
current = start_dir.resolve()
while current != current.parent:
if (current / 'package.json').exists():
return current
current = current.parent
return start_dir
class ContractValidator:
"""Validates implementation against API contract."""
def __init__(self, contract_path: Path, project_dir: Path):
self.contract_path = contract_path
self.project_dir = project_dir
self.contract = load_yaml(contract_path)
self.violations: List[Dict[str, Any]] = []
self.warnings: List[Dict[str, Any]] = []
def validate_all(self) -> Tuple[int, List[Dict], List[Dict]]:
"""
Run all validations.
Returns:
Tuple of (exit_code, violations, warnings)
"""
# Validate backend
self.validate_backend_routes()
self.validate_backend_type_imports()
# Validate frontend
self.validate_frontend_type_imports()
self.validate_frontend_api_calls()
# Determine exit code
critical_count = len([v for v in self.violations if v.get('severity') == 'critical'])
warning_count = len(self.warnings)
if critical_count > 0:
return 2, self.violations, self.warnings
elif len(self.violations) > 0:
return 1, self.violations, self.warnings
else:
return 0, self.violations, self.warnings
def validate_backend_routes(self) -> None:
"""Validate that all backend routes from contract exist."""
backend_routes = self.contract.get('backend_routes', [])
for route in backend_routes:
file_path = self.project_dir / route['file_path']
endpoint_id = route.get('endpoint_id', 'unknown')
export_name = route.get('export_name', 'GET')
if not file_path.exists():
self.violations.append({
'type': 'missing_route',
'severity': 'critical',
'endpoint_id': endpoint_id,
'expected_file': str(route['file_path']),
'message': f"Backend route file missing: {route['file_path']}",
})
continue
# Check if file exports the correct HTTP method
content = file_path.read_text()
# Check for Next.js App Router pattern: export async function GET/POST/etc.
export_pattern = rf'export\s+(async\s+)?function\s+{export_name}\s*\('
if not re.search(export_pattern, content):
# Also check for const exports: export const GET = ...
const_pattern = rf'export\s+const\s+{export_name}\s*='
if not re.search(const_pattern, content):
self.violations.append({
'type': 'missing_export',
'severity': 'critical',
'endpoint_id': endpoint_id,
'file': str(route['file_path']),
'expected_export': export_name,
'message': f"Route {route['file_path']} missing {export_name} export",
})
def validate_backend_type_imports(self) -> None:
"""Validate backend files import from shared types."""
backend_routes = self.contract.get('backend_routes', [])
for route in backend_routes:
file_path = self.project_dir / route['file_path']
if not file_path.exists():
continue # Already reported as missing
content = file_path.read_text()
# Check for import from @/types/api or ./types/api or ../types/api
import_patterns = [
r"import\s+.*from\s+['\"]@/types/api['\"]",
r"import\s+.*from\s+['\"]\.+/types/api['\"]",
r"import\s+type\s+.*from\s+['\"]@/types/api['\"]",
]
has_import = any(re.search(p, content) for p in import_patterns)
if not has_import:
self.warnings.append({
'type': 'missing_type_import',
'severity': 'warning',
'file': str(route['file_path']),
'message': f"Backend route {route['file_path']} should import types from @/types/api",
})
# Check for local type declarations that might conflict
local_type_patterns = [
r'(interface|type)\s+User\s*[={]',
r'(interface|type)\s+.*Request\s*[={]',
r'(interface|type)\s+.*Response\s*[={]',
]
for pattern in local_type_patterns:
match = re.search(pattern, content)
if match and 'import' not in content[:match.start()].split('\n')[-1]:
self.warnings.append({
'type': 'local_type_definition',
'severity': 'warning',
'file': str(route['file_path']),
'message': f"Backend route defines local types. Should import from @/types/api instead.",
})
break
def validate_frontend_type_imports(self) -> None:
"""Validate frontend files import from shared types."""
frontend_calls = self.contract.get('frontend_calls', [])
checked_files = set()
for call in frontend_calls:
file_path_str = call.get('source', {}).get('file_path', '')
if not file_path_str or file_path_str in checked_files:
continue
checked_files.add(file_path_str)
file_path = self.project_dir / file_path_str
if not file_path.exists():
# Check alternate paths (page vs component)
if '/components/' in file_path_str:
alt_path = file_path_str.replace('/components/', '/app/components/')
file_path = self.project_dir / alt_path
if not file_path.exists():
self.violations.append({
'type': 'missing_frontend_file',
'severity': 'high',
'expected_file': file_path_str,
'message': f"Frontend file missing: {file_path_str}",
})
continue
else:
self.violations.append({
'type': 'missing_frontend_file',
'severity': 'high',
'expected_file': file_path_str,
'message': f"Frontend file missing: {file_path_str}",
})
continue
content = file_path.read_text()
# Check for import from @/types/api
import_patterns = [
r"import\s+.*from\s+['\"]@/types/api['\"]",
r"import\s+.*from\s+['\"]\.+/types/api['\"]",
r"import\s+type\s+.*from\s+['\"]@/types/api['\"]",
]
has_import = any(re.search(p, content) for p in import_patterns)
if not has_import:
self.warnings.append({
'type': 'missing_type_import',
'severity': 'warning',
'file': file_path_str,
'message': f"Frontend file {file_path_str} should import types from @/types/api",
})
def validate_frontend_api_calls(self) -> None:
"""Validate frontend API calls match contract."""
frontend_calls = self.contract.get('frontend_calls', [])
endpoints = {e['id']: e for e in self.contract.get('endpoints', [])}
for call in frontend_calls:
file_path_str = call.get('source', {}).get('file_path', '')
endpoint_id = call.get('endpoint_id', '')
if not file_path_str or endpoint_id not in endpoints:
continue
file_path = self.project_dir / file_path_str
# Try alternate paths
if not file_path.exists():
if '/components/' in file_path_str:
alt_path = file_path_str.replace('/components/', '/app/components/')
file_path = self.project_dir / alt_path
if not file_path.exists():
continue # Already reported
content = file_path.read_text()
endpoint = endpoints[endpoint_id]
expected_method = endpoint.get('method', 'GET')
expected_path = endpoint.get('path', '')
# Check for API call to this endpoint
# Look for fetch calls or axios calls
fetch_patterns = [
rf"fetch\s*\(\s*['\"`][^'\"]*{re.escape(expected_path)}",
rf"fetch\s*\(\s*API_PATHS\.",
rf"axios\.{expected_method.lower()}\s*\(",
]
has_call = any(re.search(p, content, re.IGNORECASE) for p in fetch_patterns)
# If component is supposed to call this API but doesn't, it might be a dynamic call
# or using a different pattern - this is a soft warning
# The important validation is that when they DO call, they use correct types
def validate_types_file_exists(self) -> bool:
"""Check if shared types file exists."""
types_file = self.project_dir / 'app' / 'types' / 'api.ts'
if not types_file.exists():
self.violations.append({
'type': 'missing_types_file',
'severity': 'critical',
'expected_file': 'app/types/api.ts',
'message': "Shared types file missing: app/types/api.ts",
})
return False
return True
def print_report(violations: List[Dict], warnings: List[Dict]) -> None:
"""Print validation report."""
print("\n" + "=" * 60)
print("API CONTRACT VALIDATION REPORT")
print("=" * 60)
if not violations and not warnings:
print("\n✅ ALL VALIDATIONS PASSED")
print("\nBoth frontend and backend implementations comply with the API contract.")
return
if violations:
print(f"\n❌ VIOLATIONS FOUND: {len(violations)}")
print("-" * 40)
critical = [v for v in violations if v.get('severity') == 'critical']
high = [v for v in violations if v.get('severity') == 'high']
other = [v for v in violations if v.get('severity') not in ['critical', 'high']]
if critical:
print("\n🔴 CRITICAL (Must fix):")
for v in critical:
print(f" • {v['message']}")
if 'expected_file' in v:
print(f" Expected: {v['expected_file']}")
if high:
print("\n🟠 HIGH (Should fix):")
for v in high:
print(f" • {v['message']}")
if other:
print("\n🟡 OTHER:")
for v in other:
print(f" • {v['message']}")
if warnings:
print(f"\n⚠️ WARNINGS: {len(warnings)}")
print("-" * 40)
for w in warnings:
print(f" • {w['message']}")
print("\n" + "=" * 60)
if any(v.get('severity') == 'critical' for v in violations):
print("VERDICT: ❌ FAILED - Critical violations must be fixed")
elif violations:
print("VERDICT: ⚠️ WARNINGS - Review and fix if possible")
else:
print("VERDICT: ✅ PASSED with warnings")
def main():
"""Main entry point."""
if len(sys.argv) < 2:
print("Usage: validate_against_contract.py <api_contract.yml> [--project-dir <dir>]", file=sys.stderr)
sys.exit(1)
contract_path = Path(sys.argv[1])
# Parse project directory
project_dir = Path('.')
if '--project-dir' in sys.argv:
idx = sys.argv.index('--project-dir')
project_dir = Path(sys.argv[idx + 1])
project_dir = find_project_root(project_dir)
if not contract_path.exists():
print(f"Error: Contract file not found: {contract_path}", file=sys.stderr)
sys.exit(2)
# Run validation
validator = ContractValidator(contract_path, project_dir)
# First check types file exists
validator.validate_types_file_exists()
# Run all validations
exit_code, violations, warnings = validator.validate_all()
# Print report
print_report(violations, warnings)
# Summary stats
print(f"\nValidation complete:")
print(f" Backend routes checked: {len(validator.contract.get('backend_routes', []))}")
print(f" Frontend calls checked: {len(validator.contract.get('frontend_calls', []))}")
print(f" Types defined: {len(validator.contract.get('types', []))}")
sys.exit(exit_code)
if __name__ == '__main__':
main()

536
skills/guardrail-orchestrator/scripts/validate_api_contract.py Normal file
View File

@ -0,0 +1,536 @@
#!/usr/bin/env python3
"""
API Contract Validator for guardrail workflow.
Validates that frontend API calls match backend endpoint definitions:
- Endpoints exist
- HTTP methods match
- Request/response structures align
Usage:
python3 validate_api_contract.py --manifest project_manifest.json --project-dir .
"""
import argparse
import json
import os
import re
import sys
from pathlib import Path
from typing import NamedTuple
class APICall(NamedTuple):
"""Frontend API call."""
file_path: str
line_number: int
endpoint: str
method: str
has_body: bool
raw_line: str
class APIEndpoint(NamedTuple):
"""Backend API endpoint."""
file_path: str
endpoint: str
method: str
has_request_body: bool
response_type: str
class ContractIssue(NamedTuple):
"""API contract violation."""
severity: str # ERROR, WARNING
category: str
message: str
file_path: str
line_number: int | None
suggestion: str
def load_manifest(manifest_path: str) -> dict | None:
"""Load manifest if exists."""
if not os.path.exists(manifest_path):
return None
try:
with open(manifest_path) as f:
return json.load(f)
except (json.JSONDecodeError, IOError):
return None
def find_frontend_files(project_dir: str) -> list[str]:
"""Find frontend source files."""
frontend_patterns = [
'app/**/*.tsx', 'app/**/*.ts',
'src/**/*.tsx', 'src/**/*.ts',
'pages/**/*.tsx', 'pages/**/*.ts',
'components/**/*.tsx', 'components/**/*.ts',
'hooks/**/*.ts', 'hooks/**/*.tsx',
'lib/**/*.ts', 'lib/**/*.tsx',
'services/**/*.ts', 'services/**/*.tsx',
]
# Exclude patterns
exclude_patterns = ['node_modules', '.next', 'dist', 'build', 'api']
files = []
for pattern in frontend_patterns:
base_dir = pattern.split('/')[0]
search_dir = Path(project_dir) / base_dir
if search_dir.exists():
for file_path in search_dir.rglob('*.ts*'):
path_str = str(file_path)
if not any(ex in path_str for ex in exclude_patterns):
# Skip API route files
if '/api/' not in path_str:
files.append(path_str)
return list(set(files))
def find_backend_files(project_dir: str) -> list[str]:
"""Find backend API route files."""
backend_patterns = [
'app/api/**/*.ts', 'app/api/**/*.tsx',
'pages/api/**/*.ts', 'pages/api/**/*.tsx',
'api/**/*.ts',
'src/api/**/*.ts',
'server/**/*.ts',
'routes/**/*.ts',
]
files = []
for pattern in backend_patterns:
base_parts = pattern.split('/')
search_dir = Path(project_dir)
for part in base_parts[:-1]:
if '*' not in part:
search_dir = search_dir / part
if search_dir.exists():
for file_path in search_dir.rglob('*.ts*'):
path_str = str(file_path)
if 'node_modules' not in path_str:
files.append(path_str)
return list(set(files))
def extract_frontend_api_calls(file_path: str) -> list[APICall]:
"""Extract API calls from frontend file."""
calls = []
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
lines = content.split('\n')
except (IOError, UnicodeDecodeError):
return []
# Patterns for API calls
patterns = [
# fetch('/api/...', { method: 'POST', body: ... })
(r'''fetch\s*\(\s*['"](/api/[^'"]+)['"]''', 'fetch'),
# axios.get('/api/...'), axios.post('/api/...', data)
(r'''axios\.(get|post|put|patch|delete)\s*\(\s*['"](/api/[^'"]+)['"]''', 'axios'),
# api.get('/users'), api.post('/users', data)
(r'''api\.(get|post|put|patch|delete)\s*\(\s*['"]([^'"]+)['"]''', 'api_client'),
# useSWR('/api/...'), useSWR(() => '/api/...')
(r'''useSWR\s*\(\s*['"](/api/[^'"]+)['"]''', 'swr'),
# useQuery(['key'], () => fetch('/api/...'))
(r'''fetch\s*\(\s*[`'"](/api/[^`'"]+)[`'"]''', 'fetch_template'),
]
for line_num, line in enumerate(lines, 1):
for pattern, call_type in patterns:
matches = re.finditer(pattern, line, re.IGNORECASE)
for match in matches:
groups = match.groups()
if call_type == 'fetch' or call_type == 'swr' or call_type == 'fetch_template':
endpoint = groups[0]
# Try to detect method from options
method = 'GET'
if 'method' in line.lower():
method_match = re.search(r'''method:\s*['"](\w+)['"]''', line, re.IGNORECASE)
if method_match:
method = method_match.group(1).upper()
has_body = 'body:' in line.lower() or 'body=' in line.lower()
elif call_type == 'axios' or call_type == 'api_client':
method = groups[0].upper()
endpoint = groups[1]
# POST, PUT, PATCH typically have body
has_body = method in ['POST', 'PUT', 'PATCH']
else:
continue
# Normalize endpoint
if not endpoint.startswith('/api/'):
endpoint = f'/api/{endpoint.lstrip("/")}'
calls.append(APICall(
file_path=file_path,
line_number=line_num,
endpoint=endpoint,
method=method,
has_body=has_body,
raw_line=line.strip()
))
return calls
def extract_backend_endpoints(file_path: str) -> list[APIEndpoint]:
"""Extract API endpoints from backend file."""
endpoints = []
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
except (IOError, UnicodeDecodeError):
return []
# Determine endpoint from file path (Next.js App Router / Pages Router)
rel_path = file_path
if '/app/api/' in file_path:
# App Router: app/api/users/route.ts -> /api/users
api_path = re.search(r'/app/api/(.+?)/(route|page)\.(ts|tsx|js|jsx)', file_path)
if api_path:
endpoint = f'/api/{api_path.group(1)}'
else:
api_path = re.search(r'/app/api/(.+?)\.(ts|tsx|js|jsx)', file_path)
if api_path:
endpoint = f'/api/{api_path.group(1)}'
else:
endpoint = '/api/unknown'
elif '/pages/api/' in file_path:
# Pages Router: pages/api/users.ts -> /api/users
api_path = re.search(r'/pages/api/(.+?)\.(ts|tsx|js|jsx)', file_path)
if api_path:
endpoint = f'/api/{api_path.group(1)}'
else:
endpoint = '/api/unknown'
else:
endpoint = '/api/unknown'
# Clean up dynamic segments: [id] -> :id
endpoint = re.sub(r'\[(\w+)\]', r':\1', endpoint)
# Detect HTTP methods
# Next.js App Router exports: GET, POST, PUT, DELETE, PATCH
app_router_methods = re.findall(
r'export\s+(?:async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)',
content
)
# Pages Router: req.method checks
pages_router_methods = re.findall(
r'''req\.method\s*===?\s*['"](\w+)['"]''',
content
)
# Express-style: router.get, router.post, app.get, app.post
express_methods = re.findall(
r'''(?:router|app)\.(get|post|put|patch|delete)\s*\(''',
content,
re.IGNORECASE
)
methods = set()
methods.update(m.upper() for m in app_router_methods)
methods.update(m.upper() for m in pages_router_methods)
methods.update(m.upper() for m in express_methods)
# Default to GET if no methods detected
if not methods:
methods = {'GET'}
# Detect request body handling
has_body_patterns = [
r'request\.json\(\)',
r'req\.body',
r'await\s+request\.json',
r'JSON\.parse',
r'body\s*:',
]
has_request_body = any(re.search(p, content) for p in has_body_patterns)
# Detect response type
response_type = 'json' # default
if 'NextResponse.json' in content or 'res.json' in content:
response_type = 'json'
elif 'new Response(' in content:
response_type = 'response'
elif 'res.send' in content:
response_type = 'text'
for method in methods:
endpoints.append(APIEndpoint(
file_path=file_path,
endpoint=endpoint,
method=method,
has_request_body=has_request_body,
response_type=response_type
))
return endpoints
def normalize_endpoint(endpoint: str) -> str:
"""Normalize endpoint for comparison."""
# Remove query params
endpoint = endpoint.split('?')[0]
# Normalize dynamic segments
endpoint = re.sub(r':\w+', ':param', endpoint)
endpoint = re.sub(r'\$\{[^}]+\}', ':param', endpoint)
# Remove trailing slash
endpoint = endpoint.rstrip('/')
return endpoint.lower()
def match_endpoints(call_endpoint: str, api_endpoint: str) -> bool:
"""Check if frontend call matches backend endpoint."""
norm_call = normalize_endpoint(call_endpoint)
norm_api = normalize_endpoint(api_endpoint)
# Exact match
if norm_call == norm_api:
return True
# Pattern match with dynamic segments
api_pattern = re.sub(r':param', r'[^/]+', norm_api)
if re.match(f'^{api_pattern}$', norm_call):
return True
return False
def validate_api_contract(
project_dir: str,
manifest: dict | None = None
) -> tuple[list[ContractIssue], dict]:
"""Validate API contract between frontend and backend."""
issues = []
stats = {
'frontend_calls': 0,
'backend_endpoints': 0,
'matched': 0,
'unmatched_calls': 0,
'method_mismatches': 0,
'body_mismatches': 0,
}
# Find files
frontend_files = find_frontend_files(project_dir)
backend_files = find_backend_files(project_dir)
# Extract API calls and endpoints
all_calls: list[APICall] = []
all_endpoints: list[APIEndpoint] = []
for file in frontend_files:
all_calls.extend(extract_frontend_api_calls(file))
for file in backend_files:
all_endpoints.extend(extract_backend_endpoints(file))
stats['frontend_calls'] = len(all_calls)
stats['backend_endpoints'] = len(all_endpoints)
# Build endpoint lookup
endpoint_map: dict[str, list[APIEndpoint]] = {}
for ep in all_endpoints:
key = normalize_endpoint(ep.endpoint)
if key not in endpoint_map:
endpoint_map[key] = []
endpoint_map[key].append(ep)
# Validate each frontend call
for call in all_calls:
matched = False
for ep in all_endpoints:
if match_endpoints(call.endpoint, ep.endpoint):
matched = True
# Check method match
if call.method != ep.method:
# Check if endpoint supports this method
endpoint_methods = [e.method for e in all_endpoints
if match_endpoints(call.endpoint, e.endpoint)]
if call.method not in endpoint_methods:
issues.append(ContractIssue(
severity='ERROR',
category='METHOD_MISMATCH',
message=f"Frontend calls {call.method} {call.endpoint} but backend only supports {endpoint_methods}",
file_path=call.file_path,
line_number=call.line_number,
suggestion=f"Change method to one of: {', '.join(endpoint_methods)}"
))
stats['method_mismatches'] += 1
continue
# Check body requirements
if call.has_body and not ep.has_request_body:
issues.append(ContractIssue(
severity='WARNING',
category='BODY_MISMATCH',
message=f"Frontend sends body to {call.endpoint} but backend may not process it",
file_path=call.file_path,
line_number=call.line_number,
suggestion="Verify backend handles request body or remove body from frontend call"
))
stats['body_mismatches'] += 1
if not call.has_body and ep.has_request_body and ep.method in ['POST', 'PUT', 'PATCH']:
issues.append(ContractIssue(
severity='WARNING',
category='MISSING_BODY',
message=f"Backend expects body for {call.method} {call.endpoint} but frontend may not send it",
file_path=call.file_path,
line_number=call.line_number,
suggestion="Add request body to frontend call"
))
stats['matched'] += 1
break
if not matched:
issues.append(ContractIssue(
severity='ERROR',
category='ENDPOINT_NOT_FOUND',
message=f"Frontend calls {call.method} {call.endpoint} but no matching backend endpoint found",
file_path=call.file_path,
line_number=call.line_number,
suggestion=f"Create backend endpoint at {call.endpoint} or fix the frontend URL"
))
stats['unmatched_calls'] += 1
# Check for unused backend endpoints
called_endpoints = set()
for call in all_calls:
called_endpoints.add((normalize_endpoint(call.endpoint), call.method))
for ep in all_endpoints:
key = (normalize_endpoint(ep.endpoint), ep.method)
if key not in called_endpoints:
# Check if any call matches with different method
matching_calls = [c for c in all_calls
if match_endpoints(c.endpoint, ep.endpoint)]
if not matching_calls:
issues.append(ContractIssue(
severity='WARNING',
category='UNUSED_ENDPOINT',
message=f"Backend endpoint {ep.method} {ep.endpoint} is not called by frontend",
file_path=ep.file_path,
line_number=None,
suggestion="Verify endpoint is needed or remove unused code"
))
return issues, stats
def format_report(issues: list[ContractIssue], stats: dict) -> str:
"""Format validation report."""
lines = []
lines.append("")
lines.append("=" * 70)
lines.append(" API CONTRACT VALIDATION REPORT")
lines.append("=" * 70)
lines.append("")
# Stats
lines.append("SUMMARY")
lines.append("-" * 70)
lines.append(f" Frontend API calls found: {stats['frontend_calls']}")
lines.append(f" Backend endpoints found: {stats['backend_endpoints']}")
lines.append(f" Matched calls: {stats['matched']}")
lines.append(f" Unmatched calls: {stats['unmatched_calls']}")
lines.append(f" Method mismatches: {stats['method_mismatches']}")
lines.append(f" Body mismatches: {stats['body_mismatches']}")
lines.append("")
# Issues by severity
errors = [i for i in issues if i.severity == 'ERROR']
warnings = [i for i in issues if i.severity == 'WARNING']
if errors:
lines.append("ERRORS (must fix)")
lines.append("-" * 70)
for i, issue in enumerate(errors, 1):
lines.append(f" {i}. [{issue.category}] {issue.message}")
lines.append(f" File: {issue.file_path}:{issue.line_number or '?'}")
lines.append(f" Fix: {issue.suggestion}")
lines.append("")
if warnings:
lines.append("WARNINGS (review)")
lines.append("-" * 70)
for i, issue in enumerate(warnings, 1):
lines.append(f" {i}. [{issue.category}] {issue.message}")
lines.append(f" File: {issue.file_path}:{issue.line_number or '?'}")
lines.append(f" Fix: {issue.suggestion}")
lines.append("")
# Result
lines.append("=" * 70)
if not errors:
lines.append(" RESULT: PASS (no errors)")
else:
lines.append(f" RESULT: FAIL ({len(errors)} errors)")
lines.append("=" * 70)
return "\n".join(lines)
def main():
parser = argparse.ArgumentParser(description="Validate API contract")
parser.add_argument("--manifest", help="Path to project_manifest.json")
parser.add_argument("--project-dir", default=".", help="Project directory")
parser.add_argument("--json", action="store_true", help="Output as JSON")
parser.add_argument("--strict", action="store_true", help="Fail on warnings too")
args = parser.parse_args()
manifest = None
if args.manifest:
manifest = load_manifest(args.manifest)
issues, stats = validate_api_contract(args.project_dir, manifest)
if args.json:
output = {
'stats': stats,
'issues': [
{
'severity': i.severity,
'category': i.category,
'message': i.message,
'file_path': i.file_path,
'line_number': i.line_number,
'suggestion': i.suggestion
}
for i in issues
],
'result': 'PASS' if not any(i.severity == 'ERROR' for i in issues) else 'FAIL'
}
print(json.dumps(output, indent=2))
else:
print(format_report(issues, stats))
# Exit code
errors = [i for i in issues if i.severity == 'ERROR']
warnings = [i for i in issues if i.severity == 'WARNING']
if errors:
return 1
if args.strict and warnings:
return 1
return 0
if __name__ == "__main__":
sys.exit(main())

271
skills/guardrail-orchestrator/scripts/validate_bash.py Normal file
View File

@ -0,0 +1,271 @@
#!/usr/bin/env python3
"""
Bash command validator for guardrail enforcement.
Blocks shell commands that could write files outside the workflow.
Exit codes:
0 = Command allowed
1 = Command blocked (with message)
"""
import argparse
import re
import sys
from pathlib import Path
# Patterns that indicate file writing
WRITE_PATTERNS = [
# Redirections
r'\s*>\s*["\']?([^"\'&|;\s]+)', # > file
r'\s*>>\s*["\']?([^"\'&|;\s]+)', # >> file
r'\s*2>\s*["\']?([^"\'&|;\s]+)', # 2> file
r'\s*&>\s*["\']?([^"\'&|;\s]+)', # &> file
# tee command
r'\btee\s+(?:-a\s+)?["\']?([^"\'&|;\s]+)',
# Direct file creation
r'\btouch\s+["\']?([^"\'&|;\s]+)',
# Copy/Move operations
r'\bcp\s+.*\s+["\']?([^"\'&|;\s]+)',
r'\bmv\s+.*\s+["\']?([^"\'&|;\s]+)',
# In-place editing
r'\bsed\s+-i',
r'\bawk\s+-i\s+inplace',
r'\bperl\s+-i',
# Here documents
r'<<\s*["\']?EOF',
r'<<\s*["\']?END',
r"cat\s*<<",
# mkdir (could be prep for writing)
r'\bmkdir\s+(?:-p\s+)?["\']?([^"\'&|;\s]+)',
# rm (destructive)
r'\brm\s+(?:-rf?\s+)?["\']?([^"\'&|;\s]+)',
# chmod/chown
r'\bchmod\s+',
r'\bchown\s+',
# curl/wget writing to file
r'\bcurl\s+.*-o\s+["\']?([^"\'&|;\s]+)',
r'\bwget\s+.*-O\s+["\']?([^"\'&|;\s]+)',
# git operations that modify files
r'\bgit\s+checkout\s+',
r'\bgit\s+reset\s+--hard',
r'\bgit\s+clean\s+',
r'\bgit\s+stash\s+pop',
# npm/yarn install (modifies node_modules)
r'\bnpm\s+install\b',
r'\byarn\s+add\b',
r'\bpnpm\s+add\b',
# dd command
r'\bdd\s+',
# patch command
r'\bpatch\s+',
# ln (symlinks)
r'\bln\s+',
]
# Commands that are always allowed
ALWAYS_ALLOWED = [
r'^ls\b',
r'^cat\s+[^>]+$', # cat without redirect
r'^head\b',
r'^tail\b',
r'^grep\b',
r'^find\b',
r'^wc\b',
r'^echo\s+[^>]+$', # echo without redirect
r'^pwd$',
r'^cd\b',
r'^which\b',
r'^type\b',
r'^file\b',
r'^stat\b',
r'^du\b',
r'^df\b',
r'^ps\b',
r'^env$',
r'^printenv',
r'^date$',
r'^whoami$',
r'^hostname$',
r'^uname\b',
r'^git\s+status',
r'^git\s+log',
r'^git\s+diff',
r'^git\s+branch',
r'^git\s+show',
r'^git\s+remote',
r'^npm\s+run\b',
r'^npm\s+test\b',
r'^npm\s+start\b',
r'^npx\b',
r'^node\b',
r'^python3?\b.*(?!.*>)', # python without redirect
r'^pip\s+list',
r'^pip\s+show',
r'^tree\b',
r'^jq\b',
r'^curl\s+(?!.*-o)', # curl without -o
r'^wget\s+(?!.*-O)', # wget without -O
]
# Paths that are always allowed for writing
ALLOWED_PATHS = [
'.workflow/',
'.claude/',
'skills/',
'project_manifest.json',
'/tmp/',
'/var/tmp/',
'node_modules/', # npm install
'.git/', # git operations
]
def is_always_allowed(command: str) -> bool:
"""Check if command matches always-allowed patterns."""
command = command.strip()
for pattern in ALWAYS_ALLOWED:
if re.match(pattern, command, re.IGNORECASE):
return True
return False
def extract_target_paths(command: str) -> list:
"""Extract potential file paths being written to."""
paths = []
for pattern in WRITE_PATTERNS:
matches = re.findall(pattern, command)
for match in matches:
if isinstance(match, tuple):
paths.extend(match)
elif match:
paths.append(match)
return [p for p in paths if p and not p.startswith('-')]
def is_path_allowed(path: str) -> bool:
"""Check if path is in allowed list."""
path = path.lstrip('./')
for allowed in ALLOWED_PATHS:
if path.startswith(allowed) or path == allowed.rstrip('/'):
return True
return False
def has_write_operation(command: str) -> tuple[bool, list]:
"""
Check if command contains write operations.
Returns (has_write, target_paths)
"""
for pattern in WRITE_PATTERNS:
if re.search(pattern, command, re.IGNORECASE):
paths = extract_target_paths(command)
return True, paths
return False, []
def validate_bash_command(command: str) -> tuple[bool, str]:
"""
Validate a bash command for guardrail compliance.
Returns (allowed, message)
"""
if not command or not command.strip():
return True, "✓ GUARDRAIL: Empty command"
command = command.strip()
# Check if always allowed
if is_always_allowed(command):
return True, f"✓ GUARDRAIL: Safe command allowed"
# Check for write operations
has_write, target_paths = has_write_operation(command)
if not has_write:
return True, f"✓ GUARDRAIL: No write operations detected"
# Check if all target paths are allowed
blocked_paths = []
for path in target_paths:
if not is_path_allowed(path):
blocked_paths.append(path)
if not blocked_paths:
return True, f"✓ GUARDRAIL: Write to allowed paths"
# Block the command
suggested_feature = f"modify files via bash"
error_msg = f"""
⛔ GUARDRAIL VIOLATION: Bash command blocked
Command: {command[:100]}{'...' if len(command) > 100 else ''}
Detected write operation to unauthorized paths:
{chr(10).join(f' - {p}' for p in blocked_paths)}
╔══════════════════════════════════════════════════════════════════╗
║ 👉 REQUIRED ACTION: Use the workflow instead of bash ║
║ ║
║ Run this command: ║
║ /workflow:spawn {suggested_feature} ║
║ ║
║ Then use Write/Edit tools (not bash) to modify files. ║
║ ║
║ Bash is for reading/running, not writing files. ║
╚══════════════════════════════════════════════════════════════════╝
Allowed bash write targets:
- .workflow/*, .claude/*, skills/*
- project_manifest.json
- /tmp/*, node_modules/
"""
return False, error_msg
def main():
parser = argparse.ArgumentParser(description="Validate bash command for guardrails")
parser.add_argument("--command", help="Bash command to validate")
args = parser.parse_args()
command = args.command or ""
# Also try reading from stdin if no command provided
if not command and not sys.stdin.isatty():
command = sys.stdin.read().strip()
allowed, message = validate_bash_command(command)
if allowed:
print(message)
return 0
else:
print(message, file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())

868
skills/guardrail-orchestrator/scripts/validate_design.py Normal file
View File

@ -0,0 +1,868 @@
#!/usr/bin/env python3
"""
Design Document Validator and Dependency Graph Generator
Validates design_document.yml and generates:
1. dependency_graph.yml - Layered execution order
2. Context snapshots for each task
3. Tasks with full context
"""
import argparse
import json
import os
import sys
from collections import defaultdict
from datetime import datetime
from pathlib import Path
from typing import Any, Dict, List, Optional, Set, Tuple
# Try to import yaml
try:
import yaml
HAS_YAML = True
except ImportError:
HAS_YAML = False
print("Warning: PyYAML not installed. Using basic parser.", file=sys.stderr)
# ============================================================================
# YAML Helpers
# ============================================================================
def load_yaml(filepath: str) -> dict:
"""Load YAML file."""
if not os.path.exists(filepath):
return {}
with open(filepath, 'r') as f:
content = f.read()
if not content.strip():
return {}
if HAS_YAML:
return yaml.safe_load(content) or {}
# Basic fallback parser (limited)
print(f"Warning: Using basic YAML parser for {filepath}", file=sys.stderr)
return {}
def save_yaml(filepath: str, data: dict):
"""Save data to YAML file."""
os.makedirs(os.path.dirname(filepath), exist_ok=True)
if HAS_YAML:
with open(filepath, 'w') as f:
yaml.dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
else:
# Simple JSON fallback
with open(filepath, 'w') as f:
json.dump(data, f, indent=2)
# ============================================================================
# Validation Classes
# ============================================================================
class ValidationError:
"""Represents a validation error."""
def __init__(self, category: str, entity_id: str, message: str, severity: str = "error"):
self.category = category
self.entity_id = entity_id
self.message = message
self.severity = severity # error, warning
def __str__(self):
icon = "❌" if self.severity == "error" else "⚠️"
return f"{icon} [{self.category}] {self.entity_id}: {self.message}"
class DesignValidator:
"""Validates design document structure and relationships."""
def __init__(self, design_doc: dict):
self.design = design_doc
self.errors: List[ValidationError] = []
self.warnings: List[ValidationError] = []
# Collected entity IDs
self.model_ids: Set[str] = set()
self.api_ids: Set[str] = set()
self.page_ids: Set[str] = set()
self.component_ids: Set[str] = set()
self.all_ids: Set[str] = set()
def validate(self) -> bool:
"""Run all validations. Returns True if no errors."""
self._collect_ids()
self._validate_models()
self._validate_apis()
self._validate_pages()
self._validate_components()
self._validate_no_circular_deps()
return len(self.errors) == 0
def _collect_ids(self):
"""Collect all entity IDs."""
for model in self.design.get('data_models', []):
self.model_ids.add(model.get('id', ''))
for api in self.design.get('api_endpoints', []):
self.api_ids.add(api.get('id', ''))
for page in self.design.get('pages', []):
self.page_ids.add(page.get('id', ''))
for comp in self.design.get('components', []):
self.component_ids.add(comp.get('id', ''))
self.all_ids = self.model_ids | self.api_ids | self.page_ids | self.component_ids
def _validate_models(self):
"""Validate data models."""
for model in self.design.get('data_models', []):
model_id = model.get('id', 'unknown')
# Check required fields
if not model.get('id'):
self.errors.append(ValidationError('model', model_id, "Missing 'id' field"))
if not model.get('name'):
self.errors.append(ValidationError('model', model_id, "Missing 'name' field"))
if not model.get('fields'):
self.errors.append(ValidationError('model', model_id, "Missing 'fields' - model has no fields"))
# Check for primary key
fields = model.get('fields', [])
has_pk = any('primary_key' in f.get('constraints', []) for f in fields)
if not has_pk:
self.errors.append(ValidationError('model', model_id, "No primary_key field defined"))
# Check relations reference existing models
for relation in model.get('relations', []):
target = relation.get('target', '')
if target and target not in self.model_ids:
self.errors.append(ValidationError(
'model', model_id,
f"Relation target '{target}' does not exist"
))
# Check enum fields have values
for field in fields:
if field.get('type') == 'enum' and not field.get('enum_values'):
self.errors.append(ValidationError(
'model', model_id,
f"Enum field '{field.get('name')}' missing enum_values"
))
def _validate_apis(self):
"""Validate API endpoints."""
for api in self.design.get('api_endpoints', []):
api_id = api.get('id', 'unknown')
# Check required fields
if not api.get('id'):
self.errors.append(ValidationError('api', api_id, "Missing 'id' field"))
if not api.get('method'):
self.errors.append(ValidationError('api', api_id, "Missing 'method' field"))
if not api.get('path'):
self.errors.append(ValidationError('api', api_id, "Missing 'path' field"))
# POST/PUT/PATCH should have request_body
method = api.get('method', '').upper()
if method in ['POST', 'PUT', 'PATCH'] and not api.get('request_body'):
self.warnings.append(ValidationError(
'api', api_id,
f"{method} endpoint should have request_body",
severity="warning"
))
# Check at least one response defined
if not api.get('responses'):
self.errors.append(ValidationError('api', api_id, "No responses defined"))
# Check model dependencies exist
for model_id in api.get('depends_on_models', []):
if model_id not in self.model_ids:
self.errors.append(ValidationError(
'api', api_id,
f"depends_on_models references non-existent model '{model_id}'"
))
# Check API dependencies exist
for dep_api_id in api.get('depends_on_apis', []):
if dep_api_id not in self.api_ids:
self.errors.append(ValidationError(
'api', api_id,
f"depends_on_apis references non-existent API '{dep_api_id}'"
))
def _validate_pages(self):
"""Validate pages."""
for page in self.design.get('pages', []):
page_id = page.get('id', 'unknown')
# Check required fields
if not page.get('id'):
self.errors.append(ValidationError('page', page_id, "Missing 'id' field"))
if not page.get('path'):
self.errors.append(ValidationError('page', page_id, "Missing 'path' field"))
# Check data_needs reference existing APIs
for data_need in page.get('data_needs', []):
api_id = data_need.get('api_id', '')
if api_id and api_id not in self.api_ids:
self.errors.append(ValidationError(
'page', page_id,
f"data_needs references non-existent API '{api_id}'"
))
# Check components exist
for comp_id in page.get('components', []):
if comp_id not in self.component_ids:
self.errors.append(ValidationError(
'page', page_id,
f"References non-existent component '{comp_id}'"
))
def _validate_components(self):
"""Validate components."""
for comp in self.design.get('components', []):
comp_id = comp.get('id', 'unknown')
# Check required fields
if not comp.get('id'):
self.errors.append(ValidationError('component', comp_id, "Missing 'id' field"))
if not comp.get('name'):
self.errors.append(ValidationError('component', comp_id, "Missing 'name' field"))
# Check uses_apis reference existing APIs
for api_id in comp.get('uses_apis', []):
if api_id not in self.api_ids:
self.errors.append(ValidationError(
'component', comp_id,
f"uses_apis references non-existent API '{api_id}'"
))
# Check uses_components reference existing components
for child_id in comp.get('uses_components', []):
if child_id not in self.component_ids:
self.errors.append(ValidationError(
'component', comp_id,
f"uses_components references non-existent component '{child_id}'"
))
def _validate_no_circular_deps(self):
"""Check for circular dependencies."""
# Build dependency graph
deps: Dict[str, Set[str]] = defaultdict(set)
# Model relations
for model in self.design.get('data_models', []):
model_id = model.get('id', '')
for relation in model.get('relations', []):
target = relation.get('target', '')
if target:
deps[model_id].add(target)
# API dependencies
for api in self.design.get('api_endpoints', []):
api_id = api.get('id', '')
for model_id in api.get('depends_on_models', []):
deps[api_id].add(model_id)
for dep_api_id in api.get('depends_on_apis', []):
deps[api_id].add(dep_api_id)
# Page dependencies
for page in self.design.get('pages', []):
page_id = page.get('id', '')
for data_need in page.get('data_needs', []):
api_id = data_need.get('api_id', '')
if api_id:
deps[page_id].add(api_id)
for comp_id in page.get('components', []):
deps[page_id].add(comp_id)
# Component dependencies
for comp in self.design.get('components', []):
comp_id = comp.get('id', '')
for api_id in comp.get('uses_apis', []):
deps[comp_id].add(api_id)
for child_id in comp.get('uses_components', []):
deps[comp_id].add(child_id)
# Detect cycles using DFS
visited = set()
rec_stack = set()
def has_cycle(node: str, path: List[str]) -> Optional[List[str]]:
visited.add(node)
rec_stack.add(node)
path.append(node)
for neighbor in deps.get(node, []):
if neighbor not in visited:
result = has_cycle(neighbor, path)
if result:
return result
elif neighbor in rec_stack:
# Found cycle
cycle_start = path.index(neighbor)
return path[cycle_start:] + [neighbor]
path.pop()
rec_stack.remove(node)
return None
for entity_id in self.all_ids:
if entity_id not in visited:
cycle = has_cycle(entity_id, [])
if cycle:
self.errors.append(ValidationError(
'dependency', entity_id,
f"Circular dependency detected: {' → '.join(cycle)}"
))
def print_report(self):
"""Print validation report."""
print()
print("=" * 60)
print("DESIGN VALIDATION REPORT".center(60))
print("=" * 60)
# Summary
print()
print(f" Models: {len(self.model_ids)}")
print(f" APIs: {len(self.api_ids)}")
print(f" Pages: {len(self.page_ids)}")
print(f" Components: {len(self.component_ids)}")
print(f" Total: {len(self.all_ids)}")
# Errors
if self.errors:
print()
print("-" * 60)
print(f"ERRORS ({len(self.errors)})")
print("-" * 60)
for error in self.errors:
print(f" {error}")
# Warnings
if self.warnings:
print()
print("-" * 60)
print(f"WARNINGS ({len(self.warnings)})")
print("-" * 60)
for warning in self.warnings:
print(f" {warning}")
# Result
print()
print("=" * 60)
if self.errors:
print("❌ VALIDATION FAILED".center(60))
else:
print("✅ VALIDATION PASSED".center(60))
print("=" * 60)
# ============================================================================
# Dependency Graph Generator
# ============================================================================
class DependencyGraphGenerator:
"""Generates dependency graph and execution layers from design document."""
def __init__(self, design_doc: dict):
self.design = design_doc
self.deps: Dict[str, Set[str]] = defaultdict(set)
self.reverse_deps: Dict[str, Set[str]] = defaultdict(set)
self.entity_types: Dict[str, str] = {}
self.entity_names: Dict[str, str] = {}
self.layers: List[List[str]] = []
def generate(self) -> dict:
"""Generate the full dependency graph."""
self._build_dependency_map()
self._calculate_layers()
return self._build_graph_document()
def _build_dependency_map(self):
"""Build forward and reverse dependency maps."""
# Models
for model in self.design.get('data_models', []):
model_id = model.get('id', '')
self.entity_types[model_id] = 'model'
self.entity_names[model_id] = model.get('name', model_id)
for relation in model.get('relations', []):
target = relation.get('target', '')
if target:
self.deps[model_id].add(target)
self.reverse_deps[target].add(model_id)
# APIs
for api in self.design.get('api_endpoints', []):
api_id = api.get('id', '')
self.entity_types[api_id] = 'api'
self.entity_names[api_id] = api.get('summary', api_id)
for model_id in api.get('depends_on_models', []):
self.deps[api_id].add(model_id)
self.reverse_deps[model_id].add(api_id)
for dep_api_id in api.get('depends_on_apis', []):
self.deps[api_id].add(dep_api_id)
self.reverse_deps[dep_api_id].add(api_id)
# Pages
for page in self.design.get('pages', []):
page_id = page.get('id', '')
self.entity_types[page_id] = 'page'
self.entity_names[page_id] = page.get('name', page_id)
for data_need in page.get('data_needs', []):
api_id = data_need.get('api_id', '')
if api_id:
self.deps[page_id].add(api_id)
self.reverse_deps[api_id].add(page_id)
for comp_id in page.get('components', []):
self.deps[page_id].add(comp_id)
self.reverse_deps[comp_id].add(page_id)
# Components
for comp in self.design.get('components', []):
comp_id = comp.get('id', '')
self.entity_types[comp_id] = 'component'
self.entity_names[comp_id] = comp.get('name', comp_id)
for api_id in comp.get('uses_apis', []):
self.deps[comp_id].add(api_id)
self.reverse_deps[api_id].add(comp_id)
for child_id in comp.get('uses_components', []):
self.deps[comp_id].add(child_id)
self.reverse_deps[child_id].add(comp_id)
def _calculate_layers(self):
"""Calculate execution layers using topological sort."""
# Find all entities with no dependencies (Layer 1)
all_entities = set(self.entity_types.keys())
remaining = all_entities.copy()
assigned = set()
while remaining:
# Find entities whose dependencies are all assigned
layer = []
for entity_id in remaining:
deps = self.deps.get(entity_id, set())
if deps.issubset(assigned):
layer.append(entity_id)
if not layer:
# Shouldn't happen if no circular deps, but safety check
print(f"Warning: Could not assign remaining entities: {remaining}", file=sys.stderr)
break
self.layers.append(sorted(layer))
for entity_id in layer:
remaining.remove(entity_id)
assigned.add(entity_id)
def _build_graph_document(self) -> dict:
"""Build the dependency graph document."""
# Calculate stats
max_parallelism = max(len(layer) for layer in self.layers) if self.layers else 0
critical_path = len(self.layers)
graph = {
'dependency_graph': {
'design_version': self.design.get('revision', 1),
'workflow_version': self.design.get('workflow_version', 'v001'),
'generated_at': datetime.now().isoformat(),
'generator': 'validate_design.py',
'stats': {
'total_entities': len(self.entity_types),
'total_layers': len(self.layers),
'max_parallelism': max_parallelism,
'critical_path_length': critical_path
}
},
'layers': [],
'dependency_map': {},
'task_map': []
}
# Build layers
layer_names = {
1: ("Data Layer", "Database models - no external dependencies"),
2: ("API Layer", "REST endpoints - depend on models"),
3: ("UI Layer", "Pages and components - depend on APIs"),
}
for i, layer_entities in enumerate(self.layers, 1):
name, desc = layer_names.get(i, (f"Layer {i}", f"Entities with {i-1} levels of dependencies"))
layer_items = []
for entity_id in layer_entities:
entity_type = self.entity_types.get(entity_id, 'unknown')
agent = 'backend' if entity_type in ['model', 'api'] else 'frontend'
layer_items.append({
'id': entity_id,
'type': entity_type,
'name': self.entity_names.get(entity_id, entity_id),
'depends_on': list(self.deps.get(entity_id, [])),
'task_id': f"task_create_{entity_id}",
'agent': agent,
'complexity': 'medium' # Could be calculated
})
graph['layers'].append({
'layer': i,
'name': name,
'description': desc,
'items': layer_items,
'requires_layers': list(range(1, i)) if i > 1 else [],
'parallel_count': len(layer_items)
})
# Build dependency map
for entity_id in self.entity_types:
graph['dependency_map'][entity_id] = {
'type': self.entity_types.get(entity_id),
'layer': self._get_layer_number(entity_id),
'depends_on': list(self.deps.get(entity_id, [])),
'depended_by': list(self.reverse_deps.get(entity_id, []))
}
return graph
def _get_layer_number(self, entity_id: str) -> int:
"""Get the layer number for an entity."""
for i, layer in enumerate(self.layers, 1):
if entity_id in layer:
return i
return 0
def print_layers(self):
"""Print layer visualization."""
print()
print("=" * 60)
print("EXECUTION LAYERS".center(60))
print("=" * 60)
for i, layer_entities in enumerate(self.layers, 1):
print()
print(f"Layer {i}: ({len(layer_entities)} items - parallel)")
print("-" * 40)
for entity_id in layer_entities:
entity_type = self.entity_types.get(entity_id, '?')
icon = {'model': '📦', 'api': '🔌', 'page': '📄', 'component': '🧩'}.get(entity_type, '❓')
deps = self.deps.get(entity_id, set())
deps_str = f" ← [{', '.join(deps)}]" if deps else ""
print(f" {icon} {entity_id}{deps_str}")
print()
print("=" * 60)
# ============================================================================
# Context Generator
# ============================================================================
class ContextGenerator:
"""Generates context snapshots for tasks."""
def __init__(self, design_doc: dict, graph: dict, output_dir: str):
self.design = design_doc
self.graph = graph
self.output_dir = output_dir
# Index design entities by ID for quick lookup
self.models: Dict[str, dict] = {}
self.apis: Dict[str, dict] = {}
self.pages: Dict[str, dict] = {}
self.components: Dict[str, dict] = {}
self._index_entities()
def _index_entities(self):
"""Index all entities by ID."""
for model in self.design.get('data_models', []):
self.models[model.get('id', '')] = model
for api in self.design.get('api_endpoints', []):
self.apis[api.get('id', '')] = api
for page in self.design.get('pages', []):
self.pages[page.get('id', '')] = page
for comp in self.design.get('components', []):
self.components[comp.get('id', '')] = comp
def generate_all_contexts(self):
"""Generate context files for all entities."""
contexts_dir = Path(self.output_dir) / 'contexts'
contexts_dir.mkdir(parents=True, exist_ok=True)
for entity_id, entity_info in self.graph.get('dependency_map', {}).items():
context = self._generate_context(entity_id, entity_info)
context_path = contexts_dir / f"{entity_id}.yml"
save_yaml(str(context_path), context)
print(f"Generated {len(self.graph.get('dependency_map', {}))} context files in {contexts_dir}")
def _generate_context(self, entity_id: str, entity_info: dict) -> dict:
"""Generate context for a single entity."""
entity_type = entity_info.get('type', '')
deps = entity_info.get('depends_on', [])
context = {
'task_id': f"task_create_{entity_id}",
'entity_id': entity_id,
'generated_at': datetime.now().isoformat(),
'workflow_version': self.graph.get('dependency_graph', {}).get('workflow_version', 'v001'),
'target': {
'type': entity_type,
'definition': self._get_entity_definition(entity_id, entity_type)
},
'related': {
'models': [],
'apis': [],
'components': []
},
'dependencies': {
'entity_ids': deps,
'definitions': []
},
'files': {
'to_create': self._get_files_to_create(entity_id, entity_type),
'reference': []
},
'acceptance': self._get_acceptance_criteria(entity_id, entity_type)
}
# Add related entity definitions
for dep_id in deps:
dep_info = self.graph.get('dependency_map', {}).get(dep_id, {})
dep_type = dep_info.get('type', '')
dep_def = self._get_entity_definition(dep_id, dep_type)
if dep_type == 'model':
context['related']['models'].append({'id': dep_id, 'definition': dep_def})
elif dep_type == 'api':
context['related']['apis'].append({'id': dep_id, 'definition': dep_def})
elif dep_type == 'component':
context['related']['components'].append({'id': dep_id, 'definition': dep_def})
context['dependencies']['definitions'].append({
'id': dep_id,
'type': dep_type,
'definition': dep_def
})
return context
def _get_entity_definition(self, entity_id: str, entity_type: str) -> dict:
"""Get the full definition for an entity."""
if entity_type == 'model':
return self.models.get(entity_id, {})
elif entity_type == 'api':
return self.apis.get(entity_id, {})
elif entity_type == 'page':
return self.pages.get(entity_id, {})
elif entity_type == 'component':
return self.components.get(entity_id, {})
return {}
def _get_files_to_create(self, entity_id: str, entity_type: str) -> List[str]:
"""Get list of files to create for an entity."""
if entity_type == 'model':
name = self.models.get(entity_id, {}).get('name', entity_id)
return [
'prisma/schema.prisma',
f'app/models/{name.lower()}.ts'
]
elif entity_type == 'api':
path = self.apis.get(entity_id, {}).get('path', '/api/unknown')
route_path = path.replace('/api/', '').replace(':', '')
return [f'app/api/{route_path}/route.ts']
elif entity_type == 'page':
path = self.pages.get(entity_id, {}).get('path', '/unknown')
return [f'app{path}/page.tsx']
elif entity_type == 'component':
name = self.components.get(entity_id, {}).get('name', 'Unknown')
return [f'app/components/{name}.tsx']
return []
def _get_acceptance_criteria(self, entity_id: str, entity_type: str) -> List[dict]:
"""Get acceptance criteria for an entity."""
criteria = []
if entity_type == 'model':
criteria = [
{'criterion': 'Model defined in Prisma schema', 'verification': 'Check prisma/schema.prisma'},
{'criterion': 'TypeScript types exported', 'verification': 'Import type in test file'},
{'criterion': 'Relations properly configured', 'verification': 'Check Prisma relations'},
]
elif entity_type == 'api':
api = self.apis.get(entity_id, {})
method = api.get('method', 'GET')
path = api.get('path', '/api/unknown')
criteria = [
{'criterion': f'{method} {path} returns success response', 'verification': f'curl -X {method} {path}'},
{'criterion': 'Request validation implemented', 'verification': 'Test with invalid data'},
{'criterion': 'Error responses match contract', 'verification': 'Test error scenarios'},
]
elif entity_type == 'page':
page = self.pages.get(entity_id, {})
path = page.get('path', '/unknown')
criteria = [
{'criterion': f'Page renders at {path}', 'verification': f'Navigate to {path}'},
{'criterion': 'Data fetching works', 'verification': 'Check network tab'},
{'criterion': 'Components render correctly', 'verification': 'Visual inspection'},
]
elif entity_type == 'component':
criteria = [
{'criterion': 'Component renders without errors', 'verification': 'Import and render in test'},
{'criterion': 'Props are typed correctly', 'verification': 'TypeScript compilation'},
{'criterion': 'Events fire correctly', 'verification': 'Test event handlers'},
]
return criteria
# ============================================================================
# Task Generator
# ============================================================================
class TaskGenerator:
"""Generates task files with full context."""
def __init__(self, design_doc: dict, graph: dict, output_dir: str):
self.design = design_doc
self.graph = graph
self.output_dir = output_dir
def generate_all_tasks(self):
"""Generate task files for all entities."""
tasks_dir = Path(self.output_dir) / 'tasks'
tasks_dir.mkdir(parents=True, exist_ok=True)
task_count = 0
for layer in self.graph.get('layers', []):
for item in layer.get('items', []):
task = self._generate_task(item, layer.get('layer', 1))
task_path = tasks_dir / f"{task['id']}.yml"
save_yaml(str(task_path), task)
task_count += 1
print(f"Generated {task_count} task files in {tasks_dir}")
def _generate_task(self, item: dict, layer_num: int) -> dict:
"""Generate a task for an entity."""
entity_id = item.get('id', '')
entity_type = item.get('type', '')
task = {
'id': item.get('task_id', f'task_create_{entity_id}'),
'type': 'create',
'title': f"Create {item.get('name', entity_id)}",
'agent': item.get('agent', 'backend'),
'entity_id': entity_id,
'entity_ids': [entity_id],
'status': 'pending',
'layer': layer_num,
'parallel_group': f"layer_{layer_num}",
'complexity': item.get('complexity', 'medium'),
'dependencies': [f"task_create_{dep}" for dep in item.get('depends_on', [])],
'context': {
'design_version': self.graph.get('dependency_graph', {}).get('design_version', 1),
'workflow_version': self.graph.get('dependency_graph', {}).get('workflow_version', 'v001'),
'context_snapshot_path': f".workflow/versions/v001/contexts/{entity_id}.yml"
},
'created_at': datetime.now().isoformat()
}
return task
# ============================================================================
# Main CLI
# ============================================================================
def main():
parser = argparse.ArgumentParser(description="Validate design document and generate dependency graph")
parser.add_argument('design_file', help='Path to design_document.yml')
parser.add_argument('--output-dir', '-o', default='.workflow/versions/v001',
help='Output directory for generated files')
parser.add_argument('--validate-only', '-v', action='store_true',
help='Only validate, do not generate files')
parser.add_argument('--quiet', '-q', action='store_true',
help='Suppress output except errors')
parser.add_argument('--json', action='store_true',
help='Output validation result as JSON')
args = parser.parse_args()
# Load design document
design = load_yaml(args.design_file)
if not design:
print(f"Error: Could not load design document: {args.design_file}", file=sys.stderr)
sys.exit(1)
# Validate
validator = DesignValidator(design)
is_valid = validator.validate()
if args.json:
result = {
'valid': is_valid,
'errors': [str(e) for e in validator.errors],
'warnings': [str(w) for w in validator.warnings],
'stats': {
'models': len(validator.model_ids),
'apis': len(validator.api_ids),
'pages': len(validator.page_ids),
'components': len(validator.component_ids)
}
}
print(json.dumps(result, indent=2))
sys.exit(0 if is_valid else 1)
if not args.quiet:
validator.print_report()
if not is_valid:
sys.exit(1)
if args.validate_only:
sys.exit(0)
# Generate dependency graph
generator = DependencyGraphGenerator(design)
graph = generator.generate()
if not args.quiet:
generator.print_layers()
# Save dependency graph
output_dir = Path(args.output_dir)
output_dir.mkdir(parents=True, exist_ok=True)
graph_path = output_dir / 'dependency_graph.yml'
save_yaml(str(graph_path), graph)
print(f"Saved dependency graph to: {graph_path}")
# Generate context files
context_gen = ContextGenerator(design, graph, str(output_dir))
context_gen.generate_all_contexts()
# Generate task files
task_gen = TaskGenerator(design, graph, str(output_dir))
task_gen.generate_all_tasks()
print()
print("✅ Design validation and generation complete!")
print(f" Output directory: {output_dir}")
if __name__ == "__main__":
main()

129
skills/guardrail-orchestrator/scripts/validate_manifest.py Normal file
View File

@ -0,0 +1,129 @@
#!/usr/bin/env python3
"""Validate project manifest integrity."""
import argparse
import json
import os
import sys
def validate_structure(manifest: dict) -> list:
"""Validate manifest has required structure."""
errors = []
required_keys = ["project", "state", "entities", "dependencies"]
for key in required_keys:
if key not in manifest:
errors.append(f"Missing required key: {key}")
if "entities" in manifest:
entity_types = ["pages", "components", "api_endpoints", "database_tables"]
for etype in entity_types:
if etype not in manifest["entities"]:
errors.append(f"Missing entity type: {etype}")
return errors
def validate_pages(pages: list) -> list:
"""Validate page entities."""
errors = []
for page in pages:
if "id" not in page:
errors.append(f"Page missing id: {page}")
if "path" not in page:
errors.append(f"Page {page.get('id', 'unknown')} missing path")
if "file_path" not in page:
errors.append(f"Page {page.get('id', 'unknown')} missing file_path")
return errors
def validate_components(components: list) -> list:
"""Validate component entities."""
errors = []
for comp in components:
if "id" not in comp:
errors.append(f"Component missing id: {comp}")
if "name" not in comp:
errors.append(f"Component {comp.get('id', 'unknown')} missing name")
if "file_path" not in comp:
errors.append(f"Component {comp.get('id', 'unknown')} missing file_path")
return errors
def validate_apis(apis: list) -> list:
"""Validate API endpoint entities."""
errors = []
for api in apis:
if "id" not in api:
errors.append(f"API missing id: {api}")
if "method" not in api:
errors.append(f"API {api.get('id', 'unknown')} missing method")
if "path" not in api:
errors.append(f"API {api.get('id', 'unknown')} missing path")
return errors
def validate_tables(tables: list) -> list:
"""Validate database table entities."""
errors = []
for table in tables:
if "id" not in table:
errors.append(f"Table missing id: {table}")
if "name" not in table:
errors.append(f"Table {table.get('id', 'unknown')} missing name")
if "columns" not in table:
errors.append(f"Table {table.get('id', 'unknown')} missing columns")
return errors
def main():
parser = argparse.ArgumentParser(description="Validate project manifest")
parser.add_argument("--strict", action="store_true", help="Treat warnings as errors")
parser.add_argument("--manifest", default="project_manifest.json", help="Path to manifest")
args = parser.parse_args()
manifest_path = args.manifest
if not os.path.isabs(manifest_path):
manifest_path = os.path.join(os.getcwd(), manifest_path)
if not os.path.exists(manifest_path):
print(f"Error: Manifest not found at {manifest_path}")
return 1
with open(manifest_path) as f:
manifest = json.load(f)
errors = []
warnings = []
# Structure validation
errors.extend(validate_structure(manifest))
if "entities" in manifest:
errors.extend(validate_pages(manifest["entities"].get("pages", [])))
errors.extend(validate_components(manifest["entities"].get("components", [])))
errors.extend(validate_apis(manifest["entities"].get("api_endpoints", [])))
errors.extend(validate_tables(manifest["entities"].get("database_tables", [])))
# Report results
if errors:
print("VALIDATION FAILED")
for error in errors:
print(f" ERROR: {error}")
return 1
if warnings:
print("VALIDATION PASSED WITH WARNINGS")
for warning in warnings:
print(f" WARNING: {warning}")
if args.strict:
return 1
return 0
print("VALIDATION PASSED")
return 0
if __name__ == "__main__":
exit(main())

478
skills/guardrail-orchestrator/scripts/validate_workflow.py Executable file
View File

@ -0,0 +1,478 @@
#!/usr/bin/env python3
"""
Workflow enforcement hook for Claude Code.
Validates that operations comply with current workflow phase.
When blocked, instructs AI to run /workflow:spawn to start a proper workflow.
Exit codes:
0 = Operation allowed
1 = Operation blocked (with message)
"""
import argparse
import json
import os
import sys
from pathlib import Path
# Try to import yaml
try:
import yaml
HAS_YAML = True
except ImportError:
HAS_YAML = False
def load_yaml(filepath: str) -> dict:
"""Load YAML file."""
if not os.path.exists(filepath):
return {}
with open(filepath, 'r') as f:
content = f.read()
if not content.strip():
return {}
if HAS_YAML:
return yaml.safe_load(content) or {}
# Simple fallback parser
result = {}
current_list = None
for line in content.split('\n'):
stripped = line.strip()
if not stripped or stripped.startswith('#'):
continue
# Handle list items
if stripped.startswith('- '):
if current_list is not None:
value = stripped[2:].strip()
if (value.startswith('"') and value.endswith('"')) or \
(value.startswith("'") and value.endswith("'")):
value = value[1:-1]
current_list.append(value)
continue
if ':' in stripped:
key, _, value = stripped.partition(':')
key = key.strip()
value = value.strip()
if value == '' or value == '[]':
result[key] = []
current_list = result[key]
elif value == 'null' or value == '~':
result[key] = None
current_list = None
elif value == 'true':
result[key] = True
current_list = None
elif value == 'false':
result[key] = False
current_list = None
elif value.isdigit():
result[key] = int(value)
current_list = None
else:
if (value.startswith('"') and value.endswith('"')) or \
(value.startswith("'") and value.endswith("'")):
value = value[1:-1]
result[key] = value
current_list = None
return result
def get_current_phase() -> str:
"""Get current workflow phase from version session."""
workflow_dir = Path('.workflow')
current_path = workflow_dir / 'current.yml'
if not current_path.exists():
return 'NO_WORKFLOW'
current = load_yaml(str(current_path))
active_version = current.get('active_version')
if not active_version:
return 'NO_WORKFLOW'
session_path = workflow_dir / 'versions' / active_version / 'session.yml'
if not session_path.exists():
return 'NO_WORKFLOW'
session = load_yaml(str(session_path))
return session.get('current_phase', 'UNKNOWN')
def get_active_version() -> str:
"""Get active workflow version."""
workflow_dir = Path('.workflow')
current_path = workflow_dir / 'current.yml'
if not current_path.exists():
return None
current = load_yaml(str(current_path))
return current.get('active_version')
def get_workflow_feature() -> str:
"""Get the feature name from current workflow."""
workflow_dir = Path('.workflow')
current_path = workflow_dir / 'current.yml'
if not current_path.exists():
return None
current = load_yaml(str(current_path))
active_version = current.get('active_version')
if not active_version:
return None
session_path = workflow_dir / 'versions' / active_version / 'session.yml'
if not session_path.exists():
return None
session = load_yaml(str(session_path))
return session.get('feature', 'unknown feature')
def count_task_files(version: str) -> int:
"""Count task files in version directory."""
tasks_dir = Path('.workflow') / 'versions' / version / 'tasks'
if not tasks_dir.exists():
return 0
return len(list(tasks_dir.glob('task_*.yml')))
def extract_feature_from_file(file_path: str) -> str:
"""Extract a feature description from the file path."""
# Convert path to a human-readable feature description
parts = Path(file_path).parts
# Remove common prefixes
skip = {'src', 'app', 'lib', 'components', 'pages', 'api', 'utils', 'hooks'}
meaningful = [p for p in parts if p not in skip and not p.startswith('.')]
if meaningful:
# Get the file name without extension
name = Path(file_path).stem
return f"update {name}"
return f"modify {file_path}"
def validate_task_spawn(tool_input: dict) -> tuple[bool, str]:
"""
Validate Task tool spawning for workflow compliance.
"""
phase = get_current_phase()
prompt = tool_input.get('prompt', '')
subagent_type = tool_input.get('subagent_type', '')
agent_type = subagent_type.lower()
# Check architect agent
if 'system-architect' in agent_type or 'ARCHITECT AGENT' in prompt.upper():
if phase not in ['DESIGNING', 'NO_WORKFLOW']:
return False, f"""
⛔ WORKFLOW VIOLATION: Cannot spawn Architect agent
Current Phase: {phase}
Required Phase: DESIGNING
The Architect agent can only be spawned during the DESIGNING phase.
👉 REQUIRED ACTION: Run /workflow:status to check current state.
"""
# Check frontend agent
if 'frontend' in agent_type or 'FRONTEND AGENT' in prompt.upper():
if phase not in ['IMPLEMENTING', 'IMPL_REJECTED']:
return False, f"""
⛔ WORKFLOW VIOLATION: Cannot spawn Frontend agent
Current Phase: {phase}
Required Phase: IMPLEMENTING
👉 REQUIRED ACTION: Complete the design phase first, then run /workflow:approve
"""
version = get_active_version()
if version and count_task_files(version) == 0:
return False, f"""
⛔ WORKFLOW VIOLATION: No task files found
Cannot start implementation without design tasks.
👉 REQUIRED ACTION: Ensure Architect agent created task files in:
.workflow/versions/{version}/tasks/
"""
# Check backend agent
if 'backend' in agent_type or 'BACKEND AGENT' in prompt.upper():
if phase not in ['IMPLEMENTING', 'IMPL_REJECTED']:
return False, f"""
⛔ WORKFLOW VIOLATION: Cannot spawn Backend agent
Current Phase: {phase}
Required Phase: IMPLEMENTING
👉 REQUIRED ACTION: Complete the design phase first, then run /workflow:approve
"""
# Check reviewer agent
if 'quality' in agent_type or 'REVIEWER AGENT' in prompt.upper():
if phase not in ['REVIEWING', 'AWAITING_IMPL_APPROVAL']:
return False, f"""
⛔ WORKFLOW VIOLATION: Cannot spawn Reviewer agent
Current Phase: {phase}
Required Phase: REVIEWING
👉 REQUIRED ACTION: Complete implementation first.
"""
# Check security agent
if 'security' in agent_type or 'SECURITY AGENT' in prompt.upper():
if phase not in ['SECURITY_REVIEW', 'REVIEWING']:
return False, f"""
⛔ WORKFLOW VIOLATION: Cannot spawn Security agent
Current Phase: {phase}
Required Phase: SECURITY_REVIEW
👉 REQUIRED ACTION: Complete code review first, then security review runs.
"""
return True, ""
def validate_write_operation(tool_input: dict) -> tuple[bool, str]:
"""
Validate Write/Edit operations for workflow compliance.
"""
phase = get_current_phase()
file_path = tool_input.get('file_path', tool_input.get('path', ''))
if not file_path:
return True, ""
# Normalize path
try:
abs_file_path = str(Path(file_path).resolve())
project_dir = str(Path.cwd().resolve())
if abs_file_path.startswith(project_dir):
rel_path = abs_file_path[len(project_dir):].lstrip('/')
else:
rel_path = file_path
except:
rel_path = file_path
# Always allow these
always_allowed = [
'project_manifest.json',
'.workflow/',
'skills/',
'.claude/',
'CLAUDE.md',
'package.json',
'package-lock.json',
'docs/', # Documentation generation (/eureka:index, /eureka:landing)
'claudedocs/', # Claude-specific documentation
'public/', # Public assets (landing pages, images)
]
for allowed in always_allowed:
if rel_path.startswith(allowed) or rel_path == allowed.rstrip('/'):
return True, ""
# Extract feature suggestion from file path
suggested_feature = extract_feature_from_file(rel_path)
# NO_WORKFLOW - Must start a workflow first
if phase == 'NO_WORKFLOW':
return False, f"""
⛔ WORKFLOW REQUIRED: No active workflow
You are trying to modify: {rel_path}
This project uses guardrail workflows. You cannot directly edit files.
╔══════════════════════════════════════════════════════════════════╗
║ 👉 REQUIRED ACTION: Start a workflow first! ║
║ ║
║ Run this command: ║
║ /workflow:spawn {suggested_feature} ║
║ ║
║ This will: ║
║ 1. Create a design for your changes ║
║ 2. Get approval ║
║ 3. Then allow you to implement ║
╚══════════════════════════════════════════════════════════════════╝
"""
# DESIGNING phase - can't write implementation files
if phase == 'DESIGNING':
return False, f"""
⛔ WORKFLOW VIOLATION: Cannot write implementation files during DESIGNING
Current Phase: DESIGNING
File: {rel_path}
During DESIGNING phase, only these files can be modified:
- project_manifest.json
- .workflow/versions/*/tasks/*.yml
╔══════════════════════════════════════════════════════════════════╗
║ 👉 REQUIRED ACTION: Complete design and get approval ║
║ ║
║ 1. Finish adding entities to project_manifest.json ║
║ 2. Create task files in .workflow/versions/*/tasks/ ║
║ 3. Run: /workflow:approve ║
╚══════════════════════════════════════════════════════════════════╝
"""
# REVIEWING phase - read only
if phase == 'REVIEWING':
return False, f"""
⛔ WORKFLOW VIOLATION: Cannot write files during REVIEWING
Current Phase: REVIEWING
File: {rel_path}
During REVIEWING phase, files are READ-ONLY.
╔══════════════════════════════════════════════════════════════════╗
║ 👉 REQUIRED ACTION: Complete the review ║
║ ║
║ If changes are needed: ║
║ - Run: /workflow:reject "reason for changes" ║
║ - This returns to IMPLEMENTING phase ║
║ ║
║ If review passes: ║
║ - Run: /workflow:approve ║
╚══════════════════════════════════════════════════════════════════╝
"""
# SECURITY_REVIEW phase - read only
if phase == 'SECURITY_REVIEW':
return False, f"""
⛔ WORKFLOW VIOLATION: Cannot write files during SECURITY_REVIEW
Current Phase: SECURITY_REVIEW
File: {rel_path}
During SECURITY_REVIEW phase, files are READ-ONLY.
Security scan is running to check for vulnerabilities.
╔══════════════════════════════════════════════════════════════════╗
║ 👉 REQUIRED ACTION: Wait for security scan to complete ║
║ ║
║ If security issues found: ║
║ - Workflow returns to IMPLEMENTING phase to fix issues ║
║ ║
║ If security passes: ║
║ - Workflow proceeds to AWAITING_IMPL_APPROVAL ║
║ ║
║ For full audit: /workflow:security --full ║
╚══════════════════════════════════════════════════════════════════╝
"""
# AWAITING approval phases
if phase in ['AWAITING_DESIGN_APPROVAL', 'AWAITING_IMPL_APPROVAL']:
gate_type = "design" if "DESIGN" in phase else "implementation"
return False, f"""
⛔ WORKFLOW VIOLATION: Cannot write files while awaiting approval
Current Phase: {phase}
File: {rel_path}
╔══════════════════════════════════════════════════════════════════╗
║ 👉 REQUIRED ACTION: Get user approval ║
║ ║
║ Waiting for {gate_type} approval. Ask the user to run: ║
║ - /workflow:approve (to proceed) ║
║ - /workflow:reject (to revise) ║
╚══════════════════════════════════════════════════════════════════╝
"""
# COMPLETED - need new workflow
if phase == 'COMPLETED':
return False, f"""
⛔ WORKFLOW VIOLATION: Workflow already completed
Current Phase: COMPLETED
File: {rel_path}
This workflow version is complete.
╔══════════════════════════════════════════════════════════════════╗
║ 👉 REQUIRED ACTION: Start a new workflow ║
║ ║
║ Run: /workflow:spawn {suggested_feature} ║
╚══════════════════════════════════════════════════════════════════╝
"""
return True, ""
def validate_transition(tool_input: dict) -> tuple[bool, str]:
"""Validate phase transitions for proper sequencing."""
return True, ""
def main():
parser = argparse.ArgumentParser(description="Workflow enforcement hook")
parser.add_argument('--operation', required=True,
choices=['task', 'write', 'edit', 'transition', 'build'],
help='Operation type being validated')
parser.add_argument('--input', help='JSON input from tool call')
parser.add_argument('--file', help='File path (for write/edit operations)')
args = parser.parse_args()
# Parse input
tool_input = {}
if args.input:
try:
tool_input = json.loads(args.input)
except json.JSONDecodeError:
tool_input = {'raw': args.input}
if args.file:
tool_input['file_path'] = args.file
# Route to appropriate validator
allowed = True
message = ""
if args.operation == 'task':
allowed, message = validate_task_spawn(tool_input)
elif args.operation in ['write', 'edit']:
allowed, message = validate_write_operation(tool_input)
elif args.operation == 'transition':
allowed, message = validate_transition(tool_input)
elif args.operation == 'build':
phase = get_current_phase()
print(f"BUILD: Running in phase {phase}")
allowed = True
# Output result
if not allowed:
print(message, file=sys.stderr)
sys.exit(1)
else:
phase = get_current_phase()
version = get_active_version() or 'N/A'
print(f"✓ WORKFLOW: {args.operation.upper()} allowed in {phase} (v{version})")
sys.exit(0)
if __name__ == "__main__":
main()

282
skills/guardrail-orchestrator/scripts/validate_write.py Normal file
View File

@ -0,0 +1,282 @@
#!/usr/bin/env python3
"""
Pre-write validation hook for guardrail enforcement.
Validates that file writes are allowed based on:
1. Current workflow phase
2. Manifest-defined allowed paths
3. Always-allowed system paths
Exit codes:
0 = Write allowed
1 = Write blocked (with error message)
"""
import argparse
import json
import os
import sys
from pathlib import Path
# Always allowed paths (relative to project root)
ALWAYS_ALLOWED_PATTERNS = [
"project_manifest.json",
".workflow/",
".claude/",
"skills/",
"CLAUDE.md",
"package.json",
"package-lock.json",
"tsconfig.json",
".gitignore",
".env.local",
".env.example",
"docs/", # Documentation generation (/eureka:index, /eureka:landing)
"claudedocs/", # Claude-specific documentation
"public/", # Public assets (landing pages, images)
]
def load_manifest(manifest_path: str) -> dict | None:
"""Load manifest if it exists."""
if not os.path.exists(manifest_path):
return None
try:
with open(manifest_path) as f:
return json.load(f)
except (json.JSONDecodeError, IOError):
return None
def normalize_path(file_path: str, project_dir: str) -> str:
"""Normalize file path to relative path from project root."""
try:
abs_path = Path(file_path).resolve()
proj_path = Path(project_dir).resolve()
# Make relative if under project
if str(abs_path).startswith(str(proj_path)):
return str(abs_path.relative_to(proj_path))
return str(abs_path)
except (ValueError, OSError):
return file_path
def is_always_allowed(rel_path: str) -> bool:
"""Check if path is in always-allowed list."""
for pattern in ALWAYS_ALLOWED_PATTERNS:
if pattern.endswith('/'):
# Directory pattern
if rel_path.startswith(pattern) or rel_path == pattern.rstrip('/'):
return True
else:
# Exact file match
if rel_path == pattern:
return True
return False
def get_allowed_paths_from_manifest(manifest: dict) -> set:
"""Extract all allowed file paths from manifest entities."""
allowed = set()
entities = manifest.get("entities", {})
entity_types = ["pages", "components", "api_endpoints", "database_tables", "services", "utils", "hooks", "types"]
for entity_type in entity_types:
for entity in entities.get(entity_type, []):
status = entity.get("status", "")
# Allow APPROVED, IMPLEMENTED, or PENDING (for design phase updates)
if status in ["APPROVED", "IMPLEMENTED", "PENDING", "IN_PROGRESS"]:
if "file_path" in entity:
allowed.add(entity["file_path"])
# Also check for multiple file paths
if "file_paths" in entity:
for fp in entity.get("file_paths", []):
allowed.add(fp)
return allowed
def get_allowed_paths_from_tasks(project_dir: str) -> set:
"""Extract allowed file paths from task files in active workflow version."""
allowed = set()
# Try to import yaml
try:
import yaml
has_yaml = True
except ImportError:
has_yaml = False
# Find active version
current_path = Path(project_dir) / ".workflow" / "current.yml"
if not current_path.exists():
return allowed
try:
with open(current_path) as f:
content = f.read()
if has_yaml:
current = yaml.safe_load(content) or {}
else:
# Simple fallback parser
current = {}
for line in content.split('\n'):
if ':' in line and not line.startswith(' '):
key, _, value = line.partition(':')
current[key.strip()] = value.strip()
active_version = current.get('active_version')
if not active_version:
return allowed
# Read task files
tasks_dir = Path(project_dir) / ".workflow" / "versions" / active_version / "tasks"
if not tasks_dir.exists():
return allowed
for task_file in tasks_dir.glob("*.yml"):
try:
with open(task_file) as f:
task_content = f.read()
if has_yaml:
task = yaml.safe_load(task_content) or {}
file_paths = task.get('file_paths', [])
for fp in file_paths:
allowed.add(fp)
else:
# Simple extraction for file_paths
in_file_paths = False
for line in task_content.split('\n'):
if line.strip().startswith('file_paths:'):
in_file_paths = True
continue
if in_file_paths:
if line.strip().startswith('- '):
fp = line.strip()[2:].strip()
allowed.add(fp)
elif not line.startswith(' '):
in_file_paths = False
except (IOError, Exception):
continue
except (IOError, Exception):
pass
return allowed
def validate_write(file_path: str, manifest_path: str) -> tuple[bool, str]:
"""
Validate if a write operation is allowed.
Returns:
(allowed: bool, message: str)
"""
project_dir = os.path.dirname(manifest_path) or os.getcwd()
rel_path = normalize_path(file_path, project_dir)
# Check always-allowed paths first
if is_always_allowed(rel_path):
return True, f"✓ GUARDRAIL: Always-allowed path: {rel_path}"
# Load manifest
manifest = load_manifest(manifest_path)
# If no manifest exists, guardrails not active
if manifest is None:
return True, "✓ GUARDRAIL: No manifest found, allowing write"
# Get current phase
phase = manifest.get("state", {}).get("current_phase", "UNKNOWN")
# Collect all allowed paths
allowed_from_manifest = get_allowed_paths_from_manifest(manifest)
allowed_from_tasks = get_allowed_paths_from_tasks(project_dir)
all_allowed = allowed_from_manifest | allowed_from_tasks
# Check if file is in allowed paths
if rel_path in all_allowed:
return True, f"✓ GUARDRAIL: Allowed in manifest/tasks: {rel_path}"
# Also check with leading ./ removed
clean_path = rel_path.lstrip('./')
if clean_path in all_allowed:
return True, f"✓ GUARDRAIL: Allowed in manifest/tasks: {clean_path}"
# Check if any allowed path matches (handle path variations)
for allowed in all_allowed:
allowed_clean = allowed.lstrip('./')
if clean_path == allowed_clean:
return True, f"✓ GUARDRAIL: Allowed (path match): {rel_path}"
# Extract suggested feature from file path
name = Path(rel_path).stem
suggested_feature = f"update {name}"
# Not allowed - generate helpful error message with actionable instructions
error_msg = f"""
⛔ GUARDRAIL VIOLATION: Unauthorized file write
File: {rel_path}
Phase: {phase}
This file is not in the approved manifest or task files.
Allowed paths from manifest: {len(allowed_from_manifest)}
Allowed paths from tasks: {len(allowed_from_tasks)}
╔══════════════════════════════════════════════════════════════════╗
║ 👉 REQUIRED ACTION: Start a workflow to modify this file ║
║ ║
║ Run this command: ║
║ /workflow:spawn {suggested_feature} ║
║ ║
║ This will: ║
║ 1. Design what changes are needed ║
║ 2. Add this file to approved paths ║
║ 3. Get approval, then implement ║
╚══════════════════════════════════════════════════════════════════╝
Alternative: If workflow exists, add this file to:
- project_manifest.json (entities.*.file_path)
- .workflow/versions/*/tasks/*.yml (file_paths list)
"""
return False, error_msg
def main():
parser = argparse.ArgumentParser(description="Validate write operation against guardrails")
parser.add_argument("--manifest", required=True, help="Path to project_manifest.json")
parser.add_argument("--file", help="File path being written")
args = parser.parse_args()
# Get file path from argument or environment
file_path = args.file or os.environ.get('TOOL_INPUT_FILE_PATH', '')
if not file_path:
# Try reading from stdin
if not sys.stdin.isatty():
file_path = sys.stdin.read().strip()
if not file_path:
print("✓ GUARDRAIL: No file path provided, allowing (hook misconfiguration?)")
return 0
allowed, message = validate_write(file_path, args.manifest)
if allowed:
print(message)
return 0
else:
print(message, file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())

237
skills/guardrail-orchestrator/scripts/verify_async.py Normal file
View File

@ -0,0 +1,237 @@
#!/usr/bin/env python3
"""
Static analysis for async/await issues in TypeScript/JavaScript.
Catches common mistakes:
- fetch() without await
- .json() without await
- Async function calls without await
- Floating promises (promise not handled)
"""
import argparse
import json
import os
import re
import sys
from pathlib import Path
from typing import Dict, List, Tuple
# ============================================================================
# Async Pattern Detection
# ============================================================================
ASYNC_ISSUES = [
# fetch without await - but allow .then() chains
{
"pattern": r"(?<!await\s)(?<!return\s)fetch\s*\([^)]*\)(?!\s*\.then)(?!\s*\))",
"severity": "HIGH",
"message": "fetch() without await or .then()",
"fix": "Add 'await' before fetch() or use .then().catch()"
},
# .json() without await
{
"pattern": r"(?<!await\s)\.json\s*\(\s*\)(?!\s*\.then)",
"severity": "HIGH",
"message": ".json() without await",
"fix": "Add 'await' before .json() call"
},
# .text() without await
{
"pattern": r"(?<!await\s)\.text\s*\(\s*\)(?!\s*\.then)",
"severity": "MEDIUM",
"message": ".text() without await",
"fix": "Add 'await' before .text() call"
},
# axios/fetch response access without await
{
"pattern": r"(?<!await\s)(axios\.(get|post|put|delete|patch))\s*\([^)]*\)\.data",
"severity": "HIGH",
"message": "Accessing .data on unawaited axios call",
"fix": "Add 'await' or use (await axios.get(...)).data"
},
# Promise.all without await
{
"pattern": r"(?<!await\s)(?<!return\s)Promise\.(all|allSettled|race|any)\s*\(",
"severity": "HIGH",
"message": "Promise.all/race without await",
"fix": "Add 'await' before Promise.all()"
},
# Async function call patterns (common API functions)
{
"pattern": r"(?<!await\s)(?<!return\s)(createUser|updateUser|deleteUser|getUser|saveData|loadData|fetchData|submitForm|handleSubmit)\s*\([^)]*\)\s*;",
"severity": "MEDIUM",
"message": "Async function call may need await",
"fix": "Check if this function is async and add 'await' if needed"
},
# setState with async value without await
{
"pattern": r"set\w+\s*\(\s*(?:await\s+)?fetch\s*\(",
"severity": "HIGH",
"message": "Setting state with fetch result - ensure await is used",
"fix": "Use: const data = await fetch(...); setData(data)"
},
# useEffect with async but no await
{
"pattern": r"useEffect\s*\(\s*\(\s*\)\s*=>\s*\{[^}]*fetch\s*\([^}]*\}\s*,",
"severity": "MEDIUM",
"message": "useEffect with fetch - check async handling",
"fix": "Create inner async function: useEffect(() => { const load = async () => {...}; load(); }, [])"
},
]
# Files/patterns to skip
SKIP_PATTERNS = [
r"node_modules",
r"\.next",
r"dist",
r"build",
r"\.test\.",
r"\.spec\.",
r"__tests__",
r"__mocks__",
]
def should_skip_file(file_path: str) -> bool:
"""Check if file should be skipped."""
for pattern in SKIP_PATTERNS:
if re.search(pattern, file_path):
return True
return False
def analyze_file(file_path: Path) -> List[Dict]:
"""Analyze a single file for async issues."""
issues = []
try:
content = file_path.read_text(encoding='utf-8')
except Exception:
return issues
lines = content.split('\n')
for line_num, line in enumerate(lines, 1):
# Skip comments
stripped = line.strip()
if stripped.startswith('//') or stripped.startswith('*'):
continue
for rule in ASYNC_ISSUES:
if re.search(rule["pattern"], line):
# Additional context check - skip if line has .then or .catch nearby
context = '\n'.join(lines[max(0, line_num-2):min(len(lines), line_num+2)])
if '.then(' in context and '.catch(' in context:
continue
issues.append({
"file": str(file_path),
"line": line_num,
"severity": rule["severity"],
"message": rule["message"],
"fix": rule["fix"],
"code": line.strip()[:80]
})
return issues
def analyze_project(root_dir: str = ".") -> List[Dict]:
"""Analyze all TypeScript/JavaScript files in project."""
all_issues = []
extensions = [".ts", ".tsx", ".js", ".jsx"]
root = Path(root_dir)
for ext in extensions:
for file_path in root.rglob(f"*{ext}"):
if should_skip_file(str(file_path)):
continue
issues = analyze_file(file_path)
all_issues.extend(issues)
return all_issues
# ============================================================================
# Output Formatting
# ============================================================================
def format_text(issues: List[Dict]) -> str:
"""Format issues as readable text."""
if not issues:
return "\n✅ No async/await issues found.\n"
lines = []
lines.append("")
lines.append("╔" + "═" * 70 + "╗")
lines.append("║" + " ASYNC/AWAIT VERIFICATION".ljust(70) + "║")
lines.append("╠" + "═" * 70 + "╣")
high = [i for i in issues if i["severity"] == "HIGH"]
medium = [i for i in issues if i["severity"] == "MEDIUM"]
lines.append("║" + f" 🔴 High: {len(high)} issues".ljust(70) + "║")
lines.append("║" + f" 🟡 Medium: {len(medium)} issues".ljust(70) + "║")
if high:
lines.append("╠" + "═" * 70 + "╣")
lines.append("║" + " 🔴 HIGH SEVERITY".ljust(70) + "║")
for issue in high:
loc = f"{issue['file']}:{issue['line']}"
lines.append("║" + f" {loc}".ljust(70) + "║")
lines.append("║" + f" ❌ {issue['message']}".ljust(70) + "║")
lines.append("║" + f" 💡 {issue['fix']}".ljust(70) + "║")
code = issue['code'][:55]
lines.append("║" + f" 📝 {code}".ljust(70) + "║")
if medium:
lines.append("╠" + "═" * 70 + "╣")
lines.append("║" + " 🟡 MEDIUM SEVERITY".ljust(70) + "║")
for issue in medium[:5]: # Limit display
loc = f"{issue['file']}:{issue['line']}"
lines.append("║" + f" {loc}".ljust(70) + "║")
lines.append("║" + f" ⚠️ {issue['message']}".ljust(70) + "║")
lines.append("╚" + "═" * 70 + "╝")
return "\n".join(lines)
def main():
parser = argparse.ArgumentParser(description="Check for async/await issues")
parser.add_argument("--json", action="store_true", help="Output as JSON")
parser.add_argument("--path", default=".", help="Project path to analyze")
parser.add_argument("--strict", action="store_true", help="Fail on any issue")
args = parser.parse_args()
print("Scanning for async/await issues...")
issues = analyze_project(args.path)
if args.json:
print(json.dumps({
"issues": issues,
"summary": {
"high": len([i for i in issues if i["severity"] == "HIGH"]),
"medium": len([i for i in issues if i["severity"] == "MEDIUM"]),
"total": len(issues)
}
}, indent=2))
else:
print(format_text(issues))
# Exit codes
high_count = len([i for i in issues if i["severity"] == "HIGH"])
if high_count > 0:
sys.exit(1) # High severity issues found
elif args.strict and issues:
sys.exit(1) # Any issues in strict mode
else:
sys.exit(0)
if __name__ == "__main__":
main()

376
skills/guardrail-orchestrator/scripts/verify_implementation.py Normal file
View File

@ -0,0 +1,376 @@
#!/usr/bin/env python3
"""Verify implementation matches manifest specifications."""
import argparse
import json
import os
import re
import sys
from dataclasses import dataclass
from typing import Optional
@dataclass
class VerificationResult:
entity_id: str
entity_type: str
file_path: str
exists: bool
issues: list[str]
warnings: list[str]
def load_manifest(manifest_path: str) -> dict:
"""Load manifest from file."""
with open(manifest_path) as f:
return json.load(f)
def check_file_exists(project_root: str, file_path: str) -> bool:
"""Check if implementation file exists."""
full_path = os.path.join(project_root, file_path)
return os.path.exists(full_path)
def read_file_content(project_root: str, file_path: str) -> Optional[str]:
"""Read file content if it exists."""
full_path = os.path.join(project_root, file_path)
if not os.path.exists(full_path):
return None
with open(full_path, 'r') as f:
return f.read()
def verify_component(project_root: str, component: dict) -> VerificationResult:
"""Verify a component implementation matches manifest."""
issues = []
warnings = []
file_path = component.get("file_path", "")
exists = check_file_exists(project_root, file_path)
if not exists:
issues.append(f"File not found: {file_path}")
return VerificationResult(
entity_id=component.get("id", "unknown"),
entity_type="component",
file_path=file_path,
exists=False,
issues=issues,
warnings=warnings
)
content = read_file_content(project_root, file_path)
if not content:
issues.append("Could not read file content")
return VerificationResult(
entity_id=component.get("id", "unknown"),
entity_type="component",
file_path=file_path,
exists=True,
issues=issues,
warnings=warnings
)
# Check component name exists
name = component.get("name", "")
if name:
# Check for function/const declaration or export
patterns = [
rf"export\s+(const|function)\s+{name}",
rf"(const|function)\s+{name}",
rf"export\s+\{{\s*{name}\s*\}}",
]
found = any(re.search(p, content) for p in patterns)
if not found:
issues.append(f"Component '{name}' not found in file")
# Check props interface
props = component.get("props", {})
if props:
# Check if props interface exists
interface_pattern = rf"interface\s+{name}Props"
if not re.search(interface_pattern, content):
warnings.append(f"Props interface '{name}Props' not found")
# Check each prop exists in the file
for prop_name, prop_spec in props.items():
if prop_name not in content:
warnings.append(f"Prop '{prop_name}' may not be implemented")
return VerificationResult(
entity_id=component.get("id", "unknown"),
entity_type="component",
file_path=file_path,
exists=True,
issues=issues,
warnings=warnings
)
def verify_page(project_root: str, page: dict) -> VerificationResult:
"""Verify a page implementation matches manifest."""
issues = []
warnings = []
file_path = page.get("file_path", "")
exists = check_file_exists(project_root, file_path)
if not exists:
issues.append(f"File not found: {file_path}")
return VerificationResult(
entity_id=page.get("id", "unknown"),
entity_type="page",
file_path=file_path,
exists=False,
issues=issues,
warnings=warnings
)
content = read_file_content(project_root, file_path)
if not content:
issues.append("Could not read file content")
return VerificationResult(
entity_id=page.get("id", "unknown"),
entity_type="page",
file_path=file_path,
exists=True,
issues=issues,
warnings=warnings
)
# Check for default export (Next.js page requirement)
if "export default" not in content:
issues.append("Missing 'export default' (required for Next.js pages)")
# Check component dependencies
components = page.get("components", [])
for comp_id in components:
# Extract component name from ID (e.g., comp_header -> Header)
comp_name = comp_id.replace("comp_", "").title().replace("_", "")
if comp_name not in content:
warnings.append(f"Component '{comp_name}' (from {comp_id}) may not be used")
return VerificationResult(
entity_id=page.get("id", "unknown"),
entity_type="page",
file_path=file_path,
exists=True,
issues=issues,
warnings=warnings
)
def verify_api_endpoint(project_root: str, endpoint: dict) -> VerificationResult:
"""Verify an API endpoint implementation matches manifest."""
issues = []
warnings = []
file_path = endpoint.get("file_path", "")
exists = check_file_exists(project_root, file_path)
if not exists:
issues.append(f"File not found: {file_path}")
return VerificationResult(
entity_id=endpoint.get("id", "unknown"),
entity_type="api_endpoint",
file_path=file_path,
exists=False,
issues=issues,
warnings=warnings
)
content = read_file_content(project_root, file_path)
if not content:
issues.append("Could not read file content")
return VerificationResult(
entity_id=endpoint.get("id", "unknown"),
entity_type="api_endpoint",
file_path=file_path,
exists=True,
issues=issues,
warnings=warnings
)
# Check HTTP method handler exists
method = endpoint.get("method", "").upper()
method_patterns = [
rf"export\s+async\s+function\s+{method}\s*\(",
rf"export\s+function\s+{method}\s*\(",
rf"export\s+const\s+{method}\s*=",
]
found = any(re.search(p, content) for p in method_patterns)
if not found:
issues.append(f"HTTP method handler '{method}' not found")
# Check request body params if defined
request = endpoint.get("request", {})
if request.get("body"):
for param in request["body"].keys():
if param not in content:
warnings.append(f"Request param '{param}' may not be handled")
return VerificationResult(
entity_id=endpoint.get("id", "unknown"),
entity_type="api_endpoint",
file_path=file_path,
exists=True,
issues=issues,
warnings=warnings
)
def verify_database_table(project_root: str, table: dict) -> VerificationResult:
"""Verify a database table implementation matches manifest."""
issues = []
warnings = []
file_path = table.get("file_path", "")
exists = check_file_exists(project_root, file_path)
if not exists:
issues.append(f"File not found: {file_path}")
return VerificationResult(
entity_id=table.get("id", "unknown"),
entity_type="database_table",
file_path=file_path,
exists=False,
issues=issues,
warnings=warnings
)
content = read_file_content(project_root, file_path)
if not content:
issues.append("Could not read file content")
return VerificationResult(
entity_id=table.get("id", "unknown"),
entity_type="database_table",
file_path=file_path,
exists=True,
issues=issues,
warnings=warnings
)
# Check columns/fields are defined
columns = table.get("columns", {})
for col_name in columns.keys():
if col_name not in content:
warnings.append(f"Column '{col_name}' may not be defined")
# Check for CRUD operations
crud_ops = ["create", "get", "update", "delete", "find", "all"]
found_ops = [op for op in crud_ops if op.lower() in content.lower()]
if len(found_ops) < 2:
warnings.append("May be missing CRUD operations")
return VerificationResult(
entity_id=table.get("id", "unknown"),
entity_type="database_table",
file_path=file_path,
exists=True,
issues=issues,
warnings=warnings
)
def print_result(result: VerificationResult, verbose: bool = False):
"""Print verification result."""
status = "✅" if result.exists and not result.issues else "❌"
print(f"{status} [{result.entity_type}] {result.entity_id}")
print(f" File: {result.file_path}")
if result.issues:
for issue in result.issues:
print(f" ❌ ERROR: {issue}")
if verbose and result.warnings:
for warning in result.warnings:
print(f" ⚠️ WARN: {warning}")
def main():
parser = argparse.ArgumentParser(description="Verify implementation against manifest")
parser.add_argument("--manifest", default="project_manifest.json", help="Path to manifest")
parser.add_argument("--project-root", default=".", help="Project root directory")
parser.add_argument("--verbose", "-v", action="store_true", help="Show warnings")
parser.add_argument("--json", action="store_true", help="Output as JSON")
args = parser.parse_args()
manifest_path = args.manifest
if not os.path.isabs(manifest_path):
manifest_path = os.path.join(args.project_root, manifest_path)
if not os.path.exists(manifest_path):
print(f"Error: Manifest not found at {manifest_path}")
return 1
manifest = load_manifest(manifest_path)
entities = manifest.get("entities", {})
results = []
# Verify components
for component in entities.get("components", []):
result = verify_component(args.project_root, component)
results.append(result)
# Verify pages
for page in entities.get("pages", []):
result = verify_page(args.project_root, page)
results.append(result)
# Verify API endpoints
for endpoint in entities.get("api_endpoints", []):
result = verify_api_endpoint(args.project_root, endpoint)
results.append(result)
# Verify database tables
for table in entities.get("database_tables", []):
result = verify_database_table(args.project_root, table)
results.append(result)
# Output results
if args.json:
output = {
"total": len(results),
"passed": sum(1 for r in results if r.exists and not r.issues),
"failed": sum(1 for r in results if not r.exists or r.issues),
"results": [
{
"entity_id": r.entity_id,
"entity_type": r.entity_type,
"file_path": r.file_path,
"exists": r.exists,
"issues": r.issues,
"warnings": r.warnings,
}
for r in results
]
}
print(json.dumps(output, indent=2))
else:
print("\n" + "=" * 60)
print("IMPLEMENTATION VERIFICATION REPORT")
print("=" * 60 + "\n")
for result in results:
print_result(result, args.verbose)
print()
# Summary
passed = sum(1 for r in results if r.exists and not r.issues)
failed = sum(1 for r in results if not r.exists or r.issues)
warnings = sum(len(r.warnings) for r in results)
print("=" * 60)
print(f"SUMMARY: {passed}/{len(results)} passed, {failed} failed, {warnings} warnings")
print("=" * 60)
if failed > 0:
return 1
return 0
if __name__ == "__main__":
exit(main())

986
skills/guardrail-orchestrator/scripts/version_manager.py Executable file
View File

@ -0,0 +1,986 @@
#!/usr/bin/env python3
"""
Workflow versioning system with task session tracking.
Links workflow sessions with task sessions and individual operations.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import os
import shutil
import sys
from datetime import datetime
from pathlib import Path
from typing import Optional
# Try to import yaml
try:
import yaml
HAS_YAML = True
except ImportError:
HAS_YAML = False
# ============================================================================
# YAML/JSON Helpers
# ============================================================================
def load_yaml(filepath: str) -> dict:
"""Load YAML file."""
if not os.path.exists(filepath):
return {}
with open(filepath, 'r') as f:
content = f.read()
if not content.strip():
return {}
if HAS_YAML:
return yaml.safe_load(content) or {}
# Simple YAML fallback parser for basic key: value structures
return parse_simple_yaml(content)
def parse_simple_yaml(content: str) -> dict:
"""Parse simple YAML without PyYAML dependency."""
result = {}
current_key = None
current_list = None
for line in content.split('\n'):
stripped = line.strip()
# Skip empty lines and comments
if not stripped or stripped.startswith('#'):
continue
# Handle list items
if stripped.startswith('- '):
if current_list is not None:
value = stripped[2:].strip()
# Handle quoted strings
if (value.startswith('"') and value.endswith('"')) or \
(value.startswith("'") and value.endswith("'")):
value = value[1:-1]
current_list.append(value)
continue
# Handle key: value
if ':' in stripped:
key, _, value = stripped.partition(':')
key = key.strip()
value = value.strip()
# Check if this is a list start
if value == '' or value == '[]':
current_key = key
current_list = []
result[key] = current_list
elif value == '{}':
result[key] = {}
current_list = None
elif value == 'null' or value == '~':
result[key] = None
current_list = None
elif value == 'true':
result[key] = True
current_list = None
elif value == 'false':
result[key] = False
current_list = None
elif value.isdigit():
result[key] = int(value)
current_list = None
else:
# Handle quoted strings
if (value.startswith('"') and value.endswith('"')) or \
(value.startswith("'") and value.endswith("'")):
value = value[1:-1]
result[key] = value
current_list = None
return result
def save_yaml(filepath: str, data: dict):
"""Save data to YAML file."""
os.makedirs(os.path.dirname(filepath), exist_ok=True)
if HAS_YAML:
with open(filepath, 'w') as f:
yaml.dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
else:
with open(filepath, 'w') as f:
json.dump(data, f, indent=2)
def file_hash(filepath: str) -> str:
"""Get SHA256 hash of file content."""
if not os.path.exists(filepath):
return None
with open(filepath, 'rb') as f:
return hashlib.sha256(f.read()).hexdigest()[:16]
# ============================================================================
# Path Helpers
# ============================================================================
def get_workflow_dir() -> Path:
return Path('.workflow')
def get_versions_dir() -> Path:
return get_workflow_dir() / 'versions'
def get_index_path() -> Path:
return get_workflow_dir() / 'index.yml'
def get_operations_log_path() -> Path:
return get_workflow_dir() / 'operations.log'
def get_version_dir(version: str) -> Path:
return get_versions_dir() / version
def get_current_state_path() -> Path:
return get_workflow_dir() / 'current.yml'
def get_version_tasks_dir(version: str) -> Path:
"""Get the tasks directory for a specific version."""
return get_version_dir(version) / 'tasks'
def get_current_tasks_dir() -> Optional[Path]:
"""Get the tasks directory for the currently active version."""
current_path = get_current_state_path()
if not current_path.exists():
return None
current = load_yaml(str(current_path))
version = current.get('active_version')
if not version:
return None
tasks_dir = get_version_tasks_dir(version)
tasks_dir.mkdir(parents=True, exist_ok=True)
return tasks_dir
# ============================================================================
# Version Index Management
# ============================================================================
def load_index() -> dict:
"""Load or create version index."""
index_path = get_index_path()
if index_path.exists():
return load_yaml(str(index_path))
return {
'versions': [],
'latest_version': None,
'total_versions': 0
}
def save_index(index: dict):
"""Save version index."""
save_yaml(str(get_index_path()), index)
def get_next_version() -> str:
"""Get next version number."""
index = load_index()
return f"v{index['total_versions'] + 1:03d}"
# ============================================================================
# Workflow Session Management
# ============================================================================
def create_workflow_session(feature: str, parent_version: str = None) -> dict:
"""Create a new workflow session with version tracking."""
now = datetime.now()
version = get_next_version()
session_id = f"workflow_{now.strftime('%Y%m%d_%H%M%S')}"
# Create version directory and tasks subdirectory
version_dir = get_version_dir(version)
version_dir.mkdir(parents=True, exist_ok=True)
(version_dir / 'tasks').mkdir(exist_ok=True)
# Create workflow session
session = {
'version': version,
'feature': feature,
'session_id': session_id,
'parent_version': parent_version,
'status': 'pending',
'started_at': now.isoformat(),
'completed_at': None,
'current_phase': 'INITIALIZING',
'approvals': {
'design': {
'status': 'pending',
'approved_by': None,
'approved_at': None,
'rejection_reason': None
},
'implementation': {
'status': 'pending',
'approved_by': None,
'approved_at': None,
'rejection_reason': None
}
},
'task_sessions': [],
'summary': {
'total_tasks': 0,
'tasks_completed': 0,
'entities_created': 0,
'entities_updated': 0,
'entities_deleted': 0,
'files_created': 0,
'files_updated': 0,
'files_deleted': 0
}
}
# Save session to version directory
save_yaml(str(version_dir / 'session.yml'), session)
# Update current state pointer
get_workflow_dir().mkdir(exist_ok=True)
save_yaml(str(get_current_state_path()), {
'active_version': version,
'session_id': session_id
})
# Update index
index = load_index()
index['versions'].append({
'version': version,
'feature': feature,
'status': 'pending',
'started_at': now.isoformat(),
'completed_at': None,
'tasks_count': 0,
'operations_count': 0
})
index['latest_version'] = version
index['total_versions'] += 1
save_index(index)
# Take snapshot of current state (manifest, tasks)
take_snapshot(version, 'before')
return session
def load_current_session() -> Optional[dict]:
"""Load the current active workflow session."""
current_path = get_current_state_path()
if not current_path.exists():
return None
current = load_yaml(str(current_path))
version = current.get('active_version')
if not version:
return None
session_path = get_version_dir(version) / 'session.yml'
if not session_path.exists():
return None
return load_yaml(str(session_path))
def save_current_session(session: dict):
"""Save the current workflow session."""
version = session['version']
session['updated_at'] = datetime.now().isoformat()
save_yaml(str(get_version_dir(version) / 'session.yml'), session)
# Update index
index = load_index()
for v in index['versions']:
if v['version'] == version:
v['status'] = session['status']
v['tasks_count'] = session['summary']['total_tasks']
break
save_index(index)
def complete_workflow_session(session: dict):
"""Mark workflow session as completed."""
now = datetime.now()
session['status'] = 'completed'
session['completed_at'] = now.isoformat()
save_current_session(session)
# Take final snapshot
take_snapshot(session['version'], 'after')
# Update index
index = load_index()
for v in index['versions']:
if v['version'] == session['version']:
v['status'] = 'completed'
v['completed_at'] = now.isoformat()
break
save_index(index)
# Clear current pointer
current_path = get_current_state_path()
if current_path.exists():
current_path.unlink()
# ============================================================================
# Task Session Management
# ============================================================================
def create_task_session(workflow_session: dict, task_id: str, task_type: str, agent: str) -> dict:
"""Create a new task session with full directory structure."""
now = datetime.now()
session_id = f"tasksession_{task_id}_{now.strftime('%Y%m%d_%H%M%S')}"
# Create task session DIRECTORY (not file)
version_dir = get_version_dir(workflow_session['version'])
task_session_dir = version_dir / 'task_sessions' / task_id
task_session_dir.mkdir(parents=True, exist_ok=True)
task_session = {
'session_id': session_id,
'workflow_version': workflow_session['version'],
'task_id': task_id,
'task_type': task_type,
'agent': agent,
'started_at': now.isoformat(),
'completed_at': None,
'duration_ms': None,
'status': 'in_progress',
'operations': [],
'review_session': None,
'errors': [],
'attempt_number': 1,
'previous_attempts': []
}
# Save session.yml
save_yaml(str(task_session_dir / 'session.yml'), task_session)
# Snapshot task definition
snapshot_task_definition(task_id, task_session_dir)
# Initialize operations.log
init_operations_log(task_session_dir, task_id, now)
# Link to workflow
workflow_session['task_sessions'].append(session_id)
workflow_session['summary']['total_tasks'] += 1
save_current_session(workflow_session)
return task_session
def snapshot_task_definition(task_id: str, task_session_dir: Path):
"""Snapshot the task definition at execution time."""
task_file = Path('tasks') / f'{task_id}.yml'
if task_file.exists():
task_data = load_yaml(str(task_file))
task_data['snapshotted_at'] = datetime.now().isoformat()
task_data['source_path'] = str(task_file)
task_data['status_at_snapshot'] = task_data.get('status', 'unknown')
save_yaml(str(task_session_dir / 'task.yml'), task_data)
def init_operations_log(task_session_dir: Path, task_id: str, start_time: datetime):
"""Initialize the operations log file."""
log_path = task_session_dir / 'operations.log'
header = f"# Operations Log for {task_id}\n"
header += f"# Started: {start_time.isoformat()}\n"
header += "# Format: [timestamp] OPERATION target_type: target_id (path)\n"
header += "=" * 70 + "\n\n"
with open(log_path, 'w') as f:
f.write(header)
def log_to_task_operations_log(task_session: dict, operation: dict):
"""Append operation to task-specific operations log."""
version = task_session['workflow_version']
task_id = task_session['task_id']
log_path = get_version_dir(version) / 'task_sessions' / task_id / 'operations.log'
if not log_path.exists():
return
entry = (
f"[{operation['performed_at']}] "
f"{operation['type']} {operation['target_type']}: {operation['target_id']}"
)
if operation.get('target_path'):
entry += f" ({operation['target_path']})"
entry += f"\n Summary: {operation['changes']['diff_summary']}\n"
with open(log_path, 'a') as f:
f.write(entry + "\n")
def load_task_session(version: str, task_id: str) -> Optional[dict]:
"""Load a task session from directory or flat file (backwards compatible)."""
# Try new directory structure first
session_dir = get_version_dir(version) / 'task_sessions' / task_id
session_path = session_dir / 'session.yml'
if session_path.exists():
return load_yaml(str(session_path))
# Fallback to old flat file structure
old_path = get_version_dir(version) / 'task_sessions' / f'{task_id}.yml'
if old_path.exists():
return load_yaml(str(old_path))
return None
def save_task_session(task_session: dict):
"""Save a task session to directory structure."""
version = task_session['workflow_version']
task_id = task_session['task_id']
session_dir = get_version_dir(version) / 'task_sessions' / task_id
session_dir.mkdir(parents=True, exist_ok=True)
save_yaml(str(session_dir / 'session.yml'), task_session)
def complete_task_session(task_session: dict, status: str = 'completed'):
"""Mark task session as completed."""
now = datetime.now()
started = datetime.fromisoformat(task_session['started_at'])
task_session['completed_at'] = now.isoformat()
task_session['duration_ms'] = int((now - started).total_seconds() * 1000)
task_session['status'] = status
save_task_session(task_session)
# Update workflow summary
session = load_current_session()
if session and status == 'completed':
session['summary']['tasks_completed'] += 1
save_current_session(session)
# ============================================================================
# Operation Logging
# ============================================================================
def log_operation(
task_session: dict,
op_type: str, # CREATE, UPDATE, DELETE, RENAME, MOVE
target_type: str, # file, entity, task, manifest
target_id: str,
target_path: str = None,
before_state: str = None,
after_state: str = None,
diff_summary: str = None,
rollback_data: dict = None
) -> dict:
"""Log an operation within a task session."""
now = datetime.now()
seq = len(task_session['operations']) + 1
op_id = f"op_{now.strftime('%Y%m%d_%H%M%S')}_{seq:03d}"
operation = {
'id': op_id,
'type': op_type,
'target_type': target_type,
'target_id': target_id,
'target_path': target_path,
'changes': {
'before': before_state,
'after': after_state,
'diff_summary': diff_summary or f"{op_type} {target_type}: {target_id}"
},
'performed_at': now.isoformat(),
'reversible': rollback_data is not None,
'rollback_data': rollback_data
}
task_session['operations'].append(operation)
save_task_session(task_session)
# Update workflow summary
session = load_current_session()
if session:
if op_type == 'CREATE':
if target_type == 'file':
session['summary']['files_created'] += 1
elif target_type == 'entity':
session['summary']['entities_created'] += 1
elif op_type == 'UPDATE':
if target_type == 'file':
session['summary']['files_updated'] += 1
elif target_type == 'entity':
session['summary']['entities_updated'] += 1
elif op_type == 'DELETE':
if target_type == 'file':
session['summary']['files_deleted'] += 1
elif target_type == 'entity':
session['summary']['entities_deleted'] += 1
save_current_session(session)
# Also log to operations log
log_to_file(operation, task_session)
# Also log to task-specific operations log
log_to_task_operations_log(task_session, operation)
# Update index operations count
index = load_index()
for v in index['versions']:
if v['version'] == task_session['workflow_version']:
v['operations_count'] = v.get('operations_count', 0) + 1
break
save_index(index)
return operation
def log_to_file(operation: dict, task_session: dict):
"""Append operation to global operations log."""
log_path = get_operations_log_path()
log_entry = (
f"[{operation['performed_at']}] "
f"v{task_session['workflow_version']} | "
f"{task_session['task_id']} | "
f"{operation['type']} {operation['target_type']}: {operation['target_id']}"
)
if operation['target_path']:
log_entry += f" ({operation['target_path']})"
log_entry += "\n"
with open(log_path, 'a') as f:
f.write(log_entry)
# ============================================================================
# Review Session Management
# ============================================================================
def create_review_session(task_session: dict, reviewer: str = 'reviewer') -> dict:
"""Create a review session for a task."""
now = datetime.now()
session_id = f"review_{task_session['task_id']}_{now.strftime('%Y%m%d_%H%M%S')}"
review = {
'session_id': session_id,
'task_session_id': task_session['session_id'],
'workflow_version': task_session['workflow_version'],
'reviewer': reviewer,
'started_at': now.isoformat(),
'completed_at': None,
'decision': None,
'checks': {
'file_exists': None,
'manifest_compliance': None,
'code_quality': None,
'lint': None,
'build': None,
'tests': None
},
'notes': '',
'issues_found': [],
'suggestions': []
}
task_session['review_session'] = review
save_task_session(task_session)
return review
def complete_review_session(
task_session: dict,
decision: str,
checks: dict,
notes: str = '',
issues: list = None,
suggestions: list = None
):
"""Complete a review session."""
now = datetime.now()
review = task_session['review_session']
review['completed_at'] = now.isoformat()
review['decision'] = decision
review['checks'].update(checks)
review['notes'] = notes
review['issues_found'] = issues or []
review['suggestions'] = suggestions or []
save_task_session(task_session)
# ============================================================================
# Snapshots
# ============================================================================
def take_snapshot(version: str, snapshot_type: str):
"""Take a snapshot of current state (before/after)."""
snapshot_dir = get_version_dir(version) / f'snapshot_{snapshot_type}'
snapshot_dir.mkdir(exist_ok=True)
# Snapshot manifest
if os.path.exists('project_manifest.json'):
shutil.copy('project_manifest.json', snapshot_dir / 'manifest.json')
# Snapshot tasks directory
if os.path.exists('tasks'):
tasks_snapshot = snapshot_dir / 'tasks'
if tasks_snapshot.exists():
shutil.rmtree(tasks_snapshot)
shutil.copytree('tasks', tasks_snapshot)
# ============================================================================
# History & Diff
# ============================================================================
def list_versions() -> list:
"""List all workflow versions."""
index = load_index()
return index['versions']
def get_version_details(version: str) -> Optional[dict]:
"""Get detailed info about a version."""
session_path = get_version_dir(version) / 'session.yml'
if not session_path.exists():
return None
return load_yaml(str(session_path))
def get_changelog(version: str) -> dict:
"""Generate changelog for a version."""
session = get_version_details(version)
if not session:
return None
changelog = {
'version': version,
'feature': session['feature'],
'status': session['status'],
'started_at': session['started_at'],
'completed_at': session['completed_at'],
'operations': {
'created': [],
'updated': [],
'deleted': []
},
'summary': session['summary']
}
# Collect operations from all task sessions
tasks_dir = get_version_dir(version) / 'task_sessions'
if tasks_dir.exists():
for task_file in tasks_dir.glob('*.yml'):
task = load_yaml(str(task_file))
for op in task.get('operations', []):
entry = {
'type': op['target_type'],
'id': op['target_id'],
'path': op['target_path'],
'task': task['task_id'],
'agent': task['agent']
}
if op['type'] == 'CREATE':
changelog['operations']['created'].append(entry)
elif op['type'] == 'UPDATE':
changelog['operations']['updated'].append(entry)
elif op['type'] == 'DELETE':
changelog['operations']['deleted'].append(entry)
return changelog
def diff_versions(version1: str, version2: str) -> dict:
"""Compare two versions."""
v1 = get_version_details(version1)
v2 = get_version_details(version2)
if not v1 or not v2:
return None
return {
'from_version': version1,
'to_version': version2,
'from_feature': v1['feature'],
'to_feature': v2['feature'],
'summary_diff': {
'entities_created': v2['summary']['entities_created'] - v1['summary']['entities_created'],
'entities_updated': v2['summary']['entities_updated'] - v1['summary']['entities_updated'],
'files_created': v2['summary']['files_created'] - v1['summary']['files_created'],
'files_updated': v2['summary']['files_updated'] - v1['summary']['files_updated']
}
}
# ============================================================================
# Display Functions
# ============================================================================
def show_history():
"""Display version history."""
versions = list_versions()
print()
print("╔" + "═" * 70 + "╗")
print("║" + "WORKFLOW VERSION HISTORY".center(70) + "║")
print("╠" + "═" * 70 + "╣")
if not versions:
print("║" + " No workflow versions found.".ljust(70) + "║")
else:
for v in versions:
status_icon = "✅" if v['status'] == 'completed' else "🔄" if v['status'] == 'in_progress' else "⏳"
line1 = f" {status_icon} {v['version']}: {v['feature'][:45]}"
print("║" + line1.ljust(70) + "║")
line2 = f" Started: {v['started_at'][:19]} | Tasks: {v['tasks_count']} | Ops: {v.get('operations_count', 0)}"
print("║" + line2.ljust(70) + "║")
print("║" + "─" * 70 + "║")
print("╚" + "═" * 70 + "╝")
def show_changelog(version: str):
"""Display changelog for a version."""
changelog = get_changelog(version)
if not changelog:
print(f"Version {version} not found.")
return
print()
print("╔" + "═" * 70 + "╗")
print("║" + f"CHANGELOG: {version}".center(70) + "║")
print("╠" + "═" * 70 + "╣")
print("║" + f" Feature: {changelog['feature'][:55]}".ljust(70) + "║")
print("║" + f" Status: {changelog['status']}".ljust(70) + "║")
print("╠" + "═" * 70 + "╣")
ops = changelog['operations']
print("║" + " CREATED".ljust(70) + "║")
for item in ops['created']:
print("║" + f" + [{item['type']}] {item['id']}".ljust(70) + "║")
if item['path']:
print("║" + f" {item['path']}".ljust(70) + "║")
print("║" + " UPDATED".ljust(70) + "║")
for item in ops['updated']:
print("║" + f" ~ [{item['type']}] {item['id']}".ljust(70) + "║")
print("║" + " DELETED".ljust(70) + "║")
for item in ops['deleted']:
print("║" + f" - [{item['type']}] {item['id']}".ljust(70) + "║")
print("╠" + "═" * 70 + "╣")
s = changelog['summary']
print("║" + " SUMMARY".ljust(70) + "║")
print("║" + f" Entities: +{s['entities_created']} ~{s['entities_updated']} -{s['entities_deleted']}".ljust(70) + "║")
print("║" + f" Files: +{s['files_created']} ~{s['files_updated']} -{s['files_deleted']}".ljust(70) + "║")
print("╚" + "═" * 70 + "╝")
def show_current():
"""Show current active workflow."""
session = load_current_session()
if not session:
print("No active workflow.")
print("Start one with: /workflow:spawn 'feature name'")
return
print()
print("╔" + "═" * 70 + "╗")
print("║" + "CURRENT WORKFLOW SESSION".center(70) + "║")
print("╠" + "═" * 70 + "╣")
print("║" + f" Version: {session['version']}".ljust(70) + "║")
print("║" + f" Feature: {session['feature'][:55]}".ljust(70) + "║")
print("║" + f" Phase: {session['current_phase']}".ljust(70) + "║")
print("║" + f" Status: {session['status']}".ljust(70) + "║")
print("╠" + "═" * 70 + "╣")
print("║" + " APPROVALS".ljust(70) + "║")
d = session['approvals']['design']
i = session['approvals']['implementation']
d_icon = "✅" if d['status'] == 'approved' else "❌" if d['status'] == 'rejected' else "⏳"
i_icon = "✅" if i['status'] == 'approved' else "❌" if i['status'] == 'rejected' else "⏳"
print("║" + f" {d_icon} Design: {d['status']}".ljust(70) + "║")
print("║" + f" {i_icon} Implementation: {i['status']}".ljust(70) + "║")
print("╠" + "═" * 70 + "╣")
s = session['summary']
print("║" + " PROGRESS".ljust(70) + "║")
print("║" + f" Tasks: {s['tasks_completed']}/{s['total_tasks']} completed".ljust(70) + "║")
print("║" + f" Entities: +{s['entities_created']} ~{s['entities_updated']} -{s['entities_deleted']}".ljust(70) + "║")
print("║" + f" Files: +{s['files_created']} ~{s['files_updated']} -{s['files_deleted']}".ljust(70) + "║")
print("╚" + "═" * 70 + "╝")
# ============================================================================
# CLI Interface
# ============================================================================
def main():
parser = argparse.ArgumentParser(description="Workflow versioning system")
subparsers = parser.add_subparsers(dest='command', help='Commands')
# create command
create_parser = subparsers.add_parser('create', help='Create new workflow version')
create_parser.add_argument('feature', help='Feature description')
create_parser.add_argument('--parent', help='Parent version (for fixes)')
# current command
subparsers.add_parser('current', help='Show current workflow')
# history command
subparsers.add_parser('history', help='Show version history')
# changelog command
changelog_parser = subparsers.add_parser('changelog', help='Show version changelog')
changelog_parser.add_argument('version', help='Version to show')
# diff command
diff_parser = subparsers.add_parser('diff', help='Compare two versions')
diff_parser.add_argument('version1', help='First version')
diff_parser.add_argument('version2', help='Second version')
# task-start command
task_start = subparsers.add_parser('task-start', help='Start a task session')
task_start.add_argument('task_id', help='Task ID')
task_start.add_argument('--type', default='create', help='Task type')
task_start.add_argument('--agent', required=True, help='Agent performing task')
# task-complete command
task_complete = subparsers.add_parser('task-complete', help='Complete a task session')
task_complete.add_argument('task_id', help='Task ID')
task_complete.add_argument('--status', default='completed', help='Final status')
# log-op command
log_op = subparsers.add_parser('log-op', help='Log an operation')
log_op.add_argument('task_id', help='Task ID')
log_op.add_argument('op_type', choices=['CREATE', 'UPDATE', 'DELETE'])
log_op.add_argument('target_type', choices=['file', 'entity', 'task', 'manifest'])
log_op.add_argument('target_id', help='Target ID')
log_op.add_argument('--path', help='File path if applicable')
log_op.add_argument('--summary', help='Change summary')
# complete command
subparsers.add_parser('complete', help='Complete current workflow')
# update-phase command
phase_parser = subparsers.add_parser('update-phase', help='Update workflow phase')
phase_parser.add_argument('phase', help='New phase')
# tasks-dir command
tasks_dir_parser = subparsers.add_parser('tasks-dir', help='Get tasks directory for current or specific version')
tasks_dir_parser.add_argument('--version', help='Specific version (defaults to current)')
args = parser.parse_args()
if args.command == 'create':
session = create_workflow_session(args.feature, args.parent)
print(f"Created workflow version: {session['version']}")
print(f"Feature: {args.feature}")
print(f"Session ID: {session['session_id']}")
elif args.command == 'current':
show_current()
elif args.command == 'history':
show_history()
elif args.command == 'changelog':
show_changelog(args.version)
elif args.command == 'diff':
result = diff_versions(args.version1, args.version2)
if result:
print(json.dumps(result, indent=2))
else:
print("Could not compare versions")
elif args.command == 'task-start':
session = load_current_session()
if not session:
print("Error: No active workflow")
sys.exit(1)
task = create_task_session(session, args.task_id, args.type, args.agent)
print(f"Started task session: {task['session_id']}")
elif args.command == 'task-complete':
session = load_current_session()
if not session:
print("Error: No active workflow")
sys.exit(1)
task = load_task_session(session['version'], args.task_id)
if task:
complete_task_session(task, args.status)
print(f"Completed task: {args.task_id}")
else:
print(f"Task session not found: {args.task_id}")
elif args.command == 'log-op':
session = load_current_session()
if not session:
print("Error: No active workflow")
sys.exit(1)
task = load_task_session(session['version'], args.task_id)
if task:
op = log_operation(
task,
args.op_type,
args.target_type,
args.target_id,
target_path=args.path,
diff_summary=args.summary
)
print(f"Logged operation: {op['id']}")
else:
print(f"Task session not found: {args.task_id}")
elif args.command == 'complete':
session = load_current_session()
if not session:
print("Error: No active workflow")
sys.exit(1)
complete_workflow_session(session)
print(f"Completed workflow: {session['version']}")
elif args.command == 'update-phase':
session = load_current_session()
if not session:
print("Error: No active workflow")
sys.exit(1)
session['current_phase'] = args.phase
save_current_session(session)
print(f"Updated phase to: {args.phase}")
elif args.command == 'tasks-dir':
if args.version:
# Specific version requested
tasks_dir = get_version_tasks_dir(args.version)
tasks_dir.mkdir(parents=True, exist_ok=True)
print(str(tasks_dir))
else:
# Use current version
tasks_dir = get_current_tasks_dir()
if tasks_dir:
print(str(tasks_dir))
else:
print("Error: No active workflow")
sys.exit(1)
else:
parser.print_help()
if __name__ == "__main__":
main()

343
skills/guardrail-orchestrator/scripts/visualize_design.py Normal file
View File

@ -0,0 +1,343 @@
#!/usr/bin/env python3
"""
Design visualization for guardrail workflow.
Generates ASCII art visualization of pages, components, and API endpoints
from the project manifest.
Usage:
python3 visualize_design.py --manifest project_manifest.json
"""
import argparse
import json
import os
import sys
from pathlib import Path
def load_manifest(manifest_path: str) -> dict | None:
"""Load manifest if it exists."""
if not os.path.exists(manifest_path):
return None
try:
with open(manifest_path) as f:
return json.load(f)
except (json.JSONDecodeError, IOError):
return None
def get_status_icon(status: str) -> str:
"""Get icon for entity status."""
icons = {
'PENDING': '⏳',
'APPROVED': '✅',
'IMPLEMENTED': '🟢',
'IN_PROGRESS': '🔄',
'REJECTED': '❌',
}
return icons.get(status, '○')
def visualize_page(page: dict, components: list, indent: str = "") -> list:
"""Generate ASCII visualization for a page."""
lines = []
name = page.get('name', 'Unknown')
status = page.get('status', 'PENDING')
file_path = page.get('file_path', '')
description = page.get('description', '')
icon = get_status_icon(status)
# Page header
lines.append(f"{indent}┌{'─' * 60}┐")
lines.append(f"{indent}│ {icon} PAGE: {name:<50} │")
lines.append(f"{indent}│ {' ' * 3}Path: {file_path:<48} │")
if description:
desc_short = description[:45] + '...' if len(description) > 45 else description
lines.append(f"{indent}│ {' ' * 3}Desc: {desc_short:<48} │")
lines.append(f"{indent}├{'─' * 60}┤")
# Find components used by this page
page_components = []
page_id = page.get('id', '')
for comp in components:
deps = comp.get('dependencies', [])
used_by = comp.get('used_by', [])
if page_id in deps or page_id in used_by or page.get('name', '').lower() in str(comp).lower():
page_components.append(comp)
if page_components:
lines.append(f"{indent}│ COMPONENTS: │")
for comp in page_components:
comp_name = comp.get('name', 'Unknown')
comp_status = comp.get('status', 'PENDING')
comp_icon = get_status_icon(comp_status)
lines.append(f"{indent}│ {comp_icon} {comp_name:<53} │")
else:
lines.append(f"{indent}│ (No components defined yet) │")
lines.append(f"{indent}└{'─' * 60}┘")
return lines
def visualize_component_tree(components: list) -> list:
"""Generate ASCII tree of components."""
lines = []
if not components:
return [" (No components defined)"]
lines.append("┌─────────────────────────────────────────────────────────────┐")
lines.append("│ 🧩 COMPONENTS │")
lines.append("├─────────────────────────────────────────────────────────────┤")
for i, comp in enumerate(components):
name = comp.get('name', 'Unknown')
status = comp.get('status', 'PENDING')
file_path = comp.get('file_path', '')
icon = get_status_icon(status)
is_last = i == len(components) - 1
prefix = "└──" if is_last else "├──"
lines.append(f"│ {prefix} {icon} {name:<50} │")
lines.append(f"│ {' ' if is_last else '│ '} {file_path:<50} │")
lines.append("└─────────────────────────────────────────────────────────────┘")
return lines
def visualize_api_endpoints(endpoints: list) -> list:
"""Generate ASCII visualization of API endpoints."""
lines = []
if not endpoints:
return []
lines.append("┌─────────────────────────────────────────────────────────────┐")
lines.append("│ 🔌 API ENDPOINTS │")
lines.append("├─────────────────────────────────────────────────────────────┤")
for endpoint in endpoints:
name = endpoint.get('name', 'Unknown')
method = endpoint.get('method', 'GET')
path = endpoint.get('path', endpoint.get('file_path', ''))
status = endpoint.get('status', 'PENDING')
icon = get_status_icon(status)
method_colors = {
'GET': '🟢',
'POST': '🟡',
'PUT': '🟠',
'PATCH': '🟠',
'DELETE': '🔴',
}
method_icon = method_colors.get(method.upper(), '⚪')
lines.append(f"│ {icon} {method_icon} {method.upper():<6} {name:<45} │")
lines.append(f"│ Path: {path:<47} │")
lines.append("└─────────────────────────────────────────────────────────────┘")
return lines
def visualize_page_flow(pages: list) -> list:
"""Generate ASCII flow diagram of pages."""
lines = []
if not pages:
return []
lines.append("")
lines.append("📱 PAGE FLOW DIAGRAM")
lines.append("═" * 65)
lines.append("")
# Simple flow visualization
for i, page in enumerate(pages):
name = page.get('name', 'Unknown')
status = page.get('status', 'PENDING')
icon = get_status_icon(status)
# Page box
box_width = max(len(name) + 4, 20)
lines.append(f" ┌{'─' * box_width}┐")
lines.append(f" │ {icon} {name.center(box_width - 4)} │")
lines.append(f" └{'─' * box_width}┘")
# Arrow to next page (if not last)
if i < len(pages) - 1:
lines.append(f" {'│'.center(box_width + 4)}")
lines.append(f" {'▼'.center(box_width + 4)}")
lines.append("")
return lines
def visualize_data_flow(manifest: dict) -> list:
"""Generate data flow visualization."""
lines = []
pages = manifest.get('entities', {}).get('pages', [])
components = manifest.get('entities', {}).get('components', [])
endpoints = manifest.get('entities', {}).get('api_endpoints', [])
if not any([pages, components, endpoints]):
return []
lines.append("")
lines.append("🔄 DATA FLOW ARCHITECTURE")
lines.append("═" * 65)
lines.append("")
lines.append(" ┌─────────────────────────────────────────────────────────┐")
lines.append(" │ FRONTEND │")
lines.append(" │ ┌─────────┐ ┌─────────────┐ ┌───────────────┐ │")
lines.append(" │ │ Pages │───▶│ Components │───▶│ Hooks │ │")
page_count = len(pages)
comp_count = len(components)
lines.append(f" │ │ ({page_count:^3}) │ │ ({comp_count:^3}) │ │ (state) │ │")
lines.append(" │ └─────────┘ └─────────────┘ └───────┬───────┘ │")
lines.append(" │ │ │")
lines.append(" └────────────────────────────────────────────┼───────────┘")
lines.append(" │")
lines.append(" ▼")
lines.append(" ┌─────────────────────────────────────────────────────────┐")
lines.append(" │ BACKEND │")
lines.append(" │ ┌─────────────────────────────────────────────────┐ │")
lines.append(" │ │ API Endpoints │ │")
api_count = len(endpoints)
lines.append(f" │ │ ({api_count:^3}) │ │")
lines.append(" │ └──────────────────────────┬──────────────────────┘ │")
lines.append(" │ │ │")
lines.append(" │ ▼ │")
lines.append(" │ ┌─────────────────────────────────────────────────┐ │")
lines.append(" │ │ Database │ │")
lines.append(" │ └─────────────────────────────────────────────────┘ │")
lines.append(" └─────────────────────────────────────────────────────────┘")
return lines
def generate_full_visualization(manifest: dict) -> str:
"""Generate complete design visualization."""
lines = []
project_name = manifest.get('project', {}).get('name', 'Unknown Project')
entities = manifest.get('entities', {})
pages = entities.get('pages', [])
components = entities.get('components', [])
api_endpoints = entities.get('api_endpoints', [])
# Header
lines.append("")
lines.append("╔═══════════════════════════════════════════════════════════════╗")
lines.append("║ 📐 DESIGN VISUALIZATION ║")
lines.append(f"║ Project: {project_name:<51} ║")
lines.append("╚═══════════════════════════════════════════════════════════════╝")
lines.append("")
# Summary counts
lines.append("📊 ENTITY SUMMARY")
lines.append("─" * 65)
lines.append(f" Pages: {len(pages):>3} │ Components: {len(components):>3} │ API Endpoints: {len(api_endpoints):>3}")
lines.append("")
# Page Flow
if pages:
lines.extend(visualize_page_flow(pages))
lines.append("")
# Detailed Pages with Components
if pages:
lines.append("")
lines.append("📄 PAGE DETAILS")
lines.append("═" * 65)
for page in pages:
lines.extend(visualize_page(page, components))
lines.append("")
# Component Tree
if components:
lines.append("")
lines.append("🧩 COMPONENT HIERARCHY")
lines.append("═" * 65)
lines.extend(visualize_component_tree(components))
lines.append("")
# API Endpoints
if api_endpoints:
lines.append("")
lines.append("🔌 API LAYER")
lines.append("═" * 65)
lines.extend(visualize_api_endpoints(api_endpoints))
lines.append("")
# Data Flow Architecture
lines.extend(visualize_data_flow(manifest))
lines.append("")
# Legend
lines.append("")
lines.append("📋 LEGEND")
lines.append("─" * 65)
lines.append(" ⏳ PENDING - Designed, awaiting approval")
lines.append(" ✅ APPROVED - Approved, ready for implementation")
lines.append(" 🔄 IN_PROGRESS - Currently being implemented")
lines.append(" 🟢 IMPLEMENTED - Implementation complete")
lines.append("")
return "\n".join(lines)
def main():
parser = argparse.ArgumentParser(description="Visualize design from manifest")
parser.add_argument("--manifest", required=True, help="Path to project_manifest.json")
parser.add_argument("--format", choices=['full', 'pages', 'components', 'api', 'flow'],
default='full', help="Visualization format")
args = parser.parse_args()
manifest = load_manifest(args.manifest)
if manifest is None:
print("❌ Error: Could not load manifest from", args.manifest)
return 1
entities = manifest.get('entities', {})
if not any([
entities.get('pages'),
entities.get('components'),
entities.get('api_endpoints')
]):
print("⚠️ No entities found in manifest. Design phase may not be complete.")
return 0
if args.format == 'full':
print(generate_full_visualization(manifest))
elif args.format == 'pages':
pages = entities.get('pages', [])
components = entities.get('components', [])
for page in pages:
print("\n".join(visualize_page(page, components)))
elif args.format == 'components':
components = entities.get('components', [])
print("\n".join(visualize_component_tree(components)))
elif args.format == 'api':
endpoints = entities.get('api_endpoints', [])
print("\n".join(visualize_api_endpoints(endpoints)))
elif args.format == 'flow':
pages = entities.get('pages', [])
print("\n".join(visualize_page_flow(pages)))
return 0
if __name__ == "__main__":
sys.exit(main())

651
skills/guardrail-orchestrator/scripts/visualize_implementation.py Normal file
View File

@ -0,0 +1,651 @@
#!/usr/bin/env python3
"""
Implementation Visualizer for guardrail workflow.
Generates visual representation of implemented pages and components:
- Component tree structure
- Props and interfaces
- Page layouts
- API endpoints
- File statistics
Usage:
python3 visualize_implementation.py --manifest project_manifest.json
python3 visualize_implementation.py --tasks-dir .workflow/versions/v001/tasks
"""
import argparse
import json
import os
import re
import sys
from pathlib import Path
from dataclasses import dataclass, field
from typing import Optional
# Try to import yaml
try:
import yaml
HAS_YAML = True
except ImportError:
HAS_YAML = False
@dataclass
class ComponentInfo:
"""Parsed component information."""
name: str
file_path: str
props: list[str] = field(default_factory=list)
imports: list[str] = field(default_factory=list)
exports: list[str] = field(default_factory=list)
hooks: list[str] = field(default_factory=list)
children: list[str] = field(default_factory=list)
lines: int = 0
has_types: bool = False
status: str = "IMPLEMENTED"
@dataclass
class PageInfo:
"""Parsed page information."""
name: str
file_path: str
route: str
components: list[str] = field(default_factory=list)
api_calls: list[str] = field(default_factory=list)
lines: int = 0
is_client: bool = False
is_server: bool = True
@dataclass
class APIEndpointInfo:
"""Parsed API endpoint information."""
name: str
file_path: str
route: str
methods: list[str] = field(default_factory=list)
has_auth: bool = False
has_validation: bool = False
lines: int = 0
def load_yaml(filepath: str) -> dict:
"""Load YAML file."""
if not os.path.exists(filepath):
return {}
with open(filepath, 'r') as f:
content = f.read()
if HAS_YAML:
return yaml.safe_load(content) or {}
# Basic fallback
result = {}
for line in content.split('\n'):
if ':' in line and not line.startswith(' '):
key, _, value = line.partition(':')
result[key.strip()] = value.strip()
return result
def load_manifest(manifest_path: str) -> dict:
"""Load project manifest."""
if not os.path.exists(manifest_path):
return {}
try:
with open(manifest_path) as f:
return json.load(f)
except (json.JSONDecodeError, IOError):
return {}
def parse_typescript_file(file_path: str) -> dict:
"""Parse TypeScript/TSX file for component information."""
if not os.path.exists(file_path):
return {'exists': False}
try:
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
lines = content.split('\n')
except (IOError, UnicodeDecodeError):
return {'exists': False}
result = {
'exists': True,
'lines': len(lines),
'imports': [],
'exports': [],
'props': [],
'hooks': [],
'components_used': [],
'api_calls': [],
'is_client': "'use client'" in content or '"use client"' in content,
'has_types': 'interface ' in content or 'type ' in content,
'methods': [],
}
# Extract imports
import_pattern = r"import\s+(?:{[^}]+}|\w+)\s+from\s+['\"]([^'\"]+)['\"]"
for match in re.finditer(import_pattern, content):
result['imports'].append(match.group(1))
# Extract exports
export_patterns = [
r"export\s+(?:default\s+)?(?:function|const|class)\s+(\w+)",
r"export\s+{\s*([^}]+)\s*}",
]
for pattern in export_patterns:
for match in re.finditer(pattern, content):
exports = match.group(1).split(',')
result['exports'].extend([e.strip() for e in exports if e.strip()])
# Extract props interface
props_pattern = r"(?:interface|type)\s+(\w*Props\w*)\s*(?:=|{)"
for match in re.finditer(props_pattern, content):
result['props'].append(match.group(1))
# Extract React hooks
hooks_pattern = r"\b(use[A-Z]\w+)\s*\("
for match in re.finditer(hooks_pattern, content):
hook = match.group(1)
if hook not in result['hooks']:
result['hooks'].append(hook)
# Extract component usage (JSX)
component_pattern = r"<([A-Z]\w+)(?:\s|/|>)"
for match in re.finditer(component_pattern, content):
comp = match.group(1)
if comp not in result['components_used'] and comp not in ['React', 'Fragment']:
result['components_used'].append(comp)
# Extract API calls
api_patterns = [
r"fetch\s*\(\s*['\"`](/api/[^'\"`]+)['\"`]",
r"axios\.\w+\s*\(\s*['\"`](/api/[^'\"`]+)['\"`]",
]
for pattern in api_patterns:
for match in re.finditer(pattern, content):
result['api_calls'].append(match.group(1))
# Extract HTTP methods (for API routes)
method_pattern = r"export\s+(?:async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH)"
for match in re.finditer(method_pattern, content):
result['methods'].append(match.group(1))
return result
def get_route_from_path(file_path: str) -> str:
"""Convert file path to route."""
# Handle Next.js App Router
if '/app/' in file_path:
route = file_path.split('/app/')[-1]
route = re.sub(r'/page\.(tsx?|jsx?)$', '', route)
route = re.sub(r'/route\.(tsx?|jsx?)$', '', route)
route = '/' + route if route else '/'
# Handle dynamic routes
route = re.sub(r'\[(\w+)\]', r':\1', route)
return route
# Handle Pages Router
if '/pages/' in file_path:
route = file_path.split('/pages/')[-1]
route = re.sub(r'\.(tsx?|jsx?)$', '', route)
route = re.sub(r'/index$', '', route)
route = '/' + route if route else '/'
route = re.sub(r'\[(\w+)\]', r':\1', route)
return route
return file_path
def visualize_component(info: ComponentInfo, indent: str = "") -> list[str]:
"""Generate ASCII visualization for a component."""
lines = []
status_icon = {
'IMPLEMENTED': '🟢',
'PENDING': '⏳',
'IN_PROGRESS': '🔄',
'ERROR': '❌',
}.get(info.status, '○')
# Component header
lines.append(f"{indent}┌{'─' * 60}┐")
lines.append(f"{indent}│ {status_icon} COMPONENT: {info.name:<46} │")
lines.append(f"{indent}│ 📁 {info.file_path:<52} │")
lines.append(f"{indent}│ 📏 {info.lines} lines │"[:63] + "│")
# Props
if info.props:
lines.append(f"{indent}├{'─' * 60}┤")
lines.append(f"{indent}│ PROPS │")
for prop in info.props[:3]:
lines.append(f"{indent}│ • {prop:<54} │")
# Hooks
if info.hooks:
lines.append(f"{indent}├{'─' * 60}┤")
lines.append(f"{indent}│ HOOKS │")
hooks_str = ', '.join(info.hooks[:5])
if len(hooks_str) > 52:
hooks_str = hooks_str[:49] + '...'
lines.append(f"{indent}│ {hooks_str:<56} │")
# Children components
if info.children:
lines.append(f"{indent}├{'─' * 60}┤")
lines.append(f"{indent}│ USES COMPONENTS │")
for child in info.children[:5]:
lines.append(f"{indent}│ └── {child:<52} │")
lines.append(f"{indent}└{'─' * 60}┘")
return lines
def visualize_page(info: PageInfo, indent: str = "") -> list[str]:
"""Generate ASCII visualization for a page."""
lines = []
client_icon = "🖥️" if info.is_client else "🌐"
# Page header
lines.append(f"{indent}╔{'═' * 62}╗")
lines.append(f"{indent}║ {client_icon} PAGE: {info.name:<52} ║")
lines.append(f"{indent}║ Route: {info.route:<51} ║")
lines.append(f"{indent}║ File: {info.file_path:<51} ║")
lines.append(f"{indent}╠{'═' * 62}╣")
# Components used
if info.components:
lines.append(f"{indent}║ COMPONENTS USED ║")
for comp in info.components[:6]:
lines.append(f"{indent}║ ├── {comp:<54} ║")
if len(info.components) > 6:
lines.append(f"{indent}║ └── ... and {len(info.components) - 6} more ║"[:65] + "║")
else:
lines.append(f"{indent}║ (No child components detected) ║")
# API calls
if info.api_calls:
lines.append(f"{indent}╠{'═' * 62}╣")
lines.append(f"{indent}║ API CALLS ║")
for api in info.api_calls[:4]:
api_short = api[:50] if len(api) <= 50 else api[:47] + '...'
lines.append(f"{indent}║ 🔌 {api_short:<55} ║")
lines.append(f"{indent}╚{'═' * 62}╝")
return lines
def visualize_api_endpoint(info: APIEndpointInfo, indent: str = "") -> list[str]:
"""Generate ASCII visualization for an API endpoint."""
lines = []
method_colors = {
'GET': '🟢',
'POST': '🟡',
'PUT': '🟠',
'PATCH': '🟠',
'DELETE': '🔴',
}
methods_str = ' '.join([f"{method_colors.get(m, '⚪')}{m}" for m in info.methods])
lines.append(f"{indent}┌{'─' * 60}┐")
lines.append(f"{indent}│ 🔌 API: {info.route:<50} │")
lines.append(f"{indent}│ Methods: {methods_str:<47} │"[:63] + "│")
lines.append(f"{indent}│ File: {info.file_path:<50} │")
features = []
if info.has_auth:
features.append("🔐 Auth")
if info.has_validation:
features.append("✓ Validation")
if features:
features_str = ' '.join(features)
lines.append(f"{indent}│ Features: {features_str:<46} │")
lines.append(f"{indent}└{'─' * 60}┘")
return lines
def generate_implementation_tree(components: list[ComponentInfo]) -> list[str]:
"""Generate a tree view of component hierarchy."""
lines = []
lines.append("")
lines.append("🌳 COMPONENT HIERARCHY")
lines.append("═" * 65)
if not components:
lines.append(" (No components found)")
return lines
# Group by directory
by_dir: dict[str, list[ComponentInfo]] = {}
for comp in components:
dir_path = str(Path(comp.file_path).parent)
if dir_path not in by_dir:
by_dir[dir_path] = []
by_dir[dir_path].append(comp)
for dir_path, comps in sorted(by_dir.items()):
lines.append(f" 📂 {dir_path}/")
for i, comp in enumerate(comps):
is_last = i == len(comps) - 1
prefix = " └──" if is_last else " ├──"
status = "🟢" if comp.status == "IMPLEMENTED" else "⏳"
lines.append(f" {prefix} {status} {comp.name}")
# Show props
if comp.props:
prop_prefix = " " if is_last else " │ "
for prop in comp.props[:2]:
lines.append(f"{prop_prefix} 📋 {prop}")
return lines
def generate_stats(
pages: list[PageInfo],
components: list[ComponentInfo],
endpoints: list[APIEndpointInfo]
) -> list[str]:
"""Generate implementation statistics."""
lines = []
total_lines = sum(p.lines for p in pages) + sum(c.lines for c in components) + sum(e.lines for e in endpoints)
client_pages = sum(1 for p in pages if p.is_client)
server_pages = len(pages) - client_pages
typed_components = sum(1 for c in components if c.has_types)
lines.append("")
lines.append("╔══════════════════════════════════════════════════════════════════╗")
lines.append("║ 📊 IMPLEMENTATION STATS ║")
lines.append("╠══════════════════════════════════════════════════════════════════╣")
lines.append(f"║ Pages: {len(pages):<5} │ Client: {client_pages:<3} │ Server: {server_pages:<3} ║")
lines.append(f"║ Components: {len(components):<5} │ Typed: {typed_components:<4} ║")
lines.append(f"║ API Endpoints: {len(endpoints):<5} ║")
lines.append(f"║ Total Lines: {total_lines:<5} ║")
lines.append("╠══════════════════════════════════════════════════════════════════╣")
# Hooks usage
all_hooks = []
for comp in components:
all_hooks.extend(comp.hooks)
hook_counts = {}
for hook in all_hooks:
hook_counts[hook] = hook_counts.get(hook, 0) + 1
if hook_counts:
lines.append("║ HOOKS USAGE ║")
for hook, count in sorted(hook_counts.items(), key=lambda x: -x[1])[:5]:
lines.append(f"║ {hook:<20} × {count:<3} ║"[:69] + "║")
lines.append("╚══════════════════════════════════════════════════════════════════╝")
return lines
def generate_page_flow(pages: list[PageInfo]) -> list[str]:
"""Generate page flow visualization."""
lines = []
if not pages:
return lines
lines.append("")
lines.append("📱 PAGE STRUCTURE")
lines.append("═" * 65)
# Sort by route
sorted_pages = sorted(pages, key=lambda p: p.route)
for i, page in enumerate(sorted_pages):
is_last = i == len(sorted_pages) - 1
icon = "🖥️" if page.is_client else "🌐"
# Page box
lines.append(f" ┌{'─' * 50}┐")
lines.append(f" │ {icon} {page.route:<47} │")
lines.append(f" │ {page.name:<48} │")
# Components count
comp_count = len(page.components)
api_count = len(page.api_calls)
lines.append(f" │ 🧩 {comp_count} components 🔌 {api_count} API calls │"[:56] + "│")
lines.append(f" └{'─' * 50}┘")
if not is_last:
lines.append(" │")
lines.append(" ▼")
return lines
def visualize_from_manifest(manifest_path: str) -> str:
"""Generate full visualization from manifest."""
manifest = load_manifest(manifest_path)
if not manifest:
return "❌ Could not load manifest"
entities = manifest.get('entities', {})
project_name = manifest.get('project', {}).get('name', 'Unknown')
lines = []
# Header
lines.append("")
lines.append("╔═══════════════════════════════════════════════════════════════════╗")
lines.append("║ 🏗️ IMPLEMENTATION VISUALIZATION ║")
lines.append(f"║ Project: {project_name:<56} ║")
lines.append("╚═══════════════════════════════════════════════════════════════════╝")
pages: list[PageInfo] = []
components: list[ComponentInfo] = []
endpoints: list[APIEndpointInfo] = []
# Parse pages
for page_data in entities.get('pages', []):
file_path = page_data.get('file_path', '')
if file_path and os.path.exists(file_path):
parsed = parse_typescript_file(file_path)
page = PageInfo(
name=page_data.get('name', 'Unknown'),
file_path=file_path,
route=get_route_from_path(file_path),
components=parsed.get('components_used', []),
api_calls=parsed.get('api_calls', []),
lines=parsed.get('lines', 0),
is_client=parsed.get('is_client', False),
)
pages.append(page)
# Parse components
for comp_data in entities.get('components', []):
file_path = comp_data.get('file_path', '')
if file_path and os.path.exists(file_path):
parsed = parse_typescript_file(file_path)
comp = ComponentInfo(
name=comp_data.get('name', 'Unknown'),
file_path=file_path,
props=parsed.get('props', []),
imports=parsed.get('imports', []),
exports=parsed.get('exports', []),
hooks=parsed.get('hooks', []),
children=parsed.get('components_used', []),
lines=parsed.get('lines', 0),
has_types=parsed.get('has_types', False),
status=comp_data.get('status', 'IMPLEMENTED'),
)
components.append(comp)
# Parse API endpoints
for api_data in entities.get('api_endpoints', []):
file_path = api_data.get('file_path', '')
if file_path and os.path.exists(file_path):
parsed = parse_typescript_file(file_path)
endpoint = APIEndpointInfo(
name=api_data.get('name', 'Unknown'),
file_path=file_path,
route=get_route_from_path(file_path),
methods=parsed.get('methods', ['GET']),
lines=parsed.get('lines', 0),
)
endpoints.append(endpoint)
# Page flow
lines.extend(generate_page_flow(pages))
# Detailed pages
if pages:
lines.append("")
lines.append("📄 PAGE DETAILS")
lines.append("═" * 65)
for page in pages:
lines.extend(visualize_page(page))
lines.append("")
# Component hierarchy
lines.extend(generate_implementation_tree(components))
# Detailed components
if components:
lines.append("")
lines.append("🧩 COMPONENT DETAILS")
lines.append("═" * 65)
for comp in components[:10]: # Limit to 10
lines.extend(visualize_component(comp))
lines.append("")
if len(components) > 10:
lines.append(f" ... and {len(components) - 10} more components")
# API endpoints
if endpoints:
lines.append("")
lines.append("🔌 API ENDPOINTS")
lines.append("═" * 65)
for endpoint in endpoints:
lines.extend(visualize_api_endpoint(endpoint))
lines.append("")
# Stats
lines.extend(generate_stats(pages, components, endpoints))
# Legend
lines.append("")
lines.append("📋 LEGEND")
lines.append("─" * 65)
lines.append(" 🟢 Implemented ⏳ Pending 🔄 In Progress ❌ Error")
lines.append(" 🖥️ Client Component 🌐 Server Component")
lines.append(" 🟢 GET 🟡 POST 🟠 PUT/PATCH 🔴 DELETE")
lines.append("")
return "\n".join(lines)
def visualize_from_tasks(tasks_dir: str) -> str:
"""Generate visualization from task files."""
tasks_path = Path(tasks_dir)
if not tasks_path.exists():
return f"❌ Tasks directory not found: {tasks_dir}"
task_files = list(tasks_path.glob('task_*.yml'))
if not task_files:
return f"❌ No task files found in: {tasks_dir}"
lines = []
lines.append("")
lines.append("╔═══════════════════════════════════════════════════════════════════╗")
lines.append("║ 📋 TASK IMPLEMENTATION STATUS ║")
lines.append("╚═══════════════════════════════════════════════════════════════════╝")
lines.append("")
implemented_files = []
for task_file in sorted(task_files):
task = load_yaml(str(task_file))
task_id = task.get('id', task_file.stem)
status = task.get('status', 'unknown')
title = task.get('title', 'Unknown task')
file_paths = task.get('file_paths', [])
status_icon = {
'completed': '✅',
'approved': '✅',
'pending': '⏳',
'in_progress': '🔄',
'blocked': '🚫',
}.get(status, '○')
lines.append(f" {status_icon} {task_id}")
lines.append(f" {title[:55]}")
for fp in file_paths:
if os.path.exists(fp):
lines.append(f" └── ✓ {fp}")
implemented_files.append(fp)
else:
lines.append(f" └── ✗ {fp} (missing)")
lines.append("")
# Parse and visualize implemented files
if implemented_files:
lines.append("─" * 65)
lines.append("")
lines.append("🔍 IMPLEMENTED FILES ANALYSIS")
lines.append("")
for fp in implemented_files[:5]:
parsed = parse_typescript_file(fp)
if parsed.get('exists'):
name = Path(fp).stem
lines.append(f" 📁 {fp}")
lines.append(f" Lines: {parsed.get('lines', 0)}")
if parsed.get('exports'):
lines.append(f" Exports: {', '.join(parsed['exports'][:3])}")
if parsed.get('hooks'):
lines.append(f" Hooks: {', '.join(parsed['hooks'][:3])}")
if parsed.get('components_used'):
lines.append(f" Uses: {', '.join(parsed['components_used'][:3])}")
lines.append("")
return "\n".join(lines)
def main():
parser = argparse.ArgumentParser(description="Visualize implementation")
parser.add_argument('--manifest', help='Path to project_manifest.json')
parser.add_argument('--tasks-dir', help='Path to tasks directory')
parser.add_argument('--format', choices=['full', 'tree', 'stats', 'pages'],
default='full', help='Output format')
args = parser.parse_args()
if args.manifest:
output = visualize_from_manifest(args.manifest)
elif args.tasks_dir:
output = visualize_from_tasks(args.tasks_dir)
else:
# Auto-detect
if os.path.exists('project_manifest.json'):
output = visualize_from_manifest('project_manifest.json')
else:
output = "Usage: python3 visualize_implementation.py --manifest project_manifest.json"
print(output)
return 0
if __name__ == "__main__":
sys.exit(main())

835
skills/guardrail-orchestrator/scripts/workflow_manager.py Executable file
View File

@ -0,0 +1,835 @@
#!/usr/bin/env python3
"""Workflow state management for automated orchestration with approval gates."""
import argparse
import json
import os
import shutil
import sys
from datetime import datetime
from pathlib import Path
from typing import Optional
# Try to import yaml, fall back to basic parsing if not available
try:
import yaml
HAS_YAML = True
except ImportError:
HAS_YAML = False
# ============================================================================
# YAML Helpers
# ============================================================================
def load_yaml(filepath: str) -> dict:
"""Load YAML file."""
if not os.path.exists(filepath):
return {}
with open(filepath, 'r') as f:
content = f.read()
if not content.strip():
return {}
if HAS_YAML:
return yaml.safe_load(content) or {}
# Simple fallback parser
result = {}
current_key = None
current_list = None
for line in content.split('\n'):
line = line.rstrip()
if not line or line.startswith('#'):
continue
if line.startswith(' - '):
if current_list is not None:
value = line[4:].strip()
# Handle quoted strings
if (value.startswith('"') and value.endswith('"')) or \
(value.startswith("'") and value.endswith("'")):
value = value[1:-1]
current_list.append(value)
continue
if ':' in line and not line.startswith(' '):
key, _, value = line.partition(':')
key = key.strip()
value = value.strip()
if value == '[]':
result[key] = []
current_list = result[key]
elif value == '{}':
result[key] = {}
current_list = None
elif value == 'null' or value == '~':
result[key] = None
current_list = None
elif value == 'true':
result[key] = True
current_list = None
elif value == 'false':
result[key] = False
current_list = None
elif value.isdigit():
result[key] = int(value)
current_list = None
elif value:
# Handle quoted strings
if (value.startswith('"') and value.endswith('"')) or \
(value.startswith("'") and value.endswith("'")):
value = value[1:-1]
result[key] = value
current_list = None
else:
result[key] = []
current_list = result[key]
current_key = key
return result
def save_yaml(filepath: str, data: dict):
"""Save data to YAML file."""
os.makedirs(os.path.dirname(filepath), exist_ok=True)
if HAS_YAML:
with open(filepath, 'w') as f:
yaml.dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
else:
# Simple YAML writer
def write_value(value, indent=0):
prefix = ' ' * indent
lines = []
if isinstance(value, dict):
for k, v in value.items():
if isinstance(v, (dict, list)) and v:
lines.append(f"{prefix}{k}:")
lines.extend(write_value(v, indent + 1))
elif isinstance(v, list):
lines.append(f"{prefix}{k}: []")
else:
lines.append(f"{prefix}{k}: {v}")
elif isinstance(value, list):
for item in value:
if isinstance(item, dict):
lines.append(f"{prefix}-")
for k, v in item.items():
lines.append(f"{prefix} {k}: {v}")
else:
lines.append(f"{prefix}- {item}")
return lines
lines = write_value(data)
with open(filepath, 'w') as f:
f.write('\n'.join(lines))
# ============================================================================
# Workflow State Management
# ============================================================================
PHASES = [
'INITIALIZING',
'DESIGNING',
'AWAITING_DESIGN_APPROVAL',
'DESIGN_APPROVED',
'DESIGN_REJECTED',
'IMPLEMENTING',
'REVIEWING',
'SECURITY_REVIEW', # New phase for security audit
'AWAITING_IMPL_APPROVAL',
'IMPL_APPROVED',
'IMPL_REJECTED',
'COMPLETING',
'COMPLETED',
'PAUSED',
'FAILED'
]
VALID_TRANSITIONS = {
'INITIALIZING': ['DESIGNING', 'FAILED'],
'DESIGNING': ['AWAITING_DESIGN_APPROVAL', 'FAILED'],
'AWAITING_DESIGN_APPROVAL': ['DESIGN_APPROVED', 'DESIGN_REJECTED', 'PAUSED'],
'DESIGN_APPROVED': ['IMPLEMENTING', 'FAILED'],
'DESIGN_REJECTED': ['DESIGNING'],
'IMPLEMENTING': ['REVIEWING', 'FAILED', 'PAUSED'],
'REVIEWING': ['SECURITY_REVIEW', 'IMPLEMENTING', 'FAILED'], # Must pass through security
'SECURITY_REVIEW': ['AWAITING_IMPL_APPROVAL', 'IMPLEMENTING', 'FAILED'], # Can go back to fix
'AWAITING_IMPL_APPROVAL': ['IMPL_APPROVED', 'IMPL_REJECTED', 'PAUSED'],
'IMPL_APPROVED': ['COMPLETING', 'FAILED'],
'IMPL_REJECTED': ['IMPLEMENTING'],
'COMPLETING': ['COMPLETED', 'FAILED'],
'COMPLETED': [],
'PAUSED': PHASES, # Can resume to any phase
'FAILED': ['INITIALIZING', 'DESIGNING', 'IMPLEMENTING'] # Can retry
}
def get_workflow_dir() -> Path:
"""Get the .workflow directory path."""
return Path('.workflow')
def get_current_state_path() -> Path:
"""Get the current workflow state file path."""
return get_workflow_dir() / 'current.yml'
def get_history_dir() -> Path:
"""Get the workflow history directory."""
return get_workflow_dir() / 'history'
def create_workflow(feature: str) -> dict:
"""Create a new workflow state."""
now = datetime.now()
workflow_id = f"workflow_{now.strftime('%Y%m%d_%H%M%S')}"
state = {
'id': workflow_id,
'feature': feature,
'current_phase': 'INITIALIZING',
'gates': {
'design_approval': {
'status': 'pending',
'approved_at': None,
'approved_by': None,
'rejection_reason': None,
'revision_count': 0
},
'implementation_approval': {
'status': 'pending',
'approved_at': None,
'approved_by': None,
'rejection_reason': None,
'revision_count': 0
}
},
'progress': {
'entities_designed': 0,
'tasks_created': 0,
'tasks_implemented': 0,
'tasks_reviewed': 0,
'tasks_approved': 0,
'tasks_completed': 0
},
'tasks': {
'pending': [],
'in_progress': [],
'review': [],
'approved': [],
'completed': [],
'blocked': []
},
'started_at': now.isoformat(),
'updated_at': now.isoformat(),
'completed_at': None,
'last_error': None,
'resume_point': {
'phase': 'INITIALIZING',
'task_id': None,
'action': 'start_workflow'
},
'checkpoints': [] # List of checkpoint snapshots for recovery
}
# Ensure directory exists
get_workflow_dir().mkdir(exist_ok=True)
get_history_dir().mkdir(exist_ok=True)
# Save state
save_yaml(str(get_current_state_path()), state)
return state
def load_current_workflow() -> Optional[dict]:
"""Load the current workflow state from the active version."""
state_path = get_current_state_path()
if not state_path.exists():
return None
# Read current.yml to get active version
current = load_yaml(str(state_path))
active_version = current.get('active_version')
if not active_version:
return None
# Load the version's session.yml
version_session_path = get_workflow_dir() / 'versions' / active_version / 'session.yml'
if not version_session_path.exists():
return None
session = load_yaml(str(version_session_path))
current_phase = session.get('current_phase', 'INITIALIZING')
# Convert session format to state format expected by show_status
return {
'id': session.get('session_id', active_version),
'feature': session.get('feature', 'Unknown'),
'current_phase': current_phase,
'gates': {
'design_approval': session.get('approvals', {}).get('design', {'status': 'pending'}),
'implementation_approval': session.get('approvals', {}).get('implementation', {'status': 'pending'})
},
'progress': {
'entities_designed': session.get('summary', {}).get('entities_created', 0),
'tasks_created': session.get('summary', {}).get('total_tasks', 0),
'tasks_implemented': session.get('summary', {}).get('tasks_completed', 0),
'tasks_reviewed': 0,
'tasks_completed': session.get('summary', {}).get('tasks_completed', 0)
},
'tasks': {
'pending': [],
'in_progress': [],
'review': [],
'approved': [],
'completed': session.get('task_sessions', []),
'blocked': []
},
'version': active_version,
'status': session.get('status', 'unknown'),
'last_error': None,
'started_at': session.get('started_at', ''),
'updated_at': session.get('updated_at', ''),
'completed_at': session.get('completed_at'),
'resume_point': {
'phase': current_phase,
'task_id': None,
'action': 'continue_workflow'
}
}
def save_workflow(state: dict):
"""Save workflow state to the version's session.yml file."""
# Get active version
current_path = get_current_state_path()
if not current_path.exists():
print("Error: No current.yml found")
return
current = load_yaml(str(current_path))
active_version = current.get('active_version')
if not active_version:
print("Error: No active version set")
return
# Get the version's session.yml path
version_session_path = get_workflow_dir() / 'versions' / active_version / 'session.yml'
if not version_session_path.exists():
print(f"Error: Session file not found: {version_session_path}")
return
# Load existing session data
session = load_yaml(str(version_session_path))
# Create backup
backup_path = version_session_path.with_suffix('.yml.bak')
shutil.copy(version_session_path, backup_path)
# Update session with state changes
session['current_phase'] = state['current_phase']
session['updated_at'] = datetime.now().isoformat()
if state.get('completed_at'):
session['completed_at'] = state['completed_at']
session['status'] = 'completed'
# Update approvals
if 'gates' in state:
if 'approvals' not in session:
session['approvals'] = {}
if state['gates'].get('design_approval', {}).get('status') == 'approved':
session['approvals']['design'] = state['gates']['design_approval']
if state['gates'].get('implementation_approval', {}).get('status') == 'approved':
session['approvals']['implementation'] = state['gates']['implementation_approval']
save_yaml(str(version_session_path), session)
def transition_phase(state: dict, new_phase: str, error: str = None) -> bool:
"""Transition workflow to a new phase."""
current = state['current_phase']
if new_phase not in PHASES:
print(f"Error: Invalid phase '{new_phase}'")
return False
if new_phase not in VALID_TRANSITIONS.get(current, []):
print(f"Error: Cannot transition from '{current}' to '{new_phase}'")
print(f"Valid transitions: {VALID_TRANSITIONS.get(current, [])}")
return False
state['current_phase'] = new_phase
state['resume_point']['phase'] = new_phase
if new_phase == 'FAILED' and error:
state['last_error'] = error
if new_phase == 'COMPLETED':
state['completed_at'] = datetime.now().isoformat()
# Set appropriate resume action
resume_actions = {
'INITIALIZING': 'start_workflow',
'DESIGNING': 'continue_design',
'AWAITING_DESIGN_APPROVAL': 'await_user_approval',
'DESIGN_APPROVED': 'start_implementation',
'DESIGN_REJECTED': 'revise_design',
'IMPLEMENTING': 'continue_implementation',
'REVIEWING': 'continue_review',
'SECURITY_REVIEW': 'run_security_audit',
'AWAITING_IMPL_APPROVAL': 'await_user_approval',
'IMPL_APPROVED': 'start_completion',
'IMPL_REJECTED': 'fix_implementation',
'COMPLETING': 'continue_completion',
'COMPLETED': 'workflow_done',
'PAUSED': 'resume_workflow',
'FAILED': 'retry_or_abort'
}
state['resume_point']['action'] = resume_actions.get(new_phase, 'unknown')
save_workflow(state)
return True
def approve_gate(state: dict, gate: str, approver: str = 'user') -> bool:
"""Approve a gate."""
if gate not in ['design_approval', 'implementation_approval']:
print(f"Error: Invalid gate '{gate}'")
return False
state['gates'][gate]['status'] = 'approved'
state['gates'][gate]['approved_at'] = datetime.now().isoformat()
state['gates'][gate]['approved_by'] = approver
# Transition to next phase
if gate == 'design_approval':
transition_phase(state, 'DESIGN_APPROVED')
else:
transition_phase(state, 'IMPL_APPROVED')
return True
def reject_gate(state: dict, gate: str, reason: str) -> bool:
"""Reject a gate."""
if gate not in ['design_approval', 'implementation_approval']:
print(f"Error: Invalid gate '{gate}'")
return False
state['gates'][gate]['status'] = 'rejected'
state['gates'][gate]['rejection_reason'] = reason
state['gates'][gate]['revision_count'] += 1
# Transition to rejection phase
if gate == 'design_approval':
transition_phase(state, 'DESIGN_REJECTED')
else:
transition_phase(state, 'IMPL_REJECTED')
return True
def update_progress(state: dict, **kwargs):
"""Update progress counters."""
for key, value in kwargs.items():
if key in state['progress']:
state['progress'][key] = value
save_workflow(state)
def update_task_status(state: dict, task_id: str, new_status: str):
"""Update task status in workflow state."""
# Remove from all status lists
for status in state['tasks']:
if task_id in state['tasks'][status]:
state['tasks'][status].remove(task_id)
# Add to new status list
if new_status in state['tasks']:
state['tasks'][new_status].append(task_id)
# Update resume point if task is in progress
if new_status == 'in_progress':
state['resume_point']['task_id'] = task_id
save_workflow(state)
def save_checkpoint(state: dict, description: str, data: dict = None) -> dict:
"""Save a checkpoint for recovery during long operations.
Args:
state: Current workflow state
description: Human-readable description of checkpoint
data: Optional additional data to store
Returns:
The checkpoint object that was created
"""
checkpoint = {
'id': f"checkpoint_{datetime.now().strftime('%Y%m%d_%H%M%S')}",
'timestamp': datetime.now().isoformat(),
'phase': state['current_phase'],
'description': description,
'resume_point': state['resume_point'].copy(),
'progress': state['progress'].copy(),
'data': data or {}
}
# Keep only last 10 checkpoints to avoid bloat
if 'checkpoints' not in state:
state['checkpoints'] = []
state['checkpoints'].append(checkpoint)
if len(state['checkpoints']) > 10:
state['checkpoints'] = state['checkpoints'][-10:]
save_workflow(state)
return checkpoint
def get_latest_checkpoint(state: dict) -> Optional[dict]:
"""Get the most recent checkpoint.
Returns:
Latest checkpoint or None if no checkpoints exist
"""
checkpoints = state.get('checkpoints', [])
return checkpoints[-1] if checkpoints else None
def restore_from_checkpoint(state: dict, checkpoint_id: str = None) -> bool:
"""Restore workflow state from a checkpoint.
Args:
state: Current workflow state
checkpoint_id: Optional specific checkpoint ID, defaults to latest
Returns:
True if restoration was successful
"""
checkpoints = state.get('checkpoints', [])
if not checkpoints:
print("Error: No checkpoints available")
return False
# Find checkpoint
if checkpoint_id:
checkpoint = next((c for c in checkpoints if c['id'] == checkpoint_id), None)
if not checkpoint:
print(f"Error: Checkpoint '{checkpoint_id}' not found")
return False
else:
checkpoint = checkpoints[-1]
# Restore state from checkpoint
state['resume_point'] = checkpoint['resume_point'].copy()
state['progress'] = checkpoint['progress'].copy()
state['current_phase'] = checkpoint['phase']
state['last_error'] = None # Clear any error since we're recovering
save_workflow(state)
print(f"Restored from checkpoint: {checkpoint['description']}")
return True
def list_checkpoints(state: dict) -> list:
"""List all available checkpoints.
Returns:
List of checkpoint summaries
"""
return [
{
'id': c['id'],
'timestamp': c['timestamp'],
'phase': c['phase'],
'description': c['description']
}
for c in state.get('checkpoints', [])
]
def clear_checkpoints(state: dict):
"""Clear all checkpoints (typically after successful completion)."""
state['checkpoints'] = []
save_workflow(state)
def archive_workflow(state: dict, suffix: str = ''):
"""Archive completed/aborted workflow."""
history_dir = get_history_dir()
history_dir.mkdir(exist_ok=True)
filename = f"{state['id']}{suffix}.yml"
archive_path = history_dir / filename
save_yaml(str(archive_path), state)
# Remove current state
current_path = get_current_state_path()
if current_path.exists():
current_path.unlink()
def show_status(state: dict):
"""Display workflow status."""
print()
print("╔" + "═" * 58 + "╗")
print("║" + "WORKFLOW STATUS".center(58) + "║")
print("╠" + "═" * 58 + "╣")
print("║" + f" ID: {state['id']}".ljust(58) + "║")
print("║" + f" Feature: {state['feature'][:45]}".ljust(58) + "║")
print("║" + f" Phase: {state['current_phase']}".ljust(58) + "║")
print("╠" + "═" * 58 + "╣")
print("║" + " APPROVAL GATES".ljust(58) + "║")
design_gate = state['gates']['design_approval']
impl_gate = state['gates']['implementation_approval']
design_icon = "✅" if design_gate['status'] == 'approved' else "❌" if design_gate['status'] == 'rejected' else "⏳"
impl_icon = "✅" if impl_gate['status'] == 'approved' else "❌" if impl_gate['status'] == 'rejected' else "⏳"
print("║" + f" {design_icon} Design: {design_gate['status']}".ljust(58) + "║")
print("║" + f" {impl_icon} Implementation: {impl_gate['status']}".ljust(58) + "║")
print("╠" + "═" * 58 + "╣")
print("║" + " PROGRESS".ljust(58) + "║")
p = state['progress']
print("║" + f" Entities Designed: {p['entities_designed']}".ljust(58) + "║")
print("║" + f" Tasks Created: {p['tasks_created']}".ljust(58) + "║")
print("║" + f" Tasks Implemented: {p['tasks_implemented']}".ljust(58) + "║")
print("║" + f" Tasks Reviewed: {p['tasks_reviewed']}".ljust(58) + "║")
print("║" + f" Tasks Completed: {p['tasks_completed']}".ljust(58) + "║")
print("╠" + "═" * 58 + "╣")
print("║" + " TASK BREAKDOWN".ljust(58) + "║")
t = state['tasks']
print("║" + f" ⏳ Pending: {len(t['pending'])}".ljust(58) + "║")
print("║" + f" 🔄 In Progress: {len(t['in_progress'])}".ljust(58) + "║")
print("║" + f" 🔍 Review: {len(t['review'])}".ljust(58) + "║")
print("║" + f" ✅ Approved: {len(t['approved'])}".ljust(58) + "║")
print("║" + f" ✓ Completed: {len(t['completed'])}".ljust(58) + "║")
print("║" + f" 🚫 Blocked: {len(t['blocked'])}".ljust(58) + "║")
if state['last_error']:
print("╠" + "═" * 58 + "╣")
print("║" + " ⚠️ LAST ERROR".ljust(58) + "║")
print("║" + f" {state['last_error'][:52]}".ljust(58) + "║")
print("╠" + "═" * 58 + "╣")
print("║" + " TIMESTAMPS".ljust(58) + "║")
print("║" + f" Started: {state['started_at'][:19]}".ljust(58) + "║")
print("║" + f" Updated: {state['updated_at'][:19]}".ljust(58) + "║")
if state['completed_at']:
print("║" + f" Completed: {state['completed_at'][:19]}".ljust(58) + "║")
print("╚" + "═" * 58 + "╝")
# ============================================================================
# CLI Interface
# ============================================================================
def main():
parser = argparse.ArgumentParser(description="Workflow state management")
subparsers = parser.add_subparsers(dest='command', help='Commands')
# create command
create_parser = subparsers.add_parser('create', help='Create new workflow')
create_parser.add_argument('feature', help='Feature to implement')
# status command
subparsers.add_parser('status', help='Show workflow status')
# transition command
trans_parser = subparsers.add_parser('transition', help='Transition to new phase')
trans_parser.add_argument('phase', choices=PHASES, help='Target phase')
trans_parser.add_argument('--error', help='Error message (for FAILED phase)')
# approve command
approve_parser = subparsers.add_parser('approve', help='Approve a gate')
approve_parser.add_argument('gate', choices=['design', 'implementation'], help='Gate to approve')
approve_parser.add_argument('--approver', default='user', help='Approver name')
# reject command
reject_parser = subparsers.add_parser('reject', help='Reject a gate')
reject_parser.add_argument('gate', choices=['design', 'implementation'], help='Gate to reject')
reject_parser.add_argument('reason', help='Rejection reason')
# progress command
progress_parser = subparsers.add_parser('progress', help='Update progress')
progress_parser.add_argument('--entities', type=int, help='Entities designed')
progress_parser.add_argument('--tasks-created', type=int, help='Tasks created')
progress_parser.add_argument('--tasks-impl', type=int, help='Tasks implemented')
progress_parser.add_argument('--tasks-reviewed', type=int, help='Tasks reviewed')
progress_parser.add_argument('--tasks-completed', type=int, help='Tasks completed')
# task command
task_parser = subparsers.add_parser('task', help='Update task status')
task_parser.add_argument('task_id', help='Task ID')
task_parser.add_argument('status', choices=['pending', 'in_progress', 'review', 'approved', 'completed', 'blocked'])
# archive command
archive_parser = subparsers.add_parser('archive', help='Archive workflow')
archive_parser.add_argument('--suffix', default='', help='Filename suffix (e.g., _aborted)')
# exists command
subparsers.add_parser('exists', help='Check if workflow exists')
# checkpoint command
checkpoint_parser = subparsers.add_parser('checkpoint', help='Manage checkpoints')
checkpoint_parser.add_argument('action', choices=['save', 'list', 'restore', 'clear'],
help='Checkpoint action')
checkpoint_parser.add_argument('--description', '-d', help='Checkpoint description (for save)')
checkpoint_parser.add_argument('--id', help='Checkpoint ID (for restore)')
checkpoint_parser.add_argument('--data', help='JSON data to store (for save)')
args = parser.parse_args()
if args.command == 'create':
state = create_workflow(args.feature)
print(f"Created workflow: {state['id']}")
print(f"Feature: {args.feature}")
print(f"State saved to: {get_current_state_path()}")
elif args.command == 'status':
state = load_current_workflow()
if state:
show_status(state)
else:
print("No active workflow found.")
print("Start a new workflow with: /workflow:spawn <feature>")
elif args.command == 'transition':
state = load_current_workflow()
if not state:
print("Error: No active workflow")
sys.exit(1)
if transition_phase(state, args.phase, args.error):
print(f"Transitioned to: {args.phase}")
else:
sys.exit(1)
elif args.command == 'approve':
state = load_current_workflow()
if not state:
print("Error: No active workflow")
sys.exit(1)
gate = f"{args.gate}_approval"
if approve_gate(state, gate, args.approver):
print(f"Approved: {args.gate}")
elif args.command == 'reject':
state = load_current_workflow()
if not state:
print("Error: No active workflow")
sys.exit(1)
gate = f"{args.gate}_approval"
if reject_gate(state, gate, args.reason):
print(f"Rejected: {args.gate}")
print(f"Reason: {args.reason}")
elif args.command == 'progress':
state = load_current_workflow()
if not state:
print("Error: No active workflow")
sys.exit(1)
updates = {}
if args.entities is not None:
updates['entities_designed'] = args.entities
if args.tasks_created is not None:
updates['tasks_created'] = args.tasks_created
if args.tasks_impl is not None:
updates['tasks_implemented'] = args.tasks_impl
if args.tasks_reviewed is not None:
updates['tasks_reviewed'] = args.tasks_reviewed
if args.tasks_completed is not None:
updates['tasks_completed'] = args.tasks_completed
if updates:
update_progress(state, **updates)
print("Progress updated")
elif args.command == 'task':
state = load_current_workflow()
if not state:
print("Error: No active workflow")
sys.exit(1)
update_task_status(state, args.task_id, args.status)
print(f"Task {args.task_id} → {args.status}")
elif args.command == 'archive':
state = load_current_workflow()
if not state:
print("Error: No active workflow")
sys.exit(1)
archive_workflow(state, args.suffix)
print(f"Workflow archived to: {get_history_dir()}/{state['id']}{args.suffix}.yml")
elif args.command == 'exists':
state = load_current_workflow()
if state:
print("true")
sys.exit(0)
else:
print("false")
sys.exit(1)
elif args.command == 'checkpoint':
state = load_current_workflow()
if not state:
print("Error: No active workflow")
sys.exit(1)
if args.action == 'save':
if not args.description:
print("Error: --description required for save")
sys.exit(1)
data = None
if args.data:
try:
data = json.loads(args.data)
except json.JSONDecodeError:
print("Error: --data must be valid JSON")
sys.exit(1)
checkpoint = save_checkpoint(state, args.description, data)
print(f"Checkpoint saved: {checkpoint['id']}")
print(f"Description: {args.description}")
elif args.action == 'list':
checkpoints = list_checkpoints(state)
if not checkpoints:
print("No checkpoints available")
else:
print("\n" + "=" * 60)
print("CHECKPOINTS".center(60))
print("=" * 60)
for cp in checkpoints:
print(f"\n ID: {cp['id']}")
print(f" Time: {cp['timestamp'][:19]}")
print(f" Phase: {cp['phase']}")
print(f" Description: {cp['description']}")
print("\n" + "=" * 60)
elif args.action == 'restore':
if restore_from_checkpoint(state, args.id):
print("Workflow state restored successfully")
else:
sys.exit(1)
elif args.action == 'clear':
clear_checkpoints(state)
print("All checkpoints cleared")
else:
parser.print_help()
if __name__ == "__main__":
main()

99
skills/guardrail-orchestrator/templates/task_example.yml Normal file
View File

@ -0,0 +1,99 @@
# Example Task - Created by Architect Agent
# Copy this template when creating new tasks
# ============================================
# FRONTEND TASK EXAMPLE
# ============================================
id: task_create_button
type: create
title: Create Button component
agent: frontend
status: pending
priority: high
entity_ids:
- comp_button
file_paths:
- app/components/Button.tsx
dependencies: [] # No dependencies, can start immediately
description: |
Create a reusable Button component with variant support.
Must match the manifest specification for comp_button.
acceptance_criteria:
- Exports Button component as named export
- Implements ButtonProps interface matching manifest
- Supports variant prop (primary, secondary, danger)
- Supports size prop (sm, md, lg)
- Supports disabled state
- Uses Tailwind CSS for styling
- Follows existing component patterns
---
# ============================================
# BACKEND TASK EXAMPLE
# ============================================
id: task_create_api_tasks
type: create
title: Create Tasks API endpoints
agent: backend
status: pending
priority: high
entity_ids:
- api_list_tasks
- api_create_task
file_paths:
- app/api/tasks/route.ts
- app/lib/db.ts
dependencies:
- task_create_db_tasks # Needs database first
description: |
Implement GET and POST handlers for /api/tasks endpoint.
GET: List all tasks with optional filtering
POST: Create a new task
acceptance_criteria:
- Exports GET function for listing tasks
- Exports POST function for creating tasks
- GET supports ?status and ?search query params
- POST validates required title field
- Returns proper HTTP status codes
- Matches manifest request/response schemas
---
# ============================================
# REVIEW TASK EXAMPLE
# ============================================
id: task_review_button
type: review
title: Review Button component implementation
agent: reviewer
status: pending
priority: medium
entity_ids:
- comp_button
file_paths:
- app/components/Button.tsx
dependencies:
- task_create_button # Must complete implementation first
description: |
Review the Button component implementation for quality,
correctness, and adherence to manifest specifications.
acceptance_criteria:
- Code matches manifest spec
- Props interface is correct
- Follows project patterns
- Lint passes
- Type-check passes

6
start-workflow.sh Executable file
View File

@ -0,0 +1,6 @@
#!/bin/bash
# Auto-generated by Eureka Factory
# This script starts Claude Code with the workflow command
cd "$(dirname "$0")"
claude '/workflow:spawn --auto a platform where artists can publish their original songs'