opencode-skills-collection 4.1.14 → 4.1.16

package/bundled-skills/polis-protocol-a-self-optimizing-city-of-agents/scripts/init_polis.py

@@ -0,0 +1,559 @@
+#!/usr/bin/env python3
+"""
+init_polis.py — scaffold a new Polis Protocol project.
+
+Creates the canonical _polis/ folder structure inside a project root, with all
+template files populated. Idempotent and non-destructive: if files exist, it
+warns and skips rather than overwriting. Use --repair to restore missing managed
+files, and `polis migrate` for schema upgrades.
+
+Usage:
+    python init_polis.py --project-root <path> --agent-id <name>
+
+Optional arguments:
+    --project-name "Pesaj 2027 materials"
+    --vendor anthropic
+    --model claude-opus-4-7
+    --tool "claude.ai web"
+    --role "research and source-checking"
+    --languages en,es,he
+    --bridge-tools claude,codex,gemini,aider  # which entry pointers to write
+    --codex-skill / --no-codex-skill       # write .agents/skills/polis-protocol/SKILL.md
+    --antigravity-skill / --no-antigravity-skill  # write .agents/skills/polis-protocol/SKILL.md (Antigravity reads this)
+    --dry-run                              # preview files without writing
+    --repair                               # restore missing managed files (never overwrites)
+    --force                                # deprecated, ignored (init never overwrites)
+
+The bridge pointers (CLAUDE.md, AGENTS.md, GEMINI.md, AIDER.md) are short files
+at the project root that point each tool at the canonical _polis/CONSTITUTION.md,
+so Claude, Codex, Gemini, and Aider can all discover and follow the same protocol.
+"""
+
+import argparse
+import datetime
+import hashlib
+import re
+import sys
+from pathlib import Path
+
+
+AGENT_ID_PATTERN = re.compile(r"^[a-z][a-z0-9\-]{7,39}$")
+TAG_PATTERN = re.compile(r"^[a-z][a-z0-9\-]{2,49}$")
+
+
+def validate_agent_id(agent_id: str) -> None:
+    if not AGENT_ID_PATTERN.match(agent_id):
+        raise SystemExit(
+            f"Invalid agent-id '{agent_id}'. "
+            "Use lowercase ASCII letters, digits, and hyphens; start with a letter; "
+            "length 8 to 40 characters. Example: 'claude-research-pesaj'."
+        )
+
+
+def now_iso(seconds: bool = True) -> str:
+    fmt = "%Y-%m-%d %H:%M:%S" if seconds else "%Y-%m-%d %H:%M"
+    return datetime.datetime.now(datetime.timezone.utc).strftime(fmt)
+
+
+def today_iso() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%d")
+
+
+def current_quarter() -> str:
+    now = datetime.datetime.now(datetime.timezone.utc)
+    q = (now.month - 1) // 3 + 1
+    return f"{now.year}-Q{q}"
+
+
+# Data files (templates + the SKILL.md the init copies into a project) ship as
+# package data under polis/_data/ so they survive a pip/uvx install. In a repo
+# checkout that location exists too; we fall back to the repo root only if the
+# bundled copy is somehow missing.
+def data_path(rel: str) -> Path:
+    bundled = Path(__file__).resolve().parent / "_data" / rel
+    if bundled.exists():
+        return bundled
+    return Path(__file__).resolve().parent.parent / rel
+
+
+TEMPLATES_DIR = data_path("templates")
+
+
+def load_template(name: str) -> str:
+    path = TEMPLATES_DIR / name
+    if not path.exists():
+        raise SystemExit(
+            f"Template not found: {path}. "
+            "The skill folder may be incomplete; expected templates/ alongside scripts/."
+        )
+    return path.read_text(encoding="utf-8")
+
+
+def write_if_absent(path: Path, content: str, force: bool = False) -> str:
+    """Write content to path; return 'created', 'exists', or 'overwritten'."""
+    existed = path.exists()
+    if existed and not force:
+        return "exists"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return "overwritten" if existed else "created"
+
+
+def sign_card(card_body: str, agent_id: str, registered_date: str) -> str:
+    """Compute a card signature: hash of body plus identity, for integrity checks."""
+    h = hashlib.sha256()
+    h.update(card_body.encode("utf-8"))
+    h.update(agent_id.encode("utf-8"))
+    h.update(registered_date.encode("utf-8"))
+    return f"{agent_id}:{registered_date}:sha256:{h.hexdigest()[:32]}"
+
+
+def build_capability_card(
+    agent_id: str,
+    vendor: str,
+    model: str,
+    tool: str,
+    languages: list,
+) -> str:
+    """Build a minimal, honest capability card. The founder edits it after bootstrap."""
+    registered = now_iso()
+    languages_yaml = "[" + ", ".join(languages) + "]"
+
+    body_without_signature = f"""agent_id: {agent_id}
+vendor: {vendor}
+model: {model}
+tool: {tool}
+registered: {registered}
+last_card_update: {registered}
+
+languages: {languages_yaml}
+
+capability_tags:
+  # Add capability tags below with honest self-ratings (1-5).
+  # Examples to start from; edit or remove freely.
+  general-reasoning:
+    self_rating: 4
+    evidence: "default baseline for this model family"
+  long-context-reading:
+    self_rating: 3
+    evidence: "edit this to reflect your actual context window"
+
+cost_envelope:
+  relative: medium
+  notes: "edit to reflect actual pricing or rate-limit posture"
+
+latency_envelope:
+  typical_minutes: 3
+  max_minutes: 30
+  async_ok: true
+
+tools_available:
+  - read_file
+  - write_file
+  # add tools available in your current session
+
+standing_instructions: |
+  - Edit this section with persistent preferences this agent should honor.
+"""
+    signature = sign_card(body_without_signature, agent_id, registered)
+    return body_without_signature + f'\nsignature: "{signature}"\n'
+
+
+def build_readme(project_name: str) -> str:
+    return f"""# Polis Coordination Folder
+
+This folder is the coordination layer for the AI agents working on **{project_name}**.
+It is not for routine human consumption, but humans are welcome to read along.
+
+## What is in here
+
+- `CONSTITUTION.md`: the protocol every citizen follows. Read this first if you are an agent.
+- `index.md`: the canonical "where things stand" page.
+- `chronicle.md`: an append-only log of everything notable any citizen has done.
+- `citizens/`: one folder per registered citizen, with capability card, status, inbox, and journal.
+- `contracts/`: one file per task. Open contracts are active; settled contracts are closed.
+- `lessons/`: retrospective notes, filed by capability tag.
+- `reviews/`: chavruta review notes for high-stakes contracts.
+- `amendments/`: proposed and ratified changes to the protocol itself.
+
+## How agents use this
+
+Every citizen reads `index.md` and its own inbox at the start of every session,
+posts a single line to `chronicle.md` after each meaningful action, and updates
+its `status.md` when picking up or dropping a contract. Detailed work happens
+in project folders elsewhere in the repository.
+
+## How to read along as a human
+
+Start with `index.md` for the current state, then `chronicle.md` for recent
+activity. Drill into any contract or lesson that interests you.
+"""
+
+
+def build_index(project_name: str, founder_id: str) -> str:
+    today = today_iso()
+    timestamp = now_iso()
+    return f"""---
+last_updated: {timestamp}
+index_keeper: {founder_id}
+project_name: {project_name}
+project_started: {today}
+active_citizens: 1
+open_contracts: 0
+---
+
+# {project_name}
+
+## Project summary
+
+Edit this section with a two or three sentence description of what this project is,
+who it is for, and what the deliverable looks like.
+
+## Current focus
+
+No open contracts yet. Open the first contract under `contracts/open/`.
+
+## Citizens and roles
+
+- `{founder_id}`: founding citizen, currently idle
+
+## Open amendments
+
+None.
+
+## Stale or blocked
+
+None.
+"""
+
+
+def build_chronicle(founder_id: str) -> str:
+    timestamp = now_iso(seconds=False)
+    return f"""---
+file_type: chronicle
+rollover_policy: quarterly
+current_period: {current_quarter()}
+---
+
+- {timestamp} | {founder_id} | founded polis | - | first commit of polis protocol
+"""
+
+
+def build_routing_stats() -> str:
+    return f"""last_updated: {now_iso()}
+explore_rate: 0.15
+tags: {{}}
+"""
+
+
+def build_status(agent_id: str) -> str:
+    return f"""---
+agent_id: {agent_id}
+last_active: {now_iso()}
+state: idle
+current_contract: null
+blockers: []
+last_seen_event: {now_iso(seconds=False)}
+last_seen_amendment: null
+---
+
+# Status: {agent_id}
+"""
+
+
+def build_inbox(agent_id: str) -> str:
+    return f"""---
+file_type: inbox
+owner: {agent_id}
+---
+
+<!-- Messages from other citizens appear below, newest at the bottom. -->
+"""
+
+
+def build_journal(agent_id: str) -> str:
+    return f"""---
+file_type: journal
+owner: {agent_id}
+---
+
+# Private journal: {agent_id}
+
+<!-- For reasoning traces, false starts, half-formed ideas, anything that would
+be noise in the chronicle. Audience: future instances of this same citizen. -->
+"""
+
+
+def bridge_pointer_targets(
+    project_root: Path,
+    bridge_tools: list,
+) -> dict:
+    """Return supported bridge pointer targets keyed by display name."""
+    targets = {}
+    filename_map = {
+        "claude": "CLAUDE.md",
+        "codex": "AGENTS.md",
+        "gemini": "GEMINI.md",
+        "aider": "AIDER.md",
+    }
+    for tool in bridge_tools:
+        tool = tool.strip().lower()
+        if tool not in filename_map:
+            print(f"  warning: unknown bridge tool '{tool}', skipping.")
+            continue
+        filename = filename_map[tool]
+        targets[f"<root>/{filename}"] = project_root / filename
+    return targets
+
+
+def write_bridge_pointers(
+    project_root: Path,
+    bridge_tools: list,
+    force: bool,
+) -> dict:
+    """Write CLAUDE.md, AGENTS.md, GEMINI.md at project root."""
+    pointer_content = load_template("bridge_pointer.md")
+    results = {}
+    for display_name, target in bridge_pointer_targets(project_root, bridge_tools).items():
+        results[display_name] = write_if_absent(target, pointer_content, force=force)
+    return results
+
+
+def write_codex_skill_copy(project_root: Path, skill_md: Path, force: bool) -> str:
+    target = project_root / ".agents" / "skills" / "polis-protocol" / "SKILL.md"
+    return write_if_absent(target, skill_md.read_text(encoding="utf-8"), force=force)
+
+
+def write_antigravity_skill_copy(project_root: Path, skill_md: Path, force: bool) -> str:
+    """Mirror SKILL.md into the location Google Antigravity reads skills from.
+
+    Antigravity loads workspace skills from .agents/skills/ (the same path the
+    Codex CLI uses); the legacy .antigravity/skills/ folder is never read.
+    """
+    target = project_root / ".agents" / "skills" / "polis-protocol" / "SKILL.md"
+    return write_if_absent(target, skill_md.read_text(encoding="utf-8"), force=force)
+
+
+def planned_actions(
+    project_root: Path,
+    bridge_tools: list,
+    codex_skill: bool,
+    antigravity_skill: bool = False,
+) -> dict:
+    actions = {
+        "CONSTITUTION.md": "planned",
+        "README.md": "planned",
+        "index.md": "planned",
+        "chronicle.md": "planned",
+        "routing_stats.yml": "planned",
+        "capability_card.yml": "planned",
+        "status.md": "planned",
+        "inbox.md": "planned",
+        "journal.md": "planned",
+    }
+    for display_name in bridge_pointer_targets(project_root, bridge_tools):
+        actions[display_name] = "planned"
+    skill_md = data_path("SKILL.md")
+    if codex_skill:
+        if skill_md.exists():
+            actions[".agents/skills/polis-protocol/SKILL.md"] = "planned"
+        else:
+            print("  warning: SKILL.md not found at skill root; skipping codex skill copy.")
+    if antigravity_skill:
+        if skill_md.exists():
+            actions[".agents/skills/polis-protocol/SKILL.md"] = "planned"
+        else:
+            print("  warning: SKILL.md not found at skill root; skipping antigravity skill copy.")
+    return actions
+
+
+def print_report(
+    polis_root: Path,
+    agent_id: str,
+    vendor: str,
+    model: str,
+    actions: dict,
+    dry_run: bool = False,
+) -> None:
+    if dry_run:
+        print(f"\nDry run: Polis would be founded at {polis_root}")
+    else:
+        print(f"\nPolis founded at {polis_root}")
+    print(f"Founder: {agent_id} ({vendor} / {model})\n")
+    print("Files:")
+    for name, result in actions.items():
+        marker = {"created": "+", "overwritten": "~", "exists": ".", "planned": "?"}[result]
+        print(f"  {marker} {name}")
+    if dry_run:
+        print("\nNo files or directories were created.")
+        return
+    print("\nNext steps:")
+    print(f"  1. Edit _polis/citizens/{agent_id}/capability_card.yml with honest capability tags.")
+    print(f"  2. Edit _polis/index.md with a project summary.")
+    print(f"  3. Open your first contract under _polis/contracts/open/.")
+    print("  4. When other agents (Codex, Gemini, others) enter this project, they will read the bridge pointers and register themselves.\n")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Scaffold a new Polis Protocol project.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--project-root", required=True, help="Path to the project root.")
+    parser.add_argument("--agent-id", required=True, help="Your agent ID. Example: claude-research-pesaj")
+    parser.add_argument("--project-name", default="Unnamed Project", help="Human-readable project name.")
+    parser.add_argument("--vendor", default="anthropic", help="One of: anthropic, openai, google, meta, mistral, other.")
+    parser.add_argument("--model", default="claude-opus-4-7", help="Model identifier string.")
+    parser.add_argument("--tool", default="claude.ai web", help="Tool string. Example: 'claude code', 'codex', 'gemini cli'.")
+    parser.add_argument("--role", default="founding citizen", help="Short role description (used in profile prose).")
+    parser.add_argument("--languages", default="en", help="Comma-separated language codes. Example: en,es,he")
+    parser.add_argument("--bridge-tools", default="claude,codex,gemini,aider", help="Which entry pointers to write at project root.")
+    parser.add_argument("--codex-skill", dest="codex_skill", action="store_true", default=True)
+    parser.add_argument("--no-codex-skill", dest="codex_skill", action="store_false")
+    parser.add_argument("--antigravity-skill", dest="antigravity_skill", action="store_true", default=True,
+                        help="Mirror SKILL.md into .agents/skills/ for Google Antigravity.")
+    parser.add_argument("--no-antigravity-skill", dest="antigravity_skill", action="store_false")
+    parser.add_argument("--dry-run", action="store_true", help="Preview scaffolded files without writing anything.")
+    parser.add_argument("--repair", action="store_true",
+                        help="Restore missing managed files without overwriting existing ones.")
+    parser.add_argument("--force", action="store_true",
+                        help="Deprecated and ignored: init never overwrites existing files.")
+    args = parser.parse_args()
+
+    # Destructive overwrite has been removed. init only ever fills gaps; for schema
+    # upgrades use `polis migrate`. --force is kept as a no-op for compatibility.
+    if args.force:
+        print("  warning: --force is deprecated and ignored — existing files are never "
+              "overwritten. Use `polis migrate` to upgrade, or --repair to restore missing files.")
+    args.force = False
+    if args.repair:
+        print("  repair mode: restoring any missing managed files; existing files are left untouched.")
+
+    validate_agent_id(args.agent_id)
+
+    project_root = Path(args.project_root).resolve()
+    if not project_root.exists():
+        raise SystemExit(f"Project root does not exist: {project_root}")
+
+    polis_root = project_root / "_polis"
+    citizens_dir = polis_root / "citizens" / args.agent_id
+    contracts_dir = polis_root / "contracts"
+    lessons_dir = polis_root / "lessons"
+    reviews_dir = polis_root / "reviews"
+    amendments_dir = polis_root / "amendments"
+
+    languages = [lang.strip() for lang in args.languages.split(",") if lang.strip()]
+    bridge_tools = [t.strip() for t in args.bridge_tools.split(",") if t.strip()]
+
+    if args.dry_run:
+        actions = planned_actions(project_root, bridge_tools, args.codex_skill, args.antigravity_skill)
+        print_report(
+            polis_root,
+            args.agent_id,
+            args.vendor,
+            args.model,
+            actions,
+            dry_run=True,
+        )
+        return
+
+    # Pre-create directories that the templates do not include via file writes.
+    for d in [
+        polis_root,
+        citizens_dir,
+        contracts_dir / "open",
+        contracts_dir / "settled",
+        lessons_dir,
+        reviews_dir,
+        amendments_dir / "proposed",
+        amendments_dir / "ratified",
+    ]:
+        d.mkdir(parents=True, exist_ok=True)
+
+    actions = {}
+
+    # Core polis files.
+    actions["CONSTITUTION.md"] = write_if_absent(
+        polis_root / "CONSTITUTION.md",
+        load_template("POLIS_CONSTITUTION.md"),
+        force=args.force,
+    )
+    actions["README.md"] = write_if_absent(
+        polis_root / "README.md",
+        build_readme(args.project_name),
+        force=args.force,
+    )
+    actions["index.md"] = write_if_absent(
+        polis_root / "index.md",
+        build_index(args.project_name, args.agent_id),
+        force=args.force,
+    )
+    actions["chronicle.md"] = write_if_absent(
+        polis_root / "chronicle.md",
+        build_chronicle(args.agent_id),
+        force=args.force,
+    )
+    actions["routing_stats.yml"] = write_if_absent(
+        contracts_dir / "routing_stats.yml",
+        build_routing_stats(),
+        force=args.force,
+    )
+
+    # Founding citizen files.
+    actions["capability_card.yml"] = write_if_absent(
+        citizens_dir / "capability_card.yml",
+        build_capability_card(
+            agent_id=args.agent_id,
+            vendor=args.vendor,
+            model=args.model,
+            tool=args.tool,
+            languages=languages,
+        ),
+        force=args.force,
+    )
+    actions["status.md"] = write_if_absent(
+        citizens_dir / "status.md",
+        build_status(args.agent_id),
+        force=args.force,
+    )
+    actions["inbox.md"] = write_if_absent(
+        citizens_dir / "inbox.md",
+        build_inbox(args.agent_id),
+        force=args.force,
+    )
+    actions["journal.md"] = write_if_absent(
+        citizens_dir / "journal.md",
+        build_journal(args.agent_id),
+        force=args.force,
+    )
+
+    # Bridge pointers at project root.
+    bridge_results = write_bridge_pointers(project_root, bridge_tools, args.force)
+    for display_name, result in bridge_results.items():
+        actions[display_name] = result
+
+    # Codex-format skill copy.
+    skill_md = data_path("SKILL.md")
+    if args.codex_skill:
+        if skill_md.exists():
+            actions[".agents/skills/polis-protocol/SKILL.md"] = write_codex_skill_copy(
+                project_root, skill_md, args.force
+            )
+        else:
+            print("  warning: SKILL.md not found at skill root; skipping codex skill copy.")
+
+    # Antigravity skill copy. Antigravity reads .agents/skills/ — the same path the
+    # Codex copy uses — so only write it here if the Codex copy above didn't already.
+    if args.antigravity_skill and not args.codex_skill:
+        if skill_md.exists():
+            actions[".agents/skills/polis-protocol/SKILL.md"] = write_antigravity_skill_copy(
+                project_root, skill_md, args.force
+            )
+        else:
+            print("  warning: SKILL.md not found at skill root; skipping antigravity skill copy.")
+
+    print_report(polis_root, args.agent_id, args.vendor, args.model, actions)
+
+
+if __name__ == "__main__":
+    main()

package/bundled-skills/polis-protocol-a-self-optimizing-city-of-agents/scripts/route_contract.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""Backward-compatible shim.
+
+The implementation now lives in ``polis/routing.py``. This shim keeps existing
+references working (SKILL.md, docs, the reconcile regression test, and anyone
+calling ``python3 scripts/route_contract.py``).
+"""
+import sys
+from pathlib import Path
+
+# Make the `polis` package importable when this file is run directly from the repo.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from polis.routing import *  # noqa: F401,F403
+# Re-export private helpers used by scripts/test_reconcile_parsing.py.
+from polis.routing import _extract_quality, _extract_actual_minutes, main  # noqa: F401
+
+if __name__ == "__main__":
+    main()