opencode-skills-collection 4.0.0 → 4.0.1

package/bundled-skills/lore/references/compatibility.md

@@ -0,0 +1,228 @@
+# Compatibility policy
+
+This document defines how `lore` evolves without breaking existing user projects. It is the contract between current users and future maintainers. Any change to `.lore/` structure, file formats, Python scripts, mirror templates, or this skill's reference docs must conform to these rules.
+
+## Three principles
+
+1. **Add, never subtract.** New fields, scripts, sections, and reference docs always use new names. Removal happens only after the deprecation cycle (below).
+2. **Readers are forward-compatible.** An older skill reading a newer `.lore/` ignores unknown fields, unknown files, and unknown tags. It never errors on unfamiliar content.
+3. **Writers are backward-compatible (during transition).** A newer skill detecting an older `.lore/` runs a migration step before writing. It never overwrites old data with new defaults.
+
+## Layer-specific rules
+
+### Layer 1: `.lore/.config.json` schema
+
+- `schema_version` is **required** (integer). See `references/config.md` for handling missing/newer/older values.
+- Adding a new field = bump `schema_version` to N+1; old fields stay; the field is added with its default value at first read.
+- Removing a field requires the deprecation cycle (one schema version's worth of warnings before hard removal).
+- Renaming a field: write the new field, copy the value, mark the old one with `_deprecated: "reason"`. The migration tool handles this in `migrate.py`.
+
+### Layer 2: Entry format
+
+```
+- [ARCH-2026-07-10-a3f2] Entry text; reason. #added:2026-07-10 #verified:2026-07-15
+```
+
+- IDs (`LAYER-DATE-HASH`) are stable as long as the entry text is unchanged. Editing an entry produces a new ID; old ID stays in history (via git) for `history` queries.
+- Tag set is a closed set today: `#added`, `#verified`, `#stale`, `#archived`. Adding a new tag is allowed; old skills' tag parsers (which match `(added|verified|stale|archived)`) silently ignore unknown tags.
+- **Never make a tag required.** Required tags break every old entry in every old `.lore/`.
+
+### Layer 3: `.lore/` directory structure
+
+Current canonical layout:
+
+```
+.lore/
+├── SUMMARY.md
+├── _global/
+├── scopes/
+├── draft/        (init only — temporary)
+├── audit/        (audit only)
+└── archive/      (referenced in spec; reserved for future)
+```
+
+Rules:
+
+- Adding a new top-level directory (e.g., `rejected/` for rejected entries) is non-breaking.
+- Renaming an existing directory is breaking — every reference in `references/*.md`, every script, and every user's project breaks.
+- Removing a directory is breaking unless that directory was never actually written (e.g., removing `archive/` today is non-breaking because nothing writes there yet).
+
+### Layer 4: Python scripts
+
+Current scripts: `id_hash.py`, `list_entries.py`, `find_stale.py`, `find_duplicates.py`, `history.py`, plus planned `migrate.py`.
+
+Rules:
+
+- **Renaming is breaking.** All names are part of the public surface; they're referenced from `SKILL.md`, `references/*.md`, and downstream tooling. Don't rename; deprecate and add a new one if needed.
+- **Removing is breaking.** A deprecated script stays on disk with a clear "Deprecated: use `migrate.py` instead" header for one schema version.
+- **Adding a new script is non-breaking.** Reference it from `SKILL.md` reference index on introduction.
+- **Changing output format is breaking for `--json` consumers.** Add `--v2-output` or a new flag; old flag keeps old behavior forever.
+
+### Layer 5: Platform mirror files
+
+Mirror files (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`, etc.) follow this contract:
+
+```markdown
+## Lore (auto-managed)
+
+... lore content ...
+
+---
+## My notes (free edit)
+
+... user content (preserved verbatim) ...
+```
+
+Rules:
+
+- `## Lore (auto-managed)` is a **contract string**. Never rename; never remove. Mirror detection regexes depend on it.
+- `## My notes (free edit)` is a **contract string**. Never rename; never remove. User-written content depends on it.
+- The content between `## Lore` and `---` is lore's domain; content after `---` is the user's. Respect the boundary on every regeneration.
+- Adding a new auto-managed section (e.g., `## Sync history (auto-managed)`) is allowed; insert before `---`. Old skills ignore it.
+- Changing the index template body (e.g., adding a "Last mirror:" line) is non-breaking: content-based dedup means unchanged mirrors are not rewritten, so old mirrors stay valid.
+- **Backward-write safety**: if the existing mirror has no `## My notes (free edit)` section (e.g., a legacy single-section mirror from a pre-v1 project), the first `lore mirror` run must **append** an empty My notes section rather than overwriting the file.
+
+### Layer 6: reference docs
+
+Current docs: `entry-format.md`, `summary-template.md`, `audit-template.md`, `monorepo-detection.md`, `stale-new-markers.md`, `platform-mirrors.md`, `config.md`, `history-command.md`, `compatibility.md` (this file).
+
+Rules:
+
+- **Renaming a reference doc is breaking.** Every external link (issue trackers, blog posts, README badges) breaks. Add a redirect stub instead.
+- **Splitting a doc** (e.g., `platform-mirrors.md` → `mirror-index.md` + `mirror-takeover.md`) requires a stub at the old path that points to the new location. Update `SKILL.md` reference index on the same commit.
+- **Removing a doc** is breaking. Mark it `<!-- DEPRECATED: see new-location.md -->` for one schema version, then move to `archive/` (in `references/`, not in `.lore/`).
+- **Adding a doc** is non-breaking. Add to `SKILL.md` reference index on introduction.
+
+## Migration tool
+
+`scripts/migrate.py` does not exist in v1. It will be added on the first `schema_version` bump.
+
+**Triggers that will ship the first migration:**
+
+- A new required field is added to `.lore/.config.json`.
+- A field is renamed or its accepted values are tightened.
+- The entry ID algorithm changes.
+
+Until any of these happen, `schema_version: 1` is the only version and no migration is possible or needed.
+
+Until the script ships, `list_entries.py` emits a one-time warning to stderr if `.lore/.config.json` is missing the `schema_version` field. This nudges users to add the field manually before the first breaking change ships, so future upgrades can detect the version mismatch correctly.
+
+**Template — to be implemented when the first migration is needed:**
+
+```python
+#!/usr/bin/env python3
+"""Migrate .lore/.config.json from version N to N+1.
+
+Idempotent: running twice produces no further changes.
+Refuses to run if schema_version > EXPECTED_FROM.
+"""
+import json, sys
+from pathlib import Path
+
+EXPECTED_FROM = 1   # versions this script can read
+TARGET = 2          # current schema version after migration
+
+
+def migrate(config: dict) -> tuple[dict, list[str]]:
+    msgs = []
+    # v1 → v2 transformations go here. Example:
+    # if config.get("mirror_mode") == "summary":
+    #     config.pop("mirror_mode", None)
+    #     msgs.append('removed deprecated "mirror_mode": "summary"')
+    config["schema_version"] = TARGET
+    return config, msgs
+
+
+def main() -> int:
+    cfg_path = Path(".lore/.config.json")
+    if not cfg_path.exists():
+        print(f"error: {cfg_path} not found", file=sys.stderr)
+        return 1
+    cfg = json.loads(cfg_path.read_text(encoding="utf-8"))
+    current = cfg.get("schema_version", 1)
+    if current > EXPECTED_FROM:
+        print(
+            f"error: schema_version={current} is newer than this skill "
+            f"can read (max: {EXPECTED_FROM}). Pull latest lore.",
+            file=sys.stderr,
+        )
+        return 2
+    if current < TARGET:
+        print(f"migrating v{current} → v{TARGET}...")
+    cfg, msgs = migrate(cfg)
+    for m in msgs:
+        print(f"  - {m}")
+    cfg_path.write_text(json.dumps(cfg, indent=2) + "\n", encoding="utf-8")
+    print("done.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+```
+
+## Deprecation workflow
+
+Any capability slated for removal follows a three-stage cycle. The minimum cycle is **two schema versions** (typically 6–12 months).
+
+| Stage | Schema version | Behavior |
+|---|---|---|
+| **Announce** | N | Add an entry to `references/deprecations.md` with the feature name, replacement, and removal target version. The skill prints a one-line notice when the feature is used. |
+| **Warn** | N+1 | The skill prints a louder warning (with remediation steps) and writes a `_deprecation_warnings_shown` array to `.lore/.config.json` so the warning doesn't repeat. |
+| **Remove** | N+2 | Hard delete. Old `.lore/` data is migrated by `migrate.py` to the new format. Users who skipped migrations will see explicit errors pointing at `migrate.py`. |
+
+Skipping a stage is allowed only for security fixes or unreleased features that were never shipped.
+
+## CI enforcement
+
+A compatibility CI job (planned for `.github/workflows/compat.yml`) verifies:
+
+1. **New skill reads old `.lore/`**: checkout a fixture project from `fixtures/v0-project/`, run `list_entries.py`, `history.py`, `find_stale.py` on it. Pass = no exceptions, correct counts.
+2. **Old skill reads new `.lore/`**: build a fixture with the latest schema, check out the previous release's scripts, run them. Pass = no exceptions on known fields; unknown fields silently ignored.
+3. **No rename or delete in `scripts/` or `references/`**: PR diff against `scripts/` and `references/` filenames; any removed file = failure.
+
+At least one fixture project must be checked in at `fixtures/v0-project/` and re-pinned to a known old schema version after each major release.
+
+## Examples
+
+### Compatible change (additive)
+
+Adding a new `compress_thresholds.max_entries_per_scope` field:
+
+- Bump `schema_version` to 2.
+- `migrate.py` v1 → v2: add the new field with default `100` if absent.
+- Old skill reads v2 config: sees only the fields it knows; ignores `max_entries_per_scope`.
+- New skill reads v1 config: detects `schema_version` mismatch, refuses to write until migration runs.
+
+### Incompatible change (avoid)
+
+Renaming `mirror_mode` to `render_mode`:
+
+- Every existing `.lore/.config.json` would silently lose its `mirror_mode: "index"` setting on next migration (old field dropped, new field absent → defaults kick in).
+- Bad. Instead: add `render_mode` as the new canonical field; mark `mirror_mode` as `_deprecated`; keep both for one schema version; eventually remove `mirror_mode` via the deprecation cycle.
+
+### Breaking change (deprecation cycle required)
+
+Removing support for `mirror_mode: "full"`:
+
+- v1: ship `mirror_mode: "full"` as deprecated; full mode still works.
+- v2: print warning when `"full"` is set; suggest migrating to `"index"`.
+- v3: hard reject `"full"`; `migrate.py` auto-converts to `"index"`.
+- Each version's release notes link to the deprecation entry in `references/deprecations.md`.
+
+## Decision checklist
+
+Before merging any change to lore, answer these questions:
+
+1. Does this change add, modify, or remove anything in `.lore/`?
+2. Does this change add, modify, or remove any script in `scripts/`?
+3. Does this change add, modify, or remove any contract string (`## Lore (auto-managed)`, `## My notes (free edit)`, etc.)?
+4. Does this change add, modify, or remove any reference doc filename?
+5. Does this change add, modify, or remove any entry tag?
+
+If any answer is "modify" or "remove", the change requires either:
+- A migration step in `migrate.py` (for schema changes)
+- A deprecation cycle (for removals)
+- An entry in `references/deprecations.md`
+
+If all answers are "add" or "no", the change is non-breaking and can ship as a minor or patch release.

package/bundled-skills/lore/references/config.md

@@ -0,0 +1,125 @@
+# Configuration reference
+
+`.lore/.config.json` holds user-tunable settings. The file is optional; without it, the skill uses sensible defaults.
+
+## Schema
+
+```json
+{
+  "schema_version": 1,
+  "auto_mirror": true | false,
+  "sync_updates_mirror": true | false,
+  "sync_trust": "high" | "medium" | "low",
+  "mirror_targets": ["CLAUDE.md"], // optional — auto-detected if absent
+  "mirror_mode": "index",
+  "compress_thresholds": {
+    "max_entries": 500,
+    "max_days_since_compress": 30
+  },
+  "sync_thresholds": {
+    "min_lines_changed": 50,
+    "min_directories_changed": 2
+  }
+}
+```
+
+## Schema version (`schema_version`)
+
+**Required for new configs** (set automatically by `lore init`). Tracks the schema version of `.lore/.config.json` so future releases can detect old configs before writing.
+
+- **Missing** → treated as `schema_version: 1`. A `[WARN]` notice is printed to stderr by `list_entries.py`; add the field manually to silence it.
+- **Equal to skill's expected version** → use as-is.
+- **Lower than expected** → refuse to write; ask the user to run the migration script shipped with that future release.
+- **Higher than expected** → refuse to read with an error; the user's skill is older than their `.lore/`. They need to upgrade lore (pull latest from upstream) before continuing.
+
+For the full compatibility policy (migration tools, deprecation cycle, reader/writer contracts), see `references/compatibility.md`.
+
+## Field semantics
+
+### `auto_mirror`
+
+Default: `false`.
+
+Controls whether `compress` and `lore mirror` regenerate platform mirrors automatically after the canonical change is accepted.
+
+- `true` — regenerate mirrors automatically
+- `false` — ask per target before writing
+
+Note: this flag does **not** affect `sync`. By default `sync` does not touch mirrors at all (see `sync_updates_mirror`).
+
+### `sync_updates_mirror`
+
+Default: `false`.
+
+Controls whether `sync` regenerates platform mirrors as a side effect.
+
+- `false` — `sync` only writes `.lore/*.md`. Mirrors are updated by `compress` or explicit `lore mirror`. This is the recommended setting to avoid cluttering `git log` of mirror files.
+- `true` — `sync` regenerates mirrors (with content-based dedup) after the canonical change is accepted. Restore this setting if the old "update everything on every sync" behavior is preferred.
+
+### `sync_trust`
+
+Default: `"medium"`.
+
+Controls how much confirmation `sync` requires for individual change types.
+
+- `"high"` — auto-apply everything, including `NEW` and `STALE`. Only `ALERT` blocks interrupt.
+- `"medium"` — auto-apply low-risk changes (de-duplicate hits, equivalent REFINEDs). `NEW`, `STALE`, and `ALERT` require confirmation.
+- `"low"` — every change requires confirmation, including de-duplicate hits and equivalent REFINEDs.
+
+### `mirror_targets`
+
+Default: auto-detected at runtime (see "If absent" below).
+
+Array of file paths (relative to project root) that should be kept in sync with `.lore/*`.
+Every entry must pass the fail-closed allowlist and containment validation in
+`references/platform-mirrors.md` before any target is read or written. Absolute paths,
+`..` components, unsupported paths, and paths that escape the project root through symlinks
+are errors, not warnings; abort the mirror operation without touching any target.
+
+If absent: mirror targets are auto-detected at runtime by scanning the project root for existing platform files. If no platform files exist, the user is asked via a multi-select question during `init`, the first `mirror` call, or `compress` (when `auto_mirror: true`). See `references/platform-mirrors.md` for the resolution algorithm.
+
+If present: validate the complete array, then use the validated targets. Empty array `[]` is
+valid and disables mirror generation. Never partially process an array containing an invalid
+target.
+
+When auto-detection is in effect, `lore init` populates this field with the user's selections so subsequent runs are silent.
+
+### `mirror_mode`
+
+Default: `"index"`.
+
+Only `"index"` is accepted. The mirror renders a small index structure pointing into `.lore/` (see `references/platform-mirrors.md` for the template and adaptive rendering rules). Per-session token cost stays flat (~500 B) regardless of project size.
+
+Any other value (e.g., the historical `"summary"` or `"full"`) is rejected at config-load time with an error. Remove the field, or set it to `"index"`.
+
+### `compress_thresholds`
+
+Defaults: `{"max_entries": 500, "max_days_since_compress": 30}`.
+
+`sync` checks these silently and emits a `[COMPRESS NOTICE]` when tripped. See `SKILL.md` sync procedure.
+
+### `sync_thresholds`
+
+Defaults: `{"min_lines_changed": 50, "min_directories_changed": 2}`.
+
+`sync` only proposes an update when at least one trigger threshold is met (see `SKILL.md` sync trigger threshold). Lowering these values means `sync` proposes updates more often.
+
+## Editing the config
+
+Edit `.lore/.config.json` directly. After editing:
+
+- `sync` and `compress` re-read the config on every run; no restart needed.
+- Invalid JSON → fall back to defaults + warn the user.
+- After editing, verify with `python scripts/list_entries.py --config-check` (added in a future migration).
+- For schema version changes, see `references/compatibility.md`.
+
+## Upgrade path
+
+When a future lore release introduces the first `schema_version` bump:
+
+1. That release ships `scripts/migrate.py` for the specific version bump.
+2. The skill prompts: "Your `.lore/.config.json` is v1; lore now expects v2. Run `python scripts/migrate.py` to upgrade."
+3. `migrate.py` is idempotent — running it twice is a no-op.
+4. After migration, the file is updated in place; no manual editing needed.
+
+In v1, no migration has shipped and `scripts/migrate.py` does not exist. Add `"schema_version": 1` manually to old configs to silence the warning.

package/bundled-skills/lore/references/entry-format.md

@@ -0,0 +1,70 @@
+# Entry format reference
+
+Detailed specification for `.lore/` entries. The main `SKILL.md` covers entry structure briefly; this file is the full spec.
+
+## Bullet structure
+
+Each entry is a Markdown bullet (≤ 2 lines), containing:
+
+- **Layer prefix**: `ARCH`, `DEC`, or `CONV`
+- **ID**: `LAYER-YYYY-MM-DD-xxxx` where `xxxx` is a 4-char content hash
+- **Inline status tags** (at the end of the entry)
+
+```markdown
+- [ARCH-2026-07-09-a3f2] Use Next.js App Router; reason: streaming + RSC. #added:2026-07-09
+- [DEC-2026-02-03-7c19] Chose Zustand over Redux; reason: 60% less boilerplate. Alternatives: Redux Toolkit, Jotai. #added:2026-02-03
+- [CONV-2026-01-20-b1e8] Never commit secrets; use `dotenv` + `.env.local` (gitignored). #added:2026-01-20
+- [ARCH-2026-03-10-a1b2] Use TanStack Query for all server state. #added:2026-03-10 #verified:2026-06-15
+```
+
+## ID generation
+
+The 4-char `xxxx` is the first 4 hex chars of `sha256(entry text)`. This makes IDs:
+
+- **Deterministic**: rewriting the same fact produces the same ID
+- **Conflict-free** under concurrent writes by multiple agents
+- **Reverse-lookup-able** by audit tools
+
+If two entries have identical content (hash collision, statistically rare), add a distinguishing word to one and recompute.
+
+## Tag specification
+
+| Tag | Meaning |
+|---|---|
+| `#added:YYYY-MM-DD` | When the entry was created |
+| `#verified:YYYY-MM-DD` | Last time a human or audit confirmed the entry is still true |
+| `#stale:YYYY-MM-DD` | Flagged by `sync` as superseded or contradicted; user decides keep/archive |
+| `#archived:YYYY-MM-DD` | Moved to `archive/` |
+
+Multiple tags can co-exist on one entry (e.g. `#added:2026-01-15 #verified:2026-06-01`).
+
+## Cross-file references
+
+When `SUMMARY.md` or another file references an entry, qualify it with the file path to avoid ID collisions across scopes:
+
+```
+[scopes/frontend/DECISIONS.md#DEC-2026-02-03-7c19]
+[_global/CONVENTIONS.md#CONV-2026-01-20-b1e8]
+```
+
+The path is relative to `.lore/`.
+
+## Splitting vs. single entries
+
+If a fact can't fit in ≤ 2 lines, split into multiple entries and cross-reference them by ID:
+
+```markdown
+- [ARCH-2026-07-09-a3f2] Use Next.js App Router. #added:2026-07-09
+- [DEC-2026-07-09-b1e8] Reason: streaming + RSC, see [ARCH-2026-07-09-a3f2]. #added:2026-07-09
+```
+
+Instead of stuffing them into a single overly long bullet.
+
+## What counts as "atomic"
+
+A fact is atomic if it answers exactly one question:
+
+- "What is the frontend framework?" → `ARCH` entry about Next.js
+- "Why Next.js not Remix?" → `DEC` entry referencing the `ARCH` entry
+
+If your entry answers two questions, split it.

package/bundled-skills/lore/references/history-command.md

@@ -0,0 +1,106 @@
+# `lore history` — full specification
+
+Read-only command. Lists git commits related to a memory entry, a file,
+or a scope, since the entry's `#added` date. Output to stdout only;
+never writes to `.lore/`.
+
+## Synopsis
+
+```
+lore history <entry-id>
+lore history <file-path>
+lore history --scope=<name>
+lore history --since=<YYYY-MM-DD>
+lore history --json
+```
+
+## Forms
+
+| Form | Argument shape | Example | Behavior |
+|---|---|---|---|
+| Entry | `[A-Z]+-\d{4}-\d{2}-\d{2}-[a-f0-9]{4}` | `lore history DEC-2026-02-03-7c19` | Locate entry in `.lore/`, derive its `#added` date and code file, then `git log` since that date. |
+| File  | contains `/` or starts with `.` | `lore history frontend/src/store/index.ts` | Run `git log --since=1970-01-01` on the given path. |
+| Scope | `--scope=<name>` only | `lore history --scope=frontend` | For each `*.md` in `.lore/scopes/<name>/`, run file form on the lore file path itself. |
+
+## Code-file resolution (entry form)
+
+Priority:
+
+1. First backtick-quoted path in entry.text that looks like a file
+   (e.g. `src/store/index.ts`).
+2. Scope directory at the project root (e.g. entry scope `frontend` →
+   `frontend/`).
+3. Project root `.` for entries in `_global/`.
+
+If the regex finds no path, falls back to the scope directory.
+
+## Data source
+
+`git` CLI only. No network calls. Requires:
+
+- A git repository at or above the current working directory.
+- The `git` executable on `PATH`.
+
+## Output
+
+### Markdown (default)
+
+Header block: `Entry`, `Since`, `File`, `Commits`. One section per
+commit with `## <short-hash> (<date>, <author>)`, subject, optional
+`Body:` line, optional `Refs:` line. A "Suggested next step" footer
+appears only when at least one commit is found.
+
+### JSON (`--json`)
+
+```json
+{
+  "entry_id": "DEC-2026-02-03-7c19",
+  "lore_file": "scopes/frontend/DECISIONS.md",
+  "code_file": "frontend/src/store/index.ts",
+  "since": "2026-02-03",
+  "since_source": "entry_added",
+  "commits": [
+    {
+      "hash": "...",
+      "short": "abc1234",
+      "author": "alice",
+      "date": "2026-04-12",
+      "subject": "Use Zustand v4",
+      "body": "Migrate notes here.",
+      "refs": ["#234"]
+    }
+  ]
+}
+```
+
+## Error handling
+
+| Condition | Exit code | Message |
+|---|---|---|
+| No argument | 2 | `error: missing argument` |
+| Unrecognized argument | 2 | `error: unrecognized argument: <arg>` |
+| `.lore/` not found | 2 | `error: .lore/ not found. Run 'lore init' first.` |
+| Entry not in index | 3 | `error: Entry <id> not found. Available: ...` |
+| Not a git repo | 4 | `error: Not a git repository. ...` |
+| `git` missing | 5 | `error: git executable not found on PATH.` |
+| Bad scope name | 6 | `error: Scope '<name>' not found. Available: ...` |
+| `git log` failure | 7 | `error: git log failed: <stderr>` |
+| Entry missing `#added` | 0 (warning) | `warning: entry has no #added tag; using full history` |
+
+## Exit codes summary
+
+- `0` — success (including "0 commits found" case)
+- `2` — usage / configuration error
+- `3` — entry lookup failure
+- `4` — not a git repo
+- `5` — git CLI missing
+- `6` — invalid scope
+- `7` — git command failed
+
+## Why this exists
+
+`lore sync` reads `git diff` (working-tree deltas). It never reads
+commit history. `lore history` fills that gap: given a memory entry,
+it shows the commits that introduced or modified the underlying code,
+letting the agent answer "why does this decision exist?" with a pointer
+to the original commit instead of an LLM-generated guess.

package/bundled-skills/lore/references/monorepo-detection.md

@@ -0,0 +1,78 @@
+# Monorepo detection rules
+
+`init` needs to identify whether the project is a monorepo and how to split scopes. This file lists the detection rules per tool.
+
+## Detection order
+
+Check markers in this order; the first match determines scope layout:
+
+1. pnpm workspaces
+2. Yarn workspaces
+3. npm workspaces
+4. Lerna
+5. Nx
+6. Rush
+7. Cargo workspaces
+8. Go workspaces
+9. Bazel
+
+No monorepo marker → fall back to `_global/` only (single-scope project).
+
+## Per-tool rules
+
+### pnpm workspaces
+- Marker: `pnpm-workspace.yaml` at repo root
+- Read: `packages:` field, e.g. `packages: [frontend, backend, shared/*]`
+- One scope per listed package directory
+
+### Yarn workspaces (classic / berry)
+- Marker: `package.json` top-level `workspaces` field
+- Example: `"workspaces": ["packages/*"]`
+- One scope per glob-resolved directory
+
+### npm workspaces
+- Same as Yarn (npm 7+ uses the same `package.json#workspaces` field)
+
+### Lerna
+- Marker: `lerna.json`
+- Read: `packages` field (array of paths)
+- One scope per path
+
+### Nx
+- Marker: `nx.json` or `workspace.json`
+- Nx typically delegates package discovery to npm/yarn workspaces — read both
+- One scope per resolved package
+
+### Rush
+- Marker: `rush.json`
+- Read: `projects` array (each entry has a `packageName` and directory)
+
+### Cargo workspaces
+- Marker: `Cargo.toml` top-level `[workspace]` table
+- Read: `members` array
+- One scope per member crate
+
+### Go workspaces
+- Marker: `go.work`
+- Read: `use` directives (one per module)
+- One scope per module
+
+### Bazel
+- Marker: `MODULE.bazel` or `WORKSPACE`
+- Bazel repos are deeply nested; precise extraction is fragile. Fallback: collapse to one scope per top-level directory and let the user override.
+
+## Scope naming
+
+- Default: directory name (`frontend/` → scope `frontend`)
+- If multiple directories belong to one logical scope (e.g. `packages/web` and `packages/mobile` are both "frontend"), agent should ask the user whether to merge
+- Nested monorepos (`packages/web/components/`) are **not** supported as nested scopes. Flatten to `web`.
+
+## When detection fails
+
+If detection succeeds but the resulting scopes don't match the user's mental model, agent should:
+
+1. Show the proposed scope list
+2. Let the user rename / merge / split scopes
+3. Proceed with the corrected list
+
+This is part of the init confirmation step (see main `SKILL.md` init step 2).