From 2f32785ab86eb4a2fdd6d483176ce16b6aaa4072 Mon Sep 17 00:00:00 2001 From: vp Date: Tue, 3 Mar 2026 10:56:16 +0300 Subject: [PATCH 1/2] docs: add complete structured skill coverage --- CLAUDE.md | 50 ++++++++++++++++++++++++++++++++++---------------- README.md | 44 ++++++++++++++++++++++++++++++++++++-------- 2 files changed, 70 insertions(+), 24 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2bbe2fc..bc69b2c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,24 +26,33 @@ skill-name/ ### Skill Types in this Repo -1. **Agent orchestration skills** (`codex-subagent`, `llm-council`, `planner`, `parallel-task`) - - Spawn and coordinate multiple AI agents - - Handle complex multi-step workflows - - Manage parallel task execution - -2. **Documentation access skills** (`context7`, `openai-docs-skill`, `read-github`) - - Fetch up-to-date library docs +1. **Planning skills** (`planner`, `plan-harder`, `swarm-planner`, `llm-council`) + - Produce implementation plans before coding + - Define phased execution and task-level validation + - For `swarm-planner`, enforce explicit `depends_on` dependency maps + +2. **Execution skills** (`parallel-task`, `parallel-task-spark`, `super-swarm-spark`) + - Execute plan files with subagents + - `parallel-task` and `parallel-task-spark` are dependency-aware (unblocked wave execution) + - `super-swarm-spark` is a rolling-pool high-throughput executor + +3. **Documentation access skills** (`context7`, `openai-docs-skill`, `read-github`, `markdown-url`) + - Fetch up-to-date docs and repo references - Query documentation via APIs or MCP servers - - Convert URLs to LLM-friendly formats + - Convert URLs into LLM-friendly formats -3. **Domain expertise skills** (`frontend-design`, `frontend-responsive-ui`, `vercel-react-best-practices`) +4. **Domain expertise skills** (`frontend-design`, `frontend-responsive-ui`, `vercel-react-best-practices`) - Provide specialized patterns and best practices - Imported from authoritative sources (Anthropic, Vercel) -4. **Tool integration skills** (`agent-browser`, `gemini-computer-use`) +5. **Tool integration skills** (`agent-browser`, `gemini-computer-use`) - Browser automation and computer control - Integrate external tools into agent workflows +6. **Workflow utility skills** (`role-creator`, `tdd-test-writer`) + - Manage Codex role configuration + - Support test-first implementation workflows + ## Working with Skills ### Creating New Skills @@ -95,13 +104,22 @@ cp -r ./skills/ ~/.claude/skills/ ## Key Patterns -### Agent Orchestration Pattern +### Planning/Execution Patterns + +- **Planning-first pattern** (`planner`, `plan-harder`, `swarm-planner`, `llm-council`) + - Intake/clarification + - Research and dependency modeling + - Plan generation and review + - No implementation at this stage + +- **Dependency-aware execution pattern** (`parallel-task`, `parallel-task-spark`) + - Parse task graph (`depends_on`) + - Launch only unblocked tasks in parallel waves + - Validate each wave, update plan state, repeat -Skills like `codex-subagent`, `llm-council`, `planner`, and `parallel-task` follow this pattern: -- Intake/clarification phase (ask questions to build context) -- Prompt generation (create detailed prompts for subagents) -- Parallel execution (launch multiple agents via background shells) -- Collection/synthesis (gather results, merge, validate) +- **Rolling-pool execution pattern** (`super-swarm-spark`) + - Keep worker pool saturated for throughput + - Orchestrator resolves conflicts/integration at the tail end **Important for llm-council**: Do NOT yield/finish the response until the full 30-minute timer completes and `final-plan.md` is saved. The session must stay open to prevent premature termination. diff --git a/README.md b/README.md index 71e3501..3002b31 100644 --- a/README.md +++ b/README.md @@ -7,16 +7,25 @@ A collection of Codex/agent skills for planning, documentation access, frontend ## Available skills -### Agent Orchestration +### Planning - `planner`: - Create comprehensive, phased implementation plans with sprints and atomic tasks. Use for planning implementations, breaking down features, or creating structured roadmaps. + Create comprehensive phased plans with sprints, atomic tasks, and validation. - `plan-harder`: - Enhanced planning variant for more detailed analysis and task breakdown. -- `parallel-task`: - Execute plan files by launching multiple parallel subagents to complete tasks simultaneously. Requires an existing plan file from `planner`. + A deeper planning variant for larger or ambiguous implementation scopes. +- `swarm-planner`: + Explicit dependency-aware planner optimized for multi-agent execution. Requires `depends_on` task wiring. - `llm-council`: - Multi-agent orchestration system for planning complex tasks. Spawns multiple AI planners (Claude, Codex, Gemini) to generate independent plans, then uses a judge agent to synthesize the best approach. Includes a real-time web UI for monitoring progress and refining plans interactively. + Multi-agent planning council (multiple planners + judge) that synthesizes one final plan. + +### Execution + +- `parallel-task`: + Dependency-aware executor that runs unblocked tasks in waves based on `depends_on`. +- `parallel-task-spark`: + Same dependency-aware wave execution model as `parallel-task`, but forces Sparky-role workers. +- `super-swarm-spark`: + High-throughput rolling-pool Sparky executor focused on continuous parallel dispatch. ### Documentation Access @@ -40,10 +49,29 @@ A collection of Codex/agent skills for planning, documentation access, frontend ### Browser Automation -- `gemini-computer-use`: - Gemini 2.5 Computer Use browser-control agent skill (Playwright + safety confirmation loop). - `agent-browser`: Fast Rust-based headless browser automation CLI from Vercel Labs with snapshot/act pattern for AI agents. +- `gemini-computer-use`: + Gemini 2.5 Computer Use browser-control agent skill (Playwright + safety confirmation loop). + +### Workflow Utilities + +- `role-creator`: + Create and install custom Codex roles in `~/.codex/config.toml`. +- `tdd-test-writer`: + Generate test-first implementation workflows and TDD-oriented task prompts. + +## Planner/Executor Compatibility + +| Skill | Type | Dependency behavior | Best use | +|------|------|------|------| +| `swarm-planner` | Planner | Strict explicit `depends_on` graph | Build DAG-ready plans for swarm execution | +| `planner` | Planner | Dependency guidance (less strict format) | General phased implementation planning | +| `plan-harder` | Planner | Dependency guidance (deeper decomposition) | Complex planning with tighter task granularity | +| `llm-council` | Planner orchestrator | Planner-level only, no code execution | Multi-model plan synthesis and adjudication | +| `parallel-task` | Executor | Dependency-aware wave execution | Safe/default executor for dependency graphs | +| `parallel-task-spark` | Executor | Dependency-aware wave execution | Same as above, pinned to Sparky workers | +| `super-swarm-spark` | Executor | Rolling pool with relationship metadata for awareness | Max throughput execution with stronger conflict-management needs | ## Installation From 88626e2e40899c8bc51fc303a066089ae3e54fd5 Mon Sep 17 00:00:00 2001 From: vp Date: Tue, 3 Mar 2026 11:04:21 +0300 Subject: [PATCH 2/2] docs: clarify super-swarm-spark dependency semantics --- CLAUDE.md | 5 +++-- README.md | 4 ++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index bc69b2c..d8e653b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,7 +34,7 @@ skill-name/ 2. **Execution skills** (`parallel-task`, `parallel-task-spark`, `super-swarm-spark`) - Execute plan files with subagents - `parallel-task` and `parallel-task-spark` are dependency-aware (unblocked wave execution) - - `super-swarm-spark` is a rolling-pool high-throughput executor + - `super-swarm-spark` is a rolling-pool high-throughput executor that intentionally ignores dependency maps and expects orchestrator-side conflict resolution 3. **Documentation access skills** (`context7`, `openai-docs-skill`, `read-github`, `markdown-url`) - Fetch up-to-date docs and repo references @@ -119,7 +119,8 @@ cp -r ./skills/ ~/.claude/skills/ - **Rolling-pool execution pattern** (`super-swarm-spark`) - Keep worker pool saturated for throughput - - Orchestrator resolves conflicts/integration at the tail end + - Relationship metadata is awareness-only (not a launch blocker) + - Orchestrator resolves dependency/integration conflicts at the tail end **Important for llm-council**: Do NOT yield/finish the response until the full 30-minute timer completes and `final-plan.md` is saved. The session must stay open to prevent premature termination. diff --git a/README.md b/README.md index 3002b31..f70dfac 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ A collection of Codex/agent skills for planning, documentation access, frontend - `parallel-task-spark`: Same dependency-aware wave execution model as `parallel-task`, but forces Sparky-role workers. - `super-swarm-spark`: - High-throughput rolling-pool Sparky executor focused on continuous parallel dispatch. + High-throughput rolling-pool Sparky executor focused on continuous parallel dispatch. Intentionally ignores dependency maps; dependency-conflict resolution is delegated to the orchestrator. ### Documentation Access @@ -71,7 +71,7 @@ A collection of Codex/agent skills for planning, documentation access, frontend | `llm-council` | Planner orchestrator | Planner-level only, no code execution | Multi-model plan synthesis and adjudication | | `parallel-task` | Executor | Dependency-aware wave execution | Safe/default executor for dependency graphs | | `parallel-task-spark` | Executor | Dependency-aware wave execution | Same as above, pinned to Sparky workers | -| `super-swarm-spark` | Executor | Rolling pool with relationship metadata for awareness | Max throughput execution with stronger conflict-management needs | +| `super-swarm-spark` | Executor | Intentionally dependency-agnostic; relationships are awareness-only | Max throughput execution; dependency conflict resolution is handled by the orchestrator | ## Installation