affaan-m/ECC · error · Error

AGENTS.md is missing the catalog summary line

Error message

AGENTS.md is missing the catalog summary line

What it means

`parseAgentsDocExpectations` reads AGENTS.md and matches the summary line `/providing\s+(\d+)\s+specialized agents,\s+(\d+)(\+)?\s+skills,\s+(\d+)\s+commands/i`. This is the headline catalog sentence at the top of AGENTS.md (e.g. 'providing 68 specialized agents, 284+ skills, 94 commands'). The optional `(\+)?` after the skills count marks a minimum/floor expectation rather than exact. The throw fires when the sentence is absent.

Source

Thrown at scripts/ci/catalog.js:224

    if (!match) {
      throw new Error(`${pattern.source} is missing the ${pattern.category} row`);
    }

    expectations.push({
      category: pattern.category,
      mode: 'exact',
      expected: Number(match[1]),
      source: `${pattern.source} (${pattern.category})`
    });
  }

  return expectations;
}

function parseAgentsDocExpectations(agentsContent) {
  const summaryMatch = agentsContent.match(/providing\s+(\d+)\s+specialized agents,\s+(\d+)(\+)?\s+skills,\s+(\d+)\s+commands/i);
  if (!summaryMatch) {
    throw new Error('AGENTS.md is missing the catalog summary line');
  }

  const expectations = [
    { category: 'agents', mode: 'exact', expected: Number(summaryMatch[1]), source: 'AGENTS.md summary' },
    {
      category: 'skills',
      mode: summaryMatch[3] ? 'minimum' : 'exact',
      expected: Number(summaryMatch[2]),
      source: 'AGENTS.md summary'
    },
    { category: 'commands', mode: 'exact', expected: Number(summaryMatch[4]), source: 'AGENTS.md summary' }
  ];

  const structurePatterns = [
    {
      category: 'agents',
      mode: 'exact',
      regex: /^\s*agents\/\s*[—–-]\s*(\d+)\s+specialized subagents\s*$/im,

View on GitHub (pinned to 01e15490f0)

Solutions

  1. Restore the exact sentence in AGENTS.md: `providing 68 specialized agents, 284+ skills, 94 commands` (use `+` only if skills is a floor).
  2. Keep the word `providing`, the comma separators, and the unit words `specialized agents`/`skills`/`commands`.
  3. Run `node scripts/ci/catalog.js --write` to auto-sync the three counts from the live catalog.
  4. Confirm the skills count mode (exact vs minimum) matches your intent — `+` makes it a `>=` check.

Example fix

// before (AGENTS.md, paraphrased)
...offers 68 agents, 284 skills and 94 commands...

// after
**Version:** 2.2.0

This is a **production-ready AI coding plugin** providing 68 specialized agents, 284+ skills, 94 commands ...
Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs');
const agents = fs.readFileSync('AGENTS.md', 'utf8');
const re = /providing\s+(\d+)\s+specialized agents,\s+(\d+)(\+)?\s+skills,\s+(\d+)\s+commands/i;
if (!re.test(agents)) {
  console.error('AGENTS.md missing catalog summary line.');
  console.error('Expected: providing N specialized agents, N(+) skills, N commands');
  process.exit(1);
}

Type guard

function hasAgentsSummary(agentsContent) {
  const m = agentsContent.match(/providing\s+(\d+)\s+specialized agents,\s+(\d+)(\+)?\s+skills,\s+(\d+)\s+commands/i);
  return m !== null && Number.isInteger(Number(m[1])) && Number.isInteger(Number(m[2])) && Number.isInteger(Number(m[4]));
}

Try / catch

try {
  runCatalogCheck();
} catch (error) {
  if (/AGENTS\.md is missing the catalog summary line/i.test(error.message)) {
    console.error('Restore: providing N specialized agents, N(+) skills, N commands');
  }
  throw error;
}

Prevention

When it happens

Trigger: Triggered by `node scripts/ci/catalog.js` when AGENTS.md's opening summary lacks the `providing N specialized agents, N(+) skills, N commands` sentence. Drift in any connector (`specialized`, `skills`, `commands`), missing comma, or absent `providing` prefix causes failure.

Common situations: AGENTS.md is rewritten and the summary line is paraphrased (e.g. 'offers 68 agents...'). The `+` floor marker is removed or added without intent. The line is split across paragraphs. A version bump changes the headline but the wording is altered.

Related errors

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