agentleFS
KemetraKemetra/Seshat-BI/.claude/skills/showcase-build/SKILL.md

showcase-build

Skill2 starsChanged 4 months agoApache-2.0View on GitHub

Compose a shareable, disclosure-safe, OFFLINE proof bundle of Seshat BI's committed readiness truth -- stages, evidence, blockers, approvals, next actions, metric lineage, a truthful badge/project card, and a four-category disclosure manifest -- for a maintainer or analyst to hand to a reviewer, stakeholder, or prospective contributor. Use when someone asks for a "shareable proof", a "showcase bundle", a "project card", or "something I can send to show what Seshat has governed here". This is a Product Module, artifact-writing: it READS the shipped Explorer projection (`build_explorer_projection`), the Passport (`seshat.passport`), and the disclosure scanner (`seshat.disclosure.scan_disclosure`), composes ONE offline HTML bundle, and STOPS. It recomputes NO readiness, defines NO new evidence schema, invents NO meaning, and grants NO approval. It is fail-closed: a disclosure finding over the FULL composed body blocks generation and writes nothing. Generation is local-only (`.seshat-output/`); publishing the bundle anywhere is a separate, explicit human action this skill never performs.

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 7 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    MUST NOT recompute readiness, define a new evidence schema, or invent a new Explorer/Passport (FR-001/FR-002) -- it renders the existing …

    line 85
  2. Very specific:

    MUST NOT show any stage as pass without inspectable evidence (FR-003).

    line 87
  3. Very specific:

    MUST NOT write outside the contained .seshat-output/ root (FR-006).

    line 88
  4. Distinctive:

    MUST NOT publish, upload, track users, or call any external network/API (FR-007/FR-008) -- every asset is inlined or a data URI.

    line 89
  5. Distinctive:

    MUST NOT grant or imply any approval or publish sign-off (FR-011).

    line 91
  6. Distinctive:

    MUST NOT express a percentage, grade, or any other fabricated confidence number anywhere in the badge, card, or manifest (FR-013, FR-026.

    line 92
  7. Very specific:

    MUST NOT modify src/seshat/explorer/assets/explorer.css / explorer.js, or any source readiness artifact (FR-025).

    line 95
  8. Distinctive:

    MUST NOT add a new top-level CLI verb (FR-005.

    line 97
  9. Distinctive:

    Composes, never invents: Every fact in the bundle traces to the reused Explorer projection or a supplied Passport snapshot.

    line 115
  10. Distinctive:

    Four-category manifest, no silent drops: Every composed item lands under exactly one of included / unavailable / omitted / redacted, each …

    line 132
  11. Very specific:

    Generic: No worked-example specifics baked in.

    line 144
  12. Very specific:

    Disclosure gate: If bundle["disclosure"]["status"] != "pass": STOP fail-closed.

    line 161
  13. Very specific:

    Resolve the output path: Call seshat.cli.guards.resolve_local_output(root, output).

    line 164
  14. Very specific:

    Render and write: Call seshat.showcase.build.render_showcase_html(bundle, repo=root, rtl=...) and write the result to the resolved path.

    line 167

≈ “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

showcase-build

  • Roadmap feature / spec: specs/127-showcase-build/ (Shareable Seshat Proof / Showcase Bundle).
  • Authority category: Product Module / artifact-writing (docs/architecture/product-modules.md).
  • Delivery shape: a read-only skill over a reusable library function (src/seshat/showcase/build.py), per the ratified Option B decision (docs/roadmap/decisions/cli-verbs-vs-skill-driven.md, 2026-07-07). No new top-level CLI verb is added -- seshat.cli._DISPATCH has no showcase key, and importing seshat.showcase adds no network/driver import (mirrors the B1/B3 lazy-import guard).

A "shareable proof" is a single offline folder that answers "what has Seshat governed here, and can I trust it?" -- the readiness spine, the evidence, the blockers, the approvals, and the metric lineage together, a truthful badge (never a fabricated score), and a disclosure manifest stating exactly what is included, redacted, omitted, and unavailable. This skill is the COMPOSER: it fills the bundle from surfaces that already ship (the Explorer projection, the Passport, the disclosure scanner); it originates no readiness truth of its own.

Module contract (the filled F024 declaration)

  • Authority category: Product Module
  • Capability level: artifact-writing (exactly one)
  • Product layer: 6 (delivery/handoff rendering, sibling of the F013 handoff pack and the F026/F028 read-only lenses)
  • Owner: the analyst or maintainer requesting the proof
  • Status: Authored

What it does (one line)

Composes the already-committed readiness projection, an evidence-derived badge, and a four-category disclosure manifest into one offline HTML bundle, running the fail-closed disclosure scan over the FULL composed body before ever writing a file.

Core Authority it READS

  • seshat.explorer.build.build_explorer_projection -- stages, evidence states (available / missing / deferred), blockers, approvals, next actions, metric lineage, and input-defect entries.
  • seshat.passport (verify_passport) -- ONLY when two snapshot paths are supplied, to compute the optional before/after section.
  • seshat.disclosure.scan_disclosure -- the shared fail-closed scanner, run over the full composed bundle body (not merely the base projection).
  • seshat.cli.guards.resolve_local_output -- the contained-output guard.

Derived evidence it WRITES

  • One offline HTML file (default showcase/index.html) under the contained .seshat-output/ root, plus any inlined/embedded sidecar content (nothing external is ever referenced).

Approved step it EXECUTES

  • none. It composes and writes ONE local file, then STOPS. It runs no seshat check / retail validate of its own, opens no database, and calls no Power BI execution adapter.

Forbidden operations

  • MUST NOT recompute readiness, define a new evidence schema, or invent a new Explorer/Passport (FR-001/FR-002) -- it renders the existing ones.
  • MUST NOT show any stage as pass without inspectable evidence (FR-003).
  • MUST NOT write outside the contained .seshat-output/ root (FR-006).
  • MUST NOT publish, upload, track users, or call any external network/API (FR-007/FR-008) -- every asset is inlined or a data URI.
  • MUST NOT grant or imply any approval or publish sign-off (FR-011).
  • MUST NOT express a percentage, grade, or any other fabricated confidence number anywhere in the badge, card, or manifest (FR-013, FR-026; hard rule #9).
  • MUST NOT modify src/seshat/explorer/assets/explorer.css / explorer.js, or any source readiness artifact (FR-025).
  • MUST NOT add a new top-level CLI verb (FR-005; ratified Option B).

How it handles a missing or unsafe input

  • A missing artifact renders as missing; a malformed readiness file renders as an input defect; a deferred live check renders as unavailable -- never as a pass (FR-003; Principle V, stop-and-ask, never invent).
  • A live disclosure finding (secret, DSN, PII value, or a residual absolute path that survives portability normalization) in the FULL composed body BLOCKS generation fail-closed: no partial or redacted file is written; the findings are printed (FR-009/FR-010).
  • Two Passport snapshots that are not comparable (different scope, different schema_version, or fewer than two supplied) omit the before/after section gracefully with a truthful note -- never a fabricated delta (FR-020/FR-021).

Scope boundary (read first)

  • Composes, never invents. Every fact in the bundle traces to the reused Explorer projection or a supplied Passport snapshot. A missing artifact is missing; a deferred live check is unavailable; a malformed file is an input defect. Nothing is inferred into a pass.
  • Read-only over every source. Generating or browsing the bundle never modifies a readiness status file, a database, or a Power BI model. After a run, git status shows only new files under .seshat-output/ (typically git-ignored).
  • Fail-closed disclosure, full body. The scan runs over tables, enriched lineage, approval receipts, the badge, the manifest, and any before/after content -- INCLUDING user-supplied snapshot content the base projection never saw. A blocking finding writes nothing.
  • No fake confidence, ever. The badge states the highest CONTIGUOUS pass stage and the passed-stage count (e.g. "3/7 stages ready -- Gold: blocked"). It never states a percentage, a grade, or an invented score (hard rule #9). When no stage has passed, it states the truthful onboarding status, never an empty or celebratory claim.
  • Four-category manifest, no silent drops. Every composed item lands under exactly one of included / unavailable / omitted / redacted, each with a locator. "Redacted" names ONLY the composer's own by-design portability normalizations (an absolute path reduced to repo-relative, a private/internal URL stripped) -- never the suppression of a disclosure finding (those block, they are not redacted).
  • Own shell, untouched Explorer. The bundle renders showcase.css / showcase.js (its own assets); it never reads or edits explorer.css / explorer.js.
  • Generation is not publication. Producing the bundle never grants a publish approval or PII sign-off. Sharing the file anywhere is a separate, explicit human action outside this skill.
  • Generic. No worked-example specifics baked in; retail_store_sales (docs/worked-examples/retail-store-sales.md) is a cited filled instance, never hard-coded (Principle VII). ASCII + UTF-8 no BOM for any text this skill's caller writes back into the repo (the skill itself only writes under .seshat-output/, which is not tracked).

Procedure (numbered; do not reorder)

  1. Resolve inputs. Workspace root (default .); optional output path (must resolve inside .seshat-output/); optional rtl render mode; optional two Passport snapshot file paths for the before/after section.
  2. Compose. Call seshat.showcase.build.build_showcase_bundle(root, snapshots=...). This reads the Explorer projection, derives the badge and manifest, applies portability normalization (absolute path -> repo-relative; private URL stripped -- each listed under the manifest's redacted category), and computes the optional comparison if two snapshots were supplied.
  3. Disclosure gate. If bundle["disclosure"]["status"] != "pass": STOP fail-closed. Print every finding (rule, locator, message). Write NOTHING. This is not a partial-write case -- no file appears.
  4. Resolve the output path. Call seshat.cli.guards.resolve_local_output(root, output). If the path escapes .seshat-output/, refuse and write nothing (FR-006).
  5. Render and write. Call seshat.showcase.build.render_showcase_html(bundle, repo=root, rtl=...) and write the result to the resolved path.
  6. Report and STOP. Print the written path and this reminder verbatim: "This is a local offline snapshot generated from committed evidence only. Publishing it anywhere is a separate, explicit human action." Do not publish, upload, or record any approval. Any judgment call surfaced in the bundle (an unresolved assumption, a blocked gate, a retracted approval) is a stop-and-ask for the named human (Principle V) -- this skill only renders it.

Refusals

  • Uncontained output path -- refuse before writing; nothing is written outside .seshat-output/.
  • Blocking disclosure finding -- refuse fail-closed; print the findings; write nothing (no partial/redacted bundle).
  • A request to publish, upload, or otherwise distribute the bundle -- out of scope. This skill only writes a local file; publishing is the named human's separate, explicit action.
  • A request for a numeric confidence/health/percent-ready score -- refuse; the badge/manifest already state the truthful stage-and-count summary (hard rule #9).

Honest-state rules (never invent, never silently resolve)

SituationWhat the skill does
No table has reached any stage (or the workspace has no onboarded table)badge states the truthful onboarding status; never an empty or celebratory claim
A readiness file is malformedrendered as an input defect in the table panel AND listed under the manifest's omitted category
A secret / DSN / PII value / residual absolute path is present anywhere in the composed bodygeneration blocks fail-closed; findings printed; nothing written
A metric contract is unreadablerendered as an input-defect lineage node, never a valid metric
Two snapshots share scope but one is malformed or a different schematreated as not comparable; the before/after section is omitted with a note
Only one snapshot (or none) is suppliedno before/after section; no fabricated delta

See also

  • The spec: specs/127-showcase-build/spec.md, plan.md, data-model.md, contracts/showcase-contract.md, quickstart.md, research.md.
  • The library it composes: src/seshat/showcase/build.py, src/seshat/showcase/badge.py, src/seshat/showcase/manifest.py, src/seshat/showcase/compare.py.
  • The reused shipped surfaces: src/seshat/explorer/build.py, src/seshat/passport.py, src/seshat/disclosure.py, src/seshat/cli/guards.py.
  • The nearest sibling read-only lenses: .claude/skills/readiness-viewer/ (stage matrix), .claude/skills/evidence-pack-generator/ (late-stage pack) -- this skill's delta is that it renders an OFFLINE, SHAREABLE, disclosure-scanned bundle with a badge and a manifest, not an in-repo markdown artifact.
  • The Option B ratification this delivery shape applies: docs/roadmap/decisions/cli-verbs-vs-skill-driven.md.
  • A cited filled worked example: docs/worked-examples/retail-store-sales.md.

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.