Codex Workflow Packs

Repeatable workflow packs for turning Codex subagents into auditable deliverables.

codex-workflow-packs is a local Typer CLI for generating structured Codex workflow prompts, runbooks, report scaffolds, and verification checklists. It is for developers, consultants, maintainers, and technical operators who want repeatable Codex-assisted work instead of one-off prompt improvisation.

The problem it solves: a random list of agents says who might help, but it does not define the job. A workflow pack combines the input contract, recommended subagent roles, ordered steps, verification checks, and expected deliverables so the work can be reviewed, repeated, and handed off.

The CLI does not run Codex or custom subagents automatically. It prepares the materials for explicit Codex usage by a human operator.

30-Second Demo

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
codex-packs list
codex-packs plan repo-audit --input examples/repo-audit-input.md
codex-packs scaffold-run repo-audit --output runs/demo

Expected output:

• codex-packs list prints the available workflow packs and their deliverables.
• codex-packs plan ... prints a structured Codex prompt with required inputs, subagent sequence, workflow steps, deliverables, and verification checks.
• codex-packs scaffold-run ... creates a local run folder with prompt, input, evidence, deliverable, report, and verification files.

See examples/sample-output for small example deliverables.

Core Idea

Input -> workflow pack -> explicit subagent prompt -> verification checklist -> deliverables

Each pack defines:

• required and optional inputs;
• recommended Codex subagent roles to invoke explicitly;
• ordered workflow steps;
• expected output files;
• verification checks for review.

What This Is Not

• Not an autonomous agent platform.
• Not a replacement for Codex.
• Not a security, compliance, or legal guarantee.
• Not a magic wrapper that secretly runs all agents.

Generated prompts and reports require human review. This tool helps structure work; it does not guarantee fixes, security outcomes, or production readiness.

Useful Packs Included

Pack	Use it for	Sample deliverables
repo-audit	First-pass repository review before planning fixes.	Audit report, risk register, fix backlog, runbook.
bug-triage	Disciplined bug analysis before code changes.	Reproduction notes, likely cause, minimal fix plan, regression test plan.
linux-vps-audit	Preliminary Linux/VPS incident or hardening review.	Incident report, command plan, risk register, hardening checklist.
data-cleanup	Human-reviewed data cleanup and QA workflow.	Cleaned data plan, QA report, transformation log, anomaly list.
ai-workflow-eval	Prompt, agent, or workflow regression evaluation.	Eval cases, failure taxonomy, regression report, improvement backlog.

Installation

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"

Run tests:

pytest

Common Commands

List packs:

codex-packs list

Show a pack:

codex-packs show repo-audit

Validate packs:

codex-packs validate

Generate a plan without running Codex:

codex-packs plan repo-audit --input examples/repo-audit-input.md

Create a run folder:

codex-packs scaffold-run repo-audit --output runs/demo

Example Plan Output

# Workflow Plan: repo-audit

## Required Inputs
- repository context: Repository path, project purpose, target branch, and any areas of concern.

## Agent Sequence
1. code-mapper
2. dependency-manager
3. test-automator
4. reviewer
5. security-auditor
6. technical-writer

## Deliverables
- repo-audit-report.md
- risk-register.csv
- fix-backlog.md
- runbook.md

Service Ideas

• 24h repo audit.
• Bug reproduction report.
• Linux/VPS preliminary incident report.
• Data cleanup + QA report.
• AI workflow regression pack.

See docs/MONETIZATION.md for fixed-scope examples.

Install VoltAgent Awesome Codex Subagents

Clone or download the agent collection, then preview:

codex-packs install-agents --source ./awesome-codex-subagents --dry-run

Install globally into ~/.codex/agents:

codex-packs install-agents --source ./awesome-codex-subagents --no-dry-run

The installer copies nested .toml files and preserves folder structure. Codex custom subagents still must be explicitly invoked in a Codex session.