@mohammadhprp/system-prompt 0.10.1

package/framework/mcps/supabase-mcp/install.md

@@ -0,0 +1,85 @@
+# Supabase MCP Installation
+
+## Requirements
+
+- A Supabase account with a project.
+- An MCP-compatible AI client that supports remote HTTP MCP servers (Streamable HTTP).
+- No local infrastructure — the server is hosted by Supabase at `https://mcp.supabase.com/mcp`.
+
+## Configuration
+
+Supabase MCP is a remote Streamable HTTP server — no local command or install needed. Authentication uses OAuth, completed interactively on first use.
+
+| Field | Value |
+| --- | --- |
+| Server name | `supabase` |
+| Transport type | Streamable HTTP |
+| URL | `https://mcp.supabase.com/mcp` |
+
+### Config file examples
+
+Use the examples in [`configs/`](./configs/) as client-specific starting points:
+
+| Client | Example | Typical location |
+| --- | --- | --- |
+| OpenCode | [`configs/opencode.json`](./configs/opencode.json) | OpenCode MCP configuration. |
+
+### OpenCode
+
+Copy [`configs/opencode.json`](./configs/opencode.json) into your OpenCode project root or user config directory. Then authenticate:
+
+```bash
+opencode mcp auth supabase
+```
+
+This opens your browser to complete the OAuth flow.
+
+### For clients that only support local stdio servers
+
+Some MCP clients only support local stdio servers. Use the [mcp-remote](https://www.npmjs.com/package/mcp-remote) bridge to connect:
+
+```json
+{
+  "mcpServers": {
+    "supabase": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.supabase.com/mcp"]
+    }
+  }
+}
+```
+
+## Configuration options
+
+Append URL query parameters to restrict server scope:
+
+| Parameter | Description | Example |
+| --- | --- | --- |
+| `read_only=true` | Execute all queries as a read-only Postgres user | `?read_only=true` |
+| `project_ref=<id>` | Scope to a specific project (disables account tools) | `?project_ref=abc123` |
+| `features=<groups>` | Enable only specific tool groups (comma-separated) | `?features=database,docs` |
+
+Parameters can be combined: `https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true`
+
+## Verification
+
+After configuring and authenticating, ask your AI agent:
+
+```
+List all tables in the database using MCP tools.
+```
+
+## Updating
+
+Supabase MCP is hosted by Supabase — no update steps needed. The latest version is always available at `https://mcp.supabase.com/mcp`.
+
+## Uninstalling
+
+Remove the `supabase` MCP entry from AI client configuration files. Optionally, revoke the OAuth connection in your Supabase organization settings.
+
+## Common Issues
+
+- **Authentication fails**: make sure you complete the OAuth flow when prompted. Run the auth command again to trigger a fresh flow.
+- **Client does not support remote servers**: use the `mcp-remote` bridge as a stdio wrapper.
+- **Permission errors**: check that your Supabase user has the correct permissions for the project or organization.
+- **Tool not found**: verify which feature groups are enabled — some tools are disabled by default (Storage, Branching).

package/framework/mcps/supabase-mcp/troubleshooting.md

@@ -0,0 +1,113 @@
+# Supabase MCP Troubleshooting
+
+## Connection fails
+
+**Problem**
+
+The AI client reports that `supabase` cannot connect.
+
+**Cause**
+
+The client does not support remote HTTP MCP servers, or the URL is misconfigured.
+
+**Solution**
+
+- Verify the URL is `https://mcp.supabase.com/mcp`.
+- If your client only supports local stdio servers, use the `mcp-remote` bridge: `npx -y mcp-remote https://mcp.supabase.com/mcp`.
+- Check the client's documentation for how to add a remote MCP server.
+
+## Authentication fails
+
+**Problem**
+
+The connection succeeds but tools return authentication errors.
+
+**Cause**
+
+The OAuth flow was not completed or the token has expired.
+
+**Solution**
+
+- Run the auth command again: `opencode mcp auth supabase`.
+- Make sure you select the correct Supabase organization during OAuth.
+- Try disconnecting and reconnecting. Look for a "Clear authentication" or "Disconnect" option in the client's MCP settings.
+
+## Permission errors
+
+**Problem**
+
+Tools return 403 or project not found errors.
+
+**Cause**
+
+The authenticated user does not have access to the requested project or organization, or the project ref is incorrect.
+
+**Solution**
+
+- Verify your Supabase user has the correct permissions for the project.
+- Check that the `project_ref` parameter matches an actual project ID.
+- Use account-level tools (no `project_ref`) to list available projects and organizations first.
+
+## Read-only mode blocks writes
+
+**Problem**
+
+INSERT, UPDATE, DELETE queries fail silently or return errors.
+
+**Cause**
+
+The server is configured with `read_only=true`, which executes all queries as a read-only Postgres user.
+
+**Solution**
+
+- Remove `read_only=true` from the URL if you need write access.
+- Use branching to make changes in an isolated environment.
+
+## Tool not available
+
+**Problem**
+
+A specific tool is missing when the AI agent lists available tools.
+
+**Cause**
+
+The tool belongs to a feature group that is not enabled.
+
+**Solution**
+
+- Verify which feature groups are enabled via the `features` URL parameter.
+- Storage tools are disabled by default — add `features=storage` or include `storage` in the comma-separated list.
+- Branching tools are disabled by default and require a paid plan.
+- Account tools are disabled when `project_ref` is set.
+
+## Rate limited
+
+**Problem**
+
+Tools return rate limit errors.
+
+**Cause**
+
+Supabase API rate limits have been exceeded.
+
+**Solution**
+
+- Reduce the number of parallel tool calls.
+- Space out requests between agent steps.
+- Wait before retrying.
+
+## CI/CD authentication
+
+**Problem**
+
+Cannot complete the OAuth flow in a CI environment.
+
+**Cause**
+
+Browser-based OAuth is not available in CI.
+
+**Solution**
+
+- Create a personal access token (PAT) in your Supabase dashboard.
+- Pass it as an `Authorization: Bearer <token>` header in the MCP server configuration.
+- Always scope the server to a project and use read-only mode in CI.

package/framework/memory/README.md

@@ -0,0 +1,17 @@
+# Memory
+
+Persistent agent memory files that maintain context across sessions.
+
+Memory files are installed to `.opencode/memory/` and auto-included in the
+agent's `instructions` via the glob pattern `.opencode/memory/*.md`.
+
+## Files
+
+- `codebase-insights.md` — Non-obvious facts, gotchas, past decisions, and architecture quirks.
+- `user-preferences.md` — Coding style, naming conventions, and architectural preferences.
+
+## Behavior
+
+Memory files are **only written on first install**. Re-running the installer
+will not overwrite them — preserving any edits made by the user or agent
+across sessions.

package/framework/memory/codebase-insights.md

@@ -0,0 +1,6 @@
+# Codebase Insights
+
+_This file is maintained by the agent across sessions. It captures
+non-obvious facts, gotchas, past decisions, and architecture quirks that
+would be hard to rediscover from reading the code alone._
+

package/framework/memory/user-preferences.md

@@ -0,0 +1,5 @@
+# User Preferences
+
+_This file is maintained by the agent across sessions. It captures the user's
+coding style, naming conventions, architectural preferences, and other
+recurring patterns._

package/framework/modes/README.md

@@ -0,0 +1,52 @@
+# Mode Catalog
+
+A catalog of behavior, tool, and prompt presets for AI coding agents.
+
+Modes customize how the agent behaves for a given use case. Each mode defines a temperature, restricts or grants tools, and sets the response style, workflow, and output format. Switch modes to adopt a different operating posture — for example, a read-only high-scrutiny review mode versus a default building mode.
+
+## Available Modes
+
+| Mode | Purpose | Tools |
+| --- | --- | --- |
+| [Audit](./audit.md) | Read-only high-scrutiny review of artifacts — correctness, architecture, security, maintainability. | `write`, `edit`, `bash` disabled |
+
+## Mode Entry Structure
+
+```text
+modes/<mode-name>.md
+```
+
+Each mode file uses YAML frontmatter defining runtime constraints, followed by markdown instructions defining the mode's behavior, response style, workflow, and output format.
+
+```yaml
+---
+temperature: 0.1
+tools:
+  write: false
+  edit: false
+  bash: false
+---
+```
+
+| Field | Purpose |
+| --- | --- |
+| `temperature` | Sampling temperature for the mode (lower = more deterministic). |
+| `tools` | Per-tool allow/deny flags that override the base agent's tool access. |
+
+## How to Contribute a New Mode
+
+1. Create `modes/<mode-name>.md` following the existing format.
+2. Set `temperature` appropriate to the mode's posture.
+3. Declare `tools` restrictions (typically deny `write`/`edit`/`bash` for review modes).
+4. Write markdown instructions: purpose, response style, workflow, output format, and constraints.
+5. Add the mode to the table in this README.
+
+## Related Repository Areas
+
+- [`skills/`](../skills/) contains task-specific skill definitions.
+- [`agents/`](../agents/) contains specialized subagent definitions.
+- [`commands/`](../commands/) contains slash commands for repeatable workflows.
+- [`mcps/`](../mcps/) contains the MCP server catalog.
+- [`plugins/`](../plugins/) contains the OpenCode plugin catalog.
+- [`references/standards/`](../references/standards/) contains canonical engineering rules.
+- [`references/templates/`](../references/templates/) contains reusable engineering deliverables.

package/framework/modes/audit.md

@@ -0,0 +1,88 @@
+---
+temperature: 0.1
+tools:
+  write: false
+  edit: false
+  bash: false
+---
+
+# Purpose
+
+Evaluate artifacts for correctness, completeness, architectural quality, security, maintainability, and hidden failure modes.
+
+# Response Style
+  - Use direct, declarative language.
+  - Maximize information density.
+  - Eliminate filler, encouragement, praise, apologies, and conversational padding.
+  - Eliminate emojis.
+  - Eliminate motivational language.
+  - Do not mirror user tone.
+  - Prefer bullets over prose.
+  - Prefer concrete observations over general advice.
+  - End immediately after the requested output.
+
+# Default Review Framework
+
+Evaluate in this order:
+  1. Correctness
+  2. Missing requirements
+  3. Incorrect assumptions
+  4. Architecture
+  5. Scalability
+  6. Reliability
+  7. Security
+  8. Performance
+  9. Maintainability
+  10. Simplicity
+
+# Review Rules
+  - Identify incorrect reasoning before suggesting improvements.
+  - Explicitly distinguish facts from assumptions.
+  - Identify edge cases.
+  - Highlight hidden complexity.
+  - Highlight trade-offs.
+  - Recommend the simplest solution that satisfies the requirements.
+  - Reject unnecessary abstraction.
+  - Prefer production-ready patterns over theoretical ones.
+
+# Output Format
+
+## Findings
+
+Severity:
+  - Critical
+  - High
+  - Medium
+  - Low
+
+For each finding:
+  - Problem
+  - Impact
+  - Recommendation
+
+## Missing Items
+
+List omitted requirements or scenarios.
+
+## Risks
+
+List implementation or operational risks.
+
+## Final Assessment
+
+One sentence summarizing overall quality.
+
+# Constraints
+
+Never:
+
+- Ask questions unless required to complete the task.
+- Suggest unrelated improvements.
+- Add motivational statements.
+- Add conversational transitions.
+- Restate the user's request.
+- Explain obvious concepts.
+
+# Persistence
+
+Remain active until another mode replaces this one.

package/framework/plugins/README.md

@@ -0,0 +1,65 @@
+# Plugin Catalog
+
+A curated catalog of OpenCode plugins for AI coding agents.
+
+This catalog is framework-agnostic: each entry documents what the plugin does, when to use it, how to install it, how to configure it, and how to troubleshoot it.
+
+## Available Plugins
+
+| Plugin | Purpose | Best fit |
+| --- | --- | --- |
+| [OpenCode Goal Plugin](./opencode-goal-plugin/README.md) | Adds Codex-style long-running goal mode with `/goal` slash commands, persistent goal state, completion evidence, and auto-continuation. | Any OpenCode session that needs focused, goal-driven long-running tasks. |
+| [Ponytail](./ponytail/README.md) | Lazy senior dev mode — YAGNI-first, reuse-first ladder that cuts code bloat, token usage, and cost without cutting safety. | Any coding session where agents tend to over-engineer or add unnecessary abstractions. |
+
+## Why Plugins Are Useful
+
+OpenCode plugins extend the core agent with custom commands, tools, TUI elements, and lifecycle hooks. For coding agents, plugins can improve:
+
+- **Focus**: goal-driven workflows keep the agent on task across many turns.
+- **Persistence**: state survives session compaction and restarts.
+- **User experience**: custom TUI indicators and slash commands make agent behavior visible.
+- **Safety**: explicit completion evidence and blocker requirements prevent premature closure.
+
+## How to Choose a Plugin
+
+Use a plugin when it adds a concrete workflow or user interface that the base OpenCode agent does not provide.
+
+Before installing one, check:
+
+- **Compatibility**: does it match your OpenCode version? Check the `engines.opencode` field.
+- **Capabilities**: does it add commands, tools, or UI that improve your workflow?
+- **Permissions**: does it read or write files outside the project directory?
+- **Maintenance**: is the plugin actively maintained and documented?
+
+## Catalog Entry Structure
+
+Every plugin entry must use this structure:
+
+```text
+plugins/<plugin-slug>/
+├── README.md
+├── install.md
+├── capabilities.md
+└── troubleshooting.md
+```
+
+## Naming Conventions
+
+- Use lowercase kebab-case directory names, for example `opencode-goal-plugin`.
+- Use the upstream plugin name in page titles, for example `# OpenCode Goal Plugin`.
+- Keep file names exactly as shown in the catalog structure.
+
+## How to Contribute a New Plugin
+
+1. Create `plugins/<plugin-slug>/` using the standard structure.
+2. Prefer official documentation for install commands, requirements, capabilities, and configuration.
+3. Document options and their defaults in `capabilities.md`.
+4. Add common startup, permission, and version issues in `troubleshooting.md`.
+5. Add the plugin to the table in this README.
+
+## Related Repository Areas
+
+- [`mcps/`](../mcps/) contains the MCP (Model Context Protocol) server catalog.
+- [`skills/`](../skills/) contains task-specific procedures for AI coding agents.
+- [`references/standards/`](../references/standards/) contains canonical engineering rules.
+- [`references/templates/`](../references/templates/) contains reusable engineering deliverables.

package/framework/plugins/opencode-goal-plugin/README.md

@@ -0,0 +1,45 @@
+# OpenCode Goal Plugin
+
+## Overview
+
+OpenCode Goal Plugin adds Codex-style long-running goal mode to OpenCode. It gives AI coding agents a `/goal` slash command, persistent goal state, completion evidence, idle continuation, and a terminal UI goal indicator so an OpenCode session can keep working toward one explicit objective until it is complete, blocked, or cleared.
+
+Official source:
+
+- [GitHub: prevalentWare/opencode-goal-plugin](https://github.com/prevalentWare/opencode-goal-plugin)
+- [npm: @prevalentware/opencode-goal-plugin](https://www.npmjs.com/package/@prevalentware/opencode-goal-plugin)
+
+## Features
+
+- `/goal <objective>` as an OpenCode command for TUI, desktop, and web.
+- Sidebar goal indicator with status, elapsed time, and objective.
+- Agent tools: `get_goal`, `get_goal_history`, `create_goal`, `set_goal`, `update_goal_objective`, `update_goal`, and `clear_goal`.
+- Goal close evidence: `complete` requires verified evidence, `unmet` requires a concrete blocker.
+- Persistent per-session goal state with history, checkpoints, budgets, and owner-only file permissions.
+- Optional automatic continuation on idle, with no-progress pause and budget wrap-up safeguards.
+- Plan-mode safety: goals created from the `plan` agent stay paused; auto-continue never escapes Plan mode.
+- Compaction context so active goals are preserved when OpenCode summarizes a long session.
+
+## When to Use
+
+Use this plugin when you want OpenCode to behave more like a goal-driven coding agent instead of a one-prompt assistant.
+
+Good fits:
+
+- Long refactors, migrations, or test-fixing sessions.
+- Tracking one explicit objective across TUI, desktop, and web OpenCode surfaces.
+- Requiring completion evidence before a goal is marked done.
+- Preserving the current goal when OpenCode compacts a long conversation.
+
+Avoid using it for simple one-shot prompts that do not need goal tracking.
+
+## Requirements
+
+- OpenCode >= 1.17.1.
+
+## Related Skills
+
+Relevant skills in this repository:
+
+- [`backend-engineer`](../../skills/backend-engineer/SKILL.md): long-running feature work with goal tracking.
+- [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for refactoring, debugging, and testing.

package/framework/plugins/opencode-goal-plugin/capabilities.md

@@ -0,0 +1,127 @@
+# OpenCode Goal Plugin Capabilities
+
+## What It Can Do
+
+### Slash Commands
+
+| Command | Description |
+| --- | --- |
+| `/goal <objective>` | Create a new goal with the given objective |
+| `/goal` | Report the current goal state |
+| `/goal history` | Show lifecycle history and recent checkpoints |
+| `/goal edit <objective>` | Update the current objective |
+| `/goal pause` | Pause the goal without clearing it |
+| `/goal resume` | Resume a paused goal |
+| `/goal clear` | Clear the goal (aliases: `stop`, `off`, `reset`, `none`, `cancel`) |
+
+### Agent Tools
+
+| Tool | Description |
+| --- | --- |
+| `get_goal` | Get the current goal state |
+| `get_goal_history` | Get lifecycle history and checkpoints |
+| `create_goal` | Create a new goal with an objective |
+| `set_goal` | Set or replace the current goal |
+| `update_goal_objective` | Update the objective of the current goal |
+| `update_goal` | Update goal status, evidence, or blocker |
+| `clear_goal` | Clear the current goal |
+
+### TUI
+
+- Sidebar goal indicator showing status, elapsed time, token usage, auto-continue count, latest checkpoint, status message, stop reason, and objective.
+- Command-palette entry for viewing, refreshing, pausing, resuming, showing history, or clearing goal state.
+
+### Goal Lifecycle
+
+| Status | Description |
+| --- | --- |
+| `active` | Goal is set and being worked on |
+| `paused` | Goal is paused but not cleared |
+| `complete` | Goal is achieved with evidence |
+| `unmet` | Goal cannot be achieved, with a blocker specified |
+| `budgetLimited` | Token budget exhausted |
+| `usageLimited` | Auto-turn or elapsed-time budget exhausted |
+
+## Configuration Options
+
+Configure in `opencode.json`:
+
+```json
+{
+  "plugin": [
+    [
+      "@prevalentware/opencode-goal-plugin",
+      {
+        "auto_continue": true,
+        "defer_while_tasks_active": true,
+        "max_auto_turns": 25,
+        "min_continue_interval_seconds": 3,
+        "max_prompt_failures": 3,
+        "default_token_budget": 200000,
+        "max_goal_duration_seconds": 1800,
+        "no_progress_token_threshold": 50,
+        "max_no_progress_turns": 2,
+        "restricted_agents": ["plan"],
+        "allow_goal_execution_from_plan": false
+      }
+    ]
+  ]
+}
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `auto_continue` | `true` | Automatically continue goal on session idle |
+| `defer_while_tasks_active` | `true` | Wait for active Task child sessions before continuing |
+| `max_auto_turns` | `25` | Maximum auto-continuation turns per goal |
+| `min_continue_interval_seconds` | `3` | Minimum seconds between auto-continuation prompts |
+| `max_prompt_failures` | `3` | Max prompt failures before pausing |
+| `default_token_budget` | unset | Token budget inherited by new goals |
+| `max_goal_duration_seconds` | unset | Elapsed-time safety limit for goals |
+| `no_progress_token_threshold` | `50` | Output-token floor for progress detection |
+| `max_no_progress_turns` | `2` | Consecutive low-progress turns before pausing |
+| `restricted_agents` | `["plan"]` | Agents treated as planning-only |
+| `allow_goal_execution_from_plan` | `false` | Opt out of Plan-mode restrictions |
+
+## What It Cannot Do
+
+- It cannot create goals without an explicit user or agent request.
+- It cannot escape Plan-mode safety boundaries (by default).
+- It cannot persist goals across different machines without shared state storage.
+- It cannot enforce goal completion — evidence must be verified by the agent.
+
+## Best Practices
+
+- Include scope, non-goals, and verification path in the objective.
+- Ask the agent to audit real files, command output, tests, or PR state before closing a goal.
+- Use `/goal pause` and `/goal resume` to suspend and continue work across sessions.
+- Use `complete` with concrete evidence and `unmet` with a specific blocker.
+- Review goal state with `/goal` and `/goal history` regularly.
+- Set `default_token_budget` and `max_goal_duration_seconds` to prevent runaway goals.
+
+## Common Workflows
+
+### Start a long-running refactor
+
+1. Start a fresh OpenCode session.
+2. Run `/goal refactor the payment module to use the new gateway interface`.
+3. The agent works toward the goal across multiple turns.
+4. The goal auto-continues on idle until complete or blocked.
+
+### Review goal progress
+
+1. Run `/goal` to see current status, elapsed time, and objective.
+2. Run `/goal history` to see lifecycle events and checkpoints.
+3. If blocked, run `/goal pause` and address the blocker.
+
+### Close a goal with evidence
+
+1. Ask the agent to verify all requirements are met.
+2. The agent calls `update_goal` with `status: "complete"` and evidence.
+3. The goal is marked complete and the agent stops auto-continuing.
+
+### Close a blocked goal
+
+1. Run `/goal edit <updated objective>` if requirements changed.
+2. If truly blocked, ask the agent to call `update_goal` with `status: "unmet"` and a blocker description.
+3. The goal is marked unmet and the agent stops.

package/framework/plugins/opencode-goal-plugin/install.md

@@ -0,0 +1,71 @@
+# OpenCode Goal Plugin Installation
+
+## Requirements
+
+- OpenCode >= 1.17.1 installed.
+
+## Installation
+
+Install locally for the current OpenCode project:
+
+```bash
+opencode plugin @prevalentware/opencode-goal-plugin
+```
+
+Install globally:
+
+```bash
+opencode plugin -g @prevalentware/opencode-goal-plugin
+```
+
+OpenCode detects both package entrypoints and writes the plugin into the server and TUI config targets.
+
+## Manual Config
+
+If you configure it manually, add the package to both config files.
+
+`opencode.json`:
+
+```json
+{
+  "plugin": ["@prevalentware/opencode-goal-plugin"]
+}
+```
+
+`tui.json`:
+
+```json
+{
+  "plugin": ["@prevalentware/opencode-goal-plugin"]
+}
+```
+
+## Verification
+
+After installing, start or restart OpenCode and run:
+
+```
+/goal
+```
+
+You should see the current goal state (or a message that no goal is set). The TUI should also show a goal indicator in the sidebar.
+
+## Updating
+
+```bash
+opencode plugin update @prevalentware/opencode-goal-plugin
+```
+
+## Uninstalling
+
+```bash
+opencode plugin remove @prevalentware/opencode-goal-plugin
+```
+
+Then remove the plugin entries from `opencode.json` and `tui.json` if they were added manually.
+
+## Common Issues
+
+- **Plugin not found**: ensure the package name is `@prevalentware/opencode-goal-plugin` (not `opencode-goal-plugin`).
+- **OpenCode version too old**: the plugin requires OpenCode >= 1.17.1. Run `opencode --version` to check.
+- **Manual config required**: if the CLI install does not work, add the plugin to both `opencode.json` and `tui.json` manually.