Merge pull request #1 from Octane0411/feat/initial-implementation

Feat/initial implementation

Author: Octane0411

.gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.DS_Store
+*.tsbuildinfo
+opencode.json
+AGENTS.md

README.md

@@ -1,2 +1,90 @@
 # opencode-plugin-openspec
-An OpenCode plugin that integrates OpenSpec, allowing Plan Mode to create and edit spec files.
+
+An OpenCode plugin that integrates OpenSpec, providing a dedicated agent for planning and specifying software architecture.
+
+## Features
+
+- **Auto-Detection**: Automatically detects if the current workspace is an OpenSpec project.
+- **New Agent: `openspec-plan`**: A dedicated agent mode for creating and editing OpenSpec files.
+- **Smart Permissions**: Automatically grants write permissions for:
+  - `project.md`
+  - `AGENTS.md`
+  - `openspec/**`
+  - `specs/**`
+- **Read-Only Safety**: Keeps the rest of the codebase read-only when using the `openspec-plan` agent, ensuring the implementation details are not accidentally modified during the planning phase.
+
+## Installation
+
+### For Humans
+
+**Option 1: Let your agent do it (Recommended)**
+
+Paste this prompt into OpenCode:
+
+```
+Install opencode-plugin-openspec. It is an NPM package. Please add "opencode-plugin-openspec" to my opencode.json plugin list.
+```
+
+**Option 2: Manual Installation**
+
+Add the plugin package name to your `opencode.json` configuration file (usually located at `~/.config/opencode/opencode.json` or `.opencode/opencode.json`):
+
+```json
+{
+  "plugin": [
+    "opencode-plugin-openspec"
+  ]
+}
+```
+
+OpenCode will automatically download and install the plugin the next time it runs.
+
+### For LLM Agents
+
+If you are an AI agent tasked with installing this plugin, follow these steps:
+
+1.  **Locate Configuration**: Find the user's OpenCode configuration file. It is typically at `~/.config/opencode/opencode.json` or `.opencode/opencode.json` in the workspace root.
+2.  **Read Configuration**: Read the content of the configuration file.
+3.  **Update Configuration**: Add `"opencode-plugin-openspec"` to the `plugin` array. If the `plugin` array does not exist, create it.
+    ```json
+    {
+      "plugin": [
+        "opencode-plugin-openspec"
+      ]
+    }
+    ```
+4.  **Verify**: Inform the user that the plugin has been added and will be installed on the next OpenCode run.
+
+## Usage
+
+1. Open an OpenSpec project in OpenCode.
+2. The plugin will automatically detect the project structure.
+3. Switch to the **OpenSpec Architect** agent (colored #FF6B6B) in the agent selector.
+4. Start planning your architecture! The agent will have access to modify your spec files while keeping your code safe.
+
+## Development
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/yourusername/opencode-plugin-openspec.git
+   cd opencode-plugin-openspec
+   ```
+
+2. Install dependencies:
+   ```bash
+   bun install
+   ```
+
+3. Build the plugin:
+   ```bash
+   bun run build
+   ```
+
+4. Run watch mode for development:
+   ```bash
+   bun run watch
+   ```
+
+## License
+
+MIT

bun.lock

@@ -0,0 +1,41 @@
+{
+  "name": "opencode-plugin-openspec",
+  "version": "0.1.0",
+  "description": "An OpenCode plugin that integrates OpenSpec, providing a dedicated agent for planning and specifying software architecture.",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outfile ./dist/index.js --target node",
+    "watch": "bun build ./src/index.ts --outfile ./dist/index.js --target node --watch",
+    "prepublishOnly": "bun run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Octane0411/opencode-plugin-openspec.git"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "openspec",
+    "agent",
+    "architecture",
+    "planning"
+  ],
+  "author": "Octane0411",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Octane0411/opencode-plugin-openspec/issues"
+  },
+  "homepage": "https://github.com/Octane0411/opencode-plugin-openspec#readme",
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.1.19",
+    "@opencode-ai/sdk": "^1.1.19"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.0.0"
+  }
+}

package.json

@@ -0,0 +1,40 @@
+import type { Hooks } from "@opencode-ai/plugin";
+import { isOpenSpecProject } from "./utils/detection";
+import { OPENSPEC_SYSTEM_PROMPT } from "./prompts";
+
+export function createConfigHook(ctx: { directory: string }): Hooks["config"] {
+  return async (config) => {
+    // 1. Check if this is an OpenSpec project
+    const mockCtx = { directory: ctx.directory } as any;
+    
+    const isActive = await isOpenSpecProject(mockCtx);
+    if (!isActive) {
+      return;
+    }
+
+    // 2. Define the OpenSpec Plan Agent
+    const openSpecAgent = {
+      name: "openspec-plan",
+      mode: "primary",
+      description: "OpenSpec Architect - Plan and specify software architecture.",
+      prompt: OPENSPEC_SYSTEM_PROMPT,
+      permission: {
+        edit: {
+          // Allow editing specific root files
+          "project.md": "allow",
+          "AGENTS.md": "allow",
+          // Allow editing anything in openspec directory
+          "openspec/**": "allow",
+          // Allow editing anything in specs directory (standard OpenSpec structure)
+          "specs/**": "allow"
+        }
+      },
+      color: "#FF6B6B" // Distinctive color for the agent
+    };
+
+    // 3. Inject into configuration
+    const agentConfig = (config.agent || {}) as any;
+    agentConfig["openspec-plan"] = openSpecAgent;
+    config.agent = agentConfig;
+  };
+}

src/config.ts

@@ -0,0 +1,17 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { createConfigHook } from "./config";
+import { isOpenSpecProject } from "./utils/detection";
+
+const OpenSpecPlugin: Plugin = async (ctx) => {
+  const isActive = await isOpenSpecProject(ctx);
+
+  if (!isActive) {
+    return {};
+  }
+
+  return {
+    config: createConfigHook(ctx),
+  };
+};
+
+export default OpenSpecPlugin;

src/index.ts

@@ -0,0 +1,24 @@
+export const OPENSPEC_SYSTEM_PROMPT = `
+<Role>
+You are the **OpenSpec Architect**.
+Your goal is to design, specify, and document software architecture using the OpenSpec standard.
+You work primarily with Markdown files in the \`openspec/\` and \`specs/\` directories.
+</Role>
+
+<Context>
+This project follows the OpenSpec standard for documentation-driven development.
+Key files:
+- \`project.md\`: High-level project vision, goals, and scope.
+- \`openspec/AGENTS.md\` (or \`AGENTS.md\`): Definitions of agents and their roles.
+- \`specs/**/*.spec.md\`: Detailed specifications for components or features.
+</Context>
+
+<Rules>
+1. **Focus on Specifications**: Your primary output should be modifications to \`*.spec.md\` files.
+2. **No Implementation**: Do NOT write implementation code (TypeScript, Python, etc.) unless explicitly requested to "implement" or "prototype". Your job is to *plan*, not to *build*.
+3. **Structure**:
+   - When designing a new feature, create a new spec file in \`specs/<feature-name>/spec.md\`.
+   - Link back to \`project.md\` to ensure alignment with high-level goals.
+4. **Format**: Follow the existing Markdown structure found in the project. Use clear headers, bullet points, and diagrams (Mermaid) where appropriate.
+</Rules>
+`.trim();

src/prompts.ts

@@ -0,0 +1,16 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Checks if the current workspace is an OpenSpec project.
+ * 
+ * Detection logic:
+ * 1. Checks for `openspec/AGENTS.md` (Primary indicator)
+ * 2. Checks for `AGENTS.md` in root (Secondary indicator)
+ */
+export async function isOpenSpecProject(ctx: PluginInput): Promise<boolean> {
+  const openspecAgentsPath = join(ctx.directory, "openspec", "AGENTS.md");
+
+  return existsSync(openspecAgentsPath);
+}

src/utils/detection.ts

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "module": "esnext",
+    "target": "esnext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "composite": true,
+    "strict": true,
+    "downlevelIteration": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "allowJs": true,
+    "types": [
+      "bun-types" // add Bun global
+    ]
+  }
+}