kanbanlan 0.2.0__tar.gz

kanbanlan-0.2.0/.agents/skills/release/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: release
+description: Select, prepare, publish, and verify the next Kanbanlan release on GitHub and PyPI. Use when the user invokes /release, asks to release or publish Kanbanlan, requests a version bump, or wants the next package version shipped. Choose the version without asking the user unless a non-version product decision blocks the release.
+---
+
+# Release Kanbanlan
+
+Release Kanbanlan end-to-end. Treat invoking this skill as authorization to
+update versions, commit release-scoped changes, push `main` and the release tag,
+create the GitHub Release, and publish through the `pypi` environment. Never ask
+the user which version number to use.
+
+## Choose the version
+
+Inspect the latest Git tag, GitHub Release, PyPI release, current package
+version, and changes since the latest release. Select a semantic version:
+
+- Patch for backward-compatible fixes, documentation, tests, CI, packaging, or
+  maintenance only.
+- Minor for new functionality or meaningful backward-compatible behavior.
+- Major for intentional breaking changes once the project is at least `1.0`.
+  Before `1.0`, use a minor bump for breaking or substantial changes.
+
+If there is no published release, use the prepared project version when it is
+greater than any existing tag; otherwise choose the smallest suitable next
+version. Never reuse a version already present on PyPI.
+
+## Prepare
+
+1. Read repository instructions and inspect the complete worktree, history,
+   remote, tags, GitHub Releases, Actions state, and PyPI package state.
+2. Preserve user changes. Review every file that will ship and scan tracked and
+   untracked files for credentials or private data before staging.
+3. Update `pyproject.toml` and `src/kanbanlan/__init__.py` to the chosen version.
+   Refresh `uv.lock`, then confirm all three versions agree and the CLI reports
+   the same value.
+4. Update release-facing documentation when behavior, installation, supported
+   versions, or release instructions changed.
+5. Run the full gate:
+
+   ```sh
+   uv lock --check
+   uv run pytest
+   uv run ruff check .
+   uv run ruff format --check .
+   uv build
+   ```
+
+   Inspect the wheel metadata and verify the source distribution and wheel use
+   the chosen version. Validate all GitHub workflow and issue-form YAML.
+
+Do not proceed while checks fail or the worktree contains unexplained sensitive
+material.
+
+## Publish
+
+1. Commit all reviewed release changes with a concise release-oriented commit
+   message and push `main`, setting its upstream when needed.
+2. Ensure the repository has the GitHub environment `pypi`. Keep PyPI
+   authentication secretless: `.github/workflows/release.yaml` must use OIDC
+   Trusted Publishing and grant `id-token: write` only to its publish job.
+3. Wait for every required CI job on the pushed commit. If CI fails, diagnose,
+   fix, commit, push, and wait again. Do not create the release tag before CI
+   succeeds.
+4. Create an annotated tag named `v<version>`, push it, and create a published
+   GitHub Release from that exact tag with generated release notes.
+5. Wait for the `release.yaml` run to finish. Do not report success based only
+   on creating the GitHub Release.
+
+Never force-push, move a published tag, delete release history, use
+`skip-existing`, or store a PyPI token. PyPI distributions are immutable. If a
+published tag or partial upload makes the selected version unusable, diagnose
+the state and prepare a new patch version instead of rewriting history.
+
+## Verify
+
+Confirm all of the following before declaring success:
+
+- GitHub `main` points at the intended release commit and is clean locally.
+- The tag and GitHub Release exist and target that commit.
+- CI and the release workflow completed successfully.
+- PyPI reports the chosen version for `kanbanlan`.
+- A clean temporary `uvx --from kanbanlan==<version> kanbanlan --version`
+  invocation reports the same version.
+
+Report the chosen version, commit, tag, GitHub Release URL, PyPI URL, workflow
+results, and verification commands. If an external service is still processing,
+keep monitoring rather than handing off an incomplete release.

kanbanlan-0.2.0/.agents/skills/release/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Release Kanbanlan"
+  short_description: "Safely version and publish Kanbanlan releases"
+  default_prompt: "Use $release to choose and publish the next Kanbanlan version."

kanbanlan-0.2.0/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,62 @@
+name: Bug report
+description: Report reproducible behavior that is incorrect or unexpected.
+title: "[Bug] "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Remove secrets and private repository data
+        from all commands, output, configuration, and snapshots.
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened, and what did you expect instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Run `kanbanlan ...`
+        2. ...
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Kanbanlan version
+      description: Output from `kanbanlan --version`.
+      placeholder: kanbanlan X.Y.Z
+    validations:
+      required: true
+
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: Operating system, Python version, and GitHub CLI version.
+      placeholder: macOS 15, Python 3.13, gh 2.x
+    validations:
+      required: true
+
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Relevant diagnostic output
+      description: Include sanitized errors or `kanbanlan doctor` output.
+      render: text
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Pre-submission checks
+      options:
+        - label: I removed credentials and private repository data from this report.
+          required: true
+        - label: I searched existing issues for the same problem.
+          required: true

kanbanlan-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/jmitchel3/kanbanlan/security/advisories/new
+    about: Report security issues privately instead of opening a public issue.

kanbanlan-0.2.0/.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,39 @@
+name: Feature request
+description: Suggest a focused improvement to Kanbanlan.
+title: "[Feature] "
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What workflow problem should Kanbanlan solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Desired outcome
+      description: Describe the behavior or result you would like.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: How do you handle this today, and what tradeoffs did you find?
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Add sanitized examples or links that clarify the request.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Pre-submission checks
+      options:
+        - label: I searched existing issues for a similar request.
+          required: true

kanbanlan-0.2.0/.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      development-dependencies:
+        dependency-type: development
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

kanbanlan-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Summary
+
+<!-- What problem does this pull request solve? -->
+
+## Changes
+
+<!-- List the important user-visible or implementation changes. -->
+
+## Verification
+
+<!-- List automated checks and relevant manual verification. -->
+
+- [ ] `uv run pytest`
+- [ ] `uv run ruff check .`
+- [ ] `uv run ruff format --check .`
+- [ ] `uv build`
+- [ ] Tests and documentation were updated where needed.
+
+## Security and compatibility
+
+<!-- Note credential handling, GitHub API changes, compatibility risks, or write "None". -->

kanbanlan-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.11.16"
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install "${{ matrix.python-version }}"
+
+      - name: Install project
+        run: uv sync --locked --group dev --python "${{ matrix.python-version }}"
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Run lint
+        if: matrix.python-version == '3.14'
+        run: uv run ruff check .
+
+      - name: Check formatting
+        if: matrix.python-version == '3.14'
+        run: uv run ruff format --check .
+
+      - name: Build distributions
+        if: matrix.python-version == '3.14'
+        run: uv build

kanbanlan-0.2.0/.github/workflows/release.yaml

@@ -0,0 +1,70 @@
+name: Release to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.11.16"
+          enable-cache: true
+
+      - name: Verify release tag
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          package_version="$(uv version --short)"
+          if [[ "$RELEASE_TAG" != "v$package_version" ]]; then
+            echo "Release tag $RELEASE_TAG does not match package version $package_version."
+            exit 1
+          fi
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kanbanlan
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

kanbanlan-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/

kanbanlan-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to Kanbanlan
+
+Thanks for helping improve Kanbanlan. Bug reports, documentation fixes, and
+small, focused feature changes are welcome.
+
+## Development setup
+
+Kanbanlan requires Python 3.11 or newer, Git, GitHub CLI, and uv.
+
+```sh
+git clone https://github.com/jmitchel3/kanbanlan.git
+cd kanbanlan
+uv sync --group dev
+```
+
+Run the same checks used in CI before opening a pull request:
+
+```sh
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv build
+```
+
+## Proposing a change
+
+1. Open an issue for bugs or substantial changes so the intended behavior can
+   be agreed on before implementation.
+2. Keep each pull request focused on one outcome and add or update tests for
+   behavior changes.
+3. Update user-facing documentation when commands, configuration, or workflow
+   behavior changes.
+4. Explain the change and verification performed in the pull request template.
+
+Never include GitHub tokens, repository snapshots, or `.kanbanlan.toml` files
+from private repositories in reports or fixtures.
+
+## Releasing
+
+Releases use PyPI Trusted Publishing, so no long-lived PyPI token is stored in
+GitHub. Before the first release:
+
+1. Create a GitHub environment named `pypi` and add any desired deployment
+   reviewers.
+2. Configure the PyPI Trusted Publisher for owner `jmitchel3`, repository
+   `kanbanlan`, workflow `release.yaml`, and environment `pypi`.
+
+To publish a release, update the version in `pyproject.toml` and `uv.lock`, then
+publish a GitHub Release whose tag is `v` followed by that exact version, such
+as tag `v1.2.3` for package version `1.2.3`. The release workflow builds the
+distributions in an unprivileged job and publishes them from the protected
+`pypi` environment.

kanbanlan-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justin Mitchel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kanbanlan-0.2.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: kanbanlan
+Version: 0.2.0
+Summary: Reusable GitHub Projects request coordination for humans and coding agents.
+Project-URL: Homepage, https://github.com/jmitchel3/kanbanlan
+Project-URL: Documentation, https://github.com/jmitchel3/kanbanlan#readme
+Project-URL: Issues, https://github.com/jmitchel3/kanbanlan/issues
+Project-URL: Source, https://github.com/jmitchel3/kanbanlan
+Author: Justin Mitchel
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,coding-agents,github,kanban,project-management
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Kanbanlan
+
+[![CI](https://github.com/jmitchel3/kanbanlan/actions/workflows/ci.yml/badge.svg)](https://github.com/jmitchel3/kanbanlan/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jmitchel3/kanbanlan/blob/main/LICENSE)
+
+Kanbanlan turns a GitHub repository and a GitHub Projects v2 board into one
+coordinated request workflow for humans and coding agents.
+
+It provides:
+
+- one-command repository and Project setup;
+- browser-based GitHub CLI authentication when credentials or the `project`
+  scope are missing;
+- repository labels, issue/PR templates, and managed `AGENTS.md` /
+  `CLAUDE.md` instructions;
+- a private local snapshot shared across Git worktrees;
+- dry-run-first reconciliation between issue labels, Project Status, active
+  claims, and linked pull requests; and
+- safe capture, claim, release, handoff, and review commands.
+
+GitHub Issues remain canonical. Kanbanlan does not store API tokens and does
+not create another server-side database.
+
+## Install
+
+Kanbanlan requires Python 3.11+, Git, and
+[GitHub CLI](https://cli.github.com/). The examples below use
+[uv](https://docs.astral.sh/uv/) for installation and development.
+
+Install the latest release from PyPI:
+
+```sh
+uv tool install kanbanlan
+```
+
+Or install the unreleased development version from GitHub:
+
+```sh
+uv tool install git+https://github.com/jmitchel3/kanbanlan.git
+```
+
+To install a local checkout instead:
+
+```sh
+uv tool install .
+```
+
+For development:
+
+```sh
+uv sync --group dev
+uv run pytest
+uv run ruff check .
+uv build
+```
+
+## Initialize a repository
+
+Start the guided setup wizard from any GitHub-backed repository:
+
+```sh
+cd /path/to/repository
+kanbanlan init
+```
+
+The wizard detects the repository and default branch, lets you reuse, create,
+or copy a GitHub Project, collects the staging and optional production branch,
+then shows a summary for confirmation before it changes repository files or
+Project settings.
+
+You can also provide any choice up front. Reuse an existing Project:
+
+```sh
+cd /path/to/repository
+kanbanlan init --project-url https://github.com/orgs/acme/projects/2
+```
+
+Create a new Project:
+
+```sh
+kanbanlan init --create-project --project-title "Product Delivery" --open
+```
+
+Copy a Project template, including its useful views:
+
+```sh
+kanbanlan init --template-project template-owner/1 --project-title "Product Delivery"
+```
+
+`init` authenticates through
+`gh auth login --web` when necessary, ensures the GitHub token has the
+`project` scope, links the Project to the repository, repairs the Status field,
+creates the workflow labels, writes managed repository files, adds open issues,
+and reconciles their state.
+
+Use `--non-interactive` in automation and provide `--project-number`,
+`--project-url`, `--create-project`, or `--template-project` explicitly.
+Use `--local-only` to generate repository files without GitHub mutations.
+Pass `--no-open` to suppress the wizard's browser question or `--open` to open
+the configured Project after setup.
+
+Kanbanlan does not yet create custom Project views or GitHub's built-in
+auto-add workflow. Copying a template Project is the automated path when those
+views matter. Without a template, `kanbanlan init --open` opens the Project so
+a Board view can be added once. Kanbanlan's own `reconcile --apply` keeps item
+states correct even when GitHub Project workflows are not configured.
+
+## Daily use
+
+```sh
+kanbanlan ensure             # refresh only when the worktree-shared cache is stale
+kanbanlan next               # report the first unblocked Ready issue
+kanbanlan status             # summarize the local cache
+kanbanlan reconcile          # report drift, without mutations
+kanbanlan reconcile --apply  # apply and verify the displayed repairs
+```
+
+The cache lives at `<primary-checkout>/.cache/kanbanlan/` with private file
+permissions. A failed refresh preserves the last good snapshot and records the
+error in `health.json`.
+
+## Request lifecycle
+
+```sh
+kanbanlan capture "Add export audit log" --priority priority:p1
+kanbanlan claim 123 --touchpoints "audit API; exports UI; migrations"
+kanbanlan review 123
+kanbanlan release 123 --reason "Waiting for product decision" --blocked
+kanbanlan handoff 123 --session codex-next --branch work/123-audit \\
+  --worktree /path/to/worktree --reason "Shift change"
+```
+
+By default `claim` posts the claim first, verifies that it is the earliest
+active claim, and only then creates a dedicated worktree from the configured
+default branch. If checkout creation fails, it releases the claim and returns
+the card to Ready. Use `--no-worktree` only from an existing non-default
+branch/worktree.
+
+## Managed repository files
+
+`init` writes:
+
+- `.kanbanlan.toml`;
+- `.github/ISSUE_TEMPLATE/work-request.yml`;
+- `.github/pull_request_template.md`;
+- `docs/workflow/kanbanlan.md`;
+- a marked Kanbanlan section in `AGENTS.md` and `CLAUDE.md`; and
+- `/.cache/kanbanlan/` in `.gitignore`.
+
+Generated standalone files carry a marker. Existing custom templates are not
+overwritten unless `--force` is passed. Agent instruction sections are
+updated only between `kanbanlan:start` and `kanbanlan:end` markers.
+
+## State model
+
+| Issue label | Project Status |
+| --- | --- |
+| `status:intake` | Inbox |
+| `status:ready` | Ready |
+| `status:in-progress` | In progress |
+| `status:blocked` | Blocked |
+| `status:review` | In review |
+| closed issue | Done |
+
+Priorities are `priority:p0` through `priority:p3`. An active CLAIM forces In
+progress; an open pull request that closes the issue forces In review; a closed
+issue forces Done. Issue labels are the fallback status record when the
+Project is temporarily unavailable.
+
+## Diagnostics
+
+```sh
+kanbanlan auth
+kanbanlan doctor
+kanbanlan path
+kanbanlan snapshot
+kanbanlan refresh
+```
+
+`doctor` checks configuration, authentication, Project Status options, labels,
+and cache health without mutating GitHub.
+
+## Contributing and security
+
+Bug reports and focused pull requests are welcome. See
+[CONTRIBUTING.md](https://github.com/jmitchel3/kanbanlan/blob/main/CONTRIBUTING.md)
+for the development workflow. Please report security vulnerabilities privately
+as described in
+[SECURITY.md](https://github.com/jmitchel3/kanbanlan/blob/main/SECURITY.md).
+
+Kanbanlan is available under the
+[MIT License](https://github.com/jmitchel3/kanbanlan/blob/main/LICENSE).