opencode-snippets 1.0.0 → 1.1.2

package/README.md

@@ -1,29 +1,107 @@
 # opencode-snippets
 
-**Instant inline text expansion for OpenCode** - Type `#snippet` anywhere in your message and watch it transform.
+✨ **Instant inline text expansion for OpenCode** - Type `#snippet` anywhere in your message and watch it transform.
 
 ## Why Snippets?
 
-OpenCode has powerful `/slash` commands, but they must come first in your message. What if you want to inject context *mid-thought*?
+As developers, we DRY (Don't Repeat Yourself) our code. We extract functions, create libraries, compose modules. Why should our prompts be any different?
+
+Stop copy-pasting the same instructions into every message. Snippets bring software engineering principles to prompt engineering:
+
+- 🔄 **DRY** - Write once, reuse everywhere
+- 🧩 **Composability** - Build complex prompts from simple pieces  
+- 🔧 **Maintainability** - Update once, apply everywhere
+- 🔍 **Discoverability** - Your team's best practices, always a `#hashtag` away
+
+OpenCode's `/slash` commands must come first. Snippets work anywhere:
 
 ```
-# With slash commands (must be first):
+# Slash commands (must be first):
 /git-status Please review my changes
 
-# With snippets (anywhere!):
+# Snippets (anywhere!):
 Please review my changes #git-status and suggest improvements #code-style
 ```
 
-**Snippets work like `@file` mentions** - natural, inline, composable. Build complex prompts from reusable pieces without breaking your flow.
+Snippets work like `@file` mentions - natural, inline, composable.
+
+### 🎯 Composable by Design
+
+Snippets compose with each other and with slash commands. Reference `#snippets` anywhere - in your messages, in slash commands, even inside other snippets:
+
+**Example: Slash commands as snippet proxies**
+
+`~/.config/opencode/snippet/ralph.md`:
+```markdown
+Start a ralph loop for this. Automatically guess how many iterations it will require if not specified.
+#todofile
+Give the path of the status/todo file to the ralph task and tell to continuously update it.
+```
+
+`~/.config/opencode/command/ralph.md`:
+```markdown
+---
+description: "Initiates a Ralph loop"
+---
+#ralph
+
+$ARGUMENTS
+```
+
+The `/ralph` slash command simply expands the `#ralph` snippet and passes through arguments. Minimal boilerplate, maximum reuse.
+
+**Example: Extending snippets with logic**
+
+`~/.config/opencode/command/commit-and-push.md`:
+```markdown
+---
+description: Create a git commit and push to remote
+agent: fast
+---
+Please create a git commit with the current changes and push to the remote repository.
+
+Here is the current git status:
+!`git status`
+
+Here are the staged changes:
+!`git diff --cached`
+
+#conventional-commits
+#project-context
+```
+
+The slash command provides workflow logic (git status, diffs, push) while reusing shared snippets for commit conventions and project context.
+
+**Example: Snippets composing snippets**
+
+`~/.config/opencode/snippet/code-standards.md`:
+```markdown
+#style-guide
+#error-handling
+#testing-requirements
+```
+
+`~/.config/opencode/snippet/full-review.md`:
+```markdown
+#code-standards
+#security-checklist
+#performance-tips
+```
+
+Compose base snippets into higher-level ones. Type `#full-review` to inject all standards at once, keeping each concern in its own maintainable file.
+
+**The power:** Mix and match. Type `#tdd #careful` for test-driven development with extra caution. Build `/commit #conventional-commits #project-context` for context-aware commits. Create layered prompts from small, reusable pieces.
 
 ## Installation
 
-```bash
-# Add to your opencode.json plugins array:
-"plugins": ["opencode-snippets"]
+Add to your `opencode.json` plugins array:
 
-# Then install:
-bun install
+```json
+{
+  "plugins": [
+    "opencode-snippets"
+  ]
+}
 ```
 
 ## Quick Start
@@ -39,7 +117,7 @@ mkdir -p ~/.config/opencode/snippet
 `~/.config/opencode/snippet/careful.md`:
 ```markdown
 ---
-aliases: ["safe", "cautious"]
+aliases: safe
 ---
 Think step by step. Double-check your work before making changes.
 Ask clarifying questions if anything is ambiguous.
@@ -73,7 +151,9 @@ Define multiple triggers for the same snippet:
 
 ```markdown
 ---
-aliases: ["cp", "pick"]
+aliases:
+  - cp
+  - pick
 description: "Git cherry-pick helper"
 ---
 Always pick parent 1 for merge commits.
@@ -81,9 +161,18 @@ Always pick parent 1 for merge commits.
 
 Now `#cherry-pick`, `#cp`, and `#pick` all expand to the same content.
 
+Single alias doesn't need array syntax:
+```markdown
+---
+aliases: safe
+---
+```
+
+You can also use JSON array style: `aliases: ["cp", "pick"]`
+
 ### Shell Command Substitution
 
-Inject live system data with `!`backtick\`` syntax:
+Snippets support the same `!`backtick\`` syntax as [OpenCode slash commands](https://opencode.ai/docs/commands/#shell-output) for injecting live command output:
 
 ```markdown
 Current branch: !`git branch --show-current`
@@ -91,16 +180,6 @@ Last commit: !`git log -1 --oneline`
 Working directory: !`pwd`
 ```
 
-Output:
-```
-Current branch: $ git branch --show-current
---> main
-Last commit: $ git log -1 --oneline  
---> abc123f feat: add new feature
-Working directory: $ pwd
---> /home/user/project
-```
-
 ### Recursive Includes
 
 Snippets can include other snippets:
@@ -119,7 +198,7 @@ Loop detection prevents infinite recursion.
 ### `~/.config/opencode/snippet/context.md`
 ```markdown
 ---
-aliases: ["ctx"]
+aliases: ctx
 ---
 Project: !`basename $(pwd)`
 Branch: !`git branch --show-current`
@@ -129,7 +208,9 @@ Recent changes: !`git diff --stat HEAD~3 | tail -5`
 ### `~/.config/opencode/snippet/review.md`
 ```markdown
 ---
-aliases: ["pr", "check"]
+aliases:
+  - pr
+  - check
 ---
 Review this code for:
 - Security vulnerabilities
@@ -142,7 +223,9 @@ Review this code for:
 ### `~/.config/opencode/snippet/minimal.md`
 ```markdown
 ---
-aliases: ["min", "terse"]
+aliases:
+  - min
+  - terse
 ---
 Be extremely concise. No explanations unless asked.
 ```
@@ -151,10 +234,10 @@ Be extremely concise. No explanations unless asked.
 
 | Feature | `/commands` | `#snippets` |
 |---------|-------------|-------------|
-| Position | Must be first | Anywhere |
+| Position | Must come first | Anywhere |
 | Multiple per message | No | Yes |
-| Live shell data | Via implementation | Built-in `!\`cmd\`` |
-| Best for | Actions & workflows | Context injection |
+| Live shell data | Yes | Yes |
+| Best for | Triggering actions & workflows | Context injection |
 
 **Use both together:**
 ```
@@ -182,7 +265,7 @@ Logs are written to `~/.config/opencode/logs/snippets/daily/`.
 - Snippets are loaded once at plugin startup
 - Hashtag matching is **case-insensitive** (`#Hello` = `#hello`)
 - Unknown hashtags are left unchanged
-- Failed shell commands preserve the `!\`cmd\`` syntax
+- Failed shell commands preserve the original syntax in output
 - Frontmatter is stripped from expanded content
 - Only user messages are processed (not assistant responses)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-snippets",
-  "version": "1.0.0",
+  "version": "1.1.2",
   "description": "Hashtag-based snippet expansion plugin for OpenCode - instant inline text shortcuts",
   "main": "index.ts",
   "type": "module",