Product Organization (PO)

Constants, conventions, and protocols for Plane MCP (plane-lightcraft), Outline MCP (outline), and local specs.

Load this skill when working with Plane URLs, modules, work items, cycles, or Outline spec docs.

Plane Constants

WORKSPACE_SLUG:  lightcraft
PROJECT_ID:      b1e09911-9cc1-49b8-ad8f-5d55e3dafd16
PROJECT_IDENTIFIER: SPARK
BASE_URL:        https://plane.jimbui.dev

Members

Work Item States

Module Statuses

backlog → planned (/p) → in-progress (/s) → completed (/pp) | paused | cancelled

Outline Constants

OUTLINE_BASE_URL:       https://outline.jimbui.dev
SPARK_ROOT_DOC_ID:      0e3ffc06-c0b6-47e5-9821-b589d9eb4ec2
SPARK_ROOT_DOC_SLUG:    spark-FqVd5fkaAU
COLLECTION_ID:          3f608f3f-1137-4ec7-b1e8-b9ae98f57633  (LightCraft)

Local Spec Conventions

Specs live locally in docs/Spark/{path}/spec.md. MCP sync happens only during /pp.

Path Derivation

Module name → local path: strip trailing :, split by : , join as directory segments.

Module: "Navigation: Nav Bar:"
Path:   docs/Spark/Navigation/Nav Bar/spec.md

Module: "Infrastructure: Cloudflare: R2:"
Path:   docs/Spark/Infrastructure/Cloudflare/R2/spec.md

YAML Frontmatter

---
module_id: {uuid}              # Set by /pp (Plane module UUID)
outline_doc_id: {uuid}         # Set by /pp (Outline doc UUID)
module_name: "Scope: Sub-scope:"
version: 1                     # Bumped by /p EXTEND
status: planning|completed
---

• •module_id and outline_doc_id are empty until first /pp publish
• •version starts at 1, incremented by /p EXTEND
• •status: planning during /p, completed after /pp

Workflow

/p (local only) → /s (local only) → /pp (sync gateway) → /p EXTEND (local only) → ...

• •/p and /s never call MCP — all reads/writes are local
• •/pp is the only command that touches Plane and Outline

URL Parsing

Pattern: {BASE_URL}/{WORKSPACE_SLUG}/projects/{project_id}/{resource_type}/{resource_id}/

Split path by / → extract project_id, resource type (modules|cycles|work-items), resource UUID.

Module Conventions

Naming: "Scope: Sub-scope:" — trailing colon required. Examples: SSO:, Spark Shot: Timeline:

Creation by /pp: name (convention above), start_date: spec created date, lead: default assignee UUID, status: "completed", description: outline_doc_id: {UUID}

Dates: /pp sets both start_date (from spec) and target_date (publish date).

Warning: update_module rejects members field (HTTP 400) — use lead only.

Work Item Conventions

Naming: Version-prefixed phases.

• •Parents: "Scope: {ver}.{phase} - {Name}" (e.g., "Nav Bar: 1.A - Branding & Layout")
• •Children: "Scope: {ver}.{phase} - {Name}: {Task}" (e.g., "Nav Bar: 1.A - Branding & Layout: Replace logo")

Where Scope = last segment of module name (e.g., "Nav Bar" from "Navigation: Nav Bar:").

Phase naming in specs:

### Phase {ver}.{letter}: {Name}
- [ ] {ver}.{letter}.{number} - {Task}

Creation by /pp: All items created in Done state (implementation already complete). start_date: spec created date, target_date: publish date.

Must add to module via add_work_items_to_module AND cycle via add_work_items_to_cycle.

ID format in specs: SPARK-N (uuid) — appended after creation, archived in version sub-docs.

State transitions (/s): Start → In Progress + start_date today. Complete → Done + target_date today. Move ALL phase sub-items at once.

Cycle Conventions

Naming: "YYYY/WW" (ISO week). Range: Sunday 00:00:01 UTC → Saturday 23:59:00 UTC.

Auto-creation: Calculate current week → check existing cycles → create if missing with owned_by (not lead), end_date (not target_date). Cycle dates cannot be in the past.

Outline Spec Storage

Primary spec storage is local (docs/Spark/). Outline holds the published foundation and version sub-docs.

Doc Hierarchy

Module name segments map to nested Outline docs under Spark root:

Module: "Spark Shot: Nav Bar:"
Spark (root) → Spark Shot (intermediate) → Nav Bar (leaf — foundation here)

Doc Registry

Spark root doc has a registry table between <!-- doc-registry --> markers:

| Scope | Doc ID |
|---|---|
| Spark Shot | abc-123 |
| Spark Shot: Nav Bar | def-456 |

On creation (/pp): Split module name by : → check registry for each segment → create missing docs with correct parentDocumentId → add entries to registry.

On lookup: Read Spark root → parse registry → get doc ID. Never use search_documents for hierarchy resolution.

Version Sub-Docs

Created by /pp as children of the spec doc on Outline.

Title: v{N}: {summary title}

Content:

## Summary
- [3-5 bullet points of what was implemented]

---

## Planning Archive

[Full implementation phases, user journeys, technical design from this version]
[SPARK-N (uuid) IDs embedded in checkbox lines]

Each version (1, 2, 3...) gets its own sub-doc. Used by /po NN release notes.

Release Notes (/po NN)

Generate cycle release notes. Triggered by /po NN where NN is ISO week number.

Protocol

1. •Determine cycle: {currentYear}/{NN} (e.g., 2026/06)
2. •List cycle work items via MCP
3. •Group items by module (from module assignment)
4. •For each module:
   • •Find version sub-doc(s) from Outline (children of spec doc)
   • •Extract Summary section
5. •Generate release notes doc on Outline:
   • •Title: Release Notes: {YYYY}/W{NN}
   • •Content: module summaries grouped by module name
6. •Return Outline doc URL
7. •No Slack messages

Template

# Release Notes: {YYYY}/W{NN}

## {Module Name}
**v{N}: {title}**
- summary bullet
- summary bullet

## {Module Name}
**v{N}: {title}**
- summary bullet

MCP Tool Loading

Load tools via ToolSearch("select:mcp__plane-lightcraft__<name>") or ToolSearch("select:mcp__outline__<name>").

Plane: retrieve_module, update_module, create_module, list_module_work_items, create_work_item, update_work_item, add_work_items_to_module, add_work_items_to_cycle, list_cycles, create_cycle, list_states

Outline: read_document, update_document, create_document, get_document_id_from_title, search_documents

API Quirks

• •update_module rejects members — HTTP 400
• •retrieve_project_page / retrieve_workspace_page — 404 (broken). Use module description instead.
• •create_cycle uses end_date (not target_date) and owned_by (not lead)
• •Cycle dates cannot be in the past
• •Sibling MCP calls cascade-fail — if one parallel call fails, retry individually

Common Mistakes

• •Writing spec content to Outline directly instead of local docs/Spark/ first
• •Using old Phase X naming instead of {ver}.{phase} format
• •Missing module/cycle assignment on new work items
• •Using Backlog instead of Todo (or Done for /pp) for new items
• •Forgetting to update Spark root doc registry when creating new Outline docs
• •Hardcoding state/user IDs instead of referencing this skill's constants
• •Creating Plane work items during /p (only /pp creates them)
• •Calling MCP during /s (all updates are local)