steer-ai 0.1.0__tar.gz

steer_ai-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.DS_Store
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/

steer_ai-0.1.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to steer are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[SemVer](https://semver.org/) (pre-1.0: minor bumps may break).
+
+## 0.1.0: initial public release
+
+Published on PyPI as `steer-ai` (the name `steer` was already taken);
+the command and the import are `steer` either way.
+
+### Highlights beyond the components
+
+- `steer new` takes component inputs at scaffold time: `--secrets
+  KEY[,KEY...]` wires named credentials into the generated instructions,
+  `--steps id[,id...]` generates a linear chain of named flow steps, and
+  `--user-invoked` scaffolds a human-triggered skill
+  (`disable-model-invocation: true`) with validation adapting its trigger
+  checks.
+- `flow.toml` strings expand `{skill_dir}` and `{workspace}`, so printed
+  directives run verbatim from the workspace even when the skill is
+  installed under `.claude/skills/`.
+- `steer validate` prunes as well as checks: `DUPLICATE_TEXT` (the same
+  paragraph in two places) and `REFERENCE_ORPHAN` (reference files nothing
+  points to).
+- Two complete example skills in `examples/`, scaffolded by steer and
+  verified end-to-end by an agent in a sandbox.
+
+Steer is the framework for building [Agent Skills](https://agentskills.io):
+authoring tools around the whole lifecycle, plus the runtime components the
+SKILL.md format deliberately leaves out. Zero dependencies: Python stdlib
+only, Python ≥ 3.11.
+
+### Author-time CLI
+
+- `steer new`: scaffold a spec-valid skill; `--with
+  secrets,store,context,flow,proc,learn` wires components into the generated
+  SKILL.md, `--scripts` adds an example script with the result envelope,
+  `--auto-learn` wires a Claude Code Stop hook for automatic lesson capture.
+- `steer validate`: the open spec's hard rules (name/description/XML/size),
+  progressive-disclosure budgets, broken references, portability warnings for
+  Claude-Code-only frontmatter, thin-trigger descriptions, and secret hygiene.
+- `steer package`: validated, API-ready zip; refuses credential-looking
+  files.
+- `steer install` / `steer list`: copy into / enumerate `.claude/skills`
+  and `.agents/skills`, project and user scope.
+
+### Runtime components (CLI and Python library)
+
+- `steer secrets`: per-skill credentials, resolved env var → OS keychain (macOS
+  `security` / Linux `secret-tool`) → `0600` file under `~/.steer/`. Never
+  inside the skill directory.
+- `steer store`: per-skill SQLite with KV + JSON-document tables + raw SQL,
+  user or workspace scope.
+- `steer context`: one-shot situational snapshot, covering platform, host
+  agent, git state, project type, tools on PATH.
+- `steer flow`: declarative steps in `flow.toml` with verify conditions
+  (`file_exists`, `dir_exists`, `glob`, `command`, `env`); mandate steps
+  gated on prerequisites.
+- `steer proc`: managed background processes with port/log-pattern readiness,
+  PID bookkeeping, TERM→KILL stop of the whole process group.
+- `steer learn`: capture → curate → promote loop so skills improve from
+  their own runs; deterministic curation, human-gated promotion,
+  `steer learn reflect` transcript scanning for auto-capture.
+- `steer.output`: one JSON result envelope for every script.

steer_ai-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to steer
+
+Thanks for helping build the framework for Agent Skills.
+
+## Ground rules
+
+- **Zero runtime dependencies.** Steer is Python stdlib only (`sqlite3`,
+  `tomllib`, `zipfile`, …). PRs that add a runtime dependency will be asked
+  to find a stdlib way. Dev/CI tooling (pytest, ruff) is fine; it never
+  ships.
+- **Python ≥ 3.11**, macOS and Linux are the supported platforms today.
+- **Agent-first UX.** Error messages tell the agent the exact next command
+  to run. Every command that prints for humans also takes `--json`.
+- **Spec first.** Scaffolds and validation target the
+  [open Agent Skills spec](https://agentskills.io/specification);
+  client-specific extensions (e.g. Claude Code hooks) are opt-in and flagged
+  by `steer validate` as portability warnings.
+
+## Dev setup
+
+```bash
+git clone https://github.com/bh-rat/steer && cd steer
+uv venv && uv pip install -e . pytest
+.venv/bin/python -m pytest tests/ -q
+```
+
+(Plain `python3 -m venv .venv && .venv/bin/pip install -e . pytest` works
+too; there is nothing uv-specific here.)
+
+## Before you open a PR
+
+1. `python -m pytest tests/ -q`: all green, and new behavior has tests.
+   Tests are stdlib `unittest`-style via pytest, hermetic (temp dirs, no
+   network, no real `~/.steer`).
+2. `uvx ruff check steer tests`: clean.
+3. If you touched the CLI surface or on-disk formats, update the docs
+   (`docs/`) and `CHANGELOG.md` in the same PR.
+
+## Good first contributions
+
+- New `steer context` detectors (project types, host agents); see
+  `steer/context.py`.
+- New `steer flow` verify conditions; see `steer/flow.py`.
+- Validation checks with real-world evidence (link to the skill that
+  motivated them).
+
+For anything bigger, open an issue first so we can agree on the shape.

steer_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bharat Geleda
+
+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.

steer_ai-0.1.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: steer-ai
+Version: 0.1.0
+Summary: The framework for building Agent Skills: scaffolding, validation, packaging, and runtime components (secrets, storage, context, flows, processes, learning) for SKILL.md
+Project-URL: Homepage, https://github.com/bh-rat/steer
+Project-URL: Documentation, https://github.com/bh-rat/steer#readme
+Project-URL: Changelog, https://github.com/bh-rat/steer/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/bh-rat/steer/issues
+Author-email: Bharat Geleda <bharatgeleda@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: SKILL.md,agent-skills,agents,claude,llm,skills
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# steer
+
+**The framework for building Agent Skills.**
+
+[![CI](https://github.com/bh-rat/steer/actions/workflows/ci.yml/badge.svg)](https://github.com/bh-rat/steer/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python ≥ 3.11](https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB)
+![Zero dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen)
+
+[Agent Skills](https://agentskills.io) (a `SKILL.md` plus scripts) are the
+open standard for packaging agent capabilities, supported by Claude Code,
+Codex, Copilot, Cursor, Gemini CLI, and ~40 other clients. The format is
+deliberately tiny, which means it ships no batteries: the spec says nothing
+about credentials, persistence, context gathering, step enforcement, or
+managed processes. Every serious skill hand-rolls some of these.
+
+Steer provides them as components, plus the authoring tools to scaffold,
+validate, package, and install skills. Zero dependencies; Python stdlib only.
+
+```
+┌─ author-time ──────────────────────┐  ┌─ runtime (CLI or library) ─────────┐
+│ steer new        scaffold a skill  │  │ steer secrets   credentials        │
+│ steer validate   spec + hygiene    │  │ steer store     per-skill SQLite   │
+│ steer package    API-ready zip     │  │ steer context   situational recon  │
+│ steer install    into skill dirs   │  │ steer flow      enforced steps     │
+│ steer list       what's installed  │  │ steer proc      managed processes  │
+└────────────────────────────────────┘  │ steer learn     skills that learn  │
+                                        └────────────────────────────────────┘
+```
+
+## Why
+
+Steer's components are reverse-engineered from what good skills already
+hand-roll in prose and fragile bash (enforced steps, situational recon,
+persistent state, credentials, process lifecycles), turned into machinery
+you get with one flag.
+
+## Install
+
+```bash
+uv tool install steer-ai        # installs the `steer` command
+# or: pip install steer-ai
+# latest from main: uv tool install git+https://github.com/bh-rat/steer
+steer --version
+```
+
+Requires Python ≥ 3.11. No runtime dependencies.
+
+## Quickstart
+
+```bash
+steer new stripe-report \
+  --description "Generates revenue reports from Stripe. Use when the user asks for revenue, MRR, or payment reporting." \
+  --with secrets,context,flow,learn --scripts
+```
+
+This scaffolds a spec-valid skill:
+
+```
+stripe-report/
+├── SKILL.md       # frontmatter + body with the components wired in
+├── flow.toml      # declarative steps with verify conditions
+└── scripts/
+    └── example.py # non-interactive, JSON result envelope on stdout
+```
+
+The generated `SKILL.md` already tells the agent how to behave:
+
+> 1. **Ground yourself.** Run `steer context` and read the snapshot.
+> 2. **Apply past lessons.** Run `steer learn show`; those lessons came
+>    from real previous runs.
+> 3. **Check credentials.** Run `steer secrets check STRIPE_REPORT_API_KEY
+>    --skill stripe-report`. If missing, ask the user to run
+>    `steer secrets set ...` (never ask them to paste the value into the
+>    chat).
+> 4. **Follow the flow.** `steer flow status` → do the step → steps verify
+>    themselves against reality; you cannot skip ahead.
+
+For a skill only the human should trigger, `steer new --user-invoked`
+sets `disable-model-invocation: true` and validation adapts.
+
+Then:
+
+```bash
+steer validate stripe-report     # spec rules, broken refs, secret hygiene
+steer install stripe-report      # → .claude/skills/ (project scope)
+steer package stripe-report      # → validated zip for the Claude API / claude.ai
+```
+
+## Examples
+
+Two complete skills built this way live in [`examples/`](examples/):
+[`repo-health`](examples/repo-health) exercises all six components in
+one skill (enforced flow, trend memory, credential handoff, managed
+preview server, lesson capture), and
+[`commit-message`](examples/commit-message) is the minimal user-invoked
+counterpoint. Their READMEs show exactly which lines steer generated and
+which the author filled in.
+
+## The components
+
+### `steer secrets`: credentials that never live in the skill
+
+Skill directories get zipped and uploaded; credentials must live outside
+them. Resolution order: env var → OS keychain (macOS `security` /
+Linux `secret-tool`) → `0600` file under `~/.steer/`.
+
+```bash
+steer secrets check STRIPE_API_KEY --skill stripe-report   # agent checks
+steer secrets set STRIPE_API_KEY --skill stripe-report     # human sets (hidden prompt)
+```
+
+```python
+from steer import Secrets
+key = Secrets("stripe-report").require("STRIPE_API_KEY",
+                                       hint="dashboard.stripe.com/apikeys")
+# missing -> MissingSecretError whose message tells the agent
+# exactly what command to ask the human to run
+```
+
+### `steer store`: per-skill SQLite
+
+```bash
+steer store put last_run '"2026-06-11"' --skill stripe-report
+steer store insert runs '{"month": "may", "total": 1200}' --skill stripe-report
+steer store find runs --where month=may --skill stripe-report
+```
+
+KV + JSON-document tables + raw SQL. Two scopes: `user`
+(`~/.steer/skills/<name>/store.db`) and `workspace`
+(`<project>/.steer/<name>/store.db`).
+
+### `steer context`: situational recon in one command
+
+```bash
+steer context                # markdown for the agent to read
+steer context --json --only git,project,tools
+```
+
+One command reports the platform, host agent (Claude Code, Codex, Cursor,
+and others), git state, project type (from lockfiles and manifests), tools
+on PATH, and a small allowlist of env flags. It never dumps the environment.
+
+### `steer flow`: steps the agent cannot skip
+
+Define the process in `flow.toml`; steps with a `verify` condition complete
+only when reality matches, mandate steps are marked explicitly, and marking
+is gated on prerequisites:
+
+```toml
+[[steps]]
+id = "configure"
+directive = "Create out/config.json with the data sources"
+[steps.verify]
+file_exists = "out/config.json"
+
+[[steps]]
+id = "review"
+directive = "Read the config and confirm the mappings look right"
+requires = ["configure"]
+```
+
+```bash
+steer flow status        # progress bar + current directive
+steer flow next          # what to do now
+steer flow done review   # mark a mandate step (refused if prereqs incomplete)
+```
+
+Verify conditions: `file_exists`, `dir_exists`, `glob`, `command` (exit 0),
+`env`. Python API: `steer.Flow` / `steer.Step` for full programmatic control.
+
+### `steer proc`: background processes that don't zombie
+
+```bash
+steer proc start web --ready-port 5173 -- npm run dev
+steer proc status web
+steer proc logs web
+steer proc stop web      # TERM → wait → KILL, whole process group
+```
+
+It checks readiness by port or log pattern, keeps PID bookkeeping under
+`<workspace>/.steer/proc/`, guards against recycled PIDs, and captures logs.
+
+### `steer learn`: skills that improve from their own runs
+
+Tooling exists to improve a skill before it ships, and agents carry runtime
+memory; nothing connects the two, so a skill learns nothing from its own
+runs. `steer learn` is that connection, a capture → curate → promote loop:
+the agent records lessons the moment they happen, reads a bounded digest at
+the start of every run, and the author promotes the keepers into the shipped
+skill.
+
+```bash
+steer learn note "Use the EU endpoint for EU accounts" --kind correction
+steer learn show          # ranked digest the SKILL.md tells the agent to read
+steer learn confirm 3     # helped → stronger;  dispute → weaker, auto-archives
+steer learn promote 3     # human-gated: append to the skill's learnings.md
+steer learn run ok && steer learn stats
+```
+
+Curation is deterministic (no LLM inside the framework; the agent is the
+reflector): duplicates confirm instead of duplicating, disputed-more-than-
+confirmed auto-archives, a hard cap evicts the weakest, credential-shaped
+notes are refused.
+
+The structure is fixed and inspectable: `~/.steer/skills/<name>/lessons.db`
+(source of truth) plus an auto-maintained readable `LEARNINGS.md` mirror,
+both outside the skill dir, so lessons survive reinstalls and never ship by
+accident. Promoted lessons land in the skill's `learnings.md`, which does
+ship.
+
+**Auto-learning:** `steer new my-skill --auto-learn` wires a Claude Code
+skill-scoped Stop hook running `steer learn reflect`. When the agent tries
+to finish, it deterministically scans the session transcript for corrections
+and failed tool calls, and (once) blocks the stop with exact capture
+instructions. Capture no longer depends on the agent remembering to do it.
+
+### Result envelope: one output shape for every script
+
+```python
+from steer.output import print_envelope
+print_envelope("ok", "Report generated",
+               data={"rows": 120}, artifacts=["out/report.pdf"])
+```
+
+```json
+{
+  "status": "ok",
+  "summary": "Report generated",
+  "data": {"rows": 120},
+  "artifacts": ["out/report.pdf"]
+}
+```
+
+## Validation
+
+`steer validate` checks the open spec's hard rules (name format/length and
+directory match, description 1-1024 chars, no XML), progressive-disclosure
+budgets (<500-line body), broken file references, portability (Claude-Code-
+only frontmatter), thin trigger descriptions, duplicated paragraphs across
+SKILL.md and references (keep one source of truth), orphaned `references/`
+files nothing points to, and secret hygiene: credential-looking files
+inside a skill are warnings normally and hard errors at packaging time.
+`steer package` refuses to ship them.
+
+## Library use
+
+Everything the CLI does is importable (`from steer import Skill, Flow,
+Secrets, Store, validate_skill, discover`) for building your own skill
+tooling on top.
+
+## What steer is not
+
+Not a registry or installer ecosystem (use `npx skills`, Tessl, or plugin
+marketplaces; steer sits upstream of them), not an eval harness (yet), and
+not useful at runtime for pure-knowledge skills (a style guide needs no
+database, though steer still helps author and validate it).
+
+## Roadmap
+
+Skill-to-skill dependencies / shared libraries, `steer test`
+(trigger-regression + cross-runtime checks), signing/provenance, TypeScript
+SDK, PyPI release.
+
+## Docs & contributing
+
+Full documentation lives in [`docs/`](docs/) (introduction, quickstart, a
+page per component, and the authoring guide, including the checklist for
+writing skill bodies: trigger, structure, steering, pruning). Contributions
+are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Security reports go to
+[SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)