v1.20.0

What's changed in v1.20.0

Features

• Surface Claude Artifacts in specs for UX/UI projects (#432)
• Phase-entry pull, auto-gen & parallel-authoring guidance (Lot 4, #425) (#427)
• Pluggable spec backend + init choice (local | cloud) (Lot 2, #424) (#426)
• Arrow-key project picker + auto-generated key on cloud login (#421)
• Default login to api.specnaut.com — no prompt, no Convex URL (#417)
• Default the backlog picker to Specnaut Cloud (recommended) (#406)
• specnaut login alias + cloud orgs / cloud board (#399)
• Deprecated 'specflow' binary alias warning (D)
• .specflow/ → .specnaut/ config dir + safe migration (C)
• Per-agent effort tuning rubric (#387)
• Status ledger + /status-audit (#386)
• Per-axis audit-dispatch skills (#385)
• /code-audit — multi-seat parallel audit (#384)
• Machine-readable agent output contracts (#383)
• Preserve per-project customisations across template refreshes (#374)
• Parent-managed detection — suppress .claude/ provisioning in workspace sub-repos (#372)

Bug fixes

• Collapse redundant double PR reference in release notes (#434)
• Drop the detached backend benefit note from the pickers (#430)
• Don't read the keychain at login (kills the double keychain prompt) (#423)
• Picker scroll-drift on cloud login + rebrand keychain service to specnaut-cloud (#422)
• Grant unscoped --allow-net so cloud login never prompts (#420)
• Complete Markdown-cell escaping in groom-inbox (CodeQL js/incomplete-sanitization) (#418)
• Make marketplace/codex sync push failures non-blocking (#415)
• Resolve preflight smoke-audit against the monorepo .claude (#414)
• Unblock v1.15.0 pipeline (fmt + plugin preflight + tap slug) (#413)
• Retarget stale mkrlabs/specnaut + makerlabs.dev URLs to canonical (#412)
• Don't nudge cloud login twice when the cloud backend is picked (#410)
• Point plugin-sync scripts at the specnaut repos (rebrand drift) (#404)
• Disclose + confirm login target URL to block config phishing (#401)
• Harden collect-audit-scope.sh (#389, #390, #391) (#393)
• Extract agent + contract fields from the real CC payload (#392)
• Authenticate gh in CI so the Adoption guide ships (#373)
• Remove permission-asking language from phase doc (#369)
• Honour --dry-run (#368)
• Preflight CI polling + postflight soft-warn diff status + gh retry (#365)

Adoption guide

These prompts help your AI agent adopt the new features in an existing project. Copy them into your harness, or run @specnaut-expert review-upgrade to be walked through automatically.

#432 — Surface Claude Artifacts in specs for UX/UI projects

/specnaut specify now adds an optional Visual Prototyping with Claude Artifacts section to generated specs when your project has a front-end / UX-UI surface (detected via the same signals the accessibility gate uses). Specs authored before this upgrade won't have it retroactively — run the prompt below to backfill any in-flight UX/UI specs, and to update any project-local spec-template override you maintain.

Check whether this project has a front-end surface (any of: .html/.htm,
.jsx/.tsx, .vue/.svelte/.astro files; a public/, src/app/, src/pages/,
src/routes/, or pages/ markup dir; or a package.json listing react, vue,
svelte, solid-js, preact, lit, astro, @angular/core, or qwik).

If it does:
  1. For each in-flight spec under .specnaut/specs/*/spec.md that lacks a
     "## Visual Prototyping with Claude Artifacts" section, add one after
     Assumptions that points the reader at Claude Artifacts for visualising
     the UX, with links to the public artifacts docs.
  2. If you keep a customised .specnaut/templates/spec-template.md override,
     mirror the same optional, FE-gated section into it.

If this project has NO front-end surface, do nothing — a back-end/CLI-only
spec must stay artifact-free.

🤖 Generated with Claude Code

#427 — Phase-entry pull, auto-gen & parallel-authoring guidance (Lot 4, #425)

Wire the cloud spec backend into the phase flow, reusing the existing spec-backend marker-block mechanism: (1) each consuming phase (implement/review/analyze/tasks) runs one `specnaut spec pull <task>` at entry in cloud mode so agents read materialised files; (2) an opt-in `spec_autogen` lock field (default off) with a spec-autogen=on render dimension across all harnesses drives cloud `specify` at task creation, non-fatal; (3) a parallel-authoring guidance note. Keep local-mode rendering byte-identical (golden tests, EOL-agnostic), and touch Cloud only through the versioned commands (no private-half identifier).

🤖 Generated with Claude Code

#426 — Pluggable spec backend + init choice (local | cloud) (Lot 2, #424)

Add a second spec-storage backend to the Specnaut CLI, chosen at `specnaut init` like the backlog backend: `local` (current .specnaut/specs/ markdown, first-class default) or `cloud` (recommended — specs hosted on SpecNaut Cloud via the versioned /api/v1/specs* contract). Introduce a SpecStore port with local + cloud adapters, `spec push`/`spec pull` commands, gitignored materialisation under .specnaut/specs/.cache/<task>/, and cloud-mode `specify` that pushes steps + creates no branch (branch decoupled to implement, auto-creating+linking a task when none is linked). Keep the local backend byte-identical. Mirror the existing gate_* / backlog_* patterns; the cloud adapter speaks only the versioned HTTP API (no private-half identifier in the public CLI).

#421 — Arrow-key project picker + auto-generated key on cloud login

Cloud onboarding is now name-only — when an agent sets up the Cloud backend for a user, it no longer has to invent a valid uppercase key; it just supplies a project name and the CLI derives the key.

Connect this repo to Specnaut Cloud: run `specnaut cloud login`, and when it asks, create a new project called "My App" — let the CLI generate the project key.

🤖 Generated with Claude Code

#417 — Default login to api.specnaut.com — no prompt, no Convex URL

specnaut cloud login (and specnaut login) no longer asks for a deployment URL — it defaults to https://api.specnaut.com. If your project's .specnaut/backlog-config.yml pins api_url to a raw *.convex.site host, you can delete that line to use the branded default (keep it only for a dev / self-hosted deployment). No re-login is required; existing credentials keep working.

Open `.specnaut/backlog-config.yml` in my project. If it has an `api_url:` line pointing at a `*.convex.site` host under `backend: cloud`, remove that line so the CLI uses its built-in default `https://api.specnaut.com`. Leave `api_url` untouched if it points at a non-Specnaut (dev or self-hosted) deployment. Don't touch `project_key` or any other field.

#399 — specnaut login alias + cloud orgs / cloud board

specnaut login is now a top-level alias for specnaut cloud login, and two new read-only commands landed: specnaut cloud orgs (list the organizations your account belongs to) and specnaut cloud board (view the linked project's board, tasks grouped by column). If your project docs or agent rules point users at specnaut cloud login for Cloud auth, mention the shorter specnaut login, and surface the new read commands where a quick "what's on my board?" check helps.

Audit my project for references to Specnaut Cloud auth in:
  - `.claude/agents/*.md`, `.claude/skills/**/*.md`
  - `AGENTS.md`, `CLAUDE.md`, `README.md`

Where `specnaut cloud login` is mentioned, add a note that `specnaut login` is a
shorter top-level alias. Where it helps, mention the new read commands
`specnaut cloud orgs` (list your organizations) and `specnaut cloud board`
(show the linked project's board). Open a PR with the changes.

#374 — Preserve per-project customisations across template refreshes

specflow init --force and specflow upgrade now respect a .specflow/preserve.yml manifest: any managed file listed there is kept on a forced refresh instead of being overwritten by the bundled version. If your project has customised any bundled file — most commonly .claude/agents/product-owner.md (its GitHub Project handle + label conventions) or .claude/agents/developer.md (its build/test commands) — declare those paths so a future --force refresh can't silently revert them. Use the new read-only specflow diff to see how your copies have drifted from the bundle, and --reset-preserved to deliberately discard a customisation.

Find which bundled Specflow files I have customised, then protect them from forced template refreshes:

1. Run `specflow diff` and note every file reported as diverged from the bundle.
2. Create or update `.specflow/preserve.yml` with a top-level `preserved:` list
   containing each diverged project-relative path, e.g.:

   preserved:
     - .claude/agents/product-owner.md
     - .claude/agents/developer.md

3. Commit `.specflow/preserve.yml`.

From now on `specflow init --force` and `specflow upgrade` will keep those files
and print a per-file "preserved …" notice. To intentionally take the bundled
version back, run the refresh with `--reset-preserved`.

🤖 Generated with Claude Code

#372 — Parent-managed detection — suppress .claude/ provisioning in workspace sub-repos

Maintainers of monorepo-style Specflow workspaces (a parent repo that declares its sub-repos as Deno workspace members and centralises skills/agents at its own root) can now safely run specflow init / specflow upgrade inside a sub-repo: the toolkit updates but no .claude/ skills/agents are written, so a routine CLI run no longer re-introduces the drift that root-centralisation removed. No action is required to benefit — detection is automatic. If you intentionally keep a standalone Specflow project inside an unrelated parent Deno workspace and want the full local toolkit, drop an empty .specflow/standalone.yml in that project to force full provisioning. Standalone (non-nested) projects are completely unaffected.

If this project lives as a sub-repo inside a parent Deno workspace that centralises its Claude Code skills/agents at the workspace root, you can now run `specflow upgrade` here without it recreating a local `.claude/skills` or `.claude/agents` directory — Specflow detects the providing workspace and suppresses agentic-file provisioning automatically. Verify after upgrading that no `.claude/skills` or `.claude/agents` directory reappeared in this sub-repo. If instead you WANT the full local toolkit despite the enclosing workspace, create an empty file at `.specflow/standalone.yml` and re-run `specflow init`.

Internal / chores

16 internal changes

• V1.20.0 (#436)
• Add non-negotiable project-agnosticism rule (#435)
• Scan main on push so fixed alerts auto-close (#419)
• Stop scaffolding the deprecated specnaut-auto alias (#411)
• Decouple publish steps so one failure can't skip the rest (#403)
• Rebrand stale specflow <cmd> refs in JSDoc to specnaut (#397)
• Finish SpecFlow→Specnaut rebrand leftovers + rename .specflow/ dir (#396)
• /specflow command + skills → /specnaut (B)
• Specflow→specnaut brand, URLs, env vars, binary names (A)
• Close the two deferred log-subagent coverage gaps (#394)
• Extract website + docs to mkrlabs/specflow-web (#377)
• Document preserve.yml, specflow diff, --reset-preserved (#375)
• Deno fmt relocated gh-issues scripts
• Point local launchd routines at the monorepo-root tooling
• Relocate gh-issues maintenance scripts out of .claude/ → scripts/gh-issues/
• Drop .claude/ — AI tooling centralised at the monorepo root

Full changelog: v1.13.1...v1.20.0