claude-flow-novice 1.5.5 → 1.5.7

package/.claude-flow-novice/.claude/agents/CLAUDE.md

@@ -114,6 +114,28 @@ Priming Effect:
 
 ### Frontmatter (YAML)
 
+#### Required Frontmatter Fields
+
+- **name**: Lowercase with hyphens (e.g., `system-architect`, `api-developer`)
+- **description**: Clear, keyword-rich description (supports multiline with `|`)
+- **tools**: Comma-separated list of tool names (e.g., `Read, Write, Edit, Bash, Grep, Glob`)
+  - ⚠️ **IMPORTANT**: Use comma-separated format, NOT YAML array format
+  - ✅ **CORRECT**: `tools: Read, Write, Edit, Bash`
+  - ❌ **WRONG**: `tools:` followed by `- Read` on new lines
+- **model**: AI model to use (`sonnet`, `opus`, or `haiku`)
+- **color**: Visual identifier for the agent (e.g., `seagreen`, `royalblue`)
+
+#### Optional Frontmatter Fields
+
+- **type**: Agent classification (`specialist`, `coordinator`, `swarm`)
+- **capabilities**: YAML array of capability tags
+- **lifecycle**: Hooks for agent lifecycle events
+- **hooks**: Integration points with Claude Flow system
+- **triggers**: Automatic activation patterns (YAML array)
+- **constraints**: Limitations and boundaries (YAML array)
+
+#### Complete Frontmatter Example
+
 ```yaml
 ---
 name: agent-name                    # REQUIRED: Lowercase with hyphens
@@ -122,12 +144,7 @@ description: |                      # REQUIRED: Clear, keyword-rich description
   Use PROACTIVELY for [specific scenarios].
   ALWAYS delegate when user asks [trigger phrases].
   Keywords - [comma-separated keywords for search]
-tools:                              # REQUIRED: Array of tool names
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - TodoWrite
+tools: Read, Write, Edit, Bash, TodoWrite  # REQUIRED: Comma-separated list of tool names
 model: sonnet                       # REQUIRED: sonnet | opus | haiku
 color: seagreen                     # REQUIRED: Visual identifier
 type: specialist                    # OPTIONAL: specialist | coordinator | swarm
@@ -212,7 +229,7 @@ npx claude-flow@alpha hooks post-edit [FILE_PATH] --memory-key "agent/step" --st
 ---
 name: system-architect
 description: Expert in designing scalable systems
-tools: [Read, Write, Edit, Bash, TodoWrite]
+tools: Read, Write, Edit, Bash, TodoWrite
 model: sonnet
 color: seagreen
 ---
@@ -281,7 +298,7 @@ You are a senior system architect specializing in [domain]. You excel at [key st
 ---
 name: backend-api-dev
 description: Backend API development specialist
-tools: [Read, Write, Edit, Bash, Grep, Glob, TodoWrite]
+tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite
 model: sonnet
 color: royalblue
 ---
@@ -419,7 +436,7 @@ Test Pyramid:
 ---
 name: rust-coder-basic
 description: Rust implementation specialist for basic tasks
-tools: [Read, Write, Edit, Bash, Grep, Glob, TodoWrite]
+tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite
 model: sonnet
 color: mediumblue
 ---
@@ -839,7 +856,7 @@ Apply same principles but validate with testing:
 ---
 name: code-reviewer
 description: Expert code reviewer focusing on quality and maintainability
-tools: [Read, Grep, Bash]
+tools: Read, Grep, Bash
 model: sonnet
 color: orange
 ---
@@ -902,7 +919,7 @@ You are an experienced code reviewer who identifies issues and suggests improvem
 ---
 name: system-architect
 description: Senior system architect for scalable software design
-tools: [Read, Write, Edit, Bash, TodoWrite]
+tools: Read, Write, Edit, Bash, TodoWrite
 model: sonnet
 color: seagreen
 ---
@@ -956,7 +973,7 @@ You are a senior system architect specializing in [domain].
 ---
 name: unit-tester
 description: Comprehensive unit test specialist
-tools: [Read, Write, Edit, Bash, Grep, TodoWrite]
+tools: Read, Write, Edit, Bash, Grep, TodoWrite
 model: sonnet
 color: mediumvioletred
 ---
@@ -1052,7 +1069,7 @@ Test Categories:
 ---
 name: tech-researcher
 description: Technology research and analysis specialist
-tools: [Read, WebSearch, Bash, TodoWrite]
+tools: Read, WebSearch, Bash, TodoWrite
 model: sonnet
 color: steelblue
 ---
@@ -1103,7 +1120,7 @@ You conduct thorough research to inform technical decisions.
 ---
 name: cicd-engineer
 description: CI/CD pipeline specialist
-tools: [Read, Write, Edit, Bash, Grep, Glob, TodoWrite]
+tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite
 model: sonnet
 color: darkkhaki
 ---
@@ -1566,7 +1583,7 @@ description: |
   Use PROACTIVELY for distributed systems, event-driven architecture,
   microservices decomposition, scalability planning.
   Keywords - architecture, system design, microservices, scalability
-tools: [Read, Write, Edit, Bash, Grep, Glob, TodoWrite]
+tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite
 model: sonnet
 color: seagreen
 ---
@@ -1636,7 +1653,7 @@ description: |
   Backend API development specialist for RESTful and GraphQL APIs.
   Use for endpoint implementation, data modeling, API documentation.
   Keywords - API, REST, GraphQL, backend, endpoints
-tools: [Read, Write, Edit, Bash, Grep, Glob, TodoWrite]
+tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite
 model: sonnet
 color: royalblue
 ---
@@ -1786,7 +1803,7 @@ description: |
   Rust implementation specialist for basic string processing,
   error handling, and CRUD operations.
   Keywords - rust, basic tasks, string processing, error handling
-tools: [Read, Write, Edit, Bash, Grep, Glob, TodoWrite]
+tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite
 model: sonnet
 color: mediumblue
 ---

package/.claude-flow-novice/.claude/agents/README-VALIDATION.md

@@ -0,0 +1,243 @@
+# Agent Profile Validation Tool
+
+A comprehensive validation script that checks agent profiles against CLAUDE.md standards and provides actionable feedback.
+
+## Usage
+
+### Validate a single agent
+
+```bash
+node validate-agent.js path/to/agent.md
+```
+
+**Example:**
+
+```bash
+node validate-agent.js coder.md
+node validate-agent.js benchmarking-tests/test-agent-minimal.md
+node validate-agent.js architecture/system-architect.md
+```
+
+### Validate all agents
+
+```bash
+node validate-agent.js --all
+```
+
+This will:
+- Recursively find all `.md` files in the agents directory
+- Validate each agent profile
+- Generate summary statistics
+- Show top performers and agents needing improvement
+
+## What it Validates
+
+### 1. Frontmatter Structure
+
+- Required fields: `name`, `description`, `tools`, `model`, `color`
+- Tools from approved list: `Read, Write, Edit, MultiEdit, Bash, Glob, Grep, TodoWrite`
+- Valid model names: `sonnet, haiku, opus, sonnet-3-5, sonnet-4-5`
+- Color format: Named colors, hex (`#FF9800`), or RGB (`rgb(255, 152, 0)`)
+
+### 2. Format Classification
+
+Automatically detects agent format based on content analysis:
+
+- **MINIMAL** (200-400 lines): Complex tasks requiring reasoning
+- **METADATA** (400-700 lines): Medium complexity with structured workflows
+- **CODE-HEAVY** (700-1200 lines): Basic tasks benefiting from examples
+
+### 3. Complexity Analysis
+
+Analyzes task complexity based on keywords:
+
+- **Basic**: String processing, parsing, CRUD operations
+- **Medium**: Multi-component integration, refactoring, pipelines
+- **Complex**: Architecture, distributed systems, design trade-offs
+
+### 4. Format Alignment
+
+Checks if the current format aligns with best practices for the detected complexity:
+
+- Basic tasks → CODE-HEAVY format (+43% quality boost validated)
+- Medium tasks → METADATA format (balanced approach)
+- Complex tasks → MINIMAL format (avoid over-constraining)
+
+### 5. Quality Checks
+
+- Clear role definition in opening paragraph
+- Specific responsibilities section
+- Appropriate use of negative instructions
+- Anti-pattern detection
+
+## Output Example
+
+```
+════════════════════════════════════════════════════════════════════════════════
+AGENT VALIDATION REPORT: coder.md
+════════════════════════════════════════════════════════════════════════════════
+
+SUMMARY
+────────────────────────────────────────────────────────────────────────────────
+Agent Profile Status: Excellent (100/100)
+✅ Format aligned with best practices (metadata)
+
+FORMAT ANALYSIS
+────────────────────────────────────────────────────────────────────────────────
+Detected Format: METADATA
+Confidence: 60%
+Estimated Tokens: ~1000
+Word Count: 1215
+
+Characteristics:
+  • codeBlocks: 1
+  • verbosity: medium
+
+COMPLEXITY ANALYSIS
+────────────────────────────────────────────────────────────────────────────────
+Estimated Complexity: MEDIUM
+Confidence: HIGH
+Indicator Scores:
+  • basic: 2.0
+  • medium: 3.5
+  • complex: 3.0
+
+FORMAT RECOMMENDATION
+────────────────────────────────────────────────────────────────────────────────
+Current Format: METADATA
+Recommended Format: METADATA
+Alignment: ✅ ALIGNED
+Confidence: MEDIUM
+Reason: Medium complexity benefits from structure without over-constraining
+Evidence: Hypothesized from validated coder agent patterns
+
+════════════════════════════════════════════════════════════════════════════════
+Compliance Score: 100/100
+════════════════════════════════════════════════════════════════════════════════
+```
+
+## Compliance Scoring
+
+The script calculates a compliance score (0-100) based on:
+
+- **Critical Issues** (-20 points each): Missing required fields, invalid values
+- **Warnings** (-5 points each): Recommended improvements
+- **Recommendations** (-2 points each): Quality enhancement suggestions
+
+### Score Interpretation
+
+- **90-100**: Excellent - Production ready
+- **75-89**: Good - Minor improvements recommended
+- **60-74**: Fair - Several issues to address
+- **<60**: Needs Improvement - Significant work required
+
+## Exit Codes
+
+- **0**: Agent is valid (no critical issues)
+- **1**: Agent has critical issues or validation errors
+
+## Integration with CI/CD
+
+You can use this script in your CI/CD pipeline:
+
+```yaml
+# .github/workflows/validate-agents.yml
+name: Validate Agents
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+      - run: cd .claude/agents && node validate-agent.js --all
+```
+
+## Programmatic Usage
+
+You can also import and use the validation functions:
+
+```javascript
+import { validateAgent, classifyFormat, estimateComplexity, recommendFormat } from './validate-agent.js';
+
+// Validate a single agent
+const result = await validateAgent('/path/to/agent.md');
+console.log(`Valid: ${result.valid}`);
+console.log(`Score: ${result.complianceScore}/100`);
+console.log(`Format: ${result.format.classification.format}`);
+
+// Classify format
+const format = classifyFormat(content, frontmatter);
+console.log(`Detected format: ${format.format}`);
+
+// Estimate complexity
+const complexity = estimateComplexity(frontmatter, content);
+console.log(`Complexity: ${complexity.complexity}`);
+
+// Get format recommendation
+const recommendation = recommendFormat('coder', 'basic');
+console.log(`Recommended: ${recommendation.recommended}`);
+```
+
+## Best Practices
+
+1. **Run validation before committing** new or updated agent profiles
+2. **Aim for 90+ score** for production agents
+3. **Address critical issues immediately** - they block deployment
+4. **Consider recommendations** - they improve agent effectiveness
+5. **Re-validate periodically** as CLAUDE.md standards evolve
+
+## Troubleshooting
+
+### "No frontmatter found"
+
+Ensure your agent file starts with:
+
+```markdown
+---
+name: agent-name
+description: Agent description
+tools: Read, Write, Edit
+model: sonnet
+color: blue
+---
+
+# Agent Name
+...
+```
+
+### "Invalid YAML syntax"
+
+Check for:
+- Proper indentation (use spaces, not tabs)
+- Quoted strings containing special characters
+- Balanced brackets and quotes
+- No duplicate keys
+
+### "Format mismatch"
+
+The validator detected your agent format doesn't match the recommended format for the task complexity. Consider:
+
+- Is the agent truly for basic/medium/complex tasks?
+- Does the format align with empirical findings?
+- Should you add/remove examples or structure?
+
+## Future Enhancements
+
+- Integration with Claude Flow hooks
+- Automated fix suggestions
+- Performance benchmarking integration
+- Format conversion tools
+- Custom rule definitions
+
+## Support
+
+For issues or suggestions, please file an issue in the project repository.
+
+## License
+
+This validation tool is part of the Claude Flow project.

package/.claude-flow-novice/.claude/agents/validate-agent.js

@@ -357,6 +357,12 @@ function validateFrontmatter(frontmatter) {
   }
 
   // Tools validation
+  // NOTE: Tools can be specified as comma-separated string OR YAML array
+  // Examples:
+  //   tools: Read, Write, Edit          # Comma-separated string
+  //   tools:                             # YAML array
+  //     - Read
+  //     - Write
   if (!frontmatter.tools) {
     warnings.push({
       severity: 'warning',
@@ -365,9 +371,24 @@ function validateFrontmatter(frontmatter) {
       fix: 'Add "tools: Read, Write, Edit, ..." to frontmatter'
     });
   } else {
-    const tools = typeof frontmatter.tools === 'string'
-      ? frontmatter.tools.split(',').map(t => t.trim())
-      : frontmatter.tools;
+    // Parse tools: handle both comma-separated strings and YAML arrays
+    let tools;
+    if (typeof frontmatter.tools === 'string') {
+      // Comma-separated format: "Read, Write, Edit"
+      tools = frontmatter.tools.split(',').map(t => t.trim());
+    } else if (Array.isArray(frontmatter.tools)) {
+      // YAML array format: ["Read", "Write", "Edit"]
+      tools = frontmatter.tools;
+    } else {
+      // Invalid format
+      issues.push({
+        severity: 'error',
+        field: 'tools',
+        message: 'Tools must be comma-separated string or YAML array',
+        fix: 'Use "tools: Read, Write, Edit" or YAML array format'
+      });
+      tools = [];
+    }
 
     const invalidTools = tools.filter(tool => !APPROVED_TOOLS.includes(tool));
     if (invalidTools.length > 0) {

package/.claude-flow-novice/dist/src/cli/simple-commands/init/index.js

@@ -44,8 +44,6 @@ import { createLocalExecutable } from './executable-wrapper.js';
 import { createSparcStructureManually } from './sparc-structure.js';
 import { createClaudeSlashCommands } from './claude-commands/slash-commands.js';
 import { createOptimizedClaudeSlashCommands } from './claude-commands/optimized-slash-commands.js';
-// execSync imported above as execSyncOriginal\nconst execSync = execSyncOriginal;
-import { promises as fs } from 'fs';
 import { copyTemplates } from './template-copier.js';
 import { copyRevisedTemplates, validateTemplatesExist } from './copy-revised-templates.js';
 import {