@the-agenticflow/openflows 0.1.6 → 0.1.8-dev.230.5aa03a0

package/bin/orchestration/plugin/commands/handoff.md

@@ -1,75 +0,0 @@
----
-name: handoff
-description: Write a complete handoff for context reset
----
-
-# /handoff Command
-
-Writes a complete handoff and exits for context reset.
-
-## When to Use
-
-When the PreCompact hook fires, or when you choose to reset
-context at a natural segment boundary.
-
-## Steps
-
-1. **Read Worklog**
-   Read `WORKLOG.md` to summarize completed segments.
-
-2. **Scan In-Progress**
-   Check worktree for any in-progress files.
-
-3. **Collect Decisions**
-   Gather all decisions made (from WORKLOG.md).
-
-4. **Write Handoff**
-   Use `write_to_shared` MCP tool with:
-   - artifact_type: `HANDOFF`
-   - content: Must include:
-     - Completed segments summary
-     - In-progress work
-     - Decisions made
-     - **Exact next step** (required)
-     - Files modified
-     - Context needed for continuation
-
-5. **Emit Event**
-   Use `emit_event` MCP tool:
-   - event_type: "context_reset"
-   - message: "Context reset - handoff written"
-
-6. **Exit**
-   Exit cleanly. Harness will spawn fresh session.
-
-## Handoff Template
-
-```markdown
-# Handoff for T-{id}
-
-## Completed Segments
-- Segment 1: {summary}
-- Segment 2: {summary}
-
-## In-Progress
-- {What was being worked on}
-
-## Decisions Made
-- {Decision 1}: {rationale}
-- {Decision 2}: {rationale}
-
-## Exact Next Step
-{Specific, actionable next step}
-
-## Files Modified
-- src/file1.rs
-- src/file2.rs
-
-## Context Needed
-- {Any context the next session needs}
-```
-
-## Output
-
-Creates `shared/HANDOFF.md`
-Agent exits - harness spawns fresh session.

package/bin/orchestration/plugin/commands/merge.md

@@ -1,47 +0,0 @@
----
-name: merge
-description: Merge an approved PR after CI passes
----
-
-# /merge Command
-
-Merges an approved PR after all gates pass.
-
-## When to Use
-
-When:
-- CI status is success
-- SENTINEL approval exists (final-review.md)
-- No merge conflicts
-
-## Steps
-
-1. **Verify CI**
-   Use `check_ci_status` MCP tool.
-   Must be `success`.
-
-2. **Verify Approval**
-   Check `final-review.md` exists with APPROVED verdict.
-
-3. **Check for Conflicts**
-   Verify PR has no merge conflicts.
-
-4. **Merge PR**
-   Use `merge_pr` MCP tool with:
-   - pr_number: The PR number
-   - merge_method: "squash" (recommended)
-   - commit_message: From SENTINEL's PR description
-
-5. **Report**
-   Emit merge event and update NEXUS.
-
-## Blocked If
-
-- CI is failing or pending
-- No SENTINEL approval
-- Merge conflicts exist
-
-## Output
-
-PR merged into main.
-Worker slot set to Idle.

package/bin/orchestration/plugin/commands/plan.md

@@ -1,66 +0,0 @@
-# /plan Command
-
-Create a detailed implementation plan for the current ticket.
-
-## Usage
-
-```
-/plan
-```
-
-## What it does
-
-1. Reads TICKET.md and TASK.md from the shared directory
-2. Analyzes the codebase to understand the current state
-3. Creates PLAN.md with:
-   - Problem analysis
-   - Solution approach
-   - Segment breakdown with explicit deliverables
-   - Risk assessment
-   - Estimated segments
-
-## Output
-
-Writes to `${SPRINTLESS_SHARED}/PLAN.md`:
-
-```markdown
-# Implementation Plan: T-{id}
-
-## Problem Analysis
-[What the ticket asks for and why]
-
-## Solution Approach
-[High-level technical approach]
-
-## Segment Breakdown
-
-### Segment 1: {title}
-- Deliverable: {specific artifact}
-- Files to modify: [list]
-- Tests to write: [list]
-- Exit condition: {measurable state}
-
-### Segment 2: {title}
-...
-
-## Risk Assessment
-- Risk 1: {description} - Mitigation: {strategy}
-- Risk 2: ...
-
-## Estimated Segments
-Total: {N} segments
-```
-
-## After Planning
-
-Once PLAN.md is written:
-1. Commit the plan: `git add -A && git commit -m "[T-{id}] plan: implementation approach"`
-2. Begin Segment 1
-3. Use `/segment-done` when each segment is complete
-
-## Important
-
-- Each segment must have a clear, measurable exit condition
-- Plan conservatively - it's better to have more small segments than fewer large ones
-- The plan can be adjusted after segments if discovery reveals new information
-- Update WORKLOG.md as you work through segments

package/bin/orchestration/plugin/commands/segment-done.md

@@ -1,50 +0,0 @@
----
-name: segment-done
-description: Submit the current segment for SENTINEL review
----
-
-# /segment-done Command
-
-Submits the current segment to SENTINEL for evaluation.
-
-## When to Use
-
-When you believe a segment is complete and ready for review.
-
-## Steps
-
-1. **Run Tests**
-   Use `run_tests` MCP tool.
-   - All tests must pass before continuing
-   - If any fail, fix them first
-
-2. **Run Linter**
-   Use `run_linter` MCP tool.
-   - Must be clean (zero warnings)
-   - Fix any issues first
-
-3. **Commit Segment**
-   Use `commit_segment` MCP tool with:
-   - segment_name: e.g., "segment-1"
-   - description: Brief description of changes
-
-4. **Update Worklog**
-   Use `write_to_shared` MCP tool with:
-   - artifact_type: `WORKLOG_ENTRY`
-   - content: What was done, decisions made
-
-5. **Emit Event**
-   Use `emit_event` MCP tool:
-   - event_type: "segment_submitted"
-   - message: "Segment N submitted for evaluation"
-
-## Blocked If
-
-- Any tests are failing
-- Any lint warnings exist
-- No files have been changed since last commit
-
-## Output
-
-Updates WORKLOG.md, commits segment, notifies SENTINEL.
-Wait for `segment-N-eval.md` from SENTINEL.

package/bin/orchestration/plugin/commands/status-check.md

@@ -1,28 +0,0 @@
----
-name: status-check
-description: Check the current system status
----
-
-# /status-check Command
-
-Returns the current system status including workers, tickets, and PRs.
-
-## Output
-
-```json
-{
-  "workers": {
-    "idle": 1,
-    "assigned": 2,
-    "working": 0,
-    "suspended": 0,
-    "done": 0
-  },
-  "tickets": {
-    "pending": 5,
-    "in_progress": 2
-  },
-  "open_prs": 1,
-  "pending_approvals": 0
-}
-```

package/bin/orchestration/plugin/commands/status.md

@@ -1,94 +0,0 @@
----
-name: status
-description: Signal terminal status to the harness
----
-
-# /status Command
-
-Signal terminal status to the harness. Use when work is complete or blocked.
-
-## Usage
-
-```bash
-/status <status> [reason]
-```
-
-## Status Values
-
-### Terminal statuses (ends the pair lifecycle)
-- `PR_OPENED` - Work complete, PR created
-- `COMPLETE` - All work done, PR creation deferred to harness
-- `BLOCKED` - Cannot proceed, needs intervention
-- `FUEL_EXHAUSTED` - Budget/tokens exhausted, need more allocation
-
-### Non-terminal statuses (continues the event loop)
-- `PENDING_REVIEW` - Work paused, waiting for review
-- `AWAITING_SENTINEL_REVIEW` - Segment done, waiting for SENTINEL evaluation
-- `APPROVED_READY` - Changes requested by SENTINEL have been addressed
-- `SEGMENT_N_DONE` - Segment N complete (e.g. `SEGMENT_1_DONE`)
-
-### IMPORTANT
-Do NOT use any other status value. Values like `AWAITING_REVIEW`, `DONE`, `FINISHED`, `SUCCESS`, `IMPLEMENTATION_COMPLETE` will be treated as `BLOCKED` and your work will be wasted.
-
-## What it does
-
-1. Writes STATUS.json with current state
-2. Lists all files changed
-3. Provides reason/explanation
-4. Harness reads STATUS.json and takes appropriate action
-
-## STATUS.json Structure
-
-```json
-{
-  "status": "PR_OPENED | COMPLETE | BLOCKED | FUEL_EXHAUSTED | PENDING_REVIEW | AWAITING_SENTINEL_REVIEW | APPROVED_READY | SEGMENT_N_DONE",
-  "pair": "pair-{N}",
-  "ticket_id": "T-{id}",
-  "branch": "forge-{N}/T-{id}",
-  "files_changed": [
-    "src/auth.rs",
-    "tests/auth_test.rs"
-  ],
-  "segments_completed": 3,
-  "pr_url": "https://github.com/owner/repo/pull/42",
-  "reason": "Optional reason for BLOCKED or FUEL_EXHAUSTED",
-  "timestamp": "2025-03-24T10:00:00Z"
-}
-```
-
-## Examples
-
-### Work Complete
-
-```bash
-/status PR_OPENED
-```
-
-Then provide the PR URL when prompted.
-
-### Blocked
-
-```bash
-/status BLOCKED Cannot proceed due to API rate limit
-```
-
-### Fuel Exhausted
-
-```bash
-/status FUEL_EXHAUSTED Need 50k more tokens to complete
-```
-
-## After STATUS.json
-
-The harness will:
-
-- **PR_OPENED**: Notify VESSEL to check CI and merge
-- **BLOCKED**: Alert NEXUS for human intervention
-- **FUEL_EXHAUSTED**: Request more budget allocation
-
-## Important
-
-- This is a terminal state - you cannot continue after writing STATUS.json
-- For temporary pauses, use `/segment-done` instead
-- For context reset, use `/handoff` instead
-- Always list ALL files changed across all segments

package/bin/orchestration/plugin/commands/update-changelog.md

@@ -1,37 +0,0 @@
----
-name: update-changelog
-description: Add entry to CHANGELOG.md
----
-
-# /update-changelog Command
-
-Adds an entry to CHANGELOG.md for a merged PR.
-
-## Steps
-
-1. **Read PR Description**
-   Get the PR description from the merge.
-
-2. **Categorize Change**
-   Determine category:
-   - Added: New features
-   - Changed: Modified behavior
-   - Fixed: Bug fixes
-   - Security: Security fixes
-
-3. **Write Entry**
-   Add to CHANGELOG.md under [Unreleased]:
-   ```markdown
-   ### Added
-   - New feature X (#42)
-   ```
-
-4. **Commit**
-   Commit with message:
-   ```
-   docs: update CHANGELOG for T-{id}
-   ```
-
-## Output
-
-CHANGELOG.md updated with new entry.

package/bin/orchestration/plugin/hooks/forge/post_write_lint.sh

@@ -1,76 +0,0 @@
-#!/bin/bash
-# Runs after every Write, Edit, MultiEdit tool call
-# Validates atomic writes for shared/ artifacts and runs linter on source files
-#
-# Environment:
-#   CLAUDE_TOOL_INPUT_FILE_PATH - the file that was written
-#   SPRINTLESS_WORKTREE - the worktree directory
-
-FILE="${CLAUDE_TOOL_INPUT_FILE_PATH}"
-WORKTREE="${SPRINTLESS_WORKTREE}"
-
-# For shared/ artifacts, ensure atomic write was used (.tmp + rename pattern)
-case "$FILE" in
-  */orchestration/pairs/*/shared/*)
-    # Verify file was written atomically (should never see .tmp files at this point)
-    if [[ "$FILE" == *.tmp ]]; then
-      echo "ERROR: Temporary file leaked to filesystem: ${FILE}"
-      echo "All shared/ writes must be atomic (write to .tmp, then rename)."
-      exit 2
-    fi
-    # Validate JSON structure for specific artifact types
-    case "$FILE" in
-      */STATUS.json)
-        if command -v python3 &> /dev/null; then
-          python3 -c "import json, sys; json.load(open('$FILE'))" 2>&1
-          if [ $? -ne 0 ]; then
-            echo "INVALID: STATUS.json is not valid JSON"
-            exit 2
-          fi
-        fi
-        ;;
-    esac
-    exit 0
-    ;;
-esac
-
-# Only lint source files (not config, docs, etc.)
-case "$FILE" in
-  *.ts|*.tsx)
-    if command -v npx &> /dev/null; then
-      OUTPUT=$(cd "$WORKTREE" && npx eslint "$FILE" --quiet 2>&1)
-      if [ $? -ne 0 ]; then
-        echo "Lint failed on ${FILE}:"
-        echo "$OUTPUT"
-        echo ""
-        echo "Fix these lint errors before continuing."
-        exit 2
-      fi
-    fi
-    ;;
-  *.rs)
-    if command -v cargo &> /dev/null; then
-      OUTPUT=$(cd "$WORKTREE" && cargo clippy --quiet --message-format=short 2>&1 | grep -A5 "$FILE" || true)
-      if [ -n "$OUTPUT" ]; then
-        echo "Clippy warnings for ${FILE}:"
-        echo "$OUTPUT"
-        echo ""
-        echo "Fix these warnings before continuing."
-        # Clippy warnings don't fail the build, but we want clean code
-        # exit 2  # Uncomment to enforce zero warnings
-      fi
-    fi
-    ;;
-  *.py)
-    if command -v ruff &> /dev/null; then
-      OUTPUT=$(cd "$WORKTREE" && ruff check "$FILE" 2>&1)
-      if [ $? -ne 0 ]; then
-        echo "Ruff failed on ${FILE}:"
-        echo "$OUTPUT"
-        exit 2
-      fi
-    fi
-    ;;
-esac
-
-exit 0

package/bin/orchestration/plugin/hooks/forge/pre_bash_guard.sh

@@ -1,81 +0,0 @@
-#!/bin/bash
-# Runs before every Bash tool call
-# Blocks dangerous commands and access to other pairs' worktrees
-#
-# Environment:
-#   CLAUDE_TOOL_INPUT_COMMAND - the command being executed
-#   SPRINTLESS_PAIR_ID - the current pair ID
-
-CMD="${CLAUDE_TOOL_INPUT_COMMAND}"
-
-# Block direct git push to non-forge branches - must use MCP tools for PR creation
-if echo "$CMD" | grep -qE '^git push|^git push '; then
-  # Allow pushing to the pair's own branch
-  BRANCH_PATTERN="forge-${SPRINTLESS_PAIR_ID}"
-  if echo "$CMD" | grep -q "$BRANCH_PATTERN"; then
-    # Allow pushing own branch
-    exit 0
-  fi
-  echo "BLOCKED: Cannot push to branches other than your own."
-  echo ""
-  echo "Your branch: forge-${SPRINTLESS_PAIR_ID}/${SPRINTLESS_TICKET_ID}"
-  echo ""
-  echo "After pushing, create a PR using GitHub MCP tools:"
-  echo "  1. Use create_pull_request from github MCP server"
-  echo "  2. Write STATUS.json with PR_OPENED status and PR URL"
-  exit 2
-fi
-
-# Block writes to other pairs' worktrees
-if echo "$CMD" | grep -qE 'worktrees/pair-[0-9]+/' ; then
-  REFERENCED=$(echo "$CMD" | grep -oE 'pair-[0-9]+' | head -1)
-  if [ "$REFERENCED" != "${SPRINTLESS_PAIR_ID}" ]; then
-    echo "BLOCKED: Cannot access ${REFERENCED}'s worktree."
-    echo "You are ${SPRINTLESS_PAIR_ID}."
-    echo ""
-    echo "Each pair works in isolation. You cannot read or write"
-    echo "to another pair's worktree."
-    exit 2
-  fi
-fi
-
-# Block writes to main branch
-if echo "$CMD" | grep -qE 'checkout main|checkout origin/main'; then
-  echo "BLOCKED: Cannot checkout main. Work on your branch only."
-  echo ""
-  echo "Your branch: forge-${SPRINTLESS_PAIR_ID}/${SPRINTLESS_TICKET_ID}"
-  exit 2
-fi
-
-# Block dangerous commands
-DANGEROUS_PATTERNS="rm -rf /|sudo rm|:(){ :|:& };:|mkfs|dd if="
-if echo "$CMD" | grep -qE "$DANGEROUS_PATTERNS"; then
-  echo "BLOCKED: Dangerous command detected."
-  echo "This command is not allowed for safety reasons."
-  exit 2
-fi
-
-# Block network operations (MCP tools should be used instead)
-NETWORK_PATTERNS="^curl |^wget |^nc |^ncat |^telnet |^ssh "
-if echo "$CMD" | grep -qE "$NETWORK_PATTERNS"; then
-  echo "BLOCKED: Network commands are not allowed."
-  echo ""
-  echo "Use MCP tools instead:"
-  echo "  - For GitHub API: use github MCP server"
-  echo "  - For HTTP requests: use appropriate MCP tool"
-  exit 2
-fi
-
-# Block package installation (could introduce unreviewed dependencies)
-INSTALL_PATTERNS="npm install |yarn add |pip install |cargo install |go get "
-if echo "$CMD" | grep -qE "$INSTALL_PATTERNS"; then
-  echo "BLOCKED: Package installation is not allowed."
-  echo ""
-  echo "If a new dependency is needed:"
-  echo "  1. Document it in PLAN.md"
-  echo "  2. Get SENTINEL approval"
-  echo "  3. Have a human add it to package.json/Cargo.toml"
-  exit 2
-fi
-
-exit 0

package/bin/orchestration/plugin/hooks/forge/pre_compact_handoff.sh

@@ -1,28 +0,0 @@
-#!/bin/bash
-# Runs on PreCompact - converts compaction to clean context reset
-# This hook fires when the context window is approaching its limit
-#
-# Environment:
-#   SPRINTLESS_SHARED - the shared directory
-
-SHARED="${SPRINTLESS_SHARED}"
-
-echo "=============================================="
-echo "  CONTEXT RESET REQUIRED"
-echo "=============================================="
-echo ""
-echo "Your context window is approaching its limit."
-echo "Before this session ends, you must write a handoff."
-echo ""
-echo "Use the /handoff command now. It will:"
-echo "  1. Collect everything needed for the handoff"
-echo "  2. Write ${SHARED}/HANDOFF.md"
-echo "  3. Update WORKLOG.md with current state"
-echo "  4. Exit cleanly"
-echo ""
-echo "A fresh FORGE session will read your handoff and continue."
-echo ""
-echo "DO NOT attempt to continue working - write the handoff now."
-echo ""
-
-exit 2

package/bin/orchestration/plugin/hooks/forge/pre_write_check.sh

@@ -1,77 +0,0 @@
-#!/bin/bash
-# Runs before every Write, Edit, MultiEdit tool call
-# Enforces dynamic file ownership locking via flock
-# 
-# Environment:
-#   CLAUDE_TOOL_INPUT_FILE_PATH - the file being written
-#   SPRINTLESS_PAIR_ID - the current pair ID
-#   SPRINTLESS_SHARED - the shared directory
-
-FILE="${CLAUDE_TOOL_INPUT_FILE_PATH}"
-PAIR_ID="${SPRINTLESS_PAIR_ID}"
-LOCKS_DIR="${SPRINTLESS_SHARED}/../locks"
-
-# Skip lock check for shared/ artifacts - those are pair-scoped already
-case "$FILE" in
-  */orchestration/pairs/*/shared/*)
-    exit 0
-    ;;
-esac
-
-# Also skip if FILE is relative and matches shared pattern
-case "$FILE" in
-  shared/*|./shared/*)
-    exit 0
-    ;;
-esac
-
-# Create locks directory if needed
-mkdir -p "$LOCKS_DIR" 2>/dev/null
-
-# Generate lock filename (sha256 hash of filepath to avoid path issues)
-LOCK_HASH=$(echo -n "$FILE" | sha256sum | cut -d' ' -f1)
-LOCK_FILE="${LOCKS_DIR}/${LOCK_HASH}.lock"
-LOCK_JSON="${LOCKS_DIR}/${LOCK_HASH}.json"
-
-# Attempt atomic lock acquisition using flock
-{
-  # Acquire exclusive lock on .lock file (non-blocking)
-  flock -x -n 200 || {
-    echo "BLOCKED: Another process is currently locking ${FILE}"
-    echo "Waiting for lock to be released..."
-    exit 2
-  }
-  
-  # Check if lock JSON exists and who owns it
-  if [ -f "$LOCK_JSON" ]; then
-    OWNER=$(cat "$LOCK_JSON" | grep -o '"pair"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | cut -d'"' -f4)
-    if [ "$OWNER" != "$PAIR_ID" ]; then
-      echo "BLOCKED: ${FILE} is currently locked by ${OWNER}."
-      echo ""
-      echo "This file is being modified by another pair."
-      echo ""
-      echo "Options:"
-      echo "  1. Find an alternative implementation that avoids this file"
-      echo "  2. Wait for ${OWNER} to complete and release the lock"
-      echo "  3. Set STATUS.json to BLOCKED with reason FILE_LOCK_CONFLICT"
-      echo ""
-      echo "Lock details in: ${LOCK_JSON}"
-      
-      exit 2
-    fi
-    # Lock belongs to us - proceed
-  else
-    # No lock exists - acquire it
-    cat > "$LOCK_JSON" << EOF
-{
-  "pair": "${PAIR_ID}",
-  "file": "${FILE}",
-  "acquired_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-}
-EOF
-  fi
-  
-} 200>"$LOCK_FILE"
-
-# Lock acquired or already owned by us - proceed with write
-exit 0