Specorator — Agentic Development Workflow

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 to main; the marketplace entry now uses a git-subdir source pinned to that ref (ADR-0043). Bundle is gitignored on develop/main, so PR diffs stop carrying generated-artifact churn. New /issue:tackle conductor skill, /specorator:onboard guided issue series, GitHub remote MCP server in the project default, conductor-driven model-tier injection for subagents, and specorator --version flag. 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 as specorator (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/

Get Started In 5 Minutes

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 the specorator CLI 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 specorator

In 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>/.

Other tools or hacking on the template

• 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 in docs/how-to/install-claude-plugin.md.

Pick Your Entry Point

| 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.

First-Reader Route

If this is your first time here, read in this order:

1. Finish this README through the Tool Guides table.
2. Pick your role in docs/onboarding/personas.md.
3. For setup, follow docs/how-to/fork-and-personalize.md. For learning the lifecycle before setup, follow docs/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.

Tool Guides

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 init or /specorator:init after plugin installation to create a non-destructive project shell in a downstream repo.
• Codex
• Cursor
• Aider
• Copilot
• Gemini

What You Get

• 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-*), and npm run verify as the local and CI gate.
• Claude Code agents, skills, and slash commands in .claude/, with shared root context in AGENTS.md.

Reference

• 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

Roadmap

| 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 |

License

MIT