bmad-code-org/BMAD-METHOD · error · Error

llms.txt must describe Build as canonical for both direct in

Error message

llms.txt must describe Build as canonical for both direct intent and fully planned work

What it means

Thrown by validatePublishedImplementationModel when <siteDir>/llms.txt exists but lacks either the canonical entry marker ('**[Build]') or the canonical description string. The validator enforces that the LLM-discovery file advertises Build as canonical for both direct intent and fully planned work, so LLM agents reading llms.txt pick the right workflow.

Source

Thrown at tools/validate-published-implementation-model.mjs:32

  /\b(?:createStory|devStory|create_story|dev_story)\b/g,
  /\bquick[ -]?flow\b/gi,
  /flux rapide|parcours parallèle/gi,
  /paralelní cesta/gi,
  /luồng nhanh|nhánh nhanh/gi,
  /快速流程|并行快线/g,
];

export function validatePublishedImplementationModel(siteDir) {
  const findings = findObsoleteImplementationTerms(siteDir);
  if (findings.length > 0) {
    const details = findings.map(({ file, line, match }) => `${file}:${line}: ${match}`).join('\n  ');
    throw new Error(`Obsolete implementation terminology found in deployable documentation:\n  ${details}`);
  }

  const llmsPath = path.join(siteDir, 'llms.txt');
  const llmsContent = fs.readFileSync(llmsPath, 'utf-8');
  if (!llmsContent.includes(CANONICAL_LLMS_ENTRY) || !llmsContent.includes(CANONICAL_LLMS_DESCRIPTION)) {
    throw new Error('llms.txt must describe Build as canonical for both direct intent and fully planned work');
  }
}

export function findObsoleteImplementationTerms(siteDir) {
  const findings = [];

  for (const filePath of getPublishedTextFiles(siteDir)) {
    const content = fs.readFileSync(filePath, 'utf-8');
    for (const pattern of FORBIDDEN_TERMS) {
      for (const match of content.matchAll(pattern)) {
        findings.push({
          file: path.relative(siteDir, filePath),
          line: content.slice(0, match.index).split('\n').length,
          match: match[0],
        });
      }
    }
  }

View on GitHub (pinned to b70486b9bd)

Solutions

Ensure the llms.txt source/generator emits both '**[Build]' and the canonical description string verbatim.
Re-run the build step that produces llms.txt from its source.
If hand-editing, add the two required phrases exactly as defined by CANONICAL_LLMS_ENTRY and CANONICAL_LLMS_DESCRIPTION.

Example fix

# before: _site/llms.txt
#   ## Build
#   Implementation workflow.
#
# after
#   **[Build]: Canonical implementation workflow for direct intent and fully planned work**

Defensive patterns

Strategy: validation

Validate before calling

const llms = fs.readFileSync(path.join(siteDir, 'llms.txt'), 'utf8');
if (!llms.includes('**[Build]') || !llms.includes('Canonical implementation workflow for direct intent and fully planned work')) {
  console.error('llms.txt missing canonical Build markers; regenerate before validating.');
  process.exit(1);
}
validatePublishedImplementationModel(siteDir);

Try / catch

try {
  validatePublishedImplementationModel(siteDir);
} catch (e) {
  if (/llms.txt must describe Build as canonical/.test(e.message)) {
    // regenerate llms.txt from the canonical template, then re-run
  } else { throw e; }
}

Prevention

Generate llms.txt from a single template that hard-codes both canonical phrases.
Rebuild llms.txt whenever the workflow vocabulary changes.
Test the generator output includes both markers in CI.

When it happens

Trigger: Running validatePublishedImplementationModel after build; llms.txt was generated or hand-edited without both required canonical phrases.

Common situations: A llms.txt generator/template dropped the canonical markers; the workflow was renamed without updating the generator; partial build that wrote llms.txt from stale content.

Related errors

AI-assisted analysis of bmad-code-org/BMAD-METHOD@b70486b9bd (2026-08-13). Data as JSON: /api/errors/1649c811cd0d53a1. Report an issue: GitHub.