v0.9.0 — npx sam-agents demo: scaffold a working app in 90 seconds

This release adds a zero-friction first-success command and a major README rewrite that leads with proof instead of feature lists.

What's new

npx sam-agents demo

npx sam-agents demo               # → ./sam-demo
npx sam-agents demo ./my-demo     # → ./my-demo
npx sam-agents demo --force ./x   # overwrite an existing directory

Clones sam-agents/example-todo into a target directory, strips .git, and prints next-step instructions. No LLM provider required — newcomers can see exactly what SAM produces in under 2 minutes, then npm install && npm run dev to see the app work.

Verified end-to-end: clone → install → both dev servers up → full CRUD against http://localhost:3001 → frontend on http://localhost:5174 returns HTML. All in under 2 minutes (mostly npm install).

README rewrite

• New hero screenshot embedded from the example-todo Lens evidence
• Replaced "Why SAM?" strawman table with "What makes SAM different" — three named differentiators (contracts-first, TDD-as-boundary, Lens evidence) with deep links into the example repo
• New "How does it compare?" table naming actual alternatives (Cursor agents, Cline/Continue, Aider, Claude Code skills, Copilot Workspace, Devin) instead of comparing to a vague strawman
• Compacted the per-agent table — 13 agents × 2 columns (was 12 × 6), per-platform paths consolidated into the existing invocation grid
• Added extend workflow to the workflows table and invocation grid (was missing since 0.8.0)
• Clarified that Lens runs after the integration story, not in the per-story TDD loop

Companion repo: sam-agents/example-todo

The end-to-end output of one SAM run, fully committed: PRD, contracts, stories, source, tests, and Lens evidence (screenshots, network log, console, video). Linked from the README as the proof artifact.

Discoverability

Repository topics added to both sam-agents/sam and sam-agents/example-todo. GitHub description updated to reflect the 5-platform support.

Internal

• CLAUDE.md now documents the npm release process (GitHub Release triggers publish.yml).
• Zero new runtime dependencies. The demo command uses only Node built-ins.

Known gaps

Replan is not yet supported. Today's workflows handle linear builds (plan → build-tdd) and additive iteration after v1 (extend), but mid-build requirement changes, feature removal, and tech-stack pivots have no formal workflow. This is the headline of the next release.

For mid-build changes today: edit the affected story or contract file directly and re-run build-tdd on the affected story. SAM does not yet detect impact across stories.

Upgrade

npx sam-agents@latest demo

No breaking changes for existing users.

Validated end-to-end

• npx sam-agents demo → clone, install, dev, full CRUD, frontend serving — all green
• npm test (4 verifiers) — all green

v0.8.0 — Contracts-first planning, Lens demo capture, extend workflow

This release adds three SDLC artifacts that close the integration-drift gap in SAM, plus the iteration workflow that lets projects evolve past v1 without losing done work. It also brings the quick-PRD path from earlier in this cycle.

What's new

Contracts-first planning

• New plan step step-02-design-contracts runs before story generation. Atlas writes typed seams (api, type, event, repo, module) into sdocs/contracts/.
• Story schema gains kind / produces / consumes — these declare each story's role in the dependency graph and which contracts it owns or depends on.
• New resource: contract-schema.md defines the five contract kinds and the version + status lifecycle.

Lens (sam-lens) — demo recorder + integration witness

• New agent that runs after the per-epic integration story passes. Drives a real headless Chrome via Playwright; captures video, screenshots, network log, and console log to sdocs/evidence/<EPIC-ID>/.
• Web-stack only — logs a skip for non-web projects rather than failing.
• Evidence-only role: Lens does not gate the pipeline. The integration story is the gate; Lens proves it on disk.

Extend workflow (sam-extend)

• New workflow for additive iteration after v1. Takes an addendum markdown file, evolves contracts (with version bumps + prior_producers tracking), appends new stories, and merges the addendum into prd.md with a change log entry.
• Four steps: validate-addendum → evolve-contracts → extend-stories → merge-prd.

Per-epic integration stories

• The plan workflow now emits one kind: integration story per epic. These run real HTTP against the running app — no mocks. They are the gate the demo evidence proves.

Quick-PRD + Quill (Product Manager)

• New scope variant quick-prd for a one-pass PRD with explicit assumptions, plus the Quill agent that owns it. Folded into this release after the v0.7.x review cycle.

PRD schema additions

• New ## Change log section. The extend workflow appends here on every addendum merge so the PRD never goes stale.

Manifest

13 agents (was 12; added sam-lens) · 6 workflows (was 5; added sam-extend)

Validated end-to-end

• sam26: PRD → working tested todo app with Lens evidence in 14 min, contracts-first, zero integration rework.
• sam25: original todo app + extend addendum adding tags. Contract v1 consumers kept working through the v2 bump.

Breaking changes

None for consumers. Internal to plan workflow: step-02-generate-stories is now step-03-generate-stories (a new step-02-design-contracts slots ahead of it). Consumers do not script against step numbers.

Upgrade

npx sam-agents@latest --platform all <your-project>

Existing projects without contracts continue to work; the new artifacts are opt-in via the updated plan workflow.

v0.7.0 — Scope workflow + four-workflow split

v0.7.0 — Scope workflow + four-workflow split

This release reshapes the SAM pipeline. The single monolithic autonomous-tdd workflow is split into four composable workflows, a new upstream scope workflow handles users who don't have a PRD yet, and all generated artifacts now write to sdocs/.

Breaking changes

• autonomous-tdd is gone. Replaced by three workflows: plan (PRD → epics + stories), build-tdd (one story → tested code), and plan-n-build (full composer). Existing invocations of /sam:core:workflows:autonomous-tdd must switch to /sam:core:workflows:plan-n-build.
• Artifacts moved to sdocs/. Stories, epics, architecture-ref, run reports, and the PRD itself now write to sdocs/ in the consumer project — honoring the existing output_folder config. The old sdocs/autonomous-runs/<timestamp>/ path is gone.
• Per-platform command names changed. /sam-tdd-pipeline and @sam-tdd are replaced by per-workflow names: sam-plan, sam-build-tdd, sam-plan-n-build, plus the new sam-scope.

Added

• scope workflow — for users without a PRD. Takes prose, rough notes, or no input at all and produces a draft PRD via interactive discovery (Iris on UX, Atlas on technical constraints, Sage drafting). Always ships a draft on the first pass; gaps become honest "TBD" notes plus Open Questions you can iterate on. PRD status tracks draft → reviewed → accepted.
• --from-idea flag on plan-n-build — one-shot path for users with only an idea. Prepends scope in non-interactive mode to draft a PRD before planning. Preserves the composer's "no human prompts" contract.
• Canonical schemas as explicit contracts. Three new schema files in _sam/core/resources/ define the seams between workflows: prd-schema.md, story-schema.md, epic-schema.md. Workflows refuse to operate on invalid artifacts.
• Sage gains Mode 0 (PRD drafting) in addition to per-story changelog (Mode 1) and comprehensive feature docs (Mode 2).
• Per-workflow commands across all five platforms — Claude Code, Cursor, Antigravity, Gemini CLI, and GitHub Copilot all get distinct invocations per workflow.

Changed

• Story status field is now authoritative for resume. No separate pipeline-status.yaml to drift. plan-n-build --resume reads each story's frontmatter to know what's done.
• bin/cli.js refactored. A shared WORKFLOWS constant replaces the per-generator workflow blocks that previously had to be kept in sync by hand.
• verify-gemini.js updated to check for 11 agents + 4 workflows = 15 skills.
• README rewritten for the four-workflow model with a per-platform invocation matrix and the typical-flow callout.

Migration

For existing users with a working autonomous-tdd setup:

1. Reinstall: npx sam-agents@0.7.0 --platform <yours>
2. Replace any /sam:core:workflows:autonomous-tdd <prd> invocations with /sam:core:workflows:plan-n-build <prd>
3. References to sam-tdd-pipeline or @sam-tdd in your tooling/docs become sam-plan-n-build / @sam-plan-n-build (or a more granular workflow command)
4. Generated artifacts now appear in sdocs/ instead of sdocs/autonomous-runs/<timestamp>/ — adjust any scripts that read from the old path

Known leftover

_sam/docs/SAM_GEMINI_USAGE.md and SAM_COPILOT_USAGE.md still reference sam-tdd-pipeline from the old design. Informational docs only — slated for cleanup in a follow-up release.

v0.6.1- Improve UI design

v0.6.1- Improve UI design

v0.6.0 - Multi-pass Pipeline

v0.6.0 - Multi-pass Pipeline

v0.5.3

Agent Multi-pass

v0.5.2 - Agents Multipass

multi-pass

v0.5.1 - Cosmo Agent

v0.5.1 - Publish Cosmo Agent

v0.5.0 - Cosmo CSS Reviewer

v0.5.0 - Cosmo CSS Reviewer

v0.4.0 - Antigravity Support

v0.4.0 - Antigravity Support