Metadata-Version: 2.4
Name: opsward
Version: 0.0.8
Summary: Diagnose, generate, and maintain the AI agent setup of your projects — CLAUDE.md, skills, subagents, rules, and supporting docs.
Project-URL: Homepage, https://github.com/thorwhalen/opsward
Project-URL: Repository, https://github.com/thorwhalen/opsward
Project-URL: Documentation, https://thorwhalen.github.io/opsward
Author: Thor Whalen
License: mit
License-File: LICENSE
Keywords: ai-agents,claude,code-quality,developer-tools,documentation
Requires-Python: >=3.10
Requires-Dist: argh>=0.31
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
Requires-Dist: sphinx>=6.0; extra == 'docs'
Description-Content-Type: text/markdown

# 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

```bash
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:

```bash
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):

```bash
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:

```bash
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:

```bash
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

```bash
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

```python
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:

```bash
# 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
```

```yaml
# .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](https://github.com/github/spec-kit) (GitHub) | Template-based scaffolding for 20+ AI agents. No diagnosis/scoring/maintenance. |
| [claude-code-skill-factory](https://github.com/alirezarezvani/claude-code-skill-factory) | Inside-agent builders for skills, agents, hooks. Good for interactive authoring. |
| [ccexp](https://github.com/nyatinte/ccexp) | Interactive TUI for browsing Claude Code config files. Complements opsward. |
| [npx skills](https://github.com/vercel-labs/skills) (Vercel) | Cross-platform skill package manager. Opsward-generated skills are compatible. |
| [awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills) | 549+ community skills from official dev teams. |
| [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) | Best single index of the Claude Code ecosystem. |
| [wshobson/agents](https://github.com/wshobson/agents) | Pre-built plugin monorepo (72 plugins, 112 agents, 146 skills). |
| [Mintlify skill.md](https://www.mintlify.com/blog/skill-md) | Auto-generates skill.md from docs sites. Same philosophy, different input. |
