Summary

• Problem: No guided workflow for turning raw ideas into implementation-ready Work Orders; users jump straight to implementation with under-specified tasks.
• Why it matters: BKM Work Orders dramatically improve autonomous implementation quality — but creating them from scratch is tedious and error-prone without structured guidance.
• What changed: New interactive 8-node DAG workflow (archon-idea-to-wo) and 4 command files that guide users from raw idea → foundation questions → scope/approach → risk/decomposition → BKM Work Orders.
• What did not change: No TypeScript source changes, no schema changes, no tests added — workflow engine already supports all required node types (approval, command:).

UX Journey

Before

User wants to implement a feature
  ↓
User writes a rough prompt
  ↓
Archon runs archon-piv-loop with under-specified input
  ↓
Poor WO quality → implementation churn

After

User runs: archon-idea-to-wo "add dark mode toggle"
  ↓
[understand-idea] AI reads codebase, asks 5 foundation questions
  ↓
[foundation-gate] User answers foundation questions
  ↓
[scope-and-approach] AI researches codebase deeply, proposes scope
  ↓
[approach-gate] User approves or corrects scope
  ↓
[risk-and-decomposition] AI breaks into ordered WO candidates with risks
  ↓
[decomposition-gate] User approves breakdown
  ↓
[generate-wos] AI writes BKM Work Order files to $ARTIFACTS_DIR/work-orders/
  ↓
[review-wos] User reviews and signs off
  ↓
WO files ready for archon-piv-loop

Architecture Diagram

Before

.archon/workflows/defaults/
  archon-interactive-prd.yaml   (interactive pattern reference)
  archon-idea-to-pr.yaml        (command-based pattern reference)

.archon/commands/defaults/
  archon-create-plan.md, archon-implement.md, ...

After

.archon/workflows/defaults/
  archon-interactive-prd.yaml
  archon-idea-to-pr.yaml
  [+] archon-idea-to-wo.yaml    (new: 8-node interactive DAG workflow)

.archon/commands/defaults/
  archon-create-plan.md, archon-implement.md, ...
  [+] archon-wo-understand-idea.md        (Phase 1: foundation questions)
  [+] archon-wo-scope-and-approach.md     (Phase 2: codebase research + scope)
  [+] archon-wo-risk-and-decomposition.md (Phase 3: ordered breakdown + risks)
  [+] archon-wo-generate-wos.md           (Phase 4: BKM WO file generation)

packages/workflows/src/defaults/
  [~] bundled-defaults.generated.ts       (regenerated to include new files)

Connection inventory:

Label Snapshot

• Risk: risk: low
• Size: size: M
• Scope: workflows
• Module: workflows:defaults

Change Metadata

• Change type: feature
• Primary scope: workflows

Linked Issue

• Closes feat(web): add Pi provider editor panel in Settings wizard #1623

Validation Evidence (required)

bun run generate:bundled  # regenerated bundled-defaults.generated.ts
bun run check:bundled     # PASS
bun run check:bundled-skill # PASS
bun run type-check        # PASS
bun run lint              # PASS
bun run format:check      # PASS
bun run test              # PASS (3 pre-existing failures in load-command-prompt.test.ts unrelated to this change)

• Evidence: All non-test checks pass. The 3 pre-existing test failures in load-command-prompt.test.ts (home-scope resolution) are unrelated to this PR and pre-date it.

Security Impact (required)

• New permissions/capabilities? No
• New external network calls? No
• Secrets/tokens handling changed? No
• File system access scope changed? No (workflow uses existing $ARTIFACTS_DIR — pre-created by executor)

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Database migration needed? No

Human Verification (required)

• Verified scenarios: bun run cli workflow list shows archon-idea-to-wo; all 5 new files exist with valid YAML frontmatter; bundled-defaults.generated.ts contains all new files
• Edge cases checked: Command files reference gate output variables ($foundation-gate.output etc.) which are substituted by the workflow executor's variableSubstitution() — consistent with how archon-interactive-prd.yaml operates
• What was not verified: Full end-to-end run through all 8 nodes (requires live Claude + approval interaction)

Side Effects / Blast Radius (required)

• Affected subsystems/workflows: None — pure addition of new YAML/Markdown defaults
• Potential unintended effects: None — no TypeScript changes
• Guardrails: check:bundled CI check catches any stale generated file

Rollback Plan (required)

• Fast rollback: Delete the 5 new files and re-run bun run generate:bundled
• Feature flags: None needed — workflow simply won't be invoked unless user calls it
• Observable failure symptoms: bun run check:bundled would fail if generated file is stale

Risks and Mitigations

• Risk: Gate output variable substitution in command files ($foundation-gate.output) may not work
  • Mitigation: Variable substitution in executor-shared.ts applies to all prompt text regardless of source (inline prompt: or command:); pattern is consistent with existing command files

🤖 Generated with Claude Code