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

Workflow Modes

Commands

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

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.