@the-agenticflow/openflows 0.1.3 → 0.1.5

package/bin/orchestration/plugin/skills/forge-planning.md

@@ -0,0 +1,102 @@
+# FORGE Planning Skill
+
+## Writing PLAN.md
+
+Before any implementation, write a plan.
+Use the `/plan` command to structure it correctly.
+
+## What a good plan contains
+
+1. **Your understanding of the ticket** - in your own words
+2. **Technical approach** - follows `orchestration/agent/arch/patterns.md` (if it exists)
+3. **Explicit segment breakdown** - each segment is independently testable
+4. **Definition of done per segment** - specific and verifiable
+5. **List of files you will create or modify**
+6. **Risk areas** - things you are uncertain about
+7. **Questions for SENTINEL** - clarifications needed before starting
+
+## Segment sizing
+
+A good segment:
+- Touches 1-3 files
+- Has a single clear purpose
+- Can be tested in isolation
+- Takes roughly 20-40 minutes to implement
+
+A segment that is too large:
+- Touches more than 5 files
+- Has multiple unrelated concerns
+- Cannot be independently verified
+
+**Split it.**
+
+## Example PLAN.md structure
+
+```markdown
+# PLAN: [Ticket Title]
+
+## Understanding
+
+[Brief summary of what we're building and why]
+
+## Technical Approach
+
+[How we'll implement it, referencing existing patterns]
+
+## Segments
+
+### Segment 1: [Name]
+
+**Purpose:** [Single sentence]
+
+**Files:**
+- `src/path/file1.ts` (new)
+- `src/path/file2.ts` (modify)
+
+**Definition of Done:**
+- [ ] [Specific criterion 1]
+- [ ] [Specific criterion 2]
+- [ ] Tests pass
+
+### Segment 2: [Name]
+...
+
+## Files Changed
+
+- `src/auth/login.ts` (new)
+- `src/middleware/auth.ts` (modify)
+- `tests/auth/login.test.ts` (new)
+
+## Out of Scope
+
+- [Explicitly list what we're NOT building]
+- [This prevents scope creep]
+
+## Risks
+
+- [Risk 1]: [Mitigation strategy]
+- [Risk 2]: [Mitigation strategy]
+
+## Questions for SENTINEL
+
+- [Question 1]
+- [Question 2]
+```
+
+## Contract negotiation
+
+SENTINEL will review your plan.
+
+If SENTINEL objects:
+1. Read the objection carefully in `CONTRACT.md`
+2. Update `PLAN.md` addressing each specific objection
+3. Do not argue - either accept the feedback or ask a clarifying question
+
+Maximum 3 rounds of negotiation.
+After 3 rounds without agreement, the ticket is BLOCKED.
+
+## After CONTRACT is AGREED
+
+1. Read `CONTRACT.md` - these are your binding terms
+2. Begin implementation with Segment 1
+3. Do not deviate from the plan without updating `PLAN.md` and getting SENTINEL approval

package/bin/orchestration/plugin/skills/forge-skill-creator.md

@@ -0,0 +1,25 @@
+---
+name: skill-creator
+description: Meta-skill for creating, evaluating, and improving AgentFlow skills.
+---
+
+# FORGE Skill Creator Skill
+
+Use this skill when you need to formalize a new set of instructions or common workflows into an AgentFlow `SKILL.md`.
+
+## Workflow
+
+1. **Capture Intent**: What problem does this skill solve?
+2. **Research**: Identify best practices and common pitfalls for the targeted task.
+3. **Draft SKILL.md**:
+   - Use the frontmatter format: `name`, `description`.
+   - Include a clear `# Title`.
+   - Define a `# Workflow` or `# Guidelines`.
+4. **Iterative Improvement**: Use feedback from tests or user reviews to refine the skill instructions.
+
+## Skill Writing Tips
+
+- **Be Actionable**: Use imperative verbs.
+- **Be Structured**: Use headers and lists for scannability.
+- **Be Contextual**: Mention specific AgentFlow components if relevant.
+- **Be Minimal**: Only include instructions that provide high value.

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

@@ -0,0 +1,29 @@
+---
+name: web-artifacts-builder
+description: Guide for creating elaborate, multi-component React artifacts using Tailwind CSS and shadcn/ui.
+---
+
+# FORGE Web Artifacts Builder Skill
+
+Use this skill when building complex, stateful web artifacts that require more than a single-file approach.
+
+## Stack Requirements
+
+- **Framework**: React 18 / TypeScript.
+- **Styling**: Tailwind CSS + shadcn/ui.
+- **Components**: Utilize Radix UI primitives as provided by shadcn/ui.
+
+## Workflow
+
+1. **Plan Architecture**: Define state management and component hierarchy.
+2. **Implementation**: Build interactive components with clear prop interfaces.
+3. **Bundling**: Ensure all assets are optimized for presentation.
+4. **Testing**: Verify interactive flows (buttons, forms, state transitions).
+
+## Design Excellence
+
+Avoid "AI slop" by:
+
+- Using custom typography and color themes.
+- Implementing sophisticated layout patterns (not just centered stacks).
+- Adding subtle micro-animations and transitions.

package/bin/orchestration/plugin/skills/lore-brand-guidelines.md

@@ -0,0 +1,33 @@
+---
+name: brand-guidelines
+description: Maintains project-specific visual and tonal identity for AgentFlow documentation.
+---
+
+# AgentFlow Brand & Style Guidelines
+
+Use this skill to ensure all documentation and UI copy adheres to the AgentFlow project identity.
+
+## Visual Identity
+
+### Colors
+
+- **Primary**: Agentic Blue (#0047AB) - Represents focus and intelligence.
+- **Secondary**: Flow Silver (#C0C0C0) - Represents agility and connection.
+- **Accent**: Gravity Dark (#1A1A1A) - Represents stability and core logic.
+
+### Typography
+
+- **Headings**: Use strong, geometric sans-serif fonts (e.g., Montserat, Inter).
+- **Body**: Use clean, highly readable serif or sans-serif fonts (e.g., Lora, Open Sans).
+
+## Tonal Guidelines
+
+- **Professional & Precise**: Avoid jargon where possible, but maintain technical accuracy.
+- **Encouraging & Agentic**: Empower the user to interact with the system.
+- **Concise**: Value the user's time.
+
+## Formatting Standards
+
+- Use GitHub-style alerts (Note, Tip, Important, Warning, Caution) for emphasis.
+- Use consistent header hierarchies.
+- Ensure all code snippets are syntax-highlighted.

package/bin/orchestration/plugin/skills/lore-changelog.md

@@ -0,0 +1,69 @@
+---
+name: changelog
+description: Skill for maintaining CHANGELOG.md
+---
+
+# Changelog Skill
+
+## CHANGELOG Format
+
+Follow [Keep a Changelog](https://keepachangelog.com/):
+
+```markdown
+# Changelog
+
+## [Unreleased]
+
+### Added
+- New feature X
+
+### Changed
+- Modified behavior Y
+
+### Fixed
+- Bug fix Z
+
+## [1.2.0] - 2024-01-15
+
+### Added
+- Feature A
+```
+
+## Categories
+
+| Category | Use For |
+|----------|---------|
+| `Added` | New features |
+| `Changed` | Modified behavior |
+| `Deprecated` | Soon-to-be removed |
+| `Removed` | Removed features |
+| `Fixed` | Bug fixes |
+| `Security` | Security fixes |
+
+## Entry Style
+
+### Good Entry
+```
+- Add OAuth2 authentication support (#42)
+```
+
+### Bad Entry
+```
+- Fixed stuff
+- Updated code
+```
+
+## Process
+
+1. Read PR description from SENTINEL's final-review.md
+2. Categorize changes
+3. Write concise, user-focused entry
+4. Place under `[Unreleased]` section
+5. Commit with message: `docs: update CHANGELOG for T-{id}`
+
+## Release
+
+When version is released:
+1. Rename `[Unreleased]` to `[version] - date`
+2. Add new `[Unreleased]` section
+3. Tag release in git

package/bin/orchestration/plugin/skills/lore-doc-coauthoring.md

@@ -0,0 +1,33 @@
+---
+name: doc-coauthoring
+description: Advanced workflow for iterative documentation refinement and reader testing.
+---
+
+# LORE Doc Co-Authoring Skill
+
+Use this skill when tasked with creating or refining complex documentation. This workflow ensures that the final output is contextually accurate and reader-friendly.
+
+## Workflow Stages
+
+### Stage 1: Context Gathering
+
+- **Identify Goals**: What is the purpose of the document? Who is the audience?
+- **Gather Info**: Interview the user or research the codebase to capture all necessary details.
+
+### Stage 2: Refinement & Structure
+
+- **Iterative Drafting**: Start with a structure and refine it based on feedback.
+- **Gap Check**: Identify missing information and resolve contradictions.
+- **Drafting**: Write clear, professional content.
+
+### Stage 3: Reader Testing
+
+- **Predict Reader Questions**: What will the reader be confused about?
+- **Sub-Agent Testing**: If possible, ask a sub-agent to "read" the doc and provide feedback.
+- **Iterate**: Fix issues identified during testing.
+
+## Quality Standards
+
+- Clarity, conciseness, and accuracy are paramount.
+- Maintain a consistent tone throughout the document.
+- Use visual hierarchy (headers, lists, alerts) to improve readability.

package/bin/orchestration/plugin/skills/lore-documentation.md

@@ -0,0 +1,57 @@
+---
+name: documentation
+description: Skill for maintaining project documentation
+---
+
+# Documentation Skill
+
+## Documentation Types
+
+### User Documentation
+- `README.md`: Project overview, setup, usage
+- `docs/usage/`: How-to guides
+- `docs/api/`: API reference
+
+### Developer Documentation
+- `CONTRIBUTING.md`: Contribution guidelines
+- `docs/architecture/`: System design
+- `.agent/standards/`: Coding standards
+
+### Changelog
+- `CHANGELOG.md`: User-facing changes
+
+## When to Update
+
+Update documentation when:
+- New feature added
+- Breaking change introduced
+- API modified
+- Configuration changed
+- Dependencies updated
+
+## Documentation Style
+
+### README Updates
+- Keep concise
+- Update examples
+- Reflect current API
+
+### API Documentation
+- Document all public interfaces
+- Include examples
+- Document error conditions
+
+### Architecture Docs
+- Update diagrams if structure changed
+- Document new patterns
+- Update decision records
+
+## Commit Format
+
+```
+docs: update README for new auth feature
+
+- Add OAuth2 setup instructions
+- Update configuration example
+- Add troubleshooting section
+```

package/bin/orchestration/plugin/skills/lore-docx.md

@@ -0,0 +1,20 @@
+---
+name: docx
+description: Advanced document generation, analysis, and refinement for team reports and external docs.
+---
+
+# LORE Advanced Document Skill
+
+Use this skill when processing Word documents (.docx) or generating formal reports in document formats.
+
+## Capabilities
+
+- **Structure Analysis**: Verify document hierarchy and style consistency.
+- **New Doc Generation**: Create professional reports from markdown context.
+- **XML Refinement**: Perform low-level XML edits for tracking changes or complex formatting (Table of Contents, Headers).
+
+## Critical Rules
+
+- **No Unicode Bullets**: Always use standard list formatting.
+- **Style Overrides**: Ensure headers match the Brand Style Guidelines.
+- **Table Formatting**: Use consistent borders and cell padding for readability.

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

@@ -0,0 +1,20 @@
+---
+name: pdf
+description: Advanced PDF processing, including creation, analysis, text extraction, and watermarking.
+---
+
+# LORE Advanced PDF Skill
+
+Use this skill to process incoming PDF reference material or to generate formal, secure PDF outputs.
+
+## Processing Tasks
+
+- **Extraction**: Extract text and tables from complex PDF layouts using `pdfplumber`.
+- **Generation**: Create formal reports with consistent branding using `reportlab`.
+- **Security**: Apply watermarking or password protection to sensitive documents.
+
+## Quality Standards
+
+- Ensure all generated PDFs are searchable (OCR/embedded text).
+- Maintain high-resolution assets for images and charts within the PDF.
+- Follow the visual identity from `Brand & Style Guidelines`.

package/bin/orchestration/plugin/skills/lore-pptx.md

@@ -0,0 +1,23 @@
+---
+name: pptx
+description: Professional presentation design and generation using a theme-first approach.
+---
+
+# LORE Presentation Design Skill
+
+Use this skill to create high-impact, professional slide decks (.pptx) from project data or documentation.
+
+## Design Workflow
+
+1. **Choose a Theme**: Select an established goal (see `theme-factory`) or define a new one.
+2. **Slide Architecture**:
+   - One primary idea per slide.
+   - Use high-quality typography and consistent color palettes.
+   - Maintain a 16:9 aspect ratio.
+3. **Execution**: Use `python-pptx` or equivalent libraries to generate the deck.
+
+## Quality Assurance
+
+- **Visual QA**: Check for text overflows, color contrast, and font consistency.
+- **Content QA**: Ensure the message flows logically across the deck.
+- **Brand Alignment**: Follow the `Brand & Style Guidelines` strictly.

package/bin/orchestration/plugin/skills/lore-theme-factory.md

@@ -0,0 +1,20 @@
+---
+name: theme-factory
+description: Professional visual styling and theming for AgentFlow documentation and reports.
+---
+
+# LORE Theme & Styling Skill
+
+Use this skill to apply consistent, professional themes to all documentation, changelogs, and generated reports.
+
+## Themes & Atmosphere
+
+- **The "Agentic" Theme**: Blue/Silver/Dark Grey. High-tech, professional.
+- **The "Focus" Theme**: Monochrome/High-Contrast. Minimalist, objective.
+- **The "Warning" Theme**: Amber/Black. Used for critical alerts or post-mortem reports.
+
+## Styling Rules
+
+- Apply font pairings consistently (Display for headers, Serif/Sans for body).
+- Use color accents for data visualization and call-to-action blocks.
+- Ensure all styling enhances readability and doesn't distract from the content.

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

@@ -0,0 +1,20 @@
+---
+name: xlsx
+description: Advanced Excel document creation, editing, and technical data analysis.
+---
+
+# LORE Advanced Excel Skill
+
+Use this skill for generating complex reports that involve budgeting, technical metrics, or financial modeling.
+
+## Core Requirements
+
+- **Use Formulas**: NEVER hardcode values that can be calculated.
+- **Data Integrity**: Use `pandas` for large dataset analysis before writing to Excel.
+- **Formatting**: Apply professional formatting (headers, borders, number formats) for all outputs.
+
+## Analysis Patterns
+
+- **Summary Sheets**: Create high-level dashboards at the beginning of the workbook.
+- **Validation**: Include formula testing strategies to ensure zero erroneous calculations.
+- **Documentation**: Comment complex formulas or data sources within the sheet.

package/bin/orchestration/plugin/skills/nexus-doc-coauthoring.md

@@ -0,0 +1,21 @@
+---
+name: doc-coauthoring
+description: Collaborative workflow for drafting and refining project-level documents and plans.
+---
+
+# NEXUS Collaborative Planning Skill
+
+Use this skill when collaborating with the user to build high-level project plans or architectural documents.
+
+## Collaborative Workflow
+
+1. **Gather Intent**: Ask clarifying questions to understand the project's "North Star".
+2. **Draft & Discuss**: Present a skeleton plan and wait for user feedback.
+3. **Iterative Refinement**: Refine the plan based on constraints and goals uncovered during the session.
+4. **Reader Projection**: Anticipate stakeholder questions and address them in the plan.
+
+## Focus Areas
+
+- Clarity of objectives.
+- Resource and time estimation.
+- Risk identification and mitigation strategies.

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

@@ -0,0 +1,28 @@
+---
+name: internal-comms
+description: Guidelines and templates for professional internal communications (status reports, project updates, etc.).
+---
+
+# NEXUS Internal Comms Skill
+
+Use this skill to communicate project status, plans, and problems to stakeholders in a professional and structured manner.
+
+## Communication Types
+
+- **3P Updates**: Progress (what was done), Plans (what is next), Problems (blockers).
+- **Status Reports**: High-level summaries of project health.
+- **Leadership Updates**: Concise, executive-level summaries focusing on impact.
+- **Project Updates**: Detailed progress reports on specific initiatives.
+
+## Best Practices
+
+- **Tone**: Keep it objective, professional, and outcome-oriented.
+- **Clarity**: Use bullet points and clear headings to make updates scannable.
+- **Honesty**: Be transparent about problems and risks.
+- **Actionable**: Always include clear "Next Steps" or "Asks" for the reader.
+
+## 3P Template Format
+
+- **Progress**: Key accomplishments since the last update.
+- **Plans**: Primary objectives for the next period.
+- **Problems**: Current blockers or risks requiring attention.

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

@@ -0,0 +1,63 @@
+---
+name: orchestration
+description: Core orchestration skill for assigning work and managing workers
+---
+
+# NEXUS Orchestration Skill
+
+## Worker Assignment Protocol
+
+### Step 1: Check Worker Availability
+Read `KEY_WORKER_SLOTS` from shared store. Look for workers with status `Idle`.
+
+### Step 2: Prioritize Tickets
+- **BLOCKING (CI-FIRST):** CI setup tickets (IDs starting with `T-CI-`) must be assigned before any other work if `ci_readiness` is `missing` or `ci_must_go_first` is `true`. Without CI, VESSEL stalls on every PR.
+- High priority: Security fixes, blocking issues
+- Medium priority: Features, enhancements
+- Low priority: Refactors, documentation
+
+### Step 3: Match Worker to Ticket
+Consider:
+- Worker capacity (some workers may have specializations)
+- Ticket complexity vs worker history
+- Load balancing across workers
+
+### Step 4: Assign Work
+Update worker slot:
+```json
+{
+  "id": "forge-1",
+  "status": {
+    "Assigned": {
+      "ticket_id": "T-42",
+      "issue_url": "https://github.com/org/repo/issues/42"
+    }
+  }
+}
+```
+
+### Step 5: Emit Event
+Log assignment to event stream for observability.
+
+## Command Gate Protocol
+
+### Evaluating Dangerous Commands
+
+Workers may request approval for commands like:
+- `rm -rf` (file deletion)
+- `git push --force` (force push)
+- `npm publish` (package publishing)
+- Database migrations
+
+### Decision Framework
+
+1. **Necessity**: Is this command required for the ticket?
+2. **Risk**: What could go wrong?
+3. **Reversibility**: Can we undo the effects?
+4. **Alternatives**: Is there a safer approach?
+
+### Approval Response
+Set worker status from `Suspended` back to `Assigned`.
+
+### Rejection Response
+Set worker status to `Idle` with rejection reason.

package/bin/orchestration/plugin/skills/nexus-skill-creator.md

@@ -0,0 +1,15 @@
+---
+name: skill-creator
+description: Supervisory skill for identifying, directing, and evaluating the creation of new agent capabilities.
+---
+
+# NEXUS Skill Supervision Skill
+
+Use this skill to oversee the "meta-evolution" of the agent system by directing FORGE to create new skills.
+
+## Supervision Checklist
+
+- **Gap Identification**: Notice when agents struggle with a repeating pattern and need a skill.
+- **Direction**: Task FORGE with creating a specific `SKILL.md` based on successful session logs.
+- **Quality Gate**: Review new skills created by FORGE to ensure they are actionable and follow the AgentFlow standard.
+- **Integration**: Ensure new skills are correctly registered in the system manifest.

package/bin/orchestration/plugin/skills/nexus-slack-gif-creator.md

@@ -0,0 +1,21 @@
+---
+name: slack-gif-creator
+description: Custom GIF animation for project status alerts and team communication.
+---
+
+# NEXUS Communication Animations Skill
+
+Use this skill to create engaging, animated status alerts or celebration artifacts for the team.
+
+## Animation Concepts
+
+- **Pulse/Heartbeat**: For "System Alive" monitors.
+- **Explode/Particle Burst**: For "Project Milestone Achieved".
+- **Shake/Vibrate**: For "Critical Alert" or "Blocker Identified".
+- **Slide/Fade**: For transitioning between status updates.
+
+## Technical Execution
+
+- Use procedural graphics with easing functions for smooth motion.
+- Ensure GIFs are optimized for size without sacrificing visual clarity.
+- Maintain a tone that balances professionalism with team engagement.

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

@@ -0,0 +1,56 @@
+---
+name: ticket-triage
+description: Skill for analyzing and prioritizing incoming tickets
+---
+
+# Ticket Triage Skill
+
+## Analyzing Tickets
+
+### Extract Key Information
+From each ticket, identify:
+- **Type**: Bug, feature, refactor, documentation
+- **Priority**: Critical, high, medium, low
+- **Scope**: Files/components affected
+- **Dependencies**: Blocked by other tickets?
+- **Acceptance Criteria**: Definition of done
+
+### Estimation Heuristics
+
+| Scope | Estimated Segments |
+|-------|-------------------|
+| Single file, small change | 1-2 |
+| Multiple files, moderate | 3-5 |
+| Cross-cutting, large | 6-10 |
+
+### Blocking Detection
+
+A ticket is blocked if:
+- Depends on unmerged PR
+- Requires external API/service
+- Needs clarification from stakeholder
+
+## Prioritization Matrix
+
+```
+          | High Impact | Low Impact
+---------|-------------|------------
+Urgent   | Do Now      | Schedule
+Not Urgent| Plan       | Backlog
+```
+
+## CI-First Override
+
+**CI setup tickets ALWAYS take absolute priority over all other tickets.**
+
+Before applying the normal matrix, check if the repository has CI workflows:
+- If `ci_readiness` is `missing`: Only CI setup tickets should be assigned
+- CI setup tickets are identified by: ID starting with `T-CI-`, or title containing "CI" + ("setup" or "pipeline" or "workflow")
+- Without CI, VESSEL cannot validate PRs and will stall, wasting all worker cycles
+- This override applies regardless of issue number, apparent urgency, or any other priority signal
+
+## Assignment Considerations
+
+- Complexity matching worker experience
+- File ownership (avoid conflicts)
+- Load balancing across available workers