https://github.com/chojondocho/vowline
A compact operating covenant for AI agents.
https://github.com/chojondocho/vowline
agent-skills ai-agents claude-code codex developer-tools gpt-5-5 prompt-engineering skill-md skills
Last synced: about 2 months ago
JSON representation
A compact operating covenant for AI agents.
- Host: GitHub
- URL: https://github.com/chojondocho/vowline
- Owner: chojondocho
- License: mit
- Created: 2026-04-30T03:29:15.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-03T14:53:54.000Z (about 2 months ago)
- Last Synced: 2026-05-04T17:37:51.316Z (about 2 months ago)
- Topics: agent-skills, ai-agents, claude-code, codex, developer-tools, gpt-5-5, prompt-engineering, skill-md, skills
- Language: Python
- Homepage:
- Size: 1.44 MB
- Stars: 19
- Watchers: 0
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Vowline
[](https://github.com/chojondocho/vowline/actions/workflows/check.yml)
[](https://github.com/chojondocho/vowline/releases)
[](LICENSE)
**General operating skill for substantive AI agent work.**
Vowline 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.
Use 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.
## Quick start
The easiest path is to ask the target agent to install Vowline for itself:
```text
Install Vowline for yourself by following https://github.com/chojondocho/vowline/blob/main/INSTALL.md. Verify installation.
```
For a project-local install, ask from inside the project:
```text
Install Vowline into this project by following https://github.com/chojondocho/vowline/blob/main/INSTALL.md. Use project-local paths. Verify installation.
```
To update an existing install after a Vowline release or contract change:
```text
Update Vowline for yourself by following https://github.com/chojondocho/vowline/blob/main/UPDATE.md. Verify the update.
```
You 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.
## What it changes
Vowline 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.
| Area | What changes |
| --- | --- |
| Authority | Stays beneath higher-priority system, platform, safety, tool, project, runtime, and user instructions |
| Skill coordination | Runs alongside narrower active skills, while preserving the shared discipline those skills usually do not cover |
| Delegation | Propagates objective, constraints, authorization boundaries, evidence needs, validation, and reporting requirements to subagents |
| Effort | Uses fast, standard, or deep mode instead of treating every request as the same size |
| Intent | Optimizes for the user's real purpose, not only the visible wording |
| Assumptions | Proceeds with the smallest safe assumption unless missing information materially changes the result or creates risk |
| Evidence | Inspects referenced artifacts, retrieves support when needed, and separates evidence, inference, speculation, and absence of evidence |
| Tool use | Selects real available tools when they matter, remaps unavailable planned tools, and preserves verification needs |
| Change discipline | Makes the smallest sufficient change while preserving behavior, interfaces, facts, style, security, accessibility, and performance |
| Authorization | Requires explicit approval before external, irreversible, credential-related, production, purchasing, publishing, messaging, commit, push, deployment, or data-mutating actions |
| Verification | Checks the affected path by the cheapest reliable method and says exactly what could not be verified |
| Reporting | Leads with the result and keeps evidence, assumptions, validation, risks, blockers, paths, commands, and citations exact |
| Completion | Tracks every requested item and stops only when the deliverable is usable or a safe blocker is reached |
| Task overlays | Adds domain guidance for coding, debugging, research, writing, artifacts, data, frontend, high-stakes advice, plans, prompts, and handoffs |
In practice, it keeps agents focused on this operating shape:
```text
Respect higher-priority instructions.
Choose the lightest mode that can produce a correct result.
Infer the real outcome, constraints, evidence needs, and stopping condition.
Use available tools and retrieval when they materially improve the work, remapping unavailable tools without dropping the objective.
Coordinate narrower skills and subagents without losing authorization boundaries.
Make the smallest sufficient safe change or artifact.
Verify by the cheapest reliable method that matches the task.
Report result-first with evidence, validation, assumptions, risks, and blockers.
Stop when the deliverable is usable or a safe blocker is reached.
```
## Why agents need it
Modern 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.
Vowline 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.
A 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.
## Supported agents
Vowline keeps the canonical behavior in `skills/vowline/SKILL.md` and installs host bridge files for tools that read rules, memories, or instruction files.
| Agent / harness | Project install writes |
| --- | --- |
| Codex / AGENTS-aware tools | `.agents/skills/vowline/SKILL.md`, `AGENTS.md` |
| Claude Code | `.claude/skills/vowline/SKILL.md`, `CLAUDE.md` |
| Windsurf | `.windsurf/skills/vowline/SKILL.md`, `.windsurf/rules/vowline.md` |
| Cursor | `.cursor/skills/vowline/SKILL.md`, `.cursor/rules/vowline.mdc` |
| Gemini CLI | `.gemini/skills/vowline/SKILL.md`, `GEMINI.md` |
| GitHub Copilot | `.github/skills/vowline/SKILL.md`, `.github/copilot-instructions.md` |
| Community `SKILL.md` targets | OpenCode, Amp, Goose, Cline, Roo Code, Aider, OpenClaw, Trae skill folders |
Codex 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.
See [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.
## Scripted install and update
The scripts are optional. They use only the Python standard library and are safe to run repeatedly.
Clone the repository first:
```bash
git clone https://github.com/chojondocho/vowline.git
cd vowline
```
Install into the current user's agent locations:
```bash
python3 install.py global --harnesses core
python3 install.py verify-global --harnesses core
```
Update an existing install by pulling the latest repository and running the same install command again:
```bash
git pull
python3 install.py global --harnesses core
python3 install.py verify-global --harnesses core
```
Install into one project:
```bash
python3 install.py project /path/to/project --harnesses core
python3 install.py verify /path/to/project --harnesses core
```
Install only selected harnesses:
```bash
python3 install.py project /path/to/project --harnesses codex,claude,windsurf
python3 install.py global --harnesses codex
```
Harness groups:
| Group | Includes |
| --- | --- |
| `core` | Codex, Claude Code, Windsurf, Cursor, Gemini CLI, GitHub Copilot |
| `community` | OpenCode, Amp, Goose, Cline, Roo Code, Aider, OpenClaw, Trae |
| `all` | `core` plus `community` |
The script default is `all`. Pass `--harnesses core` when you want only the mainstream host targets.
## How to use it
After 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:
```text
$vowline review this launch plan for weak assumptions
/vowline rewrite this memo without losing the author's intent
@vowline compare these implementation options and recommend one
$vowline debug this failing test with the smallest safe change
```
Codex commonly uses `$vowline`, Claude Code commonly uses `/vowline`, and Windsurf commonly uses `@vowline`. Other hosts may surface skills or rules differently.
## Repository layout
```text
skills/vowline/SKILL.md Canonical Vowline contract
guidance/VOWLINE_ACTIVATION.md Canonical activation bridge body
install.py Optional installer and verifier
uninstall.py Optional uninstaller and verifier
UPDATE.md Update guide for existing installs
docs/COMPATIBILITY.md Supported paths and host notes
tests/ Installer, verifier, and uninstall coverage
```
When 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).
```text
```
Repeated 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`.
Existing installs update by repeating the relevant install command from the latest repository. See [UPDATE.md](UPDATE.md).
## Boundaries
Vowline 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.
Vowline 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.
## Development checks
Run the same basic checks used by the repository:
```bash
python3 -m py_compile install.py uninstall.py
python3 -m unittest discover -s tests
```
The tests cover project installs, global installs, harness selection, idempotent marked-block replacement, legacy cleanup, verification, and uninstall behavior.
## Uninstall
Ask the agent to remove Vowline:
```text
Uninstall Vowline from yourself by following https://github.com/chojondocho/vowline/blob/main/UNINSTALL.md. Verify removal.
```
Or use the optional script:
```bash
python3 uninstall.py global --harnesses core
python3 uninstall.py verify-global --harnesses core
```
For project-local removal:
```bash
python3 uninstall.py project /path/to/project --harnesses core
python3 uninstall.py verify /path/to/project --harnesses core
```
Uninstall removes Vowline-owned skill directories and Vowline marked blocks. It should not remove unrelated user or project instructions.
## Name
`Vowline` means a line of commitment: a small covenant tying the agent to the user's actual outcome. It is not legal trademark clearance.
## License
MIT. See [LICENSE](LICENSE).