agent-style 0.1.0__tar.gz

agent_style-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: agent-style
+Version: 0.1.0
+Summary: The Elements of Agent Style: a literature-backed English technical-prose writing ruleset for AI agents, with CLI install/enable/disable for 8 primary agent surfaces.
+Author-email: Yue Zhao <fortis@usc.edu>
+License: MIT AND CC-BY-4.0
+Project-URL: Homepage, https://github.com/yzhao062/agent-style
+Project-URL: Repository, https://github.com/yzhao062/agent-style
+Project-URL: Issues, https://github.com/yzhao062/agent-style/issues
+Project-URL: Changelog, https://github.com/yzhao062/agent-style/blob/main/CHANGELOG.md
+Keywords: writing,style,agent,llm,ai,instructions,prompt
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# agent-style (PyPI)
+
+CLI for *The Elements of Agent Style*: a literature-backed English technical-prose writing ruleset for AI agents.
+
+Install:
+
+```bash
+pip install agent-style
+```
+
+Basic use:
+
+```bash
+agent-style list-tools                               # show supported tools
+agent-style enable claude-code                       # wire up Claude Code
+agent-style enable claude-code --dry-run --json      # preview in canonical JSON
+agent-style disable claude-code                      # reverse
+agent-style rules                                    # print bundled RULES.md
+```
+
+The CLI writes to `.agent-style/` in your project and safely adds a marker-wrapped reference to your existing instruction file (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, etc.). Existing content is preserved; writes are idempotent; `--dry-run` previews without changing any file.
+
+Supported tools and install modes in v0.1.0:
+
+| Tool | Install mode |
+| --- | --- |
+| claude-code | import-marker (writes `@.agent-style/claude-code.md` to your CLAUDE.md) |
+| agents-md | append-block (writes a marker block to your AGENTS.md) |
+| copilot | append-block (writes a marker block to `.github/copilot-instructions.md`) |
+| copilot-path | owned-file (writes `.github/instructions/agent-style.instructions.md`) |
+| cursor | owned-file (writes `.cursor/rules/agent-style.mdc`) |
+| anthropic-skill | owned-file (writes `.claude/skills/agent-style/SKILL.md`) |
+| codex | print-only (writes `.agent-style/codex-system-prompt.md`; stdout = prompt) |
+| aider | multi-file-required (writes `.agent-style/aider-conventions.md`; stderr = `.aider.conf.yml` snippet) |
+
+The full rule set lives in the canonical repository at https://github.com/yzhao062/agent-style. This PyPI package bundles `RULES.md`, `NOTICE.md`, the 8 primary adapters, and the `tools.json` registry; running `agent-style rules` prints the bundled `RULES.md` for quick review.
+
+## License
+
+- Code: MIT (`LICENSES/MIT.txt`).
+- Bundled prose (`RULES.md`, `NOTICE.md`, adapters): CC BY 4.0 (`LICENSES/CC-BY-4.0.txt`).
+
+Roadmap (v0.2.0+): `agent-style update` (pull refreshed adapters), `agent-style override <RULE> disable` (per-rule opt-out), `agent-style clean` (single-command uninstall), `.agent-style/config.toml` (project-level config).

agent_style-0.1.0/README.md

@@ -0,0 +1,45 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# agent-style (PyPI)
+
+CLI for *The Elements of Agent Style*: a literature-backed English technical-prose writing ruleset for AI agents.
+
+Install:
+
+```bash
+pip install agent-style
+```
+
+Basic use:
+
+```bash
+agent-style list-tools                               # show supported tools
+agent-style enable claude-code                       # wire up Claude Code
+agent-style enable claude-code --dry-run --json      # preview in canonical JSON
+agent-style disable claude-code                      # reverse
+agent-style rules                                    # print bundled RULES.md
+```
+
+The CLI writes to `.agent-style/` in your project and safely adds a marker-wrapped reference to your existing instruction file (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, etc.). Existing content is preserved; writes are idempotent; `--dry-run` previews without changing any file.
+
+Supported tools and install modes in v0.1.0:
+
+| Tool | Install mode |
+| --- | --- |
+| claude-code | import-marker (writes `@.agent-style/claude-code.md` to your CLAUDE.md) |
+| agents-md | append-block (writes a marker block to your AGENTS.md) |
+| copilot | append-block (writes a marker block to `.github/copilot-instructions.md`) |
+| copilot-path | owned-file (writes `.github/instructions/agent-style.instructions.md`) |
+| cursor | owned-file (writes `.cursor/rules/agent-style.mdc`) |
+| anthropic-skill | owned-file (writes `.claude/skills/agent-style/SKILL.md`) |
+| codex | print-only (writes `.agent-style/codex-system-prompt.md`; stdout = prompt) |
+| aider | multi-file-required (writes `.agent-style/aider-conventions.md`; stderr = `.aider.conf.yml` snippet) |
+
+The full rule set lives in the canonical repository at https://github.com/yzhao062/agent-style. This PyPI package bundles `RULES.md`, `NOTICE.md`, the 8 primary adapters, and the `tools.json` registry; running `agent-style rules` prints the bundled `RULES.md` for quick review.
+
+## License
+
+- Code: MIT (`LICENSES/MIT.txt`).
+- Bundled prose (`RULES.md`, `NOTICE.md`, adapters): CC BY 4.0 (`LICENSES/CC-BY-4.0.txt`).
+
+Roadmap (v0.2.0+): `agent-style update` (pull refreshed adapters), `agent-style override <RULE> disable` (per-rule opt-out), `agent-style clean` (single-command uninstall), `.agent-style/config.toml` (project-level config).

agent_style-0.1.0/agent_style/__init__.py

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: MIT
+"""agent-style: literature-backed English technical-prose writing ruleset for AI agents.
+
+Programmatic entry points:
+
+    from agent_style import __version__, rules, path, list_tools, enable, disable
+
+See `agent-style --help` for the CLI.
+"""
+
+__version__ = "0.1.0"
+
+
+def rules() -> str:
+    """Return the bundled RULES.md content as a string."""
+    from agent_style.registry import Registry
+    return Registry().read_bundled_rules()
+
+
+def path() -> str:
+    """Return the absolute path of the bundled data directory."""
+    from agent_style.registry import Registry
+    return Registry().data_dir
+
+
+def list_tools() -> list:
+    """Return a list of (tool_name, install_mode, target_path) tuples."""
+    from agent_style.registry import Registry
+    r = Registry()
+    return [
+        (name, spec["install_mode"], spec["target_path"])
+        for name, spec in r.tools.items()
+    ]
+
+
+def enable(tool: str, project_root: str = ".", dry_run: bool = False) -> dict:
+    """Enable agent-style for the given tool in the given project root.
+
+    Returns a canonical JSON-shaped dict with fields: tool, install_mode, enabled,
+    manual_step_required, actions.
+    """
+    from agent_style.installer import enable as _enable
+    from agent_style.registry import Registry
+    return _enable(tool, Registry(), project_root=project_root, dry_run=dry_run)
+
+
+def disable(tool: str, project_root: str = ".", dry_run: bool = False) -> dict:
+    """Disable agent-style for the given tool in the given project root."""
+    from agent_style.installer import disable as _disable
+    from agent_style.registry import Registry
+    return _disable(tool, Registry(), project_root=project_root, dry_run=dry_run)

agent_style-0.1.0/agent_style/cli.py

@@ -0,0 +1,173 @@
+# SPDX-License-Identifier: MIT
+"""agent-style CLI entry point.
+
+Subcommands:
+    rules            Print bundled RULES.md to stdout
+    path             Print bundled data directory
+    list-tools       Print supported tools
+    enable <tool>    Install agent-style for a given tool (safe, idempotent)
+    disable <tool>   Remove agent-style from a given tool's instruction file
+
+Global:
+    --version        Print version and exit
+    --help           Print help
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from agent_style import __version__
+from agent_style.installer import enable, disable, canonical_json
+from agent_style.registry import Registry, RegistryError
+
+
+def _print_json_result(result: dict[str, Any]) -> None:
+    sys.stdout.write(canonical_json(result))
+    sys.stdout.write("\n")
+
+
+def _print_human_result(result: dict[str, Any], subcommand: str) -> None:
+    tool = result.get("tool", "?")
+    mode = result.get("install_mode", "?")
+    manual = result.get("manual_step_required", False)
+    actions = result.get("actions", [])
+    if manual:
+        # FIRST LINE must be "manual step required:" per Rev 8 acceptance criterion.
+        sys.stdout.write(f"manual step required: {tool} ({mode}) prepared, but needs a user action\n")
+    else:
+        sys.stdout.write(f"agent-style {subcommand} {tool} ({mode}): ")
+        sys.stdout.write("ok\n" if actions else "no changes\n")
+    for action in actions:
+        op = action.get("op", "?")
+        path = action.get("path", "?")
+        if op == "print-prompt":
+            # For print-only tools, the prompt body goes to stdout (clean).
+            # The human-step message is already above; the prompt content is whatever
+            # the adapter contains. The CLI loads it via print-prompt here.
+            # (Installer already wrote the file; we just echo the bundled body.)
+            sys.stderr.write(f"  action: {op} {path} (prompt body printed to stdout below)\n")
+        elif op == "print-snippet":
+            # For multi-file-required, the snippet goes to stderr so stdout stays clean.
+            snippet = action.get("snippet", "")
+            sys.stderr.write(f"  action: {op} {path}\n")
+            sys.stderr.write("  add this to your config:\n")
+            for line in snippet.splitlines():
+                sys.stderr.write(f"    {line}\n")
+        else:
+            sys.stderr.write(f"  action: {op} {path}\n")
+
+
+def _cmd_rules(args: argparse.Namespace, registry: Registry) -> int:
+    sys.stdout.write(registry.read_bundled_rules())
+    return 0
+
+
+def _cmd_path(args: argparse.Namespace, registry: Registry) -> int:
+    print(registry.data_dir)
+    return 0
+
+
+def _cmd_list_tools(args: argparse.Namespace, registry: Registry) -> int:
+    for name, spec in registry.tools.items():
+        print(f"{name:18}  {spec['install_mode']:22}  {spec['target_path']}")
+    return 0
+
+
+def _cmd_enable(args: argparse.Namespace, registry: Registry) -> int:
+    try:
+        result = enable(args.tool, registry, project_root=".", dry_run=args.dry_run)
+    except (RegistryError, RuntimeError) as exc:
+        sys.stderr.write(f"error: {exc}\n")
+        return 2
+    if args.json:
+        _print_json_result(result)
+    else:
+        _print_human_result(result, "enable")
+        if result.get("install_mode") == "print-only":
+            # Clean stdout with prompt body (for users who redirect `> prompt.md`).
+            target = result["actions"][0].get("path") if result["actions"] else None
+            if target:
+                body = registry.read_adapter(registry.get(args.tool)["adapter_source"])
+                sys.stdout.write(body)
+    return 0
+
+
+def _cmd_disable(args: argparse.Namespace, registry: Registry) -> int:
+    try:
+        result = disable(args.tool, registry, project_root=".", dry_run=args.dry_run)
+    except (RegistryError, RuntimeError) as exc:
+        sys.stderr.write(f"error: {exc}\n")
+        return 2
+    if args.json:
+        _print_json_result(result)
+    else:
+        _print_human_result(result, "disable")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agent-style",
+        description=(
+            "agent-style: install and manage The Elements of Agent Style writing "
+            "ruleset for AI agents (Claude Code, GitHub Copilot, Cursor, AGENTS.md-aware "
+            "tools, Aider, Anthropic Skills, Codex API, and more)."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"agent-style {__version__}",
+    )
+    sub = parser.add_subparsers(dest="command", required=True, metavar="<command>")
+
+    sub.add_parser("rules", help="Print bundled RULES.md to stdout.")
+    sub.add_parser("path", help="Print bundled data directory path.")
+    sub.add_parser("list-tools", help="List supported tools and their install modes.")
+
+    for subcmd in ("enable", "disable"):
+        p = sub.add_parser(
+            subcmd,
+            help=(
+                "Enable agent-style for a given tool (safe-append to your existing file)."
+                if subcmd == "enable"
+                else "Remove agent-style for a given tool from your instruction file."
+            ),
+        )
+        p.add_argument("tool", help="Tool name (see `agent-style list-tools`).")
+        p.add_argument(
+            "--dry-run",
+            action="store_true",
+            help="Print planned actions without writing any file.",
+        )
+        p.add_argument(
+            "--json",
+            action="store_true",
+            help="Emit canonical JSON output (sorted keys, LF, POSIX paths).",
+        )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        registry = Registry()
+    except RegistryError as exc:
+        sys.stderr.write(f"registry error: {exc}\n")
+        return 2
+    dispatch = {
+        "rules": _cmd_rules,
+        "path": _cmd_path,
+        "list-tools": _cmd_list_tools,
+        "enable": _cmd_enable,
+        "disable": _cmd_disable,
+    }
+    return dispatch[args.command](args, registry)
+
+
+if __name__ == "__main__":
+    sys.exit(main())