--- name: open_source_reuse_assembly description: Build a feature by reusing open source parts on purpose: split the goal into parts, find candidate code for each part, check each candidate licence and project activity with a bundled checker, take only the needed pieces as a dependency, a vendored copy, a snippet, or a clean reimplementation, and tag every piece with its source in a provenance map that ships with the code. Use when building a feature from existing open source, copying code from a repo, vendoring a library, evaluating a snippet found online, or auditing where the third party code in a feature actually came from. --- # Open Source Reuse Assembly ## Purpose Build features out of open source parts without inheriting mystery code. Every reused piece gets checked before it is taken, for its licence and for whether its project is still alive, and every piece carries its source, version, and licence in a provenance map that stays with the code. This skill ships the check as a tool, not as advice alone. `bin/reuse_check.py` reads a manifest of candidate pieces and returns a verdict per piece: TAKE, TAKE_WITH_NOTICES, REVIEW, or BLOCK, plus the obligations each licence creates and a generated provenance map. For the full licence and activity tables, read `references/license-and-activity-matrix.md`. For one feature built start to finish, read `references/worked-assembly.md`. This is triage and process, not legal advice. Close licence calls go to a human approver, with the facts written down. ## Workflow 1. **Split the goal into parts before searching for code.** Write each part as a job with an input and an output, small enough that one upstream project could fill it. Mark each part build, reuse, or cut. Cutting a part is a valid result, and a part the standard library already fills needs no candidate at all. Searching first and splitting later is how a whole framework gets taken to fill a 40 line job. 2. **Name the frame.** Write down the distribution model (internal, saas, proprietary-binary, oss-distribution, embedded), the product outbound licence, and whether users reach the feature over a network. No licence verdict exists without this frame. Code that is fine in an internal tool can block a shipped binary, and network use is the trigger for AGPL licences. 3. **Gather candidates, one manifest row per candidate.** Use `references/example-manifest.json` as the shape. For each candidate record, from the upstream repo itself: source URL, SPDX licence expression read from its LICENSE file, version or commit you would pin, copyright holder, last push date, archived flag, and whether you plan to modify it. Fill activity fields from the GitHub REST API (`archived`, `pushed_at`, `license.spdx_id`) or from deps.dev, which also gives the licence per package version and OpenSSF Scorecard data. A registry field or a README badge is a claim. The licence in the repo is the source. 4. **Run the bundled checker and obey the verdicts.** ``` python3 bin/reuse_check.py manifest.json --distribution saas python3 bin/reuse_check.py manifest.json --distribution proprietary-binary --json python3 bin/reuse_check.py manifest.json --distribution saas --as-of 2026-10-29 --provenance-md PROVENANCE.md ``` Add `--online` when manifest rows carry a `repo: "owner/name"` field and you want missing licence, archive, and activity fields filled from the GitHub API. The checker exits with code 1 while any piece is BLOCK. That is deliberate: a blocked assembly does not proceed by accident. Activity cutoffs at 180, 365, and 730 days are policy defaults in the tool, stated as such, not standards. 5. **Resolve every BLOCK and REVIEW before taking anything.** The remediation ladder, in order of preference: pick a different candidate for the part; take the same project at a different version under a different licence, after reading both licences; change the mode, for example vendor a dormant piece and own it instead of depending on it live, or reimplement the idea and copy no code; buy a commercial licence if the project offers one; accept the copyleft and plan the source offer it requires; or cut the part. A REVIEW passes only when a named person writes the reasoning in the provenance map. A dormant snippet that ships with tests and a named owner is a sound REVIEW pass. Hope is not a pass. 6. **Choose the take mode per piece, and take only what the part needs.** - depend: add the package, pinned, through the package manager. Needs the strongest activity signal, because you inherit the upstream release cadence. - vendor: copy the source of one pinned version into a named folder in your repo. Copy its tests too. You own updates from that day, so budget a scheduled check for upstream security fixes. - snippet: copy the smallest unit that fills the part, one function or one file, with its tests adapted to your suite. Provenance matters most here, because a snippet is the easiest piece to lose track of. - reimplement: copy no code, comments, or assets. Write your own from the idea or the public interface. Record that you did, and what you read while doing it. Never take a whole repo to fill one part. Extra code is extra licence surface, extra bugs, and extra provenance rows nobody checked. 7. **Tag every copied piece at copy time.** Each vendored or snippet file gets a header in its language comment style, following the REUSE specification: ``` SPDX-FileCopyrightText: SPDX-License-Identifier: Source: at Changes: ``` Put the full licence text of every shipped piece in `LICENSES/` at the repo root, one file per SPDX identifier, matching the REUSE layout. Files that cannot hold comments get an adjacent `.license` file with the same header. Tagging later does not happen. Tagging at copy time takes one minute. 8. **Commit the provenance map with the code.** Start from the checker output or `references/provenance-map-template.md`. One row per piece, including candidates you rejected and parts you cut, with the reason. Fill the obligations checklist: notices file rebuilt, NOTICE content carried, change notices on modified files, source offers live where a copyleft piece requires them. The map and the code change in the same commit, so the two cannot drift apart silently. 9. **Write the glue yourself and test the seams.** Your own code stays thin: it loads input, calls each reused piece at a clear boundary, and handles its errors. Test each seam with the cases that break reuse in practice: hostile input shapes, a dependency that fails once and then succeeds, an upstream function that returns an empty or null result. A part that passed its own upstream tests can still fail at your boundary. 10. **Keep the assembly true over time.** Re-run the checker on every version bump of a reused piece, because a bump can change the licence without changing the API. On a set schedule, check vendored and snippet rows against upstream for security fixes, and log each check in the map update log. When a piece is removed, keep its row, mark it removed with a date, and only drop its licence text once the code is gone from every shipped version. ## Output Contract Deliver, every time: - The parts list: each part, its input and output, and its build, reuse, or cut call. - The frame: distribution model, outbound licence, and network exposure. - The checker output for the manifest, with every BLOCK and REVIEW and the decision that resolved it, naming who decided. - The provenance map, committed with the code: one row per piece with mode, source, pin, SPDX expression, copyright holder, changes, and verdict, plus rows for rejected candidates. - The notices checklist, each item done or named as outstanding with an owner. - The seam tests and their results. - For reimplement rows, a statement of what was read and confirmation that no code, comments, or assets crossed over. ## Operating Rules - This skill gives triage, not a legal opinion. Say so in the provenance map, and send close calls to a human approver instead of resolving them by confidence. - No licence file in the upstream repo means no clear right to reuse. A public repo is not public domain. BLOCK until the licence is identified from the repo itself or the author clarifies it in writing. - Never strip, shorten, or rename away an upstream header, copyright notice, or licence text to make copied code look local. Provenance is part of the deliverable, not paperwork after it. - Never guess a licence, a version, a date, or a copyright holder from a project name or a search result. Read each one from the repo or the package page you are actually taking from, on the day you take it. - Activity is a signal, not a character judgment. A finished, stable project with no recent pushes can be a sound take in vendor or snippet mode. An active project with a licence that blocks your distribution is still a BLOCK. - An archived project taken as a live dependency is a block in the checker for a reason: nobody is coming to fix it, and the dependency hides that fact. Vendor it and own it, pick another piece, or get a written waiver. - Keep the snippet small enough to test and to rewrite. If a snippet needs its neighbours, it is a vendor piece, and it gets the vendor treatment. - Write every report this skill produces in plain, short sentences with exact licence names. No sales language, no filler.