opnsense-openapi 0.2.0__tar.gz → 0.3.0__tar.gz

opnsense_openapi-0.3.0/.claude/CLAUDE.md

@@ -0,0 +1,64 @@
+@../AGENTS.md
+
+# BASIC CLAUDE INSTRUCTIONS
+
+Claude's #1 priority is to use tokens efficiently:
+- Keep responses brief and to the point
+- Use local tools (Grep, Read, Edit) as a priority over Task tool
+- Only use the Task tool when necessary
+- Always inform user and ask for consent before starting sub agents
+
+Examples of when to use local tools instead of Task tool:
+- Updating types in function declarations
+- Creating or updating documentation
+- Renaming variables, functions, etc.
+- Simple code refactoring
+
+# TODOWRITE USAGE (MANDATORY)
+
+When creating new code (functions, modules, commands, features), Claude MUST use TodoWrite to plan ALL steps:
+
+**Required todo items for any code task:**
+1. Implementation file(s)
+2. Test file(s) - NEVER skip this
+3. Run `doit check` to verify
+4. Manual verification/testing
+
+**Why this is mandatory:**
+- Removes judgment calls about whether to write tests
+- Makes testing systematic, not optional
+- Ensures complete implementation (code + tests + validation)
+- Provides visibility to user about progress
+
+**Examples of when to use TodoWrite:**
+- Creating new Python modules or functions
+- Adding CLI commands or API endpoints
+- Implementing new features or bug fixes
+- Any task involving writing new Python code
+
+**Example todo list for "create new CLI command":**
+- [ ] Create src/opnsense_openapi/cli.py
+- [ ] Create tests/test_cli.py with comprehensive tests
+- [ ] Update pyproject.toml (if needed)
+- [ ] Run doit check to verify all tests pass
+- [ ] Test command manually
+
+# DEVELOPMENT WORKFLOW (MANDATORY)
+
+Before making ANY changes, Claude MUST:
+1. Read AGENTS.md and locate the "## Development Workflow" section
+2. Verify the workflow: Issue → Branch → Commit → PR → Merge
+3. **NEVER commit directly to main**
+4. Ensure a GitHub Issue exists for the task
+5. Create a branch linked to the issue
+6. Work on the branch, then create a PR
+
+# COMMIT WORKFLOW (MANDATORY)
+
+When asked to create a commit or PR, Claude MUST:
+1. Read AGENTS.md and locate the "## Commit Guidelines" section
+2. Review the commit message format rules under that section
+3. Draft commit message following the exact format specified
+4. Use /commit-commands:commit (not Bash directly)
+
+NO EXCEPTIONS. If AGENTS.md has fallen out of context, READ IT FIRST.

opnsense_openapi-0.3.0/.claude/agents/implement-worker.md

@@ -0,0 +1,67 @@
+---
+name: implement-worker
+description: >-
+  Performs the implementation step of the /implement workflow after the
+  plan comment exists and the branch is created. Reads project rules,
+  fetches the plan, edits files, writes tests, and runs `doit check`.
+  Do NOT invoke directly — /implement drives this subagent.
+tools: Read, Write, Edit, Glob, Grep, Bash, TodoWrite
+permissionMode: default
+---
+
+You implement a GitHub issue's approved plan on an already-created branch. The parent `/implement` command has verified preconditions and created the branch; your job is to read the rules, fetch the plan, edit files, write tests, run `doit check`, and return a summary.
+
+## Inputs from the parent
+
+The parent prompt will provide:
+
+- The **issue number** (so you can fetch the plan).
+- The **branch name** (for context only — you will not switch branches).
+- Any **issue-specific notes** or scope clarifications.
+
+## Steps
+
+### 1. Read the project rules
+
+- Read `AGENTS.md` — understand workflow, conventions, code style, and testing guidelines.
+- Read `.claude/CLAUDE.md` — understand TodoWrite requirements.
+
+### 2. Fetch the implementation plan
+
+Retrieve all comments and find the one whose body has a heading line starting with `Implementation Plan for`:
+
+```bash
+gh api repos/{owner}/{repo}/issues/<issue-number>/comments --jq '.[] | select(.body | test("^#+ Implementation Plan for"; "m")) | .body'
+```
+
+- If multiple plan comments exist, use the most recent one.
+- Parse the plan to extract the file list and test plan.
+
+### 3. Implement the plan
+
+- Follow the plan step by step.
+- Create implementation files.
+- Create test files — this is MANDATORY per AGENTS.md. Never skip tests when there is Python code to test.
+- Follow existing code patterns and conventions.
+- All new code must be type-annotated (mypy strict).
+
+### 4. Run validation
+
+- Run: `doit check`
+- If checks fail, fix the issues and re-run.
+- Do NOT give up after the first failure — investigate and fix.
+
+### 5. Return a summary
+
+Report to the parent:
+
+- Files created/modified with brief descriptions.
+- Test results (pass/fail counts).
+- Any deviations from the plan and why.
+
+## Constraints
+
+- **Do NOT switch branches.** The parent `/implement` command has already created and checked out the correct branch.
+- **Do NOT commit.** Committing is handled by the parent's `/finalize` step, not by you.
+- **Do NOT enter plan mode.** Do not call `EnterPlanMode`. You run with `permissionMode: default` so you can edit files directly.
+- **All new code must be type-annotated** (mypy strict mode is enforced by `doit check`).

opnsense_openapi-0.3.0/.claude/commands/close-issue.md

@@ -0,0 +1,86 @@
+# Close Issue
+
+Close GitHub issue #$ARGUMENTS after verifying its PR has been merged, and handle related issues.
+
+## Instructions
+
+### Step 1: Verify the PR is merged
+
+1. **Find PRs that reference this issue:**
+   ```bash
+   gh pr list --state merged --search "$ARGUMENTS" --json number,title,body,mergedAt
+   ```
+   Also check:
+   ```bash
+   gh pr list --state merged --search "Addresses #$ARGUMENTS" --json number,title,body,mergedAt
+   ```
+
+2. **If no merged PR is found:**
+   - Tell the user no merged PR was found for issue #$ARGUMENTS
+   - Ask if they want to proceed anyway or check the PR status
+   - Do NOT close the issue without a merged PR unless the user explicitly confirms
+
+### Step 2: Update issue task checkboxes
+
+1. **Fetch the current issue body:**
+   ```bash
+   gh issue view $ARGUMENTS --json body
+   ```
+
+2. **Check for task checkboxes** (`- [ ]` items) in the issue body.
+
+3. **If task checkboxes exist:**
+   - Review each task against the merged PR changes
+   - Mark completed tasks as `- [x]`
+   - Update the issue body with checked-off tasks:
+     ```bash
+     gh issue edit $ARGUMENTS --body "<updated body>"
+     ```
+   - Tell the user which tasks were marked complete and which remain unchecked (if any)
+
+4. **If unchecked tasks remain**, ask the user:
+   > "Some tasks in issue #$ARGUMENTS are not yet complete: <list>. Close anyway?"
+   - Wait for user confirmation before proceeding
+
+### Step 3: Close the primary issue
+
+1. **Add a closing comment:**
+   ```bash
+   gh issue comment $ARGUMENTS --body "Addressed in PR #<pr-number>"
+   ```
+
+2. **Close the issue:**
+   ```bash
+   gh issue close $ARGUMENTS
+   ```
+
+3. **Confirm** to the user that issue #$ARGUMENTS has been closed.
+
+### Step 4: Find and handle related issues
+
+1. **Scan all merged PRs** for this issue to find referenced issues:
+   ```bash
+   gh pr view <pr-number> --json body,comments
+   ```
+   Search the PR body and comments for patterns like:
+   - `Addresses #N`
+   - `Part of #N`
+   - `Related to #N`
+   - `Closes #N`
+   - `Fixes #N`
+   - `References #N`
+   - `#N` (bare issue references)
+
+   Exclude the primary issue (#$ARGUMENTS) from this list.
+
+2. **For each related issue found:**
+   - Fetch its current state: `gh issue view <N> --json state,title`
+   - Skip issues that are already closed
+   - For each **open** related issue, ask the user:
+     > "Issue #N: <title> is still open and was referenced in PR #<pr>. Would you like to close it?"
+   - If the user says yes, close it with comment "Addressed in PR #<pr-number>"
+   - If the user says no, move to the next one
+
+3. **Summary:** After processing all related issues, show the user a summary:
+   - Issues closed in this session
+   - Issues left open

opnsense_openapi-0.3.0/.claude/commands/finalize.md

@@ -0,0 +1,86 @@
+# Finalize
+
+Finalize the current branch: update documentation, commit changes, and create a PR.
+
+## Instructions
+
+This command operates on the current branch. It assumes implementation and review are complete.
+
+### Step 1: Gather context
+
+In the main context (lightweight reads):
+
+1. **Detect the current branch and linked issue:**
+   ```bash
+   git branch --show-current
+   ```
+   Extract the issue number from the branch name (e.g., `feat/245-description` → `#245`).
+   - If on `main`, tell the user they need to be on a feature branch and stop.
+
+2. **Get the issue details:**
+   ```bash
+   gh issue view <number> --json title,labels
+   ```
+
+3. **Check for uncommitted changes:**
+   ```bash
+   git status --short
+   ```
+   - If there are unstaged or uncommitted changes (e.g., from the review/fix cycle), list them for the user
+   - These will be included in the commit — confirm with the user that all changes should be included
+
+4. **Check what changed vs main:**
+   ```bash
+   git diff main --stat
+   ```
+
+### Step 2: Spawn a finalization agent
+
+Use the Task tool with `subagent_type: "general-purpose"` and provide it with the branch name, issue number, issue title, labels, and the list of changed files. The agent should:
+
+1. **Read the project rules:**
+   - Read `AGENTS.md` — understand commit guidelines, PR checklist, ADR requirements
+   - Read `.github/CONTRIBUTING.md` — understand commit format
+   - Read `.github/pull_request_template.md` — understand PR structure
+
+2. **Check documentation needs:**
+   - Review the changed files — do any user-facing behaviors change?
+   - If yes, identify which docs in `docs/` need updating and update them
+   - Check `docs/decisions/` for related ADRs that need updating
+
+3. **Check ADR needs:**
+   - If the issue has the `needs-adr` label, create an ADR using `doit adr`
+   - If the changes relate to an existing ADR, update it with the issue link
+   - Every ADR must link to documentation in `docs/`
+
+4. **Run final validation:**
+   - Run: `doit check`
+   - ALL checks must pass before proceeding
+
+5. **Draft the PR description** and write it to a temp file:
+   - Read `.github/pull_request_template.md` for structure
+   - Run `mkdir -p tmp/agents/claude` to ensure the directory exists
+   - Write the PR body to `tmp/agents/claude/pr-body-issue-<n>.md`
+   - The body MUST include `Addresses #<issue-number>`
+
+6. **Return** a summary of:
+   - Documentation changes made (if any)
+   - ADR changes made (if any)
+   - Suggested commit message following conventional format: `<type>: <subject>`
+   - Suggested PR title following conventional format: `<type>: <subject>`
+   - Path to the PR body file (`tmp/agents/claude/pr-body-issue-<n>.md`)
+
+### Step 3: Commit and create PR
+
+After the agent returns, in the main context:
+
+1. **Show the user** the suggested commit message and PR description
+2. **Ask the user** for approval to commit and create the PR
+3. **Only after user confirms:**
+   - Stage files: `git add <specific files>` (include all changed files from implementation and review/fix cycle)
+   - Commit with the approved message
+   - Create PR: `doit pr --title="<type>: <subject>" --body-file=tmp/agents/claude/pr-body-issue-<n>.md`
+   - Delete the temp file: `rm tmp/agents/claude/pr-body-issue-<n>.md`
+4. **Report** the PR URL to the user
+
+**IMPORTANT:** Do NOT commit or create the PR without explicit user confirmation.

opnsense_openapi-0.3.0/.claude/commands/gemini-review.md

@@ -0,0 +1,42 @@
+# Gemini PR Review
+
+Invoke Gemini CLI to review the current branch's pull request and post findings to the PR.
+
+## Instructions
+
+This command runs in the main conversation context. It invokes Gemini CLI
+non-interactively to get a code review, then posts the findings to the PR.
+
+### Step 1: Verify the PR exists
+
+```bash
+gh pr view --json number,title,headRefName
+```
+
+- If no PR exists for the current branch, tell the user and stop.
+- Save the PR number for later use.
+
+### Step 2: Invoke Gemini CLI
+
+Run Gemini in non-interactive mode:
+
+```bash
+gemini -p "/review-pr" --yolo 2>/dev/null
+```
+
+- Capture the stdout output — this is Gemini's review in markdown format.
+- If Gemini fails or produces empty output, report the error and stop.
+
+### Step 3: Post the review to the PR
+
+Post Gemini's review as a PR comment:
+
+```bash
+gh pr comment <PR_NUMBER> --body "<gemini review output>"
+```
+
+### Step 4: Report to user
+
+Tell the user:
+- Gemini's review has been posted to PR #<number>
+- Provide a brief summary of Gemini's findings (verdict, critical issues if any)

opnsense_openapi-0.3.0/.claude/commands/implement.md

@@ -0,0 +1,81 @@
+# Implement Issue
+
+Implement the plan for GitHub issue #$ARGUMENTS.
+
+## Instructions
+
+The implementation is delegated to a sub-agent (Task tool) so raw tool output stays out of the main conversation context. The agent does the coding; you receive the summary for user review.
+
+**Plan-mode trap:** parent plan-mode state propagates to the spawned sub-agent mid-execution and freezes it after its first non-readonly action (typically the first `Write`). Check your Claude Code status line before running — if it shows "plan mode", exit before invoking.
+
+### Step 1: Validate preconditions
+
+1. **Verify the issue exists and is open:**
+   ```bash
+   gh issue view $ARGUMENTS --json number,title,state,labels
+   ```
+   - If the issue does not exist or is closed, tell the user and stop.
+
+2. **Verify a plan comment exists:**
+   Fetch all comments and search for the plan header:
+   ```bash
+   gh api repos/{owner}/{repo}/issues/$ARGUMENTS/comments --jq '.[].body' | grep -E "^#+ Implementation Plan for"
+   ```
+   - If no plan comment is found, tell the user:
+     > "No implementation plan found for issue #$ARGUMENTS. Run `/plan-issue $ARGUMENTS` first."
+   - Stop and wait for the user.
+
+3. **Check current branch state:**
+   ```bash
+   git branch --show-current
+   git status --short
+   ```
+   - If already on a branch matching `*/$ARGUMENTS-*` (e.g., `feat/$ARGUMENTS-description`):
+     - Tell the user you're resuming work on the existing branch
+     - Skip branch creation (Step 2)
+     - If there are uncommitted changes, warn the user and ask how to proceed
+   - If on `main` or a different branch: proceed to Step 2
+
+### Step 2: Create the branch
+
+Only if not already on the correct branch:
+
+1. Fetch the issue to determine the branch type:
+   ```bash
+   gh issue view $ARGUMENTS --json title,labels
+   ```
+2. Determine branch type from labels:
+   - `enhancement` → `feat`
+   - `bug` → `fix`
+   - `refactor` → `refactor`
+   - `documentation` → `docs`
+   - `chore` → `chore`
+   - Default → `issue`
+3. Create and switch to branch:
+   ```bash
+   git checkout main && git pull
+   git checkout -b <type>/$ARGUMENTS-<short-description>
+   ```
+
+### Step 3: Spawn the implementation subagent
+
+Use the Task tool with `subagent_type: "implement-worker"`. In the prompt, pass:
+
+- The issue number (so the subagent can fetch the plan).
+- The branch name (for context; the subagent will not switch branches).
+- Any issue-specific notes or scope clarifications.
+
+The subagent carries its own system prompt covering project rules, plan fetch, implementation, and validation — this command does not repeat them. The subagent has `permissionMode: default`, which (per Claude Code's sub-agent precedence rules) should override parent plan mode for operations inside the subagent's context.
+
+### Step 4: Present changes to user
+
+After the agent returns, show the user:
+- Summary of what was implemented
+- Files changed
+- Test results
+- Any issues or deviations from the plan
+
+Tell the user:
+- Review the changes and test as needed
+- Discuss any fixes directly in conversation (no command needed)
+- When satisfied, use `/finalize` to commit and create a PR

opnsense_openapi-0.3.0/.claude/commands/plan-both.md

@@ -0,0 +1,107 @@
+# Dual-Agent Plan
+
+Both Claude and Gemini independently create implementation plans for GitHub issue
+#$ARGUMENTS in separate contexts, then the user discusses the synthesized plan
+with Claude in the current conversation.
+
+## Instructions
+
+### Step 1: Validate the issue
+
+```bash
+gh issue view $ARGUMENTS --json number,title,state,labels
+```
+
+- If the issue does not exist, tell the user and stop.
+- If the issue is closed, tell the user and ask if they want to reopen it or stop.
+
+### Step 2: Check for existing plans
+
+```bash
+gh issue view $ARGUMENTS --json comments --jq '.comments[].body' | grep -lE "^#+ Implementation Plan for"
+```
+
+- If plan comments already exist, warn the user:
+  > "Issue #$ARGUMENTS already has implementation plan comments. Continuing will post new ones. Proceed?"
+- Wait for user confirmation before continuing.
+
+### Step 3: Generate both plans in parallel (separate contexts)
+
+Both plans MUST be generated in isolated contexts so neither influences the other.
+
+**Claude's plan** — use the Task tool to spawn a subagent:
+
+Prompt the subagent with:
+> Read AGENTS.md and .claude/CLAUDE.md for project standards.
+> Fetch issue #$ARGUMENTS via `gh issue view $ARGUMENTS --json title,body,labels,assignees`.
+> Explore the codebase to understand relevant files, patterns, and tests.
+> Create an implementation plan in this exact format:
+>
+> ## Implementation Plan for #<number>: <title>
+> ### Overview
+> ### Files to Create/Modify
+> ### Test Plan
+> ### Documentation
+> ### Validation
+> ### Risks and Considerations
+>
+> End with: `---` followed by `*Plan by: Claude* | *Date: <today's date>*`
+>
+> Output ONLY the plan markdown.
+
+Save the subagent's output as Claude's plan.
+
+**Gemini's plan** — invoke Gemini CLI non-interactively:
+
+```bash
+gemini -p "/plan-issue $ARGUMENTS" --yolo 2>/dev/null
+```
+
+Capture the stdout output as Gemini's plan.
+
+Run both in parallel if possible. If either fails or produces empty output,
+report the error and ask the user if they want to continue with the other
+agent's plan only or retry.
+
+### Step 4: Post both plans to the issue
+
+Post each plan as a separate comment on the issue:
+
+```bash
+gh issue comment $ARGUMENTS --body "<claude plan>"
+gh issue comment $ARGUMENTS --body "<gemini plan>"
+```
+
+### Step 5: Synthesize the final plan
+
+Read both plans and create a synthesized final plan that:
+- Combines the best elements from both plans
+- Resolves any conflicts or contradictions between them
+- Notes where the plans agreed (higher confidence)
+- Notes where they diverged (needs discussion)
+- Preserves the standard plan format (Overview, Files, Test Plan, Documentation, Validation)
+
+Add the signature:
+```
+---
+*Synthesized Plan by: Claude (from Claude + Gemini input)* | *Date: <today's date>*
+```
+
+### Step 6: Review with user
+
+Present the synthesized plan to the user for discussion:
+- Highlight areas where the two agents disagreed
+- Ask for feedback and iterate as needed
+- Do NOT post the synthesized plan until the user approves it
+
+### Step 7: Post the approved synthesized plan
+
+Only after the user approves:
+
+```bash
+gh issue comment $ARGUMENTS --body "<synthesized plan>"
+```
+
+Tell the user:
+- All three plans (Claude, Gemini, Synthesized) have been posted to issue #$ARGUMENTS
+- When ready, use `/implement $ARGUMENTS` to start implementation

opnsense_openapi-0.3.0/.claude/commands/plan-issue.md

@@ -0,0 +1,94 @@
+# Plan Issue
+
+Plan the implementation for GitHub issue #$ARGUMENTS.
+
+## Instructions
+
+This command runs in the main conversation context (NOT in a subagent) so the user can ask questions, discuss tradeoffs, and refine the plan interactively.
+
+### Step 1: Go into Plan Mode
+
+### Step 2: Validate the issue
+
+1. **Verify the issue exists and is open:**
+   ```bash
+   gh issue view $ARGUMENTS --json number,title,state,labels
+   ```
+   - If the issue does not exist, tell the user and stop.
+   - If the issue is closed, tell the user and ask if they want to reopen it or stop.
+
+2. **Check for an existing plan comment:**
+   ```bash
+   gh issue view $ARGUMENTS --json comments --jq '.comments[].body' | grep -lE "^#+ Implementation Plan for"
+   ```
+   - If a plan comment already exists, warn the user:
+     > "Issue #$ARGUMENTS already has an implementation plan comment. Continuing will post a new one. Proceed?"
+   - Wait for user confirmation before continuing.
+
+### Step 3: Read the project rules
+
+- Read `AGENTS.md` — understand workflow, conventions, and commit guidelines
+- Read `.claude/CLAUDE.md` — understand TodoWrite requirements
+
+### Step 4: Fetch the issue details
+
+- Run: `gh issue view $ARGUMENTS --json title,body,labels,assignees`
+- Parse the issue body to understand what needs to be done
+- Check if the issue has the `needs-adr` label
+
+### Step 5: Explore the codebase
+
+- Identify which files, modules, and tests are relevant
+- Understand existing patterns and conventions in the affected areas
+- Check for related ADRs in `docs/decisions/`
+- If anything is ambiguous or there are multiple valid approaches, **ask the user** before deciding
+
+### Step 6: Draft the plan and iterate with the user (inside plan mode)
+
+**Stay in plan mode for this entire step.** Draft the plan, present it, and iterate until the user approves — all before leaving plan mode.
+
+1. Present the plan to the user. The plan MUST include these sections:
+
+   ```
+   ## Implementation Plan for #<number>: <title>
+
+   ### Overview
+   Brief description of what will be done.
+
+   ### Files to Create/Modify
+   - [ ] `path/to/file.py` — description of changes
+   - [ ] `tests/test_file.py` — description of test coverage
+
+   ### Test Plan
+   - [ ] Test case 1: description
+   - [ ] Test case 2: description
+
+   ### Documentation
+   - [ ] Any docs that need updating
+   - [ ] ADR needed: yes/no (if yes, brief description)
+
+   ### Validation
+   - [ ] `doit check` passes
+   - [ ] Manual verification steps
+   ```
+
+2. Use `AskUserQuestion` to ask for feedback on the plan.
+3. Discuss alternatives, answer questions, and adjust the plan as the user requests.
+4. Keep iterating inside plan mode until the user explicitly says the plan is approved.
+5. Do NOT leave plan mode until the user confirms approval.
+
+### Step 7: Leave plan mode
+
+Once the user has approved the plan, leave plan mode. The `ExitPlanMode` approval prompt means: **"Post the approved plan to the issue."** The plan has already been reviewed and approved by the user during Step 6.
+
+### Step 8: Post the approved plan to the issue
+
+Post the approved plan as a comment on the issue:
+
+```bash
+gh issue comment $ARGUMENTS --body "<approved plan>"
+```
+
+Tell the user:
+- The plan has been posted as a comment on issue #$ARGUMENTS
+- When ready, use `/implement $ARGUMENTS` to start implementation