# 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/digital-dividend/speclan - 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 generate, refine, and validate specifications on your behalf. Go from a one-liner to a full spec tree in minutes, not days. - **VS Code Integration**: Tree views, WYSIWYG editing, status badges, and contextual actions. Everything lives where you already work — no browser tabs required. - **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. Change requests keep locked specifications safe while still letting you iterate. - **Change Requests**: Need to update an approved spec? Create a formal change request instead of silently editing. Your audit trail stays intact. - **MCP Integration**: Expose your specifications to the AI ecosystem through 42+ Model Context Protocol tools. Any AI assistant that supports MCP can read, create, and manage your specs natively. --- ### Features Source: https://speclan.net/features/ SPECLAN is a VS Code extension for specification engineering. It gives you a layered, Git-native framework for turning ideas into traceable, machine-processable specifications — with AI agents that do the heavy lifting. ### 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. Locked specifications are protected from accidental edits. When you need to change an approved spec, create a change request that preserves the audit trail. --- ### 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. We wanted a system where specifications live in the repo, are structured enough for machines to process, and are human-friendly enough for developers to actually maintain. So we built SPECLAN — a VS Code extension that treats specifications as first-class engineering artifacts, not afterthoughts. It started with a whiteboard sketch and a question: What if your specification was your prompt? We had been building software for years, and 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. Requirements lived in tools that were disconnected from the codebase, unversioned, and invisible to the toolchain. 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**. This locks the content -- 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. Use [Change Requests](/help/workflows/change-requests/) to modify approved specs, and 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 locked specifications --- ### 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 --- ### 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 ``` --- ### 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 content is locked from casual editing - Changes require a formal [Change Request](/help/workflows/change-requests/) process - 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 approved specifications --- ### 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:** - A locked specification that serves as the implementation guide - 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 locked specifications - [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 have progressed beyond the early drafting stages. When a specification is in-development, under-test, or released status, direct editing is not allowed. Instead, you create a Change Request to propose and track the modification through its own approval lifecycle. ## 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 | No | Yes | | in-development | No | Yes | | under-test | No | Yes | | released | No | Yes | **Why not just edit directly?** Locked specifications serve as the authoritative reference for development and testing. Direct edits would undermine traceability, break the audit trail, and risk introducing unreviewed changes into active work. ## 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 locked entities | | 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**: Locked. Implementation can begin. Changes require a Change Request. - **in-development**: Active implementation. - **under-test**: Implementation complete, testing in progress. - **released**: Verified and shipped. - **deprecated**: No longer active. --- ## 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://github.com/thlandgraf/speclan-essentials/issues): Found something broken? Have an idea that would make SPECLAN better? Open an issue on GitHub and help us improve. - [Contact](https://speclan.net/contact/): Support and general inquiry contact information