Lousy Agents

https://github.com/zpratt/lousy-agents
Admin
Bootstrap projects with pre-configured instructions, tests, and linters that guide AI coding agents...
Tokens:15,127
Snippets:156
Trust Score:8.9
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Mise Project Setup Example

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/copilot-setup.md

This example demonstrates the copilot-setup command for a project using `mise` with a `mise.toml` configuration file. The command will detect `mise.toml` and configure the workflow to use `jdx/mise-action`.

```bash
# Project has mise.toml
npx @lousy-agents/cli copilot-setup
# Creates workflow with jdx/mise-action
```

--------------------------------

### Node.js Project Setup Example

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/copilot-setup.md

This example shows how to use the copilot-setup command for a Node.js project that has a `.nvmrc` file. The command will detect this file and configure the workflow to use `actions/setup-node`.

```bash
# Project has .nvmrc
npx @lousy-agents/cli copilot-setup
# Creates workflow with actions/setup-node
```

--------------------------------

### Project Setup and Build (Bash)

Source: https://github.com/zpratt/lousy-agents/blob/main/README.md

Commands for setting up the development environment and building the project. It includes installing dependencies and running a CI build process.

```bash
npm install
 mise run ci && npm run build
```

--------------------------------

### Updating Existing Workflow Example

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/copilot-setup.md

This example illustrates how the copilot-setup command updates an existing workflow file. If a `.python-version` file is added to a project that already has a `copilot-setup-steps.yml`, the command will add the necessary `actions/setup-python` step.

```bash
# Already has copilot-setup-steps.yml
# Add .python-version file
npx @lousy-agents/cli copilot-setup
# Adds actions/setup-python to existing workflow
```

--------------------------------

### Generate Copilot Setup Workflow (Bash)

Source: https://github.com/zpratt/lousy-agents/blob/main/README.md

Generates the necessary setup workflow for GitHub Copilot integration using the `copilot-setup` command of the @lousy-agents/cli package.

```bash
npx @lousy-agents/cli copilot-setup
```

--------------------------------

### GitHub Action Example: Build and Lint from Source

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/lint.md

This example shows how to use the Lousy Agents GitHub Action directly from the source code within the same repository. It includes steps to install dependencies, build the action, and then use it locally, providing the GitHub token.

```yaml
- name: Build action
  run: |
    npm ci
    npm run build --workspace=packages/action

- name: Lint with lousy-agents
  uses: ./
  with:
    github_token: ${{ github.token }}
```

--------------------------------

### GitHub Action Quick Start for Lousy Agents

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/lint.md

Provides a quick start configuration for using the Lousy Agents GitHub Action. This example sets up a job to lint the repository using the action, requiring a GitHub token for API access. It assumes Node.js is available on the runner.

```yaml
jobs:
  lint:
    runs-on: ubuntu-latest
    if: github.event.pull_request.head.repo.fork == false
    permissions:
      contents: read
      checks: write

    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Lint with lousy-agents
        uses: zpratt/lousy-agents@v3
        with:
          github_token: ${{ github.token }}
```

--------------------------------

### Mise Session Start Hook

Source: https://github.com/zpratt/lousy-agents/blob/main/CLAUDE.md

This command automatically runs when a Claude Code session starts, ensuring all necessary runtimes defined in mise.toml are installed.

```bash
mise install
```

--------------------------------

### Create New Webapp Project (Bash)

Source: https://github.com/zpratt/lousy-agents/blob/main/README.md

A quick example demonstrating how to create a new web application project using the `init` command of the @lousy-agents/cli package.

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

--------------------------------

### Install and Configure Agent Shell

Source: https://github.com/zpratt/lousy-agents/blob/main/packages/agent-shell/README.md

This snippet demonstrates how to install agent-shell globally, configure npm to use it as the script shell, and add the event storage directory to .gitignore. It also includes a command to verify the installation.

```bash
# Install globally
npm install -g @lousy-agents/agent-shell

# Configure npm to use agent-shell as the script shell
echo 'script-shell=agent-shell' >> .npmrc

# Add event storage to .gitignore
echo '.agent-shell/' >> .gitignore

# Verify it's working
agent-shell --version

# Run any npm script — events are recorded automatically
npm test
```

--------------------------------

### NPM Dependency Installation

Source: https://github.com/zpratt/lousy-agents/blob/main/CLAUDE.md

This command installs Node.js dependencies based on the package-lock.json file. It runs automatically when a Claude Code session starts.

```bash
npm ci
```

--------------------------------

### Install Agent Shell Globally (Bash)

Source: https://github.com/zpratt/lousy-agents/blob/main/README.md

Installs the @lousy-agents/agent-shell package globally. This is a required step as npm needs the shim on the PATH before the installation process runs.

```bash
npm install -g @lousy-agents/agent-shell
```

--------------------------------

### Install Exact Dependency Version

Source: https://github.com/zpratt/lousy-agents/blob/main/CLAUDE.md

This command demonstrates how to install a specific version of an npm package, adhering to the project's policy of pinning all dependencies to exact versions.

```bash
npm install <package>@<exact-version>
```

--------------------------------

### CI Integration Examples for Lousy Agents Lint

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/lint.md

Demonstrates how to integrate the `npx @lousy-agents/cli lint` command into CI pipelines. It shows examples for linting all targets, specific targets like skills or agents, and using reviewdog for machine-readable output.

```yaml
# Lint everything
- name: Lint all targets
  run: npx @lousy-agents/cli lint

# Lint specific targets
- name: Lint agent skills
  run: npx @lousy-agents/cli lint --skills

- name: Lint custom agents
  run: npx @lousy-agents/cli lint --agents

# Machine-readable output for reviewdog
- name: Lint with reviewdog
  run: npx @lousy-agents/cli lint --format rdjsonl | reviewdog -f=rdjsonl
```

--------------------------------

### Initialize Project with Lousy Agents CLI (Bash)

Source: https://github.com/zpratt/lousy-agents/blob/main/README.md

Initializes a new project using the @lousy-agents/cli package. This command can be run directly using npx without prior installation.

```bash
npx @lousy-agents/cli init
```

--------------------------------

### Setting up Copilot PR Review Ruleset with GitHub Token

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/copilot-setup.md

This example shows how to set up the Copilot PR review ruleset by providing a GitHub token via an environment variable. The command will then check for existing rulesets and prompt the user to create one if necessary.

```bash
# Set up with GitHub token
export GH_TOKEN=ghp_your_token_here
npx @lousy-agents/cli copilot-setup

# When prompted:
# No Copilot PR review ruleset found. Would you like to create one? (y/n)

# Answering 'y' creates the ruleset and the command reports:
# ✓ Created Copilot PR review ruleset: "Copilot Code Review"
```

--------------------------------

### Run Copilot Setup CLI command

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/copilot-setup.md

Executes the copilot-setup command via npx to initialize the agent configuration. This command requires the @lousy-agents/cli package to be available in the environment.

```bash
npx @lousy-agents/cli copilot-setup --help
```

--------------------------------

### Create Copilot Setup Workflow with Version Resolution

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/mcp-server.md

Initiates the creation or update of a Copilot Setup Steps workflow. It uses 'RESOLVE_VERSION' placeholders for actions and returns metadata to resolve them to their latest SHA versions for enhanced security.

```json
{
  "success": true,
  "action": "created",
  "workflowPath": ".github/workflows/copilot-setup-steps.yml",
  "workflowTemplate": "...",
  "actionsToResolve": [
    {
      "action": "actions/setup-node",
      "currentPlaceholder": "RESOLVE_VERSION",
      "lookupUrl": "https://github.com/actions/setup-node/releases/latest"
    }
  ],
  "instructions": "To resolve action versions: ..."
}
```

--------------------------------

### Generated GitHub Actions Workflow

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/copilot-setup.md

A YAML configuration file generated for Node.js projects. It automates the setup process using GitHub Actions, including checkout and Node.js environment configuration based on an .nvmrc file.

```yaml
---
name: Copilot Setup Steps
on:
  workflow_dispatch: {}
  push:
    branches:
      - main
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    branches:
      - main
    paths:
      - .github/workflows/copilot-setup-steps.yml
jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Setup node
        uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc
```

--------------------------------

### Install Lousy Agents CLI Globally (Bash)

Source: https://github.com/zpratt/lousy-agents/blob/main/README.md

Installs the @lousy-agents/cli package globally on your system using npm. This allows for frequent use of the CLI commands without needing npx each time.

```bash
npm install -g @lousy-agents/cli
```

--------------------------------

### Create Custom Copilot Agent (Bash)

Source: https://github.com/zpratt/lousy-agents/blob/main/README.md

Example of creating a custom Copilot agent named 'security' using the `new` command of the @lousy-agents/cli package.

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

--------------------------------

### GitHub Action Example: Lint Agents with PR Review Comments

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/lint.md

An example demonstrating how to configure the Lousy Agents GitHub Action to specifically lint agent files and provide feedback as PR review comments. It sets the `agents` input to 'true' and the `reporter` to 'github-pr-review'.

```yaml
- name: Lint agents
  uses: zpratt/lousy-agents@v3
  with:
    github_token: ${{ github.token }}
    agents: 'true'
    reporter: 'github-pr-review'
```

--------------------------------

### Claude Code Web Environment Setup Response

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/mcp-server.md

The response format for the create_claude_code_web_setup tool. It returns generated hooks, file paths for configuration, and recommendations for the environment.

```json
{
  "hooks": [
    { "command": "mise install", "description": "Install runtimes from mise.toml" },
    { "command": "npm ci", "description": "Install Node.js dependencies with package-lock.json" }
  ],
  "action": "created",
  "settingsPath": ".claude/settings.json",
  "documentationPath": "CLAUDE.md",
  "recommendations": [
    { "type": "network_access", "description": "Enable internet access in Claude Code environment settings" }
  ]
}
```

--------------------------------

### Troubleshoot and Bypass Instrumentation

Source: https://github.com/zpratt/lousy-agents/blob/main/packages/agent-shell/README.md

Provides commands to install the global package, bypass instrumentation using the passthrough flag, or remove the configuration entirely.

```bash
# Install globally
npm install -g @lousy-agents/agent-shell

# Bypass instrumentation
AGENTSHELL_PASSTHROUGH=1 npm test

# Remove configuration via sed
sed -i '' '/script-shell/d' .npmrc

# Uninstall package
npm uninstall -g @lousy-agents/agent-shell
```

--------------------------------

### Run MCP Server with npx

Source: https://github.com/zpratt/lousy-agents/blob/main/packages/mcp/README.md

This command allows you to run the published MCP server without a permanent installation. It uses npx to execute the package directly.

```bash
npx -y -p @lousy-agents/mcp lousy-agents-mcp
```

--------------------------------

### Query Agent Shell Events

Source: https://github.com/zpratt/lousy-agents/blob/main/packages/agent-shell/README.md

This snippet shows various ways to query execution events recorded by agent-shell using the `log` subcommand. It includes examples for filtering by time, failures, actor, script name, and output format.

```bash
# Show events from the most recent session
agent-shell log

# Show events from the last 2 hours
agent-shell log --last 2h

# Show only failures
agent-shell log --failures

# Filter by actor
agent-shell log --actor claude-code

# Filter by script name
agent-shell log --script test

# Combine filters
agent-shell log --actor claude-code --failures --last 2h

# Output as JSON (for scripting)
agent-shell log --json

# List all sessions
agent-shell log --list-sessions
```

--------------------------------

### Beads Task Reading

Source: https://github.com/zpratt/lousy-agents/blob/main/CLAUDE.md

Command to retrieve the context and details of a specific task identified by its ID in the Beads system. This should be done before starting work on a task.

```bash
bd show <id>
```

--------------------------------

### Create Agent Skill using Lousy Agents CLI

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/new.md

This command generates a new GitHub Copilot Agent Skill file within a dedicated directory in `.github/skills/`. The skill name is normalized to lowercase with hyphens. The generated file includes YAML frontmatter, instructions on when to use the skill, step-by-step guidance, and examples.

```bash
npx @lousy-agents/cli new skill <name>
```

--------------------------------

### Create Custom Copilot Agent using Lousy Agents CLI

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/new.md

This command generates a new custom GitHub Copilot agent file in the `.github/agents/` directory. The agent name is normalized to lowercase with hyphens. The generated file includes YAML frontmatter, a template for responsibilities, guidelines, and example interactions.

```bash
npx @lousy-agents/cli new --copilot-agent <name>
```

--------------------------------

### Initialize Webapp in Non-Interactive Mode (Bash)

Source: https://github.com/zpratt/lousy-agents/blob/main/README.md

Initializes a new web application project without interactive prompts, suitable for CI/CD pipelines. This command leverages npx to execute the @lousy-agents/cli package.

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

--------------------------------

### Lint Skills, Agents, and Instructions (Bash)

Source: https://github.com/zpratt/lousy-agents/blob/main/README.md

Validates the quality and consistency of skills, agents, and instruction files using the `lint` command of the @lousy-agents/cli package.

```bash
npx @lousy-agents/cli lint
```

--------------------------------

### Core Project Commands (Bash)

Source: https://github.com/zpratt/lousy-agents/blob/main/CLAUDE.md

Essential bash commands for managing the Lousy Agents project, including running tests, linters, formatters, and builds. These commands leverage 'mise' for tool version management and 'npm' for package operations.

```bash
# Core commands
mise run test            # Run tests (vitest)
mise run lint            # Run ALL linting tools in parallel (Biome, actionlint, yamllint, markdownlint, shellcheck, issue-form schemas, Trivy)
mise run format-check    # Biome only — code formatting + static analysis
mise run format-fix      # Auto-fix Biome lint/format issues
npm run build            # Production build

# Workspace-scoped commands
npm run build --workspace=packages/cli     # Build CLI only
npm run build --workspace=packages/mcp     # Build MCP server only
npm test --workspace=packages/cli          # Test a specific package

# File-scoped (faster feedback)
npx biome check path/to/file.ts
npm test path/to/file.test.ts

# Validation suite (run before commits)
mise run ci              # Runs: lint -> test -> smoke-test (smoke-test builds then exercises the CLI)

# Other
npm audit                # Security check
npm install              # Install deps
```

--------------------------------

### Execute Lint Command via CLI

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/lint.md

Demonstrates how to invoke the lint command using npx. Users can run full repository linting or target specific components like skills, agents, or instructions using command-line flags.

```bash
# Basic usage to lint everything
npx @lousy-agents/cli lint

# Lint only skills
npx @lousy-agents/cli lint --skills

# Lint only agents
npx @lousy-agents/cli lint --agents

# Analyze only instruction quality
npx @lousy-agents/cli lint --instructions
```

--------------------------------

### Display Help for Lint Command

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/lint.md

Displays the help message for the `lint` command, providing information on its usage, options, and arguments. This is useful for understanding all available configurations for the linting process.

```bash
npx @lousy-agents/cli lint --help
```

--------------------------------

### Discover SDLC Feedback Loop Scripts and Tools

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/mcp-server.md

Analyzes a repository to discover scripts from package.json and CLI commands from GitHub Actions workflows. It maps these to SDLC phases and categorizes them as mandatory or optional.

```json
{
  "success": true,
  "summary": {
    "totalScripts": 8,
    "totalTools": 6,
    "mandatoryScripts": 4,
    "mandatoryTools": 2,
    "packageManager": "npm"
  },
  "scriptsByPhase": {
    "test": [
      { "name": "test", "command": "vitest run", "mandatory": true },
      { "name": "test:integration", "command": "vitest run --config vitest.integration.config.ts", "mandatory": true }
    ],
    "build": [
      { "name": "build", "command": "rspack build", "mandatory": true }
    ],
    "lint": [
      { "name": "lint", "command": "biome check .", "mandatory": true },
      { "name": "lint:fix", "command": "biome check --write .", "mandatory": true }
    ]
  },
  "toolsByPhase": {
    "test": [
      { "name": "npm test", "command": "npm test", "mandatory": true, "source": "ci.yml" }
    ],
    "lint": [
      { "name": "mise run lint", "command": "mise run lint", "mandatory": true, "source": "ci.yml" }
    ]
  }
}
```

--------------------------------

### Beads Task Listing

Source: https://github.com/zpratt/lousy-agents/blob/main/CLAUDE.md

Command to list all open tasks or query for specific tasks within the Beads system. Useful for discovering available work.

```bash
bd list
```

```bash
bd query
```

--------------------------------

### Verify and Clean Up

Source: https://github.com/zpratt/lousy-agents/blob/main/packages/agent-shell/README.md

Commands to verify the active shim version and remove local telemetry data directories.

```bash
npx agent-shell --version
rm -rf .agent-shell/
```

--------------------------------

### Run Lint Command for Workflows

Source: https://github.com/zpratt/lousy-agents/blob/main/CLAUDE.md

This command must be run after modifying GitHub workflows. It performs linting to ensure workflow files adhere to project standards.

```bash
mise run lint
```

--------------------------------

### Git Ignore Configuration

Source: https://github.com/zpratt/lousy-agents/blob/main/packages/agent-shell/README.md

Recommended entry for .gitignore to prevent committing local telemetry data.

```text
# agent-shell telemetry
.agent-shell/
```

--------------------------------

### Configure MCP Server for VS Code and GitHub Copilot

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/mcp-server.md

Configuration snippets for integrating the Lousy Agents MCP server into VS Code or GitHub Copilot settings.

```json
{
  "servers": {
    "lousy-agents": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "@lousy-agents/mcp", "lousy-agents-mcp"]
    }
  }
}
```

```json
{
  "mcpServers": {
    "lousy-agents": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "@lousy-agents/mcp@1.0.2", "lousy-agents-mcp"],
      "tools": ["*"]
    }
  }
}
```

--------------------------------

### Run Tests Command

Source: https://github.com/zpratt/lousy-agents/blob/main/CLAUDE.md

This command is mandatory after modifying or creating test files. It ensures all tests are executed according to project standards.

```bash
mise run test
```

--------------------------------

### CI Pipeline Execution

Source: https://github.com/zpratt/lousy-agents/blob/main/CLAUDE.md

This command executes the full Continuous Integration pipeline, which includes linting, testing, and smoke tests. It's a prerequisite for marking a task as done.

```bash
mise run ci
```

--------------------------------

### Lousy Agents CLI New Command Help

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/new.md

Displays the help information for the 'new' command in the Lousy Agents CLI, outlining all available subcommands and options for creating new resources.

```bash
npx @lousy-agents/cli new --help
```

--------------------------------

### Test and Lint Execution

Source: https://github.com/zpratt/lousy-agents/blob/main/CLAUDE.md

This command runs both the test suite and the linter. It should be executed after every code change to ensure code quality and test coverage.

```bash
mise run test && mise run lint
```

--------------------------------

### Project Structure Overview (Tree)

Source: https://github.com/zpratt/lousy-agents/blob/main/CLAUDE.md

Illustrates the monorepo structure of Lousy Agents, detailing the organization of packages within the `packages/` directory. It highlights the separation of concerns for core logic, CLI, MCP server, GitHub Action, and agent shell.

```tree
.github/
  # GitHub Actions workflows, Copilot instructions, specs
packages/
  core/              # @lousy-agents/core — shared entities, use cases, gateways
  cli/               # @lousy-agents/cli — CLI entry point and commands
    src/
      entities/
      use-cases/
      gateways/
      commands/
      lib/
      index.ts
    api/
    ui/
  mcp/               # @lousy-agents/mcp — MCP server
    src/
      tools/
      server.ts
  action/            # @lousy-agents/action — GitHub Action
  agent-shell/       # @lousy-agents/agent-shell — npm script flight recorder
```

--------------------------------

### TDD Workflow Steps (Markdown)

Source: https://github.com/zpratt/lousy-agents/blob/main/CLAUDE.md

The required Test-Driven Development (TDD) workflow for all code changes in Lousy Agents. This sequence emphasizes small increments, validation at each step, and comprehensive checks before task completion.

```markdown
1. **Research**: Search codebase for existing patterns. Use Context7 MCP tools for library/API documentation.
2. **Write failing test**: Create test describing desired behavior
3. **Verify failure**: Run `mise run test` — confirm clear failure message
4. **Implement minimal code**: Write just enough to pass
5. **Verify pass**: Run `mise run test` — confirm pass
6. **Refactor**: Clean up, remove duplication
7. **Verify refactor**: Run `mise run test && mise run lint` — confirm tests still green and all linting passes
8. **Validate**: Run `mise run ci` — runs `mise run lint`, `mise run test`, and `mise run smoke-test` (which builds then exercises the CLI)
```

--------------------------------

### Beads Task Creation

Source: https://github.com/zpratt/lousy-agents/blob/main/CLAUDE.md

Command to create a new issue or task within the Beads task tracking system. This is the required method for initiating new work.

```bash
bd create
```

--------------------------------

### GitHub Action Integration

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/lint.md

Configuration details for the Lousy-Agents GitHub Action used for automated PR feedback.

```APIDOC
## GitHub Action: zpratt/lousy-agents

### Description
A composite GitHub Action that runs lint checks and reports results back to the PR using reviewdog.

### Parameters
#### Inputs
- **github_token** (string) - Required - GitHub token for reviewdog API access.
- **skills** (boolean) - Optional - Lint skill frontmatter in .github/skills/.
- **agents** (boolean) - Optional - Lint agent frontmatter in .github/agents/.
- **reporter** (string) - Optional - reviewdog reporter (github-pr-check, github-pr-review, github-check).
- **filter_mode** (string) - Optional - reviewdog filter mode (added, diff_context, file, nofilter).
- **level** (string) - Optional - Minimum severity level (info, warning, error).

### Request Example
- uses: zpratt/lousy-agents@v3
  with:
    github_token: ${{ github.token }}
    reporter: 'github-pr-review'
    agents: 'true'
```

--------------------------------

### SHA-Pinned GitHub Actions in Workflow

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/mcp-server.md

Illustrates the final output of a GitHub Actions workflow after version resolution. Actions are pinned to specific commit SHAs for security and stability, with version tags included as comments for maintainability.

```yaml
steps:
  - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332  # v4.2.2
  - uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b  # v4.0.4
```

--------------------------------

### Configure Custom Metadata Tags

Source: https://github.com/zpratt/lousy-agents/blob/main/packages/agent-shell/README.md

Attaches metadata to agent events by setting AGENTSHELL_TAG_* environment variables before executing npm commands.

```bash
AGENTSHELL_TAG_pr=1234 AGENTSHELL_TAG_task=fix-auth npm test
```

--------------------------------

### Configure Lint Rules with lousy-agents.config.ts

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/lint.md

Defines the structure for customizing linting rules and severity levels within a project. The configuration file supports various formats via c12 and allows granular control over agent, instruction, and skill validation.

```typescript
// lousy-agents.config.ts
export default {
  lint: {
    rules: {
      agents: {
        "agent/invalid-name-format": "warn",
        "agent/name-mismatch": "off",
      },
      instructions: {
        "instruction/command-outside-section": "off",
      },
      skills: {
        "skill/missing-allowed-tools": "error",
      },
    },
  },
};
```

--------------------------------

### Validate Instruction Coverage Response Format

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/mcp-server.md

The response format for the validate_instruction_coverage tool. It provides a summary of documented vs mandatory feedback loops and lists missing requirements.

```json
{
  "success": true,
  "hasFullCoverage": false,
  "summary": {
    "totalMandatory": 6,
    "totalDocumented": 4,
    "coveragePercentage": 66.67
  },
  "missing": [
    { "type": "script", "name": "lint:fix", "phase": "lint", "command": "biome check --write ." },
    { "type": "tool", "name": "mise run build", "phase": "build", "command": "mise run build" }
  ],
  "documented": [
    { "type": "script", "name": "test", "phase": "test" },
    { "type": "script", "name": "build", "phase": "build" },
    { "type": "script", "name": "lint", "phase": "lint" },
    { "type": "tool", "name": "npm test", "phase": "test" }
  ]
}
```

--------------------------------

### Configure VS Code MCP Server

Source: https://github.com/zpratt/lousy-agents/blob/main/packages/mcp/README.md

This JSON configuration snippet shows how to add the Lousy Agents MCP server to your VS Code workspace settings. It specifies the server type, command, and arguments required to launch the server.

```json
{
  "servers": {
    "lousy-agents": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "@lousy-agents/mcp", "lousy-agents-mcp"]
    }
  }
}
```

--------------------------------

### Resolve GitHub Action Versions with SHA Pinning

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/mcp-server.md

Provides the resolved SHA versions for GitHub Actions after an initial lookup. This input is used to update the workflow, ensuring actions are pinned to specific, secure commit SHAs.

```json
{
  "targetDir": "/path/to/project",
  "resolvedVersions": [
    {
      "action": "actions/checkout",
      "sha": "692973e3d937129bcbf40652eb9f2f61becf3332",
      "versionTag": "v4.2.2"
    },
    {
      "action": "actions/setup-node",
      "sha": "1e60f620b9541d16bece96c5465dc8ee9832be0b",
      "versionTag": "v4.0.4"
    }
  ]
}
```

--------------------------------

### Agent Shell Environment Variables

Source: https://github.com/zpratt/lousy-agents/blob/main/packages/agent-shell/README.md

This table lists environment variables that can be used to configure agent-shell's behavior. These include options for bypassing instrumentation, overriding actor detection, setting session IDs, and specifying log directories.

```bash
# Bypass all instrumentation
export AGENTSHELL_PASSTHROUGH=1

# Override automatic actor detection
export AGENTSHELL_ACTOR=my-custom-actor

# Set a shared session ID for event correlation
export AGENTSHELL_SESSION_ID=shared-session-123

# Override event file directory
export AGENTSHELL_LOG_DIR=/var/log/agent-shell/

# Attach custom key=value metadata to events
export AGENTSHELL_TAG_PR=1234
export AGENTSHELL_TAG_USER=testuser
```

--------------------------------

### Lint with Reviewdog Diagnostic Format (rdjsonl)

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/lint.md

Executes the lint command using the reviewdog diagnostic format (JSON Lines). This format is compatible with reviewdog and outputs each diagnostic as a standalone JSON object on a new line. It's useful for integrating with reviewdog for automated code reviews.

```bash
npx @lousy-agents/cli lint --format rdjsonl
```

```json
{"message":"Name is required","location":{"path":".github/agents/security.md","range":{"start":{"line":2}}},"severity":"ERROR","code":{"value":"agent/missing-name"}}
```

--------------------------------

### Beads Task Completion

Source: https://github.com/zpratt/lousy-agents/blob/main/CLAUDE.md

Command to mark a task as complete in the Beads system. This is the only authorized method for closing tasks.

```bash
bd close <id>
```

--------------------------------

### CLI Lint Command

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/lint.md

The lint command analyzes agent files and returns diagnostic data in various machine-readable formats.

```APIDOC
## CLI Lint Command

### Description
Executes the linting process for agents, skills, and instructions. Returns a non-zero exit code if errors are detected, making it ideal for CI pipelines.

### Method
CLI Execution

### Endpoint
npx @lousy-agents/cli lint

### Parameters
#### Query Parameters
- **--format** (string) - Optional - Output format: 'json' (array of LintDiagnostic) or 'rdjsonl' (JSON Lines for reviewdog).
- **--skills** (boolean) - Optional - Lint skill frontmatter.
- **--agents** (boolean) - Optional - Lint agent frontmatter.

### Response
#### Success Response (Exit Code 0)
- **stdout** (json/rdjsonl) - Diagnostic objects containing filePath, line, severity, message, and ruleId.

### Response Example
[
  {
    "filePath": ".github/agents/security.md",
    "line": 2,
    "severity": "error",
    "message": "Name is required",
    "ruleId": "agent/missing-name"
  }
]
```

--------------------------------

### Lint with JSON Output

Source: https://github.com/zpratt/lousy-agents/blob/main/docs/lint.md

Executes the lint command with JSON output format. This is suitable for programmatic consumption and interpretation by LLMs. It outputs a structured array of LintDiagnostic objects.

```bash
npx @lousy-agents/cli lint --format json
```

```json
[
  {
    "filePath": ".github/agents/security.md",
    "line": 2,
    "severity": "error",
    "message": "Name is required",
    "ruleId": "agent/missing-name",
    "field": "name",
    "target": "agent"
  }
]
```

--------------------------------

### Correlate Sessions Across Workflows

Source: https://github.com/zpratt/lousy-agents/blob/main/packages/agent-shell/README.md

Groups multiple script invocations under a single session ID by exporting an AGENTSHELL_SESSION_ID variable.

```bash
export AGENTSHELL_SESSION_ID=$(uuidgen)
npm run lint && npm test && npm run build
```

--------------------------------

### Agent Shell Telemetry Schema

Source: https://github.com/zpratt/lousy-agents/blob/main/packages/agent-shell/README.md

This JSON object represents the structure of a single telemetry event recorded by agent-shell for a script execution. It includes details like session ID, script name, command, exit code, duration, and environment variables.

```json
{
  "v": 1,
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "script_end",
  "script": "test",
  "command": "vitest run",
  "package": "my-app",
  "package_version": "1.2.0",
  "actor": "claude-code",
  "exit_code": 1,
  "signal": null,
  "duration_ms": 3420,
  "timestamp": "2026-03-08T14:32:01.000Z",
  "env": {
    "NODE_ENV": "test",
    "CI": "true"
  },
  "tags": {
    "pr": "1234"
  }
}
```
Tokens:
Raw