Skip to content

Support OpenSpec change directories as plan input #306

@bronislav

Description

@bronislav

Support OpenSpec change directories as plan input

I use ralphex daily, but the company I work at is pushing the OpenSpec workflow and I need to align with it — ideally without dropping ralphex. Hence this request.

Problem

OpenSpec is a spec-driven workflow where change proposals live in openspec/changes/<id>/ with a tasks.md (checkbox task list), proposal.md, design.md, and specs/ delta files. Pointing ralphex at openspec/changes/<id>/tasks.md today doesn't work:

  1. Parser at pkg/plan/parse.go:46 accepts only ### Task N: / ### Iteration N: headers. OpenSpec uses ## 1. Phase 1 — checkboxes are silently dropped.
  2. Checkboxes outside recognized task sections are ignored (pkg/plan/parse.go:106-115).
  3. On success, MovePlanToCompleted runs unconditionally for ModeFull/ModeTasksOnly (cmd/ralphex/main.go:541). For OpenSpec, the directory must stay put — archiving is a human step via openspec archive.
  4. Sibling context files (proposal.md, design.md, spec deltas) aren't fed to Claude, so tasks lose their "why".

Proposal

Detect OpenSpec by path. When the plan file matches **/openspec/changes/<id>/tasks.md:

  • Accept ## N. <title> headers as task sections (in addition to ### Task N:)
  • Skip the move-to-completed step
  • Include sibling proposal.md, design.md, and specs/**/*.md in the prompt context so Claude sees the full change package

No new flags. One command works:

ralphex openspec/changes/add-dark-mode/tasks.md

Non-goals

  • Running openspec archive on completion — stays manual
  • Producing OpenSpec changes from --plan mode
  • Modifying specs or writing deltas

Tighter integration (archive hook, --plan → OpenSpec output) can follow if this proves useful.

Alternatives considered

  • Generic flags (--no-archive, --context-glob): more surface area, user has to remember them every run.
  • Wrapper script that flattens an OpenSpec change into a ralphex plan: two moving parts, transient files, and still needs a --no-archive flag.

Path-triggered detection keeps the UX to one command and the code delta small.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions