| title | Specorator documentation |
|---|---|
| folder | docs |
| description | Entry point for user-facing documentation organized by Diataxis reading mode. |
| entry_point | true |
This is the user-facing index for docs/. It is organised by Diátaxis — the four quadrants describe what kind of doc something is, not what subject it covers.
| If you want to… | Read… | |
|---|---|---|
| 📚 | Learn Specorator end-to-end | a Tutorial |
| 🛠 | Do a specific task | a How-to |
| 📖 | Look up an authoritative fact | a Reference doc |
| 💡 | Understand why something is the way it is | an Explanation doc |
If you are new to the project, start with the tutorial. If you already know the basics, jump straight to the recipe or reference you need.
For plugin adopters, start with the Specorator Claude Code Plugin User Manual. It is written for Obsidian and surfaced by the Astro product page from the same Markdown metadata.
Learning-oriented. You follow them step by step; you reach a known end state.
- Drive your first feature end-to-end — 60–90 minutes. Add the glossary entry
docs/glossary/tracer-bullet.md, walking every Specorator stage from Idea to Retrospective. The point is to internalise the lifecycle, not the change.
Quadrant last reviewed: 2026-04-28.
Task-oriented recipes — how do I do X? You arrive knowing the goal; you leave with the steps.
Nineteen recipes are available. Four common starting points:
- How to fork and personalize the template — first-clone setup.
- How to run the verify gate —
npm run verifygreen before pushing. - How to file a new Architecture Decision Record — capture an irreversible decision.
- How to resume a paused feature — pick up an in-progress feature at the right stage.
For the full set grouped by intent (Onboarding / Day-to-day / Quality and release / Tooling and extensibility), see the how-to index.
Quadrant last reviewed: 2026-04-28.
For 2 a.m. / SRE / on-call procedures, see docs/playbooks/. Playbooks are operational responses to incidents; recipes above are workflow tasks for builders.
Look-it-up, normative. Authoritative; not narrative.
specorator.md— the full workflow definition.project-scaffolding-track.md— source-led onboarding track for turning collected docs into starter artifacts.design-track.md— brand-aware surface creation workflow.issue-breakdown-track.md— post-tasks issue-to-draft-PR decomposition workflow.roadmap-management-track.md— product/project roadmap management, stakeholder alignment, and team communication workflow.quality-assurance-track.md— ISO 9001-aligned quality assurance review workflow.release-readiness-guide.md— Stage 10 go/no-go guide for product perspectives and stakeholder requirements.release-operator-guide.md— runnable operator path for publishing a tagged GitHub Release and (when enabled) a GitHub Package.release-package-contents.md— fresh-surface contract for what ships in the released template package.cross-version-handoff.md— location, naming, and link rules for handoff contracts consumed by a later release cycle.workflow-overview.md— one-page lifecycle cheat sheet.specorator-product/site-vision.md— product-site vision for the repo-driven Astro website.slash-commands.md— generated Claude Code slash-command inventory.cross-tool/— walkthroughs for Codex, Cursor, Aider, Copilot, and Gemini.how-to/install-claude-plugin.md— install the reusable Specorator Claude Code plugin package.user-manuals/— end-user manuals with Obsidian-safe frontmatter and Astro product-page metadata.specorator-plugin-experience-checklist.md— Obsidian-friendly working checklist for installing, initializing, and tuning the plugin in a downstream project.onboarding/personas.md— role-keyed first steps for product, engineering, team lead, solo builder, and non-Claude users.onboarding/first-time-adopter-walkthrough-2026-05.md— dated walkthrough evidence for the first-reader path and onboarding friction.ears-notation.md— the requirement-syntax catalogue.traceability.md— the ID scheme and the requirement → spec → task → code → test chain.obsidian-metadata.md— frontmatter compatibility rules for Obsidian source mode, Obsidian Properties UI, and repository checks.sink.md— catalog of every artifact: where it lives, who owns it. Regenerable index — don't edit by hand.sink.md#readme-entry-points— folderREADME.mdentry-point and frontmatter convention.quality-framework.md— quality dimensions, gates, and Definition of Done per stage.glossary/— plain-English glossary, one file per term (per ADR-0010). The directory listing is the index; add a term with/glossary:new "<term>".goals/— session goal documents produced by/create-goal. Each file captures objective, scope, success criteria, and a stop-hook condition string for/goal.scripts/— generated TypeDoc API reference for the Node integrity scripts underscripts/. Regenerable —npm run fix:script-docsrebuilds it from JSDoc.adr/— index of every Architecture Decision Record. (Each ADR's rationale is an Explanation doc; this is the index.)
These three docs answer two questions side-by-side: what is the rule? (Reference) and how do I follow it? (How-to). Read the Reference first when you want to know the contract; read the How-to first when you want to do the task.
| Topic | Reference (the rule) | How-to (the procedure) |
|---|---|---|
| Pre-PR gate | verify-gate.md |
how-to/run-verify-gate.md |
| Branch shapes and prefixes | branching.md |
how-to/open-pr.md |
| Worktree lifecycle | worktrees.md |
how-to/resume-paused-feature.md, how-to/open-pr.md |
| Doctor preflight | scripts/doctor/ |
how-to/run-doctor.md |
Quadrant last reviewed: 2026-04-28.
Understanding-oriented. Background, rationale, and the why behind decisions.
discovery-track.md— why Discovery exists, how it sits before Stage 1.project-scaffolding-track.md— why source-led template adoption needs a separate evidence-first track.sales-cycle.md— why service-provider work needs a pre-Discovery commercial track.project-track.md— why client engagements need P3.Express-style governance.roadmap-management-track.md— why roadmap management needs a separate outcome, delivery-confidence, and communication surface.quality-assurance-track.md— why project execution health needs evidence-backed QA checklists and corrective actions.portfolio-track.md— why portfolios sit above the Specorator lifecycle.stock-taking-track.md— why brownfield projects need a separate inventory step.design-track.md— why branded surface creation is separate from feature-level Stage 4 design.issue-breakdown-track.md— why post-tasks issue work gets its own decomposition workflow.adr/— the rationale half of each ADR file. (The index lives under Reference above.)
Quadrant last reviewed: 2026-04-28.
These directories are not user-facing reading material; they are listed here so the doc map is complete.
steering/— scoped context loaded by stage agents (product, tech, ux, quality, operations). If you are configuring the agents for your own project, start withsteering/README.md. It is not part of the Diátaxis surface for human readers.archive/,daily-reviews/,postmortems/,issues/,pull-requests/,plans/,superpowers/— operational, historical, or contributor-internal collections. They will grow as the project adds methods, constraints, and frameworks; they are deliberately outside the Diátaxis quadrant map and the hub-drift check. Thedocs-review-botkeeps the rest ofdocs/in check.
Any PR that adds, renames, or removes a file under docs/ must update this hub in the same PR. The rule lives in CONTRIBUTING.md. The docs-review-bot flags PRs that touch docs/ without touching docs/README.md.