@fro.bot/systematic 1.20.2 → 1.21.0

package/commands/workflows/plan.md

@@ -1,7 +1,7 @@
 ---
 name: workflows:plan
 description: Transform feature descriptions into well-structured project plans following conventions
-argument-hint: '[feature description, bug report, or improvement idea]'
+argument-hint: "[feature description, bug report, or improvement idea]"
 ---
 
 # Create a plan for a new feature or bug fix
@@ -36,11 +36,19 @@ ls -la docs/brainstorms/*.md 2>/dev/null | head -10
 - If multiple candidates match, use the most recent one
 
 **If a relevant brainstorm exists:**
-1. Read the brainstorm document
-2. Announce: "Found brainstorm from [date]: [topic]. Using as context for planning."
-3. Extract key decisions, chosen approach, and open questions
-4. **Skip the idea refinement questions below** - the brainstorm already answered WHAT to build
-5. Use brainstorm decisions as input to the research phase
+1. Read the brainstorm document **thoroughly** — every section matters
+2. Announce: "Found brainstorm from [date]: [topic]. Using as foundation for planning."
+3. Extract and carry forward **ALL** of the following into the plan:
+   - Key decisions and their rationale
+   - Chosen approach and why alternatives were rejected
+   - Constraints and requirements discovered during brainstorming
+   - Open questions (flag these for resolution during planning)
+   - Success criteria and scope boundaries
+   - Any specific technical choices or patterns discussed
+4. **Skip the idea refinement questions below** — the brainstorm already answered WHAT to build
+5. Use brainstorm content as the **primary input** to research and planning phases
+6. **Critical: The brainstorm is the origin document.** Throughout the plan, reference specific decisions with `(see brainstorm: docs/brainstorms/<filename>)` when carrying forward conclusions. Do not paraphrase decisions in a way that loses their original context — link back to the source.
+7. **Do not omit brainstorm content** — if the brainstorm discussed it, the plan must address it (even if briefly). Scan each brainstorm section before finalizing the plan to verify nothing was dropped.
 
 **If multiple brainstorms could match:**
 Use **question tool** to ask which brainstorm to use, or whether to proceed without one.
@@ -150,7 +158,7 @@ Think like a product manager - what would make this issue clear and actionable?
 
 After planning the issue structure, run SpecFlow Analyzer to validate and refine the feature specification:
 
-- task spec-flow-analyzer(feature_description, research_findings)
+- task systematic:workflow:spec-flow-analyzer(feature_description, research_findings)
 
 **SpecFlow Analyzer Output:**
 
@@ -180,6 +188,7 @@ title: [Issue Title]
 type: [feat|fix|refactor]
 status: active
 date: YYYY-MM-DD
+origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md  # if originated from brainstorm, otherwise omit
 ---
 
 # [Issue Title]
@@ -207,8 +216,9 @@ class Test
 end
 ```
 
-## References
+## Sources
 
+- **Origin brainstorm:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm
 - Related issue: #[issue_number]
 - Documentation: [relevant_docs_url]
 ````
@@ -233,6 +243,7 @@ title: [Issue Title]
 type: [feat|fix|refactor]
 status: active
 date: YYYY-MM-DD
+origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md  # if originated from brainstorm, otherwise omit
 ---
 
 # [Issue Title]
@@ -277,8 +288,9 @@ date: YYYY-MM-DD
 
 [What could block or complicate this]
 
-## References & Research
+## Sources & References
 
+- **Origin brainstorm:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm
 - Similar implementations: [file_path:line_number]
 - Best practices: [documentation_url]
 - Related PRs: #[pr_number]
@@ -306,6 +318,7 @@ title: [Issue Title]
 type: [feat|fix|refactor]
 status: active
 date: YYYY-MM-DD
+origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md  # if originated from brainstorm, otherwise omit
 ---
 
 # [Issue Title]
@@ -416,7 +429,11 @@ date: YYYY-MM-DD
 
 [What docs need updating]
 
-## References & Research
+## Sources & References
+
+### Origin
+
+- **Brainstorm document:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm. Key decisions carried forward: [list 2-3 major decisions from brainstorm]
 
 ### Internal References
 
@@ -495,6 +512,16 @@ end
 
 ### 6. Final Review & Submission
 
+**Brainstorm cross-check (if plan originated from a brainstorm):**
+
+Before finalizing, re-read the brainstorm document and verify:
+- [ ] Every key decision from the brainstorm is reflected in the plan
+- [ ] The chosen approach matches what was decided in the brainstorm
+- [ ] Constraints and requirements from the brainstorm are captured in acceptance criteria
+- [ ] Open questions from the brainstorm are either resolved or flagged
+- [ ] The `origin:` frontmatter field points to the brainstorm file
+- [ ] The Sources section includes the brainstorm with a summary of carried-forward decisions
+
 **Pre-submission Checklist:**
 
 - [ ] Title is searchable and descriptive
@@ -513,7 +540,7 @@ end
 mkdir -p docs/plans/
 ```
 
-Use the write tool to save the complete plan to `docs/plans/YYYY-MM-DD-<type>-<descriptive-name>-plan.md`. This step is mandatory and cannot be skipped — even when running as part of LFG/SLFG or other automated pipelines.
+Use the Write tool to save the complete plan to `docs/plans/YYYY-MM-DD-<type>-<descriptive-name>-plan.md`. This step is mandatory and cannot be skipped — even when running as part of LFG/SLFG or other automated pipelines.
 
 Confirm: "Plan written to docs/plans/[filename]"
 
@@ -548,6 +575,7 @@ After writing the plan file, use the **question tool** to present these options:
 3. **Run `/technical_review`** - Technical feedback from code-focused reviewers (DHH, Kieran, Simplicity)
 4. **Review and refine** - Improve the document through structured self-review
 5. **Start `/workflows:work`** - Begin implementing this plan locally
+6. **Start `/workflows:work` on remote** - Begin implementing in OpenCode on the web (use `&` to run in background)
 7. **Create Issue** - Create issue in project tracker (GitHub/Linear)
 
 Based on selection:
@@ -556,7 +584,7 @@ Based on selection:
 - **`/technical_review`** → Call the /technical_review command with the plan file path
 - **Review and refine** → Load `document-review` skill.
 - **`/workflows:work`** → Call the /workflows:work command with the plan file path
-- **`/workflows:work` on remote** → Run `/workflows:work docs/plans/<plan_filename>.md &` to start work in background
+- **`/workflows:work` on remote** → Run `/workflows:work docs/plans/<plan_filename>.md &` to start work in background for OpenCode web
 - **Create Issue** → See "Issue Creation" section below
 - **Other** (automatically provided) → Accept free text for rework or specific changes
 

package/package.json

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

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. 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.
+Software agents work reliably now. OpenCode 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 an agent refactor a codebase can let it 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 OpenCode refactor a codebase can let an agent organize your files, manage your reading list, or automate your workflows.
 
-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.
+The OpenCode 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.
 
-This opens up a new field: software that works the way modern coding agents work, applied to categories far beyond coding.
+This opens up a new field: software that works the way OpenCode works, applied to categories far beyond coding.
 </why_now>
 
 <core_principles>

package/skills/agent-native-architecture/references/agent-execution-patterns.md

@@ -61,7 +61,7 @@ extension ToolResult {
     }
 
     static func complete(_ summary: String) -> ToolResult {
-        // Task done, stop the loop
+        // task done, stop the loop
         ToolResult(success: true, output: summary, shouldContinue: false)
     }
 }
@@ -165,7 +165,7 @@ Progress: 3/5 tasks complete (60%)
 - Resume continues from where it left off, not from beginning
 
 **Agent fails on one task:**
-- Task marked `.failed` with error in notes
+- task marked `.failed` with error in notes
 - Other tasks may continue (agent decides)
 - Orchestrator doesn't automatically abort entire session
 
@@ -183,7 +183,7 @@ struct AgentCheckpoint: Codable {
     let agentType: String
     let messages: [Message]          // Full conversation history
     let iterationCount: Int
-    let tasks: [AgentTask]           // Task state
+    let tasks: [AgentTask]           // task state
     let customState: [String: Any]   // Agent-specific state
     let timestamp: Date
 

package/skills/andrew-kane-gem-writer/SKILL.md

@@ -182,4 +182,3 @@ For deeper patterns, see:
 - **[references/database-adapters.md](references/database-adapters.md)** - Multi-database support patterns
 - **[references/testing-patterns.md](references/testing-patterns.md)** - Multi-version testing, CI setup
 - **[references/resources.md](references/resources.md)** - Links to Kane's repos and articles
-

package/skills/compound-docs/SKILL.md

@@ -3,10 +3,10 @@ name: compound-docs
 description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup
 disable-model-invocation: true
 allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Grep
+  - Read # Parse conversation context
+  - Write # Create resolution docs
+  - Bash # Create directories
+  - Grep # Search existing docs
 preconditions:
   - Problem has been solved (not in-progress)
   - Solution has been verified working
@@ -327,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 .opencode/skills/create-agent-skills/scripts/init_skill.py [skill-name]`
+2. Run `python3 .opencode/skills/skill-creator/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"
 

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

@@ -1,6 +1,6 @@
 # YAML Frontmatter Schema
 
-**See `.opencode/skills/compound-docs/schema.yaml` for the complete schema specification.**
+**See `schema.yaml` for the complete schema specification.**
 
 ## Required Fields
 

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

@@ -273,4 +273,3 @@ For detailed guidance, see:
 
 - [Extend Claude with skills - Official Docs](https://code.claude.com/docs/en/skills)
 - [GitHub - anthropics/skills](https://github.com/anthropics/skills)
-

package/skills/create-agent-skills/references/official-spec.md

@@ -80,7 +80,7 @@ Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict
 | `$ARGUMENTS` | All arguments passed when invoking |
 | `$ARGUMENTS[N]` | Specific argument by 0-based index |
 | `$N` | Shorthand for `$ARGUMENTS[N]` |
-| `${CLAUDE_SESSION_ID}` | Current session ID |
+| `N/A` | Current session ID |
 
 ## Dynamic Context Injection
 

package/skills/create-agent-skills/workflows/create-new-skill.md

@@ -18,7 +18,7 @@
 **If user just invoked skill without context:**
 → Ask what they want to build
 
-### Using question tool
+### Using question
 
 Ask 2-4 domain-specific questions based on actual gaps. Each question should:
 - Have specific options with descriptions
@@ -42,7 +42,7 @@ Options:
 
 ## Step 2: Research Trigger (If External API)
 
-**When external service detected**, ask using question tool:
+**When external service detected**, ask using question:
 "This involves [service name] API. Would you like me to research current endpoints and patterns before building?"
 
 Options:

package/skills/create-agent-skills/workflows/get-guidance.md

@@ -17,7 +17,7 @@ Ask the user:
 ## Step 2: Determine If a Skill Is Right
 
 **Create a skill when:**
-- Task is repeated across multiple sessions
+- task is repeated across multiple sessions
 - Domain knowledge doesn't change frequently
 - Complex enough to benefit from structure
 - Would save significant time if automated

package/skills/dhh-rails-style/SKILL.md

@@ -183,4 +183,3 @@ Based on [The Unofficial 37signals/DHH Rails Style Guide](https://github.com/mar
 - Code examples from Fizzy are licensed under the O'Saasy License
 - Not affiliated with or endorsed by 37signals
 </credits>
-

package/skills/dspy-ruby/SKILL.md

@@ -735,4 +735,3 @@ end
 ## Version
 
 Current: 0.34.3
-

package/skills/every-style-editor/SKILL.md

@@ -132,4 +132,3 @@ Based on Every's style guide, pay special attention to:
 - Word usage (fewer vs. less, they vs. them)
 - Company references (singular "it", teams as plural "they")
 - Job title capitalization
-

package/skills/gemini-imagegen/SKILL.md

@@ -235,4 +235,3 @@ file image.png
 - Image-only mode (`responseModalities: ["IMAGE"]`) won't work with Google Search grounding
 - For editing, describe changes conversationally—the model understands semantic masking
 - Default to 1K resolution for speed; use 2K/4K when quality is critical
-

package/skills/git-worktree/SKILL.md

@@ -300,4 +300,3 @@ cd $(git rev-parse --show-toplevel)
 - No repository duplication
 - Shared git objects for efficiency
 - Much faster than cloning or stashing/switching
-

package/skills/rclone/SKILL.md

@@ -148,4 +148,3 @@ rclone lsd remote: -vv
 # Check config
 rclone config show remote
 ```
-

package/skills/resolve-pr-parallel/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: resolve_pr_parallel
 description: Resolve all PR comments using parallel processing. Use when addressing PR review feedback, resolving review threads, or batch-fixing PR comments.
-argument-hint: '[optional: PR number or current PR]'
+argument-hint: "[optional: PR number or current PR]"
 disable-model-invocation: true
 allowed-tools: Bash(gh *), Bash(git *), Read
 ---
@@ -24,7 +24,7 @@ OpenCode automatically detects git context:
 Fetch unresolved review threads using the GraphQL script:
 
 ```bash
-bash ${OPENCODE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/get-pr-comments PR_NUMBER
+bash scripts/get-pr-comments PR_NUMBER
 ```
 
 This returns only **unresolved, non-outdated** threads with file paths, line numbers, and comment bodies.
@@ -61,7 +61,7 @@ Always run all in parallel subagents/Tasks for each Todo item.
 - Resolve each thread programmatically:
 
 ```bash
-bash ${OPENCODE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/resolve-pr-thread THREAD_ID
+bash scripts/resolve-pr-thread THREAD_ID
 ```
 
 - Push to remote
@@ -71,7 +71,7 @@ bash ${OPENCODE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/resolve-pr-threa
 Re-fetch comments to confirm all threads are resolved:
 
 ```bash
-bash ${OPENCODE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/get-pr-comments PR_NUMBER
+bash scripts/get-pr-comments PR_NUMBER
 ```
 
 Should return an empty array `[]`. If threads remain, repeat from step 1.
@@ -87,4 +87,3 @@ Should return an empty array `[]`. If threads remain, repeat from step 1.
 - Changes committed and pushed
 - Threads resolved via GraphQL (marked as resolved on GitHub)
 - Empty result from get-pr-comments on verify
-

package/skills/resolve-pr-parallel/scripts/get-pr-comments

@@ -5,7 +5,7 @@ set -e
 if [ $# -lt 1 ]; then
     echo "Usage: get-pr-comments PR_NUMBER [OWNER/REPO]"
     echo "Example: get-pr-comments 123"
-    echo "Example: get-pr-comments 123 owner/repo"
+    echo "Example: get-pr-comments 123 EveryInc/cora"
     exit 1
 fi
 

package/skills/setup/SKILL.md

@@ -53,7 +53,7 @@ options:
     description: "Choose stack, focus areas, and review depth."
 ```
 
-### If Auto-configure → Skip to Step 4 with defaults
+### If Auto-configure → Skip to Step 4 with defaults:
 
 - **Rails:** `[kieran-rails-reviewer, dhh-rails-reviewer, code-simplicity-reviewer, security-sentinel, performance-oracle]`
 - **Python:** `[kieran-python-reviewer, code-simplicity-reviewer, security-sentinel, performance-oracle]`

package/skills/skill-creator/SKILL.md

@@ -208,4 +208,3 @@ After testing the skill, users may request improvements. Often this happens righ
 2. Notice struggles or inefficiencies
 3. Identify how SKILL.md or bundled resources should be updated
 4. Implement changes and test again
-