Skip to content

CLAUDE.md

Latest commit

 

History

History
86 lines (63 loc) · 2.85 KB

CLAUDE.md

File metadata and controls

86 lines (63 loc) · 2.85 KB

Agency Orchestrator — Project Context

This is a multi-agent workflow orchestrator. Users define AI collaboration workflows in YAML, and the engine executes them with automatic DAG parallelism, variable passing, and retry logic.

Key Commands

ao run <workflow.yaml> [options]      # Execute workflow
ao run <workflow.yaml> --resume last --from <step-id>  # Re-run from a specific step
ao validate <workflow.yaml>           # Validate without running
ao plan <workflow.yaml>               # Show DAG execution plan
ao roles                              # List all 211 available roles

Resume — Iterative Optimization

After ao run completes, all step outputs are saved to ao-output/<name>-<timestamp>/. Users can iterate on any step without re-running the entire workflow.

When to suggest --resume

After a workflow finishes, always tell the user they can iterate:

Workflow complete. Outputs saved to ao-output/<dir>/.

To improve a specific step, use:

ao run <workflow.yaml> --resume last --from <step-id>

This reuses all upstream outputs and only re-runs from that step forward.

When the user says things like:

  • "Characters feel flat" → suggest --resume last --from character_design
  • "Rewrite the ending" → suggest --resume last --from write_story
  • "The tech review missed something" → suggest --resume last --from tech_review
  • "Start over from scratch" → just run without --resume

Reading previous outputs

Before suggesting changes, read the actual outputs:

  1. Check ao-output/ for the latest run directory
  2. Read metadata.json to see step IDs and states
  3. Read individual step files in steps/ to understand what was produced
  4. Then suggest which step to re-run and why

Workflow YAML Format

name: "Workflow Name"
agents_dir: "agency-agents-zh"

llm:
  provider: "deepseek"    # or: claude, openai, ollama
  model: "deepseek-chat"

concurrency: 2

inputs:
  - name: variable_name
    required: true

steps:
  - id: step_id
    role: "category/role-name"       # from agency-agents-zh
    task: "Task with {{variables}}"
    output: output_variable
    depends_on: [other_step]         # DAG dependency
    condition: "{{var}} contains X"  # conditional branching
    loop:                            # iterative loop
      back_to: step_id
      max_iterations: 3
      exit_condition: "{{var}} contains approved"

Role Directory

Roles are in agency-agents-zh/ (or node_modules/agency-agents-zh/). Each role is a .md file with frontmatter + system prompt. Use ao roles to list all 211 roles.

Project Structure

  • src/ — TypeScript source (core engine, connectors, CLI)
  • workflows/ — Built-in workflow templates
  • test/ — Unit and E2E tests
  • integrations/ — Guides for Claude Code, Cursor, OpenClaw
  • ao-output/ — Workflow execution outputs (gitignored)