AI-SDLC

Markdown-driven software development lifecycle powered by AI agents

uv pip install ai-sdlc

What is AI-SDLC?

AI-SDLC is a CLI tool that guides software development through an 8-step structured workflow. It generates markdown files and AI prompts that help you go from an initial idea to production-ready code with comprehensive tests.

The tool is AI-agnostic—it generates prompts you can use with any AI assistant (Claude, ChatGPT, Cursor, etc.). No API keys or specific AI tools required.

The Problem

Developers often jump straight to coding, skipping important planning steps. This leads to:

• Unclear requirements discovered mid-implementation
• Architecture decisions made ad-hoc
• Missing test coverage
• Poor documentation of decisions

The Solution

AI-SDLC enforces a structured workflow:

1. Document decisions and rationale in version-controlled markdown
2. Generate comprehensive implementation plans before coding
3. Create thorough test strategies
4. Maintain project history

Quick Start

1. Install

# Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install AI-SDLC
uv pip install ai-sdlc

2. Initialize

mkdir my-project && cd my-project
aisdlc init

3. Start a Feature

aisdlc new "Add user authentication system"
aisdlc status

4. Work Through the Steps

1. Fill out the generated markdown in doing/add-user-authentication-system/0.idea-*.md
2. Run aisdlc next to generate a prompt for the next step
3. Use the prompt with your AI tool and save the response
4. Repeat until all 8 steps complete
5. Archive with aisdlc done

The 8-Step Workflow

0.idea → 1.prd → 2.prd-plus → 3.system-template → 4.systems-patterns → 5.tasks → 6.tasks-plus → 7.tests

Step	Name	Purpose
01	idea	Initial problem statement and strategic pitch
02	prd	Product requirements document
03	prd-plus	Enhanced requirements with edge cases
04	architecture	System architecture design
05	system-patterns	Design patterns and implementation strategy
06	tasks	Task breakdown and implementation plan
07	tasks-plus	Task review and handoff preparation
08	tests	Test plan and test code generation

Workflow Modes

Mode	Steps	Description
Chat Mode	1-5	Iterate with AI chat to refine ideas, requirements, and architecture
Manual Mode	6	Fill out task list markdown directly
Agent Mode	7-8	Automated processing for task review and test generation

Commands

Command	Description
aisdlc init	Initialize AI-SDLC in current directory
aisdlc new <idea>	Start new feature with idea description
aisdlc next	Generate prompt for next step
aisdlc status	Show current project status
aisdlc done	Archive completed feature to done/
aisdlc --help	Show all available commands
aisdlc <command> --help	Show help for a specific command

How It Works

When you run aisdlc next:

1. Reads the previous step's markdown file
2. Merges content into the prompt template for the next step
3. Writes the merged prompt to _prompt-<step>.md
4. You copy the prompt to your AI tool, get a response, and save it

All state is tracked in files:

• .aisdlc - Project configuration (TOML)
• .aisdlc.lock - Current workflow state (JSON)
• doing/<slug>/ - Active feature files
• done/<slug>/ - Completed features

Project Structure

.
├── ai_sdlc/                # Main Python package
│   ├── cli.py              # Entry point for aisdlc command
│   ├── commands/           # Command implementations (init, new, next, status, done)
│   ├── scaffold_template/  # Default templates for new projects
│   └── utils.py            # Shared helpers
├── prompts/                # LLM prompt templates for each step
├── tests/                  # Test suite
│   ├── unit/               # Unit tests
│   └── integration/        # Integration tests
├── doing/                  # Active features (created by init)
├── done/                   # Completed features (created by init)
├── .aisdlc                 # Project configuration
└── .aisdlc.lock            # Current workflow state

Installation

Prerequisites

• Python 3.11+
• uv (recommended) or pip

Install Options

# Using uv (recommended)
uv pip install ai-sdlc

# Using pip
pip install ai-sdlc

# Verify installation
aisdlc --help

Development Setup

git clone https://github.com/ParkerRex/ai-sdlc.git
cd ai-sdlc
uv venv && source .venv/bin/activate
uv sync --all-features

Running Tests

uv pip install -e .[dev]

# Lint and format
uv run ruff check ai_sdlc tests
uv run ruff format ai_sdlc tests

# Type check
uv run pyright

# Run tests
uv run pytest
uv run pytest tests/unit/        # Unit tests only
uv run pytest tests/integration/ # Integration tests only

Technology Stack

Component	Technology
CLI	Python 3.11+, argparse (stdlib)
Package manager	uv
Dev tools	Ruff, Pyright, pytest
Build	setuptools, PEP 621

Runtime has zero external dependencies—uses only Python standard library.

Troubleshooting

"Permission denied" errors

• Check file permissions in your project directory

"Invalid .aisdlc configuration"

• Verify .aisdlc has valid TOML syntax
• Run aisdlc init to regenerate defaults

"Lock file corruption"

• Delete .aisdlc.lock and run aisdlc status

Contributing

1. Fork and clone the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Make changes with tests
4. Run quality checks: ruff check, pyright, pytest
5. Open a PR

Roadmap

• Pluggable AI providers (--model flag for GPT-4, Claude, Gemini)
• 09-release-plan step for CI/CD and deployment
• Context-window management for large projects
• Template customization per project
• Parallel workflows for multiple features

License

MIT - See LICENSE for details.