From 0a90d3e481784049f30127a0a72be4eaa4cd171e Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Sat, 23 May 2026 13:20:18 -0400 Subject: [PATCH 1/2] feat: align vault skills with portent model --- skills/vault-compact/SKILL.md | 10 +++++- skills/vault-concepts/SKILL.md | 6 ++++ skills/vault-ingest/SKILL.md | 22 +++++++++++-- skills/vault-lint/SKILL.md | 26 +++++++++++++++ skills/vault-maintain/SKILL.md | 47 +++++++++++++++++++--------- skills/vault-research/SKILL.md | 22 ++++++++----- skills/vault-tracker/SKILL.md | 45 ++++++++++++++++++++------ vault/skills/vault-compact/SKILL.md | 10 +++++- vault/skills/vault-concepts/SKILL.md | 6 ++++ vault/skills/vault-ingest/SKILL.md | 22 +++++++++++-- vault/skills/vault-lint/SKILL.md | 26 +++++++++++++++ vault/skills/vault-maintain/SKILL.md | 47 +++++++++++++++++++--------- vault/skills/vault-research/SKILL.md | 22 ++++++++----- vault/skills/vault-tracker/SKILL.md | 45 ++++++++++++++++++++------ 14 files changed, 286 insertions(+), 70 deletions(-) diff --git a/skills/vault-compact/SKILL.md b/skills/vault-compact/SKILL.md index 662dd23..7bd0bd5 100644 --- a/skills/vault-compact/SKILL.md +++ b/skills/vault-compact/SKILL.md @@ -12,6 +12,10 @@ Reduce repeated thinking across the active vault. This skill is for semantic overlap, not just exact duplicate text: compact passages when they do the same job in the knowledge system. +Prefer compaction when files represent the same Portent object or repeat the +same claim for the same object. Do not merge merely because objects share a +Topic. Preserve `belongs_to` and `related_to` metadata when absorbing files. + ## Command ``` @@ -83,7 +87,8 @@ detail. - `qmd search` for exact phrases, titles, URLs, and aliases - `rg` for migration residue, raw strings, and link rewrites 5. Build candidate groups by canonical topic, project, idea, source, or claim. -6. Classify each group by confidence and compaction action. +6. Classify each group by Portent object identity, confidence, and compaction + action. 7. In `report` mode, stop after a compact report. 8. In `apply-safe` mode, apply only local, high-confidence edits inside one file or obvious link substitutions to canonical concept notes. @@ -116,6 +121,7 @@ detail. - Same source URL or same clipped source identity. - Same title, slug, project, or idea identity. +- Same Portent object identity or same claim serving the same object. - One note explicitly continues, replaces, or supersedes another. - Passages make the same claim with compatible meaning. - Differences are examples, wording, or ordering, not substance. @@ -152,6 +158,8 @@ Low-confidence items should remain separate; propose links only when useful. identity and do not absorb complete external text into owned notes. - Repeated source summaries should cite complete source records under `raw/processed/YYYY-MM-DD/` when used for synthesis. +- Preserve `belongs_to` and `related_to` metadata when compacting or absorbing + notes. ### Ideas diff --git a/skills/vault-concepts/SKILL.md b/skills/vault-concepts/SKILL.md index 163ae81..128c4c3 100644 --- a/skills/vault-concepts/SKILL.md +++ b/skills/vault-concepts/SKILL.md @@ -13,6 +13,10 @@ navigation coherent. Maintain `notes/concepts/` as the durable vocabulary of your vault. Surface cross-domain patterns and decide when transience deserves permanence. +Concept pages are Portent `Topic` objects. New recurring-theme pages should use +`type: Topic`, `status: organized`, and explicit `related_to` links to the +Projects, Notes, Events, or Responsibilities they help explain. + ## Parameters - `--topic TOPIC` focus on specific theme (optional) @@ -25,6 +29,7 @@ Only create new concept pages when ALL are true: - Theme appears in 3+ unrelated notes - Evidence is concrete and linkable - Destination concept is clear +- Destination Topic object is clear - Change is additive and low-risk ## Workflow @@ -90,6 +95,7 @@ Return: - Concepts created/updated/proposed (with confidence) - Concepts merged/proposed for merge +- Topic object metadata added or updated - Evidence links used - Reference normalization performed - Index/log update status diff --git a/skills/vault-ingest/SKILL.md b/skills/vault-ingest/SKILL.md index 16b077c..58cc7de 100644 --- a/skills/vault-ingest/SKILL.md +++ b/skills/vault-ingest/SKILL.md @@ -25,6 +25,15 @@ For each ingestion cycle: - Source starts in `raw/sources/` (unprocessed inbox) - The source file itself remains the durable artifact - Each source is classified by intent, topic, and lifecycle state before moving +- Every capture is classified into a Portent lifecycle state first: `captured`, + `organized`, or `archived` +- Every organized durable object gets a Portent `type` +- Every organized object should have enough relationship metadata to explain + future usefulness: + - `belongs_to` for primary context when one exists + - `related_to` for secondary associations +- If a capture cannot attach to a Project, Responsibility, Operation, or Topic, + leave it in `raw/sources/` and report it as a delete/ignore candidate - Source files move to the most specific existing vault location when they are owned/user-authored material or working source records - Owned notes, project ideas, drafts, and planning captures are moved intact @@ -144,8 +153,14 @@ target. 1. **Scan** `raw/sources/` for unprocessed captures (skip hidden files) 2. **Classify** each capture: - - Identify source type, topic, related entities, and lifecycle state - - Match against existing `projects/`, `ideas/`, and `notes/` + - Identify whether it is PORT (`Project`, `Operation`, `Responsibility`, + `Task`) or ENTP (`Event`, `Note`, `Topic`, `Person`) + - Assign `status: captured|organized|archived` + - Identify source origin: owned, external, asset, operational record + - Identify primary `belongs_to` candidate + - Identify useful `related_to` candidates + - Match against existing `projects/`, `ideas/`, `notes/`, and indexed Topic + objects - Mark confidence as high, medium, or low 3. **Plan moves**: - Choose the most specific destination path @@ -194,11 +209,14 @@ target. Return: - discovered captures and classification plan +- Portent type, status, belongs_to, and related_to recommendations for each + capture - category, confidence, and destination path for each source - source files moved and final destination paths - files merged, merge target, and provenance retained - synthesized items, archived complete source paths, and links inserted - source files left in place with ambiguity reason +- captures left unorganized because they lack a useful relationship target - `index.md` additions - `log.md` entry appended - audit findings (empty folders, anomalies) diff --git a/skills/vault-lint/SKILL.md b/skills/vault-lint/SKILL.md index d0051d4..e7a6ebb 100644 --- a/skills/vault-lint/SKILL.md +++ b/skills/vault-lint/SKILL.md @@ -28,6 +28,17 @@ Run a focused hygiene pass over active vault surface and propose fixes. source records - **External tag drift**: Clipped source notes missing `external`, or owned notes incorrectly tagged `external` +- **Portent object validity**: missing `title`, invalid `type`, invalid + `status`, malformed `belongs_to`, malformed `related_to` +- **Organized-without-usefulness**: `status: organized` objects without any + relationship when a Project, Responsibility, Operation, or Topic target is + obvious +- **Archive visibility drift**: `status: archived` objects still shown in active + `index.md` views +- **Folder/metadata mismatch**: folder location contradicts type, status, or + stage; treat as a navigation smell, not automatic truth +- **Custom model drift**: custom types or custom relationships that duplicate + Portent defaults ## Scope @@ -103,6 +114,19 @@ High-confidence candidates may be passed to `vault-ingest`, `vault-tracker`, or `vault-concepts` for apply-mode merging. Medium/low candidates should stay as separate notes with proposed links. +## Portent Apply Constraints + +In apply mode, Portent fixes are limited to mechanical corrections: + +- normalize valid scalar/list YAML shapes +- add missing `title` from H1 when exact +- add `status: organized` only when type and relationships are already clear +- add high-confidence `related_to` links where the object explicitly names the + target + +Do not infer broad relationships or change object type in apply mode unless the +user explicitly requested that conversion. + ## Safety - Report-first by default on all ambiguous issues. @@ -126,3 +150,5 @@ Return: - Merge candidates with target, confidence, and rationale - Synthesis notes missing archived source links - External tag drift findings +- Portent object validity, relationship, archive visibility, and custom model + drift findings diff --git a/skills/vault-maintain/SKILL.md b/skills/vault-maintain/SKILL.md index c41fba5..bd83346 100644 --- a/skills/vault-maintain/SKILL.md +++ b/skills/vault-maintain/SKILL.md @@ -38,7 +38,20 @@ Run `vault-ingest --mode report` to: - Show high-confidence source moves ready to apply - Identify ambiguous captures needing user direction -### 2. Hygiene Audit +### 2. Portent Object Audit + +Run a report-mode pass over active objects to find: + +- missing or invalid `type` +- missing or invalid `status` +- organized objects without useful relationships +- captured objects that should be organized, deleted, or left in inbox +- archived objects still shown in active views +- Operations without a Responsibility or Project parent +- Projects without a clear Responsibility or Topic relationship when one is + obvious + +### 3. Hygiene Audit Run `vault-lint --mode report` to: @@ -50,7 +63,7 @@ Run `vault-lint --mode report` to: - Flag broken or ambiguous wikilinks - Surface promotion candidates from drift reports -### 3. Tracker Audit +### 4. Tracker Audit Run `vault-tracker --mode report` to: @@ -60,7 +73,7 @@ Run `vault-tracker --mode report` to: - Propose lifecycle transitions - Identify untracked projects -### 4. Idea Pressure Audit +### 5. Idea Pressure Audit Run an aggressive report-mode review of `ideas/fleeting/` and `ideas/incubating/`: @@ -86,7 +99,7 @@ Run an aggressive report-mode review of `ideas/fleeting/` and Default recommendation should be opinionated. Do not leave stale ideas as "maybe" when the evidence supports a clear cleanup action. -### 5. Compaction Audit +### 6. Compaction Audit Run `vault-compact --mode report` to: @@ -96,9 +109,9 @@ Run `vault-compact --mode report` to: shipped-project launch artifacts - Identify curated files that could be deleted after absorption - Distinguish collapse/route/link-only actions from true file merges -- Include idea-pressure candidates from step 4 as compact/reject/delete inputs +- Include idea-pressure candidates from step 5 as compact/reject/delete inputs -### 6. Concept Audit +### 7. Concept Audit Run `vault-concepts --mode report` to: @@ -108,12 +121,14 @@ Run `vault-concepts --mode report` to: - Propose updates to existing concepts - Surface new concept creation candidates -### 7. Weekly Summary Production +### 8. Weekly Summary Production Compile findings into a weekly summary including: - Pending ingestions (count, source types, routing decisions) - Source routing proposals (category, destination, confidence) +- Portent object audit findings (type/status validity, relationship gaps, + captured/archived drift) - Hygiene issues by severity (contradictions, orphans, stale) - Connection candidates (source, target, confidence, relationship) - Merge candidates (target, sources, confidence, required link rewrites) @@ -128,7 +143,7 @@ Compile findings into a weekly summary including: - Concept candidates (updates, creations deferred) - Unresolved decisions requiring user input -### 8. Maintenance Record +### 9. Maintenance Record Append the maintenance entry to `log.md` manually when the vault uses one: @@ -219,13 +234,13 @@ Additionally allow medium-confidence actions: This skill orchestrates the following specialized skills: -| Step | Skill | Purpose | -| ---- | ---------------- | ----------------------------------- | -| 1 | `vault-ingest` | Source classification and routing | -| 2 | `vault-lint` | Hygiene and contradiction detection | -| 3 | `vault-tracker` | Project lifecycle management | -| 4 | `vault-compact` | Semantic merge and absorption | -| 5 | `vault-concepts` | Concept promotion and creation | +| Step | Skill | Purpose | +| ---- | ---------------- | --------------------------------- | +| 1 | `vault-ingest` | Source classification and routing | +| 2 | `vault-lint` | Portent object and hygiene audit | +| 3 | `vault-tracker` | PORT lifecycle management | +| 4 | `vault-compact` | Semantic merge and absorption | +| 5 | `vault-concepts` | Topic promotion and creation | ## Output @@ -240,6 +255,8 @@ Return: - **Idea pressure report**: Fleeting/incubating decisions requested, stale ideas, broken idea entry points, non-idea files in `ideas/`, and recommended action +- **Portent object report**: Missing/invalid types and statuses, relationship + gaps, captured-object decisions, and archived visibility drift - **Graph report**: Links added/proposed and relationship evidence - **Confidence notes**: High/medium/low confidence per category - **Unresolved decisions**: Items requiring explicit user input diff --git a/skills/vault-research/SKILL.md b/skills/vault-research/SKILL.md index 4d768f1..f801900 100644 --- a/skills/vault-research/SKILL.md +++ b/skills/vault-research/SKILL.md @@ -15,6 +15,11 @@ keeps a complete immutable copy in `raw/processed/YYYY-MM-DD/`. Notes tagged `external` are treated as clipped/imported external sources and are eligible for synthesis while preserving the complete source record. +Research briefs are `type: Note` by default. External changes, meetings, +incidents, product launches, or decisions that happened are `type: Event`. Every +synthesized Note or Event should set `belongs_to` to its primary Project, +Responsibility, Operation, or Topic when that context is clear. + ## Parameters Target can be: @@ -45,22 +50,24 @@ Resolve target in this order: - community discussions (Reddit/HN/forums) - market signals (funding/trends/news) 4. Classify each external source by type, relevance, topic, and confidence. -5. Choose output behavior: +5. Classify the output as a Portent `Note` or `Event` and identify the primary + `belongs_to` relationship when clear. +6. Choose output behavior: - `sources`: create or update source records only - `summary`: write a concise synthesized research block with citations - `both`: preserve source records and write a concise synthesis -6. In `apply` mode, archive every external source used for synthesis to +7. In `apply` mode, archive every external source used for synthesis to `raw/processed/YYYY-MM-DD/` before writing the synthesis. -7. Place working source records in the closest durable location: +8. Place working source records in the closest durable location: - `projects/active//research/` - `ideas///research/` - `notes//` -8. Merge source records into an existing research/source note when they cover +9. Merge source records into an existing research/source note when they cover the same external source or same research thread. -9. Assign confidence (`high|medium|low`) for key claims. -10. If writing a summary, keep it clearly separate from owned notes and link +10. Assign confidence (`high|medium|low`) for key claims. +11. If writing a summary, keep it clearly separate from owned notes and link back to archived complete source records. -11. Return what was found, where sources were placed, and what was written. +12. Return what was found, where sources were placed, and what was written. ## Copy vs Synthesize Decision @@ -113,6 +120,7 @@ Return: - archived complete source paths under `raw/processed/YYYY-MM-DD/` - source records merged and canonical destinations - findings summary if requested +- Portent output type and belongs_to relationship used or proposed - confidence highlights - whether source records or target notes were updated - suggested follow-up actions diff --git a/skills/vault-tracker/SKILL.md b/skills/vault-tracker/SKILL.md index 9f47103..c44e726 100644 --- a/skills/vault-tracker/SKILL.md +++ b/skills/vault-tracker/SKILL.md @@ -1,14 +1,19 @@ --- name: vault-tracker description: - Manage project lifecycle and project-tracker.md—track state changes, propose - transitions, and coordinate archival + Manage PORT object lifecycle and project-tracker.md—track state changes, + propose transitions, and coordinate archival --- # Vault Tracker -Unified project lifecycle management: track projects, detect mismatches between -filesystem and tracker, propose transitions, and coordinate archival. +Unified PORT object lifecycle management: track Projects, Operations, +Responsibilities, and externally tracked Task references; detect mismatches +between filesystem, metadata, and tracker; propose transitions; and coordinate +archival. + +Manage lifecycle and navigation for PORT objects: `Project`, `Operation`, +`Responsibility`, and externally tracked `Task` references. ## Command @@ -35,6 +40,14 @@ vault-tracker [--mode report|apply-safe|apply] [--project NAME] [transition] - `someday` — intentionally parked idea (in `ideas/someday/`) - `rejected` — explicitly declined idea (in `ideas/rejected/`) +Portent frontmatter is authoritative for object meaning: + +- Project transitions update `stage` and `status` before file moves. +- Operations should usually `belongs_to` a Responsibility or Project. +- Responsibilities should collect related Projects and Operations. +- Ideas promoted to active work become `type: Project`, `status: organized`, and + `stage: active` before or during any folder movement. + ## Valid Transitions | From | To | Conditions | @@ -59,32 +72,42 @@ vault-tracker [--mode report|apply-safe|apply] [--project NAME] [transition] 1. **Read tracker**: Load `projects/project-tracker.md` 2. **Scan projects/**: Discover project directories and their state -3. **Detect mismatches**: +3. **Scan PORT metadata**: + - Projects in `projects/`, shaped project candidates in `ideas/` + - Operations under `notes/operations/` or equivalent local convention + - Responsibilities under `notes/responsibilities/` or equivalent local + convention + - Task references that live outside the vault but relate back to Portent + objects +4. **Detect mismatches**: - Filesystem state vs tracker state + - Portent `type`, `status`, and `stage` vs folder location + - Operations without a Responsibility or Project parent + - Responsibilities without related Projects or Operations when obvious - Orphan tracker entries (no matching directory) - Untracked projects (directory exists, not in tracker) - Duplicate idea or project directories that should be one lifecycle item -4. **Propose transitions and merges**: +5. **Propose transitions and merges**: - Smallest valid state change per mismatch - Canonical merge target for duplicate ideas/projects - Link rewrites and tracker row consolidation required by the merge -5. **Handle idea promotion paths**: +6. **Handle idea promotion paths**: - `ideas/incubating/` → `projects/active/` (promote to project) - `ideas/fleeting/` → `ideas/incubating/` (promote idea) - `ideas/incubating/` → `ideas/someday/` (park idea) - `ideas/incubating/` → `ideas/rejected/` (decline idea) -6. **Apply by mode**: +7. **Apply by mode**: - `report`: return proposals with evidence and confidence - `apply-safe`: update tracker rows/links when unambiguous, no merges - `apply`: perform confirmed file moves, high-confidence merges, and inbound link rewrites -7. **Shipped compaction**: When a project transitions to `shipped`, immediately +8. **Shipped compaction**: When a project transitions to `shipped`, immediately run or propose `vault-compact --scope projects --project --mode apply --aggression aggressive` to merge launch artifacts, drafts, research, and stale execution notes into one canonical shipped project record. Absorbed curated files may be deleted after unique content is preserved. Never delete `raw/`. -8. **Log operation**: Append concise entry to `log.md` +9. **Log operation**: Append concise entry to `log.md` ## Merge Rules @@ -149,6 +172,8 @@ Return: - Files moved/renamed and link rewrites applied - Merges applied/proposed with canonical target and retained aliases - Idea promotions (incubating→project, fleeting→incubating) +- PORT metadata updates for Project, Operation, Responsibility, and Task + references - Tracker sections changed - Touched files - Skipped items and rationale diff --git a/vault/skills/vault-compact/SKILL.md b/vault/skills/vault-compact/SKILL.md index 662dd23..7bd0bd5 100644 --- a/vault/skills/vault-compact/SKILL.md +++ b/vault/skills/vault-compact/SKILL.md @@ -12,6 +12,10 @@ Reduce repeated thinking across the active vault. This skill is for semantic overlap, not just exact duplicate text: compact passages when they do the same job in the knowledge system. +Prefer compaction when files represent the same Portent object or repeat the +same claim for the same object. Do not merge merely because objects share a +Topic. Preserve `belongs_to` and `related_to` metadata when absorbing files. + ## Command ``` @@ -83,7 +87,8 @@ detail. - `qmd search` for exact phrases, titles, URLs, and aliases - `rg` for migration residue, raw strings, and link rewrites 5. Build candidate groups by canonical topic, project, idea, source, or claim. -6. Classify each group by confidence and compaction action. +6. Classify each group by Portent object identity, confidence, and compaction + action. 7. In `report` mode, stop after a compact report. 8. In `apply-safe` mode, apply only local, high-confidence edits inside one file or obvious link substitutions to canonical concept notes. @@ -116,6 +121,7 @@ detail. - Same source URL or same clipped source identity. - Same title, slug, project, or idea identity. +- Same Portent object identity or same claim serving the same object. - One note explicitly continues, replaces, or supersedes another. - Passages make the same claim with compatible meaning. - Differences are examples, wording, or ordering, not substance. @@ -152,6 +158,8 @@ Low-confidence items should remain separate; propose links only when useful. identity and do not absorb complete external text into owned notes. - Repeated source summaries should cite complete source records under `raw/processed/YYYY-MM-DD/` when used for synthesis. +- Preserve `belongs_to` and `related_to` metadata when compacting or absorbing + notes. ### Ideas diff --git a/vault/skills/vault-concepts/SKILL.md b/vault/skills/vault-concepts/SKILL.md index 163ae81..128c4c3 100644 --- a/vault/skills/vault-concepts/SKILL.md +++ b/vault/skills/vault-concepts/SKILL.md @@ -13,6 +13,10 @@ navigation coherent. Maintain `notes/concepts/` as the durable vocabulary of your vault. Surface cross-domain patterns and decide when transience deserves permanence. +Concept pages are Portent `Topic` objects. New recurring-theme pages should use +`type: Topic`, `status: organized`, and explicit `related_to` links to the +Projects, Notes, Events, or Responsibilities they help explain. + ## Parameters - `--topic TOPIC` focus on specific theme (optional) @@ -25,6 +29,7 @@ Only create new concept pages when ALL are true: - Theme appears in 3+ unrelated notes - Evidence is concrete and linkable - Destination concept is clear +- Destination Topic object is clear - Change is additive and low-risk ## Workflow @@ -90,6 +95,7 @@ Return: - Concepts created/updated/proposed (with confidence) - Concepts merged/proposed for merge +- Topic object metadata added or updated - Evidence links used - Reference normalization performed - Index/log update status diff --git a/vault/skills/vault-ingest/SKILL.md b/vault/skills/vault-ingest/SKILL.md index 16b077c..58cc7de 100644 --- a/vault/skills/vault-ingest/SKILL.md +++ b/vault/skills/vault-ingest/SKILL.md @@ -25,6 +25,15 @@ For each ingestion cycle: - Source starts in `raw/sources/` (unprocessed inbox) - The source file itself remains the durable artifact - Each source is classified by intent, topic, and lifecycle state before moving +- Every capture is classified into a Portent lifecycle state first: `captured`, + `organized`, or `archived` +- Every organized durable object gets a Portent `type` +- Every organized object should have enough relationship metadata to explain + future usefulness: + - `belongs_to` for primary context when one exists + - `related_to` for secondary associations +- If a capture cannot attach to a Project, Responsibility, Operation, or Topic, + leave it in `raw/sources/` and report it as a delete/ignore candidate - Source files move to the most specific existing vault location when they are owned/user-authored material or working source records - Owned notes, project ideas, drafts, and planning captures are moved intact @@ -144,8 +153,14 @@ target. 1. **Scan** `raw/sources/` for unprocessed captures (skip hidden files) 2. **Classify** each capture: - - Identify source type, topic, related entities, and lifecycle state - - Match against existing `projects/`, `ideas/`, and `notes/` + - Identify whether it is PORT (`Project`, `Operation`, `Responsibility`, + `Task`) or ENTP (`Event`, `Note`, `Topic`, `Person`) + - Assign `status: captured|organized|archived` + - Identify source origin: owned, external, asset, operational record + - Identify primary `belongs_to` candidate + - Identify useful `related_to` candidates + - Match against existing `projects/`, `ideas/`, `notes/`, and indexed Topic + objects - Mark confidence as high, medium, or low 3. **Plan moves**: - Choose the most specific destination path @@ -194,11 +209,14 @@ target. Return: - discovered captures and classification plan +- Portent type, status, belongs_to, and related_to recommendations for each + capture - category, confidence, and destination path for each source - source files moved and final destination paths - files merged, merge target, and provenance retained - synthesized items, archived complete source paths, and links inserted - source files left in place with ambiguity reason +- captures left unorganized because they lack a useful relationship target - `index.md` additions - `log.md` entry appended - audit findings (empty folders, anomalies) diff --git a/vault/skills/vault-lint/SKILL.md b/vault/skills/vault-lint/SKILL.md index d0051d4..e7a6ebb 100644 --- a/vault/skills/vault-lint/SKILL.md +++ b/vault/skills/vault-lint/SKILL.md @@ -28,6 +28,17 @@ Run a focused hygiene pass over active vault surface and propose fixes. source records - **External tag drift**: Clipped source notes missing `external`, or owned notes incorrectly tagged `external` +- **Portent object validity**: missing `title`, invalid `type`, invalid + `status`, malformed `belongs_to`, malformed `related_to` +- **Organized-without-usefulness**: `status: organized` objects without any + relationship when a Project, Responsibility, Operation, or Topic target is + obvious +- **Archive visibility drift**: `status: archived` objects still shown in active + `index.md` views +- **Folder/metadata mismatch**: folder location contradicts type, status, or + stage; treat as a navigation smell, not automatic truth +- **Custom model drift**: custom types or custom relationships that duplicate + Portent defaults ## Scope @@ -103,6 +114,19 @@ High-confidence candidates may be passed to `vault-ingest`, `vault-tracker`, or `vault-concepts` for apply-mode merging. Medium/low candidates should stay as separate notes with proposed links. +## Portent Apply Constraints + +In apply mode, Portent fixes are limited to mechanical corrections: + +- normalize valid scalar/list YAML shapes +- add missing `title` from H1 when exact +- add `status: organized` only when type and relationships are already clear +- add high-confidence `related_to` links where the object explicitly names the + target + +Do not infer broad relationships or change object type in apply mode unless the +user explicitly requested that conversion. + ## Safety - Report-first by default on all ambiguous issues. @@ -126,3 +150,5 @@ Return: - Merge candidates with target, confidence, and rationale - Synthesis notes missing archived source links - External tag drift findings +- Portent object validity, relationship, archive visibility, and custom model + drift findings diff --git a/vault/skills/vault-maintain/SKILL.md b/vault/skills/vault-maintain/SKILL.md index c41fba5..bd83346 100644 --- a/vault/skills/vault-maintain/SKILL.md +++ b/vault/skills/vault-maintain/SKILL.md @@ -38,7 +38,20 @@ Run `vault-ingest --mode report` to: - Show high-confidence source moves ready to apply - Identify ambiguous captures needing user direction -### 2. Hygiene Audit +### 2. Portent Object Audit + +Run a report-mode pass over active objects to find: + +- missing or invalid `type` +- missing or invalid `status` +- organized objects without useful relationships +- captured objects that should be organized, deleted, or left in inbox +- archived objects still shown in active views +- Operations without a Responsibility or Project parent +- Projects without a clear Responsibility or Topic relationship when one is + obvious + +### 3. Hygiene Audit Run `vault-lint --mode report` to: @@ -50,7 +63,7 @@ Run `vault-lint --mode report` to: - Flag broken or ambiguous wikilinks - Surface promotion candidates from drift reports -### 3. Tracker Audit +### 4. Tracker Audit Run `vault-tracker --mode report` to: @@ -60,7 +73,7 @@ Run `vault-tracker --mode report` to: - Propose lifecycle transitions - Identify untracked projects -### 4. Idea Pressure Audit +### 5. Idea Pressure Audit Run an aggressive report-mode review of `ideas/fleeting/` and `ideas/incubating/`: @@ -86,7 +99,7 @@ Run an aggressive report-mode review of `ideas/fleeting/` and Default recommendation should be opinionated. Do not leave stale ideas as "maybe" when the evidence supports a clear cleanup action. -### 5. Compaction Audit +### 6. Compaction Audit Run `vault-compact --mode report` to: @@ -96,9 +109,9 @@ Run `vault-compact --mode report` to: shipped-project launch artifacts - Identify curated files that could be deleted after absorption - Distinguish collapse/route/link-only actions from true file merges -- Include idea-pressure candidates from step 4 as compact/reject/delete inputs +- Include idea-pressure candidates from step 5 as compact/reject/delete inputs -### 6. Concept Audit +### 7. Concept Audit Run `vault-concepts --mode report` to: @@ -108,12 +121,14 @@ Run `vault-concepts --mode report` to: - Propose updates to existing concepts - Surface new concept creation candidates -### 7. Weekly Summary Production +### 8. Weekly Summary Production Compile findings into a weekly summary including: - Pending ingestions (count, source types, routing decisions) - Source routing proposals (category, destination, confidence) +- Portent object audit findings (type/status validity, relationship gaps, + captured/archived drift) - Hygiene issues by severity (contradictions, orphans, stale) - Connection candidates (source, target, confidence, relationship) - Merge candidates (target, sources, confidence, required link rewrites) @@ -128,7 +143,7 @@ Compile findings into a weekly summary including: - Concept candidates (updates, creations deferred) - Unresolved decisions requiring user input -### 8. Maintenance Record +### 9. Maintenance Record Append the maintenance entry to `log.md` manually when the vault uses one: @@ -219,13 +234,13 @@ Additionally allow medium-confidence actions: This skill orchestrates the following specialized skills: -| Step | Skill | Purpose | -| ---- | ---------------- | ----------------------------------- | -| 1 | `vault-ingest` | Source classification and routing | -| 2 | `vault-lint` | Hygiene and contradiction detection | -| 3 | `vault-tracker` | Project lifecycle management | -| 4 | `vault-compact` | Semantic merge and absorption | -| 5 | `vault-concepts` | Concept promotion and creation | +| Step | Skill | Purpose | +| ---- | ---------------- | --------------------------------- | +| 1 | `vault-ingest` | Source classification and routing | +| 2 | `vault-lint` | Portent object and hygiene audit | +| 3 | `vault-tracker` | PORT lifecycle management | +| 4 | `vault-compact` | Semantic merge and absorption | +| 5 | `vault-concepts` | Topic promotion and creation | ## Output @@ -240,6 +255,8 @@ Return: - **Idea pressure report**: Fleeting/incubating decisions requested, stale ideas, broken idea entry points, non-idea files in `ideas/`, and recommended action +- **Portent object report**: Missing/invalid types and statuses, relationship + gaps, captured-object decisions, and archived visibility drift - **Graph report**: Links added/proposed and relationship evidence - **Confidence notes**: High/medium/low confidence per category - **Unresolved decisions**: Items requiring explicit user input diff --git a/vault/skills/vault-research/SKILL.md b/vault/skills/vault-research/SKILL.md index 4d768f1..f801900 100644 --- a/vault/skills/vault-research/SKILL.md +++ b/vault/skills/vault-research/SKILL.md @@ -15,6 +15,11 @@ keeps a complete immutable copy in `raw/processed/YYYY-MM-DD/`. Notes tagged `external` are treated as clipped/imported external sources and are eligible for synthesis while preserving the complete source record. +Research briefs are `type: Note` by default. External changes, meetings, +incidents, product launches, or decisions that happened are `type: Event`. Every +synthesized Note or Event should set `belongs_to` to its primary Project, +Responsibility, Operation, or Topic when that context is clear. + ## Parameters Target can be: @@ -45,22 +50,24 @@ Resolve target in this order: - community discussions (Reddit/HN/forums) - market signals (funding/trends/news) 4. Classify each external source by type, relevance, topic, and confidence. -5. Choose output behavior: +5. Classify the output as a Portent `Note` or `Event` and identify the primary + `belongs_to` relationship when clear. +6. Choose output behavior: - `sources`: create or update source records only - `summary`: write a concise synthesized research block with citations - `both`: preserve source records and write a concise synthesis -6. In `apply` mode, archive every external source used for synthesis to +7. In `apply` mode, archive every external source used for synthesis to `raw/processed/YYYY-MM-DD/` before writing the synthesis. -7. Place working source records in the closest durable location: +8. Place working source records in the closest durable location: - `projects/active//research/` - `ideas///research/` - `notes//` -8. Merge source records into an existing research/source note when they cover +9. Merge source records into an existing research/source note when they cover the same external source or same research thread. -9. Assign confidence (`high|medium|low`) for key claims. -10. If writing a summary, keep it clearly separate from owned notes and link +10. Assign confidence (`high|medium|low`) for key claims. +11. If writing a summary, keep it clearly separate from owned notes and link back to archived complete source records. -11. Return what was found, where sources were placed, and what was written. +12. Return what was found, where sources were placed, and what was written. ## Copy vs Synthesize Decision @@ -113,6 +120,7 @@ Return: - archived complete source paths under `raw/processed/YYYY-MM-DD/` - source records merged and canonical destinations - findings summary if requested +- Portent output type and belongs_to relationship used or proposed - confidence highlights - whether source records or target notes were updated - suggested follow-up actions diff --git a/vault/skills/vault-tracker/SKILL.md b/vault/skills/vault-tracker/SKILL.md index 9f47103..c44e726 100644 --- a/vault/skills/vault-tracker/SKILL.md +++ b/vault/skills/vault-tracker/SKILL.md @@ -1,14 +1,19 @@ --- name: vault-tracker description: - Manage project lifecycle and project-tracker.md—track state changes, propose - transitions, and coordinate archival + Manage PORT object lifecycle and project-tracker.md—track state changes, + propose transitions, and coordinate archival --- # Vault Tracker -Unified project lifecycle management: track projects, detect mismatches between -filesystem and tracker, propose transitions, and coordinate archival. +Unified PORT object lifecycle management: track Projects, Operations, +Responsibilities, and externally tracked Task references; detect mismatches +between filesystem, metadata, and tracker; propose transitions; and coordinate +archival. + +Manage lifecycle and navigation for PORT objects: `Project`, `Operation`, +`Responsibility`, and externally tracked `Task` references. ## Command @@ -35,6 +40,14 @@ vault-tracker [--mode report|apply-safe|apply] [--project NAME] [transition] - `someday` — intentionally parked idea (in `ideas/someday/`) - `rejected` — explicitly declined idea (in `ideas/rejected/`) +Portent frontmatter is authoritative for object meaning: + +- Project transitions update `stage` and `status` before file moves. +- Operations should usually `belongs_to` a Responsibility or Project. +- Responsibilities should collect related Projects and Operations. +- Ideas promoted to active work become `type: Project`, `status: organized`, and + `stage: active` before or during any folder movement. + ## Valid Transitions | From | To | Conditions | @@ -59,32 +72,42 @@ vault-tracker [--mode report|apply-safe|apply] [--project NAME] [transition] 1. **Read tracker**: Load `projects/project-tracker.md` 2. **Scan projects/**: Discover project directories and their state -3. **Detect mismatches**: +3. **Scan PORT metadata**: + - Projects in `projects/`, shaped project candidates in `ideas/` + - Operations under `notes/operations/` or equivalent local convention + - Responsibilities under `notes/responsibilities/` or equivalent local + convention + - Task references that live outside the vault but relate back to Portent + objects +4. **Detect mismatches**: - Filesystem state vs tracker state + - Portent `type`, `status`, and `stage` vs folder location + - Operations without a Responsibility or Project parent + - Responsibilities without related Projects or Operations when obvious - Orphan tracker entries (no matching directory) - Untracked projects (directory exists, not in tracker) - Duplicate idea or project directories that should be one lifecycle item -4. **Propose transitions and merges**: +5. **Propose transitions and merges**: - Smallest valid state change per mismatch - Canonical merge target for duplicate ideas/projects - Link rewrites and tracker row consolidation required by the merge -5. **Handle idea promotion paths**: +6. **Handle idea promotion paths**: - `ideas/incubating/` → `projects/active/` (promote to project) - `ideas/fleeting/` → `ideas/incubating/` (promote idea) - `ideas/incubating/` → `ideas/someday/` (park idea) - `ideas/incubating/` → `ideas/rejected/` (decline idea) -6. **Apply by mode**: +7. **Apply by mode**: - `report`: return proposals with evidence and confidence - `apply-safe`: update tracker rows/links when unambiguous, no merges - `apply`: perform confirmed file moves, high-confidence merges, and inbound link rewrites -7. **Shipped compaction**: When a project transitions to `shipped`, immediately +8. **Shipped compaction**: When a project transitions to `shipped`, immediately run or propose `vault-compact --scope projects --project --mode apply --aggression aggressive` to merge launch artifacts, drafts, research, and stale execution notes into one canonical shipped project record. Absorbed curated files may be deleted after unique content is preserved. Never delete `raw/`. -8. **Log operation**: Append concise entry to `log.md` +9. **Log operation**: Append concise entry to `log.md` ## Merge Rules @@ -149,6 +172,8 @@ Return: - Files moved/renamed and link rewrites applied - Merges applied/proposed with canonical target and retained aliases - Idea promotions (incubating→project, fleeting→incubating) +- PORT metadata updates for Project, Operation, Responsibility, and Task + references - Tracker sections changed - Touched files - Skipped items and rationale From 71e8419c5d94c5ac06e132e3b63c72c05c5069d1 Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Sat, 23 May 2026 13:29:09 -0400 Subject: [PATCH 2/2] feat: sync shared vault skill references --- scripts/sync-skills.sh | 42 +++ .../references/portent-knowledge-base-spec.md | 256 ++++++++++++++++++ skills/vault-compact/SKILL.md | 2 + skills/vault-concepts/SKILL.md | 2 + skills/vault-ingest/SKILL.md | 2 + skills/vault-lint/SKILL.md | 2 + skills/vault-maintain/SKILL.md | 2 + skills/vault-research/SKILL.md | 2 + skills/vault-tracker/SKILL.md | 2 + .../references/portent-knowledge-base-spec.md | 256 ++++++++++++++++++ vault/skills/vault-compact/SKILL.md | 2 + vault/skills/vault-concepts/SKILL.md | 2 + vault/skills/vault-ingest/SKILL.md | 2 + vault/skills/vault-lint/SKILL.md | 2 + vault/skills/vault-maintain/SKILL.md | 2 + vault/skills/vault-research/SKILL.md | 2 + vault/skills/vault-tracker/SKILL.md | 2 + 17 files changed, 582 insertions(+) create mode 100644 skills/references/portent-knowledge-base-spec.md create mode 100644 vault/skills/references/portent-knowledge-base-spec.md diff --git a/scripts/sync-skills.sh b/scripts/sync-skills.sh index c91cc88..24371bd 100755 --- a/scripts/sync-skills.sh +++ b/scripts/sync-skills.sh @@ -10,6 +10,8 @@ IGNORE_RE='^(\.git|node_modules|\.agents|\.github|scripts|docs|skills|\.husky)$' # Bash 3.2 (default on macOS) does not support associative arrays. declare -a SKILL_NAMES=() declare -a SKILL_PATHS=() +declare -a SHARED_NAMES=() +declare -a SHARED_PATHS=() echo "[sync-skills] scanning plugin skill directories..." @@ -17,6 +19,30 @@ while IFS= read -r plugin_dir; do skills_root="$plugin_dir/skills" [[ -d "$skills_root" ]] || continue + references_dir="$skills_root/references" + if [[ -d "$references_dir" ]]; then + existing_src="" + for i in "${!SHARED_NAMES[@]}"; do + if [[ "${SHARED_NAMES[$i]}" == "references" ]]; then + existing_src="${SHARED_PATHS[$i]}" + break + fi + done + + if [[ -n "$existing_src" && "$existing_src" != "$references_dir" ]]; then + echo "[sync-skills] duplicate shared references directory found:" >&2 + echo " - $existing_src" >&2 + echo " - $references_dir" >&2 + echo "Merge or rename one of them before syncing." >&2 + exit 1 + fi + + if [[ -z "$existing_src" ]]; then + SHARED_NAMES+=("references") + SHARED_PATHS+=("$references_dir") + fi + fi + while IFS= read -r skill_dir; do [[ -f "$skill_dir/SKILL.md" ]] || continue skill_name="$(basename "$skill_dir")" @@ -67,6 +93,12 @@ while IFS= read -r existing; do break fi done + for i in "${!SHARED_NAMES[@]}"; do + if [[ "${SHARED_NAMES[$i]}" == "$name" ]]; then + found=1 + break + fi + done if [[ "$found" -eq 0 ]]; then echo "[sync-skills] removing stale skill: $name" rm -rf "$existing" @@ -83,4 +115,14 @@ for i in "${!SKILL_NAMES[@]}"; do echo "[sync-skills] synced: $name" done +# Sync shared skill asset directories such as references/. +for i in "${!SHARED_NAMES[@]}"; do + name="${SHARED_NAMES[$i]}" + src="${SHARED_PATHS[$i]}" + dst="$DEST/$name" + mkdir -p "$dst" + rsync -a --delete --exclude node_modules/ --exclude .env "$src/" "$dst/" + echo "[sync-skills] synced shared: $name" +done + echo "[sync-skills] done" diff --git a/skills/references/portent-knowledge-base-spec.md b/skills/references/portent-knowledge-base-spec.md new file mode 100644 index 0000000..50f3233 --- /dev/null +++ b/skills/references/portent-knowledge-base-spec.md @@ -0,0 +1,256 @@ +# Portent Knowledge Base Spec + +Portent is an opinionated model for personal and work knowledge bases. Use it to +organize information as typed objects connected by explicit relationships, with +a simple lifecycle. + +## Core Rules + +- Model reality first. Do not use folders as the main source of meaning. +- Every durable object should answer: what is this? +- Every organized object should answer: what will this be useful for? +- Prefer Portent defaults before creating custom types or relationships. +- Keep captured material easy to record, then organize it later. +- Keep archived material searchable, but hidden from active work by default. + +## Object Shape + +Every Portent object should have: + +- `title`: human-readable name +- `type`: one of the Portent types +- `content`: readable body text +- lifecycle metadata: organized/archived state +- relationships: explicit links to other objects + +In Markdown, store metadata in frontmatter and use wikilinks for local +references. + +Example: + +```yaml +--- +type: Event +organized: true +archived: false +belongs_to: '[[Launch Portent v0.1]]' +related_to: + - '[[Alice Example]]' + - '[[Knowledge graphs]]' +--- +``` + +## Types + +Portent has eight default types. + +### Project + +A bounded effort that produces an output. + +Use for work that: + +- has a beginning and an end +- cannot be completed in one sitting +- has success criteria or a definition of done +- advances one or more responsibilities + +Projects are about outputs. + +### Operation + +Recurring work that can usually be completed in one sitting. + +Use for repeatable actions such as reviews, checks, publishing routines, +maintenance routines, or recurring admin work. + +Operations usually belong to a responsibility, but can also support a project. + +### Responsibility + +A long-running area of accountability. + +Use for outcomes that should be maintained or improved over time. + +Responsibilities usually: + +- do not have a natural end date +- are measured by indicators, metrics, KPIs, or standards +- collect projects and operations that improve or maintain the outcome + +Responsibilities are about outcomes. + +### Task + +One-off work that can usually be completed in one sitting. + +Tasks are part of Portent's worldview, but they do not have to live inside the +knowledge base. They can live in Todoist, Linear, GitHub Issues, or another task +tool as long as they can be related back to Portent objects. + +### Event + +Something that happened and should be retained in long-term memory. + +Use for meetings, conversations, decisions, achievements, incidents, personal +events, external changes, or historical records. + +Events often belong to a project or responsibility and are related to people and +topics. + +### Note + +A durable knowledge artifact. + +Use for documents, resources, references, research summaries, decision records, +checklists, tools, or any material that helps understand or advance another +object. + +### Topic + +An area of interest or conceptual lens. + +Use for knowledge that should be collected without implying ownership, +completion, or performance expectations. + +Topics are useful for grouping notes and events across projects and +responsibilities. + +### Person + +A real-world person or, when useful, an AI agent treated as an actor. + +Use for contacts, collaborators, customers, vendors, authors, attendees, +decision makers, stakeholders, or agents. + +## Type Groups + +PORT types are actionable: + +- Project +- Operation +- Responsibility +- Task + +ENTP types are non-actionable records: + +- Event +- Note +- Topic +- Person + +Use PORT when the object is something to do or operate. Use ENTP when the object +records what happened, what is known, what is interesting, or who is involved. + +## Relationships + +Portent uses two default relationship types. + +### belongs_to + +Primary context, ownership, or composition. + +Use when an object has a main parent or main operating context. + +Examples: + +- a task belongs to a project +- an operation belongs to a responsibility +- an event belongs to a project +- a note belongs to the project or responsibility it primarily supports + +Most objects should have at most one primary parent for a given organizing +purpose. + +Inverse: `has`, `contains`, or `children`. + +### related_to + +Secondary usefulness or association without ownership. + +Use for many-to-many links and supporting context. + +Examples: + +- a meeting event is related to attendees +- a note is related to multiple topics +- a project is related to a responsibility it improves +- a person is related to projects they influence + +Inverse: `referred_by`, `linked_from`, backlinks, or related items. + +## Lifecycle + +Every object can move through three lifecycle states. + +### Captured + +Recorded but not yet actionable. + +Captured objects may have unclear titles, missing types, missing relationships, +or incomplete context. They belong in an inbox or temporary surface. + +Capture optimistically. + +### Organized + +Structured enough to be useful later. + +An object is organized when it has: + +- a clear title +- a type +- enough relationships to explain future use + +Organize pessimistically. If a captured object cannot attach to a project, +responsibility, operation, or topic, consider deleting it. + +### Archived + +No longer useful in active work, but still useful as memory. + +Archived objects should remain searchable and referenceable, but hidden from +active views by default. + +Archive instead of deleting when the object still has historical, audit, or +reference value. + +## Lifecycle Fields + +Use any representation that preserves organized and archived state. + +Separate fields: + +```yaml +organized: true +archived: false +``` + +Single status field: + +```yaml +status: organized +``` + +Allowed statuses should map to: + +- captured +- organized +- archived + +## Extension Rules + +Portent can be extended, but defaults should come first. + +Add a custom type only when: + +- the object has different behavior, templates, relationships, or workflows +- a property on an existing type is not enough + +Add a custom relationship only when: + +- `belongs_to` or `related_to` hides important meaning +- the relationship needs distinct behavior or validation + +Prefer properties before root types. Prefer default relationships before custom +relationships. diff --git a/skills/vault-compact/SKILL.md b/skills/vault-compact/SKILL.md index 7bd0bd5..36eeaa3 100644 --- a/skills/vault-compact/SKILL.md +++ b/skills/vault-compact/SKILL.md @@ -12,6 +12,8 @@ Reduce repeated thinking across the active vault. This skill is for semantic overlap, not just exact duplicate text: compact passages when they do the same job in the knowledge system. +Portent reference: `../references/portent-knowledge-base-spec.md`. + Prefer compaction when files represent the same Portent object or repeat the same claim for the same object. Do not merge merely because objects share a Topic. Preserve `belongs_to` and `related_to` metadata when absorbing files. diff --git a/skills/vault-concepts/SKILL.md b/skills/vault-concepts/SKILL.md index 128c4c3..442dcc8 100644 --- a/skills/vault-concepts/SKILL.md +++ b/skills/vault-concepts/SKILL.md @@ -8,6 +8,8 @@ description: Maintain canonical concept pages and surface recurring themes Promote recurring themes into canonical concept pages and keep concept navigation coherent. +Portent reference: `../references/portent-knowledge-base-spec.md`. + ## Purpose Maintain `notes/concepts/` as the durable vocabulary of your vault. Surface diff --git a/skills/vault-ingest/SKILL.md b/skills/vault-ingest/SKILL.md index 58cc7de..3d1f32a 100644 --- a/skills/vault-ingest/SKILL.md +++ b/skills/vault-ingest/SKILL.md @@ -11,6 +11,8 @@ Categorize captures in `raw/sources/`, route owned/user-authored material to the right vault directories, and synthesize tagged external sources into curated notes while preserving complete source evidence. +Portent reference: `../references/portent-knowledge-base-spec.md`. + ## Parameters - `--mode report|apply` (default: `report`) diff --git a/skills/vault-lint/SKILL.md b/skills/vault-lint/SKILL.md index e7a6ebb..3a62110 100644 --- a/skills/vault-lint/SKILL.md +++ b/skills/vault-lint/SKILL.md @@ -7,6 +7,8 @@ description: Hygiene pass over active notes, ideas, and projects Run a focused hygiene pass over active vault surface and propose fixes. +Portent reference: `../references/portent-knowledge-base-spec.md`. + ## Parameters - `--scope notes|projects|all` (default: `all`) diff --git a/skills/vault-maintain/SKILL.md b/skills/vault-maintain/SKILL.md index bd83346..129d549 100644 --- a/skills/vault-maintain/SKILL.md +++ b/skills/vault-maintain/SKILL.md @@ -12,6 +12,8 @@ This is the unified entry point for periodic vault care, coordinating ingestion, hygiene, semantic compaction, project tracking, and concept promotion into a single bounded workflow. +Portent reference: `../references/portent-knowledge-base-spec.md`. + ## Command ``` diff --git a/skills/vault-research/SKILL.md b/skills/vault-research/SKILL.md index f801900..ee65695 100644 --- a/skills/vault-research/SKILL.md +++ b/skills/vault-research/SKILL.md @@ -15,6 +15,8 @@ keeps a complete immutable copy in `raw/processed/YYYY-MM-DD/`. Notes tagged `external` are treated as clipped/imported external sources and are eligible for synthesis while preserving the complete source record. +Portent reference: `../references/portent-knowledge-base-spec.md`. + Research briefs are `type: Note` by default. External changes, meetings, incidents, product launches, or decisions that happened are `type: Event`. Every synthesized Note or Event should set `belongs_to` to its primary Project, diff --git a/skills/vault-tracker/SKILL.md b/skills/vault-tracker/SKILL.md index c44e726..90fe4f8 100644 --- a/skills/vault-tracker/SKILL.md +++ b/skills/vault-tracker/SKILL.md @@ -15,6 +15,8 @@ archival. Manage lifecycle and navigation for PORT objects: `Project`, `Operation`, `Responsibility`, and externally tracked `Task` references. +Portent reference: `../references/portent-knowledge-base-spec.md`. + ## Command ``` diff --git a/vault/skills/references/portent-knowledge-base-spec.md b/vault/skills/references/portent-knowledge-base-spec.md new file mode 100644 index 0000000..50f3233 --- /dev/null +++ b/vault/skills/references/portent-knowledge-base-spec.md @@ -0,0 +1,256 @@ +# Portent Knowledge Base Spec + +Portent is an opinionated model for personal and work knowledge bases. Use it to +organize information as typed objects connected by explicit relationships, with +a simple lifecycle. + +## Core Rules + +- Model reality first. Do not use folders as the main source of meaning. +- Every durable object should answer: what is this? +- Every organized object should answer: what will this be useful for? +- Prefer Portent defaults before creating custom types or relationships. +- Keep captured material easy to record, then organize it later. +- Keep archived material searchable, but hidden from active work by default. + +## Object Shape + +Every Portent object should have: + +- `title`: human-readable name +- `type`: one of the Portent types +- `content`: readable body text +- lifecycle metadata: organized/archived state +- relationships: explicit links to other objects + +In Markdown, store metadata in frontmatter and use wikilinks for local +references. + +Example: + +```yaml +--- +type: Event +organized: true +archived: false +belongs_to: '[[Launch Portent v0.1]]' +related_to: + - '[[Alice Example]]' + - '[[Knowledge graphs]]' +--- +``` + +## Types + +Portent has eight default types. + +### Project + +A bounded effort that produces an output. + +Use for work that: + +- has a beginning and an end +- cannot be completed in one sitting +- has success criteria or a definition of done +- advances one or more responsibilities + +Projects are about outputs. + +### Operation + +Recurring work that can usually be completed in one sitting. + +Use for repeatable actions such as reviews, checks, publishing routines, +maintenance routines, or recurring admin work. + +Operations usually belong to a responsibility, but can also support a project. + +### Responsibility + +A long-running area of accountability. + +Use for outcomes that should be maintained or improved over time. + +Responsibilities usually: + +- do not have a natural end date +- are measured by indicators, metrics, KPIs, or standards +- collect projects and operations that improve or maintain the outcome + +Responsibilities are about outcomes. + +### Task + +One-off work that can usually be completed in one sitting. + +Tasks are part of Portent's worldview, but they do not have to live inside the +knowledge base. They can live in Todoist, Linear, GitHub Issues, or another task +tool as long as they can be related back to Portent objects. + +### Event + +Something that happened and should be retained in long-term memory. + +Use for meetings, conversations, decisions, achievements, incidents, personal +events, external changes, or historical records. + +Events often belong to a project or responsibility and are related to people and +topics. + +### Note + +A durable knowledge artifact. + +Use for documents, resources, references, research summaries, decision records, +checklists, tools, or any material that helps understand or advance another +object. + +### Topic + +An area of interest or conceptual lens. + +Use for knowledge that should be collected without implying ownership, +completion, or performance expectations. + +Topics are useful for grouping notes and events across projects and +responsibilities. + +### Person + +A real-world person or, when useful, an AI agent treated as an actor. + +Use for contacts, collaborators, customers, vendors, authors, attendees, +decision makers, stakeholders, or agents. + +## Type Groups + +PORT types are actionable: + +- Project +- Operation +- Responsibility +- Task + +ENTP types are non-actionable records: + +- Event +- Note +- Topic +- Person + +Use PORT when the object is something to do or operate. Use ENTP when the object +records what happened, what is known, what is interesting, or who is involved. + +## Relationships + +Portent uses two default relationship types. + +### belongs_to + +Primary context, ownership, or composition. + +Use when an object has a main parent or main operating context. + +Examples: + +- a task belongs to a project +- an operation belongs to a responsibility +- an event belongs to a project +- a note belongs to the project or responsibility it primarily supports + +Most objects should have at most one primary parent for a given organizing +purpose. + +Inverse: `has`, `contains`, or `children`. + +### related_to + +Secondary usefulness or association without ownership. + +Use for many-to-many links and supporting context. + +Examples: + +- a meeting event is related to attendees +- a note is related to multiple topics +- a project is related to a responsibility it improves +- a person is related to projects they influence + +Inverse: `referred_by`, `linked_from`, backlinks, or related items. + +## Lifecycle + +Every object can move through three lifecycle states. + +### Captured + +Recorded but not yet actionable. + +Captured objects may have unclear titles, missing types, missing relationships, +or incomplete context. They belong in an inbox or temporary surface. + +Capture optimistically. + +### Organized + +Structured enough to be useful later. + +An object is organized when it has: + +- a clear title +- a type +- enough relationships to explain future use + +Organize pessimistically. If a captured object cannot attach to a project, +responsibility, operation, or topic, consider deleting it. + +### Archived + +No longer useful in active work, but still useful as memory. + +Archived objects should remain searchable and referenceable, but hidden from +active views by default. + +Archive instead of deleting when the object still has historical, audit, or +reference value. + +## Lifecycle Fields + +Use any representation that preserves organized and archived state. + +Separate fields: + +```yaml +organized: true +archived: false +``` + +Single status field: + +```yaml +status: organized +``` + +Allowed statuses should map to: + +- captured +- organized +- archived + +## Extension Rules + +Portent can be extended, but defaults should come first. + +Add a custom type only when: + +- the object has different behavior, templates, relationships, or workflows +- a property on an existing type is not enough + +Add a custom relationship only when: + +- `belongs_to` or `related_to` hides important meaning +- the relationship needs distinct behavior or validation + +Prefer properties before root types. Prefer default relationships before custom +relationships. diff --git a/vault/skills/vault-compact/SKILL.md b/vault/skills/vault-compact/SKILL.md index 7bd0bd5..36eeaa3 100644 --- a/vault/skills/vault-compact/SKILL.md +++ b/vault/skills/vault-compact/SKILL.md @@ -12,6 +12,8 @@ Reduce repeated thinking across the active vault. This skill is for semantic overlap, not just exact duplicate text: compact passages when they do the same job in the knowledge system. +Portent reference: `../references/portent-knowledge-base-spec.md`. + Prefer compaction when files represent the same Portent object or repeat the same claim for the same object. Do not merge merely because objects share a Topic. Preserve `belongs_to` and `related_to` metadata when absorbing files. diff --git a/vault/skills/vault-concepts/SKILL.md b/vault/skills/vault-concepts/SKILL.md index 128c4c3..442dcc8 100644 --- a/vault/skills/vault-concepts/SKILL.md +++ b/vault/skills/vault-concepts/SKILL.md @@ -8,6 +8,8 @@ description: Maintain canonical concept pages and surface recurring themes Promote recurring themes into canonical concept pages and keep concept navigation coherent. +Portent reference: `../references/portent-knowledge-base-spec.md`. + ## Purpose Maintain `notes/concepts/` as the durable vocabulary of your vault. Surface diff --git a/vault/skills/vault-ingest/SKILL.md b/vault/skills/vault-ingest/SKILL.md index 58cc7de..3d1f32a 100644 --- a/vault/skills/vault-ingest/SKILL.md +++ b/vault/skills/vault-ingest/SKILL.md @@ -11,6 +11,8 @@ Categorize captures in `raw/sources/`, route owned/user-authored material to the right vault directories, and synthesize tagged external sources into curated notes while preserving complete source evidence. +Portent reference: `../references/portent-knowledge-base-spec.md`. + ## Parameters - `--mode report|apply` (default: `report`) diff --git a/vault/skills/vault-lint/SKILL.md b/vault/skills/vault-lint/SKILL.md index e7a6ebb..3a62110 100644 --- a/vault/skills/vault-lint/SKILL.md +++ b/vault/skills/vault-lint/SKILL.md @@ -7,6 +7,8 @@ description: Hygiene pass over active notes, ideas, and projects Run a focused hygiene pass over active vault surface and propose fixes. +Portent reference: `../references/portent-knowledge-base-spec.md`. + ## Parameters - `--scope notes|projects|all` (default: `all`) diff --git a/vault/skills/vault-maintain/SKILL.md b/vault/skills/vault-maintain/SKILL.md index bd83346..129d549 100644 --- a/vault/skills/vault-maintain/SKILL.md +++ b/vault/skills/vault-maintain/SKILL.md @@ -12,6 +12,8 @@ This is the unified entry point for periodic vault care, coordinating ingestion, hygiene, semantic compaction, project tracking, and concept promotion into a single bounded workflow. +Portent reference: `../references/portent-knowledge-base-spec.md`. + ## Command ``` diff --git a/vault/skills/vault-research/SKILL.md b/vault/skills/vault-research/SKILL.md index f801900..ee65695 100644 --- a/vault/skills/vault-research/SKILL.md +++ b/vault/skills/vault-research/SKILL.md @@ -15,6 +15,8 @@ keeps a complete immutable copy in `raw/processed/YYYY-MM-DD/`. Notes tagged `external` are treated as clipped/imported external sources and are eligible for synthesis while preserving the complete source record. +Portent reference: `../references/portent-knowledge-base-spec.md`. + Research briefs are `type: Note` by default. External changes, meetings, incidents, product launches, or decisions that happened are `type: Event`. Every synthesized Note or Event should set `belongs_to` to its primary Project, diff --git a/vault/skills/vault-tracker/SKILL.md b/vault/skills/vault-tracker/SKILL.md index c44e726..90fe4f8 100644 --- a/vault/skills/vault-tracker/SKILL.md +++ b/vault/skills/vault-tracker/SKILL.md @@ -15,6 +15,8 @@ archival. Manage lifecycle and navigation for PORT objects: `Project`, `Operation`, `Responsibility`, and externally tracked `Task` references. +Portent reference: `../references/portent-knowledge-base-spec.md`. + ## Command ```