rust-cli

rust-cli is a document-first Skill package for building and maintaining Rust-based CLI Skills that follow the local constitution and shared runtime contract.

The package now operates as a staged skill family:

• the root SKILL.md is the router and shared contract
• stages/ contains the phase-specific stage skills
• instructions/ remains the canonical detailed execution surface
• every successful workflow closes through publish

Stage Skill Family

Stage	File	Purpose	Default next step
intake	stages/rust-cli-intake/SKILL.md	Classify the request, gather required inputs, and choose the earliest safe next stage.	description, extend, validate, or publish
description	stages/rust-cli-description/SKILL.md	Approve one authoritative description contract before scaffold, extend, validate, or publish surfaces change.	scaffold, extend, validate, or publish
scaffold	stages/rust-cli-scaffold/SKILL.md	Create a new Rust CLI Skill project from the templates using the approved description contract.	validate
extend	stages/rust-cli-extend/SKILL.md	Add the supported stream or repl features to an existing scaffolded project and revisit description alignment when needed.	validate
validate	stages/rust-cli-validate/SKILL.md	Run the documented compliance checks and summarize the result.	publish
publish	stages/rust-cli-publish/SKILL.md	Close the workflow with report_only, dry_run, rehearsal, or live_release.	workflow end

Canonical Guides

These files remain the source of truth for low-level execution steps:

• instructions/new.md
• instructions/add-feature.md
• instructions/validate.md

The stage skills route to those guides instead of replacing them with a second competing instruction set.

Typical Lifecycle

1. Read SKILL.md.
2. Route through stages/rust-cli-intake/SKILL.md.
3. Complete the selected working stage:
   • description before a new scaffold or any description-impacting update
   • scaffold for a new project after the description contract is approved
   • extend for stream or repl, or after a description-impacting update
   • validate for audit or post-change verification
4. Continue into publish.

Successful flows do not stop at validate. If no real release action is requested, publish defaults to report_only so the workflow still ends with clear release-readiness or no-publish closure.

Package Layout And Packaging Boundary

The staged workflow now treats two adjacent but distinct contracts as first-class:

• the generated skill package layout
• the repository-owned CI packaging and release automation

Generated skill outputs may include package-local packaging-ready metadata or support fixtures when a supported capability requires them, but repository-owned CI workflows, release scripts, and release automation stay outside generated skill packages. Review and packaging guidance should describe both surfaces without implying they are copied into every generated skill.

What Ships In The Published Bundle

The released artifact includes the staged workflow plus the release assets that the publish stage depends on:

• SKILL.md
• README.md
• constitution.md
• stages/
• instructions/
• templates/
• docs/release/skill-release-runbook.md
• .github/workflows/release.yml
• release/skill-release.config.json
• scripts/release/
• .releaserc.json
• package.json
• package-lock.json
• CHANGELOG.md

Repository-only planning assets such as .specify/, specs/, and AGENTS.md remain outside the published bundle.

Constitution

The governing rules live in constitution.md. When a stage guide and a low-level instruction disagree, use the constitution as the top- level source of truth.

Generated projects and maintenance work should stay aligned with:

• Principle II: SKILL.md is the contract
• Principle III: text I/O behavior, output formats, structured help, streaming, Active Context, and REPL rules
• Principle VI: Rust toolchain, dependency, lint, and formatting requirements

Release Modes

The final publish stage supports four outcomes:

• report_only: summarize readiness, blockers, and next actions without running release commands
• dry_run: run GITHUB_TOKEN=<valid GitHub token> npm run release:dry-run for local semantic-release review
• rehearsal: build the exact-mirror destination tree locally for inspection
• live_release: use the supported GitHub Actions workflow in .github/workflows/release.yml

Repository-owned CI packaging gathers generated package inputs, validates the package boundary, and prepares review evidence or distributable archives. It does not mean the generated skill itself contains GitHub Actions workflows or release helper scripts.

dry_run and rehearsal are not production publication. The source release workflow creates the source tag and GitHub Release; the destination mirror is published separately through peaceiris/actions-gh-pages@v4.

Local Quality Gates

Before committing changes in this repository:

npm ci
npm run prepare
npm run format:check
npx commitlint --from HEAD~1 --to HEAD --verbose

The release-oriented guidance, rehearsal commands, failure recovery, and destination configuration rules are documented in docs/release/skill-release-runbook.md.

Repository Layout

.
├── .github/workflows/
├── docs/release/
├── instructions/
├── release/
├── scripts/release/
├── stages/
├── templates/
├── SKILL.md
├── README.md
├── constitution.md
├── package.json
└── package-lock.json