Component Validation & Remediation Workflow

Version: 1.0.0 Date: December 3, 2025 Status: Active Purpose: Define multi-agent orchestration for systematic component validation and CODITECT standards compliance

---

Executive Summary

This document defines the 5-agent workflow for validating and remediating all 271 CODITECT components against Phase 1-3 standards. Each component progresses through Analysis → Validation → Gap Analysis → Fix → QA Review with automated grading and structured documentation.

Key Principles:

• One component at a time - Sequential processing with full workflow per component
• Multi-agent orchestration - Specialized agents for each workflow stage
• Automated validation - Script-based grading with manual review checkpoints
• Structured documentation - Standardized reports for each stage
• Git-tracked progress - Atomic commits with conventional commit messages

Workflow Duration: 30-45 minutes per component (avg), 271 components = 135-204 hours total

---

Table of Contents

1. Workflow Overview
2. Agent Roles & Responsibilities
3. Stage 1: Analysis
4. Stage 2: Validation
5. Stage 3: Gap Analysis
6. Stage 4: Fix Application
7. Stage 5: QA Review
8. Workflow Execution
9. Progress Tracking
10. Quality Gates

---

1. Workflow Overview

1.1 Five-Stage Process

Component (271 total)
    ↓
[Stage 1: Analysis Agent]
    ├─ Reads component file
    ├─ Reads applicable standard
    ├─ Identifies current state
    └─ Produces: Analysis Report
    ↓
[Stage 2: Validation Agent]
    ├─ Runs validation script
    ├─ Applies grading rubric
    ├─ Calculates score (0-100)
    └─ Produces: Validation Report (Grade A-F)
    ↓
[Stage 3: Gap Analysis Agent]
    ├─ Compares current vs standard
    ├─ Identifies specific gaps
    ├─ Prioritizes fixes (P1/P2/P3)
    └─ Produces: Gap Report with fix recommendations
    ↓
[Stage 4: Fix Agent]
    ├─ Applies automated fixes
    ├─ Generates manual fix instructions
    ├─ Updates component file
    └─ Produces: Fixed Component + Change Log
    ↓
[Stage 5: QA Review Agent]
    ├─ Re-runs validation script
    ├─ Verifies grade improvement
    ├─ Checks no regressions
    └─ Produces: QA Report + Approval/Reject
    ↓
[Git Commit]
    ├─ Conventional commit message
    ├─ Links to reports
    └─ Updates TASKLIST progress

1.2 Success Criteria Per Component

Entry Criteria:

• Component exists in repository
• Applicable standard published
• Validation script supports component type

Exit Criteria:

• Grade B (80%+) achieved OR documented exception
• QA Review approved
• Changes committed to git
• TASKLIST updated with completion checkbox

Duration Targets:

• Critical fixes (F→C): 20-30 minutes
• Important fixes (C→B): 15-20 minutes
• Optional fixes (B→A): 30-45 minutes

---

2. Agent Roles & Responsibilities

2.1 Analysis Agent (Stage 1)

Agent Type: codebase-analyzer Primary Role: Deep understanding of component implementation and standards requirements

Responsibilities:

1. Read and parse component file
2. Read applicable CODITECT standard document
3. Identify component structure and organization
4. Document current state (what exists)
5. Highlight compliant sections
6. Note missing/incomplete sections
7. Estimate initial grade (A-F)

Deliverable: Analysis Report

Report Structure:

## Analysis Report: [Component Name]

### Current State
- File: [path]
- Type: [agent/skill/command/hook/script/config]
- Size: [KB]
- Structure: [description]

### What's Compliant ✅
- [List compliant aspects with scores]

### What's Missing ❌
- [List missing requirements]

### Initial Grade Estimate
- Score: [X/100]
- Grade: [A/B/C/D/F]
- Reasoning: [explanation]

Task Invocation:

Task(
    subagent_type="codebase-analyzer",
    description="Analyze [component] for standards compliance",
    prompt=f"""Analyze the component at {component_path} against {standard_path}.

    Provide detailed analysis:
    - Current state (what exists)
    - What's compliant
    - What's missing
    - Grade estimate (A-F)
    - Specific gaps to fix

    Format response as structured Analysis Report."""
)

2.2 Validation Agent (Stage 2)

Agent Type: Bash execution of validation script Primary Role: Automated, objective grading using validation script

Responsibilities:

1. Execute scripts/validate-components.py for component
2. Apply standard-specific grading rubric
3. Calculate numeric score (0-100)
4. Assign letter grade (A-F)
5. Generate compliance metrics
6. Document check results (pass/fail per criterion)

Deliverable: Validation Report (JSON + Summary)

Report Structure:

{
  "file": "component-name.md",
  "path": "/full/path/to/component",
  "type": "agent|skill|command|hook|script|config",
  "checks": {
    "yaml_frontmatter": true|false,
    "required_fields": true|false,
    "documentation_quality": true|false,
    "structure": true|false,
    ...
  },
  "score": 74.5,
  "grade": "C",
  "points": "74.5/100",
  "compliance_rate": 74.5
}

Bash Invocation:

python3 scripts/validate-components.py \
  --type [agent|skill|command|hook|script|config] \
  --file [component-path] \
  --output validation-report-[component-name].json \
  --detailed

2.3 Gap Analysis Agent (Stage 3)

Agent Type: codebase-analyzer or specialized gap-analysis agent Primary Role: Synthesize analysis and validation into actionable fix plan

Responsibilities:

1. Review Analysis Report (Stage 1)
2. Review Validation Report (Stage 2)
3. Identify specific gaps preventing Grade B (80%+)
4. Prioritize fixes (P1: Critical, P2: Important, P3: Optional)
5. Generate fix recommendations with examples
6. Estimate fix duration
7. Provide path to Grade B and Grade A

Deliverable: Gap Report with Fix Plan

Report Structure:

## Gap Report: [Component Name]

### Current Status
- Grade: [C (74%)]
- Compliant: No (needs 80%+ for Grade B)

### Critical Gaps (P1)
1. **Missing YAML frontmatter** (−20 points)
   - Fix: Add YAML block with name, description, tools
   - Example: [code snippet]
   - Duration: 5 minutes

2. **Missing Integration section** (−15 points)
   - Fix: Add Integration section with agent invocation
   - Example: [code snippet]
   - Duration: 10 minutes

### Path to Grade B (80%+)
- Current: 74%
- Target: 80%
- Gap: 6 points
- Required fixes: #1, #2 (P1 only)
- Estimated duration: 15 minutes

### Path to Grade A (90%+)
- Additional fixes: #3, #4 (P2)
- Additional duration: 20 minutes
- Total to A: 35 minutes

Task Invocation:

Task(
    subagent_type="codebase-analyzer",
    description="Gap analysis for [component]",
    prompt=f"""Synthesize Analysis Report and Validation Report for {component_name}.

    Identify:
    - Specific gaps preventing Grade B (80%+)
    - Priority ranking (P1/P2/P3)
    - Fix recommendations with examples
    - Duration estimates
    - Path to Grade B and Grade A

    Format response as structured Gap Report."""
)

2.4 Fix Agent (Stage 4)

Agent Type: Edit tool + manual instructions Primary Role: Apply fixes to component file based on Gap Report

Responsibilities:

1. Review Gap Report fix recommendations
2. Apply automated fixes using Edit tool
3. Generate manual fix instructions for complex changes
4. Validate syntax after changes
5. Create before/after comparison
6. Document all changes in Change Log

Deliverable: Fixed Component + Change Log

Change Log Structure:

## Change Log: [Component Name]

### Summary
- Grade Before: C (74%)
- Grade After: B (87%) [estimated]
- Fixes Applied: 3
- Duration: 18 minutes

### Changes Applied

**Change 1: Add YAML frontmatter**
- Type: Automated (Edit tool)
- Lines: 1-4 replaced with 1-9
- Before:
  ```yaml
  ---
  name: component
  ---

• After:

  ---
  name: component
  description: Full description
  version: 1.0.0
  tools: [Read, Write, Edit]
  model: sonnet
  ---

Change 2: Add Integration section

• Type: Manual + Edit tool
• Lines: Insert after line 45
• Content: [full section added]

Manual Steps Required

[None] or [List any complex changes requiring human review]

**Execution:**
```python
# Automated fixes
Edit(
    file_path=component_path,
    old_string="[existing content]",
    new_string="[fixed content]"
)

# Manual instructions (complex changes)
print("""
MANUAL FIX REQUIRED:
1. Review section X for [issue]
2. Apply pattern [example]
3. Verify [criterion]
""")

2.5 QA Review Agent (Stage 5)

Agent Type: qa-reviewer or validation re-run Primary Role: Verify fixes meet standards and no regressions introduced

Responsibilities:

1. Re-run validation script on fixed component
2. Verify grade improvement (should reach Grade B or better)
3. Check for regressions (no new violations)
4. Validate syntax and structure
5. Spot-check manual review (10% random sample)
6. Approve or reject with detailed reasoning

Deliverable: QA Report with Approval/Rejection

Report Structure:

## QA Report: [Component Name]

### Validation Results
- Grade Before: C (74%)
- Grade After: B (87%)
- Improvement: +13 points ✅
- Target Met: Yes (≥80% required)

### Regression Check
- New violations: 0 ✅
- Existing violations resolved: 3 ✅
- Unchanged violations: 0

### Manual Review (if applicable)
- Reviewed: [section]
- Issues found: None
- Recommendation: Approve

### Decision: **APPROVED ✅**
- Rationale: Meets Grade B standard (87%), no regressions
- Next steps: Commit changes and update TASKLIST

Task Invocation:

# Re-run validation
result = subprocess.run([
    "python3", "scripts/validate-components.py",
    "--type", component_type,
    "--file", component_path,
    "--output", f"qa-validation-{component_name}.json"
])

# Compare before/after
original_grade = validation_report_before["grade"]
new_grade = validation_report_after["grade"]

if new_grade in ["A", "B"] and new_grade >= original_grade:
    approval = "APPROVED"
else:
    approval = "REJECTED - revert and retry"

---

3. Stage 1: Analysis

3.1 Analysis Process

Input:

• Component file path
• Applicable standard document
• Component type

Process:

1. Read component file completely
2. Read applicable standard (e.g., CODITECT-STANDARD-AGENTS.md)
3. Identify structure and organization
4. Compare current state vs standard requirements
5. Document compliant sections
6. Document missing/incomplete sections
7. Estimate grade based on observations

Output:

• Analysis Report (markdown)
• Initial grade estimate
• List of gaps

3.2 Analysis Checklist

For All Components:

• Component file exists and readable
• File encoding is UTF-8
• File size reasonable (<100 KB)
• Markdown or code syntax valid

For Agents:

• YAML frontmatter present
• Required fields: name, description, tools
• Optional fields: model, version, tags
• Documentation sections present
• Examples provided

For Skills:

• YAML frontmatter present (MANDATORY)
• Progressive disclosure structure (3 levels)
• Token count <5000
• allowed-tools specified

For Commands:

• YAML frontmatter present
• Uses $ARGUMENTS placeholder
• Description provided
• Examples section present

For Hooks:

• Shebang present
• Error handling implemented
• Reads stdin
• Documentation comments
• Executable permissions

For Scripts:

• Shebang present
• Docstring/header comments
• Error handling
• CLI argument parsing
• Executable permissions

For Configurations:

• Valid JSON
• Has permissions section
• Permissions structure correct
• Has hooks or MCP servers

---

4. Stage 2: Validation

4.1 Validation Process

Input:

• Component file path
• Component type

Process:

1. Execute validation script
2. Apply component-type-specific grading rubric
3. Run all checks (see validation criteria)
4. Calculate numeric score
5. Assign letter grade
6. Generate detailed report

Output:

• Validation Report (JSON)
• Grade (A-F)
• Score (0-100)
• Check results (pass/fail)

4.2 Grading Rubrics

Agents (100 points total):

• YAML frontmatter (40 points)
• Description quality (15 points)
• Documentation structure (15 points)
• File size/encoding (10 points)
• Model specification (10 points)
• Integration examples (10 points)

Skills (100 points total):

• YAML frontmatter MANDATORY (50 points)
• Progressive disclosure (20 points)
• Token count (15 points)
• Allowed-tools (15 points)

Commands (100 points total):

• Structure/content (30 points)
• $ARGUMENTS usage (25 points)
• Frontmatter (20 points)
• Description (15 points)
• Size (10 points)

Hooks (100 points total):

• Shebang (25 points)
• Error handling (25 points)
• Stdin reading (20 points)
• Documentation (15 points)
• Executable (15 points)

Scripts (100 points total):

• Shebang (30 points)
• Docstring (25 points)
• Error handling (20 points)
• CLI parsing (15 points)
• Executable (10 points)

Configurations (100 points total):

• Valid JSON (40 points)
• Permissions section (20 points)
• Permissions structure (15 points)
• Hooks/MCP (15 points)
• Size (10 points)

4.3 Grade Scale

Score	Grade	Meaning
90-100	A	Exemplary - Exceeds standards
80-89	B	Production-ready - Meets standards
70-79	C	Functional - Basic standards met
60-69	D	Minimal - Significant gaps
<60	F	Does not meet standards

Compliance Threshold: Grade B (80%+)

---

5. Stage 3: Gap Analysis

5.1 Gap Analysis Process

Input:

• Analysis Report (Stage 1)
• Validation Report (Stage 2)
• Component file

Process:

1. Review both reports
2. Identify gaps preventing Grade B (80%+)
3. Prioritize fixes:
   • P1 (Critical): Required for Grade B
   • P2 (Important): Required for Grade A
   • P3 (Optional): Nice-to-have
4. Generate fix recommendations with examples
5. Estimate fix duration
6. Calculate path to Grade B and Grade A

Output:

• Gap Report with prioritized fix plan
• Duration estimates
• Code examples for fixes

5.2 Gap Prioritization

Priority 1 (Critical) - Required for Grade B:

• Missing YAML frontmatter
• Missing required fields (name, description, etc.)
• Missing MANDATORY elements (e.g., Skills YAML)
• Critical structural issues

Priority 2 (Important) - Required for Grade A:

• Missing optional YAML fields
• Missing integration documentation
• Missing error handling sections
• Weak progressive disclosure

Priority 3 (Optional) - Enhancements:

• Additional examples
• Best practices sections
• Advanced usage documentation

5.3 Fix Recommendation Format

For each gap:

**Gap [#]: [Title]**
- **Impact:** −[X] points
- **Priority:** P1|P2|P3
- **Fix:** [Brief description]
- **Example:**
  ```[language]
  [code example]

• Duration: [X] minutes
• Location: Lines [X-Y] or "Insert after line [Z]"

---

## 6. Stage 4: Fix Application

### 6.1 Fix Application Process

**Input:**
- Gap Report with fix recommendations
- Component file

**Process:**
1. Read Gap Report
2. Apply P1 fixes (automated with Edit tool)
3. Apply P2 fixes (if targeting Grade A)
4. Document all changes in Change Log
5. Validate syntax after changes
6. Create before/after comparison

**Output:**
- Fixed component file
- Change Log
- Manual fix instructions (if any)

### 6.2 Fix Types

**Automated Fixes (Edit tool):**
- Add/update YAML frontmatter
- Add required fields
- Fix formatting/indentation
- Add standard sections (templates)
- Add $ARGUMENTS placeholders

**Semi-Automated Fixes (Edit + Review):**
- Add integration sections (need agent name)
- Add error handling (need context)
- Improve descriptions (need domain knowledge)

**Manual Fixes (Instructions only):**
- Complex refactoring
- Progressive disclosure restructuring
- Custom integration patterns
- Domain-specific improvements

### 6.3 Change Documentation

**Every fix must document:**
- What changed (specific edits)
- Why it changed (gap addressed)
- Before/after code snippets
- Impact on grade (+X points)

---

## 7. Stage 5: QA Review

### 7.1 QA Review Process

**Input:**
- Fixed component file
- Change Log
- Original validation report

**Process:**
1. Re-run validation script
2. Compare grades (before/after)
3. Check for regressions
4. Verify target met (Grade B minimum)
5. Spot-check manual review (10% sample)
6. Make approval decision

**Output:**
- QA Report with approval/rejection
- Re-validation results
- Recommendation for next steps

### 7.2 Approval Criteria

**APPROVED if:**
- ✅ Grade B (80%+) achieved
- ✅ No new violations introduced
- ✅ All P1 fixes applied correctly
- ✅ Syntax valid
- ✅ No regressions in functionality

**REJECTED if:**
- ❌ Grade still <80%
- ❌ New violations introduced
- ❌ Syntax errors present
- ❌ Regressions detected
- ❌ Incomplete fixes

### 7.3 Rejection Handling

**If rejected:**
1. Revert changes (git reset)
2. Review rejection reasoning
3. Refine fix approach
4. Re-run Stage 4 (Fix Application)
5. Re-run Stage 5 (QA Review)

**Maximum retries:** 2 attempts per component

---

## 8. Workflow Execution

### 8.1 Execution Script

**Workflow orchestration:**
```python
def process_component(component_path, component_type, standard_path):
    """
    Execute 5-stage workflow for single component.
    """
    component_name = Path(component_path).stem

    print(f"🔄 Processing: {component_name}")

    # Stage 1: Analysis
    print("  Stage 1/5: Analysis...")
    analysis_report = run_analysis_agent(component_path, standard_path)
    save_report(f"analysis-{component_name}.md", analysis_report)

    # Stage 2: Validation
    print("  Stage 2/5: Validation...")
    validation_report = run_validation_script(component_path, component_type)
    save_report(f"validation-{component_name}.json", validation_report)

    # Stage 3: Gap Analysis
    print("  Stage 3/5: Gap Analysis...")
    gap_report = run_gap_analysis_agent(analysis_report, validation_report)
    save_report(f"gap-{component_name}.md", gap_report)

    # Stage 4: Fix Application
    print("  Stage 4/5: Applying Fixes...")
    change_log = apply_fixes(component_path, gap_report)
    save_report(f"changelog-{component_name}.md", change_log)

    # Stage 5: QA Review
    print("  Stage 5/5: QA Review...")
    qa_report = run_qa_review(component_path, component_type, validation_report)

    if qa_report["decision"] == "APPROVED":
        print(f"  ✅ {component_name}: {qa_report['grade_after']} (approved)")
        commit_changes(component_path, change_log, qa_report)
        update_tasklist(component_name, "completed")
        return "SUCCESS"
    else:
        print(f"  ❌ {component_name}: Rejected - {qa_report['rejection_reason']}")
        return "REJECTED"

8.2 Batch Processing

Processing order:

1. Priority 1: Critical (48 commands + 5 skills + 27 agents = 80 components)
2. Priority 2: High (61 components)
3. Priority 3: Medium (46 components)
4. Priority 4: Low (32 components - optional)

Parallel processing:

• Components can be processed in parallel if independent
• Maximum 3 concurrent workflows (resource management)
• Commit after each component (atomic progress)

8.3 Error Handling

If Stage 1-3 fails:

• Log error
• Skip component
• Mark as "NEEDS_MANUAL_REVIEW" in TASKLIST
• Continue with next component

If Stage 4 fails:

• Revert changes
• Mark as "FIX_FAILED" in TASKLIST
• Document error for manual resolution

If Stage 5 rejects:

• Retry with refined approach (max 2 attempts)
• If still rejected, mark as "QA_REJECTED"
• Escalate to manual review

---

9. Progress Tracking

9.1 TASKLIST Updates

For each component:

### Week 1 - Critical Commands
1. [x] commands/a11y.md - Grade B (87%) - Approved ✅
2. [ ] commands/action.md - In Progress
3. [ ] commands/agent-dispatcher.md - Pending
...

Status indicators:

• [ ] - Pending (not started)
• [~] - In Progress (currently processing)
• [x] - Completed (approved and committed)
• [!] - Needs Manual Review
• [X] - Rejected/Failed

9.2 Daily Summary

Generate daily summary:

## Daily Progress Report: December 3, 2025

### Summary
- Components processed: 12
- Approved: 10 (83.3%)
- Rejected: 2 (16.7%)
- Average grade improvement: C (74%) → B (86%)
- Total duration: 4.2 hours

### By Component Type
- Commands: 8 processed, 7 approved
- Skills: 2 processed, 2 approved
- Agents: 2 processed, 1 approved

### Issues Encountered
- 2 components require manual review (complex restructuring)

### Next Steps
- Resume batch processing tomorrow
- Manual review session for rejected components

9.3 Milestone Tracking

Week 2 Milestone:

• Target: <10% Grade F components
• Current: 31% → 8% (on track)
• Remaining: 48 commands, 5 skills

Week 4 Milestone:

• Target: 70%+ compliance
• Current: 49.8% → 68% (needs acceleration)

---

10. Quality Gates

10.1 Component-Level Gates

Before proceeding to next stage:

• Current stage complete
• Report generated and saved
• No errors encountered
• Output meets format requirements

10.2 Batch-Level Gates

Before committing batch:

• 90%+ approval rate for batch
• No critical regressions detected
• TASKLIST updated
• Reports archived

10.3 Phase-Level Gates

Before declaring phase complete:

• Compliance target met (70%/80%/90%)
• All P1 components processed
• Automated validation passing
• Documentation updated

---

Appendix A: Workflow Invocation Examples

Example 1: Process Single Command

# Full workflow for commands/a11y.md
python3 scripts/process-component.py \
  --file commands/a11y.md \
  --type command \
  --standard CODITECT-CORE-STANDARDS/CODITECT-STANDARD-COMMANDS.md \
  --workflow full \
  --auto-commit

Example 2: Process Batch (Priority 1 Commands)

# Process first 10 critical commands
python3 scripts/process-batch.py \
  --priority 1 \
  --type command \
  --count 10 \
  --parallel 3 \
  --auto-commit

Example 3: Manual Agent Invocation

# Stage 1: Analysis
Task(
    subagent_type="codebase-analyzer",
    description="Analyze commands/a11y.md",
    prompt="Analyze commands/a11y.md against CODITECT-STANDARD-COMMANDS.md..."
)

# Stage 2: Validation
Bash(command="python3 scripts/validate-components.py --file commands/a11y.md --type command")

# Stage 3: Gap Analysis
Task(
    subagent_type="codebase-analyzer",
    description="Gap analysis for a11y command",
    prompt="Synthesize analysis and validation reports..."
)

# Stage 4: Fix Application
Edit(file_path="commands/a11y.md", old_string="...", new_string="...")

# Stage 5: QA Review
Task(
    subagent_type="qa-reviewer",
    description="QA review a11y command",
    prompt="Review fixed component and approve/reject..."
)

---

End of Workflow Documentation

Next Steps: Execute workflow systematically for all 271 components per priority schedule in PROJECT-PLAN.md.