docs: add complete structured coverage for all skills

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/<skill-name> ~/.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.
 

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