oh-my-space 0.10.0 → 0.11.1

package/README.md

@@ -43,6 +43,8 @@ repos:
     branch: main # optional; defaults to the remote's default branch
 ```
 
+After scaffolding, `oms init` prints optional AI-setup hints pointing to [`oms agent install`](#ai-agent-workflow) and [`oms skills`](#workspace-skills); both are opt-in and install nothing on their own.
+
 Sync the declared repositories and check their state:
 
 ```bash
@@ -104,6 +106,29 @@ When an AI coding agent works in a workspace, the main risk is operating in the
 
   These are **root-repository files under `oms/`, not submodule files**. The managed block is delimited by `<!-- OMS START -->` / `<!-- OMS END -->`; content outside the markers is preserved, and `oms agent uninstall` removes only that block (deleting the file if it becomes empty). The files are created but never staged, so you review and commit them yourself.
 
+## Workspace skills
+
+`oms` publishes three installable agent skills that carry the workspace Git guardrail to sessions started anywhere in the workspace — including at the root, which the [`oms agent install`](#ai-agent-workflow) marker under `oms/` cannot reach. They are installed with the external Vercel Labs `skills` tool (`npx skills`):
+
+```bash
+npx skills add divlook/oh-my-space                       # project scope: install at the workspace root
+npx skills add divlook/oh-my-space -g                    # global scope: available in every workspace
+npx skills add divlook/oh-my-space --skill oms-pointer   # install one skill by name
+npx skills add divlook/oh-my-space --list                # list the available skills without installing
+```
+
+Project scope is the default and recommended: these skills are only relevant in an `oms.yaml` workspace, so a project install keeps them out of unrelated repositories. `oms skills` prints these commands, and `oms skills --install` runs the project install for you, resolving to the workspace root first and forwarding extra arguments (`-g`, `--skill`, `--list`, `--copy`) straight through.
+
+The three skills are named by the Git domain each manages:
+
+| Skill | Use it when | What it does |
+| --- | --- | --- |
+| `oms-workspace` | Scope-ambiguous Git work in the workspace — committing from the root, a moved `oms status` pointer, a push, or adding/removing a repo with `oms sync`/`oms unsync`. | Establishes workspace state and root-versus-submodule scope before acting, and separates repo add/remove topology from recording a moved pointer. |
+| `oms-pointer` | After `oms commit` or `oms pull` moves a submodule's commit. | Records the moved root pointer with `oms record`, so a submodule change is not left without a recorded pointer and the root pointer is not committed by mistake. |
+| `oms-branch` | Starting or switching a branch inside a submodule. | Chooses `oms switch` (new local branch) versus `oms checkout` (track a remote branch) and avoids detached HEAD. |
+
+Skill firing is best-effort — an agent loads a skill only when it judges the skill's description relevant — so the skills complement, rather than replace, `oms <command> --help` and the always-on marker block inside `oms/`. Each skill defers exact `oms status --json` field semantics to `oms status --help`, the version-matched authoritative source that ships with the installed CLI.
+
 ## Command reference
 
 `oms.yaml` declares each source repo with `alias`, a `remotes` mapping (which must include `origin`), and optional `branch` (the baseline).
@@ -123,6 +148,7 @@ When an AI coding agent works in a workspace, the main risk is operating in the
 | `oms push <alias>...` | workspace root | `git push <remote> <branch>` (creating the remote branch on first push). | Submodule branch only — never stages or commits the root gitlink. `--commit`/`--record` are unsupported; record the root pointer with `oms record <alias>`. `--remote <name>` (repeatable) picks the remote(s); upstream is set only for `origin`. |
 | `oms unsync <alias>` / `--all` | workspace root | `git submodule deinit` + `git rm` for the alias; drops an empty `.gitmodules`. | Keeps the `oms.yaml` entry. Use `--force` to discard uncommitted changes. Removal topology is left unstaged by default; commit via the prompt or `--commit` (`chore(oms): remove ...`). |
 | `oms agent install` / `uninstall` | workspace root | Manages a marker-delimited OMS instruction block in `oms/AGENTS.md` and/or `oms/CLAUDE.md` (root-repo files). | `--target agents\|claude\|both` (omit to choose interactively). Does not stage files. See [AI agent workflow](#ai-agent-workflow). |
+| `oms skills` | anywhere (`--install` resolves to root) | Prints the `npx skills add divlook/oh-my-space` commands (project scope and `-g` global) to install the workspace skills. | `--install` delegates to `npx skills add`, forwarding extra args (`-g`, `--skill <name>`, `--list`). Run outside a workspace without `-g`, it errors and points to the global install. See [Workspace skills](#workspace-skills). |
 | `oms update` | anywhere | Checks the npm registry and safely updates the installed `oms` CLI only when it detects a confident global install. | Use `--check` for a non-mutating check. Use `--yes` to skip the confirmation prompt for confident global updates. Project-local, temporary runner, development, and unknown installs print guidance only. |
 
 ## Updating the CLI
@@ -176,37 +202,11 @@ Rules:
 
 JSON schema: [`oms.schema.json`](./oms.schema.json) (also reachable at `https://raw.githubusercontent.com/divlook/oh-my-space/main/oms.schema.json` for YAML LSPs).
 
-## Behavior changes
-
-The AI-submodule-workflow update scopes each command to a single Git boundary and makes root pointer commits explicit. If you have existing automation, note these changes:
-
-- **`oms push --commit` is removed** (and `oms push --record` is unsupported). It fails before pushing. Push the submodule branch, then record the root pointer separately:
-
-  ```bash
-  # before
-  oms push api --commit
-
-  # after
-  oms push api      # pushes the submodule branch only
-  oms record api    # commits the moved oms/api pointer in the parent
-  ```
-
-- **`oms pull` and `oms push` no longer stage the root gitlink.** They synchronize only the submodule branch; the moved pointer shows up in `git status` and is committed with `oms record <alias>`.
-
-- **`oms sync` and `oms unsync` no longer leave the root index staged.** Topology changes (`.gitmodules` and `oms/<alias>`) stay in the working tree, unstaged. Create the topology commit through the interactive prompt or with `--commit`:
-
-  ```bash
-  # before: sync left .gitmodules + oms/api staged for you to commit
-  oms sync api && git commit -m "add api"
-
-  # after: topology is unstaged by default
-  oms sync api --commit   # creates chore(oms): add api submodule
-  ```
-
 ## Migration guides
 
 Detailed migration steps are organized per version under [`docs/migrations/`](./docs/migrations/).
 
+- [0.9.x → 0.10.0](./docs/migrations/0.9.x-to-0.10.0.md) — scopes each command to a single Git boundary and makes root pointer commits explicit via `oms record`
 - [0.7.x → 0.8.0](./docs/migrations/0.7.x-to-0.8.0.md) — splits `oms checkout` into `oms switch` (local branches) and `oms checkout` (remote branches)
 - [0.5.x → 0.6.0](./docs/migrations/0.5.x-to-0.6.0.md) — switches the data model from bare clone + worktrees back to git submodules
 - [0.3.x → 0.4.0](./docs/migrations/0.3.x-to-0.4.0.md) — renames `sources.yaml`/`sources/` to `oms.yaml`/`oms/`

package/dist/build-info.json

@@ -1 +1 @@
-{"commit":"0cc84f79dc3659f53fd76a39f9e5ecbe33337651"}
+{"commit":"b7828e49a17a0e77babec31f989a37b19ea57fe3"}

package/dist/oms.js

@@ -2014,14 +2014,16 @@ async function finalizeTopology(repoRoot, requested, kind, commit, allSucceeded)
 }
 const OMS_MARKER_START = "<!-- OMS START -->";
 const OMS_MARKER_END = "<!-- OMS END -->";
-/** Concise, durable agent rules; detailed usage is deferred to CLI help. */
+/** Canonical scope-guardrail kernel, single-sourced into the marker block and each published SKILL.md. */
+const OMS_SCOPE_GUARDRAIL = `- Run \`oms status --json\` before Git work involving \`oms/\` to read root versus submodule state.
+- Treat each \`oms/<alias>/\` directory as a separate Git repository.
+- Use \`oms\` commands for scoped submodule workflows; do not guess root repository versus submodule Git scope.
+- Do not create root commits for existing submodule pointer updates unless the user explicitly runs \`oms record <alias>\`.`;
+/** Concise, durable agent rules; detailed usage is deferred to CLI help. The marker's own --help line stays outside the kernel constant. */
 const OMS_INSTRUCTION_BLOCK = `${OMS_MARKER_START}
 ## OMS Workspace Rules
 
-- Run \`oms status --json\` before Git work involving \`oms/\` to read root versus submodule state.
-- Treat each \`oms/<alias>/\` directory as a separate Git repository.
-- Use \`oms\` commands for scoped submodule workflows; do not guess root repository versus submodule Git scope.
-- Do not create root commits for existing submodule pointer updates unless the user explicitly runs \`oms record <alias>\`.
+${OMS_SCOPE_GUARDRAIL}
 - Check \`oms --help\` and \`oms <command> --help\` for exact command usage.
 ${OMS_MARKER_END}`;
 function countOccurrences(haystack, needle) {
@@ -2171,6 +2173,45 @@ async function runAgentUninstall(options) {
     }
     return 0;
 }
+/** npx skills package identifier for the oms workspace skills. */
+const SKILLS_REPO = "divlook/oh-my-space";
+/** Extra args forwarded to "npx skills add", read from argv so flags pass through verbatim. */
+function skillsForwardedArgs() {
+    // process.argv: [node, oms.js, "skills", ...rest]; drop the "--install" flag and forward the rest.
+    return process.argv.slice(3).filter((arg) => arg !== "--install");
+}
+/** Print the install commands, or with --install delegate to "npx skills add" from the workspace root. */
+async function runSkills(install, extraArgs) {
+    const projectCommand = `npx skills add ${SKILLS_REPO}`;
+    const globalCommand = `${projectCommand} -g`;
+    if (!install) {
+        log.info("Install the oms workspace skills with the skills tool:");
+        log.message(`  ${projectCommand}        # project scope (run at the workspace root)`);
+        log.message(`  ${globalCommand}     # global scope (every workspace)`);
+        log.message("Add --skill <name> to install one (oms-workspace, oms-pointer, oms-branch), or --list to list them.");
+        return 0;
+    }
+    const wantsGlobal = extraArgs.includes("-g") || extraArgs.includes("--global");
+    const workspaceRoot = findWorkspaceRoot();
+    if (!workspaceRoot && !wantsGlobal) {
+        log.error(`"oms skills --install" must run inside an ${MANIFEST_FILENAME} workspace. ` +
+            `For a global install from anywhere, run: ${globalCommand}`);
+        return 1;
+    }
+    const args = ["skills", "add", SKILLS_REPO, ...extraArgs];
+    const npxBin = testEnv("OMS_NPX_BIN") ?? "npx";
+    const result = spawnSync(npxBin, args, {
+        stdio: "inherit",
+        cwd: workspaceRoot ?? process.cwd(),
+        shell: runtimePlatform() === "win32",
+    });
+    if (result.error || result.status === null) {
+        log.error(`Could not run "${[npxBin, ...args].join(" ")}".`);
+        log.message(`Install the skills manually: ${projectCommand}`);
+        return 1;
+    }
+    return result.status;
+}
 const INIT_TEMPLATE = `# yaml-language-server: $schema=https://raw.githubusercontent.com/divlook/oh-my-space/main/oms.schema.json
 repos:
   - alias: example
@@ -2194,6 +2235,10 @@ async function runInit(options) {
         log.info(`oms manages sources as git submodules; run "git init" here if this is not a git repo yet.`);
     }
     log.info(`edit alias/remotes/branch, then run "oms sync".`);
+    // Signpost the optional AI-setup commands; output-only, installs nothing.
+    log.info("Optional — set up AI agent guidance for this workspace:");
+    log.message(`  oms agent install   # add the OMS instruction block for AI agents`);
+    log.message(`  oms skills          # show how to install the oms workspace skills`);
     return 0;
 }
 async function runDoctor() {
@@ -2420,7 +2465,12 @@ async function exitWith(action) {
 const exitHelp = "\nExit codes: 0 ok | 1 usage/config error | 2 one or more git operations failed.";
 // Per-command help: each new or changed command states its purpose, scope boundary, and an example.
 const statusHelp = `
-Machine-readable mode prints exactly one JSON object on stdout (schemaVersion, root, repos, pointers).
+Machine-readable mode prints exactly one JSON object on stdout. The schemaVersion 1 payload has seven
+top-level keys: schemaVersion, toolVersion, workspaceRoot, currentAlias, root, repos, and errors.
+Submodule pointer movement lives under root.submodulePointers, with moved, staged, split, and conflict
+arrays (not a top-level "pointers" key). Each repos[] entry summarizes one oms/<alias>/ submodule
+(alias, path, branch, head, pin, dirty, ahead/behind, error). Read the live --json output for exact
+per-field values.
 Examples:
   $ oms status --json          # full workspace state for tools and agents
   $ oms status api --json      # narrow the JSON to one alias
@@ -2477,6 +2527,18 @@ Removes the marker-delimited OMS block; a file left empty is deleted. Missing fi
 Example:
   $ oms agent uninstall --target both
 `;
+const skillsHelp = `
+Installs the oms workspace skills (oms-workspace, oms-pointer, oms-branch) via the external "skills" tool.
+Project scope (installed at the workspace root, discovered from the root and its subdirectories) is the
+default; -g installs globally for every workspace. With --install, oms resolves to the workspace root and
+delegates to "npx skills add", forwarding extra arguments (-g, --skill <name>, --list, --copy) straight
+through to the skills tool.
+Examples:
+  $ oms skills                                # print the project and global install commands
+  $ oms skills --install                      # install the skills project-scoped at the workspace root
+  $ oms skills --install -g                    # install the skills globally
+  $ oms skills --install --skill oms-branch    # install one skill
+`;
 const commandNames = new Set([
     "init",
     "doctor",
@@ -2491,6 +2553,7 @@ const commandNames = new Set([
     "push",
     "unsync",
     "agent",
+    "skills",
     "update",
     "help",
 ]);
@@ -2636,6 +2699,16 @@ agentCommand
     .action(async (options) => {
     await exitWith(runAgentUninstall(options));
 });
+program
+    .command("skills")
+    .description("Print the command to install the oms workspace skills, or run it with --install.")
+    .option("--install", "delegate to \"npx skills add\" (forwards extra args such as -g, --skill, --list)")
+    .allowUnknownOption()
+    .argument("[args...]", "extra arguments forwarded to \"npx skills add\" with --install")
+    .addHelpText("after", `${skillsHelp}${exitHelp}`)
+    .action(async (_args, options) => {
+    await exitWith(runSkills(Boolean(options.install), skillsForwardedArgs()));
+});
 program
     .command("update")
     .description("Check for and safely update the oms CLI. Only confident global installs are updated automatically.")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-space",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Manage multi-repo workspaces with Git submodules.",
   "license": "MIT",
   "homepage": "https://github.com/divlook/oh-my-space",