| name | agent-scope-lock |
| description | Create, read, validate, and clear edit-scope locks through the nils-cli agent-scope-lock command. |
Agent Scope Lock
Use this skill when an agent workflow needs a mechanical edit boundary before changing files.
Contract
Prereqs:
- Run inside the target git work tree.
git available on PATH.- Released usage:
agent-scope-lock available on PATH from nils-cli 0.8.4 or newer.
- Local checkout fallback usage: Rust/Cargo plus a validated local
nils-cli checkout that builds the
nils-agent-scope-lock package when PATH is absent or too old.
- Scope paths are repository-relative paths chosen by the owning workflow or agent.
Inputs:
create: one or more --path <repo-relative-path> flags, optional --owner <owner>, optional --note <note>, and optional
--format json.read: optional --format json.validate: required --changes all|staged|unstaged, and optional --format json.clear: no required inputs.
Outputs:
agent-scope-lock create: writes the git metadata lock file resolved by git rev-parse --git-path agent-scope-lock.json.agent-scope-lock read: prints the current lock state.agent-scope-lock validate: reports whether selected working-tree changes stay inside the lock scope.agent-scope-lock clear: removes the current lock file.- No skill-local lock file, parser, or artifact format; treat the nils-cli command as the only stable contract.
Exit codes:
0: command succeeded.- non-zero: usage, git/repository, lock-state, validation, or dependency failure from
agent-scope-lock.
Failure modes:
agent-scope-lock is unavailable on PATH and no validated local checkout invocation is being used.- Current directory is not inside the intended git work tree.
- Requested
create paths are not repository-relative or do not match the intended edit boundary.
validate finds changes outside the active lock scope.- Caller mixes a local checkout fallback with a different released PATH binary; rerun with one explicit invocation source.
Setup
Released PATH boundary:
agent-scope-lock --help
Use the PATH command after installing nils-cli 0.8.4 or newer with nils-agent-scope-lock on PATH.
Local checkout fallback boundary:
cargo run --locked --manifest-path "$HOME/Project/sympoies/nils-cli/Cargo.toml" \
-p nils-agent-scope-lock --bin agent-scope-lock -- --help
Run the Cargo form from the target git work tree, not from the nils-cli checkout.
Use it only when PATH is absent or reports an older nils-cli. Keep the same
agent-scope-lock subcommands and flags in both modes.
Commands (only entrypoints)
Released PATH command:
agent-scope-lock create --path <repo-relative-path> [--path <path> ...] [--owner <owner>] [--note <note>] [--format json]
agent-scope-lock read [--format json]
agent-scope-lock validate --changes all|staged|unstaged [--format json]
agent-scope-lock clear
Local checkout fallback command:
cargo run --locked --manifest-path /path/to/nils-cli/Cargo.toml \
-p nils-agent-scope-lock --bin agent-scope-lock -- <subcommand> ...
Do not edit agent-scope-lock.json manually or duplicate scope validation logic in skill scripts.
Workflow
- Before editing, create the narrowest practical lock:
agent-scope-lock create --path <path> [--path <path> ...] --owner <agent-or-workflow> --note <reason> --format json
- Before acting on an existing task, read the current lock:
agent-scope-lock read --format json
- Before reporting completion, staging, committing, or handing off, validate:
agent-scope-lock validate --changes all --format json
- Clear the lock only when the owning workflow has completed or explicitly hands off:
agent-scope-lock clear
- On failure, report the exact command, exit code, stdout, and stderr; do not claim the edit scope is valid.
References
docs/runbooks/skills/TOOLING_INDEX_V2.md
