Skip to content

feat(framework): adopt the OKF frontmatter vocabulary in aidd_docs #318

Description

@cduverne

Problem

Artifacts under aidd_docs/ carry ad-hoc frontmatter (objective, status) with no shared vocabulary, and no directory describes itself. An agent that did not write them cannot tell what they are.

The Open Knowledge Format is a candidate vocabulary. Checked against the Google Cloud announcement: OKF is directories of markdown files with YAML frontmatter, plus one index.md per directory. Each document carries type, title, description, resource, tags, timestamp. Vendor-neutral, no SDK.

So the framework already has the format — markdown with YAML frontmatter, everywhere. What it lacks is the shared vocabulary and the index.

Scope

  • Map the OKF fields onto what AIDD artifacts already carry, and name the ones with no equivalent.
  • Adopt the vocabulary in the artifacts a foreign agent would consume: specs, PRDs, memory.
  • Emit an index.md per aidd_docs/ directory.

Acceptance criteria

  • Every artifact a foreign agent would read carries the OKF fields.
  • A directory under aidd_docs/ describes itself through its index.md.
  • A named tool, outside AIDD, reads one of our artifacts and understands it.

Blocked: no consumer

No OKF reader exists in the AIDD ecosystem today. This buys interoperability with tools nobody has named. The last acceptance criterion is deliberately unsatisfiable right now — that is the point. Priority stays Low until a real consumer appears, and closing this issue is a defensible alternative to doing it.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Fields

    Priority

    Low

    Projects

    Status
    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions