Skip to main content

​
Overview

Omni Architect provides powerful hooks and extension points to customize the pipeline for your team’s specific workflow. This example shows how to integrate with external tools, add custom validation logic, and automate handoff processes.

​
Available Hooks

Hooks are defined in .omni-architect.yml and execute at key pipeline stages:
.omni-architect.yml
hooks:
  on_validation_approved: "npm run generate:specs"
  on_figma_complete: "npm run notify:slack"
  on_error: "npm run alert:team"

​
Hook Lifecycle

​
Hook Reference

HookTriggerContext VariablesUse Cases
on_prd_parsedAfter Phase 1$PRD_PATH, $PARSED_JSONValidate PRD completeness, auto-tag Jira issues
on_mermaid_generatedAfter Phase 2$DIAGRAMS_DIR, $DIAGRAM_COUNTGenerate static images, commit to git
on_validation_approvedPhase 3 approved$VALIDATION_SCORE, $REPORT_JSONTrigger downstream specs generation
on_validation_rejectedPhase 3 rejected$VALIDATION_SCORE, $ERRORSNotify PM, log to analytics
on_figma_completeAfter Phase 4$FIGMA_FILE_KEY, $ASSET_IDSNotify team, update project board
on_asset_deliverAfter Phase 5$OUTPUT_DIR, $DELIVERABLESArchive artifacts, trigger CI/CD
on_errorAny phase error$PHASE, $ERROR_MESSAGEAlert ops, rollback, log to Sentry

​
Example 1: Slack Notifications

Notify your team when designs are ready: 
project_name: "My Product"
figma_file_key: "abc123"

hooks:
  on_figma_complete: "node scripts/notify-slack.js"
Output in Slack: 
🎨 New designs ready!
New Figma assets generated
5 frames created by Omni Architect

[View in Figma] (button)

​
Example 2: Jira Integration

Auto-update Jira tickets when validation passes: 
hooks:
  on_validation_approved: "python scripts/update-jira.py"
Result:
  • Jira ticket PROD-123 automatically moves to “Design Review” status
  • Comment added with validation score
  • Team is notified via Jira notifications

​
Example 3: Git Automation

Commit generated diagrams to version control: 
hooks:
  on_mermaid_generated: "bash scripts/commit-diagrams.sh"
  on_figma_complete: "bash scripts/commit-figma-links.sh"

​
Example 4: Custom Validation Rules

Add team-specific validation on top of Omni Architect’s built-in validator: 
hooks:
  on_validation_approved: "node scripts/custom-validate.js"

​
Example 5: Storybook Export

Generate Storybook documentation from Figma assets: 
hooks:
  on_figma_complete: "npm run export:storybook"
Result: 
✓ Created story: checkout-flow
✓ Created story: user-authentication
✓ Created story: domain-er-diagram

​
Example 6: Analytics & Metrics

Track pipeline metrics over time: 
hooks:
  on_asset_deliver: "node scripts/log-metrics.js"

​
Hook Best Practices

Exit Codes Matter

Return non-zero exit codes to halt the pipeline on errors.

Use Environment Variables

All context is passed via env vars like $FIGMA_FILE_KEY.

Keep Hooks Fast

Hooks should complete in < 10 seconds to avoid blocking the pipeline.

Handle Failures Gracefully

Log errors and use on_error hook for cleanup.

​
Available Context Variables

# PRD Phase
export PRD_PATH="./docs/prd.md"
export PARSED_JSON="./output/parsed-prd.json"
export PROJECT_NAME="My Project"

# Mermaid Phase
export DIAGRAMS_DIR="./output/diagrams"
export DIAGRAM_COUNT="5"
export DIAGRAM_TYPES="flowchart,sequence,erDiagram"

# Validation Phase
export VALIDATION_SCORE="0.93"
export REPORT_JSON="./output/validation-report.json"
export VALIDATION_STATUS="approved"

# Figma Phase
export FIGMA_FILE_KEY="abc123XYZ"
export FIGMA_ACCESS_TOKEN="figd_xxxx"
export ASSET_IDS="123:456,123:789,123:012"

# Delivery Phase
export OUTPUT_DIR="./output"
export DELIVERABLES="./output/deliverables.json"
export ORCHESTRATION_LOG="./output/orchestration.log"

# Error Handling
export PHASE="mermaid-gen"
export ERROR_MESSAGE="Syntax error in flowchart"
export ERROR_CODE="MERMAID_SYNTAX_ERROR"

​
Advanced: Multi-Stage Workflows

Chain multiple tools together:
.omni-architect.yml
hooks:
  on_figma_complete: |
    # Multi-command pipeline
    npm run export:storybook && \
    npm run generate:react-components && \
    npm test && \
    npm run deploy:preview && \
    node scripts/notify-slack.js
Multi-command hooks should use && to ensure each step succeeds before continuing. Use set -e in bash scripts.

​
Troubleshooting Hooks

IssueSolution
Hook not executingCheck file permissions: chmod +x scripts/*.sh
Environment vars missingHooks inherit from skill runner; export vars before running
TimeoutDefault hook timeout is 60s; keep hooks fast or run async
Non-zero exit ignoredEnsure script returns correct exit code: process.exit(1)
Path issuesHooks run in project root; use absolute paths or cd first

​
Real-World Workflow Example

Complete CI/CD pipeline for a product team:
.omni-architect.yml
project_name: "E-Commerce Platform"
figma_file_key: "abc123XYZ"
design_system: "material-3"
validation_mode: "auto"
validation_threshold: 0.88

hooks:
  # After PRD parsed → Validate completeness
  on_prd_parsed: |
    node scripts/validate-prd-completeness.js
  
  # After diagrams generated → Commit to git
  on_mermaid_generated: |
    bash scripts/commit-diagrams.sh
  
  # After validation approved → Update Jira & generate specs
  on_validation_approved: |
    python scripts/update-jira.py && \
    npm run generate:api-specs
  
  # After Figma complete → Notify team & export Storybook
  on_figma_complete: |
    node scripts/notify-slack.js && \
    npm run export:storybook && \
    npm run deploy:storybook-preview
  
  # After delivery → Log metrics & trigger downstream
  on_asset_deliver: |
    node scripts/log-metrics.js && \
    curl -X POST $CI_WEBHOOK_URL \
      -d '{"event": "omni_architect_complete"}'
  
  # On any error → Alert team & rollback
  on_error: |
    node scripts/alert-team.js && \
    bash scripts/rollback-changes.sh
Start simple with one hook (e.g., Slack notifications) and gradually add more as your team’s workflow matures.

​
Next Steps

CI/CD Integration

Run Omni Architect in GitHub Actions

Configuration Reference

Complete YAML configuration docs

API Reference

Programmatic hook API

Troubleshooting

Debug common hook issues

Build docs developers (and LLMs) love

Get started for freeTalk to us