bigbio / bigbio/hvantk

Validate plugin-author UX: walk one new plugin through agent-driven authoring

Open
#112 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
1
Forks
0
Avg merge
1d 3h
Merged PRs (30d)
40

Description

## Status (2026-05-31)

Backlog process task — **still unrun**. The structural pieces below all exist on `dev` (verified: `hvantk/skills/_conventions/SKILL.md`, `hvantk/skills/_hooks/`, the `plugin.yaml` schema, the `gevir` example plugin, `hvantk plugins list`, `hvantk reprocess`). What's missing is the validation walkthrough itself + the outcome memo. The `onek_genomes` and `cptac` plugins have since been authored, but not as a controlled "fresh agent, docs-only" pilot.

## Context

PR #109 landed the structural pieces of the plugin-author workflow:

- Conventions doc at `hvantk/skills/_conventions/SKILL.md`
- Per-skill `SKILL.md` templates
- Session hooks under `hvantk/skills/_hooks/`
- Manifest JSON schema (`plugin.yaml`) with strict validation
- Phase B `Builder` / `DownloadFn` / `ParseFn` Protocols (added in PR #110)
- Drift CI cron and conformance test scaffolding

What is **not** validated yet: whether a fresh agent, with no insider context, can author a new plugin end-to-end by reading only the conventions and an existing example.

## Why this matters

The original design framing was "datasets brought into the tool by help of coding agents." The structural pieces exist, but the conventions are unproven against the audience they target. Friction points that surface only at write-time (missing helpers, ambiguous schema rules, undocumented edge cases) are best discovered by running the workflow.

## Scope

Pick one not-yet-promoted public data source — something with a freely-available fixture, ideally a simple TSV/JSON shape. Candidates: Reactome (gene–pathway TSV), Open Targets associations, DepMap CRISPR scores (gene-level CSV).

Walk a fresh agent through:

1. Read `hvantk/skills/_conventions/SKILL.md` and one existing plugin (e.g. `gevir`) as template.
2. Draft `plugin.yaml`, `builder.py`, `drift_probe.py`, `tests/test_.py`, `SKILL.md`.
3. Iterate until `hvantk plugins list` surfaces the new dataset and `hvantk reprocess :` runs end-to-end on a fixture.

## Deliverable

A short outcome memo (similar to `local/planning/2026-05-10-skill-pilot-outcome.md`) capturing: time taken, friction points (anything the agent had to ask that wasn't covered by docs), conventions edits needed afterward, and a verdict on whether the agent-authoring workflow is fit for purpose.

## References

- Discovered during audit of PR #109; tracked as D5 in the followup planning doc.
- Conventions skill pilot (precedent): `local/planning/2026-05-10-skill-pilot-outcome.md`.

Contributor guide

Open the contributing guide

Research direction

Start by reading hvantk/skills/_conventions/SKILL.md, the gevir example plugin, and local/planning/2026-05-10-skill-pilot-outcome.md. Run the documented workflow for one public data source, including hvantk plugins list and hvantk reprocess : on a fixture. Done means the fresh-agent walkthrough is complete and an outcome memo records time, friction points, needed convention edits, and the verdict.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
developer-experience, documentation, testing, tooling
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.