Lockstep Skill

AI coding agents should plan before they touch production code.

Lockstep Skill keeps AI coding agents from editing outside the requested scope.

It is a small copyable skill and rule pack for agent-assisted code changes. It asks the agent to state the plan, lock the file scope, keep the change small, redact sensitive logs, verify the result, and end with a clear diff report.

No hooks. No backend. No frontend. No telemetry. No dependencies. No network calls.

Just a local skill pack you can copy into a project before asking an agent to edit code.

Problem

Coding agents move fast, and fast work needs an explicit boundary.

A small bug fix or refactor should stay inside the requested files. The agent should not expand the task, add packages, touch unrelated modules, expose secrets in logs, or claim a result before checking it.

That boundary is easy to ask for once.

It is better to make it part of the project.

Solution

Lockstep Skill gives the agent a strict workflow:

1. Plan the task before editing.
2. Lock the file scope.
3. Make the smallest safe change.
4. Redact sensitive data from logs.
5. Run a relevant check before claiming success.
6. Report the diff clearly.
7. Stop when approval is required.

Same project, same rules, same final report.

Supported Agents

• Codex
• Claude Code
• Cursor

Codex and Claude Code use Lockstep Skill as a skill.

Cursor uses it as a project rule.

Manual Install

Codex

Copy these into your project:

adapters/codex/AGENTS.md
adapters/codex/.agents/skills/lockstep-skill

Claude Code

Copy these into your project:

adapters/claude/CLAUDE.md
adapters/claude/.claude/skills/lockstep-skill

Cursor

Copy this into your project:

adapters/cursor/.cursor/rules/lockstep-skill.mdc

Usage

Codex:

Use the lockstep-skill skill before editing code.

Claude Code:

Use Lockstep Skill before editing code.

Cursor:

Follow the Lockstep Skill rule before editing code.

What It Enforces

• Plan First: state the exact task, files to inspect, expected edits, commands, and likely risks before editing.
• Scope Lock: only edit files listed in the plan unless the user approves a new file.
• Minimal Change: avoid unrelated refactors, renames, dependencies, architecture changes, broad formatting, and side fixes.
• Secret Redaction: redact tokens, API keys, passwords, connection strings, private keys, emails, and IP addresses from logs.
• Prove Before Claim: run a test, build, lint, typecheck, or clear manual verification before saying the work is fixed or complete.
• Diff Report: finish with files changed, why each file changed, commands run, result, remaining risk, and whether anything outside scope changed.
• Stop Conditions: ask before deleting files, migrations, new dependencies, auth changes, billing changes, secrets changes, production config changes, files outside scope, or continuing after unrelated test failures.

Examples

Bad change:

cat examples/bad-change.md

Good change:

cat examples/good-change.md

Copyable prompts:

cat examples/fix-bug-request.md
cat examples/refactor-request.md

Development

Run from this directory:

python3 scripts/validate.py
python3 -m unittest discover -s tests

The validator checks required files, adapter content, skill frontmatter, banned phrases, UTF-8 readability, Python comments, README usage, examples, and dependency manifests.

Scope

Lockstep Skill is not a sandbox, policy engine, code reviewer, or security scanner.

It does one narrow job:

Make the agent state the plan, stay inside scope, verify the work, and report what changed.

Status

Initial rule pack.

This version is manual by design. Copy the adapter files into a project and use the workflow before code edits.

About

Created by @gqnxx.

Regards, The CTO.