{"id":42708836,"url":"https://github.com/zpratt/lousy-agents","last_synced_at":"2026-04-25T20:03:11.899Z","repository":{"id":331702377,"uuid":"1126348578","full_name":"zpratt/lousy-agents","owner":"zpratt","description":"Bootstrap projects with pre-configured instructions, tests, and linters that guide AI coding agents to produce reliable code","archived":false,"fork":false,"pushed_at":"2026-04-25T04:49:30.000Z","size":7612,"stargazers_count":10,"open_issues_count":20,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-25T06:25:13.979Z","etag":null,"topics":["agent-policy","ai-agents","cli","coding-agent","lint","mcp","mcp-server","npm-package","scaffolding","typescript"],"latest_commit_sha":null,"homepage":"https://docs.modzed.io/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause-patent","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zpratt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-01T18:03:49.000Z","updated_at":"2026-04-25T00:50:51.000Z","dependencies_parsed_at":"2026-03-08T17:07:35.312Z","dependency_job_id":"83aa5451-1ba2-4719-9218-c1a46d82957b","html_url":"https://github.com/zpratt/lousy-agents","commit_stats":null,"previous_names":["zpratt/lousy-agents"],"tags_count":94,"template":false,"template_full_name":null,"purl":"pkg:github/zpratt/lousy-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zpratt%2Flousy-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zpratt%2Flousy-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zpratt%2Flousy-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zpratt%2Flousy-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zpratt","download_url":"https://codeload.github.com/zpratt/lousy-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zpratt%2Flousy-agents/sbom","scorecard":{"id":1245011,"data":{"date":"2026-03-18T20:56:22Z","repo":{"name":"github.com/zpratt/lousy-agents","commit":"8bbba1e1abbb1d5b4c751e41bf8096a41f41a3e7"},"scorecard":{"version":"v5.3.0","commit":"c22063e786c11f9dd714d777a687ff7c4599b600"},"score":6.9,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/18 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#code-review"}},{"name":"Dependency-Update-Tool","score":10,"reason":"update tool detected","details":["Info: detected update tool: RenovateBot: renovate.json:1"],"documentation":{"short":"Determines if the project uses a dependency update tool.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#dependency-update-tool"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#security-policy"}},{"name":"Maintained","score":0,"reason":"project was created within the last 90 days. Please review its contents carefully","details":["Warn: Repository was created within the last 90 days."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":10,"reason":"GitHub workflow tokens follow principle of least privilege","details":["Info: jobLevel 'contents' permission set to 'read': .github/workflows/ci.yml:24","Warn: jobLevel 'checks' permission set to 'write': .github/workflows/ci.yml:25","Info: jobLevel 'contents' permission set to 'read': .github/workflows/ci.yml:61","Info: jobLevel 'contents' permission set to 'read': .github/workflows/ci.yml:224","Info: jobLevel 'contents' permission set to 'read': .github/workflows/ci.yml:355","Info: jobLevel 'contents' permission set to 'read': .github/workflows/copilot-setup-steps.yml:25","Info: found token with 'none' permissions: .github/workflows/ci.yml:1","Info: found token with 'none' permissions: .github/workflows/copilot-setup-steps.yml:1","Info: topLevel 'contents' permission set to 'read': .github/workflows/release.yml:13","Info: topLevel permissions set to 'read-all': .github/workflows/scorecard.yml:9"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":8,"reason":"dependency not pinned by hash detected -- score normalized to 8","details":["Warn: npmCommand not pinned by hash: .github/workflows/ci.yml:122","Warn: npmCommand not pinned by hash: .github/workflows/ci.yml:138","Info:  15 out of  15 GitHub-owned GitHubAction dependencies pinned","Info:   6 out of   6 third-party GitHubAction dependencies pinned","Info:   5 out of   7 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#cii-best-practices"}},{"name":"SAST","score":10,"reason":"SAST tool is run on all commits","details":["Info: all commits (30) are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#sast"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#license"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#vulnerabilities"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/release.yml:16"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#packaging"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":3,"reason":"branch protection is not maximal on development and all release branches","details":["Info: 'allow deletion' disabled on branch 'main'","Info: 'force pushes' disabled on branch 'main'","Info: 'branch protection settings apply to administrators' is required to merge on branch 'main'","Warn: 'stale review dismissal' is disabled on branch 'main'","Warn: branch 'main' does not require approvers","Warn: codeowners review is not required on branch 'main'","Warn: 'last push approval' is disabled on branch 'main'","Warn: 'up-to-date branches' is disabled on branch 'main'","Info: status check found to merge onto on branch 'main'","Info: PRs are required in order to make changes on branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#branch-protection"}},{"name":"Contributors","score":3,"reason":"project has 1 contributing companies or organizations -- score normalized to 3","details":["Info: found contributions from: anthropics"],"documentation":{"short":"Determines if the project has a set of contributors from multiple organizations (e.g., companies).","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#contributors"}},{"name":"CI-Tests","score":10,"reason":"19 out of 19 merged PRs checked by a CI test -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project runs tests before pull requests are merged.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#ci-tests"}}]},"last_synced_at":"2026-03-19T00:26:17.405Z","repository_id":331702377,"created_at":"2026-03-19T00:26:17.417Z","updated_at":"2026-03-19T00:26:17.417Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32274987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-policy","ai-agents","cli","coding-agent","lint","mcp","mcp-server","npm-package","scaffolding","typescript"],"created_at":"2026-01-29T15:03:25.720Z","updated_at":"2026-04-25T20:03:11.870Z","avatar_url":"https://github.com/zpratt.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lousy Agents\n\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/zpratt/lousy-agents/badge)](https://scorecard.dev/viewer/?uri=github.com/zpratt/lousy-agents)\n\n**Turn \"lousy\" AI outputs into production-grade code.**\n\n![Demo](media/demo.gif)\n\n## TL;DR\n\nLousy Agents is a set of published npm packages for agentic software development, with `@lousy-agents/cli` as the main entry point. 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. Add `@lousy-agents/mcp` for MCP integrations and `@lousy-agents/agent-shell` for npm script telemetry when you need them.\n\n---\n\nLousy Agents is an npm workspace monorepo that publishes focused packages for scaffolding, MCP integrations, and npm script telemetry. The CLI package gives you a production-ready development environment with testing, linting, and AI assistant configuration in one command.\n\n## Quick Start\n\n```bash\n# Scaffold a new webapp project (no install required)\nnpx @lousy-agents/cli init --kind webapp\n\n# Or use interactive mode to choose your project type\nnpx @lousy-agents/cli init\n\n# Generate GitHub Copilot setup workflow from your project configuration\nnpx @lousy-agents/cli copilot-setup\n```\n\n## Table of Contents\n\n- [Start Here](#start-here)\n- [Who This Is For](#who-this-is-for)\n- [Why This Exists](#why-this-exists)\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Contributing](#contributing)\n- [Roadmap](#roadmap)\n- [Documentation](#documentation)\n- [Reference Examples](#reference-examples)\n\n## Start Here\n\nIf you're adopting Lousy Agents for the first time, use this order:\n\n1. **Scaffold a project** with `npx @lousy-agents/cli init`\n2. **Add repository-specific setup** with `npx @lousy-agents/cli copilot-setup`\n3. **Add deeper integrations only if you need them**:\n   - `@lousy-agents/mcp` for MCP clients like VS Code and hosted Copilot\n   - `@lousy-agents/agent-shell` for npm script telemetry\n\nLousy Agents is an npm workspace monorepo. Most users only need one published package at a time:\n\n| Package | Install / Run | Use it when |\n| --------- | ---------------- | ------------- |\n| `@lousy-agents/cli` | `npx @lousy-agents/cli init` | You want the scaffolding CLI for new or existing projects |\n| `@lousy-agents/mcp` | `npx -y -p @lousy-agents/mcp lousy-agents-mcp` | You want Lousy Agents tools available through an MCP client |\n| `@lousy-agents/agent-shell` | `npm install -g @lousy-agents/agent-shell` | You want an audit trail for npm script execution |\n\n## Who This Is For\n\n- **Software Engineers**: Frustrated by inconsistent AI output and looking for proven patterns to improve results.\n- **Curious Beginners**: Interested in AI-assisted coding but unsure how to set things up for success.\n- **Team Leads**: Exploring how to standardize AI tooling across a team or project.\n- **Platform Engineers**: Need to automate project scaffolding in scripts or CI/CD pipelines.\n\nNo prior experience with coding agents is required—just curiosity and a willingness to experiment.\n\n## Why This Exists\n\nAI 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:\n\n- **Instructions \u0026 Specs**: Templates that clearly communicate your intent, so agents produce code that matches your vision.\n- **Feedback Loops**: Pre-configured testing ([Vitest](https://vitest.dev/)) and linting ([Biome](https://biomejs.dev/)) that let agents catch and fix their own mistakes immediately.\n- **Copilot Configuration**: Settings and workflows that ground AI assistants in your specific engineering standards.\n\n## Features\n\n### CLI Commands\n\n- **[`init`](docs/init.md)** - Scaffold new projects with testing, linting, and Copilot configuration\n- **[`new`](docs/new.md)** - Create new resources like custom GitHub Copilot agents\n- **[`lint`](docs/lint.md)** - Validate skills, agents, hook configurations, and instruction files\n- **[`copilot-setup`](docs/copilot-setup.md)** - Generate GitHub Actions workflows for Copilot environment setup\n\n### MCP Server\n\n- **[MCP Server](docs/mcp-server.md)** - Model Context Protocol server for AI assistant integration\n\n### Companion Tools\n\n- **[agent-shell](packages/agent-shell/README.md)** - A flight recorder for npm script execution with policy-based command blocking. Records independent telemetry of what scripts ran, who initiated them, and whether they succeeded. Run `agent-shell policy --init` to scan your project and generate a ready-to-use policy and hook configuration — with optional AI-powered analysis via the Copilot SDK and `@lousy-agents/mcp`.\n\n![agent-shell demo](media/agent-shell.gif)\n\n### Spec-Driven Development\n\nA 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.\n\n### Non-Interactive Mode\n\nUse the `--kind` flag to skip prompts and integrate into scripts or automation:\n\n```bash\nnpx @lousy-agents/cli init --kind webapp  # No prompts, perfect for CI/CD\n```\n\n## Installation\n\nMost users do not need to clone this repository. Start with the published package that matches your use case.\n\n### `@lousy-agents/cli`\n\nNo installation required! Use npx to run directly:\n\n```bash\nnpx @lousy-agents/cli init\n```\n\nFor frequent use, install globally:\n\n```bash\nnpm install -g @lousy-agents/cli\n```\n\n### `@lousy-agents/mcp`\n\nRun the MCP server without installing it permanently:\n\n```bash\nnpx -y -p @lousy-agents/mcp lousy-agents-mcp\n```\n\n### `@lousy-agents/agent-shell`\n\nInstall agent-shell globally (required — npm needs the shim on `PATH` before `npm install` runs):\n\n```bash\nnpm install -g @lousy-agents/agent-shell\n```\n\n## Usage\n\nFor detailed documentation on each command, see:\n\n- **[`init` command](docs/init.md)** - Scaffold new projects\n- **[`new` command](docs/new.md)** - Create new resources\n- **[`lint` command](docs/lint.md)** - Validate skills, agents, hook configurations, and instruction files\n- **[`copilot-setup` command](docs/copilot-setup.md)** - Generate Copilot workflows\n- **[MCP Server](docs/mcp-server.md)** - AI assistant integration\n\n### Quick Examples\n\n**Create a new webapp:**\n\n```bash\nnpx @lousy-agents/cli init --kind webapp\n```\n\n**Create a custom Copilot agent:**\n\n```bash\nnpx @lousy-agents/cli new --copilot-agent security\n```\n\n**Generate Copilot setup workflow:**\n\n```bash\nnpx @lousy-agents/cli copilot-setup\n```\n\n**Lint skills, agents, hooks, and instructions:**\n\n```bash\nnpx @lousy-agents/cli lint\n```\n\n## Contributing\n\nThis repository is an npm workspace monorepo with packages for the CLI, MCP server, core logic, GitHub Action integration, and agent-shell.\n\n```bash\nnpm install\nmise run ci \u0026\u0026 npm run build\n```\n\nUse the root install to work on all workspace packages together. The root `npm run build` command builds the publishable packages: `packages/cli`, `packages/mcp`, and `packages/agent-shell`.\n\n## Roadmap\n\n| Feature | Status |\n| --------- | -------- |\n| Scaffolding for webapps | ✅ Complete |\n| Scaffolding for REST APIs | ✅ Complete |\n| Scaffolding for CLI | ✅ Complete |\n| Scaffolding for GraphQL APIs | Not Started |\n| Copilot setup package manager install steps | ✅ Complete |\n| Copilot agent and skill scaffolding | ✅ Complete |\n| Agent skill frontmatter linting | ✅ Complete |\n| Agent and instruction quality linting | ✅ Complete |\n| Hook configuration linting | ✅ Complete |\n| Policy-based command blocking (agent-shell) | ✅ Complete |\n| AI-powered policy initialization (agent-shell) | ✅ Complete |\n| MCP server package | ✅ Complete |\n| Claude Code web environment setup | ✅ Complete |\n\n## Documentation\n\n- **[Start with `init`](docs/init.md)** - Scaffold a project with the CLI\n- **[Then `copilot-setup`](docs/copilot-setup.md)** - Generate workflow setup for existing repositories\n- **[`new` Command](docs/new.md)** - Create new resources after your scaffold is in place\n- **[`lint` Command](docs/lint.md)** - Validate skills, agents, hook configurations, and instruction files\n- **[MCP Server](docs/mcp-server.md)** - Configure the separately published `@lousy-agents/mcp` package\n- **[agent-shell](packages/agent-shell/README.md)** - Add npm script execution telemetry\n\n## Reference Examples\n\nThe repository includes fully working reference implementations in the CLI workspace:\n\n- **[packages/cli/ui/copilot-with-react](packages/cli/ui/copilot-with-react)** - Next.js + TypeScript webapp with pre-configured testing (Vitest), linting (Biome), GitHub Copilot instructions, and Dev Container configuration.\n- **[packages/cli/api/copilot-with-fastify](packages/cli/api/copilot-with-fastify)** - Fastify + TypeScript REST API with Kysely, PostgreSQL, Testcontainers integration testing, and Dev Container configuration.\n- **[packages/cli/cli/copilot-with-citty](packages/cli/cli/copilot-with-citty)** - Citty + TypeScript CLI with pre-configured testing (Vitest), linting (Biome), GitHub Copilot instructions, and Dev Container configuration.\n\nLaunch a GitHub Codespace to instantly spin up any of these environments and experiment with spec-driven development.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzpratt%2Flousy-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzpratt%2Flousy-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzpratt%2Flousy-agents/lists"}