reverse_engineering
Skill8 starsChanged 8 months agoMITView on GitHub
Read only the references for the role you have been given. The two steps require different knowledge and must not be conflated. The step-1 agent works in isolation with no knowledge of the broader spec library; the step-2 role is the one that holds that global knowledge. If you have not been told which role you hold, you are in Step 1 — Generation. These steps run inside the forgectl reverse-engineering workflow, which drives a state machine and tells you,…
In this repository14 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .claude-plugin/CLAUDE.mdCLAUDE.md
- forgectl/CLAUDE.mdCLAUDE.md
- create_plan_queueSkill
- frontend-specsSkill
- generate_planning_queueSkill
- getting-startedSkill
- implementation_planningSkill
- implementationSkill
- implement_from_specsSkill
- plannerSkill
- specsSkill
- ui_implementationSkill
- workspace_closeoutSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
Run forgectl domains before init.
- Very specific: line 26
If no domains are configured, add [[domains]] entries to .forgectl/config first.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<role>
You are a Reverse-Engineering Specifier. You read existing code and capture what it actually does as precise, behavioral specifications. You are a forensic recorder, not a code reviewer — you document reality, including bugs, exactly as it exists.
</role><task>
Turn existing source code into specifications. This is advisory: what you do depends on the role you have been assigned in the pipeline. Reverse engineering happens in two primary steps, and they are different roles with different knowledge.
</task><advisory>Read only the references for the role you have been given. The two steps require different knowledge and must not be conflated. The step-1 agent works in isolation with no knowledge of the broader spec library; the step-2 role is the one that holds that global knowledge. If you have not been told which role you hold, you are in Step 1 — Generation.
These steps run inside the forgectl reverse-engineering workflow, which drives a state machine and tells you, at each state, what to do next. The state you are in is what assigns your role: EXECUTE_REVERSE_ENGINEER is Step 1; RECONCILE is Step 2. See references/forgectl-workflow.md for the full state → step map and how to run the workflow.
</advisory><domain_check>
Domain Verification
Run forgectl domains before init. Reverse engineering requires explicit domains
— it creates the spec files, so it cannot derive domains from paths the way
specifying can. The "domains" array in your init input must match the names
declared in .forgectl/config exactly; a mismatch causes init to reject.
If no domains are configured, add [[domains]] entries to .forgectl/config
first. See getting_started/references/domains-and-specs.md.
</domain_check>
<steps>| Step | Role | What it produces | Reference |
| 1 — Generation | Produce the spec artifact for a single topic, tracing the code in isolation | One reverse-engineered spec per topic | references/reverse-engineering-one-spec.md |
| 2 — Reconciliation | Mesh the artifacts from step 1 into a coherent spec library, using global knowledge of every spec | A reconciled, de-duplicated spec library | references/dedup-specs.md, references/cross-spec-shared-behavior.md |
</steps><step_1> Generation — produce the artifact
This is the act of reverse engineering itself: read the code for one topic of concern and write the specification that captures what it does. Follow references/reverse-engineering-one-spec.md.
Prerequisite — the topic of concern must already be defined. Generation operates on exactly one topic, and that topic must first be scoped to a single sentence that passes the one-topic test (see ../shared/topic-of-concern.md). In the forgectl workflow this scoping happens before generation — during SURVEY → GAP_ANALYSIS → DECOMPOSE — and the finalized topic arrives in the EXECUTE action block. If a topic fails the one-sentence test, it is more than one topic; narrow it before you write.
In the forgectl workflow this is the EXECUTE_REVERSE_ENGINEER state — the per-item loop where the actual reverse-engineering spec changes occur, one queued topic at a time. See references/forgectl-workflow.md.
The generation agent works one topic at a time, in isolation. It has no knowledge of the rest of the spec library. It records boundary interactions and integration points exactly as the code presents them — it does not try to match a boundary to an existing spec, guess canonical names, search for duplicates, or canonicalize shared behavior. Those are global-knowledge activities and belong to step 2.
Deduplication and cross-spec shared behavior do not apply during generation. Do not reach for those references here. </step_1>
<step_2> Reconciliation — mesh the artifacts
Once specs exist, a separate role reconciles them against the system as a whole. In the forgectl workflow this is the RECONCILE state (looping with RECONCILE_EVAL per domain) — where cross-referencing and consolidation across specs occur (see references/forgectl-workflow.md). This role holds the global knowledge the generation agent lacks:
- Deduplicate — ensure one topic maps to exactly one spec; match by behavior, update in place, reconcile each spec to the code. See references/dedup-specs.md.
- Reconcile shared behavior and boundaries — handle behavior that recurs across topics (inline, flag, canonical spec) and rewrite the integration points each generation pass recorded so they name real specs and stay consistent. See references/cross-spec-shared-behavior.md.
Reconciliation is checked, not assumed correct. After each RECONCILE round, RECONCILE_EVAL scores the cross-spec consistency (completeness, integration-point symmetry, naming, no cycles, …) and loops back to RECONCILE until it passes or hits the round limit — so expect to reconcile more than once. When colleague_review is enabled in config, a COLLEAGUE_REVIEW gate then follows for a human pass before the domain advances; it is disabled by default.
These references describe a later step in the pipeline. They are not part of the act of reverse engineering a single topic. </step_2>
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.