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