affaan-m/ECC · error · Error

README.md project tree is missing the agents count

Error message

README.md project tree is missing the agents count

What it means

The catalog CI script parses README.md to extract the documented agents/skills/commands counts and compares them against the actual filesystem catalog. This specific throw fires when the regex `/^\|\s*--\s*agents\/\s*#\s*(\d+)\s+specialized subagents for delegation\s*$/im` fails to match a line in the README project tree section. The expected line format is `| -- agents/ # 68 specialized subagents for delegation`. It runs during the default catalog check or when you invoke `node scripts/ci/catalog.js`.

Source

Thrown at scripts/ci/catalog.js:106

function parseReadmeExpectations(readmeContent) {
  const expectations = [];

  const quickStartMatch = readmeContent.match(
    /access to\s+(\d+)\s+agents,\s+(\d+)\s+skills,\s+and\s+(\d+)\s+(?:commands|legacy command shims?)/i
  );
  if (!quickStartMatch) {
    throw new Error('README.md is missing the quick-start catalog summary');
  }

  expectations.push(
    { category: 'agents', mode: 'exact', expected: Number(quickStartMatch[1]), source: 'README.md quick-start summary' },
    { category: 'skills', mode: 'exact', expected: Number(quickStartMatch[2]), source: 'README.md quick-start summary' },
    { category: 'commands', mode: 'exact', expected: Number(quickStartMatch[3]), source: 'README.md quick-start summary' }
  );

  const projectTreeAgentsMatch = readmeContent.match(/^\|\s*--\s*agents\/\s*#\s*(\d+)\s+specialized subagents for delegation\s*$/im);
  if (!projectTreeAgentsMatch) {
    throw new Error('README.md project tree is missing the agents count');
  }

  expectations.push({
    category: 'agents',
    mode: 'exact',
    expected: Number(projectTreeAgentsMatch[1]),
    source: 'README.md project tree (agents)'
  });

  const tablePatterns = [
    { category: 'agents', regex: /\|\s*(?:\*\*)?Agents(?:\*\*)?\s*\|\s*(?:(?:PASS:|\u2705)\s*)?(\d+)\s+agents\s*\|/i, source: 'README.md comparison table' },
    { category: 'commands', regex: /\|\s*(?:\*\*)?Commands(?:\*\*)?\s*\|\s*(?:(?:PASS:|\u2705)\s*)?(\d+)\s+commands(?:\s*\([^)]*\))?\s*\|/i, source: 'README.md comparison table' },
    { category: 'skills', regex: /\|\s*(?:\*\*)?Skills(?:\*\*)?\s*\|\s*(?:(?:PASS:|\u2705)\s*)?(\d+)\s+skills\s*\|/i, source: 'README.md comparison table' }
  ];

  for (const pattern of tablePatterns) {
    const match = readmeContent.match(pattern.regex);
    if (!match) {

View on GitHub (pinned to 01e15490f0)

Solutions

Open README.md and find the project structure tree section; ensure a line exactly matching `| -- agents/ # N specialized subagents for delegation` exists, where N equals the number of files in agents/.
Run `npm run catalog:write` (or `node scripts/ci/catalog.js --write`) to auto-rewrite the documented counts from the live filesystem catalog.
Verify the line uses a hyphen-minus `--` (U+002D), not an en-dash or em-dash, and a literal `#` before the digit.
Count the files with `ls agents/*.md | wc -l` and confirm the digit matches before committing.

Example fix

// before (README.md, broken — missing '# ' or wrong dash)
| — agents/ 68 specialized subagents for delegation

// after
| -- agents/ # 68 specialized subagents for delegation

Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs');
const readme = fs.readFileSync('README.md', 'utf8');
const re = /^\|\s*--\s*agents\/\s*#\s*(\d+)\s+specialized subagents for delegation\s*$/im;
if (!re.test(readme)) {
  console.error('README.md project tree agents line missing or malformed');
  console.error('Expected a line like: | -- agents/ # 68 specialized subagents for delegation');
  process.exit(1);
}
const documented = Number(readme.match(re)[1]);
const actual = fs.readdirSync('agents').filter(f => f.endsWith('.md')).length;
if (documented !== actual) {
  console.error(`agents count mismatch: README says ${documented}, actual ${actual}`);
  process.exit(1);
}

Type guard

// Guard the line shape before relying on the count
function hasValidProjectTreeAgentsLine(readmeContent) {
  const m = readmeContent.match(/^\|\s*--\s*agents\/\s*#\s*(\d+)\s+specialized subagents for delegation\s*$/im);
  return m !== null && Number.isInteger(Number(m[1]));
}

Try / catch

try {
  runCatalogCheck();
} catch (error) {
  if (/project tree is missing the agents count/i.test(error.message)) {
    console.error('README.md project-tree agents line is missing. Restore: | -- agents/ # N specialized subagents for delegation');
    console.error('Or run: node scripts/ci/catalog.js --write');
  }
  throw error;
}

Prevention

Run `node scripts/ci/catalog.js --write` after any change to agents/, skills/, or commands/ rather than editing counts by hand.
Add the catalog check as a pre-commit hook so documentation drift is caught before push.
Treat the project-tree line format (dash style, '#' separator, exact suffix) as a contract — do not reformat it.
When translating or rewriting README.md, run the check immediately to catch regex-breaking wording changes.

When it happens

Trigger: Running `node scripts/ci/catalog.js` (or `npm run catalog:check`) after the project tree section of README.md was edited. Fires when the line starting with `| -- agents/` is missing, has a different dash style (e.g. `—` em-dash or `- ` instead of `--`), is missing the `#` separator, omits the trailing `specialized subagents for delegation` phrase, or the count is non-numeric.

Common situations: A contributor rewrites the README project structure tree and reformats the agents line. Someone adds/removes agents but forgets to update the count annotation. A documentation linter or formatter collapses the `--` into an em-dash or rewraps the line. A translation pass or merge accidentally drops the line.

Related errors

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/8c79030128575f6e. Report an issue: GitHub.