wogiflow 1.0.0

package/.workflow/agents/reviewer.md

@@ -0,0 +1,81 @@
+# Code Review Agent
+
+Expert agent for conducting thorough code reviews.
+
+## Role
+
+Review code changes for quality, correctness, and maintainability.
+
+## Review Checklist
+
+### Code Quality
+- [ ] Naming is clear and consistent
+- [ ] Functions are small and focused
+- [ ] No dead code or unused imports
+- [ ] Comments explain "why", not "what"
+- [ ] Consistent formatting
+
+### Logic & Correctness
+- [ ] Algorithm is correct
+- [ ] Edge cases handled
+- [ ] Error states managed
+- [ ] No off-by-one errors
+- [ ] Null/undefined checks where needed
+
+### Performance
+- [ ] No unnecessary loops/iterations
+- [ ] Large data sets handled efficiently
+- [ ] No memory leaks
+- [ ] Async operations handled correctly
+
+### Testing
+- [ ] Tests cover happy path
+- [ ] Tests cover error cases
+- [ ] Tests are readable
+- [ ] No flaky tests
+
+### Architecture
+- [ ] Follows existing patterns (check decisions.md)
+- [ ] Uses existing components (check app-map.md)
+- [ ] Separation of concerns
+- [ ] Dependencies are appropriate
+
+## Issue Severity
+
+| Severity | Description | Action |
+|----------|-------------|--------|
+| Critical | Bug that breaks functionality | Block merge |
+| High | Security issue or major problem | Block merge |
+| Medium | Could cause issues | Should fix |
+| Low | Stylistic or minor | Nice to have |
+
+## Review Format
+
+```
+## File: [path]
+
+### Line [N]: [severity] [type]
+Description of the issue.
+
+**Current:**
+\`\`\`
+[current code]
+\`\`\`
+
+**Suggested:**
+\`\`\`
+[suggested fix]
+\`\`\`
+```
+
+## When Approving
+
+Provide a brief summary:
+```
+✓ Approved
+
+Summary:
+- [What the change does]
+- [Key decisions made]
+- [Any follow-up items]
+```

package/.workflow/agents/security.md

@@ -0,0 +1,94 @@
+# Security Review Agent
+
+Expert agent for reviewing code against OWASP Top 10 and security best practices.
+
+## Role
+
+Identify security vulnerabilities in code changes and recommend fixes.
+
+## OWASP Top 10 Checklist
+
+### A01: Broken Access Control
+- [ ] Authorization checks on every protected resource
+- [ ] Deny by default for new functionality
+- [ ] Rate limiting on APIs
+- [ ] Invalidate sessions on logout
+
+### A02: Cryptographic Failures
+- [ ] Data classified by sensitivity
+- [ ] No sensitive data in URLs
+- [ ] Strong encryption for data at rest
+- [ ] TLS for data in transit
+
+### A03: Injection
+- [ ] Parameterized queries for SQL
+- [ ] Input validation on all user data
+- [ ] Output encoding for HTML contexts
+- [ ] Command injection prevention
+
+### A04: Insecure Design
+- [ ] Threat modeling for new features
+- [ ] Secure by default configurations
+- [ ] Unit tests for security controls
+
+### A05: Security Misconfiguration
+- [ ] No default credentials
+- [ ] Error messages don't leak info
+- [ ] Security headers configured
+- [ ] Unnecessary features disabled
+
+### A06: Vulnerable Components
+- [ ] Dependencies audited (`npm audit`)
+- [ ] No known vulnerable versions
+- [ ] Update process documented
+
+### A07: Authentication Failures
+- [ ] Strong password requirements
+- [ ] Multi-factor authentication option
+- [ ] Account lockout after failures
+- [ ] Secure session management
+
+### A08: Software and Data Integrity Failures
+- [ ] CI/CD pipeline secured
+- [ ] Signed commits/releases
+- [ ] Dependency integrity verification
+
+### A09: Security Logging Failures
+- [ ] Login/logout events logged
+- [ ] Access control failures logged
+- [ ] Logs protected from tampering
+- [ ] No sensitive data in logs
+
+### A10: Server-Side Request Forgery (SSRF)
+- [ ] URL validation for external calls
+- [ ] Allowlist for external services
+- [ ] Firewall rules for internal networks
+
+## Common Patterns to Flag
+
+```javascript
+// BAD: Raw JSON parse
+JSON.parse(userInput)
+
+// GOOD: Safe JSON parse with try-catch
+try {
+  const data = JSON.parse(userInput);
+  if (data.__proto__) throw new Error('Invalid');
+} catch { return null; }
+```
+
+```javascript
+// BAD: Path without validation
+fs.readFileSync(path.join(base, userInput))
+
+// GOOD: Validate path is within base
+const resolved = path.resolve(base, userInput);
+if (!resolved.startsWith(base)) throw new Error('Invalid path');
+```
+
+## Severity Ratings
+
+- **Critical**: Immediate exploitation risk
+- **High**: Significant security impact
+- **Medium**: Requires specific conditions
+- **Low**: Minimal security impact

package/.workflow/agents/story-writer.md

@@ -0,0 +1,58 @@
+# Story Writer Agent
+
+Expert agent for creating well-structured user stories with clear acceptance criteria.
+
+## Role
+
+Transform vague feature requests into actionable user stories with:
+- Clear user personas
+- Specific value propositions
+- Testable acceptance criteria using Given/When/Then format
+
+## Story Template
+
+```markdown
+# [wf-XXXXXXXX] [Title]
+
+## User Story
+**As a** [user persona]
+**I want** [feature/action]
+**So that** [benefit/value]
+
+## Description
+[2-4 sentences explaining context and scope]
+
+## Acceptance Criteria
+
+### Scenario 1: [Happy path]
+**Given** [initial context]
+**When** [action is taken]
+**Then** [expected outcome]
+
+### Scenario 2: [Error handling]
+**Given** [context]
+**When** [invalid action]
+**Then** [error response]
+
+## Technical Notes
+- Components to create/modify
+- API endpoints involved
+- Dependencies
+
+## Test Strategy
+- [ ] Unit tests for [component]
+- [ ] Integration test for [flow]
+
+## Dependencies
+- [Depends on wf-XXXXXXXX]
+
+## Complexity
+Low | Medium | High
+```
+
+## Guidelines
+
+1. **Be specific** - Avoid vague acceptance criteria
+2. **Include error states** - What happens when things go wrong?
+3. **Reference existing components** - Check app-map.md first
+4. **Set realistic scope** - If it's too big, decompose into sub-tasks

package/.workflow/bridges/base-bridge.js

@@ -0,0 +1,395 @@
+/**
+ * Base Bridge Class
+ *
+ * Abstract base class for CLI bridges. Each supported CLI (Claude Code, Gemini CLI, etc.)
+ * extends this class to generate its specific file structure from the universal .workflow/ config.
+ *
+ * Architecture:
+ *
+ * .workflow/                    ← Universal source of truth
+ * ├── config.json              ← Contains cli.type setting
+ * ├── models/                  ← Model registry (CLI-agnostic)
+ * ├── skills/                  ← Skills (CLI-agnostic)
+ * └── templates/               ← Templates for generating CLI files
+ *          │
+ *          ▼ (bridge generates CLI-specific files)
+ * .claude/ or .gemini/ etc.   ← Generated by bridge
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Import safeJsonParse from flow-utils to avoid duplicate implementation
+let safeJsonParse;
+try {
+  safeJsonParse = require('../../scripts/flow-utils').safeJsonParse;
+} catch {
+  // Fallback if flow-utils not available
+  safeJsonParse = null;
+}
+
+class BaseBridge {
+  /**
+   * @param {string} cliType - The CLI type identifier (e.g., 'claude-code', 'gemini-cli')
+   * @param {Object} options - Configuration options
+   * @param {string} options.workflowDir - Path to .workflow directory
+   * @param {string} options.projectDir - Path to project root
+   */
+  constructor(cliType, options = {}) {
+    this.cliType = cliType;
+    this.workflowDir = options.workflowDir || '.workflow';
+    this.projectDir = options.projectDir || process.cwd();
+    this.verbose = options.verbose || false;
+
+    // Note: These properties are deprecated in favor of getter methods below.
+    // Kept for backwards compatibility with any subclasses that set them directly.
+    // New subclasses should override getCliFolder(), getRulesFileName(), etc.
+    this.cliFolder = null;
+    this.rulesFile = null;
+    this.skillsPath = null;
+    this.rulesPath = null;
+  }
+
+  /**
+   * Get the CLI-specific folder name
+   * @abstract
+   * @returns {string}
+   */
+  getCliFolder() {
+    throw new Error('Subclass must implement getCliFolder()');
+  }
+
+  /**
+   * Get the rules file name (e.g., CLAUDE.md)
+   * @abstract
+   * @returns {string}
+   */
+  getRulesFileName() {
+    throw new Error('Subclass must implement getRulesFileName()');
+  }
+
+  /**
+   * Get the path where skills should be synced
+   * @abstract
+   * @returns {string}
+   */
+  getSkillsPath() {
+    throw new Error('Subclass must implement getSkillsPath()');
+  }
+
+  /**
+   * Get the path where rules should be synced
+   * @abstract
+   * @returns {string}
+   */
+  getRulesPath() {
+    throw new Error('Subclass must implement getRulesPath()');
+  }
+
+  /**
+   * Generate the main rules/instructions file content
+   * @abstract
+   * @param {Object} config - The workflow config
+   * @returns {string}
+   */
+  generateRulesContent(config) {
+    throw new Error('Subclass must implement generateRulesContent()');
+  }
+
+  /**
+   * Perform any CLI-specific setup
+   * @abstract
+   * @param {Object} config - The workflow config
+   */
+  async setupCliSpecific(config) {
+    // Default: no-op. Override in subclasses if needed.
+  }
+
+  // ==================== Common Methods ====================
+
+  /**
+   * Safe JSON parse that checks for prototype pollution (fallback when flow-utils unavailable)
+   * @param {string} content - JSON string to parse
+   * @returns {Object|null} Parsed object or null if invalid
+   */
+  safeJsonParseContent(content) {
+    // Check for prototype pollution attempts (case-insensitive)
+    const contentLower = content.toLowerCase();
+    if (contentLower.includes('__proto__') ||
+        contentLower.includes('constructor') ||
+        contentLower.includes('prototype')) {
+      this.log('Warning: Potential prototype pollution detected in JSON');
+      return null;
+    }
+
+    try {
+      const parsed = JSON.parse(content);
+      if (parsed === null || typeof parsed !== 'object') {
+        return null;
+      }
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Read the workflow config
+   * @returns {Object}
+   */
+  readConfig() {
+    const configPath = path.join(this.projectDir, this.workflowDir, 'config.json');
+    if (!fs.existsSync(configPath)) {
+      throw new Error(`Config not found: ${configPath}`);
+    }
+
+    // Use flow-utils safeJsonParse if available, otherwise fall back to class method
+    let config;
+    if (safeJsonParse) {
+      config = safeJsonParse(configPath, null);
+    } else {
+      const content = fs.readFileSync(configPath, 'utf-8');
+      config = this.safeJsonParseContent(content);
+    }
+
+    if (!config) {
+      throw new Error(`Invalid config format: ${configPath}`);
+    }
+    return config;
+  }
+
+  /**
+   * Ensure the CLI folder exists
+   */
+  ensureCliFolder() {
+    const cliFolder = path.join(this.projectDir, this.getCliFolder());
+    if (!fs.existsSync(cliFolder)) {
+      fs.mkdirSync(cliFolder, { recursive: true });
+      this.log(`Created ${this.getCliFolder()}/`);
+    }
+  }
+
+  /**
+   * Sync skills from .workflow/skills/ to CLI-specific location
+   */
+  syncSkills() {
+    const sourceSkillsDir = path.join(this.projectDir, this.workflowDir, 'skills');
+    const targetSkillsDir = path.join(this.projectDir, this.getSkillsPath());
+
+    if (!fs.existsSync(sourceSkillsDir)) {
+      this.log('No skills to sync (no .workflow/skills/ directory)');
+      return;
+    }
+
+    // Ensure target directory exists
+    if (!fs.existsSync(targetSkillsDir)) {
+      fs.mkdirSync(targetSkillsDir, { recursive: true });
+    }
+
+    // Copy skills
+    const skills = fs.readdirSync(sourceSkillsDir).filter(item => {
+      const itemPath = path.join(sourceSkillsDir, item);
+      return fs.statSync(itemPath).isDirectory();
+    });
+
+    for (const skill of skills) {
+      const sourcePath = path.join(sourceSkillsDir, skill);
+      const targetPath = path.join(targetSkillsDir, skill);
+
+      this.copyDirRecursive(sourcePath, targetPath);
+      this.log(`Synced skill: ${skill}`);
+    }
+
+    // Also copy skills-index.json if it exists
+    const indexPath = path.join(sourceSkillsDir, 'skills-index.json');
+    if (fs.existsSync(indexPath)) {
+      fs.copyFileSync(indexPath, path.join(targetSkillsDir, 'skills-index.json'));
+      this.log('Synced skills-index.json');
+    }
+  }
+
+  /**
+   * Sync rules from .workflow/state/decisions.md to CLI-specific rules folder
+   */
+  syncRules() {
+    const rulesDir = path.join(this.projectDir, this.getRulesPath());
+
+    // Ensure rules directory exists
+    if (!fs.existsSync(rulesDir)) {
+      fs.mkdirSync(rulesDir, { recursive: true });
+    }
+
+    // Copy any existing rules from .workflow/rules/ if present
+    const sourceRulesDir = path.join(this.projectDir, this.workflowDir, 'rules');
+    if (fs.existsSync(sourceRulesDir)) {
+      const rules = fs.readdirSync(sourceRulesDir).filter(f => f.endsWith('.md'));
+      for (const rule of rules) {
+        fs.copyFileSync(
+          path.join(sourceRulesDir, rule),
+          path.join(rulesDir, rule)
+        );
+        this.log(`Synced rule: ${rule}`);
+      }
+    }
+  }
+
+  /**
+   * Sync knowledge files from .workflow/state/ to CLI-specific docs folder
+   * Also updates the knowledge-sync.json state
+   */
+  syncKnowledgeFiles() {
+    const stateDir = path.join(this.projectDir, this.workflowDir, 'state');
+    const cliDocsDir = path.join(this.projectDir, this.getCliFolder(), 'docs');
+
+    // Knowledge files to sync
+    const knowledgeFiles = ['stack.md', 'architecture.md', 'testing.md'];
+
+    // Ensure CLI docs directory exists
+    if (!fs.existsSync(cliDocsDir)) {
+      fs.mkdirSync(cliDocsDir, { recursive: true });
+    }
+
+    let syncedCount = 0;
+    for (const file of knowledgeFiles) {
+      const sourcePath = path.join(stateDir, file);
+      const targetPath = path.join(cliDocsDir, file);
+
+      if (fs.existsSync(sourcePath)) {
+        fs.copyFileSync(sourcePath, targetPath);
+        this.log(`Synced knowledge file: ${file}`);
+        syncedCount++;
+      }
+    }
+
+    // Update knowledge-sync.json after bridge sync
+    if (syncedCount > 0) {
+      try {
+        const knowledgeSync = require('../../scripts/flow-knowledge-sync');
+        knowledgeSync.markAsSynced();
+        this.log('Updated knowledge-sync.json');
+      } catch (err) {
+        // flow-knowledge-sync not available
+        this.log(`Could not update knowledge-sync state: ${err.message}`);
+      }
+    }
+
+    return syncedCount;
+  }
+
+  /**
+   * Generate and write the main rules file (e.g., CLAUDE.md)
+   */
+  generateRulesFile() {
+    const config = this.readConfig();
+    const content = this.generateRulesContent(config);
+    const rulesFilePath = path.join(this.projectDir, this.getRulesFileName());
+
+    fs.writeFileSync(rulesFilePath, content, 'utf-8');
+    this.log(`Generated ${this.getRulesFileName()}`);
+  }
+
+  /**
+   * Run full sync: skills, rules, and CLI-specific setup
+   * @returns {Object} Sync result summary
+   */
+  async sync() {
+    const startTime = Date.now();
+    const results = {
+      cliType: this.cliType,
+      cliFolder: this.getCliFolder(),
+      synced: [],
+      errors: []
+    };
+
+    try {
+      // 1. Ensure CLI folder exists
+      this.ensureCliFolder();
+      results.synced.push('cli-folder');
+
+      // 2. Sync skills
+      try {
+        this.syncSkills();
+        results.synced.push('skills');
+      } catch (err) {
+        results.errors.push({ step: 'skills', error: err.message });
+      }
+
+      // 3. Sync rules
+      try {
+        this.syncRules();
+        results.synced.push('rules');
+      } catch (err) {
+        results.errors.push({ step: 'rules', error: err.message });
+      }
+
+      // 4. Sync knowledge files (stack.md, architecture.md, testing.md)
+      try {
+        const syncedCount = this.syncKnowledgeFiles();
+        if (syncedCount > 0) {
+          results.synced.push('knowledge-files');
+        }
+      } catch (err) {
+        results.errors.push({ step: 'knowledge-files', error: err.message });
+      }
+
+      // 5. Generate rules file
+      try {
+        this.generateRulesFile();
+        results.synced.push('rules-file');
+      } catch (err) {
+        results.errors.push({ step: 'rules-file', error: err.message });
+      }
+
+      // 6. CLI-specific setup
+      try {
+        const config = this.readConfig();
+        await this.setupCliSpecific(config);
+        results.synced.push('cli-specific');
+      } catch (err) {
+        results.errors.push({ step: 'cli-specific', error: err.message });
+      }
+
+    } catch (err) {
+      results.errors.push({ step: 'general', error: err.message });
+    }
+
+    results.duration = Date.now() - startTime;
+    results.success = results.errors.length === 0;
+
+    return results;
+  }
+
+  // ==================== Utility Methods ====================
+
+  /**
+   * Copy a directory recursively
+   */
+  copyDirRecursive(source, target) {
+    if (!fs.existsSync(target)) {
+      fs.mkdirSync(target, { recursive: true });
+    }
+
+    const items = fs.readdirSync(source);
+    for (const item of items) {
+      const sourcePath = path.join(source, item);
+      const targetPath = path.join(target, item);
+
+      if (fs.statSync(sourcePath).isDirectory()) {
+        this.copyDirRecursive(sourcePath, targetPath);
+      } else {
+        fs.copyFileSync(sourcePath, targetPath);
+      }
+    }
+  }
+
+  /**
+   * Log a message (if verbose mode is on)
+   */
+  log(message) {
+    if (this.verbose) {
+      console.log(`[${this.cliType}] ${message}`);
+    }
+  }
+}
+
+module.exports = BaseBridge;