Ls Github Publishing Workflow

GitHub publishing workflow (framework baseline)

Purpose: Follow a consistent, research-backed workflow to get a repo ready for public GitHub publication: documentation layout, licensing, scrub for sensitive or context-specific content, and a repeatable checklist.

Documentation and structure (best practice)

• README: Clear value proposition near the top; install instructions; layout of deployed content; optional contents table or TOC for navigation. Section headings that work as anchors. Consider light visual cues (e.g. section icons) for scanability; keep one H1 per doc.
• SECURITY.md: How to report vulnerabilities (private advisory or contact). Link from repo Security tab. State scope (this repo only; third-party tools out of scope).
• CONTRIBUTING.md: How to open Issues, Discussions, and PRs; repo layout; that contributions are licensed under the project license. Point to LICENSE.
• LICENSE: Chosen license (e.g. MIT) with correct copyright holder. Single source for "can use, modify, distribute" terms.
• Framework README: If the repo contains a framework subfolder, its README should describe the engine, tools, and docs and link to root README, SECURITY, CONTRIBUTING, and LICENSE.

Use relative links and consistent heading levels. Avoid PII and machine-specific paths in all of the above.

Licensing and copyright

• Copyright: Attribute to the intended owner (e.g. company or author). Use a single line in LICENSE and, if desired, a short "License and copyright" section in README.
• MIT: Allows use, copy, modify, merge, publish, distribute, sublicense, and sell copies/derivatives, with copyright and permission notice preserved. See LICENSE for full text.
• Display: README and framework README should state "Copyright (c) YEAR Owner" and "Released under the MIT License" (or chosen license) with a link to LICENSE.

Author and contact (without exposing personal email)

• Author: Name and link to profile (e.g. GitHub). Do not embed a personal email in the repo if the goal is to avoid scraping and spam.
• Contact: Direct users to GitHub Issues or Discussions in the repo so they can reach you without publishing an email. Optionally link to a company or contact page.
• Co-authored-by: If the tooling adds a "Co-authored-by" trailer (e.g. from an IDE) and the maintainer does not want it in history, the commit-msg hook can strip that trailer before the commit is finalized.

Scrub before publishing (no PII or context-specific artifacts)

• No personal data: No real email, physical address, or phone in committed files except where explicitly intended for public contact.
• No secrets: No API keys, tokens, passwords, or credentials. No committed .env or secret files.
• No machine-specific paths: No hardcoded /home/username, /Users/name, C:\Users\..., or internal hostnames. Use placeholders or environment variables for paths.
• Clone and repo URLs: Default clone URL in install (or equivalent) must point to the public repo. Overridable via environment variable for forks. Issue/Discussion links in README must use the correct repo owner.
• Deploy artifacts: Any directory or file that is generated by deploy (e.g. a copy of docs under a different path) must be in .gitignore and must not be tracked. Remove from tracking if it was ever committed.

Run a quick scrub command (e.g. grep for password, secret, api_key, token, /home/, /Users/) and review matches before publishing.

Version and release

• VERSION: Set to the intended release version. README and any "Version" display must match (see ls-automatic-versioning skill).
• Versioning docs: If the project uses automatic versioning, document it (e.g. docs/VERSIONING.md) and link from README.

Repository settings (on GitHub)

LocalSetup release-documentation gate

Prepare and review the structured release record and affected public prose in the source checkout, then render and check the owned sections before canonical version and generated-document sync. Optional protected QC authoring can propose and independently review the candidate; trusted tooling applies accepted edits under the configured signing identity. The ordinary hosted release validates already committed source and does not run a model, create an unsigned bot commit, or push source.

publish.yml supports explicit release, repair, and qualify dispatch modes. After the accepted source passes main-branch checks, the maintainer creates and pushes a verified OpenPGP-signed annotated tag at that exact commit. release verifies the pre-existing tag and commit using the required public certificate, builds and checks artifacts, and creates a draft with --verify-tag. repair updates published notes from reviewed committed prose while preserving the published tag and assets. qualify prepares evidence without integration or release mutation. These modes do not grant authority to scheduled QC patrols.

Before publishing a completed draft, fetch its tag and run localsetup release-docs check --draft-tag v --expected-commit from that exact candidate. This compares rendered notes, tag identity, and the documented archive/checksum/SBOM asset names. It does not replace complete artifact, checksum, provenance, and license verification. Re-run if notes, source, or assets change. Direct administrative GitHub UI actions are outside workflow enforcement.

• Visibility: Set to Public when the checklist is done.
• Description and topics: Short description and topics for discoverability.
• Default branch: Align install/docs URLs with the default branch (e.g. main).
• Issues and Discussions: Enable if you want contact via GitHub.
• Security: Enable "Private vulnerability reporting" if desired; SECURITY.md should explain how to report.

Publishing Checklist Baseline

• Treat this section as the source checklist for the skill. If the target repo maintains a publishing checklist, create or update its repo-local docs/PUBLISHING_CHECKLIST.md from these same categories: documentation and structure, scrub (PII/secrets/paths/URLs/artifacts), version and release, and repository settings.
• Before going public, work through the checklist and optionally run the scrub command. When all items are checked, the repo is ready for public publishing.

Rule ownership

This skill owns GitHub publication readiness. Public docs can summarize publishing behavior, but release-prep agents should load this skill for the scrub checklist, repository settings, and documentation/public-boundary decisions.

• Use ls-automatic-versioning for version bump and sync behavior.
• Use ls-public-repo-identity for public identity and contact fields.
• Do not publish private maintenance state, generated local indexes, credentials, or machine paths.

Reference

• Checklist source: use Publishing Checklist Baseline in this skill unless the target repo has its own tracked checklist.
• Versioning: load ls-automatic-versioning when changing or explaining version behavior.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: CruxExperts
• Source: CruxExperts/localsetup
• License: MIT

Install and usage instructions live in the source repository linked above.