agentleFS
CRELLIA-S-LCRELLIA-S-L/srs-dd/.claude/skills/srs-arch-harvest/SKILL.md

srs-arch-harvest

Skill0 starsChanged 33 days agoMITView on GitHub

Recover an architecture from a project that already has one — for a codebase adopting the layer with an empty arch/, or one whose records describe a cut it has outgrown. Reads the code, and an architecture document where the project keeps one, and proposes element records, and the forms inside a part, in approved batches. Invoke when the user wants to recover, reconstruct, import or backfill the architecture of an existing project. For maintaining a cut that is already written down use srs-arch; for mining requirements out of code use srs-harvest.

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
  1. Very specific:

    Read first: srs-dd/arch.md, whole, in one call.

    line 10
  2. Very specific:

    Every record named to a person is cited at its first mention, as AGENTS.md asks: python3 srs-dd/tools/srs_arch.py --cite <ID>… for an …

    line 14

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- Copyright (c) 2026 CRELLIA S.L. — part of SRS-DD, distributed under the MIT License -->

Recovering an architecture from a project that has one

The format lives in srs-dd/arch.md and is not restated here. Read first: srs-dd/arch.md, whole, in one call.

The layer is installed and arch/00-elements.md is empty or describes less than the project is. This procedure turns what exists into records — always as proposals, never as decisions. Every record named to a person is cited at its first mention, as AGENTS.md asks: python3 srs-dd/tools/srs_arch.py --cite <ID>… for an element, python3 srs-dd/tools/srs_view.py --cite <ID>… for a requirement.

A project made of documents is out of scope. The readings here are written for code — the dependencies the checker computes from imports, the draft it offers over files — and a specification of documents gets no architecture layer at this stage.

Procedure

  1. Start from what the specification already answers. python3 srs-dd/tools/srs_arch.py --draft prints one candidate record per directory holding files no part carries, each with the files and the requirements that name them. That is a join, not a cut: it knows nothing about responsibility.
  2. Read what the project already says about itself, where it says anything: an architecture document, a README's layout section, a diagram's source. A claim it makes that the code contradicts is the code's, and the contradiction goes to the user — not into a record.
  3. One batch per candidate, in the order the draft prints them. For each, read the files themselves — the imports, what calls what, what each module is for — and then write the record as Naming a part in srs-dd/arch.md says: one sentence of responsibility with no "and" in it, the files, the obligations, the dependencies that are real, the interface it is reached by, and protects where the two or three it was cut to keep are clear.
  4. Judge the batch before showing it. Against the readings .claude/skills/srs-arch/SKILL.md carries: a part whose sentence needs an "and" is two, a part nobody can name is a directory rather than a part, and a part that protects nothing in particular is one to merge into its neighbour. Say which reading each record failed and what you did about it.
  5. Show the batch, then write it. The records go into arch/00-elements.md only after the maintainer has seen them — the whole batch, as it would be written, in the message that asks.
  6. Run the checker after every batch: python3 srs-dd/tools/srs_arch.py --no-write. The three readings it prints — a carrier no part claims, a realized requirement no part carries, a part answering to nothing — are the remaining work, and the dependency findings say where the cut you proposed disagrees with the imports.
  7. Repeat until no carrier is unclaimed and no realized requirement is uncarried. Then write the decision: why this cut and not the neighbouring one, in specs/adr/.

Recovering the forms inside a part

Only where the project is adopting that grain, and one part at a time: a part holding no form is silent, and a part holding one is held to every obligation it carries — so a batch covers one part whole or it leaves the project worse off than before.

  1. Take the part first. python3 srs-dd/tools/srs_arch.py --drivers E-NNN says what its obligations most constrain, which is what the forms have to answer for between them.
  2. Read what the code declares — the types, the operations they answer to, the state they own — and group them by the obligations they answer for rather than by file. This is the one place the code-first direction is the right one, and srs-dd/arch.md says so.
  3. Show the batch, then write it. The forms go into arch/20-shapes.md only after the maintainer has seen them, as a cut's batches are shown.
  4. Run the checker after every part. A built form naming a symbol nothing declares, a type no form claims, and an obligation no form answers for are the remaining work.

What this procedure does not do

  • It does not invent a part to tidy the tree: a part exists because something is responsible for something, and a directory is not a reason.
  • It does not touch specs/: a requirement never names an element, and a requirement that looks wrong while you read the code is srs-audit's business or srs-harvest's, not this one's.
  • It does not write the map: arch/90-map.md is generated; run the checker and commit what it wrote.
  • It does not run builds or tests (SRS-DD-ART-030 of the method); recovery is reading.
  • It does not flip a status for the maintainer: a part that is built says built because somebody read the files and agreed.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.