dev-hub Projects: Research Plans Above the Code

dev-hub started as a way to keep my code in shape: a task board of small upkeep jobs, and features for bigger pieces of work. But most of my repos exist because of research, and the reason for any piece of code exists is usually because it’s linked to a research project, not on a board.

So dev-hub now has a layer above the boards: projects. A project is one Markdown file per research project, holding its goals, objectives, plans, todos, references and a research log, laid out so Claude can read it and plan from it.

This post uses a made-up project to show how it works. Real project files stay private: the public template ships only the empty project template and this example.

Three levels of work

A project breaks into work packages, and each work package links down to the tasks and features doing its code work, by their board IDs. The boards don’t link back up, so there’s only one place to keep current: the project. Research that isn’t code (reading, analysis, writing) stays in the project as work packages and todos.

flowchart LR
  P["<b>Project HEAT</b><br/>urban heat islands"] --> W1["<b>WP1.1</b><br/>clean dataset"]
  P --> W2["<b>WP1.2</b><br/>intensity pipeline"]
  P --> W3["<b>WP1.3</b><br/>validation figure"]
  W1 -->|"links"| T["<b>task HT-3</b><br/>one branch, one PR"]
  W2 -->|"links"| F["<b>feature HT-FA</b><br/>one branch, one PR at the end"]
  W3 --> N["reading and analysis<br/>no code"]
  classDef proj fill:#eef5e9,stroke:#5b8a3c,color:#1b1b1b
  classDef board fill:#e8f0fb,stroke:#4a6fa5,color:#1b1b1b
  class P,W1,W2,W3,N proj
  class T,F board

The levels work together, but none needs the others. Tasks alone are the simplest way to use dev-hub, and a project with no tracked repos at all is still a useful research notebook.

A project file

Each project is one file, projects/<descriptive-name>.md, named for people. A short uppercase ID in its metadata is how Claude and I refer to it. The made-up example is urban-heat-islands.md, ID HEAT:

---
id: HEAT            # short and unique
title: Urban heat islands from satellite data
status: active      # or idea, paused, done, dropped
started: 2026-09
horizon: 2027-06    # target end or next milestone
repos: [heat_tools] # tracked repos it uses, or []
updated: 2026-09-29 # changes on every edit
---

Then come the same sections every time, in the same order:

A work-package table looks like this:

HT-3 and HT-FA are a task and a feature on the boards of an imaginary heat_tools repo. IDs never change and are never reused (goals G1, objectives O1, work packages WP1.1), so “plan WP1.2” always means the same thing.

Working with a project

Day to day there’s no command at all. I just say it: “HEAT log: the cloud mask removes 40% of July scenes”, “add a HEAT todo: email the station network”, or “HEAT decision: use MODIS, not Landsat, for the daily series”. Claude files it in the right section and updates the date. I can also edit the file by hand, as long as the structure stays.

Making a project easy to plan from

• Make each objective measurable, with success criteria you could check.
• Give each work package one output: a dataset, a figure, an analysis or a paper section.
• Write plans as checklists with inputs and outputs, so each step can become a task.
• Keep DOIs in the references, so Claude can find the papers.
• Keep the log dated and short. Decisions go in Decisions, not the log.

Try it

The public dev-hub-template has the project template, a projects guide and the full made-up HEAT project.

Going further (optional)

Why a fixed structure

The goals stay mine

Where project edits go