Specorator

Architecture decisions

• ADR-0042 Adopt a typed-artifact reader seam for frontmatter parsing Accepted
• ADR-0041 Defer npmjs.com Trusted Publishing — fall back to NPM_TOKEN Accepted
• ADR-0040 Migrate npm publication from GitHub Packages to npmjs.com Accepted
• ADR-0039 Adopt hybrid feature-tracker data source — issues/ folder primary, GitHub-API snapshot fallback Accepted
• ADR-0038 Adopt Tailwind v4 with @tailwindcss/vite and bridge brand tokens via @theme inline Accepted
• ADR-0037 Adopt Astro 6 with glob-loader + snapshot hybrid content sourcing for the product page Accepted
• ADR-0036 Adopt plugin manifests as the Specorator capability contract Accepted
• ADR-0035 Add issue-draft track for early draft PR and living PRD from /spec:idea Accepted
• ADR-0034 Expose specorator scripts as a CLI binary via bin entry in the existing package Accepted
• ADR-0033 Adopt issue-first interaction model as recommended entry point for Standard-depth workflows Accepted
• ADR-0032 Bridge Design Track handoff into /spec:design Stage 4 Accepted
• ADR-0031 Adopt issues/ folder as the canonical local mirror of feature issue tracking Accepted
• ADR-0030 Add Repo Adoption Track as v1.1 opt-in companion track Proposed
• ADR-0029 Make the multi-framework adapter pipeline additive-only over canonical sources Accepted
• ADR-0028 Treat the Claude baseline as the canonical source for multi-framework adapters Accepted
• ADR-0027 Adopt Shape B branching model (develop / main / demo) for the template Accepted
• ADR-0026 Freeze the v1.0 workflow track taxonomy Accepted
• ADR-0025 Adopt a doc-as-contract review protocol Proposed
• ADR-0024 Lock the Specorator and agentic-workflow naming contract Accepted
• ADR-0023 Adopt zod as the first runtime dependency for script-layer validation Accepted
• ADR-0022 Adopt issue-breakdown track for parallelising post-tasks issue work Accepted
• ADR-0021 Ship the released template package as a fresh-surface starter Accepted
• ADR-0020 Adopt Shape A with release/vX.Y.Z branches for v0.5 releases Superseded
• ADR-0019 Add a Design Track as an opt-in first-party workflow Accepted
• ADR-0018 Flip sites/styles.css to consume design-system tokens Superseded
• ADR-0017 Adopt `inputs/` as the canonical ingestion folder for new work packages Accepted
• ADR-0016 Adopt the specorator-design skill as the canonical brand source Accepted
• ADR-0015 Codify a bounded Codex review loop on every pull request Accepted
• ADR-0014 Shard log-shaped artifacts for Bases Proposed
• ADR-0013 Add Obsidian as an opt-in UI layer Accepted
• ADR-0012 Add a Roadmap Management Track for product and project planning Accepted
• ADR-0011 Add a Project Scaffolding Track for source-led template adoption Accepted
• ADR-0010 Shard the glossary into one file per term under docs/glossary/ Accepted
• ADR-0009 Add opt-in Portfolio Manager role and P5 Express portfolio track Accepted
• ADR-0008 Add an opt-in Project Manager Track based on P3.Express Accepted
• ADR-0007 Add a Stock-taking Track for projects that build on existing systems Accepted
• ADR-0006 Add a Sales Cycle Track that precedes the Discovery Track and Stage 1 Accepted
• ADR-0005 Add a Discovery Track that precedes Stage 1 (Idea) Accepted
• ADR-0004 Adopt operational agents alongside lifecycle agents Accepted
• ADR-0003 Adopt EARS notation for functional requirements Accepted
• ADR-0002 Adopt spec-driven development as the workflow spine Accepted
• ADR-0001 Record architecture decisions Accepted

Glossary

ADR →

A one-page record of an irreversible architectural decision — what was decided, why, what alternatives were considered, and what trade-offs were accepted.

Agent →

An AI assistant specialised for one role in the workflow — analyst, PM, designer, developer, QA, reviewer, and so on.

agentic-workflow →

agentic-workflow is the repository slug and GitHub Packages npm package identity for Specorator.

Artifact →

A markdown file produced at a stage of the workflow — idea.md, requirements.md, design.md, spec.md, tasks.md, implementation-log.md, test-plan.md, test-report.md, review.md, release-notes.md, retrospective.md, and so on.

Discovery Track →

A structured ideation mini-sprint — Frame → Diverge → Converge → Prototype → Validate → Handoff — used when there is no clear brief yet. Produces a chosen-brief.md that feeds Stage 1 (Idea) of the Specorator lifecycle.

EARS →

A sentence format for requirements — *Easy Approach to Requirements Syntax* — that makes them unambiguous and 1:1 testable.

Quality gate →

A short checklist a stage must pass before the next stage can begin.

Retrospective →

A short look-back after every feature: what worked, what didn't, what to change next time.

Spec →

A written description of exactly what to build — no ambiguity, no guessing.

Specorator →

Specorator is the product name for this spec-driven, agentic software-development workflow template.

Traceability →

The discipline of linking every piece of code back to a task, every task to a requirement, and every requirement to a test — so that any change can be reasoned about across the full chain.