Build software the right way with AI. Specorator is a spec-driven workflow template: humans decide what to build, specialist agents handle how, and every requirement, decision, task, test, and release note stays traceable.
Status: v0.8.0 — Claude Code plugin bundle moves to a long-lived orphan branch (
dist/claude-plugin) rebuilt by CI on every push tomain; the marketplace entry now uses agit-subdirsource pinned to that ref (ADR-0043). Bundle is gitignored ondevelop/main, so PR diffs stop carrying generated-artifact churn. New/issue:tackleconductor skill,/specorator:onboardguided issue series, GitHub remote MCP server in the project default, conductor-driven model-tier injection for subagents, andspecorator --versionflag. npmjs.com Trusted Publishing restored (ADR-0044, supersedes ADR-0041); every v0.8.x release ships with a sigstore provenance attestation visible on the npmjs.com package page. v0.7.0 migrated the npm CLI from GitHub Packages to npmjs.com asspecorator(unscoped, public, no.npmrc). Claude Code is first-class; Codex, Cursor, Aider, Copilot, and Gemini have Markdown-based walkthroughs.
Product page: https://luis85.github.io/agentic-workflow/
No runtime required. The Markdown workflow core (
AGENTS.md,docs/,templates/) works with any AI coding tool and needs no installation. Clone the repository and follow the workflow guide to start. The steps below add thespecoratorCLI and Claude Code plugin as optional accelerators — see the product ladder for the full adoption model.
Two one-line installs — npm CLI plus Claude Code plugin. No .npmrc configuration, no PAT.
In your shell:
npm install -g specoratorIn Claude Code:
/plugin marketplace add Luis85/agentic-workflow
/plugin install specorator@specorator-marketplace
/reload-plugins
/specorator:welcome
/specorator:init
The npm CLI provides specorator init (project file seeding); the plugin provides the Claude agents, skills, and slash commands. /specorator:welcome runs the initializer in dry-run mode and recommends the next command. /specorator:init is non-destructive: existing files are skipped, and a report lands at .specorator/install-report-*.md.
Then say:
let's start a feature: user login with email and password
Claude Code runs the conversational path, asks the stage-gate questions, and writes artifacts under specs/<feature>/.
- Codex, Cursor, Aider, Copilot, Gemini — those tools cannot load Claude Code plugins. Use the tool guides, which assume a cloned template.
- Improving Specorator itself — clone the repository, run
npm install, and use the local install path documented indocs/how-to/install-claude-plugin.md.
| You are | Start here | Outcome |
|---|---|---|
| Product manager or designer | Say "let's start a feature" or "let's run a design sprint" in Claude Code. | idea.md, research notes, and requirements.md that engineering can review. |
| Developer | Read specs/<feature>/workflow-state.md, then say "continue this feature". |
The next stage runs from the existing artifact state. |
| Team lead | Fork the repo, adapt memory/constitution.md, fill docs/steering/, and gate stages from workflow-state.md. |
A project-local workflow with explicit quality gates. |
| Solo builder | Say "drive this end-to-end: " in Claude Code. | The orchestrator walks all 11 stages with you. |
| Non-Claude user | Open the guide for your tool under docs/cross-tool/. |
Manual stage execution using the same Markdown artifacts. |
More persona detail: docs/onboarding/personas.md. Role-keyed starting paths: docs/adoption-profiles/.
If this is your first time here, read in this order:
- Finish this README through the Tool Guides table.
- Pick your role in
docs/onboarding/personas.md. - For setup, follow
docs/how-to/fork-and-personalize.md. For learning the lifecycle before setup, followdocs/tutorials/first-feature.md.
Ignore until needed: docs/superpowers/, generated script reference under docs/scripts/, release operator docs, optional tracks that do not match your job, and ADRs that are not linked by your current page.
For the plugin path, use the Specorator Claude Code Plugin User Manual. It combines install, first-run, daily use, Obsidian, verification, troubleshooting, and maintenance in one page.
Claude Code gets the native commands, agents, and skills. Other tools use the same files and stage order:
- Install the Specorator Claude Code plugin
- Use
specorator initor/specorator:initafter plugin installation to create a non-destructive project shell in a downstream repo. - Codex
- Cursor
- Aider
- Copilot
- Gemini
- An 11-stage lifecycle: Idea, Research, Requirements, Design, Specification, Tasks, Implementation, Testing, Review, Release, Retrospective.
- Optional and companion tracks for Discovery, Stock-taking, Sales, Project Management, Roadmap, Portfolio, Quality Assurance, Project Scaffolding, Design, Issue Breakdown, and Specorator Improvement. The canonical v1.0 track taxonomy is frozen in ADR-0026.
- Markdown artifacts in
specs/<feature>/, stable IDs (REQ-*,T-*,TEST-*,ADR-*), andnpm run verifyas the local and CI gate. - Claude Code agents, skills, and slash commands in
.claude/, with shared root context inAGENTS.md.
- Workflow definition:
docs/specorator.md - User manual:
docs/user-manuals/claude-plugin.md - Documentation hub:
docs/README.md - Slash commands inventory:
docs/slash-commands.md - Repository map:
docs/repo-map.md - Quality framework:
docs/quality-framework.md - Proof loop (real feature, end-to-end):
docs/proof-loop.md - Contribution guide:
CONTRIBUTING.md
| Version | Status | Focus |
|---|---|---|
| v0.5 | Done | Release workflow, branching strategy, GitHub Releases and Packages |
| v0.5.1 | Done | Recovery release for v0.5 — republished GitHub Release page after Immutable Releases incident |
| v0.5.2 | Planned | Issue-breakdown track patch release |
| v0.6.0 | Done | Astro product page — sites/index.html replaced by Astro 6 build, repo-driven sections (landing / tour / tracker / info hub), brand-token bridge, and dynamic Pages base (#335) |
| v0.6 | Active | Cross-tool adapters, live proof, hooks, and security |
| v1.0 | Planned | Release readiness checklist |