diff --git a/CLAUDE.md b/CLAUDE.md index 2bbe2fc..d8e653b 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 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 - 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,23 @@ 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 + - 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 71e3501..f70dfac 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. Intentionally ignores dependency maps; dependency-conflict resolution is delegated to the orchestrator. ### 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 | Intentionally dependency-agnostic; relationships are awareness-only | Max throughput execution; dependency conflict resolution is handled by the orchestrator | ## Installation