From 884cda85b692ed3732b9863d0cd87b75d47e9329 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Sat, 16 May 2026 21:01:45 +0200 Subject: [PATCH] docs: add Communication patterns section to all plugin CLAUDE.md Standardize named-markdown-link guidance across all plugins so file:// references render as independently clickable links in terminals like Ghostty (bare file:// URLs only make the first clickable). Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index d549842..36ff833 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,6 +8,8 @@ Voyage — a contract-driven Claude Code pipeline: brief, research, plan, execut > **Trinity context (2026-05-13, informational).** Voyage is Tier 1 (per-task) of a three-tier architecture in active design under the author's private marketplace: Tier 2 `app-creator` (per-app — "what does the app need, what's the next brief?") produces briefs Voyage consumes; Tier 3 `app-factory` (per-portfolio — "which app needs me now?") aggregates state across multiple app-creator instances. Both are pre-implementation and will ship to Forgejo when ready. **Asymmetry is a hard invariant:** Voyage stays unaware of Tier 2/3. Handover 1 (brief format) is the only integration point — any compatible producer can feed Voyage, app-creator is not privileged. Brief-schema changes are therefore breaking changes for downstream consumers, formalized as a public contract in v5.4. +> **Cross-cutting invariant: brief framing must match operator intent (2026-05-15).** Etablert etter residiv. Briefen er pipelinens source of truth; operatørens intent lever i hodet + i memory-filer (`feedback_*`, `project_*`); pipelinen tvinger ikke alignment. Høyere reasoning-kraft polerer feil premiss istedenfor å utfordre det. **Tre lag av forsvar (input-siden), alle BLOCKER ved brudd når v5.5 shipper:** (1) eksplisitt `framing: preserve|refine|replace|new-direction` i brief-frontmatter, `AskUserQuestion`-validert før brief-prosa skrives; (2) memory-alignment check som ny dimensjon i `brief-reviewer` — sammenlikner brief-prosa mot relevante memory-filer og rapporterer eksplisitte motsigelser; (3) obligatorisk `## TL;DR`-seksjon (≤ 5 linjer) øverst i `brief.md`. Implementeres i v5.5 — se [ROADMAP.md](ROADMAP.md). Inntil shipping: operatør må manuelt sjekke at briefens framingord ikke motsier intent, særlig etter avvist iterasjon hvor "delta fra forrige" er en farlig default-ankring. + ## Commands | Command | Description | Model | @@ -301,3 +303,20 @@ Stats: - **Session state** — `.session-state.local.json` per project. **Handover 7** — produced by any session-end mechanism (`/trekexecute` Phase 8/2.55/4, `/trekendsession` helper, future graceful-handoff v2.2). Consumed by `/trekcontinue` to resume the next session in a fresh chat. Schema v1 is forward-compat (unknown top-level keys ignored). Never committed (gitignored via `*.local.json`). A project typically has 1 task brief, 0–N research briefs, 0 or 1 architecture note, 0–N reviews (one per review iteration), and 0 or 1 session-state file (overwritten on every session-end). + +## Communication patterns + +### Linking to local files + +When pointing to local files in responses, always use markdown link syntax with a descriptive name: + +- Use `[Human-friendly name](file:///absolute/path)` — never bare `file:///...` URLs or autolinks ``. +- Always use absolute paths. Never `~/` or relative paths. +- For multiple files, render as a bullet list of named markdown links. + +Why: bare `file://` URLs only render the first as clickable across multiple lines. Named markdown links make each entry independently clickable and look cleaner. + +Example: + +- [Brief](file:///Users/ktg/.../brief.html) +- [Research summary](file:///Users/ktg/.../research/summary.md)