Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
  • Is something wrong?
#318 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
markdown, yaml
Domain
documentation

Research direction

Start by inventorying the artifacts under aidd_docs/, especially specs, PRDs, and memory, and compare their existing frontmatter with the listed OKF fields. Determine which fields have no equivalent, then define the required index.md for each directory. Done means foreign-facing artifacts use the vocabulary and every aidd_docs/ directory has an index; the named external-consumer criterion is currently blocked because no OKF reader exists.

Written by the indexing model from the issue text.

Description

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.

Dominant language
TypeScript
Stars
481
Forks
45
Avg merge
18h 48m
Merged PRs (30d)
111

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ai-driven-dev/framework

All issues in ai-driven-dev/framework

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.