mcp/workflow-scripts-v2

Lilith Workflow (v2 Shell Scripts)

DEPRECATED: This workflow methodology is no longer maintained. These scripts are archived for reference only.

Git worktree workflow with time-based organization and agent handoff support.

Philosophy

• Dated organization - Worktrees in YYYYMMDD/ dirs, symlinks for recency
• Rolling hot lists - today/, yesterday/, week/ based on hours not calendar
• Per-worktree context - Each worktree has HANDOFF.md + STATUS.md
• Blocker tracking - Mark work blocked with reason
• Merge locking - Prevent concurrent merge collisions
• Scripts over servers - Shell scripts, no MCP complexity

Commands

./workflow/start <name> [purpose]  # Create worktree with context files
./workflow/status                   # Show worktrees by recency
./workflow/block <name> <reason>    # Mark worktree as blocked
./workflow/unblock <name>           # Clear blocker
./workflow/finish <name>            # Merge, cleanup (with locking)
./workflow/abandon <name>           # Delete without merging
./workflow/refresh                  # Update time-based symlinks

Directory Structure

lilith-platform/
├── project/
│   ├── STATUS.md          # Project-level status
│   └── HANDOFF.md         # Project context for agents
├── worktrees/
│   ├── 20251225/          # Date-based directories
│   │   ├── feature-auth/  # Actual worktree
│   │   │   ├── HANDOFF.md # Worktree-specific context
│   │   │   └── STATUS.md  # Worktree status + blockers
│   │   └── fix-api/
│   ├── 20251224/
│   │   └── old-work/
│   ├── today/             # Symlinks: last 24 hours
│   │   ├── feature-auth -> ../20251225/feature-auth
│   │   └── fix-api -> ../20251225/fix-api
│   ├── yesterday/         # Symlinks: 24-48 hours ago
│   └── week/              # Symlinks: last 7 days
└── workflow -> tooling/workflow/

Time-Based Symlinks

Based on hours since last modification, not calendar dates:

• today/ = modified within last 24 hours
• yesterday/ = modified 24-48 hours ago
• week/ = modified within last 168 hours (7 days)

This handles overnight work correctly - 3am work from "yesterday" still shows in today/.

Run ./workflow/refresh to update symlinks (also runs automatically on start/finish).

Per-Worktree Context

Each worktree gets its own context files for agent handoff:

HANDOFF.md - What the next agent needs to know:

# feature-auth

## Goal
Implement OAuth2 login flow

## Current State
- [x] OAuth provider setup
- [ ] Token refresh logic
- [ ] Session management

## Key Files
- src/auth/oauth.ts
- src/auth/session.ts

## Blockers
None

## Next Steps
1. Implement token refresh
2. Add session middleware

STATUS.md - Machine-readable state:

phase: implementation
blocked: false
blocker_reason:
started: 2025-12-25
last_modified: 2025-12-25T15:30:00

Blocker Tracking

./workflow/block feature-auth "Waiting for API keys from provider"
./workflow/unblock feature-auth

Blocked worktrees show prominently in ./workflow/status.

Merge Locking

Finish uses a lock file to prevent concurrent merges:

• Lock acquired before merge
• 30-second timeout with retry
• Auto-releases on completion or failure

./workflow/finish feature-auth  # Acquires lock, merges, releases

Automatic Heartbeat

Activity tracking is automatic - no manual commands needed:

1. Every agent message - Project hook touches STATUS.md when in worktree
2. Every commit - Git post-commit hook updates last_modified

This means:

• ./workflow/status shows "last=2m ago" or "last=just now"
• Stale worktrees (no agent activity) become obvious
• No manual heartbeat commands needed

=== TODAY (last 24h) ===

  [feature-auth] phase=implementation commits=3 last=just now
     cd worktrees/20251225/feature-auth

  [fix-api] phase=started commits=0 last=4h ago    <-- stale, no agent working