DevFlow v2.5.0

Summary

Minor release that rolls up 2.2.2, 2.3.0, 2.4.0, 2.4.1 and 2.5.0 (#11–#16). It brings DevFlow in line with current Agent Skills best practices from Anthropic, OpenAI Codex and skills.sh (see docs/skills-best-practices.md), then fixes what an adversarial review of every workflow found. DevFlow is calibrated for the team's own repositories: same-repository work stays low-friction, and extra caution applies only to fork PRs and web content.

• Portable skill, cleaner surface. The description is front-loaded and command-free, compatibility moved into the body so the Codex validator passes too, Claude-only names left skills/, and the worktree guide became references/worktrees.md. Claude Code argument hints now actually display, and wrapper pre-approvals are scoped to read-only commands.
• PR review validates the PR's real code in a detached worktree at the PR's head commit. Same-repository PRs are validated as usual; fork PRs run nothing until you agree, and are reviewed statically otherwise. Approving or posting happens only when asked (--auto-approve, new --post), and DevFlow never merges.
• Non-interactive runs (codex exec, claude -p) never block on a question and create, post, approve, overwrite, or push nothing that needed approval unless the request asks for it.
• OpenSpec gate as a script. opsx_validate is now .devflow/scripts/opsx-validate.sh, copied by setup. It validates the branch's change (--type change), only the main specs once that change is archived, and every active change when the branch has none; exit 2 means broken configuration.
• Development workflow. Branches are cut from a freshly fetched origin/<base> with --no-track (a bare git push could previously reach main); the base is resolved explicitly; OpenSpec artifacts are written on the branch; uncommitted user work is never stashed, discarded, or committed; a PR for already-committed work can be opened without an issue.
• Planning. Epics create implementation-ready sub-issues linked with --parent/--blocked-by and hand off straight to implementation; feat and epic search for duplicates, check labels against the full list, never --force a label, and honor .devflow/feat.md.
• Validation. .devflow/check.md format documented, Rust and uv/poetry inference added, and autofix limited to the branch's own failures.

Full detail in CHANGELOG.md.

Upgrading from 2.2.1

• Re-run setup in repositories that use OpenSpec. It copies .devflow/scripts/opsx-validate.sh, which you should commit together with check.md. Older inline opsx_validate/opsx_verify gates are reported as outdated.
• .devflow/check.md runs only the first JSON block holding validations. Checks that exist only in later blocks, as the old template layout suggested, are reported skipped with a warning, and setup offers to consolidate them.
• First push of a new branch is git push -u origin <branch>, since branches no longer track the base.
• PR review always uses a worktree under .devflow/worktrees/. The first review may add that path to .gitignore, which is yours to commit. The --worktree flag is gone.
• Epic planning replaces --worktree with --epic-branch. Sub-issues merged into an epic branch must be closed by hand, because GitHub only applies Closes #n on the default branch.
• The dev wrapper drops --auto-tests and --full-validation, both now the default.
• Narrower Claude Code pre-approvals mean more permission prompts in review-pr, setup, feat and epic.

Installation

npx skills add https://github.com/docutray/devflow-skill --skill devflow

Claude Code:

/plugin marketplace add docutray/devflow-skill
/plugin install devflow@docutray-skills

Existing installs update by reinstalling:

/plugin uninstall devflow && /plugin install devflow@docutray-skills