margo-tooling 0.5.1__tar.gz

margo_tooling-0.5.1/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: lint
+        run: make lint
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: pytest
+        run: make test

margo_tooling-0.5.1/.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: build docs
+        run: make docs-check
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    name: Deploy
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

margo_tooling-0.5.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Git tag of the GitHub release to publish (e.g. 1.2.3)"
+        required: true
+        type: string
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for PyPI trusted publishing
+
+    steps:
+      - name: Resolve release tag
+        id: tag
+        run: echo "version=${{ inputs.version || github.event.release.tag_name }}" >> "$GITHUB_OUTPUT"
+
+      - name: Download release artifacts
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release download ${{ steps.tag.outputs.version }} \
+            --repo ${{ github.repository }} \
+            --pattern '*.whl' \
+            --pattern '*.tar.gz' \
+            --dir dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

margo_tooling-0.5.1/.github/workflows/release-check.yml

@@ -0,0 +1,45 @@
+name: Release Check
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  preview-release-version:
+    if: startsWith(github.head_ref, 'release/')
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Extract version from branch name
+        id: version
+        run: |
+          VERSION=${GITHUB_HEAD_REF#release/}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Validate SemVer
+        run: uvx --from 'semver>=3.0,<4.0' pysemver check ${{ steps.version.outputs.version }}
+
+  preview-changelog:
+    if: startsWith(github.head_ref, 'release/')
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract version from branch name
+        id: version
+        run: |
+          VERSION=${GITHUB_HEAD_REF#release/}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Preview release notes
+        run: |
+          echo "## Release notes preview for ${{ steps.version.outputs.version }}"
+          echo ""
+          uvx git-cliff --unreleased --strip header

margo_tooling-0.5.1/.github/workflows/release.yml

@@ -0,0 +1,105 @@
+name: Release
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+jobs:
+  release:
+    if: github.event.pull_request.merged == true && startsWith(github.head_ref, 'release/')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract version from branch name
+        id: version
+        run: |
+          VERSION=${GITHUB_HEAD_REF#release/}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Validate SemVer
+        run: uvx --from 'semver>=3.0,<4.0' pysemver check ${{ steps.version.outputs.version }}
+
+      - name: Tag the release commit
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag ${{ steps.version.outputs.version }}
+          git push origin ${{ steps.version.outputs.version }}
+
+      - name: Build
+        run: uv build
+
+      - name: Generate changelog
+        run: uvx git-cliff --latest --strip header -o RELEASE_NOTES.md
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-artifacts
+          path: dist/
+          retention-days: 1
+
+      - name: Create release and upload artifacts
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create ${{ steps.version.outputs.version }} dist/* \
+            --title "${{ steps.version.outputs.version }}" \
+            --notes-file RELEASE_NOTES.md \
+            --target main
+
+  container:
+    needs: release
+    if: github.event.pull_request.merged == true && startsWith(github.head_ref, 'release/')
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from branch name
+        id: version
+        run: |
+          VERSION=${GITHUB_HEAD_REF#release/}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Compute container image tag
+        id: image
+        run: |
+          IMAGE_NAME=$(echo "${{ github.repository }}" | tr '[:upper:]' '[:lower:]')
+          echo "name=$IMAGE_NAME" >> $GITHUB_OUTPUT
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: build-artifacts
+          path: dist/
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push container image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Containerfile
+          push: true
+          tags: |
+            ghcr.io/${{ steps.image.outputs.name }}:${{ steps.version.outputs.version }}
+            ghcr.io/${{ steps.image.outputs.name }}:latest

margo_tooling-0.5.1/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg-info/
+*.egg
+dist/
+build/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Build output
+.dist/
+.run/
+
+# Git worktrees checked out inside the repo
+.wk-*/
+
+# MkDocs
+site/
+
+# Editors
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

margo_tooling-0.5.1/.kiro/agents/docs-writer.json

@@ -0,0 +1,63 @@
+{
+  "name": "docs-writer",
+  "description": "Maintains the MkDocs documentation site under docs/. Writes and edits doc content, mkdocs.yml nav, and verifies builds. Never touches Python source.",
+  "model": "claude-sonnet-4.6",
+  "prompt": "You are a technical writer maintaining the margot MkDocs site under docs/. FEATURES.md is the authoritative source of truth for behavior, architecture, commands, config, and OCI media types — docs must never contradict it. .kiro/steering/documentation.md governs doc style, audience separation, and structure; follow it exactly. When a doc page and FEATURES.md disagree, FEATURES.md wins — fix the doc, don't work around it. New user-facing behavior belongs in FEATURES.md first; you follow, you don't lead. Before writing or editing a page, read FEATURES.md and the relevant steering files. After any change under docs/ or to mkdocs.yml, run `make docs-check` (strict build, warnings as errors) and fix any failures before considering the change done. Never modify Python source, tests, or non-doc config — if a doc gap reveals a product or code issue, report it instead of fixing code. You must never edit pyproject.toml or uv.lock directly (the write tool blocks this). If a docs dependency is needed (e.g. an mkdocs plugin), add it with `uv add <package> --group docs` — never hand-edit the dependency group.",
+  "mcpServers": {},
+  "tools": [
+    "read",
+    "write",
+    "grep",
+    "glob",
+    "code",
+    "shell",
+    "todo"
+  ],
+  "allowedTools": [
+    "read",
+    "grep",
+    "glob",
+    "code",
+    "todo"
+  ],
+  "toolsSettings": {
+    "read": {
+      "allowedPaths": [
+        "**"
+      ]
+    },
+    "write": {
+      "allowedPaths": [
+        "docs/**",
+        "mkdocs.yml",
+        "*.md",
+        ".kiro/steering/documentation.md"
+      ],
+      "deniedPaths": [
+        "**/*.py",
+        "src/**",
+        "tests/**",
+        "pyproject.toml",
+        "uv.lock"
+      ]
+    },
+    "shell": {
+      "autoAllowReadonly": true,
+      "denyByDefault": true,
+      "allowedCommands": [
+        "make.*",
+        "uv.*",
+        "git.*"
+      ]
+    }
+  },
+  "resources": [
+    "file://.kiro/steering/documentation.md",
+    "file://.kiro/steering/oci-media-types.md",
+    "file://FEATURES.md",
+    "file://AGENTS.md"
+  ],
+  "hooks": {},
+  "includeMcpJson": true,
+  "welcomeMessage": "docs-writer ready. I maintain docs/ against FEATURES.md and documentation.md. I don't touch source code."
+}

margo_tooling-0.5.1/.kiro/agents/planner.json

@@ -0,0 +1,85 @@
+{
+  "name": "planner",
+  "description": "Sprint planner: locates TODO items, forms a plan, and delegates implementation to dev agent. Never writes code.",
+  "model": "claude-sonnet-5",
+  "prompt": "You are a senior technical planner. Your role is exclusively investigating, planning and delegation — you never write, edit, or create code files.\n\nWorkflow on every request:\n1. Define a clear plan with explicit designs, key aspect and checkable steps/aspects. Search on the web if needed.\n2. Summary plan and get final approval.\n3. Delegate the full plan to the dev agent for implementation.\n4. Report back the dev agent output and a brief summary of what was done.\n\nHard constraints:\n- You MUST NOT write, edit, or create any source or test file (no .py, .toml, .yaml, .sh, etc.).\n- You MUST NOT produce code blocks intended to be applied to files.\n- You MAY write or edit Markdown files (.md) and files under .kiro/ (specs, steering, notes, task files).\n- You MAY create planning notes, task lists, or spec files to support future work.\n- When delegating, provide dev agent with the full plan, relevant file paths and a clear definition of done (tests pass, TODO removed, changes committed).\n- After the dev agent completes, instruct it to commit all changes with a meaningful commit message (conventional commits format: `feat:`, `fix:`, `test:`, etc.). The commit is part of the definition of done — a patch is not complete until it is committed.",
+  "mcpServers": {},
+  "tools": [
+    "code",
+    "delegate",
+    "glob",
+    "grep",
+    "read",
+    "shell",
+    "subagent",
+    "todo",
+    "tool_search",
+    "web_fetch",
+    "web_search",
+    "write"
+  ],
+  "allowedTools": [
+    "code",
+    "delegate",
+    "glob",
+    "grep",
+    "read",
+    "shell",
+    "subagent",
+    "todo",
+    "tool_search",
+    "web_fetch",
+    "web_search",
+    "write"
+  ],
+  "toolsSettings": {
+    "read": {
+      "allowedPaths": [
+        "**"
+      ]
+    },
+    "write": {
+      "allowedPaths": [
+        "**/*.md",
+        ".kiro/**"
+      ],
+      "deniedPaths": [
+        "**/*.py",
+        "**/*.toml",
+        "**/*.cfg",
+        "**/*.ini",
+        "**/*.yaml",
+        "**/*.yml",
+        "**/*.json",
+        "**/*.txt",
+        "**/*.sh"
+      ]
+    },
+    "shell": {
+      "autoAllowReadonly": true,
+      "denyByDefault": true,
+      "allowedCommands": [
+        "find.*",
+        "grep.*",
+        "make.*"
+      ]
+    },
+    "subagent": {
+      "availableAgents": [
+        "python-dev"
+      ],
+      "trustedAgents": [
+        "python-dev"
+      ]
+    }
+  },
+  "resources": [
+    "file://.kiro/steering/code-conventions.md",
+    "file://.kiro/steering/oci-media-types.md",
+    "file://AGENTS.md",
+    "file://FEATURES.md"
+  ],
+  "hooks": {},
+  "keyboardShortcut": "ctrl+shift+p",
+  "welcomeMessage": "Planner ready. I'll locate TODOs, build a plan, and hand off to python-dev. I don't write code."
+}

margo_tooling-0.5.1/.kiro/agents/python-dev.json

@@ -0,0 +1,60 @@
+{
+  "name": "python-dev",
+  "description": "Senior Python developer agent for building tooling.",
+  "prompt": " You are a senior Python developer. You build tooling based on user instructions. When requirements are ambiguous, incomplete, or admit multiple valid implementation choices, stop and ask before proceeding — do not guess. Work in small increments: implement one small block, then verify it (automated test or manual check) before moving to the next block. Always use the project's virtualenv when running Python or tools. Invoke via uv run <cmd> or .venv/bin/<cmd> — never via a bare python, pytest, or ruff that could resolve to a global installation.",
+  "mcpServers": {},
+  "tools": [
+    "*"
+  ],
+  "toolAliases": {},
+  "allowedTools": [
+    "code",
+    "fs_read",
+    "fs_write",
+    "glob",
+    "grep",
+    "tool_search",
+    "delegate",
+    "knowledge",
+    "todo"
+  ],
+  "resources": [
+    "file://.kiro/steering/code-conventions.md",
+    "file://AGENTS.md",
+    "skill://~/.kiro/skills/*/SKILL.md"
+  ],
+  "hooks": {},
+  "toolsSettings": {
+    "read": {
+      "allowedPaths": [
+        "**"
+      ]
+    },
+    "write": {
+      "allowedPaths": [
+        "**"
+      ]
+    },
+    "execute_bash": {
+      "autoAllowReadonly": true,
+      "allowedCommands": [
+        "diff.*",
+        "find . .*",
+        "gh.*",
+        "git.*",
+        "grep.*",
+        "ls.*",
+        "make.*",
+        "pdm.*",
+        "podman.*",
+        "sed.*",
+        "source .venv/bin/activate.*",
+        "timeout.*",
+        "true.*",
+        "uv.*"
+      ]
+    }
+  },
+  "includeMcpJson": true,
+  "model": null
+}

margo_tooling-0.5.1/.kiro/skills/code-quality-enhancement/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: code-quality-enhancement
+description: >
+  Find and fix code quality regressions in margot: ruff lint violations, low test
+  coverage, and global (non-selective) imports. Use when asked to improve code
+  quality, clean up lint, raise coverage, or fix import style — not on every
+  request.
+---
+
+# Code Quality Enhancement Skill
+
+Three independent triggers, each with its own workflow. Run only the one(s) the
+user asked for — do not run all three unless explicitly asked to do a full pass.
+
+## When to use
+
+Only when explicitly asked to improve code quality, fix lint, raise test coverage, or
+fix import style. Do not run proactively during unrelated feature or bugfix work.
+
+## Trigger 1 — ruff lint
+
+1. Run `make lint` (`ruff check --no-fix src/ tests/`) and capture the full output.
+2. Read each flagged file's surrounding context — not just the flagged line — before
+   deciding on a fix.
+3. Build a plan grouped by rule code, not a one-off patch per line.
+4. For each violation, decide real fix vs. suppress-with-`noqa`:
+   - **Default to a real fix.** `select = ["ALL"]` in `pyproject.toml` is deliberate —
+     the project wants the strict ruleset enforced, not relaxed.
+   - **`# noqa` is legitimate only when:** the rule is a false positive for this exact
+     case, or fixing it would fight an established pattern already accepted in
+     `pyproject.toml`'s `ignore` list philosophy (e.g. Typer's bool positional args,
+     inline exception messages). If in doubt, treat it as a case-by-case judgment,
+     not a default — document the reason in the `noqa` comment
+     (`# noqa: RULE — reason`).
+   - **Never blanket-suppress** a whole file or add a rule to the project-wide
+     `ignore` list to make a violation disappear. That is a scope decision for the
+     user, not an automatic fix.
+5. Delegate the grouped fix plan to the `python-dev` agent with the plan, affected
+   files, and the ruff rule codes involved.
+6. Definition of done: `make lint` passes clean, changes committed.
+
+## Trigger 2 — low test coverage
+
+1. Run `make test` (`uv run pytest`, which already runs with
+   `--cov=margot --cov-report=term-missing --cov-fail-under=90`) and capture the
+   per-file coverage table from the terminal report.
+2. Select the 1-2 files with the lowest coverage — not every under-covered file at
+   once. Read the file and its existing test file (if any) to see what's actually
+   untested (the `Missing` line-number ranges in the report point at this directly).
+3. Build a short plan: what behavior is untested, what test(s) to add, which file(s)
+   they land in (mirror the existing `tests/unit/` / `tests/integration/` /
+   `tests/e2e/` split already used in this repo).
+4. Delegate to `python-dev` with the plan and the specific uncovered line ranges.
+   Tests must assert real behavior — no stub tests that just exercise a line without
+   checking an outcome (same TDD rule as `code-conventions.md`).
+5. Definition of done: `make test` passes, coverage for the targeted file(s)
+   measurably improves, changes committed.
+
+## Trigger 3 — global (non-selective) imports
+
+1. Search for violations:
+   ```bash
+   grep -rn -E "^import " src/ tests/
+   ```
+   This catches `import x` module-level imports; selective imports (`from x import y`)
+   are the required convention (see `code-conventions.md`) and won't match.
+2. For each match, check whether a selective form is actually possible — a handful of
+   modules are conventionally imported as a namespace (e.g. `import margot.console as
+   console`, which the project's own conventions explicitly require — don't "fix" that
+   one). Distinguish real violations from accepted namespace-import patterns before
+   planning a change.
+3. Build a plan: for each real violation, the selective import form it should become,
+   and every usage site in that file that needs updating to match (e.g. `pytest.raises`
+   → `from pytest import raises` then all call sites).
+4. Delegate to `python-dev` with the plan and file list.
+5. Definition of done: `grep -rn -E "^import " src/ tests/` shows only accepted
+   namespace-import patterns, `make lint` and `make test` still pass, changes
+   committed.
+
+## Common rules across all three triggers
+
+- Always run the relevant `make` target yourself first — don't plan from memory or
+  assumption of what's currently failing.
+- Group fixes into a coherent plan before delegating; don't delegate raw tool output.
+- Delegate implementation to `python-dev` — this skill does not write code directly.
+- A trigger is not done until its verification command passes clean and the fix is
+  committed (conventional commit format), matching the repo's definition-of-done
+  pattern used elsewhere (sprints, TODO fixes).

margo_tooling-0.5.1/.kiro/skills/fix-todos/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: fix-todos
+description: >
+  Locate, plan, and delegate fixes for # TODO(kiro): markers in the margot codebase.
+  Use only when explicitly asked to find, review, or fix TODOs — not on every planning
+  request.
+---
+
+# Fix TODOs Skill
+
+## When to use
+
+Only when the user explicitly asks to find, triage, or fix TODO markers. Do not run
+this workflow proactively on unrelated planning or implementation requests.
+
+## Workflow
+
+1. Search for TODO markers:
+   ```bash
+   grep -rn "# TODO" --include="*.py" src/ tests/
+   ```
+   Any author tag counts (`TODO(kiro):`, `TODO(<other>):`, bare `TODO:`) — bare TODOs are
+   a convention violation to flag, not to ignore (see `code-conventions.md`).
+2. For each TODO found, read the surrounding function/class to understand what's
+   actually required — the TODO text alone is often incomplete context.
+3. **If a TODO is ambiguous, or its fix implies a design decision (API shape, new
+   dependency, behavior change, breaking change), stop and ask the user before
+   proceeding.** Do not guess intent and do not delegate a design decision to the dev
+   agent — that decision is the user's to make, the same way sprint planning decisions
+   in this repo are locked with the user first.
+4. Group related, unambiguous TODOs (same file, same feature) into a single plan rather
+   than one-off patches.
+5. Build a short plan per group: what changes, which files, what test proves it's done.
+6. Delegate implementation to the `python-dev` agent with the plan, file paths, and a
+   definition of done: tests pass, the TODO marker is removed, changes are committed
+   (conventional commit format).
+7. Report back what was fixed and confirm no `# TODO` markers remain in the touched
+   scope.
+
+## Conventions this enforces
+
+- Correct format is `# TODO(kiro): ...` (ruff TD002) — bare `# TODO:` must be fixed to
+  include an author tag, not just left as-is.
+- A TODO is not "done" until removed from source and its fix is committed — matching
+  the sprint definition-of-done rule ("No `# TODO` markers left from this sprint's work").
+
+## Scope
+
+Source and test files only (`src/`, `tests/`). Do not treat TODO-shaped text inside
+`.kiro/steering/*.md` or sprint docs as code TODOs to fix — those are conventions
+references, not action items.