DocsProject Entry Spec

Project Entry Spec

Project Entry Spec

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

A project page here is reserved for a major internal improvement effort: developing a product, building an internal process, or growing a company capability. Examples include E2E operators, the PortalJS go-to-market push, or the company KB rollout.

Client delivery is tracked elsewhere and never gets a project page here. Campaigns, monthly cycles, routine operations and product releases stay in execution trackers linked from the parent initiative. A deadline alone does not justify a project page.

For the scope test, the four questions every project must answer, and how to use the LTP skill, see How to run a project. This page is the field reference.

File location

A project is either one file or, when it has supporting material (analysis, briefs, LTP files, drafts), a folder:

projects/YYYY-{slug}.md

projects/{slug}/README.md plus supporting files alongside it

The folder name is the project slug, so it must not match any initiative or other project slug. The README.md carries the frontmatter below; supporting files need none. The portfolio index picks up both forms.

Examples:

  • projects/2026-current-financial-systems-capabilities.md
  • projects/portfolio-and-plans-kb.md
  • projects/e2e-hiring/README.md (with brief.md, ltp/, and so on)

Use the year the project starts as the prefix for single-file projects.

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

Every active project also needs a ## Summary section at the top of the body answering four questions: objectives and key results, whether an LTP or SCQ analysis has been done (with link), who is driving it, and the timeline. See How to run a project.

Use the rest of the body 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

Every project should have an LTP analysis (or at least an SCQ), linked from the Summary. The LTP skill can interview you from scratch; no prior write-up is needed. See How to run a project.

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: "da-215"

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

## Summary

- **Objective:** Give the team one shared view of leads, owners and follow-up.
- **Key results:**
  - All active opportunities in the CRM with owner and next step by 2026-05-10
  - Weekly pipeline review run from the CRM, not spreadsheets, by 2026-05-31
- **Analysis:** not yet, LTP due 2026-04-30.
- **Driver:** Monika
- **Timeline:** 2026-04-24 → 2026-05-31. Next milestone: opportunities migrated, 2026-05-10.

## 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

- `da-215` CRM v0.1 epic (`bd show da-215`)

## 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 documenting financial systems, visibility gaps, and improvement recommendations by 2026-06-30."

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 Summary answering objectives and key results, analysis, driver and timeline
  • 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 a beads epic as the live tracker for the project, with actions as child issues, and set active_issue to the epic ID. A linked GitHub issue is acceptable where the work already lives there.

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

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.

Edit this page
Built with LogoFlowershow