spec-discovery

Spec Discovery Skill

Locate specs and external request headers, extract IDs (e.g., REQ-NOTIFY-001), and return traceable metadata for downstream agents.

Variables

Workflow (Mandatory)

1. Load repositories: ROOT + EXTRA_REPOS
2. Walk specs: specs/, specs/external-requests/, skip specs/templates/
3. Parse headings: match ^#+\s*(REQ-[A-Za-z0-9_-]+)\s*:?\s*(.*)$
4. Normalize: path relative to repo root, anchor from ID + title
5. Traceability: compute SHA-256 of file content; record source_repo, path, hash
6. Emit manifest: sorted by repo → path → ID in JSON/TOON (see Output Schema)

Red Flags (Stop & Verify)

• No IDs detected in a spec file → confirm heading format before skipping
• Duplicate spec IDs across repos → flag in the manifest notes field
• Missing specs/ directory → report empty result rather than failing

Output Schema

{
  "format": "spec-manifest/v1",
  "generated_at": "<ISO-8601 UTC>",
  "sources": [
    {"repository": "<repo-name>", "root": "<abs-path>"}
  ],
  "specs": [
    {
      "id": "REQ-NOTIFY-001",
      "title": "Email Sending Endpoint",
      "source_repo": "ai-dev-kit",
      "path": "specs/external-requests/notify.md",
      "link": "specs/external-requests/notify.md#req-notify-001-email-sending-endpoint",
      "hash": "<sha256-of-file>"
    }
  ]
}

Provider Notes

• Use this skill when other commands request /ai-dev-kit:specs-find or spec traceability.
• Prefer JSON for machine workflows; use TOON for compact prompt embedding.
• Preserve ID/title casing; anchors should be lowercase + hyphenated.