Early PreviewJoin us on the road to v1.0 — help shape the future of specification engineering.Get Involved →
SPECLAN mascotSPECLAN

Getting Started: Existing Project

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 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.

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:

## 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:

# 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 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