@groupby/ai-dev 0.5.10 → 0.5.11

package/teams/fhr-neowise/skills/write-plan/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: write-plan
+description: "Use when: writing a development plan, creating a PLAN.md and CHECKLIST.json, breaking a spec into implementation steps, generating a TDD checklist, planning test scenarios, producing Gherkin scenarios from a spec, preparing a coding roadmap from a spec file."
+argument-hint: "Provide the path to the SPEC.md file to plan from..."
+context: fork
+
+---
+
+# Write Plan
+
+Read a completed spec file and produce an executable development plan (PLAN.md) and a companion checklist (CHECKLIST.json) that an AI coding agent can follow step-by-step using TDD.
+
+**Do NOT write any production code or test code.** Analyze the spec, research the codebase, and write the plan only.
+
+## Input
+
+The user must provide the path to a SPEC.md file. If no spec file is provided, ask for it immediately before doing anything else. Do not search the workspace for spec files; the user chooses which spec to plan.
+
+The spec file must follow the `.sprints/<sprint-name>/<ticket-number>/SPEC.md` convention. If the provided path does not match, ask the user to confirm the path before proceeding.
+
+## Templates
+
+Read the bundled templates before writing:
+1. [TEMPLATE.plan.md](./assets/TEMPLATE.plan.md) — structure for PLAN.md
+2. [TEMPLATE.checklist.json](./assets/TEMPLATE.checklist.json) — structure for CHECKLIST.json
+
+## Output Location
+
+Write both files next to the SPEC.md in the same directory:
+- `.sprints/<sprint-name>/<ticket-number>/PLAN.md`
+- `.sprints/<sprint-name>/<ticket-number>/CHECKLIST.json`
+
+Also copy the helper script next to the checklist:
+- `.sprints/<sprint-name>/<ticket-number>/checklist.mjs` — copied from `./assets/checklist.mjs`
+
+The agent reads and modifies CHECKLIST.json directly using the Read and Edit tools. The `checklist.mjs` script is available for shell/CI use:
+- `node checklist.mjs --get-next` — prints the next incomplete step as JSON
+- `node checklist.mjs --complete-step <step-id>` — sets `completed: true` on the given step
+
+Do not create any other files unless the user explicitly requests them.
+
+## Investigation Process
+
+**Step summary:** Read spec → Understand affected code → Map dependencies between changes → Sequence into phases → Write test scenarios → Produce plan → Produce checklist → Validate → Request approval → Ask whether to commit generated files.
+
+> Agent note: CHECKLIST.json is a structured JSON file — read and modify it directly with Read/Edit tools. Each step has an `id`, `description`, `verify`, and `completed` field. Set `"completed": true` to mark a step done.
+
+Work through all ten steps in order. Do not skip steps.
+
+### Step 1 — Read and internalize the spec
+
+Read the SPEC.md file completely. Extract:
+- **Objective and success criteria** — what "done" looks like
+- **Agent and module** — which agent handles implementation, which modules are in scope
+- **Files to read, modify, and create** — the full file inventory from the Context section
+- **Functional requirements** — every given/when/then requirement
+- **Technical constraints** — architecture patterns, security, performance
+- **Acceptance criteria** — the verifiable outcomes
+- **Assumptions and open questions** — anything that blocks planning
+
+If the spec has unresolved open questions that would change the plan structure, stop and ask the user to resolve them before proceeding.
+
+### Step 2 — Understand the affected code
+
+For every file listed in the spec's Context section:
+- Read the file and understand its current structure, public API, and test coverage.
+- Identify the exact methods, classes, or components that need to change.
+- Identify existing tests that cover the affected code.
+- Identify existing patterns (naming conventions, architecture style, test style) that the plan must follow.
+
+For each module in scope, identify:
+- The test framework and runner (JUnit, Spock, Jest, etc.)
+- The test command (e.g., `./gradlew :module:test`, `npm test`)
+- The integration test command if applicable
+- The directory structure for tests (unit vs integration)
+
+### Step 3 — Map dependencies between changes
+
+Build a dependency graph of the changes:
+- Which changes can proceed independently (parallel)?
+- Which changes require another change to exist first (sequential)?
+- Which tests require which production code to compile?
+
+Group changes into phases where each phase is internally independent but depends on all previous phases being complete.
+
+**Ordering rules:**
+1. Library modules before service modules that consume them.
+2. Data models and types before business logic that uses them.
+3. Lower-level utilities before higher-level orchestrators.
+4. Production code and its unit tests together in the same step.
+5. Integration tests after all production code they exercise is complete.
+
+### Step 4 — Sequence into implementation steps
+
+Break each phase into atomic implementation steps. Each step must:
+- Touch exactly one class, method, or component (single responsibility).
+- Be completable in a single coding pass — a developer should reach a GREEN test run within one focused session.
+- Have a clearly defined "done" state that can be verified by running a specific test command.
+- Follow the double-loop TDD cycle (see TDD Methodology below).
+
+For each step, specify:
+1. **What to do** — the exact change with specific method signatures, class names, field names, and return types. Not "implement the method" but "add `public Optional<Report> findById(String id)` to `ReportRepository`".
+2. **Where** — the exact file path and location within the file.
+3. **Why** — which spec requirement this satisfies.
+4. **Test first** — the test(s) to write before the production code.
+5. **Verify** — the exact command to run to confirm the step is done.
+
+**No placeholders.** These are plan failures — never write them:
+- "TBD", "TODO", "implement later", "handle edge cases"
+- "Add appropriate error handling" / "add validation"
+- "Write tests for the above" (without naming the specific scenarios)
+- "Similar to Step N" (repeat the information — the executing agent may only see this step)
+- Vague verbs with no specifics ("implement the logic", "update the service")
+
+### Step 5 — Write test scenarios
+
+For every functional requirement and acceptance criterion in the spec, produce Gherkin-style test scenarios.
+
+**Coverage rules:**
+- At least one scenario per requirement (happy path).
+- At least one scenario per error/edge case mentioned in the spec.
+- At least one scenario per branch in any conditional logic implied by the spec.
+- At least one scenario for boundary values (nulls, empty collections, min/max ranges).
+- At least one negative scenario per requirement (what should NOT happen).
+- Group scenarios by the class or component they test.
+
+**Scenario format:**
+```gherkin
+Feature: [Component or class name]
+
+  Scenario: [Descriptive name explaining what is being tested]
+    Given [precondition - specific setup state]
+    And [additional precondition if needed]
+    When [action - the method call or user interaction]
+    Then [expected outcome - specific and verifiable]
+    And [additional assertion if needed]
+```
+
+Map each scenario to:
+- The implementation step that should make it pass.
+- The test file where it should be written.
+- Whether it is a unit test or integration test.
+
+### Step 6 — Produce the plan (PLAN.md)
+
+Write PLAN.md using the template structure. Rules:
+- **Be concrete**: Exact file paths, method signatures, class names, and types. No vague descriptions.
+- **TDD flow**: Every step starts with writing a failing test, then the production code, then verification.
+- **Traceability**: Every step links back to a spec requirement or acceptance criterion.
+- **Completeness**: Every requirement in the spec must be covered by at least one step.
+- **No gaps**: A developer following the plan step-by-step should never need to make a decision not covered by the plan.
+
+Include the TDD methodology reference section in the plan (see below).
+
+### Step 7 — Produce the checklist (CHECKLIST.json)
+
+Write CHECKLIST.json as a structured JSON file derived from the plan steps. Rules:
+- One entry per implementation step, matching the plan 1:1.
+- Each step has: `id` (e.g. `"1.1"`), `description`, `verify` (exact test command or `null`), `completed: false`.
+- Group steps under phases. Each phase has `id` (integer), `title`, and `steps` array.
+- Include a `finalValidation` array for final validation items (id prefix `"final."`).
+- Use the `TEMPLATE.checklist.json` structure exactly.
+- Also copy `checklist.mjs` from assets next to the checklist file.
+
+### Step 8 — Validate the plan
+
+**Gap check first.** Re-read the spec from the top. For every requirement in Section 4 and every criterion in Section 7, point to the specific step(s) in the plan that implement it. List any requirement or criterion with no matching step — these are gaps, not optional. Add missing steps before continuing.
+
+Then verify the structural checklist:
+- [ ] PLAN.md is saved next to the SPEC.md
+- [ ] CHECKLIST.json is saved next to the SPEC.md
+- [ ] Every spec requirement has at least one implementation step (confirmed by gap check above)
+- [ ] Every implementation step has at least one test scenario
+- [ ] Every acceptance criterion is covered by at least one test scenario
+- [ ] Phase ordering respects the dependency graph (no forward references)
+- [ ] Each step specifies the exact file path, specific method/class/type names, and the verification command
+- [ ] No step uses placeholder language (TBD, "implement the logic", "add validation", "similar to Step N")
+- [ ] No step requires a decision not already made in the spec or plan
+- [ ] Gherkin scenarios cover happy path, edge cases, boundary values, and negative cases
+- [ ] The checklist matches the plan steps 1:1
+
+Fix any failing items before presenting the output.
+
+### Step 9 — Request approval or corrections
+
+After Step 8 succeeds, present the generated plan artifacts to the developer and call
+`#tool:vscode/askQuestions` using the question shape below to ask them to either approve
+the artifacts or provide corrections. Do not ask about commit yet.
+
+Requirements:
+- Ask for approval before any commit question appears.
+- Offer two explicit options: `Approve` and `Request corrections`.
+- If the developer selects `Request corrections`, collect the requested changes, amend
+  `PLAN.md` and `CHECKLIST.json`, re-run Step 8, then return to this approval step.
+- Repeat the correction cycle until the developer gives explicit approval.
+- If the developer's feedback is ambiguous and could be read as either approval or a change
+  request, ask a clarifying question instead of assuming approval.
+
+Question shape (substitute the actual sprint name and ticket number from the spec path before presenting):
+```text
+header: approveGeneratedPlan
+question: Approve the generated plan files, or request corrections?
+message: Review `.sprints/<actual-sprint-name>/<actual-ticket-number>/PLAN.md` and `.sprints/<actual-sprint-name>/<actual-ticket-number>/CHECKLIST.json` and choose whether they are ready.
+options:
+  - Approve
+  - Request corrections
+```
+
+Correction behavior:
+- When corrections are requested, update only the generated files from this skill run.
+- Re-run validation after each correction cycle before asking for approval again.
+- Do not offer commit until the developer explicitly selects `Approve`.
+
+### Step 10 — Ask whether to commit the generated files, then hand off to execution
+
+After Step 9 succeeds with explicit approval, call `#tool:vscode/askQuestions` and ask the user whether to commit or skip the generated files from this skill run.
+
+Requirements:
+- Ask exactly once at the end of the workflow, after `PLAN.md` and `CHECKLIST.json` have been written, validated, and explicitly approved.
+- The question must offer two explicit options: `Commit` and `Skip commit`.
+- The prompt must mention the generated file paths that would be included.
+- If the user chooses `Commit`, stage only the files generated by this skill run, not unrelated workspace changes.
+- If the user chooses `Skip commit`, do not stage or commit anything.
+
+Question shape:
+```text
+header: commitGeneratedFiles
+question: Commit the generated plan files now?
+message: This will commit the files created by this skill run only.
+options:
+  - Commit
+  - Skip commit
+```
+
+Commit behavior:
+- Commit only the generated files, typically `.sprints/<sprint-name>/<ticket-number>/PLAN.md`, `CHECKLIST.json`, and `checklist.mjs`.
+- Use a commit message in this format: `<ticket-number>: add <FILE> for <feature>`
+- When all files are committed together: `<ticket-number>: add PLAN.md, CHECKLIST.json, and checklist.mjs for <feature>`.
+- If the repository requires signing, respect the existing git configuration and surface any git error to the user instead of retrying with a weaker flow.
+
+After the commit question is resolved (whether committed or skipped), display this handoff message:
+
+> **Plan ready.** To begin implementation:
+> ```
+> /tdd-implementation ticket=.sprints/<sprint-name>/<ticket-number>
+> ```
+
+## TDD Methodology
+
+Include this section verbatim in every generated PLAN.md:
+
+### Double-Loop TDD
+
+```
+Outer Loop (Integration / Acceptance)          Inner Loop (Unit)
+┌─────────────────────────────────┐            ┌──────────────────────┐
+│ 1. Write a failing integration  │            │ 1. Write a failing   │
+│    test (RED)                   │            │    unit test (RED)   │
+│                                 │            │                      │
+│ 2. Enter inner loop ───────────────────────► │ 2. Write minimal     │
+│                                 │            │    code (GREEN)      │
+│                                 │            │                      │
+│                                 │  ◄──────── │ 3. Refactor (CLEAN)  │
+│                                 │  repeat    │                      │
+│ 3. Integration test passes      │  until     └──────────────────────┘
+│    (GREEN)                      │  green
+│                                 │
+│ 4. Refactor across units        │
+│    (CLEAN)                      │
+└─────────────────────────────────┘
+```
+
+**Rules:**
+- Never write production code without a failing test.
+- Each RED-GREEN-REFACTOR cycle should take minutes, not hours.
+- Run the relevant test suite after every GREEN step to confirm no regressions.
+- Commit at every GREEN boundary (all tests pass).
+
+## Output
+
+Save PLAN.md, CHECKLIST.json, and checklist.mjs to `.sprints/<sprint-name>/<ticket-number>/`. After validation, ask the user via `#tool:vscode/askQuestions` to approve the generated plan files or request corrections. Only after explicit approval should the workflow ask whether to commit the generated files or skip the commit. If the user chooses to commit, commit only the generated files with the required message format. Present a short summary covering:
+- Number of phases and steps in the plan
+- Total test scenarios generated
+- Any spec ambiguities discovered during planning
+- Suggested order of execution

package/teams/fhr-neowise/skills/write-plan/assets/TEMPLATE.checklist.json

@@ -0,0 +1,79 @@
+{
+  "title": "[Feature Title]",
+  "phases": [
+    {
+      "id": 1,
+      "title": "[Phase Title]",
+      "steps": [
+        {
+          "id": "1.1",
+          "description": "[Action description]",
+          "verify": "[test command]",
+          "completed": false
+        },
+        {
+          "id": "1.2",
+          "description": "[Action description]",
+          "verify": "[test command]",
+          "completed": false
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "title": "[Phase Title]",
+      "steps": [
+        {
+          "id": "2.1",
+          "description": "[Action description]",
+          "verify": "[test command]",
+          "completed": false
+        }
+      ]
+    },
+    {
+      "id": 99,
+      "title": "Integration Tests",
+      "steps": [
+        {
+          "id": "99.1",
+          "description": "[Test data setup]",
+          "verify": null,
+          "completed": false
+        },
+        {
+          "id": "99.2",
+          "description": "[Integration test cases]",
+          "verify": "[integration test command]",
+          "completed": false
+        }
+      ]
+    }
+  ],
+  "finalValidation": [
+    {
+      "id": "final.1",
+      "description": "All unit tests pass",
+      "verify": "[command]",
+      "completed": false
+    },
+    {
+      "id": "final.2",
+      "description": "All integration tests pass",
+      "verify": "[command]",
+      "completed": false
+    },
+    {
+      "id": "final.3",
+      "description": "No lint or compile errors",
+      "verify": null,
+      "completed": false
+    },
+    {
+      "id": "final.4",
+      "description": "No TODO, FIXME, or placeholder code",
+      "verify": null,
+      "completed": false
+    }
+  ]
+}

package/teams/fhr-neowise/skills/write-plan/assets/TEMPLATE.plan.md

@@ -0,0 +1,158 @@
+# Plan: [Feature Title]
+
+Date: YYYY-MM-DD
+Spec: [link to SPEC.md](./SPEC.md)
+
+> **Agent**: <!-- Which agent handles implementation? Inherited from spec. -->
+> **Module(s)**: <!-- Which modules are in scope? Inherited from spec. -->
+> **Ticket**: <!-- Link to the Jira/GitHub issue. Inherited from spec. -->
+
+---
+
+## TDD Methodology
+
+### Double-Loop TDD
+
+```
+Outer Loop (Integration / Acceptance)          Inner Loop (Unit)
+┌─────────────────────────────────┐            ┌──────────────────────┐
+│ 1. Write a failing integration  │            │ 1. Write a failing   │
+│    test (RED)                   │            │    unit test (RED)   │
+│                                 │            │                      │
+│ 2. Enter inner loop ───────────────────────► │ 2. Write minimal     │
+│                                 │            │    code (GREEN)      │
+│                                 │            │                      │
+│                                 │  ◄──────── │ 3. Refactor (CLEAN)  │
+│                                 │  repeat    │                      │
+│ 3. Integration test passes      │  until     └──────────────────────┘
+│    (GREEN)                      │  green
+│                                 │
+│ 4. Refactor across units        │
+│    (CLEAN)                      │
+└─────────────────────────────────┘
+```
+
+**Rules:**
+- Never write production code without a failing test.
+- Each RED-GREEN-REFACTOR cycle should take minutes, not hours.
+- Run the relevant test suite after every GREEN step to confirm no regressions.
+- Commit at every GREEN boundary (all tests pass).
+
+---
+
+## Dependency Graph
+
+<!-- Describe which phases depend on which. Example: -->
+<!-- Phase 2 depends on Phase 1. Phase 3 depends on Phases 1 and 2. -->
+
+```
+Phase 1: [module-name] (library/foundation)
+    └── Phase 2: [module-name] (consumer/service)
+        └── Phase 3: [module-name] (integration tests)
+```
+
+---
+
+## Phase 1: [Phase Title]
+
+**Module**: `module-name`
+**Test command**: `./gradlew :module-name:test`
+
+> **No placeholders.** Every "Implementation" block must name the exact method signatures, class names, field names, and return types. Never write "implement the logic", "add validation", "TBD", or "similar to Step N". An agent executing this step should never need to make a decision not already made here.
+
+### Step 1.1 — [Action description]
+
+**Spec requirement**: Section X.Y — [requirement name]
+**File**: `path/to/file.ext`
+
+**Test first** (RED):
+- File: `path/to/test/file.ext`
+- Scenario(s): [reference to Gherkin scenarios below]
+
+**Implementation** (GREEN):
+- [Exact description: e.g. "Add `public Optional<Report> findById(String id)` to `ReportRepository` — queries the `reports` Delta table filtered by `account_id` from context and the given `id`"]
+
+**Verify**: `[exact test command]`
+
+### Step 1.2 — [Action description]
+
+<!-- Repeat the same structure for each step -->
+
+---
+
+## Phase 2: [Phase Title]
+
+<!-- Repeat phase structure -->
+
+---
+
+## Phase N: Integration Tests
+
+**Module**: `module-name`
+**Test command**: `./gradlew :module-name:integrationTest`
+
+### Step N.1 — [Test data setup]
+
+**Spec requirement**: Section X.Y — [requirement name]
+**File**: `path/to/test/resources/file.sql`
+
+**Implementation**:
+- [Describe test data to add]
+
+### Step N.2 — [Integration test cases]
+
+**Spec requirement**: Acceptance criteria
+**File**: `path/to/integration/test/file.ext`
+
+**Test scenarios**: [reference to Gherkin scenarios below]
+
+**Verify**: `[exact integration test command]`
+
+---
+
+## Test Scenarios
+
+### [Component / Class Name]
+
+```gherkin
+Feature: [Component or class name]
+
+  Scenario: [Happy path description]
+    Given [precondition]
+    When [action]
+    Then [expected outcome]
+
+  Scenario: [Edge case description]
+    Given [precondition]
+    When [action]
+    Then [expected outcome]
+
+  Scenario: [Negative case description]
+    Given [precondition]
+    When [action]
+    Then [expected outcome]
+
+  Scenario: [Boundary value description]
+    Given [precondition]
+    When [action]
+    Then [expected outcome]
+```
+
+### [Next Component / Class Name]
+
+```gherkin
+Feature: [Component or class name]
+
+  <!-- Repeat scenario structure -->
+```
+
+---
+
+## Final Validation
+
+After all phases are complete, run the full validation suite:
+
+1. `[unit test command for module 1]` — all unit tests pass
+2. `[unit test command for module 2]` — all unit tests pass
+3. `[integration test command]` — all integration tests pass
+4. `[lint/compile command]` — no errors or warnings