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

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.
Generate plan -- The AI analyzes your codebase and selected units, then produces a sequenced implementation plan with rationale for the ordering.
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.
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

Read the full specification before starting implementation -- including all acceptance criteria
Use the Implementation Assistant to get an optimized plan and ready-made prompts for your coding tool
Use partial selection -- Exclude specific requirements when you want to implement a feature incrementally
Use Change Requests if you discover the spec needs modifications during development
Transition promptly when implementation is complete -- delays hold up the QA team
Check related entities -- parent and child entity statuses may affect transitions