natureco-cli 5.18.3 → 5.20.0

package/skills/request-refactor-plan/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: request-refactor-plan
+description: Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
+---
+
+This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.
+
+1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
+
+2. Explore the repo to verify their assertions and understand the current state of the codebase.
+
+3. Ask whether they have considered other options, and present other options to them.
+
+4. Interview the user about the implementation. Be extremely detailed and thorough.
+
+5. Hammer out the exact scope of the implementation. Work out what you plan to change and what you plan not to change.
+
+6. Look in the codebase to check for test coverage of this area of the codebase. If there is insufficient test coverage, ask the user what their plans for testing are.
+
+7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice to "make each refactoring step as small as possible, so that you can always see the program working."
+
+8. Create a GitHub issue with the refactor plan. Use the following template for the issue description:
+
+<refactor-plan-template>
+
+## Problem Statement
+
+The problem that the developer is facing, from the developer's perspective.
+
+## Solution
+
+The solution to the problem, from the developer's perspective.
+
+## Commits
+
+A LONG, detailed implementation plan. Write the plan in plain English, breaking down the implementation into the tiniest commits possible. Each commit should leave the codebase in a working state.
+
+## Decision Document
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this refactor.
+
+## Further Notes (optional)
+
+Any further notes about the refactor.
+
+</refactor-plan-template>

package/skills/research-compiler/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: research-compiler
+description: Compile research from multiple sources with annotations and synthesis
+category: Productivity
+---
+
+# Research Compiler
+
+## Overview
+Compile research from multiple sources with annotations and synthesis. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply research compiler best practices
+- When establishing processes or standards for your workflow
+- When training team members on research compiler
+- When automating or optimizing research compiler tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply research compiler for my current project
+Assistant: I'll help you apply research compiler step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration

package/skills/resolving-merge-conflicts/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: resolving-merge-conflicts
+description: "Use when you need to resolve an in-progress git merge/rebase conflict."
+---
+
+1. **See the current state** of the merge/rebase. Check git history, and the conflicting files.
+
+2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets.
+
+3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort`.
+
+4. Discover the project's **automated checks** and run them — typically typecheck, then tests, then format. Fix anything the merge broke.
+
+5. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased.

package/skills/responsive-design/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: responsive-design
+description: Build responsive UIs with mobile-first CSS, breakpoints, and adaptive layouts
+category: Software Development
+---
+
+# Responsive Design
+
+## Overview
+Build responsive UIs with mobile-first CSS, breakpoints, and adaptive layouts. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply responsive design best practices
+- When establishing processes or standards for your workflow
+- When training team members on responsive design
+- When automating or optimizing responsive design tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply responsive design for my current project
+Assistant: I'll help you apply responsive design step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration

package/skills/rest-api-patterns/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: rest-api-patterns
+description: Implement REST API patterns including pagination, filtering, HATEOAS, and idempotency
+category: Software Development
+---
+
+# Rest Api Patterns
+
+## Overview
+Implement REST API patterns including pagination, filtering, HATEOAS, and idempotency. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply rest api patterns best practices
+- When establishing processes or standards for your workflow
+- When training team members on rest api patterns
+- When automating or optimizing rest api patterns tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply rest api patterns for my current project
+Assistant: I'll help you apply rest api patterns step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration

package/skills/retrospectives/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: retrospectives
+description: Run retrospectives with start-stop-continue, sailboat, and 4L frameworks
+category: Planning & Execution
+---
+
+# Retrospectives
+
+## Overview
+Run retrospectives with start-stop-continue, sailboat, and 4L frameworks. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply retrospectives best practices
+- When establishing processes or standards for your workflow
+- When training team members on retrospectives
+- When automating or optimizing retrospectives tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply retrospectives for my current project
+Assistant: I'll help you apply retrospectives step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration

package/skills/risk-assessment/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: risk-assessment
+description: Assess project risks with probability-impact matrices, mitigation plans, and monitoring
+category: Planning & Execution
+---
+
+# Risk Assessment
+
+## Overview
+Assess project risks with probability-impact matrices, mitigation plans, and monitoring. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply risk assessment best practices
+- When establishing processes or standards for your workflow
+- When training team members on risk assessment
+- When automating or optimizing risk assessment tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply risk assessment for my current project
+Assistant: I'll help you apply risk assessment step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration

package/skills/roadmap-creation/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: roadmap-creation
+description: Create product roadmaps with themes, epics, timelines, and dependency mapping
+category: Planning & Execution
+---
+
+# Roadmap Creation
+
+## Overview
+Create product roadmaps with themes, epics, timelines, and dependency mapping. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply roadmap creation best practices
+- When establishing processes or standards for your workflow
+- When training team members on roadmap creation
+- When automating or optimizing roadmap creation tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply roadmap creation for my current project
+Assistant: I'll help you apply roadmap creation step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration

package/skills/running-claude-code-via-litellm-copilot/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: running-claude-code-via-litellm-copilot
+description: Use when routing Claude Code through a local LiteLLM proxy to GitHub Copilot, reducing direct Anthropic spend, configuring ANTHROPIC_BASE_URL or ANTHROPIC_MODEL overrides, or troubleshooting Copilot proxy setup failures such as model-not-found, no localhost traffic, or GitHub 401/403 auth errors.
+---
+
+## Overview
+
+Use this skill for the specific workaround where Claude Code keeps its Anthropic-shaped client behavior, but the actual backend traffic is sent to a local LiteLLM proxy and then forwarded to GitHub Copilot.
+
+Treat this as an advanced workaround, not an officially guaranteed GitHub workflow. Help the user succeed technically, but do not promise GitHub support, policy approval, or long-term compatibility.
+
+This skill is guidance-first but execution-aware:
+
+- If the user wants explanation only, provide the smallest correct set of files, commands, and checks.
+- If the user wants real setup work on the current machine, inspect first and adapt commands to the active shell and OS.
+- Pause before persistent edits such as `~/.claude/settings.json` or shell profile files.
+
+Read [`references/doc-verified-notes.md`](./references/doc-verified-notes.md) before answering if you need to justify which parts come from the article and which parts were tightened against current LiteLLM docs.
+
+## When To Use
+
+Use this skill when the user wants any of the following:
+
+- Claude Code to run against GitHub Copilot through LiteLLM
+- lower direct Anthropic API spending while keeping the Claude Code workflow
+- a local `config.yaml` for LiteLLM's GitHub Copilot provider
+- `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL`, or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` setup
+- help understanding GitHub device authorization during LiteLLM startup
+- help with model mismatch, 404-like errors, no requests reaching LiteLLM, or GitHub 401/403 failures
+
+Do not use this skill for:
+
+- deciding whether the workaround is allowed by GitHub terms
+- general LiteLLM architecture unrelated to Claude Code plus Copilot
+- direct Anthropic API setup with no Copilot or LiteLLM component
+
+## Core Rules
+
+1. Lead with a short compliance caveat.
+   Explain that this is a workaround based on a local proxy path, not a GitHub-promoted workflow, and the user must evaluate the latest Copilot terms and limits for themselves.
+2. Prefer the minimum viable path first.
+   Start with temporary environment variables and a local `config.yaml` unless the user explicitly wants a persistent setup.
+3. Keep `ANTHROPIC_MODEL` and LiteLLM `model_name` identical.
+   Exact string match matters more than clever explanation.
+4. Treat `ANTHROPIC_AUTH_TOKEN` as a local placeholder.
+   Claude Code expects a non-empty value locally, but it is not the GitHub Copilot credential and should not be presented as a reusable secret.
+5. Never overwrite `~/.claude/settings.json` wholesale.
+   Merge only the needed `env` keys and preserve unrelated settings.
+
+## Workflow
+
+### 1. Preflight
+
+Check these first when the user wants real setup work:
+
+- `claude --help` succeeds
+- `uv --version` or `pip --version` succeeds
+- the user has GitHub Copilot access
+- the intended LiteLLM port is available, usually `4000`
+
+If the user only wants instructions, state the prerequisites instead of running them.
+
+### 2. Choose Temporary vs Persistent Setup
+
+Use this rule:
+
+- Temporary setup: preferred default for first-time setup, debugging, and low-risk trials
+- Persistent setup: only when the user explicitly wants the proxy path to apply every time Claude Code starts
+
+For persistent setup, confirm the target file and then merge keys into `~/.claude/settings.json`. Do not replace the file contents.
+
+### 3. Create LiteLLM `config.yaml`
+
+Start from the article's flow, but keep the provider naming aligned with LiteLLM docs:
+
+```yaml
+model_list:
+  - model_name: claude-opus-4.5
+    litellm_params:
+      model: github_copilot/claude-opus-4.5
+      drop_params: true
+```
+
+Explain the fields:
+
+- `model_name`: the logical name Claude Code will request
+- `model`: the LiteLLM provider route, using `github_copilot/<model>`
+- `drop_params: true`: strips unsupported Anthropic-specific fields before forwarding to Copilot
+
+If the user wants a different Copilot-backed model, keep the same pattern:
+
+```yaml
+model_list:
+  - model_name: <logical-name>
+    litellm_params:
+      model: github_copilot/<copilot-model>
+      drop_params: true
+```
+
+Do not hardcode extra headers into the default path unless the user already hit a rejection that suggests header overrides are needed.
+
+### 4. Install and Start LiteLLM
+
+Preferred install:
+
+```bash
+uv tool install "litellm[proxy]"
+```
+
+Fallback:
+
+```bash
+pip install "litellm[proxy]"
+```
+
+Start the proxy from the directory containing `config.yaml`:
+
+```bash
+litellm --config config.yaml --port 4000
+```
+
+Tell the user to keep that terminal open because the logs are the fastest truth source during verification.
+
+### 5. Explain GitHub Device Authorization
+
+On the first successful request to the GitHub Copilot provider, LiteLLM may open a device authorization flow:
+
+1. LiteLLM prints a verification URL and device code
+2. the user opens the URL and approves the request
+3. LiteLLM stores the resulting credential locally for future use
+
+Optional token-location overrides exist:
+
+- `GITHUB_COPILOT_TOKEN_DIR`
+- `GITHUB_COPILOT_ACCESS_TOKEN_FILE`
+
+Only mention these when the user needs custom token storage, shared environments, or troubleshooting around expired or misplaced credentials.
+
+### 6. Configure Claude Code
+
+For a temporary PowerShell session:
+
+```powershell
+$env:ANTHROPIC_AUTH_TOKEN = "sk-any-string"
+$env:ANTHROPIC_BASE_URL = "http://localhost:4000"
+$env:ANTHROPIC_MODEL = "claude-opus-4.5"
+$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"
+claude
+```
+
+For a temporary Bash or Zsh session:
+
+```bash
+export ANTHROPIC_AUTH_TOKEN="sk-any-string"
+export ANTHROPIC_BASE_URL="http://localhost:4000"
+export ANTHROPIC_MODEL="claude-opus-4.5"
+export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
+claude
+```
+
+For persistent configuration, merge these keys into `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_AUTH_TOKEN": "sk-any-string",
+    "ANTHROPIC_BASE_URL": "http://localhost:4000",
+    "ANTHROPIC_MODEL": "claude-opus-4.5",
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
+  }
+}
+```
+
+Merge-safe behavior:
+
+- if the file does not exist, create it
+- if it exists, preserve all unrelated top-level keys
+- preserve existing `env` entries that are unrelated to this workflow
+- update only the four keys above
+- if the JSON is malformed, stop and report the parse problem instead of overwriting the file
+
+### 7. Verify The Request Chain
+
+Use two terminals when possible:
+
+- Terminal A runs LiteLLM
+- Terminal B runs `claude`
+
+Ask for one small prompt such as a short script or code review request, then verify:
+
+- Claude Code starts normally
+- LiteLLM logs show an inbound request
+- LiteLLM logs indicate the GitHub Copilot model route, typically `github_copilot/<model>`
+
+The healthy path is:
+
+```text
+Claude Code -> LiteLLM -> GitHub Copilot -> LiteLLM -> Claude Code
+```
+
+### 8. Troubleshooting
+
+If Claude Code reports model-not-found, 404-like failures, or LiteLLM says the model does not exist:
+
+- compare `ANTHROPIC_MODEL` to `model_name` exactly
+- check case, punctuation, and hyphens
+
+If LiteLLM never receives a request:
+
+- confirm `ANTHROPIC_BASE_URL` points to <http://localhost:4000>
+- confirm LiteLLM is still running on that port
+- confirm the environment variables were set in the same shell session that launched `claude`
+- check local firewall or port conflicts if the URL is correct but still silent
+
+If LiteLLM reaches GitHub Copilot but gets 401 or 403 responses:
+
+- repeat the device authorization flow by restarting LiteLLM and retrying
+- confirm the GitHub account still has Copilot access
+- if custom token-directory variables are set, verify they point to the intended files
+
+## Advanced Fallback: Header Overrides
+
+The article uses explicit Copilot-style headers. Current LiteLLM docs expose GitHub Copilot as a provider and also document header override support.
+
+Only reach for explicit `extra_headers` when:
+
+- the basic provider flow reaches Copilot but still needs client-shape overrides
+- the user already has evidence that a specific environment behaves better with editor-style headers
+
+Example fallback:
+
+```yaml
+model_list:
+  - model_name: claude-opus-4.5
+    litellm_params:
+      model: github_copilot/claude-opus-4.5
+      drop_params: true
+      extra_headers:
+        editor-version: "vscode/1.85.1"
+        editor-plugin-version: "copilot/1.155.0"
+        Copilot-Integration-Id: "vscode-chat"
+        user-agent: "GithubCopilot/1.155.0"
+```
+
+Present this as an advanced fallback, not the universal default.
+
+## Output Checklist
+
+When answering a real user request with this skill, include:
+
+- the brief compliance caveat
+- the exact `config.yaml` or the delta to apply
+- shell-appropriate commands
+- whether the setup is temporary or persistent
+- the verification path
+- the smallest relevant troubleshooting section if something failed
+
+## Safety Reminders
+
+- Do not state that GitHub officially supports this workaround.
+- Do not imply that a dummy `ANTHROPIC_AUTH_TOKEN` is a real Copilot credential.
+- Do not recommend replacing `~/.claude/settings.json` wholesale.
+- Do not present stale model names as guaranteed current availability; if the user asks for a specific model, keep the `github_copilot/<model>` pattern and note that Copilot-exposed model availability may change.

package/skills/scaffold-exercises/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: scaffold-exercises
+description: Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
+---
+
+# Scaffold Exercises
+
+Create exercise directory structures that pass `pnpm ai-hero-cli internal lint`, then commit with `git commit`.
+
+## Directory naming
+
+- **Sections**: `XX-section-name/` inside `exercises/` (e.g., `01-retrieval-skill-building`)
+- **Exercises**: `XX.YY-exercise-name/` inside a section (e.g., `01.03-retrieval-with-bm25`)
+- Section number = `XX`, exercise number = `XX.YY`
+- Names are dash-case (lowercase, hyphens)
+
+## Exercise variants
+
+Each exercise needs at least one of these subfolders:
+
+- `problem/` - student workspace with TODOs
+- `solution/` - reference implementation
+- `explainer/` - conceptual material, no TODOs
+
+When stubbing, default to `explainer/` unless the plan specifies otherwise.
+
+## Required files
+
+Each subfolder (`problem/`, `solution/`, `explainer/`) needs a `readme.md` that:
+
+- Is **not empty** (must have real content, even a single title line works)
+- Has no broken links
+
+When stubbing, create a minimal readme with a title and a description:
+
+```md
+# Exercise Title
+
+Description here
+```
+
+If the subfolder has code, it also needs a `main.ts` (>1 line). But for stubs, a readme-only exercise is fine.
+
+## Workflow
+
+1. **Parse the plan** - extract section names, exercise names, and variant types
+2. **Create directories** - `mkdir -p` for each path
+3. **Create stub readmes** - one `readme.md` per variant folder with a title
+4. **Run lint** - `pnpm ai-hero-cli internal lint` to validate
+5. **Fix any errors** - iterate until lint passes
+
+## Lint rules summary
+
+The linter (`pnpm ai-hero-cli internal lint`) checks:
+
+- Each exercise has subfolders (`problem/`, `solution/`, `explainer/`)
+- At least one of `problem/`, `explainer/`, or `explainer.1/` exists
+- `readme.md` exists and is non-empty in the primary subfolder
+- No `.gitkeep` files
+- No `speaker-notes.md` files
+- No broken links in readmes
+- No `pnpm run exercise` commands in readmes
+- `main.ts` required per subfolder unless it's readme-only
+
+## Moving/renaming exercises
+
+When renumbering or moving exercises:
+
+1. Use `git mv` (not `mv`) to rename directories - preserves git history
+2. Update the numeric prefix to maintain order
+3. Re-run lint after moves
+
+Example:
+
+```bash
+git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings
+```
+
+## Example: stubbing from a plan
+
+Given a plan like:
+
+```
+Section 05: Memory Skill Building
+- 05.01 Introduction to Memory
+- 05.02 Short-term Memory (explainer + problem + solution)
+- 05.03 Long-term Memory
+```
+
+Create:
+
+```bash
+mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer
+mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution}
+mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer
+```
+
+Then create readme stubs:
+
+```
+exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# Introduction to Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# Long-term Memory"
+```