{"id":49574721,"url":"https://github.com/chojondocho/vowline","last_synced_at":"2026-05-06T19:01:14.032Z","repository":{"id":355022096,"uuid":"1225196741","full_name":"chojondocho/vowline","owner":"chojondocho","description":"A compact operating covenant for AI agents.","archived":false,"fork":false,"pushed_at":"2026-05-03T14:53:54.000Z","size":1506,"stargazers_count":19,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-04T17:37:51.316Z","etag":null,"topics":["agent-skills","ai-agents","claude-code","codex","developer-tools","gpt-5-5","prompt-engineering","skill-md","skills"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chojondocho.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-30T03:29:15.000Z","updated_at":"2026-05-04T09:26:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chojondocho/vowline","commit_stats":null,"previous_names":["chojondocho/vowline"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/chojondocho/vowline","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chojondocho%2Fvowline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chojondocho%2Fvowline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chojondocho%2Fvowline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chojondocho%2Fvowline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chojondocho","download_url":"https://codeload.github.com/chojondocho/vowline/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chojondocho%2Fvowline/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32661193,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agents","claude-code","codex","developer-tools","gpt-5-5","prompt-engineering","skill-md","skills"],"created_at":"2026-05-03T16:06:29.254Z","updated_at":"2026-05-05T18:01:42.109Z","avatar_url":"https://github.com/chojondocho.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vowline\n\n[![check](https://github.com/chojondocho/vowline/actions/workflows/check.yml/badge.svg)](https://github.com/chojondocho/vowline/actions/workflows/check.yml)\n[![release](https://img.shields.io/github/v/release/chojondocho/vowline?label=release\u0026cacheSeconds=300)](https://github.com/chojondocho/vowline/releases)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/vowline-banner.png\" alt=\"Vowline brand banner: one luminous line moving through aligned agent nodes\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n**General operating skill for substantive AI agent work.**\n\nVowline is a portable `SKILL.md` package for Codex, Claude Code, Windsurf, Cursor, Gemini CLI, GitHub Copilot, and other skill-compatible agent harnesses. It gives agents a cross-cutting operating layer for meaningful work across domains: infer intent, choose the right effort level, use evidence and tools deliberately, preserve constraints, act safely, verify, and report the result plainly.\n\nUse it when intent inference, safe action, evidence, verification, concise reporting, or completion criteria matter: coding, debugging, research, writing, artifacts, planning, review, decisions, visual work, prompt work, repository work, and handoffs. Vowline is designed to run alongside narrower active skills; those narrower skills keep their domain-specific procedures, while Vowline governs the shared operating discipline.\n\n## Quick start\n\nThe easiest path is to ask the target agent to install Vowline for itself:\n\n```text\nInstall Vowline for yourself by following https://github.com/chojondocho/vowline/blob/main/INSTALL.md. Verify installation.\n```\n\nFor a project-local install, ask from inside the project:\n\n```text\nInstall Vowline into this project by following https://github.com/chojondocho/vowline/blob/main/INSTALL.md. Use project-local paths. Verify installation.\n```\n\nTo update an existing install after a Vowline release or contract change:\n\n```text\nUpdate Vowline for yourself by following https://github.com/chojondocho/vowline/blob/main/UPDATE.md. Verify the update.\n```\n\nYou do not need to clone this repository if your agent can read GitHub and write the relevant local files. Vowline is designed to be installed by agents as well as by humans.\n\n## What it changes\n\nVowline does not add a rigid script. It changes the agent's default operating posture for work where judgment, evidence, tools, side effects, or completion criteria matter.\n\n| Area | What changes |\n| --- | --- |\n| Authority | Stays beneath higher-priority system, platform, safety, tool, project, runtime, and user instructions |\n| Skill coordination | Runs alongside narrower active skills, while preserving the shared discipline those skills usually do not cover |\n| Delegation | Propagates objective, constraints, authorization boundaries, evidence needs, validation, and reporting requirements to subagents |\n| Effort | Uses fast, standard, or deep mode instead of treating every request as the same size |\n| Intent | Optimizes for the user's real purpose, not only the visible wording |\n| Assumptions | Proceeds with the smallest safe assumption unless missing information materially changes the result or creates risk |\n| Evidence | Inspects referenced artifacts, retrieves support when needed, and separates evidence, inference, speculation, and absence of evidence |\n| Tool use | Selects real available tools when they matter, remaps unavailable planned tools, and preserves verification needs |\n| Change discipline | Makes the smallest sufficient change while preserving behavior, interfaces, facts, style, security, accessibility, and performance |\n| Authorization | Requires explicit approval before external, irreversible, credential-related, production, purchasing, publishing, messaging, commit, push, deployment, or data-mutating actions |\n| Verification | Checks the affected path by the cheapest reliable method and says exactly what could not be verified |\n| Reporting | Leads with the result and keeps evidence, assumptions, validation, risks, blockers, paths, commands, and citations exact |\n| Completion | Tracks every requested item and stops only when the deliverable is usable or a safe blocker is reached |\n| Task overlays | Adds domain guidance for coding, debugging, research, writing, artifacts, data, frontend, high-stakes advice, plans, prompts, and handoffs |\n\nIn practice, it keeps agents focused on this operating shape:\n\n```text\nRespect higher-priority instructions.\nChoose the lightest mode that can produce a correct result.\nInfer the real outcome, constraints, evidence needs, and stopping condition.\nUse available tools and retrieval when they materially improve the work, remapping unavailable tools without dropping the objective.\nCoordinate narrower skills and subagents without losing authorization boundaries.\nMake the smallest sufficient safe change or artifact.\nVerify by the cheapest reliable method that matches the task.\nReport result-first with evidence, validation, assumptions, risks, and blockers.\nStop when the deliverable is usable or a safe blocker is reached.\n```\n\n## Why agents need it\n\nModern agents can already write, browse, edit, run tools, inspect files, call APIs, and delegate work. The failure point is often not raw capability; it is inconsistent operating discipline. An agent may ask when it should proceed, proceed when it should ask, assume a tool exists without checking, abandon verification when a preferred tool is unavailable, edit beyond the requested scope, delegate without constraints, or report effort instead of a usable result.\n\nVowline gives every agent a portable default for those failure points. It does not replace specialized skills; it makes them safer and more reliable by carrying the shared contract for intent, evidence, authorization, verification, completion, and result-first reporting. Any agent trusted with meaningful work should have Vowline installed before that work begins.\n\nA useful surprise is that this can make the same underlying model behave more agentically while spending fewer tokens. Clear operating defaults reduce avoidable clarification loops, redundant retrieval, over-planning, unfocused tool use, and verbose status reporting. The result is not just cleaner prose; it is more useful work per turn.\n\n## Supported agents\n\nVowline keeps the canonical behavior in `skills/vowline/SKILL.md` and installs host bridge files for tools that read rules, memories, or instruction files.\n\n| Agent / harness | Project install writes |\n| --- | --- |\n| Codex / AGENTS-aware tools | `.agents/skills/vowline/SKILL.md`, `AGENTS.md` |\n| Claude Code | `.claude/skills/vowline/SKILL.md`, `CLAUDE.md` |\n| Windsurf | `.windsurf/skills/vowline/SKILL.md`, `.windsurf/rules/vowline.md` |\n| Cursor | `.cursor/skills/vowline/SKILL.md`, `.cursor/rules/vowline.mdc` |\n| Gemini CLI | `.gemini/skills/vowline/SKILL.md`, `GEMINI.md` |\n| GitHub Copilot | `.github/skills/vowline/SKILL.md`, `.github/copilot-instructions.md` |\n| Community `SKILL.md` targets | OpenCode, Amp, Goose, Cline, Roo Code, Aider, OpenClaw, Trae skill folders |\n\nCodex uses `~/.agents/skills/vowline/SKILL.md` as the documented user-level skill path. The installer also mirrors the skill into `${CODEX_HOME:-~/.codex}/skills/vowline/SKILL.md` for compatibility with Codex environments that use `CODEX_HOME/skills`. Treat that mirror as compatibility support, not as the primary Codex path.\n\nSee [INSTALL.md](INSTALL.md) and [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) for exact global and project paths. See [UPDATE.md](UPDATE.md) and [UNINSTALL.md](UNINSTALL.md) for update and removal flows.\n\n## Scripted install and update\n\nThe scripts are optional. They use only the Python standard library and are safe to run repeatedly.\n\nClone the repository first:\n\n```bash\ngit clone https://github.com/chojondocho/vowline.git\ncd vowline\n```\n\nInstall into the current user's agent locations:\n\n```bash\npython3 install.py global --harnesses core\npython3 install.py verify-global --harnesses core\n```\n\nUpdate an existing install by pulling the latest repository and running the same install command again:\n\n```bash\ngit pull\npython3 install.py global --harnesses core\npython3 install.py verify-global --harnesses core\n```\n\nInstall into one project:\n\n```bash\npython3 install.py project /path/to/project --harnesses core\npython3 install.py verify /path/to/project --harnesses core\n```\n\nInstall only selected harnesses:\n\n```bash\npython3 install.py project /path/to/project --harnesses codex,claude,windsurf\npython3 install.py global --harnesses codex\n```\n\nHarness groups:\n\n| Group | Includes |\n| --- | --- |\n| `core` | Codex, Claude Code, Windsurf, Cursor, Gemini CLI, GitHub Copilot |\n| `community` | OpenCode, Amp, Goose, Cline, Roo Code, Aider, OpenClaw, Trae |\n| `all` | `core` plus `community` |\n\nThe script default is `all`. Pass `--harnesses core` when you want only the mainstream host targets.\n\n## How to use it\n\nAfter installation, direct invocation is usually optional because host bridge files activate or route to Vowline where the host supports that pattern. Direct invocation is still useful when you want to force the skill for one request:\n\n```text\n$vowline review this launch plan for weak assumptions\n/vowline rewrite this memo without losing the author's intent\n@vowline compare these implementation options and recommend one\n$vowline debug this failing test with the smallest safe change\n```\n\nCodex commonly uses `$vowline`, Claude Code commonly uses `/vowline`, and Windsurf commonly uses `@vowline`. Other hosts may surface skills or rules differently.\n\n## Repository layout\n\n```text\nskills/vowline/SKILL.md         Canonical Vowline contract\nguidance/VOWLINE_ACTIVATION.md  Canonical activation bridge body\ninstall.py                      Optional installer and verifier\nuninstall.py                    Optional uninstaller and verifier\nUPDATE.md                       Update guide for existing installs\ndocs/COMPATIBILITY.md           Supported paths and host notes\ntests/                          Installer, verifier, and uninstall coverage\n```\n\nWhen Vowline edits an existing instruction file, it uses a marked block and preserves unrelated content. The activation body has one source of truth: [guidance/VOWLINE_ACTIVATION.md](guidance/VOWLINE_ACTIVATION.md).\n\n```text\n\u003c!-- vowline:start --\u003e\n\u003ccontents of guidance/VOWLINE_ACTIVATION.md\u003e\n\u003c!-- vowline:end --\u003e\n```\n\nRepeated installs replace only that marked block. Generated rule files for Cursor and Windsurf use the same activation body with host-required front matter added by `install.py`. Manual installers can render the exact block or rule text with `python3 install.py render-guidance marked-block`, `python3 install.py render-guidance CURSOR.mdc`, or `python3 install.py render-guidance WINDSURF.md`.\n\nExisting installs update by repeating the relevant install command from the latest repository. See [UPDATE.md](UPDATE.md).\n\n## Boundaries\n\nVowline does not override system messages, platform policies, safety rules, repository instructions, organization settings, or tool permissions. It also does not make every host invoke the skill automatically.\n\nVowline does not grant permission to deploy, publish, purchase, message people, mutate production data, delete user data, rotate credentials, or take other externally visible or irreversible actions. It tells the agent to prepare the work and ask for explicit approval first.\n\n## Development checks\n\nRun the same basic checks used by the repository:\n\n```bash\npython3 -m py_compile install.py uninstall.py\npython3 -m unittest discover -s tests\n```\n\nThe tests cover project installs, global installs, harness selection, idempotent marked-block replacement, legacy cleanup, verification, and uninstall behavior.\n\n## Uninstall\n\nAsk the agent to remove Vowline:\n\n```text\nUninstall Vowline from yourself by following https://github.com/chojondocho/vowline/blob/main/UNINSTALL.md. Verify removal.\n```\n\nOr use the optional script:\n\n```bash\npython3 uninstall.py global --harnesses core\npython3 uninstall.py verify-global --harnesses core\n```\n\nFor project-local removal:\n\n```bash\npython3 uninstall.py project /path/to/project --harnesses core\npython3 uninstall.py verify /path/to/project --harnesses core\n```\n\nUninstall removes Vowline-owned skill directories and Vowline marked blocks. It should not remove unrelated user or project instructions.\n\n## Name\n\n`Vowline` means a line of commitment: a small covenant tying the agent to the user's actual outcome. It is not legal trademark clearance.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchojondocho%2Fvowline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchojondocho%2Fvowline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchojondocho%2Fvowline/lists"}