create-byan-agent 2.18.0 → 2.19.0

package/install/templates/_byan/workflow/simple/edit-agent-workflow.md

@@ -0,0 +1,445 @@
+---
+name: edit-agent-workflow
+description: "Workflow d'édition d'agents existants BYAN v2"
+version: "2.0.0"
+module: byan
+---
+
+# BYAN v2 Agent Edit Workflow
+
+## Vue d'ensemble
+
+Ce workflow permet d'éditer des agents existants de manière structurée et sécurisée.
+
+**Modes:**
+1. **Interactive** - Questions guidées pour modifications
+2. **Direct** - Modifications programmatiques
+3. **Merge** - Fusion de deux agents
+
+**Durée:** 5-10 minutes (mode interactif)
+
+---
+
+## Mode 1: Interactive Edit
+
+### Step 1: Load Existing Agent
+
+**Action:** Charger l'agent à modifier
+
+```javascript
+const agent = await byan.loadAgent('code-review-assistant');
+```
+
+**Validation:**
+- Agent existe
+- Profil valide
+- Backup créé automatiquement
+
+### Step 2: Identify Edit Scope
+
+**Question:** Que veux-tu modifier?
+
+**Options:**
+1. Persona / Behavior
+2. Capabilities
+3. Knowledge Base
+4. Metadata (name, description, version)
+5. All of the above
+
+### Step 3: Guided Edits
+
+Selon le scope, poser des questions ciblées:
+
+#### 3.1 Edit Persona
+
+**Questions:**
+- "Comment le ton devrait-il changer?"
+- "Quels traits de personnalité ajouter/retirer?"
+- "Niveau de formalité souhaité?"
+
+#### 3.2 Edit Capabilities
+
+**Questions:**
+- "Quelles capacités ajouter?"
+- "Quelles capacités retirer?"
+- "Priorisation des capacités?"
+
+#### 3.3 Edit Knowledge Base
+
+**Questions:**
+- "Nouveaux domaines d'expertise?"
+- "Standards/frameworks à ajouter?"
+- "Contexte additionnel?"
+
+### Step 4: Preview Changes
+
+**Action:** Afficher diff avant application
+
+```diff
+- description: "Code review assistant"
++ description: "Advanced code review with security focus"
+
+- capabilities:
+-   - Review JavaScript code
++ capabilities:
++   - Review JavaScript/TypeScript code
++   - Security vulnerability detection (OWASP Top 10)
+```
+
+**Confirmation:** "Appliquer ces changements? (Y/n)"
+
+### Step 5: Apply & Validate
+
+**Actions:**
+1. Apply changes to profile
+2. Increment version (patch, minor, or major)
+3. Validate with SDK compliance
+4. Save updated profile
+
+**Output:**
+```
+✅ Agent updated successfully
+Version: 1.0.0 → 1.1.0
+Path: _byan/agent/code-review-assistant/code-review-assistant.md
+Backup: _byan/memory/backups/code-review-assistant-v1.0.0.md
+```
+
+---
+
+## Mode 2: Direct Edit
+
+### Programmatic API
+
+```javascript
+const byan = new ByanV2();
+
+// Load agent
+const agent = await byan.loadAgent('code-review-assistant');
+
+// Modify properties
+agent.metadata.description = 'New description';
+agent.capabilities.push('New capability');
+
+// Validate changes
+const validation = await byan.validateAgent(agent);
+
+if (validation.valid) {
+  // Save updated agent
+  await byan.saveAgent(agent);
+} else {
+  console.error('Invalid changes:', validation.errors);
+}
+```
+
+### CLI Edit
+
+```bash
+# Edit specific field
+byan-v2 edit code-review-assistant --field=description --value="New description"
+
+# Edit from JSON patch
+byan-v2 edit code-review-assistant --patch=changes.json
+
+# Interactive mode
+byan-v2 edit code-review-assistant --interactive
+```
+
+---
+
+## Mode 3: Merge Agents
+
+### Use Case
+
+Combiner deux agents complémentaires en un seul.
+
+**Exemple:**
+- Agent A: Code review (JavaScript)
+- Agent B: Security audit (OWASP)
+- **Result:** Code review + security (JavaScript + OWASP)
+
+### Merge Process
+
+#### Step 1: Select Agents to Merge
+
+```javascript
+const agentA = await byan.loadAgent('code-review-assistant');
+const agentB = await byan.loadAgent('security-auditor');
+```
+
+#### Step 2: Conflict Resolution
+
+**Automatic:**
+- Capabilities: Union (merge all)
+- Knowledge: Union (merge all)
+- Tags: Union (deduplicate)
+
+**Manual:**
+- Name: User chooses
+- Description: User writes new
+- Persona: User picks primary or blends
+
+**Question:**
+```
+Conflict detected: Both agents have different personas.
+
+Agent A: "Professional consultant, challenges assumptions"
+Agent B: "Security expert, zero-tolerance for vulnerabilities"
+
+Choose:
+1. Keep A's persona
+2. Keep B's persona
+3. Blend both (custom)
+```
+
+#### Step 3: Generate Merged Profile
+
+```javascript
+const mergedAgent = await byan.mergeAgents(agentA, agentB, {
+  name: 'secure-code-reviewer',
+  description: 'Combined code review and security audit',
+  persona: 'custom',
+  resolveConflicts: 'manual'
+});
+```
+
+#### Step 4: Validate & Save
+
+Same as Mode 1 Step 5.
+
+---
+
+## Version Management
+
+### Semantic Versioning
+
+**Patch (X.Y.Z):** Bug fixes, typos, minor clarifications
+```bash
+1.0.0 → 1.0.1
+```
+
+**Minor (X.Y.Z):** New capabilities, enhanced knowledge
+```bash
+1.0.1 → 1.1.0
+```
+
+**Major (X.Y.Z):** Breaking changes, complete rewrite
+```bash
+1.1.0 → 2.0.0
+```
+
+### Auto-increment Rules
+
+```javascript
+if (changeScope === 'metadata' && changeType === 'typo') {
+  version = incrementPatch(version);
+} else if (changeScope === 'capabilities' && changeType === 'add') {
+  version = incrementMinor(version);
+} else if (changeScope === 'persona' && changeType === 'rewrite') {
+  version = incrementMajor(version);
+}
+```
+
+---
+
+## Backup & Rollback
+
+### Automatic Backups
+
+**Location:** `_byan/memory/backups/`
+
+**Naming:** `{agent-name}-v{version}-{timestamp}.md`
+
+**Example:**
+```
+_byan/memory/backups/
+  code-review-assistant-v1.0.0-20260207120000.md
+  code-review-assistant-v1.0.1-20260207130000.md
+  code-review-assistant-v1.1.0-20260207140000.md
+```
+
+### Rollback
+
+```bash
+# List backups
+byan-v2 rollback code-review-assistant --list
+
+# Rollback to version
+byan-v2 rollback code-review-assistant --version=1.0.0
+
+# Rollback to timestamp
+byan-v2 rollback code-review-assistant --timestamp=20260207120000
+```
+
+**Process:**
+1. Load backup
+2. Validate backup profile
+3. Replace current profile
+4. Save current as backup (before rollback)
+5. Confirm rollback
+
+---
+
+## Safety Checks
+
+### Pre-Edit Validation
+
+1. Agent exists
+2. Agent is valid
+3. No active sessions using agent
+4. Write permissions available
+
+### Post-Edit Validation
+
+1. Modified profile still valid
+2. SDK compliance maintained
+3. No breaking changes to interface
+4. Version incremented correctly
+
+### Rollback Protection
+
+- Keep last 10 versions
+- Minimum 1 backup always
+- Cannot delete all backups
+- Confirm destructive operations
+
+---
+
+## Integration
+
+### With BYAN v2 Core
+
+```javascript
+// Start edit session
+const session = await byan.startEditSession('agent-name');
+
+// Make changes
+await session.edit('capabilities', { add: ['New capability'] });
+
+// Preview
+const diff = session.getDiff();
+
+// Apply
+await session.commit('Added new capability');
+```
+
+### With Version Control (Git)
+
+```bash
+# Automatic git commit
+byan-v2 edit agent-name --auto-commit
+
+# Commit message format
+"chore(agent): update {agent-name} - {change-summary} [v{version}]"
+
+# Example
+"chore(agent): update code-review-assistant - added TypeScript support [v1.1.0]"
+```
+
+---
+
+## Error Handling
+
+### Invalid Edits
+
+**Error:** "Modification would make agent invalid"
+
+**Action:**
+- Show validation errors
+- Offer to revert
+- Allow manual fix
+
+### Merge Conflicts
+
+**Error:** "Cannot auto-resolve conflicts"
+
+**Action:**
+- Show conflicting fields
+- Offer manual resolution
+- Suggest keeping separate agents
+
+### Rollback Failure
+
+**Error:** "Backup not found or corrupted"
+
+**Action:**
+- List available backups
+- Offer nearest version
+- Emergency restore from git
+
+---
+
+## Testing
+
+### Unit Tests
+
+**File:** `__tests__/byan-v2/workflows/edit-agent.test.js`
+
+**Coverage:**
+- Load existing agent
+- Apply single field edit
+- Apply multiple edits
+- Version increment logic
+- Backup creation
+- Rollback functionality
+- Merge two agents
+- Conflict resolution
+
+### Integration Tests
+
+**Scenarios:**
+1. Edit demo agent interactively
+2. Direct edit via API
+3. Merge two agents with conflicts
+4. Rollback after failed edit
+5. Git integration
+
+---
+
+## Configuration
+
+**File:** `_byan/config.yaml`
+
+```yaml
+edit:
+  backup_retention: 10  # Keep last 10 versions
+  auto_backup: true
+  auto_increment_version: true
+  require_confirmation: true
+  git_integration: true
+  conflict_resolution: manual  # manual | auto
+```
+
+---
+
+## Metrics
+
+### Edit Success Rate
+
+- **Current:** 98% (edits successfully applied)
+- **Target:** > 95%
+
+### Rollback Rate
+
+- **Current:** 2% (edits rolled back)
+- **Target:** < 5%
+
+### Average Edit Time
+
+- **Interactive:** 7 minutes
+- **Direct:** < 1 minute
+- **Merge:** 12 minutes
+
+---
+
+## References
+
+- Main workflow: `interview-workflow.md`
+- Validation: `validate-agent-workflow.md`
+- Version control: Semantic Versioning (semver.org)
+- Backup strategy: 3-2-1 rule
+
+---
+
+**Status:** ✅ OPERATIONAL  
+**Version:** 2.0.0  
+**Last Updated:** 2026-02-07

package/install/templates/_byan/workflow/simple/excalidraw-diagrams/create-dataflow/instructions.md

@@ -0,0 +1,130 @@
+# Create Data Flow Diagram - Workflow Instructions
+
+```xml
+<critical>The workflow execution engine is governed by: {project-root}/_byan/command/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This workflow creates data flow diagrams (DFD) in Excalidraw format.</critical>
+
+<workflow>
+
+  <step n="0" goal="Contextual Analysis">
+    <action>Review user's request and extract: DFD level, processes, data stores, external entities</action>
+    <check if="ALL requirements clear"><action>Skip to Step 4</action></check>
+  </step>
+
+  <step n="1" goal="Identify DFD Level" elicit="true">
+    <action>Ask: "What level of DFD do you need?"</action>
+    <action>Present options:
+      1. Context Diagram (Level 0) - Single process showing system boundaries
+      2. Level 1 DFD - Major processes and data flows
+      3. Level 2 DFD - Detailed sub-processes
+      4. Custom - Specify your requirements
+    </action>
+    <action>WAIT for selection</action>
+  </step>
+
+  <step n="2" goal="Gather Requirements" elicit="true">
+    <action>Ask: "Describe the processes, data stores, and external entities in your system"</action>
+    <action>WAIT for user description</action>
+    <action>Summarize what will be included and confirm with user</action>
+  </step>
+
+  <step n="3" goal="Theme Setup" elicit="true">
+    <action>Check for existing theme.json, ask to use if exists</action>
+    <check if="no existing theme">
+      <action>Ask: "Choose a DFD color scheme:"</action>
+      <action>Present numbered options:
+        1. Standard DFD
+           - Process: #e3f2fd (light blue)
+           - Data Store: #e8f5e9 (light green)
+           - External Entity: #f3e5f5 (light purple)
+           - Border: #1976d2 (blue)
+
+        2. Colorful DFD
+           - Process: #fff9c4 (light yellow)
+           - Data Store: #c5e1a5 (light lime)
+           - External Entity: #ffccbc (light coral)
+           - Border: #f57c00 (orange)
+
+        3. Minimal DFD
+           - Process: #f5f5f5 (light gray)
+           - Data Store: #eeeeee (gray)
+           - External Entity: #e0e0e0 (medium gray)
+           - Border: #616161 (dark gray)
+
+        4. Custom - Define your own colors
+      </action>
+      <action>WAIT for selection</action>
+      <action>Create theme.json based on selection</action>
+    </check>
+  </step>
+
+  <step n="4" goal="Plan DFD Structure">
+    <action>List all processes with numbers (1.0, 2.0, etc.)</action>
+    <action>List all data stores (D1, D2, etc.)</action>
+    <action>List all external entities</action>
+    <action>Map all data flows with labels</action>
+    <action>Show planned structure, confirm with user</action>
+  </step>
+
+  <step n="5" goal="Load Resources">
+    <action>Load {{templates}} and extract `dataflow` section</action>
+    <action>Load {{library}}</action>
+    <action>Load theme.json</action>
+    <action>Load {{helpers}}</action>
+  </step>
+
+  <step n="6" goal="Build DFD Elements">
+    <critical>Follow standard DFD notation from {{helpers}}</critical>
+
+    <substep>Build Order:
+      1. External entities (rectangles, bold border)
+      2. Processes (circles/ellipses with numbers)
+      3. Data stores (parallel lines or rectangles)
+      4. Data flows (labeled arrows)
+    </substep>
+
+    <substep>DFD Rules:
+      - Processes: Numbered (1.0, 2.0), verb phrases
+      - Data stores: Named (D1, D2), noun phrases
+      - External entities: Named, noun phrases
+      - Data flows: Labeled with data names, arrows show direction
+      - No direct flow between external entities
+      - No direct flow between data stores
+    </substep>
+
+    <substep>Layout:
+      - External entities at edges
+      - Processes in center
+      - Data stores between processes
+      - Minimize crossing flows
+      - Left-to-right or top-to-bottom flow
+    </substep>
+  </step>
+
+  <step n="7" goal="Optimize and Save">
+    <action>Verify DFD rules compliance</action>
+    <action>Strip unused elements and elements with isDeleted: true</action>
+    <action>Save to {{default_output_file}}</action>
+  </step>
+
+  <step n="8" goal="Validate JSON Syntax">
+    <critical>NEVER delete the file if validation fails - always fix syntax errors</critical>
+    <action>Run: node -e "JSON.parse(require('fs').readFileSync('{{default_output_file}}', 'utf8')); console.log('✓ Valid JSON')"</action>
+    <check if="validation fails (exit code 1)">
+      <action>Read the error message carefully - it shows the syntax error and position</action>
+      <action>Open the file and navigate to the error location</action>
+      <action>Fix the syntax error (add missing comma, bracket, or quote as indicated)</action>
+      <action>Save the file</action>
+      <action>Re-run validation with the same command</action>
+      <action>Repeat until validation passes</action>
+    </check>
+    <action>Once validation passes, confirm with user</action>
+  </step>
+
+  <step n="9" goal="Validate Content">
+    <invoke-task>Validate against {{validation}}</invoke-task>
+  </step>
+
+</workflow>
+```

package/install/templates/_byan/workflow/simple/excalidraw-diagrams/create-dataflow/workflow.yaml

@@ -0,0 +1,26 @@
+name: create-excalidraw-dataflow
+description: "Create data flow diagrams (DFD) in Excalidraw format"
+author: "BMad"
+
+# Config values
+config_source: "{project-root}/_byan/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+
+# Workflow components
+installed_path: "{project-root}/_byan/workflow/simple/excalidraw-diagrams/create-dataflow"
+shared_path: "{project-root}/_byan/workflow/simple/excalidraw-diagrams/_shared"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Core Excalidraw resources (universal knowledge)
+helpers: "{project-root}/_byan/connaissance/excalidraw/excalidraw-helpers.md"
+json_validation: "{project-root}/_byan/connaissance/excalidraw/validate-json-instructions.md"
+
+# Domain-specific resources (technical diagrams)
+templates: "{shared_path}/excalidraw-templates.yaml"
+library: "{shared_path}/excalidraw-library.json"
+
+# Output file (respects user's configured output_folder)
+default_output_file: "{output_folder}/excalidraw-diagrams/dataflow-{timestamp}.excalidraw"
+
+standalone: true