daemora 1.0.0-alpha.0

package/skills/orchestration.md

@@ -0,0 +1,114 @@
+---
+name: orchestration
+description: Multi-agent orchestration - teams, parallel execution, delegation, swarm-style dependency resolution
+triggers: parallel, orchestrate, sub-agent, project, plan, multiple tasks, frontend backend, coordinate, spawn, contract, full-stack, multi-step, team, teammates, priority, research, swarm
+---
+
+# Orchestration & Multi-Agent Planning
+
+## Decision Matrix
+
+### Do it yourself when:
+- Single action: send email, quick search, toggle setting
+- Direct iteration: "fix this line", "change that word"
+- < 3 tool calls total
+
+### Use useCrew when:
+- Single focused task - research, build one file, analysis
+- Fire-and-forget - spawn, collect result, move on
+
+### Use parallelCrew when:
+- Multiple INDEPENDENT tasks - no shared deliverable
+- Never for tasks that share a project - use teamTask instead
+
+### Use teamTask when:
+- Multi-component project - frontend + backend, microservices, any "build X with Y"
+- Dependent tasks where output of A feeds into B
+- 3+ workers that need to coordinate via shared filesystem
+- Full-stack builds, research pipelines, anything with phases
+
+## teamTask (Swarm Pattern)
+
+Code orchestrator spawns workers, passes completed results to dependent workers. No AI lead.
+
+### How it works:
+1. You define workers with tasks and `blockedByWorkers` dependencies
+2. Independent workers spawn in parallel immediately
+3. When a worker completes, its structured result (files, endpoints, ports) auto-injects into dependent workers' context
+4. Dependent workers spawn once all their deps finish
+5. Repeat until all done
+
+### Creating a team:
+```
+teamTask({
+  action: "createTeam",
+  name: "todo-app",
+  project: "todo-app",
+  projectType: "coding",
+  projectStack: "Node.js, React, SQLite",
+  task: "Build a full-stack todo app with CRUD",
+  workers: [
+    {
+      name: "backend",
+      profile: "backend",
+      task: "TASK: Build Express API with SQLite...\nFILES: /path/backend/...\nSPEC: GET/POST/PATCH/DELETE /api/todos...\nOUTPUT: Working API on port 3001"
+    },
+    {
+      name: "frontend",
+      profile: "frontend",
+      task: "TASK: Build React UI with shadcn...\nFILES: /path/frontend/...\nOUTPUT: Working UI on port 5173",
+      blockedByWorkers: ["backend"]
+    },
+    {
+      name: "tester",
+      profile: "tester",
+      task: "TASK: Test CRUD flows end-to-end...\nOUTPUT: Test results",
+      blockedByWorkers: ["backend", "frontend"]
+    }
+  ]
+})
+```
+
+### Dependency flow (swarm handoff):
+- backend completes → reports: endpoints, port, files created
+- frontend spawns → gets backend's result in its context: "backend built GET /api/todos on port 3001"
+- frontend completes → reports: files, components built
+- tester spawns → gets both backend + frontend results in its context
+
+### Other actions:
+- `relaunchProject` - `{ teamId }` - resume incomplete team
+- `status` - `{ teamId }` - check team state
+- `listTeams` - all active teams
+- `disbandTeam` - `{ teamId }` - stop a team
+
+## Mandatory Structured Brief
+
+Every worker task must include:
+
+```
+TASK: What to build/research/fix (one sentence)
+CONTEXT: Background - what exists, what this connects to, why
+FILES: Exact paths to create or modify
+SPEC: Full contract - endpoints, schemas, interfaces
+CONSTRAINTS: Frameworks, patterns, format requirements
+OUTPUT: What to produce - files, report, test results
+```
+
+**Bad:** "Write the backend"
+**Good:** "TASK: Build Express API with SQLite for todo CRUD. FILES: /project/backend/src/server.js, /project/backend/src/db.js. SPEC: GET /api/todos, POST /api/todos, PATCH /api/todos/:id, DELETE /api/todos/:id. JSON bodies. CORS for localhost:5173. CONSTRAINTS: Use better-sqlite3, zod validation. OUTPUT: Working API on port 3001."
+
+## Parallel vs Sequential Decision
+- Does task B need output from task A? → `blockedByWorkers: ["A"]` in teamTask
+- Independent work? → parallelCrew or teamTask without blockedByWorkers (both run parallel)
+- Same project, multiple parts? → teamTask always (shared filesystem + result handoff)
+
+## Context Preservation
+Spawn sub-agents to keep verbose output OUT of main context:
+- Test suite output → sub-agent runs tests, returns summary only
+- Log analysis → sub-agent reads logs, writes findings to file
+- Large audit → sub-agent scans files, produces report
+
+## Error Recovery
+- Worker fails → team continues with other workers, reports failure in summary
+- Relaunch → `relaunchProject` picks up where it left off, only runs incomplete workers
+- Worker stuck → 30 min timeout, marked as failed automatically

package/skills/pdf.md

@@ -0,0 +1,60 @@
+---
+name: pdf
+description: Create, read, extract text from, merge, split, compress, and manipulate PDF files. Use when the user asks to create a PDF, extract text from a PDF, merge PDFs, convert to PDF, or do any PDF operation.
+triggers: pdf, create pdf, read pdf, extract pdf, merge pdf, split pdf, convert to pdf, pdf report, pdf document, compress pdf, rotate pdf
+metadata: {"daemora": {"emoji": "📄", "requires": {"anyBins": ["wkhtmltopdf", "pandoc", "pdftotext"]}, "install": ["brew install wkhtmltopdf"]}}
+---
+
+## Create PDF from HTML (best quality)
+
+```bash
+brew install wkhtmltopdf
+wkhtmltopdf --page-size A4 --margin-top 20mm --margin-bottom 20mm \
+  --encoding UTF-8 --footer-center "[page] / [topage]" \
+  /tmp/report.html /tmp/report.pdf
+```
+
+## Create PDF with Python (no binary needed)
+
+```bash
+pip install reportlab
+# Use SimpleDocTemplate, Paragraph, Table from reportlab.platypus
+```
+
+## Extract text from PDF
+
+```bash
+pip install pdfplumber
+python3 -c "import pdfplumber; pdf=pdfplumber.open('file.pdf'); print(pdf.pages[0].extract_text())"
+# Or: brew install poppler && pdftotext file.pdf -
+```
+
+## Merge PDFs
+
+```bash
+pip install pypdf
+# PdfWriter + PdfReader from pypdf
+# Or with ghostscript:
+gs -dBATCH -dNOPAUSE -q -sDEVICE=pdfwrite -sOutputFile=merged.pdf a.pdf b.pdf
+```
+
+## Markdown → PDF
+
+```bash
+brew install pandoc
+pandoc input.md -o output.pdf --pdf-engine=wkhtmltopdf -V geometry:margin=25mm
+```
+
+## Compress PDF (macOS)
+
+```bash
+gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.5 -dPDFSETTINGS=/ebook \
+  -dNOPAUSE -dQUIET -dBATCH -sOutputFile=/tmp/compressed.pdf input.pdf
+# PDFSET options: /screen (72dpi) /ebook (150dpi) /printer (300dpi) /prepress (HQ)
+```
+
+## After creating
+
+1. Report the path: "PDF saved to `/tmp/report.pdf`"
+2. On macOS: `executeCommand("open /tmp/report.pdf")` to preview
+3. To send: `sendFile("/tmp/report.pdf", channel, sessionId)`

package/skills/planning/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: planning
+description: Produce structured executable plans from a user goal — any domain. Make sure to use this skill whenever the user (or another agent) needs a plan, strategy, roadmap, or breakdown of how a multi-step task will be done — even if the word "plan" isn't used. Pairs with the task-decomposition skill.
+triggers: [plan, strategy, roadmap, breakdown, "step by step", phases, "how would you", "what's the approach"]
+requires_tools: []
+version: 1.0.0
+enabled: true
+---
+
+# Planning
+
+Turn a goal into an executable plan. Never execute from this skill —
+hand the plan back for the caller to run.
+
+## When to apply
+
+Whenever the work is multi-step, multi-day, or coordinated across
+multiple owners (crews, sub-agents, MCP servers, the main agent
+itself). Skip planning for a single-action task.
+
+## What every plan contains
+
+```
+# Plan: <one-line goal>
+
+## Goal & success criteria
+- Observable definition of done
+- 2–3 falsifiable checks
+
+## Assumptions & prerequisites
+- Crews / skills / MCP servers / integrations / API keys needed
+- Open questions for the user
+
+## Phases
+1. <Phase name — 1-line outcome>
+   - Owner: <crew | sub-agent | MCP server | main agent>
+   - Tool(s) / skill(s): <names from the live inventory>
+   - Steps: <numbered, concrete>
+   - Output: <artifact / record / message>
+   - Cadence: <one-shot | recurring with cron expression>
+
+## Schedule (cron, if any)
+| name | cron | runs |
+|---|---|---|
+
+## Risks & mitigations
+- Likely failure modes + how the plan reacts
+
+## Approval gate
+Reply 'go' to start. Reply 'tweak <part>' to revise.
+```
+
+Skip sections that don't apply. Don't pad.
+
+## How to think
+
+### Map to real names
+Every owner / tool / skill / server you reference must already exist
+in the running daemora install. Look them up first. If something
+isn't there, list it as a prerequisite the user must add.
+
+### Outcome cuts, not activity cuts
+A phase = a thing you can point at when done. Phase names with
+verbs ("research", "build", "optimize") rarely produce evidence;
+phase names with outcomes do.
+
+### Schedule with commitment
+If the work is recurring, write the cron expression. "Daily" alone
+is not a schedule.
+
+### Surface unknowns honestly
+If the goal as stated doesn't give you enough to commit, list the
+gaps in **Open questions** rather than guessing.
+
+### Right-size
+A small plan that ships beats a long plan that doesn't. Cut every
+line that doesn't change a decision.
+
+### Stay generic
+Plans should work for any domain — code, content, research, ops,
+monitoring, comms, infrastructure, anything. Don't infer a domain
+from a few keywords; mirror the user's vocabulary.
+
+## When a plan already exists
+
+If the caller hands you a structured plan, **validate, don't
+regenerate**. Confirm every owner/tool/skill/server is real,
+prerequisites are met, cron expressions parse, success checks are
+observable. Return one of:
+
+- "Executable as-written. Confirm prerequisites:" + checklist
+- "Gaps:" + specific items + a fix per gap
+
+## Guardrails
+
+- Reference secrets by vault key name only; never paste values.
+- Stay inside the user's stated scope.
+- Refuse illegal / deceptive / mass-spam asks in one sentence.

package/skills/planning.md

@@ -0,0 +1,168 @@
+---
+name: planning
+description: Task planning for any complex work - coding, research, communication, automation. Decide when to plan vs just do, break into steps, get user confirmation before executing.
+triggers: plan, planning, design, architect, approach, strategy, implement, big task, complex task, multi-step, think through, break down, figure out, how should, what approach, steps, workflow
+---
+
+# Planning - Think Before You Act
+
+## When to Plan vs Just Do It
+
+**Plan first** when ANY of these apply:
+- **Multiple steps required** - the task needs 3+ distinct actions to complete.
+- **Multiple valid approaches** - the task can be solved several ways. Pick the right one first.
+- **Unclear scope** - you need to explore or research before understanding the full extent of work.
+- **User preferences matter** - the outcome could go multiple reasonable directions.
+- **High stakes** - mistakes are costly to undo (emails sent, files restructured, data transformed).
+- **Multi-agent work** - the task needs parallel or sequential agent coordination.
+- **New feature or system change** - adding meaningful new functionality or modifying existing behavior.
+- **Multi-file code changes** - the task will touch 3+ files. Map out which files and what changes.
+- **Architectural decisions** - choosing between patterns, libraries, data models, or technologies.
+
+**Skip planning** - do it directly:
+- Single-action tasks (send one email, fetch one page, fix a typo).
+- Tasks where the user gave very specific, detailed instructions.
+- Quick lookups, simple questions, casual conversation.
+- Few-line code fixes with obvious solutions.
+
+**When in doubt → plan.** The cost of planning is low. The cost of rework is high.
+
+## Planning Workflow
+
+1. **Explore** - gather context. Read files, search the web, check memory, review conversation history. Understand the current state before deciding what to change.
+2. **Identify the approach** - what needs to happen, in what order, using what tools/agents. Consider alternatives and pick the best one.
+3. **Break into steps** - ordered list of concrete actions. Each step = one verifiable outcome. Keep it short - a list of actions, not an essay.
+4. **Present the plan to the user** - before executing, tell the user what you're about to do and ask for confirmation. This prevents wasted effort and ensures alignment. Format: numbered list of concrete actions, not vague descriptions.
+5. **Execute on confirmation** - work through each step. Verify after each one.
+
+## User Confirmation
+
+**Always confirm before executing a complex plan.** Present the plan clearly and ask:
+- "Here's my plan - want me to go ahead?"
+- List the concrete steps so the user can see what will happen.
+- If the user adjusts, update the plan and confirm again.
+- Only skip confirmation for simple tasks that don't need planning.
+
+This is non-negotiable for complex work. The user should always know what's about to happen before it happens.
+
+## Exploration by Task Type
+
+**Code tasks:**
+- Find files - `glob("src/**/*.ts")`, `glob("*.controller.*")` to map the structure.
+- Find patterns - `grep("export function", "src/")`, `grep("interface.*Props")` to see conventions.
+- Read key files - entry points, related components, tests, configs.
+- Check dependencies - what libraries, APIs, patterns are established.
+
+**Research tasks:**
+- Web search for current information on the topic.
+- Fetch and read actual pages - don't stop at summaries.
+- Check memory for previous findings on the same topic.
+- Cross-reference multiple sources for anything important.
+
+**Communication tasks:**
+- Review conversation history for context and tone.
+- Check memory for user preferences (writing style, contacts, templates).
+- Identify all recipients, attachments, and follow-up actions needed.
+
+**Automation / workflow tasks:**
+- Map the full workflow end-to-end before automating any step.
+- Identify dependencies between steps.
+- Check what tools, APIs, and MCP servers are available.
+
+3-5 targeted explorations is usually enough. Get the lay of the land, then plan.
+
+## What a Good Plan Looks Like
+
+A plan is a short ordered list of concrete actions:
+
+**Coding example:**
+```
+1. Add FooService class in src/services/foo.ts - handles X with methods Y, Z
+2. Update src/routes/api.ts - add GET /api/foo endpoint, wire to FooService
+3. Add tests in tests/foo.test.ts - cover happy path + error cases
+4. Run build + tests, fix any failures
+```
+
+**Research example:**
+```
+1. Search web for latest pricing on X, Y, Z services
+2. Fetch each provider's pricing page, extract plan details
+3. Compare features and costs in a structured table
+4. Save findings to memory for future reference
+```
+
+**Workflow example:**
+```
+1. Fetch all invoices from email (last 30 days)
+2. Extract amounts, dates, vendors from each
+3. Create summary spreadsheet in workspace
+4. Send summary to user via email
+```
+
+NOT:
+```
+First, I'll think about what to do. Then I'll consider the options.
+After that, I'll figure out the best approach. Finally, I'll do everything.
+```
+
+Each step should be specific enough to hand to someone with zero context.
+
+## Planning Multi-Agent Work
+
+Any task that spawns agents - `spawnAgent`, `parallelAgents`, `useMCP` - is multi-agent work. MCP tasks are spawned agent tasks. Plan them the same way.
+
+### Agent Isolation - Non-Negotiable
+- Each agent operates in its own context. No shared memory, no shared state, no implicit communication.
+- Agents must NOT touch files, paths, or resources owned by another agent. Define boundaries upfront.
+- If two agents need the same data, pass it explicitly via `sharedContext` or workspace files. Never assume one agent can read another's output unless the plan says so.
+- MCP agents (`useMCP`) get ONLY that server's tools. They cannot access files, shell, or other MCP servers. Plan accordingly - don't expect an MCP agent to do something outside its server's scope.
+
+### Contract-Based Planning
+Before spawning any agents, define the contract:
+1. **Inputs** - what each agent receives. Exact data, file paths, specs. Paste the actual content into the brief - don't reference it.
+2. **Outputs** - what each agent produces. File paths, data shapes, expected format.
+3. **Boundaries** - what each agent is NOT allowed to touch. Files, directories, APIs outside its scope.
+4. **Dependencies** - does agent B need output from agent A? Yes → sequential. No → parallel.
+5. **Profiles** - coder for code, researcher for research, writer for docs, analyst for data.
+
+### MCP as Spawned Agents
+- `useMCP(serverName, taskDescription)` spawns a specialist agent with ONLY that MCP server's tools.
+- The specialist has ZERO context beyond the task description you write. Include everything: what to do, all details, full content, background context.
+- Plan MCP calls like any other agent spawn - define inputs, expected outputs, and what happens with the result.
+- Multiple MCP calls to different servers can run in parallel if they don't depend on each other.
+
+### Preventing Cross-Agent Impact
+- Never let two agents write to the same file. Split by file or by section with clear ownership.
+- Never let an agent modify global state (env vars, configs, databases) without the plan explicitly calling for it.
+- Use workspace directories (`data/workspaces/{id}/`) as artifact stores. Each agent writes to its own path within the workspace.
+- After all agents finish, the parent synthesizes results. Agents never directly consume each other's output during execution.
+
+Load `readFile("skills/orchestration.md")` for full multi-agent coordination patterns, error recovery, and structured return conventions.
+
+## Tracking Complex Work
+
+For multi-step work, use `projectTracker("createProject")` to persist the plan:
+- Mark tasks `in_progress` before starting, `done` with notes when finished.
+- If interrupted → `projectTracker("listProjects")` to find and resume.
+- Workspace files survive crashes - work is never lost.
+
+## Re-Assessment
+
+If you're 3+ steps into execution and:
+- The approach isn't working as expected
+- You discovered something that changes the requirements
+- The scope is larger than initially estimated
+
+**Stop. Re-read the original request. Re-plan from current state.** Don't push through a broken plan. If the new plan differs significantly, confirm with the user again.
+
+## Planning Checklist
+
+Before executing, verify:
+- [ ] Gathered enough context (files, web, memory, conversation)
+- [ ] Identified the best approach from available options
+- [ ] Steps are ordered (dependencies resolved)
+- [ ] Each step has a clear, verifiable outcome
+- [ ] User has confirmed the plan (for complex work)
+- [ ] Edge cases and potential failures considered
+- [ ] Multi-agent tasks: contracts defined, boundaries set, no shared-file conflicts
+- [ ] MCP tasks: task descriptions are self-contained, expected outputs specified

package/skills/raffle-winner-picker.md

@@ -0,0 +1,159 @@
+---
+name: raffle-winner-picker
+description: Picks random winners from lists, spreadsheets, or Google Sheets for giveaways, raffles, and contests. Ensures fair, unbiased selection with transparency.
+---
+
+# Raffle Winner Picker
+
+This skill randomly selects winners from lists, spreadsheets, or Google Sheets for giveaways and contests.
+
+## When to Use This Skill
+
+- Running social media giveaways
+- Picking raffle winners at events
+- Randomly selecting participants for surveys or tests
+- Choosing winners from contest submissions
+- Fair distribution of limited spots or resources
+- Random team assignments
+
+## What This Skill Does
+
+1. **Random Selection**: Uses cryptographically random selection
+2. **Multiple Sources**: Works with CSV, Excel, Google Sheets, or plain lists
+3. **Multiple Winners**: Can pick one or multiple winners
+4. **Duplicate Prevention**: Ensures the same person can't win twice
+5. **Transparent Results**: Shows the selection process clearly
+6. **Winner Details**: Displays all relevant information about winners
+
+## How to Use
+
+### From Google Sheets
+
+```
+Pick a random row from this Google Sheet to select a winner 
+for a giveaway: [Sheet URL]
+```
+
+### From Local File
+
+```
+Pick 3 random winners from entries.csv
+```
+
+### From List
+
+```
+Pick a random winner from this list:
+- Alice (alice@email.com)
+- Bob (bob@email.com)
+- Carol (carol@email.com)
+...
+```
+
+### Multiple Winners
+
+```
+Pick 5 random winners from contest-entries.xlsx, 
+make sure no duplicates
+```
+
+## Example
+
+**User**: "Pick a random row from this Google Sheet to select a winner for a giveaway."
+
+**Output**:
+```
+Accessing Google Sheet...
+Total entries found: 247
+
+Randomly selecting winner...
+
+🎉 WINNER SELECTED! 🎉
+
+Row #142
+Name: Sarah Johnson
+Email: sarah.j@email.com
+Entry Date: March 10, 2024
+Comment: "Love your newsletter!"
+
+Selection method: Cryptographically random
+Timestamp: 2024-03-15 14:32:18 UTC
+
+Would you like to:
+- Pick another winner (excluding Sarah)?
+- Export winner details?
+- Pick runner-ups?
+```
+
+**Inspired by:** Lenny's use case - picking a Sora 2 giveaway winner from his subscriber Slack community
+
+## Features
+
+### Fair Selection
+- Uses secure random number generation
+- No bias or patterns
+- Transparent process
+- Repeatable with seed (for verification)
+
+### Exclusions
+```
+Pick a random winner excluding previous winners: 
+Alice, Bob, Carol
+```
+
+### Weighted Selection
+```
+Pick a winner with weighted probability based on 
+the "entries" column (1 entry = 1 ticket)
+```
+
+### Runner-ups
+```
+Pick 1 winner and 3 runner-ups from the list
+```
+
+## Example Workflows
+
+### Social Media Giveaway
+1. Export entries from Google Form to Sheets
+2. "Pick a random winner from [Sheet URL]"
+3. Verify winner details
+4. Announce publicly with timestamp
+
+### Event Raffle
+1. Create CSV of attendee names and emails
+2. "Pick 10 random winners from attendees.csv"
+3. Export winner list
+4. Email winners directly
+
+### Team Assignment
+1. Have list of participants
+2. "Randomly split this list into 4 equal teams"
+3. Review assignments
+4. Share team rosters
+
+## Tips
+
+- **Document the process**: Save the timestamp and method
+- **Public announcement**: Share selection details for transparency
+- **Check eligibility**: Verify winner meets contest rules
+- **Have backups**: Pick runner-ups in case winner is ineligible
+- **Export results**: Save winner list for records
+
+## Privacy & Fairness
+
+✓ Uses cryptographically secure randomness
+✓ No manipulation possible
+✓ Timestamp recorded for verification
+✓ Can provide seed for third-party verification
+✓ Respects data privacy
+
+## Common Use Cases
+
+- Newsletter subscriber giveaways
+- Product launch raffles
+- Conference ticket drawings
+- Beta tester selection
+- Focus group participant selection
+- Random prize distribution at events
+