@the-agenticflow/openflows 0.1.3 → 0.1.6

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

@@ -0,0 +1,94 @@
+---
+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

@@ -0,0 +1,37 @@
+---
+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

@@ -0,0 +1,76 @@
+#!/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

@@ -0,0 +1,81 @@
+#!/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

@@ -0,0 +1,28 @@
+#!/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

@@ -0,0 +1,77 @@
+#!/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

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

@@ -0,0 +1,59 @@
+#!/bin/bash
+# Runs when FORGE starts a new session
+# This hook runs at the beginning of every FORGE session
+
+PAIR_ID="${SPRINTLESS_PAIR_ID}"
+TICKET_ID="${SPRINTLESS_TICKET_ID}"
+SHARED="${SPRINTLESS_SHARED}"
+WORKTREE="${SPRINTLESS_WORKTREE}"
+
+# Log session start to shared event log
+echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] forge-${PAIR_ID} session_start ticket=${TICKET_ID}" \
+  >> "${SHARED}/../events.log"
+
+# Check if this is a resume (HANDOFF.md exists)
+if [ -f "${SHARED}/HANDOFF.md" ]; then
+  echo "=========================================="
+  echo "  RESUME MODE: HANDOFF.md found"
+  echo "=========================================="
+  echo ""
+  echo "Read ${SHARED}/HANDOFF.md before doing anything else."
+  echo "Continue from the exact next step described in the handoff."
+  echo ""
+  echo "Key things to check:"
+  echo "  1. Which segments are already complete"
+  echo "  2. Which segment is in progress"
+  echo "  3. Decisions already made (do not contradict)"
+  echo "  4. Files already written (do not rewrite)"
+  echo "  5. Exact next step to take"
+  echo ""
+else
+  echo "=========================================="
+  echo "  NEW SESSION: No handoff found"
+  echo "=========================================="
+  echo ""
+  echo "Starting fresh on ticket ${TICKET_ID}"
+  echo ""
+  echo "IMPORTANT - Directory Structure:"
+  echo "  CURRENT DIR (worktree): ${WORKTREE}"
+  echo "    -> Write ALL source code, tests, package.json here"
+  echo "  SHARED DIR: ${SHARED}"
+  echo "    -> Write PLAN.md, WORKLOG.md, STATUS.json here"
+  echo ""
+  echo "First steps:"
+  echo "  1. Read ${SHARED}/TICKET.md to understand the task"
+  echo "  2. Read ${SHARED}/TASK.md for specific instructions"
+  echo "  3. Use /plan command to create ${SHARED}/PLAN.md"
+  echo "  4. Wait for CONTRACT.md from SENTINEL"
+  echo ""
+fi
+
+# Show current state
+echo "Environment:"
+echo "  PAIR_ID:    ${PAIR_ID}"
+echo "  TICKET_ID:  ${TICKET_ID}"
+echo "  WORKTREE:   ${WORKTREE}"
+echo "  SHARED:     ${SHARED}"
+echo ""
+
+exit 0

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

@@ -0,0 +1,75 @@
+#!/bin/bash
+# Runs on Stop - FORGE cannot exit without a terminal artifact
+# This ensures FORGE always leaves a clear state for the harness
+#
+# Environment:
+#   SPRINTLESS_SHARED - the shared directory
+
+SHARED="${SPRINTLESS_SHARED}"
+
+# Accept: STATUS.json written (done or blocked)
+if [ -f "${SHARED}/STATUS.json" ]; then
+  # Validate it has required fields
+  if command -v python3 &> /dev/null; then
+    VALID=$(python3 -c "
+import json, sys
+try:
+    s = json.load(open('${SHARED}/STATUS.json'))
+    required = ['status','pair','ticket_id','files_changed']
+    missing = [k for k in required if k not in s]
+    valid_statuses = ['PR_OPENED','BLOCKED','FUEL_EXHAUSTED','PENDING_REVIEW']
+    # Note: IMPLEMENTATION_COMPLETE and COMPLETED are NOT valid terminal statuses
+    # FORGE must push and create PR (PR_OPENED) or explicitly block
+    if missing:
+        print(f'missing: {missing}')
+        sys.exit(1)
+    if s['status'] not in valid_statuses:
+        print(f'invalid status: {s[\"status\"]}')
+        sys.exit(1)
+except Exception as e:
+    print(str(e))
+    sys.exit(1)
+" 2>&1)
+    if [ $? -ne 0 ]; then
+      echo "STATUS.json exists but is invalid: ${VALID}"
+      echo "Fix STATUS.json before exiting."
+      echo ""
+      echo "Required fields: status, pair, ticket_id, files_changed"
+      echo "Valid statuses: PR_OPENED, BLOCKED, FUEL_EXHAUSTED, PENDING_REVIEW"
+      exit 2
+    fi
+  fi
+  exit 0
+fi
+
+# Accept: HANDOFF.md written (context reset in progress)
+if [ -f "${SHARED}/HANDOFF.md" ]; then
+  # Verify HANDOFF.md has required sections
+  if grep -q "## Exact next step" "${SHARED}/HANDOFF.md"; then
+    exit 0
+  else
+    echo "HANDOFF.md is incomplete. It must contain '## Exact next step'."
+    echo ""
+    echo "Required sections in HANDOFF.md:"
+    echo "  - ## Completed Segments"
+    echo "  - ## Decisions"
+    echo "  - ## Files Changed"
+    echo "  - ## Exact next step"
+    exit 2
+  fi
+fi
+
+# Neither exists - block exit
+echo "=============================================="
+echo "  BLOCKED: Cannot exit without terminal artifact"
+echo "=============================================="
+echo ""
+echo "You must write either:"
+echo "  - ${SHARED}/STATUS.json  (if done or blocked)"
+echo "  - ${SHARED}/HANDOFF.md   (if context reset needed)"
+echo ""
+echo "Use /status command if your work is complete."
+echo "Use /handoff command if you need a context reset."
+echo ""
+
+exit 2

package/bin/orchestration/plugin/hooks/lore/session-start.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# LORE Session Start Hook
+# Initializes the documenter session
+
+echo "=========================================="
+echo "LORE Session Starting"
+echo "=========================================="
+echo ""
+echo "Checking for recently merged PRs..."
+
+# Lore monitors merged PRs and updates documentation
+
+exit 0

package/bin/orchestration/plugin/hooks/nexus/init-session.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# NEXUS Session Start Hook
+# Initializes the orchestrator session
+
+echo "NEXUS session starting..."
+echo "Reading registry from: ${AGENTFLOW_REGISTRY:-.agent/registry.json}"
+echo "Store path: ${AGENTFLOW_STORE:-.agent/store.json}"
+
+# Check if jq is installed
+if ! command -v jq &> /dev/null; then
+  echo "ERROR: jq is not installed. Please install it to use NEXUS."
+  exit 1
+fi
+
+# Check for pending command gate items
+if [ -n "${AGENTFLOW_STORE}" ] && [ -f "${AGENTFLOW_STORE}" ]; then
+  GATE_PENDING=$(jq -r '.command_gate | length // 0' "${AGENTFLOW_STORE}" 2>/dev/null || echo "0")
+  if [ "$GATE_PENDING" -gt 0 ]; then
+    echo "WARNING: ${GATE_PENDING} pending command(s) awaiting approval"
+  fi
+fi
+
+exit 0

package/bin/orchestration/plugin/hooks/nexus/log-decision.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# NEXUS Stop Hook
+# Logs the decision made this session
+
+echo "NEXUS session ending. Decision logged."
+
+# The actual decision is captured in the shared store
+# This hook ensures we have a log entry
+
+exit 0

package/bin/orchestration/plugin/hooks/sentinel/post_write_validate.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# SENTINEL Post-Write Validation Hook
+# Validates that eval files have correct structure
+#
+# Environment:
+#   SPRINTLESS_SHARED - the shared directory
+#   CLAUDE_FILE - the file that was just written (injected by Claude Code)
+
+SHARED="${SPRINTLESS_SHARED}"
+FILE="${CLAUDE_FILE:-}"
+
+# Only validate eval files
+if [[ ! "$FILE" =~ -eval\.md$ ]] && [[ ! "$FILE" =~ final-review\.md$ ]]; then
+  exit 0
+fi
+
+echo "Validating evaluation file: ${FILE}"
+echo ""
+
+# Check required sections
+MISSING=""
+
+if ! grep -q "## Summary" "$FILE"; then
+  MISSING="${MISSING}Summary, "
+fi
+
+if ! grep -q "## Tests Run" "$FILE" && ! grep -q "## Test Results" "$FILE"; then
+  MISSING="${MISSING}Tests Run, "
+fi
+
+if ! grep -q "## Verdict" "$FILE"; then
+  MISSING="${MISSING}Verdict, "
+fi
+
+# Check verdict is valid
+VERDICT=$(grep -oP '(?<=## Verdict\n)[A-Z_]+' "$FILE" 2>/dev/null || echo "")
+if [ -n "$VERDICT" ]; then
+  if [ "$VERDICT" != "APPROVED" ] && [ "$VERDICT" != "NEEDS_WORK" ]; then
+    echo "ERROR: Invalid verdict '${VERDICT}'. Must be APPROVED or NEEDS_WORK."
+    exit 2
+  fi
+fi
+
+if [ -n "$MISSING" ]; then
+  echo "ERROR: Missing required sections: ${MISSING%,*}"
+  echo ""
+  echo "Required sections for eval files:"
+  echo "  - ## Summary"
+  echo "  - ## Tests Run (or ## Test Results)"
+  echo "  - ## Verdict (APPROVED or NEEDS_WORK)"
+  echo ""
+  echo "If NEEDS_WORK, also include:"
+  echo "  - ## Issues Found"
+  echo "  - ## Required Fixes"
+  exit 2
+fi
+
+echo "Validation passed."
+exit 0