ecoportal-api-graphql 1.3.13 → 1.3.15

data/.ai-assistance/skills/code-specs/SKILL.md

@@ -1,69 +1,69 @@
-# SKILL: Code Specs for AI
-
-**Purpose:** Maintain AI-readable markdown documentation in `.ai-assistance/code/` so that future AI agents don't need to re-analyse code from scratch. These docs are shortcuts, not replacements — when real analysis is needed, always update them.
-
----
-
-## When to Use
-
-- After analysing a new area of the codebase.
-- Before starting work in an area — check if a doc exists and whether it's stale.
-- After making changes that alter the understanding of an area.
-- Periodically (especially at project cycle-end) — use Gemini Assist to spot stale sections.
-
----
-
-## Document Structure
-
-Each code spec document (`.ai-assistance/code/<area>.md`) must include:
-
-```markdown
-# Code Spec: <Area Name>
-
-**Scope:** What this document covers. What it explicitly does NOT cover.
-**Last updated:** YYYY-MM-DD
-**Key files:** List of the most important files in this area.
-
----
-
-## Overview
-Brief description of what this area does and its role in the gem.
-
-## Key Classes / Modules
-For each significant class: one-line purpose, key public methods/interface.
-
-## Patterns & Conventions
-Design patterns, inheritance chains, naming conventions specific to this area.
-
-## Dependencies
-What this area depends on (internal and external). What depends on it.
-
-## Gotchas / Non-Obvious Behaviours
-Things that would cause confusion or bugs if not known upfront.
-
-## TODOs / Open Questions
-Pending items specific to this area. Link to project TODO if applicable.
-```
-
----
-
-## Naming & Placement
-
-Mirror the `lib/` structure:
-
-| Code area | Doc path |
-|-----------|---------|
-| `lib/ecoportal/api/graphql/model/` | `.ai-assistance/code/model.md` |
-| `lib/ecoportal/api/graphql/input/` | `.ai-assistance/code/input.md` |
-| `lib/ecoportal/api/graphql/logic/` | `.ai-assistance/code/logic.md` |
-| Whole gem overview | `.ai-assistance/code/OVERVIEW.md` |
-
-For deeply nested areas, use subdirectories: `.ai-assistance/code/model/location_structure.md`
-
----
-
-## Keeping Docs Fresh
-
-- When you read a file and find something the doc doesn't mention — add it.
-- When a refactor changes a class — update the corresponding doc.
-- Use the `gemini-assist` skill for batch reviews of multiple docs vs. current code.
+# SKILL: Code Specs for AI
+
+**Purpose:** Maintain AI-readable markdown documentation in `.ai-assistance/code/` so that future AI agents don't need to re-analyse code from scratch. These docs are shortcuts, not replacements — when real analysis is needed, always update them.
+
+---
+
+## When to Use
+
+- After analysing a new area of the codebase.
+- Before starting work in an area — check if a doc exists and whether it's stale.
+- After making changes that alter the understanding of an area.
+- Periodically (especially at project cycle-end) — use Gemini Assist to spot stale sections.
+
+---
+
+## Document Structure
+
+Each code spec document (`.ai-assistance/code/<area>.md`) must include:
+
+```markdown
+# Code Spec: <Area Name>
+
+**Scope:** What this document covers. What it explicitly does NOT cover.
+**Last updated:** YYYY-MM-DD
+**Key files:** List of the most important files in this area.
+
+---
+
+## Overview
+Brief description of what this area does and its role in the gem.
+
+## Key Classes / Modules
+For each significant class: one-line purpose, key public methods/interface.
+
+## Patterns & Conventions
+Design patterns, inheritance chains, naming conventions specific to this area.
+
+## Dependencies
+What this area depends on (internal and external). What depends on it.
+
+## Gotchas / Non-Obvious Behaviours
+Things that would cause confusion or bugs if not known upfront.
+
+## TODOs / Open Questions
+Pending items specific to this area. Link to project TODO if applicable.
+```
+
+---
+
+## Naming & Placement
+
+Mirror the `lib/` structure:
+
+| Code area | Doc path |
+|-----------|---------|
+| `lib/ecoportal/api/graphql/model/` | `.ai-assistance/code/model.md` |
+| `lib/ecoportal/api/graphql/input/` | `.ai-assistance/code/input.md` |
+| `lib/ecoportal/api/graphql/logic/` | `.ai-assistance/code/logic.md` |
+| Whole gem overview | `.ai-assistance/code/OVERVIEW.md` |
+
+For deeply nested areas, use subdirectories: `.ai-assistance/code/model/location_structure.md`
+
+---
+
+## Keeping Docs Fresh
+
+- When you read a file and find something the doc doesn't mention — add it.
+- When a refactor changes a class — update the corresponding doc.
+- Use the `gemini-assist` skill for batch reviews of multiple docs vs. current code.

data/.ai-assistance/skills/gemini-assist/SKILL.md

@@ -1,63 +1,63 @@
-# SKILL: Gemini Assist
-
-**Purpose:** Offload large-context tasks to Gemini to save Claude token quota, speed up development, and leverage Gemini's wide context window.
-
----
-
-## When to Use
-
-- The task requires reading many files at once (e.g. whole-gem analysis, cross-cutting refactor planning).
-- A task is mostly "read and summarise / read and advise" rather than "write code" — Gemini handles these cheaply.
-- You're doing a cycle-end review and want a second pass over a large diff or many changed files.
-- Token budget is running low and the task doesn't require Claude's nuanced judgement for the current step.
-
-## When NOT to Use
-
-- Tasks that require writing or editing actual code (Claude applies changes; Gemini only advises).
-- Tasks where hallucination risk is high and verification would cost more time than doing it directly.
-- Short tasks that fit comfortably in Claude's context — the overhead isn't worth it.
-
----
-
-## How to Invoke
-
-Run from the repo root:
-
-```bash
-ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
-  --prompt "Your question or instruction here" \
-  --files path/to/file1.rb path/to/file2.rb \
-  [--model gemini-1.5-pro]
-```
-
-Or pass a prompt file:
-
-```bash
-ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
-  --prompt-file .ai-assistance/skills/gemini-assist/prompts/cycle_end_review.txt \
-  --files "lib/ecoportal/api/graphql/**/*.rb"
-```
-
-**Environment variable required:** `GEMINI_API_KEY` — set in `.env` at repo root (git-ignored).
-**Optional:** `GEMINI_MODEL` — defaults to `gemini-1.5-pro`. Override in `.env` or via `--model`.
-
----
-
-## Output Handling (IMPORTANT)
-
-Gemini responses **must always be reviewed** before acting on them:
-
-1. Read the response carefully.
-2. Cross-check any specific claims (method names, class hierarchies, argument counts) against the actual code.
-3. Where Gemini proposes code changes, treat them as a draft — apply only after verifying correctness.
-4. Where Gemini flags issues in a cycle-end review, confirm each issue is real before proposing a fix to the developer.
-
----
-
-## Prompting Tips for Best Results
-
-- Give Gemini explicit instructions: what to look for, what to ignore, what format to respond in.
-- Tell it the role: "You are reviewing a Ruby gem. Focus on X. Do not suggest Y."
-- Ask for a structured output (e.g. "Respond with a numbered list of concerns, each with: file, line range, issue, suggested fix").
-- For large reviews, ask it to triage by severity first.
-- Use the pre-built prompt in `prompts/cycle_end_review.txt` for end-of-cycle reviews.
+# SKILL: Gemini Assist
+
+**Purpose:** Offload large-context tasks to Gemini to save Claude token quota, speed up development, and leverage Gemini's wide context window.
+
+---
+
+## When to Use
+
+- The task requires reading many files at once (e.g. whole-gem analysis, cross-cutting refactor planning).
+- A task is mostly "read and summarise / read and advise" rather than "write code" — Gemini handles these cheaply.
+- You're doing a cycle-end review and want a second pass over a large diff or many changed files.
+- Token budget is running low and the task doesn't require Claude's nuanced judgement for the current step.
+
+## When NOT to Use
+
+- Tasks that require writing or editing actual code (Claude applies changes; Gemini only advises).
+- Tasks where hallucination risk is high and verification would cost more time than doing it directly.
+- Short tasks that fit comfortably in Claude's context — the overhead isn't worth it.
+
+---
+
+## How to Invoke
+
+Run from the repo root:
+
+```bash
+ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
+  --prompt "Your question or instruction here" \
+  --files path/to/file1.rb path/to/file2.rb \
+  [--model gemini-1.5-pro]
+```
+
+Or pass a prompt file:
+
+```bash
+ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
+  --prompt-file .ai-assistance/skills/gemini-assist/prompts/cycle_end_review.txt \
+  --files "lib/ecoportal/api/graphql/**/*.rb"
+```
+
+**Environment variable required:** `GEMINI_API_KEY` — set in `.env` at repo root (git-ignored).
+**Optional:** `GEMINI_MODEL` — defaults to `gemini-1.5-pro`. Override in `.env` or via `--model`.
+
+---
+
+## Output Handling (IMPORTANT)
+
+Gemini responses **must always be reviewed** before acting on them:
+
+1. Read the response carefully.
+2. Cross-check any specific claims (method names, class hierarchies, argument counts) against the actual code.
+3. Where Gemini proposes code changes, treat them as a draft — apply only after verifying correctness.
+4. Where Gemini flags issues in a cycle-end review, confirm each issue is real before proposing a fix to the developer.
+
+---
+
+## Prompting Tips for Best Results
+
+- Give Gemini explicit instructions: what to look for, what to ignore, what format to respond in.
+- Tell it the role: "You are reviewing a Ruby gem. Focus on X. Do not suggest Y."
+- Ask for a structured output (e.g. "Respond with a numbered list of concerns, each with: file, line range, issue, suggested fix").
+- For large reviews, ask it to triage by severity first.
+- Use the pre-built prompt in `prompts/cycle_end_review.txt` for end-of-cycle reviews.

data/.ai-assistance/skills/project-cycle/SKILL.md

@@ -1,177 +1,177 @@
-# SKILL: Project Preparation, Maintenance & Cycle
-
-**Purpose:** Capture, organise, and track a development project from intent through completion, including upstream dependency decisions and cycle-end review.
-
----
-
-## When to Use
-
-- A developer describes a new piece of work.
-- Picking up an existing project after a gap.
-- A cycle of changes is complete and needs a closing review.
-
----
-
-## Folder Structure
-
-```
-.ai-assistance/projects/<project-slug>/
-  INTENT.md          What we're trying to achieve and why
-  TODO.md            Ordered task list, ticked off as done
-  DECISIONS.md       Key decisions made and why
-  UPSTREAM.md        Upstream dependency changes needed (if any)
-```
-
-Project folders are **not git-ignored** — they should be committed so other developers can pick up context.
-
----
-
-## Starting a Project
-
-1. Ask the developer: "What are we trying to change and why?"
-2. Capture the answer in `INTENT.md` (see template below).
-3. Present it back: "Here's my understanding — does this capture it?" Iterate until confirmed.
-4. Break the intent into an ordered TODO list in `TODO.md`.
-5. If upstream deps are involved, create `UPSTREAM.md` and present options (patch, fork, new version).
-
-### INTENT.md template
-
-```markdown
-# Project: <Name>
-
-**Created:** YYYY-MM-DD
-**Status:** [active | paused | complete]
-**Branch:** feature/<slug>
-**Target branch:** main
-
-## Goal
-One paragraph: what we want to achieve.
-
-## Motivation
-Why now? What problem does this solve?
-
-## Scope
-What's in scope. What's explicitly out of scope.
-
-## Success Criteria
-How we'll know it's done.
-```
-
----
-
-## TODO.md format
-
-```markdown
-# TODOs — <Project Name>
-
-- [ ] Task description  <!-- add detail as needed -->
-- [x] Completed task
-```
-
-Tick items off as they're completed. Never delete items — the history matters.
-
----
-
-## DECISIONS.md format
-
-```markdown
-# Decisions — <Project Name>
-
-## [DATE] <Decision title>
-
-**Context:** What made this decision necessary.
-**Options considered:** Brief list.
-**Decision:** What was chosen.
-**Reason:** Why.
-**Consequences:** What this means going forward.
-```
-
----
-
-## Session Start — Git Orientation (Always Do This)
-
-Before any other work, run:
-
-```bash
-# 1. Confirm current branch
-git branch --show-current
-
-# 2. Check how far ahead of target branch
-git rev-list --count main..HEAD
-
-# 3. Get a cheap summary of what's changed
-git diff main...HEAD --stat
-```
-
-Cross-reference the diff stat against the active project's `TODO.md`:
-- Changed files should map to ticked TODO items.
-- Unticked TODOs with no corresponding changed files = work not yet started.
-- Changed files with no corresponding TODO = untracked work, worth noting.
-
-If **GitKraken MCP** is connected, use it instead — it returns the same information as structured data without a bash call.
-
-If the branch in `INTENT.md` doesn't match the current branch, flag it to the developer before proceeding.
-
----
-
-## Cycle-End Review
-
-When all TODOs are ticked:
-
-1. **Git summary:** Run `git diff main...HEAD --name-only` to get the exact file list.
-2. **Gemini review:** Pass changed files to `gemini-assist` using the `cycle_end_review.txt` prompt:
-   ```bash
-   ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
-     --prompt-file .ai-assistance/skills/gemini-assist/prompts/cycle_end_review.txt \
-     --output .ai-assistance/projects/<slug>/gemini_review.txt \
-     --files $(git diff main...HEAD --name-only | tr '\n' ' ')
-   ```
-3. Review Gemini's output — verify each claim against actual code before acting.
-4. Propose fixes for genuine issues — confirm with developer.
-5. **If GitLab MCP is connected:** Check `get_merge_request_pipelines` to confirm CI is green.
-6. Update `INTENT.md` status to `complete`.
-7. Prompt: "Ready to open the MR / start the next project?"
-
----
-
-## Upstream Dependency Changes
-
-If changes require modifying an upstream gem:
-
-Options (present all three to developer):
-
-1. **Local patch** — monkey-patch from this gem. Fast, messy, temporary.
-2. **Fork change** — commit to our fork (for `graphlient` or `graphql-client`). Appropriate for lasting fixes we own.
-3. **New version** — for `ecoportal-api` or `ecoportal-api-v2` (team-owned), cut a new version. For external forks, optionally contribute back upstream.
-
-Document the decision in `UPSTREAM.md` and `DECISIONS.md`.
-
----
-
-## Session / Collaborator Setup (First Time on a Machine)
-
-When starting a session and `.ai-assistance/local_paths.md` does not exist, run this setup flow **before** any project work:
-
-1. Tell the developer: "I don't see a `local_paths.md` for your machine yet. This helps me cross-reference upstream and downstream gem code without fetching from remotes every time."
-
-2. For each dependency in the table below, ask: "Do you have `<gem>` cloned locally?"
-
-   | Gem | Remote |
-   |-----|--------|
-   | `ecoportal-api` | https://gitlab.ecoportal.co.nz/ecoportal/ecoportal-api.git |
-   | `ecoportal-api-v2` | https://gitlab.ecoportal.co.nz/oscar/ecoportal-api-v2.git |
-   | `graphlient` | https://github.com/rellampec/graphlient.git |
-   | `graphql-client` | https://github.com/rellampec/graphql-client.git |
-   | `eco-helpers` | https://gitlab.ecoportal.co.nz/oscar/script_api_helpers.git |
-
-3. For each one they have locally:
-   - In **Cowork**: ask them to connect the folder (via the folder picker), then record the confirmed path.
-   - In **Claude Code**: ask them to provide the path, or run `find ~ -name "<gemspec>" -maxdepth 6 2>/dev/null` to locate it.
-
-4. Once all available paths are collected, create `.ai-assistance/local_paths.md` from `.ai-assistance/local_paths.example.md`, filling in only the repos they confirmed.
-
-5. Also ask: "Do you have GitKraken MCP or GitLab MCP set up?" — if not, point them to `.ai-assistance/integrations/`.
-
-6. Confirm: "Done — I've saved your local paths. You can update `.ai-assistance/local_paths.md` any time if your setup changes."
-
-If a developer doesn't have a repo locally and the task requires reading it, offer: "I can fetch the relevant files from the remote — just note it'll be slower. Want me to proceed that way?"
+# SKILL: Project Preparation, Maintenance & Cycle
+
+**Purpose:** Capture, organise, and track a development project from intent through completion, including upstream dependency decisions and cycle-end review.
+
+---
+
+## When to Use
+
+- A developer describes a new piece of work.
+- Picking up an existing project after a gap.
+- A cycle of changes is complete and needs a closing review.
+
+---
+
+## Folder Structure
+
+```
+.ai-assistance/projects/<project-slug>/
+  INTENT.md          What we're trying to achieve and why
+  TODO.md            Ordered task list, ticked off as done
+  DECISIONS.md       Key decisions made and why
+  UPSTREAM.md        Upstream dependency changes needed (if any)
+```
+
+Project folders are **not git-ignored** — they should be committed so other developers can pick up context.
+
+---
+
+## Starting a Project
+
+1. Ask the developer: "What are we trying to change and why?"
+2. Capture the answer in `INTENT.md` (see template below).
+3. Present it back: "Here's my understanding — does this capture it?" Iterate until confirmed.
+4. Break the intent into an ordered TODO list in `TODO.md`.
+5. If upstream deps are involved, create `UPSTREAM.md` and present options (patch, fork, new version).
+
+### INTENT.md template
+
+```markdown
+# Project: <Name>
+
+**Created:** YYYY-MM-DD
+**Status:** [active | paused | complete]
+**Branch:** feature/<slug>
+**Target branch:** main
+
+## Goal
+One paragraph: what we want to achieve.
+
+## Motivation
+Why now? What problem does this solve?
+
+## Scope
+What's in scope. What's explicitly out of scope.
+
+## Success Criteria
+How we'll know it's done.
+```
+
+---
+
+## TODO.md format
+
+```markdown
+# TODOs — <Project Name>
+
+- [ ] Task description  <!-- add detail as needed -->
+- [x] Completed task
+```
+
+Tick items off as they're completed. Never delete items — the history matters.
+
+---
+
+## DECISIONS.md format
+
+```markdown
+# Decisions — <Project Name>
+
+## [DATE] <Decision title>
+
+**Context:** What made this decision necessary.
+**Options considered:** Brief list.
+**Decision:** What was chosen.
+**Reason:** Why.
+**Consequences:** What this means going forward.
+```
+
+---
+
+## Session Start — Git Orientation (Always Do This)
+
+Before any other work, run:
+
+```bash
+# 1. Confirm current branch
+git branch --show-current
+
+# 2. Check how far ahead of target branch
+git rev-list --count main..HEAD
+
+# 3. Get a cheap summary of what's changed
+git diff main...HEAD --stat
+```
+
+Cross-reference the diff stat against the active project's `TODO.md`:
+- Changed files should map to ticked TODO items.
+- Unticked TODOs with no corresponding changed files = work not yet started.
+- Changed files with no corresponding TODO = untracked work, worth noting.
+
+If **GitKraken MCP** is connected, use it instead — it returns the same information as structured data without a bash call.
+
+If the branch in `INTENT.md` doesn't match the current branch, flag it to the developer before proceeding.
+
+---
+
+## Cycle-End Review
+
+When all TODOs are ticked:
+
+1. **Git summary:** Run `git diff main...HEAD --name-only` to get the exact file list.
+2. **Gemini review:** Pass changed files to `gemini-assist` using the `cycle_end_review.txt` prompt:
+   ```bash
+   ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
+     --prompt-file .ai-assistance/skills/gemini-assist/prompts/cycle_end_review.txt \
+     --output .ai-assistance/projects/<slug>/gemini_review.txt \
+     --files $(git diff main...HEAD --name-only | tr '\n' ' ')
+   ```
+3. Review Gemini's output — verify each claim against actual code before acting.
+4. Propose fixes for genuine issues — confirm with developer.
+5. **If GitLab MCP is connected:** Check `get_merge_request_pipelines` to confirm CI is green.
+6. Update `INTENT.md` status to `complete`.
+7. Prompt: "Ready to open the MR / start the next project?"
+
+---
+
+## Upstream Dependency Changes
+
+If changes require modifying an upstream gem:
+
+Options (present all three to developer):
+
+1. **Local patch** — monkey-patch from this gem. Fast, messy, temporary.
+2. **Fork change** — commit to our fork (for `graphlient` or `graphql-client`). Appropriate for lasting fixes we own.
+3. **New version** — for `ecoportal-api` or `ecoportal-api-v2` (team-owned), cut a new version. For external forks, optionally contribute back upstream.
+
+Document the decision in `UPSTREAM.md` and `DECISIONS.md`.
+
+---
+
+## Session / Collaborator Setup (First Time on a Machine)
+
+When starting a session and `.ai-assistance/local_paths.md` does not exist, run this setup flow **before** any project work:
+
+1. Tell the developer: "I don't see a `local_paths.md` for your machine yet. This helps me cross-reference upstream and downstream gem code without fetching from remotes every time."
+
+2. For each dependency in the table below, ask: "Do you have `<gem>` cloned locally?"
+
+   | Gem | Remote |
+   |-----|--------|
+   | `ecoportal-api` | https://gitlab.ecoportal.co.nz/ecoportal/ecoportal-api.git |
+   | `ecoportal-api-v2` | https://gitlab.ecoportal.co.nz/oscar/ecoportal-api-v2.git |
+   | `graphlient` | https://github.com/rellampec/graphlient.git |
+   | `graphql-client` | https://github.com/rellampec/graphql-client.git |
+   | `eco-helpers` | https://gitlab.ecoportal.co.nz/oscar/script_api_helpers.git |
+
+3. For each one they have locally:
+   - In **Cowork**: ask them to connect the folder (via the folder picker), then record the confirmed path.
+   - In **Claude Code**: ask them to provide the path, or run `find ~ -name "<gemspec>" -maxdepth 6 2>/dev/null` to locate it.
+
+4. Once all available paths are collected, create `.ai-assistance/local_paths.md` from `.ai-assistance/local_paths.example.md`, filling in only the repos they confirmed.
+
+5. Also ask: "Do you have GitKraken MCP or GitLab MCP set up?" — if not, point them to `.ai-assistance/integrations/`.
+
+6. Confirm: "Done — I've saved your local paths. You can update `.ai-assistance/local_paths.md` any time if your setup changes."
+
+If a developer doesn't have a repo locally and the task requires reading it, offer: "I can fetch the relevant files from the remote — just note it'll be slower. Want me to proceed that way?"