opencastle 0.1.0

package/src/orchestrator/skills/slack-notifications/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: slack-notifications
+description: "Slack MCP integration for agent-to-human notifications and bi-directional communication. Use when agents need to post progress updates, request approvals, or read user responses via Slack channels and threads."
+---
+
+# Slack Notifications
+
+Agent communication patterns via the Slack MCP server. Enables agents to post progress updates, request human approvals, and read responses — all through Slack channels and threads.
+
+## MCP Server
+
+| Field | Value |
+|-------|-------|
+| **URL** | `https://mcp.slack.com/mcp` |
+| **Type** | Streamable HTTP (JSON-RPC 2.0) |
+| **Auth** | OAuth 2.0 via registered Slack app (`client_id` + `client_secret`) |
+| **Supported clients** | Claude.ai, Claude Code, Cursor, Perplexity |
+
+### Required OAuth Scopes
+
+The Slack app must be granted scopes for the operations agents will perform:
+
+| Scope | Purpose |
+|-------|---------|
+| `channels:read` | List and search public channels |
+| `channels:history` | Read messages in public channels |
+| `chat:write` | Post messages and replies |
+| `users:read` | Look up user profiles for mentions |
+| `reactions:read` | Read emoji reactions (approval signals) |
+| `reactions:write` | Add emoji reactions (acknowledgments) |
+| `search:read` | Search messages and files |
+
+Admin approval is required. Work with the workspace admin to install the app.
+
+## Available MCP Tools
+
+The Slack MCP server exposes tools for:
+
+- **Search** — `slack_search_messages`, `slack_search_channels`, `slack_search_users`
+- **Read** — `slack_get_channel_history`, `slack_get_thread_replies`, `slack_get_channel_info`
+- **Write** — `slack_post_message`, `slack_reply_to_thread`, `slack_add_reaction`
+- **Canvases** — `slack_create_canvas`, `slack_update_canvas`
+
+Tool names may vary by MCP server version. Use tool discovery to list available tools at runtime.
+
+## Agent Notification Patterns
+
+### Progress Updates
+
+Post structured progress updates to a designated channel:
+
+```
+Channel: #agent-updates (or project-specific channel)
+Format:
+  🔄 **Task:** TAS-42 — Add price filter component
+  **Status:** In progress — implementing unit tests
+  **Files changed:** 3 (PriceFilter.tsx, PriceFilter.test.tsx, index.ts)
+  **ETA:** ~5 minutes
+```
+
+### Completion Notifications
+
+```
+✅ **Task:** TAS-42 — Add price filter component
+**Status:** Complete — PR opened
+**PR:** https://github.com/org/repo/pull/123
+**Summary:** Added PriceRangeFilter with 4 range options, 12 unit tests passing
+```
+
+### Error / Blocking Notifications
+
+```
+🚨 **Task:** TAS-42 — Add price filter component
+**Status:** Blocked — needs human input
+**Issue:** Cannot determine correct price ranges for the market
+**Action needed:** Reply in this thread with the desired price range values
+```
+
+## Bi-Directional Communication
+
+### Human-in-the-Loop Approval
+
+When an agent needs approval before proceeding (destructive operations, production deployments, large refactors):
+
+1. **Post approval request** to the channel with clear options:
+   ```
+   ⏳ **Approval Required**
+   Task: TAS-42 — Database migration adds `price_range` column
+   Action: Run migration on production database
+   
+   React with:
+   ✅ — Approve and proceed
+   ❌ — Reject and stop
+   💬 — Reply in thread with questions
+   ```
+
+2. **Poll for response** — Read reactions or thread replies to determine the decision
+3. **Acknowledge** — Post confirmation of the action taken
+
+### Reading User Responses
+
+To check for approvals or instructions:
+
+1. Use `slack_get_thread_replies` to read replies to the approval message
+2. Use `slack_get_channel_history` with a time range to find recent directives
+3. Parse reactions on messages for quick yes/no signals
+
+### Parsing Conventions
+
+| Signal | Meaning |
+|--------|---------|
+| ✅ reaction | Approved — proceed |
+| ❌ reaction | Rejected — stop and report |
+| 👀 reaction | Acknowledged — user is reviewing |
+| Thread reply | Detailed instructions or questions |
+| `@agent` mention | Direct command or question for the agent |
+
+## Channel & Thread Conventions
+
+### Channel Structure
+
+| Channel | Purpose |
+|---------|---------|
+| `#agent-updates` | General agent activity feed |
+| `#agent-approvals` | Approval requests requiring human action |
+| `#agent-errors` | Error reports and blocked tasks |
+| Project-specific channel | All activity for a specific project |
+
+### Threading Rules
+
+- **Always thread replies** — never post top-level messages for follow-ups
+- **One thread per task** — keep all updates for a single task in one thread
+- **Include task ID** — every message references the Linear/Jira issue ID
+- **Pin important threads** — pin approval requests and blocking issues
+
+## Message Formatting
+
+Slack uses a markdown-like syntax with some differences:
+
+| Format | Syntax |
+|--------|--------|
+| Bold | `*bold*` |
+| Italic | `_italic_` |
+| Strikethrough | `~strikethrough~` |
+| Code | `` `inline code` `` |
+| Code block | ` ```code block``` ` |
+| Link | `<https://example.com|Display Text>` |
+| User mention | `<@U12345>` |
+| Channel mention | `<#C12345>` |
+| Emoji | `:emoji_name:` |
+| Blockquote | `> quoted text` |
+| List | `• item` or `1. item` |
+
+## Rate Limits
+
+| Tier | Limit | Applies to |
+|------|-------|------------|
+| Tier 1 | 1 per minute | Rare admin actions |
+| Tier 2 | 20 per minute | Most write operations (`chat:write`) |
+| Tier 3 | 50 per minute | Most read operations |
+| Tier 4 | 100+ per minute | Search, history reads |
+
+**Best practices:**
+- Batch updates into single messages rather than posting many small messages
+- Use threads to consolidate related updates
+- Add 1-second delays between consecutive write operations
+- Cache channel/user IDs — don't look them up repeatedly
+
+## Security Considerations
+
+- **OAuth tokens** are managed by the MCP server — agents never see raw tokens
+- **Scope minimization** — request only the scopes agents actually need
+- **Channel restrictions** — limit the app to specific channels rather than granting workspace-wide access
+- **Audit logging** — Slack Enterprise Grid provides audit logs for all API activity
+- **No secrets in messages** — never post tokens, passwords, or credentials in Slack messages (per Constitution #1)
+
+## Integration with Agent Workflows
+
+### Session Start
+
+At the beginning of a work session, post a brief status message:
+```
+🏁 **Session started**
+Agent: Frontend Engineer
+Task: TAS-42 — Add price filter component
+Mode: Autonomous (will request approval for destructive actions)
+```
+
+### Session End
+
+At the end of a work session, post a summary:
+```
+🏁 **Session complete**
+Agent: Frontend Engineer
+Task: TAS-42 — Add price filter component
+Result: ✅ PR opened (#123)
+Duration: 12 minutes
+Files changed: 5
+Tests: 12 passing, 0 failing
+```
+
+### Error Recovery
+
+If an agent encounters an unrecoverable error, notify before stopping:
+```
+💥 **Session failed**
+Agent: Frontend Engineer
+Task: TAS-42 — Add price filter component
+Error: TypeScript compilation failed — 3 type errors in PriceFilter.tsx
+Action: Posted details in thread. Needs manual fix or re-delegation.
+```

package/src/orchestrator/skills/strapi-cms/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: strapi-cms
+description: "Strapi CMS development patterns, REST/GraphQL API usage, content type building, plugin development, and deployment best practices. Use when working with Strapi content types, controllers, services, or plugins."
+---
+
+# Strapi CMS
+
+Generic Strapi CMS development methodology. For project-specific configuration, content types, and deployment details, see [cms-config.md](../../customizations/stack/cms-config.md).
+
+## Critical Development Rules
+
+1. **Use Content-Type Builder** — define content types through the admin panel or `content-types` directory
+2. **REST API by default** — Strapi exposes REST endpoints automatically; enable GraphQL plugin if needed
+3. **Customize controllers** — extend auto-generated controllers in `src/api/<type>/controllers/`
+4. **Services for business logic** — keep business logic in services, not controllers
+5. **Lifecycle hooks** — use model lifecycle hooks for side effects (e.g., `beforeCreate`, `afterUpdate`)
+6. **Permissions and roles** — configure permissions via the Users & Permissions plugin
+7. **Draft/Publish system** — enable draft/publish on content types that need editorial workflow
+8. **Media Library** — use Strapi's media library for asset management; configure providers for S3/Cloudinary
+9. **Environment configs** — use `config/env/<env>/` for environment-specific configuration
+10. **Never modify `node_modules`** — extend functionality through plugins and customizations
+
+## API Patterns
+
+### REST API
+- Endpoints follow `/api/<content-type>` convention
+- Use `populate` parameter to include relations
+- Use `filters` parameter with operators (`$eq`, `$contains`, `$in`, etc.)
+- Pagination via `pagination[page]` and `pagination[pageSize]`
+- Use `fields` to select specific attributes
+
+### GraphQL Plugin
+- Enable via `@strapi/plugin-graphql`
+- Auto-generates types and resolvers from content types
+- Use `filters`, `pagination`, and `sort` arguments
+- Custom resolvers in `src/api/<type>/graphql/`
+
+## Plugin Development
+
+- Scaffold with `strapi generate plugin <name>`
+- Follow the plugin structure: `admin/`, `server/`, `content-types/`
+- Register plugin in `config/plugins.ts`
+- Use the Plugin SDK for admin panel extensions

package/src/orchestrator/skills/supabase-database/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: supabase-database
+description: "Supabase database migration rules, RLS policy patterns, and auth integration best practices. Use when designing database tables, writing migrations, configuring RLS policies, implementing auth, or managing user roles."
+---
+
+# Supabase Database
+
+Generic Supabase development methodology. For project-specific schema, roles, migration history, auth flow, and key files, see [supabase-config.md](../../customizations/stack/supabase-config.md).
+
+## Migration Rules
+
+1. Always write migrations for schema changes — never modify schema directly.
+2. Use RLS on all tables — no exceptions.
+3. Test RLS from different roles (anon, user, moderator, admin).
+4. `CASCADE DELETE` where appropriate.
+5. Add indexes for frequently queried columns.
+6. Naming: `NNN_description.sql` or `YYYYMMDD_description.sql`.
+7. Write idempotent migrations — they must be safe to re-run.
+8. Document migration purpose with SQL comments.
+9. Validate schema changes don't break existing RLS policies.
+10. Use `auth.uid()` in RLS policies — never pass user ID from the client.
+11. Prefer database functions for complex authorization logic.
+12. Test migrations in a development dataset before production.
+13. Always generate TypeScript types after schema changes.

package/src/orchestrator/skills/task-management/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: task-management
+description: "Linear board conventions for tracking feature work — issue naming, labels, priorities, status workflow, and session continuity. Use when decomposing features into tasks or resuming interrupted sessions."
+---
+
+# Task Management with Linear
+
+Conventions for tracking feature work on the Linear board via MCP tools. For project-specific team ID, workflow state UUIDs, and label UUIDs, see [linear-config.md](../../customizations/project/linear-config.md).
+
+## Discovered Issues (Bug Tickets)
+
+When an agent encounters a pre-existing bug or issue unrelated to the current task, it must be tracked. Follow this flow:
+
+1. **Check** known issues docs and Linear (search for open bugs) to see if it's already tracked
+2. **If tracked** — skip it, continue with current work
+3. **If NOT tracked:**
+   - **Unfixable limitation** — add to known issues with Issue ID, Status, Severity, Evidence, Root Cause, Solution Options
+   - **Fixable bug** — create a Linear ticket:
+     - **Name:** `[Bug] Short description of the symptom`
+     - **Label:** `bug` (plus the relevant domain label, e.g., `ui`, `nextjs`)
+     - **Priority:** P2 if it affects users, P3 if cosmetic or non-blocking
+     - **Description:** Include symptoms, reproduction steps, affected files, and any error messages or screenshots
+     - **Status:** Backlog (unless it's blocking current work, then Todo)
+
+## Issue Naming
+
+Use `[Area] Short description` format:
+
+```
+[Schema] Add priceRange field to place type
+[DB] Add price_range column and migration
+[Query] Update GROQ query with priceRange filter
+[UI] Build PriceRangeFilter component
+[Page] Integrate price filter into /places
+[Test] E2E test price range filtering
+[Docs] Update data model documentation
+```
+
+**Area prefixes:** `[Schema]`, `[DB]`, `[Query]`, `[UI]`, `[Page]`, `[API]`, `[Auth]`, `[Test]`, `[Docs]`, `[Deploy]`, `[Data]`, `[Perf]`, `[Security]`
+
+## Priority
+
+| Level | Meaning | When to use |
+|-------|---------|-------------|
+| P1 (Urgent) | Blocker | Blocks other tasks, critical path |
+| P2 (High) | Important | Core feature work, on critical path |
+| P3 (Medium) | Normal | Supporting tasks, can be parallelized |
+| P4 (Low) | Nice-to-have | Docs, cleanup, polish |
+
+## Status Workflow
+
+```
+Backlog -> Todo -> In Progress -> In Review -> Done -> Cancelled
+```
+
+- **Backlog** — Captured but not yet planned
+- **Todo** — Planned for current feature, ready to start
+- **In Progress** — Actively being worked on by an agent
+- **In Review** — PR opened, awaiting review/merge
+- **Done** — Completed and verified
+- **Cancelled** — Dropped or no longer relevant
+
+### Status Drivers
+
+Issue status is driven by **two sources** — the Team Lead agent (via MCP) and the GitHub integration (automatically). Both can move issues through the workflow.
+
+**Agent-driven transitions (via MCP):**
+- **Todo -> In Progress** — when the agent starts working on a task
+- **In Progress -> Done** — when non-PR tasks are verified (e.g., docs, config changes)
+- **Any -> Cancelled** — when a task is dropped
+
+**GitHub-driven transitions (automatic):**
+
+The Linear-GitHub integration auto-updates issue status based on PR lifecycle events. This is configured in Linear under *Settings -> Team -> Issue statuses & automations -> Pull request and commit automation*.
+
+| PR Event | Linear Status Change |
+|----------|---------------------|
+| Branch pushed / PR drafted | -> **In Progress** |
+| PR opened | -> **In Progress** |
+| Review requested | -> **In Review** |
+| PR ready for merge (all checks pass) | -> **In Review** |
+| PR merged to `main` | -> **Done** |
+
+**Linking issues to PRs:** Include the Linear issue ID (e.g., `TAS-123`) in the branch name or PR title. Linear auto-detects the link and begins status automation. Use the branch name format from Linear: copy with `Cmd+Shift+.` on any issue.
+
+**Multiple PRs per issue:** When multiple PRs are linked to one issue, the status only advances to Done when the *last* linked PR is merged.
+
+**Important:** When GitHub automation handles status transitions, the agent does not need to update status manually — avoid conflicting updates. Only use MCP to move status when there is no linked PR (e.g., documentation-only tasks, config changes, schema deploys).
+
+## Issue Descriptions
+
+Every issue must include:
+
+```markdown
+**Objective:** One sentence describing the deliverable
+
+**Files (partition):**
+- `path/to/relevant/file.ts`
+- `path/to/another/file.ts`
+
+**Acceptance Criteria:**
+- [ ] Specific, verifiable outcome 1
+- [ ] Specific, verifiable outcome 2
+
+**Dependencies:** #TAS-XX (if any)
+```
+
+The **Files (partition)** section defines which files this agent is allowed to modify. This prevents merge conflicts when multiple agents work in parallel — no two issues in the same phase should list overlapping files.
+
+## Feature Grouping
+
+- Use a **Linear project** for each major feature
+- Create projects via the Linear UI — no create_project API is available via MCP
+- All related issues belong to that project
+- Issues track individual subtasks within the feature
+
+## Session Workflow
+
+### Starting a new feature
+
+1. Read the board to check for existing in-progress work
+2. Decompose the feature into issues following the conventions above
+3. Create all issues on Linear with correct naming, labels, priority, and descriptions
+4. Note dependencies in issue descriptions — Linear MCP has no dependency API
+5. Begin delegation
+
+### During execution
+
+- Move issue to **In Progress** before delegating to an agent
+- Move issue to **Done** immediately after the agent completes and output is verified
+- If a task is blocked, update the issue description explaining the blocker (Linear MCP has no comment API)
+
+### Resuming an interrupted session
+
+1. List issues filtered by **In Progress** and **Todo** status
+2. Read issue descriptions to restore context
+3. Pick up where work left off — no need to re-analyze from scratch
+
+### Completing a feature
+
+1. Verify all issues are **Done** or **Cancelled**
+2. Run final build/lint/test checks
+3. Mark all project issues as Done or Cancelled (closing the project requires the Linear UI)