agentlane 0.5.0__tar.gz

agentlane-0.5.0/.agents/skills/code-change-verification/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: code-change-verification
+description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents Python repository.
+---
+
+# Code Change Verification
+
+## Overview
+
+Ensure work is only marked complete after formatting, linting, type checking, and tests pass. Use this skill when changes affect runtime code, tests, or build/test configuration. You can skip it for docs-only or repository metadata unless a user asks for the full stack.
+
+## Quick start
+
+1. macOS/Linux: `bash .agents/skills/code-change-verification/scripts/run.sh`.
+2. If any command fails, fix the issue, rerun the script, and report the failing output.
+3. Confirm completion only when all commands succeed with no remaining issues.
+
+## Manual workflow
+
+- If dependencies are not installed or have changed, run `make sync` first to install dev requirements via `uv`.
+- Run from the repository root in this order: `make format`, `make lint`, `make typecheck`, `make tests`.
+- Do not skip steps; stop and fix issues immediately when a command fails.
+- Re-run the full stack after applying fixes so the commands execute in the required order.
+
+## Resources
+
+### scripts/run.sh
+
+- Executes the full verification sequence with fail-fast semantics from the repository root. Prefer this entry point to ensure the required commands run in the correct order.

agentlane-0.5.0/.agents/skills/code-change-verification/scripts/run.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Fail fast on any error or undefined variable.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if command -v git >/dev/null 2>&1; then
+  REPO_ROOT="$(git -C "${SCRIPT_DIR}" rev-parse --show-toplevel 2>/dev/null || true)"
+fi
+REPO_ROOT="${REPO_ROOT:-$(cd "${SCRIPT_DIR}/../../../.." && pwd)}"
+
+cd "${REPO_ROOT}"
+
+echo "Running make format..."
+make format
+
+echo "Running make lint..."
+make lint
+
+echo "Running make typecheck..."
+make typecheck
+
+echo "Running make tests..."
+make tests
+
+echo "code-change-verification: all commands passed."

agentlane-0.5.0/.agents/skills/docs-sync/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: docs-sync
+description: Review the current AgentLane code and public docs under docs/ to find missing, outdated, or misplaced documentation, then propose or apply concise documentation updates that match the repository’s structure and writing style. Ignore internal planning docs under docs/plans/.
+---
+
+# Docs Sync
+
+Use this skill when the user wants to audit documentation coverage, keep
+`docs/` aligned with implementation changes, or update public technical docs.
+
+## Scope
+
+This skill is for public documentation under `docs/**`.
+
+Rules:
+
+1. Treat `docs/plans/**` as internal tracking, not public documentation.
+2. English only.
+3. Keep edits concise and easy to maintain.
+
+## Workflow
+
+### 1. Define the scope to review
+
+Pick one of these modes:
+
+1. full public-doc audit against the current branch
+2. doc sync for a specific feature or directory
+3. diff-based audit against `main` for in-flight changes
+
+Prefer diff-based review when there is active branch work. Prefer a full audit
+ when the user asks for broad documentation cleanup.
+
+### 2. Build a feature inventory from code
+
+Review the selected scope in code first.
+
+Focus on user-facing behavior:
+
+1. public exports
+2. runtime behaviors and guarantees
+3. configuration options and defaults
+4. examples that define supported usage
+5. important developer workflows
+6. renamed, removed, or newly added features
+
+Capture lightweight evidence:
+
+1. file path
+2. symbol or setting name
+3. short note about the behavior that should be documented
+
+### 3. Review the existing docs hierarchy
+
+Use the current docs tree as the source of structure.
+
+Start with:
+
+1. `docs/README.md`
+2. the relevant page under `docs/runtime/`, `docs/messaging/`, `docs/harness/`,
+   or `docs/transport/`
+
+When reviewing, prefer updating an existing page over creating a new one unless
+the topic clearly has no home.
+
+If you add, remove, or rename a public docs page, update `docs/README.md`.
+
+### 4. Compare docs against code
+
+Look for:
+
+1. missing public behavior
+2. outdated names, defaults, or semantics
+3. examples in docs that no longer match implementation
+4. information that belongs on a different page for discoverability
+5. public docs that accidentally expose internal rollout or planning details
+
+### 5. Produce a Docs Sync Report
+
+Before editing, produce a short report with:
+
+1. doc gaps
+2. inaccurate or outdated content
+3. structural suggestions, if any
+4. proposed file-level edits
+
+Keep the report concise.
+
+### 6. Apply updates if asked
+
+When applying edits:
+
+1. edit only the relevant public docs under `docs/**`
+2. keep the current writing style and section structure
+3. keep examples short and directly tied to the repo
+4. prefer current-state documentation over rollout history
+5. do not add jokes, slang, rhetoric, puns, or contrastive-negation phrasing
+
+## Writing Style
+
+Match the existing documentation style in this repository.
+
+Rules:
+
+1. write in plain technical English
+2. prefer short sections and short paragraphs
+3. use direct statements over persuasive or dramatic framing
+4. explain the current behavior, boundaries, and intended usage
+5. keep examples minimal and realistic
+6. avoid figures of speech, jokes, slang, and rhetorical phrasing
+7. avoid contrastive negation patterns such as “not X, but Y”
+8. keep tone neutral and open-source appropriate
+
+## Public Docs Boundary
+
+For this repository, public docs currently live under `docs/**`.
+
+Internal tracking docs live under `docs/plans/**` and should not be treated as
+the public documentation surface.
+
+## Output format
+
+Use this report shape when auditing before edits:
+
+Docs Sync Report
+
+- Scope
+  - What was reviewed
+- Missing or weak coverage
+  - Doc file or missing page -> evidence -> proposed change
+- Incorrect or outdated content
+  - Doc file -> issue -> correct behavior -> evidence
+- Structural suggestions
+  - Proposed move/add/remove -> rationale
+- Proposed edits
+  - File -> short summary
+
+## References
+
+- `references/doc-coverage-checklist.md`

agentlane-0.5.0/.agents/skills/docs-sync/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Docs Sync"
+  short_description: "Audit public docs coverage and propose concise updates"
+  default_prompt: "Use $docs-sync to review AgentLane public docs under docs/ against the current implementation, then propose concise documentation updates."

agentlane-0.5.0/.agents/skills/docs-sync/references/doc-coverage-checklist.md

@@ -0,0 +1,48 @@
+# Doc Coverage Checklist
+
+Use this checklist when reviewing AgentLane public documentation.
+
+## Review targets
+
+- Public docs under `docs/**`
+- Public docs index in `docs/README.md`
+- Current implementation under `src/`
+- Public examples when they define supported usage
+
+Do not treat `docs/plans/**` as public documentation.
+
+## Code-first pass
+
+- Identify public exports, runtime behaviors, configuration, and examples.
+- Note renamed, removed, or newly added features.
+- Record short evidence only: file path plus symbol or setting.
+
+## Doc-first pass
+
+- Review the relevant page in `docs/`.
+- Check whether the page reflects the current behavior and naming.
+- Prefer updating existing pages over creating new ones.
+- Update `docs/README.md` if public docs pages are added, removed, or renamed.
+
+## Common gaps
+
+- Missing public behavior after a new feature lands
+- Old names or defaults that no longer match code
+- Examples that no longer match the actual API
+- Public docs that still contain rollout notes, phases, dates, or status markers
+- Information placed on the wrong page for discoverability
+
+## Writing guardrails
+
+- Keep docs concise.
+- Use plain technical English.
+- Avoid slang, jokes, rhetoric, figures of speech, and puns.
+- Avoid contrastive negation phrasing.
+- Describe current behavior rather than implementation history.
+
+## Patch guidance
+
+- Keep edits narrow and local to the affected pages.
+- Preserve the current section style and hierarchy.
+- Prefer short examples over long explanatory blocks.
+- Keep internal planning notes in `docs/plans/**`, not in public docs.

agentlane-0.5.0/.agents/skills/release/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: release
+description: Prepare an AgentLane release with lockstep versioning across the root package and workspace packages, release notes based on changes since the last remote tag, full verification, and local-only git tag creation.
+---
+
+# Release
+
+Use this skill when the user wants to cut a release, bump versions, draft
+release notes, or create a git tag for PyPI or GitHub release preparation.
+
+## Quick start
+
+1. Run `bash .agents/skills/release/scripts/run.sh`.
+2. The release must halt unless the current branch is `main`.
+3. The release must halt if `git status --short` is not empty.
+4. If the current versions are not in lockstep yet, update:
+   - `pyproject.toml`
+   - every discovered `packages/*/pyproject.toml`
+5. Keep all package versions identical for a release.
+6. Do not add compatibility bounds between workspace packages as part of this
+   release workflow.
+7. Write release notes to `docs/releases/v<version>.md` using the short
+   template in `references/release_notes_template.md`.
+8. Run `/usr/bin/make format`, `/usr/bin/make lint`, and `/usr/bin/make tests`.
+9. Create a local annotated tag with `git tag -a v<version> -F docs/releases/v<version>.md`.
+10. Do not push the tag. Leave tag pushing to the user after review.
+
+## Versioning policy
+
+This repository uses lockstep versioning.
+
+Rules:
+
+1. The root package and all workspace packages share the same release version.
+2. While the project is still pre-`1.0`, treat `0.MINOR.0` as the release line
+   for meaningful public changes.
+3. Use `PATCH` only for safe fixes, docs, and internal improvements that do not
+   intentionally break documented public APIs.
+4. Use a `MINOR` bump for new public capabilities or any public behavior change
+   users should adapt to.
+
+## Release workflow
+
+### 1. Confirm repository state
+
+Before editing anything:
+
+1. ensure the current branch is exactly `main`
+2. ensure `git status --short` is empty
+3. halt immediately if either check fails
+4. do not discard unrelated changes just to force a release through
+
+### 2. Review release context from the remote
+
+Always base the release review on the latest remote tag, not just local tags.
+
+Run:
+
+```bash
+bash .agents/skills/release/scripts/run.sh
+```
+
+This helper:
+
+1. verifies the current branch is `main`
+2. verifies the worktree is clean
+3. fetches tags from `origin`
+4. reads the current versions from the root and workspace packages
+5. checks whether the repo is already in lockstep
+6. finds the latest remote semver tag
+7. prints the review range and the git commands to inspect commits and files
+
+If there are no remote tags yet, treat the release as the initial release and
+review the full history.
+
+### 3. Bump versions in lockstep
+
+Update:
+
+1. `pyproject.toml`
+2. every discovered `packages/*/pyproject.toml`
+
+All version values should match exactly.
+
+Do not add or change inter-package compatibility bounds as part of this
+workflow.
+
+### 4. Write release notes
+
+Create `docs/releases/v<version>.md`.
+
+Base the notes on:
+
+1. `git log --reverse --no-merges --oneline <range>`
+2. `git diff --name-only <range>` or `git log --name-only --pretty=format: --diff-filter=AM HEAD` for an initial release
+3. user-facing API and behavior changes
+4. examples and documentation added or updated
+
+Keep the notes short. Prefer one or two sentences of summary plus a few bullets
+for the most notable user-facing changes. Do not turn release notes into a full
+project history dump.
+
+Use `references/release_notes_template.md` as the starting point.
+
+Format rules:
+
+1. summarize the release in one or two sentences
+2. keep only the most notable changes and fixes
+3. group them into short sections such as `Added`, `Changed`, and `Fixed`
+4. attach commit links or short commit references for each bullet
+5. omit low-signal internal churn unless it materially affects users
+6. do not hard-wrap or reflow the release notes to fit an 80-column line limit
+7. keep each summary paragraph on one physical line
+8. keep each bullet on one physical line
+
+The template shape is intentionally short, closer to:
+
+```markdown
+# v<version>
+
+## Summary
+
+One or two concise sentences.
+
+## Added
+
+- Short user-facing addition (`abc1234`)
+
+## Changed
+
+- Short user-facing change (`def5678`)
+
+## Fixed
+
+- Short user-facing fix (`fedcba9`)
+```
+
+For an initial release, make that explicit in the summary.
+
+The helper intentionally stops at guardrails plus release context. Do the
+commit review and release-note writing directly in the release task instead of
+trying to encode the whole release process in a script.
+
+### 5. Verify
+
+Run from the repository root:
+
+```bash
+/usr/bin/make format
+/usr/bin/make lint
+/usr/bin/make tests
+```
+
+Do not create a release tag until all three pass.
+
+### 6. Create the tag locally only
+
+Create the tag:
+
+```bash
+git tag -a v<version> -F docs/releases/v<version>.md
+```
+
+Rules:
+
+1. create the tag locally only
+2. do not push the tag
+3. use the release notes file as the annotated tag body
+4. report the tag name and release notes path back to the user
+
+## Expected output
+
+A release-ready result should include:
+
+1. the chosen version
+2. confirmation that the release was cut from `main`
+3. confirmation that the worktree was clean before the release started
+4. confirmation that all package versions match
+5. the release notes file path
+6. the verification results
+7. the local tag name
+8. an explicit note that the tag was not pushed

agentlane-0.5.0/.agents/skills/release/references/release_notes_template.md

@@ -0,0 +1,27 @@
+# v<version>
+
+## Summary
+
+One or two short sentences describing what changed in this release and why it matters to users.
+
+## Added
+
+- Short user-facing addition ([`abc1234`](https://github.com/<owner>/<repo>/commit/abc1234))
+
+## Changed
+
+- Short user-facing change ([`def5678`](https://github.com/<owner>/<repo>/commit/def5678))
+
+## Fixed
+
+- Short user-facing fix ([`fedcba9`](https://github.com/<owner>/<repo>/commit/fedcba9))
+
+## Notes
+
+- Keep this file concise.
+- Include only notable user-facing changes.
+- Prefer commit links over issue taxonomy unless an issue number adds real value.
+- For an initial release, say so in the summary.
+- Do not hard-wrap or reflow lines to fit an 80-column limit.
+- Keep each summary paragraph on one physical line.
+- Keep each bullet on one physical line.

agentlane-0.5.0/.agents/skills/release/scripts/release_context.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Print minimal release context and enforce release guardrails."""
+
+import argparse
+import subprocess
+import tomllib
+from pathlib import Path
+
+
+def run_git(
+    repo_root: Path,
+    *args: str,
+    check: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    """Run one git command from the repository root."""
+    return subprocess.run(
+        ["git", *args],
+        cwd=repo_root,
+        check=check,
+        capture_output=True,
+        text=True,
+    )
+
+
+def repo_root() -> Path:
+    """Resolve the current repository root."""
+    result = run_git(Path.cwd(), "rev-parse", "--show-toplevel")
+    return Path(result.stdout.strip())
+
+
+def ensure_main_branch(repo_root_path: Path) -> str:
+    """Ensure the release is being prepared from the main branch."""
+    result = run_git(repo_root_path, "branch", "--show-current")
+    branch = result.stdout.strip()
+    if branch != "main":
+        raise RuntimeError(
+            "Release preparation must run from the main branch. "
+            f"Current branch: {branch or '<detached>'}."
+        )
+    return branch
+
+
+def ensure_clean_worktree(repo_root_path: Path) -> None:
+    """Ensure the working tree is clean before release preparation starts."""
+    result = run_git(repo_root_path, "status", "--short")
+    lines = [line for line in result.stdout.splitlines() if line.strip()]
+    if not lines:
+        return
+
+    joined = "\n".join(lines)
+    raise RuntimeError(
+        "Release preparation requires a clean working tree. "
+        "Commit or stash changes first.\n"
+        f"{joined}"
+    )
+
+
+def discover_version_file_paths(repo_root_path: Path) -> list[Path]:
+    """Return the root package file plus all workspace package files."""
+    paths: list[Path] = [Path("pyproject.toml")]
+    packages_root = repo_root_path / "packages"
+    if not packages_root.is_dir():
+        return paths
+
+    for package_file in sorted(packages_root.glob("*/pyproject.toml")):
+        paths.append(package_file.relative_to(repo_root_path))
+    return paths
+
+
+def read_versions(repo_root_path: Path) -> dict[str, str]:
+    """Read package versions from the root and workspace package files."""
+    versions: dict[str, str] = {}
+    for relative_path in discover_version_file_paths(repo_root_path):
+        absolute_path = repo_root_path / relative_path
+        with absolute_path.open("rb") as handle:
+            data = tomllib.load(handle)
+        project = data.get("project", {})
+        version = project.get("version")
+        if not isinstance(version, str):
+            raise RuntimeError(f"Missing string version in {relative_path}.")
+        versions[str(relative_path)] = version
+    return versions
+
+
+def latest_semver_tag(repo_root_path: Path) -> str | None:
+    """Return the latest fetched semver tag, if one exists."""
+    result = run_git(repo_root_path, "tag", "--sort=-v:refname")
+    for line in result.stdout.splitlines():
+        candidate = line.strip()
+        if candidate.startswith("v"):
+            return candidate
+    return None
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Check release guardrails and print release context."
+    )
+    parser.add_argument(
+        "--remote",
+        default="origin",
+        help="Git remote used for tags. Defaults to origin.",
+    )
+    return parser.parse_args()
+
+
+def print_release_context(
+    *,
+    repo_root_path: Path,
+    remote: str,
+    branch: str,
+    versions: dict[str, str],
+    last_tag: str | None,
+) -> None:
+    """Print the small release context that is useful to the skill."""
+    print("Release context")
+    print(f"Repository: {repo_root_path}")
+    print(f"Remote: {remote}")
+    print(f"Branch: {branch}")
+    print("Worktree: clean")
+    print()
+
+    print("Version files:")
+    for path, version in versions.items():
+        print(f"- {path}: {version}")
+    lockstep = len(set(versions.values())) == 1
+    print(f"Lockstep: {'yes' if lockstep else 'no'}")
+    print()
+
+    if last_tag is None:
+        review_range = "HEAD"
+        print("Last remote tag: none")
+        print("Review range: initial release (full history)")
+    else:
+        review_range = f"{last_tag}..HEAD"
+        print(f"Last remote tag: {last_tag}")
+        print(f"Review range: {review_range}")
+    print()
+
+    print("Suggested review commands:")
+    if last_tag is None:
+        print("- git log --reverse --no-merges --oneline HEAD")
+        print("- git log --name-only --pretty=format: --diff-filter=AM HEAD")
+    else:
+        print(f"- git log --reverse --no-merges --oneline {review_range}")
+        print(f"- git diff --name-only {review_range}")
+
+
+def main() -> int:
+    """Run the release helper."""
+    args = parse_args()
+    repo_root_path = repo_root()
+    branch = ensure_main_branch(repo_root_path)
+    ensure_clean_worktree(repo_root_path)
+    run_git(repo_root_path, "fetch", "--tags", args.remote)
+
+    versions = read_versions(repo_root_path)
+    last_tag = latest_semver_tag(repo_root_path)
+    print_release_context(
+        repo_root_path=repo_root_path,
+        remote=args.remote,
+        branch=branch,
+        versions=versions,
+        last_tag=last_tag,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentlane-0.5.0/.agents/skills/release/scripts/run.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(git -C "${SCRIPT_DIR}" rev-parse --show-toplevel 2>/dev/null || true)"
+REPO_ROOT="${REPO_ROOT:-$(cd "${SCRIPT_DIR}/../../../.." && pwd)}"
+
+cd "${REPO_ROOT}"
+uv run python .agents/skills/release/scripts/release_context.py "$@"