super-opencode 1.1.2 → 1.2.0

package/.opencode/commands/soc-validate.md

@@ -0,0 +1,221 @@
+---
+description: "Requirements validation, traceability matrices, and acceptance criteria verification"
+---
+
+# /soc-validate
+
+## 1. Command Overview
+
+The `/soc-validate` command is the "Quality Gate" between design and implementation. It ensures requirements are complete, unambiguous, and testable before coding begins. It creates traceability matrices that map requirements to tests, designs, and implementation artifacts—ensuring nothing falls through the cracks.
+
+## 2. Triggers & Routing
+
+The command activates validation modes based on what needs verification.
+
+| Trigger Scenario | Flag | Target Agent | Context Injected |
+| :--- | :--- | :--- | :--- |
+| **Requirements Review** | `--type requirements` | `[pm-agent]` | User Stories, Acceptance Criteria |
+| **Design Validation** | `--type design` | `[architect]` | ADRs, API Contracts, Schemas |
+| **Test Coverage Check** | `--type coverage` | `[quality]` | Test Plans, Code Coverage Reports |
+| **Full Validation** | `--type full` | `[pm-agent]` + `[quality]` + `[architect]` | All artifacts |
+
+## 3. Usage & Arguments
+
+```bash
+/soc-validate [target] [flags]
+```
+
+### Arguments
+
+- **`[target]`**: The artifact to validate (e.g., "User Auth Requirements", "API v2 Design", "Sprint 5").
+
+### Flags
+
+- **`--type [requirements|design|coverage|full]`**: **MANDATORY**. Specifies validation scope.
+- **`--strict [lenient|normal|strict]`**: Validation strictness (default: normal).
+- **`--output [report|matrix|checklist]`**: Output format (default: report).
+- **`--block-on-fail`**: Return non-zero exit code if validation fails (for CI/CD).
+
+## 4. Behavioral Flow (Orchestration)
+
+### Phase 1: Artifact Discovery
+
+1. **Read**: Parse target requirements/design documents.
+2. **Collect**: Gather related artifacts (tests, code, ADRs).
+3. **Baseline**: Establish validation criteria based on `--strict` level.
+
+### Phase 2: Validation Checks
+
+#### Requirements Validation (`--type requirements`):
+- **INVEST Check**: Are stories Independent, Negotiable, Valuable, Estimable, Small, Testable?
+- **Acceptance Criteria**: Are Gherkin-style Given/When/Then statements present?
+- **Ambiguity Scan**: Flag vague terms ("fast", "user-friendly", "soon").
+- **Completeness**: Verify all user personas have journeys.
+
+#### Design Validation (`--type design`):
+- **ADR Completeness**: Does every major decision have an ADR?
+- **API Contract**: Are request/response schemas defined?
+- **Security Review**: Does design address authZ, authN, data protection?
+- **Scalability**: Are load/performance targets specified?
+
+#### Coverage Validation (`--type coverage`):
+- **Traceability Matrix**: Map each requirement to test cases.
+- **Coverage Gaps**: Identify requirements with no tests.
+- **Orphan Tests**: Find tests that don't map to requirements.
+
+### Phase 3: Report Generation
+
+- **Consolidate**: Aggregate all validation findings.
+- **Score**: Calculate validation score (% of criteria met).
+- **Blocker Flag**: Mark items that must be resolved before implementation.
+- **Export**: Generate validation report.
+
+## 5. Output Guidelines (The Contract)
+
+### Validation Report Template
+
+```markdown
+# Validation Report: [Target Name]
+
+## Summary
+**Validation Type**: Requirements  
+**Strictness Level**: Normal  
+**Overall Score**: 87% (✅ PASS / ❌ FAIL)  
+**Blockers**: 2 (Must resolve before implementation)  
+**Warnings**: 5 (Should address)  
+**Date**: 2026-01-30
+
+## Detailed Findings
+
+### ✅ Passed Checks
+
+| Check | Details |
+|:-----|:--------|
+| INVEST - Independent | All stories are self-contained |
+| INVEST - Testable | Acceptance criteria use Gherkin syntax |
+| API Contracts | All endpoints have Zod schemas |
+
+### ⚠️ Warnings (Should Fix)
+
+| ID | Category | Issue | Recommendation | Severity |
+|:---|:---------|:------|:---------------|:--------:|
+| W-001 | Ambiguity | Story US-004 says "fast response" | Define specific SLA (<200ms) | Medium |
+| W-002 | Completeness | No error handling requirements | Add failure scenarios | Medium |
+
+### 🛑 Blockers (Must Fix)
+
+| ID | Category | Issue | Recommendation | Severity |
+|:---|:---------|:------|:---------------|:--------:|
+| B-001 | Security | No authentication requirements | Add auth flows and token handling | Critical |
+| B-002 | Testability | US-007 lacks acceptance criteria | Add Given/When/Then scenarios | High |
+
+## Traceability Matrix
+
+| Requirement | Design | Test Case | Status |
+|:------------|:-------|:----------|:------:|
+| US-001: User login | ADR-003 | TC-001, TC-002 | ✅ Covered |
+| US-002: Password reset | ADR-003 | ❌ None | ❌ Gap |
+| US-003: OAuth | ADR-005 | TC-003 | ✅ Covered |
+
+## Recommendations
+
+1. **Immediate**: Resolve B-001 (security) before any implementation.
+2. **Before Sprint**: Add acceptance criteria to US-007.
+3. **Nice to Have**: Quantify performance requirements (replace "fast" with SLA).
+
+## Sign-off
+
+- [ ] Requirements validated
+- [ ] Blockers resolved
+- [ ] Ready for implementation
+```
+
+### Quick Checklist Output
+
+```markdown
+## Validation Checklist: [Target]
+
+### Requirements
+- [x] All stories follow INVEST principles
+- [x] Acceptance criteria present
+- [ ] No ambiguous language (2 found)
+- [x] User personas defined
+
+### Design
+- [x] ADRs for major decisions
+- [ ] API contracts complete (1 missing)
+- [x] Security considerations documented
+
+### Test Coverage
+- [x] Traceability matrix created
+- [ ] 100% requirement coverage (87% actual)
+- [x] Orphan tests identified
+
+**Result**: ⚠️ PARTIAL - Address 3 items before proceeding
+```
+
+## 6. Examples
+
+### A. Requirements Validation
+
+```bash
+/soc-validate "User Authentication Epic" --type requirements --strict strict
+```
+
+*Effect:* Validates all user stories in the auth epic against INVEST principles, flags ambiguous language, and ensures acceptance criteria follow Gherkin syntax.
+
+### B. Full Project Validation
+
+```bash
+/soc-validate "v2.0 Release" --type full --output matrix --block-on-fail
+```
+
+*Effect:* Runs comprehensive validation across requirements, design, and test coverage. Generates a traceability matrix and exits with error code if blockers found (for CI/CD gates).
+
+### C. Design-Only Check
+
+```bash
+/soc-validate "Payment API Design" --type design --output checklist
+```
+
+*Effect:* Validates the payment API design has complete ADRs, proper schemas, security considerations, and scalability plans. Outputs a quick checklist format.
+
+## 7. Dependencies & Capabilities
+
+### Agents
+
+- **Orchestrator**: `[pm-agent]` - Requirements validation and acceptance criteria review.
+- **Technical Validator**: `[architect]` - Design and ADR validation.
+- **Quality Validator**: `[quality]` - Test coverage and traceability analysis.
+
+### Skills
+
+- **Confidence Check**: `@[.opencode/skills/confidence-check/SKILL.md]` - Ensures validation criteria are clear.
+- **Security Audit**: `@[.opencode/skills/security-audit/SKILL.md]` - Validates security requirements.
+- **Self Check**: `@[.opencode/skills/self-check/SKILL.md]` - Validates validation process itself (meta!).
+
+### MCP Integration
+
+- **`read_file`**: Parse requirements, designs, and test files.
+- **`grep`**: Search for patterns (e.g., "TODO", "FIXME", ambiguous terms).
+- **`sequential-thinking`**: Analyze complex requirement dependencies.
+
+## 8. Boundaries
+
+**Will:**
+
+- Validate requirements against industry standards (INVEST, SMART, Gherkin).
+- Create traceability matrices linking requirements to tests and designs.
+- Flag ambiguous or incomplete requirements.
+- Block implementation if critical gaps found (with `--block-on-fail`).
+
+**Will Not:**
+
+- **Auto-Fix Issues**: Identifies problems but doesn't rewrite requirements.
+- **Write Tests**: Validates test coverage exists, but doesn't create tests.
+- **Override Business Decisions**: Flags concerns but doesn't change requirements without user approval.
+- **Validate Implementation**: Checks design/requirements only—use `/soc-review` for code review.
+
+## User Instruction
+
+The user have executed the `/soc-validate` command by parsing the user's arguments provided in `<user-instruction>$ARGUMENTS</user-instruction>`, then route to the appropriate validation type (requirements, design, coverage, or full), read and parse the target artifacts (requirements documents, ADRs, test files), apply validation checks based on strictness level (INVEST, Gherkin, ambiguity detection, coverage analysis), identify blockers that must be resolved before implementation, generate a comprehensive validation report with traceability matrix, output findings in the requested format (report, matrix, or checklist), and if `--block-on-fail` is set, signal failure when blockers are present.

package/.opencode/commands/soc-workflow.md

@@ -5,9 +5,11 @@ description: Custom workflow creation and execution
 # /soc-workflow
 
 ## 1. Command Overview
+
 The `/soc-workflow` command is the "Factory." It allows users to create, list, and run custom sequences of agent commands. It turns a manual, multi-step process (e.g., "Check status -> Pull -> Build -> Deploy") into a single executable command.
 
 ## 2. Triggers & Routing
+
 The command is a meta-orchestrator.
 
 | Trigger Scenario | Flag | Action |
@@ -17,29 +19,34 @@ The command is a meta-orchestrator.
 | **List Available** | `list` | Scans directory for `.md` files |
 
 ## 3. Usage & Arguments
+
 ```bash
 /soc-workflow [action] [name]
 ```
 
 ### Arguments
--   **`[action]`**: `create`, `run`, `list`, `edit`, `delete`.
--   **`[name]`**: Name of the workflow (e.g., `deploy`).
+
+- **`[action]`**: `create`, `run`, `list`, `edit`, `delete`.
+- **`[name]`**: Name of the workflow (e.g., `deploy`).
 
 ## 4. Behavioral Flow (Orchestration)
 
 ### Phase 1: Definition (Create)
-1.  **Template**: Creates a standard markdown file with "Steps."
-2.  **Define**: User fills in shell commands or agent commands (`/soc-git`, `/soc-test`).
+
+1. **Template**: Creates a standard markdown file with "Steps."
+2. **Define**: User fills in shell commands or agent commands (`/soc-git`, `/soc-test`).
 
 ### Phase 2: Execution (Run)
-1.  **Parse**: Reads the markdown.
-2.  **Step**: Executes step 1.
-3.  **Check**: If step 1 fails, stop (unless `continue_on_error: true`).
-4.  **Next**: Proceed to step 2.
+
+1. **Parse**: Reads the markdown.
+2. **Step**: Executes step 1.
+3. **Check**: If step 1 fails, stop (unless `continue_on_error: true`).
+4. **Next**: Proceed to step 2.
 
 ## 5. Output Guidelines (The Contract)
 
 ### Workflow Definition (Template)
+
 ```markdown
 ---
 description: Deploy to Staging
@@ -51,6 +58,7 @@ description: Deploy to Staging
 ```
 
 ### Execution Log
+
 ```markdown
 ## Workflow: Deploy Staging
 1.  [x] **Test**: Passed (2s)
@@ -62,36 +70,49 @@ description: Deploy to Staging
 ## 6. Examples
 
 ### A. Create Release Workflow
+
 ```bash
 /soc-workflow create release
 ```
+
 *Effect:* Creates `.agent/workflows/release.md` for the user to edit.
 
 ### B. Run Nightly Build
+
 ```bash
 /soc-workflow run nightly
 ```
+
 *Effect:* Runs the sequence defined in `nightly.md`.
 
 ## 7. Dependencies & Capabilities
 
 ### Agents
--   **PM Agent**: `@[.opencode/agents/pm-agent.md]` - For oversight.
+
+- **PM Agent**: `@[.opencode/agents/pm-agent.md]` - For oversight.
 
 ### Skills
--   **None**: It relies on other commands.
+
+- **None**: It relies on other commands.
 
 ### MCP Integration
--   **`filesystem`**: Reading/Writing workflow files.
--   **`run_command`**: Executing shell steps.
+
+- **`filesystem`**: Reading/Writing workflow files.
+- **`run_command`**: Executing shell steps.
 
 ## 8. Boundaries
 
 **Will:**
--   Execute commands in sequence.
--   Stop on error.
--   Pass context between steps.
+
+- Execute commands in sequence.
+- Stop on error.
+- Pass context between steps.
 
 **Will Not:**
--   **Auto-Debug**: If a step fails, the workflow just stops.
--   **Parallize**: Steps are currently sequential only.
+
+- **Auto-Debug**: If a step fails, the workflow just stops.
+- **Parallize**: Steps are currently sequential only.
+
+## User Instruction
+
+The user have executed the `/soc-workflow` command by parsing the user's arguments provided in `<user-instruction>$ARGUMENTS</user-instruction>`, then perform the specified action (create, run, list, edit, or delete) on the named workflow, create a new workflow template in `.agent/workflows/` when the action is `create`, list all available workflows when the action is `list`, parse and execute workflow steps in sequence when the action is `run`—stopping on error unless `continue_on_error` is specified, pass context between steps, and generate an execution log showing the status of each step and overall workflow completion.

package/.opencode/skills/confidence-check/SKILL.md

@@ -6,11 +6,13 @@ description: Pre-execution risk assessment to prevent hallucinations and archite
 # Confidence Check Skill
 
 ## Purpose
+
 To calculate a probabilistic "Success Score" (0.0 - 1.0) **before** generating code. This acts as a circuit breaker for the `execution` mode.
 
 **ROI Metric**: A 200-token analysis prevents 2,000+ tokens of incorrect code generation and subsequent debugging time.
 
 ## When to Use
+
 - **Automatic Trigger**: Before any `write_file` operation affecting > 50 lines of code.
 - **Manual Trigger**: When requirements are vague (e.g., "Fix the bug").
 - **Agent Handoff**: When `pm-agent` assigns a task to `backend` or `frontend`.
@@ -28,20 +30,23 @@ To calculate a probabilistic "Success Score" (0.0 - 1.0) **before** generating c
 ## Scoring & Protocols
 
 ### 🟢 High Confidence (≥ 0.90)
+
 **Action**: **PROCEED** to `execution` mode.
-*   *Definition:* You have the file paths, the schema is defined, you have verified the library version, and you have a rollback plan.
+- *Definition:* You have the file paths, the schema is defined, you have verified the library version, and you have a rollback plan.
 
 ### 🟡 Medium Confidence (0.70 - 0.89)
+
 **Action**: **REFINE** before coding.
-*   *Protocol:* Identify the weak pillar and fix it.
-    *   *Weak Docs?* -> Trigger `researcher` to fetch API refs.
-    *   *Weak Specs?* -> Trigger `architect` to define the interface.
-    *   *Weak Context?* -> Run `grep` to find usages.
+- *Protocol:* Identify the weak pillar and fix it.
+  - *Weak Docs?* -> Trigger `researcher` to fetch API refs.
+  - *Weak Specs?* -> Trigger `architect` to define the interface.
+  - *Weak Context?* -> Run `grep` to find usages.
 
 ### 🔴 Low Confidence (< 0.70)
+
 **Action**: **HALT**.
-*   *Protocol:* Do not write code. Return control to `pm-agent` or ask the user clarifying questions.
-    *   *Example:* "I cannot proceed. I do not know the expected return type of the API, and I cannot find a design pattern for this module."
+- *Protocol:* Do not write code. Return control to `pm-agent` or ask the user clarifying questions.
+  - *Example:* "I cannot proceed. I do not know the expected return type of the API, and I cannot find a design pattern for this module."
 
 ## Execution Template
 
@@ -81,17 +86,19 @@ To calculate a probabilistic "Success Score" (0.0 - 1.0) **before** generating c
 ## Scenario Examples
 
 ### Scenario A: Adding a new API Endpoint
-*   **Context**: Read `server.ts`? Yes.
-*   **Spec**: No request schema defined. (**0**)
-*   **Docs**: Know Express well. (0.2)
-*   **Pattern**: Copied existing controller style. (0.15)
-*   **Risk**: Low. (0.15)
-*   **Total**: **0.75 (Medium)**
-*   **Action**: *STOP. Call `backend` agent to define Zod schema first. Then Proceed.*
+
+* **Context**: Read `server.ts`? Yes.
+- **Spec**: No request schema defined. (**0**)
+- **Docs**: Know Express well. (0.2)
+- **Pattern**: Copied existing controller style. (0.15)
+- **Risk**: Low. (0.15)
+- **Total**: **0.75 (Medium)**
+- **Action**: *STOP. Call `backend` agent to define Zod schema first. Then Proceed.*
 
 ### Scenario B: "Fix the white screen"
-*   **Context**: No error logs provided. (**0**)
-*   **Spec**: Unknown. (**0**)
-*   **Docs**: N/A.
-*   **Total**: **0.15 (Low)**
-*   **Action**: *HALT. Ask user for logs or reproduction steps. Trigger `brainstorming` mode.*
+
+* **Context**: No error logs provided. (**0**)
+- **Spec**: Unknown. (**0**)
+- **Docs**: N/A.
+- **Total**: **0.15 (Low)**
+- **Action**: *HALT. Ask user for logs or reproduction steps. Trigger `brainstorming` mode.*

package/.opencode/skills/debug-protocol/SKILL.md

@@ -6,42 +6,52 @@ description: Scientific debugging workflow using Root Cause Analysis and Minimal
 # Debug Protocol Skill
 
 ## Purpose
+
 To replace "Shotgun Debugging" (randomly changing code) with a deterministic, scientific process.
 **Goal:** Fix the *root cause*, not just the symptom.
 
 ## When to Use
+
 - **Trigger**: When a test fails, an exception is thrown, or output is unexpected.
 - **Agent**: Primarily used by `execution` mode.
 - **Support**:
-    - Call `quality` to write the reproduction test.
-    - Call `researcher` if the error message is obscure/undocumented.
+  - Call `quality` to write the reproduction test.
+  - Call `researcher` if the error message is obscure/undocumented.
 
 ## The Scientific Method (4-Step Protocol)
 
 ### Phase 1: Observation (The MRE)
+
 **Rule**: *If you cannot reproduce it, you cannot fix it.*
-1.  **Isolate**: Create a standalone script or test case that fails 100% of the time.
-2.  **Minimize**: Remove all code not strictly necessary to produce the error.
-3.  **Log**: Do not guess variables. Log them.
+
+1. **Isolate**: Create a standalone script or test case that fails 100% of the time.
+2. **Minimize**: Remove all code not strictly necessary to produce the error.
+3. **Log**: Do not guess variables. Log them.
 
 ### Phase 2: Localization (The "Wolf Fence")
+
 **Rule**: *Divide and Conquer.*
-1.  **Binary Search**: Is the data wrong at the Database? No? At the API? No? At the UI?
-2.  **Trace**: Follow the data flow. Find the *exact line* where the reality diverges from expectation.
+
+1. **Binary Search**: Is the data wrong at the Database? No? At the API? No? At the UI?
+2. **Trace**: Follow the data flow. Find the *exact line* where the reality diverges from expectation.
 
 ### Phase 3: Hypothesis (The "5 Whys")
+
 **Rule**: *Do not fix the symptom.*
-1.  **Identify**: "Variable X is null."
-2.  **Ask Why**: "Why is X null?" -> "Because the API returned 404."
-3.  **Ask Why**: "Why 404?" -> "Because the ID was undefined."
-4.  **Ask Why**: "Why undefined?" -> "Because of a typo in the frontend."
-5.  **Root Cause**: Typo in the frontend payload.
+
+1. **Identify**: "Variable X is null."
+2. **Ask Why**: "Why is X null?" -> "Because the API returned 404."
+3. **Ask Why**: "Why 404?" -> "Because the ID was undefined."
+4. **Ask Why**: "Why undefined?" -> "Because of a typo in the frontend."
+5. **Root Cause**: Typo in the frontend payload.
 
 ### Phase 4: Resolution & Verification
+
 **Rule**: *Prove it.*
-1.  **Apply Fix**: Correct the root cause.
-2.  **Verify**: Run the MRE from Phase 1. It must pass.
-3.  **Regression**: Run the full test suite. Ensure nothing else broke.
+
+1. **Apply Fix**: Correct the root cause.
+2. **Verify**: Run the MRE from Phase 1. It must pass.
+3. **Regression**: Run the full test suite. Ensure nothing else broke.
 
 ## Debugging Scratchpad Template
 
@@ -79,5 +89,5 @@ To replace "Shotgun Debugging" (randomly changing code) with a deterministic, sc
 
 ## Integration with Agents
 
--   **`quality` agent**: If you are stuck on **Phase 1 (Reproduction)**, delegate to `quality`. *"I see the error, but I can't write a test for it. Quality Agent, please create a Cypress test for this UI bug."*
--   **`researcher` agent**: If you are stuck on **Phase 3 (Hypothesis)**. *"I have the error 'Heap Out of Memory'. Researcher, what are the common causes for this in Node.js 18?"*
+- **`quality` agent**: If you are stuck on **Phase 1 (Reproduction)**, delegate to `quality`. *"I see the error, but I can't write a test for it. Quality Agent, please create a Cypress test for this UI bug."*
+- **`researcher` agent**: If you are stuck on **Phase 3 (Hypothesis)**. *"I have the error 'Heap Out of Memory'. Researcher, what are the common causes for this in Node.js 18?"*