Project Entry Spec

Use this guide when creating or updating a project page in projects/.

A project is bounded work such as:

• a versioned push
• an experiment
• a campaign
• a time-limited implementation effort
• a concrete part of an initiative with a clearer done state

File location

Create one file per project:

projects/YYYY-{slug}.md

Examples:

• projects/2026-portaljs-awesome-demo.md
• projects/2026-volume-and-velocity-discord-review-v0.1.md
• projects/2026-crm-v0.1.md

Use the year the project starts as the prefix.

What every active project must include

Every active project should have:

• title
• owner
• status
• parent
• hypothesis
• success_metric
• definition_of_done
• end or a clear timebox
• active_issue

Use the body of the page for the project definition, plan of work, evidence, related issues, and notes.

Optional fields

Use these only when they add value:

• description
• start
• url
• created

Projects do not require a full SCQH by default.

Use SCQH at the project level only when the problem itself is unclear and needs deeper framing.

Copy-and-edit example

---
title: "CRM Setup v0.1"
status: active
parent: crm
owner: monika
hypothesis: "Lead tracking is fragmented. If we set up a lightweight CRM, we should get clearer pipeline visibility and more consistent follow-up."
success_metric: "The team can reliably see current lead status, owner, and next step in one place."
definition_of_done: "A usable CRM v0.1 is in place, active opportunities are entered, and the team is using it for follow-up."
end: 2026-05-31
active_issue: "bd-215"

# Optional fields
description: "First-pass CRM setup for marketing."
start: 2026-04-24
created: 2026-04-24
url: "https://..."
---

## What this project is

Set up a lightweight CRM that gives the team a clearer shared view of leads, ownership, and follow-up.

This project commits to putting a usable CRM v0.1 in place by 2026-05-31.

## Plan of work

| Milestone / checkpoint | ETA | Expected outcome | Done | Completion date |
|---|---|---|---|---|
| CRM structure defined | 2026-04-24 | CRM schema or workspace setup that can be reviewed | ✅ | 2026-04-24 |
| Active opportunities migrated | 2026-05-10 | Live opportunity list entered into the CRM | [ ] | |
| CRM v0.1 reviewed | 2026-05-31 | Review note or decision confirming whether v0.1 meets the definition of done | [ ] | |

## Links / Evidence

- CRM workspace:
- Migration checklist:
- Example active opportunities entered:

## Related Issues

- [#215](https://github.com/.../issues/215) CRM v0.1 working issue

## Notes

- Keep the initial version lightweight and focused on visibility first

Definition rule

The ## What this project is section should do two things clearly:

• explain what the project is
• state explicitly what the project is promising by when

That promise does not need a separate section, but it should be explicit.

Good:

• "This project commits to putting a usable CRM v0.1 in place by 2026-05-31."
• "This project commits to launching the Meta ads campaign on 2026-05-22 and reviewing first-month results by 2026-06-22."

Too vague:

• "Improve CRM"
• "Push on campaign setup"
• "Work on automation"

Plan of work rule

Use one combined Plan of work table:

• Milestone / checkpoint
• ETA
• Expected outcome
• Done
• Completion date

This table should show both:

• what has already been completed
• what still needs to happen

The Expected outcome column should describe the concrete result expected from the milestone and link to proof where possible.

Quality rule

No active project should exist without:

• a clear hypothesis
• a clear success test
• a clear done definition
• a clear end date or review point
• one canonical active issue

If the project cannot be assessed at the end, the template is too light.

Tracking rule

Use the linked GitHub issue as the live status tracker for the project.

The markdown project page should define the project clearly and show its milestones, evidence, and canonical issue, but day-to-day status, blockers, and current progress should live in GitHub.

Evidence rule

Where an output already exists, link it directly.

This applies especially to:

• docs
• folders
• prototypes
• workflows
• assets
• review notes
• active issues

If the Expected outcome in the Plan of work table already exists, link to the proof wherever possible.

KISS rule

The template should stay lightweight, but not rushed.

People should spend enough time to think properly about:

• why this project exists
• what success looks like
• what done looks like
• what exactly is being promised by when

Planning should stay high level.

Do not turn the page into day-by-day planning.

If the project cannot be assessed at the end, the template is too light.