sf-agent-framework

# Document Folder Management Utility This utility provides automated document folder structure creation and management for Salesforce workflows, ensuring consistent organization across all projects. ## Purpose Automatically creates and maintains a standardized folder structure when workflows start, based on the agents and roles involved in the workflow. ## Core Functionality ### 1. Folder Structure Detection When a workflow starts, this utility: - Checks for the existence of `docs/` directory - Scans for expected subfolders based on workflow agents - Identifies missing folders - Creates any missing folders automatically ### 2. Role-Based Folder Templates Each agent role has associated document folders: ```yaml folder-structures: # Core Management Folders orchestrator: - project-planning/ - project-planning/roadmaps/ - project-planning/timelines/ - release-management/ - release-management/deployment-runbooks/ - quality-reports/ - quality-reports/test-results/ - quality-reports/coverage-reports/ # Business Analysis Folders analyst: - requirements/ - requirements/functional/ - requirements/non-functional/ - requirements/user-stories/ - process-documentation/ - process-documentation/as-is/ - process-documentation/to-be/ - gap-analysis/ # Product Management Folders pm: - prd/ - prd/epics/ - prd/features/ - product-roadmap/ - release-notes/ - stakeholder-communications/ # Architecture Folders architect: - architecture/ - architecture/solution-design/ - architecture/data-models/ - architecture/integration-patterns/ - architecture/security-design/ - architecture/decisions/ - technical-specifications/ # Development Folders developer: - development/ - development/code-documentation/ - development/api-specifications/ - development/component-diagrams/ - development/deployment-packages/ # Quality Assurance Folders qa: - quality-assurance/ - quality-assurance/test-plans/ - quality-assurance/test-cases/ - quality-assurance/test-results/ - quality-assurance/bug-reports/ - quality-assurance/performance-reports/ # Security Folders security: - security/ - security/assessments/ - security/compliance-reports/ - security/vulnerability-scans/ - security/access-reviews/ - security/policies/ # DevOps Folders devops: - devops/ - devops/pipeline-configs/ - devops/deployment-scripts/ - devops/environment-configs/ - devops/monitoring-dashboards/ - devops/runbooks/ # Data Architecture Folders data-architect: - data-architecture/ - data-architecture/data-models/ - data-architecture/migration-plans/ - data-architecture/data-quality-reports/ - data-architecture/etl-documentation/ # Integration Folders integration-architect: - integration/ - integration/api-contracts/ - integration/middleware-configs/ - integration/event-schemas/ - integration/error-handling/ # Specialized Folders omnistudio-architect: - omnistudio/ - omnistudio/omniscript-designs/ - omnistudio/flexcard-specifications/ - omnistudio/dataraptor-mappings/ - omnistudio/integration-procedures/ # Governance Folders coe-director: - governance/ - governance/standards/ - governance/policies/ - governance/best-practices/ - governance/training-materials/ - governance/metrics-dashboards/ ``` ### 3. Workflow-Based Folder Creation Different workflows create different folder combinations: ```yaml workflow-folders: salesforce-greenfield-fullstack: include-roles: - orchestrator - analyst - pm - architect - developer - qa - security - devops additional-folders: - project-templates/ - reference-architecture/ salesforce-brownfield-enhancement: include-roles: - analyst - architect - developer - qa additional-folders: - existing-system-analysis/ - change-impact-analysis/ salesforce-data-migration: include-roles: - data-architect - analyst - qa - devops additional-folders: - data-mapping/ - migration-scripts/ - validation-reports/ salesforce-devops-cicd: include-roles: - devops - security - qa additional-folders: - automation-scripts/ - environment-provisioning/ ``` ## Implementation ### 1. Folder Creation Function ```javascript function ensureDocumentFolders(workflowId, agentRoles) { const baseDocsPath = './docs'; // Ensure base docs directory exists if (!fs.existsSync(baseDocsPath)) { fs.mkdirSync(baseDocsPath, { recursive: true }); console.log('Created docs/ directory'); } // Get folders for workflow const workflowConfig = workflowFolders[workflowId]; const foldersToCreate = new Set(); // Add role-based folders if (workflowConfig && workflowConfig['include-roles']) { workflowConfig['include-roles'].forEach((role) => { const roleFolders = folderStructures[role] || []; roleFolders.forEach((folder) => foldersToCreate.add(folder)); }); } // Add workflow-specific folders if (workflowConfig && workflowConfig['additional-folders']) { workflowConfig['additional-folders'].forEach((folder) => { foldersToCreate.add(folder); }); } // Create missing folders let createdCount = 0; foldersToCreate.forEach((folder) => { const fullPath = path.join(baseDocsPath, folder); if (!fs.existsSync(fullPath)) { fs.mkdirSync(fullPath, { recursive: true }); createdCount++; } }); return { totalFolders: foldersToCreate.size, createdFolders: createdCount, existingFolders: foldersToCreate.size - createdCount, }; } ``` ### 2. Workflow Integration When a workflow starts: ```javascript // In workflow initialization function initializeWorkflow(workflowId, context) { // Existing workflow init code... // Ensure document folders exist const agents = getWorkflowAgents(workflowId); const folderResult = ensureDocumentFolders(workflowId, agents); console.log(`Document folders initialized:`); console.log(`- ${folderResult.existingFolders} folders already existed`); console.log(`- ${folderResult.createdFolders} folders created`); console.log(`- Total: ${folderResult.totalFolders} folders ready`); // Continue with workflow... } ``` ### 3. Agent Activation Integration When an agent is activated within a workflow: ```javascript // In agent activation function activateAgent(agentId, workflowContext) { // Check if this agent needs specific folders const agentRole = getAgentRole(agentId); const agentFolders = folderStructures[agentRole] || []; // Ensure agent-specific folders exist agentFolders.forEach((folder) => { const fullPath = path.join('./docs', folder); if (!fs.existsSync(fullPath)) { fs.mkdirSync(fullPath, { recursive: true }); console.log(`Created missing folder for ${agentId}: ${folder}`); } }); // Continue with agent activation... } ``` ## Usage Examples ### 1. Manual Folder Creation Agents can manually trigger folder creation: ```bash # From any agent *ensure-folders # Output: Checking document folder structure... ✓ docs/ exists ✓ docs/prd/ exists ✗ docs/architecture/ missing - creating... ✓ docs/architecture/ created ✓ docs/architecture/solution-design/ created ... All required folders are now in place! ``` ### 2. Workflow-Triggered Creation When starting a greenfield project: ```bash @sf-orchestrator *workflow salesforce-greenfield-fullstack # Output: Starting Salesforce Greenfield Full-Stack workflow... Initializing document structure... Created 45 folders in docs/ Document structure ready for project artifacts! ``` ### 3. Role-Specific Creation When a specific agent joins mid-workflow: ```bash @sf-security # Automatic folder check on activation Checking security documentation folders... Created: docs/security/assessments/ Created: docs/security/compliance-reports/ Security folders initialized. ``` ## Best Practices ### 1. Folder Naming Conventions - Use lowercase with hyphens: `test-results/` - Be descriptive but concise: `api-specifications/` - Include role prefix for clarity: `qa-test-results/` - Use consistent patterns across roles ### 2. Folder Organization - Group by function, not by time - Create subfolders for large categories - Keep depth reasonable (max 3 levels) - Use README files in each folder ### 3. Content Guidelines Each folder should contain: - README.md explaining folder purpose - Template files for common documents - Index or catalog of contents - Clear naming conventions ### 4. Maintenance - Regular cleanup of outdated content - Archive completed project docs - Update folder structures as needed - Document any custom folders ## Integration Points ### 1. With create-doc Task The create-doc task automatically saves to appropriate folders: ```javascript // When creating a document function saveDocument(docType, content) { const targetFolder = getDocumentFolder(docType); ensureFolderExists(targetFolder); // Save document... } ``` ### 2. With Workflow Management Workflows can specify custom folder requirements: ```yaml workflow: custom-folders: - custom-analysis/ - vendor-documentation/ - compliance-artifacts/ ``` ### 3. With Agent Handoffs Context includes folder locations: ```javascript handoffContext.folders = { requirements: './docs/requirements/', testPlans: './docs/quality-assurance/test-plans/', deploymentDocs: './docs/devops/deployment-scripts/', }; ``` ## Error Handling ### Permission Issues ```javascript try { fs.mkdirSync(folderPath, { recursive: true }); } catch (error) { if (error.code === 'EACCES') { console.error(`Permission denied: Cannot create ${folderPath}`); console.error('Please check folder permissions or run with appropriate access'); } } ``` ### Path Validation ```javascript function validatePath(folderPath) { // Prevent directory traversal const normalized = path.normalize(folderPath); if (normalized.includes('..')) { throw new Error('Invalid path: Directory traversal not allowed'); } return normalized; } ``` This utility ensures consistent, organized documentation across all Salesforce projects while reducing manual setup overhead.