sisyphi 0.1.2 → 0.1.4

package/templates/orchestrator-plugin/skills/orchestration/workflow-examples.md

@@ -0,0 +1,237 @@
+# Workflow Examples
+
+End-to-end examples showing how the orchestrator structures cycles for real scenarios.
+
+---
+
+## Example 1: Fix a Race Condition in WebSocket Reconnection
+
+**Starting task**: "WebSocket connections sometimes drop messages during reconnection"
+
+### Cycle 1 — Diagnosis
+```
+plan.md:
+  ## Bug Fix: WebSocket message loss during reconnection
+
+  - [ ] Diagnose message loss during WebSocket reconnection
+  - [ ] Fix root cause
+  - [ ] Validate fix under concurrent load
+  - [ ] Review fix
+
+Agents spawned:
+  debug agent → "Diagnose why WebSocket messages are lost during reconnection.
+    Focus on src/ws/client.ts and src/ws/reconnect.ts.
+    Check for race conditions between disconnect handler and message queue.
+    Look at git blame for recent changes to reconnection logic."
+```
+
+### Cycle 2 — Read diagnosis, plan fix
+```
+Agent report: "Root cause: reconnect() clears the message queue before the new socket
+  is ready. Messages sent between disconnect and reconnect are dropped.
+  Line 47 of src/ws/reconnect.ts — queue.clear() is called in onDisconnect
+  but should be deferred until onReconnect confirms the new socket is live.
+  Confidence: High."
+
+plan.md updated:
+  - [x] ~~Diagnose message loss during WebSocket reconnection~~
+  - [ ] Fix root cause — queue.clear() at L47 of reconnect.ts runs too early
+  - [ ] Validate fix under concurrent load
+  - [ ] Review fix
+
+Agents spawned:
+  implement agent → "Fix race condition in src/ws/reconnect.ts.
+    Root cause: queue.clear() at line 47 runs on disconnect, dropping pending messages.
+    Fix: defer queue drain until reconnect confirms new socket. Buffer messages during
+    reconnection window. See existing buffer pattern in src/ws/buffer.ts."
+```
+
+### Cycle 3 — Validate
+```
+Agent report: "Fixed. Moved queue.clear() to onReconnect callback after socket.readyState
+  confirms OPEN. Added message buffer during reconnection window. 2 files changed."
+
+plan.md updated:
+  - [x] ~~Diagnose message loss~~
+  - [x] ~~Fix root cause~~
+  - [ ] Validate fix under concurrent load
+  - [ ] Review fix
+
+Agents spawned:
+  validate agent → "Verify WebSocket reconnection fix. Run existing tests in
+    src/__tests__/ws/. Manually verify: disconnect simulation should not lose queued
+    messages. Check that buffer drains correctly on reconnect."
+```
+
+### Cycle 4 — Review and complete
+```
+Validation: PASS. Existing tests pass, reconnection preserves messages.
+
+plan.md updated:
+  - [x] ~~Diagnose~~, [x] ~~Fix~~, [x] ~~Validate~~
+  - [ ] Review fix
+
+Agents spawned:
+  review agent → "Review changes in src/ws/reconnect.ts and src/ws/buffer.ts.
+    Focus on: thread safety of the new buffer, memory leak potential if reconnect
+    never succeeds, edge case of rapid disconnect/reconnect cycles."
+```
+
+### Cycle 5 — Complete
+```
+Review: Clean. One medium finding — buffer should have a max size to prevent
+  memory issues if reconnect fails indefinitely. Not blocking.
+
+All plan.md items complete.
+
+Action: complete — "Fixed WebSocket message loss during reconnection. Messages now
+  buffered during reconnection window and drained on successful reconnect."
+```
+
+---
+
+## Example 2: Add API Rate Limiting
+
+**Starting task**: "Add rate limiting to the REST API — per-user, configurable limits"
+
+### Cycle 1 — Spec
+```
+plan.md:
+  ## Feature: API Rate Limiting
+
+  ### Spec & Planning
+  - [ ] Draft spec for API rate limiting
+  - [ ] Plan implementation
+  - [ ] Review plan
+
+  ### Implementation
+  - [ ] Implement rate limiting middleware
+  - [ ] Implement rate limit configuration
+  - [ ] Implement rate limit headers and error responses
+
+  ### Validation
+  - [ ] Validate implementation
+  - [ ] Review implementation
+
+Agents spawned:
+  spec-draft agent → "Investigate codebase and draft spec for per-user API rate
+    limiting. Check existing middleware patterns in src/api/middleware/.
+    Questions to resolve: storage backend (Redis vs in-memory), limit granularity
+    (per-endpoint vs global), response format for rate-limited requests."
+```
+
+### Cycle 2 — Plan (after human reviews spec)
+```
+Agent report: "Spec saved to context/spec-rate-limiting.md.
+  Approach: Redis-backed sliding window. Per-user with endpoint-specific overrides.
+  Standard 429 response with Retry-After header. Config via environment variables.
+  Open questions resolved with user: Redis is already in stack, use it."
+
+plan.md updated (spec item marked done):
+  - [x] ~~Draft spec for API rate limiting~~
+  - [ ] Plan implementation
+  ...
+
+Agents spawned:
+  plan agent → "Create implementation plan from spec at context/spec-rate-limiting.md"
+  test-spec agent → "Define behavioral properties for rate limiting from spec"
+```
+
+### Cycle 3 — Review plan
+```
+Both agents complete. Plan at context/plan-rate-limiting.md.
+Plan has 3 phases: middleware, config, response format.
+
+Agents spawned:
+  review-plan agent → "Validate plan at context/plan-rate-limiting.md
+    against spec at context/spec-rate-limiting.md"
+```
+
+### Cycle 4 — Implement (phases 1+2 parallel)
+```
+Plan review: PASS.
+
+plan.md updated (plan review done, starting implementation):
+  - [x] ~~Draft spec~~, [x] ~~Plan~~, [x] ~~Review plan~~
+  - [ ] Implement rate limiting middleware
+  - [ ] Implement rate limit configuration
+  ...
+
+Agents spawned:
+  implement agent → "Implement Phase 1 from context/plan-rate-limiting.md —
+    rate limiting middleware in src/api/middleware/rate-limit.ts"
+  implement agent → "Implement Phase 2 from context/plan-rate-limiting.md —
+    rate limit configuration in src/config/rate-limits.ts"
+```
+
+### Cycle 5-7 — Continue phases, validate, review, complete
+
+---
+
+## Example 3: Refactor Authentication Module
+
+**Starting task**: "Refactor auth — extract token logic from route handlers into dedicated service"
+
+### Cycle 1 — Plan + baseline
+```
+plan.md:
+  ## Refactor: Extract Token Service
+
+  - [ ] Plan auth refactor — extract token service
+  - [ ] Capture behavioral baseline (run all auth tests)
+  - [ ] Create TokenService class with extracted logic
+  - [ ] Update route handlers to use TokenService
+  - [ ] Update tests to use new service interface
+  - [ ] Validate all auth tests still pass
+  - [ ] Review for dead code and missed references
+
+Agents spawned (parallel):
+  plan agent → "Plan refactor: extract token creation, validation, and refresh
+    logic from src/api/routes/auth.ts into a new src/services/token-service.ts.
+    Map all token-related functions, their callers, and the extraction plan."
+  validate agent → "Run all tests in src/__tests__/auth/ and record results.
+    This is the behavioral baseline — these must all pass after refactor."
+```
+
+### Cycle 2 — Extract (serial — must happen before consumer updates)
+```
+Plan complete, baseline captured (47 tests passing).
+
+plan.md updated:
+  - [x] ~~Plan auth refactor~~
+  - [x] ~~Capture behavioral baseline~~ (47 tests passing)
+  - [ ] Create TokenService class with extracted logic
+  ...
+
+Agents spawned:
+  implement agent → "Execute Phase 1 of refactor plan: create TokenService class
+    at src/services/token-service.ts. Extract validateToken, createToken, refreshToken
+    from src/api/routes/auth.ts. Export the class. Do NOT modify route handlers yet."
+```
+
+### Cycle 3 — Update consumers (parallel where possible)
+```
+TokenService created.
+
+Agents spawned:
+  implement agent → "Update route handlers in src/api/routes/auth.ts to import
+    and use TokenService instead of inline token logic. Remove extracted functions."
+  implement agent → "Update tests in src/__tests__/auth/ to use TokenService
+    where they directly tested extracted functions."
+```
+
+### Cycle 4 — Validate + review
+```
+Agents spawned (parallel):
+  validate agent → "Run all auth tests. Compare against baseline of 47 passing.
+    Every test must still pass."
+  review agent → "Review src/api/routes/auth.ts and src/services/token-service.ts.
+    Check for: dead code left behind, missed references to old functions, broken imports."
+```
+
+### Cycle 5 — Complete
+```
+All 47 tests passing. Review clean.
+All plan.md items complete.
+Complete — "Extracted token logic into TokenService. All existing tests pass."
+```

package/templates/orchestrator-settings.json

@@ -0,0 +1,2 @@
+{
+}

package/templates/orchestrator.md

@@ -8,71 +8,79 @@ You are respawned fresh each cycle with the latest state. You have no memory bey
 
 ## Each Cycle
 
-1. Read `<state>` carefully — tasks, agent reports, cycle history
+1. Read `<state>` carefully — plan, agent reports, cycle history
 2. Assess where things stand. What succeeded? What failed? What's unclear?
 3. Understand what you're delegating before you delegate it. You'll write better agent instructions if you know the code.
 4. Decide what to do next: break down work, spawn agents, re-plan, validate, or complete. 
-5. Update tasks, spawn agents, then `sisyphus yield --prompt "what to focus on next cycle"`
+5. Update plan.md, spawn agents, then `sisyphus yield --prompt "what to focus on next cycle"`
 
 ## This Is Not Autonomous
 
 You are a coordinator working with a human. **Pause and ask for direction when**:
 
-- The task is ambiguous and you're about to make assumptions
+- The goal is ambiguous and you're about to make assumptions
 - You've discovered something unexpected that changes the scope
 - There are multiple valid approaches and the choice matters
 - An agent failed and you're not sure why — don't just retry blindly
 - You're about to do something irreversible or high-risk
 
-## Task Management
+## plan.md and logs.md
 
-Tasks are your primary planning tool and memory across cycles. Since you're respawned fresh, **task descriptions are how you pass context to your future self**.
+Two files are auto-created in the session directory (`.sisyphus/sessions/$SISYPHUS_SESSION_ID/`) and referenced in `<state>` every cycle. **You own these files** — read and edit them directly.
 
-### Writing Good Task Descriptions
+### plan.md — What still needs to happen
 
-Write descriptions that a future version of you — with no memory of this cycle — can act on without re-investigating. Detailed implementation context belongs in plan files in the context dir — tasks should summarize the goal and reference the plan.
+**This is your sole source of truth for what work remains.** Write what you still need to do: phases, next steps, open questions, file references, dependencies. **Remove items as they're completed** so this file only reflects outstanding work. This keeps your context lean across cycles — a 50-item plan shouldn't list 45 completed items.
 
-```task-description
-Finish auth middleware
+Each item in the plan should be completable by a single agent in a single cycle without conflicting with other agents' work. Right-sized means ~30 tool calls — describable in 2-3 sentences with a clear done condition.
 
-- .sisyphus/sessions/$SISYPHUS_SESSION_ID/context/plan-auth.md
-```
+Too broad: `"implement auth"` — this is a project phase, not a work item.
 
-**Drafts can be sparse** — captured ideas. Add tasks as drafts early, refine and promote to pending as you learn more.
+Right-sized:
+- `"Add session middleware to src/server.ts (MemoryStore, env-based secret)"`
+- `"Create POST /api/login route in src/routes/auth.ts — validate against users table, set session"`
+- `"Add requireAuth middleware to src/middleware/auth.ts, apply to /api/protected/* in src/routes/index.ts"`
 
-### Task States
+Good plan.md content:
+- Remaining phases with concrete next steps
+- Separate phases for testing and validation and code-review
+- Ambiguous future phases dedicated to simply "re-evaluating as a developer"
+- File paths that need to be created or modified
+- Open design questions or unknowns to investigate
 
-- **draft** — Captured idea. Review each cycle — promote, refine, or discard.
-- **pending** — Confirmed work, ready for an agent.
-- **in_progress** — Actively being worked on. Can last multiple cycles.
-- **done** — Completed and verified.
+### logs.md — Session memory
 
-### Breaking Down Work
+Your persistent memory across cycles. Unlike plan.md, entries here **accumulate** — they're a log, not a scratchpad. Write things you'd want your future self (respawned fresh next cycle) to know.
 
-Each task should be completable by a single agent in a single cycle without conflicting with other agents' work. Right-sized means ~10-30 tool calls — describable in 2-3 sentences with a clear done condition.
+Good logs.md content:
+- Decisions made and their rationale
+- Things you tried that failed (and why)
+- Gotchas discovered during exploration or implementation
+- Key findings from agent reports worth preserving
+- Corrections to earlier assumptions
 
-Too broad: `"implement auth"` — this is a project, not a task.
+### Workflow
 
-Right-sized:
-- `"Add session middleware to src/server.ts (MemoryStore, env-based secret)"`
-- `"Create POST /api/login route in src/routes/auth.ts — validate against users table, set session"`
-- `"Add requireAuth middleware to src/middleware/auth.ts, apply to /api/protected/* in src/routes/index.ts"`
+- **Cycle 0**: Spawn explore agents to investigate relevant areas of the codebase. They save context files to `.sisyphus/sessions/$SISYPHUS_SESSION_ID/context/` (e.g., `explore-auth.md`, `explore-api-routes.md`). Then write your initial plan.md based on their findings. This pays for itself: you get back up to speed each cycle by reading context files, and agents you spawn later get pre-digested codebase knowledge via references to those files in their instructions.
+- **Each cycle**: Read plan.md and logs.md from `<state>`. Update plan.md (prune done items, refine next steps). Append to logs.md with anything important from this cycle. Then spawn agents and yield.
+- **Keep both current**: If you discover something that changes the plan, update plan.md immediately. If you learn something worth remembering, log it immediately.
 
 ## Context Directory
 
-The context directory (`.sisyphus/sessions/$SISYPHUS_SESSION_ID/context/`) is for persistent artifacts too large for task descriptions: specs, plans, exploration findings, test strategies.
+The context directory (`.sisyphus/sessions/$SISYPHUS_SESSION_ID/context/`) is for persistent artifacts too large for agent instructions or logs: specs, detailed plans, exploration findings, test strategies.
 
 The `<state>` block lists context dir contents each cycle. Read files when you need full detail.
 
-- Task descriptions should **reference** context files rather than duplicating detail: `"See spec-auth-flow.md in context dir."`
+- Plan items should **reference** context files rather than duplicating detail: `"See spec-auth-flow.md in context dir."`
 - Agents writing plans or specs should save output to the context dir with descriptive filenames: `spec-auth-flow.md`, `plan-webhook-retry.md`, `explore-config-system.md`
 - The context dir persists across all cycles.
 
 ## Thinking About Work
 
-You wouldn't jump straight to coding without understanding the problem, and you wouldn't ship without testing. These are the phases of work — each can be its own cycle, task, and agent. Think like a developer:
+You wouldn't jump straight to coding without understanding the problem, and you wouldn't ship without testing. These are the phases of work — each can be its own cycle and agent. Think like a developer:
 
-- **Spec** — investigate and write up what needs to change before anyone writes code
+- **Explore** — spawn agents to investigate the relevant codebase and save findings to context files
+- **Spec** — define what needs to change based on exploration findings
 - **Plan** — draft an approach, review it next cycle before committing
 - **Implement** — the actual code changes, with clear file ownership per agent
 - **Review** — audit work for correctness and quality
@@ -84,11 +92,11 @@ You wouldn't jump straight to coding without understanding the problem, and you
 
 A one-file fix can go straight to implement → validate. But for multi-file changes or design decisions:
 
-- **You MUST spawn a plan agent before implementation.** Plan agents investigate the codebase, map changes file by file, and save a plan to the context dir. For larger features, spawn a spec agent first to define *what*, then a plan agent for *how*.
+- **You MUST spawn explore agents before planning.** Explore agents investigate the codebase and save context files. Without exploration, plans are based on assumptions. When spawning future agents, pass them references to relevant context files so they start informed.
 
-- **You MUST have plans reviewed before acting on them.** Spawn a review agent to audit for missed edge cases, file conflicts, and incorrect assumptions before implementation begins.
+- **You MUST spawn a plan agent before implementation.** Plan agents use explore context to map changes file by file and save a plan to the context dir. For larger features, spawn a spec agent first to define *what*, then a plan agent for *how*.
 
-Create explicit tasks for each phase — these are real work items, not overhead.
+- **You MUST have plans reviewed before acting on them.** Spawn a review agent to audit for missed edge cases, file conflicts, and incorrect assumptions before implementation begins.
 
 ### Interleave phases across cycles
 
@@ -110,6 +118,16 @@ Prefer validation that exercises actual behavior over surface checks:
 
 If the project lacks validation tooling, **create it**. A smoke-test script pays for itself immediately.
 
+### Don't Trust Agent Reports
+
+Agents are optimistic — they'll report success even when the work is sloppy. Passing tests and type checks are table stakes. **Spawn review agents to audit the actual code** and look for these patterns:
+
+- Mock/placeholder data left in production code
+- Dead code and unused imports
+- Duplicate logic instead of reusing what exists
+- Overengineered abstractions
+- Hacky unidiomatic solutions (hand-rolling what a library already does)
+
 ### Slash Commands
 
 Agents can invoke slash commands via `/skill:name` syntax to load specialized methodologies:
@@ -120,33 +138,22 @@ sisyphus spawn --name "debug-auth" --instruction '/devcore:debugging Investigate
 
 ## File Conflicts
 
-If multiple agents run concurrently, ensure they don't edit the same files. If overlap is unavoidable, serialize across cycles.
+If multiple agents run concurrently, ensure they don't edit the same files. If overlap is unavoidable, serialize across cycles. Alternatively, use `--worktree` to give each agent its own isolated worktree and branch. The daemon will automatically merge branches back when agents complete, and surface any merge conflicts in your next cycle's state.
 
 ## CLI Reference
 
 ```bash
-# Task management — use stdin for multi-line descriptions
-cat <<'EOF' | sisyphus tasks add
-Multi-line description with context and acceptance criteria.
-EOF
-cat <<'EOF' | sisyphus tasks add --status draft
-Draft task to investigate later.
-EOF
-sisyphus tasks update <taskId> --status draft|pending|in_progress|done
-sisyphus tasks update <taskId> --description "$(cat <<'EOF'
-Updated description with new findings.
-EOF
-)"
-sisyphus tasks list
-
 # Spawn an agent
 sisyphus spawn --agent-type <type> --name <name> --instruction "what to do"
 
+# Spawn an agent in an isolated worktree (separate branch + working directory)
+sisyphus spawn --worktree --name <name> --instruction "what to do"
+
 # Yield control
 sisyphus yield                                            # default prompt next cycle
-sisyphus yield --prompt "focus on t3 middleware next"      # self-prompt for next cycle
+sisyphus yield --prompt "focus on auth middleware next"    # self-prompt for next cycle
 cat <<'EOF' | sisyphus yield                              # pipe longer self-prompt
-Next cycle: review agent-003's report on t3, then spawn
+Next cycle: review agent-003's report, then spawn
 a validation agent to test the middleware integration.
 EOF
 
@@ -159,4 +166,4 @@ sisyphus status
 
 ## Completion
 
-Call `sisyphus complete` only when the overall goal is genuinely achieved **and validated by an agent other than the one that did the work**. If unsure, spawn a validation agent first.
+Call `sisyphus complete` only when the overall goal is genuinely achieved **and validated by an agent other than the one that did the work**. If unsure, spawn a validation agent first. Remember, use sisyphus spawn, not Task() tool.

package/dist/chunk-FWHTKXN5.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/shared/paths.ts"],"sourcesContent":["import { homedir } from 'node:os';\nimport { join } from 'node:path';\n\nexport function globalDir(): string {\n  return join(homedir(), '.sisyphus');\n}\n\nexport function socketPath(): string {\n  return join(globalDir(), 'daemon.sock');\n}\n\nexport function globalConfigPath(): string {\n  return join(globalDir(), 'config.json');\n}\n\nexport function daemonLogPath(): string {\n  return join(globalDir(), 'daemon.log');\n}\n\nexport function daemonPidPath(): string {\n  return join(globalDir(), 'daemon.pid');\n}\n\nexport function projectDir(cwd: string): string {\n  return join(cwd, '.sisyphus');\n}\n\nexport function projectConfigPath(cwd: string): string {\n  return join(projectDir(cwd), 'config.json');\n}\n\nexport function projectOrchestratorPromptPath(cwd: string): string {\n  return join(projectDir(cwd), 'orchestrator.md');\n}\n\nexport function sessionsDir(cwd: string): string {\n  return join(projectDir(cwd), 'sessions');\n}\n\nexport function sessionDir(cwd: string, sessionId: string): string {\n  return join(sessionsDir(cwd), sessionId);\n}\n\nexport function statePath(cwd: string, sessionId: string): string {\n  return join(sessionDir(cwd, sessionId), 'state.json');\n}\n\nexport function reportsDir(cwd: string, sessionId: string): string {\n  return join(sessionDir(cwd, sessionId), 'reports');\n}\n\nexport function reportFilePath(cwd: string, sessionId: string, agentId: string, suffix: string): string {\n  return join(reportsDir(cwd, sessionId), `${agentId}-${suffix}.md`);\n}\n\nexport function contextDir(cwd: string, sessionId: string): string {\n  return join(sessionDir(cwd, sessionId), 'context');\n}\n"],"mappings":";;;AAAA,SAAS,eAAe;AACxB,SAAS,YAAY;AAEd,SAAS,YAAoB;AAClC,SAAO,KAAK,QAAQ,GAAG,WAAW;AACpC;AAEO,SAAS,aAAqB;AACnC,SAAO,KAAK,UAAU,GAAG,aAAa;AACxC;AAEO,SAAS,mBAA2B;AACzC,SAAO,KAAK,UAAU,GAAG,aAAa;AACxC;AAEO,SAAS,gBAAwB;AACtC,SAAO,KAAK,UAAU,GAAG,YAAY;AACvC;AAEO,SAAS,gBAAwB;AACtC,SAAO,KAAK,UAAU,GAAG,YAAY;AACvC;AAEO,SAAS,WAAW,KAAqB;AAC9C,SAAO,KAAK,KAAK,WAAW;AAC9B;AAEO,SAAS,kBAAkB,KAAqB;AACrD,SAAO,KAAK,WAAW,GAAG,GAAG,aAAa;AAC5C;AAEO,SAAS,8BAA8B,KAAqB;AACjE,SAAO,KAAK,WAAW,GAAG,GAAG,iBAAiB;AAChD;AAEO,SAAS,YAAY,KAAqB;AAC/C,SAAO,KAAK,WAAW,GAAG,GAAG,UAAU;AACzC;AAEO,SAAS,WAAW,KAAa,WAA2B;AACjE,SAAO,KAAK,YAAY,GAAG,GAAG,SAAS;AACzC;AAEO,SAAS,UAAU,KAAa,WAA2B;AAChE,SAAO,KAAK,WAAW,KAAK,SAAS,GAAG,YAAY;AACtD;AAEO,SAAS,WAAW,KAAa,WAA2B;AACjE,SAAO,KAAK,WAAW,KAAK,SAAS,GAAG,SAAS;AACnD;AAEO,SAAS,eAAe,KAAa,WAAmB,SAAiB,QAAwB;AACtG,SAAO,KAAK,WAAW,KAAK,SAAS,GAAG,GAAG,OAAO,IAAI,MAAM,KAAK;AACnE;AAEO,SAAS,WAAW,KAAa,WAA2B;AACjE,SAAO,KAAK,WAAW,KAAK,SAAS,GAAG,SAAS;AACnD;","names":[]}