opsward 0.0.2__tar.gz

opsward-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

opsward-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,213 @@
+name: Continuous Integration (2025-11)
+on: [push, pull_request]
+
+# Note: Environment variables (PROJECT_NAME and vars from [tool.wads.ci.env])
+# are set by the read-ci-config action in the setup job and made available
+# to all subsequent jobs via GITHUB_ENV
+
+jobs:
+  # First job: Read configuration from pyproject.toml
+  setup:
+    name: Read Configuration
+    runs-on: ubuntu-latest
+    outputs:
+      project-name: ${{ steps.config.outputs.project-name }}
+      python-versions: ${{ steps.config.outputs.python-versions }}
+      pytest-args: ${{ steps.config.outputs.pytest-args }}
+      coverage-enabled: ${{ steps.config.outputs.coverage-enabled }}
+      exclude-paths: ${{ steps.config.outputs.exclude-paths }}
+      test-on-windows: ${{ steps.config.outputs.test-on-windows }}
+      build-sdist: ${{ steps.config.outputs.build-sdist }}
+      build-wheel: ${{ steps.config.outputs.build-wheel }}
+      metrics-enabled: ${{ steps.config.outputs.metrics-enabled }}
+      metrics-config-path: ${{ steps.config.outputs.metrics-config-path }}
+      metrics-storage-branch: ${{ steps.config.outputs.metrics-storage-branch }}
+      metrics-python-version: ${{ steps.config.outputs.metrics-python-version }}
+      metrics-force-run: ${{ steps.config.outputs.metrics-force-run }}
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Read CI Config
+        id: config
+        uses: i2mint/wads/actions/read-ci-config@master
+        with:
+          pyproject-path: .
+
+  # Second job: Validation using the config
+  validation:
+    name: Validation
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    needs: setup
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ${{ fromJson(needs.setup.outputs.python-versions) }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install System Dependencies
+        uses: i2mint/wads/actions/install-system-deps@master
+        with:
+          pyproject-path: .
+
+      - name: Install Dependencies
+        uses: i2mint/wads/actions/install-deps@master
+        with:
+          dependency-files: pyproject.toml
+          extras: dev,test
+
+      - name: Format Source Code
+        uses: i2mint/wads/actions/ruff-format@master
+        with:
+          line-length: 88
+          target-path: .
+
+      - name: Lint Validation
+        uses: i2mint/wads/actions/ruff-lint@master
+        with:
+          root-dir: ${{ needs.setup.outputs.project-name }}
+          output-format: github
+
+      - name: Run Tests
+        uses: i2mint/wads/actions/run-tests@master
+        with:
+          root-dir: ${{ needs.setup.outputs.project-name }}
+          exclude: ${{ needs.setup.outputs.exclude-paths }}
+          coverage: ${{ needs.setup.outputs.coverage-enabled }}
+          pytest-args: ${{ needs.setup.outputs.pytest-args }}
+
+      - name: Track Code Metrics
+        if: needs.setup.outputs.metrics-enabled == 'true'
+        uses: i2mint/umpyre/actions/track-metrics@master
+        continue-on-error: true
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          config-path: ${{ needs.setup.outputs.metrics-config-path }}
+          storage-branch: ${{ needs.setup.outputs.metrics-storage-branch }}
+          python-version: ${{ needs.setup.outputs.metrics-python-version }}
+          force-run: ${{ needs.setup.outputs.metrics-force-run }}
+
+  # Optional Windows testing (if enabled in config)
+  windows-validation:
+    name: Windows Tests
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && needs.setup.outputs.test-on-windows == 'true'"
+    needs: setup
+    runs-on: windows-latest
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ fromJson(needs.setup.outputs.python-versions)[0] }}
+
+      - name: Install System Dependencies
+        uses: i2mint/wads/actions/install-system-deps@master
+        with:
+          pyproject-path: .
+
+      - name: Install Dependencies
+        uses: i2mint/wads/actions/install-deps@master
+        with:
+          dependency-files: pyproject.toml
+          extras: dev,test
+
+      - name: Run tests
+        id: test
+        continue-on-error: true
+        run: pytest
+
+      - name: Report test results
+        if: always()
+        run: |
+          if ("${{ steps.test.outcome }}" -eq "failure") {
+            echo "::warning::Windows tests failed but workflow continues"
+            echo "## ⚠️ Windows Tests Failed" >> $env:GITHUB_STEP_SUMMARY
+            echo "Tests failed on Windows but this is informational only." >> $env:GITHUB_STEP_SUMMARY
+          } else {
+            echo "## ✅ Windows Tests Passed" >> $env:GITHUB_STEP_SUMMARY
+          }
+
+  # Publishing job
+  publish:
+    name: Publish
+    permissions:
+      contents: write
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main')"
+    needs: [setup, validation]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ fromJson(needs.setup.outputs.python-versions)[0] }}
+
+      - name: Format Source Code
+        uses: i2mint/wads/actions/ruff-format@master
+
+      - name: Update Version Number
+        id: version
+        uses: i2mint/isee/actions/bump-version-number@master
+
+      - name: Build Distribution
+        uses: i2mint/wads/actions/build-dist@master
+        with:
+          sdist: ${{ needs.setup.outputs.build-sdist }}
+          wheel: ${{ needs.setup.outputs.build-wheel }}
+
+      - name: Publish to PyPI
+        uses: i2mint/wads/actions/pypi-upload@master
+        with:
+          pypi-username: ${{ secrets.PYPI_USERNAME }}
+          pypi-password: ${{ secrets.PYPI_PASSWORD }}
+          skip-existing: false
+
+      - name: Force SSH for git remote
+        run: |
+          git remote set-url origin git@github.com:${{ github.repository }}.git
+          
+      - name: Commit Changes
+        uses: i2mint/wads/actions/git-commit@master
+        with:
+          commit-message: "**CI** Formatted code + Updated version to ${{ env.VERSION }} [skip ci]"
+          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
+          push: true
+
+      - name: Tag Repository
+        uses: i2mint/wads/actions/git-tag@master
+        with:
+          tag: ${{ env.VERSION }}
+          message: "Release version ${{ env.VERSION }}"
+          push: true
+
+  # Optional GitHub Pages
+  github-pages:
+    name: Publish GitHub Pages
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    if: "!contains(github.event.head_commit.message, '[skip ci]') && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)"
+    needs: publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: i2mint/epythet/actions/publish-github-pages@master
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          ignore: "tests/,scrap/,examples/"

opsward-0.0.2/.gitignore

@@ -0,0 +1,121 @@
+wads_configs.json
+data/wads_configs.json
+wads/data/wads_configs.json
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

opsward-0.0.2/CLAUDE.md

@@ -0,0 +1,174 @@
+# Opsward
+
+Diagnose, generate, and maintain the AI agent setup of your projects — CLAUDE.md, skills, subagents, rules, and supporting docs.
+
+## Project Overview
+
+Opsward is a Python CLI tool (and library) that treats a project's AI agent configuration as a first-class artifact. It scans project roots, reports what's missing or stale, scaffolds missing pieces from templates, and keeps everything current as the codebase evolves. It works on Python projects, JS/TS projects, and mixed repos.
+
+There is also an `ow` PyPI package that is a thin re-export shim for `opsward`.
+
+## Tech Stack
+
+- **Language:** Python 3.10+
+- **CLI:** `argh` for dispatching functions to CLI commands
+- **Templates:** String-based (`string.Template` or simple f-string/jinja2-minimal) — keep deps light
+- **Data structures:** `dataclasses` for models, `Mapping`/`MutableMapping` where storage is involved
+- **File access:** `importlib.resources.files` for bundled templates in `opsward/data/`
+- **Testing:** `pytest`, doctests where practical
+- **No heavy deps:** This is a lightweight diagnostic/scaffolding tool. Avoid pulling in large frameworks.
+
+## Documentation
+
+For detailed project knowledge, see `misc/docs/docs_guide.md`.
+Read it to discover which docs to consult for your current task.
+
+Key docs to read before starting work:
+- `misc/docs/ai_setup_meta_tooling.md` — the foundational research report (what exists, what we're building, why)
+- `misc/docs/architecture.md` — system design, module responsibilities, data flow
+- `misc/docs/conventions.md` — coding style and patterns for this project
+- `misc/docs/target_artifacts.md` — complete spec of what opsward generates for target projects
+
+## Module Map
+
+- `opsward/` — the main package
+  - `__init__.py` — public interface (the facade). Exports `diagnose`, `generate`, `maintain`, key types
+  - `base.py` — core data structures: `ProjectType`, `DiagnosisReport`, `DocSpec`, `SetupComponent`, scoring models
+  - `scan.py` — read-only filesystem scanning: detect project type, find CLAUDE.md, skills, agents, rules, hooks, docs
+  - `score.py` — quality scoring: CLAUDE.md rubric, skill validation, doc freshness, cross-reference checks
+  - `generate.py` — template rendering and file generation (never overwrites without confirmation)
+  - `maintain.py` — staleness detection, update suggestions, drift analysis
+  - `cli.py` — argh-based CLI entry point
+  - `util.py` — internal helpers (underscore-prefixed)
+  - `data/` — bundled package resources (accessed via `importlib.resources.files`)
+    - `templates/` — generation templates organized by target project type
+      - `shared/` — templates that work for any project type
+      - `python/` — Python-specific templates (paths use `misc/docs/`)
+      - `jsts/` — JS/TS-specific templates (paths use `docs/`)
+    - `rubrics/` — scoring criteria (YAML or TOML)
+    - `skills/` — Claude Code skill templates that opsward installs into target projects
+- `tests/` — pytest tests
+
+## Commands
+
+```bash
+# Install
+pip install opsward   # or: pip install ow
+
+# CLI usage
+python -m opsward diagnose /path/to/project          # Diagnose AI setup
+python -m opsward diagnose /path/to/proj1 /path/to/proj2  # Multi-project
+python -m opsward generate /path/to/project           # Generate missing pieces
+python -m opsward maintain /path/to/project            # Check for staleness/drift
+
+# After pip install (via pyproject.toml [project.scripts]):
+opsward diagnose .
+opsward generate . --dry-run
+opsward maintain .
+```
+
+## Conventions
+
+### Python Style
+
+- Functional over OOP. Use dataclasses for data, plain functions for logic.
+- Keyword-only arguments from the 3rd position onward.
+- Small helper functions: inner if single-caller, underscore-prefixed if module-private.
+- Minimal docstrings on everything. Simple doctests when practical.
+- `yield` over `return list`. Generators for sequences.
+- `Mapping`/`MutableMapping` for storage abstractions.
+- Use `importlib.resources.files("opsward.data")` to access bundled templates — never hardcode filesystem paths to package data.
+
+### CLI Pattern
+
+Follow the argh SSOT dispatch pattern:
+
+```python
+# In cli.py
+_dispatch_funcs = [diagnose, generate, maintain]
+
+if __name__ == "__main__":
+    import argh
+    argh.dispatch_commands(_dispatch_funcs)
+```
+
+```python
+# In __main__.py
+from opsward.cli import _dispatch_funcs
+import argh
+argh.dispatch_commands(_dispatch_funcs)
+```
+
+### Template Pattern
+
+Templates live in `opsward/data/templates/`. They are plain markdown files with `${variable}` placeholders (using `string.Template`). The generator reads them via `importlib.resources`, substitutes variables from the scan results, and writes to the target project.
+
+### Scoring Pattern
+
+Scoring functions are pure: `(scan_result) -> score_dict`. No side effects. The rubric definitions live in `opsward/data/rubrics/` as YAML. Scoring dimensions for CLAUDE.md (inspired by community best practices):
+
+1. **Commands/Workflows** (0-20): Are build/test/run commands documented?
+2. **Architecture Clarity** (0-20): Is the module map present and accurate?
+3. **Conventions** (0-15): Are non-obvious patterns documented?
+4. **Conciseness** (0-15): Is it dense and scannable, not bloated?
+5. **Currency** (0-15): Do referenced paths/files actually exist?
+6. **Actionability** (0-15): Can an agent act on the instructions without guessing?
+
+### Project Type Detection
+
+```python
+# Detection signals — check in this order:
+PYTHON_SIGNALS = ("pyproject.toml", "setup.py", "setup.cfg", "Pipfile")
+JSTS_SIGNALS = ("package.json", "tsconfig.json", "deno.json")
+
+# Docs location by type:
+# Python  -> misc/docs/
+# JS/TS   -> docs/
+# Mixed   -> docs/  (JS/TS convention wins)
+```
+
+### What Opsward Generates for Target Projects
+
+When generating for a target project, opsward can produce:
+
+**Documentation layer** (the `docs/` or `misc/docs/` folder):
+- `docs_guide.md` — always first. Entry point listing all other docs.
+- `architecture.md`, `known_issues.md`, `conventions.md`, `roadmap.md`, `glossary.md`, `testing.md`, `dependencies.md`, `deployment.md`
+- `decisions/` folder for MADR-style architectural decision records
+
+**AI configuration layer** (the `.claude/` folder):
+- `CLAUDE.md` at project root (or updates to existing one)
+- `.claude/skills/diagnose-setup/SKILL.md` — the diagnostic skill
+- `.claude/skills/maintain-docs/SKILL.md` — the doc maintenance skill
+- `.claude/agents/setup-auditor.md` — read-only auditor subagent
+- `.claude/rules/` files if appropriate
+
+See `misc/docs/target_artifacts.md` for the full spec of generated artifacts.
+
+### Output Principles
+
+- **Never overwrite** existing files without explicit confirmation.
+- **Dry-run by default** for generate/maintain. Use `--write` or `--apply` to actually write.
+- **Diff-first**: Show what would change before changing it.
+- **Minimal generation**: Only suggest docs/skills that are genuinely useful for the detected project type. Don't generate a `deployment.md` template for a library with no deployment.
+
+## Non-Obvious Patterns
+
+- Templates are **not** Jinja2. Use `string.Template` for simplicity and zero deps. If a template needs conditionals, split it into separate template files per variant.
+- The `diagnose` function returns a `DiagnosisReport` dataclass that is both human-readable (via `__str__`) and machine-consumable (via dataclass fields). The CLI pretty-prints it; library users get structured data.
+- The `scan.py` module must be **purely read-only** — it never modifies the target project. This is a hard invariant. It uses `pathlib.Path` and `os.walk`, never writes.
+- For multi-project scanning, each project gets its own `DiagnosisReport`. There is also an aggregate `MultiProjectReport` that summarizes cross-project patterns.
+- The `ow` shim package is a separate `pyproject.toml` / directory. It literally just does `from opsward import *` and declares `opsward` as a dependency.
+
+## Git Workflow
+
+- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
+- No AI attribution in commit messages.
+
+## Build & Test
+
+```bash
+pip install -e ".[dev]" --break-system-packages
+pytest
+pytest --doctest-modules opsward/
+```

opsward-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opsward-0.0.2/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: opsward
+Version: 0.0.2
+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.
+
+## Install
+
+```bash
+pip install opsward
+```
+
+## Quick Start
+
+### Diagnose
+
+Score your project's AI setup health:
+
+```bash
+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):
+
+```bash
+opsward generate-cmd .
+opsward generate-cmd . --write   # actually create files
+```
+
+Generates CLAUDE.md, docs (architecture, conventions, known_issues, etc.),
+skills (diagnose-setup, maintain-docs), and agents (setup-auditor) —
+only what's missing, never overwrites existing files.
+
+### Maintain
+
+Find stale references and drift:
+
+```bash
+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:
+
+```bash
+opsward diagnose-cmd . --format json
+opsward generate-cmd . --format json
+opsward maintain-cmd . --format json
+```
+
+## Python API
+
+```python
+from opsward import scan, diagnose, generate, 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]
+```