Skip to content

About

Agent Workflow Orchestration installs a consistent role-based AI workflow for Cursor, Codex, and Claude.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Agent Workflow Orchestration

npm version

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.

What It Provides

  • 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, and specs.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.

ADS Workflow

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.

Targets

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.

Install

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 claude

The 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 --global

Global Codex files use ~/.agents/skills, ~/.codex/agents, ~/.codex/config.toml, and the managed block in ~/.codex/AGENTS.md.

Update Existing Installations

Use an explicit @latest when you want npx to fetch the current CLI:

npx @hankim.dev/agent-workflow-orchestration@latest update

Project 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 codex

Codex 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 --force

update 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 requires project trust

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.

Initialize Specs

Create the shared specs directory and example ADS documents:

npx @hankim.dev/agent-workflow-orchestration init

Generated 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

Create a Feature

npx @hankim.dev/agent-workflow-orchestration feature --name user-onboarding

This 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": []
}

Continuity And Migration

Import existing target-specific specs without changing their source files:

agent-workflow-orchestration import --from cursor --dry-run
agent-workflow-orchestration import --from cursor

Create 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-onboarding

work 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 cursor

Update Notifications

Interactive 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.

CLI

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 validate

doctor

Checks 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.json scripts for lint, test, and typecheck

validate

Checks package consistency:

  • role contracts and required output keys
  • target adapter rendering
  • required template files
  • package metadata

Verification Strategy

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.

Local Development

npm run validate
npm run check:readme
npm run test:smoke
npm run test:update-check
npm run check

Contributing

  1. Keep role contract changes synchronized across agent-workflow.manifest.json and skills/.
  2. If target behavior changes, update adapters/, bin/cli.js, templates/, and scripts/fixture-smoke.js.
  3. If CLI output or generated structure changes, update both README.md and README.ko.md.
  4. Run npm run check before publishing or opening a PR.

Requirements

  • Cursor, Codex, or Claude
  • Node.js >= 14.14.0

License

MIT

About

Agent Workflow Orchestration installs a consistent role-based AI workflow for Cursor, Codex, and Claude.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages