Company Worktask Plugin

imageOS imageClaude Code imageCodex

A staged worktask system for Claude Code and Codex — 9 stages standard, 11 with --secure — with a durable state ledger, worktree-isolated execution behind two human approval gates (plan + finalization), stage transitions, and structured task management.

Plugin 4.1.3 · Requires Claude Code 2.1.303+ · Verified with Codex CLI 0.156.1

Features

• Worktree-isolated + two approval gates (plan + finalization): every worktask runs in a dedicated git worktree and STOPs twice — once after planning to approve the plan (plan_gate: "checkpoint"; skipped by --auto=[plan] / --emergency) and once before finalization to approve commit/push/PR (fn_gate: "checkpoint"; skipped by --auto=[finalization] / --emergency). By default FN STOPs before any commit/push/PR; --auto=[finalization] finalizes unattended. The values are orthogonal — plan skips only the plan gate, never the FN gate; the third value, --auto=[decision], skips no gate but delegates PL open questions to a Fable-model decision pass instead of the user. Changes are reviewable as PRs. (Batch runs via /megatask stamp both gates "bypass" directly per issue — see the Megatask feature below.)
• /megatask — dependency-DAG batch orchestration: run many worktasks across a GitHub milestone (/megatask N) or an explicit issue array (/megatask --issues 12,15,18). Parses Depends on: / Blocks: + P0–P3 labels into a DAG, executes in topological + priority order (never starting an issue whose blockers are unmerged), isolates each issue in its own worktree, and drives completion via the megatask-monitor hook (unblock-dependents + progress). One human checkpoint: the R1 batch confirmation.
• 9-Stage Worktask: Planning → Architecture → Team Lead → Development → Developer Review → QA → Documentation → Finalization → Stakeholder
• State Ledger: .context/state.json tasks{} — one durable ledger, written only through state-patch.sh
• Native Dependencies: blocked_by arrays for explicit dependency management
• Durable by construction: the ledger is a file in the worktask folder, so it survives sessions, compaction, and resume
• Dynamic Task Creation: PL0 seeds subsequent stage tasks based on complexity assessment
• Error Handling: Retry logic (max 3 per stage) and escalation chains
• Sub-agent Visibility: every agent reads the same ledger
• Agent-Specific Commands: Specialized commands for each worktask role
• Ethics Review: Optional constitutional compliance checkpoint for high-risk features

State Ledger

Stage state lives in .context/state.json under tasks{}, keyed by stage id (PL0, DV0, DV1). All writes go through skills/worktask/scripts/state-patch.sh, which owns the merge lock, the atomic write, and the disk guard.

Key Benefits

• Durable: a file in the worktask folder — survives sessions, compaction, and resume with no configuration
• Native dependencies: blocked_by arrays, resolved by the orchestrator loop
• Sub-agent visibility: every agent reads the same ledger
• Parallel-track safe: numbered keys mean DV0 and DV1 are distinct entries, not a collision
• Metadata support: routing, gates, and dispatch config per task

corpflow does not use Claude Code's TaskCreate/TaskUpdate/TaskGet/TaskList tools. No current model (Opus 5.5, Sonnet 5.5, Haiku 5.5 or Fable 5.x) is offered them, so the ledger is the one mechanism that works on every stage. See skills/shared/state-ledger.md.

Installation

Requirements

Tools listed below are organized by status (required, optional, platform-specific) with their degradation mode — what capability is lost if the tool is missing. All tool invocations in the repository are derived from actual call sites, not assumed.

Hard requirements — your worktask will not complete without these

The jq split behavior, explained: hooks/agent-stop.sh (line 30) exits 0 when jq is missing — hook skips with "jq not found, skipping" message — so you can still run worktasks. state-patch.sh (line 1777, the main patch path at 1833) exits 2 when jq is missing — ledger write fails and blocks the entire stage — so the ledger stays unchanged. Both behaviors are correct for their context: hooks must never block the orchestrator; the ledger writer must never silently skip. If you see "jq required" errors in your logs, you cannot proceed until jq is installed.

Strongly recommended — your worktask is slower or incomplete without these

Platform-specific tools — degrade gracefully on other platforms

Screenshot capture (on-demand per platform)

Screenshot capture at the DV stage pulls in per-platform tooling on demand (ImageMagick, pngquant, Playwright, a Swift toolchain on macOS). None of it is needed to install or to run a worktask; see skills/dv-screenshot-capture/SKILL.md for what each capture path expects.

New tools in this release

Install with Claude Code

This repository is both a Claude Code marketplace (agnidia) and the plugin it publishes (corpflow). From inside Claude Code:

/plugin marketplace add Agnidia/corpflow
/plugin install corpflow@agnidia

The plugin activates as soon as it is safe to do so; if the commands do not appear, run /reload-plugins. Hooks — including the SubagentStop state-merge safety net — are registered by .claude-plugin/plugin.json on install. There is no manual hook step.

Install with Codex

codex plugin marketplace add https://github.com/Agnidia/corpflow.git
codex plugin add corpflow@agnidia

Start a new Codex thread after installation, review and trust the bundled hooks, then invoke workflows as skills: $request-plan, $worktask, $arch-review, and the other command names. Codex hooks use its native PLUGIN_ROOT/PLUGIN_DATA environment; Corpflow normalizes those to BASE_PLUGIN_ROOT/BASE_PLUGIN_DATA before shared logic runs.

Upgrade from the igrsoft marketplace

The marketplace id is now agnidia. If you installed corpflow@igrsoft, remove the old marketplace and install again:

/plugin marketplace remove igrsoft
/plugin marketplace add Agnidia/corpflow
/plugin install corpflow@agnidia

Then rename the corpflow@igrsoft key to corpflow@agnidia in every enabledPlugins map that names it. In Codex, remove the old plugin and marketplace, then add the new ones. These steps were verified on Codex CLI 0.163.0; the two remove commands are not checked on 0.156.1:

codex plugin remove corpflow@igrsoft
codex plugin marketplace remove igrsoft
codex plugin marketplace add https://github.com/Agnidia/corpflow.git
codex plugin add corpflow@agnidia

Verify

Claude Code's /plugin or Codex's codex plugin list should show corpflow. /worktask should autocomplete in Claude Code and $worktask should be available in Codex. Then run the host-native planning entrypoint:

/request-plan "add a dark mode toggle to settings"

In Codex, use $request-plan "add a dark mode toggle to settings" instead.

A plan comes back without touching the repo — the cheapest end-to-end check that agents, skills, and routing all resolved.

Optional — platform plugins

The DV stage routes to whichever platform plugin matches the repo, and falls back to project tooling when none is installed. Each is a separate marketplace under the same org, installed the same way (/plugin marketplace add Agnidia/<name> then /plugin install <name>@<name>):

Version floors and the routing contract live in skills/shared/compatible-plugins.md.

Routing overrides

Alias→plugin routing is canonical in skills/shared/routing-matrix.md — one row per platform entry point and functional role (corpflow:apple-developer → apple-developer:apple-developer, corpflow:web-code-fixer → frontend-developer:fe-code-fixer, …). A project can swap any of them: copy skills/cross-plugin-handoff/templates/PROJECT-CORPFLOW.md to the project root as CORPFLOW.md, keep only the rows you override under ## Routing, and the next worktask resolves through your targets instead. The same file at ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/CORPFLOW.md applies to every project; a project-root file wins per heading (## Routing, ## Models), so a project overrides only what it names:

## Routing

| Alias | Target |
|-------|--------|
| `corpflow:apple-developer` | `my-org-apple:apple-developer` |
| `corpflow:apple-code-fixer` | `my-org-apple:code-fixer` |

Overrides resolve once at worktask init (persisted as state.routing); uninstalled targets fall back to the default with a plugin_unavailable audit row.

From source

For contributing, or to run the plugin from a working tree:

git clone https://github.com/Agnidia/corpflow.git
cd corpflow
make bootstrap     # vendor bats, check the swift toolchain, probe kcov
make test          # offline suite — no API calls, no spend

Then point Claude Code at the checkout with /plugin marketplace add /path/to/corpflow and install as above.

Quick Start

Launching a Worktask

Run the worktask command:

/worktask "[task description]"   # The worktask pipeline — PL0 dynamic sizing picks stages

/worktask is the single-issue entry point. PL0 sizes the pipeline by complexity (dropping AR/TL/DC for small tasks). Use --auto=[plan] to skip the plan-approval stop; --auto=[finalization] to skip the finalization-approval stop (auto commit/push/PR); --auto=[decision] to let a Fable-model delegate answer PL0's open questions; combine as --auto=[plan, decision, finalization] for a fully unattended run (escalation-class questions still stop). Use --emergency for the incident pipeline (skips both gates). You can also launch via Skill({skill:"corpflow:worktask"}). For multi-issue batches, use /megatask N (a milestone) or /megatask --issues 12,15,18 (an array) — it orders by a dependency/blocker DAG and runs each issue unattended.

/worktask sets up the worktask context, the state ledger, and stage management.

Examples

/worktask "Add dark mode to settings"
/worktask "/apple-developer:fix-modernize migrate @StateObject to @Environment"
/worktask "/system-developer:fix-modernize . --target cpp23"

Combining with Other Commands

You can embed slash commands within the worktask payload. The orchestrator will:

1. Set up the context and planning
2. Detect the embedded /command pattern and store it in metadata.embedded_commands
3. Pass the command to the DV stage agent, which invokes it via the Skill tool
4. The embedded command's output feeds into the DV stage implementation

Embedded commands are detected by matching /<name> or /<plugin:name> patterns against available skills. The command arguments are preserved and passed through.

/worktask "/apple-developer:fix-refactor src/Views/SettingsView.swift"
/worktask "/code-review PR #123"

Options

/worktask

Gate automation — --auto=[<values>] takes an array of any subset of plan, decision, finalization (brackets optional, e.g. --auto=plan,decision). Each value is independent:

Scope and pipeline flags:

/megatask

Pipeline Sizing

Single entry point (/worktask). PL always runs; PL0 dynamic sizing scores complexity (0–50) and creates only the stages the work needs:

+ TL — only when PL0 splits the work across ≥2 developers (see Stage Inclusion Criteria in skills/estimation-methodology/SKILL.md)

--secure / --full forces the 11-stage path (SR after DR, RE before FN). Security-sensitive features auto-include SR regardless of score.

9-Stage Worktask

Ledger Initialization

Only PL0 is seeded at startup. PL0 seeds subsequent stage tasks after planning:

# Seed PL0 only — the PL agent seeds remaining stages after planning.
state-patch.sh --task-create PL0 --metadata '{
  "stage":"PL","agent":"corpflow:product-manager",
  "description":"Define requirements, assess complexity, seed stage tasks",
  "worktask_id":"dark-mode","priority":"medium"}'

state-patch.sh --task-status PL0 in_progress

# After planning, PL0 seeds stages based on complexity:
# AR0, DV0, QA0, … — each with metadata.agent for executor resolution.
# Stage agents can split into sub-tasks: DV0 → DV1, DV2

Context Folder Structure

.context/
├── planning-0.md            # PL stage (run 0; subsequent PL runs add planning-1.md, planning-2.md, …)
├── architecture-0.md           # AR stage (run 0)
├── coordination-0.md        # TL stage (run 0)
├── development-0.md         # DV stage (run 0)
├── developer-review-0.md    # DR stage (run 0)
├── security-review-0.md     # SR stage (run 0, secure/full variant)
├── testing-0.md             # QA stage (run 0)
├── documentation-0.md       # DC stage (run 0)
├── release-0.md             # RE stage (run 0, secure/full variant)
├── complete-summary-0.md    # FN stage (run 0)
├── retrospective-0.md       # ST stage (run 0)
├── state.json               # Worktask ledger (shared across runs)
├── errors/                  # Per-agent error narratives (if needed)
│   ├── developer.md         # DV retries
│   └── qa-engineer.md       # QA retries
├── designs/                 # Designer-generated .pen mockups
├── images/                  # User-attached visual assets
└── logs/                    # Raw runtime capture (build/test/monitor)

All stage artifacts follow the <basename>-N.md pattern where N equals task.metadata.run_index (stamped by PL0 on every downstream task). First run uses N=0.

Components

Agents

Commands

28 commands. Orchestration, planning, and publishing commands are unprefixed; the rest carry a stable domain prefix (design-, arch-, test-, docs-) naming the surface they act on.

Core / Orchestration

Design (design-)

Planning

Architecture (arch-)

Development

QA / Test (test-)

Docs (docs-)

Ethics

Authoring

Publishing

The store flows themselves live in the plugin that ships to that store (apple-developer:gen-appstore-*, android-developer:gen-playstore-*), because App Store Connect and Play Console differ field by field. --apple-platform selects an Apple device class and is passed through unchanged — it is deliberately distinct from the plugin-wide --platform.

Skills (24 total)

• agent-coordination — Multi-agent coordination, handoffs, parallel execution, error escalation
• claude-constitution — Constitutional principles and ethics framework
• code-comment-standard — Compact source-comment standard (WHY/contract only); loadable skill wrapping code-documentation.md
• context-compression — Context compression between agent handoffs
• cost-optimization — Token and cost tracking/optimization
• cross-plugin-handoff — Handoff protocol to external plugins; includes the add/replace-a-plugin checklist. Compatible dev plugins are registered in skills/shared/compatible-plugins.md (apple-developer, system-developer, android-developer, frontend-developer, backend-developer, ai-engineer)
• csv-export-templates — CSV export structure for Google Sheets import
• dv-screenshot-capture — DV-stage screenshot capture, attached to the PR as visual evidence
• estimation-methodology — Complexity scoring (0–50) and T-shirt sizing
• gh-issue-dedup — One GitHub issue per .context/; later runs comment instead of duplicating
• incident-response — Incident classification, hotfix worktask, rollback, post-mortem (IR)
• logging-conventions — Route runtime log capture to .context/logs/
• megatask — Dependency-DAG orchestration of many worktasks (the /megatask command)
• milestone-helpers — Helper patterns for milestone/megatask operations (ships from skills/shared/milestone-helpers/)
• pencil-design-worktask — Design mockup generation via Pencil MCP (Designer)
• preview-ensurer — Auto-add #Preview to modified SwiftUI views before snapshotting
• release-engineering — Semantic versioning, changelog, deployment readiness (RE)
• request-plan — Turn a free-form request into a lightweight, context-aware plan
• security-review-process — OWASP Top 10 checklist, dependency supply-chain triage, secure-coding patterns (SR)
• self-improvement — ST-stage retrospective: propose scoped updates from user edits
• task-folder-organization — .context/ folder structure and artifact naming
• worktask — Complete staged worktask system (dynamic sizing, init, stage management)
• worktask-testing-strategy — Test-strategy planning for PL/AR stages
• writing-style — ASD-STE100-derived prose standard (~80%) for replies, handoffs, reports and docs; loadable skill wrapping writing-style.md

Each name above is the invocable id — prefix with corpflow: (e.g. Skill({skill:"corpflow:worktask"})). See skills/README.md for the full index with effort levels and shared (non-loadable) utilities.

Hooks

Registered in .claude-plugin/plugin.json. Several are gates — they can block a stage from completing, not just observe it.

Error Handling

Retry Logic

Retry budget depends on how the failure classifies: transient retries up to 3 times (exponential backoff), logic up to 2 (corrective context added on the second attempt). missing_input, ambiguous_requirements, design_flaw, and hard_constraint do not retry — they escalate immediately. Full matrix in skills/agent-coordination/SKILL.md § Retry / Escalate Matrix.

Error narrative tracked per-agent in .context/errors/<agent>.md (parallel-safe for concurrent stage failures). Raw build/test captures go to .context/logs/ per logging-conventions skill.

## Retry 2 — 2026-04-20T14:32:10Z
**Agent**: developer (DV0)
**Classification**: logic
**retry_count**: 2

Escalation Chains

9-stage:   ST → FN → DC → QA → DR → DV → TL → AR → PL → USER
11-stage:  ST → FN → RE → DC → QA → SR → DR → DV → TL → AR → PL → USER
Emergency: FN → RE → QA → DR → DV → IR → USER
Ethics:    Any → ethics-reviewer → stakeholder → USER

Command Quick Reference

Per-command usage (grouped by role/phase) lives in the Commands tables above (§ Commands). Every command — planning, development, testing, docs, release, troubleshooting, and /improve-yourself retrospective flags — is documented there.

Development

The deterministic test suite runs offline — bats for shell, stdlib unittest for Python, Swift Testing for the benchmark artifact package. No system bats or kcov needed; make bootstrap vendors what it can and probes the rest.

make bootstrap     # vendor bats, check the swift toolchain, probe kcov
make test          # full offline suite (bats + Python + Swift), via run-tests.sh
make coverage      # + kcov / llvm-cov gating (≥85% target)
make test-ios      # TicTacToeKit on an iOS Simulator (SKIPs without a runtime)
make benchmark     # deterministic A/B plugin-overhead benchmark
make benchmark-live BUDGET=10.00   # live full-pipeline run (credential-gated, opt-in)
make report        # HTML report → benchmark/results/result.html
make clean

make help lists every target. Details live with the suites they describe:

• tests/README.md — suite organization, fixtures, coverage verdict
• benchmark/README.md — the WITH/WITHOUT Tic-Tac-Toe A/B harness
• skills/README.md — full skill index with effort levels
• CHANGELOG.md — release history (4.0.0+); earlier majors archived in CHANGELOG-3.x.md, CHANGELOG-2.x.md, and CHANGELOG-1.x.md

License

Apache License 2.0 — see LICENSE for details.