Lousy Agents

Turn "lousy" AI outputs into production-grade code.

TL;DR

A CLI tool that scaffolds projects with the structure AI coding assistants need to be effective. Run npx @lousy-agents/cli init to create a new project with testing, linting, and GitHub Copilot configuration. Run npx @lousy-agents/cli copilot-setup in existing projects to generate a workflow that gives Copilot your environment context. Run npx @lousy-agents/cli lint to validate skills, agents, and instruction files.

---

Lousy Agents is a CLI scaffolding tool that sets up your projects with the structure, instructions, and feedback loops that AI coding assistants need to be effective. One command gives you a production-ready development environment with testing, linting, and AI assistant configuration.

Quick Start

# Scaffold a new webapp project (no install required)
npx @lousy-agents/cli init --kind webapp

# Or use interactive mode to choose your project type
npx @lousy-agents/cli init

# Generate GitHub Copilot setup workflow from your project configuration
npx @lousy-agents/cli copilot-setup

Table of Contents

• Who This Is For
• Why This Exists
• Features
• Installation
• Usage
• Roadmap
• Documentation
• Reference Examples

Who This Is For

• Software Engineers: Frustrated by inconsistent AI output and looking for proven patterns to improve results.
• Curious Beginners: Interested in AI-assisted coding but unsure how to set things up for success.
• Team Leads: Exploring how to standardize AI tooling across a team or project.
• Platform Engineers: Need to automate project scaffolding in scripts or CI/CD pipelines.

No prior experience with coding agents is required—just curiosity and a willingness to experiment.

Why This Exists

AI coding assistants work best when given clear constraints. Without structure, they guess—and often guess wrong. Lousy Agents provides the scaffolding they need to succeed:

• Instructions & Specs: Templates that clearly communicate your intent, so agents produce code that matches your vision.
• Feedback Loops: Pre-configured testing (Vitest) and linting (Biome) that let agents catch and fix their own mistakes immediately.
• Copilot Configuration: Settings and workflows that ground AI assistants in your specific engineering standards.

Features

CLI Commands

• init - Scaffold new projects with testing, linting, and Copilot configuration
• new - Create new resources like custom GitHub Copilot agents
• lint - Validate skills, agents, and instruction files
• copilot-setup - Generate GitHub Actions workflows for Copilot environment setup

MCP Server

• MCP Server - Model Context Protocol server for AI assistant integration

Spec-Driven Development

A methodology where you write clear specifications first, giving agents precise requirements to implement—rather than vague prompts. Each scaffolded project includes instruction files for writing specs and tests.

Non-Interactive Mode

Use the --kind flag to skip prompts and integrate into scripts or automation:

npx @lousy-agents/cli init --kind webapp  # No prompts, perfect for CI/CD

Installation

No installation required! Use npx to run directly:

npx @lousy-agents/cli init

For frequent use, install globally:

npm install -g @lousy-agents/cli

Usage

For detailed documentation on each command, see:

• init command - Scaffold new projects
• new command - Create new resources
• lint command - Validate skills, agents, and instruction files
• copilot-setup command - Generate Copilot workflows
• MCP Server - AI assistant integration

Quick Examples

Create a new webapp:

npx @lousy-agents/cli init --kind webapp

Create a custom Copilot agent:

npx @lousy-agents/cli new --copilot-agent security

Generate Copilot setup workflow:

npx @lousy-agents/cli copilot-setup

Lint skills, agents, and instructions:

npx @lousy-agents/cli lint

Roadmap

Feature	Status
Scaffolding for webapps	✅ Complete
Scaffolding for REST APIs	✅ Complete
Scaffolding for CLI	✅ Complete
Scaffolding for GraphQL APIs	Not Started
Copilot setup package manager install steps	✅ Complete
Copilot agent and skill scaffolding	✅ Complete
Agent skill frontmatter linting	✅ Complete
Agent and instruction quality linting	✅ Complete
MCP server package	✅ Complete
Claude Code web environment setup	✅ Complete

Documentation

• init Command - Project scaffolding
• new Command - Create new resources
• lint Command - Skills, agents, and instruction quality validation
• copilot-setup Command - Workflow generation
• MCP Server - AI assistant integration

Reference Examples

The repository includes fully working reference implementations demonstrating these patterns in action:

• ui/copilot-with-react - Next.js + TypeScript webapp with pre-configured testing (Vitest), linting (Biome), GitHub Copilot instructions, and Dev Container configuration.
• api/copilot-with-fastify - Fastify + TypeScript REST API with Kysely, PostgreSQL, Testcontainers integration testing, and Dev Container configuration.
• cli/copilot-with-citty - Citty + TypeScript CLI with pre-configured testing (Vitest), linting (Biome), GitHub Copilot instructions, and Dev Container configuration.

Launch a GitHub Codespace to instantly spin up any of these environments and experiment with spec-driven development.