complexipy 6.2.0__tar.gz → 7.0.1__tar.gz

complexipy-7.0.1/.agents/skills/create-issue/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: create-issue
+description: >
+    Create a well-formed GitHub issue with a clean title and body. Invoke
+    whenever the user asks to create an issue, file a bug report, open a
+    feature request, or report something via GitHub CLI. Encodes the lessons
+    learned from bad issue drafts: GitHub renders every single newline as a
+    hard line break, internal working-doc jargon does not belong in public
+    issues, and titles must match the repo's existing conventions.
+---
+
+# Create GitHub Issue
+
+Creates a GitHub issue using `gh issue create`. Produces a public, well-formatted
+title and body, then verifies the rendered result.
+
+## Before Writing
+
+1. **Search for existing issues first.** `gh search issues --repo <owner>/<repo> "<topic>"` — never duplicate an open or closed issue that already covers the topic. Reference it instead.
+1. **Check the repo's conventions.** `gh issue list --repo <owner>/<repo> --state all --limit 20` and skim titles/labels/body structure of recent issues. Match that style.
+
+## Title Rules
+
+- **No internal prefixes.** Never `TASK 12: ...`, `TASK-123: ...`, or working-document IDs — those mean nothing to a public audience.
+- Descriptive, matching the repo's existing style (imperative or noun phrase, e.g. "Add --fix to apply machine-applicable suggestions", "Report when ignore comments can be removed").
+- One short sentence; no trailing period.
+- If the repo uses labels (bug / enhancement / feature request), add the matching ones with `--label`.
+
+## Body Rules — the ones that actually bite
+
+1. **GitHub renders EVERY single newline in an issue body as a hard line break (`<br>`).** There is no soft-wrap collapsing. Therefore:
+   - Each paragraph is **one continuous line** — never wrap text at 80 columns.
+   - List items each go on **one line** (no indented continuation lines).
+   - Separate blocks (paragraphs, lists, headings) with a single blank line.
+   - Only fenced code blocks may contain real newlines — use them for multi-line content.
+2. **Public tone, no internal context.** No "Task N", no references to private working docs (HANDOFF.md, backlog files, agent notes), no abbreviations only the team understands. A stranger must be able to act on the issue with only the repo in front of them. Say what the rule/feature is by its public name (rule IDs like C007 are fine — they're in the docs).
+3. **Structure the body** with `##` sections. A proven shape:
+
+   ```markdown
+   ## Problem
+   <what is broken or missing, from a user perspective>
+
+   ## The idea / Why this is nontrivial
+   <proposed change; for complex work, the constraints that make it hard>
+
+   ## Open questions
+   - <decisions that need input before implementing>
+
+   ## Acceptance criteria (draft)
+   - <verifiable outcomes>
+   ```
+
+4. **Write the body to a temp file** (`/tmp/issue-<n>.md`) with the write tool and pass it via `--body-file`. Never inline long markdown in shell arguments — quoting will mangle it.
+5. **If the body was extracted from a larger document** (sed/awk/head), verify the extraction boundaries: a section header from the NEXT section can leak into the end of your file. Check the last lines of the extracted file before submitting.
+
+## Workflow
+
+1. Write title + body file per the rules above.
+2. Create:
+
+   ```bash
+   gh issue create --repo <owner>/<repo> --title "<title>" --body-file /tmp/issue-<n>.md
+   ```
+
+   Use the `gh_cli` tool where available (it validates against an allowlist and parses JSON).
+3. **Verify after creation** — this step is mandatory, it is how the previous mistakes were caught:
+
+   - Fetch the rendered HTML and confirm there are **zero `<br>` tags outside code blocks**:
+
+     ```bash
+     gh api graphql -f query='query { repository(owner:"<owner>", name:"<repo>") { issue(number:<n>) { bodyHTML } } }' \
+       --jq '.data.repository.issue.bodyHTML' | grep -c "<br"
+     ```
+
+     Expect `0` (grep exits 1 with no matches — that is success).
+   - Re-read the stored body (`gh issue view <n>`) and check: no stray headings at the end, no internal jargon, title clean.
+4. Report the issue URL. Leave the temp body file in place for reference.
+
+## Editing an Existing Issue
+
+Same rules apply to `gh issue edit <n> --title ... --body-file ...` — unwrapped single-line paragraphs, clean title, then re-verify with the GraphQL check.
+
+## Edge Cases
+
+| Scenario | Action |
+| --- | --- |
+| Existing issue covers the topic | Don't create a duplicate; link/reference the existing one |
+| Repo has label conventions | Add labels with `--label` matching existing usage |
+| Body extracted from a draft doc | Check the tail of the extracted file for leaked headings |
+| Rendered body shows `<br>` breaks | Unwrap paragraphs to single lines, re-edit, re-verify |
+| User wants an internal/rough draft | Ask — public issues default to the public style above |

complexipy-7.0.1/.agents/skills/create-pr/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: create-pr
+description: >
+    Create a GitHub Pull Request with generated title/body from git diff.
+    Supports optional target branch (defaults to main). Invoke when the user
+    asks to create a PR, open a pull request, or submit changes via GitHub CLI.
+---
+
+# Create PR
+
+Creates a GitHub Pull Request using `gh pr create`. Generates the PR title and body
+from `git diff`, writes it to `PR_DESCRIPTION.md`, then submits.
+
+## Usage
+
+The user may specify a target branch. If omitted, default is `main`.
+
+Examples:
+
+- "Create a PR" → targets `main`
+- "Create a PR for staging" → targets `staging`
+- "Create a PR against release-v2" → targets `release-v2`
+
+## PR Description Format
+
+When generating the PR description:
+
+1. Run `git diff <base>...HEAD` (where `<base>` is the target branch) to see all changes on this branch.
+1. Create or overwrite `PR_DESCRIPTION.md` in the repository root.
+1. Write the PR description into `PR_DESCRIPTION.md` following the format below.
+1. Final response must mention the file path and briefly summarize what was written.
+
+Output requirements:
+
+- MUST use the write tool to create or update `PR_DESCRIPTION.md`.
+- MUST NOT only print the PR description in chat unless the user explicitly asks for chat-only output.
+- If `PR_DESCRIPTION.md` was not written, the task is incomplete.
+
+### Template
+
+The file has two distinct sections — the title block and the body. The title is the first non-empty line after `## Title suggestion`. The body is everything from `## What` onwards.
+
+```markdown
+## Title suggestion
+
+<short descriptive title here>
+
+## What
+
+One sentence explaining what this PR does.
+
+## Why
+
+Brief context on why this change is needed.
+
+## Changes
+
+- Bullet points of specific changes made
+- Group related changes together
+- Mention any files deleted or renamed
+```
+
+## Workflow
+
+1. **Generate the PR description** following the format above — run `git diff <target-branch>...HEAD`, then create `PR_DESCRIPTION.md` with the title and body.
+
+1. **Determine target branch**: if user specified a branch, use that; otherwise `main`.
+
+1. **Read `PR_DESCRIPTION.md`** to extract title and body:
+
+    - **Title**: the first non-empty line after `## Title suggestion`. Do not include the header itself.
+    - **Body**: everything from `## What` onwards (inclusive). This excludes the `## Title suggestion` block entirely.
+
+    Extraction example:
+
+    ```bash
+    # Title: first non-empty line after "## Title suggestion"
+    TITLE=$(sed -n '/^## Title suggestion/,/^##/{/^##/d;/^$/d;p;}' PR_DESCRIPTION.md | head -1)
+    # Body: everything from "## What" to end of file
+    BODY=$(sed -n '/^## What/,$p' PR_DESCRIPTION.md)
+    ```
+
+1. **Create PR via `gh pr create`**:
+
+    ```bash
+    gh pr create \
+      --base <target-branch> \
+      --title "$TITLE" \
+      --body "$BODY"
+    ```
+
+    - If on a fork, add `--repo <owner>/<repo>` inferred from `git remote get-url origin`.
+    - If the branch has no remote, prompt to push first with `git push -u origin HEAD`.
+    - If `gh` is not authenticated, report error and stop.
+
+1. **Report result**: output the PR URL and a summary. Do NOT delete `PR_DESCRIPTION.md` — leave it for reference.
+
+## Edge Cases
+
+| Scenario                     | Action                                                    |
+| ---------------------------- | --------------------------------------------------------- |
+| No commits on branch vs base | Warn user: no diff to create PR from                      |
+| Branch already has open PR   | Detect with `gh pr list --head "$BRANCH"`; reuse or abort |
+| Unpushed branch              | Offer to push before creating PR                          |
+| `gh` not installed           | Report error, suggest `brew install gh`                   |
+| `gh` not authenticated       | Report error, suggest `gh auth login`                     |
+
+## Parameter Detection
+
+Parse the user's request for a target branch:
+
+| Phrase            | Branch |
+| ----------------- | ------ |
+| "for X"           | X      |
+| "against X"       | X      |
+| "into X"          | X      |
+| "to X"            | X      |
+| "base X"          | X      |
+| No branch mention | `main` |

complexipy-7.0.1/.agents/skills/git-commit/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: git-commit
+description: >
+    Generic git commit workflow and commit message conventions. MUST be loaded
+    before running any git commit command. Invoke whenever the user asks to
+    inspect, stage, split, or commit changes — even without an explicit slash
+    command.
+---
+
+# Git Commits
+
+Use this skill to create clean, reviewable git commits in any project.
+
+## First: Inspect Local Conventions
+
+Before staging or committing:
+
+1. Run `git status --short` to see changed files.
+1. Inspect recent commit style with `git log --oneline -n 10`.
+1. Check project guidance files when present, such as `AGENTS.md`, `CONTRIBUTING.md`,
+   `README.md`, or `.github/` templates.
+1. Follow explicit project conventions over this generic default.
+1. Derive the repo's commit shape from the log — subject-only vs bodies, scoped vs
+   unscoped, bundled vs split — and match it.
+
+If no stronger project convention exists, use Conventional Commits.
+
+______________________________________________________________________
+
+## Default Commit Format
+
+```text
+<type>(<scope>): <short description>
+```
+
+Scope is optional when the change is broad or no clear module exists:
+
+```text
+<type>: <short description>
+```
+
+______________________________________________________________________
+
+## Types
+
+| Type       | When to use                                             |
+| ---------- | ------------------------------------------------------- |
+| `feat`     | New user-visible functionality                          |
+| `fix`      | Bug fix                                                 |
+| `refactor` | Code change that neither adds a feature nor fixes a bug |
+| `perf`     | Performance improvement                                 |
+| `test`     | Adding or updating tests                                |
+| `docs`     | Documentation only                                      |
+| `build`    | Build system, packaging, or dependency changes          |
+| `ci`       | CI/CD configuration                                     |
+| `chore`    | Maintenance that does not affect runtime behavior       |
+| `revert`   | Revert a previous commit                                |
+
+______________________________________________________________________
+
+## Scope
+
+Choose a short, lowercase scope from the affected area:
+
+- Directory or package: `api`, `web`, `cli`, `server`, `docs`
+- Module or feature: `auth`, `billing`, `search`, `config`
+- Tooling area: `deps`, `ci`, `lint`, `release`
+
+Rules:
+
+- Keep scope to one short token when possible.
+- Prefer names that already appear in paths, package names, or recent commits.
+- Omit scope for broad repository-wide changes.
+
+______________________________________________________________________
+
+## Short Description
+
+- Lowercase unless using a proper noun
+- Imperative mood: `add retry logic`, not `added retry logic`
+- No period at the end
+- Prefer 50 chars or less; hard maximum 72 chars
+- Explain the intent, not the implementation detail
+
+______________________________________________________________________
+
+## Body
+
+Add a body only when the subject cannot explain the why, risk, or migration impact.
+
+If recent commits in this repo are subject-only, stay subject-only: write a subject
+that carries the intent rather than compensating with a body. The exceptions are
+breaking changes (`BREAKING CHANGE:`) and migration/rollout impact. When the repo
+merges via PRs with descriptions, the PR description — not the commit body — is
+where the explanation belongs.
+
+Body rules:
+
+- Wrap around 72 characters.
+- Explain why the change exists and notable tradeoffs.
+- Mention breaking changes with `BREAKING CHANGE:` when applicable.
+- Reference issues only when useful and allowed by project convention.
+
+______________________________________________________________________
+
+## Examples
+
+```text
+feat(auth): add passkey login
+fix(api): handle empty search results
+refactor(cli): split command parsing from execution
+test(billing): cover failed payment retries
+docs(readme): document local setup
+build(deps): update vite
+ci(actions): cache package manager downloads
+chore: remove unused assets
+```
+
+______________________________________________________________________
+
+## Grouping Changes
+
+When multiple files changed, do not blindly commit everything together. Create one
+commit per logical concern.
+
+Workflow:
+
+1. Run `git status --short`.
+1. Review diffs with `git diff` and, for staged changes, `git diff --staged`.
+1. Identify logical groups. Each group should map to one type and optional scope.
+1. Commit foundational changes before dependent changes.
+1. Stage only files or hunks that belong to the current group.
+
+Use explicit paths or interactive staging:
+
+```bash
+git add <file1> <file2>
+git add -p <file>
+git commit -m "<type>(<scope>): <description>"
+```
+
+Avoid `git add .` and `git add -A` unless the user explicitly asks for a single
+all-changes commit and the diff has been reviewed.
+
+### Dependency and Lockfile Changes
+
+Commit package manifest and lockfile updates together for the same package manager.
+Examples:
+
+- `package.json` with `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, or `bun.lockb`
+- `pyproject.toml` with `uv.lock` or compatible Python lockfile
+- `Cargo.toml` with `Cargo.lock`
+- `go.mod` with `go.sum`
+
+Use `build(deps)` or the project's established dependency commit style.
+
+______________________________________________________________________
+
+## Commit Execution Rules
+
+- Only commit when the user asks to commit.
+- Never push unless the user explicitly asks.
+- Never amend, rebase, reset, or discard changes without explicit approval.
+- Preserve unrelated user changes.
+- If staged changes already exist, inspect them before adding more.
+- If hooks fail, report the failure and do not bypass hooks unless the user approves.
+- Do not add AI tool co-author lines or generation footers unless explicitly requested.
+
+______________________________________________________________________
+
+## What to Avoid
+
+```text
+# Too vague
+fix: bug fix
+chore: changes
+feat: stuff
+
+# Not imperative
+feat(auth): added passkey support
+
+# Too much implementation detail
+fix(api): change line 42 to check null before mapping response
+
+# Mixed concerns
+feat(api): add search endpoint and update CI cache
+```