mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-16 10:50:38 +09:00
508355b8fc
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - The plugin system is the extension surface for optional product capabilities without baking every workflow into core. > - The LLM Wiki plugin package was reviewed in stacked PR #5592, which targeted `pap-9173-llm-wiki-rest`. > - The stack base PR #5597 merged to `master` before #5592 was merged into that branch, so the plugin package never reached `master`. > - A direct PR from `pap-9173-llm-wiki-rest` back to `master` would be noisy because that branch has diverged from current `master`. > - This pull request reapplies the reviewed `packages/plugins/plugin-llm-wiki/` package onto current `master` and updates Docker deps-stage manifest coverage. > - The branch intentionally no longer changes `pnpm-workspace.yaml` after maintainer feedback; because the new package is now a root workspace importer, the remaining integration question is how maintainers want the root lockfile handled under the current PR policy. ## What Changed - Added the LLM Wiki plugin package under `packages/plugins/plugin-llm-wiki/` from the merged PR #5592 head. - Preserved the post-review cleanup from #5592: generated design/screenshot artifacts are not committed, and `src/ui/index.tsx` / `src/wiki.ts` are small public entrypoints. - Added the new plugin package manifest to the Docker deps stage so policy can validate package manifest coverage. - Removed the earlier `pnpm-workspace.yaml` exclusion per maintainer request, so the plugin is included by the existing `packages/plugins/*` workspace glob. ## Verification Current head: - PGlite migration harness: ran migrations 001-003, verified old non-space distillation unique constraints were removed, inserted duplicate cursor and work-item keys in a second space, then reran migration 003 successfully - `node ./scripts/check-docker-deps-stage.mjs` - `git diff --check` Known current-head install result after removing the workspace exclusion: - `pnpm install --frozen-lockfile` fails because `pnpm-lock.yaml` has no importer for `packages/plugins/plugin-llm-wiki/package.json`. Previously verified on the same plugin source before the workspace-exclusion removal: - `pnpm --filter @paperclipai/plugin-sdk build` - `cd packages/plugins/plugin-llm-wiki && pnpm install --lockfile=false && pnpm test` ## Risks - The branch now includes `packages/plugins/plugin-llm-wiki` in the root workspace but does not update `pnpm-lock.yaml`. Root frozen install will fail until maintainers choose a lockfile path that fits repo policy. - Committing `pnpm-lock.yaml` directly on this PR conflicts with the current PR policy check, while excluding the package from `pnpm-workspace.yaml` was rejected in maintainer feedback. - The package includes UI code already reviewed in #5592; generated screenshot/design artifacts were intentionally removed per maintainer request, so visual review should regenerate screenshots locally if needed. - The package depends on plugin host support from #5597, which is already merged to `master`. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI GPT-5 Codex via Codex CLI, tool use and local code execution enabled; context window not exposed. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run the targeted checks listed above - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge Stack context: #5592 was merged into `pap-9173-llm-wiki-rest` after #5597 had already merged that branch to `master`, so this follow-up PR is needed to carry the plugin package itself into `master`. Co-authored-by: Paperclip <noreply@paperclip.ing>
125 lines
11 KiB
Markdown
125 lines
11 KiB
Markdown
---
|
||
name: paperclip-distill
|
||
description: Use when an operation issue is a Paperclip cursor-window, distill, or backfill — `operationType: "distill"` or `"backfill"` and the body references a Paperclip source bundle for a project or root issue. Turn raw Paperclip activity into a wiki-insightful project page, decisions log, and history note. This skill exists specifically to replace the stiff, datestamp-heavy templated output that the deterministic distiller produces.
|
||
---
|
||
|
||
# Paperclip Distill
|
||
|
||
Distill Paperclip project, issue, comment, and document activity into durable wiki pages. The success criterion is **wiki-insightful, not procedural**: a reader who has never seen Paperclip should learn what the project is, what was decided, what is at risk, and what the current state is — without scanning a list of `## [YYYY-MM-DD]` headers.
|
||
|
||
## When this skill is needed
|
||
|
||
- Cursor-window distillation: the routine fed you a bounded source bundle of recent Paperclip activity for one project or root issue.
|
||
- Backfill: the user asked to seed the wiki with the historical activity of a project or root issue. Source window may be wide.
|
||
- Manual `distill-paperclip-now` request from the UI.
|
||
|
||
If the operation issue is `operationType: "ingest"` (raw file) or `operationType: "query"`, this is the wrong skill — use `wiki-ingest` or `wiki-query`.
|
||
|
||
## Destination space
|
||
|
||
In Phase 1, every Paperclip distill, backfill, and cursor-window operation writes into the
|
||
default wiki space. The operation issue should always carry `spaceSlug: "default"`. If an
|
||
operation issue passes any other slug, stop and surface the mismatch in a comment — do not
|
||
write Paperclip-derived pages into a non-default space.
|
||
|
||
This rule is destination-only. The Paperclip source scope (which projects, root issues,
|
||
comments, documents are read) is set elsewhere in the operation issue and is independent of
|
||
the destination.
|
||
|
||
## Inputs
|
||
|
||
- A Paperclip source bundle (issue list, comment refs, document refs, source hash, cursor window).
|
||
- An existing or planned `wiki/projects/<slug>/standup.md` page path.
|
||
- An existing or planned `wiki/projects/<slug>/index.md` page path.
|
||
- The operation issue's target `wikiId`, `spaceSlug`, space root, and the target space's `AGENTS.md` for page conventions.
|
||
- The current `wiki/projects/<slug>/standup.md`, `wiki/projects/<slug>/index.md`, `decisions.md`, and `history.md` if they already exist (so you write a *patch*, not a rewrite).
|
||
|
||
## Paperclip Asset Gate
|
||
|
||
Do not treat Paperclip assets/attachments or issue work products as source text for this skill.
|
||
|
||
- Allowed Paperclip body text: issue descriptions, comment bodies, document bodies.
|
||
- Assets/attachments are metadata-only until a separate approved extraction policy exists.
|
||
- Work products are metadata-only until a separate approved extraction policy exists.
|
||
- Never fetch `/api/assets/:id/content`.
|
||
- Never dereference a work-product `url`, preview URL, artifact URL, or other linked destination from this skill.
|
||
- If an operator asks for attachment/work-product content distillation, stop and point them at the Phase 5 asset/work-product security gate policy instead of improvising.
|
||
|
||
## Anti-patterns to avoid
|
||
|
||
The deterministic templating this skill replaces produced these failure modes — do not reproduce them:
|
||
|
||
1. **Datestamp-as-section-header.** Lines like `## [2026-04-15] paperclip-distill | proposed` belong in `wiki/log.md`, not in the project page. The project page is durable knowledge; the log is the audit trail.
|
||
2. **Procedural status lists.** `Issue mix: 3 todo, 5 in_progress, 2 done` tells the reader nothing they could not read off Paperclip directly. State *what is happening and why it matters*, then cite the issues that constitute the evidence.
|
||
3. **One-line-per-issue dumps.** A page that is mostly `- PAP-1234: title (in_progress, updated 2026-...)` is an issue list, not a wiki page. Group issues by what they are *about* (a decision, a risk, a workstream) and cite multiple issues per bullet when they share a story.
|
||
4. **Mechanical "Current as of" timestamps everywhere.** One `current_as_of` in frontmatter is enough.
|
||
5. **No interpretation.** "Active issues: PAP-A, PAP-B, PAP-C" is bookkeeping. "The team is concentrating on the schema migration ([PAP-A], [PAP-B]) and has parked the index work pending capacity ([PAP-C])." is wiki-insightful.
|
||
6. **Opaque identifiers in prose.** UUIDs, cursor ids, source hashes, run ids, and raw metadata belong in logs or frontmatter when needed, not in executive-facing project narrative.
|
||
|
||
## Workflow
|
||
|
||
1. **Read the bundle in full.** Don't sample. Read every issue title, every comment, every document key the bundle includes. Note: which issues are decisions, which are risks/blockers, which are recently completed, which are inflight.
|
||
2. **Read the existing project page** (if any) so you write a patch, not a rewrite. The "Decisions" section in particular accumulates over time — never wipe accepted decisions; supersede them with `> ⚠ reversed by ...` callouts when something later overrides them.
|
||
3. **Read the target space's `AGENTS.md`** for page conventions: filename style, YAML frontmatter shape, link style, voice. Always pass the operation issue's `wikiId` and `spaceSlug` to LLM Wiki tools.
|
||
4. **Write `wiki/projects/<slug>/standup.md` first.** Every Paperclip project represented in the wiki must have this file. It is the executive standup: where the project stands today, what changed recently, what is blocked or risky, and what happens next. Use stable sections, in this order:
|
||
- Frontmatter (`type: project-standup`, `project: <slug>`, `current_as_of: YYYY-MM-DD`, `sources`).
|
||
- **Executive Readout** — one short paragraph that explains the current project posture in plain language.
|
||
- **What Changed** — the meaningful work completed or advanced since the last window. Group by concept; cite issues/comments/documents only as evidence.
|
||
- **Decisions** — accepted/rejected/reversed decisions that changed the project direction. Omit when none exist.
|
||
- **Blockers / Risks** — current blockers and risks with named owner or next action when the source provides one.
|
||
- **Next Actions** — concrete next actions and owners inferred from Paperclip issues, not vague aspirations.
|
||
- **Links** — durable wiki project page and relevant Paperclip project/issues/documents.
|
||
Rewrite the standup to today's state. Do not append endless dated sections; the audit trail belongs in `wiki/log.md` and Paperclip comments.
|
||
5. **Write `wiki/projects/<slug>/index.md`** with these stable sections, in this order:
|
||
- Frontmatter (`type: project`, `current_as_of: YYYY-MM-DD`, `tags`, `sources`).
|
||
- **Overview** — 2–4 sentences saying what the project is and why it exists. Use the project description if it exists; otherwise synthesise it from the root issue.
|
||
- **Current Direction** — narrative paragraph naming the active workstreams, the immediate next concrete deliverable, and the stance on risks. Cite 2–4 issues, do not list 20.
|
||
- **Workstreams** — a short, grouped list. Each line is a workstream or idea, not an issue.
|
||
- **Decisions** — accepted and reversed decisions with one paragraph each. Each decision cites the issue / approval / comment that ratified it. Format: `### Decision — short title` then a paragraph; never a bare bullet list.
|
||
- **Open Risks / Blockers** — what could derail the project, with the issue ref that surfaces it. Skip this section when the bundle has no risk signal — do not pad with `_(none)_`.
|
||
- **References** — readable links to the current standup and supporting Paperclip tasks/documents. Keep hashes and cursor ids out of the narrative.
|
||
6. **Optionally write `wiki/projects/<slug>/decisions.md`** when the project has accumulated more decisions than the project page can carry without becoming a wall of text. Each decision is a `## ` section with: short title, accepted/reversed/superseded status, one-paragraph rationale, citing the source. *Do not* duplicate decisions already on the project page — link instead.
|
||
7. **Optionally write `wiki/projects/<slug>/history.md`** for a compact narrative timeline of meaningful project changes. **Not** an issue dump — group by phase ("Discovery", "Architecture", "Build", "Stabilisation"), not by date. Each phase is a paragraph that cites the 2–4 issues that defined it.
|
||
8. **Refresh `wiki/index.md`** under the `## Projects` section — one line per durable project page with a one-sentence summary of the project's purpose, plus a link to the current `wiki/projects/<slug>/standup.md` when present.
|
||
9. **Append `wiki/log.md`** entry — this is where the datestamp belongs:
|
||
```
|
||
## [YYYY-MM-DD] paperclip-distill | <project name>
|
||
- standup: wiki/projects/<slug>/standup.md
|
||
- page: wiki/projects/<slug>/index.md
|
||
- source hash: `<hash>`
|
||
- cursor window: <start> → <end>
|
||
- notes: <one line on what changed in this distill, e.g. "decisions section grew with PAP-X reversal", "low-signal window, no page changes">
|
||
```
|
||
10. **Surface bundle warnings** (clipped sources, low signal, stale hash). Bundle warnings → `human_review_required: true` on the patch. Do not paper over them.
|
||
|
||
## Voice
|
||
|
||
- Past-tense for completed work, present-tense for current state, future-tense only with citation ("the team plans to … per [[…]]").
|
||
- Cite Paperclip source refs inline using their issue identifier (e.g. `PAP-3179`), not opaque UUIDs.
|
||
- Use issue links as evidence, not as the shape of the page. Headings and paragraphs should be organized by concepts, workstreams, decisions, and blockers.
|
||
- Wiki voice: terse, factual, neutral. No "the team is excited to" or "this initiative aims to".
|
||
- Headings are about *content*, not metadata. `## Schema migration` not `## Active Issues`.
|
||
|
||
## When the bundle has no signal
|
||
|
||
If the bundle has no durable signal — no decisions, no risk, no completed work, only routine status churn — do **not** write a project page. Instead:
|
||
|
||
- Append a `paperclip-distill | low-signal skip` log entry naming the cursor window.
|
||
- Close the operation issue with a one-line "no durable change in this window" comment.
|
||
- Do not bump the source hash on a binding that has no proposed page.
|
||
|
||
## Verification
|
||
|
||
Before closing the operation issue:
|
||
|
||
- [ ] The project page reads as wiki content, not as a Paperclip status report. A reader new to the company should understand what the project is.
|
||
- [ ] `wiki/projects/<slug>/standup.md` exists for the represented project and reads as an executive current-state update, not a raw issue dump.
|
||
- [ ] Decisions section names decisions, not issues — every decision has a one-paragraph rationale and a citation.
|
||
- [ ] The page contains exactly one `current_as_of` (in frontmatter), zero `## [YYYY-MM-DD]` headings (those go to the log).
|
||
- [ ] Bundle warnings (clipped, low signal, stale hash) are surfaced; the patch carries `human_review_required: true` when the deployment is authenticated/public.
|
||
- [ ] `wiki/index.md` and `wiki/log.md` are updated.
|
||
- [ ] No file under `raw/` was modified.
|
||
|
||
## Tools
|
||
|
||
`wiki_search`, `wiki_read_page`, `wiki_write_page`, `wiki_list_sources`, `wiki_read_source`. Always include the operation issue's `wikiId` and `spaceSlug`. The Paperclip source bundle arrives as part of the operation context — you do not need to assemble it.
|