ecosystem/AGENT-CHECK.md

Repository Quality Check Instructions

Purpose: This document provides detailed instructions for AI agents to perform comprehensive quality assurance checks on the Logos Ecosystem Wiki repository.

Overview

When the user says "check", perform the following quality assurance tasks across the repository.

IMPORTANT: When running checks, always exclude the tmp/ directory.

---

Check Tasks

1. Ensure Filename Conventions

Verify that all markdown files follow naming best practices:

• Use underscores instead of spaces (e.g., activity_hub.md not Activity Hub.md)
• Filename should closely match the title frontmatter property (lowercase, underscores, reasonable length)

Examples:

• title: Activity Hub → activity_hub.md ✅
• title: Multisig Wallet → multisig_wallet.md or multisig.md ✅ (abbreviated for brevity)
• title: Logos JS SDK (Browser) → logos_js_sdk_browser.md ✅ (special chars removed)
• title: Private DEX → private_dex.md ✅

2. Ensure Document Structure Consistency

Verify that files within the same folders follow consistent structure patterns:

• All files in content/integration/desired_projects/, infrastructure_essentials/, or application_essentials/ should have similar headings, sections, and frontmatter format
• Check for required sections: FURPS+, Demand Validation, Possible Implementation, Technical Validation
• Verify frontmatter includes: title, type, priority (can be empty), category, flywheel (where applicable)

3. Add Internal Links

Identify mentions of concepts and artifacts that are defined elsewhere in the repository and add wikilinks to connect them.

Example: If a file mentions "Multisig" and there's a multisig.md file, link to it using [[integration/desired_projects/multisig|Multisig]]

When to add wikilinks:

• First mention of another desired project in the document
• Key integration points in "Technical Validation" or "Integration Points" sections
• Dependencies section (always link)

When NOT to add wikilinks:

• Repeated mentions of the same project within a document (link only the first)
• Generic references (e.g., "users need a DEX" vs "integrate with integration/desired_projects/private_dex")
• Within section headers

4. Validate Internal Links

Check that all existing internal links in the repository point to valid files that exist.

Process:

1. Extract all wikilink paths from markdown files
2. For each unique path, verify the corresponding file exists
3. Report any broken links with file location and expected path

5. Validate Wikilink Titles

Ensure that wikilink display text matches the title frontmatter property of the linked file.

Example:

• If multisig.md has title: Multisig Treasury / Vault
• Links should ideally be [[integration/desired_projects/multisig|Multisig Treasury / Vault]]
• Acceptable: [[integration/desired_projects/multisig|Multisig]] (contextual abbreviation)
• Incorrect: [[integration/desired_projects/multisig|Wallet]]

Note: Contextual abbreviations are acceptable when the full title is verbose or when the context makes the reference clear.

6. Verify AI-Generated Content Disclaimer

CRITICAL: Ensure all LLM-generated files in content/ folder have the AI disclaimer.

Check for:

• All markdown files in content/ should have > [!ai-generated] indicator
• This applies to ALL content types: integration docs, processes, protocols, guides, and any other generated documents
• Indicator should be placed immediately after frontmatter and description (for whole-file) or after section headers (for partial)

Recommended pattern (whole-file):

---
title: Document Title
---

Brief description.

> [!ai-generated]
> This entire document was generated by an LLM and has not yet been human-reviewed.

## First Section
...

What to report:

• Files missing AI disclaimer
• Files with incorrectly placed disclaimers
• Percentage of files with proper disclaimers

---

Automated Check Commands

The following bash commands can be used to automate quality checks:

1. Check for Files with Spaces in Names

find . -name "*.md" -type f -name "* *" -not -path "*/tmp/*"

Expected output: Empty (no files with spaces)

2. List All Markdown Files with Titles and Filenames

find . -name "*.md" -type f -not -path "*/tmp/*" -exec sh -c '
  for file; do
    title=$(grep -m1 "^title:" "$file" 2>/dev/null | sed "s/title: *//")
    filename=$(basename "$file" .md)
    if [ -n "$title" ]; then
      echo "$file | Title: $title | Filename: $filename"
    fi
  done
' sh {} +

Use: Review to ensure filenames closely match titles (with reasonable abbreviations)

3. Extract All Unique Wikilinks (Path and Display Text)

grep -roh "\[\[integration/[^]]*\]\]" . --include="*.md" --exclude-dir=tmp | sort -u

Use: Review all wikilinks for correctness and consistency

4. Extract Just File Paths from Wikilinks

grep -roh "\[\[integration/[^]]*\]\]" . --include="*.md" --exclude-dir=tmp | sed 's/\[\[\(integration\/[^|]*\).*/\1/' | sort -u

Use: Get list of all referenced files for validation

5. Count Total Markdown Files (Excluding tmp)

find . -name "*.md" -type f -not -path "*/tmp/*" | wc -l

Use: Track total number of integration documents

6. Find References to a Specific File/Concept

grep -r "SEARCH_TERM" . --include="*.md" --exclude-dir=tmp

Use: Find all mentions of a specific concept or file reference

7. Validate Wikilink Paths Exist

# Extract unique wikilink paths, then check if corresponding files exist
grep -roh "\[\[integration/[^]]*\]\]" . --include="*.md" --exclude-dir=tmp | \
  sed 's/\[\[\(integration\/[^|]*\).*/\1/' | sort -u | while read link; do
  filepath="${link#integration/}.md"
  if [ ! -f "$filepath" ]; then
    echo "BROKEN: $link -> $filepath"
  fi
done

Expected output: Empty (no broken links) or list of broken wikilinks

8. Count Wikilink Occurrences

grep -r "\[\[" . --include="*.md" --exclude-dir=tmp | wc -l

Use: Track total number of wikilinks across all documents

---

Expected Check Output

After performing all checks, provide a summary report in this format:

✅ Filename conventions enforced (underscores not spaces)
✅ Document structure consistency across integration folders
✅ Internal links added throughout documents
✅ All internal links validated
✅ Wikilink titles match frontmatter title properties
✅ AI-generated content disclaimers present

---

Common Issues Caught

• Files with spaces in names (e.g., Activity Hub.md → activity_hub.md)
• Filenames don't match title property (e.g., dex.md with title: Private DEX → should be private_dex.md)
• Inconsistent section headers (e.g., ## FURPS → ## FURPS+)
• Missing standard sections (e.g., no "Demand Validation" section)
• Broken wikilinks pointing to non-existent files
• Unlinked mentions of other projects
• Wikilink display text doesn't match the target file's title property (e.g., [[file|Wrong Title]] when frontmatter says title: Correct Title)
• Missing AI-generated content disclaimer in LLM-created files

---

Reporting

When reporting check results:

1. Summary Statistics:

   • Total files analyzed
   • Total wikilink occurrences
   • Unique file paths referenced

2. Issues Found:

   • List each type of issue with count
   • Provide specific examples with file paths

3. Issues Fixed:

   • List what was corrected
   • Note file paths modified

4. Remaining Issues:

   • List issues requiring human review or decision
   • Provide recommendations

5. Documentation Updates:

   • Note if AGENT-CHECK.md or CLAUDE.md were updated
   • Document any new check commands added