claude-code-orchestrator-kit 1.2.3 → 1.2.5

package/.claude/skills/resume-session/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: resume-session
+description: Resume a previously saved session by loading context and recent log entries. Use at start of orchestrator workflows to check for existing sessions.
+trigger: At the start of health workflows, or when user asks to continue previous work
+---
+
+# Resume Session
+
+Checks for and loads a previously saved session context, enabling seamless workflow continuation.
+
+## When to Use
+
+- At the start of health orchestrator workflows (automatic)
+- When user explicitly asks to continue previous work
+- After session restart or context switch
+
+## When NOT to Use
+
+- For new workflows with no prior context
+- When user explicitly wants to start fresh
+
+## Algorithm
+
+### Step 1: Check for Existing Session
+
+Check if `.tmp/current/session/context.md` exists.
+
+### Step 2: Validate Freshness
+
+If file exists, check the "Updated" timestamp:
+- If < 24 hours old: Session is valid
+- If > 24 hours old: Session is stale, ask user
+
+### Step 3: Load Context
+
+Read `.tmp/current/session/context.md` and extract:
+- Current workflow and phase
+- Last action and next steps
+- Git state
+- Quality gate status
+
+### Step 4: Load Recent Log Entries
+
+Read last 10 entries from `.tmp/current/session/log.md`:
+- Recent decisions
+- Issues encountered
+- Learnings
+
+### Step 5: Present Resume Option
+
+If valid session found, present to user:
+```
+Found previous session:
+- Workflow: health-bugs
+- Phase: 3/7 (Staged Fixing)
+- Last action: Fixed auth validation
+- Age: 2 hours ago
+
+Options:
+1. Resume from where you left off
+2. Start fresh (archive current session)
+```
+
+### Step 6: On Resume
+
+Return combined context for orchestrator to continue:
+```markdown
+## Resuming Session
+
+### Current State
+[Content from context.md]
+
+### Recent Decisions
+[Last 5 entries from log.md]
+
+### Next Actions
+[From context.md Next Steps section]
+```
+
+### Step 7: On Start Fresh
+
+If user chooses fresh start:
+1. Move current session files to `.tmp/archive/session-[timestamp]/`
+2. Return empty context
+3. Orchestrator starts Phase 1
+
+## Implementation
+
+```markdown
+### Check session exists
+
+Read `.tmp/current/session/context.md`
+
+If not found:
+  Return "No previous session found. Starting fresh."
+
+### Validate timestamp
+
+Extract "Updated: YYYY-MM-DDTHH:MM:SS" from file
+Calculate age in hours
+
+If age > 24:
+  Ask user: "Session is [X] hours old. Resume or start fresh?"
+
+### Load and return
+
+Read context.md fully
+Read last 500 lines of log.md (covers ~10 entries)
+Return combined content
+```
+
+## Output Format
+
+### When session found:
+```
+Previous session found:
+- Workflow: health-bugs
+- Phase: 3/7 (Staged Fixing)
+- Age: 2h 15m
+- Last: Fixed auth validation in src/auth.ts
+
+Resume? [Y/n]
+```
+
+### When no session:
+```
+No previous session found. Starting fresh workflow.
+```
+
+### When stale:
+```
+Found stale session (26 hours old):
+- Workflow: health-security
+- Phase: 2/5
+
+[R]esume anyway, [A]rchive and start fresh, or [C]ancel?
+```
+
+## Token Cost
+
+- Context read: ~100-150 tokens
+- Log read (last 10 entries): ~200-300 tokens
+- Total: ~300-450 tokens (only when resuming)
+
+## Related Skills
+
+- `save-session-context` — Save current state for later
+- `load-project-context` — Load project structure
+
+## Integration with Orchestrators
+
+Health orchestrators should call this skill in Phase 0:
+
+```markdown
+## Phase 0: Session Check
+
+1. Invoke `resume-session` skill
+2. If valid session:
+   - Ask user: Resume or fresh?
+   - If resume: Jump to saved phase
+3. If no session:
+   - Proceed to Phase 1
+4. Create new session context
+```

package/.claude/skills/save-session-context/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: save-session-context
+description: Save current session state for later resumption. Use after completing workflow phases or before ending a session.
+trigger: After completing a workflow phase, before session end, or when switching to different task
+---
+
+# Save Session Context
+
+Saves the current workflow state to enable seamless session resumption.
+
+## When to Use
+
+- After completing each phase in health orchestrator workflows
+- Before ending a long-running session
+- When switching context to a different task
+- After significant progress that should be preserved
+
+## When NOT to Use
+
+- For simple, quick tasks that don't need resumption
+- When workflow is fully complete (clean up instead)
+
+## Algorithm
+
+### Step 1: Gather Current State
+
+Collect the following information:
+- Current workflow name and phase
+- Priority level and completion counts
+- Last completed action
+- List of modified files (from git status)
+
+### Step 2: Get Git State
+
+Run `git status` and `git log -1` to capture:
+- Current branch
+- Uncommitted files count
+- Last commit hash and message
+
+### Step 3: Determine Next Steps
+
+Based on current phase and workflow, identify:
+- Immediate next action
+- Following 2-3 actions
+
+### Step 4: Write Context File
+
+Write to `.tmp/current/session/context.md`:
+
+```markdown
+# Session Context
+
+> Auto-generated by save-session-context skill. Updated: [ISO timestamp]
+
+## Current State
+
+- **Workflow:** [workflow-name]
+- **Phase:** [current]/[total] ([phase-name])
+- **Priority:** [priority-level] ([completed] of [total] fixed)
+- **Last Action:** [description]
+
+## Active Files
+
+[List from git status]
+
+## Next Steps
+
+1. [Next action]
+2. [Following action]
+3. [Third action]
+
+## Git State
+
+- **Branch:** [branch-name]
+- **Uncommitted:** [count] files
+- **Last Commit:** [hash] "[message]"
+
+## Quality Gate Status
+
+- **Type-check:** [status]
+- **Build:** [status]
+- **Tests:** [status]
+
+## Resume Instructions
+
+To continue this session:
+1. Read this file to understand current state
+2. Read `session-log.md` for recent decisions
+3. Continue from "Next Steps" section
+```
+
+### Step 5: Confirm Save
+
+Output confirmation message with file path.
+
+## Implementation Notes
+
+```bash
+# Get git state
+git status --porcelain | wc -l  # Uncommitted count
+git log -1 --format="%h %s"     # Last commit
+git branch --show-current       # Current branch
+```
+
+## Output
+
+Confirmation message:
+```
+Session context saved to .tmp/current/session/context.md
+- Workflow: health-bugs
+- Phase: 3/7 (Staged Fixing)
+- Uncommitted: 2 files
+```
+
+## Token Cost
+
+- Execution: ~50 tokens for git commands
+- Output: 0 (write-only operation)
+
+## Related Skills
+
+- `resume-session` — Read saved context to continue
+- `run-quality-gate` — Update quality gate status in context

package/.claude/templates/project-index.template.md

@@ -0,0 +1,67 @@
+# Project Index
+
+> Quick navigation for AI agents. Updated: YYYY-MM-DD
+>
+> **Purpose:** This file helps agents understand project structure without reading entire codebase.
+> **Usage:** Read by `load-project-context` skill when exploring unfamiliar areas.
+
+## Architecture
+
+- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** — System design, diagrams, data flow
+- **[CLAUDE.md](CLAUDE.md)** — Behavioral rules, orchestration patterns
+
+## Core Domains
+
+### [Domain 1 Name]
+- **[path/to/domain/](path/to/domain/)** — Brief description of what this domain does
+  - Key: `src/` — Main source code
+  - Key: `types/` — TypeScript types and interfaces
+  - Pattern: [Describe the main pattern used, e.g., "Repository pattern", "MVC"]
+
+### [Domain 2 Name]
+- **[path/to/domain/](path/to/domain/)** — Brief description
+  - Key: `components/` — UI components
+  - Key: `hooks/` — Custom React hooks
+
+## Shared Code
+
+- **[packages/shared/](packages/shared/)** — Shared utilities, types, constants
+  - Key: `utils/` — Helper functions
+  - Key: `types/` — Shared TypeScript types
+
+## Configuration
+
+- **[.env.example](.env.example)** — Environment variables template
+- **[tsconfig.json](tsconfig.json)** — TypeScript configuration
+- **[package.json](package.json)** — Dependencies and scripts
+
+## Patterns & Conventions
+
+- **Auth:** [How authentication is implemented]
+- **State:** [State management approach]
+- **Styling:** [CSS/styling approach]
+- **Testing:** [Testing framework and patterns]
+- **Error Handling:** [How errors are handled]
+
+## Key Entry Points
+
+| Purpose | File | Description |
+|---------|------|-------------|
+| App entry | `src/index.ts` | Main application entry point |
+| API routes | `src/routes/` | All API endpoints |
+| Database | `src/db/` | Database connection and queries |
+
+## Recent Changes (last 7 days)
+
+- YYYY-MM-DD: [Brief description of change]
+- YYYY-MM-DD: [Brief description of change]
+
+---
+
+## Usage Notes
+
+1. Keep this file under 150 lines
+2. Update "Recent Changes" weekly
+3. Only include KEY directories and files
+4. Annotations should be 1 line max
+5. Link to detailed docs, don't duplicate content

package/.claude/templates/session/context.template.md

@@ -0,0 +1,40 @@
+# Session Context
+
+> Auto-generated by save-session-context skill. Updated: YYYY-MM-DDTHH:MM:SS
+
+## Current State
+
+- **Workflow:** [workflow-name]
+- **Phase:** [current]/[total] ([phase-name])
+- **Priority:** [priority-level] ([completed] of [total] [type])
+- **Last Action:** [brief description of last completed action]
+
+## Active Files
+
+- `path/to/file1.ts` — [status: Modified/Created/Deleted], [not committed/committed]
+- `path/to/file2.ts` — [status], [commit status]
+
+## Next Steps
+
+1. [Next immediate action]
+2. [Following action]
+3. [Action after that]
+
+## Git State
+
+- **Branch:** [current-branch-name]
+- **Uncommitted:** [count] files
+- **Last Commit:** [short-hash] "[commit-message]"
+
+## Quality Gate Status
+
+- **Type-check:** [PASS/FAIL/NOT_RUN]
+- **Build:** [PASS/FAIL/NOT_RUN]
+- **Tests:** [PASS/FAIL/NOT_RUN]
+
+## Resume Instructions
+
+To continue this session:
+1. Read this file to understand current state
+2. Read `session-log.md` for recent decisions and issues
+3. Continue from "Next Steps" section

package/.claude/templates/session/log.template.md

@@ -0,0 +1,72 @@
+# Session Log
+
+> Decisions, issues, and learnings from this session.
+> Newest entries at the top.
+
+---
+
+## YYYY-MM-DDTHH:MM:SS
+
+### [Category]: [Brief Title]
+
+**Context:** [What were you trying to do]
+
+**Issue/Decision:** [What happened or what decision was made]
+
+**Resolution:** [How it was resolved or why this decision was made]
+
+**Learning:** [Optional - what to remember for future]
+
+---
+
+## Entry Categories
+
+Use these categories for consistency:
+
+- **Decision** — Architectural or implementation choice made
+- **Issue** — Problem encountered and how it was solved
+- **Discovery** — Something learned about the codebase
+- **Blocker** — Something that stopped progress (and resolution)
+- **Rollback** — Change that was reverted and why
+
+---
+
+## Example Entries
+
+### 2025-11-27T14:30:00
+
+### Decision: Auth validation approach
+
+**Context:** Multiple auth checks scattered across codebase
+
+**Issue/Decision:** Chose middleware-based approach over per-route validation
+
+**Resolution:** Created `authMiddleware.ts` in `src/middleware/`
+
+**Learning:** Check existing patterns in `middleware/` before adding new auth logic
+
+---
+
+### 2025-11-27T15:00:00
+
+### Issue: TypeScript error after fix
+
+**Context:** Fixed auth validation, but broke type inference
+
+**Issue/Decision:** Type 'string | undefined' not assignable to 'string'
+
+**Resolution:** Added nullish coalescing `?? ''` fallback
+
+---
+
+### 2025-11-27T15:30:00
+
+### Blocker: Missing dependency
+
+**Context:** Tried to use zod validation
+
+**Issue/Decision:** zod not installed in this package
+
+**Resolution:** Added to package.json, ran pnpm install
+
+**Learning:** Check package.json before using external libraries

package/CLAUDE.md

@@ -77,6 +77,23 @@ If contradictions occur:
 - If truly ambiguous: ask user with specific options
 - Only ask when unable to determine best practice (rare, ~10%)
 
+**8. LIBRARY-FIRST APPROACH (MANDATORY)**
+
+Before writing new code (>20 lines), ALWAYS search for existing libraries:
+- WebSearch: "npm {functionality} library 2024" or "python {functionality} package"
+- Context7: documentation for candidate libraries
+- Check: weekly downloads >1000, commits in last 6 months, TypeScript/types support
+
+**Use library when**:
+- Covers >70% of required functionality
+- Actively maintained, no critical vulnerabilities
+- Reasonable bundle size (check bundlephobia.com)
+
+**Write custom code when**:
+- <20 lines of simple logic
+- All libraries abandoned or insecure
+- Core business logic requiring full control
+
 ### Planning Phase (ALWAYS First)
 
 Before implementing tasks:

package/README.md

@@ -60,7 +60,7 @@ Complete toolkit with **33+ AI agents**, **quality gates**, **health monitoring*
 
 ### ⚙️ **MCP Server Configurations**
 
-Switch between 6 optimized MCP configurations based on your needs:
+Switch between 7 optimized MCP configurations based on your needs:
 
 | Configuration | Servers | Token Usage | Use Case |
 |---------------|---------|-------------|----------|
@@ -69,7 +69,8 @@ Switch between 6 optimized MCP configurations based on your needs:
 | **SUPABASE-FULL** | Base + Supabase (dual) | ~3000 | Multi-project database |
 | **N8N** | Base + n8n automation | ~2500 | Workflow automation |
 | **FRONTEND** | Base + Playwright + ShadCN | ~2000 | UI/UX development |
-| **FULL** | All servers enabled | ~5000 | Maximum capabilities |
+| **SERENA** | Base + Serena LSP | ~2500 | Semantic code search |
+| **FULL** | All servers + Serena | ~6500 | Maximum capabilities |
 
 ### 🚀 **Slash Commands**
 
@@ -231,6 +232,37 @@ Orchestrator → Resume → Verify → Next phase
 
 **Result**: Main Claude Code stays lean, all context gathered on-demand.
 
+### 🧠 **DeksdenFlow Integration (Lazy Knowledge Loading)**
+
+Inspired by [deksden-flow](https://github.com/deksden/deksden-flow), we implement **zero-overhead context management**:
+
+**Project Index** (`.claude/project-index.md`):
+- Compact project map with annotated links
+- Loaded on-demand via `load-project-context` skill
+- ~100-200 tokens when used, 0 at baseline
+
+**Session Context** (`.tmp/current/session/`):
+- `context.md`: Current workflow state for resumption
+- `log.md`: Decisions, issues, learnings (write-only)
+- Enables seamless session continuation
+
+**Why It Matters**:
+- Resume health workflows after session restart
+- Track decisions for debugging
+- Navigate codebase without full exploration
+
+**Token Impact**: Zero baseline overhead. Skills load context only when needed.
+
+### 🔬 **Serena LSP Integration**
+
+**Serena MCP** provides semantic code understanding via Language Server Protocol:
+- **Symbol Search**: Find functions, classes, types by name
+- **Reference Lookup**: "Find all usages of X"
+- **Intelligent Refactoring**: Rename with full reference awareness
+- **Context**: `ide-assistant` mode avoids tool duplication
+
+**When to Use**: Large codebases where Grep produces too many false positives.
+
 ---
 
 ## 🚀 Quick Start
@@ -246,7 +278,7 @@ cp .env.example .env.local
 
 # 3. Choose MCP configuration
 ./switch-mcp.sh
-# Select option 1-6 based on your needs
+# Select option 1-7 based on your needs
 
 # 4. Restart Claude Code
 # Your orchestration system is ready!
@@ -815,6 +847,14 @@ Reusable utilities accessible via `Skill` tool.
 | `render-template` | Variable substitution in templates |
 | `rollback-changes` | Restore files from changes log |
 
+### Context & Session Skills (DeksdenFlow)
+
+| Skill | Purpose |
+|-------|---------|
+| `load-project-context` | Load project index for navigation |
+| `save-session-context` | Save workflow state for resumption |
+| `resume-session` | Resume previously saved session |
+
 ---
 
 ## 💡 Usage Examples
@@ -1210,8 +1250,8 @@ Special thanks to the open-source community and all contributors!
 
 - **33+** AI Agents (Orchestrators + Workers)
 - **19+** Slash Commands
-- **15+** Reusable Skills
-- **6** MCP Configurations
+- **18+** Reusable Skills
+- **7** MCP Configurations (including Serena LSP)
 - **3** Quality Gate Scripts
 - **100%** Environment Variable Security
 

package/mcp/.mcp.full.json

@@ -56,6 +56,17 @@
     "shadcn": {
       "command": "npx",
       "args": ["shadcn@latest", "mcp"]
+    },
+    "serena": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/oraios/serena",
+        "serena",
+        "start-mcp-server",
+        "--context",
+        "ide-assistant"
+      ]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-orchestrator-kit",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Complete automation and orchestration system for Claude Code with 33+ AI agents, quality gates, health monitoring, and workflow automation",
   "main": "index.js",
   "type": "module",

package/switch-mcp.sh

@@ -29,11 +29,12 @@ echo -e "${GREEN}2${NC} - SUPABASE         (Base + Supabase MegaCampusAI)
 echo -e "${GREEN}3${NC} - SUPABASE + LEGACY (Base + Supabase + Legacy project)   ~3000 tokens"
 echo -e "${GREEN}4${NC} - N8N              (Base + n8n-workflows + n8n-mcp)      ~2500 tokens"
 echo -e "${GREEN}5${NC} - FRONTEND         (Base + Playwright + ShadCN)          ~2000 tokens"
-echo -e "${GREEN}6${NC} - FULL             (All servers)                         ~5000 tokens"
+echo -e "${GREEN}6${NC} - SERENA           (Base + Serena LSP semantic search)   ~2500 tokens"
+echo -e "${GREEN}7${NC} - FULL             (All servers including Serena)        ~6500 tokens"
 echo ""
 echo -e "${YELLOW}0${NC} - STATUS           (Show current configuration)"
 echo ""
-read -p "Your choice (0-6): " choice
+read -p "Your choice (0-7): " choice
 
 case "$choice" in
   1)
@@ -57,8 +58,12 @@ case "$choice" in
     desc="FRONTEND (Playwright + ShadCN)"
     ;;
   6)
+    config="serena"
+    desc="SERENA (Base + LSP semantic search)"
+    ;;
+  7)
     config="full"
-    desc="FULL (All servers)"
+    desc="FULL (All servers including Serena)"
     ;;
   0)
     echo ""
@@ -76,11 +81,12 @@ case "$choice" in
     [ -f "$MCP_DIR/.mcp.supabase-full.json" ] && echo -e "  ✓ $MCP_DIR/.mcp.supabase-full.json"
     [ -f "$MCP_DIR/.mcp.n8n.json" ] && echo -e "  ✓ $MCP_DIR/.mcp.n8n.json"
     [ -f "$MCP_DIR/.mcp.frontend.json" ] && echo -e "  ✓ $MCP_DIR/.mcp.frontend.json"
+    [ -f "$MCP_DIR/.mcp.serena.json" ] && echo -e "  ✓ $MCP_DIR/.mcp.serena.json"
     [ -f "$MCP_DIR/.mcp.full.json" ] && echo -e "  ✓ $MCP_DIR/.mcp.full.json"
     exit 0
     ;;
   *)
-    echo -e "${RED}Invalid choice. Use numbers 0-6.${NC}"
+    echo -e "${RED}Invalid choice. Use numbers 0-7.${NC}"
     exit 1
     ;;
 esac