opsward 0.0.3

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

opsward

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

Install

pip install opsward

Quick Start

Diagnose

Score your project's AI setup health:

opsward diagnose-cmd .

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-cmd .
opsward generate-cmd . --write   # actually create files

Generates CLAUDE.md, docs (architecture, conventions, known_issues, etc.), AI-enhanced skills (opsward, opsward-diagnose, opsward-generate, opsward-maintain), and agents (setup-auditor) — only what's missing, never overwrites existing files.

Install Skills

Install opsward's Claude Code skills into a project (or globally):

opsward install-skills-cmd                  # dry run for current project
opsward install-skills-cmd --write          # install into ./.claude/
opsward install-skills-cmd --global-install --write  # install into ~/.claude/

The installed skills let Claude Code run opsward's deterministic tools, interpret the results intelligently, and act on suggestions — no API keys needed, Claude Code is the AI engine.

Skill	Trigger	What it does
opsward	"check my setup"	Diagnose → decide next step → generate or maintain → re-diagnose
opsward-diagnose	"audit my AI config"	Run opsward diagnose, interpret scores, offer fixes
opsward-generate	"scaffold AI setup"	Run opsward generate, review, customize with real content
opsward-maintain	"check for staleness"	Run opsward maintain, prioritize issues, apply fixes

Maintain

Find stale references and drift:

opsward maintain-cmd .

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)

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.

Output Formats

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

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

Python API

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

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]

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