Agent Scope Lock

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 flags, optional --owner , optional --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  [--path  ...] [--owner ] [--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 --  ...

Do not edit agent-scope-lock.json manually or duplicate scope validation logic in skill scripts.

Workflow

1. Before editing, create the narrowest practical lock:

agent-scope-lock create --path [--path ...] --owner --note --format json

1. Before acting on an existing task, read the current lock:

agent-scope-lock read --format json

1. Before reporting completion, staging, committing, or handing off, validate:

agent-scope-lock validate --changes all --format json

1. Clear the lock only when the owning workflow has completed or explicitly hands off:

agent-scope-lock clear

1. 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: graysurf
• Source: graysurf/agent-kit
• License: MIT

Install and usage instructions live in the source repository linked above.