Getting Started

From zero to acceptance in 5 minutes.

---

Install

npm install -g speclore

Prerequisites

Node.js 18+

---

5-Minute Tutorial

1. Initialize Your Project

cd your-project && speclore setup

setup runs only once. It detects your AI tools, writes MCP config, and generates .speclore/config.yaml.

2. Generate Acceptance Criteria from Requirements

speclore spec "Patient registration requires phone verification and WeChat login"

Outputs specs/patient/register.feature with 3 BDD acceptance scenarios.

Supports any requirement source format:

speclore spec requirements.md          # Markdown
speclore spec design.docx              # Word
speclore spec specs.xlsx               # Excel
speclore spec https://jira.example/123 # URL

3. Generate Coding Constraints + Test Scaffolding

speclore code

Generates constraint rule files for your AI coding tools, plus test scaffolding (it.skip placeholders).

4. Code, Then Run Acceptance

Code in your AI client, fill in the test scaffolding, then:

speclore verify

✔ 3/3 scenarios passed (100%)

specs/patient/register.feature
  ✓ Register with valid phone number    → passed
  ✓ Reject invalid phone format         → passed
  ✓ Warn on duplicate phone number      → passed

✅ Acceptance passed

---

Other Ways to Use

The tutorial above uses the CLI. SpecLore also supports two other approaches:

MCP + AI Client (Recommended)

If you use Cursor, Qoder, or Claude Code, you can complete the entire workflow with natural language — no manual CLI commands needed.

Step 1: Open your project in the AI client first

Make sure your AI client (Cursor / Qoder / Claude Code) has the current project open. This matters because setup needs to detect the client's directory before writing MCP config:

AI Client	Required detection marker	Config file written
Cursor	.cursor/ directory exists	.cursor/mcp.json
Qoder	.qoder/ or .qoder-cn/ directory exists	.qoder/mcp.json or .qoder-cn/mcp.json
Claude Code	.claude/ directory or CLAUDE.md exists	.mcp.json (project root)

Step 2: Run setup

cd your-project && speclore setup

setup auto-detects your AI client and writes the SpecLore MCP server into the corresponding config file. You don't need to manually edit any MCP config.

Client not detected?

If setup did not detect your AI tool, configure it manually:

speclore mcp add cursor   # Write MCP config for Cursor (auto-creates .cursor/)
speclore mcp add claude   # Write MCP config for Claude Code
speclore mcp add qoder    # Write MCP config for Qoder (auto-creates .qoder/)
speclore mcp list         # Show MCP config status for all clients

Step 3: Restart the AI client

After setup completes, restart or reopen your AI client so it loads the new MCP configuration.

Step 4: Just chat

Open your AI client and describe your requirement in natural language:

You: Help me implement patient registration with phone verification

AI (calls speclore.spec): Generated specs/patient/register.feature with 3 acceptance scenarios

AI (calls speclore.code): Generated coding constraints and test scaffolding

You: Run acceptance

AI (calls speclore.verify): ✅ 3/3 scenarios passed (100%)

No manual CLI commands needed. The AI calls SpecLore tools directly via MCP, automatically advancing the workflow.

Hybrid

CLI for initialization and requirement generation, AI client for coding and acceptance:

speclore setup
speclore spec requirements.md
speclore code

Then code in your AI client, and let AI call speclore.verify for acceptance.

---

Workflow States

speclore.status → speclore.spec → speclore.code → (AI codes) → speclore.verify
   check status    generate feature  constraints+scaffold   implement     verify tests
       ↓                ↓               ↓               ↓              ↓
   project state   → specified     → constrained     → coding     → verified

Out-of-order calls produce clear errors:

Out-of-order scenario	Error message
Call code without .feature files	No .feature files found. Run speclore.spec first.
Call verify without test scaffolding	No test scaffolding. Run speclore.code first.
Project not initialized	Auto-creates .speclore/config.yaml

---

Next Steps

• Learn the full Workflow state machine
• Check the Configuration Reference for all config options
• Explore MCP Tools in detail
• See Test Mapping for how test results map to acceptance scenarios