lx-tooling 0.2.0

Labinetix workflow CLI for humans and AI agents

lx-tooling

Tag: Org and orchestration

Labinetix workflow CLI for humans and AI agents. lx-tooling orchestrates GitHub issues, branches, pull requests, releases, local verification, and repository policy checks without owning domain logic.

Non-goals: model semantics, ABI schema ownership, runtime algorithms, or protocol implementations.

Stability

Milestone 1 — issue start and PR prepare. Branch creation and gh pr create require --yes. Release planning comes in Milestone 2.

Quickstart

Prerequisites:

• Python 3.11+
• uv
• gh authenticated (gh auth login)

Local development:

git clone [e-mail]:labinetix/lx-tooling.git
cd lx-tooling
uv sync --all-groups
uv run lx --version

Local checks (same as CI):

just check

Or explicitly:

uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv run pytest

Install

From PyPI:

uv tool install lx-tooling
lx --version

Upgrade:

uv tool upgrade lx-tooling

From a checkout:

uv sync --all-groups
uv run lx --help

Commands

Inspect the current repository:

lx repo inspect
lx repo inspect --json

Run conservative pre-PR checks:

lx workflow check

Read a GitHub issue with Labinetix readiness hints:

lx issue view 123

Start work from an issue (dry-run by default):

lx issue start 123
lx issue start 123 --yes
lx issue start 123 --yes --comment

Prepare a pull request (dry-run by default):

lx pr prepare
lx pr prepare --yes

Examples:

• docs/examples/repo-inspect.md
• docs/examples/issue-start.md
• docs/examples/pr-prepare.md

Development workflow with lx

This is the intended day-to-day loop for a new feature or bugfix in any Labinetix repository once lx is installed. lx wraps git and gh; risky steps stay behind --yes.

flowchart LR
  issue["Issue or bug report"]
  view["lx issue view"]
  start["lx issue start --yes"]
  work["Code tests docs"]
  check["just check + lx workflow check"]
  prepare["lx pr prepare"]
  pr["lx pr prepare --yes"]
  merge["Review + merge main"]
  release["Tag + release notes"]
  issue --> view --> start --> work --> check --> prepare --> pr --> merge --> release

1. Start from an issue

Create a scoped GitHub issue (or use an existing one). The body should include Scope, Tests, and Release impact when possible.

gh issue create --title "fix: ..." --body "## Scope\n..."
lx issue view 123

2. Start the branch

From an up-to-date main:

git checkout main && git pull
lx issue start 123          # preview branch name and readiness
lx issue start 123 --yes --comment

If you prefer a manual branch name, use the Labinetix convention (feat/, fix/, docs/, etc.) and skip --yes.

3. Implement one coherent slice

• Update code, tests, docs, and examples together
• Reference the issue in commits: feat(cli): ... (#123) or Refs #123
• Run the same checks as CI:

just check
lx workflow check

4. Open a pull request

git push -u origin HEAD
lx pr prepare               # preview generated PR body
lx pr prepare --yes         # gh pr create when ready

Review and merge through GitHub as usual. CI and branch protection remain authoritative.

5. Release (maintainers)

After merging to main:

1. Bump version in pyproject.toml and src/lx_tooling/__init__.py
2. Add docs/release-notes/vX.Y.Z.md (see below)
3. Merge the version/release-notes PR
4. Tag on main and push the tag — CI publishes to PyPI and GitHub Releases

git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0

Bugfixes vs features

Kind	Branch prefix	Typical release
Feature	feat/	minor 0.y.0
Bugfix	fix/	patch 0.y.z
Docs only	docs/	patch or none
CI/tooling	ci/	patch

Use lx workflow check before every PR; it warns on wrong branch names, missing AGENTS.md / README.md, and src/ changes without tests/ updates.

What comes later (Milestone 2+)

• lx release plan — summarize changes since last tag
• lx release create — guided, dry-run-first release validation
• More automation does not replace CI, reviews, or protected environments

Design and Agent Rules

• Design: docs/design/lx-tooling.md
• Agent rules: AGENTS.md

Releases and release notes

• Package name on PyPI: lx-tooling
• CLI command: lx
• Latest release: GitHub Releases
• Artifacts: wheel + sdist built by CI on protected SemVer tags (v*), published to PyPI via trusted publishing (pypi.yml, environment pypi)

Release notes practice

Store release notes in the repository, not only on GitHub:

docs/release-notes/vX.Y.Z.md

Each file should include:

• User-facing summary and command changes
• Breaking changes (if any)
• Linked issues and PRs
• Session notes when AI agents helped — goal, approach, verification, follow-ups

See docs/release-notes/README.md for the full template and policy.

The PyPI workflow uses the matching file as the GitHub Release body when you push a tag.

Maintainer checklist

1. Merge feature/fix PRs to main; keep CI green
2. Open a small PR (or commit on main if policy allows) that bumps version + adds docs/release-notes/vX.Y.Z.md
3. Merge to main
4. Tag vX.Y.Z on main and push the tag
5. Confirm PyPI workflow succeeded; verify uv tool install lx-tooling picks up the new version