@monochange/skill 0.0.0 → 0.4.2

package/examples/migration.md

@@ -0,0 +1,21 @@
+# Migration example
+
+## Recommend this when
+
+- the repository already has release scripts, CI workflows, or tag conventions
+- monochange must coexist with current tooling first
+- the user wants a phased migration instead of a big-bang switch
+
+## Default recommendation
+
+- choose `migration` depth
+- inspect existing CI files, tag conventions, changelog flow, and competitor tooling first
+- keep publishing external more often during the first phase
+- move config validation, discovery, and release dry-runs into CI before replacing publish jobs
+
+## Good default output
+
+- current workflow summary
+- recommended coexistence phase
+- pieces safe to migrate now
+- pieces to delay until trust is established

package/examples/publishing.md

@@ -0,0 +1,21 @@
+# Publishing example
+
+## Recommend this when
+
+- the user is choosing between local-only, builtin, and external publishing
+- trusted publishing or placeholder publication needs to be planned
+- the workspace contains public packages
+
+## Default recommendation
+
+- GitHub + npm: builtin is the preferred default
+- `crates.io` and `pub.dev`: external is often clearer when the registry-maintained workflow should own the publish step
+- GitLab: builtin planning still fits well, but publishing is external more often
+- ask about placeholder publication only when public names matter and the first real release may be delayed
+
+## Good default output
+
+- public vs internal package split
+- recommended publish mode per ecosystem
+- trusted-publishing follow-up steps
+- placeholder strategy, if needed

package/examples/quickstart.md

@@ -0,0 +1,22 @@
+# Quickstart example
+
+## Recommend this when
+
+- the repository is greenfield or nearly greenfield
+- the user wants a safe first success before full automation
+- package discovery and config quality matter more than publish setup right now
+
+## Default recommendation
+
+- ask for setup depth first: `quickstart` or `standard`
+- inspect the repository before asking ecosystem-specific questions
+- start with `mc init`, `mc validate`, `mc discover --format json`, and `mc release --dry-run --diff`
+- stop before real publishing unless the user explicitly wants a deeper setup
+
+## Good default output
+
+- detected provider and ecosystems
+- recommended lint profile
+- whether grouping is needed yet
+- next commands to run
+- what to defer until `full` mode

package/examples/readme.md

@@ -0,0 +1,22 @@
+# monochange skill examples
+
+Use these condensed examples when the main skill needs quick setup guidance without loading the larger repo-shaped examples from the monochange repository.
+
+## Example index
+
+- [quickstart.md](./quickstart.md) — choosing between quickstart and standard adoption
+- [migration.md](./migration.md) — adopting monochange into an existing repository safely
+- [publishing.md](./publishing.md) — builtin vs external publishing, trusted publishing, and placeholders
+- [release-pr.md](./release-pr.md) — long-running release PR branch recommendations
+
+## How to use this folder
+
+- start with `skills/adoption.md` when the user is still choosing setup depth
+- open one of the example pages here when you need a short recommendation pattern
+- use the top-level repository examples for fuller CI shapes and future end-to-end fixtures
+
+Full repository examples live in the monochange repository at:
+
+- <https://github.com/monochange/monochange/tree/main/examples>
+
+That folder also includes `examples/validate-examples.sh` for running `mc validate`, `mc check`, and `mc release --dry-run --diff` across the repo-shaped examples.

package/examples/release-pr.md

@@ -0,0 +1,20 @@
+# Release PR example
+
+## Recommend this when
+
+- the team wants a reviewable release branch
+- release files should be inspected before they land on the default branch
+- tags and publishes should happen only after merge
+
+## Default recommendation
+
+- use `mc release-pr` for branch refresh
+- do not create tags on the release branch
+- after merge, detect the durable release commit with `mc release-record --from HEAD --format json`
+- run `mc tag-release --from HEAD` before package publishing
+
+## Good default output
+
+- release PR refresh strategy
+- post-merge tagging and publish steps
+- approval and human-review checkpoints

package/package.json

@@ -1,15 +1,42 @@
 {
-  "name": "@monochange/skill",
-  "version": "0.0.0",
-  "description": "Temporary placeholder package for monochange",
-  "main": "index.js",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ifiokjr/monochange.git"
-  },
-  "homepage": "https://github.com/ifiokjr/monochange#readme",
-  "bugs": {
-    "url": "https://github.com/ifiokjr/monochange/issues"
-  },
-  "license": "MIT"
+	"name": "@monochange/skill",
+	"version": "0.4.2",
+	"description": "Skill for monochange adoption, release planning, and publishing guidance",
+	"keywords": [
+		"agent",
+		"mcp",
+		"monochange",
+		"monorepo",
+		"releases",
+		"skill"
+	],
+	"homepage": "https://github.com/monochange/monochange",
+	"bugs": {
+		"url": "https://github.com/monochange/monochange/issues"
+	},
+	"license": "Unlicense",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/monochange/monochange.git"
+	},
+	"files": [
+		"SKILL.md",
+		"skills/reference.md",
+		"skills/changeset-guide.md",
+		"skills/artifact-types.md",
+		"skills/trusted-publishing.md",
+		"skills/multi-package-publishing.md",
+		"skills",
+		"examples",
+		"readme.md",
+		"LICENSE",
+		"changelog.md"
+	],
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"engines": {
+		"node": ">=20"
+	}
 }

package/readme.md

@@ -0,0 +1,63 @@
+# @monochange/skill
+
+Installable agent skill for monochange.
+
+This package bundles:
+
+- `SKILL.md` — concise entrypoint for agents
+- `skills/readme.md` — index of focused deep dives
+- `skills/adoption.md` — setup-depth questions, migration guidance, and recommendation patterns
+- `skills/changesets.md` — changeset authoring and lifecycle guidance
+- `skills/commands.md` — built-in command catalog and usage patterns
+- `skills/configuration.md` — `monochange.toml` setup and editing guidance
+- `skills/linting.md` — `mc check`, `[lints]`, presets, and manifest-focused rule explanations with examples
+- `examples/readme.md` — condensed scenario examples for quick recommendations
+- `skills/reference.md` — high-context reference with broader examples
+- `skills/trusted-publishing.md` — GitHub/OIDC setup guidance for `npm`, `crates.io`, `jsr`, `pub.dev`, PyPI, and Go module tags
+- `skills/multi-package-publishing.md` — monorepo-oriented publishing patterns for multiple public packages
+- `monochange-skill` — helper executable for printing or copying the bundled skill
+
+## Install
+
+For project-local installation through the upstream `skills add` flow, prefer:
+
+```bash
+mc help skill
+mc skill
+mc skill -a pi -y
+```
+
+If you need the lower-level package helper directly, install it with:
+
+```bash
+npm install -g @monochange/skill
+```
+
+## Helper usage
+
+```bash
+monochange-skill --print-install
+monochange-skill --print-skill
+monochange-skill --copy ~/.pi/agent/skills/monochange
+```
+
+`monochange-skill --copy` copies the full skill bundle, including `SKILL.md`, `skills/reference.md`, `skills/trusted-publishing.md`, `skills/multi-package-publishing.md`, the `skills/` deep-dive folder, and the bundled `examples/` folder.
+
+## What the skill teaches
+
+The bundled skill explains how to:
+
+- plan adoption in `quickstart`, `standard`, `full`, or `migration` mode
+- create or refine `monochange.toml` with `mc init`, generated `[cli.*]` workflow commands, `mc step:*`, and `mc validate`
+- inspect the normalized model with `mc discover --format json`
+- create, update, and audit explicit change files with `mc change` and `mc diagnostics`, including dependency-follow-up notes with `caused_by`
+- preview release effects with `mc release --dry-run --format json` and `mc release --dry-run --diff`
+- inspect durable release history with `mc release-record`
+- understand groups, package ids, changelogs, linting policy, package publishing, and source-provider release flows
+- set up trusted publishing / OIDC-backed package publishing for the registries that monochange supports
+- choose sane multi-package publish patterns when one repository ships multiple public packages
+- point users at condensed bundled examples and fuller repository-level example indexes
+
+Open [SKILL.md](./SKILL.md) first, then use [skills/readme.md](./skills/readme.md), [examples/readme.md](./examples/readme.md), [skills/reference.md](./skills/reference.md), [skills/trusted-publishing.md](./skills/trusted-publishing.md), and [skills/multi-package-publishing.md](./skills/multi-package-publishing.md) for the deeper sections.
+
+For fuller repo-shaped examples in the monochange repository, see <https://github.com/monochange/monochange/tree/main/examples>.

package/skills/adoption.md

@@ -0,0 +1,125 @@
+# Adoption skill
+
+Use this guide when the user wants help deciding **how** to adopt monochange, not just which command to run next.
+
+## First move: inspect before interrogating
+
+Inspect the repository before asking detailed setup questions.
+
+Look for:
+
+- package ecosystems and workspace managers
+- existing CI files such as `.github/workflows/*` or `.gitlab-ci.yml`
+- existing release tooling such as changesets, knope, semantic-release, release-please, or custom scripts
+- whether packages appear public, private, or mixed
+- existing changelog, tag, and release-branch conventions
+
+Use that evidence to decide confidence:
+
+- **high confidence** — recommend a default and ask for confirmation
+- **medium confidence** — recommend a default and ask one or two targeted questions
+- **low confidence** — ask more questions before proposing file changes
+
+## Ask setup depth first
+
+Start with one question:
+
+- `quickstart` — generate or refine config and stop at validation plus dry-run release planning
+- `standard` — config, linting, and release preview
+- `full` — config, linting, CI automation, publishing, and placeholder strategy when relevant
+- `migration` — phase monochange into an existing repository safely
+
+## Core question tree
+
+### 1. Repository starting point
+
+Ask:
+
+- is this a greenfield repository or an existing one?
+- if it already exists, what handles releases today?
+- what must stay compatible during the first adoption phase?
+
+Recommendation:
+
+- prefer coexistence first for existing repositories
+- replace old tooling only after monochange discovery and dry-run planning are trusted
+
+### 2. Workspace shape
+
+Ask:
+
+- which ecosystems are present?
+- which packages are public, private, or internal-only?
+- should versions stay package-specific or move into groups?
+
+Recommendation:
+
+- prefer package ids first
+- create groups only when the outward release identity is truly shared
+
+### 3. Linting depth
+
+Ask:
+
+- does the team want minimal guardrails or stronger manifest consistency?
+
+Recommendation:
+
+- `minimal` — start with a small `[lints.rules]` set for publication-safety rules only
+- `balanced` — prefer `[lints].use = ["cargo/recommended", "npm/recommended"]` plus a few targeted overrides
+- `strict` — promote stricter presets or scoped overrides after the repo is already stable
+
+### 4. Release orchestration
+
+Ask:
+
+- should releases stay local-only, use a merged release commit, or use a long-running release PR branch?
+- which provider owns CI: GitHub, GitLab, or something custom?
+
+Recommendation:
+
+- default to hybrid: local discovery and dry-runs, CI for real release and publish work
+- prefer GitHub for the most automated builtin path today
+- on GitLab, keep planning builtin and keep publishing external more often when auth/bootstrap is already specialized
+
+### 5. Publishing and placeholders
+
+Ask these only if the workspace contains public packages.
+
+Ask:
+
+- which registries are involved?
+- does the team want builtin or external publish jobs?
+- do package names need to be reserved before the real release flow is ready?
+
+Recommendation:
+
+- GitHub + npm: builtin is the preferred default
+- `crates.io` and `pub.dev`: external is often clearer when the registry-maintained workflow should own the publish step
+- ask about `mc placeholder-publish` only when public names matter and the first real release may be delayed
+
+## Final output contract
+
+End the planning flow with a compact decision record:
+
+- detected repo profile
+- chosen setup depth
+- recommended adoption path
+- recommended `monochange.toml` shape
+- recommended lint profile
+- recommended CI and release strategy
+- recommended publishing and placeholder strategy, if applicable
+- open risks or unanswered questions
+- next commands to run
+
+## Guardrails
+
+- do not write CI or publish configuration without permission
+- do not force publishing questions into internal-only repositories
+- do not recommend big-bang migration by default
+- keep recommendations short, with the default plus a brief tradeoff explanation
+
+## Related examples
+
+- [../examples/readme.md](../examples/readme.md)
+- full repository examples: <https://github.com/monochange/monochange/tree/main/examples>