ctxora 6.2.2 → 6.3.0

package/src/harness_context/skills/ecc/team-agent-orchestration/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: team-agent-orchestration
+description: "Run team-based orchestration for agent squads using work items, ownership, agent Kanban, merge gates, and control pane handoffs. Use when coordinating an agent squad with work items, ownership, Kanban, and merge gates."
+metadata:
+  origin: ECC
+---
+
+# Team Agent Orchestration
+
+Use this skill when agents are being managed like a team rather than a single assistant. The purpose is to make team-based orchestration reliable: clear work items, explicit ownership, agent Kanban state, branch isolation, control pane visibility, and merge gates.
+
+## When To Activate
+
+- The task spans multiple agents, tools, harnesses, branches, or worktrees.
+- The user mentions team orchestration, agent Kanban, squad, conductor, control pane, manager, desktop app, Zellij, tmux, Hermes, Devin, Codex, Claude Code, or multi-agent work.
+- A project needs shared workflow state across people and agents.
+- Existing agent fan-out is producing output but not mergeable product.
+
+## Operating Model
+
+Treat every agent as a teammate with a narrow contract:
+
+- **Owner**: the person or agent accountable for the work item.
+- **Scope**: files, branch, tool surface, and forbidden areas.
+- **State**: backlog, ready, running, review, blocked, merged, or archived.
+- **Evidence**: tests, screenshots, logs, review notes, or eval reports.
+- **Merge gate**: the exact condition that allows integration.
+
+## Agent Kanban
+
+Use agent Kanban when work must be visible across sessions.
+
+| Column | Meaning | Exit Criteria |
+| --- | --- | --- |
+| Backlog | Candidate work item, not yet shaped | Acceptance criteria written |
+| Ready | Shaped and assignable | Owner and branch/worktree assigned |
+| Running | Agent is actively working | Handoff artifact and changed files exist |
+| Review | Work is complete but not merged | Tests, diff review, and risk check pass |
+| Blocked | Needs external input or failed gate | Blocker has owner and next action |
+| Merged | Integrated into mainline | PR merged or local main updated |
+| Archived | No longer relevant | Reason recorded |
+
+Each card should fit this schema:
+
+```json
+{
+  "id": "agent-card-001",
+  "title": "Build dynamic workflow skill",
+  "owner": "codex",
+  "state": "running",
+  "branch": "product/dynamic-workflow-team-orchestration",
+  "worktree": ".",
+  "acceptance": [
+    "Skill exists",
+    "Tests cover required concepts",
+    "Content artifact contains video and article angles"
+  ],
+  "merge_gate": "lint, focused tests, and catalog check pass",
+  "handoff": "path/to/handoff.md"
+}
+```
+
+## Team-Based Orchestration Flow
+
+1. **Shape the board**: convert fuzzy ambition into work items with owners and merge gates.
+2. **Pick execution mode**: single-agent, dynamic workflow mode, dmux/tmux, worktree fan-out, or external desktop orchestrator.
+3. **Assign boundaries**: one owner per card, clear file scope, and no overlapping writes without an integrator.
+4. **Run agents**: each agent writes evidence and handoff notes, not just code.
+5. **Review in sequence**: tests first, then diff review, then security/risk checks, then content/product polish.
+6. **Merge deliberately**: one integrator resolves conflicts and updates the control pane or status artifact.
+7. **Extract reusable skill**: if the card pattern repeats, promote it into `skills/`.
+
+## Control Pane Requirements
+
+A useful control pane for team orchestration should show:
+
+- Active work items and their agent Kanban state.
+- Owner, harness, branch, worktree, and last heartbeat.
+- Links to handoff artifacts, tests, screenshots, and PRs.
+- Blockers grouped by owner and unblock action.
+- Merge readiness by gate, not vibes.
+- Reusable workflow candidates that should become shared skills.
+
+Do not add more automation until the operator can answer: who owns this, what changed, what gate failed, and what can safely merge?
+
+## Dynamic Workflow Compatibility
+
+When a card needs dynamic workflow mode:
+
+- Put the task-local harness under the card owner.
+- Store inputs and outputs on the card.
+- Require an eval before moving from Running to Review.
+- Promote the harness to a shared skill only after repeat use.
+
+## Failure Modes To Watch
+
+- **Agent soup**: many agents running, no owner or merge gate.
+- **Invisible work**: useful output exists only in a chat transcript.
+- **Board theater**: a Kanban board exists but cards have no acceptance criteria.
+- **Overlapping writes**: parallel agents edit the same files without worktrees.
+- **No product artifact**: the process produces docs but no runnable or publishable surface.
+
+## Output Standard
+
+Finish each orchestration pass with:
+
+- Board/card changes.
+- Merged or pending branches.
+- Tests and eval evidence.
+- Blockers with owner and next action.
+- New shared skill candidates.

package/src/harness_context/skills/ecc/team-builder/LICENSE.ecc

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/harness_context/skills/ecc/team-builder/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: team-builder
+description: Interactive agent picker for composing and dispatching parallel teams. Use when composing and dispatching a parallel team of agents for a task.
+metadata:
+  origin: community
+---
+
+# Team Builder
+
+Interactive menu for browsing and composing agent teams on demand. Works with flat or domain-subdirectory agent collections.
+
+## When to Use
+
+- You have multiple agent personas (markdown files) and want to pick which ones to use for a task
+- You want to compose an ad-hoc team from different domains (e.g., Security + SEO + Architecture)
+- You want to browse what agents are available before deciding
+
+## Prerequisites
+
+Agent files must be markdown files containing a persona prompt (identity, rules, workflow, deliverables). The first `# Heading` is used as the agent name and the first paragraph as the description.
+
+Both flat and subdirectory layouts are supported:
+
+**Subdirectory layout** — domain is inferred from the folder name:
+
+```
+agents/
+├── engineering/
+│   ├── security-engineer.md
+│   └── software-architect.md
+├── marketing/
+│   └── seo-specialist.md
+└── sales/
+    └── discovery-coach.md
+```
+
+**Flat layout** — domain inferred from shared filename prefixes. A prefix counts as a domain when 2+ files share it. Files with unique prefixes go to "General". Note: the algorithm splits at the first `-`, so multi-word domains (e.g., `product-management`) should use the subdirectory layout instead:
+
+```
+agents/
+├── engineering-security-engineer.md
+├── engineering-software-architect.md
+├── marketing-seo-specialist.md
+├── marketing-content-strategist.md
+├── sales-discovery-coach.md
+└── sales-outbound-strategist.md
+```
+
+## Configuration
+
+Agents are discovered via two methods, merged and deduplicated by agent name:
+
+1. **`claude agents` command** (primary) — run `claude agents` to get all agents known to the CLI, including user agents, plugin agents (e.g. `ecc:architect`), and built-in agents. This automatically covers ECC marketplace installs without any path configuration.
+2. **File glob** (fallback, for reading agent content) — agent markdown files are read from:
+   - `./agents/**/*.md` + `./agents/*.md` — project-local agents
+   - `~/.claude/agents/**/*.md` + `~/.claude/agents/*.md` — global user agents
+
+Earlier sources take precedence when names collide: user agents > plugin agents > built-in agents. A custom path can be used instead if the user specifies one.
+
+## How It Works
+
+### Step 1: Discover Available Agents
+
+Run `claude agents` to get the full agent list. Parse each line:
+- **Plugin agents** are prefixed with `plugin-name:` (e.g., `ecc:security-reviewer`). Use the part after `:` as the agent name and the plugin name as the domain.
+- **User agents** have no prefix. Read the corresponding markdown file from `~/.claude/agents/` or `./agents/` to extract the name and description.
+- **Built-in agents** (e.g., `Explore`, `Plan`) are skipped unless the user explicitly asks to include them.
+
+For user agents loaded from markdown files:
+- **Subdirectory layout:** extract the domain from the parent folder name
+- **Flat layout:** collect all filename prefixes (text before the first `-`). A prefix qualifies as a domain only if it appears in 2 or more filenames (e.g., `engineering-security-engineer.md` and `engineering-software-architect.md` both start with `engineering` → Engineering domain). Files with unique prefixes (e.g., `code-reviewer.md`, `tdd-guide.md`) are grouped under "General"
+- Extract the agent name from the first `# Heading`. If no heading is found, derive the name from the filename (strip `.md`, replace hyphens with spaces, title-case)
+- Extract a one-line summary from the first paragraph after the heading
+
+If no agents are found after running `claude agents` and probing file locations, inform the user: "No agents found. Run `claude agents` to verify your setup." Then stop.
+
+### Step 2: Present Domain Menu
+
+```
+Available agent domains:
+1. Engineering — Software Architect, Security Engineer
+2. Marketing — SEO Specialist
+3. Sales — Discovery Coach, Outbound Strategist
+
+Pick domains or name specific agents (e.g., "1,3" or "security + seo"):
+```
+
+- Skip domains with zero agents (empty directories)
+- Show agent count per domain
+
+### Step 3: Handle Selection
+
+Accept flexible input:
+- Numbers: "1,3" selects all agents from Engineering and Sales
+- Names: "security + seo" fuzzy-matches against discovered agents
+- "all from engineering" selects every agent in that domain
+
+If more than 5 agents are selected, list them alphabetically and ask the user to narrow down: "You selected N agents (max 5). Pick which to keep, or say 'first 5' to use the first five alphabetically."
+
+Confirm selection:
+```
+Selected: Security Engineer + SEO Specialist
+What should they work on? (describe the task):
+```
+
+### Step 4: Spawn Agents in Parallel
+
+1. Read each selected agent's markdown file
+2. Prompt for the task description if not already provided
+3. Spawn all agents in parallel using the Agent tool:
+   - `subagent_type: "general-purpose"`
+   - `prompt: "{agent file content}\n\nTask: {task description}"`
+   - Each agent runs independently — no inter-agent communication needed
+4. If an agent fails (error, timeout, or empty output), note the failure inline (e.g., "Security Engineer: failed — [reason]") and continue with results from agents that succeeded
+
+### Step 5: Synthesize Results
+
+Collect all outputs and present a unified report:
+- Results grouped by agent
+- Synthesis section highlighting:
+  - Agreements across agents
+  - Conflicts or tensions between recommendations
+  - Recommended next steps
+
+If only 1 agent was selected, skip synthesis and present the output directly.
+
+## Rules
+
+- **Dynamic discovery only.** Never hardcode agent lists. New files in the directory auto-appear in the menu.
+- **Max 5 agents per team.** More than 5 produces diminishing returns and excessive token usage. Enforce at selection time.
+- **Parallel dispatch.** All agents run simultaneously — use the Agent tool's parallel invocation pattern.
+- **Parallel Agent calls, not TeamCreate.** This skill uses parallel Agent tool calls for independent work. TeamCreate (a Claude Code tool for multi-agent dialogue) is only needed when agents must debate or respond to each other.
+
+## Examples
+
+```
+User: team builder
+
+Claude:
+Available agent domains:
+1. Engineering (2) — Software Architect, Security Engineer
+2. Marketing (1) — SEO Specialist
+3. Sales (4) — Discovery Coach, Outbound Strategist, Proposal Strategist, Sales Engineer
+4. Support (1) — Executive Summary
+
+Pick domains or name specific agents:
+
+User: security + seo
+
+Claude:
+Selected: Security Engineer + SEO Specialist
+What should they work on?
+
+User: Review my Next.js e-commerce site before launch
+
+[Both agents spawn in parallel, each applying their specialty to the codebase]
+
+Claude:
+## Security Engineer Findings
+- [findings...]
+
+## SEO Specialist Findings
+- [findings...]
+
+## Synthesis
+Both agents agree on: [...]
+Tension: Security recommends CSP that blocks inline styles, SEO needs inline schema markup. Resolution: [...]
+Next steps: [...]
+```

package/src/harness_context/skills/ecc/terminal-opener/LICENSE.ecc

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/harness_context/skills/ecc/terminal-opener/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: terminal-opener
+description: Open an executable and its argument array in a visible terminal window through a reusable, shell-free launch plan with dry-run, JSON, capability detection, detached fallback, and standalone recovery modes. Use when Codex needs to open an interactive CLI, SSH session, local development process, sandbox, or other argv-based command in a new host terminal; diagnose whether a supported terminal is available; or provide an actionable plan when the requested terminal is unsupported.
+---
+
+# Terminal Opener
+
+Use `scripts/open-terminal.js` to preserve an executable and every argument as
+separate process entries. Never interpolate a shell command string. Keep every
+spawn on `shell: false`. Default to a non-launching plan. Use `--launch` only
+after the user explicitly requests a real window and the argv has been reviewed.
+The launched process inherits the full environment of the calling process,
+including secret-bearing variables. The launcher does not filter the
+environment. Run it from a shell whose environment is safe to expose to the
+target command.
+
+## Launch a command
+
+Pass launcher options before `--`, then pass exactly one executable followed by
+its argument array:
+
+```bash
+node skills/terminal-opener/scripts/open-terminal.js \
+  --launch \
+  --cwd /absolute/host/path \
+  -- ssh -t example.test command-with-arguments
+```
+
+Run normal mode first. Let WezTerm try its mux with a new window, then let the
+launcher fall back to a detached `wezterm start` process if the mux is not
+available. When fallback is used, read `muxFailure` from JSON output (or the
+human-readable failure line) to diagnose why the mux path failed.
+
+## Recover from terminal configuration
+
+Add `--recover` or `--standalone` when user configuration or mux state may
+interfere with the requested command. Start a detached WezTerm process with:
+
+```text
+--skip-config start --always-new-process
+```
+
+Expect recovery mode to skip all user terminal configuration intentionally.
+
+## Inspect before launch
+
+Omit `--launch` (or add `--dry-run`) and add `--json` to inspect the exact
+executable, argv, working directory, terminal adapter, primary launch, and
+fallback without opening a window. Treat the JSON plan as the composition
+boundary for callers.
+
+Run `--detect --json` without a command to probe terminal availability. Follow
+the returned `action` when the adapter is missing or unsupported. Use WezTerm
+for the current adapter; treat other requested terminals as unsupported plans,
+not as commands to execute.

package/src/harness_context/skills/ecc/terminal-opener/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Terminal Opener"
+  short_description: "Open commands safely in visible terminals"
+  default_prompt: "Use $terminal-opener to open an executable and its argument array in a visible terminal."