opsward.cli#
CLI dispatch for opsward.
Functions
|
Diagnose the AI agent setup of one or more projects. |
|
Report-only evals of a project's agent setup: an LLM judge of CLAUDE.md, and golden tasks. |
|
Find assets (skills, agents, docs) across one or more projects by QUERY. |
|
Diagnose many projects at once and roll the results up into one fleet report. |
|
Generate missing AI setup artifacts for one or more projects. |
|
Install opsward's Claude Code skills (and agents) into a project or globally. |
|
Check skill specs and the hooks config: pass or fail, no score (exit 1 on any finding). |
|
Check for stale references, out-of-sync docs, and other drift. |
|
Allocate the next numbered ADR for TITLE (dry run unless --write; never overwrites). |
|
Append TEXT as a dated one-line decision (a Y-statement) to decisions/log.md (dry run unless --write). |
|
Show which agent hosts find project instructions, and how renders drift from AGENTS.md. |
|
Recommend ecosystem skills based on the project's tech stack. |
- opsward.cli.diagnose(*project_roots, format='text', verbose=False, min_score=80)[source]#
Diagnose the AI agent setup of one or more projects.
- opsward.cli.eval_(project_root, *, judge='rubric', samples=1, tasks='', runs=1, format='text')[source]#
Report-only evals of a project’s agent setup: an LLM judge of CLAUDE.md, and golden tasks.
The judge scores CLAUDE.md’s subjective dimensions next to the rubric’s own score. The golden tasks (a JSON list of {name, prompt, expect, forbid}, by default <docs>/evals/golden_tasks.json) run with and without CLAUDE.md and report the pass-rate delta. –judge rubric is free and deterministic (the rubric judge and an agent that quotes the config: it checks the harness, not a model); –judge anthropic makes paid calls (pip install ‘opsward[eval]’). Exits 0 whenever it ran (a report, never a gate); 2 only on a usage error.
- Parameters:
project_root (
str) – the project directoryjudge (
str) – ‘rubric’ (free) or ‘anthropic’ (paid model calls)samples (
int) – judge samples per dimension (the median is reported)tasks (
str) – golden-tasks JSON file (default: <docs>/evals/golden_tasks.json, if present)runs (
int) – runs per golden task and armformat (
str) – output format — ‘text’ or ‘json’
- opsward.cli.find(query, *project_roots, kinds='skill,agent', semantic=False, limit=10)[source]#
Find assets (skills, agents, docs) across one or more projects by QUERY.
Cross-repo asset discovery via the toolery package (install with: pip install ‘opsward[discovery]’).
- opsward.cli.fleet(*project_roots, under='', depth=1, format='text', manifest='')[source]#
Diagnose many projects at once and roll the results up into one fleet report.
The fleet is the given roots, plus the git repos found under –under. With –manifest the fleet is remembered: the roots and the latest summary are written to that JSON file, and a later run with only –manifest re-diagnoses the same roots (given roots or –under replace them). The manifest holds this machine’s absolute paths, so keep it out of version control. Exits 1 when any root could not be diagnosed.
- Parameters:
project_roots (
str) – project directories to diagnoseunder (
str) – also diagnose every git repo found under this directorydepth (
int) – how many levels below –under to look for git reposformat (
str) – output format — ‘text’ or ‘json’ (the name-keyed summary)manifest (
str) – JSON file that remembers the fleet’s roots and its latest summary
- opsward.cli.generate(*project_roots, write=False, format='text', agents_md=False, hooks=False)[source]#
Generate missing AI setup artifacts for one or more projects.
By default, shows what would be created (dry run). Use –write to actually write files. Existing files are never overwritten.
- Parameters:
- opsward.cli.install_skills(target='.', *, global_install=False, agents=True, write=False)[source]#
Install opsward’s Claude Code skills (and agents) into a project or globally.
By default, shows what would be created (dry run). Use –write to actually write files. Existing files are never overwritten.
- opsward.cli.lint(*project_roots, validators='auto', format='text')[source]#
Check skill specs and the hooks config: pass or fail, no score (exit 1 on any finding).
The strict counterpart of
diagnose --min-score, for CI and pre-commit. Validators: opsward (its own agentskills.io check, always there), skill (the skill package’s validate(); pip install ‘opsward[lint]’), and the external agnix and skillcheck linters (opt-in by name). auto runs opsward and skill, each when installed.
- opsward.cli.maintain(*project_roots, format='text')[source]#
Check for stale references, out-of-sync docs, and other drift.
Each finding carries a recommended triage: align (update the config to match the code), revert (restore the code the config describes) or ignore (a legitimately volatile reference: put
opsward: ignore-pathon its line).
- opsward.cli.new(title, write=False, project_root='.', status='Proposed', evidence='')[source]#
Allocate the next numbered ADR for TITLE (dry run unless –write; never overwrites).
- Parameters:
title (
str) – the decision’s title; the file name is derived from itwrite (
bool) – actually write the file (default: dry run)project_root (
str) – the project directory (default: current dir)status (
str) – initial status — Proposed (default), or Accepted when the human has accepted itevidence (
str) – the issue, discussion or PR this rests on (a URL or #N)
- opsward.cli.note(text, write=False, project_root='.')[source]#
Append TEXT as a dated one-line decision (a Y-statement) to decisions/log.md (dry run unless –write).
- opsward.cli.portability(*project_roots, format='text')[source]#
Show which agent hosts find project instructions, and how renders drift from AGENTS.md.
One row per host (claude, codex, copilot, cursor, …) with how it is covered: symlink, import (an @AGENTS.md shim), native (reads AGENTS.md itself), copy, rules, or none. Then every section where a render differs from AGENTS.md, and (with opsward[lint]) every project skill whose render drops fields. Report-only.