zspec

zspec is a CLI scaffold that combines two complementary workflows into one tool:

• gsd workflow — a pragmatic, log-driven productivity workflow that keeps teams moving with small diffs, explicit assumptions, and continuous progress logging.
• GitHub Speckit — a spec-first, directory-per-feature specification system inspired by GitHub's internal spec-kit, where every feature lives in its own specs/NNNN-slug/ directory and its lifecycle is tracked through git branches.

On top of these two, zspec wires in Serena MCP — a Model Context Protocol server for AI agents — so that Copilot, Claude, or any MCP-capable agent can navigate and edit your codebase with structured tools instead of raw file reads.

---

Table of contents

• Why zspec?
• Installation
• Quick start
• Commands
  • init
  • story
  • new
  • use
  • status
  • mcp
• Repo layout after init
• The story workflow
• The zspec workflow
• The Speckit workflow
• Copilot custom agents
• Serena MCP integration
• Skills
• npm scripts
• Contributing
• License

---

Why zspec?

Modern software teams work with AI coding assistants every day. Those assistants produce better results when they have:

1. Clear specs — a written description of what to build, why, and what "done" looks like.
2. A defined workflow — a short loop that drives tasks to completion without endless back-and-forth.
3. Structured tool access — MCP tooling so the agent can search symbols, read files, and make safe edits.

zspec gives you all three with a single npx zspec init command.

---

Installation

# Use without installing (recommended for initial scaffold)
npx zspec init

# Or install globally
npm install -g zspec

# Or as a dev dependency
npm install --save-dev zspec

Requires Node.js ≥ 18.

---

Quick start

# 1. Scaffold conventions into your repo
npx zspec init

# 2. Create a story for a new feature
zspec story "add billing"

# 3. Run @codebase-mapper in Copilot Chat to analyze the codebase
# @codebase-mapper story-slug: add-billing

# 4. Implement tasks in .zspec/stories/add-billing/tasks.md

# 5. Or use the older spec-based workflow
zspec new "add billing"

# 6. Check status at any time
zspec status

# 7. Set up Serena MCP in your client
zspec mcp

---

Commands

init

zspec init [--force|--upgrade]

Scaffolds the following into your current working directory:

Path	Purpose
AGENTS.md	Agent operating manual (workflows, rules, agent guide)
.github/copilot-instructions.md	Repo-wide Copilot instructions
.github/agents/	Copilot custom agent definitions (5 agents)
.zspec/stories/	Story storage root
.zspec/templates/	Story and codebase doc templates
specs/0000-template/	Spec/plan/tasks templates for new features
zspec/run.mjs	zspec task runner (spec lifecycle, git helpers, repo summary)
zspec/logs/progress.md	Progress log appended by agents after each session
zspec/checklists/definition-of-done.md	Checklist agents verify before closing a feature
zspec/memory/	Persistent agent memory (constitution, project principles)
mcp/serena.json	Serena MCP client config
scripts/serena.mjs	Serena launcher script (stdio or HTTP/SSE)
skills/	Optional skill modules for specialized tasks

If a package.json is present in the repo root, init also injects zspec and spec npm scripts (see npm scripts).

init modes:

• default: only creates missing scaffold files (does not overwrite existing files)
• --upgrade: updates scaffold files outside .zspec/ and keeps existing .zspec/ files intact
• --force: overwrites scaffold files everywhere, including .zspec/

---

story

zspec story <story-name>

Creates a new story scaffold under .zspec/stories/<story-slug>/.

What it does:

1. Slugifies the story name (lowercase, hyphens, max 60 chars).
2. Creates the story directory with all required files.
3. Prints a Copilot-ready prompt to kick off codebase analysis with @codebase-mapper.

Example:

zspec story "user authentication"
# Creates: .zspec/stories/user-authentication/
#   story.md · context.md · tasks.md · notes.md
#   codebase/STACK.md · INTEGRATIONS.md · ARCHITECTURE.md
#   codebase/STRUCTURE.md · CONVENTIONS.md · TESTING.md · CONCERNS.md
# Prints: @codebase-mapper invocation prompt

The codebase/ files are initially empty placeholders. Run @codebase-mapper story-slug: <slug> in Copilot Chat to populate them.

---

new

zspec new <feature-name>

Creates a new spec directory and optionally a git branch for the feature.

What it does:

1. Computes the next spec number (NNNN) by scanning specs/ for existing numbered directories.
2. Slugifies the feature name (lowercase, hyphens, max 60 chars).
3. Creates specs/NNNN-slug/spec.md from the template in specs/0000-template/spec.md (falls back to a built-in template if not present).
4. If the current directory is a git repo, creates a feature branch named NNNN-slug and commits the new spec.
5. Prints a Copilot-ready prompt you can paste directly into your AI assistant to kick off the feature.

Example:

zspec new "user authentication"
# Creates: specs/0001-user-authentication/spec.md
# Branch:  0001-user-authentication
# Prints:  agent prompt

---

use

zspec use <skill-name>

Prints a skill activation prompt for your AI assistant. Skills live in skills/<skill-name>/SKILL.md after init.

Built-in skills (scaffolded by init):

Skill	Purpose
zspec-core	Small diffs, verification-first, progress logging
speckit-core	Clear specs with goals, non-goals, and acceptance criteria
frontend-design	UI/component/layout conventions

Example:

zspec use frontend-design
# Prints: skill activation prompt to paste into your AI assistant

---

status

zspec status

Summarizes the current state of the repo:

• Lists the most recent 10 specs (by directory name) with their branch status:
  • ▶ current — the currently checked-out branch
  • ○ active — branch exists but not yet merged
  • ✓ done — branch merged into main/master
  • no-branch — spec files exist but no associated git branch
• Prints the last 20 lines of zspec/logs/progress.md if present.

---

mcp

zspec mcp

Prints setup instructions for connecting Serena MCP to your AI client, including:

• Stdio mode: client spawns Serena as a subprocess via scripts/serena.mjs stdio
• HTTP/SSE mode: you run Serena as a server, client connects to http://127.0.0.1:9123

See the Serena docs for client-specific configuration.

---

Repo layout after init

.
├── AGENTS.md                               # Agent operating manual
├── .github/
│   ├── copilot-instructions.md             # Repo-wide Copilot instructions
│   ├── agents/
│   │   ├── codebase-mapper.agent.md        # Orchestrator: full codebase analysis
│   │   ├── stack-mapper.agent.md           # Stack and integrations analysis
│   │   ├── arch-mapper.agent.md            # Architecture and structure analysis
│   │   ├── quality-mapper.agent.md         # Conventions and testing analysis
│   │   └── concerns-mapper.agent.md        # Technical concerns analysis
│   ├── ISSUE_TEMPLATE/
│   └── pull_request_template.md
├── .zspec/
│   ├── templates/
│   │   ├── story.md                        # Story template
│   │   ├── context.md                      # Context template
│   │   ├── tasks.md                        # Tasks template
│   │   ├── notes.md                        # Notes template
│   │   └── codebase/
│   │       ├── STACK.md
│   │       ├── INTEGRATIONS.md
│   │       ├── ARCHITECTURE.md
│   │       ├── STRUCTURE.md
│   │       ├── CONVENTIONS.md
│   │       ├── TESTING.md
│   │       └── CONCERNS.md
│   └── stories/
│       └── <story-slug>/                   # One directory per story (zspec story)
│           ├── story.md
│           ├── context.md
│           ├── tasks.md
│           ├── notes.md
│           └── codebase/
│               ├── STACK.md
│               ├── INTEGRATIONS.md
│               ├── ARCHITECTURE.md
│               ├── STRUCTURE.md
│               ├── CONVENTIONS.md
│               ├── TESTING.md
│               └── CONCERNS.md
├── specs/
│   ├── 0000-template/                      # Template files for new specs
│   │   ├── spec.md
│   │   ├── plan.md
│   │   └── tasks.md
│   └── 0001-add-billing/                   # One directory per feature
│       ├── spec.md
│       ├── plan.md
│       └── tasks.md
├── zspec/
│   ├── run.mjs
│   ├── logs/progress.md
│   ├── checklists/definition-of-done.md
│   ├── memory/constitution.md
│   └── playbooks/add-endpoint.md
├── mcp/serena.json
├── scripts/serena.mjs
└── skills/
    ├── zspec-core/SKILL.md
    ├── speckit-core/SKILL.md
    └── frontend-design/SKILL.md

---

The story workflow

The story workflow organizes work by user story with Copilot custom agents:

1. Create a story:

zspec story "user authentication"
# → .zspec/stories/user-authentication/

2. Analyze the codebase:

In Copilot Chat, invoke the orchestrator agent:

@codebase-mapper story-slug: user-authentication

This delegates to four specialized mapper agents and populates the codebase/ folder with story-scoped documentation.

3. Implement:

• Follow the checklist in tasks.md
• Reference codebase/ARCHITECTURE.md, codebase/CONCERNS.md, etc.
• Record decisions in notes.md
• Update tasks.md as work completes

4. Review:

The review checklist in tasks.md ensures all acceptance criteria from story.md are met.

---

The zspec workflow

zspec is a lightweight loop designed to keep AI-assisted development moving without thrash:

1. Load context — read the active spec(s) and the Definition of Done.
2. Ask bounded questions — at most 7 critical questions; proceed with explicit assumptions if info is missing.
3. Plan — 3–7 PR-sized steps (small, reviewable, easy to roll back).
4. Execute — prefer Serena MCP tools for symbol lookup, references, and safe edits.
5. Verify — run tests, lint, typecheck if present; provide a manual verification plan otherwise.
6. Log — append a short entry to zspec/logs/progress.md: what changed, how to verify, any risks.

The zspec task runner (node zspec/run.mjs) provides spec lifecycle commands:

node zspec/run.mjs spec:new "feature name"   # create spec
node zspec/run.mjs spec:add-plan             # scaffold plan.md
node zspec/run.mjs spec:add-tasks            # scaffold tasks.md
node zspec/run.mjs spec:list                 # list all specs with status
node zspec/run.mjs spec:done                 # merge instructions
node zspec/run.mjs repo:summary              # instant repo context for agents
node zspec/run.mjs git:pr-body               # generate PR body from active spec

---

The Speckit workflow

zspec uses GitHub's spec-kit approach: one directory per feature, one git branch per feature. Lifecycle is tracked through git, not folder renames.

Creating a spec:

zspec new "user authentication"
# → specs/0001-user-authentication/spec.md
# → git branch: 0001-user-authentication

Filling in the spec (spec.md template sections):

• Problem — what are we fixing/building, and why now?
• Goal — what does success look like? (measurable outcomes)
• Non-goals — explicitly what we are NOT doing
• Constraints — tech, performance, security, timeline
• Proposed solution — high-level design + alternatives considered
• Acceptance criteria — checkboxes, each verifiable
• Risks / unknowns

Adding a plan and tasks:

node zspec/run.mjs spec:add-plan    # creates specs/0001-.../plan.md
node zspec/run.mjs spec:add-tasks   # creates specs/0001-.../tasks.md

Completing a feature:

node zspec/run.mjs spec:done        # switch to main + print merge instructions
# Merge the branch, then:
git branch -d 0001-user-authentication

Rejecting a feature:

node zspec/run.mjs spec:reject      # delete branch; spec files kept for reference

---

Copilot custom agents

zspec init scaffolds five Copilot-compatible agent files in .github/agents/. Use them in Copilot Chat with @agent-name.

Agent	Purpose	User-Invocable
@codebase-mapper	Orchestrates full codebase analysis for a story	✅
@stack-mapper	Analyzes tech stack and third-party integrations	✅
@arch-mapper	Analyzes architecture, layers, and file structure	✅
@quality-mapper	Analyzes conventions and testing patterns	✅
@concerns-mapper	Identifies technical concerns, debt, and risks	✅

Orchestration pattern:

@codebase-mapper
  → @stack-mapper     → codebase/STACK.md, INTEGRATIONS.md
  → @arch-mapper      → codebase/ARCHITECTURE.md, STRUCTURE.md
  → @quality-mapper   → codebase/CONVENTIONS.md, TESTING.md
  → @concerns-mapper  → codebase/CONCERNS.md

Example usage:

@codebase-mapper story-slug: add-billing

---

Serena MCP integration

Serena is an open-source MCP server that gives AI agents structured access to your codebase:

• Symbol search — find classes, functions, variables by name
• File navigation — open, read, navigate files with context
• Safe edits — make targeted code edits with agent guardrails

Setup after zspec init:

# Print setup instructions for your MCP client
zspec mcp

# Option 1: Stdio mode (client manages process lifecycle)
node scripts/serena.mjs stdio

# Option 2: HTTP/SSE mode
node scripts/serena.mjs http --port 9123
# Configure client URL: http://127.0.0.1:9123

The mcp/serena.json file contains a pre-built Serena client config. The SERENA_CMD environment variable overrides the Serena binary (useful with uvx serena or custom installs).

---

Skills

Skills are constraint files that agents apply when working on specific types of tasks. They live in skills/<skill-name>/SKILL.md.

Activating a skill:

zspec use frontend-design
# Prints an activation prompt to paste into your AI assistant

Creating a custom skill:

mkdir -p skills/my-skill
cat > skills/my-skill/SKILL.md << 'EOF'
# my-skill

Purpose: describe what this skill does.

Rules:
- rule one
- rule two
EOF

---

npm scripts

zspec init injects the following scripts into your package.json (non-destructive unless --force):

Script	Command
spec:new	node zspec/run.mjs spec:new
spec:list	node zspec/run.mjs spec:list
spec:init	node zspec/run.mjs spec:init
spec:add-plan	node zspec/run.mjs spec:add-plan
spec:add-tasks	node zspec/run.mjs spec:add-tasks
spec:commit	node zspec/run.mjs spec:commit
spec:done	node zspec/run.mjs spec:done
spec:reject	node zspec/run.mjs spec:reject
zspec:repo	node zspec/run.mjs repo:summary
zspec:diff	node zspec/run.mjs git:diff-summary
zspec:plan	node zspec/run.mjs spec:plan
zspec:pr	node zspec/run.mjs git:pr-body
zspec:check	node zspec/run.mjs checks:all

Usage:

npm run spec:new -- "my feature"
npm run spec:list
npm run zspec:repo

---

Contributing

1. Fork the repo and create a feature branch.
2. Run zspec init in a temp directory to smoke-test your changes.
3. Run tests: npm test
4. Submit a PR with a filled-out PR template.

---

License

MIT