Central PM system

# Central PM system

A small Railway-deployed project management app that keeps the flexibility of the `yawp-pm` markdown repo, but removes the Git/repo friction from normal product work.

## Source

Granola meeting: `3fbd5f2d-e409-42bd-b585-fed305edd5cd`, **Summer priorities — assignment types, LMS integration, and reporter**, 2026-05-26 1:31 PM CDT.

The call exposed the core pain: the current repo-based PM workflow is powerful for agents and engineers, but too technical for Kevin/Brian when they just need to ask "what needs work?", update priority, answer an open question, or see whether a feature is in idea, spec, PR, preview, QA, or production.

## Problem

The current product lifecycle is split across two repos:

- `yawp-pm` owns ideas, specs, status tables, bugs, and requirements.
- `yawp-2.0` owns implementation truth: branches, PRs, preview environments, CI, deploy status, and production state.

That split creates friction:

- Specs can drift after a prototype PR exists because the live implementation becomes the effective spec.
- Kevin has to select multiple repos, wait for repo cloning, and sometimes run through Git concepts just to get a status answer.
- Brian/Kevin should not need to know whether a status update came from markdown, GitHub PRs, preview deploy metadata, or a meeting transcript.
- Agents can work with markdown well, but non-technical collaborators need a central app/chat surface that hides the mechanics.

## Goals

- Preserve markdown as the durable, portable source of truth.
- Provide a simple UI for tickets, specs, open questions, PRs, previews, and shipped work.
- Let Bryant, Brian, Kevin, Codex, Claude, and ChatGPT ask/update project status through a central service.
- Sync with `yawp-2.0` so PM status cannot quietly fall behind PR/preview/merge reality.
- Make "what needs my attention?" a first-class view for Brian, Kevin, and Bryant.
- Keep v1 smaller than Linear/Jira/GitHub Issues: purpose-built for Yawp's spec -> prototype -> preview -> review -> ship loop.

## Non-goals

- Replacing `yawp-pm` markdown with an opaque database as the only source of truth.
- Building a full Linear/Jira clone with workflows, sprints, estimates, dependencies, and reporting bloat.
- Making non-technical collaborators resolve Git conflicts.
- Two-way syncing every field with GitHub Issues or Linear in v1.
- Replacing Granola or Google Docs as capture tools; v1 can import/link them as sources.

## Core entities

### Ticket

Represents a feature, bug, research item, prototype, decision, or chore.

Fields:

- `id`
- `title`
- `type`: `feature`, `bug`, `research`, `prototype`, `decision`, `chore`
- `status`: `idea`, `spec-needed`, `planned`, `ready-for-prototype`, `prototype-pr-open`, `preview-ready`, `needs-review`, `needs-qa`, `ready-to-ship`, `shipped`, `blocked`, `parked`
- `priority`
- `owner`
- `reviewers`
- `source_docs`
- `source_meetings`
- `related_prs`
- `related_branches`
- `related_preview_urls`
- `spec_path`
- `open_questions`
- `last_synced_at`
- `staleness_state`

### Spec

The markdown body for requirements, acceptance criteria, domain notes, test plan, rollout plan, and open product questions.

### Prototype

Links a ticket to a `yawp-2.0` PR, branch, preview URL, demo video, QA status, and review state.

### Decision

Captures a product/engineering decision with date, source, affected tickets, and superseded alternatives.

### External source

Records Granola meetings, Google Docs, GitHub PRs/issues, Codex sessions, Slack threads, and pasted notes that informed a ticket/spec.

## Storage model

Markdown remains canonical.

Proposed structure:

```text
tickets/
  YPM-001-central-pm-system.md
  YPM-002-side-by-side-revision.md
decisions/
  2026-05-26-central-pm-system.md
sources/
  granola-3fbd5f2d-e409-42bd-b585-fed305edd5cd.md
```

The Railway app may keep a Postgres cache/index for search, filters, auth sessions, and sync metadata, but the source of truth is still committed markdown unless the team explicitly changes that decision.

## UX sketch

First screen is the working dashboard, not a marketing page.

Views:

- **Now**: active PRs, preview-ready prototypes, blocked work, and items needing Brian/Kevin/Bryant.
- **Backlog**: ideas and specs grouped by priority/readiness.
- **Prototypes**: PRs, preview URLs, demo videos, CI/review state.
- **Questions**: open product/engineering questions waiting on a human answer.
- **Stale specs**: specs where linked PR/code changed after the markdown was updated.
- **Shipped**: recently merged/deployed work with source links.

Each ticket page shows:

- Current status and next action.
- Human-readable spec.
- Linked PRs/previews/videos.
- Open questions with owner.
- Agent handoff block.
- Source references from meetings/docs/chats.

## Agent interface

V1 API:

- `GET /api/status` - compact current project brief.
- `GET /api/tickets` - filterable tickets.
- `GET /api/tickets/:id` - full ticket/spec.
- `PATCH /api/tickets/:id` - controlled metadata/body updates.
- `POST /api/sync/github` - refresh PR/preview/check metadata.
- `GET /api/agent-brief` - markdown context bundle for Codex/Claude/ChatGPT.

Agent handoff format:

```markdown
## Current state
...

## Source links
...

## Open questions
...

## Acceptance criteria
...

## Likely yawp-2.0 files
...

## Next safe action
...
```

The app should make cloud chat usable without requiring Kevin to select both repos manually every session.

## MVP progress

Central Station now exists as a separate app at `The-Connell-School/central-station`.

Current local MVP:

- Imports all `yawp-pm` feature, bug, and archive markdown into a queryable store.
- Preserves original markdown body, front matter, source path, related specs, open questions, PR references, and meeting IDs.
- Seeds recent Granola/Gmail/LMS research source records from the May 26 planning context.
- Syncs `yawp-2.0` PR state through GitHub and creates placeholder tickets for PRs that do not yet map cleanly to PM specs.
- Serves a working dashboard at `/` and agent-readable API endpoints at `/api/status`, `/api/tickets`, `/api/tickets/:id`, and `/api/sources`.
- Accepts controlled ticket updates through `PATCH /api/tickets/:id`, proving agents can update project status without Git commands.

Current imported state:

- 178 tickets total after PM import plus GitHub PR sync.
- 10 source records, including two May 26 Granola meetings, recent Daily Pages/AP History/preview Gmail threads, the disappearing-text customer signal, and LMS official-doc research.
- The Now view surfaces blocked work, in-progress high-priority work, active PRs, and ready-for-engineering specs.

Deployment state:

- Source repo exists: `https://github.com/The-Connell-School/central-station`.
- Railway config exists, but deploy is blocked because local Railway auth returns `invalid_grant` and needs `railway login` refreshed.
- v1 persistence should use a Railway volume mounted at `/data` with `CENTRAL_STATION_DATA_PATH=/data/central-station.json`; Postgres remains the better next step for multi-user durability.

## GitHub sync

Read from `yawp-2.0`:

- PR number, title, state, draft/ready state.
- Branch and author.
- Merge/review/check status.
- Preview deploy URL when available.
- Changed files.
- Labels and linked issue/spec references.
- Updated/merged timestamps.

Derived checks:

- PR exists with no linked PM ticket.
- Ticket says PR-open but no matching PR exists.
- PR updated after spec `updated:` date.
- Preview failed or missing for a prototype-ready PR.
- Merged PR still leaves ticket unshipped.

MVP should be read-only against `yawp-2.0`. Writing labels/comments back to GitHub can follow after the read model is reliable.

## Permissions

Roles:

- `Admin`: Bryant/Brock. Configure repos, sync, auth, and dangerous writes.
- `Product collaborator`: Brian/Kevin. Create/edit specs, change status/priority, answer questions, link videos.
- `Agent`: Codex/Claude/ChatGPT service identity. Read state, propose/update markdown through controlled writes.
- `Read-only`: future stakeholders.

## Open questions

- [ ] Should canonical markdown stay in `yawp-pm`, move inside `yawp-2.0/docs`, or move to a new repo dedicated to the app?
- [ ] Should the app commit directly to `main`, open PM PRs, or write to a database and periodically export markdown?
- [ ] Auth choice for v1: GitHub OAuth, passwordless email, or private app login?
- [ ] Minimum ticket status taxonomy Bryant/Brian/Kevin actually want to see.
- [ ] How aggressive should agent writes be: direct updates, proposed diffs, or "draft until approved"?
- [ ] Should Google Docs remain source material only, or can a Google Doc become canonical for a ticket?
- [ ] Where is preview deploy metadata most reliably available today?

## Implementation shape

Likely stack:

- Railway app.
- Remix/React Router or Next.js, matching Yawp team familiarity.
- Postgres for indexed/cache state.
- GitHub App or fine-scoped token for markdown commits and PR reads.
- Background sync worker for GitHub/preview metadata.
- Markdown/frontmatter parser, not ad hoc string editing.

## Test plan

- Unit: frontmatter parse/serialize round-trips without body loss.
- Unit: ticket status derivation from linked PR metadata.
- Unit: stale-spec detection when PR `updatedAt` is newer than spec `updated`.
- Integration: GitHub sync imports PR metadata and links it to a ticket.
- Integration: markdown write uses optimistic locking and rejects stale updates.
- E2E: Kevin asks "what should I work on?" and sees backlog/preview/open-question items without Git concepts.
- E2E: Bryant updates priority/status in UI and markdown reflects the change.
- E2E: agent updates an open question answer through the API and the ticket view refreshes.

## Rollout

1. Read-only dashboard against existing `yawp-pm` + `yawp-2.0`.
2. Controlled metadata edits: priority, status, owner, open-question answers.
3. Full spec body editing with optimistic locking.
4. Agent API and generated agent briefs.
5. Optional Granola/Google Docs import automation.

## Engineering handoff checklist

- [x] Domain context covered
- [x] File paths in `yawp-2.0` listed
- [x] Data model implications spelled out, including backward-compat plan
- [x] UX sketch in prose
- [x] Edge cases enumerated
- [x] Test plan written
- [x] Rollout plan decided
- [ ] Canonical markdown location decided
- [ ] Auth model decided