super-opencode 1.1.0

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

@@ -0,0 +1,107 @@
+---
+description: "Systematically clean up code, remove dead code, and optimize project structure"
+---
+
+# /soc-cleanup
+
+## 1. Command Overview
+The `/soc-cleanup` command is the "Janitor" of the codebase. It safely identifies and removes technical debt, unused exports, and dead code. It operates in two modes: `Safe` (conservative) and `Aggressive` (deep cleaning). Its primary directive is "Do No Harm."
+
+## 2. Triggers & Routing
+The command routes cleanup tasks based on the `--type` flag.
+
+| Trigger Scenario | Flag | Target Agent | Tool Used |
+| :--- | :--- | :--- | :--- |
+| **Dead Code** | `--type code` | `[quality]` | TSPrune, Knip |
+| **Unused Imports** | `--type imports` | `[quality]` | ESLint/Birome |
+| **File Structure** | `--type files` | `[architect]` | Filesystem Analysis |
+| **Deep Clean** | `--type all` | `[quality]` | All tools |
+
+## 3. Usage & Arguments
+```bash
+/soc-cleanup [target] [flags]
+```
+
+### Arguments
+-   **`[target]`**: Directory or file to clean (default: current context).
+
+### Flags
+-   **`--type [code|imports|files|all]`**: **MANDATORY**.
+-   **`--safe`**: (Default) Only removes code with 0 references.
+-   **`--aggressive`**: Removes code with indirect/suspect references (requires confirmation).
+-   **`--preview`**: Lists changes without applying them (Dry Run).
+
+## 4. Behavioral Flow (Orchestration)
+
+### Phase 1: Analysis (The Scanner)
+1.  **Map**: Scans `[target]` for exports and imports.
+2.  **Trace**: Builds a dependency graph.
+3.  **Flag**: Identifies "orphan" nodes (code with no incoming edges).
+
+### Phase 2: Plan (The Stratagem)
+-   If `safe`: Select only orphans with 0 references.
+-   If `aggressive`: Select orphans + "soft" references (comments, test-only usage).
+
+### Phase 3: Execution (The Broom)
+1.  **Backup**: (Implicit) Relies on Git.
+2.  **Remove**: Deletes lines/files.
+3.  **Verify**: Runs build/tests. If fail -> Revert.
+
+## 5. Output Guidelines (The Contract)
+
+### Cleanup Report
+```markdown
+## Cleanup Report: [Target]
+
+### Summary
+-   **Removed**: 15 unused exports
+-   **Deleted**: 2 dead files
+-   **Bytes Saved**: 4.5KB
+
+### Actions Taken
+-   [x] Removed `oldFunction` from `src/utils.ts` (0 refs).
+-   [x] Deleted `src/components/unused-modal.tsx`.
+
+### Skipped (Safety Check)
+-   [ ] `legacyAuth.ts` (Referenced in TODO comment).
+```
+
+## 6. Examples
+
+### A. Safe Import Cleanup
+```bash
+/soc-cleanup src/ --type imports --safe
+```
+*Effect:* Removes unused `import` statements and sorts remaining ones.
+
+### B. Dead Code Preview
+```bash
+/soc-cleanup --type code --preview
+```
+*Effect:* Lists all exported functions that are never imported, but does not delete them.
+
+## 7. Dependencies & Capabilities
+
+### Agents
+-   **Quality**: `@[.opencode/agents/quality.md]` - Primary agent for code analysis.
+-   **Architect**: `@[.opencode/agents/architect.md]` - For structural cleanup.
+
+### Skills
+-   **Safety Check**: `@[.opencode/skills/security-audit/SKILL.md]` - ensuring cleanup doesn't remove security gates.
+-   **Reflexion**: `@[.opencode/skills/reflexion/SKILL.md]` - Recovering if cleanup breaks the build.
+
+### MCP Integration
+-   **`context7`**: Verifying if "unused" code is actually a framework entry point (e.g., Next.js pages).
+-   **`filesystem`**: Moving and deleting files.
+
+## 8. Boundaries
+
+**Will:**
+-   Remove unused imports.
+-   Delete files with 0 references (in `aggressive` mode).
+-   Consolidate duplicate logic (if explicitly identified).
+
+**Will Not:**
+-   **Delete "Commented Out" Code**: Unless explicitly told to.
+-   **Touch Config Files**: (e.g., `tsconfig.json`) without explicit intent.
+-   **Break Public APIs**: Will not remove exports from `index.ts` files in libraries.

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

@@ -0,0 +1,122 @@
+---
+name: design
+description: "Design system architecture, APIs, and component interfaces with comprehensive specifications"
+---
+
+# /soc-design
+
+## 1. Command Overview
+The `/soc-design` command orchestrates the creation of technical specifications, architecture diagrams, and API contracts. It transitions a project from "brainstorming" to "blueprint." It delegates specific design tasks to the `architect`, `backend`, or `frontend` agents, ensuring all designs are validated against the "Ultrathink" protocol before any code is written.
+
+## 2. Triggers & Routing
+The command routes to specialized sub-agents based on the `--type` flag.
+
+| Trigger Scenario | Flag | Target Agent | Context Injected |
+| :--- | :--- | :--- | :--- |
+| **System Architecture** | `--type architecture` | `[architect]` | Scalability, Cloud Limits, ADR templates |
+| **API Contract** | `--type api` | `[backend]` | REST/GraphQL patterns, Auth headers |
+| **Database Schema** | `--type database` | `[backend]` | Normalization rules, Migration templates |
+| **UI Component** | `--type component` | `[frontend]` | Accessibility (WCAG), Design Tokens |
+
+## 3. Usage & Arguments
+```bash
+/soc-design [target] [flags]
+```
+
+### Arguments
+-   **`[target]`**: The feature, system, or component to design (e.g., "User Auth", "Payment Gateway").
+
+### Flags
+-   **`--type [type]`**: **MANDATORY**. One of `architecture`, `api`, `database`, `component`.
+-   **`--format [format]`**:
+    -   `spec`: Textual specification with requirements (default).
+    -   `diagram`: Mermaid or ASCII visualization.
+    -   `code`: Interface definitions (TypeScript interfaces, SQL DDL).
+
+## 4. Behavioral Flow (Orchestration)
+
+### Phase 1: Context Analysis
+1.  **Read**: Examines existing `task.md`, `README.md`, and any previous brainstorming artifacts.
+2.  **Constraint Check**: Identifies tech stack limitations (e.g., "We are using Next.js on Vercel").
+
+### Phase 2: Design Generation
+The command prompts the target agent:
+> "Agent **[Name]**, create a **[Type]** design for **[Target]**.
+> Standard: **Intentional Minimalism**.
+> Output: **[Format]**."
+
+### Phase 3: Validation (Reflexion)
+-   Does the design violate "Zero Trust"?
+-   Is the schema normalized?
+-   Are the UI components accessible?
+
+## 5. Output Guidelines (The Contract)
+
+### A. Architecture Decision Record (ADR)
+```markdown
+# ADR: [Title]
+## Context
+[Problem description]
+## Decision
+[Solution chosen]
+## Consequences
+[Trade-offs]
+```
+
+### B. API Specification
+```typescript
+interface CreateUserRequest {
+  email: string; // @format email
+  role?: 'admin' | 'user';
+}
+```
+
+### C. Database Schema (Prisma/SQL)
+```prisma
+model User {
+  id    String @id @default(cuid())
+  email String @unique
+}
+```
+
+## 6. Examples
+
+### A. System Architecture
+```bash
+/soc-design user-management --type architecture --format diagram
+```
+*Effect:* Triggers `architect` to draw a high-level system diagram including Auth0, Postgres, and Next.js linkage.
+
+### B. API Design
+```bash
+/soc-design payment-api --type api --format spec
+```
+*Effect:* Triggers `backend` to define `POST /api/payments` with request/response schemas and error codes.
+
+## 7. Dependencies & Capabilities
+### Agents
+-   **Architecture**: `@[.opencode/agents/architect.md]` - System design and patterns.
+-   **API/DB**: `@[.opencode/agents/backend.md]` - Schema and interface definitions.
+-   **UI/UX**: `@[.opencode/agents/frontend.md]` - Component and interaction design.
+-   **Research**: `@[.opencode/agents/researcher.md]` - Competitive analysis and best practices.
+
+### Skills
+-   **Simplification**: `@[.opencode/skills/simplification/SKILL.md]` - Ensuring designs are not over-engineered.
+-   **Reflexion**: `@[.opencode/skills/reflexion/SKILL.md]` - Critiquing design decisions.
+
+### MCP Integration
+-   **`generate_image`**: Used to create UI mockups, architectural diagrams, and visual flows.
+-   **`context7`**: Accessing latest documentation for chosen frameworks (e.g., "Next.js App Router patterns").
+-   **`tavily`**: Researching industry standards and existing solutions.
+
+## 8. Boundaries
+
+**Will:**
+-   Create comprehensive design specifications.
+-   Generate interface definitions (contracts).
+-   Validate designs against architectural constraints.
+
+**Will Not:**
+-   **Write Implementation Code**: Use `/soc-implement` for that.
+-   **Deploy Infrastructure**: Use Terraform/SOC agents for that.
+-   **Guess Requirements**: If ambiguous, it will ask for clarification.

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

@@ -0,0 +1,113 @@
+---
+description: Code explanation and understanding
+---
+
+# /soc-explain
+
+## 1. Command Overview
+The `/soc-explain` command is the "Tutor." It translates complex code, errors, or concepts into natural language. It adapts its depth to the user's needs, from simple analogies to expert technical deep-dives. It generates documentation that can be saved.
+
+## 2. Triggers & Routing
+The command uses the `writer` agent effectively to synthesize information.
+
+| Trigger Scenario | Flag | Target Agent | Style |
+| :--- | :--- | :--- | :--- |
+| **High Level** | `--depth simple` | `[writer]` | Analogies, non-technical |
+| **Standard** | `--depth detailed` | `[writer]` | Code logic, flow, syntax |
+| **Deep Dive** | `--depth expert` | `[architect]` | Memory, performance, edge cases |
+
+## 3. Usage & Arguments
+```bash
+/soc-explain [target] [flags]
+```
+
+### Arguments
+-   **`[target]`**: Code snippet, file path, error message, or concept (e.g., "Dependency Injection").
+
+### Flags
+-   **`--depth [simple|detailed|expert]`**: (Default: `detailed`).
+-   **`--context [file]`**: Add extra context for better explanation.
+
+## 4. Behavioral Flow (Orchestration)
+
+### Phase 1: Analysis
+1.  **Parse**: Is the target a file, a string, or a concept?
+2.  **Context**: If it's an error, where did it come from? If it's code, what language?
+
+### Phase 2: Synthesis (The Lesson)
+-   **Analogy**: "Think of a Promise like a pizza buzzer..."
+-   **Technical**: "It wraps the value in a microtask queue..."
+-   **Example**: "Here is how you use it:"
+
+### Phase 3: Formatting
+-   Structure with clear Headers.
+-   Use Code Blocks for syntax.
+-   Highlight "Key Takeaways."
+
+## 5. Output Guidelines (The Contract)
+
+### Explanation Document
+```markdown
+## Explanation: [Topic]
+
+### Summary
+[1-2 sentences. The TL;DR.]
+
+### Conceptual Analogy (If Simple)
+[Mundane comparison]
+
+### Technical Breakdown
+-   **Component A**: Does X.
+-   **Component B**: Does Y.
+
+### Code Example
+```javascript
+// Before
+badCode()
+
+// After (corrected/explained)
+goodCode()
+```
+
+### Key Takeaways
+1.  [Point 1]
+2.  [Point 2]
+```
+
+## 6. Examples
+
+### A. Async/Await (Expert)
+```bash
+/soc-explain "How Node Event Loop works" --depth expert
+```
+*Effect:* Explains Phases (Timers, Poll, Check), Microtasks vs Macrotasks, and `process.nextTick`.
+
+### B. Error Parsing
+```bash
+/soc-explain "TypeError: Cannot read property 'map' of undefined"
+```
+*Effect:* Explains that the array is missing, helps identify the source variable, suggests Optional Chaining (`?.`).
+
+## 7. Dependencies & Capabilities
+
+### Agents
+-   **Writer**: `@[.opencode/agents/writer.md]` - Primary explainer.
+-   **Architect**: `@[.opencode/agents/architect.md]` - For system-level concepts.
+
+### Skills
+-   **Simplification**: `@[.opencode/skills/simplification/SKILL.md]` - To de-jargonize complex topics.
+
+### MCP Integration
+-   **`context7`**: Fetching official docs to cite sources.
+-   **`read_file`**: Reading the full content of the file being explained.
+
+## 8. Boundaries
+
+**Will:**
+-   Explain *why* code works.
+-   Suggest *best practices*.
+-   Debug *logic* errors via explanation.
+
+**Will Not:**
+-   **Write the Fix**: It explains the fix; `/soc-implement` writes it.
+-   **Execute Code**: It analyzes static text.

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

@@ -0,0 +1,104 @@
+---
+description: "Git operations with intelligent commit messages and workflow optimization"
+---
+
+# /soc-git
+
+## 1. Command Overview
+The `/soc-git` command is the "Version Controller." It wraps standard git operations with intelligence. It can analyze diffs to generate Conventional Commit messages, check for accidental secrets before pushing, and manage branching strategies.
+
+## 2. Triggers & Routing
+The command routes to the `writer` agent for message generation and `security` for pre-push checks.
+
+| Trigger Scenario | Flag | Target Agent | Action |
+| :--- | :--- | :--- | :--- |
+| **Commit Message** | `--smart` | `[writer]` | Generate `feat(scope): desc` |
+| **Pre-Push** | `push` | `[security]` | Scan for secrets |
+| **Branching** | `branch` | `[pm-agent]` | Enforce naming conventions |
+
+## 3. Usage & Arguments
+```bash
+/soc-git [operation] [args] [flags]
+```
+
+### Arguments
+-   **`[operation]`**: `commit`, `push`, `pull`, `branch`, `status`, `diff`.
+
+### Flags
+-   **`--smart`**: Auto-generate messages/descriptions.
+-   **`--force`**: Bypass safety checks (Use with caution).
+
+## 4. Behavioral Flow (Orchestration)
+
+### Phase 1: Context Analysis
+1.  **Status Check**: Run `git status`.
+2.  **Diff Analysis**: Run `git diff --staged`.
+3.  **Safety Check**: Scan pending changes for keys/env files.
+
+### Phase 2: Operations
+-   **Commit**:
+    -   If `--smart`: Feed diff to LLM -> Generate Conventional Commit.
+    -   If standard: Execute `git commit -m`.
+-   **Push**:
+    -   Check upstream. If missing, auto-set `-u origin`.
+-   **Branch**:
+    -   Normalize name (e.g., `My Feature` -> `feat/my-feature`).
+
+### Phase 3: Post-Op
+-   Confirm success.
+-   Show Next Step (e.g., "Ready to open PR").
+
+## 5. Output Guidelines (The Contract)
+
+### Git Operation Result
+```markdown
+## Git: [Operation]
+
+### Status
+✅ Success / ❌ Failure
+
+### Details
+-   **Branch**: `feat/user-auth`
+-   **Commit**: `a1b2c3d` - "feat(auth): add login route"
+
+### Tips
+-   [ ] Run `/test` before pushing.
+```
+
+## 6. Examples
+
+### A. Smart Commit
+```bash
+/soc-git commit --smart
+```
+*Effect:* Analyzes staged files, detects added login logic, commits with: `feat(auth): implement user login flow`.
+
+### B. Branch Creation
+```bash
+/soc-git branch "Update README"
+```
+*Effect:* Creates and checks out `docs/update-readme` (auto-categorized).
+
+## 7. Dependencies & Capabilities
+
+### Agents
+-   **Writer**: `@[.opencode/agents/writer.md]` - For commit messages.
+-   **Security**: `@[.opencode/agents/security.md]` - For pre-commit hooks.
+
+### Skills
+-   **Security Audit**: `@[.opencode/skills/security-audit/SKILL.md]` - Scanning staged files.
+
+### MCP Integration
+-   **`run_command`**: Executing actual git binaries.
+-   **`filesystem`**: Reading ignores and config.
+
+## 8. Boundaries
+
+**Will:**
+-   Execute git commands.
+-   Generate text for messages.
+-   Block commits with secrets (unless `--force`).
+
+**Will Not:**
+-   **Solve Merge Conflicts**: It will report them, but user must resolve.
+-   **Rewrite History**: No `rebase` or `reset --hard` without explicit user confirmation.

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

@@ -0,0 +1,94 @@
+---
+description: Help and command reference
+---
+
+# /soc-help
+
+## 1. Command Overview
+The `/soc-help` command is the "Librarian." It serves as the primary documentation interface for the agent system. It explains *how* to use the other commands, details what each agent does, and lists available skills. It uses the `researcher` agent to find answers within the system's own documentation.
+
+## 2. Triggers & Routing
+The command is self-contained but may use `researcher` for deep queries.
+
+| Trigger Scenario | Flag | Target Agent | Action |
+| :--- | :--- | :--- | :--- |
+| **Command Syntax** | `[command]` | `[System]` | Show usage and flags |
+| **Agent Roles** | `[agent]` | `[System]` | Show persona description |
+| **Workflow Guide** | `[topic]` | `[researcher]` | Summarize best practices |
+
+## 3. Usage & Arguments
+```bash
+/soc-help [target] [flags]
+```
+
+### Arguments
+-   **`[target]`**: (Optional) Specific command (`implement`), agent (`backend`), or topic (`workflows`). Default: Shows index.
+
+### Flags
+-   **`--verbose`**: Show detailed descriptions and hidden flags.
+
+## 4. Behavioral Flow (Orchestration)
+
+### Phase 1: Lookup
+1.  **Index**: Check if target is a known Command, Agent, or Skill.
+2.  **Search**: If unknown, grep `.opencode/` documentation for keywords.
+
+### Phase 2: Formatting
+-   **Structure**: Group by Category (Workflow vs Skill).
+-   **Clarity**: Show "Quick Start" snippets.
+
+## 5. Output Guidelines (The Contract)
+
+### Help Document
+```markdown
+## Help: [Target]
+
+### Description
+[Brief summary]
+
+### Usage
+`[Command Pattern]`
+
+### Key Features
+-   Feature 1
+-   Feature 2
+
+### Related Commands
+-   `/related-command`
+```
+
+## 6. Examples
+
+### A. Command Help
+```bash
+/soc-help implement
+```
+*Effect:* Displays usage for `/soc-implement`, including flags like `--agent` and `--test`.
+
+### B. Agent Role
+```bash
+/soc-help backend
+```
+*Effect:* Shows the `backend` agent's persona, including "Prime Directives" and "Restrictions."
+
+## 7. Dependencies & Capabilities
+
+### Agents
+-   **Researcher**: `@[.opencode/agents/researcher.md]` - For finding unstructured help.
+
+### Skills
+-   **None**: This is a read-only command.
+
+### MCP Integration
+-   **`filesystem`**: Reading documentation files.
+
+## 8. Boundaries
+
+**Will:**
+-   Explain system capabilities.
+-   List available tools.
+-   Provide syntax examples.
+
+**Will Not:**
+-   **Execute Commands**: It only explains them.
+-   **Hallucinate Features**: Only lists what exists in `.opencode/`.

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

@@ -0,0 +1,112 @@
+---
+description: Code implementation with best practices
+---
+
+# /soc-implement
+
+## 1. Command Overview
+The `/soc-implement` command is the execution engine of the agent system. It transforms approved designs and specifications into production-ready code. It enforces strict quality control, testing (TDD), and "self-correction" loops via the `reflexion` skill. It does not plan; it executes.
+
+## 2. Triggers & Routing
+The command routes to specialized sub-agents based on the `--agent` flag or file context.
+
+| Trigger Scenario | Flag | Target Agent | Context Injected |
+| :--- | :--- | :--- | :--- |
+| **API/Database Logic** | `--agent backend` | `[backend]` | DB Schemas, Error Handling Middleware |
+| **UI/Components** | `--agent frontend` | `[frontend]` | Design System, A11y Rules, Hooks |
+| **Testing/QA** | `--agent quality` | `[quality]` | Test Runner Config, Coverage Reports |
+| **Refactoring** | `--agent fullstack` | `[backend]` + `[frontend]` | Cross-layer dependencies |
+
+## 3. Usage & Arguments
+```bash
+/soc-implement [target] [flags]
+```
+
+### Arguments
+-   **`[target]`**: The feature or file to implement (e.g., "Login Flow", "src/components/Button.tsx").
+
+### Flags
+-   **`--agent [backend|frontend|quality]`**: **MANDATORY**. Specifies the executing persona.
+-   **`--test`**: (Default: true) Run capabilities tests after implementation.
+-   **`--document`**: (Default: true) Update associated documentation/comments.
+
+## 4. Behavioral Flow (Orchestration)
+
+### Phase 1: Pre-Flight (Confidence Check)
+1.  **Read**: Review existing code and referencing `design.md` or `requirements`.
+2.  **Verify**: Check for patterns (e.g., "How do existing controllers handle errors?").
+3.  **Gate**: If confidence < 80%, ask user/PM for clarification.
+
+### Phase 2: Execution (The Loop)
+1.  **Test**: Write the test case first (TDD) if applicable.
+2.  **Edit**: Apply changes using `replace_file_content` or `write_to_file`.
+3.  **Verify**: Run the project's build/test command.
+    *   *If Fail*: Trigger `reflexion` skill (Why did it fail? -> Fix -> Retry).
+    *   *Limit*: Max 3 retries before asking for help.
+
+### Phase 3: Post-Flight (Self Check)
+-   Did I leave any `console.log`?
+-   Are inputs sanitized?
+-   Did I break the build?
+
+## 5. Output Guidelines (The Contract)
+
+### Standard Implementation Report
+```markdown
+## Implementation: [Feature Name]
+
+### 1. Changes Summary
+-   **Created:** `src/features/auth/login.ts`
+-   **Modified:** `src/components/navbar.tsx`
+
+### 2. Verification
+-   ✅ **Build:** Passed
+-   ✅ **Tests:** 3 new tests added, all passing.
+-   ✅ **Lint:** 0 errors.
+
+### 3. Key Decisions
+-   Used `zod` for validation to match existing patterns.
+-   Extracted `useAuth` hook for reusability.
+```
+
+## 6. Examples
+
+### A. Backend Feature
+```bash
+/soc-implement "User Registration API" --agent backend
+```
+*Effect:* `backend` agent writes `POST /register`, adds `UserSchema` validation, inputs into Postgres, and returns a sanitized User DTO.
+
+### B. Frontend Component
+```bash
+/soc-implement "DarkMode Toggle" --agent frontend
+```
+*Effect:* `frontend` agent checks `tailwind.config.js`, creates a toggle component using `Radix UI` primitives (if installed) and handles local storage state.
+
+## 7. Dependencies & Capabilities
+
+### Agents
+-   **Backend**: `@[.opencode/agents/backend.md]`
+-   **Frontend**: `@[.opencode/agents/frontend.md]`
+-   **Quality**: `@[.opencode/agents/quality.md]` - For TDD and verification.
+
+### Skills
+-   **Confidence Check**: `@[.opencode/skills/confidence-check/SKILL.md]` - MANDATORY step before starting.
+-   **Self Check**: `@[.opencode/skills/self-check/SKILL.md]` - Validation protocol after changes.
+-   **Debug Protocol**: `@[.opencode/skills/debug-protocol/SKILL.md]` - If implementation hits errors.
+
+### MCP Integration
+-   **`context7`**: For looking up exact syntax and library API usage to prevent hallucinations.
+-   **`filesystem`**: For determining current project structure and patterns.
+
+## 8. Boundaries
+
+**Will:**
+-   Write code modules, tests, and documentation.
+-   Fix compilation errors it causes.
+-   Respect existing linters and formatters.
+
+**Will Not:**
+-   **Invent Designs**: If no design exists, it will fall back to simple best practices or ask for a design.
+-   **Commit Violations**: Will not commit code with secrets or critical bugs.
+-   **Touch Forbidden Files**: (e.g., `package-lock.json` manual edits, `.env` manual edits).