opencastle 0.1.0

package/src/orchestrator/skills/team-lead-reference/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: team-lead-reference
+description: "Reference data for Team Lead orchestration — model routing, pre-delegation checks, cost tracking template, and DLQ format. Load when starting a delegation session."
+---
+
+# Team Lead Reference
+
+For the specialist agent registry and model assignments, see [agent-registry.md](../../customizations/agents/agent-registry.md).
+
+## Cost-Aware Model Routing
+
+Choose models deliberately based on task complexity. Not every task needs the most expensive model.
+
+### Model Cost Tiers
+
+| Tier | Cost | Use For |
+|------|------|---------|
+| **Premium** | $$$ | Architecture decisions, security audits, complex reasoning, panel reviews |
+| **Standard** | $$ | Feature implementation, schema design, component building |
+| **Utility** | $$ | Terminal-heavy tasks, E2E tests, data pipelines, scripted workflows |
+| **Economy** | $ | Documentation, simple config changes, formatting, boilerplate |
+
+### Selection Rules
+
+1. **Default to the agent's assigned model** — the registry maps tasks to appropriate tiers
+2. **Downgrade when possible** — If a task is pure docs/config with no reasoning needed, prefer Economy tier
+3. **Upgrade for ambiguity** — If the task involves security, architecture decisions, or complex tradeoffs, use Premium
+4. **Never use Premium for boilerplate** — Writing test scaffolding, updating docs, or config changes should use Economy/Standard
+5. **Parallel sub-agents are cost multipliers** — When firing 3+ parallel sub-agents, prefer Standard/Economy unless precision is critical
+
+## Complexity-Based Task Scoring
+
+During decomposition, assign a **complexity score** (Fibonacci: 1, 2, 3, 5, 8, 13) to each subtask. The score determines which model tier handles the task.
+
+### Scoring Criteria
+
+| Factor | Low (1-2) | Medium (3-5) | High (8-13) |
+|--------|-----------|--------------|-------------|
+| **Files touched** | 1-2 files | 3-5 files | 6+ files or cross-library |
+| **Reasoning depth** | Mechanical / boilerplate | Pattern matching, moderate logic | Architecture decisions, security, tradeoffs |
+| **Ambiguity** | Clear spec, obvious approach | Some judgment calls | Multiple valid approaches, needs exploration |
+| **Risk** | No data loss, easily reversible | Moderate impact, testable | DB migrations, auth changes, breaking changes |
+| **Dependencies** | None | 1-2 upstream tasks | Complex dependency chain |
+
+### Score to Model Tier Mapping
+
+| Score | Tier | Examples |
+|-------|------|----------|
+| **1-2** | Economy/Utility | Docs update, config tweak, rename, simple test |
+| **3-5** | Standard | Component build, GROQ query, API route, migration |
+| **8** | Premium | Architecture decision, security audit, complex refactor |
+| **13** | Premium + Panel | DB migration with data transform, auth flow redesign |
+
+### Override Rules
+
+- **Blocker tasks** (blocking 2+ downstream tasks): Upgrade one tier regardless of score
+- **Security-touching tasks**: Always Premium, regardless of score
+- **Pure documentation**: Always Economy, regardless of estimated scope
+- The agent registry default model takes precedence unless the task complexity clearly warrants an upgrade/downgrade
+
+## Deepen-Plan Protocol
+
+After initial decomposition, **enrich the plan** with concrete codebase evidence before delegating. This prevents agents from wasting time on discovery that the Team Lead can do upfront.
+
+### When to Deepen
+
+| Plan Complexity | Action |
+|----------------|--------|
+| 1-2 subtasks, familiar area | Skip — proceed directly to delegation |
+| 3-5 subtasks, mixed familiarity | Quick deepen — single Researcher sub-agent |
+| 6+ subtasks, unfamiliar area | Full deepen — parallel Researcher sub-agents |
+
+### Quick Deepen (Single Researcher)
+
+Fire one **Researcher** sub-agent with this prompt:
+
+```
+Research the following planned subtasks and enrich each with:
+1. Exact file paths and line numbers for code that will change
+2. Existing patterns to follow (with file:line examples)
+3. Related lessons from .github/customizations/LESSONS-LEARNED.md
+4. Risks or blockers (missing dependencies, known issues)
+
+Subtasks:
+- [Subtask 1 description]
+- [Subtask 2 description]
+- ...
+
+Return a structured report per subtask.
+```
+
+### Full Deepen (Parallel Researchers)
+
+For large plans, split research by domain and fire parallel Researcher sub-agents. See [agent-registry.md](../../customizations/agents/agent-registry.md) for project-specific scope examples.
+
+### What Deepening Produces
+
+After deepening, each subtask in the plan should have:
+
+| Field | Before Deepen | After Deepen |
+|-------|--------------|--------------|
+| **Files** | "some component" | Exact file path with line range |
+| **Pattern** | "follow existing style" | Specific file:line reference to follow |
+| **Risks** | unknown | Known issues identified |
+| **Lessons** | unchecked | Relevant lessons applied |
+| **Dependencies** | assumed | Verified with exact imports |
+
+### Integrating Results
+
+Take the Researcher output and update delegation prompts with concrete file paths, patterns, and lessons. This transforms vague prompts into precise instructions that agents can execute without discovery overhead.
+
+## Pre-Delegation Policy Checks
+
+Run these validation checks **before** delegating any subtask. Non-negotiable gates.
+
+### Mandatory Checks (before every delegation)
+
+1. **Linear issue exists** — The subtask has a tracked issue with acceptance criteria
+2. **File partition is clean** — No overlap with other active/parallel agents
+3. **Dependencies are met** — All prerequisite tasks are verified Done (not just claimed done)
+4. **Prompt is specific** — Contains: objective, file paths, acceptance criteria, patterns to follow
+5. **Lessons file referenced** — Prompt includes self-improvement reminder
+
+### Context Checks (before feature work)
+
+6. **Known issues reviewed** — known issues doc checked for blockers
+7. **Architecture docs read** — architecture and decision docs consulted
+8. **Existing code searched** — Confirmed no duplicate implementation exists
+
+### Safety Checks (before high-risk delegations)
+
+9. **Panel review planned** — Security, auth, DB migration, or architecture changes have panel review scheduled
+10. **Rollback path identified** — For DB migrations or data changes, rollback strategy is documented
+
+### Enforcement
+
+Before calling `runSubagent` or handing off to a background agent, mentally walk through checks 1-5. If any fail, fix the gap first. Checks 6-8 apply at feature start. Checks 9-10 apply only to high-risk work.
+
+## Cost Tracking Convention
+
+After completing a feature (all Linear issues Done), add a cost summary to the roadmap update:
+
+```markdown
+**Cost Summary:**
+| Metric | Value |
+|--------|-------|
+| Sub-agent delegations | X |
+| Background agent delegations | X |
+| Panel reviews | X |
+| Model tiers used | Premium: X, Standard: X, Utility: X, Economy: X |
+| Upgrades/downgrades | [reason if any] |
+| Est. total tokens | ~XXK |
+```
+
+This data helps optimize future model assignments. If no meaningful data was collected, skip the summary.
+
+During execution, maintain a running delegation log in the session checkpoint (see the **session-checkpoints** skill § Delegation Cost Log). Update it after each delegation completes or fails.
+
+## Context Source Tagging
+
+When collecting results from multiple sub-agents or background agents, **tag each result by its source** to prevent context confusion:
+
+```markdown
+### [Content Engineer] TAS-42 Schema
+- Created `schemas/review.ts` with star rating field
+- Deployed to Sanity Studio
+- Verification: lint ✅, type-check ✅
+
+### [DB Engineer] TAS-43 Migration
+- Created `supabase/migrations/20260227_add_reviews.sql`
+- RLS policies for authenticated users
+- Verification: migration applied ✅, tests ✅
+```
+
+**Rules:**
+- Prefix each agent's output summary with `### [Agent Name] TAS-XX Description`
+- Never merge outputs from different agents into a single undifferentiated block
+- When referencing prior agent output in a delegation prompt, cite the source: *"The Content Engineer created `schemas/review.ts` — follow that pattern"*
+- In the session checkpoint "Completed Work" table, always include the Agent column
+
+This prevents the Team Lead from confusing which agent produced what, especially after 5+ delegations when context is dense.
+
+## Dead Letter Queue Format
+
+Log to `.github/customizations/AGENT-FAILURES.md` when:
+- A delegated agent fails to complete its task after 2+ attempts
+- A background agent produces output that fails all verification gates
+- An agent encounters an unrecoverable error (e.g., MCP server down, tool unavailable)
+
+> **Note:** When a panel review BLOCKs 3 times, create a **dispute record** instead of a DLQ entry. See § Dispute Protocol below.
+
+### Failure Entry Format
+
+```markdown
+### DLQ-XXX: Short description
+
+| Field | Value |
+|-------|-------|
+| **Date** | YYYY-MM-DD |
+| **Agent** | Agent name |
+| **Linear Issue** | TAS-XX (if applicable) |
+| **Failure Type** | `verification-fail` / `tool-error` / `panel-block` / `timeout` / `scope-creep` |
+| **Attempts** | Number of attempts before logging |
+| **Est. Tokens Spent** | ~XXK across all attempts |
+| **Model Tier** | Economy / Utility / Standard / Premium |
+
+**Task:** What was the agent supposed to do?
+
+**Failure Details:** What went wrong? Include error messages, failed checks, or panel BLOCK reasons.
+
+**Root Cause:** Why did it fail? (if known)
+
+**Resolution:** How was it eventually resolved? (or "pending" if unresolved)
+```
+
+### Review Cadence
+
+At the start of each session, scan the agent failures doc for:
+- **Pending failures** that need retry
+- **Patterns** — same agent failing repeatedly may indicate a prompt or skill issue
+- **Tool issues** — MCP servers or external dependencies that need attention
+
+## Batch Review Strategy
+
+When multiple agents complete work simultaneously, **batch similar reviews together**:
+- Review all API/query changes in one session, then all UI changes in another
+- Context-switches less and you spot inconsistencies more easily
+
+## Error Recovery Playbook
+
+Common failure modes and how to recover:
+
+### Agent Stuck in Retry Loop
+
+**Symptom:** Agent retries the same failing command 3+ times without changing approach.
+**Recovery:** Intervene immediately. Read the error output, identify the root cause, and re-delegate with explicit fix instructions. Add a lesson to lessons learned.
+
+### MCP Tool Unavailable
+
+**Symptom:** Tool calls fail with connection or timeout errors.
+**Recovery:** (1) Check if the MCP server is running. (2) If transient, retry once. (3) If persistent, work around: use CLI tools as alternatives. Log to DLQ if critical.
+
+### Background Agent Produces Broken Output
+
+**Symptom:** Background agent returns, but files have lint/type/test errors.
+**Recovery:** (1) Review the diff to understand intent. (2) If fixable with small edits, fix inline. (3) If fundamentally wrong, discard the worktree changes and re-delegate with a more specific prompt. (4) Log to DLQ after 2 failed attempts.
+
+### Merge Conflict from Parallel Agents
+
+**Symptom:** Two background agents modified overlapping files.
+**Recovery:** (1) This should never happen if file partitioning was followed. (2) Accept one agent's changes first (the one with more complex work). (3) Re-delegate the simpler changes to adapt to the new state. (4) Add the conflict to your lessons learned.
+
+### Context Window Exhausted
+
+**Symptom:** Agent responses become confused, repetitive, or lose track of earlier instructions.
+**Recovery:** (1) Save a session checkpoint immediately. (2) End the current session. (3) Resume in a new session, loading the checkpoint. (4) Reduce parallel work in the next session.
+
+### Test Failures After Merge
+
+**Symptom:** Tests pass individually but fail when multiple agent outputs are merged.
+**Recovery:** (1) Run affected tests to identify which projects break. (2) Check for import conflicts, duplicate definitions, or state pollution. (3) Delegate fix to the agent whose changes are most likely the cause.
+
+## Dispute Protocol
+
+When automated resolution is exhausted (panel 3x BLOCK, approach conflicts, or criteria contradictions), create a **formal dispute record** in `.github/customizations/DISPUTES.md`. Inspired by the [Steroids CLI](https://github.com/UnlikeOtherAI/steroids-cli) dispute/escalation pattern.
+
+### When to Create a Dispute (vs. DLQ Entry)
+
+| Scenario | Action |
+|----------|--------|
+| Tool error, timeout, MCP failure | DLQ entry |
+| Scope creep | DLQ entry + redirect |
+| Agent fails 2+ times (simple) | DLQ entry |
+| Panel BLOCKs 3 times | **Dispute record** |
+| Agent and reviewer fundamentally disagree | **Dispute record** |
+| Acceptance criteria contradict each other | **Dispute record** |
+| Multiple valid approaches, agents can't converge | **Dispute record** |
+| Fix requires external/human action | **Dispute record** |
+
+### Dispute Creation Procedure
+
+1. **Number the dispute** — Increment from the last `DSP-XXX` ID in the Index table
+2. **Set priority** — Use the priority guidelines in DISPUTES.md (critical/high/medium/low)
+3. **Document both perspectives** — Agent's position AND reviewer's position with specific file/code references
+4. **Build attempt history** — List every fast review and panel attempt with one-line verdict summaries
+5. **Present resolution options** — At least 2 concrete options with rationale and risk for each
+6. **Recommend an action** — Which option the Team Lead thinks is best, with specific next steps
+7. **Link artifacts** — Panel reports, review logs, changed files, DLQ entries
+8. **Log to disputes.ndjson** — Append a machine-readable record (see logs README)
+9. **Update the Linear issue** — Add the dispute ID and link to the dispute record
+10. **Update the Index table** — Add the new dispute to the bottom of the Index
+
+### After Human Resolution
+
+When a human resolves a dispute:
+1. Update the dispute `Status` → `resolved` or `deferred`
+2. Record which option was chosen and any additional instructions
+3. If `resolved` → re-delegate the task with the human's decision as an explicit constraint
+4. If `deferred` → create a follow-up Linear issue and continue with other work
+5. Log the resolution in `disputes.ndjson` (update the existing record or append a resolution event)
+
+### Session Start: Check Disputes
+
+At the start of each session, after checking the DLQ, also check `DISPUTES.md` for:
+- **Pending disputes** that a human has resolved since the last session → act on the resolution
+- **Critical/high disputes** that are still pending → flag to the user before proceeding
+- **Patterns** — recurring disputes may indicate a skill gap, ambiguous instructions, or a need for a new validation gate
+
+## Background Agent Git Merge Strategy
+
+Background agents work in isolated Git worktrees. When merging their output:
+
+1. **Merge order matters:** Merge the most foundational changes first (DB migrations -> queries -> components -> pages -> tests -> docs)
+2. **Test after each merge:** Run affected tests after merging each agent's work
+3. **Resolve conflicts immediately:** Don't accumulate multiple agent outputs before merging
+4. **Discard stale worktrees:** If an agent's output is no longer compatible with the main branch (due to other agents' changes merging first), re-delegate rather than force-merge
+5. **Atomic merge preference:** Use `git merge --no-ff` to keep agent work traceable in history

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

@@ -0,0 +1,249 @@
+---
+name: teams-notifications
+description: "Microsoft Teams 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 Teams channels and chats."
+---
+
+# Teams Notifications
+
+Agent communication patterns via the Microsoft Teams MCP server (Microsoft Agent 365). Enables agents to post progress updates, request human approvals, and read responses — all through Teams channels and chats.
+
+## MCP Server
+
+| Field | Value |
+|-------|-------|
+| **URL** | `https://mcp.microsoft365.com/mcp` |
+| **Type** | Remote MCP server (HTTP) |
+| **Auth** | Microsoft Graph API — OAuth 2.0 with `McpServers.Teams.All` scope |
+| **Platform** | Microsoft Agent 365 (Frontier preview) |
+| **Status** | Preview — requires Microsoft Agent 365 Frontier preview access |
+
+### Prerequisites
+
+1. **Microsoft Agent 365 Frontier preview** enrollment
+2. **App registration** in Microsoft Entra ID (Azure AD)
+3. **Graph API permissions:** `McpServers.Teams.All` (delegated or application)
+4. **Admin consent** for the registered app
+
+> **Note:** The Teams MCP server is in preview and not yet generally available as a standalone endpoint. Features and availability may change.
+
+## Available MCP Tools
+
+The Teams MCP server exposes tools for:
+
+- **Chats** — Create, list, read, update, delete chats
+- **Messages** — Send, read, edit, delete messages in chats and channels
+- **Channels** — List, create, manage channel settings
+- **Members** — List, add, remove members from chats and channels
+- **Teams** — List teams, get team details, manage team settings
+
+Tool names follow the pattern `teams_<resource>_<action>`. 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:
+
+1. **Post approval request** to the channel with clear instructions:
+   ```
+   ⏳ **Approval Required**
+   Task: TAS-42 — Database migration adds `price_range` column
+   Action: Run migration on production database
+   
+   Reply with:
+   ✅ Approve — to proceed
+   ❌ Reject — to stop
+   Or reply with questions/comments
+   ```
+
+2. **Poll for response** — Read replies to determine the decision
+3. **Acknowledge** — Post confirmation of the action taken
+
+### Reading User Responses
+
+To check for approvals or instructions:
+
+1. Read message replies in the channel or chat thread
+2. Parse reply content for approval keywords (`approve`, `approved`, `yes`, `proceed`, `reject`, `no`, `stop`)
+3. Check for reactions on messages (Teams supports reactions via Graph API)
+
+### Parsing Conventions
+
+| Signal | Meaning |
+|--------|---------|
+| `✅` or "approve"/"yes" reply | Approved — proceed |
+| `❌` or "reject"/"no" reply | Rejected — stop and report |
+| `👀` reaction or "looking" reply | Acknowledged — user is reviewing |
+| Detailed reply | Instructions or questions for the agent |
+| `@mention` of agent | Direct command or question |
+
+## Channel & Chat 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 reply in threads** — use message replies, not top-level posts for follow-ups
+- **One thread per task** — keep all updates for a single task in one conversation thread
+- **Include task ID** — every message references the Linear/Jira issue ID
+- **Mark important messages** — use importance flags for approval requests
+
+### Chat vs Channel
+
+| Use Case | Preferred |
+|----------|-----------|
+| Team-wide updates | Channel |
+| Approval requests | Channel (for visibility) |
+| Direct questions | 1:1 or group chat |
+| Sensitive discussions | 1:1 chat |
+
+## Message Formatting
+
+Teams messages support HTML and a subset of Markdown:
+
+| Format | Syntax |
+|--------|--------|
+| Bold | `**bold**` or `<strong>bold</strong>` |
+| Italic | `*italic*` or `<em>italic</em>` |
+| Code | `` `inline code` `` |
+| Code block | ` ```code block``` ` |
+| Link | `[Display Text](https://example.com)` |
+| User mention | `<at>User Name</at>` (requires user ID in adaptive card) |
+| List | `- item` or `1. item` |
+| Heading | `### Heading` |
+
+### Adaptive Cards
+
+For richer formatting, Teams supports Adaptive Cards (JSON-based card format):
+
+```json
+{
+  "type": "AdaptiveCard",
+  "body": [
+    { "type": "TextBlock", "text": "Approval Required", "weight": "Bolder", "size": "Medium" },
+    { "type": "TextBlock", "text": "Task: TAS-42 — Database migration", "wrap": true }
+  ],
+  "actions": [
+    { "type": "Action.Submit", "title": "Approve", "data": { "action": "approve" } },
+    { "type": "Action.Submit", "title": "Reject", "data": { "action": "reject" } }
+  ],
+  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
+  "version": "1.4"
+}
+```
+
+Use Adaptive Cards for approval workflows when available — they provide structured input.
+
+## Rate Limits
+
+Microsoft Graph API rate limits for Teams:
+
+| Resource | Limit |
+|----------|-------|
+| Messages (per app per tenant) | 50 per second |
+| Channel messages | 50 per second |
+| Chat creation | 50 per second |
+| Individual API calls | 10,000 per 10 minutes |
+
+**Best practices:**
+- Batch updates into single messages rather than posting many small messages
+- Use threads to consolidate related updates
+- Cache team/channel/user IDs — don't look them up repeatedly
+- Respect 429 (Too Many Requests) responses with retry-after headers
+
+## Security Considerations
+
+- **OAuth tokens** are managed by the MCP server — agents never see raw tokens
+- **Scope minimization** — request only the Graph API permissions agents actually need
+- **Tenant restrictions** — configure the app for single-tenant or specific tenant access
+- **Conditional Access** — Microsoft Entra Conditional Access policies apply to API calls
+- **Audit logging** — Microsoft 365 audit logs capture all Graph API activity
+- **No secrets in messages** — never post tokens, passwords, or credentials in Teams messages (per Constitution #1)
+- **Data residency** — Teams data is stored in the tenant's Microsoft 365 region
+
+## 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.
+```
+
+## Preview Limitations
+
+Since the Teams MCP server is in Frontier preview:
+
+- **Availability** may change without notice
+- **Tool surface** may be incomplete compared to the full Graph API
+- **Performance** may vary during preview
+- **Breaking changes** are possible between preview versions
+
+Check [Microsoft Agent 365 documentation](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/) for the latest status.