STD-017: Portfolio Project Format

The standard format for portfolio project entries — the canonical inventory of all active, planned, and completed projects. 70+ entries across 12 categories. Each entry captures a project’s purpose, state, and trajectory. Extracted from portfolio audit revealing 17+ inconsistent status labels (Apr 2026).

Principles

  1. Controlled vocabulary is non-negotiable. Status labels are a closed set. Freeform status text ("mostly done," "needs review," "waiting on vendor") is prohibited. Use the 8 defined values and add nuance in Notes.

  2. Every entry tells a complete story. Premise, goals, current state, next steps. A reader encountering the entry for the first time should understand the project’s purpose and trajectory without navigating elsewhere.

  3. Next steps are actionable. Vague items ("improve documentation") are not next steps. Every item is a concrete task with a clear done condition, expressed as a checklist.

  4. Portfolio entries are not project documentation. They are summaries that xref to full project pages. Do not duplicate phase-level detail here.

  5. Categories are structural, not aspirational. A project belongs to exactly one of the 12 categories. If it does not fit, the project scope is unclear, not the taxonomy.

Status Controlled Vocabulary

8 permitted values. No others.

Status Definition Icon

Complete

All goals met, no remaining work

✅

Operational

Deployed and in use, minor improvements possible

✅

Active

Currently receiving regular work

🟡

In Progress

Work started but not receiving daily attention

🟡

Planned

Scoped and scheduled, work not yet started

❌

Parked

Intentionally paused — will resume when preconditions are met

⚠️

Blocked

Cannot proceed — waiting on external dependency

⚠️

Not Started

Identified but not yet scoped or scheduled

❌

Do not invent status labels. "Beta," "MVP," "Draft," "Needs Review," "Mostly Done," "Pending," and "WIP" are all prohibited. Map to the controlled vocabulary and add context in the Notes column or Current State section.

Portfolio Categories

12 categories. A project belongs to exactly one.

Category Scope

infrastructure

Servers, networking gear, hypervisors, storage

security

Hardening, certificates, access control, auditing

networking

Routing, switching, VLANs, DNS, DHCP, firewalls

automation

Scripts, pipelines, scheduled tasks, CI/CD

ai

Claude Code, LLM integration, AI-assisted workflows

software

Applications, tools, configurations (vim, tmux, shell)

documentation

Antora, docs-as-code, knowledge management

observability

Monitoring, logging, alerting, dashboards

identity

Active Directory, RADIUS, 802.1X, SSO, LDAP

collaboration

Team tooling, shared infrastructure, onboarding

operations

Day-to-day operational processes, runbooks, maintenance

education

Training tracks, certifications, study plans

Required Sections

Every portfolio entry MUST include these sections in order:

  1. Document header — = Title, :description:, :navtitle:, :icons: font

  2. Lead paragraph — 1-2 sentences stating the project’s purpose

  3. Status table — Category and Status using controlled vocabulary

  4. Premise — Why this project exists (the problem or opportunity)

  5. Goals — Numbered list of concrete objectives

  6. Current State — What has been accomplished, what remains

  7. Next Steps — Checklist ([ ] format) of actionable items

Optional Sections

These sections MAY be included when applicable:

  • Architecture Notes — If present, MUST include a diagram (D2, Mermaid, or Kroki) or a concrete TODO for creating one. Prose-only architecture notes are prohibited.

  • Related Documentation — xrefs to full project pages (pages/projects/), spoke repos, and case studies

  • Decision Log — Key decisions with rationale (date, decision, why)

Entry Template

= Project Title
:description: One-line project summary
:navtitle: Short Title
:icons: font

[.lead]
Brief statement of what this project is and why it matters.

[cols="1,2"]
|===
| Field | Value

| Category
| <one of 12 categories>

| Status
| <one of 8 controlled vocabulary values>
|===

== Premise

Why this project exists. The problem it solves or the opportunity it captures.

== Goals

. First concrete objective
. Second concrete objective
. Third concrete objective

== Current State

What has been accomplished. Where the project stands today.

== Next Steps

* [ ] First actionable task with clear done condition
* [ ] Second actionable task
* [ ] Third actionable task

== Architecture Notes

// OPTIONAL -- include only if architecture is relevant
// MUST contain a diagram or TODO for a diagram

== Related Documentation

* xref:projects/<category>/<slug>/index.adoc[Full Project Documentation]
* xref:infra-ops::runbooks/<related>.adoc[Related Runbook]

Compliance Checklist

# Check Result

1

Document header includes = Title, :description:, :navtitle:, :icons: font

PASS / FAIL

2

Entry begins with [.lead] paragraph

PASS / FAIL

3

Status uses controlled vocabulary (8 permitted values only)

PASS / FAIL

4

Category matches one of the 12 portfolio categories

PASS / FAIL

5

All required sections present: Premise, Goals, Current State, Next Steps

PASS / FAIL

6

Next Steps uses [ ] checklist format with actionable items

PASS / FAIL

7

Architecture Notes (if present) includes diagram or diagram TODO

PASS / FAIL

8

No :toc: attributes in any file

PASS / FAIL

Related