@djordje-stojanovic/sigmaskills 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,73 @@ All notable changes to [Sigmaskills](https://github.com/Djordje-Stojanovic/Sigma
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-09-27
+
+### Added
+
+- SigmaImprove (`sigmaimprove`) finds what would make a product, game, codebase, or system clearly better. It scans a full list of improvement categories (value, speed, control, look and feel, reach, intelligence, trust, engineering, and games) and compares the product with the world's top one to three products and with published bars such as Core Web Vitals and WCAG 2.2. It keeps at least ten entries: ideas with 3–5 weighed options and text sketches, and signals that flag a gap for a person to think about. It files one living issue per category (1–20 per run) and updates those issues on later runs instead of duplicating them. It never edits the system. It grew out of the SigmaCheck draft, which was never released.
+- The first SigmaCheck audit of this repository is kept in `docs/audits/SIGMACHECK-2026-09-26.md` as a baseline.
+- SigmaShip (`sigmaship`) ships one planned GitHub issue end to end: a feature worktree and branch, a draft PR linked to the ticket, spec, and map, test-first commits pushed as it goes, review rounds by fresh agents until one finds nothing at P0–P2, then merge, ticket closed, branches and worktree deleted, and local `main` verified equal to `origin/main`. It refuses tickets without checkable acceptance criteria and names the skill to run first. It builds on Matt Pocock's `implement` skill.
+- `install` takes several skill ids (`install sigmawrite sigmareview`) or `--all`. Every skill is planned first, then all of them install in one transaction: if one fails, none stay installed, and `skills-lock.json` is written once. `--json` prints `{ schemaVersion, plans }` when there is more than one skill; one skill prints the same plan as before. (#38)
+- Skill evals. `npm test` now checks the output contract of every skill against good and bad sample outputs, and checks that near-miss prompts route to the right skill. `node scripts/eval-skills.js [skill...]` runs the real skills on a small fixture game with Claude Code, on demand only. See `docs/evals.md`. (#43)
+
+### Changed
+
+- SigmaReview (`sigmareview`) now covers correctness, security (source review plus safe tests on a local instance), and measured performance in one run. It reports every finding with no cap, each written as a self-contained fix brief that an LLM can act on, grouped into waves that can be fixed in parallel. It still never changes code: it publishes one feature-branch pull request with the review file. The report file is now `SIGMAREVIEW-YYYY-MM-DD.md`.
+- SigmaBrief (`sigmabrief`) accepts SigmaReview reports and SigmaImprove issues as input and groups briefs into waves, so only independent items run in parallel. Every brief now asks for green baseline checks before changes and ends with a fixed report (`DONE`, `DONE_WITH_CONCERNS`, or `BLOCKED`, plus PR, checks, and open questions). `approval: auto` lets agents record their decisions as rulings instead of waiting. A host's native worktree tool is preferred over manual `git worktree`. A new `session` brief hands the current conversation to a fresh agent.
+- The skill picker and `list` now show each skill's short description for people (`short_description` in `agents/openai.yaml`) instead of the agent-facing description cut off mid-word. The picker wraps it onto at most two lines, so narrow terminals show it whole. A skill without that line shows the first sentence of its description. `list --json` still gives the full description. (#39)
+- The installer's private files (state, lock, backups, journals, staging) now live in `.agents/.sigmaskills/` (global: `~/.agents/.sigmaskills/`). The folder ignores itself in Git, so `git add -A` no longer stages `.agents/state.json` or backups. Older projects move there on the next write command; `status` and `--dry-run` still read the old layout and write nothing. `--state-dir` and `SIGMA_STATE_DIR` are unchanged. (#34)
+- The npm package now ships only the user CLI: about 110 KB smaller unpacked and 10 fewer files. Release and registry automation moved to `scripts/` in the repository, and `sigmaskills release` is gone from the published CLI. Maintainers run `npm run release -- <flags>` from a checkout; the checks it makes are unchanged. (#40)
+- Every pull request now rehearses the Release path. A CI job commits the Release identities in a throwaway worktree, then runs the preview, the dispatch checks, and the trusted `validate` and publish steps with a real `npm pack` (`node scripts/release-rehearsal.js`). npm and GitHub lookups, dispatch, and publish are stubbed, so the job needs no secrets. A pull request that breaks packing, such as the `npm pack` JSON bug fixed in 0.2.1, now fails before merge. (#41)
+- CI now runs with a read-only token (`permissions: contents: read`) and pins every action to a full commit SHA, like the Release workflows. (#41)
+- CI now tests Node.js 22 and 24 on Windows, macOS, and Linux. Node.js 20 reached end of life on 2026-04-30, but `engines` stays at `>=20` for this Release so current users on Node.js 20 can still install; one Linux job on Node.js 20 keeps that promise tested. A later Release may raise it. (#41)
+- The README is short again. It keeps the quick start, the skills, one install table, and run examples. Command details moved to [`docs/installer.md`](docs/installer.md); releases, registry automation, tests, and CI moved to [`docs/maintainers.md`](docs/maintainers.md). A test keeps it under 1,500 words, with no paragraph over 80 words. (#42)
+- The Agent Host registry follows `vercel-labs/skills` at `7407f38`: Droid and Kilo read project skills from `.agents/skills` (Kilo global: `~/.kilo/skills`), fx and sarvam-code are new hosts, and Antigravity, antigravity-cli, and deepagents leave the universal-prompt list. Existing installs keep their recorded paths.
+
+### Removed
+
+- SigmaPerformance (`sigmaperformance`). Its measurement method and evidence classes are now part of SigmaReview.
+
+### Fixed
+
+- The release tool now treats a breaking change before 1.0.0 as a minor version step, as SemVer allows for 0.y.z versions, instead of jumping to 1.0.0.
+- The README no longer points to the v0.2.1 zip as the latest Release.
+- The finished 0.3.0 `plan.md` is removed from the repository root; its content lives in issue #3 and PR #29.
+- `update` no longer stops when a skill that left the Skill Pack is still installed. The manifest lists retired skills (`sigmaperformance`); `update` leaves them unchanged, lists them under *Retired skills*, and names the `uninstall` command that removes them.
+- An unknown skill id now fails with `unknown skill '<id>'` before any planning, for `install`, `update`, `restore`, and `uninstall`. `uninstall --skill nope` said `stale-state` before. (#38)
+- A value flag with a missing, empty, or dash-prefixed value now fails with the flag name. Before, `--skill --yes` read `--yes` as a skill id, and a value flag at the end of the command was ignored. One flag table now parses and checks every flag; all current flags and aliases still work. (#38)
+- The registry sync test writes into a temporary folder instead of `registry/agent-hosts.json`, so parallel test files no longer read a half-written file and fail at random.
+- Update previews show the relevant release notes and correct running-version relation, omit empty sections, and ask for outside-edit choices only when needed. JSON field names and the installed-side relation remain compatible. (#36)
+- Lock recovery serializes competing takeovers, preserves fresh incomplete records, and checks unique ownership when releasing. Locks expire after 24 hours; a crash-leftover takeover guard stops safely with recovery instructions. Legacy migration uses the same lock. (#37)
+- Untouched copies of earlier Releases are recognized again. `registry/skill-baselines.json` now holds the file hashes of 0.1.0, 0.2.0, 0.2.1, and 0.3.0, rebuilt from their git tags (`node scripts/backfill-baselines.js <tag>...`), and `npm run release -- --write-identities` adds the outgoing Release each time. Such a copy shows as `legacy` with high provenance and upgrades with no `--adopt-*` flag; a changed copy still needs a choice. (#35)
+- Install plans now label files from the installer's point of view: *Additions* are files the new Release brings, *Deletions* are files the install removes. They were swapped before. (#35)
+
+## [0.3.0] — 2026-09-08
+
+### Added
+
+- SigmaRefactor (`sigmarefactor`) scans and reconciles the five largest maintained files, reads them fully, discusses behavior-preserving refactoring choices with the user, and verifies approved changes.
+
+### Fixed
+
+- The interactive installer stops repeating unchanged static pages and pauses standard input during cleanup, so confirmed installs return to the shell reliably.
+- The installer opens directly to skill selection, keeps destination pages within eight rows, and offers line-based commands in plain terminals. Help preserves cancellation, and short terminals keep focus and controls visible.
+- Package tests compare complete trees and bytes for all five skills, including customized reinstall protection and updates.
+
+
+## [0.2.1] — 2026-08-27
+
+### Changed
+
+- The Agent Host registry now includes Posit Assistant from the pinned `vercel-labs/skills` revision `dd3ca3c85581`.
+
+### Fixed
+
+- The destination picker paints one compact row per path, windows a live TTY list, groups search hits that share a path, and leaves the alternate screen before cancel or error copy so Windows does not stack or swallow that text.
+- Registry Sync no longer fails when a leftover `registry/sync-*` branch still exists: it replaces that generated branch, or reuses a matching open pull request, and still refuses human branches.
+- Release packing reads `npm pack --json` after prepack logs, so publication can rebuild the tarball digest.
+
+
 ## [0.2.0] — 2026-08-20
 
 ### Fixed
@@ -72,6 +139,7 @@ Ship high-rigor, installable agent skills (not apps): full-repo audits, performa
 | 2026-08-11 | `5dab832` | Add CHANGELOG and mark v0.1.0 as the first Sigmaskills release |
 | 2026-08-11 | `124a666` | Polish v0.1.0 docs for multi-host install and use |
 
-[Unreleased]: https://github.com/Djordje-Stojanovic/Sigmaskills/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/Djordje-Stojanovic/Sigmaskills/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/Djordje-Stojanovic/Sigmaskills/releases/tag/v0.2.1
 [0.2.0]: https://github.com/Djordje-Stojanovic/Sigmaskills/releases/tag/v0.2.0
 [0.1.0]: https://github.com/Djordje-Stojanovic/Sigmaskills/releases/tag/v0.1.0

package/README.md

@@ -6,15 +6,17 @@ Portable [Agent Skills](https://agentskills.io/) that install once and run on **
 
 | | |
 |---|---|
-| **Release** | [**v0.2.0**](https://github.com/Djordje-Stojanovic/Sigmaskills/releases/tag/v0.2.0) |
+| **Release** | [**v0.4.0**](https://github.com/Djordje-Stojanovic/Sigmaskills/releases/tag/v0.4.0) |
 | **Changelog** | [CHANGELOG.md](CHANGELOG.md) |
 | **License** | [MIT](LICENSE) |
 | **Spec** | [agentskills.io](https://agentskills.io/) |
 
 ```text
-  Σ  review     →  one findings report, one PR, no runtime edits
-  Σ  performance→  calibrated bottlenecks, one report PR
+  Σ  review     →  find and prove what is wrong, one PR an LLM can fix from
+  Σ  improve    →  ideas versus the world's best, one living issue per category
+  Σ  refactor   →  user-guided, behavior-preserving code reduction
   Σ  brief      →  paste-ready agent briefs, chat only
+  Σ  ship       →  one planned ticket to a merged, cleaned-up PR
   Σ  write      →  clear STE-inspired technical English
 ```
 
@@ -22,23 +24,25 @@ Portable [Agent Skills](https://agentskills.io/) that install once and run on **
 
 ## Quick start
 
-Start the first-party Sigma Installer in a project:
+Run the Sigma Installer in your project:
 
 ```bash
 npx @djordje-stojanovic/sigmaskills
 ```
 
-Select any set of skills. By default the installer writes only to `.agents/skills/<id>` and lists every Agent Host that reads that universal destination. Host-specific directories such as `.claude/skills` or `.pi/skills` stay unselected until you choose them. Selected host destinations use Windows directory junctions or macOS/Linux symbolic links to the canonical copy; `--copy` writes an independent managed copy instead. Link failure reports the exact cause and offers copy — the installer never changes method silently. Exact current official copies and valid links are adopted in place without rewriting skill bytes. Changed, older, pre-marker, and unverified Sigma-looking trees are classified with a file diff and provenance confidence; replace commits a private backup first, skip leaves the tree, and export writes a collision-safe copy. Pre-marker extra content is never guessed into the customization block; malformed markers stop unless you pass an explicit `--adopt-malformed` choice. The confirmation plan shows every full destination path and method. Press `g` in the skill picker for Global Installation: an immediate scope warning appears, then a second confirmation repeats every Agent Host, resolved path, method, overwrite effect, and backup action. Non-interactive Global writes need both `--global` and `--yes`; CI, TTY, JSON, and Agent Host detection never imply that authority. To install one skill without the interactive interface:
+Pick the skills you want and confirm. By default the installer writes only to `.agents/skills/<id>`, the folder that many Agent Hosts read. It writes nothing until you confirm.
+
+To install without the picker, name one or more skills, or pass `--all`. Several skills install together: if one fails, none stay installed.
 
 ```bash
 npx @djordje-stojanovic/sigmaskills install sigmawrite --project .
-npx @djordje-stojanovic/sigmaskills install sigmawrite --project . --destination .claude/skills
-npx @djordje-stojanovic/sigmaskills install sigmawrite --project . --destination .claude/skills --copy
-npx @djordje-stojanovic/sigmaskills install sigmawrite --global --dry-run
-npx @djordje-stojanovic/sigmaskills install sigmawrite --global --yes
+npx @djordje-stojanovic/sigmaskills install sigmawrite sigmareview sigmaship --project .
+npx @djordje-stojanovic/sigmaskills install --all --project .
 ```
 
-Then invoke with your host’s normal skill syntax (`$sigmawrite`, `/skill:sigmawrite`, skill picker, …).
+Then call a skill with your host's normal skill syntax (`$sigmawrite`, `/skill:sigmawrite`, the skill picker, …).
+
+The [installer guide](https://github.com/Djordje-Stojanovic/Sigmaskills/blob/main/docs/installer.md) explains host folders, Global Installation, `status`, `update`, `restore`, `uninstall`, and `purge`.
 
 ---
 
@@ -46,159 +50,69 @@ Then invoke with your host’s normal skill syntax (`$sigmawrite`, `/skill:sigma
 
 | Skill | Id | Job | Output |
 |-------|-----|-----|--------|
-| **SigmaReview** | `sigmareview` | One-shot full-repo engineering audit | One findings MD + report-only PR |
-| **SigmaPerformance** | `sigmaperformance` | Calibrated performance investigation | One report MD + report-only PR |
+| **SigmaReview** | `sigmareview` | Find and prove what is wrong: bugs, security, performance, tests | One feature-branch PR with one review file |
+| **SigmaImprove** | `sigmaimprove` | Find what would make it clearly better, measured against the world's best | One living issue per category (1–20), updated on every run |
 | **SigmaBrief** | `sigmabrief` | Prompt factory for parallel / single agents | Chat briefs only |
+| **SigmaShip** | `sigmaship` | Ship one planned ticket: build, review rounds, merge, clean up | One merged PR, closed ticket, main in sync |
 | **SigmaWrite** | `sigmawrite` | Clear STE-inspired technical English | Chat writing voice |
+| **SigmaRefactor** | `sigmarefactor` | Safe, user-approved large-file refactoring | Discussion, changes, and verification |
 
-### SigmaReview
-
-A single agent walks an entire repository — correctness, completeness, architecture, data and concurrency, reliability, security, performance, tests, dependencies, delivery, operations, and domain-specific engineering. Speculative findings are rejected. Exactly **one** evidence-rich Markdown report is published as a **report-only** pull request. Runtime code is never changed.
-
-### SigmaPerformance
-
-Maps real user journeys, then separates **measured** and **mechanically proven** bottlenecks from measurement-required opportunities. Publishes one structured report PR. Runtime sources stay untouched unless calibration explicitly says otherwise.
-
-### SigmaBrief
-
-Turns GitHub issues, features, upgrades, bugs, or plain work statements into short, copy-pastable briefs for other agents. Light research → dispatch list → fenced briefs → **stop**. Does not implement work or open product fix PRs. Default brief arc: plan → optional grill-me (including Windows worktree) → approve → execute → validate → PR for review (**do not merge**).
-
-**User-triggered only.** Do not treat Brief as ambient chat decoration.
-
-### SigmaWrite
-
-Writing voice inspired by **ASD-STE100 Simplified Technical English** — soft steers, not hard numbered rules. High-quality, still-technical explanations a sharp outsider can follow. Hard bans on gibberish and invented words. Includes a pasteable system-prompt block inside `SKILL.md`. Not certified STE; no dictionary ship.
-
----
-
-## Install
-
-### Sigma Installer: Project Installation (recommended)
-
-Run `npx @djordje-stojanovic/sigmaskills` with no command. The Sigma Installer's Emberforge interface reads the Skill Pack catalog from `manifest.json` and the bundled Agent Host registry. Project Installation selects only the universal `.agents/skills/` destination by default, expands every Agent Host that reads it, and leaves host-specific destinations unselected until you choose them. Search remains available for every supported Agent Host, including hosts that are not detected. Exact current official copies and valid links are recorded as managed without rewriting skill bytes. Escape, EOF, Ctrl+C, or a rejected confirmation exits without writing.
-
-The Emberforge screens keep the accepted warm LAPI palette and do not mix in Prismgrid or Monolith. Layouts reflow below 76 columns and wrap long paths. Keyboard-only controls cover focus, search, selection, confirmation, cancellation, and `?` help. `--no-color`, `--static`, `--narrow`, `--json`, `NO_COLOR`, `CI`, `REDUCED_MOTION=1`, `PREFERS_REDUCED_MOTION=reduce`, redirected output, and non-TTY sessions disable animation and decorative color. Truecolor, 256-color, 16-color, and ASCII fallbacks stay readable and still show safety copy. The cursor and raw mode restore after success, failure, interrupt, EOF, and exceptions.
-
-Use `--no-color`, `--static`, or `--narrow` when the terminal needs those modes. Use `--project <path>` to select another project root.
-
-### Sigma Installer: Global Installation
+### Which one do I need?
 
-Project Installation stays the default. In the interactive installer, `g` selects Global Installation and shows a scope warning immediately. The final confirmation repeats every selected Agent Host, exact resolved path, method, overwrite or delete effect, and backup action. Cancel at either prompt leaves prior user-level state unchanged.
+SigmaReview and SigmaImprove split on one question: **is it wrong, or could it be better?**
 
-Non-interactive mutation requires both `--global` and `--yes`. `--dry-run` shows those confirmation requirements and the full impact without writing. Unknown newer global state schemas fail closed; supported migrations keep ownership, hashes, methods, and backup references. Exact and changed existing copies use the same adoption path as Project Installation.
+- If a test, a doc, a stated goal, or a budget can prove it wrong, it is a SigmaReview finding. Examples: a crash, a security hole, a page that breaks its latency budget.
+- If good people could disagree about the answer, it is a SigmaImprove idea. Examples: weak animation, a missing level, an onboarding flow with too many steps.
+- If the code is only too large and behavior must not change, use SigmaRefactor.
 
-### Sigma Installer: status
+The skills chain into two loops. **Fix:** SigmaReview → review PR → SigmaBrief or SigmaShip fixes each finding → merge. **Grow:** SigmaImprove → category issues → specs and tickets → SigmaShip.
 
-`npx @djordje-stojanovic/sigmaskills status` is read-only. It reports Project Installation state by default, or Global Installation with `--global`. Human and `--json` output name the scope, installed and running Release, Skill Revisions, Agent Hosts, methods, exact paths, and ownership. Classification uses live per-file hashes and `lstat`/link checks. Valid Skill Customization is drift, not corruption. Drift discovery still exits `0`; command failures exit `1`. Status does not migrate, repair, write state or destinations, rewrite `skills-lock.json`, or contact the network.
-
-### Sigma Installer: update
-
-`npx @djordje-stojanovic/sigmaskills update --dry-run` groups changed and unchanged skills, shows the bundled changelog and whole-skill file diffs, and writes nothing. `--yes` updates every changed skill when none are blocked; `--skill <id>` (repeatable) selects complete skills only. Valid Skill Customization bytes between the markers are copied onto the new official `SKILL.md` exactly. Edits outside that block are classified as local-only or concurrent with upstream; `--dry-run` names those cases and the overwrite or delete effects. `--outside-edit replace|skip|export` is required before mutation: replace takes a complete integrity-checked private backup first, skip leaves that skill and its state untouched while other skills continue, and export copies the prior tree to a planned path and refuses collisions. Missing, duplicate, reversed, nested, or otherwise malformed customization markers block automatic update for that skill and are never guessed into a customization boundary. `--dry-run` shows the marker shape, exact proposed repair bytes when a unique mechanical repair exists, and the resulting replacements or deletions. `--malformed-markers skip|repair|replace` is required before mutation: skip leaves that skill unchanged while others continue, repair writes only an approved exact repair, and replace takes a complete private backup then installs a clean official copy. Malformed markers plus outside drift keep all content until both `--malformed-markers` and `--outside-edit` are explicit. Cancellation, invalid repair, editor failure, backup failure, or transaction failure writes nothing partial. The latest valid backup stays until the new tree and backup metadata commit; cleanup failure may keep two backups and record cleanup debt. The canonical `.agents/skills/<id>` copy owns customization; links and matching managed copies follow it. Unknown newer state schemas, missing bundled Skill Revisions, broken links, and copy disagreement stop without mutation. Updates use the same transactional install path and refresh state only after commit. Project Installation is the default; Global Installation needs `--global` and `--yes`.
-
-### Sigma Installer: restore
-
-`npx @djordje-stojanovic/sigmaskills restore --skill <id> --dry-run` shows the latest retained backup: Release and Skill Revision when known, creation date, verified size, scope, canonical target, and affected links or copies. `--yes` stages and integrity-checks the backup before any live write. On success the displaced current tree becomes the new one-step backup. Restoring identical content is a no-op and does not rotate backups. A removed skill can return from portable ownership metadata without claiming unrelated paths. Missing, truncated, tampered, schema-incompatible, insufficient-space, stale-ownership, occupied-unowned, and failed Windows fallback cases stop with the prior live tree and retained backup intact. Project Installation is the default; Global Installation needs `--global` and `--yes`.
-
-### Sigma Installer: uninstall
-
-`npx @djordje-stojanovic/sigmaskills uninstall --skill <id> --dry-run` runs Uninstall Review for each selected skill. `npx @djordje-stojanovic/sigmaskills uninstall --all --dry-run` composes that same Uninstall Review across every recorded Sigma skill in one explicit Project or Global scope. There is no review-skipping fast path. The aggregate plan lists every skill, owned destination, canonical dependency, planned state change, and retained backup. Clean skills offer `--clean remove|keep`. Changed, customized, or malformed skills offer `--changed backup|keep|export|delete`. Uninstall-all defaults to `--changed backup` so backups remain restorable. `--yes` applies those choices: remove deletes only revalidated Sigma-owned paths; backup snapshots the current tree then removes it; export copies the current tree to `--export-dir` then removes managed paths; delete removes current content and leaves any older retained backup; keep writes nothing. Keep choices leave shared state and canonical dependency graphs intact. Execution rechecks each leaf with `lstat` and deletes a link itself, never its resolved target. Canonical content stays until recorded dependents are gone. Project uninstall-all never writes Global Installation; global uninstall-all never scans projects. For selected uninstall, missing paths, stale state, unowned replacements, divergent managed copies, and wrong-target links stop without a partial ownership change. For uninstall-all, those cases skip that skill, continue the rest, and report it as skipped. Interruption or failure leaves a durable recovery journal in installer state (`uninstall-journal.json`) and restores the failed skill so no active partial links remain. Human, dry-run, and JSON results report removed, retained, skipped, and failed skills. State and lock update only after filesystem operations commit. Project Installation is the default; Global Installation needs `--global` and `--yes`.
-
-### Sigma Installer: purge
-
-`npx @djordje-stojanovic/sigmaskills purge --dry-run` lists the exact ownership plan for one Project or Global scope: revalidated Sigma-owned trees, links or junctions, copies, backups, staging, journals, and relevant locks. Purge never infers ownership from folder names. `--yes`, CI, non-TTY, and JSON are not authority. Apply with the typed phrase `purge SigmaSkills`, or non-interactively with `--confirm-purge "purge SigmaSkills"`. Unexpected unowned occupants stop the command and stay untouched. Cross-filesystem deletes journal first and quarantine owned trees before the ownership manifest is removed. An interrupted cleanup leaves recoverable quarantined state rather than active partial links. Retry with the same confirmation phrase finishes the purge. Project purge never writes Global Installation; global purge never scans projects.
-
-### Sigma Installer: Agent Host registry automation
-
-The `registry-sync.yml` workflow fetches one pinned `vercel-labs/skills` revision as data and runs converter code only from the exact default-branch SHA in `EXPECTED_HEAD`. Generated changes are limited to `registry/agent-hosts.json`, `registry/source.json`, and `test/fixtures/vercel-skills/src/agents.ts`. New hosts must pass safe-root, traversal, collision, overlap, control-character, and platform checks. Only a generated pull request from that trusted workflow, with an exact allowlisted diff, the validated head SHA, current protected `main`, and all required checks may auto-merge. Validated additions and description-only edits can then publish a patch Release through the same idempotent trusted publication primitive as owner Releases. Path, ID, alias, detection, platform, membership, removal, unknown fields, and validation failures stay blocked for owner review. Version calculation serializes concurrent runs and reconciles npm and GitHub before the patch. The generated branch is deleted only after verified merge and matching npm/GitHub completion. Automation cannot change skills, CLI behavior, unrelated issues or pull requests, human branches, or major/minor Releases, and it never overwrites an existing npm version. Configure an npm trusted publisher for `registry-sync.yml` in addition to `release.yml`.
-
-### Sigma Installer: release
-
-`npx @djordje-stojanovic/sigmaskills release --dry-run` calculates the next semantic version and complete change set from the accepted source commit, then prints one publication preview: commit, version, required tests, tarball contents and SHA-256 digest, Skill Revisions, git tag, GitHub Release, npm package, and `latest` dist-tag. Ordinary merges never publish. `--yes`, CI, and informal text cannot dispatch. `--write-identities` writes matching `package.json`, `manifest.json`, and `CHANGELOG.md` identities so the owner can commit them. Dispatch requires `--expected-commit`, `--expected-version`, and `--expected-digest` that match that rebuilt preview. The trusted `release.yml` workflow independently checks out the approved commit, re-runs tests, rebuilds the tarball, and verifies those values before the publish job. Validation stays `contents: read`. Only the final job receives `id-token: write`, `contents: write`, and the protected `release` environment, with actions pinned by commit SHA. Missing npm reservation, trusted publisher, environment protection, or a conflicting version, tag, or GitHub Release fails closed with setup guidance. Matching npm provenance or an existing GitHub Release at the same commit is skipped rather than overwritten or duplicated.
-
-### Cross-host alternative
-
-The cross-agent [skills](https://github.com/vercel-labs/skills) CLI detects Codex, Claude Code, Cursor, OpenCode, Pi, and dozens more:
+### SigmaReview
 
-```bash
-# Everything, all detected agents, global
-npx skills add Djordje-Stojanovic/Sigmaskills --all -g -y
+Finds everything that breaks the system's own promises: bugs, security holes, slow paths, broken rendering, and weak tests. It measures performance and runs security probes only when you allow it, and only on a local instance. Each finding has a location, a mechanism, an impact, evidence, a fix, and a proof test, so an LLM can fix it from that finding alone. All findings go into `SIGMAREVIEW-YYYY-MM-DD.md` on one pull request. It never changes your code.
 
-# One skill at a time
-npx skills add Djordje-Stojanovic/Sigmaskills --skill sigmareview -g
-npx skills add Djordje-Stojanovic/Sigmaskills --skill sigmaperformance -g
-npx skills add Djordje-Stojanovic/Sigmaskills --skill sigmabrief -g
-npx skills add Djordje-Stojanovic/Sigmaskills --skill sigmawrite -g
+SigmaPerformance is retired. Its measurement method now lives in SigmaReview.
 
-# Pin to specific hosts
-npx skills add Djordje-Stojanovic/Sigmaskills --skill sigmawrite -g -a cursor -a claude-code -a codex -a opencode -a pi
+### SigmaImprove
 
-# List what this repo ships (no install)
-npx skills add Djordje-Stojanovic/Sigmaskills --list
-```
+Compares the product with the world's top one to three products and with published bars such as WCAG 2.2. It uses the product like a new user and keeps at least ten entries. An *idea* has three to five weighed options with sketches. A *signal* flags a gap that a person must think about first. Each category gets one living issue, so a run makes 1–20 issues, and later runs update them. It never edits the system.
 
-Full GitHub URL also works:
+### SigmaBrief
 
-```bash
-npx skills add https://github.com/Djordje-Stojanovic/Sigmaskills --skill sigmabrief -g
-```
+Turns GitHub issues, features, bugs, or plain work statements into short, copy-pastable briefs for other agents. It does light research, writes a dispatch list and fenced briefs, and then stops. It never implements the work. Each brief tells the agent to plan, build, check, and open a PR for review, and not to merge. Run it only when you ask for it by name.
 
-### Codex
+### SigmaShip
 
-```text
-$skill-installer install sigmareview from https://github.com/Djordje-Stojanovic/Sigmaskills
-$skill-installer install sigmaperformance from https://github.com/Djordje-Stojanovic/Sigmaskills
-$skill-installer install sigmabrief from https://github.com/Djordje-Stojanovic/Sigmaskills
-$skill-installer install sigmawrite from https://github.com/Djordje-Stojanovic/Sigmaskills
-```
+Ships one GitHub issue that has acceptance criteria. It opens a worktree, a branch, and a draft PR that tracks the criteria and review rounds. It builds test-first and pushes each slice. Fresh agents then review the branch in rounds until one round finds nothing at P0–P2. Then it merges, closes the ticket, removes the branches and worktree, and checks that local `main` equals `origin/main`. It refuses a ticket without checkable criteria and names the skill to run first.
 
-### Manual / universal copy
-
-When a host only watches a skills folder (Pi, LAPI mirrors, custom TUIs, air-gapped boxes):
-
-**POSIX**
+### SigmaWrite
 
-```bash
-git clone https://github.com/Djordje-Stojanovic/Sigmaskills.git
-mkdir -p ~/.agents/skills
-cp -R Sigmaskills/sigmareview ~/.agents/skills/sigmareview
-cp -R Sigmaskills/sigmaperformance ~/.agents/skills/sigmaperformance
-cp -R Sigmaskills/sigmabrief ~/.agents/skills/sigmabrief
-cp -R Sigmaskills/sigmawrite ~/.agents/skills/sigmawrite
-```
+A writing voice inspired by **ASD-STE100 Simplified Technical English**. It gives soft steers, not numbered rules, and bans gibberish and invented words. A sharp outsider can follow the result, and it stays technical. It stays on until you turn it off. To keep the voice on everywhere, copy the **Paste as system prompt** block from [`sigmawrite/SKILL.md`](sigmawrite/SKILL.md) into your host's instructions. It is not certified STE.
 
-**Windows (PowerShell)**
+### SigmaRefactor
 
-```powershell
-git clone https://github.com/Djordje-Stojanovic/Sigmaskills.git
-New-Item -ItemType Directory -Force -Path "$HOME\.agents\skills" | Out-Null
-Copy-Item -Recurse Sigmaskills\sigmareview   "$HOME\.agents\skills\sigmareview"
-Copy-Item -Recurse Sigmaskills\sigmaperformance "$HOME\.agents\skills\sigmaperformance"
-Copy-Item -Recurse Sigmaskills\sigmabrief    "$HOME\.agents\skills\sigmabrief"
-Copy-Item -Recurse Sigmaskills\sigmawrite    "$HOME\.agents\skills\sigmawrite"
-```
+Runs a `laloc` scan, reads the five largest maintained files, and explains safe refactoring choices. It waits for your approval before it edits. It keeps behavior, tests, interfaces, and your own changes intact. At the end it reports lines removed apart from lines moved into new modules.
 
-Point other hosts at the same folders (or copy again) as needed:
+---
 
-| Host family | Typical skills path |
-|-------------|---------------------|
-| Universal / Codex-style | `~/.agents/skills/<id>/` |
-| Cursor | `~/.cursor/skills/<id>/` or project `.agents/skills/` |
-| Claude Code | `~/.claude/skills/<id>/` |
-| Pi / LAPI-style | `~/.pi/agent/skills/<id>/` |
-| OpenCode | `~/.config/opencode/skills/<id>/` |
-| Codex | `~/.codex/skills/<id>/` |
+## Install
 
-Release zip: download [**Sigmaskills-v0.2.0**](https://github.com/Djordje-Stojanovic/Sigmaskills/releases/tag/v0.2.0) and copy the four skill folders into the path your agent reads.
+Pick one method. The [installer guide](https://github.com/Djordje-Stojanovic/Sigmaskills/blob/main/docs/installer.md#other-install-methods) has the full per-skill commands and host folders.
 
-### Optional: SigmaWrite as system prompt
+| Method | Command | Best for |
+|--------|---------|----------|
+| **Sigma Installer** (recommended) | `npx @djordje-stojanovic/sigmaskills install --all --project .` | Project or Global Installation with status, update, restore, and uninstall |
+| **`npx skills`** | `npx skills add Djordje-Stojanovic/Sigmaskills --all -g -y` | Every agent that the [skills](https://github.com/vercel-labs/skills) CLI detects |
+| **Codex** | `$skill-installer install <id> from https://github.com/Djordje-Stojanovic/Sigmaskills` | Codex only |
+| **Manual copy** | `git clone` this repository, then copy `<id>/` into `~/.agents/skills/` | Air-gapped machines and hosts that only watch a folder |
 
-Open [`sigmawrite/SKILL.md`](sigmawrite/SKILL.md), copy the **Paste as system prompt** block into host instructions when you want the voice always on — without editing this repo’s release contract.
+Every [GitHub Release](https://github.com/Djordje-Stojanovic/Sigmaskills/releases) matches the npm package of the same version.
 
 ---
 
 ## Run
 
-Use your host’s skill syntax. Examples:
+Use your host's skill syntax. Examples:
 
 <table>
 <tr>
@@ -208,10 +122,12 @@ Use your host’s skill syntax. Examples:
 
 ```text
 $sigmareview https://github.com/owner/repo
-$sigmaperformance https://github.com/owner/repo
+$sigmaimprove
 $sigmabrief https://github.com/owner/repo/issues/12
 $sigmabrief all open
+$sigmaship https://github.com/owner/repo/issues/42
 $sigmawrite
+$sigmarefactor
 ```
 
 </td>
@@ -221,121 +137,55 @@ $sigmawrite
 
 ```text
 /skill:sigmareview https://github.com/owner/repo
-/skill:sigmaperformance https://github.com/owner/repo
+/skill:sigmaimprove
 /skill:sigmabrief https://github.com/owner/repo/issues/12
 /skill:sigmabrief all open
+/skill:sigmaship https://github.com/owner/repo/issues/42
 /skill:sigmawrite
+/skill:sigmarefactor
 ```
 
 </td>
 </tr>
 </table>
 
-**Claude Code · Cursor · OpenCode · ChatGPT/Codex UI · Reasonix-class · Kimi/Muse · others**  
-Use the skill picker, `@` / `$` skill mention, or whatever that product documents for Agent Skills. Folder name = skill id = invocation token.
-
-| Skill | Typical invoke | Notes |
-|-------|----------------|-------|
-| `sigmareview` | repo URL | Needs push/fork rights for the report PR |
-| `sigmaperformance` | repo URL | Starts with two short calibration batches, then runs |
-| `sigmabrief` | issue URL · `#N` · `all open` · plain work | Explicit only — not ambient |
-| `sigmawrite` | (no args) | Session writing voice until you turn it off |
-
----
-
-## Output contracts
-
-### SigmaReview
-
-- File: `SIGMAREVIEW-FINDINGS-YYYY-MM-DD.md`
-- One dedicated branch + **report-only** PR
-- Prioritized, confidence-gated findings with exact evidence
-- Implementation-ready remediation and verification steps
-- Full repository coverage ledger
-- **No** source fixes, dependency installs, app execution, subagents, or auxiliary repo artifacts
-
-### SigmaPerformance
+**Claude Code · Cursor · OpenCode · ChatGPT/Codex UI · Reasonix-class · Kimi/Muse · others:** use the skill picker, an `@` or `$` mention, or whatever the product documents for Agent Skills. The folder name is the skill id and the call token.
 
-- File: `SIGMAPERFORMANCE-REPORT-YYYY-MM-DD.md`
-- One dedicated **report-only** PR
-- **M1** measured · **M2** mechanically proven bottlenecks
-- **M3** measurement-required opportunities, failed experiments, unverified boundaries (accounted separately)
-- Structured future SigmaOptimize handoff
-- Default single-agent; bounded subagents only via explicit calibration opt-in
-- **No** runtime-source changes or temp measurement junk in the repo diff
+| Skill | Typical input | Notes |
+|-------|---------------|-------|
+| `sigmareview` | repo URL · path | One setup message (authority, goals), then runs alone |
+| `sigmaimprove` | repo · path · running product | One setup message (vision, focus, constraints, ticket place), then discusses ideas |
+| `sigmabrief` | issue URL · `#N` · `all open` · plain work | Only when you ask for it |
+| `sigmaship` | issue URL · `#N` | Refuses tickets without checkable acceptance criteria |
+| `sigmawrite` | (no input) | Session writing voice until you turn it off |
+| `sigmarefactor` | repository path or current repository | Scans and discusses large files before any edit |
 
-### SigmaBrief
-
-- Chat-only dispatch list + paste-ready fenced `text` briefs  
-  (**no** `SIGMABRIEF-*.md` in the product repo)
-- Types: greenfield · finish-PR · skip · blocked
-- Executing briefs: plan first · optional grill-me · **do not merge** · self-review before PR
-- Isolation on → agent-created Windows `git worktree`; cleanup only after human merge or abandon
-- Never implements the work or opens product fix PRs
-
-### SigmaWrite
-
-- Chat writing style only (no report file, no PR)
-- Soft STE-inspired steers + hard bans (gibberish / invented words / talking down / renaming code)
-- Optional pasteable system-prompt block in `SKILL.md`
-- Does not override another skill’s rigid output contract
-
----
-
-## Requirements
+### Requirements
 
 | Skill | Needs |
 |-------|--------|
-| All | Agent that can load Agent Skills (`SKILL.md`) |
-| SigmaReview · SigmaPerformance | Read access to the target repo · authenticated GitHub tooling to push a branch or fork + open a PR |
-| SigmaPerformance | Authority / safety boundary chosen in calibration |
-| SigmaBrief | `gh` read when briefing from issues/PRs · **no** push to the product repo |
-| SigmaWrite | Nothing beyond chat — optional paste into system instructions |
+| All | An agent that can load Agent Skills (`SKILL.md`) |
+| SigmaReview | Read access to the target repo · GitHub tooling to push a branch or fork and open a PR · execution authority only if you want measured findings |
+| SigmaImprove | Read access to the target · GitHub issue access only if tickets go to GitHub |
+| SigmaShip | Push rights and GitHub tooling (`gh` or connector) to open, merge, and close; the repository's test commands |
+| SigmaBrief | `gh` read access when briefing from issues or PRs · **no** push to the product repo |
+| SigmaWrite | Nothing beyond chat |
+| SigmaRefactor | Read access to the target repository and `laloc` when available |
 
-Windows-native defaults where skills mention shells or worktrees (PowerShell-friendly; do not assume WSL).
+Where skills mention shells or worktrees, they default to native Windows (PowerShell-friendly; no WSL assumed).
 
 ---
 
-## Repo layout
-
-```text
-Sigmaskills/
-├── AGENTS.md                 Agent working contract
-├── README.md · CHANGELOG.md · LICENSE · package.json
-├── test/                     Structural regression tests (npm test)
-├── .github/                  Issue forms · PR template · CI
-├── sigmareview/              SKILL.md · agents/ · references/
-├── sigmaperformance/         SKILL.md · agents/ · references/
-├── sigmabrief/               SKILL.md · agents/ · references/
-└── sigmawrite/               SKILL.md · agents/
-```
-
-Each top-level folder is one installable skill. `name` in frontmatter = folder name = `--skill` id.
-
-Agents working in this repo should read [`AGENTS.md`](AGENTS.md).
-
----
-
-## Testing
-
-Zero-dependency Node tests guard the beauty: skill registry, `SKILL.md` frontmatter, `agents/openai.yaml`, README install/run wiring, CHANGELOG, issue templates, agent docs, and SigmaWrite’s soft-steer contract.
+## Links
 
-```bash
-npm test
-```
-
-CI runs the same suite on Windows, macOS, and Linux for Node.js 20 and 22, on every pull request and every push to `main`. Those jobs cover real junctions or symbolic links, copy fallback, shell differences, and an isolated temp filesystem.
-
-When you **add or rename a skill**, update `KNOWN_SKILLS` in [`test/repo-invariants.test.js`](test/repo-invariants.test.js) in the same change as README and CHANGELOG — otherwise CI fails on purpose. That rule also lives in [`AGENTS.md`](AGENTS.md).
-
----
-
-## Contributing & issues
-
-Use the issue chooser: [New issue](https://github.com/Djordje-Stojanovic/Sigmaskills/issues/new/choose)  
-Bug · Feature · Improvement · Docs — written for skills, prompts, and templates (not unrelated product apps).
-
----
+- [Installer guide](https://github.com/Djordje-Stojanovic/Sigmaskills/blob/main/docs/installer.md): every command, flag, and install method
+- [Maintainer guide](https://github.com/Djordje-Stojanovic/Sigmaskills/blob/main/docs/maintainers.md): tests, CI, releases, and registry automation
+- [Skill evals](https://github.com/Djordje-Stojanovic/Sigmaskills/blob/main/docs/evals.md): how each skill's output is checked, and the latest results
+- [CHANGELOG.md](CHANGELOG.md): what changed in each Release
+- [AGENTS.md](https://github.com/Djordje-Stojanovic/Sigmaskills/blob/main/AGENTS.md): the working rules for agents in this repository
+- [CONTEXT.md](https://github.com/Djordje-Stojanovic/Sigmaskills/blob/main/CONTEXT.md): the words this project uses, such as Skill Pack and Agent Host
+- [Decision records](https://github.com/Djordje-Stojanovic/Sigmaskills/tree/main/docs/adr): why the installer works the way it does
+- [New issue](https://github.com/Djordje-Stojanovic/Sigmaskills/issues/new/choose): bug, feature, improvement, or docs
 
 ## License
 

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "name": "sigmaskills",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Portable Agent Skills monorepo and first-party Sigma Installer",
   "skills": [
     {
@@ -10,8 +10,8 @@
       "needsReferences": true
     },
     {
-      "id": "sigmaperformance",
-      "title": "SigmaPerformance",
+      "id": "sigmaimprove",
+      "title": "SigmaImprove",
       "needsReferences": true
     },
     {
@@ -19,10 +19,23 @@
       "title": "SigmaBrief",
       "needsReferences": true
     },
+    {
+      "id": "sigmaship",
+      "title": "SigmaShip",
+      "needsReferences": true
+    },
     {
       "id": "sigmawrite",
       "title": "SigmaWrite",
       "needsReferences": false
+    },
+    {
+      "id": "sigmarefactor",
+      "title": "SigmaRefactor",
+      "needsReferences": true
     }
+  ],
+  "retired": [
+    "sigmaperformance"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djordje-stojanovic/sigmaskills",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Portable Agent Skills monorepo and first-party Sigma Installer",
   "type": "module",
   "bin": {
@@ -15,9 +15,11 @@
     "registry/skill-baselines.json",
     "manifest.json",
     "sigmareview",
-    "sigmaperformance",
+    "sigmaimprove",
     "sigmabrief",
+    "sigmaship",
     "sigmawrite",
+    "sigmarefactor",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -36,7 +38,8 @@
   "scripts": {
     "prepack": "node ./src/prepack.js",
     "test": "node scripts/run-tests.js",
-    "registry:sync": "node ./src/registry/sync.js",
+    "release": "node scripts/release.js",
+    "registry:sync": "node ./scripts/registry/sync.js",
     "registry:validate": "node ./test/registry-validate-cli.mjs"
   }
 }