@lousy-agents/cli 5.14.9 → 5.15.0

package/ui/copilot-with-react/.agents/skills/feature-to-plan/references/spec-format.md

@@ -0,0 +1,434 @@
+# Spec Format Reference
+
+> The `feature-to-plan` skill loads this reference during Phase 2 (Create) to construct the spec file. It contains the EARS requirement syntax, user story format, persona template, value assessment table, full Spec File Structure, task design guidelines, and Mermaid diagram requirements.
+
+## Your Role
+
+When drafting a spec, act as a collaborative PM pair, not a passive assistant:
+
+- **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.
+
+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 the repo's engineering guidance
+4. Identify any missing error states or edge cases
+5. Assess whether tasks are appropriately sized for a coding agent session
+
+## 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 workflow engine shall execute jobs in dependency order.
+- When a workflow run completes, the system shall send a notification to subscribed channels.
+- While a runner is offline, the system shall queue jobs for that runner.
+- Where manual approval is configured, the system shall pause deployment until approved.
+- If the workflow file contains invalid YAML, then the system shall display a validation error with line number.
+- While branch protection is enabled, when a push is attempted to a protected branch, the system shall reject the push and return an error message.
+```
+
+## 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>
+```
+
+## Persona Development
+
+Personas should be inlined into each spec's Personas table (see Spec File Structure below). When identifying personas:
+
+### Persona Template
+
+```markdown
+## <Persona Name>
+
+**Role**: <Job title or function>
+**Goals**: <What they're trying to achieve>
+**Pain Points**: <Current frustrations or blockers>
+**Context**: <Team size, experience level, tools they use>
+```
+
+### Persona Guidance
+
+- Name personas by role, not individual (e.g., "Platform Engineer" not "Sarah")
+- Identify both primary and secondary personas for each feature
+- Document whether impact is positive, negative, or neutral
+- Consider: Who benefits? Who is disrupted? Who needs to change behavior?
+- Pull persona names from the target product's existing materials when available; otherwise propose roles grounded in the feature's domain (end user, operator, integrator, administrator, etc.)
+
+## Value Assessment
+
+Evaluate every feature against these value types. A feature may deliver multiple.
+
+| Value Type | Question to Ask                                                    |
+| ---------- | ------------------------------------------------------------------ |
+| Commercial | Does this increase revenue or reduce cost of sale?                 |
+| Future     | Does this save time or money later? Does it reduce technical debt? |
+| Customer   | Does this increase retention or satisfaction for existing users?   |
+| Market     | Does this attract new users or open new segments?                  |
+| Efficiency | Does this save operational time or reduce manual effort now?       |
+
+State the value assessment explicitly in the spec. If value is unclear, flag it as a risk.
+
+## 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 a coding agent)
+
+```markdown
+# Feature: <name>
+
+## Problem Statement
+
+<2-3 sentences describing the problem, not the solution>
+
+## Personas
+
+| Persona | Impact                    | Notes               |
+| ------- | ------------------------- | ------------------- |
+| <name>  | Positive/Negative/Neutral | <brief explanation> |
+
+## Value Assessment
+
+- **Primary value**: <type> — <explanation>
+- **Secondary value**: <type> — <explanation>
+
+## User Stories
+
+### Story 1: <Title>
+
+As a **<persona>**,
+I want **<capability>**,
+so that I can **<outcome>**.
+
+#### Acceptance Criteria
+
+- When...
+- While...
+- If..., then...
+
+---
+
+## Design
+
+> Refer to the repo's engineering guidance (e.g., `AGENTS.md`, `CONTRIBUTING.md`, `.github/copilot-instructions.md`, `CLAUDE.md`) for technical standards.
+
+### Components Affected
+
+- `<path/to/file-or-directory>` — <what changes>
+
+### Dependencies
+
+- <External service, library, or internal component>
+
+### Data Model Changes
+
+<If applicable: new fields, schemas, or state changes>
+
+### Diagrams
+
+<Include Mermaid diagrams to visualize data flow, architecture, or sequences>
+
+### Open Questions
+
+- [ ] <Unresolved technical or product question>
+
+---
+
+## Tasks
+
+> Each task should be completable in a single coding agent session.
+> Tasks are sequenced by dependency. Complete in order unless noted.
+
+### Task 1: <Title>
+
+**Objective**: <One sentence describing what this task accomplishes>
+
+**Context**: <Why this task exists, what it unblocks>
+
+**Affected files**:
+
+- `<path/to/file>`
+
+**Requirements**:
+
+- <Specific acceptance criterion this task satisfies>
+
+**Verification**:
+
+- [ ] <Command to run or condition to check>
+- [ ] <Test that should pass>
+
+**Done when**:
+
+- [ ] All verification steps pass
+- [ ] No new errors in affected files
+- [ ] Acceptance criteria <reference specific criteria> satisfied
+- [ ] Code follows the repo's engineering guidance
+
+---
+
+### Task 2: <Title>
+
+**Depends on**: Task 1
+
+**Objective**: ...
+
+---
+
+## Out of Scope
+
+- <Explicitly excluded item>
+
+## Future Considerations
+
+- <Potential follow-on work>
+```
+
+## 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 ("Add validation to...", "Create endpoint for...")
+- **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**:
+
+- [ ] `<repo's test command>` passes
+- [ ] `<repo's lint command>` passes
+- [ ] New endpoint returns 200 for valid input
+- [ ] New endpoint returns 400 with error message for invalid input
+```
+
+Prefer automated checks (commands, tests) over subjective criteria. Use whatever commands the target repo defines — don't hardcode a tool the repo doesn't use.
+
+### Sequencing
+
+- State dependencies explicitly ("Depends on: Task 2")
+- First task should be the smallest vertical slice
+- Final task often includes integration tests or documentation
+
+## Anti-Patterns for Coding Agents
+
+When implementing tasks from specs, avoid these common mistakes:
+
+**Don't:**
+
+- Create files outside the Affected files list without explicit approval
+- Skip verification steps or mark tasks complete without running them
+- Implement features not specified in acceptance criteria
+- Assume dependencies are installed — verify or install as part of the task
+- Make architectural decisions that contradict the repo's engineering guidance
+- Batch multiple unrelated changes in a single task implementation
+- Ignore error states or edge cases mentioned in acceptance criteria
+
+**Do:**
+
+- Read the full spec (Requirements, Design, and specific Task) before starting
+- Follow verification steps in the exact order specified
+- Reference the repo's engineering guidance for technical patterns and standards
+- Ask for clarification when acceptance criteria are ambiguous
+- Stay within the scope of the specific task assigned
+- Update only the files listed in "Affected files" unless creating new test files
+- Run all verification commands and report results
+
+## Workflow: Spec to Implementation
+
+1. **Specify**
+   - Define problem, personas, value
+   - Write user stories with EARS acceptance criteria
+   - Review: Is the problem clear? Are criteria testable?
+
+2. **Design**
+   - Identify affected components and files
+   - Note dependencies and data model changes
+   - Review: Does this align with the repo's engineering guidance?
+
+3. **Task Breakdown**
+   - Decompose into agent-sized tasks
+   - Add verification steps to each task
+   - Sequence by dependency
+   - Review: Can each task complete independently?
+
+4. **Implement (per task)**
+   - Assign task to coding agent (issue or direct prompt)
+   - Agent references spec for context, engineering guidance for standards
+   - Run verification steps
+   - Mark task complete, proceed to next
+
+5. **Validate**
+   - All tasks complete
+   - All acceptance criteria verified
+   - Update spec if implementation revealed changes
+
+## Assigning Tasks to a Coding Agent
+
+When assigning a task, include:
+
+1. **Link to spec file** — "See `<path-to-spec>`"
+2. **Task reference** — "Implement Task 3: Add validation"
+3. **Engineering guidance reference** — "Follow the repo's engineering instructions"
+
+### Example: GitHub Issue for a Coding Agent
+
+```markdown
+## Task
+
+Implement **Task 3: Add input validation** from `.github/specs/workflow-triggers.spec.md`
+
+## Context
+
+This task adds validation for workflow trigger configurations.
+See the spec for full acceptance criteria and design context.
+
+## References
+
+- Spec: `.github/specs/workflow-triggers.spec.md` (Task 3)
+- Standards: <repo's engineering guidance file>
+
+## Verification
+
+- [ ] `<repo test command>` passes
+- [ ] `<repo lint command>` passes
+- [ ] Validation rejects invalid cron expressions with descriptive error
+```
+
+### Example: Direct Prompt to a Coding Agent
+
+```text
+Implement Task 3 from .github/specs/workflow-triggers.spec.md
+
+Read the full spec for context. This task adds input validation
+for workflow trigger configurations.
+
+Follow the engineering standards documented in the repo.
+
+After implementation, run the verification steps in the task
+and confirm they pass.
+```
+
+## Constraints
+
+- **Avoid vague appeals to "best practices."** These terms are subjective and can change. Be specific about what you recommend and why.
+
+## Diagram Requirements
+
+All diagrams in specs must use **Mermaid** syntax for consistency and GitHub rendering support.
+
+### Supported Diagram Types
+
+| Diagram Type        | Mermaid Type                     | Use Case                                      |
+| ------------------- | -------------------------------- | --------------------------------------------- |
+| Data Flow           | `flowchart TB` or `flowchart LR` | Show how data moves between components        |
+| Sequence            | `sequenceDiagram`                | Show interaction order between actors/systems |
+| State               | `stateDiagram-v2`                | Show state transitions                        |
+| Entity Relationship | `erDiagram`                      | Show data model relationships                 |
+| Class               | `classDiagram`                   | Show object relationships and structure       |
+
+### Example: Data Flow Diagram
+
+````markdown
+```mermaid
+flowchart TB
+    subgraph CLI["CLI Layer"]
+        CMD["command"]
+    end
+    subgraph UseCases["Use Cases Layer"]
+        UC["use case logic"]
+    end
+    CMD --> UC
+```
+````
+
+### Example: Sequence Diagram
+
+````markdown
+```mermaid
+sequenceDiagram
+    participant User
+    participant System
+    User->>System: request
+    System-->>User: response
+```
+````
+
+### Guidelines
+
+- Use subgraphs to group related components by architectural layer
+- Include descriptive labels for each node
+- Show data types flowing between components where relevant
+- For complex flows, prefer sequence diagrams to show interaction order
+
+## Integration with Engineering Guidance
+
+For technical decisions, implementation patterns, and architectural standards, defer to whatever engineering guidance the target repo provides — common examples include `AGENTS.md`, `CONTRIBUTING.md`, `.github/copilot-instructions.md`, `CLAUDE.md`, or files under `.github/instructions/`.
+
+**This spec file governs:**
+
+- What to build and why (product decisions)
+- Who it's for (personas)
+- How to know it's done (acceptance criteria)
+- Task breakdown for agent assignment
+
+**The repo's engineering guidance governs:**
+
+- How to build it (technical approach)
+- Code standards and patterns
+- Testing and validation requirements
+
+When a spec requires architectural input, note it in Open Questions and recommend review against engineering guidance before implementation begins.

package/ui/copilot-with-react/.devcontainer/devcontainer.json

@@ -3,14 +3,14 @@
     "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04@sha256:4bcb1b466771b1ba1ea110e2a27daea2f6093f9527fb75ee59703ec89b5561cb",
     "features": {
         "ghcr.io/devcontainers/features/node:1.7.1": {
-            "version": "24.15.0"
+            "version": "24.16.0"
         },
         "ghcr.io/devcontainers/features/github-cli:1.1.0": {
             "version": "latest"
         },
         "ghcr.io/devcontainers/features/copilot-cli:1.0.0": {},
         "ghcr.io/anthropics/devcontainer-features/claude-code:1": {
-            "version": "v2.1.143"
+            "version": "v2.1.160"
         },
         "ghcr.io/rocker-org/devcontainer-features/apt-packages:1.0.2": {
             "packages": "libnss3, libnspr4, libatk1.0-0t64, libatk-bridge2.0-0t64, libcups2t64, libdrm2, libdbus-1-3, libatspi2.0-0t64, libxcomposite1, libxdamage1, libxfixes3, libxrandr2, libgbm1, libxkbcommon0, libasound2t64, yamllint, shellcheck",

package/ui/copilot-with-react/.github/ISSUE_TEMPLATE/feature-to-spec.yml

@@ -40,15 +40,23 @@ body:
     id: extra-instructions
     attributes:
       label: Extra Instructions
-      description: Specific prompt engineering for the agent. This will be posted as a comment to guide the bot.
+      # yamllint disable rule:line-length
+      description: >-
+        Skill invocation for the agent.
+        This will be posted as a comment to guide the bot.
       value: |
-        1. Review .github/instructions/spec.instructions.md for more details and use this as your guide for the feature specification.
-        2. Ensure you review all other repository instructions before starting work to understand engineering requirements.
-        3. Create your final spec output in the .github/specs directory and ensure requirements are captured in the EARS format.
-        4. Create a data flow diagram and sequence diagram to illustrate the feature's operation.
-        5. Break down the feature into manageable tasks with clear descriptions.
-        6. As you complete each task in the spec, mark the checkboxes as complete in the spec file using [x] notation.
-        7. If you need to make assumptions, ask questions on the issue.
-        8. Use the diagrams to inform your implementation plan.
+        ## MANDATORY — Do not skip this step
+
+        You **MUST** invoke the `feature-to-plan` skill to produce the
+        spec for this issue. This is not optional — the skill defines the
+        authoritative procedure (Orient → Approval Gate → Create → Validate) and output
+        format. Do not attempt to produce the spec manually or deviate
+        from the skill's procedure.
+
+        Invoke the skill with this issue number as the argument.
+
+        Failure to use the `feature-to-plan` skill will result in the
+        spec being rejected.
+      # yamllint enable rule:line-length
     validations:
-      required: false
+      required: true

package/ui/copilot-with-react/.github/instructions/spec.instructions.md

@@ -48,7 +48,9 @@ This repository includes a GitHub issue template for streamlined spec creation w
 2. Select **"Copilot Feature To Spec"** template
 3. Fill in the **Context & Goal** section describing what you want to build
 4. Fill in the **Acceptance Criteria** section with testable requirements
-5. Optionally customize the **Extra Instructions** section for agent-specific guidance
+5. Keep the default **Extra Instructions** unchanged — it mandates
+   invoking the `feature-to-plan` skill, which is the authoritative
+   spec-authoring workflow
 6. Submit the issue
 
 ### Automatic Copilot Assignment
@@ -56,7 +58,8 @@ This repository includes a GitHub issue template for streamlined spec creation w
 When you create an issue with the `copilot-ready` label (applied automatically by the template):
 
 1. The `assign-copilot.yml` workflow triggers
-2. Copilot is mentioned in a comment with your Extra Instructions
+2. Copilot is mentioned in a comment that includes the mandatory
+   `feature-to-plan` invocation instructions
 3. Copilot begins working on the spec in `.github/specs/`
 
 ### Related Files

package/ui/copilot-with-react/.nvmrc

@@ -1 +1 @@
-24.15.0
+24.16.0

package/ui/copilot-with-react/biome.template.json

@@ -1,6 +1,6 @@
 {
     "root": true,
-    "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
+    "$schema": "https://biomejs.dev/schemas/2.4.16/schema.json",
     "vcs": {
         "enabled": true,
         "clientKind": "git",

package/ui/copilot-with-react/package.json

@@ -16,29 +16,29 @@
         "@emotion/server": "11.11.0",
         "@mui/material": "9.0.1",
         "@mui/material-nextjs": "9.0.1",
-        "next": "16.2.6",
-        "react": "19.2.6",
-        "react-dom": "19.2.6"
+        "next": "16.2.7",
+        "react": "19.2.7",
+        "react-dom": "19.2.7"
     },
     "devDependencies": {
-        "@biomejs/biome": "2.4.15",
+        "@biomejs/biome": "2.4.16",
         "@eslint/eslintrc": "3.3.5",
-        "@lousy-agents/mcp": "5.14.8",
+        "@lousy-agents/mcp": "5.14.10",
         "@modelcontextprotocol/server-sequential-thinking": "2025.12.18",
         "@testing-library/jest-dom": "6.9.1",
         "@testing-library/react": "16.3.2",
         "@types/node": "24.12.4",
-        "@types/react": "19.2.14",
+        "@types/react": "19.2.16",
         "@types/react-dom": "19.2.3",
-        "@upstash/context7-mcp": "2.2.5",
+        "@upstash/context7-mcp": "3.1.0",
         "@vitejs/plugin-react": "6.0.2",
-        "@vitest/ui": "4.1.6",
-        "eslint": "10.4.0",
-        "eslint-config-next": "16.2.6",
+        "@vitest/ui": "4.1.8",
+        "eslint": "10.4.1",
+        "eslint-config-next": "16.2.7",
         "happy-dom": "20.9.0",
         "jsdom": "29.1.1",
         "typescript": "6.0.3",
-        "vitest": "4.1.6",
+        "vitest": "4.1.8",
         "whatwg-fetch": "3.6.20"
     }
 }