Skip to content
/
Tier B A4 Markdown scaffold

Specorator (Luis85/agentic-workflow)

specorator-workflow · Luis85/agentic-workflow · ★ 0 · last commit 2026-05-25

18 commands + 40 skills + 36 specialist agents + 11-stage lifecycle covering Idea through Retrospective — full software product lifecycle with dedicated orchestrator, ADR system, GitHub MCP, and Obsidian companion for spec authoring.

Best whenSoftware development is a multi-domain activity requiring domain-authority-specialized agents; a generic AI assistant produces inconsistent outputs because i…
Skip ifAd-hoc AI conversations replacing structured lifecycle stages, Monolithic AI sessions where the same context handles strategy AND implementation
vs seeds
openspec(Archetype 2 — commands + skills + multi-agent + GitHub native). Specorator significantly expands this archetype: 36 nam…
Primitive shape 97 total
Commands 18 Skills 40 Subagents 36 Hooks 2 MCP tools 1
00

Summary

Luis85/agentic-workflow (Specorator) — Summary

Specorator is a Claude Code plugin shipped as an npm package (specorator) and a Claude plugin marketplace entry. It bundles 18 slash commands, 40+ skills, 36 named agents, and a GitHub MCP integration into a full-lifecycle software development workflow covering 11 mandatory stages (Idea → Retrospective) plus 12 optional tracks (Discovery, Stock-taking, Sales, QA, Scaffolding, and more).

The defining architectural choice is agent specialization at scale — 36 distinct named agents (analyst, architect, critic, qa, dev, pm, orchestrator, estimator, ux-designer, etc.) each with specific domain authority. This is the largest named-agent roster in the batch. The orchestrator agent drives cross-agent coordination, and the dispatch command routes work to the appropriate specialist.

Distribution uses a CI-built orphan branch (dist/claude-plugin) rather than a main-branch release, with an Obsidian plugin companion (specorator-obsidian-mcp) for specification authoring. The project uses its own methodology to manage itself (ADR-0043, ADR-0044 are Specorator decisions made by Specorator).

0 GitHub stars (private/very early public), MIT licensed, HTML primary language (documentation), actively developed with commits as recent as 2026-05-25.

The closest seed match is openspec (Archetype 2 — commands + skills + agents + GitHub native). Specorator has a much larger component surface than openspec (18 commands vs openspec's comparable set), adds a dedicated orchestrator agent, an ADR system, an Obsidian companion, and a formal 11-stage lifecycle with optional specialty tracks.

01

Overview

Luis85/agentic-workflow (Specorator) — Overview

Origin

Created by Luis85. Repository: Luis85/agentic-workflow. Description: "The Specorator Workflow bundled in a Claude Plugin." npm package name: specorator. 0 stars, MIT licensed, HTML primary language (documentation site), last commit 2026-05-25. Actively developed — commits daily to weekly.

The project uses Specorator itself to manage Specorator's development. Architecture Decision Records (ADRs) are real Specorator artifacts: ADR-0043 (dist branch strategy), ADR-0044 (npm publishing). This self-hosting is an intentional demonstration of the methodology.

Philosophy

Specorator treats software development as a lifecycle with discrete, interconnected stages — not as a set of ad-hoc tasks. Every feature travels through all 11 stages, producing artifacts at each step that feed the next.

The core problem: AI coding tools are used reactively (user asks, AI answers) rather than systematically. Specorator replaces the ad-hoc pattern with a structured workflow where:

  • Each stage has a named agent with specific domain authority
  • Each stage produces mandatory artifacts
  • Artifacts from stage N are inputs to stage N+1
  • An orchestrator agent manages cross-stage coordination

On specialization:

"Each agent owns its domain. The orchestrator does not know how to write code; the dev agent does not know how to set product strategy."

On lifecycle completeness:

The 11 core stages plus 12 optional tracks cover every activity in professional software development — from initial idea through post-release retrospective.

The Specorator name

"Specorator" combines "spec" (specification) and "decorator" — the idea that the workflow decorates development with specifications at every stage, not just at the planning phase.

Distribution model

Specorator ships via three mechanisms simultaneously:

  1. npm package (npm install -g specorator)
  2. Claude plugin marketplace (/plugin marketplace add Luis85/agentic-workflow)
  3. CI-built orphan branch (dist/claude-plugin) that contains the compiled plugin artifacts

This multi-channel distribution is documented in ADR-0044 (npm) and ADR-0043 (dist branch). The project explicitly treats its own distribution decisions as ADRs — demonstrating the methodology's ADR system.

Target tools

Primary: Claude Code. The Claude plugin architecture, .claude/ directory structure, and claude-task-tool subagent spawning are all Claude Code primitives. Cross-tool portability to other AI CLIs (Cursor, Windsurf) would require manual adaptation.

02

Architecture

Luis85/agentic-workflow (Specorator) — Architecture

Distribution

  • Type: Claude Code plugin (npm + plugin marketplace)
  • Install: npm install -g specorator OR /plugin marketplace add Luis85/agentic-workflow && /plugin install specorator@specorator-marketplace
  • Install complexity: multi-step (plugin install + project init)
  • Distribution branch: dist/claude-plugin (CI-built orphan branch, NOT main)

Directory tree

agentic-workflow/
├── .claude/
│   ├── commands/               ← 18 slash commands
│   │   ├── spec.md
│   │   ├── specorator.md
│   │   ├── design.md
│   │   ├── discovery.md
│   │   ├── glossary.md
│   │   ├── issue.md
│   │   ├── portfolio.md
│   │   ├── product.md
│   │   ├── project-review.md
│   │   ├── project.md
│   │   ├── quality.md
│   │   ├── roadmap.md
│   │   ├── sales.md
│   │   ├── scaffold.md
│   │   ├── stock-taking.md
│   │   ├── adr.md
│   │   ├── create-goal.md
│   │   └── token-review.md
│   ├── skills/                 ← 40+ skills
│   │   ├── orchestrate.md
│   │   ├── tdd-cycle.md
│   │   ├── grill.md
│   │   ├── caveman.md
│   │   ├── design-twice.md
│   │   ├── discovery-sprint.md
│   │   ├── domain-context.md
│   │   ├── github-project-setup.md
│   │   ├── improve-codebase-architecture.md
│   │   ├── issue-breakdown.md
│   │   ├── issue-draft.md
│   │   ├── issue-pr-sync.md
│   │   ├── new-adr.md
│   │   ├── new-glossary-entry.md
│   │   ├── portfolio-track.md
│   │   ├── product-page.md
│   │   ├── project-review.md
│   │   ├── project-run.md
│   │   ├── project-scaffolding.md
│   │   ├── quality-assurance.md
│   │   ├── quality-metrics.md
│   │   ├── record-decision.md
│   │   ├── review-fix.md
│   │   ├── roadmap-management.md
│   │   ├── sales-cycle.md
│   │   ├── specorator-design.md
│   │   ├── specorator-improvement.md
│   │   ├── specorator-onboard.md
│   │   ├── stock-taking.md
│   │   ├── tackle-issue.md
│   │   ├── token-budget-review.md
│   │   ├── tracer-bullet.md
│   │   ├── ubiquitous-language.md
│   │   ├── verify.md
│   │   ├── agentic-security-review.md
│   │   ├── arc42-baseline.md
│   │   ├── caveman-commit.md
│   │   ├── caveman-help.md
│   │   └── caveman-review.md
│   ├── agents/                 ← 36 named agents
│   │   ├── analyst.md
│   │   ├── architect.md
│   │   ├── brand-reviewer.md
│   │   ├── critic.md
│   │   ├── design-lead.md
│   │   ├── dev.md
│   │   ├── divergent-thinker.md
│   │   ├── estimator.md
│   │   ├── facilitator.md
│   │   ├── game-designer.md
│   │   ├── issue-breakdown.md
│   │   ├── issue-draft.md
│   │   ├── legacy-auditor.md
│   │   ├── orchestrator.md
│   │   ├── planner.md
│   │   ├── pm.md
│   │   ├── portfolio-manager.md
│   │   ├── product-page-designer.md
│   │   ├── product-strategist.md
│   │   ├── project-manager.md
│   │   ├── project-reviewer.md
│   │   ├── project-scaffolder.md
│   │   ├── proposal-writer.md
│   │   ├── prototyper.md
│   │   ├── qa.md
│   │   ├── release-manager.md
│   │   ├── retrospective.md
│   │   ├── reviewer.md
│   │   ├── roadmap-manager.md
│   │   ├── sales-qualifier.md
│   │   ├── scoping-facilitator.md
│   │   ├── sre.md
│   │   ├── ui-designer.md
│   │   ├── user-researcher.md
│   │   └── ux-designer.md
│   ├── hooks/
│   │   ├── startup.sh          ← SessionStart hook (memory reminder)
│   │   └── branch-guard.py     ← PreToolUse/Bash hook (branch protection)
│   └── settings.json           ← Git permission allow/deny lists
├── .mcp.json                   ← GitHub MCP server config
├── memory/
│   └── constitution.md         ← Project-level constitution
├── docs/
│   └── steering/               ← Steering documents
├── specs/
│   └── <feature>/              ← Per-feature specification folders
│       └── workflow-state.md   ← Progress tracking artifact
├── adr/                        ← Architecture Decision Records
│   ├── ADR-0043.md             ← dist branch strategy
│   └── ADR-0044.md             ← npm publishing
└── package.json                ← npm package (specorator)

Required runtime

  • Node.js / npm (for npm install -g specorator)
  • Claude Code (primary target)
  • Git
  • GitHub account (for MCP server integration)

Plugin distribution via orphan branch

CI rebuilds dist/claude-plugin on every push to main. The plugin install pulls from this branch:

/plugin install specorator@specorator-marketplace

This pattern (orphan dist branch + CI rebuild) is documented in ADR-0043 as a deliberate choice to keep build artifacts separate from source history.

03

Components

Luis85/agentic-workflow (Specorator) — Components

Slash Commands (18)

Command Purpose
/spec Create/manage specifications for a feature
/specorator Entry point — start the Specorator workflow
/design Design phase — architecture and system design
/discovery Discovery sprint — user research and problem framing
/glossary Manage ubiquitous language glossary
/issue GitHub issue creation and management
/portfolio Portfolio-level tracking and management
/product Product page and product management
/project-review Structured project retrospective
/project Project setup and management
/quality Quality assurance checks
/roadmap Roadmap creation and management
/sales Sales cycle management
/scaffold Project scaffolding
/stock-taking Inventory existing code/tech debt
/adr Architecture Decision Record creation
/create-goal Define and document a project goal
/token-review Token budget review and optimization

Skills (40+)

Core workflow skills:

  • orchestrate — cross-agent coordination
  • tdd-cycle — test-driven development loop
  • grill — adversarial questioning / assumption challenging
  • caveman — simplification skill (reduce to fundamentals)
  • design-twice — double-design review
  • discovery-sprint — user research sprint
  • domain-context — domain model definition
  • tracer-bullet — end-to-end thin-slice implementation
  • ubiquitous-language — domain language standardization
  • verify — verification/validation check

GitHub/project management skills:

  • github-project-setup — GitHub Projects configuration
  • issue-breakdown — decompose issues to subtasks
  • issue-draft — draft GitHub issue
  • issue-pr-sync — sync PR state to issues
  • portfolio-track — portfolio tracking
  • project-run — run project workflow
  • project-scaffolding — project structure setup
  • roadmap-management — roadmap maintenance

Quality/architecture skills:

  • improve-codebase-architecture — architecture improvement
  • quality-assurance — QA process
  • quality-metrics — quality measurement
  • agentic-security-review — security audit
  • arc42-baseline — arc42 architecture documentation baseline
  • review-fix — review finding resolution
  • token-budget-review — token cost analysis

Documentation skills:

  • new-adr — write new ADR
  • new-glossary-entry — add glossary term
  • record-decision — record architectural decision
  • product-page — product page generation
  • specorator-onboard — onboard to Specorator workflow
  • specorator-design — design the workflow itself
  • specorator-improvement — workflow self-improvement

Caveman skills (simplification sub-system):

  • caveman-commit — commit with simplification constraint
  • caveman-help — help with simplification
  • caveman-review — review with simplification lens

Sales/portfolio skills:

  • sales-cycle — manage sales process
  • stock-taking — codebase inventory
  • tackle-issue — implement an issue
  • project-review — structured project review

Agents (36)

The full agent roster, organized by domain:

Strategy/product:

  • product-strategist — product direction and strategy
  • pm / project-manager — project management
  • portfolio-manager — portfolio-level management
  • planner — planning specialist
  • roadmap-manager — roadmap ownership
  • proposal-writer — proposals and pitches
  • sales-qualifier — sales qualification
  • estimator — effort estimation

Design/UX:

  • architect — system architecture
  • design-lead — design leadership
  • ui-designer — UI design
  • ux-designer — UX design
  • user-researcher — user research
  • prototyper — rapid prototyping
  • game-designer — game-specific design (optional track)

Implementation:

  • dev — software development
  • qa — quality assurance
  • sre — site reliability engineering
  • legacy-auditor — legacy code audit

Process/facilitation:

  • orchestrator — cross-agent coordination (meta-agent)
  • facilitator — meeting/process facilitation
  • scoping-facilitator — scope definition
  • retrospective — retrospective facilitation
  • project-reviewer — project review
  • project-scaffolder — project setup

Content/communication:

  • analyst — analysis and research
  • critic — adversarial review
  • brand-reviewer — brand consistency
  • divergent-thinker — creative ideation
  • product-page-designer — product page design
  • reviewer — code/artifact review

Special purpose:

  • issue-breakdown — issue decomposition agent
  • issue-draft — issue authoring agent
  • release-manager — release management

Hooks (2 events, 3+ files)

File Event Purpose
.claude/hooks/startup.sh SessionStart Memory reminder — loads constitution.md and steering docs
.claude/hooks/branch-guard.py PreToolUse/Bash Prevents destructive git operations on protected branches

MCP Integration

.mcp.json configures the GitHub remote MCP server:

  • Provides GitHub API access to all agents
  • Enables issue creation, PR management, project board operations
  • Used by github-project-setup, issue-draft, issue-pr-sync skills

Artifacts system

Path Purpose
specs/<feature>/ Per-feature specification folder
specs/<feature>/workflow-state.md Stage progress tracking
memory/constitution.md Project-level invariants
docs/steering/ Steering documents for long-term direction
adr/ Architecture Decision Records

Obsidian companion

specorator-obsidian-mcp — a separate plugin for Obsidian note-taking app that exposes Specorator workflow data via MCP. Allows specification authoring in Obsidian with sync to the Claude Code workflow.

05

Prompts

Luis85/agentic-workflow (Specorator) — Prompts & Instructions

Instruction delivery

Specorator uses the Claude Code plugin primitive system — all instructions are delivered via .claude/ directory files:

  • Commands (/cmd syntax): user-invoked entry points
  • Skills (slash-invoked via Skill tool): behavioral modules
  • Agents (spawned via claude-task-tool): specialized personas with domain authority

There is no global system prompt or custom instructions file. All behavioral context is loaded on-demand through the plugin system.

Agent definition format

Each of the 36 agents is defined in .claude/agents/<name>.md. The format is a persona-style Markdown file with:

  • Role description and domain authority
  • Behavioral constraints
  • Typical inputs and outputs
  • Interaction style

Example structure from the orchestrator.md pattern:

---
name: orchestrator
description: Coordinates multi-agent workflow execution
---

You are the orchestrator agent. Your role is to:
- Read workflow-state.md to determine current stage
- Dispatch to the appropriate specialist agent
- Aggregate results across agent boundaries
- NOT perform domain work directly

The orchestrator is explicitly prohibited from doing domain work — it only manages routing and aggregation.

Skill format

Each skill is a .claude/skills/<name>.md file with a description field and behavioral instructions. Skills are invoked by Claude during task execution when the Skill tool is called.

Command format

Commands in .claude/commands/<name>.md follow the standard Claude Code format with a description and prose instructions. Commands are entry points that typically invoke one or more skills and agents.

Key prompting patterns

Grill pattern (adversarial questioning)

The grill skill instructs the AI to take an adversarial stance toward assumptions in any document or plan. Used at the end of Requirements and Review stages to surface weak assumptions before they become bugs.

Caveman pattern (radical simplification)

The caveman skill (and its sub-skills caveman-commit, caveman-help, caveman-review) instructs the AI to strip away complexity and find the simplest possible implementation. Named after the heuristic of explaining to a hypothetical caveman who only understands basic concepts.

Design-twice pattern

The design-twice skill requires producing two distinct designs for any architectural decision before choosing. Prevents premature commitment to the first viable solution.

Tracer-bullet pattern

The tracer-bullet skill implements a thin end-to-end slice first — touching all architectural layers — to validate integration before building full features. Inspired by the Pragmatic Programmer concept.

Domain-context loading

The domain-context skill loads the project's ubiquitous language (from glossary) and domain model into context before any implementation work. Ensures the AI uses correct domain terminology.

Memory/constitution prompt

memory/constitution.md is loaded by the SessionStart hook (startup.sh). It contains project-level invariants — decisions that are not up for debate:

  • Non-negotiable architectural constraints
  • Team agreements
  • Long-term strategic commitments

The hook reminds the AI to read the constitution at session start, but does not enforce it programmatically.

Steering documents

docs/steering/ contains direction-setting documents loaded by the SessionStart hook alongside the constitution. Steering documents are periodically updated and represent the current project direction (as opposed to the constitution which rarely changes).

Token budget awareness

The token-budget-review skill and /token-review command are dedicated to managing Claude Code token consumption. The skill analyzes token usage patterns and recommends optimizations — an unusual feature that addresses the practical economics of AI-assisted development.

09

Uniqueness

Luis85/agentic-workflow (Specorator) — Uniqueness

Largest named-agent roster in the corpus

36 named agents is the highest count in this batch and among the highest in the entire corpus. Each agent has exclusive domain authority and a defined interaction pattern with other agents. The breadth of coverage is notable:

  • Strategy agents (product-strategist, portfolio-manager, roadmap-manager)
  • Design agents (architect, ui-designer, ux-designer, design-lead, prototyper)
  • Process agents (facilitator, scoping-facilitator, retrospective, estimator)
  • Domain-specific agents (game-designer, legacy-auditor, brand-reviewer)
  • Self-management agents (orchestrator, project-reviewer, release-manager)

No other framework in the batch has this level of agent specialization. BMAD-METHOD has ~5 personas; spec-driver has 1 agent.

Dedicated orchestrator meta-agent

The orchestrator agent is explicitly prohibited from performing domain work. Its sole function is routing and coordination. This clean separation between "meta" (orchestration) and "domain" (specialist) agents is architecturally cleaner than frameworks where orchestration and implementation are mixed.

Self-hosting as design validation

Specorator uses Specorator to develop Specorator. ADR-0043 and ADR-0044 are real decisions made through the Specorator workflow. This is not just documentation — the ADRs exist in the repository as outputs of the workflow. No other framework in this batch demonstrably uses itself.

ADR system as first-class citizen

Architecture Decision Records are a built-in primitive, not an afterthought:

  • /adr command
  • new-adr skill
  • record-decision skill (lightweight alternative)
  • adr/ directory with sequenced ADR files
  • Superseding ADR references for decision evolution

The ADR system is integrated into the workflow — Design stage naturally produces ADRs. No other framework in the batch treats ADRs as a primary artifact type.

Token budget awareness

The token-budget-review skill and /token-review command explicitly manage token consumption as a workflow concern. This is the only framework in the batch that treats AI token economics as a first-class workflow problem worth dedicated tooling.

Obsidian companion as specification authoring surface

The specorator-obsidian-mcp plugin provides a GUI for specification authoring outside the terminal. This bidirectional Obsidian-to-Claude sync is unique in the corpus — most frameworks accept specs as flat text files with no dedicated authoring tool.

12 optional specialty tracks

Beyond the 11 mandatory stages, 12 optional tracks cover: Discovery, Stock-taking, Sales, Project Management, Roadmap, Portfolio, QA, Scaffolding, Design, Issue Breakdown, Specorator Improvement, ADR. This is the most comprehensive coverage of non-development software work activities in the batch.

CI-built orphan dist branch (documented as ADR)

The CI pipeline that rebuilds the plugin distribution branch on every push to main is documented as ADR-0043. This is unusual: most frameworks treat their CI/packaging as infrastructure, not as an architectural decision worth recording. Treating distribution strategy as a first-class decision (subject to the same ADR system as code decisions) reflects consistent methodology application.

Closest seed comparison

Closest: openspec (Archetype 2 — commands + skills + multi-agent + GitHub native)

Similarities:

  • Multi-agent architecture with specialist roles
  • GitHub-native issue/project management
  • Formal lifecycle stages
  • Claude Code plugin format

Key differences from openspec:

  • 36 agents vs openspec's smaller agent set
  • Dedicated orchestrator meta-agent (openspec doesn't have one)
  • ADR system as first-class primitive
  • Obsidian companion for spec authoring
  • Token budget tooling
  • 12 optional specialty tracks (Sales, Portfolio, Roadmap not in openspec)
  • Self-hosting loop via specorator-improvement skill
  • CI-built orphan dist branch (openspec uses standard distribution)
  • npm package as secondary distribution path

The scope difference is significant: openspec covers the development workflow; Specorator covers development workflow + product strategy + sales + portfolio management + team process. Specorator is designed for a team that manages all aspects of a software product, not just its implementation.

04

Workflow

Luis85/agentic-workflow (Specorator) — Workflow

11-Stage Core Lifecycle

Every feature or project travels through all 11 stages in sequence:

1. Idea
2. Research
3. Requirements
4. Design
5. Specification
6. Tasks
7. Implementation
8. Testing
9. Review
10. Release
11. Retrospective

Stage 1: Idea

Entry point. /specorator or /create-goal command. The divergent-thinker agent generates possibilities; the facilitator structures the session. Output: documented idea with initial scope statement.

Stage 2: Research

/discovery command → discovery-sprint skill. The user-researcher agent drives user research, the analyst agent synthesizes findings. Output: discovery report in specs/<feature>/.

Stage 3: Requirements

The pm or product-strategist agent converts research findings to requirements. The grill skill challenges assumptions. Output: requirements document; issues drafted via issue-draft skill.

Stage 4: Design

/design command → design-twice skill. The architect agent owns system design; ui-designer and ux-designer agents own interface design; design-lead coordinates. Output: design artifacts in specs/<feature>/.

The arc42-baseline skill can be invoked here to produce architecture documentation in arc42 format.

Stage 5: Specification

/spec command. Consolidates research, requirements, and design into a formal specification. Output: specs/<feature>/spec.md or equivalent structured document.

Stage 6: Tasks

issue-breakdown skill → issue-breakdown agent. Decomposes specification into GitHub issues. The estimator agent provides effort estimates. Output: GitHub issues on project board (via GitHub MCP).

Stage 7: Implementation

tackle-issue skill → dev agent. Implements one issue at a time. The tdd-cycle skill enforces test-first implementation. The tracer-bullet skill can be used to validate an end-to-end thin slice before full implementation.

Stage 8: Testing

quality-assurance skill → qa agent. The verify skill checks implementation against specification. The agentic-security-review skill audits for security issues. Output: test results, QA report.

Stage 9: Review

review-fix skill → reviewer and critic agents. The critic provides adversarial review; brand-reviewer checks brand consistency. The project-reviewer agent conducts structured project review (/project-review command).

Stage 10: Release

release-manager agent manages release preparation. The sre agent validates operational readiness. Output: release notes, deployment artifacts.

Stage 11: Retrospective

/project-review command → retrospective agent. Structured retrospective covering what worked, what didn't, and improvements. Output: retrospective document; improvements fed back as Specorator ADRs (self-improvement loop).

12 Optional Specialty Tracks

Additional tracks activated on demand for non-standard work types:

Track Command/Skill Use case
Discovery /discovery Dedicated research sprint
Stock-taking /stock-taking Legacy codebase audit
Sales /sales Sales cycle management
Project Management /project Project setup
Roadmap /roadmap Roadmap planning
Portfolio /portfolio Multi-project management
QA /quality Standalone QA audit
Scaffolding /scaffold Project structure setup
Design /design Standalone design work
Issue Breakdown issue-breakdown skill Issue decomposition
Specorator Improvement specorator-improvement skill Workflow self-improvement
ADR /adr Architecture decision recording

Workflow state tracking

specs/<feature>/workflow-state.md tracks stage completion for each feature:

  • Current stage
  • Artifacts produced
  • Next actions
  • Blocked items

The orchestrate skill coordinates multi-agent stage transitions by reading workflow state and dispatching to the appropriate next agent.

Self-hosting loop

The Specorator team uses Specorator to develop Specorator:

  • New workflow changes go through the 11-stage lifecycle
  • ADRs are created using the /adr command and new-adr skill
  • Retrospectives feed back as specorator-improvement skill invocations
  • ADR-0043 and ADR-0044 are real Specorator artifacts

This self-hosting demonstrates that the methodology is applicable to the development of the methodology itself.

06

Memory Context

Luis85/agentic-workflow (Specorator) — Memory & Context

Memory architecture

Specorator uses a layered file-based memory system:

Layer 1: Constitution (project invariants)        memory/constitution.md
Layer 2: Steering documents (current direction)   docs/steering/
Layer 3: ADRs (point-in-time decisions)           adr/ADR-XXXX.md
Layer 4: Per-feature workflow state               specs/<feature>/workflow-state.md
Layer 5: Glossary (ubiquitous language)           referenced via glossary skills

Each layer has a different mutability contract:

  • Constitution: rarely changes, loaded every session
  • Steering: updated as direction evolves, loaded every session
  • ADRs: immutable once written (superseded by new ADRs, not edited)
  • Workflow state: updated as stages complete
  • Glossary: grows as new domain terms are defined

SessionStart hook

.claude/hooks/startup.sh fires at every Claude Code session start:

  • Injects a reminder to read memory/constitution.md
  • Injects a reminder to check docs/steering/ for current direction
  • Does not automatically load files — it instructs the AI to load them

This is a soft enforcement mechanism: the hook generates instructions, but the AI must follow them.

Workflow state files

specs/<feature>/workflow-state.md is the primary per-feature state artifact:

  • Current lifecycle stage (1-11)
  • Completed stages and their artifacts
  • Next required action
  • Blocked items and blockers
  • Decisions made during this feature's development

The orchestrate skill reads this file to determine routing decisions (which agent to dispatch next).

ADR system

Architecture Decision Records in adr/ provide immutable decision history:

  • Each ADR is a numbered file (ADR-XXXX.md)
  • Status: proposed → accepted → superseded
  • Superseding ADRs reference the ADR they replace
  • Created via /adr command → new-adr skill

The record-decision skill creates a lightweight decision record that is not a full ADR (for smaller, less consequential decisions).

GitHub integration as external memory

The GitHub MCP server integration provides an external memory system for issues and project boards:

  • Issues represent work items with history
  • GitHub Projects board tracks workflow stage
  • PR-to-issue links via issue-pr-sync skill
  • The external GitHub state is the authoritative record for task status

This offloads task-tracking memory from local files to GitHub, which has better persistence and collaboration properties.

Cross-session context recovery

No automated snapshot tool (unlike Disciplined-AI's project_extract.py). Context recovery relies on:

  1. SessionStart hook loading constitution and steering docs
  2. AI reading relevant workflow-state.md for active features
  3. Glossary providing domain term definitions
  4. ADRs providing architectural decision context

The specorator-onboard skill provides a structured onboarding sequence for new sessions — loads key context in the correct order.

Context window management

The token-budget-review skill and /token-review command provide active context window management:

  • Identifies which loaded context is consuming tokens
  • Recommends which context to drop
  • Prioritizes what must stay in context vs what can be re-loaded on demand

This is the most explicit context window management tooling in the batch — most frameworks treat token limits as a constraint to work around; Specorator treats it as a first-class concern.

Obsidian MCP companion

The specorator-obsidian-mcp plugin connects Obsidian (note-taking) to the Specorator workflow:

  • Specifications authored in Obsidian are accessible to Claude agents via MCP
  • Provides a human-friendly authoring interface for specs and steering documents
  • Bidirectional sync between Obsidian notes and specs/ directory
07

Orchestration

Luis85/agentic-workflow (Specorator) — Orchestration

Orchestration model: orchestrator agent + sequential pipeline

Specorator uses a dedicated orchestrator agent as the coordination layer. The orchestrator:

  • Reads workflow-state.md to determine current stage
  • Dispatches to the appropriate specialist agent for that stage
  • Aggregates results from multiple agents when needed
  • Updates workflow state after stage completion
  • Does NOT perform domain work directly

The orchestrate skill drives this pattern — it is a meta-skill that coordinates multi-agent stage transitions.

Agent spawn mechanism

Agents are spawned via claude-task-tool (Claude Code's built-in task spawning). The orchestrator invokes specialist agents as subtasks:

orchestrator (meta)
  → dispatches to analyst (Research stage)
  → dispatches to architect (Design stage)
  → dispatches to dev (Implementation stage)
  → dispatches to qa (Testing stage)
  → dispatches to release-manager (Release stage)

Each spawned agent receives:

  • The relevant section of workflow-state.md
  • Domain context (constitution, steering docs, glossary)
  • Stage-specific inputs (spec, design artifacts, etc.)

Concurrency model

Sequential by design — one stage completes before the next begins. The lifecycle enforces this: stage N+1 requires artifacts from stage N.

Within a stage, some agents may work in parallel (e.g., architect and ux-designer both working in the Design stage), but this is not explicitly automated — it depends on the orchestrator's dispatch decisions.

Agent domain authority model

Each of the 36 agents has exclusive domain authority:

  • The architect agent cannot make product strategy decisions (that's product-strategist)
  • The orchestrator cannot write code (that's dev)
  • The critic is specifically adversarial — it challenges other agents' outputs

This authority model prevents role confusion in multi-agent sessions. When an agent encounters a decision outside its domain, it explicitly defers to the appropriate specialist.

Cross-cutting skills as coordination primitives

Several skills serve as cross-agent coordination tools:

  • orchestrate — the main coordination driver
  • grill — adversarial challenge across any agent's output
  • domain-context — shared domain model loading (called before any domain work)
  • ubiquitous-language — shared terminology enforcement
  • verify — cross-agent verification checkpoint

GitHub as external coordination bus

The GitHub MCP integration provides an external coordination mechanism:

  • Issues represent work items shared across agents
  • Project board state is visible to all agents
  • issue-pr-sync keeps PR state consistent with issue state
  • issue-breakdown ensures all implementation work is tracked as issues before dispatch to dev

This means external coordination happens through GitHub, not just through local files.

Self-improvement loop

The Specorator workflow includes a self-modification path:

  1. Retrospective identifies workflow improvement
  2. specorator-improvement skill is invoked
  3. New ADR is created via new-adr skill
  4. Workflow is updated

This creates a feedback loop where the orchestration model itself evolves via the same lifecycle it orchestrates.

Comparison to other multi-agent frameworks

Framework Orchestration model
Specorator Dedicated orchestrator agent + 35 specialist agents + sequential lifecycle
spec-driver Single agent + sequential phase skills, no multi-agent
autospec Session isolation per stage (no cross-session agent communication)
openspec (seed) Multi-agent with parallel dispatching
claude-flow (seed) Hive-mind parallel swarm

Specorator's model is closest to openspec in structure but has a much larger agent surface and an explicit orchestrator meta-agent that openspec lacks.

08

Ui Cli Surface

Luis85/agentic-workflow (Specorator) — UI & CLI Surface

Installation

Three installation paths:

npm (global):

npm install -g specorator

Claude plugin marketplace:

/plugin marketplace add Luis85/agentic-workflow
/plugin install specorator@specorator-marketplace

Direct from dist branch: The dist/claude-plugin orphan branch contains CI-built plugin artifacts. The plugin marketplace command pulls from this branch.

Claude Code surface (primary interface)

After installation, the developer interacts via Claude Code's native primitive surfaces:

Slash commands (18)

/spec           /specorator    /design        /discovery
/glossary       /issue         /portfolio     /product
/project-review /project       /quality       /roadmap
/sales          /scaffold      /stock-taking  /adr
/create-goal    /token-review

These are the primary entry points. Each command triggers a workflow stage or specialty track.

Session start

The SessionStart hook (startup.sh) fires automatically. It:

  • Reminds the AI to read memory/constitution.md
  • Reminds the AI to check docs/steering/

No interactive prompt is displayed to the user; the hook injects context into the AI's instruction stream.

Branch protection

The PreToolUse/Bash hook (branch-guard.py) intercepts git commands before execution:

  • Checks if the command would affect a protected branch
  • Aborts and explains if protection would be violated
  • Allows non-destructive operations through

npm package surface

The specorator npm package provides:

specorator --help        # Command help
specorator install       # Install plugin to Claude Code project
specorator <other>       # Additional subcommands (not fully enumerated)

The npm package is primarily an installer/updater for the Claude plugin, not a standalone tool.

Obsidian companion

specorator-obsidian-mcp — separate Obsidian plugin:

  • Installed in Obsidian (not Claude Code)
  • Exposes Specorator workflow data via MCP server
  • Allows specification authoring in Obsidian with bidirectional sync
  • Provides a GUI specification authoring experience

This is the only non-terminal UI surface in Specorator. Obsidian is a desktop Markdown editor, so this provides a visual editor for specs and steering documents.

No web dashboard or TUI

Unlike spec-driver (which ships a TUI with live agent session follow), Specorator has no local web server, no terminal UI, and no dedicated dashboard. All interaction is through Claude Code's chat interface or Obsidian.

GitHub Projects integration

Via the GitHub MCP server (.mcp.json), Specorator exposes GitHub's project board as a workflow visualization surface. This is not a custom UI — it uses GitHub's existing project board — but the github-project-setup skill configures it to match the Specorator workflow stages.

Cross-platform notes

The plugin is Claude Code native. Portability to other AI CLIs (Cursor, Windsurf, Copilot) would require:

  • Reimplementing the .claude/commands/ as that tool's equivalent
  • Reimplementing the .claude/agents/ persona loading
  • Reimplementing the hooks in that tool's hook system
  • Replacing the GitHub MCP with that tool's external tool integration

The methodology itself (11 stages, agent roles, artifact types) is tool-agnostic, but the implementation is Claude Code specific.

Related frameworks

same archetype · same primary tool · same memory type

BMAD-METHOD ★ 48k
A4 Markdown scaffold

Provides a full agile delivery lifecycle with named expert-persona AI collaborators that elicit the human's best thinking rather…

Agent OS ★ 4.6k
A4 Markdown scaffold

Extracts implicit codebase conventions into token-efficient markdown standards files and injects them selectively into AI agent…

Claude Conductor ★ 367
A4 Markdown scaffold

Gives Claude Code a persistent, cross-linked, auto-analyzed documentation system so it retains codebase context across sessions.

Spec-Driver (Greenfield Spec-Driven Development) ★ 25
A4 Markdown scaffold

Prevents spec rot in AI-assisted development by making implementation changes flow back into evergreen, authoritative specs via…

Anthropic Knowledge Work Plugins ★ 16k
A4 Markdown scaffold

Role-specialized plugin bundles with live MCP connectors that turn Claude into a domain expert for enterprise knowledge workers.

Codex Integration for Claude Code (skill-codex) ★ 1.3k
A4 Markdown scaffold

Single Claude Code skill that handles Codex CLI invocation correctly (stdin blocking, thinking token suppression, session resume)…