# SPECLAN > SPECLAN is a VS Code extension for specification engineering. It provides a layered, Git-native framework for turning ideas into traceable, machine-processable specifications with AI agents that do the heavy lifting. SPECLAN treats specifications as first-class engineering artifacts stored as Markdown files with YAML frontmatter directly in your repository. The entity hierarchy flows from Goals through Features (with hierarchical sub-features) down to Requirements. AI agents generate, refine, and validate specifications on your behalf. Full traceability links every requirement back to a business goal. - Website: https://speclan.net - GitHub: https://github.com/thlandgraf/speclan-essentials - Install: `code --install-extension DigitalDividend.speclan-vscode-extension` ## About ### Home Source: https://speclan.net/ ## Your Specification Is Your Prompt The missing middle layer between business intent and AI coding agents. SPECLAN turns loose ideas into layered, traceable specifications — right inside VS Code. Git-native. AI-powered. Built for developers who ship. ### From Idea to Spec to Code in Four Steps SPECLAN gives you a repeatable path from a rough idea to a production-ready specification — with AI doing the heavy lifting. 1. **Capture the Idea** - Start with a business goal or a napkin sketch. SPECLAN creates a structured Goal entity and stores it as a Markdown file in your repo. 2. **Break It Down** - Decompose goals into features, nest sub-features to any depth, and attach detailed requirements. AI agents suggest the next level of detail. 3. **Validate and Refine** - Review specs in a WYSIWYG editor, run traceability checks, and move entities through a status lifecycle — from draft to approved. 4. **Generate and Ship** - Hand specs to an AI coding assistant that finally knows what to build. Or export for downstream tools. ### Key Features - **Layered Hierarchy**: Structure specs from business goals through features and sub-features to detailed requirements. Every requirement traces back to a reason, every feature to a goal. - **Git-Native Specs**: Specifications live as Markdown files with YAML frontmatter — right next to your code. Branch, diff, and merge specs the same way you merge code. - **AI-Powered Agents**: AI agents powered by Claude, Google Gemini, or OpenAI generate, refine, and validate specifications on your behalf. Go from a one-liner to a full spec tree in minutes, not days. Three providers. Your choice. Zero lock-in. - **VS Code Integration**: Same file, same tool, two experiences: a Markdown text editor for developers and a WYSIWYG editor for everyone else. Plus tree views, status badges, and contextual actions — all inside VS Code. - **Full Traceability**: Trace any requirement back through its feature tree — sub-features, features, and business goals. Bidirectional links let you navigate the full chain. Know exactly why every line of code exists. - **Status Lifecycle**: Move specs from draft to review to approved to released. Once in development, specs are locked — change requests let you iterate without creating moving targets. - **Change Requests**: Need to update a spec that’s already in development or released? Create a formal change request. The change is tracked, reviewed, and merged in the next dev cycle. - **MCP Integration**: Expose your specifications to the AI ecosystem through 43 Model Context Protocol tools. Any AI assistant that supports MCP can read, create, and manage your specs natively. --- ### Features Source: https://speclan.net/features/ AI coding agents are only as good as their input. SPECLAN gives you the framework to turn loose ideas into structured specifications that AI can actually act on — layered, traceable, Git-native, and built right into VS Code. ### Layered Specifications Structure requirements from business goals down to detailed requirements using a layered hierarchy: Goals, Features (with hierarchical Sub-Features), and Requirements. Features can nest to any depth, letting you decompose complex systems naturally. The hierarchy is flexible — start at any level and let AI fill in the rest. ### Git-Native Workflow Specifications live as Markdown files with YAML frontmatter, stored directly in your repository. Track changes with git diff, review specs in pull requests, branch for experiments, and merge when ready. No external database, no vendor lock-in, no syncing headaches. Your specs travel with your code — always in context, always versioned. ### AI-Powered Agents Integrated AI agents — powered by Claude, Google Gemini, or OpenAI — generate, refine, and validate specifications on your behalf. Describe a feature in a sentence and watch the agent produce a full requirement tree. Agents also detect gaps, suggest improvements, and flag inconsistencies. You stay in control — every suggestion is a proposal, never an override. ### VS Code Integration A purpose-built extension with spec tree views, a WYSIWYG Markdown editor, status badges, and contextual actions. Create, navigate, and edit specifications without leaving your editor. Git status colors show which specs have changed, and the command palette gives you quick access to every operation. It feels like a native part of VS Code because it is. ### Full Traceability Trace any requirement back through sub-features, features, and business goals. Bidirectional links mean you can also start at a goal and see every requirement that implements it. Traceability reports surface orphaned specs and incomplete chains. Know exactly why every line of code exists — and prove it. ### Status Lifecycle Move specifications through a formal lifecycle: draft, review, approved, in-development, and released. Status transitions enforce rules — you cannot approve a spec that still has draft children. Once a spec enters development, it is locked to prevent moving targets. When you need to change a spec in development or later, create a change request — it follows its own lifecycle and merges in the next sprint. --- ### About SPECLAN Source: https://speclan.net/about/ ### Mission We believe specifications should be living documents that evolve with your software — not artifacts buried in a wiki that nobody reads. ### Story SPECLAN was born from a simple frustration: specs scattered across Google Docs, Jira tickets, Confluence pages, and Slack threads. Nobody could find the current version, nobody knew if a requirement had been tested, and AI coding assistants had no idea what to build. So we built a system where specifications live in the repo — structured enough for machines to process, human-friendly enough for developers to actually maintain. It started with a whiteboard sketch and a question: What if your specification was your prompt? The same pattern kept repeating — someone would write requirements in a document, a developer would interpret them differently, QA would test against a third understanding, and the AI coding assistant would hallucinate a fourth. The problem was never the people. It was the medium. SPECLAN puts specifications where they belong: in the repository, as structured Markdown files that humans can read, machines can process, and AI agents can act on. ### Principles - **Specs Are Code**: Specifications are engineering artifacts, not paperwork. They belong in the repository, versioned with git, reviewed in pull requests, and treated with the same rigor as source code. - **Structure Enables AI**: A well-structured spec tree is the best prompt an AI agent can receive. When your requirements are layered and traceable, AI generates better code, better tests, and better suggestions. - **Developer-First**: SPECLAN lives in VS Code because that is where developers live. No context switching, no browser tabs, no separate tools. Everything is a keyboard shortcut away. - **No Lock-In**: Your specifications are plain Markdown files with YAML frontmatter. If you stop using SPECLAN tomorrow, your specs are still readable, portable, and yours. No proprietary formats, no export gymnastics. --- ## Documentation ### Getting Started: New Project Source: https://speclan.net/help/getting-started/greenfield/ You have a new project idea. No code yet. No specs. Just an idea and the motivation to build something. This guide walks you through setting up SPECLAN from zero. By the end, you will have a structured specification tree and a clear path to implementation -- whether you write the code yourself or hand it to an AI coding assistant. ### What SPECLAN Does -- and What It Does Not SPECLAN is a **specification tool**. It helps you describe *what* your system should do from the user's perspective, and it manages the lifecycle of those specifications -- from first draft through review, approval, implementation, testing, and release. SPECLAN is **technology-agnostic**. It does not know or care whether you build with TypeScript, Python, Rust, Java, or anything else. It does not generate code. It does not choose frameworks. It does not make architecture decisions. What SPECLAN *does* is inject your approved specifications into your preferred implementation assistant -- Claude Code, Gemini CLI, Cursor, Aider, or any other AI coding tool. Your specifications become the prompt. The implementation assistant turns them into code. SPECLAN owns the *what*; you and your tools own the *how*. This means **technology decisions are yours**. You choose the language, the framework, the database, the deployment target. You document those choices in your project (Step 5 shows you how), and your implementation assistant picks them up from there. ## What You Will Build Following this guide, you will: 1. Set up a project directory with version control 2. Initialize SPECLAN in your project 3. Create a specification tree -- Goals, Features, and Requirements 4. Move your specifications through the review lifecycle 5. Prepare your project for AI-assisted implementation 6. Hand your specifications to an AI coding assistant Each step builds on the previous one. Take them in order. --- ## Step 1: Set Up Your Project SPECLAN specifications live alongside your source code. Before you can write specs, you need a project. ### Create your project directory Start with an empty directory. If you use a project scaffolding tool -- NX, Angular CLI, Gradle, Create React App, or similar -- now is the time to run it. ```bash # Option A: Start completely empty mkdir my-project && cd my-project # Option B: Scaffold with your preferred tool npx create-nx-workspace@latest my-project # or: ng new my-project # or: gradle init # or: npx create-next-app@latest my-project ``` If you are truly starting from scratch and have not decided on a tech stack yet, that is fine. Start with an empty directory. You can scaffold later -- SPECLAN does not care what language or framework you use. ### Initialize Git SPECLAN depends on Git. It uses Git for collaboration, change tracking, and status coloring in the tree view. Initialize a repository if your scaffolding tool did not already do so: ```bash git init git add -A && git commit -m "initial commit" ``` ### Open the project in VS Code ```bash code my-project ``` --- ## Step 2: Initialize SPECLAN With your project open in VS Code and the SPECLAN extension installed, look for the **SPECLAN** panel in the sidebar. If the project does not yet have a `speclan/` directory, the tree view shows an **"Initialize SPECLAN"** button. Click it. SPECLAN creates the directory structure automatically: ``` my-project/ ├── src/ # your source code (if scaffolded) ├── speclan/ # SPECLAN creates this │ ├── goals/ │ ├── features/ │ └── templates/ ├── .git/ └── package.json # (if scaffolded) ``` That is the entire setup. No database. No server. No configuration files. Your specifications are plain Markdown files with YAML frontmatter, stored right inside your project. --- ## Step 3: Create Your Specification This is the core of the guide. You have two paths to get started, depending on how much you already know about what you are building. ### Path A: Start From a Description (HLRD Import) If you have a rough description of your project -- a product brief, meeting notes, a brainstorm document, or even a few paragraphs of text -- the **HLRD Import Assistant** can turn it into structured specifications. 1. Open the **AI Assistants** panel in the SPECLAN sidebar 2. Click **HLRD Import** 3. Paste or import your description -- it can be as rough as a few sentences or as detailed as a stakeholder brief 4. The assistant analyzes your input and generates a structured specification tree: Goals, Features, and Requirements The generated specs land in your `speclan/` directory as Markdown files, all in **draft** status. Review them, edit anything that needs adjustment, and continue to Step 4. This is the fastest way to go from "I have an idea" to a structured specification tree. ### Path B: Build It Manually If you prefer to think through each specification yourself, build the tree from the top down. SPECLAN follows a clear hierarchy: ``` Goal --> Feature --> Requirement ``` Each level answers a different question: | Entity | Question It Answers | Example | |--------|-------------------|---------| | **Goal** | What business outcome do we want? | "Enable users to manage their tasks efficiently" | | **Feature** | What capability do we build to reach that goal? | "Task List View", "Task Creation Form" | | **Requirement** | What exactly must this feature do? | "The task list displays all tasks sorted by due date" | #### Create a Goal Right-click in the **Goals** tree view and select **New Goal**. Give it a short, outcome-oriented title. A good Goal describes a desired outcome, not a feature: - "Enable users to manage their daily tasks" -- outcome-oriented - "Build a task management app" -- too implementation-focused Goals use the ID pattern `G-###` (three digits). SPECLAN assigns a random, collision-checked ID automatically. #### Create a Feature Right-click on a Goal or in the **Features** tree view and select **New Feature**. Features describe capabilities your system provides. A good Feature is a user-visible capability: - "Task List View" -- clear capability - "Database schema" -- implementation detail, not a feature Features use the ID pattern `F-####` (four digits). Features can contain sub-features, forming a tree: ``` F-1234 Task Management ├── F-5678 Task List View ├── F-9012 Task Creation └── F-3456 Task Editing ``` #### Create a Requirement Right-click on a Feature and select **New Requirement**. Requirements are the most specific level -- they define exactly what a feature must do. A good Requirement is testable and unambiguous: - "The task list displays all tasks belonging to the current user, sorted by due date ascending" -- specific, testable - "The task list should work well" -- too vague Requirements use the ID pattern `R-####` (four digits). Each Requirement belongs to exactly one Feature. #### Write Acceptance Criteria Inside each Requirement, add an **Acceptance Criteria** section with checkbox items: ```markdown ## Acceptance Criteria - [ ] The task list loads within 2 seconds - [ ] Tasks are sorted by due date in ascending order - [ ] Overdue tasks are visually highlighted - [ ] Empty state shows a message when no tasks exist ``` These checkboxes define what "done" looks like. They become the contract between the specification and the implementation. --- ## Step 4: Refine Your Specifications Every specification starts in **draft** status. Before it can be implemented, it needs to move through the lifecycle: ``` draft --> review --> approved ``` ### Draft Your specs start here. Edit freely. Rework the wording. Add acceptance criteria. Remove things that do not belong. There is no pressure -- drafts are working documents. ### Review When a specification is ready, transition it to **review**. This signals that it is ready for feedback -- from stakeholders, team members, or even just your own fresh-eyes read-through. Right-click a specification in the tree view and select **Transition Status** to move it forward. During review, read each specification and ask: - Is the title clear? - Are the acceptance criteria specific enough to test? - Does this belong at this level of the hierarchy? (Goal vs. Feature vs. Requirement) - Is anything missing? ### Approved Once a specification passes review, transition it to **approved**. Approved specs are still editable -- this is your last window to refine before development starts. Once the spec moves to **in-development**, it becomes locked and any further changes require a formal Change Request. **Approved status means:** this specification is the authoritative reference for what needs to be built. It is the contract. You do not need to approve everything at once. Approve the specifications you want to implement first. The rest can stay in draft or review until you are ready. --- ## Step 5: Prepare for Implementation Your specifications describe *what* to build. The *how* is entirely your decision -- SPECLAN stays out of technology choices by design. Before handing specifications to an implementation assistant, you need to make and document your technology decisions. Which language? Which framework? Which database? These choices are yours. SPECLAN will inject your specifications into whichever AI coding tool you prefer, but that tool needs to know your tech stack to generate the right code. Here are several ways to communicate your technology choices: ### Option A: Scaffold first, specify second If you already scaffolded your project in Step 1 (using NX, Angular CLI, Next.js, etc.), the project structure itself communicates the tech stack. The AI assistant can read `package.json`, `build.gradle`, `Cargo.toml`, or whatever configuration your framework uses. ### Option B: Write a CLAUDE.md Create a `CLAUDE.md` file in your project root. This file is read by Claude Code at the start of every session. Use it to document your technology decisions: ```markdown # CLAUDE.md ## Tech Stack - TypeScript with Node.js - React for the frontend - PostgreSQL for persistence - Express for the API layer ## Conventions - Use functional components with hooks - Tests with Vitest - API routes follow REST conventions ``` ### Option C: Document your decisions in a Markdown file Create a `techstack.md`, `architecture.md`, or similar file in your project root. Any AI assistant with file system access will find it and use it as context: ```markdown # Technology Decisions We use Python with FastAPI for the backend, React with TypeScript for the frontend, and SQLite for local development. ``` The key insight: AI coding assistants read your project's files for context. The more clearly you document your decisions, the better the generated code will match your expectations. --- ## Step 6: Implement With AI With approved specifications and your technology decisions documented, you are ready to build. This is where SPECLAN hands off to your implementation assistant. SPECLAN's job was to help you define *what* to build and shepherd those specifications through their lifecycle. Now it injects those specifications into your preferred AI coding tool and lets it do the implementation work. ### Using the Implementation Assistant SPECLAN includes a built-in **Implementation Assistant** that bridges your specifications and your AI coding tool of choice. 1. Open the **AI Assistants** panel in the SPECLAN sidebar 2. Click **Implementation Assistant** 3. The assistant scans for specifications in **approved** status 4. Select which specifications to implement 5. The assistant generates an optimized implementation plan with ready-made prompts 6. Copy each prompt into your AI coding tool (Claude Code, Gemini CLI, Cursor, Aider, etc.) 7. Mark tasks complete as you go The assistant groups specifications into **implementation units** -- a leaf feature bundled with its requirements. It sequences them based on dependencies, technical complexity, and business value. You get a step-by-step plan with prompts you can copy and paste. ### Without the Implementation Assistant You can also hand specifications directly to your AI coding assistant. Since SPECLAN specs are plain Markdown files, any tool that reads files can use them: ```bash # In Claude Code, reference a spec directly claude "Implement the requirement described in speclan/features/F-1234-task-list/requirements/R-5678-sort-by-date/R-5678-sort-by-date.md" ``` Or point the assistant at your entire specification tree: ```bash claude "Read the speclan/ directory and implement all approved specifications" ``` The specifications are your prompt. The better the spec, the better the code. --- ## What You Have Now If you followed each step, your project contains: - A Git repository with your source code (or scaffolding) - A `speclan/` directory with your specification tree - Goals that describe your business outcomes - Features that describe your system's capabilities - Requirements with acceptance criteria that define exactly what each feature must do - Approved specifications ready for implementation - Technology decisions documented for your AI assistant This is a complete starting point. Your specifications will evolve as your project grows -- that is expected. Approved specs are still editable, but once they enter development, use [Change Requests](/help/workflows/change-requests/) to propose modifications for the next sprint. Keep drafting new ones as you discover what else needs to be built. ## Next Steps - [Requirements Workflow](/help/workflows/requirements-workflow/) -- Deep dive into the draft-to-approved process - [Development Workflow](/help/workflows/development-workflow/) -- How to manage the implementation phase - [Goals](/help/concepts/goals/), [Features](/help/concepts/features/), [Requirements](/help/concepts/requirements/) -- Detailed concept guides - [Entity Types](/help/reference/entity-types/) -- Complete reference for all SPECLAN entities - [Change Requests](/help/workflows/change-requests/) -- How to modify specifications in development or later --- ### Getting Started: Existing Project Source: https://speclan.net/help/getting-started/brownfield/ You have a project. It has code, it has history, it has momentum. Now you want to bring structure to what comes next. This guide walks you through adopting SPECLAN in an existing codebase. Unlike the [greenfield guide](/help/getting-started/greenfield/) where everything starts from zero, brownfield adoption meets you where you are. Your project keeps running. Your code stays untouched. SPECLAN adds a specification layer on top -- nothing more, nothing less. ### What SPECLAN Does -- and What It Does Not SPECLAN is a **specification tool**. It describes *what* your system should do from the user's perspective and manages the lifecycle of those specifications -- from draft through review, approval, implementation, testing, and release. SPECLAN is **technology-agnostic**. It does not alter your source code, your build pipeline, your dependencies, or your project structure. The only thing SPECLAN adds to your project is a single `speclan/` directory at the project root. Everything SPECLAN needs lives inside that directory -- plain Markdown files with YAML frontmatter, tracked by Git alongside your code. When it is time to implement new functionality, SPECLAN injects your approved specifications into your preferred AI coding tool -- Claude Code, Gemini CLI, Cursor, Aider, or any other implementation assistant. Since your project already exists, the implementation assistant will infer your tech stack, coding patterns, and library choices from your codebase automatically. No configuration needed. ## What You Will Do 1. Initialize SPECLAN in your existing project 2. Infer specifications from your codebase using AI 3. Review and restructure the inferred specifications 4. Mark already-implemented specs as released 5. Write new specifications for what you want to build next 6. Hand approved specs to your implementation assistant --- ## Step 1: Initialize SPECLAN Your project directory already exists and is under Git management. No scaffolding, no setup -- you are ahead of the greenfield crowd. Open your project in VS Code. Find the **SPECLAN** panel in the sidebar. Click **"Initialize SPECLAN"**. That is it. SPECLAN creates one directory: ``` your-project/ ├── src/ # your existing code -- untouched ├── tests/ # your existing tests -- untouched ├── package.json # your existing config -- untouched ├── speclan/ # NEW -- SPECLAN creates only this │ ├── goals/ │ ├── features/ │ └── templates/ └── .git/ ``` Nothing else changes. Your source code, your configuration, your build pipeline, your dependencies -- all untouched. SPECLAN lives entirely inside `speclan/`. --- ## Step 2: Infer Specifications From Your Codebase Your project already has functionality. Rather than writing specifications from scratch for everything that already exists, let the **Codebase Inference Assistant** read your code and generate a specification tree. 1. Open the **AI Assistants** panel in the SPECLAN sidebar 2. Click **Infer Specs from Codebase** 3. The assistant scans your project -- source files, configuration, directory structure, tests 4. It generates a specification tree: Goals, Features, and Requirements inferred from what it finds The generated specs land in your `speclan/` directory as Markdown files, all in **draft** status. ### A Word of Caution Code-to-specification inference is useful but imperfect. The assistant reads implementation details and tries to reconstruct the intent behind them. This is inherently working backwards -- specifications are supposed to describe *what* before the *how* exists, not after. What you get is a reasonable starting point, not a finished specification tree. Expect: - **Specifications that mirror code structure rather than user needs.** The assistant may create a feature for every module or service it finds, even when those are internal implementation details, not user-facing capabilities. - **Missing higher-level goals.** Business context lives in people's heads, not in source code. The assistant cannot infer why a feature exists, only that it does. - **Overly technical language.** Inferred specs tend to describe what the code does rather than what the user experiences. A good specification says "Users can filter tasks by due date." An inferred spec might say "The TaskFilterService accepts a dateRange parameter." - **Incomplete acceptance criteria.** The assistant generates criteria based on test coverage and code behavior, but it cannot know about edge cases or requirements that were never implemented. This is fine. The inference gives you raw material. Step 3 is where you turn it into something valuable. --- ## Step 3: Review and Restructure This is the most important step. The quality of your specification tree determines the quality of everything that follows -- implementation plans, AI-generated code, test coverage, and team communication. Go through the inferred specifications and restructure them from the user's perspective: ### Reorganize the hierarchy SPECLAN follows a three-level hierarchy: | Entity | Question It Answers | Example | |--------|-------------------|---------| | **Goal** | What business outcome does this serve? | "Enable customers to self-manage their accounts" | | **Feature** | What capability does the user interact with? | "Account Settings Page", "Password Reset Flow" | | **Requirement** | What exactly must this feature do? | "The password reset link expires after 24 hours" | If the inference created features that map to internal services, database tables, or API endpoints rather than user-facing capabilities, restructure them. Merge implementation-level specs into user-facing features. Move internal details into requirement descriptions or acceptance criteria where they belong. ### Add business context Write Goals that capture *why* these features exist. The codebase inference cannot know your business reasoning -- only you can add that. Even a one-sentence goal like "Reduce support tickets by enabling self-service account management" gives the specification tree purpose. ### Sharpen acceptance criteria Review the acceptance criteria on each requirement. Make them specific and testable: - "The password reset email is sent within 30 seconds" -- specific, testable - "Password reset works correctly" -- too vague to verify ### Delete what does not belong Not everything in your codebase deserves a specification. Internal utilities, infrastructure code, build tooling, and developer conveniences are implementation details. If a specification does not describe something a user cares about, delete it. You can always add it back later if it turns out to matter. --- ## Step 4: Mark Implemented Specs as Released Your codebase already implements the functionality described by these specifications. These are not drafts waiting for implementation -- they are records of what already exists. For each specification that accurately describes existing, working functionality, transition it through the full lifecycle: ``` draft --> review --> approved --> in-development --> under-test --> released ``` Right-click each specification in the tree view and select **Transition Status** to move it forward, step by step, to **released**. **Released status means:** this specification describes functionality that is implemented, tested, and live. It is a locked record. Any future changes to this functionality require a formal [Change Request](/help/workflows/change-requests/). You do not need to release everything at once. Start with the specifications you are confident about -- the ones that clearly and accurately describe working functionality. Leave the rest in draft for further refinement. ### Why bother? Marking existing functionality as released gives you: - **A baseline.** You can see at a glance what is specified and what is not. - **Change tracking.** Future modifications go through Change Requests, so specification drift becomes visible. - **Traceability.** New features can reference existing ones. The specification tree becomes a living map of your system. --- ## Step 5: Specify What Comes Next Now you are in the same position as a greenfield project -- with the advantage of having an existing codebase and a documented baseline. This is where SPECLAN starts earning its keep. For new functionality, write specifications from scratch: ### Create new Goals What do you want to achieve next? Write Goals that describe business outcomes, not features: - "Reduce checkout abandonment by 20%" -- outcome-oriented - "Add Apple Pay" -- that is a feature, not a goal ### Create new Features Under each Goal, create Features that describe the user-facing capabilities you plan to build: ``` G-142 Reduce Checkout Abandonment ├── F-3891 One-Click Reorder ├── F-7204 Guest Checkout └── F-5563 Saved Payment Methods ``` ### Create new Requirements with Acceptance Criteria Under each Feature, write Requirements that define exactly what the feature must do. Include acceptance criteria as checkboxes: ```markdown ## Acceptance Criteria - [ ] Guest users can complete checkout without creating an account - [ ] Email address is the only required field for guest checkout - [ ] Order confirmation is sent to the provided email - [ ] Guest users can optionally create an account after checkout ``` ### Move through the lifecycle New specifications follow the standard lifecycle: ``` draft --> review --> approved ``` Draft freely. Review carefully. Approve only when the specification is clear, testable, and ready to be built. Approved specifications become the contract for implementation. --- ## Step 6: Implement New Features With approved specifications for new functionality, you are ready to build. Since your project is brownfield, you have a significant advantage: **your tech stack decisions are already made**. Your implementation assistant -- Claude Code, Gemini CLI, Cursor, or whichever tool you use -- will read your existing codebase and automatically infer: - The programming language and framework - Coding conventions and patterns - Library choices and dependencies - Project structure and architecture - Test framework and testing patterns You do not need to write a `CLAUDE.md` or `techstack.md` (though you can if you want to be explicit about conventions). The existing code *is* the context. The implementation assistant will adopt the patterns it finds and generate code that fits your project. ### Using the Implementation Assistant SPECLAN's built-in **Implementation Assistant** bridges your specifications and your AI coding tool: 1. Open the **AI Assistants** panel in the SPECLAN sidebar 2. Click **Implementation Assistant** 3. The assistant finds all specifications in **approved** status 4. Select which ones to implement 5. The assistant generates an optimized implementation plan with ready-made prompts 6. Copy each prompt into your AI coding tool 7. Mark tasks complete as you go The assistant sequences implementation based on dependencies, complexity, and business value. It generates prompts that reference your specifications and your existing codebase together -- so the AI coding tool knows both *what* to build and *how* it should fit into what already exists. ### Without the Implementation Assistant Since SPECLAN specs are plain Markdown files, any AI tool with file system access can use them directly: ```bash # Point your AI assistant at a specific requirement claude "Implement the requirement in speclan/features/F-7204-guest-checkout/requirements/R-4521-no-account-required/R-4521-no-account-required.md" # Or at a set of approved specs claude "Read the speclan/ directory and implement all approved specifications, following the existing codebase patterns" ``` The implementation assistant will read your project structure, recognize your tech stack, and generate code that matches your existing conventions. --- ## What You Have Now If you followed each step, your project now has: - A `speclan/` directory living alongside your existing code -- with nothing else changed - Inferred specifications for existing functionality, reviewed and restructured from the user's perspective - Existing functionality marked as **released** -- a documented baseline - New specifications for planned features, moving through the draft-review-approved lifecycle - A clear path from approved spec to implementation using your preferred AI coding tool Your specification tree is a living document. It grows with your project. Use [Change Requests](/help/workflows/change-requests/) when released specs need updates. Keep drafting new specifications as you plan future work. The more your specification tree reflects reality, the more value it delivers. ## Next Steps - [Requirements Workflow](/help/workflows/requirements-workflow/) -- Deep dive into the draft-to-approved process - [Development Workflow](/help/workflows/development-workflow/) -- Managing the implementation phase - [Change Requests](/help/workflows/change-requests/) -- How to modify released specifications - [Goals](/help/concepts/goals/), [Features](/help/concepts/features/), [Requirements](/help/concepts/requirements/) -- Detailed concept guides - [Status Lifecycle](/help/reference/status-lifecycle/) -- The full entity status progression --- ### The Claude Code SPECLAN Plugin Source: https://speclan.net/help/getting-started/speclan-plugin/ If you prefer the speed of your terminal over point-and-click editors, the SPECLAN Plugin for Claude Code is built for you. It brings the full power of SPECLAN into your Claude Code session -- create goals, draft features, write requirements, navigate the hierarchy, transition statuses, search across your specification tree, and ask questions about any entity in context. All through natural language. No window switching. No context breaks. You stay in the flow. Claude does the heavy lifting. ## What You Get The plugin gives Claude Code deep knowledge of SPECLAN's specification model and the skills to operate on it: - **Create** goals, features, requirements, scenarios, acceptance criteria, and tests by describing what you need - **Read** any entity by ID, by name, or by browsing the tree - **Update** titles, descriptions, statuses, owners, and acceptance criteria - **Navigate** the full hierarchy -- parent chains, child trees, sibling features - **Search** across your entire spec repository by keyword, status, type, or owner - **Transition** entities through the lifecycle: draft, review, approved, in-development, under-test, released, deprecated - **Manage change requests** for locked entities that are already in development or beyond - **Ask** questions about any entity, status, relationship, or project health -- get contextual answers with hierarchy, siblings, change requests, and actionable next steps - **Assign features to goals** and manage templates Every operation produces the same Markdown files with YAML frontmatter that the VS Code Extension reads. There is no format difference -- the plugin and the extension work on the same files. Switch between them freely. ## Installation The plugin is distributed through the [cc-marketplace](https://github.com/thlandgraf/cc-marketplace). Installation takes two commands. ### Quick Install (Two Commands) ``` /plugin marketplace add thlandgraf/cc-marketplace /plugin install speclan@digital-dividend-marketplace ``` That is it. The plugin's skills and agents are available immediately -- no restart needed. ### Interactive Install (Plugin Manager UI) If you prefer browsing the plugin manager: 1. Run `/plugin` in Claude Code 2. Go to the **Marketplaces** tab (use arrow keys or Tab to cycle) 3. Select **+ Add Marketplace** 4. When prompted for the marketplace source, enter: `thlandgraf/cc-marketplace` 5. Go to the **Discover** tab 6. Find **speclan** in the list 7. Select it and choose your installation scope (User, Project, or Local) Adding the marketplace is a one-time setup. After that, you can always find and manage the plugin from the **Discover** and **Installed** tabs. See [Discover and install plugins](https://code.claude.com/docs/en/discover-plugins) for details on how marketplaces work. ### Choosing a Scope When installing, you pick where the plugin lives: | Scope | What It Means | |-------|---------------| | **User** (default) | Available in every project you open. Good for personal use. | | **Project** | Shared with everyone who works on this repository. Stored in `.claude/settings.json`. Good for teams. | | **Local** | Available only to you, only in this repository. Good for trying things out. | For most users, the default **User** scope is the right choice -- you want SPECLAN available wherever you work. ## Working With the Plugin Once installed, you interact with SPECLAN the way you interact with everything in Claude Code: by asking. ### Creating Specifications Describe what you want, and Claude creates the spec: ``` Create a new feature under F-1234 called "User Notification Preferences" with a description about letting users choose how they receive notifications. ``` Claude creates the Markdown file in the right directory, generates a collision-free ID, and fills in the frontmatter. You can review the result and refine it in the same conversation. This works for every entity type. Ask for a goal, a feature, a requirement -- Claude knows the hierarchy and places things correctly. ### Navigating the Hierarchy Ask Claude to show you the shape of your project: ``` Show me the feature tree under G-001 ``` ``` What requirements belong to F-5678? ``` ``` Trace the ancestry of R-2345 back to its goal ``` Claude reads the specification files and presents the hierarchy in a clear, readable format. ### Transitioning Statuses Move specifications through their lifecycle: ``` Transition F-5678 to review ``` ``` Move all draft requirements under F-1234 to review status ``` The plugin enforces the same lifecycle rules as the VS Code Extension. You cannot skip statuses, and locked entities (in-development and beyond) require change requests. ### Searching Find things fast: ``` Show me all features in approved status ``` ``` Find requirements that mention "authentication" ``` ``` List all entities owned by alice@example.com ``` ### Managing Change Requests When a specification is locked (in-development, under-test, or released), direct edits are not allowed. Create a change request instead: ``` Create a change request for R-2345 to add a new acceptance criterion about handling timeout errors ``` The plugin respects the same business rules as the rest of SPECLAN -- no shortcuts, no workarounds. ### Asking Questions The other commands manage specs -- the ask command helps you understand them. Instead of reading files and piecing together context yourself, ask a question and get a contextual answer that situates the entity in its full hierarchy. ``` /speclan:ask F-0471 ``` This does not just dump the file. It shows F-0471's identity and status, its parent features up to the top-level, the goal it contributes to, its child requirements and sub-features with their statuses, sibling features at the same level, any active change requests, and what the status means for next steps. One question, full picture. You can also ask without the slash command. Claude recognizes SPECLAN questions conversationally: ``` What does F-0471 do? ``` ``` Tell me about the notification feature ``` #### What You Can Ask **By entity ID** -- look up any entity directly: ``` /speclan:ask R-0311 ``` ``` /speclan:ask CR-0012 ``` **By status** -- find entities in a specific lifecycle stage: ``` /speclan:ask what's approved ``` ``` /speclan:ask show in-development features ``` **By relationship** -- explore the hierarchy: ``` /speclan:ask children of G-001 ``` ``` /speclan:ask what contributes to G-001 ``` **Freehand questions** -- ask anything about your spec repository: ``` /speclan:ask which features don't have acceptance criteria yet? ``` ``` /speclan:ask are there any requirements that reference authentication? ``` ``` /speclan:ask summarize goal G-001 and how far along its contributing features are ``` #### What the Answer Looks Like For a single entity question, the answer is a context card: ``` ## R-0311 Lateral March Edge Reversal [approved] Type: Requirement | Owner: tl@example.com | Updated: 2026-02-19 Hierarchy: G-001 Core Game Experience → F-0471 Core Gameplay → F-0492 Alien Grid Movement → R-0311 Lateral March Edge Reversal ← you are here Description: [concise summary] Siblings (other requirements under F-0492): - R-0312 Descent After Reversal [in-development] - R-0315 Speed Increase Per Wave [approved] Change Requests: None active Status Notes: Approved and ready for implementation. ``` For status queries, the answer is a table grouped by parent feature. For relationship queries, the answer is an indented tree with status badges: ``` G-001 Core Game Experience [released] F-0471 Core Gameplay [in-development] R-0311 Lateral March Edge Reversal [approved] R-0312 Descent After Reversal [in-development] F-0089 VS Code Extension [released] F-0792 Tree Views [released] F-1380 View Panels [in-dev] ``` #### Read-Only Guarantee The ask command never creates, modifies, deletes, or transitions any entities. It only reads. If the answer reveals something you want to act on -- a stale status, a missing acceptance criterion, an orphan feature with no goal -- it points you to the right command to fix it. ## Why Use the Plugin Instead of the VS Code Extension? You do not have to choose. The plugin and the extension work on the same files. Many users use both. But if your workflow already lives in Claude Code -- if you are writing code, running tests, committing changes, and reviewing diffs in the terminal -- switching to a WYSIWYG editor just to update a spec breaks your rhythm. With the plugin, specification work becomes part of your conversation. You can draft a requirement, implement it, and transition its status to in-development without ever leaving Claude Code. The round-trip from spec to code to status update happens in one place. This is especially powerful when you are in the middle of implementation. You are reading a spec, writing code, and you notice the acceptance criteria are missing a case. Instead of opening a different tool, you say: ``` Create a change request for R-2345 to add an acceptance criterion: "The system returns a 429 status when the rate limit is exceeded" ``` Done. Back to coding. ## Keeping the Plugin Updated The cc-marketplace supports auto-updates. When enabled, Claude Code checks for new plugin versions at startup and updates automatically. To toggle auto-updates: 1. Run `/plugin` in Claude Code 2. Go to the **Marketplaces** tab 3. Select **digital-dividend-marketplace** 4. Choose **Enable auto-update** or **Disable auto-update** You can also manually update at any time: ``` /plugin marketplace update digital-dividend-marketplace ``` ## Troubleshooting **Plugin skills not appearing after install:** Clear the plugin cache and restart Claude Code: ```bash rm -rf ~/.claude/plugins/cache ``` Then reinstall the plugin. **`/plugin` command not recognized:** Make sure you are running Claude Code version 1.0.33 or later. Run `claude --version` to check. **Plugin not finding your specifications:** The plugin operates on the `speclan/` directory in your current project. Make sure you are in a project directory that has been initialized with SPECLAN. ## Related Topics - [Getting Started: New Project](/help/getting-started/greenfield/) -- Set up SPECLAN from scratch - [Getting Started: Existing Project](/help/getting-started/brownfield/) -- Adopt SPECLAN in a project that already has code - [Status Lifecycle](/help/reference/status-lifecycle/) -- The full entity status progression - [Change Requests](/help/workflows/change-requests/) -- How to modify locked specifications - [Development Workflow](/help/workflows/development-workflow/) -- Implementation phase and the Implementation Assistant - [BMAD Support](/help/reference/speclan-plugin/bmad-support/) -- Bidirectional conversion between BMAD-METHOD and SPECLAN --- ### Goals Source: https://speclan.net/help/concepts/goals/ Goals (G-###) represent high-level business objectives. They are the starting point of the SPECLAN specification hierarchy. ## Structure Each goal is a Markdown file with YAML frontmatter: ```yaml --- id: G-001 title: "Improve User Onboarding" status: approved --- ``` ## Relationship to Features Goals decompose into Features (F-####). A goal may contribute to multiple features, and a feature may support multiple goals. --- ### Features Source: https://speclan.net/help/concepts/features/ Features (F-####) describe specific capabilities of the system. They form a hierarchical tree and can contain sub-features and requirements. ## Hierarchy Features can nest infinitely. A parent feature groups related sub-features, while leaf features contain requirements. ## Directory Structure ``` speclan/features/ ├── F-1234-user-auth/ │ ├── F-1234-user-auth.md │ ├── F-5678-login/ │ │ └── F-5678-login.md │ └── requirements/ │ └── R-9012-password-rules/ │ └── R-9012-password-rules.md ``` --- ### Requirements Source: https://speclan.net/help/concepts/requirements/ Requirements (R-####) define specific, testable conditions that a feature must satisfy. They belong to exactly one feature. ## Acceptance Criteria Requirements contain acceptance criteria as markdown checkboxes: ```markdown ## Acceptance Criteria - [ ] Password must be at least 8 characters - [ ] Password must contain at least one uppercase letter - [ ] Invalid passwords show clear error messages ``` --- ### The New Specification Assistant Source: https://speclan.net/help/workflows/new-spec-assistant/ You used to write specifications by staring at an empty file and trying to remember every section that belonged there, every edge case you'd regret forgetting, every sibling spec you might be about to duplicate. The New Spec Assistant takes a single sentence of intent and gives you back a structured, context-aware first draft — then helps you make it *correct* and *complete* before you commit a word to disk. This page is a hands-on walkthrough. Open the assistant in VS Code and follow the numbered steps; nothing here is persisted until you explicitly press **Create**, so you can explore freely. > This guide covers the **AI-assisted (From Idea)** path and the happy path through it. The template-only path and error recovery are documented separately. ## Watch the Walkthrough Prefer to watch before you read? This tutorial walks through the New Spec Assistant end to end — the same flow the numbered steps below describe.
## Before You Start The assistant always knows what you're creating and where it goes — because you launch it from the spec tree, not from a blank menu. 1. In the SPECLAN spec tree, **right-click a feature**. 2. Choose **New Sub-feature (Assistant)** or **New Requirement (Assistant)**. To start a top-level feature, use the tree's **New Feature** action. 3. The assistant opens already knowing the **artifact type** and the **parent** it belongs under. You never re-enter what the tree already knows. ![Starting the assistant from the spec tree — a feature's right-click context menu with "New Requirement (Assistant)" and "New Sub-feature (Assistant)" as the entry points](/help/workflows/new-spec-assistant/launch-from-tree.png) The panel opens with two tabs above a shared header: - **From Idea** — the AI path. Available whenever your AI provider is configured and reachable. - **From Template** — a structured scaffold from a template and a title, no AI required. Always available. The shared header (title field, artifact-type chip, parent-context pill) sits above both tabs and is preserved if you switch between them. This walkthrough stays on **From Idea**. ## Phase 1 — Idea Entry This is where the journey begins. The footer at the bottom of the panel is **phase-aware**: it always shows you the one button that moves you forward, so you never hunt for the right affordance. 1. Make sure the **From Idea** tab is selected. 2. *(Optional)* Type a **title** in the shared header. If you leave it blank, the AI proposes one and adopts it into the header so you can see what's about to be created — you can always edit it before Create. 3. *(Optional)* Pick a **template** from the recommended cards. On the AI path a template is just a hint to the AI, not a hard structure. While the draft is being generated these cards are locked, so you can't change the structure out from under an in-flight draft. 4. Type your **idea** into the large text box — one sentence is enough. The **context pill** tells you exactly what surrounding specification the AI will read first (for example, *"AI will read: parent + 7 sibling requirement(s)"*), so the draft is connected to your project rather than written in a vacuum. 5. Look at the footer's primary button on the right: - If you left the title blank, it reads **"Next: Clarify"**. - If you typed a title, it reads **"Next: Generate Draft"**. - Either label runs the same step. The button is disabled until the idea box has text. **Cancel** sits to its left in every phase as the universal escape hatch. 6. Click the primary button. ![The New Spec Assistant panel — the From Template and From Idea tabs, the title field, artifact-type chips, the idea textarea, and the context-budget pill](/help/workflows/new-spec-assistant/idea-entry.png) The assistant now decides whether it needs to ask you anything before drafting. If your idea is already clear in the available context, it tells you so explicitly (*"Idea is clear — drafting…"*) and jumps straight to the draft. Otherwise, you enter the clarification phase. ## Phase 2 — Clarification Q&A When the idea leaves room for interpretation, the assistant presents **up to three** clarification questions on a single page (a form, not a multi-step wizard). This step is **always optional** — you are never blocked. Each question comes in the type that best fits the decision being asked: - **Multiple choice** — checkboxes, used when several answers can apply at once. Always includes an **Other** free-text option and a **None of these apply** option (with a "why none?" box). Picking *None* clears the other selections. - **Decision (single choice)** — radio buttons, used when you should pick one primary direction. Always includes an **Other** free-text option. - **Free text** — a plain text box, used when the assistant needs your judgment in your own words. Work through the form: 1. Answer the questions that matter to you. **Leave any question blank to skip it** — unanswered and answered questions are visually distinct, so you always know what you've addressed. 2. *(Optional)* Use each question's **importance** control to mark how much that ambiguity matters. You rate importance independently of whether you answer — a way to tell the assistant which gaps are most worth resolving even if you can't answer them yet. 3. Choose a footer action: - **"Next: Process Answers"** (primary, right) — apply your answers and refine the draft. - **"Next: Proceed without Answers"** (secondary) — skip the whole form and let the AI draft with reasonable assumptions, made visible in the result. - **Cancel** — the universal escape hatch (closes the assistant). ![A Clarify session — a single-select question with concrete options and an importance toggle, plus a second question, on one form](/help/workflows/new-spec-assistant/clarify-session.png) While the AI is generating questions or working your answers back in, the relevant footer button shows an in-button spinner and stays disabled — that button is the single source of truth for progress. You won't see a separate banner, and the panel won't jump ahead while the AI is still working. When the refinement completes, the assistant doesn't bolt a Q&A list onto the bottom of the spec — it **rewrites the draft body** so your answers are woven in, and returns you to the Draft Review page with the tighter version ready. ## Phase 3 — Draft Review You now have a real specification draft — scoped sections, acceptance criteria, and validated relative links to related specs already in your project. Review it in the panel. The footer in this phase offers: - **Create** (primary, right) — write the draft to disk. It lands in **`draft`** status, the very start of the normal review lifecycle. The assistant then closes itself and confirms the new artifact's identifier. - **Cancel** — discard and close. - **Clarify** and **Brainstorm** (centre) — the two refinement tools, *if they are available* (see the gating rule below). You can press **Create** here and be done. Or you can sharpen the draft first with one of the two tools. ### The Gating Rule **Clarify and Brainstorm appear in Draft Review only after at least one clarification cycle has completed against the current draft.** They are deliberately hidden: - during idea entry (there's no draft yet), - during the Q&A phase (you're mid-iteration), - on a first-pass draft where the AI never needed to ask you anything ("idea was already clear"), - on a draft where you skipped clarification while must-answer questions were still unanswered. This keeps the iteration tools off drafts they can't meaningfully act on. Once you've been through one clarification round, both tools are available for as many follow-on rounds as you like. ## The Clarify Tool — Catch the Ambiguity A first draft is confident, and that's the problem: the gaps hide as assumptions nobody questioned. **Clarify** makes them speak up. 1. In Draft Review, click **Clarify** in the footer's centre. 2. The assistant opens a dedicated Clarify page and re-reads your draft like a skeptical reviewer, looking for ambiguous wording, underspecified behavior, missing scope boundaries, and unstated decisions. 3. It presents a fresh set of questions — same three types and the same skip/importance behavior as Phase 2. Answer what matters, skip the rest, rate importance as you like. 4. Choose a footer action: - **"Next: Process Answers"** — apply your answers; the AI runs a refinement pass and works them back into the draft body. - **"Next: Proceed without Answers"** — proceed without answering. - **"Cancel Clarification"** — abandon *just this clarification round* and return to the draft preview exactly as it was. This does **not** close the assistant — you're back in Draft Review, free to Create, Clarify again, or Brainstorm. 5. When the refinement finishes, you return to Draft Review with the revised draft already in place. Run Clarify as many times as the draft needs. Each round makes it more precise. ## The Brainstorm Tool — Find the Angles You Didn't Think Of Clarify makes a draft *correct*. **Brainstorm** makes it *complete* — it surfaces the directions, edge cases, and inconsistencies a good reviewer would have raised. 1. In Draft Review, click **Brainstorm** in the footer's centre. 2. The assistant generates a set of **idea cards** from your draft and its surrounding context — scope options, related requirements, edge cases, and places the draft quietly contradicts the specs around it. 3. Review each card and react to it: - **Accept** an idea to keep it — accepted ideas are the ones that will be worked into the draft. - **Reject** an idea to discard it — it is no longer treated as preferred. - Click the same button again to toggle a reaction back to neutral. Only the ideas you **Accept** are incorporated; rejected and untouched ideas are not. 4. *(Optional)* While ideas are still generating, the footer shows **"Cancel Brainstorm"** — it cancels only this brainstorm round and returns you to the draft, not the whole assistant. 5. When you've made your choices, use the footer at the bottom of the panel: - **Apply N accepted idea(s)** (primary) — run a refinement pass that weaves your accepted ideas into the draft body. Disabled until at least one idea is accepted. - **Done (no changes)** — leave brainstorming without changing the draft. 6. You return to Draft Review with the updated draft. Spec links inside an idea are clickable — they open the referenced spec in a side-by-side preview so you can check context without leaving the flow. ![A Brainstorm session — AI-generated idea cards, each with Accept and Reject controls](/help/workflows/new-spec-assistant/brainstorm-session.png) What's notable is what the AI raises: not padding, but real catches — a business-rule contradiction, a dependency pointing at a bare ID instead of a link, an ambiguously named out-of-scope exclusion. **You are the filter.** Brainstorm widens the option space; it never widens your scope without your consent. ## You Stay in Control the Whole Way At no point does the assistant finalize a spec for you: - Clarification questions are **optional** — answer, skip individually, or proceed without any. - Clarify **asks**; you answer or skip. Brainstorm **offers**; you accept or reject. - The draft lives **in memory** until *you* press **Create**. Nothing touches disk before that. - A created spec lands in **`draft`** status — the start of the review lifecycle, not the end. Owners and stakeholders review it exactly as they always have. - **Cancel** (and the scoped **Cancel Clarification** / **Cancel Brainstorm**) is always one click away. The assistant is a faster path to a better first draft. It is not a shortcut around the judgment that makes a specification worth writing down. ## Quick Reference — Footer by Phase | Phase | You are here when… | Footer actions | |---|---|---| | **Idea entry** | No draft yet, no questions pending | `Cancel` · `Next: Clarify` / `Next: Generate Draft` | | **Clarification Q&A** | The AI asked questions, or a refine round-trip is in flight | `Cancel` · `Next: Proceed without Answers` · `Next: Process Answers` | | **Draft review** | A draft exists, no questions pending | `Cancel` · `Create` · *(centre, when gated-in)* `Clarify` · `Brainstorm` | | **Clarify page** | Inside a follow-on Clarify round | `Cancel Clarification` · `Next: Proceed without Answers` · `Next: Process Answers` | | **Brainstorm page** | Inside a follow-on Brainstorm round | *(generating)* `Cancel Brainstorm` — *(ideas shown)* `Done (no changes)` · `Apply N accepted idea(s)` | Your specification was always your prompt. Now SPECLAN helps you write it. --- ### Requirements Workflow Source: https://speclan.net/help/workflows/requirements-workflow/ The requirements workflow governs how SPECLAN specifications progress from initial creation through to approval. This process ensures consistent quality, facilitates stakeholder reviews, and maintains clear accountability. ## Overview Every specification begins as a **draft** and must pass through a structured review before becoming **approved**. The Requirements Engineer owns this process and is responsible for the specification's quality, completeness, and readiness for development. ``` draft ──> review ──> approved ``` ## Workflow Stages ### Draft The initial working state where the Requirements Engineer develops the specification. **Who owns it:** Requirements Engineer **What happens:** - Content can be freely edited and revised - No formal review process is active ### Review The specification is submitted for stakeholder review and feedback. **Who owns it:** Requirements Engineer (with reviewer participation) **What happens:** - The Requirements Engineer submits the draft for review - The Requirements Engineer tracks and responds to all feedback - Multiple review cycles may occur until approval criteria are met ### Approved The specification has passed review and is ready for implementation. **Who owns it:** Transitions to the implementation team **What happens:** - The specification is still editable — this is the last chance to refine before development starts - Once the spec moves to in-development, it becomes locked and changes require a formal [Change Request](/help/workflows/change-requests/) - Ownership responsibility transitions to the development team - The specification serves as the authoritative reference for development ## Transition Criteria | From | To | Requirements | |------|-----|-------------| | draft | review | All mandatory fields completed; submitted by spec owner | | review | approved | All review feedback addressed; approval criteria met | ## Related Topics - [Status Lifecycle](/help/reference/status-lifecycle/) -- Full status progression reference - [Development Workflow](/help/workflows/development-workflow/) -- What happens after approval - [Change Requests](/help/workflows/change-requests/) -- How to modify specifications in development or later --- ### Development Workflow Source: https://speclan.net/help/workflows/development-workflow/ The development workflow covers the transition of SPECLAN specifications from **approved** to **under-test** status. This phase is owned by the development team and represents the implementation period where approved specifications are turned into working software. ## Overview Once a specification is approved, the development team takes ownership. When implementation is complete and ready for verification, the team transitions the specification to under-test status, signaling that the QA team can begin validation. ``` approved ──> in-development ──> under-test ``` ## Workflow Stages ### Approved (Starting Point) The specification has been reviewed and approved by the Requirements Engineer. It is now the authoritative reference for what needs to be built. **What the development team receives:** - The specification that serves as the implementation guide (locked once moved to in-development) - Acceptance criteria that define what "done" looks like - Traceability back to business goals through the specification hierarchy ### In-Development Active implementation is underway. **Who owns it:** Development team **What happens:** - The development team implements the specification - The specification itself remains locked -- only Change Requests can modify it - Progress is tracked through the specification's status - Child entities may have constraints based on parent entity status **Key rules:** - Only users with development team permissions can work in this phase - The specification content cannot be directly edited - If changes are needed, a [Change Request](/help/workflows/change-requests/) must be created ### Under-Test (Transition Target) Implementation is complete and the specification is ready for QA verification. **Who performs the transition:** Development team member **What this signals:** - All acceptance criteria have been implemented - The development team considers the work complete - The QA team can begin their validation process **Key rules:** - The entity must be in "approved" or "in-development" status before transitioning to under-test - The transition must capture who performed it and when - Users receive confirmation when the transition is successful - Clear error messages are shown when a transition cannot be completed ## Transition Criteria | From | To | Requirements | |------|-----|-------------| | approved | in-development | Development team member initiates work | | in-development | under-test | Implementation complete; transitioned by development team member | ## Validation Rules Before transitioning to under-test, the system validates: - The entity is currently in the correct preceding status - The user has development team permissions - Related entities are notified or updated as appropriate ## Status History Every transition is recorded with: - The team member who performed the transition - A timestamp of when it occurred - The reason or context for the transition Users can view the complete status history for any entity, providing full transparency into the development lifecycle. ## Implementation Assistant SPECLAN includes an AI-powered **Implementation Assistant** that guides you through the implementation phase. It analyzes your entire specification hierarchy, identifies approved items ready for implementation, and generates structured plans with copy-paste prompts for your preferred AI coding tool. ### How It Works The assistant scans your project for specifications in "approved" status and organizes them into **implementation units** -- leaf features bundled with their approved requirements. It then uses AI analysis of both your specifications and your existing codebase to recommend an optimal implementation sequence. ``` approved specs ──> implementation units ──> sequenced plan ──> prompts ``` An **implementation unit** is a leaf feature (a feature with requirements but no child features) together with its approved requirements. This is the natural unit of work -- you implement a feature and its requirements together, not individual specs in isolation. ### Launching the Assistant Open the **AI Assistants** panel in the sidebar and click **Implementation Assistant**. A dedicated panel opens showing a summary of implementation-ready items, available modes, and a call-to-action to begin. If no specifications have "approved" status yet, you see an informative empty state with a snapshot of your project's current statuses and guidance on what to do next (such as reviewing draft specs or resolving clarifications). ### Manual Implementation The primary mode for user-driven implementation. You select which implementation units to include, the AI generates an optimized plan, and you copy prompts into your coding tool one at a time. **Workflow:** 1. **Select units** -- All implementation units are shown with checkboxes (selected by default). Deselect any you want to skip, or expand a unit to exclude specific requirements for partial implementation. 2. **Generate plan** -- The AI analyzes your codebase and selected units, then produces a sequenced implementation plan with rationale for the ordering. 3. **Copy and implement** -- Each unit has a ready-made prompt. Click to copy it, paste into your CLI tool (Claude Code, Gemini CLI, Cursor, Aider, etc.), and mark the task complete when done. 4. **Track progress** -- The plan view shows status for each unit: pending, in-progress, or completed. #### Implementation Order The AI determines sequencing using balanced multi-factor scoring: | Factor | What It Considers | |--------|-------------------| | Dependency satisfaction | Whether prerequisites are already implemented | | Foundation value | How many other specs depend on this one | | Risk reduction | Technical complexity and uncertainty | | Incremental value | Business value deliverable on completion | | Cohesion bonus | Relatedness to recently implemented items | When the AI cannot determine a definitive order for some units (e.g., equivalent scores or circular dependencies), those items are placed into an **unordered group** that you can implement in any order. #### Plan Files Plans are saved as markdown files in `speclan/.local/plans/` with the naming pattern `{slug}.{timestamp}.manual.md` (e.g., `auth-feature.2024-03-15T14-30.manual.md`). The slug is AI-generated (max 3 words) to describe the plan's content. Plans persist across sessions so you can pick up where you left off. #### Regenerating Plans If you regenerate a plan while work is in progress, the assistant performs a **smart merge**: - Completed and in-progress tasks are preserved with their status - Pending tasks are re-evaluated and potentially reordered - New specs are added in their optimal position - Warnings appear if regeneration would affect existing work - You can cancel regeneration to keep the current plan unchanged ### Swarm/Team Implementation (Preview) An advanced mode that deploys multiple AI agents working in parallel. Instead of copying prompts one at a time, a coordinated team of agents simultaneously implements different parts of your plan. A **Team Leader** agent coordinates the work, delegates tasks to **Implementation Team** members, monitors progress, and detects conflicts. You see a dashboard with overall progress, individual agent status, and controls to pause or stop execution. ## Tips for Development Teams 1. **Read the full specification** before starting implementation -- including all acceptance criteria 2. **Use the Implementation Assistant** to get an optimized plan and ready-made prompts for your coding tool 3. **Use partial selection** -- Exclude specific requirements when you want to implement a feature incrementally 4. **Use Change Requests** if you discover the spec needs modifications during development 5. **Transition promptly** when implementation is complete -- delays hold up the QA team 6. **Check related entities** -- parent and child entity statuses may affect transitions ## Related Topics - [Requirements Workflow](/help/workflows/requirements-workflow/) -- How specifications get approved - [QA Workflow](/help/workflows/qa-workflow/) -- What happens after under-test - [Change Requests](/help/workflows/change-requests/) -- How to modify specifications in development or later - [Status Lifecycle](/help/reference/status-lifecycle/) -- The full entity status progression from draft to released --- ### QA Workflow Source: https://speclan.net/help/workflows/qa-workflow/ The QA workflow covers the final verification phase where the QA team validates completed development work and transitions specifications from **under-test** to **released** status. This process ensures that only properly verified features reach end users. ## Overview When development work reaches the under-test status, the QA team takes ownership of the validation process. After successful verification against acceptance criteria and test scenarios, the team transitions the specification to released status. ``` under-test ──> released ``` If testing fails, the work returns to an earlier status for correction. ## Workflow Stages ### Under-Test (Starting Point) The development team has signaled that implementation is complete and the specification is ready for verification. **What the QA team receives:** - A specification with clearly defined acceptance criteria - Implementation that the development team considers complete - Full traceability from the specification back to business goals - Visibility into what changed compared to previous versions ### Testing in Progress The QA team conducts validation activities. **Who owns it:** QA team **What happens:** - QA team members review the specification's acceptance criteria - Testing is performed against the implemented functionality - Test results are recorded - Issues found are documented and communicated **What QA team members can do:** - View all work items currently in under-test status - Access the details of work items they need to test - Indicate when testing has passed or failed - Transition items to released when validation is complete ### Released (Transition Target) The specification has been verified and is available to end users. **Who performs the transition:** Authorized QA team member **What this signals:** - All acceptance criteria have been verified - The implementation meets the specification requirements - The feature is approved for production use **Key rules:** - Only users with QA team authorization can transition items to released - Work items must be in under-test status before they can be released - The release transition must capture an audit trail of who approved the release - Work items cannot skip the under-test phase ### Test Failure When testing reveals issues that need correction. **What happens:** - The QA team member indicates the test failure - The work item returns to an earlier status for rework - The development team addresses the issues - The item returns to under-test for re-verification ## Transition Criteria | From | To | Requirements | |------|-----|-------------| | under-test | released | All acceptance criteria verified; authorized QA team member approves | | under-test | (earlier status) | Test failure documented; returned for rework | ## QA Team Responsibilities 1. **Review acceptance criteria** -- understand exactly what needs to be verified 2. **Validate implementation** -- test against the specification, not assumptions 3. **Document results** -- record what was tested and the outcome 4. **Approve or reject** -- make a clear decision on each work item 5. **Maintain the audit trail** -- every decision should be traceable ## Status History Every QA transition is recorded with: - The QA team member who performed the action - A timestamp of the decision - Whether the item was released or returned for rework - Context or notes about the decision ## Tips for QA Teams 1. **Start with the acceptance criteria** -- they define the pass/fail boundaries 2. **Check the specification hierarchy** -- understand the feature's context within goals 3. **Verify traceability** -- ensure tests map back to acceptance criteria 4. **Communicate clearly** when returning items for rework -- the development team needs to understand what failed 5. **Use the SPECLAN tree view** to quickly see all items awaiting testing ## Related Topics - [Development Workflow](/help/workflows/development-workflow/) -- How specifications reach under-test - [Requirements Workflow](/help/workflows/requirements-workflow/) -- How specifications get approved - [Status Lifecycle](/help/reference/status-lifecycle/) -- Full status progression reference - [Change Requests](/help/workflows/change-requests/) -- How to modify released specifications --- ### Change Requests Source: https://speclan.net/help/workflows/change-requests/ Change Requests (CRs) are the formal mechanism for proposing modifications to SPECLAN specifications that are locked. Once a specification enters **in-development**, **under-test**, or **released** status, direct editing is not allowed — the spec becomes a stable reference that must not be a moving target. Instead, you create a Change Request to propose and track the modification through its own approval lifecycle. The change request is reviewed, approved, and implemented in the next development cycle or sprint, then merged back into the parent specification. ## When Are Change Requests Required? Change Requests are required when you need to modify a specification that is in one of these statuses: | Specification Status | Direct Edit? | Change Request Required? | |---------------------|-------------|------------------------| | draft | Yes | No | | review | Yes (limited) | No | | approved | Yes | No | | in-development | No | Yes | | under-test | No | Yes | | released | No | Yes | **Why not just edit directly?** Specifications in development, under test, or released serve as the authoritative reference for active work. Direct edits would create moving targets, undermine traceability, break the audit trail, and risk introducing unreviewed changes. Change requests ensure modifications are tracked and implemented in the next development cycle. ## Change Request Types SPECLAN supports five types of Change Requests, each suited to different situations: ### Enhancement Use when you want to **add new capabilities** or **extend existing functionality** to a specification. **Example:** Adding a new acceptance criterion to an approved requirement, or expanding the scope of a feature. ### Bugfix Use when you need to **correct an error** in the specification itself -- not a code bug, but a specification that is incorrect or incomplete. **Example:** Fixing a contradictory acceptance criterion, or correcting a wrong reference to another entity. ### Breaking Use when a change **alters the existing behavior or contract** defined by the specification. Breaking changes require careful review because they may affect downstream implementations and tests. **Example:** Changing an API contract defined in a requirement, or modifying acceptance criteria in a way that invalidates existing tests. ### Deprecation Use when a specification or part of it should be **phased out** and eventually removed. **Example:** Marking a feature as deprecated when it will be replaced by a newer approach. ### Documentation Use for **non-functional changes** to the specification text that do not alter the actual requirements -- such as fixing typos, improving clarity, or updating examples. **Example:** Rewriting a confusing description, adding examples to acceptance criteria, or fixing formatting. ## Change Request Lifecycle Change Requests follow the same status lifecycle as other SPECLAN entities: ``` draft ──> review ──> approved ──> in-development ──> under-test ──> released ──> deprecated ``` ### How It Works 1. **Create (draft):** A team member identifies a needed change and creates a CR linked to the parent specification (Feature or Requirement) 2. **Review:** The CR is submitted for review, just like a regular specification 3. **Approve:** Stakeholders review and approve the proposed change 4. **Implement (in-development):** The development team implements the change 5. **Test (under-test):** QA verifies the change meets the CR's acceptance criteria 6. **Release:** The CR is marked as released, and the parent specification is updated accordingly 7. **Deprecate (optional):** The CR can be deprecated if it is no longer relevant ## Creating a Change Request A Change Request includes: ```yaml --- id: CR-5282 title: "Add OAuth2 support to login requirement" status: draft parentId: R-4821 parentType: requirement changeType: enhancement --- ``` **Key fields:** - **parentId:** The specification being modified (Feature or Requirement) - **parentType:** Whether the parent is a feature or requirement - **changeType:** One of enhancement, bugfix, breaking, deprecation, or documentation ## Relationship to Parent Specifications - Each Change Request references exactly one parent specification - Multiple CRs can exist for the same parent (e.g., one enhancement and one bugfix) - When a CR is released, the parent specification is updated to reflect the change - The CR itself becomes part of the specification's history and audit trail ## Common Workflows ### Fixing a spec error during development 1. Developer discovers an incorrect acceptance criterion in R-4821 2. Developer creates CR-5282 (type: bugfix) referencing R-4821 3. CR goes through review and approval 4. The corrected criterion is applied to R-4821 5. Development continues with the corrected specification ### Adding scope to a released feature 1. Product owner wants to add new capability to feature F-3012 2. Creates CR-7901 (type: enhancement) referencing F-3012 3. CR goes through full lifecycle: review, approval, development, testing 4. When released, F-3012 is updated with the new scope 5. Full audit trail shows when and why the change was made ### Deprecating an old feature 1. Team decides F-2001 will be replaced by F-3012 2. Creates CR-8456 (type: deprecation) referencing F-2001 3. After review and approval, F-2001 status transitions to deprecated 4. The CR documents why the deprecation occurred ## Tips for Working with Change Requests 1. **Choose the right type** -- it affects how reviewers evaluate the change 2. **Link to the correct parent** -- CRs must reference exactly one Feature or Requirement 3. **Write clear descriptions** -- explain what needs to change and why 4. **Consider impact** -- breaking changes require extra scrutiny 5. **Keep CRs focused** -- one change per CR makes review and tracking easier ## Related Topics - [Requirements Workflow](/help/workflows/requirements-workflow/) -- How specifications get approved - [Development Workflow](/help/workflows/development-workflow/) -- How approved specs are implemented - [QA Workflow](/help/workflows/qa-workflow/) -- How implementations are verified - [Status Lifecycle](/help/reference/status-lifecycle/) -- Full status progression reference - [Entity Types](/help/reference/entity-types/) -- Complete reference of all entity types --- ### Entity Types Source: https://speclan.net/help/reference/entity-types/ SPECLAN uses a layered hierarchy of entity types. Features can be nested to create hierarchical sub-feature trees: | Entity | ID Pattern | Purpose | |--------|-----------|---------| | Goal | G-### | Business objectives | | Feature | F-#### | System capabilities (hierarchical — can contain sub-features) | | Requirement | R-#### | Testable conditions | | Change Request | CR-#### | Modifications to entities in development or later | | Template | UUID v4 | Reusable structures | --- ### Status Lifecycle Source: https://speclan.net/help/reference/status-lifecycle/ Every SPECLAN entity follows a defined status progression: ``` draft → review → approved → in-development → under-test → released → deprecated ``` ## Status Rules - **draft**: Initial state. Freely editable. - **review**: Submitted for review. Editable with caution. - **approved**: Implementation can begin. Still editable — last chance to refine before development starts. - **in-development**: Active implementation. Locked — changes require a Change Request to avoid moving targets. - **under-test**: Implementation complete, testing in progress. Locked — changes require a Change Request. - **released**: Verified and shipped. Locked — changes require a Change Request for the next development cycle. - **deprecated**: No longer active. --- ### Roles Source: https://speclan.net/help/reference/roles/ SPECLAN's specification-driven workflow distributes responsibility across six roles. Each role owns specific lifecycle stages and collaborates with others at clearly defined handoff points. This page is your go-to reference for understanding who does what and when. > **Want a narrative introduction?** Read the companion blog post [Your PO Should Own the Spec, Not the Developer — Here's How](/blog/2026-04-04-roles/) for a storytelling perspective on roles in SPECLAN, including a video walkthrough. ## The Six Roles ### Requirements Engineers Requirements Engineers are the authors and stewards of specifications. They translate business goals into structured, testable specifications that the rest of the team can act on. **Primary responsibilities:** - Create and maintain Goals, Features, and Requirements - Write clear acceptance criteria that define "done" - Shepherd specifications through draft and review stages - Respond to review feedback and refine specifications until they meet approval criteria - Ensure specifications remain consistent, traceable, and complete **Lifecycle ownership:** - **draft** -- Create and iterate on specifications freely - **review** -- Submit specifications for stakeholder review, track and address all feedback **Collaboration points:** - Hand off approved specifications to Development Teams for implementation - Collaborate with Product Teams to ensure specifications align with business goals - Review Change Requests submitted by Development or QA Teams during locked stages --- ### Development Teams Development Teams turn approved specifications into working software. They own the implementation phase and signal readiness for testing when their work is complete. **Primary responsibilities:** - Implement specifications according to acceptance criteria - Transition specifications from approved through in-development to under-test - Submit Change Requests when specifications need modifications during implementation - Use the Implementation Assistant to generate optimized plans and prompts for coding tools **Lifecycle ownership:** - **in-development** -- Active implementation; the specification is locked to prevent moving targets **Collaboration points:** - Receive approved specifications from Requirements Engineers - Hand off completed work to QA Teams by transitioning to under-test - Submit Change Requests to Requirements Engineers when spec changes are needed during development - Coordinate with AI Systems that may assist with or perform implementation tasks --- ### QA Teams QA Teams validate that implementations match their specifications. They are the gatekeepers who decide whether work is ready for release. **Primary responsibilities:** - Verify implementations against acceptance criteria and test scenarios - Document test results and communicate findings - Transition verified specifications from under-test to released - Return failing work to Development Teams with clear explanations of what went wrong **Lifecycle ownership:** - **under-test** -- Conduct validation; approve or reject implementations **Collaboration points:** - Receive completed implementations from Development Teams - Return failing items to Development Teams for rework - Submit Change Requests to Requirements Engineers if specifications need clarification or correction - Report release status to Managers and Product Teams --- ### Product Teams Product Teams set the strategic direction. They define business goals and ensure that specifications align with the product vision. **Primary responsibilities:** - Define and prioritize business goals (G-### entities) - Review specifications during the review stage to verify alignment with product strategy - Approve or request changes to specifications that affect product direction - Monitor the overall health and progress of the specification portfolio **Lifecycle ownership:** - **review** -- Participate as stakeholders, providing feedback and approval on specification content **Collaboration points:** - Work with Requirements Engineers to define goals and shape feature priorities - Provide business context that helps Development Teams understand the "why" behind specifications - Receive release reports from QA Teams and Managers --- ### Managers Managers oversee the workflow from a process and delivery perspective. They ensure that work moves through the lifecycle smoothly and that teams have what they need. **Primary responsibilities:** - Monitor specification status across the portfolio - Identify bottlenecks and resolve cross-team blockers - Track progress through lifecycle stages - Ensure compliance with process rules (e.g., Change Request requirements for locked specifications) **Lifecycle ownership:** - Managers do not own a specific lifecycle stage but have visibility across all stages **Collaboration points:** - Coordinate between Requirements Engineers, Development Teams, and QA Teams - Escalate issues that block lifecycle transitions - Use the SPECLAN tree view and status reports to maintain portfolio-level awareness --- ### AI Systems AI Systems participate as implementation agents, working alongside or in place of human developers. SPECLAN treats AI as a first-class participant with the same workflow rules as human team members. **Primary responsibilities:** - Implement specifications according to acceptance criteria (same as Development Teams) - Follow the locked-specification workflow -- AI cannot modify specs without a Change Request - Generate implementation plans using the Implementation Assistant - Operate within the boundaries set by approved specifications **Lifecycle ownership:** - **in-development** -- Perform implementation tasks, identical to human Development Teams **Collaboration points:** - Receive work assignments through the Implementation Assistant or directly from Development Teams - Produce implementations that QA Teams validate through the same process as human-authored code - Operate under the same Change Request rules -- if a spec needs modification, AI must request it through the formal process ## Roles and the Lifecycle The diagram below maps each role to the lifecycle stages where they are active. Roles shown in bold own that stage; roles in regular text participate or collaborate.
Diagram mapping the six SPECLAN roles to the seven lifecycle stages. Requirements Engineers own draft, review, and approved. Product Teams participate in review. Development Teams and AI Systems own in-development. QA Teams own under-test. All roles have visibility into released and deprecated stages. Managers have cross-cutting visibility across all stages.
### Key Handoff Points 1. **review to approved** -- Requirements Engineers complete the review process. The specification becomes the authoritative reference for what to build. Ownership transitions to Development Teams. 2. **approved to in-development** -- Development Teams (or AI Systems) pick up the specification and begin implementation. The specification locks -- further changes require a [Change Request](/help/workflows/change-requests/). 3. **in-development to under-test** -- Development Teams signal that implementation is complete. QA Teams take ownership and begin validation against acceptance criteria. 4. **under-test to released** -- QA Teams verify the implementation and approve it for release. If testing fails, the item returns to Development Teams for rework. ## How Roles Interact with Change Requests Once a specification reaches **in-development** or later, it is locked. Any role that needs a modification must create a [Change Request](/help/workflows/change-requests/) rather than editing the specification directly. This ensures traceability and prevents moving targets during active work. | Situation | Who Creates the Change Request | |-----------|-------------------------------| | Spec ambiguity discovered during implementation | Development Teams or AI Systems | | Test reveals a spec defect | QA Teams | | Business priorities shift | Product Teams (via Requirements Engineers) | | Process or compliance update needed | Managers (via Requirements Engineers) | ## Related Topics - [Requirements Workflow](/help/workflows/requirements-workflow/) -- Draft to approved: the Requirements Engineer's workflow - [Development Workflow](/help/workflows/development-workflow/) -- Approved to under-test: the Development Team's workflow - [QA Workflow](/help/workflows/qa-workflow/) -- Under-test to released: the QA Team's workflow - [Status Lifecycle](/help/reference/status-lifecycle/) -- Complete reference of all lifecycle stages and rules - [Change Requests](/help/workflows/change-requests/) -- How to modify locked specifications - [Entity Types](/help/reference/entity-types/) -- Goals, Features, Requirements, and their relationships --- ### Artifacts Source: https://speclan.net/help/reference/artifacts/ A specification is more than text. It comes with the wireframe that drove the decision, the API contract it has to honour, the regulatory PDF it answers to, the slide deck it was negotiated against. SPECLAN keeps that evidence in git, alongside the specs it backs, instead of leaving it scattered across Confluence, shared drives, or pasted-and-lost in chat. This page covers what artifacts are, where they live, how you add and remove them, and the rules that govern artifact changes on locked specs. ## Video Tutorial The video below is a guided walkthrough of SPECLAN artifacts — attaching spec-level evidence, organising the project-wide reference shelf, and embedding inline images inside a spec body. Watch it first if you prefer a demo before reading the full reference.
Can't see the video? [Watch on YouTube](https://youtu.be/WwYuxKniobo). ## What Is an Artifact? An artifact is a supporting file that belongs to a spec — anything externally maintained that helps explain or justify the specification: - Mockups and wireframes - OpenAPI / GraphQL / JSON schemas - ER diagrams and data models - Regulatory or compliance PDFs - Stakeholder slide decks and approval scans - Research transcripts, recordings, or session notes - Brand guidelines and style guides Artifacts are git-tracked. They version with your repository, travel with branches, and show up in code review the same way spec body changes do. ## The Four Levels Artifacts attach at four levels: | Level | What it represents | Where it lives | |---|---|---| | **Project** | Reference material the whole project leans on | `speclan/artifacts/` | | **Feature** | Evidence pinned to one feature | `/artifacts/` | | **Requirement** | Evidence pinned to one requirement | `/artifacts/` | | **Change Request** | Evidence introduced *with* a proposed change | `/artifacts/` | Project-level artifacts are reference shelves — diagrams, brand guides, data dictionaries — that many specs may consult and no single spec owns. The other three levels (feature, requirement, change request) are spec-level: each artifact is pinned to exactly one spec entity and travels with it. ## What SPECLAN Does (and Doesn't) Do With Artifact Content This is the most important thing to understand before you start adding artifacts. **SPECLAN does not read, parse, summarise, or interpret the content of your artifacts.** It stores them, references them from the spec, surfaces them in the UI, tracks their lifecycle through Change Requests, and keeps inline image embeds in sync on rename. That's it. None of SPECLAN's AI features (Clarification, Infer Specs, CR Merge, HLRD Import) consume artifact bytes. What SPECLAN does is make sure the **implementation agent** — Claude Code, Codex, Cursor, or whatever assistant you're handing the spec to — can find the artifacts and decide for itself how to read them. The Quick Impl. prompt and the planfile-based implementation flows include the spec's relative path; from there the agent can walk the spec body's markdown links into the `artifacts/` folder. What the agent can read depends on the file format: | Format | Implementation agent reads it? | |---|---| | Markdown (`.md`), plain text (`.txt`) | Natively — same as any source file | | JSON, YAML, CSV, XML, source code | Natively — same as any source file | | PNG, JPG, SVG, GIF | Most modern coding agents can read images directly | | PDF, DOCX, PPTX, XLSX | Usually requires a skill, tool, or pre-extraction step | | Archives (`.zip`, `.tar`) | Requires explicit extraction | For binary office formats, the practical pattern is to either pre-extract the relevant content into a sibling Markdown artifact (`requirements.docx` → `requirements.md`) before the implementation hand-off, or to attach a skill/tool to the agent that handles the format. SPECLAN won't do this for you, and that's deliberate: it keeps SPECLAN provider-agnostic, avoids bundling PDF/DOCX parsers, and lets you control what evidence actually reaches the AI. Think of artifacts as **traceability and reference**, not as input the AI has already consumed. ## Spec-Level Artifacts The spec-level Artifacts section appears at the bottom of every spec page in the WYSIWYG editor. Each attachment renders as a row showing the file-type icon, the file name, the type label, the human-readable size, and a row of action icons (open in a new tab, open in the default OS application, copy path, delete). ![The Artifacts section in the SPECLAN WYSIWYG editor — six attachments to a feature spec, each row showing a file-type icon, type label, size, and per-row action icons. The green left-edge band signals the git-decoration status.](/help/reference/artifacts/spec-artifacts.png) ### Where They Live Every feature, requirement, or change request can have its own `artifacts/` folder right next to its `.md` file: ``` speclan/features/F-2419-login-flow/ ├── F-2419-login-flow.md ├── artifacts/ │ ├── login-mockup.png │ ├── api-response-schema.json │ └── stakeholder-approval.pdf └── change-requests/ ``` ### Adding Artifacts Two ways, both available in the SPECLAN editor at the bottom of the spec page: 1. **Add Artifact button** — opens a multi-file picker. 2. **Drag-and-drop** — drop one or more files onto the Artifacts section from your OS file manager. Each artifact appears as a compact box showing its file name, file-type icon, type label, and human-readable size. Click the box to open the artifact in a new VS Code tab using the registered default viewer (image viewer for PNG/SVG, PDF reader for PDFs, text editor for JSON, and so on). ### Removing Artifacts Click the trash icon on any artifact box. SPECLAN asks for confirmation before removing — because on a locked spec, removal triggers a Change Request rather than a direct delete (see below). ### Images Are Special — Illustrations, Diagrams, and Pictures in the Spec Image files (PNG, JPEG, GIF, WebP, SVG) are the one artifact class that can render **inside the specification itself**. The WYSIWYG editor displays them as part of the prose — illustrations next to a feature description, diagrams under an architecture section, screenshots illustrating a user flow, mockups beside the requirement that drove them — not as separate attachments the reader has to click through. ![A SPECLAN feature spec open in the WYSIWYG editor, with a hand-drawn whiteboard mockup embedded inline between the Overview section and the Capabilities section. The image is part of the document's visual flow, not a separate attachment row below.](/help/reference/artifacts/embedded-image.png) To insert one, use the image button in the editor toolbar. SPECLAN copies the file into the spec's `artifacts/` folder and inserts a standard markdown image link pointing at it: ```md ![Login flow mockup](artifacts/login-flow-mockup.png) ``` The link is plain markdown — it renders in any markdown viewer, in code review, on GitHub, in any tool that reads the file. The WYSIWYG view simply renders the image in place; switch to plain Markdown view and you see the link above with the same image rendered below it. If you rename an image artifact later through the SPECLAN UI, SPECLAN cascades the rename through every inline link in the spec body so the embeds stay valid. PDFs, spreadsheets, archives, and other non-image artifacts are referenced as plain markdown links — they don't render inline, but they're listed in the Artifacts section and one click opens them in the appropriate viewer. ### Filename Sanitation Filenames in `artifacts/` need to stay portable across macOS, Windows, and Linux. SPECLAN sanitises every filename you add: - Allowed characters: letters, digits, dot, dash, underscore (everything else becomes a dash). - Base name capped at 120 characters. - Windows-reserved names (`CON`, `PRN`, `AUX`, `NUL`, `COM1`–`COM9`, `LPT1`–`LPT9`) rejected. - Case-only differences treated as collisions (`Foo.png` and `foo.png` are the same file). Existing files that violate these rules are not auto-renamed — sanitation runs at every Add path, not on existing folders. ## Change Request Governance — the Drift-Prevention Rule SPECLAN's most important artifact rule: **on a locked spec, you cannot silently change an artifact**. A spec is "locked" once it reaches `in-development`, `under-test`, or `released`. By that point, the implementation is being built, tested, or already shipped — and the artifacts attached to that spec are what the implementation is being verified against. If the API contract silently changes, the implementation no longer matches the evidence, and nobody knows. To prevent this drift, SPECLAN dispatches artifact mutations on the parent spec's status: | Spec status | Add or replace | Remove | |---|---|---| | `draft`, `review`, `approved` | Direct file copy | Direct delete | | `in-development`, `under-test`, `released` | Auto-creates a Change Request that **stages** the file | Auto-creates a Change Request that **proposes** the deletion | | `deprecated` | Disabled | Disabled (existing artifacts remain visible) | ### How Staged Artifacts Work When you add or replace an artifact on a locked spec, SPECLAN: 1. Creates a Change Request in `draft` status, titled either `"New artifact added"` or `"Replace artifact "`. 2. Stages your file in the spec's `artifacts/` folder under a CR-suffixed disk name: `.CR-####-.`. Both the canonical file and the staged file coexist in the folder. 3. Shows the staged file in the Artifacts section with a **"Pending CR-####"** badge that displays the owning Change Request's lifecycle status. Click the badge to navigate to the CR. You then advance the Change Request through SPECLAN's standard flow — `draft → review → approved → in-development → under-test → released` — and click the **Merge** button when it reaches `released`. On merge, the CR archives, the staged filename loses its CR suffix and becomes canonical, and the Artifacts section refreshes. ### Removal Creates a Documented Decision When you remove an artifact from a locked spec, the auto-created CR's body is pre-populated with: > `` was deleted — describe what implications this has on the specification. You fill in those implications before advancing the CR to `review`. This turns "delete a wireframe" from a click into a documented decision — *why* is this evidence no longer relevant? what changed about the spec that makes the wireframe obsolete? — which is exactly the kind of trail an auditor or a future contributor will ask for. ### Why This Matters: the Implementation Signal The Change Request gate isn't just about review hygiene. An approved artifact-change CR is a **signal into your implementation flow**: the same trigger that releases a new mockup or a new contract also tells the implementation team that the build needs to update to match. Approve the CR, hand it to your implementation flow, and the implementation catches up to the evidence in the same lifecycle that surfaced the change. Without the gate, a 4MB updated `stakeholder-approval.pdf` could overwrite the original on a `released` requirement and the implementation team would never see the diff. With the gate, every artifact edit is a tracked, mergeable, implementation-relevant event. ### Multi-File Drops Stay One CR Each Dropping three files onto a locked spec produces three separate Change Requests, not one batch CR. This preserves a strict one-add-one-CR symmetry: a reviewer looking at the Change Request list sees one CR per pending artifact change, not a "miscellaneous" CR carrying three unrelated mockups. ## Project Artifacts — the Reference Shelf The fourth artifact level — project-wide — works differently. Project Artifacts have **no Change Request governance**. ### Where They Live In a single directory at `speclan/artifacts/`, surfaced as the third top-level entry of the **PROJECT** view in the SPECLAN sidebar (alongside Vision and Mission): ``` PROJECT ├── 👁 Vision ├── 🚀 Mission └── 📁 Artifacts ├── architecture/ │ ├── system-overview.png │ └── deployment-diagram.svg ├── data-dictionary.xlsx ├── meeting-notes/ │ ├── 2026-03-kickoff.md │ └── 2026-04-review.md └── brand-guidelines.pdf ``` ![The PROJECT tree's Artifacts entry expanded — nested folders (architecture, meeting-notes, regulatory) and top-level files. Live git-status decorations propagate from leaves up to parent folders; an `M` badge marks a modified file, `U` badges mark new untracked files, and clean rows carry no decoration.](/help/reference/artifacts/project-artifacts.png) Project Artifacts can be organised hierarchically — folders nest to any depth. Click any file leaf to open it in VS Code's default viewer. ### Adding Project Artifacts Same two ways as Spec Artifacts: a multi-file picker (`+ upload artifacts` in the empty state) and native OS drag-and-drop on the Artifacts root entry. When a filename collides with an existing one, SPECLAN prompts per file: **Overwrite / Keep both / Skip**. You can also organise subfolders directly in your OS file manager — the on-disk filetree under `speclan/artifacts/` is the source of truth, and SPECLAN's filesystem watcher refreshes the tree automatically when you add, remove, or rename anything. Folders dragged from the OS file manager are **rejected** at the SPECLAN drop target. Only files are accepted via SPECLAN; subfolder organisation goes through the OS file manager. ### Why No Governance? Locking applies to spec entities — they have a status, and that status declares whether the team has agreed on their content. Project folders don't have status. There's no "released project" to gate changes against. Project Artifacts are reference material that many specs may consult, that no single spec owns, and that don't fit any specification's lifecycle. Forcing them through a Change Request workflow would be ceremony without reason. ### How Spec and Project Artifacts Compose A spec body can link to a project artifact by relative path: ```md See the project [brand guidelines](../../../artifacts/brand-guidelines.pdf). ``` The link is plain markdown. SPECLAN doesn't track it as a referential relationship, doesn't auto-stage it under a CR, and doesn't validate that the path resolves. The two surfaces share one thing: a consistent **icon vocabulary**. A `.pdf` artifact gets the same icon in the spec's Artifacts section as it does in the PROJECT tree's Artifacts subtree, so you see a consistent visual language even though the governance is different. ## Referencing Artifacts from the Spec Body Once an artifact exists, you'll usually want to link to it from somewhere in the spec body — "see the contract here", "implements this mockup", "answers the regulation in this PDF." SPECLAN gives you two ergonomic ways to insert those links from inside the WYSIWYG editor, plus the manual fallback. ### Spec Artifacts — the `@` Command While Typing While editing a spec body, type `@` to open a contextual search popup. The popup mixes two kinds of result: - **Spec entities** — Goals, Features, Requirements, Change Requests anywhere in the project, filtered by your query. - **The current spec's own artifacts** — both canonical files and any CR-staged ones, filtered by case-insensitive substring on the filename. Keep typing to narrow the list, then pick an artifact and SPECLAN inserts a correctly-relative markdown link at the cursor — no copy-paste, no path arithmetic, no broken links. If you open the popup with no query yet (just `@` on its own), the contextual mode shows the spec's artifacts alongside its ancestors, siblings, and children — useful when you're orienting around the current spec rather than searching. Note: the `@` popup only surfaces artifacts attached to the **currently open spec**. To reference an artifact attached to a different spec, navigate to that spec's link via `@`, then drag the file from there — or write the relative markdown link by hand (always works). ### Project Artifacts — Drag from the PROJECT Tree For project-wide artifacts living under `speclan/artifacts/`, the natural flow is drag-and-drop **out of** the PROJECT tree: 1. Expand the **PROJECT → Artifacts** entry in the SPECLAN sidebar. 2. Locate the file you want to reference (architecture diagram, brand guideline PDF, data dictionary…). 3. Drag it onto the WYSIWYG editor at the position where the link should appear. SPECLAN inserts a correctly-relative markdown link pointing from the open spec's location into `speclan/artifacts/`. The format depends on the file type: - **Image files** (PNG, JPEG, GIF, WebP, SVG) drop in as inline `![alt](path)` embeds — the image renders in place inside the WYSIWYG editor. - **Other files** drop in as styled, read-only link tiles — clickable, but visually distinguished from prose so reviewers see at a glance that something external is referenced. The drop target is the editor body. Folder nodes and the Artifacts root entry are deliberately **not draggable** — only individual file leaves are. Single-file drag only; multi-selection exports just the first file leaf. ### Manual Markdown Links Always Work Both flows above just produce plain markdown links (`[label](relative/path)` or `![label](relative/path)` for images). If you prefer to type the link by hand, that works exactly the same — the artifacts are visible to any markdown reader regardless of how the link got there. ## Quick Reference | What you want to do | Where to look | |---|---| | Attach a wireframe to a feature | Editor → Artifacts section → Add Artifact / drag-drop | | Embed an image inline in a spec body | Editor toolbar (image artifact already added) → insert image | | Replace a contract on a `released` requirement | Editor → Artifacts section → Add (auto-stages a CR) | | Delete a wireframe from a `released` feature | Editor → Artifacts section → trash icon (auto-creates a removal CR) | | Share an architecture diagram across the project | PROJECT view → Artifacts entry → drag-drop | | Find an artifact you added | PROJECT view → Artifacts (project-wide) or the spec's editor (spec-level) | ## Related - [Status Lifecycle](/help/reference/status-lifecycle/) — the lifecycle that gates direct vs CR-routed artifact changes. - [Getting Started — New Project](/help/getting-started/greenfield/) and [Existing Project](/help/getting-started/brownfield/) — where artifacts fit into a project from day one. --- ### Excalidraw Diagrams Source: https://speclan.net/help/reference/excalidraw-diagrams/ Excalidraw lets you draw architecture diagrams, flowcharts, and sketches directly inside your SPECLAN specs - and they live in your repo as real files, versioned with everything else. This guide shows you how to set it up and use it. Prefer to watch? The video below walks through the whole flow end to end.
Can't see the video? [Watch on YouTube](https://youtu.be/QQ81eCAjElk). ## Why diagrams in specs A wall of text is hard to reason about. A diagram makes structure obvious at a glance - how components talk to each other, how a flow branches, where the boundaries are. SPECLAN treats Excalidraw diagrams as first-class artifacts. They are not screenshots pasted into a doc that rot the moment something changes. They are editable source files that sit next to your spec, travel with your repo, and render inline while you read. ## What you need: the Excalidraw extension, side by side with SPECLAN This is the one setup step, and it matters: **viewing diagrams works out of the box, but creating and editing them requires a companion VS Code extension installed alongside SPECLAN.** The companion is **Excalidraw** by **pomdtr** (extension id `pomdtr.excalidraw-editor`), available on the VS Code Marketplace: [Excalidraw editor on the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor) SPECLAN and the Excalidraw extension run **side by side**, each owning its own job: - **SPECLAN** owns the specification and renders the diagram inline as you read. - **The Excalidraw extension** owns the drawing canvas where you create and edit. Install it once - from the Extensions view (search "Excalidraw pomdtr") or from the Marketplace page above - and SPECLAN detects it automatically. If you try to create or edit a diagram before it is installed, SPECLAN prompts you with a one-click link to install it. ## Creating your first diagram There are two easy ways in. ### From the editor toolbar While editing a spec in the SPECLAN editor, click the Excalidraw button in the toolbar. Give your diagram a name, and SPECLAN creates the file and opens the canvas. ### From the artifacts section Every spec has an Artifacts section at the bottom. Use the add control there and choose to create a new Excalidraw diagram. Same result - a new diagram, ready to draw. Either way, SPECLAN drops a new `.excalidraw.png` file into the spec's `artifacts/` folder and opens it in the Excalidraw canvas. ## Drawing The canvas is the full Excalidraw experience: shapes, arrows, text, freehand, libraries, the lot. Draw whatever your spec needs - a box-and-arrow architecture sketch, a sequence of steps, a state machine. When you are done, just save. The diagram is written straight back into the `.excalidraw.png` file in your spec's artifacts folder. ## Seeing it in your spec Back in the SPECLAN editor, your diagram shows up inline, rendered right where it belongs. No export step, no copy-paste. The picture you see in the spec *is* the file on disk. Because the file is a real PNG with the drawing baked in, it also renders anywhere a normal image does - GitHub, your docs site, a Markdown preview. But because it is *also* an Excalidraw file, you can reopen it any time and keep editing. One file, both jobs. ## Editing later Click an existing diagram to open it back up in the Excalidraw canvas. Make your changes, save, and the inline render in your spec updates to match. Diagrams evolve with your spec. When the design changes, update the picture - it is right there, not buried in some external tool. ## Dark mode SPECLAN is theme-aware. A diagram you drew on a light background is automatically adjusted to sit comfortably in a dark editor theme, so it never glares at you. If you deliberately drew a dark-themed diagram, name the file with a `.dark.excalidraw.png` ending and SPECLAN leaves it untouched. ## Diagrams on locked specs Once a spec is locked - in development, under test, or released - it is protected from silent changes. Diagrams follow the same rule as everything else. If you edit a diagram on a locked spec, SPECLAN notices and offers to open a Change Request, so the update is tracked and reviewed like any other change. You get a small prompt right by the diagram - one click to raise the CR. ## Where the files live Every diagram is a `.excalidraw.png` file inside the `artifacts/` folder next to your spec. That means: - It is versioned with your spec in git - It travels with your repo - no external service, no broken links - It renders as a normal image anywhere, and stays editable in Excalidraw Diagrams are part of your specification, not an attachment to it. ## Quick reference | Task | How | | --- | --- | | View a diagram | Just open the spec - it renders inline (no extension needed) | | Install the editor | VS Code Marketplace, "Excalidraw" by pomdtr (`pomdtr.excalidraw-editor`) | | Create a diagram | Toolbar button, or Artifacts section add control | | Edit a diagram | Click it to open the Excalidraw canvas | | Keep a dark diagram dark | Name it `.dark.excalidraw.png` | | Change a diagram on a locked spec | Accept the Change Request prompt | | Find the files | `artifacts/` folder next to the spec | ## That's it Draw, save, see it in your spec. Your diagrams live in your repo, version with your work, and render everywhere - while staying fully editable. No external tools to wrangle, no exports to keep in sync. The only thing to install is the Excalidraw extension by pomdtr, running side by side with SPECLAN. --- ### Local LLM Source: https://speclan.net/help/reference/local-llm/ SPECLAN can use a local LLM running on your machine instead of a cloud provider like Claude, OpenAI, or Google. Your specification content never leaves your network, you pay zero API costs, and you can work offline. This guide covers setup with three popular local LLM servers: **Ollama**, **LM Studio**, and **vLLM**. > **From the SPECLAN Team — A Model That Works Beautifully** > > Looking for a proven starting point? The SPECLAN team has had excellent results using **Qwen 3.6 35B A3B** with a context length of **50,000 tokens**. Running on a Mac M4 Max with 128 GB of memory, this model runs smoothly and produces wonderful, high-quality specifications. If you have similar hardware, this combination is a great place to start your local LLM journey with SPECLAN. For the full story behind that recommendation — what we tested, what failed, and why this one worked — read [We Gave SPECLAN a Local Brain](/blog/2026-04-25-we-gave-speclan-a-local-brain/). ## The Two Things That Actually Matter Most local LLM setups fail for one of two reasons. Get these right and the rest is plumbing: 1. **Pick a capable model.** SPECLAN's heavy features (Infer Specs, Clarification, CR Merge, HLRD Import) are *agentic* — they chain many tool calls and require strong instruction-following. Small or MoE models loop, hallucinate, or produce garbage. See [Recommended Models](#recommended-models) below — in short: **Qwen 3.6 (instruct) or dense Gemma 4 (27B)** are your best starting points. 2. **Configure a 50k+ token context window.** The default in most servers (especially LM Studio at 4096 tokens) is far too small. SPECLAN's system prompt, tool definitions, and multi-turn tool results easily exceed 4k. Aim for **50,000 tokens minimum**; set it to the model's maximum if your RAM allows. If you get nothing else right, get these right. ## TL;DR — Fastest Path to Working If you just want it running, pick **Ollama**. It has the least to configure: one install, one `ollama pull `, no GUI, no context length to tune (Ollama picks a sensible value from the model's native capability). Everything past Step 1 takes about two minutes. The setup in this guide is a one-time job. Once SPECLAN is pointed at your local server, every AI feature in the extension routes through it — no more touching the server unless you change models. ## What You Need - A machine with at least **8 GB RAM** (16 GB+ recommended for larger models; for Qwen 3.6 35B A3B, plan on 64 GB+ unified memory) - SPECLAN VS Code extension with **Experimental features enabled** - One of: Ollama, LM Studio, or vLLM installed and running ## How It Works Local LLM servers expose an OpenAI-compatible API on your machine. SPECLAN connects to that API the same way it connects to OpenAI's cloud — but the traffic stays on `localhost`. The AI features (spec editing, artifact generation, clarification, CR merge) work the same way regardless of whether the model runs locally or in the cloud. Quality depends on the model. Smaller models (1–8B parameters) are fast but may struggle with complex specification tasks. Larger models (20B+) produce better results but need more RAM and are slower. --- ## Step 1: Install a Local LLM Server Pick one. You only need one. ### Option A: Ollama (recommended for first-time setup) Ollama is the simplest option. One install, one command, models download automatically. Context length is handled for you — there are no sliders to tune. 1. Install from [ollama.com](https://ollama.com) 2. Pull a model: ```bash ollama pull gemma4 ``` 3. Ollama runs automatically after install. Default endpoint: `http://localhost:11434` **Further reading:** [Ollama documentation](https://github.com/ollama/ollama/tree/main/docs) · [Model library](https://ollama.com/library) · [OpenAI-compatible API reference](https://github.com/ollama/ollama/blob/main/docs/openai.md) ### Option B: LM Studio LM Studio gives you a GUI for browsing, downloading, and configuring models. 1. Download from [lmstudio.ai](https://lmstudio.ai) 2. Open LM Studio, search for a model (e.g., "qwen3.6" or "gemma-4"), and download it 3. Go to the **Developer** tab (the `<->` icon in the sidebar) and click **Start Server** 4. Default endpoint: `http://localhost:1234` **Critical: Context Length (read this, don't skip it)** This is the single most common reason local LLM setups fail. LM Studio defaults to a **4096-token** context window. SPECLAN's agentic workflows (Infer Specs, Clarification, CR Merge, HLRD Import) need **at least 50,000 tokens** — the system prompt, tool definitions, and intermediate tool results alone consume far more than 4k. Without enough context, you will see errors like: > The number of tokens to keep from the initial prompt is greater than the context length Or — worse — the model silently truncates its own reasoning and produces garbage output with no error at all. **How to fix it in LM Studio:** 1. In LM Studio, open the **Load** panel for your model (right sidebar) 2. Under **Context and Offload**, drag the **Context Length** slider to **50,000+** tokens (we recommend using the model's full supported length if your RAM allows — Qwen 3.6 35B A3B, for example, supports 262,144 tokens) 3. Set **GPU Offload** as high as your VRAM allows for acceptable speed 4. **Reload the model** — context length changes only apply after reloading ![LM Studio Load panel showing Context Length set to the model's maximum of 262,144 tokens and GPU Offload at 40 layers for Qwen 3.6 35B A3B](/help/reference/local-llm/set-context-size.png) Ollama handles context length automatically based on the model's native capability — another reason it's the easier starting point. **Further reading:** [LM Studio documentation](https://lmstudio.ai/docs) · [LM Studio OpenAI-compatible API](https://lmstudio.ai/docs/app/api/endpoints/openai) · [Configuring per-model context length](https://lmstudio.ai/docs/app/basics) ### Option C: vLLM vLLM is a high-performance inference server, best if you have a GPU. 1. Install: `pip install vllm` 2. Start with an explicit context length — vLLM's default is often the model's maximum, but set it explicitly so you know what you're getting: ```bash vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 --max-model-len 65536 ``` 3. Default endpoint: `http://localhost:8000` **Further reading:** [vLLM documentation](https://docs.vllm.ai/) · [vLLM OpenAI-compatible server](https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html) --- ## Step 2: Enable Experimental Features Local LLM support is an experimental feature. You need to enable it once. 1. Open VS Code Settings (`Cmd+,` on Mac, `Ctrl+,` on Windows/Linux) 2. Search for `speclan.experimental` 3. Check the **Enable experimental features** checkbox --- ## Step 3: Configure SPECLAN to Use Your Local Server 1. Open the SPECLAN sidebar and click **Settings** (gear icon) 2. Go to the **LLM Configuration** tab 3. In the **API Keys** section, find the **Local LLM (Experimental)** card ![Local LLM API Keys card: base URL field prefilled with http://localhost:1234, Test button, delete icon, quick-pick chips for Ollama / LM Studio / vLLM, optional API Key field, and a STORED badge indicating the URL is saved](/help/reference/local-llm/localLLM-URL.png) **What each control does:** - **Base URL field** (`http://localhost:1234` shown) — the endpoint SPECLAN calls. Must match the server you started in Step 1. - **Quick-pick chips** (`Ollama`, `LM Studio`, `vLLM`) — click one to fill in its default URL (`:11434`, `:1234`, `:8000`). Faster than typing. - **Test button** (flask icon) — sends a probe request to `/v1/models` and confirms the server is reachable. Do this before moving on. - **Trash icon** — clears the saved URL for this card. - **API Key field** — optional. Most local servers ignore this. Fill it in only if you've put your server behind an auth proxy. Click the eye icon to reveal. - **STORED badge** — appears in the top right once the URL is saved to your user settings. No badge means the URL is unsaved. Enter your base URL (or click a quick-pick), then click **Test**. Wait for the success confirmation before continuing. --- ## Step 4: Select a Model In the **LLM Model** section, switch the provider to **Local LLM (Experimental)**, pick a model, and apply it. ![LLM Model panel: Current-model summary at top (qwen/qwen3.6-35b-a3b, Provider: Local LLM, Model ID), Provider dropdown set to Local LLM (Experimental), Model dropdown with refresh button, State panel showing Loaded / Context window 262.1K / Quantization Q4_K_M / Architecture qwen35moe / Runtime LM Studio / Tool use Supported, and three action buttons: Apply Model, Test Selected Model, Refresh](/help/reference/local-llm/configLLM.png) **What each control does:** - **Current model summary** (top card) — read-only view of what SPECLAN is *actually* using right now: model name, provider, and full Model ID. This updates only after you click **Apply Model**. - **Provider dropdown** — choose `Local LLM (Experimental)`. Cloud providers (Claude, OpenAI, Google) stay available in the same list — switching back later does not wipe your local config. - **Model dropdown** — populated from your server's `/v1/models` endpoint. If it's empty, your server isn't reachable; see [troubleshooting](#model-dropdown-is-empty-or-disabled). - **Refresh button** (circular arrow, right of the Model dropdown) — re-fetches the model list. Use it after you load a new model in LM Studio or pull a new one with Ollama. - **State panel** — diagnostic info about the selected model: - **State** (e.g., `Loaded`, green dot) — whether the server has the model resident in memory and ready to answer. - **Context window** (e.g., `262.1K`) — the effective context length the server is serving this model with. If this shows `4.0K`, stop and go back to Step 1 Option B; your server will choke on SPECLAN's agentic workflows. - **Quantization** (e.g., `Q4_K_M`) — the weight-precision format. Q4 variants are the usual speed/quality sweet spot. - **Architecture** (e.g., `qwen35moe`) — the model family. Look for `moe` in the name: mixture-of-experts variants are faster but weaker at sequential tool use (see [Known Local Model Limitations](#known-local-model-limitations)). - **Runtime** (e.g., `LM Studio`) — which local server is hosting the model. Handy when you have both Ollama and LM Studio running. - **Tool use** (e.g., `Supported`) — whether the model advertises function-calling. If this says `Not supported`, heavy workflows will fail — pick a different model. - **Apply Model** — commits the selection. Nothing is active until you click this. - **Test Selected Model** — runs a short live round-trip through the model (a few tokens in, a few tokens out) so you can catch broken configurations before you hit a real workflow. - **Refresh** (bottom, duplicate of the dropdown refresh) — same action, placed with the buttons for convenience. Recommended order: pick a model → **Test Selected Model** → **Apply Model**. If the model dropdown is empty, your server may not be running or the URL may be incorrect. Check the URL in the API Keys tab and click the refresh button next to the model dropdown. --- ## Step 5: Use SPECLAN as Usual All AI features now route through your local model. Open a spec, use the AI chat, generate artifacts, run clarification — it all works the same way. ### Switching Back to a Cloud Provider Select a different provider (Claude, OpenAI, or Google) from the LLM Model dropdown and click **Apply Model**. Your local server configuration is preserved — you can switch back anytime. --- ## SPECLAN Feature Compatibility with Local LLMs Not every SPECLAN feature works equally well on every local model. SPECLAN has two distinct categories of AI workloads, and your local model's capabilities determine which ones you can use reliably. ### Light Workloads (work on most local models) These features use a single AI call with a focused prompt. Most 8B+ local models handle them well: - **Spec editing with AI chat** (in the spec editor) - **Slash commands** (`/rewrite`, `/shorten`, `/expand`) - **Commit message generation** (Git Sync panel) - **Frontmatter repair** - **AI response to a single question** ### Heavy Workloads (require capable tool-calling models) These features are **agentic** — the AI calls multiple MCP tools in sequence, reads intermediate results, and decides what to do next. They place heavy demands on the model's reasoning, instruction-following, and self-termination. Most small local models fail here. - **Infer Specifications from Codebase** — the AI explores your code, creates features, creates requirements with acceptance criteria, and links to goals. Many sequential `speclan_create` / `speclan_update` calls. - **HLRD Import** — turns a requirements document into structured specs via multi-phase analysis - **Clarification Workflow** — the AI finds issues in your specs and proposes structured changes - **CR Merge** — the AI merges a Change Request into its parent spec - **Artifact Generation with Clarification** — multi-turn Q&A with the user ### Known Local Model Limitations When a local model isn't capable enough for a heavy workflow, you typically see one of these failure modes. All have been reproduced in our E2E test harness: > **Note on tool names:** SPECLAN's MCP server now exposes 13 consolidated `speclan_*` tools (e.g. `speclan_create`, `speclan_update`). The tool names shown below and in the benchmark table are the current v2 names; the failure-mode observations and measurements themselves were gathered before the v2 tool consolidation, but the behaviors described are unchanged. | Failure mode | What happens | Typical cause | |---|---|---| | **Tool-call loop** | Model calls the same MCP tool (e.g., `speclan_update`) with the same arguments 5–10+ times in a row until it hits the turn limit | Model can't recognize "the tool already succeeded, I'm done." Common on Gemma MoE variants — Google's own docs note Gemma has no built-in loop termination | | **Tool hallucination** | Model's final answer claims the spec was updated, but no MCP tool was actually called. The file on disk is unchanged | Model generated a "completion" narrative instead of executing tool calls. Seen on GPT-OSS 20B via LM Studio | | **Garbage frontmatter** | YAML frontmatter is malformed — body content jammed into the `title:` field, markdown sections missing | Model doesn't follow the exact argument schema of the MCP tool, confusing field names | | **Infinite retry on parse errors** | Wizard shows "JSON parse failed, retrying..." over and over, then gives up after 3 attempts | Model ignores the response schema, returns freeform text or wrong-shape JSON | These are **limitations of the local model**, not SPECLAN bugs. Cloud models (Claude, GPT-4/5, Gemini) are trained specifically for agentic tool use and rarely exhibit these issues. ### E2E Benchmark Results We test each local model with our live-LLM harness (`apps/ai-agents-e2e`). Results on a representative multi-step MCP workflow (reading and updating a requirement with full description + acceptance criteria): | Server | Model | Tool-calling | Structured output | Verdict | |---|---|---|---|---| | Ollama | `gemma4:latest` (dense) | PASS | PASS | Good for heavy workflows | | Ollama | `gemma4:31b` (dense) | PASS | PASS | Slower but clean | | Ollama | `gpt-oss:20b` | PASS | FAIL | OK for Infer Specs, not Clarification | | LM Studio | `qwen/qwen3.6-35b-a3b` (MoE) | PASS | PASS | **Our current pick** — with 50k+ context | | LM Studio | `google/gemma-4-26b-a4b` (MoE) | **FAIL (loop)** | PASS | Light workloads only | | LM Studio | `openai/gpt-oss-20b` | **FAIL (hallucinates)** | PASS | Light workloads only | | LM Studio | `openai/gpt-oss-120b` | **FAIL (partial tool call)** | PASS | Bigger is not always safer | Three patterns stand out: 1. **MoE variants (A4B) are weaker at sequential tool use** than their dense counterparts — with the notable exception of Qwen 3.6, whose training mix produces reliable agentic behavior despite MoE. 2. **Ollama's native tool-calling harness is more reliable** than LM Studio's OpenAI-compatibility layer for the same base model family. If a model works in Ollama but fails in LM Studio, it's usually a chat-template translation issue, not a model-quality issue. 3. **Size does not rescue you.** The 120B variant of `gpt-oss` on LM Studio failed in the same category as its 20B sibling. Picking the right 8B can beat picking the wrong 120B. For the full narrative behind these results — including why we almost shipped without Qwen 3.6 and what changed when we tried it — see the companion blog post [We Gave SPECLAN a Local Brain](/blog/2026-04-25-we-gave-speclan-a-local-brain/). ## See What Each Model Actually Writes Recommendations and benchmark tables only take you so far — at some point you have to read what a model produces. We ran the same brief (the excalidraw codebase) through Claude Opus 4.7, Sonnet 4.6, Haiku 4.5, GPT 5.4, and GPT 5.4 Mini and parked every resulting spec tree side-by-side at [speclan.net/compare](/compare/). Pick a feature, pick a requirement, read what each model authored. Useful for calibrating expectations against a real decomposition before you commit to a local setup. ## Recommended Models ### For light workloads (AI chat, slash commands, commit messages) Any 8B+ instruction-tuned model works: | Model | Parameters | RAM Needed | Notes | |---|---|---|---| | Llama 3.1 (8B) | 8B | 6 GB | Fast, good enough for quick edits | | Gemma 4 (dense variant) | 27B | 14 GB | Best balance of quality and speed | | GPT-OSS (20B) | 20B | 12 GB | Strong at instruction following | ### For heavy workloads (Infer Specs, Clarification, CR Merge, HLRD) You need a model that reliably handles sequential tool calls AND structured output. Our current recommendations, ordered by preference: | Model | Parameters | RAM Needed | Notes | |---|---|---|---| | **Qwen 3.6 35B A3B (LM Studio, 50k+ context)** | 35B (3B active) | 64 GB+ | **Team pick.** Passes our full E2E benchmark. Best quality on capable hardware. | | **Ollama `gemma4:latest` (dense)** | 27B | 14 GB | Passes our full E2E benchmark. Best general-purpose choice on modest hardware. | | Qwen 3.5 (instruct) | 4–30B | 4–16 GB | Top of 2026 tool-calling benchmarks. Run in Ollama for best results. | | GLM-4.7 Flash | ~10B | 8 GB | High tool-calling accuracy per Hodges' 2026 eval. | ### Models to avoid for heavy workloads (based on current testing) - **`google/gemma-4-26b-a4b`** in LM Studio — infinite tool-call loops on multi-step workflows - **`openai/gpt-oss-20b`** in LM Studio — hallucinates tool calls, file never actually updated - **Any model under 7B** — not enough reasoning for multi-step agentic workflows - **Base models (non-instruct)** — function calling requires instruction tuning ### If a heavy workflow fails 1. Check the **SPECLAN Debug** output channel — look for repeated identical tool calls (loop) or missing tool calls with a claim-of-completion final answer (hallucination) 2. Try the same model in Ollama if you were using LM Studio (or vice versa) — the integration layer often matters more than the model 3. Fall back to a cloud provider for the specific workflow. You can switch providers freely — your local configuration is preserved 4. Try a smaller but more capable model — Qwen 3.5 4B often beats Gemma 26B on tool calling --- ## Troubleshooting ### "Model did not produce a final response!" Your local server's context length is too small — by far the most common cause. See the LM Studio context length note in Step 1, Option B. Increase the **Context Length** slider to **50,000+ tokens** (use the model's maximum if your RAM allows) and reload the model. ### "Unknown provider: local" Enable experimental features (Step 2). Local LLM only appears when `speclan.experimental` is checked. ### Model dropdown is empty or disabled - Check that your server is running (`curl http://localhost:11434/v1/models`) - Verify the URL in the Local LLM API Keys card - Click the refresh button next to the model dropdown ### "ECONNREFUSED" or "Network error" Your local server is not running or is on a different port. Start the server and check the URL. ### Slow responses Local inference speed depends on your hardware. Tips: - Use a smaller model (8B instead of 70B) - Close other memory-intensive applications - If using LM Studio, enable GPU offloading in model settings - If using Ollama on Apple Silicon, it uses Metal acceleration by default ### Infer Specs or Clarification gets stuck in a loop You see the same tool call (like `speclan_update → R-0049`) in the log repeated many times per second, and the workflow never completes. Your model can't terminate its own agentic workflow — see the **Tool-call loop** failure mode above. Switch to a dense (non-MoE) model or use Ollama instead of LM Studio for the same model family. See the recommendations for heavy workloads. ### Spec files look empty or have body content in `title:` The frontmatter shows something like `title: "Multi-line description got jammed in here..."` and the actual body is the placeholder `Feature description goes here.` Your model isn't following the MCP tool argument schema — it's putting body content into the wrong argument. Switch to a more capable model for heavy workloads. ### "JSON parse failed, retrying..." repeats and gives up Your model isn't following the expected response schema for the workflow. SPECLAN retries up to 3 times with a reformatting prompt, then aborts. If this happens consistently on a specific workflow, try a different model. Qwen 3.6 and dense Gemma variants handle structured output more reliably than most other MoE variants. --- Local LLM support shipped in [SPECLAN v0.9.6](/news/2026-04-25-releasev0-9-6/). See the release notes for context on the other v0.9.6 LLM provider additions (ChatGPT OAuth, weaker-model adjustments). --- ### SpecURI Source: https://speclan.net/help/reference/specuri/ You are reviewing a clickdummy an agent built from your specs. A button in the mockup has a small link beside it: *F-1234 — Session Invitations*. You click it, and the Feature opens in VS Code, right there in the SPECLAN editor, revealed in the tree with its parents expanded. That link is a SpecURI. It is how a generated work product points back at the specification that governs it. This page covers what a SpecURI is, what happens when you click one, how links behave when you have several SPECLAN projects open, and what to do when a link appears to do nothing. ## What Is a SpecURI? A SpecURI is a link that names a SPECLAN entity by its ID and opens it in VS Code: ``` vscode://DigitalDividend.speclan-vscode-extension/open?id=F-1234 ``` It can name any of four entity types: | Type | ID shape | Example | |---|---|---| | Goal | `G-###` | `G-002` | | Feature | `F-####` | `F-1234` | | Requirement | `R-####` | `R-0291` | | Change Request | `CR-####` | `CR-8931` | **The ID is the durable handle.** A SpecURI does not contain a file path. When you click it, SPECLAN looks the ID up in the current project's index and opens whatever file holds it *right now*. Rename the spec, move it under a different parent, reorganise the whole tree — the link still lands. This is the main reason to link by SpecURI rather than by relative path. ## Where the Links Come From You will mostly encounter SpecURIs rather than write them. The intended producer is an AI agent generating something from your specs — an interactive clickdummy, a status report, a diagram, a slide deck. As it builds each element, it embeds a back-reference to the Goal, Feature, or Requirement that element realizes. The result is a work product you can audit: every claim in it is one click from the specification it came from. That is a task an agent does well and a human does badly. An agent already knows which spec it used for each element, and it can read the project's identity out of git. Hand-writing these links is possible — the format is documented at the bottom of this page — but it is not the point of the feature. ## Clicking a Link The first time you follow a SpecURI, VS Code asks: > **Allow 'SPECLAN' extension to open this URI?** That prompt comes from VS Code, not from SPECLAN, and it appears once per extension. Tick **Do not ask me again for this extension** if you follow links regularly. Then the spec opens: - **Goals, Features and Requirements** open in the SPECLAN editor and are revealed in the tree, with their parent chain expanded so you can see where the spec sits. - **Change Requests** open the Change Request's own file. - The tab is **persistent**, not a preview — it will not be replaced by the next thing you open, because following a link is a deliberate navigation. **Following a link never changes anything.** A SpecURI can only navigate. It cannot edit a spec, create one, delete one, or run anything. There is no link you can be sent that modifies your specifications. ## Working Across Several Projects Here is the part worth understanding before it surprises you. SPECLAN IDs are four random digits, assigned per project. Two different projects can both contain an `F-1234`, and they will be completely unrelated specs. So a bare `?id=F-1234` link is only unambiguous inside one project. For that reason a link can carry a **workspace key** identifying which project it belongs to: ``` vscode://DigitalDividend.speclan-vscode-extension/open?id=F-1234&ws=github.com%2Facme%2Fspeclan ``` The key is either the project's git remote reduced to `host/owner/repo`, or — for a project with no remote — `path:` followed by its folder path. The git-remote form is the portable one: it is the same for every clone of the repository, on every machine. ### Which window answers the link **VS Code hands a `vscode://` link to whichever window you used last.** Not the window holding the target project — the most recently focused one. If you have SPECLAN open on three projects, the link goes wherever your attention happened to be. SPECLAN's job is to make sure that never misleads you: | Situation | What happens | |---|---| | The link names your current project (or carries no workspace key) and the spec exists here | The spec opens | | The link carries a workspace key for a **different** project | SPECLAN declines: *"This link points at SPECLAN F-1234 in a different project. Open that project, then follow the link again."* | | The link carries no workspace key and the ID is not in this project | *"SPECLAN F-1234 not found in this workspace"*, with a **Go to Spec…** button to search what you do have open | The middle row is the one that matters. A workspace-qualified link will **never** open a same-numbered spec from the wrong project. Being shown the wrong `F-1234` with no indication anything went wrong would be far worse than being told to switch projects. **Today, switching is manual.** SPECLAN does not open or switch a workspace for you. Focus (or open) the window holding that project, then follow the link again. Automatic routing to the right window is planned but not yet available. ## When Nothing Seems to Happen **You clicked a link, VS Code asked permission, you clicked Open — and nothing happened.** Almost always, the window that received the link is running a SPECLAN version from before deep links existed. VS Code decides whether to show the permission prompt by looking at the *installed* extension, but delivers the link to the *running* one — and a window that has been open since before the update is still running the old code, which has nothing to receive it. Fix it with **Developer: Reload Window** (`Cmd/Ctrl+Shift+P`) in that window. After any SPECLAN update, windows you already had open keep running the previous version until they are reloaded. **"…is not a valid SPECLAN entity ID."** The link is malformed, or names something that is not a Goal, Feature, Requirement, or Change Request. Nothing was opened or changed. If an agent generated it, the ID was likely invented rather than read from the project. **"This link needs a newer version of SPECLAN."** The link uses a capability your installed version does not have — for example, a link produced by a newer SPECLAN. Update the extension. Old versions decline politely rather than guessing. **"SPECLAN F-1234 not found in this workspace."** The link reached a project that does not contain that ID. Either the wrong window answered — see above — or the spec has been deleted. Use the **Go to Spec…** button to search the project you are actually in. ## Writing a Link Yourself *This section is for agents generating artifacts, and for anyone constructing a link by hand.* ``` vscode://DigitalDividend.speclan-vscode-extension/open?id=[&ws=] ``` | Part | Value | |---|---| | Scheme | `vscode` — use `vscode-insiders` to target VS Code Insiders | | Extension identity | `DigitalDividend.speclan-vscode-extension`, always exactly this | | Action | `open` | | `id` | The entity ID: `G-###`, `F-####`, `R-####`, or `CR-####`. Case is not significant | | `ws` | Optional workspace key — see below | To determine the workspace key for a project: 1. Read its `origin` remote and reduce it to `host/owner/repo`, lower-cased and without a `.git` suffix. `git@github.com:Acme/SpecLan.git` and `https://github.com/acme/speclan` both give `github.com/acme/speclan`. 2. If the project has no remote, use `path:` followed by the absolute path of the project folder. This form only works on the machine that folder lives on. **URL-encode every value.** A workspace key contains `/` and often `:`. Include `ws` whenever the artifact might be read alongside another SPECLAN project — which, for anything shared with a colleague, is most of the time. Omit it only for a link that will be followed inside a single known project. Unknown parameters are ignored, so adding your own metadata to a link is harmless. ## Related - [Artifacts](/help/artifacts) — where generated work products carrying back-reference links usually live - [Getting Started](/help/getting-started-greenfield) — new to SPECLAN and looking for the basics first --- ### BMAD Support Source: https://speclan.net/help/reference/speclan-plugin/bmad-support/ The SPECLAN Plugin for Claude Code converts between [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) and SPECLAN in both directions. Three commands handle the bridge: one imports BMAD artifacts into SPECLAN, two export SPECLAN specs back to BMAD format. This page covers what maps to what, how each command works, and how to set up a project that uses both frameworks together. ## What Is BMAD-METHOD? BMAD-METHOD is an AI-driven agile framework that organizes development through specialized agent personas. A PM agent ("John") facilitates PRD creation through collaborative interviews. An Architect agent ("Winston") documents technical decisions. A QA agent and UX Designer handle their respective domains. Each agent runs structured, step-by-step workflows that produce planning artifacts: Product Briefs, PRDs with measurable Functional Requirements, Architecture Documents, Epics with User Stories and BDD Acceptance Criteria. BMAD excels at the **discovery and planning phase** -- turning a vague product idea into precise, measurable specifications through facilitated agent conversations. SPECLAN picks up where BMAD's planning phase ends. It manages the **lifecycle after planning** -- status transitions (`draft` through `released`), change request tracking for locked specs, traceability across your hierarchy, and AI prime context for implementation agents. The philosophy: **plan with BMAD, govern with SPECLAN**. ## How BMAD and SPECLAN Map to Each Other When you convert between BMAD and SPECLAN, concepts map as follows: | BMAD Concept | SPECLAN Entity | Notes | |---|---|---| | Success Criteria (User, Business, Technical) | Goals (`G-###`) | Each measurable outcome becomes a Goal | | PRD Capability Areas | Parent Features (`F-####`) | Top-level grouping preserved | | Functional Requirements (`FR#`) | Requirements (`R-####`) | `[Actor] can [capability]` format retained, acceptance criteria converted | | Epic Stories / User Stories | Child Features (`F-####`) | User Story format preserved in description | | BDD Acceptance Criteria (`Given/When/Then`) | Acceptance Criteria checkboxes (`- [ ]`) | Each step becomes a checkbox item | | Non-Functional Requirements | NFR Features (`F-####`) | Measurable thresholds preserved | | Product Scope phases (MVP, Growth, Vision) | Scope tags on Features | Phase boundaries maintained | | Architecture Requirements (`AR#`) | Requirements under Architecture Features | Captured from Architecture Documents | | UX Requirements (`UX#`) | Requirements under UX Features | Captured from Epics document | ### Non-Obvious Mappings **FR Coverage Map authority.** When both a PRD and an Epics document exist, the converter uses BMAD's FR Coverage Map -- the authoritative table that assigns each Functional Requirement to an Epic -- rather than guessing from section headings. This produces more accurate Feature groupings. **Developer-infrastructure reclassification.** Functional Requirements where the actor is "Project" or "Build system" rather than a user (for example, `FR8: Project can lint and format code automatically`) are not user-facing behavior. The converter reclassifies these as NFRs under a Code Quality feature, keeping your spec hierarchy focused on what users experience. **Implementation stripping.** BMAD artifacts often include technology names, architecture patterns, and file paths -- useful during planning, but not appropriate for specifications that define _what_ rather than _how_. The converter strips implementation-specific language during import. A requirement like "Use PostgreSQL for data persistence" becomes "The system persists data reliably" -- the architecture decision lives in your Architecture Document, not in your spec. ## Prerequisites You need two things installed before using the BMAD conversion commands. ### BMAD-METHOD Install BMAD's agent skills into your project: ``` npx bmad-method install ``` This creates the `_bmad/` directory with BMAD's agent personas and workflow templates. You only need this for planning with BMAD agents and for the `/speclan:to-bmad` command. The other two commands (`from-bmad` and `to-bmad-prd`) work without BMAD skills installed. ### SPECLAN Plugin Install the plugin through the cc-marketplace: ``` /plugin marketplace add thlandgraf/cc-marketplace /plugin install speclan@digital-dividend-marketplace ``` See the [plugin overview](/help/getting-started/speclan-plugin/) for detailed installation instructions and scope options. ## Importing BMAD Artifacts (`/speclan:from-bmad`) This command reads your BMAD planning artifacts and builds the corresponding SPECLAN hierarchy. ### What It Reads The converter looks in your `_bmad-output/planning-artifacts/` directory for: - **PRD** -- Capability Areas, Functional Requirements, Non-Functional Requirements, Success Criteria, Product Scope - **Epics document** -- Epic Stories, User Stories, BDD Acceptance Criteria, FR Coverage Map, Architecture-derived requirements (`AR#`), UX-derived requirements (`UX#`) - **Architecture Document** -- Architecture requirements and decisions You do not need all three. The converter works with whatever artifacts it finds -- a PRD alone is enough. ### What It Produces The converter builds a SPECLAN hierarchy from the BMAD artifacts: ``` speclan/ goals/ G-001-user-success.md # from Success Criteria G-002-business-success.md features/ F-1234-user-management/ # from Capability Area F-1234-user-management.md requirements/ R-5678-user-registration/ # from FR1 R-5678-user-registration.md F-2345-registration-flow/ # from Epic Story F-2345-registration-flow.md F-9012-nfr-performance/ # from NFR category F-9012-nfr-performance.md ``` All imported entities land at `status: review`, giving you a chance to inspect the conversion before approving anything. ### Provenance Tracking Each imported entity carries a `provenance` field in its frontmatter that links back to the original BMAD source: ```yaml provenance: source: bmad file: _bmad-output/planning-artifacts/prd.md ref: "FR3" ``` This field serves two purposes: 1. **Traceability** -- you can always trace a SPECLAN entity back to the BMAD artifact it came from 2. **Re-import deduplication** -- when you re-run `/speclan:from-bmad` after updating your BMAD artifacts, the converter matches existing entities by their provenance rather than creating duplicates. New content is merged; your manual edits to descriptions or acceptance criteria are preserved. ### Running the Import ``` /speclan:from-bmad ``` The converter discovers your BMAD artifacts automatically. After it finishes, review the generated hierarchy: ``` /speclan:ask show all features ``` Check that the mapping makes sense for your project. You can adjust entity titles, descriptions, and parent-child relationships before transitioning anything to `approved`. ### ID Generation SPECLAN generates its own IDs (`G-###`, `F-####`, `R-####`) during import -- it does not reuse BMAD's `FR#` or Epic numbering. IDs are random and collision-checked against your existing spec repository. The original BMAD identifiers are preserved in the `provenance` field. ## Exporting to BMAD Two commands export SPECLAN specifications to BMAD format. Which one you use depends on whether you have BMAD installed and how you want the output produced. ### Decision Guide | | `/speclan:to-bmad` | `/speclan:to-bmad-prd` | |---|---|---| | **Requires BMAD skills** | Yes | No | | **How it works** | Feeds specs into BMAD's PM agent workflow | Generates PRD directly from spec data | | **Output style** | BMAD-native, follows BMAD templates | BMAD-standard format, built by SPECLAN | | **Best for** | Teams already running BMAD workflows | Quick PRD export without BMAD installation | | **Traceability** | Links back to SPECLAN source files | Links back to SPECLAN source files | | **Quality checks** | BMAD's own validation | Implementation leak detection, NFR measurement verification | ### `/speclan:to-bmad` -- Export via BMAD's Native PM Workflow This command feeds your approved SPECLAN specifications into BMAD's PM agent workflow. It invokes `/bmad-bmm-create-prd`, and the PM agent -- "John" -- runs its full step-by-step PRD creation process using your specs as input. The result is a BMAD-native PRD that follows BMAD's own templates and validation rules, with traceability links back to your SPECLAN source files. ``` /speclan:to-bmad ``` Use this when your team already runs BMAD workflows and you want the PRD to feel native to that ecosystem. **Requirement:** BMAD skills must be installed in your project (`_bmad/` directory must exist). If they are not, the command tells you to run `npx bmad-method install` first. ### `/speclan:to-bmad-prd` -- Standalone PRD Export No BMAD installation required. This command reads your approved SPECLAN specifications and generates a complete BMAD-standard PRD directly: - **Executive Summary** derived from your Goals and their vision statements - **Success Criteria** mapped from Goal measurable outcomes - **User Journeys** reconstructed from your Scenario entities - **Functional Requirements** with `FR#` numbering, grouped by Capability Area - **Non-Functional Requirements** with measurement methods and testable thresholds - **Product Scope** with phase boundaries from your Feature scope tags ``` /speclan:to-bmad-prd ``` The output includes a **quality check pass** that catches two categories of problems: 1. **Implementation leaks** -- technology names, architecture patterns, file paths, or framework references that do not belong in a PRD. These are flagged so you can decide whether to remove them or keep them intentionally. 2. **NFR measurement methods** -- Non-Functional Requirements with subjective or vague thresholds (like "fast" or "reliable") are flagged. Each NFR should have a concrete, testable measurement method. Use this when you need a BMAD-format PRD for handoff or documentation but do not want to install BMAD's full agent ecosystem. ## The Bridge Workflow Here is how a full round-trip looks in practice. ### 1. Plan with BMAD Start by running BMAD's PM agent to create your planning artifacts: ``` /bmad-bmm-create-prd ``` The PM agent walks you through collaborative interviews to produce a PRD with Functional Requirements, NFRs, and Success Criteria. Then decompose it into Epics and Stories. Optionally, run the Architect agent for technical decisions. When planning is done, your `_bmad-output/planning-artifacts/` directory contains the PRD, Epics document, and Architecture Document. ### 2. Import to SPECLAN ``` /speclan:from-bmad ``` The converter reads your BMAD artifacts and builds the SPECLAN hierarchy. Everything lands at `review` status. Walk through the imported entities, adjust anything that needs refinement, and transition to `approved` when you are satisfied: ``` Transition all review features under F-1234 to approved ``` ### 3. Govern with SPECLAN Now you are in SPECLAN's world. Implement against structured specs with full lifecycle tracking: - Transition features to `in-development` when work starts - Create [change requests](/help/workflows/change-requests/) when approved specs need modification - Track progress through `under-test` to `released` - Use `/speclan:ask` to check project health at any point ### 4. Export Back When stakeholders need an updated PRD -- for a review, a handoff, or a new planning cycle -- generate one from your current approved specs: ``` /speclan:to-bmad-prd ``` The exported PRD reflects the current state of your specifications, including any changes made through change requests since the original import. ## Troubleshooting **No `_bmad/` directory found (for `/speclan:to-bmad`)** The `/speclan:to-bmad` command requires BMAD skills to be installed. Run: ``` npx bmad-method install ``` The other two commands (`from-bmad` and `to-bmad-prd`) do not require BMAD skills. **No planning artifacts found (for `/speclan:from-bmad`)** The converter looks in `_bmad-output/planning-artifacts/` for your PRD, Epics, and Architecture documents. If this directory is empty or missing, run BMAD's planning workflow first (`/bmad-bmm-create-prd`) to generate the artifacts. **Missing BMAD skills (for `/speclan:to-bmad`)** If the BMAD skills directory exists but the PM workflow is not available, your BMAD installation may be incomplete. Reinstall with `npx bmad-method install`. **Naming conflicts during import** If the converter encounters an entity with the same provenance reference as an existing SPECLAN entity, it updates the existing entity rather than creating a duplicate. If you see unexpected merges, check the `provenance` field in the affected entity's frontmatter to verify the source mapping is correct. **No approved specs for export** Both export commands (`to-bmad` and `to-bmad-prd`) require at least some specifications at `approved` status or beyond. If all your specs are still in `draft` or `review`, transition them through the [status lifecycle](/help/reference/status-lifecycle/) first. **Implementation language appearing in imported specs** The converter strips obvious implementation references (technology names, file paths, architecture patterns) during import. If implementation language still appears in your imported specs, edit the descriptions manually -- the converter is conservative and does not remove language it is not confident is implementation-specific. ## Related Topics - [The Claude Code SPECLAN Plugin](/help/getting-started/speclan-plugin/) -- Full plugin overview, installation, and usage - [Status Lifecycle](/help/reference/status-lifecycle/) -- The complete entity status progression from draft to released - [Change Requests](/help/workflows/change-requests/) -- How to modify locked specifications that are already in development - [BMAD-METHOD Documentation](https://github.com/bmad-code-org/BMAD-METHOD) -- BMAD's own guides, templates, and agent persona reference --- ### MCP Server Source: https://speclan.net/help/integrations/mcp-server/ Ask your AI assistant "what does F-1234 actually require?" and it usually guesses, or greps, or reads whatever file happens to be open. SPECLAN ships a server that removes the guessing. Start it from a panel in VS Code, point your assistant at it, and the assistant gets thirteen purpose-built tools for your specification tree: ranked search, entity lookup with ancestors and children, graph traversal, SQL queries, project statistics — and, if you allow it, the ability to create and update specs directly. This is the headline capability of this release. This page covers starting the server, configuring it safely, and connecting your particular assistant. ## What MCP Is, Briefly **Model Context Protocol** is an open standard for connecting AI assistants to data sources. An assistant that speaks MCP can use tools that any MCP server offers, without either side knowing about the other in advance. SPECLAN is such a server. You do not need to understand the protocol — you need to start the server and paste one line of configuration into your assistant. ## Opening the Control Panel Everything happens in one place. Open the Command Palette (`Cmd/Ctrl+Shift+P`) and run: **SPECLAN: Open MCP Server Control Panel** The panel has a status line and four sections: **Configuration**, **Authentication**, **Tools**, and **Connect a client**. ### Server status The status line shows one of three states: | State | Meaning | |---|---| | **Stopped** | Not running. Clients cannot connect. | | **Starting…** | Coming up. Usually momentary. | | **Running** | Accepting connections. The panel shows the URL and how many tools are live. | The **Start Server** button becomes **Stop Server** while running. **The server runs only while VS Code is open.** Close the window and it stops; clients lose their connection until you start it again. To have it come up on its own, enable `speclan.mcpServer.autoStart` in Settings — the server then starts whenever you open a SPECLAN project. The server listens on `127.0.0.1` — your own machine only. It is not reachable from your network, and there is nothing to expose to the internet. ## Configuration ### Port Default **3000**, giving the endpoint: ``` http://127.0.0.1:3000/mcp ``` If something else already uses that port, starting fails with *"Port 3000 is already in use"*. Change the port in the panel and start again. If you change it after a client is configured, update the client too — the URL is part of its configuration. ## Authentication The **Authentication** section controls whether clients must prove themselves. When no key is set, the panel shows **Off — open localhost**: any program running on your machine can connect and use the enabled tools. For a personal machine that is usually fine, and it is the zero-friction default. It is worth knowing rather than discovering. Click **Generate API Key** to change that. SPECLAN generates a random key, and the panel switches to showing the last four characters and the header clients must send: ``` X-API-Key: ••••••••abcd ``` Once a key exists, every request must carry that header. The button becomes **Regenerate Key** (mint a new one, invalidating the old) and **Clear Key** removes it, returning to open localhost. The key is stored in VS Code's encrypted secret storage. It is **not** synchronised to your other machines — generate a separate key on each, or set `speclan.mcpServer.apiKey` in Settings if you want to control the value yourself. **When you regenerate or clear the key, every configured client must be updated.** The snippets in *Connect a client* always contain the current key, so re-copying is the fastest fix. ## Tools The **Tools** section lists all thirteen tools in three groups. The header summarises the current selection, e.g. *"13 of 13 enabled"*. | Group | Tools | What the assistant can do | |---|---|---| | **Read specs** | `speclan_search`, `speclan_get`, `speclan_list`, `speclan_traverse`, `speclan_sql`, `speclan_project` | Ranked search, read an entity with its ancestors and children, list with filters, walk the spec graph, run read-only SQL over the tree, get project info and statistics | | **Write specs** | `speclan_create`, `speclan_update`, `speclan_transition`, `speclan_link`, `speclan_move`, `speclan_delete` | Create entities, edit them, move them through the status lifecycle, link them, relocate them, delete them | | **Artifacts** | `speclan_artifact` | List, read, add and remove artifacts | All thirteen are enabled by default. Untick any you would rather not expose; each group has **All** and **None** toggles. **Tool selection is locked while the server runs** — the panel shows *"Stop the server to change tools."* Stop it, adjust, start again. ### Read-only mode For a stronger guarantee than unticking boxes, turn on `speclan.mcpServer.readOnly` in Settings. The six write tools are then **not registered at all** — an assistant cannot call them because it never learns they exist — and `speclan_artifact` is narrowed to listing and reading. This is the setting to use when you want an assistant that can answer questions about your specs but must never change them. The panel shows *"Read-only mode is on"* while it applies. Read-only and per-tool selection combine: read-only removes the write surface, and your selection narrows what remains. ## Connect a Client Start the server first — the snippets contain the live URL and key. ### GitHub Copilot (VS Code) **Nothing to configure.** SPECLAN advertises the running server to VS Code directly; Copilot Chat picks it up on its own. Look for **SPECLAN** in Copilot's tools list, then ask it something about your specs. This requires VS Code **1.101 or newer**. On older versions the feature is simply absent — use the Cursor JSON approach below, which VS Code also accepts. ### Claude Code Click **Claude Code CLI** in *Connect a client* to copy the command, then run it in your project: ```bash claude mcp add --transport http speclan http://127.0.0.1:3000/mcp --header "X-API-Key: your-key-here" ``` The `--header` argument is included only when a key is set. Verify with `/mcp` inside Claude Code — `speclan` should be listed with its tools. ### Cursor Click **Cursor mcp.json** to copy this fragment, and merge it into Cursor's MCP configuration: ```json { "mcpServers": { "speclan": { "url": "http://127.0.0.1:3000/mcp", "headers": { "X-API-Key": "your-key-here" } } } } ``` The `headers` object is omitted when no key is set. Cursor shows the server in its MCP settings once saved. ### Claude Desktop Claude Desktop uses the same `mcpServers` shape as Cursor. Copy the **Cursor mcp.json** snippet and merge it into `claude_desktop_config.json`, then restart Claude Desktop. The SPECLAN tools appear in the attach menu. ### Any other MCP client Plenty of assistants speak MCP, and their configuration formats differ. SPECLAN's side is only ever these two values: - **Endpoint** — `http://127.0.0.1:3000/mcp` (streamable HTTP transport) - **Header** — `X-API-Key: `, only if you generated one Give those to your client in whatever form it expects; consult its documentation for where its MCP configuration lives. Most clients that accept a URL use the same `mcpServers` shape shown above, so the Cursor snippet is usually a good starting point. ### Clients that cannot use HTTP Some assistants only launch MCP servers as a subprocess over stdio. SPECLAN bundles a stdio server for exactly that case. Point the client at: ```bash node /mcp-stdio/speclan-stdio.js --specRoot=/path/to/your/project/speclan ``` Useful flags: `--readOnly` for a read-only surface, and `--owner=you@example.com` to set the owner recorded on entities the assistant creates. `SPECLAN_ROOT` and `SPECLAN_OWNER` work as environment variables instead. This server runs independently of the control panel — the panel's start/stop and settings do not apply to it. Note that `` contains the extension version and therefore changes when SPECLAN updates, so this configuration needs revisiting after an upgrade. Prefer the HTTP transport when your client supports it. ## Checking It Works Ask your assistant something only your specifications can answer: - *"Search my specs for anything about authentication."* - *"Show me F-1234 with its parent chain and child requirements."* - *"How many requirements are still in draft?"* - *"Which features contribute to G-002?"* The assistant reads the **live** tree. Edit a spec in VS Code and the next question sees the change — nothing to restart, no re-index. ## Troubleshooting **You just updated SPECLAN and the panel or server looks wrong.** A VS Code window keeps running the version it started with until you reload it, so a window opened before the update is still running the previous extension — with the previous MCP server, or none at all. Run **Developer: Reload Window** (`Cmd/Ctrl+Shift+P`) in that window. Worth doing first whenever something behaves as though a feature you just installed isn't there. **The client cannot connect.** Check the panel says **Running** — the server stops when VS Code closes. Then check the port in the client's configuration matches the panel. If a key is set, the client must send it; re-copy the snippet, since it always carries the current key. **"Port 3000 is already in use."** Another program has the port. Pick a different one in the panel, start again, and update your clients with the new URL. **The client connects but shows no tools.** Everything is unticked in the **Tools** section, or read-only mode is on and only write tools were selected. Check the header summary — it shows how many tools are enabled. **The assistant says it cannot create or update specs.** Either read-only mode is on, or the write tools are unticked. Both are deliberate; turn off `speclan.mcpServer.readOnly` and re-tick the Write specs group, then restart the server. **Anything else.** Open the Output panel (`Cmd/Ctrl+Shift+U`) and choose **SPECLAN Debug**. The server logs every start, stop, and tool call there, including the port, tool count, and whether authentication is on. ## Related - [Local LLM](/help/local-llm) — run the assistant itself on your own machine too - [Getting Started](/help/getting-started-greenfield) — new to SPECLAN and want the basics first --- ### Spec-Kit Integration Source: https://speclan.net/help/integrations/speckit/ If you already use [spec-kit](https://github.com/github/spec-kit) — GitHub's open-source spec-driven development workflow — you can author SPECLAN specifications from inside any of the 30+ AI coding agents spec-kit supports. Claude, Cursor, Codex, Cline, Windsurf, Gemini — they all become SPECLAN-aware once the `speckit-speclan` extension is installed. This is the spec-kit-first path into SPECLAN. The VS Code extension is still the richest way to browse and review specs, but the spec-kit integration lets you do the *authoring* from whichever agent you already work in. ## What You Get The `speckit-speclan` extension composes spec-kit's slash-command workflow with SPECLAN's typed entity model and status lifecycle: - **Typed entities** — Goals, Features, Requirements, Change Requests with collision-checked IDs (`G-###`, `F-####`, `R-####`, `CR-####`) instead of folder numbers. - **Status lifecycle** — every entity moves through `draft → review → approved → in-development → under-test → released → deprecated`. `/implement` is gated on `approved`. - **CR-gated edits** — once a spec is locked (`in-development` or later), edits must go through a Change Request whose lifecycle governs the merge. - **Pure shell** — `bash` + `yq` + `jq`; no Node, no Python on your machine. - **Drop-in hooks** — `/specify`, `/clarify`, and `/implement` participate in the SPECLAN lifecycle automatically. ## Prerequisites - [spec-kit](https://github.com/github/spec-kit) ≥ 0.8.0 installed (`specify` CLI on `PATH`). - An AI coding agent spec-kit supports. - `bash` ≥ 4, `yq` ≥ 4, `jq` ≥ 1.6, `git` ≥ 2.30. ## Installation Once the extension is listed in spec-kit's community catalog: ```bash specify extension add speclan ``` Before the catalog PR is merged, install directly from the GitHub Release: ```bash specify extension add speclan --from https://github.com/thlandgraf/speckit-speclan/releases/latest/download/speckit-speclan.zip ``` For contributors testing a local clone: ```bash specify extension add --dev /path/to/speckit-speclan ``` Then verify: ```bash specify extension list # → speclan 0.1.0 Apache-2.0 ``` If you previously installed an earlier build and need to refresh, remove first — `specify extension remove` keeps a backup at `.specify/extensions/.backup/` so you can roll back: ```bash specify extension remove speclan specify extension add --dev /path/to/speckit-speclan ``` You may see `⚠ Configuration may be required` after install. That message is a generic hint that fires whenever an extension declares `provides.config` entries — the `speclan-config.yml` this extension ships is `required: false`, so safe to ignore unless you want to override the defaults (`spec_root`, locked statuses, gate behaviour, etc.) baked into `data/format-spec.json`. ### Spec-kit version floor This extension declares `requires.speckit_version: ">=0.8.15"`. If your `specify` CLI is older, install a newer version with **force-reinstall** (`uv tool upgrade` does NOT accept `--from`): ```bash uv tool install --force specify-cli --from git+https://github.com/github/spec-kit.git@v0.8.16 ``` ## Commands The extension contributes 11 commands. Seven are user-facing; the other four (`intake`, `gate`, `migrate`, `plan`) are typically run via hooks or for one-shot operations. ### `/speckit.speclan.specify ` Create a Goal, Feature, or Requirement from a natural-language description. The extension picks the entity type from cues in the prompt and assigns a collision-checked ID. ```text > /speckit.speclan.specify a magic-link login flow for the web app ✓ Created speclan/features/F-7421-magic-link-login/F-7421-magic-link-login.md ✓ Wrote pointer specs/001-magic-link-login/SPECLAN.md ``` ### `/speckit.speclan.clarify ` Refine an entity. Behaviour depends on the entity's current status: - **Unlocked** (`draft` / `review` / `approved`) — direct edit. The body is updated and the `updated:` frontmatter is bumped. - **Locked** (`in-development` / `under-test` / `released`) — a Change Request is created under `/change-requests/`. The CR body is pre-populated with the current spec and a description of the proposed change. - **Deprecated** — refused. ```text > /speckit.speclan.clarify R-3094 also support magic links sent via SMS ✓ R-3094 is approved → direct edit applied ✓ updated: 2026-05-22 ``` ### `/speckit.speclan.status ` Advance an entity through the lifecycle. Transitions are forward-only — you cannot move a `released` spec back to `approved`. ```text > /speckit.speclan.status R-3094 approved ✓ R-3094: review → approved ``` ### `/speckit.speclan.implement ` Implement an approved Requirement. The command is gated on `status: approved`; non-approved requirements are refused with a clear error. On success the status transitions to `in-development`. ```text > /speckit.speclan.implement R-3094 ✓ Gate passed (R-3094 is approved) …agent implements… ✓ R-3094: approved → in-development ``` ### `/speckit.speclan.cr-create ` Open a Change Request against a locked spec. `change-type` is one of `enhancement`, `bugfix`, `breaking`, `deprecation`, `documentation`, `artifact`. ```text > /speckit.speclan.cr-create R-3094 enhancement add SMS magic-link support ✓ Created speclan/features/F-7421-…/requirements/R-3094-…/change-requests/CR-0567-sms-magic-link/CR-0567-sms-magic-link.md ``` ### `/speckit.speclan.cr-merge ` Merge an `approved` CR back into its parent. The original parent body is archived to a `.pre-CR-####.bak` file in the same directory; the parent's body is replaced with the CR's body verbatim. ```text > /speckit.speclan.cr-merge CR-0567 ✓ Archived parent → R-3094-…/R-3094-….pre-CR-0567.bak ✓ Merged CR-0567 into R-3094 ✓ CR-0567: approved → released ``` ### `/speckit.speclan.cr-close --reason ` Close a CR without merging. Reason is one of `rejected`, `cancelled`, `superseded`, `duplicate`, `obsolete`. ```text > /speckit.speclan.cr-close CR-0567 --reason duplicate ✓ CR-0567: review → deprecated (reason: duplicate) ``` ## The Composition Model The integration solves the two-stores problem by making each tool own its own surface: | Concern | Owner | Where it lives | |---|---|---| | Spec body (the WHAT) | SPECLAN | `speclan/features/F-####-slug/F-####-slug.md` | | Working artifacts (the HOW) | spec-kit | `specs/NNN-feature/plan.md`, `tasks.md`, `data-model.md`, … | | Lifecycle & governance | SPECLAN | YAML frontmatter, status DAG, Change Requests | | Agent UX | spec-kit | slash commands, agent rendering, plan/tasks/implement workflow | | Cross-link | `SPECLAN.md` pointer | `specs/NNN-feature/SPECLAN.md` | When you run `/specify` (vanilla spec-kit), the `after_specify` hook silently moves the generated `spec.md` into the SPECLAN tree, replaces it with a `SPECLAN.md` pointer, and assigns an ID. From that point forward, every command — vanilla spec-kit or `/speckit.speclan.*` — reads the spec body from the canonical SPECLAN location. ``` speclan/ ← canonical store (SPECLAN owns) features/F-7421-login/ F-7421-login.md ← THE spec requirements/R-3094-token-issuance/ R-3094-token-issuance.md change-requests/CR-0567-sms/ CR-0567-sms.md specs/ ← working dir (spec-kit owns) 001-login/ SPECLAN.md ← pointer to speclan/features/F-7421-login/ plan.md ← references F-7421 / R-3094 tasks.md ← references R-3094 data-model.md ``` ### Hook Integration Three spec-kit hooks are wired automatically: | Hook | Dispatches | What it does | |---|---|---| | `after_specify` | `/speckit.speclan.intake` | Moves `specs/NNN/spec.md` into the SPECLAN tree; writes `SPECLAN.md` pointer. No-op on projects without `speclan/`. | | `after_clarify` | `/speckit.speclan.clarify` | Routes the clarification through SPECLAN's status dispatch (direct edit if unlocked, CR if locked). Optional — prompts the user. | | `before_implement` | `/speckit.speclan.gate` | Blocks `/implement` unless every referenced entity is in `approved` status. Non-SPECLAN projects pass through silently. | The hooks degrade gracefully — if the project has no `speclan/` directory, every hook exits 0 silently and vanilla spec-kit behaviour is preserved. ### Migrating Existing Projects If you already have `specs/NNN-feature/` directories from previous spec-kit work, run: ```bash /speckit.speclan.migrate 001-login ``` The command converts the existing `spec.md` into a SPECLAN entity (preserving the body byte-for-byte) and writes the `SPECLAN.md` pointer. Every other file in the directory (`plan.md`, `tasks.md`, `data-model.md`, …) is preserved unchanged. ## Status Lifecycle ``` draft → review → approved → in-development → under-test → released → deprecated ``` - **`draft` → `review` → `approved`** — edits are direct. - **`in-development` → `under-test` → `released`** — the spec is locked; every edit must go through a Change Request. `/clarify` and `/implement` route appropriately. - **`deprecated`** — terminal. No further mutations allowed. See the [Status Lifecycle reference](/help/reference/status-lifecycle/) for the full state machine and transition rules. ## Configuration Defaults are sensible out of the box. To override, edit `.specify/extensions/speclan/speclan-config.yml` after installation. The full default template lives in [`config-template.yml`](https://github.com/thlandgraf/speckit-speclan/blob/main/config-template.yml) inside the public repo. ## Resources - [`thlandgraf/speckit-speclan` on GitHub](https://github.com/thlandgraf/speckit-speclan) — source, releases, issue tracker. - [spec-kit community catalog entry](https://github.com/github/spec-kit/blob/main/extensions/catalog.community.json) — find the `speclan` entry alongside other extensions. - [spec-kit documentation](https://github.com/github/spec-kit) — base workflow this extension extends. - [SPECLAN VS Code Extension](https://marketplace.visualstudio.com/items?itemName=DigitalDividend.speclan-vscode-extension) — rich UI for SPECLAN specs. - [`thlandgraf/speclan-essentials`](https://github.com/thlandgraf/speclan-essentials) — SPECLAN public docs and issue tracker. ## Feedback Bug reports and feature requests are tracked on the [`thlandgraf/speckit-speclan` issues page](https://github.com/thlandgraf/speckit-speclan/issues). For SPECLAN format questions, use [`thlandgraf/speclan-essentials`](https://github.com/thlandgraf/speclan-essentials/issues). --- ### HowTo: Revert to an Older Version Source: https://speclan.net/help/troubleshooting/revert-extension/ Something broke. A feature you relied on changed. A workflow that was smooth yesterday now stumbles. An update that should have made things better made them worse. It happens. And when it does, you need to get back to a version that works -- fast. This guide walks you through reverting the SPECLAN VS Code Extension to a previous version, keeping it there, and making sure we hear about the problem so it gets fixed. ## When to Revert You might want to revert if a recent update: - Introduced a bug that blocks your workflow - Changed or removed behavior you depend on - Causes compatibility issues with your VS Code version or project setup - Feels unstable compared to the version you were on before Reverting is a **temporary measure** -- a way to unblock yourself while the issue is addressed. It is not a permanent solution. We will cover how to report the problem so you can safely return to the latest version once a fix is released. --- ## Step 1: Find the Version You Want Before reverting, figure out which version to go back to. ### Check your update history If you are not sure which version you were running before the update, look at the [SPECLAN Changelog](https://marketplace.visualstudio.com/items/DigitalDividend.speclan-vscode-extension/changelog) on the VS Code Marketplace. Each release lists what changed. Find the version just before the change that caused your problem. ### Check your currently installed version Open the **Extensions** sidebar (`Ctrl+Shift+X` on Windows/Linux, `Cmd+Shift+X` on macOS), find **SPECLAN**, and look at the version number displayed next to the extension name. --- ## Step 2: Revert to an Older Version VS Code has built-in support for installing previous versions of any extension. No external downloads needed. ### Option A: Use the Extensions UI (Recommended) 1. Open **Extensions** (`Ctrl+Shift+X` / `Cmd+Shift+X`) 2. Find **SPECLAN** in your installed extensions (type `@installed speclan` in the search bar) 3. **Right-click** the SPECLAN extension 4. Select **Install Another Version...** 5. A list of all previously published versions appears -- pick the one you want 6. VS Code installs the selected version and prompts you to reload After the reload, you are running the older version. ### Option B: Use the Command Line If you prefer the terminal, VS Code's CLI can install a specific version directly: ```bash code --install-extension DigitalDividend.speclan-vscode-extension@0.9.2 --force ``` Replace `0.9.2` with the version number you want. The `--force` flag ensures the downgrade proceeds even though a newer version is already installed. To confirm what version is now installed: ```bash code --list-extensions --show-versions | grep speclan ``` ### Option C: Install From a VSIX File If you have a `.vsix` package file (for example, from a direct download or a team-shared archive): 1. Open the **Command Palette** (`Ctrl+Shift+P` / `Cmd+Shift+P`) 2. Run **Extensions: Install from VSIX...** 3. Select the `.vsix` file Or from the terminal: ```bash code --install-extension path/to/speclan-0.9.2.vsix ``` Installing from a VSIX file **automatically disables auto-update** for that extension, which means you will not be pushed back to the latest version unexpectedly. --- ## Step 3: Prevent Auto-Update By default, VS Code auto-updates extensions to the latest version. After reverting, you almost certainly want to stop that from happening -- otherwise your next restart could silently undo the downgrade. ### Pin the SPECLAN extension 1. Open **Extensions** (`Ctrl+Shift+X` / `Cmd+Shift+X`) 2. Right-click **SPECLAN** 3. Uncheck **Auto Update** in the context menu This disables auto-update for SPECLAN only. All other extensions continue to update normally. ### Alternative: Disable auto-update globally If you prefer to control all extension updates manually: 1. Open the **Command Palette** (`Ctrl+Shift+P` / `Cmd+Shift+P`) 2. Run **Disable Auto Update for All Extensions** Or set it in your VS Code settings: ```json { "extensions.autoUpdate": false } ``` You can re-enable auto-update at any time by reversing these steps. --- ## Step 4: Report the Problem Reverting gets you unblocked, but it does not fix the underlying issue. Reporting the problem helps us fix it for everyone -- including you, so you can safely return to the latest version. ### What to include in your report - **The version that caused the problem** (the one you reverted from) - **The version you reverted to** (the one that works) - **What went wrong** -- describe the behavior you experienced, ideally with steps to reproduce - **What you expected** -- describe how it worked in the version you reverted to ### Where to report - **r/speclan on Reddit**: [reddit.com/r/speclan](https://www.reddit.com/r/speclan/) -- the primary channel for community bug reports. Include your version, OS, steps to reproduce, and expected vs. actual behavior. - **Email**: If you prefer not to use Reddit, reach out via the contact information on [speclan.net](https://speclan.net) The more detail you provide, the faster the fix. --- ## Things to Keep in Mind ### Compatibility with your specifications SPECLAN specification files are plain Markdown with YAML frontmatter. Older extension versions can generally read specifications created by newer versions without issues. However, if a newer version introduced a new frontmatter field or entity type, an older version may ignore those additions. Your specification files themselves are never modified by a version change. They remain exactly as they are in your project directory. ### Compatibility with VS Code Older extension versions may not support the very latest VS Code release if it introduced breaking API changes. If you experience issues after reverting, try checking the extension's changelog for minimum VS Code version requirements. ### Missing fixes and features While running an older version, you will not benefit from bug fixes, security patches, or new features released after that version. This is the trade-off. Revert to get unblocked now, but plan to return to the latest version once the problem is resolved. --- ## Returning to the Latest Version When the issue that caused you to revert has been fixed in a new release: 1. Open **Extensions** (`Ctrl+Shift+X` / `Cmd+Shift+X`) 2. Right-click **SPECLAN** 3. Re-enable **Auto Update** (if you disabled it) 4. Click **Update** to install the latest version, or simply restart VS Code You are back on the latest version with the fix included. --- ## Quick Reference | Task | How | |------|-----| | Revert via UI | Right-click extension > **Install Another Version...** | | Revert via CLI | `code --install-extension DigitalDividend.speclan-vscode-extension@x.y.z --force` | | Revert via VSIX | Command Palette > **Extensions: Install from VSIX...** | | Pin version (prevent auto-update) | Right-click extension > uncheck **Auto Update** | | Check installed version | `code --list-extensions --show-versions \| grep speclan` | | Return to latest | Right-click extension > **Update** | --- ### Windows: Long Path and Filename Too Long Errors When Cloning SPECLAN Source: https://speclan.net/help/troubleshooting/windows-long-paths/ If you're on Windows and Git is refusing to clone, check out, pull, or switch branches in a SPECLAN repository, the most likely cause is the platform's default 260-character path limit. This page walks you through what you're seeing, why it happens, and the one-line fix. ## Symptoms You're running one of these Git operations: - `git clone ` - `git checkout ` or `git switch ` - `git pull` - `git checkout -- ` (restoring a file) …and Git stops with an error that mentions any of the following: - `Filename too long` - `unable to create file …: Filename too long` - `error: invalid path '…'` - `Clone succeeded, but checkout failed` - Files appear missing from your working tree after a clone or pull, even though the clone command itself seemed to finish - Files that were present a moment ago disappear after you switch branches These errors point at specific file paths inside `speclan/features/…` whose total length looks unusually long. ## Why this happens SPECLAN uses deliberately long, descriptive filenames so that you — and the AI coding agents working alongside you — can identify what's in a spec **without opening the file**. For example: ``` speclan/features/F-7897-assistants/F-6752-new-spec-assistant/requirements/R-5088-unsaved-draft-warning-on-tab-close/R-5088-unsaved-draft-warning-on-tab-close.md ``` That single path is already 173 characters relative to the repo root. Combined with the absolute path on your machine (e.g. `C:\Users\YourName\Projects\…\`), it can easily exceed Windows' default 260-character maximum. When a Windows process — including the Git binary — tries to create, read, or delete a file whose path is longer than that limit, the operating system rejects it with `ERROR_FILENAME_EXCED_RANGE` (a.k.a. "Filename too long"). Git surfaces that as the clone/checkout failure you see in the terminal. This is a **Windows-only** issue. macOS and Linux do not enforce a comparable global path-length limit, which is why your colleagues on those platforms aren't seeing the same errors. ## The fix Run this command **once** in any terminal: ```bash git config --global core.longpaths true ``` Then retry the failing operation (clone, checkout, pull, switch). It should now complete successfully. That's the whole fix. No reboot, no environment-variable changes, no admin privileges required. ## What the command does (and doesn't) **It does:** - Tells Git to use the Windows long-path API when it talks to the filesystem, lifting the 260-character ceiling. - Applies globally to every Git repository on your user account from this point forward — not just SPECLAN. - Persists across terminal sessions, reboots, and Git upgrades. You only ever need to run it once per machine and user account. **It does not:** - Change anything about other repositories you already have. They continue to work exactly as before; the setting just removes a limit that wasn't being hit. - Affect Git running on macOS, Linux, WSL, or any other platform — those don't have the limit in the first place. - Require enabling Windows long-paths at the operating-system level. The Git setting alone is sufficient for Git operations. (Some other tools may still have their own limits — see "Other tools" below.) - Modify your shell, your editor, or your operating system in any way. It writes a single key into your global `.gitconfig` file. ## Verifying the setting To confirm the value is set, run: ```bash git config --global --get core.longpaths ``` You should see: ``` true ``` If nothing prints, the command from the fix step didn't take effect — re-run it and make sure you're using the exact form `--global` (not `--local`, which would only apply inside the current repo). ## If the error persists If you still see "Filename too long" after applying the fix, work through these checks in order: 1. **Confirm the setting is `true`** with `git config --global --get core.longpaths` (see above). If it shows blank or `false`, re-run the fix command. 2. **Make sure you ran the command for the same user account.** `--global` writes to `%USERPROFILE%\.gitconfig`. If you ran it inside an admin command prompt while normally working as a non-admin (or vice versa), the setting may not be picked up by the Git invocation that's failing. 3. **Restart your terminal or IDE.** Some integrated terminals (and some Git GUI clients) cache the config they read at startup. Closing and reopening the terminal — or the IDE itself — picks up the new value. 4. **Clean up a half-cloned repository.** If a previous clone failed partway through, Git may have left a directory in a state where retrying picks up corrupt internal files instead of starting fresh. Delete the partial directory entirely and re-run `git clone …`. 5. **Check your antivirus / file-protection software.** Some real-time protection tools quarantine files whose paths look unusual and surface the rejection as a Git error. Try temporarily disabling on-access scanning for your repository directory and re-run the failing command. 6. **Confirm your Git version supports long paths.** `core.longpaths` was added in Git for Windows 2.x; any release from the last several years has it. Check with `git --version` and update from [git-scm.com/download/win](https://git-scm.com/download/win) if you're on an older release. If none of these resolve it, the error is likely something other than path length — copy the full error message and ask in your team's usual channel. ## Other tools Git is the most common entry point for this issue, but Windows' path limit can affect any tool that talks to the filesystem without using the long-path API: - **File Explorer** sometimes refuses to copy, move, or delete files whose paths are too long. Use the command line (`del`, `rmdir /s`) or a tool like 7-Zip as a workaround. - **Archive utilities** (built-in ZIP, some older third-party tools) may fail to extract archives containing long paths. Modern utilities like 7-Zip handle them correctly. - **Editors and IDEs** vary. Most modern editors (VS Code, JetBrains IDEs) handle long paths transparently; some older Windows-specific tools do not. SPECLAN itself is not affected by this limit when it's running — the limit is enforced by the filesystem at the path-creation moment, which is exactly when Git fails. Once the files exist on disk (after a successful clone or checkout) reading and editing them through SPECLAN works normally. ## Why SPECLAN doesn't simply shorten its filenames The long, descriptive filenames are load-bearing for the way both human users and AI coding agents navigate the spec set: - You can identify a spec from the filesystem without opening it. - Search tools (ripgrep, fd, your editor's quick-open) work against the filename itself, not just the file contents. - AI agents working with the codebase use filenames as natural-language anchors — `R-5088-unsaved-draft-warning-on-tab-close` is far more useful than `R-5088.md`. Shortening the names — for example to just the ID — would remove the discoverability benefit for every user on every platform to work around a default setting that takes one command to change. The remediation here is the smaller cost. ## TL;DR Run this once: ```bash git config --global core.longpaths true ``` Then retry whatever Git operation failed. --- ## Optional - [Community Discussions](https://github.com/thlandgraf/speclan-essentials/discussions/1): Ask questions, share your experience, and connect with other SPECLAN users. Whether you are just getting started or pushing the boundaries — the community is here to help. - [Issue Tracker](https://www.reddit.com/r/speclan/): Found something broken? Post a bug report on the r/speclan subreddit. Include your version, OS, steps to reproduce, and what you expected to happen. - [Contact](https://speclan.net/contact/): Support and general inquiry contact information