English | 한국어
Agent Workflow Orchestration installs a consistent role-based AI workflow for Cursor, Codex, and Claude. It does not provide an agent runtime. Instead, it lays down role contracts, target-specific skill files, a harness-neutral Single Source of Truth, and resumable handoff state for AI-assisted planning, design, and implementation.
- Platform-neutral role contracts in
agent-workflow.manifest.json - Target adapters for Cursor, Codex, and Claude
- Role files for orchestrator, researcher, planner, designer, architect, developer, and reviewer workflows
- ADS feature documents:
articulate.md,designs.md, andspecs.md - Shared project configuration and specs in
.agent-workflow/ - Optional local or version-controlled continuity work items for model/session handoff
- Safe role-file updates with ownership hashes and sidecar preservation
- Once-daily interactive update notifications that never modify files automatically
Role assignment is not a fixed sequence. The orchestrator reads each role's declared capabilities, produces, and consumes from the manifest, picks the roles whose inputs are already satisfied, and recomputes the selection after every step. Declaring a new role makes it dispatchable without editing any routing table.
Each feature is managed as a folder under the target specs directory:
.agent-workflow/specs/features/user-onboarding/
├── articulate.md
├── designs.md
└── specs.md
articulate.md: product intent. The planner acts as the driver and works with the user to capture why the feature is needed, who it serves, goals, non-goals, constraints, and success criteria.designs.md: UI/UX detail. The designer converts the articulate document into flows, states, information architecture, accessibility requirements, and design decisions.specs.md: implementation reference. The developer turns articulate and designs into concrete implementation context that an AI coding agent can use to plan and produce code.
The documents are not one-time handoffs. They can be revised during development whenever discussion with the user changes product intent, design behavior, or implementation requirements.
| Target | Runtime files | Shared Specs Path |
|---|---|---|
cursor |
.cursor/skills/*/SKILL.md |
.agent-workflow/specs/ |
codex |
.agents/skills/role-orchestrator/SKILL.md, .codex/agents/role-*.toml, .codex/config.toml, managed AGENTS.md block |
.agent-workflow/specs/ |
claude |
.claude/skills/role-orchestrator/SKILL.md, .claude/agents/role-*.md |
.agent-workflow/specs/ |
Multiple targets can be installed in one project. Their role files read the same harness-neutral specs and continuity state.
How much a target enforces differs, and the contract text is the same either way.
Run doctor to see what your target actually enforces.
| Target | Per-role tool allowlist | Notes |
|---|---|---|
claude |
Enforced — rendered into each subagent's tools: |
Skills are all-or-nothing: withholding the Skill tool is the only boundary the runtime honors |
codex |
Not enforced — only sandbox_mode and web_search exist |
A role's required_tools is contract text |
cursor |
Not enforced — no mapping is configured | Contracts pass through verbatim; required_tools is contract text |
No role is granted a subagent-spawning tool on any target. A role that needs
another role returns needs and the orchestrator assigns it.
npx @hankim.dev/agent-workflow-orchestration install --target cursor
npx @hankim.dev/agent-workflow-orchestration install --target codex
npx @hankim.dev/agent-workflow-orchestration install --target claudeThe default target is cursor. Installing another target adds its files without deleting existing target content.
Package-owned full files are recorded with their package version and SHA-256 ownership hash. For Codex, the CLI preserves unknown TOML keys and comments, adds only missing compatible multi-agent keys, and manages only a uniquely marked block in AGENTS.md. Conflicting shared values or unowned files abort the operation before the Codex payload is written; --force does not overwrite unowned shared content.
Global installation is also supported:
npx @hankim.dev/agent-workflow-orchestration install --target cursor --global
npx @hankim.dev/agent-workflow-orchestration install --target codex --globalGlobal Codex files use ~/.agents/skills, ~/.codex/agents,
~/.codex/config.toml, and the managed block in ~/.codex/AGENTS.md.
Use an explicit @latest when you want npx to fetch the current CLI:
npx @hankim.dev/agent-workflow-orchestration@latest updateProject update refreshes every target recorded in .agent-workflow/.local/state.json. Select one target with --target. Global role files require an explicit target:
npx @hankim.dev/agent-workflow-orchestration@latest update --target codex
npm install -g @hankim.dev/agent-workflow-orchestration@latest
agent-workflow-orchestration update --global --target codexCodex updates migrate package-owned legacy .codex/skills/role-*/AGENT.md files to the official structure. The four standard files generated by the published 1.0.0 package are recognized by exact SHA-256 hashes. Other legacy files are removed only when their recorded hash or complete contents prove package ownership; sidecars are preserved. Custom-specs or edited legacy files stop the update and report the path for manual review. For other 1.0.x target files without ownership hashes, perform the first migration explicitly:
npx @hankim.dev/agent-workflow-orchestration@latest update --forceupdate and uninstall preflight package ownership and Codex shared-file entries. Modified, missing, conflicting, or unprovable files abort before target files are changed. --force may restore a recorded package-owned full file, but never silently replaces or deletes unowned Codex shared content.
Existing TOML comments, unknown keys, dotted managed keys, and CRLF line
endings are preserved. Inline-table definitions of features or agents,
disabled required flags, and a thread cap below three are reported as conflicts
instead of being rewritten.
Codex skips the entire .codex/ layer in an untrusted project, so custom agents
and the merged config are ignored even when the files are installed correctly.
Trust is inherited by subdirectories of a trusted path.
After a Codex install or update, open the project as trusted and start a new
Codex session. Confirm role-orchestrator with /skills and active custom
agent threads with /agent.
doctor reports trust state so an installed-but-inactive target is diagnosable:
agent-workflow-orchestration doctor --target codex[warn] codex project trust: not trusted; Codex skips .codex/ entirely, ...
The .agents/skills/ orchestrator skill is outside .codex/ and loads without
trust.
Create the shared specs directory and example ADS documents:
npx @hankim.dev/agent-workflow-orchestration initGenerated structure:
your-project/
├── .cursor/
│ └── skills/
│ │ ├── role-orchestrator/SKILL.md
│ │ ├── role-researcher/SKILL.md
│ │ ├── role-planner/SKILL.md
│ │ ├── role-designer/SKILL.md
│ │ ├── role-architect/SKILL.md
│ │ ├── role-developer/SKILL.md
│ │ └── role-reviewer/SKILL.md
└── .agent-workflow/
├── workflow.json
├── .gitignore
└── specs/
│ ├── README.md
│ ├── features/
│ │ └── _example-feature/
│ │ ├── articulate.md
│ │ ├── designs.md
│ │ └── specs.md
│ ├── changes/_example-change.md
│ └── decisions/000-example-decision.md
npx @hankim.dev/agent-workflow-orchestration feature --name user-onboardingThis creates:
.agent-workflow/specs/features/user-onboarding/
├── articulate.md
├── designs.md
└── specs.md
Existing feature documents are preserved by default. Use --force to overwrite them.
workflow.json.specsRoot controls the shared specs location. It must be a project-relative path that remains inside the project:
{
"schemaVersion": 2,
"specsRoot": "docs/agent-specs",
"continuity": { "storage": "local" },
"migrations": []
}Import existing target-specific specs without changing their source files:
agent-workflow-orchestration import --from cursor --dry-run
agent-workflow-orchestration import --from cursorCreate and resume a work item after its feature exists:
agent-workflow-orchestration work --name implement-onboarding --feature user-onboarding
agent-workflow-orchestration advance --name implement-onboarding --phase implementation --role role-developer --next-role role-reviewer
agent-workflow-orchestration resume --name implement-onboardingwork records Developer as the default next role. Use --next-role <role> or --next-role none on work and advance to persist the actual handoff.
By default, work items are stored below .agent-workflow/.local/ and excluded from version control. Set "continuity": { "storage": "project" } in .agent-workflow/workflow.json to share new work items through the repository. resume, advance, and forced work-item refreshes search both locations, so changing this setting does not strand existing work. If the same ID exists in both locations, the command stops and prints both paths.
For legacy target specs, preview conflicts before importing. The source is never removed:
agent-workflow-orchestration import --from cursor --dry-run
agent-workflow-orchestration import --from cursorInteractive TTY runs check the npm latest tag at most once per day with an 800 ms timeout. Failures are cached for one hour and never affect the command result. CI and non-TTY runs skip the check. Set AGENT_WORKFLOW_NO_UPDATE_CHECK=1 or NO_UPDATE_NOTIFIER=1 to disable it.
The notification is advisory only. It never updates the package or generated files. Because 1.0.0 did not contain this checker, the first 1.1.0 migration must be discovered through the GitHub Release or these instructions.
agent-workflow-orchestration install --target cursor
agent-workflow-orchestration install --target codex
agent-workflow-orchestration update
agent-workflow-orchestration init
agent-workflow-orchestration feature --name payment-retry
agent-workflow-orchestration work --name payment-retry-implementation --feature payment-retry
agent-workflow-orchestration resume --name payment-retry-implementation
agent-workflow-orchestration doctor --target claude
agent-workflow-orchestration list
agent-workflow-orchestration validateChecks target readiness:
- target runtime paths (including Codex skill, agents, config, and guidance)
- shared specs and workflow configuration
- available legacy specs imports
- installed target role files
package.jsonscripts forlint,test, andtypecheck
Checks package consistency:
- role contracts and required output keys
- target adapter rendering
- required template files
- package metadata
You do not need to validate this workflow only by running mini projects. The package has layered checks:
npm run validate: verifies manifest, role files, adapters, templates, and package metadata.npm run check:readme: verifies English/Korean README links and important command references.npm run test:smoke: creates temporary fixtures and checks ownership hashes, sidecar safety, shared specs, legacy import, continuity resume, and safe updates/removal.npm run test:update-check: uses a local mock registry and fake clock to cover update availability, cache, timeout, offline, CI, and opt-out behavior without accessing the real registry.npm run check: runs all of the above.
Mini projects are still useful as final acceptance tests, but the core workflow is covered by automated fixture tests.
npm run validate
npm run check:readme
npm run test:smoke
npm run test:update-check
npm run check- Keep role contract changes synchronized across
agent-workflow.manifest.jsonandskills/. - If target behavior changes, update
adapters/,bin/cli.js,templates/, andscripts/fixture-smoke.js. - If CLI output or generated structure changes, update both
README.mdandREADME.ko.md. - Run
npm run checkbefore publishing or opening a PR.
- Cursor, Codex, or Claude
- Node.js >= 14.14.0
MIT