lx-tooling

Tag: Org and orchestration · CLI: lx · PyPI: lx-tooling

lx-tooling is the Labinetix engineering workflow CLI for humans and AI agents. It orchestrates the GitHub issue → branch → pull request → release loop and checks repository policy, without owning domain logic or company strategy.

What this repository is

Labinetix's company strategy, durable architecture, and cross-repo design decisions live in ../.VAULT/. This repository implements the engineering workflow toolstack that consumes those rules. The operating model rests on a few ideas:

• GitHub is the durable coordination layer. Issues are the backlog and the development memory; PRs are the review record; releases are the shipped product.
• Issues are strictly typed and related natively. Work is classified with GitHub issue types and connected with sub-issues and blocked-by/blocking dependencies (GitHub Issues 2.0), not ad-hoc labels or free text.
• Local Cursor agents do the implementation, driving git/gh; a cloud coding agent is an optional secondary lane for small chores.
• CI is the merge gate. Leaf implementation PRs auto-merge on green CI (ADR-0013); humans own product judgment, stable-release authorization (ADR-0014), and deployment.

lx-tooling is the front-end that makes the correct path the easy path. It wraps git, gh, repository metadata, and Labinetix policy so that humans and agents run one consistent, dry-run-first, JSON-emitting command instead of remembering every rule. It does not replace git, gh, CI, GitHub review, or branch protection — those stay authoritative.

Non-goals: model semantics, ABI/schema ownership, runtime algorithms, protocol implementations, build logic (lx-toolchains), deployment (lx-deploy), or hardware validation (lx-testbench).

Strategy boundary: .VAULT owns company strategy and generalized architecture. lx-tooling owns scoped, tested engineering workflow commands. See docs/design/adr-0001-lx-tooling-policy-boundary.md.

How lx relates to gh and git

Think of three layers:

Guiding rule: lx consumes native gh primitives and adds Labinetix interpretation. It does not re-implement anything gh already does well. Before a feature is added to lx, we check whether gh ... --json already covers it.

Workflow ↔ command map

Legend: ✅ shipped in lx 1.0 (stability surface) · 🔜 planned post-1.0 · 🟦 use gh/git directly (native command already covers it precisely; lx will not wrap it)

In short: lx ships the policy-heavy orchestration (readiness, branch start, PR body, release preflight); gh keeps the precise platform operations (relationship edits, CI inspection, releases); and the 🔜 rows are where lx still adds value on top of gh.

Reading the whole backlog: the issue graph

Both you and an agent need to see the entire issue knowledge base at any moment. GitHub Issues 2.0 stores issue types, sub-issues, and blocked-by/blocking dependencies natively, and a single GraphQL query returns the whole open backlog with those relationships in one round-trip (measured: 63 issues in ~1.5s, no pagination under 100). No background-synced database is needed.

Load the derived graph (recommended — from a clone use uv run lx until lx-tooling is installed globally):

uv run lx issue graph
uv run lx issue graph --json > issue-graph.json
uv run lx issue graph --include-recent-closed --since 90d --json

lx issue graph runs the live GraphQL query and adds the derived view GitHub does not give for free: ready-vs-blocked ordering, dependency-cycle detection, roots/leaves, per-issue created_at/updated_at timestamps, and an agent-friendly denormalized shape. With --include-recent-closed, it also merges a recent closed slice (PR-seeded closures plus a time window) for familiarization — use lx issue context <n> for full comment bodies on specific closed threads.

Inspect native relationship coverage:

jq '.summary | {open: .open_count, typed: .typed_count, parented: .parented_count, deps: .with_dependencies_count, ready: (.ready | length), blocked: (.blocked | length), leaves: (.leaves | length)}' issue-graph.json

The graph is structure only — fetch full comment bodies on candidate issues with lx issue context <n> --json (preferred) or gh issue view <n> --json …,comments. Human gh issue view <n> --comments is a quick preview only; the terminal renderer may truncate long closure comments. For backlog curation, use the lx-backlog-groom skill.

Set relationships natively (these are 🟦 gh, not lx):

gh issue edit <n> --type "Feature"
gh issue edit <epic> --add-sub-issue <child1>,<child2>
gh issue edit <n> --add-blocked-by <blocker>

Keeping the issue knowledge base current

Because issues are the durable memory, they must stay honest. When the workflow or manifests change, some open issues go stale: already shipped, superseded by a native gh feature, duplicate titles for the same scope, or no longer matching the workflow. Stale issues mislead both humans and agents and make the graph meaningless.

Before creating issues: search open titles first (gh issue list --search "in:title …") so maintainer and agent do not open the same scope twice in one session. See AGENTS.md § Backlog and readiness.

The fix is a recurring reconciliation pass. Start with the dry-run audit:

uv run lx issue audit
uv run lx issue audit --json

lx issue audit loads the graph, fetches issue bodies by default, and flags deterministic hygiene findings: closed blockers, deprecated pre-1.0 labels, hold on epics, duplicate titles, and raw/thin bodies. It never closes issues and does not edit labels or native edges. With --yes, it posts the generated Reconciliation comments only:

uv run lx issue audit --yes

For deeper curation, give Cursor an instruction such as:

Load issue-graph.json. For every open issue, judge it against the current repository state, the shipped lx surface (lx --help), latest docs/release-notes/v*.md, and the workflow model in ../.VAULT/MANIFEST.md. Flag issues that are (a) already implemented, (b) superseded by a native gh feature such as issue types / sub-issues / dependencies, or (c) inconsistent with the updated workflow. For each, propose: comment, relabel, set a dependency, or close as superseded. Do not close anything silently — leave a Reconciliation comment first. For a full autonomous pass, use the lx-backlog-groom skill and commit the session report under docs/reports/.

For each stale issue, the agent (or you) leaves a comment and relabels — never a silent close:

# Mark an issue as superseded by a native GitHub feature, with rationale
gh issue comment <n> --body "Re-triage: the relationship modelling planned here is now native (GitHub Issues 2.0 dependencies/sub-issues, exposed via gh + GraphQL). See ../.VAULT/MANIFEST.md. Recommend closing as superseded; remaining policy value tracked in #<m>."

# Opt out of the AFK queue until a human confirms
gh issue edit <n> --add-label "hold:design"

# Only after human confirmation:
gh issue close <n> --reason "not planned" --comment "Superseded by native GitHub issue dependencies. Tracked in #<m>."

lx issue audit automates the load + heuristic flagging (contradictory labels, duplicate titles, raw/thin bodies, stale blockers) and can emit suggested Reconciliation comments with --yes — but closing issues stays a human decision.

Quickstart

Prerequisites:

• Python 3.11+
• uv
• gh v2.94.0+ (native issue types/sub-issues/dependencies), authenticated with gh auth login

Local development:

git clone git@github.com: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

Working across repositories

Work-repo commands resolve the git checkout and GitHub repository from the process cwd by default. That breaks when you run lx from a different clone — for example uv run --directory lx-tooling lx issue start 42 while scoped to .VAULT targets lx-tooling#42.

Prefer one of:

# Install lx on PATH, then work from the target repo
cd ../.VAULT && lx issue start 42 --yes --comment

# Or pass the target checkout explicitly (group flags before the subcommand)
cd lx-tooling
uv run lx issue --repo-root ../.VAULT start 42 --yes --comment
uv run lx workflow --repo-root ../.VAULT check
uv run lx pr --repo-root ../.VAULT prepare --yes
uv run lx issue --repo-url https://github.com/labinetix/.VAULT view 42

--repo-root sets the local git root for branch creation, workflow checks, PR preparation, and metadata. --repo-url pins gh -R owner/name (git operations still need a matching local clone or --repo-root). Without override, lx issue view / context / start warn when the fetched issue URL disagrees with the resolved checkout.

Optional .labinetix/repo.toml:

[github]
repository = "labinetix/.VAULT"

Install

uv tool install lx-tooling
lx --version

Upgrade:

uv tool upgrade lx-tooling

Command reference (1.0 stability surface + 1.1 additions)

Frozen 1.0 command/flag contract: docs/design/cli-stability-1.0.md. 1.1.0 adds lx contract changelog (minor release per SemVer policy).

# Orient
lx repo inspect
lx repo inspect --json

# Discover work
lx issue graph
lx issue graph --json
lx issue graph --include-recent-closed --since 90d --json
lx issue audit
lx issue audit --json
lx issue list --ready
lx issue list --label area:workflow
lx issue view 123
lx issue context 123
lx issue context 123 --json

# Start work (dry-run unless --yes; branch prefix inferred from issue type + git preflight)
lx issue start 123
lx issue start 123 --yes --comment
lx issue --repo-root ../other-repo start 123 --yes --comment

# Verify before a PR
just check
lx workflow check
lx workflow --repo-root ../other-repo check

# Open a PR (dry-run unless --yes)
lx pr prepare
lx pr prepare --yes
lx pr --repo-root ../other-repo prepare --yes

# Plan / validate a release (never tags or publishes)
lx release plan
lx release create 0.8.0
lx release create 0.8.0 --yes
lx release notes draft 0.8.0

# Contract changelog (1.1.0+)
lx contract changelog main..HEAD
lx contract --repo-root ../lx-interface changelog v1.0.0..HEAD --json
lx release notes draft 0.8.0 --yes

Examples:

• docs/examples/repo-inspect.md
• docs/examples/issue-list.md
• docs/examples/issue-context.md
• docs/examples/issue-start.md
• docs/examples/issue-closure-comment.md
• docs/examples/pr-prepare.md
• docs/examples/release-plan.md
• docs/examples/release-notes-draft.md

Development loop with lx

The intended day-to-day loop in any Labinetix repository. lx wraps git/gh; risky steps stay behind --yes.

flowchart LR
  graph["lx issue graph"]
  view["lx issue view"]
  start["lx issue start --yes"]
  work["code + tests + docs"]
  check["just check + lx workflow check"]
  pr["lx pr prepare --yes"]
  merge["auto-merge on green CI"]
  release["release plan + human-authorized tag"]
  graph --> view --> start --> work --> check --> pr --> merge --> release

1. See the backlog. Load the issue graph and pick a ready, scoped issue. Fetch full comment bodies on candidates with lx issue context <n> --json — the graph is structure only; human gh issue view --comments may truncate. Skills (lx-skills catalog): lx-backlog-groom (curation → docs/reports/), lx-release-planning (release horizon), lx-feature-implementation (unbiased pick + implement, incl. release-plan and follow-up lanes), lx-release-prepare (compile notes + tag).

2. Confirm scope. lx issue context 123 --json (or lx issue context 123). Set/verify native type, parent, and dependencies with gh issue edit; explain the rationale in a Plan comment.

3. Start the branch. From an up-to-date main:

   git checkout main && git pull
   lx issue start 123 --yes --comment
   # When cwd is not the work repo: lx issue --repo-root <path> start 123 --yes --comment
   

4. Implement one coherent slice — code, tests, docs, examples together; reference the issue (feat(cli): ... (#123)).

5. Verify. just check then lx workflow check.

6. Open the PR.

   git push -u origin HEAD
   lx pr prepare          # preview body
   lx pr prepare --yes    # gh pr create with Closes #123
   

7. Merge on green CI. Leaf PRs auto-merge once required checks pass (ADR-0013); the issue closes on merge via the closing keyword. The stable release tag/publish stays human-authorized (ADR-0014).

8. Close the loop on the issue. Post an after-merge comment with what users can do now, verification, release impact, suggested next issues, and any workflow observations. See docs/examples/issue-closure-comment.md.

Releases and release notes

• 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).

Store release notes in the repository (docs/release-notes/vX.Y.Z.md) drafted from merged PRs and the issues they closed. See docs/release-notes/README.md. 1.2.0 improves release-command ergonomics: PEP 440 pre-releases (1.0.0rc1) and cross-repo title resolution in lx release notes draft. Release planning (what should ship): lx-release-planning. Release preparation (compile notes + tag after merge): lx-release-prepare. Maintainer flow:

1. Merge feature/fix PRs to main; keep CI green.

2. Bump version in pyproject.toml and src/lx_tooling/__init__.py; add docs/release-notes/vX.Y.Z.md.

3. Merge to main, then tag and push:

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

4. Confirm the PyPI workflow succeeded; verify uv tool install lx-tooling picks up the new version.

Design and agent rules

• Workflow model: ../.VAULT/MANIFEST.md and ../.VAULT/adr/
• Design: docs/design/lx-tooling.md
• 1.0 CLI stability contract: docs/design/cli-stability-1.0.md
• Agent rules: AGENTS.md