opsward#

Diagnose, generate, and maintain the AI agent setup of your projects — CLAUDE.md, skills, subagents, rules, and supporting docs.

Opsward works in two modes:

  • CLI mode — deterministic, pure-code analysis you run directly. No AI involved.

  • Claude Code mode — install opsward as Claude Code skills so that Claude runs the CLI tools, interprets results intelligently, and acts on suggestions. No API keys needed — Claude Code is the AI engine.

Install#

pip install opsward

CLI Mode (no AI)#

These commands are deterministic Python code — regex scoring, filesystem checks, template substitution. Same input always gives the same output.

Diagnose#

Score your project’s AI setup health:

opsward diagnose .

Diagnosis Report: myproject
Project type: python
Overall score: 72/100  (Grade: C)

Components:
  CLAUDE.md quality         [################....] 81/100
  Documentation             [##############......] 70/100
  Skills                    [############........] 60/100
  Setup (rules/agents/hooks) [##########..........] 50/100
  Cross-references          [####################] 100/100

Missing:
  [ ] docs_guide.md
  [ ] docs/known_issues.md

Suggestions:
  1. Create a docs_guide.md to index your documentation
  2. Consider adding hooks in .claude/hooks.json

Generate#

Create missing artifacts (dry run by default):

opsward generate .
opsward generate . --write   # actually create files

Generates CLAUDE.md, docs (architecture, conventions, known_issues, etc.), skill templates, and agents — only what’s missing, never overwrites existing files.

Maintain#

Find stale references and drift:

opsward maintain .

myproject: 3 issue(s)

  [stale_path] CLAUDE.md references `src/old_module.py` but it does not exist
  [sync_issue] `new_doc.md` exists in docs/ but is not listed in docs_guide.md
  [empty_doc] `conventions.md` appears to be an empty stub (12 bytes)

Output Formats#

All CLI commands support --format json for machine-parseable output:

opsward diagnose . --format json
opsward generate . --format json
opsward maintain . --format json

Claude Code Mode (AI-enhanced)#

Install opsward’s skills into Claude Code, and Claude becomes an intelligent layer on top of the deterministic tools. It doesn’t just run opsward — it goes beyond the heuristic scores by reading actual source code, reasoning about accuracy, and making intelligent edits.

Install Skills#

opsward install-skills --write                    # into ./.claude/ (project-level)
opsward install-skills --global-install --write   # into ~/.claude/ (all projects)

What the Skills Do#

Once installed, these skills activate automatically in Claude Code when you ask the right thing:

Skill

Trigger

What it does

opsward

“check my setup”, “opsward”

Diagnose → decide next step → generate or maintain → re-diagnose

opsward-diagnose

“audit my AI config”

Run opsward diagnose, then read code to assess semantic quality, offer fixes

opsward-generate

“scaffold AI setup”

Run opsward generate, then read the codebase and replace templates with real content

opsward-maintain

“check for staleness”

Run opsward maintain, then check for semantic drift (docs that no longer match code)

How It Works#

  1. Opsward CLI runs deterministic checks (regex scoring, path validation, template substitution) — fast, reproducible, no AI

  2. Claude reads the output and adds deeper analysis: reads actual source code, checks if docs match reality, verifies commands are correct

  3. Claude proposes fixes — not just what opsward suggests, but what it discovers by understanding the code

  4. Claude applies fixes with user approval, then re-runs opsward to show improvement

The CLI provides the structural analysis. Claude provides the semantic understanding and action.

Permissions#

The skills use Claude Code’s standard permission model — no special permissions are assumed or required:

  • Read-only operations (reading files, searching code, running opsward diagnose): always safe, used freely

  • Write operations (creating docs, editing CLAUDE.md): Claude Code prompts the user for each action per their permission settings

  • Destructive operations (deleting files, removing content): always ask for explicit confirmation

If you want faster workflows (e.g., auto-approve file creation during generation), you can configure that in your Claude Code permission settings — but opsward skills never assume it.

What It Checks#

CLAUDE.md quality (6 dimensions):

  • Commands & workflows — are build/test/lint commands documented?

  • Architecture clarity — is there a module map with role descriptions?

  • Conventions — are project-specific style rules present?

  • Conciseness — is the file scannable, not bloated?

  • Currency — do referenced paths actually exist?

  • Actionability — are instructions specific enough to act on?

Documentation completeness: docs_guide.md, architecture.md, conventions.md, known_issues.md, and content quality.

Skills & agents: SKILL.md presence, descriptions, setup-auditor agent.

Cross-references: paths in CLAUDE.md validated against the filesystem.

Overall health: weighted score (A–F grade) combining all components.

Python API#

from pathlib import Path
from opsward import scan, diagnose, generate, generate_skills, maintain
from opsward import recommend_skills, validate_skill_spec

sr = scan(".")
report = diagnose(sr)
print(report)  # human-readable report card
print(report.grade)  # 'A', 'B', 'C', 'D', or 'F'

files = generate(sr)  # list[GeneratedFile]
issues = maintain(sr)  # list[MaintenanceSuggestion]

# Recommend ecosystem skills based on tech stack
recs = recommend_skills(sr)  # list[SkillRecommendation]

# Validate skills against agentskills.io spec
for skill in sr.skills:
    violations = validate_skill_spec(skill)

# Install skills programmatically
skill_files = generate_skills(Path.home() / ".claude")

CI Integration#

Use opsward in CI to enforce AI setup quality:

# Fail if overall score drops below 60
opsward diagnose . --min-score 60

# Machine-parseable output for CI tooling
opsward diagnose . --format json --min-score 60

# .github/workflows/ai-setup-check.yml
name: AI Setup Check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install opsward
      - run: opsward diagnose . --min-score 60

built 2026-09-22 17:17 UTC from abc162c (main) · opsward 0.0.14 · about this build