0.5.0

[0.5.0] - 2026-05-18

Added

• Codex (app + CLI) support — first-class integration that writes skills to .codex/skills/alphaspec-<slug>/SKILL.md and shared workflow guidance to AGENTS.md. Detected automatically when .codex/ or AGENTS.md is present; opt-in non-interactively via --tools codex (or as part of --tools all). Invoke skills in Codex with $alphaspec-create-stories, $alphaspec-implement-story, etc.

Upgrade

Existing 0.4.x installs:

npm i -g alphaspec@latest
alphaspec init   # re-select tools, tick Codex

alphaspec upgrade only re-applies writers for tools already in your .alphaspec/config.json — it won't add Codex on its own, so re-run init to opt in. No on-disk migration is required.

Thanks

Big thanks to @edel-macias-cubix for landing this in #1 — first external contribution to alphaspec.

0.4.0

Changed

• create-stories — stories now require an Out of Scope section with at least two concrete items, and may include an explicitly non-binding Implementation Hints section. Description and Acceptance Criteria are governed by a vocabulary fence (no transport / protocol / runtime / storage terminology). Every acceptance criterion must be expressible as Given [precondition] / When [action] / Then [measurable result]. Dependencies are stated as capabilities in domain language, not as references to other stories' code shapes.
• refine-story — replaced the open-ended gap audit with a finite, binary 8-check rubric (INVEST + Out-of-Scope completeness + business intent clarity). Adds a 5 Whys recovery protocol when business intent is unclear and an anti-assumption protocol that requires the agent to externalize WHAT-assumptions rather than silently filling them. The skill now converges: running it on a passing story produces a fixed convergence message.
• bootstrap-from-research — generated stories follow the new create-stories template (including Out of Scope and Implementation Hints) and pass the same vocabulary-fence and falsifiability checks, so they converge on the first run of refine-story.
• implement-story — explicitly reads Out of Scope (treated as a hard fence) and Implementation Hints (treated as non-binding orientation) when grounding in the story.
• verify-story — drift check now flags when the implementation includes any capability listed in Out of Scope.
• complete-story — refinement comparison now considers whether anything previously in Out of Scope actually got built, and surfaces material divergence from Implementation Hints for the appended Implementation Notes.

Upgrade

Existing 0.3.x installs:

npm i -g alphaspec@latest
alphaspec upgrade

No on-disk migration is needed — only prompt content changed. The upgrade command re-runs IDE writers in place and bumps the recorded version. Existing stories keep working; running the new refine-story on them will surface rubric findings (an Out of Scope section will be the first thing it asks for).

v0.3.0

[0.3.0] - 2026-04-25

⚠ Breaking Changes

• Slug prefix renamed from alphaspec.<name> to alphaspec-<name>. Some IDEs (Cursor, Windsurf) don't accept dots in command names, so prompts now register with hyphens uniformly across all supported tools.
• create-story prompt removed. Replaced by create-stories, which natively handles multi-story briefs, produces story maps for large briefs, splits work by implementation effort and architectural area, and enforces epic-as-complete-capability boundaries.
• .alphaspec/prompts/ no longer maintained. The "source-of-truth" copy has been dropped — IDE writers are now the sole distribution surface for prompts. Your tools read the prompts directly from their respective tool-specific folders.

Added

• alphaspec upgrade command — in-place version upgrades for existing installs. Reads .alphaspec/config.json, plans the relevant migrations, prints the plan, runs them, re-applies IDE writers, and bumps the recorded version. Idempotent: re-running on an up-to-date install is a no-op.
• Version-aware migration framework (src/lib/migrations.ts) — versioned migration registry with semver-ish range selection (installed < to <= current). The first migration handles 0.0.0 → 0.3.0: scrubs the dot-prefix legacy layout, removes create-story artifacts across all tools, and deletes orphaned .alphaspec/prompts/.
• refine-story prompt — gap-analysis pass with per-lens audits (Description, Acceptance Criteria, Artifacts, Sources, Dependencies, Key Decisions). Each lens includes concrete examples and "not worth surfacing" guidance to prevent noise.
• Tighter create-stories authoring guidance:
  • Step 2 — effort-based granularity heuristics (story scope is judged by what's being built, not how it's described; a short brief can hide a large story)
  • Step 2.5 — architectural-not-numeric trigger for story maps (multi-epic briefs, not multi-story features)
  • Step 4 — scope-filtered artifact transcription (broad mockups partition by story, not duplicated everywhere)
  • Step 5 — epic-as-complete-capability placement criterion
  • Step 6 — granularity, reviewer-load, and artifact-relevance self-checks
  • Step 8 — ## Capability delivered section in _epic.md template
  • Critical rules — dual-budget reviewer ergonomics rule (spec sections under 100 lines for scope discipline; whole story aim under 200 for reviewer cognitive load)

Changed

• alphaspec init detects version drift. When run on an existing install with an older recorded version, it now refuses with a clear pointer to alphaspec upgrade instead of silently no-op'ing.
• All instruction templates updated to list the new prompt set (create-stories, refine-story, complete-story, implement-story, verify-story, define-principles, bootstrap-from-research).
• All IDE writer comments updated to reflect the new slug format.
• README — added ### alphaspec upgrade section under CLI reference; documented the upgrade path for existing users.

Removed

• src/templates/prompts/create-story.md — replaced by create-stories.md.
• .alphaspec/prompts/ writeout in init — no longer part of the install footprint.
• Dead PROMPT_NAMES import in src/commands/init.ts.

Upgrading from 0.2.0

npm i -g alphaspec@latest   # or your equivalent
alphaspec upgrade

v0.2.0

Added

• Support to define custom stories directory
• Added a standalone verification skill for checklist verification against story AC as well as project principles and other guidelines

Changed

• The default container directory for stories is now ./stories instead writting the pending and done story directories to the root of the repo directly.
• Reworked prompts to lead to more accurately follow intent and lead to better outputs from the AI
• Updated skills names to use a prefix so they can be quickly listed and identified from other slash commands