{"id":34108053,"url":"https://github.com/proact0/act-operator","last_synced_at":"2026-04-11T04:07:55.953Z","repository":{"id":318858195,"uuid":"1075135519","full_name":"Proact0/act-operator","owner":"Proact0","description":"Provides and manages the standards of the Act Template.","archived":false,"fork":false,"pushed_at":"2026-03-31T09:20:41.000Z","size":5123,"stargazers_count":18,"open_issues_count":3,"forks_count":9,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-31T10:14:10.088Z","etag":null,"topics":["act","ai","ai-native","ax","beginner-friendly","cast","claude","claude-code","langchain","langgraph","langgraph-template","modular","open-source","python","scalable-architecture","template","template-framework"],"latest_commit_sha":null,"homepage":"https://www.proact0.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Proact0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-13T04:57:16.000Z","updated_at":"2026-03-31T09:20:40.000Z","dependencies_parsed_at":"2025-10-16T20:49:38.813Z","dependency_job_id":"146c21e5-5415-423b-ba9a-ad26199c5d04","html_url":"https://github.com/Proact0/act-operator","commit_stats":null,"previous_names":["qjrm1430/act","proact0/act-operator"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/Proact0/act-operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Proact0%2Fact-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Proact0%2Fact-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Proact0%2Fact-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Proact0%2Fact-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Proact0","download_url":"https://codeload.github.com/Proact0/act-operator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Proact0%2Fact-operator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31504897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["act","ai","ai-native","ax","beginner-friendly","cast","claude","claude-code","langchain","langgraph","langgraph-template","modular","open-source","python","scalable-architecture","template","template-framework"],"created_at":"2025-12-14T18:13:00.660Z","updated_at":"2026-04-11T04:07:55.936Z","avatar_url":"https://github.com/Proact0.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://www.proact0.org/\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: light)\" srcset=\".github/images/light-theme.png\"\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\".github/images/dark-theme.png\"\u003e\n      \u003cimg alt=\"Proact0 Logo\" src=\".github/images/light-theme.png\" width=\"80%\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch2\u003eAct Operator\u003c/h2\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://www.apache.org/licenses/LICENSE-2.0\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/pypi/l/act-operator\" alt=\"PyPI - License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypistats.org/packages/act-operator\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/pepy/dt/act-operator?color=deeppink\" alt=\"PyPI - Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/act-operator/#history\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/act-operator\" alt=\"Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.linkedin.com/company/proact0\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/LinkedIn-Proact0-blue?logo=linkedin\" alt=\"LinkedIn\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.proact0.org/\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Homepage-Proact0.org-brightgreen?logo=internet-explorer\" alt=\"Homepage\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n※ 한국어로 읽으시는 경우: [README_KR.md](README_KR.md)\n\n**A production-grade harness for controlling LangGraph 1.0+ project structure with AI agents.** Designed for real products — not just prototypes.\n\n```bash\nuvx --from act-operator act new\n```\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\".github/images/flowchart-light-theme.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\".github/images/flowchart-dark-theme.png\"\u003e\n  \u003cimg alt=\"Act Operator Flowchart\" src=\".github/images/flowchart-light-theme.png\" width=\"100%\"\u003e\n\u003c/picture\u003e\n\n## The Problem: Context Gap\n\n\u003e Same model, different results — why?\n\nWhile developing LangGraph agents in production, we kept observing the same pattern across our team.\n\nAn experienced developer asks Claude Code to implement a workflow — excellent code comes back. A newcomer makes the same request to the same Claude Code — generic, inconsistent, subtly wrong code comes back. Same model. Why?\n\nThe problem isn't the model. It's the **context gap** — and it affects humans and AI agents equally. A new team member without onboarding struggles with the same codebase for the same reason: conventions are implicit, architecture lives in someone's head, and there's no structured environment to guide them. The AI agent is no different.\n\nEven experienced developers hit this wall: when sessions change, the agent forgets yesterday's architecture. Knowledge lives in people's heads, not in the codebase. If a human can't find the conventions, the agent can't either.\n\nThe fix isn't better prompts or better models. It's designing the environment in which both humans and agents operate.\n\n## What is a Harness?\n\nThe word *harness* comes from Old French *harnois* — originally meaning \"military equipment, apparatus of control.\" Since the 1690s, it has carried a metaphorical meaning: *to control an untamed force for productive use*. A wind farm \"harnesses\" the wind. Engineering has applied this principle in different forms for decades:\n\n- **Wiring Harness**: Bundles tangled wires into a single controlled unit. An automotive industry standard for decades.\n- **Test Harness**: Isolates a component with stubs and drivers so it can run without the full infrastructure. A core concept in software testing.\n- **CI/CD Pipeline**: Structures the deployment flow so code passes through build, test, and verification layers before reaching production. Another harness.\n\nThe common thread:\n\u003e An external environment designed to steer an uncontrolled subject — wires, code components, deployment flows — in the right direction.\n\nIn AI-assisted development, **a harness is the system of scaffolding, executable knowledge, and feedback loops that wraps both humans and AI agents so they reliably produce correct output — regardless of who is driving.**\n\nAct Operator implements this with three layers:\n\n| Layer | Role | How Act implements it |\n|-------|------|----------------------|\n| **Scaffolding** | Structure assembled before the first agent prompt | `act new` — generates the full project skeleton with module conventions and base classes baked in |\n| **Executable SSOT** | Knowledge encoded as living files that agents and humans read at runtime | Act Template (project structure, CI, base classes, configs), Agent Skills (50+ patterns for agents), Drawkit (visual architecture for teams) |\n| **Feedback Loop** | Specs that survive across sessions and keep agents aligned | `CLAUDE.md` — architecture diagrams, node specifications, and development commands generated by skills and maintained across sessions |\n\nThese three layers work together. Scaffolding gives agents a consistent starting point. The SSOT layer provides three forms of executable knowledge: the **Act Template** establishes project conventions (CI workflows, base classes, test structure, configs), **Skills** give agents the patterns to reason correctly within that structure, and the **Drawkit** gives teams a shared visual vocabulary for architecture diagrams. CLAUDE.md gives them persistent memory of what was designed — so the agent in your next session picks up exactly where the last one left off.\n\n\u003e **Terminology**: An **Act** is a harness instance — your LangGraph project. A **Cast** is a graph unit within it (one StateGraph = one Cast). A single Act can contain multiple Casts as independent packages in a monorepo.\n\n**Use Cases**: Conversational agents, agentic AI systems, business workflow automation, multi-step data pipelines, document processing flows — or any application requiring stateful graph/workflow orchestration.\n\n## Quick Start\n\nRequires Python 3.11+.\n\n```bash\n# Create a new Act project\nuvx --from act-operator act new\n\n# Follow interactive prompts:\n# - Path: default [.] or new path\n# - Act name: project_name\n# - Cast name: workflow_name\n```\n\nAfter creation, install dependencies:\n\n```bash\nuv sync\n```\n\n### Start Building with AI\n\nLaunch your AI tool in the project root. If you use **Claude Code**:\n\n```bash\nclaude\n```\n\nThe skills in `.claude/skills/` are pre-loaded. Mention a skill by name to activate it:\n\n```\nUse @architecting-act to design a customer support chatbot\n```\n\n\u003e **Note for other tools**: The `.claude` directory naming is specific to Claude Code. If you use Cursor, Gemini CLI, or other AI tools that support skill directories, rename it according to that tool's conventions.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eOpenCode Quick Start\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\nopencode .\n# or\nopencode run \"Design a customer support chatbot\"\n```\n\nOpenCode reads environment variables from `.env` at the project root (configured in `langgraph.json` as `env: \".env\"`).\n\n\u003c/details\u003e\n\n## The Executable SSOT\n\nTraditional teams share LangGraph knowledge through wikis, architecture docs, and tribal memory. The problem: documentation decays, wikis go stale, and tribal memory doesn't survive team changes.\n\nThe harness encodes that knowledge as **living files** — not static documentation, but executable references that agents and humans read directly. Act Operator scaffolds three complementary SSOT components:\n\n| Component | Audience | What it provides |\n|-----------|----------|------------------|\n| **Act Template** (scaffold) | Developers | The project skeleton itself — CI workflows, base classes, test structure, pre-commit hooks, monorepo config, `.env.example`, `TEMPLATE_README.md` usage guide |\n| **Agent Skills** (`.claude/skills/`) | AI agents | 50+ reference patterns, decision trees, architecture templates — agents read these at runtime |\n| **Drawkit** (`drawkit.xml`) | Teams | Pre-defined draw.io shapes for Act architecture — a shared visual vocabulary for human-to-human communication |\n\nEach component targets a different audience while referencing the same underlying conventions. The Act Template establishes the structural foundation that agents and developers both work within; Skills tell agents how to build correctly inside that structure; the Drawkit tells teams how to communicate architecture visually.\n\n### Agent Skills\n\nSkills encode LangGraph knowledge as files that agents read directly. Instead of you telling the agent what patterns exist, the skill shows the agent the exact patterns, decision trees, and reference implementations it needs — at the moment it needs them. All patterns reference official LangChain 1.0+/LangGraph 1.0+ documentation, not guesswork. The skills are lean by design: context-aware guidance without unnecessary code generation, keeping token usage low across long sessions.\n\n```\n.claude/skills/\n├── architecting-act/      # Design phase — agentic patterns, CLAUDE.md generation\n├── developing-cast/       # Implementation phase — 50+ LangGraph patterns\n├── developing-deepagent/  # DeepAgent phase — subagents, backends, sandbox, HITL\n├── streaming-cast/        # Streaming phase — stream modes, SSE/WebSocket integration\n└── testing-cast/          # Testing phase — mocking strategies, fixtures, coverage\n```\n\nEach skill contains a `SKILL.md` (entry point) and `resources/` (reference docs). `architecting-act` additionally includes `scripts/` (validation) and `templates/` (CLAUDE.md generation).\n\n**Available Skills**:\n\n- `architecting-act` — Design graph architectures and node composition strategies. Uses an interactive question sequence to understand requirements before producing a CLAUDE.md that becomes the persistent spec for the implementation phase. Supports 4 modes: initial design, add cast, extract sub-cast, redesign cast.\n- `developing-cast` — Implement LangGraph casts (state, nodes, agents with `create_agent`, tools, memory, middlewares, graph assembly). Reads CLAUDE.md as its source of truth.\n- `developing-deepagent` — Implement DeepAgent harnesses (`create_deep_agent`, subagents, backends, sandbox execution, HITL). Used when a cast node requires multi-step planning or subagent delegation.\n- `streaming-cast` — Implement LangGraph v2 streaming for graphs with subgraphs and agents. Covers stream modes (values, messages, updates, custom, events), StreamWriter, subgraph/agent streaming with namespace parsing, and transport integration (SSE, WebSocket).\n- `testing-cast` — Write pytest tests with LLM mocking strategies. Covers node-level unit tests and graph integration tests.\n\n### Node Composition Types\n\nThe `architecting-act` skill designs graph architecture around 5 node types:\n\n| Node Type | Use when |\n|-----------|----------|\n| **`START` / `END`** | Built-in virtual nodes — flow control markers for graph entry and termination |\n| **`ToolNode`** | Stateless tool execution — parses `AIMessage.tool_calls`, no reasoning loop |\n| **`create_agent`** | Subgraph node/node-internal subgraph needing tools + autonomous reasoning (ReAct) loop |\n| **`create_deep_agent`** | Subgraph node/node-internal subgraph needing subagent delegation, backends, or sandbox |\n| **Custom Node** | `BaseNode`/`AsyncBaseNode` — single deterministic operation, user-defined logic |\n\n### Reference Pattern Categories\n\nThe `developing-cast` skill includes patterns for every major LangGraph concern:\n\n| Category | Patterns |\n|----------|----------|\n| **Core** | State, sync/async nodes, conditional edges, subgraph composition |\n| **Agents** | `create_agent` with tools, structured output, multi-agent networks |\n| **Memory** | Short-term (conversation history, trimming, summarization), long-term (Store API) |\n| **Middleware** | Retry, fallback models, guardrails, call limits, human-in-the-loop, context editing |\n| **Observability** | LangSmith integration, structured logging |\n| **Integrations** | Embeddings, vector stores (FAISS/Pinecone/Chroma), text splitters |\n\n## The CLAUDE.md Feedback Loop\n\nThe key to keeping agents aligned across sessions is the `CLAUDE.md` spec. `architecting-act` generates it; `developing-cast` reads it.\n\n```\nRoot /CLAUDE.md          ← Act overview, purpose, table of all Casts\nCast /casts/{cast}/CLAUDE.md  ← Architecture diagram, node specifications for this Cast\n```\n\nThe CLAUDE.md is not static documentation — it is a **living specification** that:\n- Gets generated by the architecture skill with diagrams and node specs\n- Gets read by the implementation skill as the source of truth\n- Gets updated by the architecture skill when you add casts, extract sub-casts, or redesign\n- Gets synced to match existing code when you use Mode 4 (Redesign Cast)\n\nThis loop is the harness feedback mechanism: every agent session anchors to the same spec, producing consistent output regardless of who prompts it.\n\n## Architecture Diagram Kit (Drawkit)\n\nThe `drawkit.xml` file scaffolded in every Act project provides pre-defined [draw.io](https://app.diagrams.net/) shapes for designing Act architecture visually.\n\n\u003e **Note**: Drawkit is for **human-to-human communication** — sharing architecture with teammates, stakeholders, or documentation.\n\u003e For **agent-to-agent communication**, use the Mermaid charts in `CLAUDE.md` generated by `@architecting-act`.\n\u003e For **runtime inspection**, use the LangGraph Development Server (LangSmith).\n\nImport `drawkit.xml` into draw.io's Scratchpad to get drag-and-drop Act components. See `TEMPLATE_README.md` in your generated project for detailed import instructions and examples.\n\n## Skill-Driven Development Flow\n\n```mermaid\nsequenceDiagram\n    participant U as Developer\n    box rgba(100, 149, 237, 0.15) Agent Skills (Harness)\n        participant AA as architecting-act\n        participant DC as developing-cast\n        participant DD as developing-deepagent\n        participant SC as streaming-cast\n        participant TC as testing-cast\n    end\n    participant P as Act Project\n\n    Note over U,P: Phase 1 — Architecture (Harness: design decisions + CLAUDE.md)\n    U-\u003e\u003eAA: \"Design a customer support chatbot\"\n    AA-\u003e\u003eU: AskUserQuestion (purpose, pattern, node composition)\n    U-\u003e\u003eAA: Answer selections\n    AA-\u003e\u003eP: Write CLAUDE.md (architecture spec + diagram + node specs)\n\n    Note over U,P: Phase 2 — Implementation (Harness: 50+ reference patterns)\n    U-\u003e\u003eDC: \"Implement the chatbot based on CLAUDE.md\"\n    DC-\u003e\u003eP: Read CLAUDE.md (architecture spec)\n    DC-\u003e\u003eP: state.py → nodes.py → conditions.py → optional modules → graph.py\n    DC-\u003e\u003eP: Install dependencies (uv add)\n\n    opt Nodes using create_deep_agent\n    U-\u003e\u003eDD: \"Implement DeepAgent components\"\n    DD-\u003e\u003eP: Read CLAUDE.md (agent node specs)\n    DD-\u003e\u003eP: backend → tools → subagents → middleware → agent assembly\n    end\n\n    opt Streaming required\n    U-\u003e\u003eSC: \"Add streaming to the chatbot cast\"\n    SC-\u003e\u003eP: Read graph.py (graph structure)\n    SC-\u003e\u003eP: Stream mode selection → StreamWriter → subgraph/agent streaming\n    end\n\n    Note over U,P: Phase 3 — Testing (Harness: mocking strategies + coverage guides)\n    U-\u003e\u003eTC: \"Write tests for the chatbot cast\"\n    TC-\u003e\u003eP: Read implementation code\n    TC-\u003e\u003eP: Node unit tests + Graph integration tests\n    TC-\u003e\u003eP: uv run pytest --cov\n```\n\n## Workflow Examples\n\n**Example 1: Starting a New Project**\n```plaintext\n1. Create Project   → uvx --from act-operator act new\n\n2. Design           → \"Design a customer support chatbot\"\n   (architecting-act Mode 1: asks about purpose, pattern, node composition\n    → generates /CLAUDE.md + /casts/chatbot/CLAUDE.md with diagram and node specs)\n\n3. Implement        → \"Implement the chatbot based on CLAUDE.md\"\n   (developing-cast: reads CLAUDE.md → implements state/nodes/agents/graph)\n\n4. Add Streaming    → \"Add streaming to the chatbot cast\"\n   (streaming-cast: stream mode selection → token streaming, subgraph streaming)\n\n5. Test             → \"Write comprehensive tests for the chatbot\"\n   (testing-cast: LLM mocking + node unit tests + graph integration tests)\n```\n\n**Example 2: Adding a Cast to an Existing Project**\n```plaintext\n1. Design New Cast  → \"Add a knowledge-base cast for document indexing\"\n   (architecting-act Mode 2: reads /CLAUDE.md for context → designs new cast\n    → updates root CLAUDE.md + creates /casts/knowledge-base/CLAUDE.md)\n\n2. Scaffold Cast    → uv run act cast -c \"knowledge-base\"\n   (per CLAUDE.md development commands)\n\n3. Implement        → \"Implement knowledge-base based on its CLAUDE.md\"\n   (developing-cast: reads cast CLAUDE.md → implements components)\n```\n\n**Example 3: Redesigning an Existing Cast**\n```plaintext\n1. Analyze          → \"The chatbot cast has grown complex, help me redesign it\"\n   (architecting-act Mode 4: reads graph.py, nodes.py, agents.py, conditions.py\n    → presents current architecture summary)\n\n2. Redesign         → Select scope: \"Change node composition, restructure routing\"\n   (architecting-act: proposes changes, waits for confirmation)\n\n3. Sync CLAUDE.md   → Updates CLAUDE.md to reflect the redesigned architecture\n   (developing-cast can now re-implement against the new spec)\n```\n\n**Example 4: Extracting a Sub-Cast**\n```plaintext\n1. Analyze Complexity → \"The chatbot cast has 12 nodes and feels tangled\"\n   (architecting-act Mode 3: identifies reusable validation logic)\n\n2. Extract          → \"Extract input validation into a separate sub-cast\"\n   (architecting-act: creates /casts/input-validator/CLAUDE.md\n    → updates parent cast CLAUDE.md with sub-cast references)\n\n3. Implement Sub-Cast → \"Implement input-validator\"\n   (developing-cast: implements sub-cast, manages dependencies via CLAUDE.md commands)\n```\n\n## Project Structure\n\n```\nmy_workflow/\n├── .claude/\n│   └── skills/                    # Harness: skills loaded by AI agents\n│       ├── architecting-act/      # Design phase: patterns, templates, validation\n│       ├── developing-cast/       # Implementation phase: 50+ reference patterns\n│       ├── developing-deepagent/  # DeepAgent phase: backends, subagents, sandbox\n│       ├── streaming-cast/        # Streaming phase: stream modes, subgraph streaming\n│       └── testing-cast/          # Testing phase: mocking, fixtures, coverage\n├── casts/\n│   ├── base_node.py              # Base node class (sync/async, signature validation)\n│   ├── base_graph.py             # Base graph class (abstract build method)\n│   └── chatbot/                  # A Cast (graph package)\n│       ├── CLAUDE.md             # Living spec: architecture diagram + node specs\n│       ├── modules/\n│       │   ├── state.py          # [Required] InputState, OutputState, State\n│       │   ├── nodes.py          # [Required] Node implementations\n│       │   ├── agents.py         # [Optional] Agent configurations (create_agent)\n│       │   ├── tools.py          # [Optional] Tool definitions / MCP adapters\n│       │   ├── models.py         # [Optional] LLM model configs / structured output\n│       │   ├── conditions.py     # [Optional] Routing conditions\n│       │   ├── middlewares.py    # [Optional] Lifecycle hooks\n│       │   ├── prompts.py        # [Optional] Prompt templates\n│       │   └── utils.py          # [Optional] Helper functions\n│       ├── graph.py              # Graph assembly → entry point\n│       └── pyproject.toml        # Cast-specific dependencies\n├── tests/\n│   ├── cast_tests/               # Graph integration tests\n│   └── node_tests/               # Node unit tests\n├── CLAUDE.md                     # Root spec: Act overview + Cast index\n├── drawkit.xml                   # draw.io shapes for architecture diagrams\n├── langgraph.json                # LangGraph entry points\n├── pyproject.toml                # Monorepo workspace (uv workspace, shared deps)\n└── TEMPLATE_README.md            # Template usage guide\n```\n\n### Module Dependency\n\n```mermaid\ngraph TD\n    LG[\"graph.py\"] --\u003e|inherits| BG[\"base_graph.py\"]\n    LG --\u003e|imports| S[\"state.py\"]\n    LG --\u003e|imports| N[\"nodes.py\"]\n    LG --\u003e|imports| CD[\"conditions.py\"]\n    N --\u003e|inherits| BN[\"base_node.py\"]\n    N -.-\u003e|optional| A[\"agents.py\"]\n    N -.-\u003e|optional| U[\"utils.py\"]\n    A -.-\u003e|uses| M[\"models.py\"]\n    A -.-\u003e|uses| P[\"prompts.py\"]\n    A -.-\u003e|uses| T[\"tools.py\"]\n    A -.-\u003e|uses| MW[\"middlewares.py\"]\n\n    classDef required fill:#4a9eff,stroke:#2d7cd6,color:#fff\n    classDef optional fill:#a0a0a0,stroke:#808080,color:#fff\n    classDef base fill:#34c759,stroke:#28a745,color:#fff\n    classDef entry fill:#ff9500,stroke:#e68a00,color:#fff\n\n    class LG entry\n    class G,S,N required\n    class BG,BN base\n    class CD,A,T,MW,M,P,U optional\n```\n\n\u003e **Legend**: 🟠 Entry Point / 🔵 Required / 🟢 Base Class / ⚫ Optional\n\n### Execution Flow\n\nThe runtime contract the harness is built around: each node reads state, returns a partial update, and the graph merges it.\n\n```mermaid\nsequenceDiagram\n    participant G as Graph\n    participant N as Node (BaseNode)\n    participant St as State\n\n    G-\u003e\u003eSt: Initialize State from InputState\n    loop For each node in graph\n        G-\u003e\u003eN: node.__call__(state, config, runtime)\n        N-\u003e\u003eN: execute(state, ...) → dict\n        N-\u003e\u003eSt: Merge returned dict into State\n    end\n    G-\u003e\u003eG: Extract OutputState → Result\n```\n\n## CLI Commands\n\n```bash\n# Create new Act project\nact new [OPTIONS]\n  --act-name TEXT       Project name\n  --cast-name TEXT      Initial cast name\n  --path PATH           Target directory\n  --lang TEXT           Language for scaffolded docs (en|kr)\n\n# Add cast to existing project\nact cast [OPTIONS]\n  --cast-name TEXT      Cast name\n  --path PATH           Act project directory\n  --lang TEXT           Language for scaffolded cast docs (en|kr)\n\n# Upgrade skills in an existing Act project\nact upgrade [OPTIONS]\n  --path PATH           Act project directory (default: current directory)\n```\n\n### `act upgrade`\n\nUpdates `.claude/skills/` in an existing Act project to the latest version bundled with Act Operator. This is useful when a new version of Act Operator ships improved or additional skills.\n\n- Auto-detects the project language (English/Korean) from `README.md`\n- Auto-detects the first Cast from `langgraph.json`\n- Backs up existing skills to `.claude/skills.bak/` before replacing\n\n```bash\n# Upgrade skills in the current directory\nact upgrade\n\n# Upgrade skills in a specific project\nact upgrade --path ./my-act-project\n```\n\nAfter scaffolding, see `TEMPLATE_README.md` in your generated project for detailed usage — dependency management, development server, graph registry configuration, and more.\n\n## Contributing\n\nWe welcome contributions from the community! Please read our contributing guide:\n\n- [CONTRIBUTING.md](CONTRIBUTING.md) (English)\n\n### Contributors\n\nThank you to all our contributors! Your contributions make Act Operator better.\n\n\u003ca href=\"https://github.com/Proact0/act-operator/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=Proact0/act-operator\" /\u003e\n\u003c/a\u003e\n\n## License\n\nApache License 2.0 - see [LICENSE](https://www.apache.org/licenses/LICENSE-2.0) for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003eBuilt with ❤️ by \u003ca href=\"https://www.proact0.org/\"\u003eProact0\u003c/a\u003e\u003c/p\u003e\n  \u003cp\u003eA non-profit open-source hub dedicated to standardizing Act (AX Template) and boosting AI productivity\u003c/p\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproact0%2Fact-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fproact0%2Fact-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproact0%2Fact-operator/lists"}