# Adapters

How `pm` reads from / writes to each PM tool. Add new adapters here as needed.

Each business board has a `tool` value in `boards.md` that selects one of these adapters.

---

## notion

**Auth:** `$NOTION_API_KEY` (in `~/.zshenv`). No MCP — call API directly. See `reference_notion_api.md` in memory.

**Pattern:** Each business board is a Notion database with these properties:
- `Name` (title)
- `Status` (select: Backlog / Ready / In Progress / Review/Blocked / Done) — defaults; override in `boards.md`
- `Priority` (select: Q1 / Q2 / Q3 / Q4) — Eisenhower quadrant
- `Owner` (people or text)
- `Size` (select: XS / S / M / L)

**Operations:**

```bash
# List cards by column
curl -X POST "https://api.notion.com/v1/databases/<db-id>/query" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"filter":{"property":"Status","select":{"equals":"In Progress"}}}'

# Read one card (page)
curl -X GET "https://api.notion.com/v1/pages/<page-id>" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2022-06-28"

# Move a card to another column
curl -X PATCH "https://api.notion.com/v1/pages/<page-id>" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"properties":{"Status":{"select":{"name":"Ready"}}}}'

# Create a new card
curl -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"parent":{"database_id":"<db-id>"},"properties":{"Name":{"title":[{"text":{"content":"<title>"}}]},"Status":{"select":{"name":"Backlog"}}}}'
```

---

## github

**Auth:** `gh` CLI (already authed). Works for both GitHub Issues and GitHub Projects (v2).

**Pattern A — Issues on a single repo:**

The "board" is the repo's issues filtered by label (e.g., `column:ready`, `column:in-progress`). Or by Project (v2) status field.

```bash
# List issues in a column (label-based)
gh issue list --repo <owner>/<repo> --label "column:ready" --json number,title,labels

# Move (change label)
gh issue edit <num> --repo <owner>/<repo> --remove-label "column:ready" --add-label "column:in-progress"

# Create
gh issue create --repo <owner>/<repo> --title "<title>" --label "column:backlog"
```

**Pattern B — GitHub Projects (v2):**

```bash
# List items in a column (Status field)
gh project item-list <project-number> --owner <owner> --format json

# Move item (set Status field)
gh project item-edit --id <item-id> --field-id <status-field-id> --single-select-option-id <option-id> --project-id <project-id>
```

For Projects v2, the skill needs to discover field IDs once via `gh project field-list` and cache them in `boards.md`.

---

## plane

**Auth:** Plane API key (set as `$PLANE_API_KEY` in `~/.zshenv` if not yet — prompt the user if missing). Workspace slug from `boards.md`.

**Pattern:** Plane has Projects → Modules/Cycles → Issues. The "board" maps to a Plane Project; columns map to Plane "State" values.

```bash
# List issues in a state
curl -X GET "https://api.plane.so/api/v1/workspaces/<workspace>/projects/<project-id>/issues/?state__name=Ready" \
  -H "X-API-Key: $PLANE_API_KEY"

# Move issue (change state)
curl -X PATCH "https://api.plane.so/api/v1/workspaces/<workspace>/projects/<project-id>/issues/<issue-id>/" \
  -H "X-API-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "<state-id-for-In Progress>"}'
```

Note: Plane uses state IDs, not names — discover and cache once per workspace.

---

## linear

**Auth:** Linear MCP if installed, else `$LINEAR_API_KEY`. Prefer MCP when available.

**Pattern:** Each Linear Team or Project maps to a board. Columns map to workflow states.

If using the Linear MCP, the skill calls those tools directly. If using the API:

```bash
curl -X POST "https://api.linear.app/graphql" \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ issues(filter: {team: {key: {eq: \"<team-key>\"}}, state: {name: {eq: \"In Progress\"}}}) { nodes { id title } } }"}'
```

---

## obsidian

**Auth:** none — local files.

**Pattern:** Obsidian Kanban plugin stores boards as markdown files with `## Column Name` headings. Each card is a `- [ ] Card title` bullet under its column.

```
## Backlog
- [ ] Card A
- [ ] Card B

## Ready
- [ ] Card C

## In Progress
- [ ] Card D

## Review/Blocked
- [ ] Card E — blocked on <person>

## Done/Archived
- [x] Card F
```

**Operations:**
- **Read**: `Read` the markdown file at the path in `boards.md`
- **Move**: edit the file — remove card from old column, add under new column
- **Create**: append a bullet under the right column
- **Done**: change `[ ]` to `[x]` and move to Done section

Watch out: Obsidian Kanban supports embedded YAML metadata blocks per card (priority, due, assignee). Preserve them when moving cards.

---

## manual

**Auth:** none.

When no tool is connected (or the user doesn't want one for a particular business), `pm` works in conversation:

1. Ask the user to paste the current board state (or describe verbally)
2. Run the requested mode against that snapshot
3. Output recommended moves as plain text
4. Optionally: persist a snapshot to `${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/pm/boards-cache/<business>.md` so subsequent runs don't require re-pasting (with a clear warning that the cache is stale until next paste) — never inside the skill folder; upgrades wipe it

The cache file uses the same Obsidian-style markdown format above so it's portable.

---

## Adding a new adapter

When the user starts using a new tool (Trello, Jira, Asana, ClickUp, etc.):

1. Add a new section above with: auth method, board structure, list/read/move/create operations
2. Add the tool as a valid value in `boards.md`
3. Test once with a real board before relying on it

# Boards — per-business config (TEMPLATE)

This is the template. Your real board mappings live in `${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/pm/boards.md` — not in this repo. Copy the schema below and populate it there.

One row per business. Populated by `/pm setup [business]` and edited freely.

When the skill targets a business not listed in your local config, it falls back to `manual` mode and prompts setup.

| business | tool | board_id / URL / path | columns (if custom) | WIP override |
|---|---|---|---|---|
| _example_project_a_ | _notion_ | _<db-id>_ | _default_ | _default_ |

_No boards configured yet. Run `/pm setup <business>` to start._

---

## Default columns

If a row doesn't list custom columns, the skill uses:

```
Backlog → Ready → In Progress → Review/Blocked → Done/Archived
```

## Default WIP

```
In Progress: 3
Review/Blocked: no cap (flag at 5+)
Ready: soft cap 10
```

## Cross-portfolio WIP

Max **5 In Progress** across all boards combined. Above that, `/pm next` (cross-board) recommends finishing something before pulling new work.

# Methodology — kanban + Eisenhower + async

## Kanban core

### Why kanban

- **Make work visible.** Cards on columns. Nothing hidden in someone's head.
- **Pull, don't push.** Only start new work when capacity opens — finishing > starting.
- **Limit WIP.** Multitasking is the most reliable way to ship nothing. Cap In Progress.
- **Flow over batch.** Small cards moving steadily beats heroic sprints.
- **Inspect and adapt.** Look at flow weekly. If cards pile up in one column, that's the constraint.

### The 5-column flow (the user's default)

```
Backlog  →  Ready  →  In Progress  →  Review/Blocked  →  Done/Archived
```

- **Backlog**: everything that *might* matter. Wide net. No commitment yet.
- **Ready**: triaged. Well-defined enough that anyone could pick it up. Has acceptance criteria.
- **In Progress**: actively being worked. Strict WIP limit.
- **Review/Blocked**: waiting on someone or something external. Should be the shortest-lived state — if a card lives here >5 days, escalate or kill.
- **Done/Archived**: shipped or explicitly killed. Archived weekly.

### Card hygiene

A good card has:
- **Title** — verb-first ("Ship waitlist email" not "Waitlist email")
- **Acceptance criteria** — what does "done" look like? 1–3 bullets.
- **Owner** — even for solo projects: which "hat" is wearing this?
- **Size** — XS / S / M / L (XS = <2 hrs, S = <1 day, M = 2–3 days, L = >1 week — break it down)

Cards that don't meet hygiene live in Backlog, not Ready.

## Eisenhower matrix — the prioritization overlay

```
                    Urgent          Not Urgent
Important           Q1: Do          Q2: Schedule
Not Important       Q3: Delegate    Q4: Delete
```

### Quadrant rules

- **Q1 — Urgent + Important.** Do it. Move to Ready (or In Progress if capacity). These earn priority within Ready.
- **Q2 — Important, Not Urgent.** *This is where leverage lives.* Schedule it. Most Q2 items become Q1 emergencies if neglected — proactively pulling Q2 is the difference between operators who compound and ones who firefight.
- **Q3 — Urgent, Not Important.** Delegate. If there's nobody to delegate to (solo project), ask: is this actually important and I'm mislabeling it, or is it actually noise I'm letting trick me?
- **Q4 — Not Urgent, Not Important.** Archive. The hardest skill in PM is closing tabs.

### When to apply Eisenhower

1. **During Backlog triage** — sort Backlog into Q1/Q2/Q3/Q4; Q1+Q2 candidates move to Ready, Q3 gets delegated or noted, Q4 gets archived.
2. **When picking next from Ready** — within Ready, Q1 > Q2 > Q3.
3. **During weekly planning** — bias next week's pull toward Q2 (preventative + high-leverage).

### Common Eisenhower mistakes

- **Mislabeling Q3 as Q1.** "Urgent" feels urgent because someone else made it urgent. Test: would this matter if you didn't do it for a week?
- **Q4 sneaking into Ready as "easy wins."** If it's not important, the only thing easy about it is the time it takes from Q2 work.
- **Endless Q2.** Q2 is great in moderation. Too many Q2 cards in Ready = the board is wishful thinking, not a commitment. Cap Q2 cards in Ready at ~5 per board.

## Async-first

You're likely running multiple businesses with partners and async clients. Async-first PM means:

1. **Status visible without you.** Anyone should be able to look at the board and know where things stand. No "let me catch you up" calls.
2. **Decisions documented.** When a card moves between columns, the why is in the card or a comment. Compose with `/decide` for big calls.
3. **Cards read like messages.** Title = headline. Body = what a colleague would need to pick this up cold. No "see Slack thread" — link the thread *and* summarize.
4. **Status updates are written, not spoken.** Use the `/pm status` output format. Send a Slack message. Don't call.
5. **Reduce back-and-forth.** Every card has owner + acceptance criteria so reviewers don't ping you to ask "what should I check for."

## Cross-portfolio prioritization

When you have N businesses each with their own kanban, the meta-decision is "which board should I work in today?"

Heuristics, in order:

1. **Q1 across all boards first.** Even a Q2 on a hot business loses to a Q1 on a quieter one.
2. **Then: revenue or strategic lever.** Among Q2 items across boards, pull from the business with the most leverage right now.
3. **Then: momentum tax.** If a business has gone 14+ days without progress, prioritize ANY card there. Drift kills compound businesses faster than slow execution.
4. **Then: energy fit.** If two cards are tied, pick the one that matches your current state. Morning analytical brain ≠ end-of-day creative brain.

## WIP limits — recommended defaults

Per business board (override per business in `boards.md`):

| Column | Default WIP |
|---|---|
| In Progress | **3** (max) |
| Review/Blocked | no cap, but flag at 5+ |
| Ready | soft cap at 10 — more than that means you're hoarding, not committing |

Cross-portfolio: across all businesses, **don't exceed 5 In-Progress total**. Each business burns context-switch tax; more than 5 means you're not really In Progress anywhere.