From 5c74c4376d47f45f3648b406a7907bd6e39e5da3 Mon Sep 17 00:00:00 2001 From: hopeatina Date: Fri, 3 Apr 2026 06:53:21 -0500 Subject: [PATCH] Refresh skills for current OrgX MCP workflows --- .github/workflows/skill-integrity.yml | 18 +++ README.md | 10 ++ bulk-create/SKILL.md | 135 +++++------------ bulk-create/instructions.md | 115 +++----------- bulk-create/skill.toml | 6 +- design-agent/SKILL.md | 48 ++++-- design-agent/skill.toml | 4 +- engineering-agent/SKILL.md | 58 ++++--- engineering-agent/skill.toml | 2 +- initiative-kickoff/SKILL.md | 147 ++++++------------ initiative-kickoff/instructions.md | 131 +++------------- initiative-kickoff/skill.toml | 6 +- initiative-protocol/SKILL.md | 57 ++++--- initiative-protocol/skill.toml | 6 +- marketing-agent/SKILL.md | 52 +++++-- marketing-agent/skill.toml | 2 +- milestone-protocol/SKILL.md | 48 +++--- milestone-protocol/skill.toml | 6 +- morning-briefing/SKILL.md | 100 ++++-------- morning-briefing/instructions.md | 67 +++----- morning-briefing/skill.toml | 6 +- nightly-recap/SKILL.md | 68 ++++----- nightly-recap/skill.toml | 6 +- operations-agent/SKILL.md | 52 +++++-- operations-agent/skill.toml | 2 +- orchestrator-agent/SKILL.md | 63 +++++--- orchestrator-agent/skill.toml | 2 +- product-agent/SKILL.md | 55 ++++--- product-agent/skill.toml | 2 +- sales-agent/SKILL.md | 53 +++++-- sales-agent/skill.toml | 4 +- scripts/check_skill_tool_drift.py | 210 ++++++++++++++++++++++++++ task-protocol/SKILL.md | 56 ++++--- task-protocol/skill.toml | 6 +- workstream-protocol/SKILL.md | 47 +++--- workstream-protocol/skill.toml | 6 +- 36 files changed, 864 insertions(+), 792 deletions(-) create mode 100644 .github/workflows/skill-integrity.yml create mode 100644 scripts/check_skill_tool_drift.py diff --git a/.github/workflows/skill-integrity.yml b/.github/workflows/skill-integrity.yml new file mode 100644 index 0000000..81b1872 --- /dev/null +++ b/.github/workflows/skill-integrity.yml @@ -0,0 +1,18 @@ +name: Skill Integrity + +on: + pull_request: + push: + branches: + - main + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.11" + - name: Check OrgX skill tool drift + run: python3 scripts/check_skill_tool_drift.py diff --git a/README.md b/README.md index 55495e2..da28a62 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,16 @@ These skills require the [OrgX MCP server](https://mcp.useorgx.com) to be config } ``` +## Verification + +Run the repo-level drift check before opening a PR or shipping skill changes: + +```bash +python3 scripts/check_skill_tool_drift.py +``` + +The check fails on deprecated OrgX tool names, unknown `mcp__orgx__*` references, and high-value workflow gaps such as spawning without `check_spawn_guard` or opening plan sessions without `complete_plan`. + ## Skill Format Each skill follows [Anthropic's skill format](https://github.com/anthropics/skills): diff --git a/bulk-create/SKILL.md b/bulk-create/SKILL.md index 7b01f91..747cded 100644 --- a/bulk-create/SKILL.md +++ b/bulk-create/SKILL.md @@ -1,126 +1,63 @@ --- name: Bulk Create description: | - Create multiple OrgX tasks or milestones from a markdown checklist or bullet list. - Automatically detects priorities from keywords and sets up dependencies for nested items. - Use when: importing a task list, creating multiple items at once, converting notes to tasks, - or batch-creating entities from any list format. - Triggers on: "bulk create", "create tasks from list", "import checklist", "batch create". - Supports: checkbox lists (- [ ]), bullet lists (- or *), numbered lists (1.). + Create multiple OrgX tasks or milestones from a markdown checklist or bullet + list. Uses batch creation, ref-based dependency wiring, and current workspace + context instead of one-off entity creation loops. --- # Bulk Create -Parse markdown lists and create multiple OrgX entities in batch. +Parse markdown lists and create multiple OrgX entities in one pass. ## Supported Formats -```markdown -# Checkbox lists +- checkbox lists: `- [ ] item` +- bullet lists: `- item` or `* item` +- numbered lists: `1. item` -- [ ] Task one -- [ ] Task two (urgent) -- [x] Already done (skipped) - -# Bullet lists - -- Task one -- Task two - - Subtask (creates dependency) - -# Numbered lists - -1. First task -2. Second task (high priority) - -# Mixed priorities - -- [CRITICAL] Fix security issue -- [P0] Launch blocker -- Task with (urgent) keyword -- (low priority) Nice to have -``` +Completed checkbox items are skipped by default. ## Workflow -1. **Parse input** to extract items: - - - Title: main text content - - Priority: detected from keywords - - Parent: if nested under another item - - Checked: skip if already checked [x] - -2. **Confirm scope** with user: - - - Entity type: task (default) or milestone - - Parent initiative/workstream/milestone - - Default priority if not detected - -3. **Check context** using `mcp__orgx__list_entities` - - - Verify parent entities exist - - Avoid duplicates - -4. **Create entities** using `mcp__orgx__create_entity` - - - Process in order (parents before children) - - Capture IDs for dependency setup - -5. **Set dependencies** using `mcp__orgx__update_entity` - - Nested items blocked by their parent - - Sequential items can be linked if requested +1. Bootstrap with `mcp__orgx__orgx_bootstrap`. +2. Confirm or set workspace via `mcp__orgx__workspace`. +3. Parse the list into ordered items with priority, nesting, and completion state. +4. Check the parent initiative, milestone, or workstream with `mcp__orgx__list_entities`. +5. Build a single `mcp__orgx__batch_create_entities` payload: + - use `ref` keys for each created item + - use `depends_on` for nested or sequential dependencies + - prefer `type=task` unless the user explicitly wants milestones +6. If a few standalone items are being added to an existing hierarchy, `mcp__orgx__create_task` or `mcp__orgx__create_milestone` is acceptable, but batch create is preferred. ## Priority Detection -| Keywords | Priority | -| --------------------------------------------------- | -------- | -| urgent, critical, ASAP, P0, blocker, [CRITICAL] | high | -| important, P1, high priority | high | -| normal, P2, medium priority | medium | -| low priority, P3, nice to have, backlog, eventually | low | - -Default: medium (if no keywords detected) +| Keywords | Priority | +| --- | --- | +| urgent, critical, ASAP, P0, blocker | high | +| important, P1, high priority | high | +| normal, P2, medium priority | medium | +| low priority, P3, backlog, nice to have | low | -## Output Format +Default priority is `medium`. -``` -✅ Bulk Create Complete +## Dependency Logic -| # | Title | Priority | ID | Blocked By | -|---|-------|----------|----|-----------| -| 1 | Task one | high | task_xxx | - | -| 2 | Task two | medium | task_yyy | - | -| 3 | Subtask | medium | task_zzz | task_yyy | +- Nested items depend on their nearest parent item. +- Sequential mode is optional; only apply it when the user asks for ordered execution. +- Prefer `depends_on` in the batch payload over patching dependencies after creation. -📊 Summary: - - Created: X entities - - Dependencies: Y set - - Skipped: Z (already checked or errors) +## Output Format -❌ Errors (if any): - - "Item text": [error message] ``` +Bulk create complete -## Dependency Logic +Created: +- [id] [title] ([priority]) -``` -- Parent task - - Child task 1 → blockedBy: [parent] - - Child task 2 → blockedBy: [parent] - - Grandchild → blockedBy: [child 2] -``` - -For sequential mode (optional): +Skipped: +- [title] — already complete +Errors: +- [title] — [reason] ``` -1. First → blockedBy: [] -2. Second → blockedBy: [first] -3. Third → blockedBy: [second] -``` - -## Error Handling - -- Continue on individual failures -- Report all errors at end -- Never fail entire batch for one item -- Rollback not supported (items remain if created) diff --git a/bulk-create/instructions.md b/bulk-create/instructions.md index cafddca..e3634c3 100644 --- a/bulk-create/instructions.md +++ b/bulk-create/instructions.md @@ -1,104 +1,23 @@ -You are bulk-creating tasks or milestones from a markdown checklist or bullet list. +You are bulk-creating OrgX tasks or milestones from a markdown list. -## Input Parsing +## Required Sequence -Parse the user's input to extract items from: +1. Call `mcp__orgx__orgx_bootstrap`. +2. Resolve the active workspace with `mcp__orgx__workspace`. +3. Parse the list items, skipping checked-off items unless the user explicitly wants them imported. +4. Resolve the parent initiative/workstream/milestone with `mcp__orgx__list_entities`. +5. Build one `mcp__orgx__batch_create_entities` payload using: + - `ref` for each created item + - `depends_on` for nested or sequential relationships +6. Only fall back to repeated `create_task` / `create_milestone` calls if batching is impossible. -1. **Checkbox lists**: `- [ ] Item title` or `- [x] Item title` (completed) -2. **Bullet lists**: `- Item title` or `* Item title` -3. **Numbered lists**: `1. Item title` +## Parsing Rules -For each item, extract: +- preserve item order +- infer priority from title and description +- carry nested text into the item description +- do not invent parent entities -- **Title**: The main text of the item -- **Description**: Any sub-bullets or indented text under the item -- **Priority**: Detect from keywords in the title or description +## Output -## Priority Detection - -Scan for priority keywords (case-insensitive): - -- **high**: "urgent", "critical", "asap", "important", "high priority", "p0", "p1" -- **medium**: "medium priority", "p2", "normal" -- **low**: "low priority", "p3", "nice to have", "backlog" - -Default to "medium" if no keywords found. - -## Nested Items and Dependencies - -If items are nested (indented under a parent): - -``` -- [ ] Parent task - - [ ] Child task 1 - - [ ] Child task 2 -``` - -1. Create the parent entity first -2. Create child entities with `blockedBy` set to parent's ID -3. Use `mcp__orgx__update_entity` to set dependencies after creation - -## Entity Creation Process - -1. **Confirm scope**: Ask the user which entity type to create: - - - `task` (default) - - `milestone` - -2. **Check context**: Use `mcp__orgx__list_entities` to verify: - - - Active initiative (if creating tasks under an initiative) - - Active workspace context - -3. **Create entities**: For each parsed item, call `mcp__orgx__create_entity` with: - - ``` - type: "task" or "milestone" - title: - description: - priority: - initiative_id: - ``` - -4. **Set dependencies**: For nested items, use `mcp__orgx__update_entity` to set `blockedBy` relationships - -## Output Format - -After creation, report a summary: - -``` -Created X entities: - -| ID | Title | Priority | Dependencies | -|----|-------|----------|--------------| -| abc123 | Task title | high | - | -| def456 | Child task | medium | blocked by abc123 | - -All entities created successfully under initiative: [initiative name] -``` - -## Error Handling - -- If an entity fails to create, continue with remaining items -- Report failures at the end with the specific error -- Suggest fixes for common issues (missing initiative, invalid priority) - -## Example Workflow - -User provides: - -``` -- [ ] URGENT: Set up CI pipeline - - [ ] Configure GitHub Actions - - [ ] Add test coverage reporting -- [ ] Update documentation -- [ ] Nice to have: Add dark mode support -``` - -You should: - -1. Parse 4 items (1 parent with 2 children, 2 standalone) -2. Detect priorities: high, medium, medium, low -3. Create parent task first, then children with dependencies -4. Create remaining standalone tasks -5. Report all created entities with IDs +Report the created IDs, skipped items, and any per-item failures. diff --git a/bulk-create/skill.toml b/bulk-create/skill.toml index b5a2c2a..e80b5af 100644 --- a/bulk-create/skill.toml +++ b/bulk-create/skill.toml @@ -1,7 +1,7 @@ name = "bulk-create" -version = "1.0.0" -description = "Create multiple tasks or milestones from a markdown checklist or bullet list" +version = "2.0.0" +description = "Create multiple tasks or milestones from a markdown checklist or bullet list using batch creation and ref-based dependency wiring" entry_instructions = "instructions.md" -required_tools = ["mcp__orgx__create_entity", "mcp__orgx__list_entities", "mcp__orgx__update_entity"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__list_entities", "mcp__orgx__batch_create_entities", "mcp__orgx__create_task", "mcp__orgx__create_milestone"] required_scopes = [] resources = [] diff --git a/design-agent/SKILL.md b/design-agent/SKILL.md index 9f45734..1332596 100644 --- a/design-agent/SKILL.md +++ b/design-agent/SKILL.md @@ -9,14 +9,17 @@ description: | ## 1. Quick Start -1. Confirm the artifact or decision type and the target audience. -2. Pull OrgX context with `mcp__orgx__list_entities` and `mcp__orgx__query_org_memory`. -3. Identify the **context signal** (see Context Adaptation Protocol) and adjust depth accordingly. -4. Produce the artifact using the contract below and return: +1. Run `mcp__orgx__orgx_bootstrap`, then resolve workspace scope with `mcp__orgx__workspace`. +2. Confirm the artifact or decision type and the target audience. If the request is task-bound, hydrate it with `mcp__orgx__get_task_with_context`; otherwise map neighboring work with `mcp__orgx__list_entities`. +3. Pull prior design precedent with `mcp__orgx__query_org_memory` and `mcp__orgx__get_relevant_learnings`. +4. For interaction specs, breakpoint plans, or design-system migrations, use the planning loop: `mcp__orgx__start_plan_session`, `mcp__orgx__improve_plan`, `mcp__orgx__record_plan_edit`, then `mcp__orgx__complete_plan`. +5. Identify the **context signal** (see Context Adaptation Protocol) and adjust depth accordingly. +6. Produce the artifact using the contract below and return: - A concise summary (3-6 bullets) - The artifact body (JSON or structured Markdown) - 3 actionable next steps with owners and effort estimates -5. Run the precision loop before delivery. Every artifact ships validator-clean. +7. Run the precision loop before delivery. Every artifact ships validator-clean. +8. Attach the result back to the active entity with `mcp__orgx__entity_action` (`action=attach`) or `mcp__orgx__comment_on_entity`, then record quality with `mcp__orgx__record_quality_score`. Deliver design artifacts that are implementation-ready, accessibility-compliant, and validator-clean. @@ -115,23 +118,31 @@ If inputs are incomplete, declare assumptions explicitly at the top of the artif ## 6. Operating Workflow -1. **Scope**: Confirm the artifact type and audience. Identify the context signal from the table above. -2. **Gather evidence**: +1. **Bootstrap**: Run `mcp__orgx__orgx_bootstrap` and resolve workspace with `mcp__orgx__workspace`. +2. **Scope**: Confirm the artifact type and audience. If task-bound, load `mcp__orgx__get_task_with_context`. Identify the context signal from the table above. +3. **Gather evidence**: - Query existing OrgX artifacts with `mcp__orgx__list_entities` - Pull prior standards and decisions with `mcp__orgx__query_org_memory` + - Pull prior learnings with `mcp__orgx__get_relevant_learnings` - Pull Figma context with `mcp__figma__*` when available - Review related artifacts from Engineering and Product agents for constraints -3. **Draft**: Produce the artifact directly in JSON (preferred) or Markdown with a fenced JSON block. -4. **Self-review**: Run the Precision Loop (Section 12) against the draft. -5. **Validate**: +4. **Plan when needed**: For interaction flows, token migrations, or breakpoint programs, open a plan session with `mcp__orgx__start_plan_session`, refine with `mcp__orgx__improve_plan`, and record major revisions with `mcp__orgx__record_plan_edit`. +5. **Draft**: Produce the artifact directly in JSON (preferred) or Markdown with a fenced JSON block. +6. **Self-review**: Run the Precision Loop (Section 12) against the draft. +7. **Validate**: ```bash python3 scripts/validate_design.py --type ``` -6. **Fix and re-validate**: Resolve every failed gate. Re-run validator until all gates pass. -7. **Publish**: Save with `mcp__orgx__create_entity` and link related entities. -8. **Handoff**: Notify downstream agents per the Cross-Agent Handoff Contracts. +8. **Fix and re-validate**: Resolve every failed gate. Re-run validator until all gates pass. +9. **Publish**: Save with `mcp__orgx__create_entity` and link related entities. +10. **Attach proof**: + - `mcp__orgx__complete_plan` with `attach_to` for planning sessions + - `mcp__orgx__entity_action` with `action=attach` for audits, token packages, and component docs + - `mcp__orgx__comment_on_entity` for design review feedback +11. **Record learnings and quality**: Submit learnings with `mcp__orgx__submit_learning` and record quality with `mcp__orgx__record_quality_score`. +12. **Handoff**: Before delegating downstream work, run `mcp__orgx__check_spawn_guard`, then notify or spawn downstream agents per the Cross-Agent Handoff Contracts. ## 7. Artifact Contracts @@ -771,11 +782,22 @@ Apply relevant prior learnings. Reference them explicitly (e.g., "Per learning L ### Primary: +- `mcp__orgx__orgx_bootstrap` — initialize OrgX session scope and recommended workflow +- `mcp__orgx__workspace` — resolve workspace scope before review or publication +- `mcp__orgx__get_task_with_context` — hydrate task-bound context, attachments, and plan sessions - `mcp__orgx__list_entities` — Query existing design artifacts and related work - `mcp__orgx__query_org_memory` — Pull prior design decisions and learnings +- `mcp__orgx__get_relevant_learnings` — retrieve design-specific learnings before drafting +- `mcp__orgx__start_plan_session` — open tracked design planning sessions +- `mcp__orgx__improve_plan` — refine interaction or system plans +- `mcp__orgx__record_plan_edit` — capture major planning revisions +- `mcp__orgx__complete_plan` — persist and attach finalized design plans - `mcp__orgx__create_entity` — Publish completed artifacts +- `mcp__orgx__entity_action` — attach evidence and update entity state - `mcp__orgx__submit_learning` — Record design learnings for the flywheel - `mcp__orgx__comment_on_entity` — Add design review comments to engineering work +- `mcp__orgx__record_quality_score` — score artifact quality for calibration +- `mcp__orgx__check_spawn_guard` — verify delegation is allowed before spawning follow-on work ### Optional (when configured): diff --git a/design-agent/skill.toml b/design-agent/skill.toml index 000a051..bfd7ec4 100644 --- a/design-agent/skill.toml +++ b/design-agent/skill.toml @@ -1,7 +1,7 @@ name = "design-agent" -version = "1.0.0" +version = "2.0.0" description = "Produce high-confidence design artifacts for OrgX: WCAG accessibility audits, design token packages, and component documentation. Use when work requires design-system decisions, accessibility validation, or design-to-engineering handoff quality gates." entry_instructions = "SKILL.md" -required_tools = ["mcp__orgx__create_entity", "mcp__orgx__list_entities", "mcp__orgx__query_org_memory"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__get_task_with_context", "mcp__orgx__list_entities", "mcp__orgx__query_org_memory", "mcp__orgx__get_relevant_learnings", "mcp__orgx__start_plan_session", "mcp__orgx__improve_plan", "mcp__orgx__record_plan_edit", "mcp__orgx__complete_plan", "mcp__orgx__create_entity", "mcp__orgx__entity_action", "mcp__orgx__submit_learning", "mcp__orgx__comment_on_entity", "mcp__orgx__record_quality_score", "mcp__orgx__check_spawn_guard"] required_scopes = [] resources = [] diff --git a/engineering-agent/SKILL.md b/engineering-agent/SKILL.md index 36e3c9f..7e2319a 100644 --- a/engineering-agent/SKILL.md +++ b/engineering-agent/SKILL.md @@ -11,15 +11,17 @@ description: | ## Quick Start -1. Confirm the artifact or decision type and the target audience. -2. Pull OrgX context with `mcp__orgx__list_entities` and `mcp__orgx__query_org_memory`. +1. Run `mcp__orgx__orgx_bootstrap`, then resolve workspace scope with `mcp__orgx__workspace`. +2. Confirm the artifact or decision type and the target audience. If the request comes from a task, load it with `mcp__orgx__get_task_with_context`; otherwise map related work with `mcp__orgx__list_entities`. 3. Retrieve relevant learnings with `mcp__orgx__get_relevant_learnings` and prior decisions with `mcp__orgx__query_org_memory` scoped to decisions. -4. Assess the org context (stage, team topology, reliability maturity) and adapt formality accordingly. -5. Produce the artifact using the contract below and return: +4. For RFCs, migration playbooks, or other plan-shaped outputs, run a planning loop with `mcp__orgx__start_plan_session`, `mcp__orgx__improve_plan`, `mcp__orgx__record_plan_edit`, and `mcp__orgx__complete_plan`. +5. Assess the org context (stage, team topology, reliability maturity) and adapt formality accordingly. +6. Produce the artifact using the contract below and return: - A concise summary (3-6 bullets) - The artifact body (JSON or structured Markdown) - 3 actionable next steps -6. Submit learnings with `mcp__orgx__submit_learning` and score the artifact with `mcp__orgx__record_quality_score`. +7. Attach the output back to the active work item with `mcp__orgx__entity_action` (`action=attach`) or `mcp__orgx__comment_on_entity`, then submit learnings with `mcp__orgx__submit_learning` and score the artifact with `mcp__orgx__record_quality_score`. +8. Before delegating implementation or investigation, run `mcp__orgx__check_spawn_guard` and only then use `mcp__orgx__spawn_agent_task`. Deliver technically rigorous artifacts that are evidence-based and execution-ready. @@ -171,29 +173,39 @@ Declare assumptions explicitly if data is missing. Never fabricate metrics or in ## Operating Workflow -1. Select `artifact_type` and identify the target decision or deliverable. -2. Assess org context using the Context Adaptation Protocol. -3. Retrieve learnings and precedent: +1. Run `mcp__orgx__orgx_bootstrap` and resolve workspace with `mcp__orgx__workspace`. +2. Select `artifact_type` and identify the target decision or deliverable. +3. Hydrate the active task or parent entity: + - `mcp__orgx__get_task_with_context` for task-bound work + - `mcp__orgx__list_entities` for neighboring initiatives, milestones, and prior artifacts +4. Assess org context using the Context Adaptation Protocol. +5. Retrieve learnings and precedent: - `mcp__orgx__get_relevant_learnings` for engineering domain insights - `mcp__orgx__query_org_memory` with `scope: "decisions"` for related architecture decisions - `mcp__orgx__query_org_memory` for organizational precedent -4. Gather evidence: +6. Gather evidence: - `mcp__github__*` for code, PR, and repository evidence - `mcp__grafana__*` and `mcp__loki__*` for runtime telemetry - `mcp__orgx__list_entities` for related work items and initiatives -5. Apply learnings as constraints or confidence adjustments on the draft. -6. Draft artifact in JSON (or Markdown with fenced JSON) following the artifact contract. -7. Run the Precision Loop (all 5 passes). -8. Validate: +7. For architecture or migration planning, open a plan session with `mcp__orgx__start_plan_session`, refine with `mcp__orgx__improve_plan`, and record any material revision with `mcp__orgx__record_plan_edit`. +8. Apply learnings as constraints or confidence adjustments on the draft. +9. Draft artifact in JSON (or Markdown with fenced JSON) following the artifact contract. +10. Run the Precision Loop (all 5 passes). +11. Validate: ```bash python3 scripts/validate_engineering.py --type ``` -9. Fix all failed gates. -10. Publish with `mcp__orgx__create_entity`. -11. Submit learnings: `mcp__orgx__submit_learning` with outcome-linked insight. -12. Score the artifact: `mcp__orgx__record_quality_score`. +12. Fix all failed gates. +13. Publish with `mcp__orgx__create_entity`. +14. Attach proof or conclusions back to the active entity: + - `mcp__orgx__complete_plan` with `attach_to` for plan sessions + - `mcp__orgx__entity_action` with `action=attach` for RFCs, reviews, and runbooks + - `mcp__orgx__comment_on_entity` for review findings or architectural guidance +15. Submit learnings: `mcp__orgx__submit_learning` with outcome-linked insight. +16. Score the artifact: `mcp__orgx__record_quality_score`. +17. Before spawning follow-on work, run `mcp__orgx__check_spawn_guard`, then delegate with `mcp__orgx__spawn_agent_task`. ## Artifact Contracts @@ -465,11 +477,21 @@ Run the validator script and confirm zero errors. Verify that recommendation lan Primary: +- `mcp__orgx__orgx_bootstrap` — initialize the OrgX session and recommended workflow +- `mcp__orgx__workspace` — resolve the active workspace before reading or writing +- `mcp__orgx__get_task_with_context` — hydrate task-bound context, attachments, and plan sessions - `mcp__orgx__query_org_memory` — organizational precedent and context - `mcp__orgx__list_entities` — related work items and initiatives +- `mcp__orgx__start_plan_session` — open tracked planning sessions for RFCs and migrations +- `mcp__orgx__improve_plan` — refine architecture and rollout plans +- `mcp__orgx__record_plan_edit` — capture meaningful planning revisions +- `mcp__orgx__complete_plan` — persist the final plan and attach it to entities - `mcp__orgx__create_entity` — publish completed artifacts +- `mcp__orgx__entity_action` — attach evidence and update entity state +- `mcp__orgx__comment_on_entity` — write review or implementation notes onto the active entity +- `mcp__orgx__check_spawn_guard` — verify delegation is allowed before spawning execution +- `mcp__orgx__spawn_agent_task` — hand off implementation or investigation work - `mcp__orgx__get_relevant_learnings` — domain-specific insights from previous work -- `mcp__orgx__query_org_memory` — prior architecture decisions and organizational precedent - `mcp__orgx__submit_learning` — contribute learnings back to the flywheel - `mcp__orgx__record_quality_score` — score artifact quality for continuous improvement diff --git a/engineering-agent/skill.toml b/engineering-agent/skill.toml index b77df3f..b84e924 100644 --- a/engineering-agent/skill.toml +++ b/engineering-agent/skill.toml @@ -2,6 +2,6 @@ name = "engineering-agent" version = "2.0.0" description = "Produce high-confidence engineering artifacts for OrgX: RFCs, ADRs, code reviews, postmortems, tech debt inventories, capacity plans, runbooks, migration playbooks, dependency audits, and performance budgets. Use when technical decisions, implementation risk, reliability analysis, or engineering quality gates are required." entry_instructions = "SKILL.md" -required_tools = ["mcp__orgx__create_entity", "mcp__orgx__list_entities", "mcp__orgx__query_org_memory", "mcp__orgx__get_relevant_learnings", "mcp__orgx__submit_learning", "mcp__orgx__record_quality_score"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__get_task_with_context", "mcp__orgx__query_org_memory", "mcp__orgx__list_entities", "mcp__orgx__start_plan_session", "mcp__orgx__improve_plan", "mcp__orgx__record_plan_edit", "mcp__orgx__complete_plan", "mcp__orgx__create_entity", "mcp__orgx__entity_action", "mcp__orgx__comment_on_entity", "mcp__orgx__check_spawn_guard", "mcp__orgx__spawn_agent_task", "mcp__orgx__get_relevant_learnings", "mcp__orgx__submit_learning", "mcp__orgx__record_quality_score"] required_scopes = [] resources = [] diff --git a/initiative-kickoff/SKILL.md b/initiative-kickoff/SKILL.md index 16190a2..6adcd69 100644 --- a/initiative-kickoff/SKILL.md +++ b/initiative-kickoff/SKILL.md @@ -1,127 +1,74 @@ --- name: Initiative Kickoff description: | - Create a complete OrgX initiative from a one-line goal, with milestones, workstreams, tasks, and agent assignments. - Use when the user wants to: start a new project, create an initiative, kick off work on a goal, - set up a project structure, or bootstrap a new effort. - Triggers on: "kickoff", "new initiative", "start project", "create initiative for", "set up [goal]". - NOT for: updating existing initiatives, simple task creation, or research questions. + Create a complete OrgX initiative from a one-line goal, using the current + workspace, hierarchy scaffolding tools, and guarded agent delegation. + Use when the user wants to start a new project, create an initiative, kick + off work on a goal, set up a project structure, or bootstrap a new effort. --- # Initiative Kickoff -Transform a goal into a structured OrgX initiative with milestones, workstreams, and initial tasks. +Transform a goal into a structured OrgX initiative with milestones, workstreams, starter tasks, and optional agent delegation. ## Quick Start -1. Confirm the goal, scope, and any timeline hints. -2. Check for existing initiatives to avoid duplicates. -3. Create the initiative, milestones, workstreams, and starter tasks. -4. Launch the initiative if the user asks to start execution immediately. +1. Bootstrap the session with `mcp__orgx__orgx_bootstrap`. +2. Confirm or set the target workspace with `mcp__orgx__workspace`. +3. Check for duplicate or overlapping initiatives. +4. Prefer `mcp__orgx__scaffold_initiative` for the full hierarchy. +5. Launch only if the user wants execution to start now. ## Workflow -1. **Parse the goal** to extract: +1. Parse the goal: + - target outcome + - likely domains + - timeline hints + - success indicators +2. Check context: + - `mcp__orgx__list_entities type=initiative` + - `mcp__orgx__query_org_memory` for similar efforts or prior decisions +3. Create the full hierarchy with `mcp__orgx__scaffold_initiative`. +4. If the user requests specific agent delegation: + - call `mcp__orgx__check_spawn_guard` + - then `mcp__orgx__spawn_agent_task` +5. Launch with `mcp__orgx__entity_action type=initiative action=launch` when the initiative should go live immediately. +6. Finish with `mcp__orgx__recommend_next_action` so the user knows the first move after kickoff. + +## Default Structure + +- 3-5 milestones +- 2-6 workstreams depending on domain spread +- 2-4 starter tasks per workstream +- an orchestrator-owned coordination path when more than two domains are involved - - Core objective (what success looks like) - - Domain signals (engineering, product, marketing, etc.) - - Timeline hints (if mentioned) - - Success indicators - -2. **Check context** using `mcp__orgx__list_entities` - - - Verify no duplicate initiative exists - - Check for related initiatives to link - -3. **Create initiative** using `mcp__orgx__create_entity` - - ```json - { - "type": "initiative", - "title": "[Derived from goal]", - "description": "[Expanded goal with context]", - "priority": "high" - } - ``` - -4. **Create 3-5 milestones** following this pattern: - - - M1: Discovery/Planning (10-15% of timeline) - - M2: Foundation/Setup (15-20%) - - M3: Core Development (40-50%) - - M4: Integration/Testing (15-20%) - - M5: Launch/Delivery (10-15%) - -5. **Create workstreams** by detected domains: - - - Engineering: technical implementation - - Product: requirements, specs, prioritization - - Marketing: positioning, launch prep - - Sales: enablement, outreach prep - - Operations: processes, tooling - - Design: UX/UI, visual assets - -6. **Create 2-4 initial tasks per workstream**: - - | Domain | Starter Tasks | - | ----------- | --------------------------------------------- | - | Engineering | Tech spike, architecture doc, dev environment | - | Product | PRD draft, user stories, acceptance criteria | - | Marketing | Messaging brief, positioning doc | - | Sales | ICP definition, battlecard draft | - | Operations | Process mapping, tool evaluation | - | Design | Design brief, wireframes, style exploration | - -7. **Assign agents** (if requested) using `mcp__orgx__spawn_agent_task` +## Timeline Inference -8. **Launch initiative** (if requested) using `mcp__orgx__launch_entity` +- 1 domain: 2 weeks +- 2-3 domains: 4-6 weeks +- 4+ domains: 8-12 weeks ## Output Format ``` -✅ Initiative Created: [title] (ID: init_xxx) - -📍 Milestones (X created): - M1: [title] - Due: [date] (ID: ms_xxx) - M2: [title] - Due: [date] (ID: ms_xxx) - ... +Initiative created: [title] ([id]) -🔀 Workstreams (X created): - - [domain]: [X tasks] (ID: ws_xxx) - ... +Milestones: +- [milestone title] — [due date] -📋 Tasks Created: X total +Workstreams: +- [domain] — [task count] starter tasks -🤖 Agents Assigned: [list or "none - use /delegate to assign"] +Delegation: +- [agent assignment summary or "none"] -🔗 Next Steps: - 1. Review milestones and adjust dates - 2. Add specific tasks to workstreams - 3. Assign agents with: delegate-task [task_id] to [agent] +Next action: +- [single highest-leverage next step] ``` -## Timeline Inference - -If no timeline specified: - -- Small initiative (1 domain): 2 weeks -- Medium initiative (2-3 domains): 4-6 weeks -- Large initiative (4+ domains): 8-12 weeks - -Set milestone due dates proportionally. - -## Domain Detection - -Detect domains from goal keywords: - -- "build", "implement", "code", "API" → engineering -- "launch", "campaign", "content" → marketing -- "sell", "pipeline", "deal" → sales -- "design", "UI", "UX" → design -- "process", "workflow", "automate" → operations -- "spec", "requirements", "feature" → product - ## Failure Handling -- If a similar initiative exists, pause and ask whether to update or create a new one. -- If required OrgX tools are unavailable, explain what is missing and stop rather than guessing. +- If a similar initiative exists, stop and ask whether to extend it or create a new one. +- If the workspace is unset, resolve it before scaffolding anything. +- If spawn guard blocks delegation, create the initiative anyway and report the block explicitly. diff --git a/initiative-kickoff/instructions.md b/initiative-kickoff/instructions.md index acfef48..debc94f 100644 --- a/initiative-kickoff/instructions.md +++ b/initiative-kickoff/instructions.md @@ -1,116 +1,31 @@ -You are launching a new initiative from a single goal statement. +You are creating a new OrgX initiative from a single goal statement. -## Quick Start +## Required Sequence -1. Confirm the goal, scope, and any timeline hints. -2. Check for existing initiatives to avoid duplicates. -3. Create the initiative, milestones, workstreams, and starter tasks. -4. Launch the initiative if the user wants execution to start immediately. +1. Call `mcp__orgx__orgx_bootstrap`. +2. Call `mcp__orgx__workspace action=get`. +3. If no workspace is active, call `mcp__orgx__workspace action=list`, pick the default (or ask the user if the choice is ambiguous), then call `mcp__orgx__workspace action=set`. +4. Check for overlapping initiatives with: + - `mcp__orgx__list_entities type=initiative` + - `mcp__orgx__query_org_memory` +5. Prefer `mcp__orgx__scaffold_initiative` to create the full initiative, workstream, milestone, and starter-task hierarchy in one call. +6. If the user asks for agent delegation, call `mcp__orgx__check_spawn_guard` before `mcp__orgx__spawn_agent_task`. +7. If the user wants execution to begin now, launch with `mcp__orgx__entity_action type=initiative action=launch`. +8. End with `mcp__orgx__recommend_next_action` for the created initiative. -## Input +## Hierarchy Expectations -The user provides a one-line goal describing what they want to accomplish. Examples: - -- "Launch our mobile app in the App Store by Q2" -- "Migrate our infrastructure to Kubernetes" -- "Build an AI-powered customer support chatbot" - -## Process - -### Step 1: Parse the Goal - -Extract from the goal statement: - -- **Core objective**: What is the primary outcome? -- **Domain signals**: Which teams/domains are involved? (engineering, product, marketing, sales, operations, design) -- **Timeline hints**: Any dates or quarters mentioned? -- **Success indicators**: What would "done" look like? - -### Step 2: Create the Initiative - -Use `mcp__orgx__create_entity` with type="initiative" to create: - -- **title**: Clear, action-oriented title (e.g., "Mobile App Launch Q2 2025") -- **description**: 2-3 sentence summary including: - - What we're building/achieving - - Why it matters (business impact) - - Key constraints or dependencies -- **priority**: "high" for strategic goals, "medium" for operational improvements - -### Step 3: Define Milestones (3-5) - -Create milestones that represent major checkpoints. Each milestone should be: - -- **Time-bound**: Include realistic due_date (YYYY-MM-DD format) -- **Measurable**: Clear definition of done -- **Sequential**: Earlier milestones enable later ones - -Typical milestone pattern: - -1. **Discovery/Planning** (Week 1-2): Requirements, research, architecture decisions -2. **Foundation** (Week 3-4): Core infrastructure, setup, initial builds -3. **Core Development** (Week 5-8): Main feature implementation -4. **Integration/Testing** (Week 9-10): QA, bug fixes, integration testing -5. **Launch/Delivery** (Final week): Go-live, monitoring, handoff - -Use `mcp__orgx__create_entity` with type="milestone" for each, linking to the initiative_id. - -### Step 4: Create Workstreams - -Workstreams organize work by domain. Based on the goal, create relevant workstreams: - -| Domain | When to Create | Example Tasks | -| --------------- | ----------------------------------- | --------------------------------- | -| **engineering** | Technical implementation needed | Architecture, coding, DevOps | -| **product** | Product decisions/specs needed | PRD, user stories, prioritization | -| **marketing** | External communication needed | Messaging, launch plan, content | -| **sales** | Revenue impact or customer outreach | Enablement, pricing, demos | -| **operations** | Process/workflow changes needed | Runbooks, training, support | -| **design** | UI/UX work needed | Wireframes, prototypes, assets | - -Use `mcp__orgx__create_entity` with type="workstream" for each, linking to the initiative_id. - -### Step 5: Assign Agents to Workstreams - -For each workstream, use `mcp__orgx__spawn_agent_task` to assign the appropriate agent: - -- Match agent type to workstream domain -- Provide clear context about the initiative and their responsibilities -- Include the initiative_id for tracking - -Agent types: product, engineering, marketing, sales, operations, design, orchestrator - -### Step 6: Configure Agent Autonomy (Optional) - -If the user specifies trust preferences, use `mcp__orgx__configure_agent` to set: - -- **trust_level**: "strict" (approve everything), "balanced" (approve key decisions), "autonomous" (minimal oversight) -- **focus_areas**: Specific areas the agent should prioritize -- **approval_required**: Actions that need human sign-off -- **skip_approval**: Actions that can proceed automatically - -### Step 7: Launch the Initiative - -After all components are created, use `mcp__orgx__launch_entity` with type="initiative" to activate it. +- Use 3-5 milestones unless the user specifies a tighter structure. +- Use only the domains implied by the goal. +- Add an orchestrator path when the effort spans more than two domains or has non-trivial dependencies. +- Keep starter tasks small enough to be owned by one agent. ## Output -Provide a summary to the user including: - -1. **Initiative created**: Title and ID -2. **Milestones**: List with due dates -3. **Workstreams**: List with assigned agents -4. **Next steps**: What the user should expect (agent activity, first decisions) - -## Guidelines - -- Ask clarifying questions if the goal is ambiguous (timeline, scope, priority) -- Default to 2-week sprints for milestone spacing if no timeline given -- Always create at least engineering and product workstreams for technical goals -- Include an orchestrator agent task to coordinate cross-functional work -- Keep descriptions concise but specific; avoid generic filler text - -## Failure Handling +Report: -- If a similar initiative already exists, pause and ask whether to update it or create a new one. -- If OrgX MCP tools are unavailable, explain what is missing and stop rather than guessing. +- initiative title and ID +- milestones created +- workstreams created +- any delegated agents +- the single best next action diff --git a/initiative-kickoff/skill.toml b/initiative-kickoff/skill.toml index 421b7ca..3f6771f 100644 --- a/initiative-kickoff/skill.toml +++ b/initiative-kickoff/skill.toml @@ -1,7 +1,7 @@ name = "initiative-kickoff" -version = "1.1.0" -description = "From a one-line goal, creates a complete initiative with milestones, workstreams, and agent assignments" +version = "2.0.0" +description = "From a one-line goal, creates a complete initiative with scaffolded hierarchy, current workspace context, and optional guarded agent assignments" entry_instructions = "instructions.md" -required_tools = ["mcp__orgx__create_entity", "mcp__orgx__list_entities", "mcp__orgx__spawn_agent_task", "mcp__orgx__launch_entity", "mcp__orgx__configure_agent"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__list_entities", "mcp__orgx__query_org_memory", "mcp__orgx__scaffold_initiative", "mcp__orgx__entity_action", "mcp__orgx__check_spawn_guard", "mcp__orgx__spawn_agent_task", "mcp__orgx__recommend_next_action"] required_scopes = [] resources = ["checklist.md"] diff --git a/initiative-protocol/SKILL.md b/initiative-protocol/SKILL.md index 5c76845..1aa3e31 100644 --- a/initiative-protocol/SKILL.md +++ b/initiative-protocol/SKILL.md @@ -1,36 +1,55 @@ --- name: initiative-protocol description: | - Initiative lifecycle management for OrgX. Handles creation, decomposition - into workstreams/streams, launch, monitoring, and completion. + Initiative lifecycle management for OrgX. Handles workspace selection, + hierarchy scaffolding, launch, monitoring, evidence attachment, and completion. Use when planning or managing an OrgX initiative. --- # Initiative Protocol +Use this protocol whenever the user is creating, updating, launching, pausing, or closing an initiative. + +## Core Loop + +1. Bootstrap the session with `mcp__orgx__orgx_bootstrap`. +2. Ensure the correct workspace is active with `mcp__orgx__workspace`. +3. Load the target initiative with `mcp__orgx__list_entities` or `mcp__orgx__get_initiative_pulse`. +4. Create or update the hierarchy using the highest-level wrapper available. +5. Attach evidence, plans, and notes back to the initiative before marking it complete. + ## Creating an Initiative -1. Query existing: `mcp__orgx__query_org_memory("initiative [topic]")` -2. Create: `mcp__orgx__create_entity type=initiative` with title, summary, target_date -3. Break into 3-5 workstreams by domain -4. For each workstream, create a stream: `mcp__orgx__create_entity type=stream` - - Set agent_domain, depends_on (DAG), auto_continue -5. Launch: `mcp__orgx__launch_entity type=initiative` +1. Check for related work: + - `mcp__orgx__query_org_memory` for prior initiatives or decisions + - `mcp__orgx__list_entities type=initiative` for active duplicates +2. Prefer `mcp__orgx__scaffold_initiative` when the request includes milestones, workstreams, or starter tasks. +3. Use `mcp__orgx__create_entity type=initiative` only for a single initiative shell with no nested hierarchy yet. +4. For follow-on edits, prefer: + - `mcp__orgx__create_milestone` + - `mcp__orgx__create_task` + - `mcp__orgx__batch_create_entities` when creating several related children at once +5. Launch or pause through `mcp__orgx__entity_action`: + - launch: `type=initiative action=launch` + - pause: `type=initiative action=pause` ## Monitoring -- Check health: `mcp__orgx__get_initiative_pulse` -- Stream state: `mcp__orgx__get_initiative_stream_state` -- Key metrics: overall_progress, min_confidence, blocked_count, next_completions +- `mcp__orgx__get_initiative_pulse` for health, blockers, and milestones +- `mcp__orgx__get_initiative_stream_state` for stream progress and bottlenecks +- `mcp__orgx__recommend_next_action` when the user asks what to do next +- `mcp__orgx__comment_on_entity` for status notes that should live on the initiative itself -## Completing +## Completion -- All streams must be completed first -- Synthesize outputs from each domain -- Verify readiness: `mcp__orgx__verify_entity_completion type=initiative` -- Complete: `mcp__orgx__complete_entity type=initiative` +1. Confirm all dependent work is done or intentionally deferred. +2. Run `mcp__orgx__verify_entity_completion type=initiative`. +3. Attach proof with `mcp__orgx__entity_action action=attach` for plans, docs, URLs, or deliverable artifacts. +4. If planning happened in OrgX, finish the plan loop with `mcp__orgx__complete_plan attach_to=[...]` so the rationale is attached to the initiative context. +5. Mark complete with `mcp__orgx__entity_action type=initiative action=complete`. -## Risk Management +## Risk Handling -- Pause: `mcp__orgx__pause_entity type=initiative` with reason -- Re-launch after resolving blockers +- Use `mcp__orgx__entity_action type=initiative action=pause note="..."` for blockers or intentional holds. +- Use `mcp__orgx__queue_action` or `mcp__orgx__pin_workstream` when the priority problem is sequencing, not state. +- Use `mcp__orgx__comment_on_entity` instead of burying exceptions in the chat transcript. diff --git a/initiative-protocol/skill.toml b/initiative-protocol/skill.toml index c7485c6..1a29de1 100644 --- a/initiative-protocol/skill.toml +++ b/initiative-protocol/skill.toml @@ -1,7 +1,7 @@ name = "initiative-protocol" -version = "1.0.0" -description = "Initiative lifecycle management for OrgX. Handles creation, decomposition into workstreams/streams, launch, monitoring, and completion. Use when planning or managing an OrgX initiative." +version = "2.0.0" +description = "Initiative lifecycle management for OrgX with workspace resolution, hierarchy scaffolding, monitoring, evidence attachment, and completion verification." entry_instructions = "SKILL.md" -required_tools = ["mcp__orgx__complete_entity", "mcp__orgx__create_entity", "mcp__orgx__get_initiative_pulse", "mcp__orgx__get_initiative_stream_state", "mcp__orgx__launch_entity", "mcp__orgx__pause_entity", "mcp__orgx__query_org_memory", "mcp__orgx__verify_entity_completion"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__query_org_memory", "mcp__orgx__list_entities", "mcp__orgx__scaffold_initiative", "mcp__orgx__create_entity", "mcp__orgx__create_milestone", "mcp__orgx__create_task", "mcp__orgx__batch_create_entities", "mcp__orgx__entity_action", "mcp__orgx__get_initiative_pulse", "mcp__orgx__get_initiative_stream_state", "mcp__orgx__verify_entity_completion", "mcp__orgx__comment_on_entity", "mcp__orgx__recommend_next_action", "mcp__orgx__complete_plan"] required_scopes = [] resources = [] diff --git a/marketing-agent/SKILL.md b/marketing-agent/SKILL.md index a6d2313..4f3dff2 100644 --- a/marketing-agent/SKILL.md +++ b/marketing-agent/SKILL.md @@ -9,12 +9,16 @@ description: | ## Quick Start -1. Confirm the artifact or decision type and the target audience. -2. Pull OrgX context with `mcp__orgx__list_entities` and `mcp__orgx__query_org_memory`. -3. Produce the artifact using the contract below and return: +1. Run `mcp__orgx__orgx_bootstrap`, then resolve workspace scope with `mcp__orgx__workspace`. +2. Confirm the artifact or decision type and the target audience. If the request is task-bound, hydrate it with `mcp__orgx__get_task_with_context`; otherwise map relevant initiatives and prior artifacts with `mcp__orgx__list_entities`. +3. Pull precedent with `mcp__orgx__query_org_memory` and `mcp__orgx__get_relevant_learnings`. +4. For launch plans or initiative decomposition, use the planning loop: `mcp__orgx__start_plan_session`, `mcp__orgx__improve_plan`, `mcp__orgx__record_plan_edit`, then `mcp__orgx__complete_plan`. +5. Produce the artifact using the contract below and return: - A concise summary (3-6 bullets) - The artifact body (JSON or structured Markdown) - 3 actionable next steps +6. Attach the result back to the active task or initiative with `mcp__orgx__entity_action` (`action=attach`) or `mcp__orgx__comment_on_entity`. +7. Before handing off campaign execution, run `mcp__orgx__check_spawn_guard`, then use `mcp__orgx__spawn_agent_task`. Deliver conversion-oriented, evidence-backed marketing assets with deterministic quality gates. @@ -414,26 +418,38 @@ Use findings to inform the new artifact. Cite previous learnings explicitly: "Ba ## Operating Workflow -1. Choose `artifact_type` and define one primary goal metric. -2. Run context adaptation protocol -- classify company stage, audience type, and GTM motion. -3. Gather evidence: +1. Run `mcp__orgx__orgx_bootstrap` and resolve workspace with `mcp__orgx__workspace`. +2. Choose `artifact_type` and define one primary goal metric. +3. Hydrate context: + - `mcp__orgx__get_task_with_context` for active task work + - `mcp__orgx__list_entities` for related initiatives, prior briefs, and existing content +4. Run context adaptation protocol -- classify company stage, audience type, and GTM motion. +5. Gather evidence: - Prior campaign context from `mcp__orgx__query_org_memory` +- Prior learnings from `mcp__orgx__get_relevant_learnings` - Existing artifacts from `mcp__orgx__list_entities` - Channel constraints from CMS or content platform when available - Competitive context from org memory or provided intel -4. Select frameworks -- choose 1-3 frameworks from the Domain Expertise Canon that are most relevant to this artifact type and context. -5. Draft JSON-first artifact following the contract for the chosen type. -6. Run the Precision Loop (see below). -7. Validate: +6. For launch plans, messaging frameworks, or initiative decomposition, open a plan session with `mcp__orgx__start_plan_session`, refine with `mcp__orgx__improve_plan`, and log major revisions with `mcp__orgx__record_plan_edit`. +7. Select frameworks -- choose 1-3 frameworks from the Domain Expertise Canon that are most relevant to this artifact type and context. +8. Draft JSON-first artifact following the contract for the chosen type. +9. Run the Precision Loop (see below). +10. Validate: ```bash python3 scripts/validate_marketing.py --type ``` -8. Fix all failed gates, then publish with `mcp__orgx__create_entity`. -9. Record learnings via `mcp__orgx__submit_learning`. +11. Fix all failed gates, then publish with `mcp__orgx__create_entity`. +12. Attach proof or conclusions back to the active work: + - `mcp__orgx__complete_plan` with `attach_to` for completed plan sessions + - `mcp__orgx__entity_action` with `action=attach` for campaign briefs, launch plans, and messaging docs + - `mcp__orgx__comment_on_entity` for feedback or decision notes +13. Record learnings via `mcp__orgx__submit_learning`. +14. Record artifact quality via `mcp__orgx__record_quality_score`. +15. Before handing off execution, run `mcp__orgx__check_spawn_guard`, then use `mcp__orgx__spawn_agent_task`. --- @@ -467,11 +483,23 @@ Before marking any artifact as complete, verify these strategic questions are an Primary: +- `mcp__orgx__orgx_bootstrap` -- initialize OrgX session scope and recommended workflow +- `mcp__orgx__workspace` -- resolve or switch workspace scope +- `mcp__orgx__get_task_with_context` -- hydrate task-bound context, attachments, and plan sessions - `mcp__orgx__query_org_memory` -- retrieve prior campaigns, learnings, competitive intel +- `mcp__orgx__get_relevant_learnings` -- pull prior GTM learnings before drafting - `mcp__orgx__list_entities` -- find existing artifacts, initiatives, and context +- `mcp__orgx__start_plan_session` -- open tracked planning sessions for launch and messaging work +- `mcp__orgx__improve_plan` -- refine campaign or launch plans +- `mcp__orgx__record_plan_edit` -- capture material revisions to the plan +- `mcp__orgx__complete_plan` -- finalize and attach the plan to OrgX entities - `mcp__orgx__create_entity` -- publish completed artifacts +- `mcp__orgx__entity_action` -- attach evidence and update entity state +- `mcp__orgx__comment_on_entity` -- leave review notes on active initiatives or tasks +- `mcp__orgx__check_spawn_guard` -- verify delegation is allowed before handoff - `mcp__orgx__spawn_agent_task` -- hand off to other agents - `mcp__orgx__submit_learning` -- record learnings for the flywheel +- `mcp__orgx__record_quality_score` -- record artifact quality for calibration - `mcp__orgx__get_org_snapshot` -- understand current org state and priorities - `mcp__orgx__recommend_next_action` -- identify highest-leverage marketing action diff --git a/marketing-agent/skill.toml b/marketing-agent/skill.toml index ed3f6f7..3a4620e 100644 --- a/marketing-agent/skill.toml +++ b/marketing-agent/skill.toml @@ -2,6 +2,6 @@ name = "marketing-agent" version = "2.0.0" description = "Produce high-confidence marketing artifacts for OrgX: campaign briefs, multichannel content packs, nurture sequences, positioning documents, messaging matrices, competitive narratives, launch plans, analyst briefs, and community strategies. Use when go-to-market messaging, campaign strategy, content execution, or channel performance planning is needed." entry_instructions = "SKILL.md" -required_tools = ["mcp__orgx__create_entity", "mcp__orgx__list_entities", "mcp__orgx__query_org_memory", "mcp__orgx__spawn_agent_task", "mcp__orgx__submit_learning", "mcp__orgx__get_org_snapshot"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__get_task_with_context", "mcp__orgx__query_org_memory", "mcp__orgx__list_entities", "mcp__orgx__start_plan_session", "mcp__orgx__improve_plan", "mcp__orgx__record_plan_edit", "mcp__orgx__complete_plan", "mcp__orgx__create_entity", "mcp__orgx__entity_action", "mcp__orgx__comment_on_entity", "mcp__orgx__check_spawn_guard", "mcp__orgx__spawn_agent_task", "mcp__orgx__get_relevant_learnings", "mcp__orgx__submit_learning", "mcp__orgx__record_quality_score", "mcp__orgx__get_org_snapshot", "mcp__orgx__recommend_next_action"] required_scopes = [] resources = [] diff --git a/milestone-protocol/SKILL.md b/milestone-protocol/SKILL.md index beb4486..2af3ce3 100644 --- a/milestone-protocol/SKILL.md +++ b/milestone-protocol/SKILL.md @@ -2,39 +2,45 @@ name: milestone-protocol description: | Milestone tracking and checkpoint management for OrgX initiatives. - Handles milestone creation, progress tracking, risk flagging, and completion. - Use when working with initiative milestones and delivery checkpoints. + Handles milestone creation, launch, risk flagging, evidence attachment, + and completion. Use when working with initiative milestones and delivery + checkpoints. --- # Milestone Protocol +Milestones are checkpoints with explicit deliverables. Treat them as proof gates, not status labels. + +## Core Loop + +1. Bootstrap and confirm workspace with `mcp__orgx__orgx_bootstrap` and `mcp__orgx__workspace`. +2. Load the parent initiative or workstream with `mcp__orgx__list_entities`. +3. Create or update the milestone. +4. Attach evidence as deliverables land. +5. Verify readiness before completing. + ## Creating Milestones -- Create: `mcp__orgx__create_entity type=milestone` -- Link to initiative and workstream -- Define deliverables and due_date +- Prefer `mcp__orgx__create_milestone` when creating a single checkpoint. +- Use `mcp__orgx__batch_create_entities` when creating multiple milestones with shared refs. +- Always link the milestone to its initiative, and workstream when applicable. +- Include deliverables and `due_date`. ## Tracking Progress -- Start: `mcp__orgx__launch_entity type=milestone` -- Check status via `mcp__orgx__list_entities type=milestone` -- Review linked tasks for completion percentage +- Start with `mcp__orgx__entity_action type=milestone action=launch`. +- Inspect status with `mcp__orgx__list_entities type=milestone` or the parent initiative pulse. +- Use `mcp__orgx__comment_on_entity` for checkpoint notes that should remain visible to operators. ## Flagging Risk -- If at risk: `mcp__orgx__pause_entity type=milestone` -- Include reason and mitigation plan -- Escalate to orchestrator if cross-domain impact +- Pause with `mcp__orgx__entity_action type=milestone action=pause note="..."`. +- Include the blocker, mitigation path, and owner. +- Escalate cross-domain risks through the parent initiative or orchestrator comments, not only in chat. ## Completing -- Verify all deliverables are met -- Verify readiness: `mcp__orgx__verify_entity_completion type=milestone` -- Complete: `mcp__orgx__complete_entity type=milestone` -- Document what was delivered - -## Best Practices - -- Milestones are checkpoints, not tasks - they mark meaningful progress -- Each milestone should have clear, verifiable deliverables -- Flag risk early rather than missing silently +1. Verify all milestone deliverables are attached or linked. +2. Run `mcp__orgx__verify_entity_completion type=milestone`. +3. Attach proof with `mcp__orgx__entity_action action=attach`. +4. Complete with `mcp__orgx__entity_action type=milestone action=complete`. diff --git a/milestone-protocol/skill.toml b/milestone-protocol/skill.toml index 758e3b4..6caef3b 100644 --- a/milestone-protocol/skill.toml +++ b/milestone-protocol/skill.toml @@ -1,7 +1,7 @@ name = "milestone-protocol" -version = "1.0.0" -description = "Milestone tracking and checkpoint management for OrgX initiatives. Handles milestone creation, progress tracking, risk flagging, and completion. Use when working with initiative milestones and delivery checkpoints." +version = "2.0.0" +description = "Milestone checkpoint management for OrgX initiatives with launch, pause, evidence attachment, and completion verification." entry_instructions = "SKILL.md" -required_tools = ["mcp__orgx__complete_entity", "mcp__orgx__create_entity", "mcp__orgx__launch_entity", "mcp__orgx__list_entities", "mcp__orgx__pause_entity", "mcp__orgx__verify_entity_completion"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__create_milestone", "mcp__orgx__batch_create_entities", "mcp__orgx__list_entities", "mcp__orgx__entity_action", "mcp__orgx__verify_entity_completion", "mcp__orgx__comment_on_entity"] required_scopes = [] resources = [] diff --git a/morning-briefing/SKILL.md b/morning-briefing/SKILL.md index a0f1f92..1d275ea 100644 --- a/morning-briefing/SKILL.md +++ b/morning-briefing/SKILL.md @@ -1,96 +1,56 @@ --- name: Morning Briefing description: | - Generate a daily OrgX briefing with morning brief value signals, pending decisions, blocked tasks, agent status, and initiative health. - Use when the user asks for: a daily briefing, morning update, status overview, what needs attention today, - pending decisions summary, blocked work report, or any variation of "what should I work on first?" - Triggers on: "morning briefing", "daily status", "what's pending", "show me blockers", "agent activity". + Generate a daily OrgX briefing with morning-brief value signals, pending + decisions, blocked tasks, agent activity, initiative health, and the single + best next action for the active workspace. --- # Morning Briefing -Generate a concise daily status report for OrgX users. +Generate a concise daily status report for the active OrgX workspace. ## Workflow -1. **Fetch morning brief value signals** using `mcp__orgx__get_morning_brief` - - - Use the most recent session by default - - Surface exceptions, ROI delta, and value signals first - -2. **Fetch pending decisions** using `mcp__orgx__list_entities` - - - Type: `decision`, status: `pending` - - Filter by urgency: critical and high first when available in metadata - - Sort by age (oldest first) - -3. **Fetch blocked tasks** using `mcp__orgx__list_entities` - - - Type: `task`, status: `blocked` - - Group by initiative - -4. **Fetch agent status** using `mcp__orgx__get_agent_status` - - - Include active agents only by default - - Show current task for each - -5. **Fetch initiative health** using `mcp__orgx__get_initiative_pulse` - - - For active initiatives - - Include blockers and upcoming milestones - -6. **Synthesize and prioritize** the suggested first action: - - Critical decision > Blocked high-priority task > Morning brief exception > Agent needing input +1. Bootstrap with `mcp__orgx__orgx_bootstrap`. +2. Resolve the workspace with `mcp__orgx__workspace`. +3. Fetch: + - `mcp__orgx__get_morning_brief` + - `mcp__orgx__list_entities type=decision status=pending` + - `mcp__orgx__list_entities type=task status=blocked` + - `mcp__orgx__get_agent_status include_idle=false` + - `mcp__orgx__get_org_snapshot` + - `mcp__orgx__recommend_next_action entity_type=workspace` +4. Prioritize the briefing: + - critical decisions + - blocked work the user can unblock + - value exceptions or risk signals + - agents waiting on input ## Output Format ```markdown -## 🌅 Morning Brief Signals +## Morning Brief Signals -- [Value delta, exceptions, and notable receipts] +- [value delta, exceptions, notable receipts] -## 🔴 Critical Decisions (X need attention) +## Critical Decisions -| ID | Title | Urgency | Age | -| --- | ----- | ------- | --- | +- [decision summary] -## 🟡 Blocked Tasks (X blocked) +## Blocked Tasks -| ID | Title | Blocker | Unblock Owner | -| --- | ----- | ------- | ------------- | +- [task summary] -## 🤖 Active Agents (X running) +## Active Agents -| Agent | Domain | Current Task | -| ----- | ------ | ------------ | +- [agent + current work] -## 📊 Initiative Health +## Initiative Health -| Name | Status | Health | Next Milestone | -| ---- | ------ | ------ | -------------- | +- [highest-risk initiatives] -## ✅ Suggested First Action +## Suggested First Action -> [Specific, actionable recommendation with entity ID] +> [single actionable recommendation] ``` - -## Priority Logic - -Recommend first action based on: - -1. Critical decision pending > 24 hours -2. High-priority task blocked by something user can resolve -3. Decision aging toward SLA breach -4. Agent waiting for input -5. Initiative at risk (health < 50%) -6. Stale task needing attention -7. Low-priority cleanup items -8. Proactive review if nothing urgent - -## Error Handling - -If any API call fails: - -- Continue with available data -- Note missing sections -- Never block on partial failures diff --git a/morning-briefing/instructions.md b/morning-briefing/instructions.md index 1ba4a8d..367567b 100644 --- a/morning-briefing/instructions.md +++ b/morning-briefing/instructions.md @@ -1,51 +1,20 @@ You are generating the morning briefing for the user's OrgX workspace. -## Data Collection - -1. **Morning Brief Signals** - Call `mcp__orgx__get_morning_brief` to fetch the latest value summary, exceptions, and recent receipt highlights. - -2. **Pending Decisions** - Call `mcp__orgx__list_entities` with `type: "decision"` and `status: "pending"` to fetch all pending decisions. Sort by urgency (critical first, then high) when metadata is available. - -3. **Blocked Tasks** - Call `mcp__orgx__list_entities` with `type: "task"` and `status: "blocked"` to identify work that is stuck and needs attention. - -4. **Agent Status** - Call `mcp__orgx__get_agent_status` with `include_idle: false` to see which agents are currently active and what they are working on. - -## Output Format - -Present the briefing in the following structure: - -### Morning Brief Signals - -- Summarize the latest value delta, important exceptions, and standout receipts first. -- If the morning brief is empty, state that no recent autonomous-session value summary is available. - -### Critical Decisions - -- List any decisions with critical or high urgency that require immediate attention. -- Include the decision ID, summary, and who needs to approve. -- If none, state "No critical decisions pending." - -### Blocked Tasks - -- List tasks that are currently blocked. -- Include task name, owner, and what is blocking progress. -- If none, state "No blocked tasks." - -### Active Agents - -- Summarize which agents are currently running and their current activity. -- If all agents are idle, state "All agents idle." - -### Suggested First Action - -- Based on the briefing data, recommend the single most important action to take first. -- Prioritize: critical decisions > unblocking tasks > morning brief exceptions > reviewing agent outputs. -- Be specific and actionable (e.g., "Approve decision DEC-123 to unblock the marketing workstream"). - -## Guidelines - -- Keep the briefing concise - aim for a 2-minute read. -- Use bullet points for easy scanning. -- Include IDs and links where available for quick action. -- If data is unavailable or empty, acknowledge it gracefully rather than omitting sections. -- Timestamp the briefing with the current date. +## Required Sequence + +1. Call `mcp__orgx__orgx_bootstrap`. +2. Resolve the active workspace with `mcp__orgx__workspace`. +3. Collect: + - `mcp__orgx__get_morning_brief` + - `mcp__orgx__list_entities` for pending decisions + - `mcp__orgx__list_entities` for blocked tasks + - `mcp__orgx__get_agent_status include_idle=false` + - `mcp__orgx__get_org_snapshot` + - `mcp__orgx__recommend_next_action entity_type=workspace` + +## Output Rules + +- Keep it short enough to scan in 2 minutes. +- Surface the single most important next move. +- If any section is empty, say so explicitly instead of omitting it. +- Prefer workspace-level priorities over generic summaries. diff --git a/morning-briefing/skill.toml b/morning-briefing/skill.toml index 8dc412c..ef77a39 100644 --- a/morning-briefing/skill.toml +++ b/morning-briefing/skill.toml @@ -1,7 +1,7 @@ name = "morning-briefing" -version = "1.0.0" -description = "Get your daily OrgX briefing - morning brief value signals, pending decisions, blocked work, and agent status" +version = "2.0.0" +description = "Get your daily OrgX briefing with workspace-aware value signals, pending decisions, blocked work, agent status, initiative health, and the single best next action" entry_instructions = "instructions.md" -required_tools = ["mcp__orgx__get_morning_brief", "mcp__orgx__get_agent_status", "mcp__orgx__list_entities", "mcp__orgx__get_initiative_pulse"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__get_morning_brief", "mcp__orgx__get_agent_status", "mcp__orgx__list_entities", "mcp__orgx__get_org_snapshot", "mcp__orgx__recommend_next_action"] required_scopes = [] resources = [] diff --git a/nightly-recap/SKILL.md b/nightly-recap/SKILL.md index f7d5a06..56c3f57 100644 --- a/nightly-recap/SKILL.md +++ b/nightly-recap/SKILL.md @@ -1,66 +1,50 @@ --- name: nightly-recap description: | - Draft nightly recaps summarizing OrgX activity including completed tasks, decisions made, and agent work. - Use when: user asks for a daily summary, end-of-day recap, activity report, or wants to see what happened today. - Triggers on: "nightly recap", "daily summary", "what happened today", "end of day report", "activity summary". + Draft nightly recaps summarizing OrgX workspace activity including completed + work, pending decisions, active agents, and notable risks still open at the + end of the day. --- # Nightly Recap -Generate a summary of the day's OrgX activity. +Generate an end-of-day OrgX summary for the active workspace. -## Required Tools +## Required Sequence -- `context.run_summary` - Get run activity -- `telemetry.errors.list` - Check for errors +1. Call `mcp__orgx__orgx_bootstrap`. +2. Resolve the workspace with `mcp__orgx__workspace`. +3. Gather: + - `mcp__orgx__get_org_snapshot` + - `mcp__orgx__list_entities type=task status=done` + - `mcp__orgx__list_entities type=decision status=pending` + - `mcp__orgx__get_agent_status include_idle=true` + - `mcp__orgx__recommend_next_action entity_type=workspace` -## Workflow - -1. **Fetch today's activity** using run summary tools -2. **Aggregate by category**: - - - Tasks completed - - Decisions made - - Artifacts created - - Agent activity - - Errors/issues encountered - -3. **Generate recap** in this format: +## Output ```markdown # Nightly Recap - [Date] -## 📊 Summary - -- Tasks completed: X -- Decisions made: Y -- Artifacts created: Z +## Summary -## ✅ Completed Tasks +- Work completed: [highlights] +- Decisions still pending: [count] +- Risks still open: [count or none] -| Task | Initiative | Completed By | -| ---- | ---------- | ------------ | +## Completed Work -## 🎯 Decisions Made +- [task or milestone] -| Decision | Outcome | Initiative | -| -------- | ------- | ---------- | +## Pending Decisions -## 🤖 Agent Activity +- [decision] -| Agent | Tasks Completed | Time Active | -| ----- | --------------- | ----------- | +## Agent Activity -## ⚠️ Issues (if any) +- [agent summary] -- [List any errors or blocked items] +## Tomorrow's First Move -## 📝 Notes - -[Any notable patterns or recommendations] +> [single next action] ``` - -## Checklist - -See [checklist.md](checklist.md) for validation items. diff --git a/nightly-recap/skill.toml b/nightly-recap/skill.toml index 3ceaad8..f9abc00 100644 --- a/nightly-recap/skill.toml +++ b/nightly-recap/skill.toml @@ -1,7 +1,7 @@ name = "nightly-recap" -version = "0.1.0" -description = "Draft nightly recaps with highlights, blockers, and approvals needed." +version = "1.0.0" +description = "Draft nightly OrgX recaps with completed work, pending approvals, agent activity, and tomorrow's first move." entry_instructions = "instructions.md" -required_tools = ["context.run_summary", "context.conversation_history", "telemetry.errors.list", "verification.contract.check"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__get_org_snapshot", "mcp__orgx__list_entities", "mcp__orgx__get_agent_status", "mcp__orgx__recommend_next_action"] required_scopes = [] resources = ["checklist.md"] diff --git a/operations-agent/SKILL.md b/operations-agent/SKILL.md index 9bf9b3c..f8ac7e1 100644 --- a/operations-agent/SKILL.md +++ b/operations-agent/SKILL.md @@ -9,14 +9,17 @@ description: | ## Quick Start -1. Confirm the artifact or decision type and the target audience. -2. Pull OrgX context with `mcp__orgx__list_entities` and `mcp__orgx__query_org_memory`. -3. Identify the operational maturity stage (see Context Adaptation Protocol) and calibrate depth. -4. Produce the artifact using the contract below and return: +1. Run `mcp__orgx__orgx_bootstrap`, then resolve workspace scope with `mcp__orgx__workspace`. +2. Confirm the artifact or decision type and the target audience. If the request is task-bound, hydrate it with `mcp__orgx__get_task_with_context`; otherwise map related work with `mcp__orgx__list_entities`. +3. Pull precedent with `mcp__orgx__query_org_memory` and `mcp__orgx__get_relevant_learnings`. +4. For playbooks, migrations, or SLO programs, use the planning loop: `mcp__orgx__start_plan_session`, `mcp__orgx__improve_plan`, `mcp__orgx__record_plan_edit`, then `mcp__orgx__complete_plan`. +5. Identify the operational maturity stage (see Context Adaptation Protocol) and calibrate depth. +6. Produce the artifact using the contract below and return: - A concise summary (3-6 bullets) - The artifact body (JSON or structured Markdown) - 3 actionable next steps -5. Run the Precision Loop before publishing. +7. Run the Precision Loop before publishing. +8. Attach the result back to the active task or initiative with `mcp__orgx__entity_action` (`action=attach`) or `mcp__orgx__comment_on_entity`, then record quality with `mcp__orgx__record_quality_score`. Deliver operational artifacts that reduce incident risk, improve response quality, and drive systematic reliability improvement. @@ -173,23 +176,36 @@ When producing any artifact, identify the applicable signals first and adjust ar ## Operating Workflow -1. Pick `artifact_type` and define success condition. -2. Identify organizational maturity signals from Context Adaptation Protocol. -3. Gather evidence: +1. Run `mcp__orgx__orgx_bootstrap` and resolve workspace with `mcp__orgx__workspace`. +2. Pick `artifact_type` and define success condition. +3. Hydrate the active task or parent entity: + - `mcp__orgx__get_task_with_context` for task-bound work + - `mcp__orgx__list_entities` for surrounding initiatives, milestones, and prior incidents or playbooks +4. Identify organizational maturity signals from Context Adaptation Protocol. +5. Gather evidence: - OrgX context: `mcp__orgx__query_org_memory`, `mcp__orgx__list_entities` + - Prior learnings: `mcp__orgx__get_relevant_learnings` - Incident context: PagerDuty/observability tools when available - Cost data: cloud provider billing, FinOps tooling - Capacity data: APM, load balancer metrics, database metrics -4. Apply relevant frameworks from Domain Expertise Canon. -5. Draft JSON-first artifact following the contract for the selected type. -6. Run the Precision Loop (all 4 passes). -7. Validate: +6. For programmatic operational plans, open a plan session with `mcp__orgx__start_plan_session`, refine with `mcp__orgx__improve_plan`, and record major revisions with `mcp__orgx__record_plan_edit`. +7. Apply relevant frameworks from Domain Expertise Canon. +8. Draft JSON-first artifact following the contract for the selected type. +9. Run the Precision Loop (all 4 passes). +10. Validate: ```bash python3 scripts/validate_ops.py --type ``` -8. Resolve all failed gates, then publish via `mcp__orgx__create_entity`. +11. Resolve all failed gates, then publish via `mcp__orgx__create_entity`. +12. Attach proof or conclusions back to the active work: + - `mcp__orgx__complete_plan` with `attach_to` for plan sessions + - `mcp__orgx__entity_action` with `action=attach` for incidents, SLOs, budgets, and playbooks + - `mcp__orgx__comment_on_entity` for reviews or escalation notes +13. Submit learnings via `mcp__orgx__submit_learning`. +14. Record measurable outcomes with `mcp__orgx__record_outcome` when the artifact closes a reliability or cost event. +15. Record artifact quality with `mcp__orgx__record_quality_score`. --- @@ -533,12 +549,22 @@ Incorporate relevant prior learnings into the artifact. Reference them explicitl ### Primary +- `mcp__orgx__orgx_bootstrap` — initialize OrgX session scope and recommended workflow +- `mcp__orgx__workspace` — resolve workspace scope before reading or writing +- `mcp__orgx__get_task_with_context` — hydrate task-bound context, attachments, and prior plan sessions - `mcp__orgx__query_org_memory` — Retrieve organizational context and prior decisions - `mcp__orgx__list_entities` — List initiatives, workstreams, tasks, milestones +- `mcp__orgx__start_plan_session` — open tracked planning sessions for playbooks, migrations, and SLO programs +- `mcp__orgx__improve_plan` — refine operational plans with historical patterns +- `mcp__orgx__record_plan_edit` — capture major planning revisions +- `mcp__orgx__complete_plan` — persist and attach finalized operational plans - `mcp__orgx__create_entity` — Publish artifacts and create operational tasks +- `mcp__orgx__entity_action` — attach evidence and update operational state +- `mcp__orgx__comment_on_entity` — add operational notes and review feedback to active work - `mcp__orgx__update_entity` — Update existing operational entities - `mcp__orgx__submit_learning` — Feed findings into the learning loop - `mcp__orgx__record_outcome` — Record measurable operational outcomes +- `mcp__orgx__record_quality_score` — score artifact quality for calibration - `mcp__orgx__get_relevant_learnings` — Check for prior learnings before drafting ### Optional (if configured) diff --git a/operations-agent/skill.toml b/operations-agent/skill.toml index aad8a67..7c0a748 100644 --- a/operations-agent/skill.toml +++ b/operations-agent/skill.toml @@ -2,6 +2,6 @@ name = "operations-agent" version = "2.0.0" description = "Produce high-confidence operations artifacts for OrgX: incident analyses, operational playbooks, budget controls, capacity plans, vendor evaluations, SLO proposals, chaos test plans, migration checklists, and on-call rotation audits. Use when reliability, incident management, escalation readiness, or operational cost governance is required." entry_instructions = "SKILL.md" -required_tools = ["mcp__orgx__create_entity", "mcp__orgx__list_entities", "mcp__orgx__query_org_memory", "mcp__orgx__update_entity", "mcp__orgx__submit_learning", "mcp__orgx__record_outcome", "mcp__orgx__get_relevant_learnings"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__get_task_with_context", "mcp__orgx__query_org_memory", "mcp__orgx__list_entities", "mcp__orgx__start_plan_session", "mcp__orgx__improve_plan", "mcp__orgx__record_plan_edit", "mcp__orgx__complete_plan", "mcp__orgx__create_entity", "mcp__orgx__entity_action", "mcp__orgx__comment_on_entity", "mcp__orgx__update_entity", "mcp__orgx__submit_learning", "mcp__orgx__record_outcome", "mcp__orgx__record_quality_score", "mcp__orgx__get_relevant_learnings"] required_scopes = [] resources = ["evaluations/ops-evaluation.json", "examples/incident-analysis.md", "examples/slo-proposal.md", "reference/ops-frameworks-cheatsheet.md", "reference/incident-template.md"] diff --git a/orchestrator-agent/SKILL.md b/orchestrator-agent/SKILL.md index 73acce1..6a8d662 100644 --- a/orchestrator-agent/SKILL.md +++ b/orchestrator-agent/SKILL.md @@ -10,15 +10,18 @@ description: | ## Quick Start -1. Confirm the artifact or decision type and the target audience. -2. Pull OrgX context with `mcp__orgx__list_entities` and `mcp__orgx__query_org_memory`. +1. Run `mcp__orgx__orgx_bootstrap`, then resolve workspace scope with `mcp__orgx__workspace`. +2. Confirm the artifact or decision type and the target audience. If the work is task-bound, hydrate it with `mcp__orgx__get_task_with_context`; otherwise map the surrounding initiative with `mcp__orgx__list_entities` and `mcp__orgx__get_initiative_pulse`. 3. Retrieve relevant learnings with `mcp__orgx__get_relevant_learnings` and prior coordination decisions with `mcp__orgx__query_org_memory` scoped to decisions. -4. Assess the coordination context (number of agents, dependency complexity, time horizon) and adapt formality accordingly. -5. Produce the artifact using the contract below and return: +4. For new initiative formation, prefer `mcp__orgx__scaffold_initiative`. For strategy-heavy coordination work, run a planning loop with `mcp__orgx__start_plan_session`, `mcp__orgx__improve_plan`, `mcp__orgx__record_plan_edit`, and `mcp__orgx__complete_plan`. +5. Assess the coordination context (number of agents, dependency complexity, time horizon) and adapt formality accordingly. +6. Produce the artifact using the contract below and return: - A concise summary (3-6 bullets) - The artifact body (JSON or structured Markdown) - 3 actionable next steps with owners and deadlines -6. Submit learnings with `mcp__orgx__submit_learning` and score the artifact with `mcp__orgx__record_quality_score`. +7. Attach proof back to the initiative, task, or decision with `mcp__orgx__entity_action` (`action=attach`) or `mcp__orgx__comment_on_entity`. +8. Before every delegation, run `mcp__orgx__check_spawn_guard`, then use `mcp__orgx__spawn_agent_task`. +9. Submit learnings with `mcp__orgx__submit_learning` and score the artifact with `mcp__orgx__record_quality_score`. Drive multi-agent execution with clear dependencies, quality gates, and accountable handoffs. The orchestrator never does the domain work itself — it coordinates, sequences, unblocks, and synthesizes. @@ -160,34 +163,44 @@ If unknown, state assumptions explicitly and request missing owners or dates. Ne ## Operating Workflow -1. Choose `artifact_type` based on the coordination need. -2. Assess coordination context using the Context Adaptation Protocol. -3. Retrieve learnings and precedent: +1. Run `mcp__orgx__orgx_bootstrap` and resolve workspace with `mcp__orgx__workspace`. +2. Choose `artifact_type` based on the coordination need. +3. Hydrate the active task or initiative: + - `mcp__orgx__get_task_with_context` for task-bound orchestration work + - `mcp__orgx__list_entities` and `mcp__orgx__get_initiative_pulse` for parent initiative state and neighboring work +4. Assess coordination context using the Context Adaptation Protocol. +5. Retrieve learnings and precedent: - `mcp__orgx__get_relevant_learnings` — past coordination patterns for similar initiatives - `mcp__orgx__query_org_memory` with `scope: "decisions"` — what worked and failed in prior cross-domain work - `mcp__orgx__query_org_memory` — organizational precedent and norms -4. Gather baseline context: +6. Gather baseline context: - `mcp__orgx__list_entities` — discover existing initiatives, workstreams, tasks, agents - `mcp__orgx__get_initiative_pulse` — understand momentum and blockers for in-flight work -5. Apply learnings as constraints or calibration adjustments. If a learning says "engineering-agent estimates are consistently 1.5x optimistic," apply that correction factor. -6. Draft JSON-first artifact following the artifact contract. -7. Run the Precision Loop (all 5 passes). -8. Validate: + - `mcp__orgx__recommend_next_action` — understand current queue pressure before adding new work +7. For new initiative setup, prefer `mcp__orgx__scaffold_initiative` to manual hierarchy assembly. For coordination plans and retrospectives, run a plan session with `mcp__orgx__start_plan_session`, `mcp__orgx__improve_plan`, and `mcp__orgx__record_plan_edit`. +8. Apply learnings as constraints or calibration adjustments. If a learning says "engineering-agent estimates are consistently 1.5x optimistic," apply that correction factor. +9. Draft JSON-first artifact following the artifact contract. +10. Run the Precision Loop (all 5 passes). +11. Validate: ```bash python3 scripts/validate_orchestration.py --type ``` -9. Resolve all failed gates. -10. Execute orchestration: - - Create/launch initiative with `mcp__orgx__create_entity` and `mcp__orgx__entity_action` - - Delegate with `mcp__orgx__spawn_agent_task` +12. Resolve all failed gates. +13. Execute orchestration: + - Create new initiative hierarchies with `mcp__orgx__scaffold_initiative`, or publish supporting artifacts with `mcp__orgx__create_entity` + - Launch, block, resume, complete, attach evidence, or update state with `mcp__orgx__entity_action` + - Before each delegation, run `mcp__orgx__check_spawn_guard`, then delegate with `mcp__orgx__spawn_agent_task` - Emit progress checkpoints with `mcp__orgx__orgx_emit_activity` - Batch state updates with `mcp__orgx__orgx_apply_changeset` (idempotent, transactional) - Record outcomes with `mcp__orgx__record_outcome` at each milestone - - Close loop with `mcp__orgx__entity_action` -11. Submit learnings: `mcp__orgx__submit_learning` with coordination-specific insight. -12. Score the artifact: `mcp__orgx__record_quality_score`. +14. Attach coordination proof back to OrgX: + - `mcp__orgx__complete_plan` with `attach_to` for planning sessions + - `mcp__orgx__entity_action` with `action=attach` for initiative plans, synthesis, and risk registers + - `mcp__orgx__comment_on_entity` for unblock requests, reviews, and decision notes +15. Submit learnings: `mcp__orgx__submit_learning` with coordination-specific insight. +16. Score the artifact: `mcp__orgx__record_quality_score`. ## Artifact Contracts @@ -484,10 +497,20 @@ Run the validator script and confirm zero errors. Verify that all spawned tasks ### Primary +- `mcp__orgx__orgx_bootstrap` — initialize OrgX session scope and recommended workflow +- `mcp__orgx__workspace` — resolve workspace scope before orchestration changes +- `mcp__orgx__get_task_with_context` — hydrate task-bound orchestration work with attachments and plan sessions - `mcp__orgx__query_org_memory` — organizational precedent and context - `mcp__orgx__list_entities` — discover existing initiatives, workstreams, tasks, agents +- `mcp__orgx__start_plan_session` — open tracked plan sessions for initiative design and retrospectives +- `mcp__orgx__improve_plan` — refine coordination plans using prior patterns +- `mcp__orgx__record_plan_edit` — capture major plan revisions +- `mcp__orgx__complete_plan` — persist and attach the final plan to OrgX entities +- `mcp__orgx__scaffold_initiative` — create initiative hierarchies in one step - `mcp__orgx__create_entity` — create initiatives, workstreams, milestones, tasks - `mcp__orgx__entity_action` — launch, complete, or update entity status +- `mcp__orgx__comment_on_entity` — write unblock requests, reviews, and coordination notes +- `mcp__orgx__check_spawn_guard` — verify delegation is allowed before agent spawn - `mcp__orgx__spawn_agent_task` — delegate work to domain agents - `mcp__orgx__orgx_emit_activity` — emit progress checkpoints and status updates - `mcp__orgx__orgx_apply_changeset` — batch state updates (idempotent, transactional) diff --git a/orchestrator-agent/skill.toml b/orchestrator-agent/skill.toml index 7358516..70a00e3 100644 --- a/orchestrator-agent/skill.toml +++ b/orchestrator-agent/skill.toml @@ -2,6 +2,6 @@ name = "orchestrator-agent" version = "2.0.0" description = "Coordinate high-confidence cross-domain execution in OrgX by creating initiatives, delegating to domain agents, and synthesizing outputs. Produces initiative plans, delegation messages, synthesis reports, retrospectives, dependency audits, resource allocations, risk registers, stakeholder updates, and program status reports. Use when work spans multiple teams or requires explicit dependency, sequencing, and quality coordination." entry_instructions = "SKILL.md" -required_tools = ["mcp__orgx__create_entity", "mcp__orgx__entity_action", "mcp__orgx__get_initiative_pulse", "mcp__orgx__get_relevant_learnings", "mcp__orgx__list_entities", "mcp__orgx__orgx_apply_changeset", "mcp__orgx__orgx_emit_activity", "mcp__orgx__query_org_memory", "mcp__orgx__record_outcome", "mcp__orgx__record_quality_score", "mcp__orgx__recommend_next_action", "mcp__orgx__spawn_agent_task", "mcp__orgx__submit_learning"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__get_task_with_context", "mcp__orgx__query_org_memory", "mcp__orgx__list_entities", "mcp__orgx__start_plan_session", "mcp__orgx__improve_plan", "mcp__orgx__record_plan_edit", "mcp__orgx__complete_plan", "mcp__orgx__scaffold_initiative", "mcp__orgx__create_entity", "mcp__orgx__entity_action", "mcp__orgx__comment_on_entity", "mcp__orgx__check_spawn_guard", "mcp__orgx__get_initiative_pulse", "mcp__orgx__get_relevant_learnings", "mcp__orgx__orgx_apply_changeset", "mcp__orgx__orgx_emit_activity", "mcp__orgx__record_outcome", "mcp__orgx__record_quality_score", "mcp__orgx__recommend_next_action", "mcp__orgx__spawn_agent_task", "mcp__orgx__submit_learning"] required_scopes = [] resources = ["examples/initiative-plan.md", "examples/delegation-message.md", "reference/orchestration-frameworks-cheatsheet.md", "reference/delegation-template.md", "reference/raci-template.md", "evaluations/orchestrator-evaluation.json"] diff --git a/product-agent/SKILL.md b/product-agent/SKILL.md index c066b67..12fab29 100644 --- a/product-agent/SKILL.md +++ b/product-agent/SKILL.md @@ -9,15 +9,17 @@ description: | ## Quick Start -1. Confirm the artifact type (`--type`) and the target audience. -2. Pull OrgX context with `mcp__orgx__list_entities` and `mcp__orgx__query_org_memory`. -3. Check flywheel learnings with `mcp__orgx__get_relevant_learnings` for the product domain. -4. Produce the artifact using the contract below and return: +1. Run `mcp__orgx__orgx_bootstrap`, then resolve the active workspace with `mcp__orgx__workspace`. +2. Confirm the artifact type (`--type`) and the target audience. If the request is task-bound, hydrate it with `mcp__orgx__get_task_with_context`; otherwise pull surrounding context with `mcp__orgx__list_entities`. +3. Pull precedent with `mcp__orgx__query_org_memory` and `mcp__orgx__get_relevant_learnings`. +4. If the output is a plan, start a planning loop with `mcp__orgx__start_plan_session`, refine with `mcp__orgx__improve_plan`, record material revisions with `mcp__orgx__record_plan_edit`, and close it with `mcp__orgx__complete_plan` using `attach_to`. +5. Produce the artifact using the contract below and return: - A concise summary (3-6 bullets) - The artifact body (JSON or structured Markdown) - 3 actionable next steps with owners -5. Validate with `python3 scripts/validate_artifact.py --type `. -6. Publish via `mcp__orgx__create_entity` and record quality via `mcp__orgx__record_quality_score`. +6. Validate with `python3 scripts/validate_artifact.py --type `. +7. Publish via `mcp__orgx__create_entity`, attach evidence back to the task or initiative with `mcp__orgx__entity_action` (`action=attach`) or `mcp__orgx__comment_on_entity`, and record quality via `mcp__orgx__record_quality_score`. +8. Before delegating follow-on execution, run `mcp__orgx__check_spawn_guard`, then use `mcp__orgx__spawn_agent_task`. Create product artifacts that are decision-ready, measurable, and execution-aligned. @@ -350,24 +352,35 @@ After every artifact is finalized and published: ## Operating Workflow -1. Select `artifact_type` and confirm decision scope with the requester. -2. Run Context Adaptation Protocol — detect the product stage and adjust behavior. -3. Gather evidence: +1. Run `mcp__orgx__orgx_bootstrap` and resolve workspace with `mcp__orgx__workspace`. +2. Select `artifact_type` and confirm decision scope with the requester. +3. Hydrate the active task or parent entity: + - Use `mcp__orgx__get_task_with_context` for task-bound work + - Use `mcp__orgx__list_entities` for nearby initiatives, milestones, workstreams, or prior artifacts +4. Run Context Adaptation Protocol and detect the product stage. +5. Gather evidence: - OrgX context: `mcp__orgx__query_org_memory`, `mcp__orgx__list_entities` - Flywheel learnings: `mcp__orgx__get_relevant_learnings`, `mcp__orgx__query_org_memory` with `scope: "decisions"` - Work planning context: `mcp__linear__*` when available - User signal context: `mcp__intercom__search` when available -4. Draft JSON-first artifact applying the Domain Expertise Canon. -5. Run the Precision Loop (see below). -6. Validate: +6. For planning-heavy outputs, open a plan session with `mcp__orgx__start_plan_session`, iterate with `mcp__orgx__improve_plan`, and record substantive edits with `mcp__orgx__record_plan_edit`. +7. Draft JSON-first artifact applying the Domain Expertise Canon. +8. Run the Precision Loop (see below). +9. Validate: ```bash python3 scripts/validate_artifact.py --type ``` -7. Resolve all validator errors. -8. Publish via `mcp__orgx__create_entity` and record quality via `mcp__orgx__record_quality_score`. -9. Submit learnings via `mcp__orgx__submit_learning`. +10. Resolve all validator errors. +11. Publish via `mcp__orgx__create_entity`. +12. Attach proof or summaries back to the triggering entity: + - `mcp__orgx__complete_plan` with `attach_to` for plan-session outputs + - `mcp__orgx__entity_action` with `action=attach` for artifacts, research notes, and handoff docs + - `mcp__orgx__comment_on_entity` for review notes or decision annotations +13. Record quality via `mcp__orgx__record_quality_score`. +14. Submit learnings via `mcp__orgx__submit_learning`. +15. Before delegating implementation or research, run `mcp__orgx__check_spawn_guard`, then use `mcp__orgx__spawn_agent_task`. --- @@ -385,13 +398,21 @@ python3 scripts/validate_artifact.py --type ### Primary +- `mcp__orgx__orgx_bootstrap` — initialize the current OrgX session and recommended workflow +- `mcp__orgx__workspace` — resolve or switch workspace scope before reading or writing +- `mcp__orgx__get_task_with_context` — hydrate task-bound context attachments and prior plan sessions - `mcp__orgx__query_org_memory` — retrieve organizational context and prior decisions - `mcp__orgx__list_entities` — discover existing initiatives, workstreams, tasks +- `mcp__orgx__start_plan_session` — open a tracked planning session for plan-shaped work +- `mcp__orgx__improve_plan` — refine a draft plan using historical patterns +- `mcp__orgx__record_plan_edit` — log significant planning revisions +- `mcp__orgx__complete_plan` — persist the final plan and attach it to OrgX entities - `mcp__orgx__create_entity` — publish completed artifacts -- `mcp__orgx__spawn_agent_task` — assign follow-up work to other agents - `mcp__orgx__entity_action` — update entity status and properties +- `mcp__orgx__comment_on_entity` — leave review notes on the active task or initiative +- `mcp__orgx__check_spawn_guard` — verify delegation is allowed before spawning follow-on work +- `mcp__orgx__spawn_agent_task` — assign follow-up work to other agents - `mcp__orgx__get_relevant_learnings` — retrieve flywheel learnings for context -- `mcp__orgx__query_org_memory` — retrieve prior decisions and organizational precedent - `mcp__orgx__submit_learning` — record new learnings - `mcp__orgx__record_quality_score` — record artifact quality assessment - `mcp__orgx__get_initiative_pulse` — understand initiative momentum diff --git a/product-agent/skill.toml b/product-agent/skill.toml index 6091f50..189c0b0 100644 --- a/product-agent/skill.toml +++ b/product-agent/skill.toml @@ -2,6 +2,6 @@ name = "product-agent" version = "2.0.0" description = "Produce high-confidence product artifacts for OrgX: PRDs, initiative plans, product canvases, user research briefs, competitive analyses, feature prioritization matrices, pivot evaluations, metric dashboard specs, and launch readiness checklists. Use when problem framing, user/value articulation, prioritization, and measurable product outcomes are required." entry_instructions = "SKILL.md" -required_tools = ["mcp__orgx__create_entity", "mcp__orgx__entity_action", "mcp__orgx__list_entities", "mcp__orgx__query_org_memory", "mcp__orgx__spawn_agent_task", "mcp__orgx__get_relevant_learnings", "mcp__orgx__submit_learning", "mcp__orgx__record_quality_score", "mcp__orgx__get_initiative_pulse"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__get_task_with_context", "mcp__orgx__query_org_memory", "mcp__orgx__list_entities", "mcp__orgx__start_plan_session", "mcp__orgx__improve_plan", "mcp__orgx__record_plan_edit", "mcp__orgx__complete_plan", "mcp__orgx__create_entity", "mcp__orgx__entity_action", "mcp__orgx__comment_on_entity", "mcp__orgx__check_spawn_guard", "mcp__orgx__spawn_agent_task", "mcp__orgx__get_relevant_learnings", "mcp__orgx__submit_learning", "mcp__orgx__record_quality_score", "mcp__orgx__get_initiative_pulse"] required_scopes = [] resources = [] diff --git a/sales-agent/SKILL.md b/sales-agent/SKILL.md index a0656ab..1cbf88b 100644 --- a/sales-agent/SKILL.md +++ b/sales-agent/SKILL.md @@ -9,14 +9,17 @@ description: | ## Quick Start -1. Confirm the artifact or decision type and the target audience. -2. Pull OrgX context with `mcp__orgx__list_entities` and `mcp__orgx__query_org_memory`. -3. Adapt behavior to deal segment and motion using the Context Adaptation Protocol below. -4. Produce the artifact using the contract below and return: +1. Run `mcp__orgx__orgx_bootstrap`, then resolve workspace scope with `mcp__orgx__workspace`. +2. Confirm the artifact or decision type and the target audience. If the request is task-bound, hydrate it with `mcp__orgx__get_task_with_context`; otherwise map related deal work with `mcp__orgx__list_entities`. +3. Pull precedent with `mcp__orgx__query_org_memory` and `mcp__orgx__get_relevant_learnings`. +4. For deal plans, QBRs, or territory programs, use the planning loop: `mcp__orgx__start_plan_session`, `mcp__orgx__improve_plan`, `mcp__orgx__record_plan_edit`, then `mcp__orgx__complete_plan`. +5. Adapt behavior to deal segment and motion using the Context Adaptation Protocol below. +6. Produce the artifact using the contract below and return: - A concise summary (3-6 bullets) - The artifact body (JSON or structured Markdown) - 3 actionable next steps with owners and dates -5. Run the Precision Loop before finalizing. +7. Run the Precision Loop before finalizing. +8. Attach the result back to the active work with `mcp__orgx__entity_action` (`action=attach`) or `mcp__orgx__comment_on_entity`, then record quality with `mcp__orgx__record_quality_score`. Create revenue-focused sales artifacts that are specific, evidence-backed, and execution-ready. Every claim must have proof or an explicit confidence level. Every action must have an owner. @@ -418,23 +421,34 @@ Before producing any artifact, query learnings via `mcp__orgx__get_relevant_lear ## Operating Workflow -1. Select `artifact_type`. -2. Run Context Adaptation Protocol to determine segment, motion, and complexity level. -3. Gather evidence: +1. Run `mcp__orgx__orgx_bootstrap` and resolve workspace with `mcp__orgx__workspace`. +2. Select `artifact_type`. +3. Hydrate the active task or deal context: + - `mcp__orgx__get_task_with_context` for task-bound sales work + - `mcp__orgx__list_entities` for related initiatives, prior proposals, and deal artifacts +4. Run Context Adaptation Protocol to determine segment, motion, and complexity level. +5. Gather evidence: - OrgX historical context via `mcp__orgx__query_org_memory` - Recent learnings via `mcp__orgx__get_relevant_learnings` - CRM/call context via `mcp__salesforce__*` and `mcp__gong__*` when available -4. Apply relevant frameworks from the Domain Expertise Canon. -5. Draft JSON-first artifact per the contract above. -6. Run Precision Loop (below). -7. Validate: +6. For sequences, account plans, or QBRs, open a plan session with `mcp__orgx__start_plan_session`, refine with `mcp__orgx__improve_plan`, and record substantive revisions with `mcp__orgx__record_plan_edit`. +7. Apply relevant frameworks from the Domain Expertise Canon. +8. Draft JSON-first artifact per the contract above. +9. Run Precision Loop (below). +10. Validate: ```bash python3 scripts/validate_sales.py --type ``` -8. Resolve all validator errors and publish with `mcp__orgx__create_entity`. -9. Record learnings via `mcp__orgx__submit_learning`. +11. Resolve all validator errors and publish with `mcp__orgx__create_entity`. +12. Attach proof or conclusions back to the active work: + - `mcp__orgx__complete_plan` with `attach_to` for plan sessions + - `mcp__orgx__entity_action` with `action=attach` for battlecards, sequences, and pricing docs + - `mcp__orgx__comment_on_entity` for coaching notes and decision annotations +13. Record learnings via `mcp__orgx__submit_learning`. +14. Record artifact quality via `mcp__orgx__record_quality_score`. +15. Before delegating prospecting or follow-up work, run `mcp__orgx__check_spawn_guard`, then use `mcp__orgx__spawn_agent_task`. --- @@ -471,12 +485,23 @@ Every artifact must pass all four passes before delivery. Primary: +- `mcp__orgx__orgx_bootstrap` -- initialize OrgX session scope and recommended workflow +- `mcp__orgx__workspace` -- resolve or switch workspace scope +- `mcp__orgx__get_task_with_context` -- hydrate task-bound context, attachments, and plan sessions - `mcp__orgx__query_org_memory` -- pull deal history, past artifacts, org context - `mcp__orgx__list_entities` -- list existing deals, initiatives, tasks +- `mcp__orgx__start_plan_session` -- open tracked planning sessions for sequences, QBRs, and territory plans +- `mcp__orgx__improve_plan` -- refine sales plans with historical patterns +- `mcp__orgx__record_plan_edit` -- capture major planning revisions +- `mcp__orgx__complete_plan` -- finalize and attach the plan to OrgX entities - `mcp__orgx__create_entity` -- publish completed artifacts +- `mcp__orgx__entity_action` -- attach evidence and update entity state +- `mcp__orgx__comment_on_entity` -- leave coaching notes and deal annotations on active work +- `mcp__orgx__check_spawn_guard` -- verify delegation is allowed before handoff - `mcp__orgx__spawn_agent_task` -- delegate sub-tasks to other agents - `mcp__orgx__submit_learning` -- record deal learnings for the flywheel - `mcp__orgx__get_relevant_learnings` -- pull learnings from past deals +- `mcp__orgx__record_quality_score` -- record artifact quality for calibration - `mcp__orgx__get_org_snapshot` -- understand current org state and priorities Optional (if configured): diff --git a/sales-agent/skill.toml b/sales-agent/skill.toml index 720aece..47dd7db 100644 --- a/sales-agent/skill.toml +++ b/sales-agent/skill.toml @@ -1,7 +1,7 @@ name = "sales-agent" -version = "1.0.0" +version = "2.0.0" description = "Produce high-confidence sales artifacts for OrgX: competitive battlecards, MEDDIC deal scorecards, and outreach sequences. Use when deal qualification, competitive positioning, stakeholder persuasion, or revenue-risk reduction is needed." entry_instructions = "SKILL.md" -required_tools = ["mcp__orgx__create_entity", "mcp__orgx__list_entities", "mcp__orgx__query_org_memory", "mcp__orgx__spawn_agent_task"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__get_task_with_context", "mcp__orgx__query_org_memory", "mcp__orgx__list_entities", "mcp__orgx__get_relevant_learnings", "mcp__orgx__start_plan_session", "mcp__orgx__improve_plan", "mcp__orgx__record_plan_edit", "mcp__orgx__complete_plan", "mcp__orgx__create_entity", "mcp__orgx__entity_action", "mcp__orgx__comment_on_entity", "mcp__orgx__check_spawn_guard", "mcp__orgx__spawn_agent_task", "mcp__orgx__submit_learning", "mcp__orgx__record_quality_score", "mcp__orgx__get_org_snapshot"] required_scopes = [] resources = [] diff --git a/scripts/check_skill_tool_drift.py b/scripts/check_skill_tool_drift.py new file mode 100644 index 0000000..b35df96 --- /dev/null +++ b/scripts/check_skill_tool_drift.py @@ -0,0 +1,210 @@ +#!/usr/bin/env python3 +"""Validate OrgX skill docs against the current MCP tool surface.""" + +from __future__ import annotations + +import re +import sys +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +SKILL_DIRS = sorted( + path for path in ROOT.iterdir() if path.is_dir() and (path / "SKILL.md").exists() +) +FILE_NAMES = ("SKILL.md", "instructions.md", "skill.toml") +ORGX_TOOL_RE = re.compile(r"mcp__orgx__([a-zA-Z0-9_]+)") +STRING_RE = re.compile(r'"([^"]+)"') + +KNOWN_ORGX_TOOLS = { + "account_status", + "account_upgrade", + "account_usage_report", + "approve_decision", + "batch_action", + "batch_create_entities", + "batch_delete_entities", + "check_spawn_guard", + "classify_task_model", + "comment_on_entity", + "complete_plan", + "configure_org", + "create_decision", + "create_entity", + "create_milestone", + "create_task", + "entity_action", + "get_active_sessions", + "get_agent_status", + "get_decision_history", + "get_initiative_pulse", + "get_initiative_stream_state", + "get_morning_brief", + "get_my_trust_context", + "get_org_snapshot", + "get_outcome_attribution", + "get_pending_decisions", + "get_relevant_learnings", + "get_scoring_signals", + "get_task_with_context", + "handoff_task", + "improve_plan", + "list_entities", + "list_entity_comments", + "orgx_apply_changeset", + "orgx_bootstrap", + "orgx_describe_action", + "orgx_describe_tool", + "orgx_emit_activity", + "pin_workstream", + "query_org_memory", + "queue_action", + "recommend_next_action", + "record_outcome", + "record_plan_edit", + "record_quality_score", + "reject_decision", + "resume_plan_session", + "scaffold_initiative", + "score_next_up_queue", + "scoring_config", + "spawn_agent_task", + "start_autonomous_session", + "start_plan_session", + "stats", + "submit_learning", + "sync_client_state", + "update_entity", + "update_stream_progress", + "validate_studio_content", + "verify_entity_completion", + "workspace", +} + +DEPRECATED_ORGX_TOOLS = { + "complete_entity", + "get_decision_history", + "get_pending_decisions", + "launch_entity", + "pause_entity", + "score_next_up_queue", +} + +PLAN_TOOLS = {"start_plan_session", "improve_plan", "record_plan_edit"} + + +def read_text(path: Path) -> str: + return path.read_text(encoding="utf-8") + + +def iter_skill_files(skill_dir: Path) -> list[Path]: + return [path for name in FILE_NAMES if (path := skill_dir / name).exists()] + + +def collect_refs(text: str) -> set[str]: + return set(ORGX_TOOL_RE.findall(text)) + + +def parse_required_tools(skill_toml: Path) -> list[str]: + text = read_text(skill_toml) + match = re.search(r"required_tools\s*=\s*\[(.*?)\]", text, re.DOTALL) + if not match: + return [] + return STRING_RE.findall(match.group(1)) + + +def main() -> int: + errors: list[str] = [] + + for skill_dir in SKILL_DIRS: + combined_refs: set[str] = set() + + for file_path in iter_skill_files(skill_dir): + refs = collect_refs(read_text(file_path)) + combined_refs |= refs + + for ref in sorted(refs): + if ref in DEPRECATED_ORGX_TOOLS: + errors.append( + f"{file_path.relative_to(ROOT)} references deprecated OrgX tool " + f"`mcp__orgx__{ref}`" + ) + elif ref not in KNOWN_ORGX_TOOLS: + errors.append( + f"{file_path.relative_to(ROOT)} references unknown OrgX tool " + f"`mcp__orgx__{ref}`" + ) + + if not combined_refs: + continue + + missing_baseline = {"orgx_bootstrap", "workspace"} - combined_refs + for tool in sorted(missing_baseline): + errors.append( + f"{skill_dir.name} is missing baseline OrgX workflow tool " + f"`mcp__orgx__{tool}` in its skill files" + ) + + if "spawn_agent_task" in combined_refs and "check_spawn_guard" not in combined_refs: + errors.append( + f"{skill_dir.name} references `mcp__orgx__spawn_agent_task` without " + f"`mcp__orgx__check_spawn_guard`" + ) + + if combined_refs & PLAN_TOOLS and "complete_plan" not in combined_refs: + errors.append( + f"{skill_dir.name} references plan-session tools without " + f"`mcp__orgx__complete_plan`" + ) + + skill_toml = skill_dir / "skill.toml" + if skill_toml.exists(): + required_tools = set(parse_required_tools(skill_toml)) + orgx_required = { + tool.removeprefix("mcp__orgx__") + for tool in required_tools + if tool.startswith("mcp__orgx__") + } + + for tool in sorted({"orgx_bootstrap", "workspace"} - orgx_required): + errors.append( + f"{skill_toml.relative_to(ROOT)} is missing required tool " + f"`mcp__orgx__{tool}`" + ) + + if "spawn_agent_task" in orgx_required and "check_spawn_guard" not in orgx_required: + errors.append( + f"{skill_toml.relative_to(ROOT)} declares `mcp__orgx__spawn_agent_task` " + f"without `mcp__orgx__check_spawn_guard`" + ) + + if orgx_required & PLAN_TOOLS and "complete_plan" not in orgx_required: + errors.append( + f"{skill_toml.relative_to(ROOT)} declares plan-session tools without " + f"`mcp__orgx__complete_plan`" + ) + + for tool in sorted(orgx_required): + if tool in DEPRECATED_ORGX_TOOLS: + errors.append( + f"{skill_toml.relative_to(ROOT)} declares deprecated OrgX tool " + f"`mcp__orgx__{tool}`" + ) + elif tool not in KNOWN_ORGX_TOOLS: + errors.append( + f"{skill_toml.relative_to(ROOT)} declares unknown OrgX tool " + f"`mcp__orgx__{tool}`" + ) + + if errors: + print("OrgX skill drift check failed:\n") + for error in errors: + print(f"- {error}") + return 1 + + print(f"OrgX skill drift check passed for {len(SKILL_DIRS)} skills.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/task-protocol/SKILL.md b/task-protocol/SKILL.md index a5daa10..d9183bc 100644 --- a/task-protocol/SKILL.md +++ b/task-protocol/SKILL.md @@ -2,7 +2,8 @@ name: task-protocol description: | Individual task execution protocol for OrgX. Handles task lifecycle from - start through completion with consistent status reporting. + hydration through completion with consistent reporting, evidence attachment, + and spawn-guarded delegation. Use when executing individual tasks within a workstream. --- @@ -10,38 +11,45 @@ description: | ## Starting a Task -- Read task details: `mcp__orgx__list_entities type=task` -- Start: `mcp__orgx__launch_entity type=task` -- Emit kickoff telemetry: `mcp__orgx__orgx_emit_activity` (`phase=intent`) -- Verify prerequisites are met +- Bootstrap with `mcp__orgx__orgx_bootstrap`. +- Confirm or set workspace through `mcp__orgx__workspace`. +- Read the task with `mcp__orgx__get_task_with_context`. +- If you only have an entity ID, use `mcp__orgx__list_entities` with `id` and `hydrate_context=true`. +- Start with `mcp__orgx__entity_action type=task action=launch`. +- Emit kickoff telemetry with `mcp__orgx__orgx_emit_activity phase=intent`. +- Verify prerequisites, context attachments, and acceptance criteria before doing work. ## Executing -- Follow domain-specific workflows from your skill -- For each meaningful step, emit telemetry: `mcp__orgx__orgx_emit_activity` (`phase=execution`) -- Create artifacts as needed: `mcp__orgx__create_entity type=artifact` -- Batch state mutations through `mcp__orgx__orgx_apply_changeset` (do not do per-entity reporting writes) +- Follow the domain-specific workflow from the active skill. +- Emit progress with `mcp__orgx__orgx_emit_activity` at meaningful milestones. +- Use `mcp__orgx__entity_action action=attach` to link docs, URLs, plans, PRs, screenshots, or other proof back to the task. +- If the work starts as planning, run: + - `mcp__orgx__start_plan_session` + - `mcp__orgx__improve_plan` + - `mcp__orgx__record_plan_edit` for major revisions + - `mcp__orgx__complete_plan attach_to=[{ entity_type: "task", entity_id: ... }]` ## Handling Blockers -- Block: `mcp__orgx__pause_entity type=task` -- Document the blocker clearly -- Emit blocker telemetry: `mcp__orgx__orgx_emit_activity` (`phase=blocked`) -- Escalate if cross-domain: `mcp__orgx__spawn_agent_task` to relevant agent +- Pause with `mcp__orgx__entity_action type=task action=pause note="..."`. +- Document the blocker clearly with `mcp__orgx__comment_on_entity`. +- Emit blocker telemetry with `mcp__orgx__orgx_emit_activity phase=blocked`. +- Before cross-domain delegation, call `mcp__orgx__check_spawn_guard`. +- Use `mcp__orgx__spawn_agent_task` or `mcp__orgx__handoff_task` only after the guard passes. ## Completing -- Validate output against acceptance criteria -- Run domain-specific quality gates -- Verify readiness: `mcp__orgx__verify_entity_completion type=task` -- Complete via changeset when possible: `mcp__orgx__orgx_apply_changeset` (`task.update`, `milestone.update`, `decision.create` as needed) -- Emit final telemetry: `mcp__orgx__orgx_emit_activity` (`phase=completed`, `progress_pct=100`) -- Complete: `mcp__orgx__complete_entity type=task` -- Link artifacts to task for traceability +- Validate output against acceptance criteria. +- Run domain-specific quality gates. +- Verify readiness with `mcp__orgx__verify_entity_completion type=task`. +- Attach final proof if anything is still only in the transcript. +- Emit final telemetry with `mcp__orgx__orgx_emit_activity phase=completed progress_pct=100`. +- Complete with `mcp__orgx__entity_action type=task action=complete`. ## Task Types -- `research`: Gather information, analyze options -- `create`: Produce new artifact (RFC, PRD, campaign, etc.) -- `review`: Evaluate existing work, provide feedback -- `implement`: Execute technical changes +- `research`: gather information, analyze options +- `create`: produce a new artifact +- `review`: evaluate existing work and comment on it +- `implement`: execute technical or operational changes diff --git a/task-protocol/skill.toml b/task-protocol/skill.toml index efe0248..563adec 100644 --- a/task-protocol/skill.toml +++ b/task-protocol/skill.toml @@ -1,7 +1,7 @@ name = "task-protocol" -version = "1.0.0" -description = "Individual task execution protocol for OrgX. Handles task lifecycle from start through completion with consistent status reporting. Use when executing individual tasks within a workstream." +version = "2.0.0" +description = "Individual task execution protocol for OrgX with context hydration, plan-session handoff, evidence attachment, guarded delegation, and completion verification." entry_instructions = "SKILL.md" -required_tools = ["mcp__orgx__complete_entity", "mcp__orgx__create_entity", "mcp__orgx__launch_entity", "mcp__orgx__list_entities", "mcp__orgx__orgx_apply_changeset", "mcp__orgx__orgx_emit_activity", "mcp__orgx__pause_entity", "mcp__orgx__spawn_agent_task", "mcp__orgx__verify_entity_completion"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__get_task_with_context", "mcp__orgx__list_entities", "mcp__orgx__entity_action", "mcp__orgx__orgx_emit_activity", "mcp__orgx__comment_on_entity", "mcp__orgx__check_spawn_guard", "mcp__orgx__spawn_agent_task", "mcp__orgx__handoff_task", "mcp__orgx__verify_entity_completion", "mcp__orgx__start_plan_session", "mcp__orgx__improve_plan", "mcp__orgx__record_plan_edit", "mcp__orgx__complete_plan"] required_scopes = [] resources = [] diff --git a/workstream-protocol/SKILL.md b/workstream-protocol/SKILL.md index 1f26e6c..adb39e9 100644 --- a/workstream-protocol/SKILL.md +++ b/workstream-protocol/SKILL.md @@ -2,8 +2,9 @@ name: workstream-protocol description: | Stream execution lifecycle for OrgX workstreams. Handles initialization, - progress reporting, blocker management, and completion with DAG resolution. - Use when executing work within an OrgX initiative stream. + progress reporting, blocker management, evidence attachment, and completion + with DAG-aware sequencing. Use when executing work within an OrgX initiative + stream. --- # Workstream Execution Protocol @@ -12,35 +13,37 @@ description: | ### 1. Initialize -- Read stream: `mcp__orgx__list_entities type=stream` -- Check deps: `mcp__orgx__get_initiative_stream_state` -- Verify status is 'ready' or 'active' before proceeding -- Report 0% progress: `mcp__orgx__update_stream_progress` +- Bootstrap with `mcp__orgx__orgx_bootstrap`. +- Confirm or set workspace through `mcp__orgx__workspace`. +- Read the stream with `mcp__orgx__list_entities type=stream`. +- Check upstream and downstream pressure with `mcp__orgx__get_initiative_stream_state`. +- If the stream is ready to start, use `mcp__orgx__entity_action type=stream action=launch`. +- Report 0% progress via `mcp__orgx__update_stream_progress`. ### 2. Execute -- Follow your domain skill workflows -- Report progress at meaningful milestones (25%, 50%, 75%) -- Progress and confidence are SEPARATE: - - `progress_pct` (0-100): How much work is done - - `confidence` (0-1): How confident you are in the output quality -- Include `status_note` for human visibility -- Use `expected_version` for optimistic locking +- Follow the relevant domain skill workflow. +- Report progress at meaningful milestones. +- Progress and confidence are separate: + - `progress_pct`: how much work is done + - `confidence`: how confident you are in the current output +- Attach important outputs to the stream or its tasks with `mcp__orgx__entity_action action=attach`. ### 3. Handle Blockers -- If blocked: `mcp__orgx__entity_action type=stream action=block` -- Always include `blocked_reason` -- Spawn tasks for unresolved deps: `mcp__orgx__spawn_agent_task` +- Pause or block with `mcp__orgx__entity_action type=stream action=pause note="..."`. +- Use `mcp__orgx__comment_on_entity` for detailed blocker context. +- Before delegating new work, call `mcp__orgx__check_spawn_guard`. +- Use `mcp__orgx__spawn_agent_task` or `mcp__orgx__handoff_task` only after the guard passes. ### 4. Complete -- Run domain-specific validation (quality gates) -- Verify readiness: `mcp__orgx__verify_entity_completion type=workstream` -- Complete: `mcp__orgx__complete_entity type=stream` -- This triggers DAG resolution: downstream streams become 'ready' +- Run domain-specific validation. +- Verify readiness with `mcp__orgx__verify_entity_completion type=workstream`. +- Complete with `mcp__orgx__entity_action type=stream action=complete`. +- Downstream streams should move because the DAG is now unblocked; verify with `mcp__orgx__get_initiative_stream_state`. ### 5. Error Handling -- Recoverable: set confidence to 0.5, add status_note, continue -- Unrecoverable: block stream with reason, never silently fail +- Recoverable issue: lower confidence, document status, continue. +- Unrecoverable issue: pause the stream and make the blocker explicit on the entity. diff --git a/workstream-protocol/skill.toml b/workstream-protocol/skill.toml index 34f3afc..2151cd8 100644 --- a/workstream-protocol/skill.toml +++ b/workstream-protocol/skill.toml @@ -1,7 +1,7 @@ name = "workstream-protocol" -version = "1.0.0" -description = "Stream execution lifecycle for OrgX workstreams. Handles initialization, progress reporting, blocker management, and completion with DAG resolution. Use when executing work within an OrgX initiative stream." +version = "2.0.0" +description = "Stream execution lifecycle for OrgX workstreams with DAG-aware monitoring, evidence attachment, guarded delegation, and completion verification." entry_instructions = "SKILL.md" -required_tools = ["mcp__orgx__complete_entity", "mcp__orgx__entity_action", "mcp__orgx__get_initiative_stream_state", "mcp__orgx__list_entities", "mcp__orgx__spawn_agent_task", "mcp__orgx__update_stream_progress", "mcp__orgx__verify_entity_completion"] +required_tools = ["mcp__orgx__orgx_bootstrap", "mcp__orgx__workspace", "mcp__orgx__entity_action", "mcp__orgx__get_initiative_stream_state", "mcp__orgx__list_entities", "mcp__orgx__check_spawn_guard", "mcp__orgx__spawn_agent_task", "mcp__orgx__handoff_task", "mcp__orgx__update_stream_progress", "mcp__orgx__verify_entity_completion", "mcp__orgx__comment_on_entity"] required_scopes = [] resources = []