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

Getting Started: New Project

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.

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

git init
git add -A && git commit -m "initial commit"

Open the project in VS Code

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:

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

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

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

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

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 to modify approved specs, and keep drafting new ones as you discover what else needs to be built.

Next Steps