sureforge

SureForge

An instruction-only Agent Skill for complex work. It tells an AI agent to research before it asks, ask before it plans, plan before it builds, verify before it delivers, and to get an independent review before it calls anything done.

Version 1.0.0. MIT license. Maintained by Da7-Tech.

Why this exists

Agents fail in predictable ways on big tasks. They start building before the request is understood. They treat a skipped question as a yes. They check a sample and call it complete. They re-read their own work and call it a review. They run out of review rounds and ship anyway.

SureForge is the working procedure that grew out of dealing with exactly those failures, written down so an agent can follow it. The pattern behind it is simple: the time spent understanding, planning, and checking up front is far less than the time spent redoing work, patching it, and re-checking it by hand afterwards. Fewer do-overs means fewer tokens over the life of a task, less of your attention spent on review, and work that is right the first time far more often.

It is plain text: a short entry point plus reference files the agent loads when it needs them. There is no runtime, no hook, and no dependency. The agent follows it the way it follows any other skill.

Install

The skill is the skills/sureforge/ folder: one SKILL.md plus the reference files and templates it links to. Installing means putting a copy of that folder where your agent looks for skills. Nothing runs at install time and nothing runs afterwards; the agent reads the text when the skill is selected.

With the Skills CLI (Node.js 22.20 or newer), from your project:

npx skills add Da7-Tech/SureForge

The CLI asks which agents to install for and copies the folder into each one's skill directory. To skip the prompt, name the agents with the CLI's identifiers, for example:

npx skills add Da7-Tech/SureForge --agent claude-code --agent codex --agent cursor --agent devin --agent hermes-agent -y

Add -g to install at user level instead of in the current project. The CLI may write a skills-lock.json in your project; that file can contain local paths, so look at it before committing it. npx skills update refreshes installed skills and npx skills remove uninstalls them.

Manual install: copy the whole skills/sureforge/ folder, including LICENSE, references/, and assets/, into the directory your host reads. Copying only SKILL.md is not enough, because it links to the other files.

These are the directories the pinned Skills CLI and the hosts' own documentation used when this was checked (dates and details in platforms.md). Hosts change their paths; if a skill is not discovered, check the host's current documentation first.

To read the skill without installing anything, open SKILL.md. It is the same text the agent gets.

Use

Ask for it by name:

Use SureForge for this task. Research the important unknowns before you ask me anything, then give me a plan I can check before you build.

For high-stakes work, ask for full mode:

Use SureForge in full mode. Do not pass a gate without three verification methods of your own and three from an independent reviewer. If a reviewer or tool is missing, tell me instead of pretending.

Small tasks are meant to stay small. If you ask SureForge to fix a typo, the instructions call for fixing the typo and checking the diff, not for starting a research project.

How it works

Four phases, each ending in a gate that is READY, REPAIR, or BLOCKED:

1. Research and clarify. Read what is already there, research the unknowns that change the decision, look at the problem from three angles, then ask the questions that matter and offer alternatives. A skipped question is not an answer.
2. Plan. Map every acceptance criterion to a step, an inspection unit, and a way to verify it. Write down permissions, budgets, and stop conditions before touching anything.
3. Execute. One owner, dependency order, failing test before the fix where tests exist. If execution shows the plan was wrong, go back to the plan gate instead of patching.
4. Deliver. Freeze the candidate, inspect every agreed unit on that exact version, try the recipient's path (open it, install it, run it), and report what was verified, what was reused, and what was not checked.

Three tiers set how much of this runs:

Independent review means a reviewer that has not seen the author's reasoning, self-rating, or preferred verdict. It gets the artifact, the request, the contract, and the material it needs, and it picks its own methods. Every finding is investigated before anything is changed: confirmed, refuted with evidence, unresolved, duplicate, or out of scope. There are at most three review rounds per gate, and running out of rounds is a BLOCKED result, not a delivery.

When something is missing (no internet, no question tool, no reviewer, no renderer), the skill says so and uses a named fallback rather than pretending the check happened.

What is in this repository

• skills/sureforge/ is the skill: SKILL.md, seven reference files (the four phases, the review protocol, a verification catalog, dated platform notes), and templates for the reviewer brief, critic brief, task ledger, and coverage ledger. This folder is all a user needs.
• evals/ is the evaluation kit: thirteen failure scenarios with pass/fail oracles, twenty activation prompts with expected tiers, five synthetic benchmark tasks with hidden grading criteria, a three-arm study protocol, an abstract gate model, and a strict aggregator for run records.
• review/ holds the review contract the skill was built against and a neutral intake for fresh-context reviewers.
• scripts/ and tests/ check the package itself: inventory, metadata, links, licenses, privacy patterns, archive integrity, and installation. See Verification for the commands.
• CONTRIBUTING, SECURITY, and the code of conduct cover how to propose changes, how to report text that could steer an agent badly, and how people are expected to treat each other here.

How it has been tested

Three kinds of evidence, kept apart because they prove different things.

Mechanical checks you can rerun from this repository: the unit tests (see Verification) pass on Python 3.11 and 3.14, and every fault listed in scripts/mutation_audit.py is caught by them when seeded into a temporary copy. The skill passes the reference skills-ref validator at the commit pinned in review/toolchain.json.

Installation checks, run locally with Skills CLI 1.5.23 in an isolated project: copies installed for the five CLI targets Claude Code, Cursor, Codex, Devin, and Hermes (four directories, since Cursor and Codex share one) were byte-id