@fro.bot/systematic 1.14.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

package/skills/agent-browser/SKILL.md

@@ -221,3 +221,4 @@ Use Playwright MCP when:
 - You need deep MCP tool integration
 - You want tool-based responses
 - You're building complex automation
+

package/skills/agent-native-architecture/SKILL.md

@@ -6,13 +6,13 @@ description: Build applications where agents are first-class citizens. Use this
 <why_now>
 ## Why Now
 
-Software agents work reliably now. Claude Code demonstrated that an LLM with access to bash and file tools, operating in a loop until an objective is achieved, can accomplish complex multi-step tasks autonomously.
+Software agents work reliably now. Modern coding agents like OpenCode have demonstrated that an LLM with access to bash and file tools, operating in a loop until an objective is achieved, can accomplish complex multi-step tasks autonomously.
 
-The surprising discovery: **a really good coding agent is actually a really good general-purpose agent.** The same architecture that lets Claude Code refactor a codebase can let an agent organize your files, manage your reading list, or automate your workflows.
+The surprising discovery: **a really good coding agent is actually a really good general-purpose agent.** The same architecture that lets an agent refactor a codebase can let it organize your files, manage your reading list, or automate your workflows.
 
-The Claude Code SDK makes this accessible. You can build applications where features aren't code you write—they're outcomes you describe, achieved by an agent with tools, operating in a loop until the outcome is reached.
+Agent SDKs make this accessible. You can build applications where features aren't code you write—they're outcomes you describe, achieved by an agent with tools, operating in a loop until the outcome is reached.
 
-This opens up a new field: software that works the way Claude Code works, applied to categories far beyond coding.
+This opens up a new field: software that works the way modern coding agents work, applied to categories far beyond coding.
 </why_now>
 
 <core_principles>

package/skills/agent-native-architecture/references/files-universal-interface.md

@@ -5,7 +5,7 @@ Files are the universal interface for agent-native applications. Agents are natu
 <why_files>
 ## Why Files
 
-Agents are naturally good at files. Claude Code works because bash + filesystem is the most battle-tested agent interface. When building agent-native apps, lean into this.
+Agents are naturally good at files. OpenCode works because bash + filesystem is the most battle-tested agent interface. When building agent-native apps, lean into this.
 
 ### Agents Already Know How
 

package/skills/agent-native-architecture/references/product-implications.md

@@ -11,7 +11,7 @@ The best agent-native applications are simple to start but endlessly powerful.
 
 Excel is the canonical example: you can use it for a grocery list, or you can build complex financial models. The same tool, radically different depths of use.
 
-Claude Code has this quality: fix a typo, or refactor an entire codebase. The interface is the same—natural language—but the capability scales with the ask.
+OpenCode has this quality: fix a typo, or refactor an entire codebase. The interface is the same—natural language—but the capability scales with the ask.
 
 ### The Pattern
 

package/skills/brainstorming/SKILL.md

@@ -188,3 +188,4 @@ Planning answers **HOW** to build it:
 - Testing strategy and verification
 
 When brainstorm output exists, `/workflows:plan` should detect it and use it as input, skipping its own idea refinement phase.
+

package/skills/compound-docs/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: compound-docs
 description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup
+disable-model-invocation: true
 allowed-tools:
-  - Read # Parse conversation context
-  - Write # Create resolution docs
-  - Bash # Create directories
-  - Grep # Search existing docs
+  - Read
+  - Write
+  - Bash
+  - Grep
 preconditions:
   - Problem has been solved (not in-progress)
   - Solution has been verified working
@@ -61,7 +62,7 @@ Extract from conversation history:
 
 **Required information:**
 
-- **Module name**: Which CORA module had the problem
+- **Module name**: Which module or component had the problem
 - **Symptom**: Observable error/behavior (exact error messages)
 - **Investigation attempts**: What didn't work and why
 - **Root cause**: Technical explanation of actual problem
@@ -249,7 +250,7 @@ But **NEVER auto-promote**. User decides via decision menu (Option 2).
 
 **Template for critical pattern addition:**
 
-When user selects Option 2 (Add to Required Reading), use the template from `assets/critical-pattern-template.md` to structure the pattern entry. Number it sequentially based on existing patterns in `docs/solutions/patterns/cora-critical-patterns.md`.
+When user selects Option 2 (Add to Required Reading), use the template from `assets/critical-pattern-template.md` to structure the pattern entry. Number it sequentially based on existing patterns in `docs/solutions/patterns/critical-patterns.md`.
 </step>
 
 </critical_sequence>
@@ -270,7 +271,7 @@ File created:
 
 What's next?
 1. Continue workflow (recommended)
-2. Add to Required Reading - Promote to critical patterns (cora-critical-patterns.md)
+2. Add to Required Reading - Promote to critical patterns (critical-patterns.md)
 3. Link related issues - Connect to similar problems
 4. Add to existing skill - Add to a learning skill (e.g., hotwire-native)
 5. Create new skill - Extract into new learning skill
@@ -295,7 +296,7 @@ User selects this when:
 Action:
 1. Extract pattern from the documentation
 2. Format as ❌ WRONG vs ✅ CORRECT with code examples
-3. Add to `docs/solutions/patterns/cora-critical-patterns.md`
+3. Add to `docs/solutions/patterns/critical-patterns.md`
 4. Add cross-reference back to this doc
 5. Confirm: "✓ Added to Required Reading. All subagents will see this pattern before code generation."
 
@@ -317,7 +318,7 @@ Action:
 4. Confirm: "✓ Added to [skill-name] skill in [file]"
 
 Example: For Hotwire Native Tailwind variants solution:
-- Add to `hotwire-native/references/resources.md` under "CORA-Specific Resources"
+- Add to `hotwire-native/references/resources.md` under "Project-Specific Resources"
 - Add to `hotwire-native/references/examples.md` with link to solution doc
 
 **Option 5: Create new skill**
@@ -326,7 +327,7 @@ User selects this when the solution represents the start of a new learning domai
 
 Action:
 1. Prompt: "What should the new skill be called? (e.g., stripe-billing, email-processing)"
-2. Run `python3 .claude/skills/skill-creator/scripts/init_skill.py [skill-name]`
+2. Run `python3 .opencode/skills/create-agent-skills/scripts/init_skill.py [skill-name]`
 3. Create initial reference files with this solution as first example
 4. Confirm: "✓ Created new [skill-name] skill with this solution as first example"
 
@@ -397,11 +398,11 @@ Documentation is successful when ALL of the following are true:
 - Present multiple matches
 - Let user choose: new doc, update existing, or link as duplicate
 
-**Module not in CORA-MODULES.md:**
+**Module not in modules documentation:**
 
 - Warn but don't block
 - Proceed with documentation
-- Suggest: "Add [Module] to CORA-MODULES.md if not there"
+- Suggest: "Add [Module] to modules documentation if not there"
 
 ---
 
@@ -488,7 +489,7 @@ File created:
 
 What's next?
 1. Continue workflow (recommended)
-2. Add to Required Reading - Promote to critical patterns (cora-critical-patterns.md)
+2. Add to Required Reading - Promote to critical patterns (critical-patterns.md)
 3. Link related issues - Connect to similar problems
 4. Add to existing skill - Add to a learning skill (e.g., hotwire-native)
 5. Create new skill - Extract into new learning skill

package/skills/compound-docs/assets/critical-pattern-template.md

@@ -1,6 +1,6 @@
 # Critical Pattern Template
 
-Use this template when adding a pattern to `docs/solutions/patterns/cora-critical-patterns.md`:
+Use this template when adding a pattern to `docs/solutions/patterns/critical-patterns.md`:
 
 ---
 

package/skills/compound-docs/assets/resolution-template.md

@@ -1,5 +1,5 @@
 ---
-module: [Module name or "CORA" for system-wide]
+module: [Module name or "System" for system-wide]
 date: [YYYY-MM-DD]
 problem_type: [build_error|test_failure|runtime_error|performance_issue|database_issue|security_issue|ui_bug|integration_issue|logic_error]
 component: [rails_model|rails_controller|rails_view|service_object|background_job|database|frontend_stimulus|hotwire_turbo|email_processing|brief_system|assistant|authentication|payments]
@@ -19,7 +19,7 @@ tags: [keyword1, keyword2, keyword3]
 [1-2 sentence clear description of the issue and what the user experienced]
 
 ## Environment
-- Module: [Name or "CORA system"]
+- Module: [Name or "System-wide"]
 - Rails Version: [e.g., 7.1.2]
 - Affected Component: [e.g., "Email Processing model", "Brief System service", "Authentication controller"]
 - Date: [YYYY-MM-DD when this was solved]
@@ -78,7 +78,7 @@ tags: [keyword1, keyword2, keyword3]
 
 ## Prevention
 
-[How to avoid this problem in future CORA development:]
+[How to avoid this problem in future development:]
 - [Specific coding practice, check, or pattern to follow]
 - [What to watch out for]
 - [How to catch this early]

package/skills/compound-docs/references/yaml-schema.md

@@ -1,10 +1,10 @@
 # YAML Frontmatter Schema
 
-**See `.claude/skills/codify-docs/schema.yaml` for the complete schema specification.**
+**See `.opencode/skills/compound-docs/schema.yaml` for the complete schema specification.**
 
 ## Required Fields
 
-- **module** (string): Module name (e.g., "EmailProcessing") or "CORA" for system-wide issues
+- **module** (string): Module name (e.g., "EmailProcessing") or "System" for system-wide issues
 - **date** (string): ISO 8601 date (YYYY-MM-DD)
 - **problem_type** (enum): One of [build_error, test_failure, runtime_error, performance_issue, database_issue, security_issue, ui_bug, integration_issue, logic_error, developer_experience, workflow_issue, best_practice, documentation_gap]
 - **component** (enum): One of [rails_model, rails_controller, rails_view, service_object, background_job, database, frontend_stimulus, hotwire_turbo, email_processing, brief_system, assistant, authentication, payments, development_workflow, testing_framework, documentation, tooling]

package/skills/create-agent-skills/SKILL.md

@@ -1,21 +1,35 @@
 ---
-name: creating-agent-skills
-description: Expert guidance for creating, writing, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.
+name: create-agent-skills
+description: Expert guidance for creating OpenCode skills and slash commands. Use when working with SKILL.md files, authoring new skills, improving existing skills, creating slash commands, or understanding skill structure and best practices.
 ---
 
-# Creating Agent Skills
+# Creating Skills & Commands
 
-This skill teaches how to create effective Claude Code Skills following Anthropic's official specification.
+This skill teaches how to create effective OpenCode skills following the official specification from [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills).
 
-## Core Principles
+## Commands and Skills Are Now The Same Thing
 
-### 1. Skills Are Prompts
+Custom slash commands have been merged into skills. A file at `.opencode/commands/review.md` and a skill at `.opencode/skills/review/SKILL.md` both create `/review` and work the same way. Existing `.opencode/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.
 
-All prompting best practices apply. Be clear, be direct. Assume Claude is smart - only add context Claude doesn't have.
+**If a skill and a command share the same name, the skill takes precedence.**
 
-### 2. Standard Markdown Format
+## When To Create What
 
-Use YAML frontmatter + markdown body. **No XML tags** - use standard markdown headings.
+**Use a command file** (`commands/name.md`) when:
+- Simple, single-file workflow
+- No supporting files needed
+- Task-oriented action (deploy, commit, triage)
+
+**Use a skill directory** (`skills/name/SKILL.md`) when:
+- Need supporting reference files, scripts, or templates
+- Background knowledge Claude should auto-load
+- Complex enough to benefit from progressive disclosure
+
+Both use identical YAML frontmatter and markdown content format.
+
+## Standard Markdown Format
+
+Use YAML frontmatter + markdown body with **standard markdown headings**. Keep it clean and direct.
 
 ```markdown
 ---
@@ -35,265 +49,228 @@ Step-by-step procedures...
 Concrete usage examples...
 ```
 
-### 3. Progressive Disclosure
+## Frontmatter Reference
 
-Keep SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed.
+All fields are optional. Only `description` is recommended.
 
-```
-my-skill/
-├── SKILL.md              # Entry point (required)
-├── reference.md          # Detailed docs (loaded when needed)
-├── examples.md           # Usage examples
-└── scripts/              # Utility scripts (executed, not loaded)
-```
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | No | Display name. Lowercase letters, numbers, hyphens (max 64 chars). Defaults to directory name. |
+| `description` | Recommended | What it does AND when to use it. Claude uses this for auto-discovery. Max 1024 chars. |
+| `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` |
+| `disable-model-invocation` | No | Set `true` to prevent Claude auto-loading. Use for manual workflows like `/deploy`, `/commit`. Default: `false`. |
+| `user-invocable` | No | Set `false` to hide from `/` menu. Use for background knowledge. Default: `true`. |
+| `allowed-tools` | No | Tools Claude can use without permission prompts. Example: `Read, Bash(git *)` |
+| `model` | No | Model to use. Options: `haiku`, `sonnet`, `opus`. |
+| `context` | No | Set `fork` to run in isolated subagent context. |
+| `agent` | No | Subagent type when `context: fork`. Options: `Explore`, `Plan`, `general-purpose`, or custom agent name. |
 
-### 4. Effective Descriptions
+### Invocation Control
 
-The description field enables skill discovery. Include both what the skill does AND when to use it. Write in third person.
+| Frontmatter | User can invoke | Claude can invoke | When loaded |
+|-------------|----------------|-------------------|-------------|
+| (default) | Yes | Yes | Description always in context, full content loads when invoked |
+| `disable-model-invocation: true` | Yes | No | Description not in context, loads only when user invokes |
+| `user-invocable: false` | No | Yes | Description always in context, loads when relevant |
+
+**Use `disable-model-invocation: true`** for workflows with side effects: `/deploy`, `/commit`, `/triage-prs`, `/send-slack-message`. You don't want Claude deciding to deploy because your code looks ready.
+
+**Use `user-invocable: false`** for background knowledge that isn't a meaningful user action: coding conventions, domain context, legacy system docs.
+
+## Dynamic Features
+
+### Arguments
+
+Use `$ARGUMENTS` placeholder for user input. If not present in content, arguments are appended automatically.
 
-**Good:**
 ```yaml
-description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+---
+name: fix-issue
+description: Fix a GitHub issue
+disable-model-invocation: true
+---
+
+Fix GitHub issue $ARGUMENTS following our coding standards.
 ```
 
-**Bad:**
+Access individual args: `$ARGUMENTS[0]` or shorthand `$0`, `$1`, `$2`.
+
+### Dynamic Context Injection
+
+The `` !`command` `` syntax runs shell commands before content is sent to Claude:
+
 ```yaml
-description: Helps with documents
-```
+---
+name: pr-summary
+description: Summarize changes in a pull request
+context: fork
+agent: Explore
+---
 
-## Skill Structure
+## Context
+- PR diff: !`gh pr diff`
+- Changed files: !`gh pr diff --name-only`
 
-### Required Frontmatter
+Summarize this pull request...
+```
 
-| Field | Required | Max Length | Description |
-|-------|----------|------------|-------------|
-| `name` | Yes | 64 chars | Lowercase letters, numbers, hyphens only |
-| `description` | Yes | 1024 chars | What it does AND when to use it |
-| `allowed-tools` | No | - | Tools Claude can use without asking |
-| `model` | No | - | Specific model to use |
+### Running in a Subagent
 
-### Naming Conventions
+Add `context: fork` to run in isolation. The skill content becomes the subagent's prompt. It won't have conversation history.
 
-Use **gerund form** (verb + -ing) for skill names:
+```yaml
+---
+name: deep-research
+description: Research a topic thoroughly
+context: fork
+agent: Explore
+---
 
-- `processing-pdfs`
-- `analyzing-spreadsheets`
-- `generating-commit-messages`
-- `reviewing-code`
+Research $ARGUMENTS thoroughly:
+1. Find relevant files
+2. Analyze the code
+3. Summarize findings
+```
 
-Avoid: `helper`, `utils`, `tools`, `anthropic-*`, `claude-*`
+## Progressive Disclosure
 
-### Body Structure
+Keep SKILL.md under 500 lines. Split detailed content into reference files:
 
-Use standard markdown headings:
+```
+my-skill/
+├── SKILL.md           # Entry point (required, overview + navigation)
+├── reference.md       # Detailed docs (loaded when needed)
+├── examples.md        # Usage examples (loaded when needed)
+└── scripts/
+    └── helper.py      # Utility script (executed, not loaded)
+```
 
-```markdown
-# Skill Name
+Link from SKILL.md: `For API details, see [reference.md](reference.md).`
 
-## Quick Start
-Fastest path to value...
+Keep references **one level deep** from SKILL.md. Avoid nested chains.
 
-## Instructions
-Core guidance Claude follows...
+## Effective Descriptions
 
-## Examples
-Input/output pairs showing expected behavior...
+The description enables skill discovery. Include both **what** it does and **when** to use it.
 
-## Advanced Features
-Additional capabilities (link to reference files)...
+**Good:**
+```yaml
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
 
-## Guidelines
-Rules and constraints...
+**Bad:**
+```yaml
+description: Helps with documents
 ```
 
 ## What Would You Like To Do?
 
 1. **Create new skill** - Build from scratch
-2. **Audit existing skill** - Check against best practices
-3. **Add component** - Add workflow/reference/example
-4. **Get guidance** - Understand skill design
+2. **Create new command** - Build a slash command
+3. **Audit existing skill** - Check against best practices
+4. **Add component** - Add workflow/reference/example
+5. **Get guidance** - Understand skill design
 
-## Creating a New Skill
+## Creating a New Skill or Command
 
 ### Step 1: Choose Type
 
-**Simple skill (single file):**
-- Under 500 lines
-- Self-contained guidance
-- No complex workflows
+Ask: Is this a manual workflow (deploy, commit, triage) or background knowledge (conventions, patterns)?
 
-**Progressive disclosure skill (multiple files):**
-- SKILL.md as overview
-- Reference files for detailed docs
-- Scripts for utilities
+- **Manual workflow** → command with `disable-model-invocation: true`
+- **Background knowledge** → skill without `disable-model-invocation`
+- **Complex with supporting files** → skill directory
 
-### Step 2: Create SKILL.md
+### Step 2: Create the File
 
+**Command:**
 ```markdown
 ---
-name: your-skill-name
-description: [What it does]. Use when [trigger conditions].
+name: my-command
+description: What this command does
+argument-hint: [expected arguments]
+disable-model-invocation: true
+allowed-tools: Bash(gh *), Read
 ---
 
-# Your Skill Name
+# Command Title
 
-## Quick Start
+## Workflow
 
-[Immediate actionable example]
+### Step 1: Gather Context
+...
 
-```[language]
-[Code example]
-```
+### Step 2: Execute
+...
 
-## Instructions
+## Success Criteria
+- [ ] Expected outcome 1
+- [ ] Expected outcome 2
+```
 
-[Core guidance]
+**Skill:**
+```markdown
+---
+name: my-skill
+description: What it does. Use when [trigger conditions].
+---
 
-## Examples
+# Skill Title
 
-**Example 1:**
-Input: [description]
-Output:
-```
-[result]
-```
+## Quick Start
+[Immediate actionable example]
 
-## Guidelines
+## Instructions
+[Core guidance]
 
-- [Constraint 1]
-- [Constraint 2]
+## Examples
+[Concrete input/output pairs]
 ```
 
 ### Step 3: Add Reference Files (If Needed)
 
 Link from SKILL.md to detailed content:
-
-```markdown
-For API reference, see [REFERENCE.md](REFERENCE.md).
-For form filling guide, see [FORMS.md](FORMS.md).
-```
-
-Keep references **one level deep** from SKILL.md.
-
-### Step 4: Add Scripts (If Needed)
-
-Scripts execute without loading into context:
-
 ```markdown
-## Utility Scripts
-
-Extract fields:
-```bash
-python scripts/analyze.py input.pdf > fields.json
-```
+For API reference, see [reference.md](reference.md).
+For form filling guide, see [forms.md](forms.md).
 ```
 
-### Step 5: Test With Real Usage
+### Step 4: Test With Real Usage
 
 1. Test with actual tasks, not test scenarios
-2. Observe where Claude struggles
-3. Refine based on real behavior
-4. Test with Haiku, Sonnet, and Opus
-
-## Auditing Existing Skills
+2. Invoke directly with `/skill-name` to verify
+3. Check auto-triggering by asking something that matches the description
+4. Refine based on real behavior
 
-Check against this rubric:
+## Audit Checklist
 
 - [ ] Valid YAML frontmatter (name + description)
-- [ ] Description includes trigger keywords
+- [ ] Description includes trigger keywords and is specific
 - [ ] Uses standard markdown headings (not XML tags)
 - [ ] SKILL.md under 500 lines
-- [ ] References one level deep
+- [ ] `disable-model-invocation: true` if it has side effects
+- [ ] `allowed-tools` set if specific tools needed
+- [ ] References one level deep, properly linked
 - [ ] Examples are concrete, not abstract
-- [ ] Consistent terminology
-- [ ] No time-sensitive information
-- [ ] Scripts handle errors explicitly
-
-## Common Patterns
-
-### Template Pattern
-
-Provide output templates for consistent results:
-
-```markdown
-## Report Template
-
-```markdown
-# [Analysis Title]
-
-## Executive Summary
-[One paragraph overview]
-
-## Key Findings
-- Finding 1
-- Finding 2
-
-## Recommendations
-1. [Action item]
-2. [Action item]
-```
-```
-
-### Workflow Pattern
-
-For complex multi-step tasks:
-
-```markdown
-## Migration Workflow
-
-Copy this checklist:
-
-```
-- [ ] Step 1: Backup database
-- [ ] Step 2: Run migration script
-- [ ] Step 3: Validate output
-- [ ] Step 4: Update configuration
-```
-
-**Step 1: Backup database**
-Run: `./scripts/backup.sh`
-...
-```
-
-### Conditional Pattern
-
-Guide through decision points:
-
-```markdown
-## Choose Your Approach
-
-**Creating new content?** Follow "Creation workflow" below.
-**Editing existing?** Follow "Editing workflow" below.
-```
+- [ ] Tested with real usage
 
 ## Anti-Patterns to Avoid
 
-- **XML tags in body** - Use markdown headings instead
+- **XML tags in body** - Use standard markdown headings
 - **Vague descriptions** - Be specific with trigger keywords
 - **Deep nesting** - Keep references one level from SKILL.md
+- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
 - **Too many options** - Provide a default with escape hatch
-- **Windows paths** - Always use forward slashes
-- **Punting to Claude** - Scripts should handle errors
-- **Time-sensitive info** - Use "old patterns" section instead
+- **Punting to Claude** - Scripts should handle errors explicitly
 
 ## Reference Files
 
 For detailed guidance, see:
-
-- [official-spec.md](references/official-spec.md) - Anthropic's official skill specification
+- [official-spec.md](references/official-spec.md) - Official skill specification
 - [best-practices.md](references/best-practices.md) - Skill authoring best practices
 
-## Success Criteria
+## Sources
 
-A well-structured skill:
-- Has valid YAML frontmatter with descriptive name and description
-- Uses standard markdown headings (not XML tags)
-- Keeps SKILL.md under 500 lines
-- Links to reference files for detailed content
-- Includes concrete examples with input/output pairs
-- Has been tested with real usage
-
-Sources:
-- [Agent Skills - Claude Code Docs](https://code.claude.com/docs/en/skills)
-- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+- [Extend Claude with skills - Official Docs](https://code.claude.com/docs/en/skills)
 - [GitHub - anthropics/skills](https://github.com/anthropics/skills)
+