# Goal Lock > Use for non-trivial repository work where Codex must stay scoped, resumable, and verifiable: implementation, audits, repairs, refactors, roadmaps, plans, multi-file changes, long autonomous runs, compaction recovery, and work likely to reveal follow-up issues. Skip tiny chat-only answers, simple one-command checks, and obvious one-line edits unless the user explicitly asks for goal-lock. - Skill: `lordslayer247/goal-lock` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add lordslayer247/goal-lock` - Raw SKILL.md: https://api.skillmd.com/api/skills/lordslayer247/goal-lock/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: lordslayer247 (https://skillmd.com/u/lordslayer247) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/lordslayer247/goal-lock --- # Goal Lock Use this skill as the task control layer for non-trivial repository work. It keeps each run isolated in its own task folder, grounded in a spec, resumable after context compaction, and honest about verification, issues, and blockers. Allowed `task.json` statuses are only: - `in_progress` - `completed` - `blocked` - `pruned` Do not write `complete`, `done`, `paused`, or other status variants. ## Start 1. Inspect the relevant repository surface before making commitments. 2. Classify the run: - `short`: one bounded outcome, likely finishable in one session. - `long`: phased work, broad architecture, many subsystems, high risk, or likely compaction. 3. Create a task folder with the scaffolder: - `python3 .agents/skills/goal-lock/scripts/scaffold_goal_task.py --kind short --title "" --root ` - `python3 .agents/skills/goal-lock/scripts/scaffold_goal_task.py --kind long --title "" --root ` 4. Use the printed folder path as the task anchor for the rest of the run. 5. If the active collaboration mode forbids file edits, do not scaffold; keep the same structure in the response or plan instead. Task folders live under: - `docs/agent-work/shorttasks//` - `docs/agent-work/longtasks//` ## Required Spec Step Every goal-lock run starts with the `spec-refiner` workflow: - Short tasks: write one repo-grounded `spec.md` before implementation. - Long tasks: write a repo-grounded top-level `spec.md` overview and `phased-plan.md` first, then refine each `phases/phase-XX-spec.md` immediately before implementing that phase. Specs must name verified codebase facts, success criteria, assumptions, and developer handoff notes. Do not invent product or repository facts. ## Task Folder Contract Every task folder contains: - `task.json`: id, kind, status, title, timestamps, and current phase. - `spec.md`: repo-grounded implementation spec for short tasks or overview spec for long tasks. - `logger.md`: chronological progress ledger, discoveries, decisions, and compaction notes. - `implementation.md`: touched areas, intended edits, actual edits, and deviations. - `verification.md`: commands or manual checks, results, skipped checks, and evidence. - `audit.md`: self-audit for short tasks; optional subagent audit notes when used. - `issues-and-blockers.md`: discovered issues, blockers, danger level, owner, and resolution status. Long task folders additionally contain: - `phased-plan.md`: full implementation roadmap. - `phases/phase-XX-spec.md`: just-in-time phase specs. - `phases/phase-XX-log.md`: phase execution notes. - `subagent-audit-plan-compliance.md`: independent audit against user goal, plan, and specs. - `subagent-audit-code-health.md`: independent audit for regressions, duplication, dead code, missed verification, and architectural drift. ## Live Loop Keep `logger.md` and `task.json` current: - after initial discovery and spec creation - after each milestone, phase, or major discovery - before risky or newly in-scope changes - after verification - before and after subagent audits - when resuming after compaction or context loss Before each new milestone or phase, run a drift check: - Does the next step still serve the original user goal? - Has scope expanded without an explicit reason? - Are unrelated files or systems being changed? - Does the plan still match discovered codebase facts? - Is the next step the smallest useful step? Stop and ask the user when a drift check fails, discovered facts contradict the plan, scope must expand materially, or high-risk/out-of-scope files or contracts must change. ## Resume After Compaction On resume: 1. Re-open the remembered task folder if the path survived context compaction. 2. If no path survived, run `python3 .agents/skills/goal-lock/scripts/resume_goal_task.py --root ` or scan `docs/agent-work/shorttasks/*/task.json` and `docs/agent-work/longtasks/*/task.json`. 3. Resume the newest task whose status is not `completed` or `pruned`; treat unknown status values as malformed until fixed. 4. If more than one plausible active task exists, ask the user which task to resume. 5. Read `task.json`, `logger.md`, the active spec or phase spec, `issues-and-blockers.md`, and `verification.md` before continuing. ## Audits And Blockers Short tasks require a written self-audit in `audit.md`. Use a subagent audit when the task is risky, surprising, multi-file, or user-visible enough that independent review is worth the overhead. Long tasks require two subagent audits before completion when subagent tooling is available: - plan/spec compliance audit - code health, regression, duplication, dead-code, and verification audit If subagents are unavailable, record the skipped audit and reason in the relevant audit file. Do not pretend an independent audit happened. For completed long tasks, do not leave placeholder top-level `audit.md` text behind. If the real completion audits live in `subagent-audit-plan-compliance.md` and `subagent-audit-code-health.md`, update `audit.md` to point to those files and summarize the result. Codex may fix small in-scope issues discovered while working. Ask for approval before fixing dangerous or out-of-scope issues involving security/auth, data deletion, migrations, billing, public APIs/contracts, broad refactors, or unrelated systems. Keep durable unresolved findings in `issues-and-blockers.md`; promote important unresolved items to existing repository audit or architecture issue docs when relevant. ## Verification And Completion Prefer targeted verification first. Broaden to larger tests, lint, build, or manual checks when the risk or touched surface warrants it. Before calling the task complete: - record exact verification commands or manual checks - state skipped or blocked verification honestly - summarize changed files and behavior - list remaining risks, issues, and blockers - update `task.json` status to `completed` or `blocked` - run `python3 .agents/skills/goal-lock/scripts/validate_goal_task.py ` and fix any contract errors For clean completed short tasks, prune the folder to `summary.md` plus `task.json`. Keep the full short-task folder when verification failed, unresolved blockers remain, or the task changed architecture. Never claim live, production, full-suite, or end-to-end verification unless it actually ran. Final responses for goal-lock work should include: - task folder path - final status - verification run - verification skipped or blocked - residual risks ## Helper Scripts - `scaffold_goal_task.py`: create standard short or long task folders. - `validate_goal_task.py`: validate status values, required files, scaffold placeholders, verification sections, blockers, and long-task audit records. - `resume_goal_task.py`: list active or malformed task folders. - `close_goal_task.py`: close a task as `completed`, `blocked`, or `pruned`; it refuses completed/pruned closeout when validation fails.