zeoel-framework 1.0.0

package/.agents/skills/zeoel/skills/opensource-pipeline/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: opensource-pipeline
+description: "Open-source pipeline: fork, sanitize, and package private projects for safe public release. Chains 3 agents (forker, sanitizer, packager). Triggers: '/opensource', 'open source this', 'make this public', 'prepare for open source'."
+origin: ECC
+---
+
+# Open-Source Pipeline Skill
+
+Safely open-source any project through a 3-stage pipeline: **Fork** (strip secrets) → **Sanitize** (verify clean) → **Package** (CLAUDE.md + setup.sh + README).
+
+## When to Activate
+
+- User says "open source this project" or "make this public"
+- User wants to prepare a private repo for public release
+- User needs to strip secrets before pushing to GitHub
+- User invokes `/opensource fork`, `/opensource verify`, or `/opensource package`
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `/opensource fork PROJECT` | Full pipeline: fork + sanitize + package |
+| `/opensource verify PROJECT` | Run sanitizer on existing repo |
+| `/opensource package PROJECT` | Generate CLAUDE.md + setup.sh + README |
+| `/opensource list` | Show all staged projects |
+| `/opensource status PROJECT` | Show reports for a staged project |
+
+## Protocol
+
+### /opensource fork PROJECT
+
+**Full pipeline — the main workflow.**
+
+#### Step 1: Gather Parameters
+
+Resolve the project path. If PROJECT contains `/`, treat as a path (absolute or relative). Otherwise check: current working directory, `$HOME/PROJECT`, then ask the user.
+
+```
+SOURCE_PATH="<resolved absolute path>"
+STAGING_PATH="$HOME/opensource-staging/${PROJECT_NAME}"
+```
+
+Ask the user:
+1. "Which project?" (if not found)
+2. "License? (MIT / Apache-2.0 / GPL-3.0 / BSD-3-Clause)"
+3. "GitHub org or username?" (default: detect via `gh api user -q .login`)
+4. "GitHub repo name?" (default: project name)
+5. "Description for README?" (analyze project for suggestion)
+
+#### Step 2: Create Staging Directory
+
+```bash
+mkdir -p $HOME/opensource-staging/
+```
+
+#### Step 3: Run Forker Agent
+
+Spawn the `opensource-forker` agent:
+
+```
+Agent(
+  description="Fork {PROJECT} for open-source",
+  subagent_type="opensource-forker",
+  prompt="""
+Fork project for open-source release.
+
+Source: {SOURCE_PATH}
+Target: {STAGING_PATH}
+License: {chosen_license}
+
+Follow the full forking protocol:
+1. Copy files (exclude .git, node_modules, __pycache__, .venv)
+2. Strip all secrets and credentials
+3. Replace internal references with placeholders
+4. Generate .env.example
+5. Clean git history
+6. Generate FORK_REPORT.md in {STAGING_PATH}/FORK_REPORT.md
+"""
+)
+```
+
+Wait for completion. Read `{STAGING_PATH}/FORK_REPORT.md`.
+
+#### Step 4: Run Sanitizer Agent
+
+Spawn the `opensource-sanitizer` agent:
+
+```
+Agent(
+  description="Verify {PROJECT} sanitization",
+  subagent_type="opensource-sanitizer",
+  prompt="""
+Verify sanitization of open-source fork.
+
+Project: {STAGING_PATH}
+Source (for reference): {SOURCE_PATH}
+
+Run ALL scan categories:
+1. Secrets scan (CRITICAL)
+2. PII scan (CRITICAL)
+3. Internal references scan (CRITICAL)
+4. Dangerous files check (CRITICAL)
+5. Configuration completeness (WARNING)
+6. Git history audit
+
+Generate SANITIZATION_REPORT.md inside {STAGING_PATH}/ with PASS/FAIL verdict.
+"""
+)
+```
+
+Wait for completion. Read `{STAGING_PATH}/SANITIZATION_REPORT.md`.
+
+**If FAIL:** Show findings to user. Ask: "Fix these and re-scan, or abort?"
+- If fix: Apply fixes, re-run sanitizer (maximum 3 retry attempts — after 3 FAILs, present all findings and ask user to fix manually)
+- If abort: Clean up staging directory
+
+**If PASS or PASS WITH WARNINGS:** Continue to Step 5.
+
+#### Step 5: Run Packager Agent
+
+Spawn the `opensource-packager` agent:
+
+```
+Agent(
+  description="Package {PROJECT} for open-source",
+  subagent_type="opensource-packager",
+  prompt="""
+Generate open-source packaging for project.
+
+Project: {STAGING_PATH}
+License: {chosen_license}
+Project name: {PROJECT_NAME}
+Description: {description}
+GitHub repo: {github_repo}
+
+Generate:
+1. CLAUDE.md (commands, architecture, key files)
+2. setup.sh (one-command bootstrap, make executable)
+3. README.md (or enhance existing)
+4. LICENSE
+5. CONTRIBUTING.md
+6. .github/ISSUE_TEMPLATE/ (bug_report.md, feature_request.md)
+"""
+)
+```
+
+#### Step 6: Final Review
+
+Present to user:
+```
+Open-Source Fork Ready: {PROJECT_NAME}
+
+Location: {STAGING_PATH}
+License: {license}
+Files generated:
+  - CLAUDE.md
+  - setup.sh (executable)
+  - README.md
+  - LICENSE
+  - CONTRIBUTING.md
+  - .env.example ({N} variables)
+
+Sanitization: {sanitization_verdict}
+
+Next steps:
+  1. Review: cd {STAGING_PATH}
+  2. Create repo: gh repo create {github_org}/{github_repo} --public
+  3. Push: git remote add origin ... && git push -u origin main
+
+Proceed with GitHub creation? (yes/no/review first)
+```
+
+#### Step 7: GitHub Publish (on user approval)
+
+```bash
+cd "{STAGING_PATH}"
+gh repo create "{github_org}/{github_repo}" --public --source=. --push --description "{description}"
+```
+
+---
+
+### /opensource verify PROJECT
+
+Run sanitizer independently. Resolve path: if PROJECT contains `/`, treat as a path. Otherwise check `$HOME/opensource-staging/PROJECT`, then `$HOME/PROJECT`, then current directory.
+
+```
+Agent(
+  subagent_type="opensource-sanitizer",
+  prompt="Verify sanitization of: {resolved_path}. Run all 6 scan categories and generate SANITIZATION_REPORT.md."
+)
+```
+
+---
+
+### /opensource package PROJECT
+
+Run packager independently. Ask for "License?" and "Description?", then:
+
+```
+Agent(
+  subagent_type="opensource-packager",
+  prompt="Package: {resolved_path} ..."
+)
+```
+
+---
+
+### /opensource list
+
+```bash
+ls -d $HOME/opensource-staging/*/
+```
+
+Show each project with pipeline progress (FORK_REPORT.md, SANITIZATION_REPORT.md, CLAUDE.md presence).
+
+---
+
+### /opensource status PROJECT
+
+```bash
+cat $HOME/opensource-staging/${PROJECT}/SANITIZATION_REPORT.md
+cat $HOME/opensource-staging/${PROJECT}/FORK_REPORT.md
+```
+
+## Staging Layout
+
+```
+$HOME/opensource-staging/
+  my-project/
+    FORK_REPORT.md           # From forker agent
+    SANITIZATION_REPORT.md   # From sanitizer agent
+    CLAUDE.md                # From packager agent
+    setup.sh                 # From packager agent
+    README.md                # From packager agent
+    .env.example             # From forker agent
+    ...                      # Sanitized project files
+```
+
+## Anti-Patterns
+
+- **Never** push to GitHub without user approval
+- **Never** skip the sanitizer — it is the safety gate
+- **Never** proceed after a sanitizer FAIL without fixing all critical findings
+- **Never** leave `.env`, `*.pem`, or `credentials.json` in the staging directory
+
+## Best Practices
+
+- Always run the full pipeline (fork → sanitize → package) for new releases
+- The staging directory persists until explicitly cleaned up — use it for review
+- Re-run the sanitizer after any manual fixes before publishing
+- Parameterize secrets rather than deleting them — preserve project functionality
+
+## Related Skills
+
+See `security-review` for secret detection patterns used by the sanitizer.

package/.agents/skills/zeoel/skills/orchestration-workflow/orchestration-workflow.md

@@ -0,0 +1,199 @@
+# Orchestration Workflow
+
+This document describes the **Command → Agent (with skill) → Skill** orchestration workflow, demonstrated through a weather data fetching and SVG rendering system.
+
+<table width="100%">
+<tr>
+<td><a href="../">← Back to Claude Code Best Practice</a></td>
+<td align="right"><img src="../!/claude-jumping.svg" alt="Claude" width="60" /></td>
+</tr>
+</table>
+
+## System Overview
+
+The weather system demonstrates two distinct skill patterns within a single orchestration workflow:
+- **Agent Skills** (preloaded): `weather-fetcher` is injected into the `weather-agent` at startup as domain knowledge
+- **Skills** (independent): `weather-svg-creator` is invoked directly by the command via the Skill tool
+
+This showcases the **Command → Agent → Skill** architecture pattern, where:
+- A command orchestrates the workflow and handles user interaction
+- An agent fetches data using its preloaded skill
+- A skill creates the visual output independently
+
+## Component Summary
+
+| Component | Role | Example |
+|-----------|------|---------|
+| **Command** | Entry point, user interaction | [`/weather-orchestrator`](../.claude/commands/weather-orchestrator.md) |
+| **Agent** | Fetches data with preloaded skill (agent skill) | [`weather-agent`](../.claude/agents/weather-agent.md) with [`weather-fetcher`](../.claude/skills/weather-fetcher/SKILL.md) |
+| **Skill** | Creates output independently (skill) | [`weather-svg-creator`](../.claude/skills/weather-svg-creator/SKILL.md) |
+
+## Flow Diagram
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║              ORCHESTRATION WORKFLOW                              ║
+║           Command  →  Agent  →  Skill                            ║
+╚══════════════════════════════════════════════════════════════════╝
+
+                         ┌───────────────────┐
+                         │  User Interaction │
+                         └─────────┬─────────┘
+                                   │
+                                   ▼
+         ┌─────────────────────────────────────────────────────┐
+         │  /weather-orchestrator — Command (Entry Point)      │
+         └─────────────────────────┬───────────────────────────┘
+                                   │
+                              Step 1
+                                   │
+                                   ▼
+                      ┌────────────────────────┐
+                      │  AskUser — C° or F°?   │
+                      └────────────┬───────────┘
+                                   │
+                         Step 2 — Agent tool
+                                   │
+                                   ▼
+         ┌─────────────────────────────────────────────────────┐
+         │  weather-agent — Agent ● skill: weather-fetcher     │
+         └─────────────────────────┬───────────────────────────┘
+                                   │
+                          Returns: temp + unit
+                                   │
+                         Step 3 — Skill tool
+                                   │
+                                   ▼
+         ┌─────────────────────────────────────────────────────┐
+         │  weather-svg-creator — Skill ● SVG card + output    │
+         └─────────────────────────┬───────────────────────────┘
+                                   │
+                          ┌────────┴────────┐
+                          │                 │
+                          ▼                 ▼
+                   ┌────────────┐    ┌────────────┐
+                   │weather.svg │    │ output.md  │
+                   └────────────┘    └────────────┘
+```
+
+## Component Details
+
+### 1. Command
+
+#### `/weather-orchestrator` (Command)
+- **Location**: `.claude/commands/weather-orchestrator.md`
+- **Purpose**: Entry point — orchestrates the workflow and handles user interaction
+- **Actions**:
+  1. Asks user for temperature unit preference (Celsius/Fahrenheit)
+  2. Invokes weather-agent via Agent tool
+  3. Invokes weather-svg-creator via Skill tool
+- **Model**: haiku
+
+### 2. Agent with Preloaded Skill (Agent Skill)
+
+#### `weather-agent` (Agent)
+- **Location**: `.claude/agents/weather-agent.md`
+- **Purpose**: Fetch weather data using its preloaded skill
+- **Skills**: `weather-fetcher` (preloaded as domain knowledge)
+- **Tools Available**: Read, Skill
+- **Model**: sonnet
+- **Color**: green
+- **Memory**: project
+
+The agent has `weather-fetcher` preloaded into its context at startup. It follows the skill's instructions to fetch the temperature and returns the value to the command.
+
+### 3. Skill
+
+#### `weather-svg-creator` (Skill)
+- **Location**: `.claude/skills/weather-svg-creator/SKILL.md`
+- **Purpose**: Create a visual SVG weather card and write output files
+- **Invocation**: Via Skill tool from the command (not preloaded into any agent)
+- **Outputs**:
+  - `orchestration-workflow/weather.svg` — SVG weather card
+  - `orchestration-workflow/output.md` — Weather summary
+
+### 4. Preloaded Skill
+
+#### `weather-fetcher` (Skill)
+- **Location**: `.claude/skills/weather-fetcher/SKILL.md`
+- **Purpose**: Instructions for fetching real-time temperature data
+- **Data Source**: Open-Meteo API for Dubai, UAE
+- **Output**: Temperature value and unit (Celsius or Fahrenheit)
+- **Note**: This is an agent skill — preloaded into `weather-agent`, not invoked directly
+
+## Execution Flow
+
+1. **User Invocation**: User runs `/weather-orchestrator` command
+2. **User Prompt**: Command asks user for preferred temperature unit (Celsius/Fahrenheit)
+3. **Agent Invocation**: Command invokes `weather-agent` via Agent tool
+4. **Skill Execution** (within agent context):
+   - Agent follows `weather-fetcher` skill instructions to fetch temperature from Open-Meteo
+   - Agent returns the temperature value and unit to the command
+5. **SVG Creation**: Command invokes `weather-svg-creator` via Skill tool
+   - Skill creates SVG weather card at `orchestration-workflow/weather.svg`
+   - Skill writes summary to `orchestration-workflow/output.md`
+6. **Result Display**: Summary shown to user with:
+   - Temperature unit requested
+   - Temperature fetched
+   - SVG card location
+   - Output file location
+
+## Example Execution
+
+```
+Input: /weather-orchestrator
+├─ Step 1: Asks: Celsius or Fahrenheit?
+│  └─ User: Celsius
+├─ Step 2: Agent tool → weather-agent
+│  ├─ Preloaded Skill:
+│  │  └─ weather-fetcher (domain knowledge)
+│  ├─ Fetches from Open-Meteo → 26°C
+│  └─ Returns: temperature=26, unit=Celsius
+├─ Step 3: Skill tool → /weather-svg-creator
+│  ├─ Creates: orchestration-workflow/weather.svg
+│  └─ Writes: orchestration-workflow/output.md
+└─ Output:
+   ├─ Unit: Celsius
+   ├─ Temperature: 26°C
+   ├─ SVG: orchestration-workflow/weather.svg
+   └─ Summary: orchestration-workflow/output.md
+```
+
+## Key Design Principles
+
+1. **Two Skill Patterns**: Demonstrates both agent skills (preloaded) and skills (invoked directly)
+2. **Command as Orchestrator**: The command handles user interaction and coordinates the workflow
+3. **Agent for Data Fetching**: The agent uses its preloaded skill to fetch data, then returns it
+4. **Skill for Output**: The SVG creator runs independently, receiving data from the command context
+5. **Clean Separation**: Fetch (agent) → Render (skill) — each component has a single responsibility
+
+## Architecture Patterns
+
+### Agent Skill (Preloaded)
+
+```yaml
+# In agent definition (.claude/agents/weather-agent.md)
+---
+name: weather-agent
+skills:
+  - weather-fetcher    # Preloaded into agent context at startup
+---
+```
+
+- **Skills are preloaded**: Full skill content is injected into agent's context at startup
+- **Agent uses skill knowledge**: Agent follows instructions from preloaded skills
+- **No dynamic invocation**: Skills are reference material, not invoked separately
+
+### Skill (Direct Invocation)
+
+```yaml
+# In skill definition (.claude/skills/weather-svg-creator/SKILL.md)
+---
+name: weather-svg-creator
+description: Creates an SVG weather card...
+---
+```
+
+- **Invoked via Skill tool**: Command calls `Skill(skill: "weather-svg-creator")`
+- **Independent execution**: Runs in the command's context, not inside an agent
+- **Receives data from context**: Uses temperature data already available in the conversation

package/.agents/skills/zeoel/skills/orchestration-workflow/orchestration-workflow.svg

@@ -0,0 +1,78 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 435" width="1200" height="435">
+  <defs>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="4" orient="auto">
+      <path d="M0,0 L0,8 L8,4 z" fill="#666"/>
+    </marker>
+  </defs>
+
+  <!-- Background -->
+  <rect width="1200" height="435" fill="#fafafa" rx="10"/>
+
+  <!-- Header: Claude mascot + title -->
+  <g transform="translate(390, 8) scale(0.38)">
+    <rect x="22" y="10" width="8" height="14" fill="#E07C4C"/>
+    <rect x="70" y="10" width="8" height="14" fill="#E07C4C"/>
+    <rect x="18" y="24" width="64" height="4" fill="#E07C4C"/>
+    <rect x="14" y="28" width="72" height="32" fill="#E07C4C"/>
+    <rect x="30" y="34" width="8" height="10" fill="#000"/>
+    <rect x="62" y="34" width="8" height="10" fill="#000"/>
+    <rect x="2" y="36" width="12" height="8" fill="#E07C4C"/>
+    <rect x="86" y="36" width="12" height="8" fill="#E07C4C"/>
+    <rect x="24" y="60" width="12" height="14" fill="#E07C4C"/>
+    <rect x="64" y="60" width="12" height="14" fill="#E07C4C"/>
+  </g>
+  <text x="435" y="33" text-anchor="start" fill="#333" font-family="system-ui" font-size="18" font-weight="bold">Claude Code Orchestration Workflow</text>
+
+  <!-- User -->
+  <circle cx="75" cy="190" r="38" fill="#E07C4C"/>
+  <text x="75" y="196" text-anchor="middle" fill="white" font-family="system-ui" font-size="16" font-weight="bold">User</text>
+
+  <!-- Arrow 1 -->
+  <line x1="118" y1="190" x2="183" y2="190" stroke="#666" stroke-width="2.5" marker-end="url(#arrow)"/>
+
+  <!-- Command Box -->
+  <rect x="193" y="145" width="240" height="90" rx="8" fill="#2C3E50" stroke="#1A252F" stroke-width="2.5"/>
+  <text x="313" y="179" text-anchor="middle" fill="white" font-family="system-ui" font-size="16" font-weight="bold">Command</text>
+  <text x="313" y="207" text-anchor="middle" fill="white" font-family="system-ui" font-size="12" opacity="0.9">commands/weather-orchestrator</text>
+  <!-- Command description -->
+  <text x="313" y="265" text-anchor="middle" fill="#888" font-family="system-ui" font-size="11">Asks user for C°/F°, invokes</text>
+  <text x="313" y="280" text-anchor="middle" fill="#888" font-family="system-ui" font-size="11">agent and SVG creator skill</text>
+
+  <!-- Arrow 2 -->
+  <line x1="438" y1="190" x2="503" y2="190" stroke="#666" stroke-width="2.5" marker-end="url(#arrow)"/>
+  <text x="470" y="180" text-anchor="middle" fill="#666" font-family="system-ui" font-size="11">Task</text>
+
+  <!-- Agent Box -->
+  <rect x="513" y="127" width="240" height="126" rx="8" fill="#2BA5A5" stroke="#1E8F8F" stroke-width="2.5"/>
+  <text x="633" y="155" text-anchor="middle" fill="white" font-family="system-ui" font-size="16" font-weight="bold">Agent</text>
+  <text x="633" y="173" text-anchor="middle" fill="white" font-family="system-ui" font-size="12" opacity="0.85">agents/weather-agent</text>
+
+  <!-- Skills inside Agent -->
+  <rect x="527" y="183" width="212" height="56" rx="5" fill="white" opacity="0.2"/>
+  <text x="633" y="205" text-anchor="middle" fill="white" font-family="system-ui" font-size="12" opacity="0.7">(preloaded skill)</text>
+  <text x="633" y="229" text-anchor="middle" fill="white" font-family="system-ui" font-size="11" opacity="0.9">weather-fetcher</text>
+  <!-- Agent description -->
+  <text x="633" y="273" text-anchor="middle" fill="#888" font-family="system-ui" font-size="11">Fetches temperature from</text>
+  <text x="633" y="288" text-anchor="middle" fill="#888" font-family="system-ui" font-size="11">Open-Meteo API for Dubai</text>
+
+  <!-- Arrow 3 -->
+  <line x1="758" y1="190" x2="823" y2="190" stroke="#666" stroke-width="2.5" marker-end="url(#arrow)"/>
+  <text x="790" y="180" text-anchor="middle" fill="#666" font-family="system-ui" font-size="11">Skill</text>
+
+  <!-- SVG Creator Skill Box -->
+  <rect x="833" y="145" width="280" height="90" rx="8" fill="#9B59B6" stroke="#8E44AD" stroke-width="2.5"/>
+  <text x="973" y="179" text-anchor="middle" fill="white" font-family="system-ui" font-size="16" font-weight="bold">Skill</text>
+  <text x="973" y="207" text-anchor="middle" fill="white" font-family="system-ui" font-size="12" opacity="0.9">skills/weather-svg-creator</text>
+  <!-- Skill description -->
+  <text x="973" y="265" text-anchor="middle" fill="#888" font-family="system-ui" font-size="11">Creates SVG weather card at</text>
+  <text x="973" y="280" text-anchor="middle" fill="#888" font-family="system-ui" font-size="11">orchestration-workflow/weather.svg</text>
+
+  <!-- Arrow 4 (back to user) -->
+  <path d="M 1113 190 Q 1160 190 1160 325 Q 1160 360 75 360 Q 40 360 40 255 L 40 235"
+        stroke="#666" stroke-width="2.5" fill="none" stroke-dasharray="6,4" marker-end="url(#arrow)"/>
+
+  <!-- Legend -->
+  <text x="600" y="407" text-anchor="middle" fill="#888" font-family="system-ui" font-size="12">
+    commands/weather-orchestrator → agents/weather-agent (preloaded skill) → skills/weather-svg-creator (skill)
+  </text>
+</svg>

package/.agents/skills/zeoel/skills/orchestration-workflow/output.md

@@ -0,0 +1,13 @@
+# Weather Result
+
+## Temperature
+89.3°F
+
+## Location
+Dubai, UAE
+
+## Unit
+Fahrenheit
+
+## SVG Card
+![Weather Card](weather.svg)

package/.agents/skills/zeoel/skills/orchestration-workflow/weather.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 300 160" width="300" height="160">
+  <rect width="300" height="160" rx="12" fill="#1a1a2e"/>
+  <text x="150" y="45" text-anchor="middle" fill="#8892b0" font-family="system-ui" font-size="14">Unit: Fahrenheit</text>
+  <text x="150" y="100" text-anchor="middle" fill="#ccd6f6" font-family="system-ui" font-size="42" font-weight="bold">89.3°F</text>
+  <text x="150" y="140" text-anchor="middle" fill="#64ffda" font-family="system-ui" font-size="16">Dubai, UAE</text>
+</svg>