@monochange/skill 0.0.0 → 0.4.2

package/skills/commands.md

@@ -0,0 +1,204 @@
+# Commands skill
+
+Use this guide when the task is to choose, explain, or sequence monochange CLI commands.
+
+## Command selection by goal
+
+### Create or repair config
+
+| Goal                        | Command       | When to use it                                                  |
+| --------------------------- | ------------- | --------------------------------------------------------------- |
+| Bootstrap a repo            | `mc init`     | You need a starter `monochange.toml` based on detected packages |
+| Check config and changesets | `mc validate` | Before and after release-affecting edits                        |
+
+Examples:
+
+```bash
+mc init
+mc init --provider github
+mc validate
+```
+
+### Inspect the workspace
+
+| Goal                                      | Command                          | When to use it                                                     |
+| ----------------------------------------- | -------------------------------- | ------------------------------------------------------------------ |
+| See normalized packages and groups        | `mc discover --format json`      | You need package ids, dependency edges, or group ownership         |
+| Audit pending changesets with git context | `mc diagnostics --format json`   | You need introduced commits, linked reviews, or related issues     |
+| Inspect a durable release declaration     | `mc release-record --from <ref>` | You need to inspect a past release after the commit already exists |
+
+Examples:
+
+```bash
+mc discover --format json
+mc diagnostics --format json
+mc diagnostics --changeset .changeset/feature.md
+mc release-record --from v1.2.3
+mc release-record --from HEAD --format json
+```
+
+### Inspect lint rules and presets
+
+| Goal                            | Command                | When to use it                                                          |
+| ------------------------------- | ---------------------- | ----------------------------------------------------------------------- |
+| List registered rules/presets   | `mc lint list`         | You want to see which lint ids and presets monochange currently exposes |
+| Explain one rule or preset      | `mc lint explain <id>` | You want the details before configuring a rule in `[lints]`             |
+| Run configured lint enforcement | `mc check`             | You want validation plus lint execution against manifests               |
+
+Examples:
+
+```bash
+mc lint list
+mc lint list --format json
+mc lint explain cargo/recommended
+mc lint explain npm/workspace-protocol
+mc check --fix
+```
+
+### Create release intent
+
+| Goal                                     | Command                     | When to use it                                                                               |
+| ---------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------- |
+| Create a changeset                       | `mc change`                 | You know the target package or group id                                                      |
+| Check policy coverage from changed files | `mc step:affected-packages` | CI or review needs to confirm that changed packages have changesets without a config wrapper |
+
+Examples:
+
+```bash
+mc change --package monochange --bump minor --reason "add diagnostics command"
+mc change --package monochange_config --bump none --caused-by monochange_core --reason "dependency-only follow-up"
+mc step:affected-packages --verify --changed-paths crates/monochange/src/lib.rs --format json
+```
+
+### Plan or execute a release
+
+| Goal                            | Command                            | When to use it                                                                   |
+| ------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------- |
+| Preview a release safely        | `mc release --dry-run`             | You want the computed plan without mutating files                                |
+| Preview file diffs too          | `mc release --dry-run --diff`      | You want to see version/changelog patches before applying them                   |
+| Apply the release locally       | `mc release`                       | You are ready to update files on disk                                            |
+| Create a release commit locally | `mc commit-release`                | You want the prepared commit before provider publishing                          |
+| Publish package artifacts       | `mc publish --output <path>`       | Built-in package publishing is configured for the release state                  |
+| Create provider releases        | `mc publish-release`               | Source/provider publishing is configured                                         |
+| Open or update a release PR     | `mc release-pr`                    | You want provider-hosted release-request automation                              |
+| Bootstrap release packages      | `mc publish-bootstrap --from HEAD` | A release package must exist in the public registry before automation can finish |
+| Retarget a recent release       | `mc repair-release --from <ref>`   | A just-created release needs to move forward to a later commit                   |
+
+Examples:
+
+```bash
+mc release --dry-run
+mc release --dry-run --diff
+mc release --dry-run --format json
+mc commit-release --dry-run --diff
+mc publish --dry-run --format json
+mc publish-readiness --from HEAD --output .monochange/readiness.json
+mc publish-bootstrap --from HEAD --output .monochange/bootstrap-result.json
+mc publish-readiness --from HEAD --output .monochange/readiness.json
+mc publish-plan --readiness .monochange/readiness.json --format json
+mc publish --output .monochange/publish-result.json
+mc publish-release --dry-run --format json
+mc release-pr --dry-run --format json
+mc placeholder-publish --dry-run --format json
+mc repair-release --from v1.2.3 --target HEAD --dry-run
+```
+
+### Assistant workflows
+
+| Goal                                  | Command                       | When to use it                                               |
+| ------------------------------------- | ----------------------------- | ------------------------------------------------------------ |
+| Install the monochange skill locally  | `mc skill [skills-add flags]` | You want the project-local skill bundle through `skills add` |
+| Generate repo-local agent setup files | `mc subagents <target>`       | You want monochange-aware agents, subagents, or rules        |
+| Start the MCP server                  | `mc mcp`                      | The client launches monochange over stdio                    |
+
+Examples:
+
+```bash
+mc help skill
+mc skill
+mc skill -a pi -y
+mc help subagents
+mc subagents claude
+mc subagents pi codex
+mc mcp
+```
+
+## Output formats
+
+Many commands support `text`, `markdown`, and `json`.
+
+Use:
+
+- `--format json` for automation and agent parsing
+- `--format markdown` for human-readable terminal output with richer structure
+- `--format text` when you explicitly want the older plain-text rendering
+
+For release-oriented commands, markdown is the default output format.
+
+## A practical command flow
+
+For most work, use this order:
+
+```bash
+mc validate
+mc discover --format json
+mc change --package <id> --bump patch --reason "describe the change"
+mc diagnostics --format json
+mc release --dry-run --diff
+```
+
+Then choose the next step:
+
+- `mc release` to apply
+- `mc commit-release` to produce the local release commit
+- `mc publish-readiness --from HEAD --output <path>`, optional `mc publish-bootstrap --from HEAD --output <path>`, `mc publish-plan --readiness <path>`, and `mc publish --output <path>` to preflight/plan/bootstrap/publish package artifacts; rerun with `--resume <path>` after a partial publish failure
+- `mc publish-release` to create provider releases
+- `mc release-pr` to update a release request instead
+
+## Common mistakes
+
+### Guessing package ids
+
+**Avoid:**
+
+```bash
+mc change --package crates/monochange --bump patch --reason "..."
+```
+
+**Prefer:**
+
+```bash
+mc discover --format json
+mc change --package monochange --bump patch --reason "..."
+```
+
+### Releasing before a dry run
+
+**Avoid:**
+
+```bash
+mc release
+```
+
+**Prefer:**
+
+```bash
+mc release --dry-run --diff
+mc release
+```
+
+### Reading raw changesets when diagnostics would be clearer
+
+**Avoid:** manually scraping `.changeset/*.md` files to discover provenance.
+
+**Prefer:**
+
+```bash
+mc diagnostics --format json
+```
+
+## Related references
+
+- [reference.md](./reference.md)
+- [configuration.md](./configuration.md)
+- [changesets.md](./changesets.md)

package/skills/configuration.md

@@ -0,0 +1,258 @@
+# Configuration skill
+
+Use this guide when the task is to create, review, or extend `monochange.toml`.
+
+## First choice: generate, then edit
+
+Start with generated config whenever possible:
+
+```bash
+mc init
+```
+
+`mc init` seeds editable `[cli.*]` workflow commands. If you already have `monochange.toml`, edit existing workflow tables directly or add new `[cli.<name>]` tables; use immutable `mc step:*` commands when you need direct built-in step execution without a wrapper.
+
+Validate after every meaningful change:
+
+```bash
+mc validate
+```
+
+## Minimum viable config
+
+A small repo can start with defaults plus one package:
+
+```toml
+[defaults]
+package_type = "cargo"
+
+[package.monochange]
+path = "crates/monochange"
+```
+
+Use this when the repo is simple and one ecosystem dominates.
+
+## Add changelog defaults early
+
+A useful next step is defining how changelogs should render:
+
+```toml
+[defaults]
+package_type = "cargo"
+
+[defaults.changelog]
+path = "{{ path }}/changelog.md"
+format = "keep_a_changelog"
+```
+
+Why:
+
+- packages inherit the same changelog shape by default
+- you avoid repeating the same table everywhere
+- you can still override per package or group later
+
+## Declare packages explicitly
+
+monochange works best when every managed package has a stable id.
+
+```toml
+[package.monochange_core]
+path = "crates/monochange_core"
+
+[package.monochange]
+path = "crates/monochange"
+versioned_files = ["Cargo.toml"]
+```
+
+Prefer ids you want to see in changesets and release output.
+
+## Use groups for shared release identity
+
+When several packages version together, create a group:
+
+```toml
+[group.sdk]
+packages = ["monochange_core", "monochange"]
+tag = true
+release = true
+version_format = "primary"
+```
+
+Use a group when the outward release boundary is shared.
+
+Do not use a group just because packages depend on each other. Simple dependency propagation often does the right thing without grouping.
+
+## Add extra changelog sections intentionally
+
+Use `extra_changelog_sections` when one change type deserves its own heading:
+
+```toml
+[package.web-app]
+path = "apps/web"
+type = "cargo"
+extra_changelog_sections = [
+	{ name = "User Experience", types = ["ux"], default_bump = "minor" },
+]
+```
+
+Then create a changeset like:
+
+```bash
+mc change --package web-app --bump minor --type ux --reason "redesign settings navigation"
+```
+
+## Version more than manifests
+
+Use `versioned_files` when a release also needs to update README badges, install scripts, or extra manifests.
+
+### Ecosystem-aware entries
+
+```toml
+[package.monochange]
+path = "crates/monochange"
+versioned_files = [
+	"Cargo.toml",
+	{ path = "crates/monochange/extra.toml", type = "cargo" },
+]
+```
+
+### Regex entries for plain text
+
+```toml
+[package.monochange]
+path = "crates/monochange"
+versioned_files = [
+	{ path = "README.md", regex = 'v(?<version>\d+\.\d+\.\d+)' },
+]
+```
+
+Use regex entries when no ecosystem parser applies.
+
+## Lockfile refresh strategy
+
+If the built-in lockfile rewriting is enough, keep config minimal.
+
+Add `lockfile_commands` only when the package manager must do the refresh:
+
+```toml
+[ecosystems.npm]
+lockfile_commands = [
+	{ command = "pnpm install --lockfile-only", cwd = "packages/web" },
+]
+```
+
+Use this when workspace-specific package-manager behavior matters more than raw speed.
+
+## Package publishing and trust
+
+Publishing is separate from release planning.
+
+```toml
+[ecosystems.npm.publish]
+mode = "builtin"
+trusted_publishing = true
+
+[package.web.publish.placeholder]
+readme_file = "docs/web-placeholder.md"
+```
+
+Use:
+
+- `mc placeholder-publish` to bootstrap missing public packages
+- `mc publish-readiness --from HEAD --output <path>` and `mc publish` for package-registry publishing
+- `mc publish-release` for hosted/provider releases
+
+Preference rules for trusted publishing:
+
+- for npm on GitHub, `mode = "builtin"` is the preferred path because monochange can verify and configure trust itself
+- for `crates.io`, prefer `rust-lang/crates-io-auth-action@v1` when you want a registry-native GitHub Actions publish workflow
+- for `pub.dev`, prefer `dart-lang/setup-dart/.github/workflows/publish.yml@v1` when you want the workflow shape recommended by the Dart team
+- for `crates.io` and `pub.dev`, `mode = "external"` is often the clearest fit when the registry-maintained workflow should own the publish command directly
+- if one repository publishes multiple public packages, use [multi-package-publishing.md](./multi-package-publishing.md) to decide between one shared readiness-enforced `mc publish` job, package-specific jobs, or fully external workflows
+
+## Release titles and changelog headings
+
+Customize outward release text with these fields:
+
+```toml
+[defaults]
+release_title = "{{ version }} ({{ date }})"
+changelog_version_title = "[{{ version }}]({{ tag_url }}) ({{ date }})"
+```
+
+Use them when:
+
+- provider release titles need a consistent format
+- changelog headings should include links or dates
+- group releases should read differently from package releases
+
+## Add or override top-level commands
+
+`monochange.toml` can define or override `[cli.<command>]` entries.
+
+```toml
+[cli.release]
+help_text = "Prepare a release from discovered change files"
+
+[[cli.release.inputs]]
+name = "format"
+type = "choice"
+choices = ["markdown", "text", "json"]
+default = "markdown"
+
+[[cli.release.steps]]
+type = "PrepareRelease"
+```
+
+Use the `[cli.*]` workflow tables generated by `mc init` as the editable starting point, or add a new `[cli.<name>]` table yourself.
+
+## A safe config-edit workflow
+
+```bash
+mc init
+mc validate
+mc discover --format json
+mc validate
+mc release --dry-run --format json
+```
+
+If you touched grouped packages, changelog settings, or versioned files, add `--diff` to inspect the planned file changes:
+
+```bash
+mc release --dry-run --diff
+```
+
+## Common mistakes
+
+### Hand-writing ids before discovery
+
+**Avoid:** inventing ids from directory names.
+
+**Prefer:**
+
+```bash
+mc discover --format json
+```
+
+### Over-grouping packages
+
+**Avoid:** putting every related package into one group.
+
+**Prefer:** only group packages that should share one outward version and release identity.
+
+### Forgetting validation after config edits
+
+**Avoid:** editing `monochange.toml` and going straight to publishing.
+
+**Prefer:**
+
+```bash
+mc validate
+mc release --dry-run --format json
+```
+
+## Related references
+
+- [reference.md](./reference.md)
+- [commands.md](./commands.md)
+- [linting.md](./linting.md)