Verifying Artifact Structures

Verifying Artifact Structures

This skill provides the standard procedure for ensuring that all documentation artifacts (knowledge JSONs and workflow markdowns) meet the factory's structural requirements.

When to Use

• After creating or modifying a knowledge file or workflow.
• During CI/CD quality gate checks.
• Before a major release or version bump.

Prerequisites

• Python Environment: Conda environment D:\Anaconda\envs\cursor-factory must be active.
• Validation Script: scripts/validation/verify_structures.py must exist.
• Project Structure: Artifacts must be located in .agent/knowledge or .agent/workflows.

Process

To maintain artifact integrity, follow this systematic verification sequence to identify and fix structural drift.

1. Run Automated Verification

Execute the verification script to identify structural deficiencies:

conda run -p D:\Anaconda\envs\cursor-factory python scripts/validation/verify_structures.py

2. Remediate Failures

For each failure:

• Knowledge JSON: Ensure id, name, version, category, description are present. Add patterns, best_practices, and anti_patterns.
• Workflow MD: Ensure an H1 title, ## Overview, ## Trigger Conditions, and Version: declarations are present.
• Workflow Metadata: Check if **Version:** and **Trigger Examples:** body metadata are present for IDE visibility.

3. Synchronize Manifests

After structural fixes, update the system counts:

1. conda run -p D:\Anaconda\envs\cursor-factory python scripts/validation/sync_knowledge_counts.py --sync
2. conda run -p D:\Anaconda\envs\cursor-factory python scripts/validation/sync_artifacts.py --sync
3. conda run -p D:\Anaconda\envs\cursor-factory python scripts/validation/sync_manifest_versions.py --sync
4. conda run -p D:\Anaconda\envs\cursor-factory python scripts/validation/validate_readme_structure.py --update

Best Practices

• Verify early: Run structural checks immediately after file creation.
• Sync ALWAYS: Never assume the manifests are correct. Always run the sync suite after modification.
• JSON Precision: Always match the id field to the filename (without extension).
• Trigger Clarity: Ensure workflows have at least 2 clear trigger examples.