{
  "projectName": "MyProject",
  "mypkaPath": { "<hostname-short>": "/abs/path/to/myPKA" },
  "inboxSubdir": "Team Inbox",
  "dropPrefix": "myproject-project-updates",
  "sourcesOfTruth": {
    "tasks": "TODO.md",
    "journal": "journal/sessions/"
  }
}

# myPKA Drop

This skill sends **operational project updates** from the current working repo into
**myPKA** (a personal-knowledge vault, e.g. Obsidian) as a one-way Team Inbox
*drop*.

**Core stance — one-way and shallow.** Updates flow *out* of this repo into the
myPKA inbox. myPKA never reaches back into this repo, and its copy of anything is
never treated as canonical — this repo is always the source of truth for its own
facts. We hold **no knowledge of myPKA beyond its location (path + inbox) and the
drop template**; where each item ultimately gets filed is myPKA's job, not ours.

## When to use

Trigger when the user:
- Explicitly asks to send updates: "inbox this", "push to myPKA", "send updates to
  PKA", "send this to Larry", "drop an update". Treat Larry only as a trigger
  phrase for the default myPKA manager; do not configure or route anything about
  Larry.
- Signals the end of a working session (pattern-match intent, not literal strings):
  "we're done [for today]", "done with the session", "close the session", "wrap
  up", "let's stop here". On session close, also write the local session log first
  (see **Session close** below), then generate the drop.

If no project config is present (see next section), say so and ask the user to
create one rather than guessing paths.

## Configuration (per project)

Read the project's config to resolve everything project-specific. Look for, in
order of preference:
1. `.agents/mypka.config.json` — **preferred**. `.agents/` is the conventional
   cross-agent config dir (the same place skills themselves install), so myPKA
   config sits with other agent settings instead of cluttering the repo root.
2. `mypka.config.json` at the repo root — if you'd rather keep it top-level.
3. A `[mypka]` section in the repo's `AGENTS.md` or `CLAUDE.md`.

The config carries only *where* the drop goes and *what this repo is made of* —
nothing about how myPKA works internally. Expected shape (see
`references/config.example.json`):

```json
{
  "projectName": "MyProject",
  "mypkaPath": { "<hostname-short>": "/abs/path/to/myPKA" },
  "inboxSubdir": "Team Inbox",
  "dropPrefix": "myproject-project-updates",
  "sourcesOfTruth": {
    "tasks": "TODO.md",
    "journal": "journal/sessions/"
  }
}
```

`sourcesOfTruth` is an **open map** — `tasks` and `journal` are the common keys;
add any project-specific records the drop should draw from (e.g. a product
catalog, a CHANGELOG) and omit keys that don't apply.

**Resolving the myPKA path (per machine).** Paths differ per computer. Take them
from `mypkaPath`, matching the current short hostname (`hostname -s`). If the host
isn't listed, **ask rather than guess** — do not invent a path.

## How an update flows

The myPKA inbox accepts plain-markdown drops; myPKA files them later. You never
reach into myPKA's structure or import the drop yourself.

1. **Fill the template from real workspace records only.** Use the configured
   `sourcesOfTruth` and the actual decisions made this session. Never fabricate —
   an empty section is simply omitted.
2. **Write the drop** to
   `<mypkaPath>/<inboxSubdir>/<dropPrefix>-YYYY-MM-DD-HHMM.md`.
3. **Hand off.** Tell the user the drop is in the inbox. myPKA ingests it
   downstream when the user processes the inbox — out of scope here. The drop is
   the dry run; there is no local preview/approval step — write it and report.

This repo only ever writes the drop file into the inbox. Never write anywhere else
in myPKA, and never read or depend on its internal structure.

## The two streams: the why vs. the what

Every drop separates two kinds of information. This split is the whole point —
capturing the *why* at the moment it happens is what's lost if only the
operational record survives.

- **Context → journal.** Reasoning, decisions, tradeoffs, what was uncertain.
- **Changes / Tasks / About → project page.** Operational facts, the task mirror,
  durable project info.

## Rules (carry these into every drop)

- **We classify, myPKA routes.** Label each item by what it *is* (context /
  changes / tasks / project facts). Where it gets filed — journal, project page,
  topic, goal — is myPKA's call. Do not prescribe destination files or reach into
  its structure.
- **Omit empty sections — no filler.** A section is simply absent when there's
  nothing to say. Never emit "_(nothing this update)_" or "_(no change)_".
- **Context is reasoning, drawn from real decisions.** Capture *why* X over Y, the
  tradeoff weighed, what's still uncertain — from decisions actually made or
  discussed. Never invent a motive to fill space.
- **Decision rationale goes in Context, not Tasks.** A task keeps the actionable
  item plus a light concept tag; the tradeoff behind it belongs in Context.
- **Altitude: operational + concept-level.** The user reasons about technical
  *decisions* in myPKA, then implements in this repo. Name the approach and the
  trade-off (e.g. "displacement maps", "CV-based workflow", "ported to Go"). Keep
  out implementation minutiae: IDs, file paths, function names, commit hashes,
  exact commands.
- **Tasks are a one-way mirror.** The repo's tasks file is the single source of
  truth; the drop's task list is a flagged snapshot, not myPKA's authoritative
  list. Mirror operationally meaningful tasks; keep pure dev-internal chores out.
- **About the project is conditional.** Include it only on **first import** (the
  project page has no real overview — send the full overview; the description line
  states the prior state) or on a **material change** to the project itself (send
  only the changed facts; the description line names the change). Otherwise omit
  it. No state file — read the current project page to decide. The description line
  always does real work and is never filler.
- **Real data only.** Generated from workspace records, never invented.

## The drop template

The exact markdown written to the inbox lives in
[`references/inbox-template.md`](references/inbox-template.md). Fill its
placeholders from real records and apply the omit-empty rules above. Keep the
template editable as its own file so the user can tune what myPKA receives — and
retune it if myPKA mis-files something — without touching this skill's instructions.

## Session close

When the user signals end-of-session, run **both** steps from real records only:

1. **Local session log.** Create/append the project's session journal (per
   `sourcesOfTruth.journal`, e.g. `journal/sessions/YYYY-MM-DD.md`) with what
   happened, decisions made, and next steps.
2. **myPKA drop.** Generate the inbox drop per the flow above. Omit-empty rules
   apply, so a light session yields a small drop — and if nothing material
   happened, no drop at all. Always write the drop without pausing for content
   review; the user ingests it downstream in myPKA.

Both are best-effort and use real workspace records only — never fabricate to fill
a section.

{
  "_comment": "Per-project config for the mypka-drop skill (github.com/c11dev/agents). Tells the skill only WHERE the drop goes and WHAT this repo is made of — nothing about how myPKA works internally. Copy to `.agents/mypka.config.json` (preferred) or the repo root as `mypka.config.json`, then fill in.",

  "projectName": "MyProject",

  "_mypkaPath": "Per-hostname (`hostname -s`) absolute path to the myPKA vault. Same vault, different path per machine. If the current host isn't listed, the skill asks rather than guessing. Add a block per machine you work on.",
  "mypkaPath": {
    "myhost": "/Users/myuser/Obsidian/myPKA"
  },

  "_inboxSubdir": "Folder inside myPKA that accepts drops. The only place this skill ever writes.",
  "inboxSubdir": "Team Inbox",

  "_dropPrefix": "Filename prefix for drops. Final name: <dropPrefix>-YYYY-MM-DD-HHMM.md",
  "dropPrefix": "myproject-project-updates",

  "_sourcesOfTruth": "Repo-relative paths the drop is generated FROM — real records only. An OPEN map: `tasks` and `journal` are the common keys; add any project-specific records the drop should draw from (e.g. a product catalog, a CHANGELOG) and omit keys that don't apply.",
  "sourcesOfTruth": {
    "tasks": "TODO.md",
    "journal": "journal/sessions/"
  }
}

# Inbox drop template

This is the **template** the agent fills in to send project updates to myPKA's
Team Inbox. The `SKILL.md` holds the rules; this file is the literal markdown that
gets written. Tune this file to change what myPKA receives — it's intentionally
separate from `SKILL.md` so the format can be retuned (e.g. if myPKA mis-files
something) without touching the skill's instructions.

## How it's used
1. Resolve the myPKA path from the project config (`hostname -s` → `mypkaPath`).
2. Fill the template **from real workspace records only** (the configured
   `sourcesOfTruth` and the actual decisions made this session). Never fabricate.
   **Include a section only if it has something to say — omit empty sections
   entirely (no "nothing this update" / "no change" filler).**
3. Write the result to `<mypkaPath>/<inboxSubdir>/<dropPrefix>-YYYY-MM-DD-HHMM.md`.
   Import is **manual** in myPKA, so the drop just sits there until the user
   processes it ("process the inbox") — the drop itself is the dry run.

## The two-stream split (the point of this template)
Every drop separates **the why** from **the what**:
- **Context → journal.** Reasoning, decisions, tradeoffs, what felt uncertain —
  the stuff lost if you only keep the operational record.
- **Changes / Tasks / About → project page.** Operational facts, the task mirror,
  durable project info.

(Full rules live in `SKILL.md`: classify-don't-route, omit-empty, decision
rationale in Context not Tasks, altitude, one-way task mirror, conditional About.)

---
## TEMPLATE (everything below the line is what gets written to the inbox)
## Include only the sections that apply; the About variants are alternatives.
---

# {{PROJECT_NAME}} Project Update — {{DATETIME_ISO}}

<!-- {{DATETIME_ISO}}: ISO 8601, local time, e.g. 2026-06-06T14:30 (add the
     timezone offset, e.g. 2026-06-06T14:30-07:00, if myPKA spans zones).
     Use ISO — this drop is parsed by an agent and the source filename (which
     carries the date) is deleted once filed, so the in-body date must stand
     alone, be unambiguous, and sort correctly. -->


> Inbox drop from the {{PROJECT_NAME}} project — a separate repo myPKA tracks at
> a high level. File each section wherever it belongs per your usual conventions:
> **Context** is reasoning for the journal; **Changes / Tasks / About** are
> project-page material. Delete this file once filed.

## Context
_The why: decisions, tradeoffs, what was uncertain — journal material._
{{REASONING as bullets}}

## Changes
_The what: operational facts of what changed._
{{CHANGES as bullets}}

## Tasks
_Snapshot mirrored from the {{PROJECT_NAME}} repo (that repo is the source of
truth) — a reference for what's done / pending, not your authoritative task list._
**Completed since last update**
{{COMPLETED_TASKS as checklist}}
**Outstanding**
{{OUTSTANDING_TASKS as checklist}}

## About the project
<!-- First import (page empty/thin): full overview. Description states prior state. -->
_Initial overview — project page was empty._
{{FULL_OVERVIEW: what it is, main components, pipeline, light "how it's built", status}}

<!-- OR, material change only: -->
_Changed: {{WHAT_CHANGED}}._
{{ONLY_THE_CHANGED_FACTS}}