fix: ai/commands/index.md shows "No description available" for 12 of 20 commands

[griffinwork40]

Problem

ai/commands/index.md shows "No description available" for 12 of 20 commands because those command files ship without a description: frontmatter field, which is what lib/index-generator.js reads from.

Affected commands

aidd-fix.md
aidd-rtc.md
commit.md
discover.md
execute.md
help.md
log.md
plan.md
review.md
run-test.md
task.md
user-test.md

Verification

$ grep -c "No description available" ai/commands/index.md
12

$ for f in ai/commands/*.md; do
    [ "$(basename "$f")" = "index.md" ] && continue
    head -10 "$f" | grep -q "^description:" || echo "missing: $(basename "$f")"
  done
missing: aidd-fix.md
missing: aidd-rtc.md
missing: commit.md
... (12 total, same list as above)

The index header (ai/commands/index.md:1–4) reads "This index provides an overview of the contents in this directory," which implies it's authoritative — but for 60% of commands the index gives the agent no signal at all.

The index is auto-generated by the --index pre-commit hook (AGENTS.md mentions this), so the source of the regression is the command files themselves, not the generator.

Why this matters

/help reads a separate live registry (ai/skills/aidd-please/SKILL.md) and is therefore unaffected — but agents and humans who follow the AGENTS.md "Progressive Discovery" guidance read index.md first (AGENTS.md:13–24) and may skip a relevant command they would have used if its purpose were stated.

Suggested directions

1. Backfill description: frontmatter on the 12 commands. Simplest, smallest diff. Description can mirror what /help returns.

2. Make the generator fall back when frontmatter is missing — e.g., use the first non-empty markdown line after the title as a description, with a // no description comment in the output so the gap is visible during code review.

3. Add a CI check (e.g., a unit test in lib/index-generator.test.js) that fails if any ai/commands/*.md or ai/skills/*/SKILL.md lacks description:. Prevents regressions when new commands/skills are added.

(1) and (3) together would close the gap and keep it closed.

Related

• fix: aidd-custom/index.md omits config.yml from directory listing #204 — adjacent issue in aidd-custom/index.md (omits config.yml). Same generator, different surface. The CI check in suggestion (3) would catch both classes.

Expected

ai/commands/index.md lists a one-line purpose for every shipped command.

Notes

Found during a third-party audit. Citations are against paralleldrive/aidd@57758344 (current main).