Steward 0.18.0

Steward

A configurable repository stewardship CLI for humans and AI agents. Steward validates documentation structure, enforces governance policies, and keeps repository artifacts in sync — all driven by declarative YAML configuration.

Release candidate: v0.18.0 (pending publication, pre-1.0.0). Latest published release: v0.17.0. See Current Status.

Quick Start

# Build and install (requires .NET 10 SDK)
git clone https://github.com/jonv11/steward.git
cd steward
dotnet build steward.sln -c Release
dotnet pack src/Steward.Cli -c Release --no-build
dotnet tool install --tool-path ./.tools/steward --add-source ./src/Steward.Cli/bin/Release Steward
export PATH="$PWD/.tools/steward:$PATH"    # or add to .bashrc / PowerShell profile

# Use on any repository
cd /path/to/your-repo
steward orient                       # see what the repo contains
steward init --profile software      # set up governance (maintainers)
steward check                        # validate against policy

orient, outline, and check work on any repository immediately — no .steward/ config needed for basic structural analysis. A configured .steward/ directory unlocks policy-driven validation, frontmatter enforcement, and artifact maintenance.

Who Is Steward For?

Maintainers configure Steward for a repository: define required artifacts, naming conventions, frontmatter standards, and auto-generated indexes. See the Maintainer Guide.

Contributors validate their changes against the configured rules before committing. See the Contributor Guide.

AI agents use Steward's structured diagnostics and JSON output for automated validation loops. See Agent Integration.

Features

• Repository orientation — auto-classify and outline repository structure
• Policy-driven validation — enforce required artifacts, frontmatter fields, section sizes, naming conventions, and path policies via 21 rules
• Artifact families — group recurring document types (ADRs, RFCs, etc.) with convention-based discovery and type-aware validation
• Markdown structural editing — query, edit, and manage Markdown documents with section and frontmatter operations
• Deterministic maintenance — auto-generate structure documents, indexes, and managed sections
• Broken link detection — find internal Markdown links that don't resolve
• Rule explainability — every validation rule is explainable with remediation guidance
• Multi-format output — text and JSON across the command surface, plus SARIF 2.1.0 from steward check
• Auto-fix — 4 rules (STWD-003, STWD-007, STWD-012, STWD-018) support deterministic auto-fix via steward check --fix --apply

Installation

Steward requires the .NET 10 SDK (10.0 or later). Run dotnet --version to verify. Earlier SDK versions will not work.

Build and install locally (recommended)

git clone https://github.com/jonv11/steward.git
cd steward
dotnet build steward.sln -c Release
dotnet pack src/Steward.Cli -c Release --no-build
dotnet tool install --tool-path ./.tools/steward --add-source ./src/Steward.Cli/bin/Release Steward

Add to your PATH:

# Unix / Git Bash
export PATH="$PWD/.tools/steward:$PATH"

# Windows PowerShell
$env:PATH = "$PWD\.tools\steward;$env:PATH"

Install from NuGet

dotnet tool install --global Steward

This installs the latest published release. To test unreleased work, use the source build above. Published packages and self-contained bundles are also available from GitHub Releases.

GitHub Releases

Tagged releases attach .nupkg, self-contained bundles for win-x64/linux-x64/osx-arm64, and a SHA256SUMS.txt checksum file.

The global.json trap

If you run Steward via dotnet run --project from inside another repository, that repository's global.json can select a different SDK and break Steward. Always use a tool-path install or the built executable for cross-repo use.

Exit codes

Commands

Global options

Validation Rules

Use steward explain <rule-id> for detailed guidance on any rule. Severities can be overridden via validation.severity_overrides in policy.yaml. Rules can be suppressed globally or per-path.

Configuration

Steward uses a .steward/ directory with three optional YAML configuration files:

Run steward init --profile <name> to scaffold initial files. Available profiles: software, docs, minimal.

For complete field documentation, valid values, defaults, and configuration examples, see the Configuration Reference.

What Steward Does Not Do

• Not a code linter. Steward validates documentation structure and repository governance, not source code.
• Not a CI system. Steward is a validation command you run in CI — it does not replace CI.
• Not a content generator. Steward generates structure indexes and managed sections. It does not write documentation content.
• Not a hosting platform tool. No GitHub/GitLab API integration. Steward operates on the local filesystem and git state.
• No IDE plugin. CLI-only. No LSP, no editor extension.

Current Status

Steward is prepared as a v0.18.0 release candidate on a pre-1.0.0 release line. The latest published release remains v0.17.0 until the tag-driven release and NuGet publication are verified. 1.0.0 requires explicit authorization per ADR-013.

What works today: All 21 validation rules, all commands listed above, three built-in profiles (software, docs, minimal), artifact family classification, deterministic maintenance, Markdown structural editing, JSON and SARIF output, and scoped validation.

Known limitations: .NET 10 SDK required (not yet widely adopted). search --role matches explicit artifact declarations only, not family-classified files. 4 of 21 rules support auto-fix. mixed and knowledge profiles are not yet scaffolded via init.

Current release state: v0.18.0 metadata and release notes are prepared, but publication is still pending. Stable v1.0.0 remains unauthorized. See project status and the roadmap.

Documentation

Internal project documents (planning, decisions, audits) are under docs/.

Development

See CONTRIBUTING.md for contributor workflow and pull request guidelines.

Prerequisites

• .NET 10 SDK
• Node.js (24.x) — only for Markdown linting, not required by the CLI itself

Build and test

dotnet build steward.sln
dotnet test steward.sln

Markdown lint

npm ci
npm run lint:md

Project structure

• src/Steward.Cli — CLI entry point and commands
• src/Steward.Core — Core library (validation, Markdown, maintenance)
• tests/Steward.Core.Tests — Core library tests
• tests/Steward.Cli.Tests — CLI integration tests
• tests/Steward.TestFixtures — Shared test infrastructure

License

MIT License.