codeply-cli 0.5.5 → 0.6.0

package/skills/team-agent-orchestration/SKILL.md

@@ -1,111 +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."
-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.
+---
+name: team-agent-orchestration
+description: "Run team-based orchestration for agent squads using work items, ownership, agent Kanban, merge gates, and control pane handoffs."
+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/skills/team-builder/SKILL.md

@@ -1,169 +1,169 @@
----
-name: team-builder
-description: Interactive agent picker for composing and dispatching parallel teams
-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: [...]
-```
+---
+name: team-builder
+description: Interactive agent picker for composing and dispatching parallel teams
+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: [...]
+```