Portable Agent Workflows

Portable Agent Workflows is a harness-agnostic workflow layer for coding agents. It defines a shared vocabulary, portable skills, adapter mappings, persistent artifacts, and generated native entrypoints so Codex, OpenCode, Claude Code, Cursor, and similar harnesses can follow the same workflow model without sharing tool names or hidden chat state.

Origins

This model combines the strongest ideas from obra/superpowers and DasDigitaleMomentum/opencode-processing-skills: explicit skill workflows, durable planning artifacts, review gates, handovers, and harness-specific adapters. It does not copy either system directly; it defines a clean agent-work-v1 domain model that can be used across Codex, OpenCode, Claude Code, Cursor, and future harnesses.

What This Repository Is

• A portable workflow and artifact model for coding agents.
• A set of harness-agnostic skills under .agent-work/skills/.
• A generated integration layer for Codex, Claude Code, and Cursor.
• A project-local npm initializer for Codex, Claude Code, Cursor, and OpenCode.
• A governance-backed reference repository for agent-work-v1.

What This Repository Is Not

• It is not a runtime library or global installer.
• It is not tied to one agent harness.
• It does not mutate GitHub repository settings automatically.

Public Project Status

Portable Agent Workflows is a public, MIT-licensed, open-source reference model. It is ready for evaluation, issues, and focused pull requests that improve the agent-work-v1 model, documentation, validation, or generated harness entrypoints. The GitHub Community Profile is complete: README, license, contributing guide, Code of Conduct, issue template, pull request template, and contributor content reporting are in place.

The main reader path is this README, then docs/overview.md, then the .agent-work/ source artifacts. docs/superpowers/ records design and planning history; it is kept for transparency, not as the primary product documentation path.

Enterprise Readiness

• PR-first governance is documented in CONTRIBUTING.md.
• Security reporting is documented in SECURITY.md.
• Community standards are documented in CODE_OF_CONDUCT.md.
• License terms are published in LICENSE.
• Releases follow the release policy.
• Release history is tracked in CHANGELOG.md.
• Compatibility is governed by the compatibility policy.
• Deprecations follow the deprecation policy.
• Recommended repository settings are documented in GitHub settings.
• Supported harnesses are tracked in the compatibility matrix.

Quality Gates

npm run check:node
uv run python tools/generate_harness_integrations.py --check
uv run pytest tests/ -v
uv run ruff check tests/ tools/
uv run ruff format --check tests/ tools/
uv run python tools/check_markdown_links.py
git diff --check

What Is Included

• .agent-work/glossary.md defines the agent-work-v1 domain model.
• .agent-work/adapters/ maps neutral roles and capabilities to Codex, OpenCode, Claude Code, and Cursor.
• .agent-work/skills/ contains the eleven V1 portable skills.
• .agent-work/plans/portable-agent-work-example/ demonstrates the full artifact lifecycle.
• package.json, bin/, and src/ publish the portable-agent-workflows and paw npm commands.
• AGENTS.md, CLAUDE.md, .claude/commands/, .cursor/rules/, and .opencode/commands/ provide native harness entrypoints.
• docs/superpowers/ records design and planning history for major changes.
• tools/generate_harness_integrations.py regenerates native harness files from .agent-work/.
• tools/check_markdown_links.py validates local Markdown links.
• tests/ validates model structure, generated files, and enterprise foundation artifacts.
• docs/ documents architecture, governance, reference material, modules, and features.

Core Ideas

• Skills describe behavior.
• Artifacts store durable state.
• Roles define responsibility.
• Capabilities define what a harness can do.
• Adapters translate neutral intent into concrete harness execution.
• Later agents should be able to continue from files, not hidden chat context.

Quickstart

Install project-local workflow files into another repository:

npx portable-agent-workflows init

For non-interactive installs, select harnesses explicitly:

npx portable-agent-workflows init --harness codex,claude,cursor,opencode --yes
npx portable-agent-workflows check

See Distribution for safety rules, dry runs, overwrite behavior, and publishing boundaries.

Install development dependencies with uv:

uv sync --dev

Run validation:

npm run check:node
uv run python tools/generate_harness_integrations.py --check
uv run pytest tests/ -v
uv run ruff check tests/ tools/
uv run ruff format --check tests/ tools/
uv run python tools/check_markdown_links.py

Supported Harnesses

See the compatibility matrix for current support status.

Documentation

• Start here: Project overview
• Governance: Release policy, Compatibility policy, Deprecation policy, ADRs
• Administration: GitHub settings
• Reference: Compatibility matrix, Distribution
• Modules: Domain model, Adapters, Harness generator, Skills, Lifecycle example, Validation tests
• Features: Generated harness integration, Portable skill lifecycle, Artifact validation, Harness adapters

V1 Skills

• define-domain-model
• shape-idea
• shape-spec
• create-phased-plan
• verify-implementation-plan
• execute-work-package
• review-artifact
• review-implementation
• update-work-state
• create-handover
• write-portable-skill

Repository Status

This repository is a documentation-and-artifact model with a small npm initializer. It does not ship an importable runtime library; the CLI only installs and verifies project-local workflow files. The tests validate that the package, generated files, and artifacts remain structurally coherent.