@lousy-agents/cli 5.14.9 → 5.15.0

package/api/copilot-with-fastify/package.json

@@ -28,16 +28,16 @@
         "zod": "4.4.3"
     },
     "devDependencies": {
-        "@biomejs/biome": "2.4.15",
-        "@lousy-agents/mcp": "5.14.8",
+        "@biomejs/biome": "2.4.16",
+        "@lousy-agents/mcp": "5.14.10",
         "@modelcontextprotocol/server-sequential-thinking": "2025.12.18",
-        "@testcontainers/postgresql": "11.14.0",
+        "@testcontainers/postgresql": "12.0.1",
         "@types/node": "24.12.4",
-        "@upstash/context7-mcp": "2.2.5",
+        "@upstash/context7-mcp": "3.1.0",
         "chance": "1.1.13",
-        "testcontainers": "11.14.0",
-        "tsx": "4.22.1",
+        "testcontainers": "12.0.1",
+        "tsx": "4.22.4",
         "typescript": "6.0.3",
-        "vitest": "4.1.6"
+        "vitest": "4.1.8"
     }
 }

package/cli/copilot-with-citty/.agents/skills/feature-to-plan/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: feature-to-plan
+description: Use when the user asks to turn a feature request, idea, PRD draft, or backlog issue into a structured EARS-format spec. Trigger phrases include "draft a spec", "plan a feature", "scaffold a spec", "write a feature spec", "convert this issue to a spec", "plan this issue", or invocation via /feature-to-plan. Do NOT use for reviewing an existing spec PR (use triaging-pr-reviews) or for editing a specific section of an already-drafted spec (use a direct Edit instead).
+argument-hint: "GitHub issue number (e.g., #47), a feature name, or empty for interactive drafting"
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Feature to Plan
+
+## Overview
+
+Convert a feature request — either freeform or seeded from a GitHub issue — into an EARS-format spec under the repo's specs directory (default `.github/specs/`).
+
+```
+Phase 1: Orient   (read-only planning — read context, identify ambiguities, draft outline)
+        ↓
+   Approval Gate  (present the planned spec outline and wait for approval)
+        ↓
+Phase 2: Create   (write the spec file, optionally post clarifying comments)
+        ↓
+Phase 3: Validate (diff → classify findings → fix loop, ≤3 rounds)
+```
+
+Two on-demand references back this skill:
+
+- [`references/spec-format.md`](./references/spec-format.md) — EARS patterns, persona template, value assessment, the full Spec File Structure, task design guidelines, and Mermaid diagram requirements. **Load when drafting Phase 2 output.**
+- [`references/interactive-flow.md`](./references/interactive-flow.md) — a six-step collaborative conversation flow (greet → context → criteria → clarify → outline → write). **Load when the user wants multi-turn drafting or Phase 1 surfaces more than ~3 substantive ambiguities.**
+
+## When to Use
+
+- User asks to "draft / plan / scaffold / write" a spec for a feature
+- User references a GitHub issue and wants it turned into a spec
+- User invokes `/feature-to-plan` (with or without an argument)
+- User wants to convert a freeform idea into a structured spec
+
+**Do NOT use when:**
+
+- The task is reviewing an existing spec PR — use `triaging-pr-reviews` instead
+- The user wants to edit a specific section of an existing spec — make the targeted Edit directly
+- The user is asking implementation questions about an already-written spec — answer from the spec content; don't re-draft
+
+## Prerequisites
+
+- Read access to the current repository
+- `gh` CLI authenticated (`gh auth status`) **only if** seeding from a GitHub issue or posting clarifying comments
+- Whatever lint/format/test commands the repo defines (used in Phase 3's final check)
+
+## Procedure
+
+> **Note on the invocation argument.** Below, "the argument" refers to whatever string was passed to this skill — for example, the value of `$ARGUMENTS` when invoked via a slash command, the argument supplied through your agent's skill-invocation surface, or the inline argument in a user prompt like "use feature-to-plan on #47". The skill behavior keys off three cases: an issue reference (`#N` or `^\d+$`), a freeform feature name, or empty.
+
+### Phase 1 — Orient (READ-ONLY PLANNING)
+
+Work in a read-only planning phase first. If the runtime provides a dedicated plan mode, use it; otherwise avoid file writes until the Approval Gate is complete.
+
+1. **Discover product and engineering context.** Read whatever conventional files the repo provides — for example `AGENTS.md`, `README.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `CONTRIBUTING.md`, anything under `.github/instructions/`, or product docs under `docs/`. Don't assume any specific file exists; use what's there.
+2. **Seed Context & Goal.** Based on the argument:
+   - **Issue reference (`#N` or matches `^\d+$`):** fetch the issue and treat its Context & Goal and Acceptance Criteria sections (if present) as the starting point. Note any cross-reference IDs (e.g., a beads ID) in the issue footer.
+
+     ```bash
+     gh issue view <N> --json title,body,labels,comments
+     ```
+
+   - **Freeform feature name or empty:** the user must provide Context & Goal. Ask once, concisely.
+3. **Choose drafting mode.** Decide between single-shot and interactive based on these signals:
+   - **Switch to interactive** if (a) the user explicitly asked for a multi-turn walkthrough ("walk me through", "let's draft this together"), or (b) Context & Goal is too thin to outline without back-and-forth, or (c) you anticipate more than ~3 substantive ambiguities.
+   - **Otherwise proceed single-shot** through steps 4-5 below.
+
+   To run interactive mode: **load [`references/interactive-flow.md`](./references/interactive-flow.md)** and follow its six-step flow until the outline is ready for the gate. The interactive flow owns the conversation; this skill resumes at the Approval Gate once the outline is approved. **Skip steps 4-5 below in this mode.**
+4. **List ambiguities** (single-shot mode). For each one, decide:
+   - Resolvable with a reasonable assumption → record the assumption in the draft's "Open Questions" section
+   - Requires user input → add to a clarifying-questions list to surface at the gate
+5. **Draft the spec outline** (single-shot mode) for approval. Include:
+   - Exact target file path (default `.github/specs/<kebab-case-feature>.spec.md`; honor any override the user requested)
+   - Section list (Problem Statement, Personas, Value Assessment, User Stories, Design, Tasks, Out of Scope, Future Considerations)
+   - One-line persona summary and value-type summary
+   - Estimated task count
+   - Clarifying-question text to optionally post on the source issue
+
+### Approval Gate
+
+Present the outline through the agent's approval mechanism. In runtimes with `ExitPlanMode`, call it; otherwise ask for explicit approval in the conversation. Present:
+
+- The target file path
+- The section list (headers only)
+- The persona/value summary
+- The task count
+- Any clarifying-question text, with an explicit yes/no prompt: "Should I also post these as a comment on issue #N?"
+
+Wait for user approval before continuing.
+
+### Phase 2 — Create (POST-APPROVAL)
+
+1. **Load the spec format reference.** Read [`references/spec-format.md`](./references/spec-format.md) for the authoritative template, EARS patterns, persona table, value assessment block, task structure, and diagram requirements.
+2. **Resolve the output path.** Default `.github/specs/<kebab-case-feature>.spec.md`. If the repo uses a different convention (e.g., `docs/specs/`, `specs/`), honor it.
+3. **Write the spec** using the Spec File Structure template. The following section *identities* are required — keep the same set of sections in this order. Cosmetic title variation is allowed only when the target repo has an established convention (e.g., `## Stakeholders` instead of `## Personas`, or `## Acceptance` instead of `## Acceptance Criteria`). If you customize a title, keep the role of the section identical to what's described below; never drop a section.
+   - `# Feature: <name>`
+   - `## Problem Statement` (2-3 sentences — problem, not solution)
+   - `## Personas` (table with Impact column)
+   - `## Value Assessment` (Primary / Secondary value types)
+   - `## User Stories` (each with EARS acceptance criteria)
+   - `## Design` (Components Affected, Dependencies, Data Model Changes, Diagrams, Open Questions)
+   - `## Tasks` (each with Objective, Context, Affected files, Requirements, Verification, Done when)
+   - `## Out of Scope`
+   - `## Future Considerations`
+4. **Include Mermaid diagrams.** At minimum a data-flow diagram (`flowchart TB` or `flowchart LR`) and a sequence diagram (`sequenceDiagram`). Use state, ER, or class diagrams when the feature warrants them.
+5. **Mark every checkbox `[ ]` (not `[x]`).** Tasks, Verification, and Done-when lists are unchecked at draft time. Only the implementer marks them `[x]` as they ship.
+6. **Add a Cross-Reference footer if seeded from an issue:**
+
+   ```markdown
+   ---
+
+   ## Cross-Reference
+
+   - GitHub Issue: #<N>
+   - <Any tracker ID or external link surfaced in Phase 1>
+   ```
+
+7. **Optionally post clarifying questions on the source issue** (only if the user opted in at the gate):
+
+   ```bash
+   gh issue comment <N> --body "Clarifying questions before drafting the spec: ..."
+   ```
+
+### Phase 3 — Validate
+
+1. **Generate the diff:**
+
+   ```bash
+   git diff -- <path/to/new-spec>
+   ```
+
+2. **Classify each finding.** Apply the classification rubric inline:
+   - **Security** — Does the spec leak credentials, prescribe unsafe defaults, or invite injection patterns?
+   - **Correctness** — Are EARS criteria testable? Do tasks have measurable verification?
+   - **Performance** — Does the design imply hot paths, N+1 patterns, or unbounded loops?
+   - **Style** — Headings, link formats, file conventions consistent with the repo
+   - **Architecture** — Does the design contradict existing engineering guidance you read in Phase 1?
+3. **Re-Edit the spec** to resolve each finding. Keep this lightweight — don't rewrite working content.
+4. **Iterate up to 3 rounds.** Exit when no high/medium severity findings remain or after the third round, whichever comes first.
+5. **Run the repo's own validation gate** before reporting completion. Use whatever the repo defines — for example `make lint`, `npm run lint`, `bun run format:check && bun run lint`, `cargo fmt --check`, or a CI workflow. Markdown-only changes typically don't affect test/build, but running the gate keeps you honest.
+
+## Delegation Rules
+
+| Situation                                                                                  | Hand off to                                                                              |
+| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| User says "walk me through" / "let's draft this together" / wants multi-turn collaboration | Load [`references/interactive-flow.md`](./references/interactive-flow.md)                |
+| Phase 1 surfaces > 3 substantive ambiguities                                               | Load [`references/interactive-flow.md`](./references/interactive-flow.md)                |
+| Spec already lives in an open PR and the user wants review                                 | `triaging-pr-reviews` skill with the PR number — this skill should not be used at all    |
+
+## Output Contract
+
+- **File path:** `.github/specs/<kebab-case-feature>.spec.md` by default, or the user's specified location
+- **Required sections:** all sections in the Spec File Structure template (see [`references/spec-format.md`](./references/spec-format.md))
+- **EARS:** every acceptance criterion uses one of the six EARS patterns (Ubiquitous, Event-driven, State-driven, Optional, Unwanted, Complex)
+- **Diagrams:** at least one Mermaid data-flow diagram and one sequence diagram
+- **Tasks:** each has Objective, Context, Affected files, Requirements, Verification, Done when — checkboxes start unchecked
+- **Cross-Reference footer:** present if seeded from a GitHub issue
+
+## Gotchas
+
+- **Historical specs use varying extensions** (`*.md`, `*.spec.md`, `*.prd.md`). Match whatever the target repo already uses; don't rename existing files.
+- **Nested planning states behave unexpectedly.** If the runtime uses a dedicated plan mode and the skill is invoked while already planning, calling `ExitPlanMode` may exit the **outer** plan. Make this clear in the gate prompt.
+- **Spec output path is not universal.** Default to `.github/specs/` but respect any existing convention you find (e.g., `docs/specs/`, `specs/`, `rfcs/`).

package/cli/copilot-with-citty/.agents/skills/feature-to-plan/references/interactive-flow.md

@@ -0,0 +1,122 @@
+# Interactive Drafting Flow
+
+> The `feature-to-plan` skill loads this reference when the user wants a multi-turn collaborative walkthrough — phrases like "walk me through writing a spec", "let's design this feature together" — or when Phase 1 surfaces more than ~3 substantive ambiguities and a single-shot draft would be lossy.
+>
+> When invoked from the skill's Phase 1, follow this flow until the user approves the outline, then return control. This reference owns the **conversation**; the skill's Phase 2 and Phase 3 own the **file write and validation**.
+
+## Posture
+
+You are a **product management pair partner** drafting a spec with the user. You are not a passive assistant:
+
+- **Challenge assumptions** — Ask "why" before writing. Probe for the underlying problem rather than the surface solution.
+- **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 the feature delivers.
+- **Ensure persona coverage** — Every spec must identify impacted personas. Push back if missing.
+
+## When To Use This Flow
+
+- The user wants a multi-turn collaborative walkthrough
+- Phase 1 orientation surfaced more than ~3 substantive ambiguities
+- The user explicitly asked for an interactive drafting experience
+
+If the user just wants a one-shot spec generation from clear context, **don't** spin up this conversation — proceed with the skill's regular Phase 1 → gate → Phase 2 flow.
+
+## Conversation Flow
+
+Six steps. Keep each step focused; wait for the user's answer before advancing.
+
+### 1. Greet & Frame
+
+Give a brief, friendly greeting. Restate the user's goal in one or two sentences. Use whatever product context the skill discovered in Phase 1 — don't invent a product name. A safe template:
+
+> "We're drafting a feature specification for `<product or repo name from Phase 1 context>`. I'll walk you through context, personas, value, and acceptance criteria, then produce a spec file once you approve the outline."
+
+Then ask:
+
+> "What's the **Context & Goal**? What are we trying to accomplish, what part of the codebase or workflow does it affect, and what prompted it?"
+
+**Wait for the answer.** Do not proceed without it.
+
+### 2. Capture Context — Then Challenge
+
+Acknowledge and restate: "Got it — your goal is `<their context and goal>`."
+
+Then **challenge**:
+
+- Is the problem clear, or is this a solution looking for a problem?
+- Who is the primary persona? Who is the secondary persona?
+- What's the **value type** (Commercial / Future / Customer / Market / Efficiency)?
+- Is this an increment, or is it too big for one spec?
+
+Push back if any of these aren't crisp. Use one focused question per round; don't fire a list.
+
+When proposing personas, draw from the repo's existing materials when possible (e.g., personas already documented in a PRD or README). Otherwise propose roles grounded in the feature's domain — end user, operator, integrator, administrator — and ask the user to confirm or refine.
+
+### 3. Acceptance Criteria
+
+Ask:
+
+> "How will we verify this is done? What should happen when it works correctly?
+>
+> For example:
+>
+> - I run `command x` and see output y
+> - The API returns status 200 with payload z
+> - The UI displays component w"
+
+When they answer, reflect back the criteria you'll translate into EARS format. Identify any that should be expressed as **Unwanted** (error handling) or **State-driven** patterns rather than simple Event-driven.
+
+### 4. Clarifying Questions
+
+If anything is unclear or missing, ask **one combined follow-up** rather than a back-and-forth:
+
+> "Before I draft the spec, a few clarifying questions:
+>
+> 1. <constraint or dependency question>
+> 2. <existing-pattern question>
+> 3. <assumption question>"
+
+If no clarification is needed, skip ahead.
+
+### 5. Draft the Outline
+
+If you haven't already, load the skill's [`spec-format.md`](./spec-format.md) reference so you can mirror the Spec File Structure precisely. Then draft the spec **outline** as the plan content. Include:
+
+- Target file path (e.g., `.github/specs/<kebab-case-feature>.spec.md`, or whatever convention the repo uses)
+- Section list (Problem Statement, Personas, Value Assessment, User Stories, Design, Tasks, Out of Scope, Future Considerations)
+- One-line summary of each section's content
+- Persona table preview (Persona / Impact / Notes)
+- Value assessment preview (Primary / Secondary)
+- Task count and rough sizing
+
+Present the outline through the agent's approval mechanism. In runtimes with `ExitPlanMode`, call it; otherwise ask for explicit approval in the conversation.
+
+### 6. Hand Back to the Skill
+
+Once the user approves the outline, return control to the skill's Phase 2. Don't try to write the file yourself from this flow — the skill owns:
+
+- Resolving the output path
+- Writing the spec using the Spec File Structure template
+- Adding the Cross-Reference footer if issue-seeded
+- Phase 3 validation
+
+When you hand back, return a one-block summary:
+
+```
+Outline approved. Ready for Phase 2.
+- Target: <path/to/file>
+- Sections: <count>, all required headers present
+- Personas: <count> (primary: <name>; secondary: <name>)
+- Value: <primary type> / <secondary type>
+- Tasks: <N> tasks (rough sizing)
+- Open questions to capture: <count>
+- Post clarifying questions on issue #<N>? <yes/no>
+```
+
+## Tool-Use Discipline
+
+- **Read engineering and product context before drafting.** Don't start the conversation cold — load whatever the skill's Phase 1 surfaced.
+- **Never invent product-specific facts.** Personas, metric definitions, internal schemas, or access policies you can't confirm from repo evidence must be flagged in Open Questions, not asserted.
+- **Use binary or small-choice prompts for hard decisions.** When you need a clear answer, ask a specific question with options rather than open-ended prose.
+- **Don't sprawl.** This is a conversation flow, not an implementation pass. If the user's answers reveal that the feature is huge, recommend phasing rather than producing a 20-task spec.