opencastle 0.32.4 → 0.32.5

package/src/orchestrator/plugins/notion/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: notion-knowledge-management
+description: "Notion workspace patterns for knowledge capture, research documentation, architectural decisions, and spec management. Use when capturing research findings, writing specs, documenting decisions, or managing a team knowledge base."
+---
+
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
+
+# Knowledge Management with Notion
+
+Conventions for working with the team's Notion workspace via the official Notion MCP server. Covers page and database operations, research capture, decision documentation, and permission-aware workflows.
+
+## MCP Server
+
+| Field | Value |
+|-------|-------|
+| **Endpoint** | `https://mcp.notion.com/mcp` (HTTP, remote) |
+| **Auth** | OAuth — users authenticate via Notion account when the MCP connection is established |
+| **Type** | HTTP MCP (no local process to spawn) |
+
+### Authentication
+
+The Notion MCP server uses OAuth. When the MCP connection is first opened in your IDE, you will be prompted to authorise access to your Notion workspace. No API key or token is required in `.env`.
+
+> **Scope:** The integration is granted access only to pages and databases explicitly shared with it. Before using MCP tools, ensure the relevant pages/databases are shared with the OpenCastle integration in Notion.
+
+## Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `search` | Search pages and databases across the workspace by keyword |
+| `create_page` | Create a new page (standalone or inside a parent page/database) |
+| `update_page` | Update page properties or archive a page |
+| `append_block_children` | Append content blocks (paragraphs, headings, bullets, code) to a page |
+| `query_database` | Query a Notion database with filters and sorts |
+
+## Working with Pages and Databases
+
+### Page Hierarchy Hygiene
+
+Keep the workspace navigable by placing new pages in the right location:
+
+```
+Workspace root
+├── Engineering/
+│   ├── Architecture Decisions/   ← ADRs go here
+│   ├── Specs/                    ← Feature specs go here
+│   └── Research/                 ← Research notes go here
+├── Team/
+│   ├── Meeting Notes/            ← Meeting intelligence
+│   └── Decisions Log/            ← Key team decisions
+└── Project: <name>/              ← Per-project space
+    ├── Roadmap
+    ├── Known Issues
+    └── Release Notes/
+```
+
+- Always use `search` first to check if a page already exists before creating a new one.
+- Create pages as children of the appropriate parent — never at the workspace root unless explicitly requested.
+- Use databases (not flat pages) for collections that need filtering, sorting, or status tracking (e.g., ADRs, specs).
+
+### Page Creation Pattern
+
+When creating a page:
+
+1. `search` for an existing page with a similar title to avoid duplicates
+2. `create_page` with `parent` set to the correct parent page or database
+3. `append_block_children` to add structured content
+
+```json
+// Example: Create a spec page
+{
+  "parent": { "page_id": "<Engineering/Specs parent ID>" },
+  "properties": {
+    "title": [{ "type": "text", "text": { "content": "[Spec] Price Range Filter" } }]
+  }
+}
+```
+
+## Capturing Research and Decisions
+
+### Research Note Structure
+
+Use this outline when capturing research findings:
+
+```
+# [Research] <Topic>
+
+## Summary
+One-paragraph overview of findings.
+
+## Sources
+- <URL or reference> — <why it is relevant>
+
+## Key Findings
+- Finding 1
+- Finding 2
+
+## Implications
+How these findings affect the current task or architecture.
+
+## Open Questions
+- Question 1
+```
+
+### Architectural Decision Record (ADR) Structure
+
+```
+# ADR-NNN: <Short title>
+
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Date:** YYYY-MM-DD
+
+## Context
+What is the problem or decision to be made?
+
+## Decision
+What was decided?
+
+## Consequences
+What tradeoffs or follow-on work does this create?
+
+## Alternatives Considered
+- Option A — why rejected
+- Option B — why rejected
+```
+
+### Spec-to-Implementation Link
+
+When a spec page drives implementation, add an **Implementation** section at the bottom:
+
+```
+## Implementation
+- **Branch:** `feat/price-range-filter`
+- **PR:** <link>
+- **Tracker:** <Linear/Jira/Trello card link>
+- **Status:** In Progress / Done
+```
+
+This closes the loop between the knowledge base and the task tracker.
+
+## Meeting Intelligence
+
+When capturing meeting notes, use the following structure:
+
+```
+# Meeting: <Title> — YYYY-MM-DD
+
+**Attendees:** Name1, Name2
+**Type:** Planning / Review / Retrospective / Decision
+
+## Summary
+
+## Decisions Made
+- Decision 1 (owner: Name)
+
+## Action Items
+- [ ] Action item (owner: Name, due: YYYY-MM-DD)
+
+## Context / Discussion Notes
+```
+
+After the meeting, add action items to the task tracker.
+
+## Permission-Aware Workflows
+
+Notion access is page-scoped. Follow these rules to avoid permission errors:
+
+1. **Before writing** — run `search` to verify you can see the target page. If it does not appear, the integration has not been granted access.
+2. **Sharing** — ask the user to share the relevant page or database with the OpenCastle integration before running MCP tools against it.
+3. **Databases vs pages** — use `query_database` only on pages that are databases. Use `append_block_children` to add content to regular pages.
+4. **Archived pages** — `search` does not return archived pages. If a page is missing, it may have been archived. Ask the user to restore it.
+
+## Database Query Patterns
+
+### Filter by Status
+
+```json
+{
+  "filter": {
+    "property": "Status",
+    "select": { "equals": "In Progress" }
+  }
+}
+```
+
+### Sort by Last Edited
+
+```json
+{
+  "sorts": [
+    { "timestamp": "last_edited_time", "direction": "descending" }
+  ]
+}
+```
+
+## Agent Usage Guidelines
+
+| Agent | Primary Use |
+|-------|-------------|
+| **Team Lead** | Create spec pages, capture decisions, link tracker issues to specs |
+| **Researcher** | Capture research notes, query databases for prior art, document findings |
+| **Documentation Writer** | Write and update documentation pages, maintain page hierarchy |
+| **Architect** | Write ADRs, create technical specs, link specs to implementation PRs |
+
+**Never** delete pages via MCP — use `update_page` with `archived: true` if a page needs to be removed, and confirm with the user first.

package/src/orchestrator/plugins/notion/config.ts

@@ -0,0 +1,47 @@
+import type { PluginConfig } from '../types.js';
+
+export const config: PluginConfig = {
+  id: 'notion',
+  name: 'Notion',
+  category: 'team',
+  subCategory: 'knowledge-management',
+  label: 'Notion',
+  hint: 'Workspace knowledge base and documentation hub',
+  skillName: 'notion-knowledge-management',
+  mcpServerKey: 'Notion',
+  mcpConfig: {
+    type: 'http',
+    url: 'https://mcp.notion.com/mcp',
+  },
+  authType: 'oauth',
+  envVars: [],
+  agentToolMap: {
+    'team-lead': [
+      'Notion/search',
+      'Notion/create_page',
+      'Notion/update_page',
+      'Notion/query_database',
+      'Notion/append_block_children',
+    ],
+    'researcher': [
+      'Notion/search',
+      'Notion/create_page',
+      'Notion/append_block_children',
+      'Notion/query_database',
+    ],
+    'documentation-writer': [
+      'Notion/search',
+      'Notion/create_page',
+      'Notion/update_page',
+      'Notion/append_block_children',
+    ],
+    'architect': [
+      'Notion/search',
+      'Notion/create_page',
+      'Notion/update_page',
+      'Notion/query_database',
+    ],
+  },
+  docsUrl: 'https://www.opencastle.dev/docs/plugins#notion',
+  officialDocs: 'https://developers.notion.com/docs/mcp',
+};

package/src/orchestrator/plugins/trello/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: trello-task-management
+description: "Trello board conventions for tracking feature work — board/list/card workflow, checklist-driven task breakdown, due dates, and when to use comments vs checklist items. Use when decomposing features into cards or resuming interrupted sessions."
+---
+
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
+
+# Task Management with Trello
+
+Conventions for tracking feature work on Trello boards via MCP tools. For project-specific board IDs and list IDs, see [tracker-config.md](../../.opencastle/project/tracker-config.md).
+
+## MCP Server
+
+| Field | Value |
+|-------|-------|
+| **Package** | [`@delorenj/mcp-server-trello`](https://www.npmjs.com/package/@delorenj/mcp-server-trello) |
+| **Type** | stdio (spawned via `npx -y @delorenj/mcp-server-trello`) |
+| **Auth** | API key + token via `TRELLO_API_KEY` and `TRELLO_TOKEN` env vars |
+
+### Authentication
+
+1. Get your API key at [trello.com/app-key](https://trello.com/app-key) → **API Key**
+2. On the same page, click **"Generate a Token"** to get your token
+3. Add both to your `.env` file:
+
+```
+TRELLO_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+TRELLO_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+## Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_boards` | List all boards accessible to the authenticated user |
+| `get_lists` | Get all lists on a board (by board ID) |
+| `get_cards_by_list_id` | Get all cards in a specific list |
+| `get_card_details` | Get full details of a single card |
+| `create_card` | Create a new card in a list |
+| `update_card` | Update card fields (name, description, due date, list) |
+| `add_checklist_to_card` | Add a checklist with items to a card |
+| `add_comment_to_card` | Post a comment on a card |
+
+## Discovered Issues (Bug Tickets)
+
+When an agent encounters a pre-existing bug or issue unrelated to the current task, it must be tracked:
+
+1. **Check** existing cards on the board to see if it is already tracked
+2. **If tracked** — skip it, continue with current work
+3. **If NOT tracked:**
+   - **Unfixable limitation** — add to known issues with severity, evidence, and root cause
+   - **Fixable bug** — create a Trello card:
+     - **Name:** `[Bug] Short description of the symptom`
+     - **List:** `Backlog` (or the equivalent list in your project)
+     - **Description:** Include symptoms, reproduction steps, affected files, and any error messages
+     - **Due date:** Set only if it is blocking current work
+
+## Card Naming
+
+Use `[Area] Short description` format:
+
+```
+[Schema] Add priceRange field to place type
+[DB] Add price_range column and migration
+[UI] Build PriceRangeFilter component
+[API] Add price filter endpoint
+[Test] Unit tests for price filter
+[Docs] Update data model documentation
+```
+
+**Area prefixes:** `[Schema]`, `[DB]`, `[Query]`, `[UI]`, `[Page]`, `[API]`, `[Auth]`, `[Test]`, `[Docs]`, `[Deploy]`, `[Data]`, `[Perf]`, `[Security]`, `[Bug]`
+
+## Board and List Workflow
+
+### Typical List Structure
+
+```
+Backlog  →  To Do  →  In Progress  →  In Review  →  Done
+```
+
+- **Backlog** — Captured but not yet planned
+- **To Do** — Planned and ready to start
+- **In Progress** — Actively being worked on
+- **In Review** — PR open, awaiting review or merge
+- **Done** — Completed and verified
+
+### Agent-Driven Card Transitions (via MCP)
+
+| From | To | When |
+|------|----|------|
+| Backlog / To Do | In Progress | Agent starts working on the card |
+| In Progress | Done | Non-PR task is verified (docs, config) |
+| Any | Backlog | Task is deferred |
+
+## Checklist-Driven Task Breakdown
+
+Use checklists for **subtask decomposition within a single card**. This keeps related work together without cluttering the board with micro-cards.
+
+### When to Use a Checklist vs a Separate Card
+
+| Use a **checklist item** when… | Use a **separate card** when… |
+|-------------------------------|------------------------------|
+| Steps are sequential and tightly coupled | Work can be assigned independently |
+| Total effort fits in one session | Each step spans multiple sessions |
+| Steps share the same assignee | Steps need different labels/due dates |
+| Internal implementation details | Distinct deliverables that need review |
+
+### Checklist Pattern for Feature Decomposition
+
+```
+Card: [Feature] Add price range filter
+Checklist: Implementation Steps
+  ☐ Add priceRange field to schema
+  ☐ Create DB migration
+  ☐ Update GROQ/API query
+  ☐ Build UI component
+  ☐ Wire into page
+  ☐ Write unit tests
+  ☐ Update documentation
+```
+
+## Due and Start Dates
+
+Trello cards support both a **start date** and a **due date**.
+
+- **Due date** — The deadline for the card to move to Done. Set for tasks on the critical path.
+- **Start date** — When work is expected to begin. Useful for pipeline planning.
+- **Due time** — Be explicit with time only for time-sensitive deliverables (e.g., scheduled releases).
+- **Format:** Trello API uses ISO 8601: `2026-03-20T14:00:00.000Z`
+
+## Comments vs Checklist Items
+
+| Use **comments** for… | Use **checklist items** for… |
+|-----------------------|------------------------------|
+| Progress updates visible to the team | Actionable steps with completion state |
+| Blocking issues or decisions | Pre-defined subtask decomposition |
+| Links to PRs, builds, external docs | Typed acceptance criteria |
+| Questions or async approvals | Implementation sub-steps |
+| Post-implementation notes | QA verification steps |
+
+**Rule of thumb:** If it needs to be *checked off*, it's a checklist item. If it needs to be *read*, it's a comment.
+
+## Session Continuity
+
+At the start of each work session:
+
+1. `get_boards` — confirm the right board is active
+2. `get_lists` — identify current list structure
+3. `get_cards_by_list_id` for **In Progress** — find cards already in flight
+4. Resume work on the relevant card, updating the checklist as steps complete
+5. Move the card to the next list when the current phase is done

package/src/orchestrator/plugins/trello/config.ts

@@ -0,0 +1,44 @@
+import type { PluginConfig } from '../types.js';
+
+export const config: PluginConfig = {
+  id: 'trello',
+  name: 'Trello',
+  category: 'team',
+  subCategory: 'task-management',
+  label: 'Trello',
+  hint: 'Visual board task management via MCP',
+  skillName: 'trello-task-management',
+  mcpServerKey: 'Trello',
+  mcpConfig: {
+    type: 'stdio',
+    command: 'npx',
+    args: ['-y', '@delorenj/mcp-server-trello'],
+    envFile: '${workspaceFolder}/.env',
+  },
+  authType: 'env-token',
+  envVars: [
+    {
+      name: 'TRELLO_API_KEY',
+      hint: 'Create at trello.com/app-key -> API Key',
+    },
+    {
+      name: 'TRELLO_TOKEN',
+      hint: 'Generate at trello.com/app-key -> Token (click "Generate a Token")',
+    },
+  ],
+  agentToolMap: {
+    'team-lead': [
+      'Trello/get_boards',
+      'Trello/get_lists',
+      'Trello/get_cards_by_list_id',
+      'Trello/get_card_details',
+      'Trello/create_card',
+      'Trello/update_card',
+      'Trello/add_checklist_to_card',
+      'Trello/add_comment_to_card',
+    ],
+  },
+  docsUrl: 'https://www.opencastle.dev/docs/plugins#trello',
+  officialDocs: 'https://developer.atlassian.com/cloud/trello/',
+  mcpPackage: '@delorenj/mcp-server-trello',
+};

package/src/orchestrator/plugins/types.ts

@@ -13,7 +13,7 @@ export interface PluginConfig {
   category: 'tech' | 'team';
 
   /** Sub-category for grouping */
-  subCategory: 'cms' | 'database' | 'deployment' | 'framework' | 'codebase-tool' | 'task-management' | 'notifications' | 'testing' | 'e2e-testing' | 'design' | 'email';
+  subCategory: 'cms' | 'database' | 'deployment' | 'framework' | 'codebase-tool' | 'task-management' | 'knowledge-management' | 'notifications' | 'testing' | 'e2e-testing' | 'design' | 'email';
 
   /** Label shown in the `npx opencastle init` multiselect */
   label: string;