@lousy-agents/cli 2.2.0 → 2.3.0

package/cli/copilot-with-citty/.github/instructions/spec.instructions.md

@@ -0,0 +1,127 @@
+---
+applyTo: "**/spec.md"
+---
+
+# Spec Development Instructions
+
+You are a product management partner helping define features for <product> targeting <customers>.
+
+> Placeholder variables:
+> - `<product>` is the name of the product or system for which this spec is being written.
+> - `<customers>` describes the primary customer or user segments targeted by the spec.
+> These placeholders may be automatically populated by your tooling; if not, replace them manually with the appropriate values before using this document.
+## Your Role
+
+Act as a collaborative PM pair, not a passive assistant. This means:
+
+- **Challenge assumptions** — Ask "why" before writing. Probe for the underlying problem.
+- **Identify gaps** — Flag missing acceptance criteria, edge cases, and error states.
+- **Guard scope** — Call out when a feature is too large for a single increment. Suggest phasing.
+- **Propose value** — Don't wait to be asked. Assess and state which value types a feature delivers.
+- **Ensure persona coverage** — Every spec must identify impacted personas. Push back if missing.
+
+## Collaboration Approach
+
+Before writing or modifying a spec:
+
+1. Confirm you understand the problem being solved, not just the solution requested
+2. Ask clarifying questions if the request is ambiguous
+3. Identify which personas are affected and how
+4. Propose a value assessment
+5. Suggest scope boundaries if the feature feels too broad
+
+When reviewing a spec:
+
+1. Verify all acceptance criteria use EARS notation
+2. Check that personas are explicitly named with impact described
+3. Confirm design aligns with engineering guidance
+4. Identify any missing error states or edge cases
+5. Assess whether tasks are appropriately sized for the coding agent
+
+## EARS Requirement Syntax
+
+All acceptance criteria must use EARS (Easy Approach to Requirements Syntax) patterns:
+
+| Pattern | Template | Use When |
+|---------|----------|----------|
+| Ubiquitous | The `<system>` shall `<response>` | Always true, no trigger |
+| Event-driven | When `<trigger>`, the `<system>` shall `<response>` | Responding to an event |
+| State-driven | While `<state>`, the `<system>` shall `<response>` | Active during a condition |
+| Optional | Where `<feature>` is enabled, the `<system>` shall `<response>` | Configurable capability |
+| Unwanted | If `<condition>`, then the `<system>` shall `<response>` | Error handling, edge cases |
+| Complex | While `<state>`, when `<trigger>`, the `<system>` shall `<response>` | Combining conditions |
+
+### EARS Examples
+
+```markdown
+- The CLI shall validate all input arguments before execution.
+- When a user runs `init`, the system shall display a project type selection prompt.
+- While verbose mode is enabled, the system shall log detailed debug information.
+- Where custom configuration is provided, the system shall use it instead of defaults.
+- If the configuration file is invalid, then the system shall display a validation error with details.
+- While strict mode is enabled, when an unknown argument is provided, the system shall reject the command.
+```
+
+## User Story Format
+
+```markdown
+### Story: <Concise Title>
+
+As a **<persona>**,
+I want **<capability>**,
+so that I can **<outcome/problem solved>**.
+
+#### Acceptance Criteria
+
+- When <trigger>, the <system> shall <response>
+- While <state>, the <system> shall <response>
+- If <error condition>, then the <system> shall <response>
+
+#### Notes
+
+<Context, constraints, or open questions>
+```
+
+## Spec File Structure
+
+A spec has three sections that flow into each other:
+
+1. **Requirements** — What we're building and why (human and agent context)
+2. **Design** — How it fits into the system (agent context for implementation)
+3. **Tasks** — Discrete units of work (directly assignable to coding agent)
+
+## Task Design Guidelines
+
+### Size
+
+- Completable in one agent session (~1-3 files, ~200-300 lines changed)
+- If a task feels too large, split it
+- If you have more than 7-10 tasks, split the feature into phases
+
+### Clarity
+
+- **Objective** — One sentence, action-oriented
+- **Context** — Explains why; agents make better decisions with intent
+- **Affected files** — Tells the agent where to focus
+- **Requirements** — Links back to specific acceptance criteria
+
+### Verification
+
+Every task must include verification steps the agent can run:
+
+```markdown
+**Verification**:
+- [ ] `npm test` passes
+- [ ] `npm run lint` passes
+- [ ] New command returns expected output for valid input
+- [ ] New command returns error message for invalid input
+```
+
+## Diagram Requirements
+
+All diagrams in specs must use **Mermaid** syntax for consistency and GitHub rendering support.
+
+## Related Files
+
+- `.github/ISSUE_TEMPLATE/feature-to-spec.yml` — Issue template for creating specs
+- `.github/workflows/assign-copilot.yml` — Workflow for auto-assigning Copilot

package/cli/copilot-with-citty/.github/instructions/test.instructions.md

@@ -0,0 +1,157 @@
+---
+applyTo: "src/**/*.{test,spec}.ts"
+---
+
+# Testing Conventions for CLI
+
+## MANDATORY: After Test Changes
+
+Run `npm test` after modifying or creating tests to verify all tests pass.
+
+## Test File Structure
+
+Use this structure for all test files:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+
+describe('ComponentName', () => {
+  describe('when [condition]', () => {
+    it('should [expected behavior]', () => {
+      // Arrange
+      const input = 'test-value';
+
+      // Act
+      const result = functionUnderTest(input);
+
+      // Assert
+      expect(result).toBe('expected-value');
+    });
+  });
+});
+```
+
+## Test Data
+
+- Use Chance.js to generate random test data when actual input values are not important.
+- Generate Chance.js data that produces readable assertion failure messages.
+- Use simple strings or numbers - avoid overly complex Chance.js configurations.
+
+## Test Design Rules
+
+1. Follow the Arrange-Act-Assert (AAA) pattern for ALL tests.
+2. Use spec-style tests with `describe` and `it` blocks.
+3. Write test descriptions as user stories: "should [do something] when [condition]".
+4. Focus on behavior, NOT implementation details.
+5. Extract fixture values to variables - NEVER hardcode values in both setup and assertions.
+6. Use `msw` to mock external HTTP APIs - do NOT mock fetch directly.
+7. Avoid mocking third-party dependencies when possible.
+8. Tests MUST be isolated - no shared state between tests.
+9. Tests MUST be deterministic - same result every run.
+10. Tests MUST run identically locally and in CI.
+11. NEVER use partial mocks.
+12. Test ALL conditional paths with meaningful assertions.
+13. Test unhappy paths and edge cases, not just happy paths.
+14. Every assertion should explain the expected behavior.
+15. Write tests that would FAIL if production code regressed.
+16. **NEVER export functions, methods, or variables from production code solely for testing purposes.**
+17. **NEVER use module-level mutable state for dependency injection in production code.**
+
+## Dependency Injection for Testing
+
+When you need to inject dependencies for testing:
+
+- **DO** use constructor parameters, function parameters, or factory functions.
+- **DO** pass test doubles through the existing public API of the code under test.
+- **DO NOT** export special test-only functions like `_setTestDependencies()` or `_resetTestDependencies()`.
+- **DO NOT** modify module-level state from tests.
+
+### Good Example (Dependency Injection via Factory Function)
+
+```typescript
+// Production code - use-cases/process-input.ts
+export interface InputReader {
+  read(source: string): Promise<string>;
+}
+
+export function createInputProcessor(reader: InputReader) {
+  return {
+    async execute(source: string) {
+      const content = await reader.read(source);
+      if (!content.trim()) {
+        throw new Error('Empty input');
+      }
+      return content;
+    }
+  };
+}
+
+// Test code
+it("should process valid input", async () => {
+  const mockReader = {
+    read: vi.fn().mockResolvedValue("valid content")
+  };
+  const processor = createInputProcessor(mockReader);
+
+  const result = await processor.execute("source.txt");
+
+  expect(result).toBe("valid content");
+  expect(mockReader.read).toHaveBeenCalledWith("source.txt");
+});
+```
+
+### Bad Example (Test-Only Exports)
+
+```typescript
+// ❌ BAD: Production code
+let _readerOverride: any;
+
+export function _setTestDependencies(deps: any) {
+  _readerOverride = deps.reader;
+}
+
+export function processInput(source: string) {
+  const reader = _readerOverride || defaultReader;
+  return reader.read(source);
+}
+
+// ❌ BAD: Test code
+import { _setTestDependencies, processInput } from "./process-input";
+
+beforeEach(() => {
+  _setTestDependencies({ reader: mockReader });
+});
+```
+
+## CLI Command Testing
+
+Test citty commands by providing mock context:
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { myCommand } from './my-command';
+
+describe('My Command', () => {
+  describe('given valid arguments', () => {
+    it('should execute the expected action', async () => {
+      // Arrange
+      const mockPrompt = vi.fn().mockResolvedValue('user-input');
+
+      // Act
+      await myCommand.run({
+        rawArgs: ['--name', 'test'],
+        args: { _: [], name: 'test' },
+        cmd: myCommand,
+        data: { prompt: mockPrompt },
+      });
+
+      // Assert
+      expect(mockPrompt).not.toHaveBeenCalled();
+    });
+  });
+});
+```
+
+## Dependencies
+
+Install new test dependencies using: `npm install <package>@<exact-version>`

package/cli/copilot-with-citty/.github/specs/README.md

@@ -0,0 +1,84 @@
+# Specifications Directory
+
+This directory contains feature specifications created through the spec-driven development workflow.
+
+## Workflow Overview
+
+1. **Create a Spec Issue** — Use the "Copilot Feature To Spec" issue template to define your feature
+2. **Auto-Assignment** — Issues with the `copilot-ready` label automatically trigger Copilot assignment
+3. **Spec Creation** — Copilot creates a structured specification in this directory
+4. **Implementation** — Follow the tasks in the spec to implement the feature
+
+## Spec File Structure
+
+Each spec follows this structure:
+
+```markdown
+# Feature: <name>
+
+## Problem Statement
+<2-3 sentences describing the problem>
+
+## Personas
+| Persona | Impact | Notes |
+|---------|--------|-------|
+
+## Value Assessment
+- **Primary value**: <type> — <explanation>
+
+## User Stories
+
+### Story 1: <Title>
+As a **<persona>**,
+I want **<capability>**,
+so that I can **<outcome>**.
+
+#### Acceptance Criteria
+- When <trigger>, the <system> shall <response>
+
+---
+
+## Design
+
+### Components Affected
+### Dependencies
+### Open Questions
+
+---
+
+## Tasks
+
+### Task 1: <Title>
+**Objective**: ...
+**Verification**: ...
+```
+
+## EARS Syntax for Acceptance Criteria
+
+Use EARS (Easy Approach to Requirements Syntax) patterns:
+
+| Pattern | Template | Use When |
+|---------|----------|----------|
+| Ubiquitous | The `<system>` shall `<response>` | Always true |
+| Event-driven | When `<trigger>`, the `<system>` shall `<response>` | Responding to event |
+| State-driven | While `<state>`, the `<system>` shall `<response>` | During a condition |
+| Optional | Where `<feature>` is enabled, the `<system>` shall `<response>` | Configurable capability |
+| Unwanted | If `<condition>`, then the `<system>` shall `<response>` | Error handling |
+| Complex | While `<state>`, when `<trigger>`, the `<system>` shall `<response>` | Combining conditions |
+
+### Examples
+
+```markdown
+- The CLI shall validate all input arguments
+- When a user runs a command, the system shall display the result
+- While verbose mode is enabled, the system shall log debug information
+- Where custom configuration is provided, the system shall use it instead of defaults
+- If the input is malformed, then the system shall return a descriptive error
+- While strict mode is enabled, when an unknown argument is provided, the system shall reject the command
+```
+
+## Related Files
+
+- `.github/ISSUE_TEMPLATE/feature-to-spec.yml` — Issue template for creating specs
+- `.github/workflows/assign-copilot.yml` — Workflow for auto-assigning Copilot
+- `.github/instructions/spec.instructions.md` — Detailed instructions for spec writing

package/cli/copilot-with-citty/.github/workflows/assign-copilot.yml

@@ -0,0 +1,59 @@
+---
+name: Auto-Assign Copilot on Spec Issues
+
+on:
+  issues:
+    types: [opened, edited]
+
+permissions:
+  issues: write
+
+jobs:
+  assign-agent:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Assign and Instruct Copilot
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea  # v7.0.1
+        with:
+          script: |
+            const issue = context.payload.issue;
+
+            // Check if issue has the copilot-ready label
+            const hasCopilotLabel = issue.labels.some(label => label.name === 'copilot-ready');
+
+            if (!hasCopilotLabel) {
+              console.log("Issue does not have 'copilot-ready' label. Skipping.");
+              return;
+            }
+
+            const body = issue.body || "";
+            const pattern = /### Extra Instructions\s+([\s\S]*?)(?=\n###|$)/;
+            const match = body.match(pattern);
+
+            // Always mention @copilot to trigger assignment and provide context
+            let comment = "@copilot";
+
+            if (match && match[1].trim().length > 0) {
+              let instructions = match[1].trim();
+
+              // Basic sanitization: limit length to prevent overly long comments
+              const MAX_LENGTH = 2000;
+              if (instructions.length > MAX_LENGTH) {
+                instructions = instructions.slice(0, MAX_LENGTH) + "\n\n[Instructions truncated]";
+              }
+
+              comment = `@copilot ${instructions}`;
+              console.log("Found extra instructions, mentioning Copilot with instructions.");
+            } else {
+              comment = "@copilot Please work on this issue according to the specification provided.";
+              console.log("No extra instructions found, mentioning Copilot with default message.");
+            }
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issue.number,
+              body: comment
+            });
+
+            console.log("Successfully mentioned Copilot in issue comment.");

package/cli/copilot-with-citty/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+---
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4.4.0
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npx biome check
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4.4.0
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4.4.0
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build

package/cli/copilot-with-citty/.nvmrc

@@ -0,0 +1 @@
+v24.13.0

package/cli/copilot-with-citty/.vscode/extensions.json

@@ -0,0 +1,13 @@
+{
+    "recommendations": [
+        "biomejs.biome",
+        "editorconfig.editorconfig",
+        "vitest.explorer",
+        "ms-vscode-remote.remote-containers",
+        "GitHub.codespaces",
+        "GitHub.Copilot",
+        "GitHub.Copilot-Chat",
+        "GitHub.github-vscode-theme",
+        "redhat.vscode-yaml"
+    ]
+}

package/cli/copilot-with-citty/.vscode/launch.json

@@ -0,0 +1,25 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Start CLI Locally",
+            "type": "node",
+            "request": "launch",
+            "runtimeExecutable": "npm",
+            "runtimeArgs": ["run", "dev"],
+            "console": "integratedTerminal",
+            "cwd": "${workspaceFolder}"
+        },
+        {
+            "name": "Debug Current Test File",
+            "type": "node",
+            "request": "launch",
+            "autoAttachChildProcesses": true,
+            "skipFiles": ["<node_internals>/**", "**/node_modules/**"],
+            "program": "${workspaceFolder}/node_modules/vitest/vitest.mjs",
+            "args": ["run", "${relativeFile}"],
+            "smartStep": true,
+            "console": "integratedTerminal"
+        }
+    ]
+}

package/cli/copilot-with-citty/.vscode/mcp.json

@@ -0,0 +1,19 @@
+{
+    "servers": {
+        "context7": {
+            "type": "stdio",
+            "command": "npx",
+            "args": ["-y", "@upstash/context7-mcp"]
+        },
+        "sequential-thinking": {
+            "type": "stdio",
+            "command": "npx",
+            "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+        },
+        "lousy-agents": {
+            "type": "stdio",
+            "command": "npx",
+            "args": ["-y", "@lousy-agents/cli", "mcp"]
+        }
+    }
+}

package/cli/copilot-with-citty/.yamllint

@@ -0,0 +1,18 @@
+extends: default
+
+ignore: |
+  node_modules/
+  dist/
+
+rules:
+  indentation:
+    spaces: 2
+    indent-sequences: true
+  line-length:
+    max: 120
+    level: warning
+
+  document-start: disable
+  truthy: disable
+  comments:
+    min-spaces-from-content: 1

package/cli/copilot-with-citty/biome.json

@@ -0,0 +1,31 @@
+{
+    "root": false,
+    "$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
+    "vcs": {
+        "enabled": true,
+        "clientKind": "git",
+        "useIgnoreFile": true
+    },
+    "files": {
+        "ignoreUnknown": false
+    },
+    "formatter": {
+        "enabled": true,
+        "indentStyle": "space",
+        "indentWidth": 4
+    },
+    "linter": {
+        "enabled": true,
+        "rules": {
+            "recommended": true,
+            "style": {
+                "useConsistentCurlyBraces": "error"
+            }
+        }
+    },
+    "javascript": {
+        "formatter": {
+            "quoteStyle": "double"
+        }
+    }
+}

package/cli/copilot-with-citty/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "<%= it.projectName %>",
+    "version": "0.1.0",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "tsx watch src/index.ts",
+        "build": "tsc",
+        "start": "node dist/index.js",
+        "test": "vitest run",
+        "lint": "biome check .",
+        "lint:fix": "biome check --write .",
+        "lint:workflows": "actionlint",
+        "lint:yaml": "yamllint ."
+    },
+    "dependencies": {
+        "citty": "0.2.0",
+        "consola": "3.4.2",
+        "zod": "3.25.56"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.3.8",
+        "@types/node": "22.16.4",
+        "chance": "1.1.12",
+        "tsx": "4.20.3",
+        "typescript": "5.8.3",
+        "vitest": "4.0.15"
+    }
+}

package/cli/copilot-with-citty/tsconfig.json

@@ -0,0 +1,28 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "lib": ["ES2022"],
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "resolveJsonModule": true,
+        "noEmit": false,
+        "isolatedModules": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noFallthroughCasesInSwitch": true,
+        "exactOptionalPropertyTypes": true,
+        "noImplicitReturns": true,
+        "noUncheckedIndexedAccess": true
+    },
+    "include": ["src/**/*.ts"],
+    "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}

package/cli/copilot-with-citty/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: "node",
+        setupFiles: ["./vitest.setup.ts"],
+        include: ["src/**/*.test.ts"],
+        coverage: {
+            provider: "v8",
+            reporter: ["text", "json", "html"],
+            exclude: ["node_modules/", "dist/", "**/*.test.ts"],
+        },
+    },
+});

package/cli/copilot-with-citty/vitest.setup.ts

@@ -0,0 +1,2 @@
+// Vitest setup file for CLI tests
+// Add any global test setup here