@the-agenticflow/openflows 0.1.3 → 0.1.6

package/bin/orchestration/plugin/skills/nexus-xlsx.md

@@ -0,0 +1,20 @@
+---
+name: xlsx
+description: Analysis of project metrics, timelines, and budgets using Excel automation.
+---
+
+# NEXUS Metrics Analysis Skill
+
+Use this skill to track and visualize project health through quantitative data analysis.
+
+## Metrics Tracking
+
+- **Velocity**: Track task completion rates and sprint progress.
+- **Budgeting**: Keep tabs on project costs and resource allocation.
+- **Timeline Modeling**: Generate "what-if" scenarios for project schedules.
+
+## Workflow
+
+1. Collect raw data from session logs or external trackers.
+2. Use formulas to calculate trends and health indicators.
+3. Present summaries in a clear, actionable format for stakeholders.

package/bin/orchestration/plugin/skills/sentinel-algorithmic-art.md

@@ -0,0 +1,20 @@
+---
+name: algorithmic-art
+description: Use generative art principles to visualize code quality, coverage, and complex failure states.
+---
+
+# SENTINEL Visual Diagnostics Skill
+
+Use this skill to create algorithmic visualizations of system health, testing results, or code complexity.
+
+## Visualizing Data
+
+- **Code Coverage**: Represent files as recursive treemaps where color indicates coverage depth.
+- **Failure Heatmaps**: Visualize test suite failures across the codebase chronologically or structurally.
+- **Complexity Clouds**: Use particle systems to represent cyclomatic complexity in large modules.
+
+## Goals
+
+- **Scannability**: Make complex system states readable at a glance.
+- **Impact**: Use motion and color to draw attention to critical bottlenecks or regressions.
+- **Diagnostic Clarity**: Ensure the visualization directly correlates with underlying metrics.

package/bin/orchestration/plugin/skills/sentinel-criteria.md

@@ -0,0 +1,115 @@
+# SENTINEL Evaluation Criteria
+
+## The five criteria - all must pass for any approval
+
+### 1. Correctness
+
+Does the implementation correctly handle all cases described in CONTRACT.md?
+Does it handle the error paths, edge cases, and boundary conditions?
+
+**FAIL:** any CONTRACT criterion not met, any obvious logic error
+
+### 2. Test coverage
+
+Are all changed files covered by tests?
+Does every new function have at least one test for the happy path
+and one for the primary error path?
+
+**FAIL:** any changed file with no tests, any new function with no test
+
+### 3. Standards compliance
+
+Does the implementation follow `orchestration/agent/standards/CODING.md`?
+Does it use the patterns in `orchestration/agent/arch/patterns.md`?
+Does it respect the API contracts in `orchestration/agent/arch/api-contracts.md`?
+
+**FAIL:** any violation of the team's written standards
+
+### 4. Code quality
+
+Is the code readable? Are names clear? Is complexity justified?
+Is there duplication that should be extracted?
+
+**NOTE:** This criterion is advisory - it cannot block alone.
+It informs feedback but a single quality concern is not a blocker.
+
+### 5. No regressions
+
+Do all existing tests still pass?
+Has any existing behaviour been changed without explicit ticket scope?
+
+**FAIL:** any previously passing test now failing
+
+---
+
+## Evaluation checklist
+
+Use this checklist for every segment review:
+
+```markdown
+## Evaluation Checklist
+
+### Correctness
+- [ ] All CONTRACT criteria verified
+- [ ] Error paths handled
+- [ ] Edge cases covered
+- [ ] Boundary conditions tested
+
+### Test Coverage
+- [ ] All changed files have tests
+- [ ] New functions have happy path tests
+- [ ] New functions have error path tests
+- [ ] Integration tests where needed
+
+### Standards Compliance
+- [ ] CODING.md rules followed
+- [ ] patterns.md patterns used
+- [ ] API contracts respected
+- [ ] Naming conventions followed
+
+### Code Quality
+- [ ] Readable and clear
+- [ ] No unnecessary duplication
+- [ ] Appropriate abstraction level
+- [ ] Comments where needed
+
+### No Regressions
+- [ ] All existing tests pass
+- [ ] No unintended behavior changes
+```
+
+---
+
+## Severity levels
+
+When writing feedback, indicate severity:
+
+- **BLOCKER:** Must be fixed before approval (correctness, test coverage, standards)
+- **MAJOR:** Should be fixed, but approval possible if addressed in next segment
+- **MINOR:** Advisory, can be deferred
+
+### Example with severity
+
+```markdown
+## Specific feedback
+
+- `src/auth/login.ts:23` [BLOCKER]: Missing error handling for `fetchUser()`. Required: Add try-catch with `AppError('USER_NOT_FOUND', 404)`
+
+- `src/auth/login.ts:67` [MAJOR]: Hardcoded timeout value. Required: Use `config.timeout` from `src/config.ts`
+
+- `src/auth/login.ts:89` [MINOR]: Variable name `tmp` is unclear. Consider: `userSession`
+```
+
+---
+
+## Quick decision guide
+
+| Situation | Verdict |
+|-----------|---------|
+| All criteria pass | APPROVED |
+| Any BLOCKER items | CHANGES_REQUESTED |
+| Multiple MAJOR items | CHANGES_REQUESTED |
+| Only MINOR items | APPROVED (with notes) |
+| Tests failing | CHANGES_REQUESTED |
+| Lint warnings | CHANGES_REQUESTED |
+| Standards violation | CHANGES_REQUESTED |

package/bin/orchestration/plugin/skills/sentinel-frontend-design.md

@@ -0,0 +1,20 @@
+---
+name: frontend-design
+description: Reference for evaluating UI quality and aesthetic consistency in frontend reviews.
+---
+
+# SENTINEL Frontend Design Critique Skill
+
+Use this skill to evaluate the design quality of PRs and artifacts against project standards.
+
+## Critique Criteria
+
+- **Aesthetic Direction**: Does it follow a clear, bold direction? Is it cohesive?
+- **Typography Quality**: Are font choices intentional and well-paired? Is it distinct from generic defaults?
+- **Color Harmony**: Is the palette professional and balanced? Is there sufficient contrast?
+- **Visual Polish**: Check for spacing consistency, border-radius harmony, and attention to detail.
+- **Avoidance of "AI Slop"**: Does it feel designed, or just generated? Watch out for overused patterns (purple gradients, Inter-only stacks).
+
+## Reporting Feedback
+
+Provide constructive, specific feedback on how to elevate the design. Refer to the `Forge Frontend Design` standards.

package/bin/orchestration/plugin/skills/sentinel-review.md

@@ -0,0 +1,124 @@
+# SENTINEL Review Skill
+
+## Your role
+
+You are SENTINEL. You are spawned for a single purpose: evaluate one segment.
+You have no history. You have no future. You only have this segment.
+
+## Your disposition
+
+- Be skeptical
+- Be specific
+- Be constructive
+
+FORGE is your partner, not your adversary.
+Your feedback must be actionable - FORGE must know exactly what to fix.
+
+## Reviewing a plan (PLAN.md)
+
+Check:
+1. Does the plan address all acceptance criteria in TICKET.md?
+2. Does the technical approach follow `orchestration/agent/arch/patterns.md`?
+3. Are all relevant files identified?
+4. Is the definition of done specific and testable?
+5. Is there an explicit out-of-scope list?
+
+Write `CONTRACT.md` with:
+- `status: AGREED` if the plan is sound
+- `status: ISSUES` if there are problems (list specific objections)
+
+## Reviewing a segment
+
+Check:
+1. Run tests: `orchestration/agent/tooling/run-tests.sh` - they must all pass
+2. Run linter on changed files - zero warnings
+3. Read every changed file against the CONTRACT criteria
+4. Check error handling - every error path covered?
+5. Check test coverage - is every new function tested?
+6. Check standards compliance - CODING.md and patterns.md respected?
+
+## Writing feedback
+
+When writing `segment-N-eval.md` with `CHANGES_REQUESTED`:
+
+- Every item must have: `file`, `line number`, `problem`, `required fix`
+- Do NOT write vague feedback like "improve error handling"
+- DO write: `src/auth/session.ts line 47: throws raw Error. Required: throw new AppError('SESSION_EXPIRED', 401) per CODING.md rule 3`
+
+### Example segment eval
+
+```markdown
+# Segment 3 Evaluation
+
+## Verdict
+
+CHANGES_REQUESTED
+
+## Specific feedback
+
+- `src/auth/login.ts:23`: Missing error handling for `fetchUser()`. Required: Add try-catch with `AppError('USER_NOT_FOUND', 404)`
+
+- `tests/auth/login.test.ts:45`: Test only covers happy path. Required: Add test for invalid credentials returning 401
+
+- `src/auth/login.ts:67`: Hardcoded timeout value. Required: Use `config.timeout` from `src/config.ts`
+```
+
+## Final review
+
+When all segments are approved, run the complete verification:
+
+1. Full test suite via `orchestration/agent/tooling/run-tests.sh`
+2. Full linter across entire project
+3. Check every CONTRACT criterion is satisfied
+4. Write `final-review.md` with `APPROVED` verdict and PR description
+
+Your PR description becomes the actual PR body - make it informative.
+
+### Example final review
+
+```markdown
+# Final Review
+
+## Verdict
+
+APPROVED
+
+## Summary
+
+This PR implements JWT-based authentication for the login endpoint, including:
+- POST /auth/login endpoint with credential validation
+- JWT token generation with configurable expiry
+- Auth middleware for protected routes
+- Comprehensive test coverage (12 new tests)
+
+## PR description
+
+[Title: [T-42] Add user authentication endpoint]
+
+Implements JWT-based authentication for the login endpoint.
+
+### Changes
+- `src/auth/login.ts`: Login endpoint with credential validation
+- `src/auth/jwt.ts`: JWT token generation and validation
+- `src/middleware/auth.ts`: Auth middleware for protected routes
+- `tests/auth/`: Comprehensive test coverage
+
+### Testing
+- 12 new tests added
+- All existing tests still pass
+- Manual testing completed
+
+Closes #42
+
+> **IMPORTANT**: The PR body MUST include `Closes #<issue_number>` (with `#` prefix, no colon) to auto-close the issue on merge.
+> - Extract the issue number from `SPRINTLESS_TICKET_ID`: `T-004` → issue number `4`
+> - Use: `Closes #4` (correct) — NOT `Closes: T-004` (wrong)
+```
+
+## Environment variables
+
+- `SPRINTLESS_PAIR_ID` - the pair you're evaluating
+- `SPRINTLESS_TICKET_ID` - the ticket being worked on
+- `SPRINTLESS_SEGMENT` - segment number (empty for plan review, "final" for final review)
+- `SPRINTLESS_SHARED` - the shared directory with artifacts
+- `SPRINTLESS_WORKTREE` - the worktree to read files from

package/bin/orchestration/plugin/skills/sentinel-web-artifacts-builder.md

@@ -0,0 +1,20 @@
+---
+name: web-artifacts-builder
+description: Skill for building reproduction environments and diagnostic dashboards for UI issues.
+---
+
+# SENTINEL Diagnostic Artifacts Skill
+
+Use this skill to create visual dashboards or reproduction environments when debugging complex UI/UX issues.
+
+## Usage Scenarios
+
+- **Reproduction**: Build a minimal React artifact that demonstrates a reported bug.
+- **Diagnostics**: Create a dashboard visualizing log data or state transitions for a failed session.
+- **Comparison**: Show a side-by-side comparison of "Expected" vs "Actual" UI states.
+
+## Best Practices
+
+- Keep diagnostic artifacts focused on the issue at hand.
+- Use clear visual indicators (red/green, status badges) to highlight problems.
+- Ensure the reproduction is self-contained and easy for the user to view.

package/bin/orchestration/plugin/skills/sentinel-webapp-testing.md

@@ -0,0 +1,34 @@
+---
+name: webapp-testing
+description: Toolkit for interacting with and testing local web applications using Playwright.
+---
+
+# Web Application Testing Skill
+
+Use this skill to verify frontend functionality, debug UI behavior, and capture browser state for evaluation or deployment verification.
+
+## Workflow
+
+1. **Reconnaissance**:
+   - Navigate to the local server URL.
+   - Wait for `networkidle` state to ensure JS execution is complete.
+   - Inspect the rendered DOM or take a full-page screenshot.
+
+2. **Identification**:
+   - Locate specific elements using descriptive selectors (`text=`, `role=`, CSS, or IDs).
+   - Use `page.locator()` and `all()` to discover interactive elements.
+
+3. **Execution**:
+   - Write Playwright scripts to perform actions (click, type, navigate).
+   - Verify assertions and capture logs for debugging.
+
+## Helper Pattern
+
+When working with local servers, ensure the server is running correctly before beginning reconnaissance. If managing server lifecycles, wait for port availability.
+
+## Best Practices
+
+- **Synchronous Logic**: Use `playwright.sync_api` for cleaner script integration where applicable.
+- **Headless Mode**: Always launch browsers in headless mode for server-side execution.
+- **Waits**: Use `wait_for_selector` or specific network idle states instead of arbitrary timeouts.
+- **Artifacts**: Capture screenshots and console logs to provide proof of verification.

package/bin/orchestration/plugin/skills/shared-claude-api.md

@@ -0,0 +1,25 @@
+---
+name: claude-api
+description: Technical reference for Claude-specific features and best practices.
+---
+
+# Shared Claude API Skill
+
+Use this reference to optimize interactions with the Claude LLM, utilizing advanced features for improved performance and cost-efficiency.
+
+## Core Features
+
+- **Thinking & Effort**: Adjust `thinking` parameters for complex reasoning tasks.
+- **Prompt Caching**: Structure prompts to take advantage of caching for repetitive context.
+- **Tool Use**: Follow best practices for tool definition and selection.
+- **Streaming**: Handle streaming responses efficiently in the CLI/Frontend.
+
+## Best Practices
+
+- **System Prompting**: Provide clear, concise role definitions.
+- **Context Management**: Be mindful of the context window; use summarization or trimming when necessary.
+- **Output Formatting**: Request specific formats (JSON, Markdown) explicitly for deterministic processing.
+
+## Managed Agents (Beta)
+
+When coordinating with other agents, follow the established orchestration protocol defined in the `AgentFlow` system instructions.

package/bin/orchestration/plugin/skills/vessel-ci-gate.md

@@ -0,0 +1,68 @@
+---
+name: ci-gate
+description: Skill for checking CI status and validating merge readiness
+---
+
+# CI Gate Skill
+
+## CI Readiness Pre-Check
+
+**BEFORE polling CI status**, check if the repository has CI workflows configured:
+
+1. Use `has_workflows` on the GitHub client to check if `.github/workflows/` exists
+2. Check `ci_readiness` in the shared store if available
+
+If **no CI workflows exist**:
+- Do NOT poll CI status — there is nothing to poll
+- Return `CiStatus::Success` immediately (empty check suites = pass by default)
+- Emit a `ci_missing` event to alert NEXUS that CI setup is required
+- Log a WARNING that the repository has no CI pipelines
+
+This prevents VESSEL from spending polling cycles waiting for CI that will never arrive,
+which causes watchdog timeouts and stalls the entire pair.
+
+## CI Status Check
+
+Use `check_ci_status` MCP tool to verify:
+- All required checks passed
+- No failing checks
+- No pending checks (unless configured to allow)
+
+## Required Checks
+
+Typical required checks:
+- Build: Compiles successfully
+- Tests: All tests pass
+- Lint: No lint errors
+- Security: No vulnerabilities detected
+
+## CI Status Values
+
+| Status | Action |
+|--------|--------|
+| `success` | All checks passed |
+| `failure` | One or more checks failed |
+| `pending` | Checks still running |
+| `unknown` | No CI configured — treat as `success` and alert NEXUS |
+
+## Merge Readiness
+
+PR is ready to merge when:
+1. CI status is `success`
+2. SENTINEL approval exists (final-review.md)
+3. No merge conflicts
+4. Branch is up to date with main
+
+## Handling Failures
+
+If CI fails:
+1. Do NOT merge
+2. Report failure to NEXUS
+3. Return `deploy_failed` action with details
+
+## Handling Pending
+
+If CI is pending:
+1. Wait and poll
+2. Timeout after configured duration
+3. Report timeout if exceeded

package/bin/orchestration/plugin/skills/vessel-internal-comms.md

@@ -0,0 +1,20 @@
+---
+name: internal-comms
+description: Tailored guidelines for deployment reports, incident logs, and release notes.
+---
+
+# VESSEL Deployment Communications Skill
+
+Use this skill to communicate deployment outcomes and system health updates to the team.
+
+## Formats
+
+- **Deployment Summary**: SHA, Environment, Status (Success/Failure), and smoke test results.
+- **Incident Logs**: Detailed timeline of deployment failures and recovery actions taken.
+- **Release Notes**: Developer-focused summaries of what was deployed.
+
+## Tonal Goals
+
+- **Highly Informational**: Focus on raw data and outcomes.
+- **Action-Oriented**: In case of failure, clearly state the rollback status or required human intervention.
+- **Reliable**: Maintain a predictable format for automated parsing or quick human review.

package/bin/orchestration/plugin/skills/vessel-mcp-builder.md

@@ -0,0 +1,21 @@
+---
+name: mcp-builder
+description: Skilled management and extension of the deployment automation MCP environment.
+---
+
+# VESSEL Infrastructure MCP Skill
+
+Use this skill to maintain and extend the MCP servers used for deployment automation and monitoring.
+
+## Focus Areas
+
+- **Transport Reliability**: Ensure Stdio/SSE connections to deployment tools are stable.
+- **Tool Mapping**: Correctly map CLI tools (Docker, K8s, Terraform) to MCP tools.
+- **Environment Safety**: Ensure MCP tools have minimal necessary permissions for the target environment.
+- **Monitoring Tools**: Build tools for retrieving logs and metrics into the AgentFlow context.
+
+## Workflow
+
+1. Identify missing infrastructure visibility.
+2. Direct Forge or self-implement a new MCP tool/resource.
+3. Verify tool safety and reliability in a staging environment.

package/bin/orchestration/plugin/skills/vessel-merge-protocol.md

@@ -0,0 +1,113 @@
+---
+name: merge-protocol
+description: Protocol for safely merging approved PRs
+---
+
+# Merge Protocol Skill
+
+## Pre-Merge Checklist
+
+Before merging, verify:
+- [ ] CI status: success
+- [ ] SENTINEL approval: final-review.md exists with APPROVED
+- [ ] No merge conflicts
+- [ ] Branch up to date with main (or rebased)
+
+## Merge Process
+
+### Step 1: Fetch Latest
+```bash
+git fetch origin main
+```
+
+### Step 2: Check Divergence
+```bash
+BEHIND=$(git rev-list --count HEAD..origin/main)
+if [ "$BEHIND" -gt 0 ]; then
+  # Need rebase or merge
+fi
+```
+
+### Step 3: Merge
+Use `merge_pr` MCP tool with:
+- Merge method: `squash` (recommended) or `merge`
+- Commit message: From SENTINEL's PR description
+
+### Step 4: Verify
+- Confirm merge completed
+- Confirm branch deleted (optional)
+
+### Step 5: Sync Active Worktrees
+
+After a successful merge into main, **all active FORGE worktrees MUST be rebased**
+onto the updated main to prevent drift and merge conflicts.
+
+**Policy:** No branch may fall behind main. All branches must be at main or ahead of main.
+
+```bash
+# Fetch the latest main (now including the merge we just performed)
+git fetch origin main
+
+# Sync every active worktree
+for wt in $(git worktree list --porcelain | grep "^worktree" | cut -d' ' -f2); do
+  BRANCH=$(git -C "$wt" branch --show-current)
+  if [ "$BRANCH" != "main" ] && [ -n "$BRANCH" ]; then
+    BEHIND=$(git -C "$wt" rev-list --count "HEAD..origin/main" 2>/dev/null || echo "0")
+    if [ "$BEHIND" -gt 0 ]; then
+      echo "Syncing worktree $wt ($BRANCH) — $BEHIND commits behind main"
+      git -C "$wt" rebase origin/main
+      if [ $? -ne 0 ]; then
+        git -C "$wt" rebase --abort
+        echo "CONFLICT in $wt on branch $BRANCH — requires manual resolution"
+        # Report conflict to NEXUS
+      fi
+    else
+      echo "Worktree $wt ($BRANCH) is up to date"
+    fi
+  fi
+done
+```
+
+Alternatively, use the dedicated sync script:
+```bash
+bash scripts/sync-worktrees.sh
+```
+
+**Conflict handling:**
+- If rebase conflicts, **abort immediately** — do NOT attempt auto-resolution
+- Report the conflict to NEXUS with the worktree path and branch name
+- Set the affected worker's STATUS.json to `BLOCKED` with reason `REBASE_CONFLICT`
+- A human or fresh FORGE instance must resolve the conflict
+
+### Step 6: Report
+- Emit merge event
+- Update shared store with merge status
+- Include worktree sync results in the report
+
+## Merge Methods
+
+| Method | Use When |
+|--------|----------|
+| `squash` | Single logical change (recommended) |
+| `merge` | Multiple commits should be preserved |
+| `rebase` | Linear history preferred |
+
+## Post-Merge
+
+1. **Sync**: Rebase all active worktrees onto updated main (Step 5)
+2. **Cleanup**: Remove worktree for the merged branch only
+3. **Notify**: Emit event for NEXUS (include sync results)
+4. **Update**: Set worker slot to Idle
+
+## Failure Handling
+
+If merge fails:
+1. Check for conflicts
+2. Report to NEXUS with `deploy_failed`
+3. Do NOT attempt to resolve conflicts automatically
+
+If worktree sync fails (rebase conflict):
+1. Abort the rebase immediately
+2. Report to NEXUS with worktree path and branch name
+3. Set affected worker STATUS.json to `BLOCKED` with reason `REBASE_CONFLICT`
+4. Do NOT attempt to resolve conflicts automatically — assign a fresh FORGE or human

package/bin/orchestration/plugin/skills/vessel-pdf.md

@@ -0,0 +1,20 @@
+---
+name: pdf
+description: Generating formal, secure reports for deployment cycles and infrastructure mapping.
+---
+
+# VESSEL Infrastructure Reporting Skill
+
+Use this skill to generate tamper-proof, high-quality reports on infrastructure state and deployment history.
+
+## Reporting Types
+
+- **Infrastructure Audit**: PDF mapping of current cloud resources and security groups.
+- **Deployment Sign-off**: Formal PDF certificate of successful deployment, including QA pass logs.
+- **Security Scans**: Summarized PDF reports of vulnerability scans performed during CI/CD.
+
+## Requirements
+
+- Professional, objective formatting.
+- Inclusion of cryptographic hashes or signatures where required.
+- Clear, scannable summaries for architectural review.

package/bin/orchestration/plugin/skills/vessel-webapp-testing.md

@@ -0,0 +1,34 @@
+---
+name: webapp-testing
+description: Toolkit for interacting with and testing local web applications using Playwright.
+---
+
+# Web Application Testing Skill
+
+Use this skill to verify frontend functionality, debug UI behavior, and capture browser state for evaluation or deployment verification.
+
+## Workflow
+
+1. **Reconnaissance**:
+   - Navigate to the local server URL.
+   - Wait for `networkidle` state to ensure JS execution is complete.
+   - Inspect the rendered DOM or take a full-page screenshot.
+
+2. **Identification**:
+   - Locate specific elements using descriptive selectors (`text=`, `role=`, CSS, or IDs).
+   - Use `page.locator()` and `all()` to discover interactive elements.
+
+3. **Execution**:
+   - Write Playwright scripts to perform actions (click, type, navigate).
+   - Verify assertions and capture logs for debugging.
+
+## Helper Pattern
+
+When working with local servers, ensure the server is running correctly before beginning reconnaissance. If managing server lifecycles, wait for port availability.
+
+## Best Practices
+
+- **Synchronous Logic**: Use `playwright.sync_api` for cleaner script integration where applicable.
+- **Headless Mode**: Always launch browsers in headless mode for server-side execution.
+- **Waits**: Use `wait_for_selector` or specific network idle states instead of arbitrary timeouts.
+- **Artifacts**: Capture screenshots and console logs to provide proof of verification.