opsward 0.0.8

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.

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

Related Work

Project	Relationship
spec-kit (GitHub)	Template-based scaffolding for 20+ AI agents. No diagnosis/scoring/maintenance.
claude-code-skill-factory	Inside-agent builders for skills, agents, hooks. Good for interactive authoring.
ccexp	Interactive TUI for browsing Claude Code config files. Complements opsward.
npx skills (Vercel)	Cross-platform skill package manager. Opsward-generated skills are compatible.
awesome-agent-skills	549+ community skills from official dev teams.
awesome-claude-code	Best single index of the Claude Code ecosystem.
wshobson/agents	Pre-built plugin monorepo (72 plugins, 112 agents, 146 skills).
Mintlify skill.md	Auto-generates skill.md from docs sites. Same philosophy, different input.