opencode-skills-collection 3.0.34 → 3.0.35

package/bundled-skills/user-thoughts/assets/Runtime-Template/mdbase/details/general.md

@@ -0,0 +1,7 @@
+# General Project Notes
+
+> Project-relevant thoughts that do not fit another dimension yet.
+
+## Current Notes
+
+<!-- Append dated user thoughts here. -->

package/bundled-skills/user-thoughts/assets/Runtime-Template/mdbase/details/plans.md

@@ -0,0 +1,7 @@
+# Project Plans
+
+> Directional plans, milestones, priorities, sequencing, and strategic project ideas.
+
+## Current Plans
+
+<!-- Append dated user plans here. -->

package/bundled-skills/user-thoughts/assets/Runtime-Template/mdbase/details/rules.md

@@ -0,0 +1,7 @@
+# Project Rules and Constraints
+
+> User-defined rules, constraints, conventions, preferences, and non-negotiables.
+
+## Current Rules
+
+<!-- Append dated user rules here. -->

package/bundled-skills/user-thoughts/assets/Runtime-Template/mdbase/details/ui/details.md

@@ -0,0 +1,7 @@
+# UI Details
+
+> Component-level UI preferences, interaction details, copy details, spacing, states, and visual refinements.
+
+## Current Details
+
+<!-- Append dated UI detail decisions here. -->

package/bundled-skills/user-thoughts/assets/Runtime-Template/mdbase/details/ui/outline.md

@@ -0,0 +1,7 @@
+# UI Outline
+
+> Product-level UI direction, layout concepts, design principles, themes, and screen-level decisions.
+
+## Current Direction
+
+<!-- Append dated UI outline decisions here. -->

package/bundled-skills/user-thoughts/references/commands.md

@@ -0,0 +1,54 @@
+# Command Reference
+
+`user-thoughts` accepts `/user-thoughts` and `/ustht`. They are equivalent.
+
+## Command Summary
+
+| Command | Meaning |
+|---|---|
+| `/ustht init` | Initialize `.ustht/` in the current project. |
+| `/ustht status` | Show skill state, instant state, raw count, and dimension count. |
+| `/ustht skill` | Show `SKILL_STATUS`. |
+| `/ustht skill on|off` | Enable or disable write operations. |
+| `/ustht instant` | Show `INSTANT_STATUS`. |
+| `/ustht instant on|off` | Enable or disable instant capture. |
+| `/ustht sortin [--dry]` | Append raw entries into mdbase. |
+| `/ustht resort [--dry]` | Reorganize all mdbase content semantically. |
+| `/ustht raw` | Show unprocessed raw entries. |
+| `/ustht mdbase show [--all|--dimension]` | Show the index, all dimensions, or one dimension. |
+| `/ustht mdbase export [--all|--dimension]` | Export mdbase content. |
+| `/ustht import <path>` | Import project-relevant decisions from markdown files. |
+| `/ustht ignore start|end` | Start or stop a temporary ignore interval. |
+| `/ustht ignore --last` | Remove the last raw entry and record it as ignored. |
+| `/ustht ignore show` | Show ignored entries. |
+
+## Natural-Language Mapping
+
+Agents may map clear user intent to commands:
+
+- "turn on project memory" -> `/ustht skill on && instant on`
+- "stop recording this" -> `/ustht ignore start`
+- "start recording again" -> `/ustht ignore end`
+- "organize what I said" -> `/ustht sortin`
+- "show what you remember" -> `/ustht mdbase show`
+- "ignore the last note" -> `/ustht ignore --last`
+
+When intent is ambiguous, ask a short clarification instead of guessing.
+
+## Chained Commands
+
+Commands can be chained with `&&` and should run left to right. Stop only if a command fails in a way that makes the following command unsafe.
+
+Example:
+
+```text
+/ustht skill on && instant on && status
+```
+
+## Dimension Arguments
+
+Dimension names must pass validation:
+
+- lowercase letters, digits, and hyphens;
+- `/` allowed for subdirectories, such as `ui/outline`;
+- no spaces, `..`, backslashes, absolute paths, or reserved names.

package/bundled-skills/user-thoughts/references/edge-cases.md

@@ -0,0 +1,84 @@
+# Edge Cases
+
+Use these examples to keep behavior predictable.
+
+## No Runtime Directory
+
+User: `/ustht status`
+
+Agent: `.ustht/ was not found. Run /ustht init first.`
+
+## Skill Disabled
+
+If `SKILL_STATUS=off`, write commands should not modify files. Read commands such as `status`, `raw`, and `mdbase show` may still run.
+
+## Instant Mode Disabled
+
+When `INSTANT_STATUS=off`, do not capture natural-language thoughts automatically. Explicit commands still run.
+
+## Command Plus Thought
+
+User: `Make buttons use 8px radius, and /ustht status`
+
+Agent: run the command and record the UI preference if instant capture is enabled. Do not record the command text itself.
+
+## Message Suffix Ignore
+
+User: `This color experiment is temporary /ustht ignore`
+
+Agent: do not write it to raw. Record it in `ignored/` as a suffix-ignored entry if ignore tracking is available.
+
+## Ignore Interval
+
+User: `/ustht ignore start`
+
+Agent: enter ignore mode for the current context.
+
+User: `Try three throwaway layouts.`
+
+Agent: do not record the thought.
+
+User: `/ustht ignore end`
+
+Agent: exit ignore mode.
+
+## Last Entry Ignore
+
+User: `/ustht ignore --last`
+
+Agent: remove the last unprocessed raw entry and append it to `ignored/`. If no entry exists, say so without failing.
+
+## Processed Marker Mentioned by User
+
+User: `Maybe we should use <!-- processed --> as a completion marker in docs.`
+
+Agent: preserve that text as ordinary user content. `sortin` checks only the first line of raw files.
+
+## Illegal Dimension Names
+
+Reject dimensions containing spaces, `..`, backslashes, absolute paths, or unsafe characters.
+
+Examples:
+
+- Reject `../../../etc/passwd`.
+- Reject `my file`.
+- Accept `ui/details`.
+- Accept `dev-stack`.
+
+## Chained Commands
+
+User: `/ustht skill on && instant on && status`
+
+Agent: run commands left to right and report a compact summary.
+
+## Import With No Relevant Content
+
+If `/ustht import README.md` finds no project decisions, report that no entries were extracted and do not write empty dimension sections.
+
+## Multi-Agent Writes
+
+No file locks are provided. If multiple agents are active, coordinate before `sortin` or `resort` to avoid conflicting writes.
+
+## Sensitive Content
+
+If the user says a thought contains secrets or personal data, prefer ignore behavior and remind them that `.ustht/` is not automatically redacted.

package/bundled-skills/user-thoughts/references/safety.md

@@ -0,0 +1,65 @@
+# Safety and Data Integrity
+
+This document defines path safety, input validation, and data-integrity rules for `user-thoughts`.
+
+## Path Safety
+
+All runtime file operations must stay inside `#ustht/` unless an import command reads project-local markdown files.
+
+Dimension names are used to construct paths, so validate them strictly:
+
+| Rule | Reason |
+|---|---|
+| Each path segment uses `[a-z0-9-]` only | Prevents shell and path surprises. |
+| Each segment starts and ends with `[a-z0-9]` | Avoids hidden or malformed files. |
+| `/` is allowed only as a dimension subdirectory separator | Supports `ui/outline`. |
+| `..`, backslashes, spaces, and absolute paths are forbidden | Prevents path traversal. |
+| Reserved names are forbidden | Avoids collisions with runtime folders. |
+
+Reserved names: `backlog`, `readme-ai`, `export`, `raw`, `ignored`, `define`, `general`.
+
+## Content Safety
+
+Raw entries use this format:
+
+```text
+- [HH:MM] original user text | suggested-dim:dimension
+```
+
+The suffix is agent-generated metadata. User text may contain markdown and should be preserved as written. Parse the last ` | suggested-dim:` separator only.
+
+`<!-- processed -->` is meaningful only as the first line of a raw file. If the user mentions that string inside a thought, treat it as normal content.
+
+## define.ini Safety
+
+Allowed keys and values:
+
+| Key | Allowed value |
+|---|---|
+| `SKILL_STATUS` | `on` or `off` |
+| `INSTANT_STATUS` | `on` or `off` |
+| `LAST_SORTIN` | empty or `yyyy-mm-dd HH:MM` |
+
+Values must not contain newlines or `=`. Write the whole file rather than appending partial fragments.
+
+## Shell Safety
+
+- Do not execute user-provided shell commands.
+- Do not use `eval` or dynamic execution.
+- Construct file paths only from validated dimensions or fixed template paths.
+- During initialization, copy known template files safely instead of recursively shell-copying arbitrary directories.
+
+## Data Integrity
+
+`sortin` is not fully atomic. To reduce partial-write risk:
+
+1. Parse raw entries first.
+2. Write dimension files.
+3. Mark raw files as processed only after writes succeed.
+4. Update `LAST_SORTIN` last.
+
+Processed raw files are retained for traceability. Dimension files should be appended or marked deprecated; do not silently delete user history.
+
+## Sensitive Data
+
+The skill preserves original wording and does not redact secrets or personal data. Users should use ignore commands before sensitive content is captured, and teams should protect `.ustht/` with normal repository and filesystem hygiene.

package/bundled-skills/user-thoughts/references/sortin.md

@@ -0,0 +1,76 @@
+# Sortin and Resort Algorithms
+
+This document describes how raw thoughts become organized mdbase records.
+
+## Commands
+
+| Command | Behavior |
+|---|---|
+| `/ustht sortin` | Soft maintenance: append new raw entries into mdbase without restructuring existing content. |
+| `/ustht resort` | Hard maintenance: review all mdbase content, deduplicate, reclassify, merge, and update indexes. |
+| `--dry` | Preview intended changes without writing. |
+
+## Raw Format
+
+Before processing:
+
+```text
+- [14:30] Make buttons use 8px radius | suggested-dim:ui/details
+- [14:45] Login should use a dark theme | suggested-dim:ui/outline
+- [15:10] Use REST APIs, not GraphQL | suggested-dim:dev-stack
+```
+
+After processing, the first line of the file becomes:
+
+```text
+<!-- processed -->
+```
+
+## Soft Append Format
+
+A raw entry is appended under a date heading in the selected dimension file:
+
+```markdown
+## 2026-06-01
+
+- Make buttons use 8px radius
+```
+
+Rules:
+
+- Preserve original wording.
+- Remove only the timestamp and `suggested-dim` suffix.
+- Group entries by raw-file date.
+- Append to an existing date section when present.
+- Create a new date section when needed.
+
+## Dimension Management
+
+Create a new dimension only when the thought does not fit an existing dimension. Dimension names must be kebab-case path segments and must pass safety validation.
+
+When `resort` finds overlapping dimensions, merge them into the clearest target and preserve provenance. When a dimension is no longer useful, mark it with `<!-- deprecated -->` instead of deleting it.
+
+## Classification Priority
+
+1. User-specified dimension.
+2. Exact existing dimension match.
+3. Closest semantic existing dimension, with a note if the fit is weak.
+4. `general.md` fallback.
+
+## Import Algorithm
+
+`/ustht import <path>` scans markdown files under a safe project-local path and extracts project-relevant user decisions, constraints, and requirements. It should not modify source files. Imported entries should include source provenance such as `[source:docs/design.md]`.
+
+Skip ordinary technical docs, generated docs, API reference text, and code comments unless they clearly encode a user decision.
+
+## Summary Output
+
+After `sortin`, report the number of processed entries and destination dimensions, for example:
+
+```text
+Soft maintenance complete. Processed 3 thoughts:
+  -> ui/details.md: +1
+  -> ui/outline.md: +1
+  -> dev-stack.md: +1
+LAST_SORTIN updated to 2026-06-01 15:30
+```

package/bundled-skills/user-thoughts/scripts/common.py

@@ -0,0 +1,62 @@
+"""Shared helpers for user-thoughts scripts."""
+import re
+from pathlib import Path
+
+
+def find_ustht() -> Path | None:
+    """Find .ustht/ in the current directory or one of its parents."""
+    cwd = Path.cwd()
+    for d in [cwd, *cwd.parents]:
+        ustht = d / ".ustht"
+        if ustht.is_dir():
+            return ustht
+    return None
+
+
+def find_skill_dir() -> Path | None:
+    """Find the installed user-thoughts skill directory."""
+    script_dir = Path(__file__).resolve().parent
+    skill_dir = script_dir.parent
+    if (skill_dir / "SKILL.md").exists():
+        return skill_dir
+    return None
+
+
+def read_define_ini(ustht: Path) -> dict:
+    """Read define.ini and return key/value pairs."""
+    ini = ustht / "define.ini"
+    if not ini.exists():
+        return {}
+    result = {}
+    for line in ini.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if "=" in line and not line.startswith("#"):
+            k, v = line.split("=", 1)
+            result[k.strip()] = v.strip()
+    return result
+
+
+def write_define_ini(ustht: Path, cfg: dict):
+    """Replace define.ini with the provided key/value pairs."""
+    ini = ustht / "define.ini"
+    lines = [f"{k}={v}" for k, v in cfg.items()]
+    ini.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def is_processed(filepath: Path) -> bool:
+    """Return true when the first raw-file line is the processed marker."""
+    first_line = filepath.read_text(encoding="utf-8").split("\n", 1)[0].strip()
+    return first_line == "<!-- processed -->"
+
+
+def validate_dim_name(dim: str) -> bool:
+    """Validate a dimension path made of safe kebab-case segments."""
+    reserved = {"raw", "ignored", "export", "define", "readme-ai"}
+    if not dim or len(dim) > 64 or ".." in dim or "\\" in dim or " " in dim:
+        return False
+    for part in dim.split("/"):
+        if part in reserved:
+            return False
+        if not part or not re.match(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$", part):
+            return False
+    return True

package/bundled-skills/user-thoughts/scripts/ignore_ops.py

@@ -0,0 +1,125 @@
+"""Manage ignored user-thought entries."""
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from common import find_ustht
+
+HELP = """Usage: python ignore_ops.py show|remove_last|add_suffix "text" [--help]
+
+Subcommands:
+  show                List entries under #ignored/
+  remove_last         Remove the latest raw entry and move it to #ignored/
+  add_suffix "text"   Add a suffix-ignored entry to #ignored/
+"""
+
+
+def find_last_raw_entry(raw_dir: Path):
+    """Return (file path, line index, entry text) for the latest raw entry."""
+    files = sorted(raw_dir.glob("*.md"), reverse=True)
+    for f in files:
+        lines = f.read_text(encoding="utf-8").splitlines()
+        if lines and lines[0].strip() == "<!-- processed -->":
+            continue
+        for idx in range(len(lines) - 1, -1, -1):
+            if lines[idx].strip().startswith("- ["):
+                return f, idx, lines[idx]
+    return None, None, None
+
+
+def remove_line(filepath: Path, idx: int):
+    """Remove one line from a file."""
+    lines = filepath.read_text(encoding="utf-8").splitlines()
+    del lines[idx]
+    filepath.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
+
+
+def append_to_ignored(ignored_dir: Path, text: str, reason: str):
+    """Append one ignored entry to today's ignored file."""
+    ignored_dir.mkdir(exist_ok=True)
+    today = datetime.now().strftime("%Y-%m-%d")
+    now = datetime.now().strftime("%H:%M")
+    f = ignored_dir / f"{today}.md"
+    clean = text.strip()
+    if " | suggested-dim:" in clean:
+        clean = clean.rsplit(" | suggested-dim:", 1)[0]
+    entry = f"- [{now}] {clean} ({reason})"
+    if f.exists():
+        content = f.read_text(encoding="utf-8").rstrip()
+        f.write_text(f"{content}\n{entry}\n", encoding="utf-8")
+    else:
+        f.write_text(f"{entry}\n", encoding="utf-8")
+
+
+def show_ignored(ignored_dir: Path):
+    """Print all ignored entries."""
+    if not ignored_dir.exists():
+        print("No ignored entries.")
+        return
+    files = sorted(ignored_dir.glob("*.md"), reverse=True)
+    if not files:
+        print("No ignored entries.")
+        return
+    for f in files:
+        entries = [line for line in f.read_text(encoding="utf-8").splitlines() if line.strip().startswith("- [")]
+        if entries:
+            print(f"#{f.name} ({len(entries)} entries):")
+            for entry in entries:
+                print(entry)
+
+
+def remove_last(ustht: Path):
+    raw_dir = ustht / "raw"
+    if not raw_dir.exists():
+        print("No previous thought to ignore.")
+        return
+    filepath, idx, entry = find_last_raw_entry(raw_dir)
+    if filepath is None:
+        print("No previous thought to ignore.")
+        return
+    remove_line(filepath, idx)
+    append_to_ignored(ustht / "ignored", entry, "ignored with --last")
+    display = entry
+    if "] " in display:
+        display = display.split("] ", 1)[1]
+    if " | suggested-dim:" in display:
+        display = display.rsplit(" | suggested-dim:", 1)[0]
+    print(f"Ignored previous thought: {display}")
+
+
+def add_suffix(ustht: Path, text: str):
+    append_to_ignored(ustht / "ignored", text, "ignored by suffix")
+    print("Ignored current message.")
+
+
+def main():
+    if "--help" in sys.argv or "-h" in sys.argv:
+        print(HELP)
+        sys.exit(0)
+
+    ustht = find_ustht()
+    if ustht is None:
+        print("Error: .ustht/ was not found. Run /ustht init first.")
+        sys.exit(1)
+
+    if len(sys.argv) < 2:
+        print(f"Usage: {sys.argv[0]} show|remove_last|add_suffix \"text\"")
+        sys.exit(1)
+
+    cmd = sys.argv[1]
+    if cmd == "show":
+        show_ignored(ustht / "ignored")
+    elif cmd == "remove_last":
+        remove_last(ustht)
+    elif cmd == "add_suffix":
+        if len(sys.argv) < 3:
+            print("Error: add_suffix requires text.")
+            sys.exit(1)
+        add_suffix(ustht, sys.argv[2])
+    else:
+        print(f"Unknown command: {cmd}. Available: show, remove_last, add_suffix")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/bundled-skills/user-thoughts/scripts/init.py

@@ -0,0 +1,63 @@
+"""Initialize the .ustht/ runtime directory from templates."""
+import shutil
+import sys
+from pathlib import Path
+
+from common import find_skill_dir
+
+HELP = """Usage: python init.py [--help]
+
+Create .ustht/ in the current working directory, copy the runtime templates,
+and create raw/, ignored/, and export/ directories. Existing .ustht/ content is
+not overwritten.
+"""
+
+
+def copy_template(src: Path, dst: Path):
+    """Copy template files while skipping symlinks."""
+    for item in src.rglob("*"):
+        rel = item.relative_to(src)
+        target = dst / rel
+        if item.is_symlink():
+            continue
+        if item.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+        else:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(item, target)
+
+
+def main():
+    if "--help" in sys.argv or "-h" in sys.argv:
+        print(HELP)
+        sys.exit(0)
+
+    target = Path.cwd() / ".ustht"
+    if target.exists():
+        print("Already initialized; .ustht/ exists, skipping creation.")
+        sys.exit(0)
+
+    skill_dir = find_skill_dir()
+    if skill_dir is None:
+        print("Error: SKILL.md was not found. Ensure this script is inside user-thoughts/scripts/.")
+        sys.exit(1)
+
+    template = skill_dir / "assets" / "Runtime-Template"
+    if not template.exists():
+        print(f"Error: template directory does not exist: {template}")
+        sys.exit(1)
+
+    target.mkdir()
+    copy_template(template, target)
+    for name in ["raw", "ignored", "export"]:
+        (target / name).mkdir(exist_ok=True)
+
+    define = target / "define.ini"
+    if not define.exists():
+        define.write_text("SKILL_STATUS=on\nINSTANT_STATUS=off\nLAST_SORTIN=\n", encoding="utf-8")
+
+    print("Initialized .ustht/.")
+
+
+if __name__ == "__main__":
+    main()

package/bundled-skills/user-thoughts/scripts/show_mdbase.py

@@ -0,0 +1,93 @@
+"""Show the mdbase index or dimension content."""
+import sys
+from pathlib import Path
+
+from common import find_ustht, validate_dim_name
+
+HELP = """Usage: python show_mdbase.py show [--all|--dimension] [--help]
+
+Subcommands:
+  show              Show README.ai.md index
+  show --all        List all dimensions and entry counts
+  show <dimension>  Show one dimension file
+"""
+
+
+def show_index(mdbase: Path):
+    index = mdbase / "README.ai.md"
+    if not index.exists():
+        print("mdbase/README.ai.md does not exist.")
+        return
+    print(index.read_text(encoding="utf-8"))
+
+
+def list_dims(mdbase: Path):
+    details = mdbase / "details"
+    if not details.exists():
+        return []
+    return sorted(p.relative_to(details).with_suffix("").as_posix() for p in details.rglob("*.md"))
+
+
+def show_dim(mdbase: Path, dim: str):
+    if not validate_dim_name(dim):
+        print(f"Invalid dimension name: {dim}. Use lowercase letters, digits, hyphens, and optional / subdirectories.")
+        return
+    if dim == "backlog":
+        path = mdbase / "backlog.md"
+    else:
+        path = mdbase / "details" / f"{dim}.md"
+    if not path.exists():
+        print(f"mdbase/details/{dim}.md does not exist yet.")
+        return
+    print(path.read_text(encoding="utf-8"))
+
+
+def show_all(mdbase: Path):
+    details = mdbase / "details"
+    if not details.exists():
+        print("mdbase/details/ does not exist.")
+        return
+    dims = list_dims(mdbase)
+    if not dims:
+        print("mdbase has no dimension files.")
+        return
+    print(f"mdbase has {len(dims)} dimensions:")
+    for dim in dims:
+        path = details / f"{dim}.md"
+        lines = [line for line in path.read_text(encoding="utf-8").splitlines() if line.strip().startswith("- ")]
+        print(f"  {dim}.md: {len(lines)} entries")
+
+
+def main():
+    if "--help" in sys.argv or "-h" in sys.argv:
+        print(HELP)
+        sys.exit(0)
+
+    ustht = find_ustht()
+    if ustht is None:
+        print("Error: .ustht/ was not found. Run /ustht init first.")
+        sys.exit(1)
+
+    mdbase = ustht / "mdbase"
+    if not mdbase.exists():
+        print("mdbase is not initialized. Run /ustht init first.")
+        return
+
+    args = sys.argv[1:]
+    if not args or args[0] != "show":
+        print(f"Usage: {sys.argv[0]} show [--all|--dimension]")
+        sys.exit(1)
+
+    rest = args[1:]
+    if not rest:
+        show_index(mdbase)
+    elif rest[0] == "--all":
+        show_all(mdbase)
+    elif rest[0].startswith("--"):
+        show_dim(mdbase, rest[0][2:])
+    else:
+        show_dim(mdbase, rest[0])
+
+
+if __name__ == "__main__":
+    main()