archon-idea-to-wo

An interactive Archon workflow that turns a raw idea into a set of self-contained, implementation-ready Work Orders (WOs) — through four AI phases with human approval gates between each.

Published in the Archon Workflow Marketplace.

Credit

Originally authored by Robert (Bob) L O'Donnell in Archon PR #1647, where it was proposed as a bundled default workflow. With the launch of the community marketplace, the workflow was reshaped into a standalone, SHA-pinned external repo so other Archon users can install it with one command instead of waiting for a release. The original design, prompts, and Work Order template are Bob's; this repo is a packaging adaptation.

What It Does

Most autonomous coding loops fail because the input is under-specified. This workflow forces the missing thinking up front: foundation questions → scope research → risk-aware decomposition → BKM-format Work Order files. The output is a directory of WO-NNN-*.wo.md files that the user can hand straight to archon-piv-loop (or any other implementer).

Flow

archon workflow run archon-idea-to-wo "add a dark mode toggle"
  │
  ▼
[understand-idea]          AI reads the codebase, asks 5 foundation questions
  │
  ▼ ━━━ approval gate ━━━  User answers
  │
[scope-and-approach]       AI researches deeply, proposes scope + alternatives
  │
  ▼ ━━━ approval gate ━━━  User approves or corrects
  │
[risk-and-decomposition]   AI orders the work, sizes WOs, calls out risks
  │
  ▼ ━━━ approval gate ━━━  User approves the breakdown
  │
[generate-wos]             AI writes BKM Work Orders to $ARTIFACTS_DIR/work-orders/
  │
  ▼ ━━━ approval gate ━━━  User signs off

Each phase reads the prior gate's captured user response, so corrections actually propagate.

Install

From inside any git repo where you've installed Archon:

archon workflow install archon-idea-to-wo

This pulls the workflow YAML and the four command files at the pinned SHA from the marketplace entry into your local .archon/.

Run

archon workflow run archon-idea-to-wo "the feature, fix, or capability you want to plan"

The workflow is interactive — approval gates pause for input in the Archon Web UI (or CLI prompt). Final Work Orders land in $ARTIFACTS_DIR/work-orders/ along with a README.md index.

Output Format — BKM Work Orders

Each generated WO-NNN-*.wo.md includes:

• Priority + effort + domain + Conductor track
• Context (why this WO exists, how it fits the plan)
• "Files to Read First" table (verified, with line ranges)
• Numbered task steps, with explicit decision points
• Anti-patterns to avoid
• Test cases to write
• Definition of Done with validation commands

The template is designed so each WO is autonomously implementable — no additional context required.

When to Use This Workflow

Good fit:

• New feature where you have an idea but not a spec
• Multi-step refactor that needs ordering
• Backlog item that needs to be broken into reviewable pieces before implementation

Not a fit:

• PRD creation — use archon-interactive-prd
• Direct implementation when scope is already clear — use archon-piv-loop
• Single-file bug fixes — overkill

Repository Layout

.archon/
├── archon-idea-to-wo.yaml        # main workflow (8 nodes)
└── commands/
    ├── archon-wo-understand-idea.md
    ├── archon-wo-scope-and-approach.md
    ├── archon-wo-risk-and-decomposition.md
    └── archon-wo-generate-wos.md

This is the canonical layout for marketplace directory-format submissions. The Archon installer expects <slug>.yaml at .archon/ root and walks commands/, scripts/, and skills/ one level deep.

License

MIT — see LICENSE.