format-assembler-discipline

Adds a new output-format assembler over an existing shared intermediate representation in a CLI tool.

Updated Jul 8, 2026
One-click install
npx skills add https://github.com/NarenKarthikBM/specseyal --skill format-assembler-discipline-narenkarthikbm
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: format-assembler-discipline
Source: https://github.com/NarenKarthikBM/specseyal/tree/main/.claude/skills/format-assembler-discipline
Command: npx skills add https://github.com/NarenKarthikBM/specseyal --skill format-assembler-discipline-narenkarthikbm

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a CLI tool gains a second output format (for example a stdlib-only HTML emitter beside a python-pptx assembler), ad-hoc implementations fork the data model, duplicate stamp logic, and corrupt prior outputs on failed writes. This Skill enforces the architectural discipline that keeps multiple format assemblers consistent over one shared intermediate representation. ## Core Features & Use Cases - Shared IR consumption: Requires the new assembler to read the existing format-agnostic intermediate representation, extending the IR itself rather than creating a format-specific side channel. - Single provenance builder: Routes every assembler's stamp (source path plus sha256 content hash) through one shared builder so implementations cannot drift apart. - Explicit format discrimination and atomic writes: Mandates a named format field on the shared result dataclass and atomic output via temporary-file-then-os.replace, so interrupted writes never destroy prior good output. - Use Case: Adding a zero-dependency HTML deck assembler next to an existing python-pptx one, with disclosure and exit codes keyed by (item, format) so a partial success in one format is never reported as a full success or failure. ## Quick Start Add a second output-format assembler over the existing shared IR in this CLI tool, following the format-assembler-discipline rules for stamps, atomic writes, and per-format results.

Frequently Asked Questions about format-assembler-discipline

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a second output format to a CLI tool that already has one assembler?

Build the new assembler over the same intermediate representation the existing one consumes, and extend the IR itself if data is missing rather than creating a format-specific side channel. Route stamps through the existing shared builder and add an explicit format field to the shared result dataclass.

How should provenance stamps be computed when multiple format assemblers exist?

Compute the stamp (source path plus a sha256 hash of the source bytes) once, in a single shared builder function that every assembler calls. A second hand-rolled hash or stamp string is a second place the implementations can silently drift apart.

Why should assembler output be written with os.replace instead of writing directly?

Writing to a temporary file in the target directory and then moving it with os.replace makes the write atomic. A failed or interrupted run leaves any prior good output at the final path completely untouched, which direct writes and pre-deletion cannot guarantee.

How should exit codes and disclosure be aggregated for multi-format output?

Key disclosure and exit-code aggregation by (item, format), never by item alone. Collapsing two formats' outcomes into one per-item verdict can turn a real partial success into a reported full success or full failure, hiding information the disclosure exists to surface.

Can a stdlib-only assembler import the toolchain another assembler uses?

No. If the new format's guarantee is zero external dependencies, importing a sibling assembler's toolchain at module scope or unconditionally breaks that guarantee the moment the import runs. Each format must preserve its own dependency contract.