@phren/cli 0.1.41 → 0.1.44

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/dist/capabilities/cli.js +1 -1
  2. package/dist/capabilities/mcp.js +1 -1
  3. package/dist/capabilities/vscode.js +3 -3
  4. package/dist/capabilities/web-ui.js +29 -29
  5. package/dist/cli/actions.js +1 -13
  6. package/dist/cli/extract.js +3 -2
  7. package/dist/cli/hooks-output.js +15 -6
  8. package/dist/cli/hooks.js +2 -2
  9. package/dist/cli/namespaces-utils.js +1 -1
  10. package/dist/content/archive.js +3 -2
  11. package/dist/content/dedup.js +4 -3
  12. package/dist/content/learning.js +5 -4
  13. package/dist/content/secrets.js +4 -1
  14. package/dist/data/access.js +10 -9
  15. package/dist/data/tasks.js +46 -6
  16. package/dist/finding/lifecycle.js +3 -2
  17. package/dist/governance/policy.js +4 -3
  18. package/dist/governance/scores.d.ts +9 -1
  19. package/dist/governance/scores.js +12 -1
  20. package/dist/init/init-uninstall.js +12 -2
  21. package/dist/profile-store.d.ts +2 -0
  22. package/dist/profile-store.js +13 -17
  23. package/dist/project-config.js +3 -2
  24. package/dist/project-topics.js +13 -12
  25. package/dist/shared/data-utils.js +13 -3
  26. package/dist/shared/fragment-graph.js +7 -2
  27. package/dist/shared/retrieval.d.ts +10 -0
  28. package/dist/shared/retrieval.js +17 -4
  29. package/dist/shell/entry.d.ts +8 -0
  30. package/dist/shell/entry.js +114 -58
  31. package/dist/shell/input.d.ts +1 -1
  32. package/dist/shell/input.js +4 -1
  33. package/dist/shell/keys.d.ts +36 -0
  34. package/dist/shell/keys.js +107 -0
  35. package/dist/shell/render.d.ts +33 -0
  36. package/dist/shell/render.js +216 -46
  37. package/dist/shell/shell.js +16 -3
  38. package/dist/shell/view.js +2 -1
  39. package/dist/store-registry.d.ts +13 -0
  40. package/dist/store-registry.js +106 -34
  41. package/dist/store-routing.d.ts +8 -0
  42. package/dist/store-routing.js +23 -1
  43. package/dist/tools/config.js +4 -3
  44. package/dist/tools/extract-facts.js +3 -2
  45. package/dist/tools/finding.js +6 -5
  46. package/dist/tools/memory.js +12 -5
  47. package/dist/tools/ops.js +1 -1
  48. package/dist/ui/server.js +2 -6
  49. package/dist/utils-fts.js +3 -2
  50. package/dist/utils-paths.d.ts +1 -0
  51. package/dist/utils-paths.js +1 -1
  52. package/dist/utils.d.ts +1 -1
  53. package/dist/utils.js +1 -1
  54. package/package.json +31 -4
  55. package/starter/global/skills/phren-consolidate/SKILL.md +152 -0
  56. package/starter/global/skills/phren-discover/SKILL.md +175 -0
  57. package/starter/global/skills/phren-init/SKILL.md +216 -0
  58. package/starter/global/skills/phren-profiles/SKILL.md +121 -0
  59. package/starter/global/skills/phren-sync/SKILL.md +261 -0
  60. package/dist/init-uninstall.d.ts +0 -3
  61. package/dist/init-uninstall.js +0 -514
  62. package/dist/init-walkthrough.d.ts +0 -55
  63. package/dist/init-walkthrough.js +0 -524
@@ -7,7 +7,8 @@ import { PROACTIVITY_LEVELS, } from "../proactivity.js";
7
7
  import { writeGovernanceInstallPreferences, } from "../init/preferences.js";
8
8
  import { FINDING_SENSITIVITY_CONFIG, buildProactivitySnapshot, checkProjectInProfile } from "../cli/config.js";
9
9
  import { readProjectConfig, updateProjectConfigOverrides, } from "../project-config.js";
10
- import { errorMessage, isValidProjectName, safeProjectPath } from "../utils.js";
10
+ import { errorMessage, isValidProjectName } from "../utils.js";
11
+ import { storeAwareProjectPath } from "../store-routing.js";
11
12
  import { ACCESS_ROLE_KEYS, ACL_LOCKOUT_HINT, permissionDeniedError, setAccessRoles } from "../governance/rbac.js";
12
13
  import { readProjectTopics, writeProjectTopics, } from "../project-topics.js";
13
14
  import { buildConfigView } from "../config/resolve.js";
@@ -41,7 +42,7 @@ function hasOwnOverride(overrides, key) {
41
42
  const projectParam = z.string().optional().describe("Project name. When provided, writes to that project's phren.project.yaml instead of global .config/.");
42
43
  // ── Topic helpers (shared by get_config topic domain and set_config topic domain) ──
43
44
  function getTopicConfigData(phrenPath, project) {
44
- const projectDir = safeProjectPath(phrenPath, project);
45
+ const projectDir = storeAwareProjectPath(phrenPath, project);
45
46
  if (!projectDir || !fs.existsSync(projectDir)) {
46
47
  return { ok: false, error: `Project "${project}" not found in phren.` };
47
48
  }
@@ -533,7 +534,7 @@ async function handleSetConfig(ctx, { domain, settings, project }) {
533
534
  catch (err) {
534
535
  return mcpResponse({ ok: false, error: errorMessage(err) });
535
536
  }
536
- const projectDir = safeProjectPath(topicPhrenPath, topicProject);
537
+ const projectDir = storeAwareProjectPath(topicPhrenPath, topicProject);
537
538
  if (!projectDir || !fs.existsSync(projectDir)) {
538
539
  return mcpResponse({ ok: false, error: `Project "${topicProject}" not found in phren.` });
539
540
  }
@@ -7,14 +7,15 @@
7
7
  import * as fs from "fs";
8
8
  import * as path from "path";
9
9
  import { debugLog } from "../shared.js";
10
- import { safeProjectPath, isFeatureEnabled, errorMessage } from "../utils.js";
10
+ import { isFeatureEnabled, errorMessage } from "../utils.js";
11
+ import { storeAwareProjectPath } from "../store-routing.js";
11
12
  import { callLlm } from "../content/dedup.js";
12
13
  import { withFileLock } from "../shared/governance.js";
13
14
  import { logger } from "../logger.js";
14
15
  const FACT_EXTRACT_FLAG = "PHREN_FEATURE_FACT_EXTRACT";
15
16
  const MAX_FACTS = 50;
16
17
  function preferencesPath(phrenPath, project) {
17
- const dir = safeProjectPath(phrenPath, project);
18
+ const dir = storeAwareProjectPath(phrenPath, project);
18
19
  return dir ? path.join(dir, "preferences.json") : null;
19
20
  }
20
21
  export function readExtractedFacts(phrenPath, project) {
@@ -3,7 +3,8 @@ import { z } from "zod";
3
3
  import * as fs from "fs";
4
4
  import * as path from "path";
5
5
  import { logger } from "../logger.js";
6
- import { isValidProjectName, safeProjectPath, errorMessage } from "../utils.js";
6
+ import { isValidProjectName, errorMessage } from "../utils.js";
7
+ import { storeAwareProjectPath } from "../store-routing.js";
7
8
  import { removeFinding as removeFindingCore, removeFindings as removeFindingsCore, applyFindingTypePrefix, } from "../core/finding.js";
8
9
  import { debugLog, EXEC_TIMEOUT_MS, FINDING_TYPES, normalizeMemoryScope, } from "../shared.js";
9
10
  import { getCurrentActor, getMachineName } from "../machine-identity.js";
@@ -101,7 +102,7 @@ function withLifecycleMutation(phrenPath, project, writeQueue, updateIndex, hand
101
102
  const result = handler();
102
103
  if (!result.ok)
103
104
  return mcpResponse({ ok: false, error: result.error });
104
- const resolvedFindingsDir = safeProjectPath(phrenPath, project);
105
+ const resolvedFindingsDir = storeAwareProjectPath(phrenPath, project);
105
106
  if (resolvedFindingsDir)
106
107
  updateIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
107
108
  const mapped = mapResponse(result.data);
@@ -445,7 +446,7 @@ async function handleEditFinding(ctx, { project: projectInput, old_text, new_tex
445
446
  const result = editFindingCore(phrenPath, project, old_text, new_text);
446
447
  if (!result.ok)
447
448
  return mcpResponse({ ok: false, error: result.error });
448
- const resolvedFindingsDir = safeProjectPath(phrenPath, project);
449
+ const resolvedFindingsDir = storeAwareProjectPath(phrenPath, project);
449
450
  if (resolvedFindingsDir)
450
451
  updateFileInIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
451
452
  return mcpResponse({
@@ -477,7 +478,7 @@ async function handleRemoveFinding(ctx, { project: projectInput, finding }) {
477
478
  const result = removeFindingsCore(phrenPath, project, finding);
478
479
  if (!result.ok)
479
480
  return mcpResponse({ ok: false, error: result.message });
480
- const resolvedFindingsDir = safeProjectPath(phrenPath, project);
481
+ const resolvedFindingsDir = storeAwareProjectPath(phrenPath, project);
481
482
  if (resolvedFindingsDir)
482
483
  updateFileInIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
483
484
  return mcpResponse({ ok: true, message: result.message, data: result.data });
@@ -487,7 +488,7 @@ async function handleRemoveFinding(ctx, { project: projectInput, finding }) {
487
488
  const result = removeFindingCore(phrenPath, project, finding);
488
489
  if (!result.ok)
489
490
  return mcpResponse({ ok: false, error: result.message });
490
- const resolvedFindingsDir = safeProjectPath(phrenPath, project);
491
+ const resolvedFindingsDir = storeAwareProjectPath(phrenPath, project);
491
492
  if (resolvedFindingsDir)
492
493
  updateFileInIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
493
494
  return mcpResponse({ ok: true, message: result.message, data: result.data });
@@ -6,6 +6,12 @@ import { runtimeDir } from "../shared.js";
6
6
  import { recordFeedback, flushEntryScores, } from "../shared/governance.js";
7
7
  import { upsertCanonical } from "../shared/content.js";
8
8
  import { isValidProjectName } from "../utils.js";
9
+ import { storeAwareProjectPath } from "../store-routing.js";
10
+ /** truths.md path via the same store-aware routing upsertCanonical writes with. */
11
+ function truthsFilePath(phrenPath, project) {
12
+ return storeAwareProjectPath(phrenPath, project, "truths.md")
13
+ ?? path.join(phrenPath, project, "truths.md");
14
+ }
9
15
  export function register(server, ctx) {
10
16
  const { withWriteQueue, updateFileInIndex } = ctx;
11
17
  server.registerTool("pin_memory", {
@@ -32,8 +38,7 @@ export function register(server, ctx) {
32
38
  const result = upsertCanonical(phrenPath, project, memory);
33
39
  if (!result.ok)
34
40
  return mcpResponse({ ok: false, error: result.error });
35
- const canonicalPath = path.join(phrenPath, project, "truths.md");
36
- updateFileInIndex(canonicalPath);
41
+ updateFileInIndex(truthsFilePath(phrenPath, project));
37
42
  return mcpResponse({ ok: true, message: result.data, data: { project, memory } });
38
43
  });
39
44
  });
@@ -56,7 +61,7 @@ export function register(server, ctx) {
56
61
  }
57
62
  if (!isValidProjectName(project))
58
63
  return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
59
- const truthsPath = path.join(phrenPath, project, "truths.md");
64
+ const truthsPath = truthsFilePath(phrenPath, project);
60
65
  if (!fs.existsSync(truthsPath)) {
61
66
  return mcpResponse({ ok: true, message: `No truths pinned for "${project}" yet.`, data: { project, truths: [], count: 0 } });
62
67
  }
@@ -74,9 +79,11 @@ export function register(server, ctx) {
74
79
  });
75
80
  server.registerTool("memory_feedback", {
76
81
  title: "◆ phren · feedback",
77
- description: "Record feedback on whether an injected memory was helpful or noisy/regressive.",
82
+ description: "Record feedback on whether an injected memory was helpful or noisy/regressive. " +
83
+ "The key is printed in <phren-context> snippet headers as `fb:<project>/<file>:<digest>` — pass that token (with or without the `fb:` prefix). " +
84
+ "Feedback adjusts that memory's ranking weight in future injections.",
78
85
  inputSchema: z.object({
79
- key: z.string().describe("Memory key to score."),
86
+ key: z.string().describe("Feedback key from an injected snippet header, e.g. `fb:myproj/FINDINGS.md:a1b2c3d4e5f6` or `myproj/FINDINGS.md:a1b2c3d4e5f6`."),
80
87
  feedback: z.enum(["helpful", "reprompt", "regression"]).describe("Feedback type."),
81
88
  }),
82
89
  }, async ({ key, feedback }) => {
package/dist/tools/ops.js CHANGED
@@ -494,7 +494,7 @@ export function register(server, ctx) {
494
494
  }, (params) => handleGetReviewQueue(ctx, params));
495
495
  server.registerTool("manage_review_item", {
496
496
  title: "◆ phren · manage review item",
497
- description: "Manage a review queue item: approve (removes from queue, finding stays), reject (removes from queue AND FINDINGS.md), or edit (updates text in both).",
497
+ description: "Manage a review queue item: approve (PROMOTES the queued line into FINDINGS.md — if the finding is already present or archived it just dequeues), reject (removes from queue AND FINDINGS.md), or edit (updates text in both).",
498
498
  inputSchema: z.object({
499
499
  project: z.string().describe("Project name."),
500
500
  line: z.string().max(10000).describe("The raw queue line text (as returned by get_review_queue)."),
package/dist/ui/server.js CHANGED
@@ -15,7 +15,8 @@ import { buildGraph, collectProjectsForUI, collectSkillsForUI, getHooksData, isA
15
15
  import { lookupEventsLogFile } from "../shared.js";
16
16
  import { CONSOLIDATION_ENTRY_THRESHOLD } from "../content/validate.js";
17
17
  import { ensureTopicReferenceDoc, getProjectTopicsResponse, listProjectReferenceDocs, pinProjectTopicSuggestion, readReferenceContent, reclassifyLegacyTopicDocs, unpinProjectTopicSuggestion, writeProjectTopics, } from "../project-topics.js";
18
- import { getWorkflowPolicy, updateWorkflowPolicy, mergeConfig, getRetentionPolicy, getProjectConfigOverrides, getIndexPolicy, updateIndexPolicy, VALID_TASK_MODES } from "../governance/policy.js";
18
+ import { getWorkflowPolicy, updateWorkflowPolicy, updateRetentionPolicy, mergeConfig, getRetentionPolicy, getProjectConfigOverrides, getIndexPolicy, updateIndexPolicy, VALID_TASK_MODES } from "../governance/policy.js";
19
+ import { listProfiles, setMachineProfile, getDefaultMachineAlias } from "../profile-store.js";
19
20
  import { setAccessRoles, ACCESS_ROLE_KEYS, permissionDeniedError } from "../governance/rbac.js";
20
21
  import { readProjectConfig, updateProjectConfigOverrides } from "../project-config.js";
21
22
  import { buildConfigView } from "../config/resolve.js";
@@ -1009,7 +1010,6 @@ function handlePostSettingsMcpEnabled(req, res, url, ctx) {
1009
1010
  }
1010
1011
  function handleGetProfiles(res, ctx) {
1011
1012
  try {
1012
- const { listProfiles } = require("../profile-store.js");
1013
1013
  const profileResult = listProfiles(ctx.phrenPath);
1014
1014
  if (!profileResult.ok) {
1015
1015
  return jsonOk(res, { ok: false, error: profileResult.error, profiles: [] });
@@ -1027,7 +1027,6 @@ function handlePostProfile(req, res, url, ctx) {
1027
1027
  if (!profileName)
1028
1028
  return jsonErr(res, "Profile name required", 400);
1029
1029
  try {
1030
- const { setMachineProfile, getDefaultMachineAlias } = require("../profile-store.js");
1031
1030
  const machineAlias = getDefaultMachineAlias();
1032
1031
  const result = setMachineProfile(ctx.phrenPath, machineAlias, profileName);
1033
1032
  if (!result.ok)
@@ -1082,7 +1081,6 @@ function handlePostSettingsProjectOverrides(req, res, url, ctx) {
1082
1081
  if (globalUpdate) {
1083
1082
  try {
1084
1083
  if (NUMERIC_RETENTION_FIELDS.includes(field)) {
1085
- const { updateRetentionPolicy } = require("../governance/policy.js");
1086
1084
  let updateData = {};
1087
1085
  if (!clearField) {
1088
1086
  const num = parseFloat(value);
@@ -1096,7 +1094,6 @@ function handlePostSettingsProjectOverrides(req, res, url, ctx) {
1096
1094
  return jsonOk(res, { ok: true, retentionPolicy: result.data });
1097
1095
  }
1098
1096
  else if (field.startsWith("decay.")) {
1099
- const { updateRetentionPolicy } = require("../governance/policy.js");
1100
1097
  const point = field.slice("decay.".length);
1101
1098
  let updateData = {};
1102
1099
  if (!clearField) {
@@ -1118,7 +1115,6 @@ function handlePostSettingsProjectOverrides(req, res, url, ctx) {
1118
1115
  return jsonOk(res, { ok: true, workflowPolicy: result.data });
1119
1116
  }
1120
1117
  else if (NUMERIC_WORKFLOW_FIELDS.includes(field)) {
1121
- const { updateWorkflowPolicy } = require("../governance/policy.js");
1122
1118
  let updateData = {};
1123
1119
  if (!clearField) {
1124
1120
  const num = parseFloat(value);
package/dist/utils-fts.js CHANGED
@@ -3,7 +3,8 @@ import * as path from "path";
3
3
  import * as yaml from "js-yaml";
4
4
  import { fileURLToPath } from "url";
5
5
  import { findPhrenPath } from "./phren-paths.js";
6
- import { isValidProjectName, safeProjectPath } from "./utils-paths.js";
6
+ import { isValidProjectName } from "./utils-paths.js";
7
+ import { storeAwareProjectPath } from "./store-routing.js";
7
8
  // Lazy import of logDebug to break circular dependency:
8
9
  // utils.ts -> phren-paths.ts -> logger.ts -> phren-paths.ts -> utils.ts
9
10
  let _logDebug;
@@ -184,7 +185,7 @@ function parseLearnedSynonymsJson(filePath) {
184
185
  export function learnedSynonymsPath(phrenPath, project) {
185
186
  if (!isValidProjectName(project))
186
187
  return null;
187
- return safeProjectPath(phrenPath, project, LEARNED_SYNONYMS_FILE);
188
+ return storeAwareProjectPath(phrenPath, project, LEARNED_SYNONYMS_FILE);
188
189
  }
189
190
  export function loadLearnedSynonyms(project, phrenPath) {
190
191
  if (!project || !isValidProjectName(project))
@@ -1,3 +1,4 @@
1
1
  export declare function isValidProjectName(name: string): boolean;
2
2
  export declare function safeProjectPath(base: string, ...segments: string[]): string | null;
3
+ export declare const QUEUE_FILENAME = "review.md";
3
4
  export declare function queueFilePath(phrenPath: string, project: string): string;
@@ -48,7 +48,7 @@ export function safeProjectPath(base, ...segments) {
48
48
  }
49
49
  return resolved;
50
50
  }
51
- const QUEUE_FILENAME = "review.md";
51
+ export const QUEUE_FILENAME = "review.md";
52
52
  export function queueFilePath(phrenPath, project) {
53
53
  if (!isValidProjectName(project)) {
54
54
  throw new Error(`Invalid project name: ${project}`);
package/dist/utils.d.ts CHANGED
@@ -1,3 +1,3 @@
1
1
  export { runGitOrThrow, runGit, normalizeExecCommand, resolveExecCommand, errorMessage, isFeatureEnabled, clampInt, getOptionValue, getPositionalArgs, } from "./utils-helpers.js";
2
- export { isValidProjectName, safeProjectPath, queueFilePath, } from "./utils-paths.js";
2
+ export { isValidProjectName, safeProjectPath, queueFilePath, QUEUE_FILENAME, } from "./utils-paths.js";
3
3
  export { STOP_WORDS, extractKeywordEntries, extractKeywords, learnedSynonymsPath, loadLearnedSynonyms, loadSynonymMap, learnSynonym, removeLearnedSynonym, sanitizeFts5Query, buildRobustFtsQuery, buildRelaxedFtsQuery, buildFtsQueryVariants, } from "./utils-fts.js";
package/dist/utils.js CHANGED
@@ -2,5 +2,5 @@
2
2
  // helpers, argv parsing, exec helpers), utils-paths.ts (path validation),
3
3
  // utils-fts.ts (FTS5 query building, synonym/keyword extraction).
4
4
  export { runGitOrThrow, runGit, normalizeExecCommand, resolveExecCommand, errorMessage, isFeatureEnabled, clampInt, getOptionValue, getPositionalArgs, } from "./utils-helpers.js";
5
- export { isValidProjectName, safeProjectPath, queueFilePath, } from "./utils-paths.js";
5
+ export { isValidProjectName, safeProjectPath, queueFilePath, QUEUE_FILENAME, } from "./utils-paths.js";
6
6
  export { STOP_WORDS, extractKeywordEntries, extractKeywords, learnedSynonymsPath, loadLearnedSynonyms, loadSynonymMap, learnSynonym, removeLearnedSynonym, sanitizeFts5Query, buildRobustFtsQuery, buildRelaxedFtsQuery, buildFtsQueryVariants, } from "./utils-fts.js";
package/package.json CHANGED
@@ -1,11 +1,13 @@
1
1
  {
2
2
  "name": "@phren/cli",
3
- "version": "0.1.41",
4
- "description": "Knowledge layer for AI agents — CLI, MCP server, and data layer",
3
+ "version": "0.1.44",
4
+ "description": "Knowledge layer for AI agents \u2014 CLI, MCP server, and data layer",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "phren": "dist/index.js"
8
8
  },
9
+ "main": "./dist/index.js",
10
+ "types": "./dist/index.d.ts",
9
11
  "exports": {
10
12
  ".": {
11
13
  "types": "./dist/index.d.ts",
@@ -27,6 +29,26 @@
27
29
  "types": "./dist/shared/retrieval.d.ts",
28
30
  "default": "./dist/shared/retrieval.js"
29
31
  },
32
+ "./shared/content": {
33
+ "types": "./dist/shared/content.d.ts",
34
+ "default": "./dist/shared/content.js"
35
+ },
36
+ "./shared/governance": {
37
+ "types": "./dist/shared/governance.d.ts",
38
+ "default": "./dist/shared/governance.js"
39
+ },
40
+ "./skill/registry": {
41
+ "types": "./dist/skill/registry.d.ts",
42
+ "default": "./dist/skill/registry.js"
43
+ },
44
+ "./cli/extract": {
45
+ "types": "./dist/cli/extract.d.ts",
46
+ "default": "./dist/cli/extract.js"
47
+ },
48
+ "./store-routing": {
49
+ "types": "./dist/store-routing.d.ts",
50
+ "default": "./dist/store-routing.js"
51
+ },
30
52
  "./data/access": {
31
53
  "types": "./dist/data/access.d.ts",
32
54
  "default": "./dist/data/access.js"
@@ -82,14 +104,12 @@
82
104
  "preuninstall": "node scripts/preuninstall.mjs"
83
105
  },
84
106
  "dependencies": {
85
- "3d-force-graph": "^1.80.0",
86
107
  "@modelcontextprotocol/sdk": "^1.29.0",
87
108
  "chalk": "^5.6.2",
88
109
  "glob": "^13.0.6",
89
110
  "inquirer": "^14.0.2",
90
111
  "js-yaml": "^4.2.0",
91
112
  "sql.js-fts5": "^1.4.0",
92
- "three": "^0.184.0",
93
113
  "zod": "^4.4.3"
94
114
  },
95
115
  "engines": {
@@ -108,5 +128,12 @@
108
128
  "type": "git",
109
129
  "url": "git+https://github.com/alaarab/phren.git",
110
130
  "directory": "packages/cli"
131
+ },
132
+ "devDependencies": {
133
+ "3d-force-graph": "^1.80.0",
134
+ "three": "^0.184.0"
135
+ },
136
+ "publishConfig": {
137
+ "access": "public"
111
138
  }
112
139
  }
@@ -0,0 +1,152 @@
1
+ ---
2
+ name: phren-consolidate
3
+ description: Find patterns across project findings and surface insights that apply everywhere.
4
+ dependencies:
5
+ - git
6
+ ---
7
+ # phren-consolidate - Cross-project synthesis
8
+
9
+ > Find patterns across project findings and surface insights that apply everywhere.
10
+
11
+ Read every project's FINDINGS.md, find patterns that show up across multiple projects, and write them to a shared global findings file.
12
+
13
+ The point: something you learned on one project probably applies elsewhere. This surfaces those connections.
14
+
15
+ ## Prerequisites
16
+
17
+ This skill needs at least two projects with FINDINGS.md files to be useful. If you haven't captured any findings yet, use `add_finding()` during a session first.
18
+
19
+ **Works with or without profiles.** If profiles are set up, it scans projects in the active profile. If not, it scans all project directories in the phren repo.
20
+
21
+ ## When to run
22
+
23
+ - Monthly, or when the user asks
24
+ - After a burst of work across multiple projects
25
+ - When starting a new project (to seed it with relevant cross-cutting knowledge)
26
+
27
+ ## What to do
28
+
29
+ ### 1. Find the phren directory
30
+
31
+ ```bash
32
+ PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
33
+ ls "$PHREN_DIR" 2>/dev/null
34
+ ```
35
+
36
+ If it doesn't exist, tell the user:
37
+ > "No phren directory found at ~/.phren. This skill needs a phren repo with project findings. Run `phren-init` to set one up, or set PHREN_DIR if yours is elsewhere."
38
+
39
+ ### 2. Gather ALL findings
40
+
41
+ Try the profile-aware path first, fall back to scanning all directories:
42
+
43
+ ```bash
44
+ MACHINE=$(cat ~/.phren/.machine-id 2>/dev/null || hostname)
45
+ # look up profile in machines.yaml to get the project list
46
+
47
+ # fallback: scan all project directories
48
+ FINDINGS_FILES=()
49
+ for dir in "$PHREN_DIR"/*/; do
50
+ if [ -f "$dir/FINDINGS.md" ]; then
51
+ PROJECT_NAME=$(basename "$dir")
52
+ FINDINGS_FILES+=("$PROJECT_NAME:$dir/FINDINGS.md")
53
+ fi
54
+ done
55
+ ```
56
+
57
+ Read **every** FINDINGS.md file found. Don't sample or skip any. For each file, track which project it came from.
58
+
59
+ If no FINDINGS.md files exist anywhere, tell the user:
60
+ > "No FINDINGS.md files found in any project. Use `add_finding()` during a work session to start capturing findings."
61
+
62
+ If only one project has a FINDINGS.md, tell the user:
63
+ > "Only found findings for <project>. Need at least two projects to find cross-cutting patterns. Use `add_finding()` in other projects first."
64
+
65
+ ### 3. Find cross-cutting patterns
66
+
67
+ Compare findings across all projects. A pattern counts as cross-cutting when the **same insight, technique, or pitfall** appears in 2+ projects. Don't just look for keyword overlap; look for conceptual overlap.
68
+
69
+ Be specific. Not "testing is important" but "mocking at service boundaries instead of HTTP layer caught integration bugs in both my-app and backend."
70
+
71
+ Common categories (use only the ones that have actual matches):
72
+
73
+ - **Build and tooling**: cache issues, config pitfalls, CI patterns
74
+ - **Testing**: mocking strategies, fixture patterns, what to test vs skip
75
+ - **TypeScript/JS**: type tricks, async pitfalls, framework quirks
76
+ - **State management**: reactivity pitfalls, update ordering, stale closures
77
+ - **API patterns**: error handling, retry logic, auth flows
78
+ - **Performance**: what actually mattered vs premature optimization
79
+ - **Git and workflow**: branching patterns, commit conventions, release steps
80
+ - **Dependencies**: version conflicts, peer dep issues, lock file handling
81
+
82
+ Don't force categories. If only one project mentions something, it stays project-specific. If a pattern genuinely spans projects, include it even if it doesn't fit a neat category.
83
+
84
+ ### 4. Check existing global findings
85
+
86
+ Before writing, read `$PHREN_DIR/global/FINDINGS.md` if it exists. Don't duplicate entries that are already there. Update existing entries if there's new evidence or additional projects that confirm the pattern.
87
+
88
+ ### 5. Write global findings
89
+
90
+ File: `$PHREN_DIR/global/FINDINGS.md`
91
+
92
+ ```markdown
93
+ # Cross-project findings
94
+
95
+ Last consolidated: <date>
96
+ Sources: <list of project names scanned>
97
+
98
+ ## Build and tooling
99
+ - Clear dist/ after any tsconfig change, the build cache doesn't invalidate (my-app, backend)
100
+ - Lock file conflicts: delete and regenerate, don't try to merge (my-app, frontend)
101
+
102
+ ## Testing
103
+ - Mock at the service boundary, not the HTTP layer (backend, frontend)
104
+ - Session-scoped fixtures cause flaky parallel tests (backend, my-app)
105
+ ```
106
+
107
+ Rules for each entry:
108
+ - Include which projects it came from in parentheses
109
+ - Be specific enough that someone could act on it without reading the original findings
110
+ - If two projects describe the same thing differently, synthesize into one clear statement
111
+ - Keep entries to 1-2 lines max
112
+
113
+ ### 6. Report
114
+
115
+ ```
116
+ phren-consolidate
117
+
118
+ Scanned: my-app (12 findings), backend (8 findings), frontend (5 findings)
119
+
120
+ Found 6 cross-cutting patterns:
121
+ Build: 2 patterns (cache invalidation, lock file handling)
122
+ Testing: 2 patterns (mock boundaries, fixture scoping)
123
+ TypeScript: 2 patterns (strict nulls, path aliases)
124
+
125
+ New patterns added: 4
126
+ Existing patterns updated: 2 (added new project evidence)
127
+ Skipped: 0 (already captured)
128
+
129
+ Updated: $PHREN_DIR/global/FINDINGS.md
130
+ ```
131
+
132
+ ### 7. Commit (if git repo)
133
+
134
+ ```bash
135
+ cd "$PHREN_DIR"
136
+ git add global/FINDINGS.md
137
+ git commit -m "update global findings"
138
+ git push # only if remote exists
139
+ ```
140
+
141
+ ## What not to do
142
+
143
+ - Don't include findings that only apply to one project. Those stay in the project's own file.
144
+ - Don't water down specifics to make them "general." If it's about Angular signals specifically, say so.
145
+ - Don't duplicate what's already in global findings. Update existing entries if there's new evidence.
146
+ - Don't create a wall of text. Keep it scannable. Bullet points, grouped by theme.
147
+ - Don't invent patterns. If two findings use the same word but describe different problems, they're not a pattern.
148
+
149
+ ## Related skills
150
+
151
+ - `add_finding()`: capture findings during a session via MCP
152
+ - `phren-sync`: sync the consolidated findings to other machines
@@ -0,0 +1,175 @@
1
+ ---
2
+ name: phren-discover
3
+ description: Audit your phren repo and tell you exactly what needs attention.
4
+ dependencies:
5
+ - git
6
+ - gh
7
+ ---
8
+ # phren-discover - Phren health check
9
+
10
+ > Audit your phren repo and tell you exactly what needs attention.
11
+
12
+ Scans your phren directory for missing files, stale content, skill gaps, and stuck task items. Outputs a concrete, prioritized action list.
13
+
14
+ **Works standalone.** Just needs a phren directory.
15
+
16
+ ## When to run
17
+
18
+ - Weekly or monthly maintenance
19
+ - When you feel like things are getting messy
20
+ - Before starting a new project (to see what you've been neglecting)
21
+ - When the user asks "what should I work on"
22
+
23
+ ## What to do
24
+
25
+ ### 1. Find the phren directory
26
+
27
+ ```bash
28
+ PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
29
+ ls "$PHREN_DIR" 2>/dev/null
30
+ ```
31
+
32
+ If it doesn't exist:
33
+ > "No phren directory found at ~/.phren. Run `phren-init` to set one up."
34
+
35
+ ### 2. Scan all projects
36
+
37
+ For each project directory in `$PHREN_DIR/*/` (skip `global/`, `profiles/`):
38
+
39
+ ```bash
40
+ for dir in "$PHREN_DIR"/*/; do
41
+ PROJECT=$(basename "$dir")
42
+ [ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue
43
+
44
+ [ -f "$dir/CLAUDE.md" ] && echo "$PROJECT: has CLAUDE.md" || echo "$PROJECT: MISSING CLAUDE.md"
45
+ [ -f "$dir/summary.md" ] && echo "$PROJECT: has summary.md" || echo "$PROJECT: MISSING summary.md"
46
+ [ -f "$dir/FINDINGS.md" ] && echo "$PROJECT: has FINDINGS.md" || echo "$PROJECT: MISSING FINDINGS.md"
47
+ [ -f "$dir/tasks.md" ] && echo "$PROJECT: has tasks.md" || echo "$PROJECT: MISSING tasks.md"
48
+ done
49
+ ```
50
+
51
+ ### 3. Check staleness
52
+
53
+ For projects that are in a git-tracked phren, check when files were last modified:
54
+
55
+ ```bash
56
+ cd "$PHREN_DIR"
57
+ for dir in */; do
58
+ PROJECT=$(basename "$dir")
59
+ [ "$PROJECT" = "global" ] || [ "$PROJECT" = "profiles" ] && continue
60
+
61
+ if [ -f "$dir/FINDINGS.md" ]; then
62
+ LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/FINDINGS.md" 2>/dev/null || stat -c %Y "$dir/FINDINGS.md" 2>/dev/null || stat -f %m "$dir/FINDINGS.md" 2>/dev/null)
63
+ echo "$PROJECT/FINDINGS.md: last updated $LAST_MODIFIED"
64
+ fi
65
+
66
+ if [ -f "$dir/CLAUDE.md" ]; then
67
+ LAST_MODIFIED=$(git log -1 --format="%cr" -- "$dir/CLAUDE.md" 2>/dev/null || stat -c %Y "$dir/CLAUDE.md" 2>/dev/null || stat -f %m "$dir/CLAUDE.md" 2>/dev/null)
68
+ echo "$PROJECT/CLAUDE.md: last updated $LAST_MODIFIED"
69
+ fi
70
+ done
71
+ ```
72
+
73
+ Flag anything not updated in 30+ days as stale.
74
+
75
+ ### 4. Detect skill gaps
76
+
77
+ Look at patterns in tasks.md files and FINDINGS.md files across projects. A skill gap is when:
78
+ - Multiple projects repeat the same manual process (e.g., "remember to update the changelog," which should be a skill)
79
+ - A FINDINGS.md entry says "next time, do X first," which is a skill waiting to happen
80
+ - A task item keeps getting deferred, and might need a skill to make it easier
81
+
82
+ Also check global/skills/ to see what skills exist, and whether any project's workflow isn't covered.
83
+
84
+ ### 5. Check task health
85
+
86
+ For each project with a tasks.md:
87
+ - Count total items, completed items, items with no recent progress
88
+ - Flag tasks where nothing has been completed recently
89
+ - Flag tasks with items older than 60 days that haven't moved
90
+
91
+ ### 6. Scaffold missing summary.md files
92
+
93
+ For each project with a missing summary.md, output the template and offer to create it:
94
+
95
+ ```
96
+ Project: myapp
97
+ MISSING: summary.md
98
+
99
+ Template:
100
+ ```
101
+ # myapp
102
+
103
+ What:
104
+ Stack:
105
+ Status: active
106
+ Run:
107
+ Watch out:
108
+ ```
109
+
110
+ Want me to fill this in for myapp?
111
+ ```
112
+
113
+ If yes, gather the 5 fields from the user and write the file to `$PHREN_DIR/myapp/summary.md`.
114
+
115
+ ### 7. Output the report
116
+
117
+ ```
118
+ phren-discover
119
+
120
+ ## Section 1: Missing files
121
+
122
+ Projects without core files:
123
+
124
+ | Project | CLAUDE.md | summary.md | FINDINGS.md | tasks.md |
125
+ |---------|-----------|------------|--------------|------------|
126
+ | myapp | ok | MISSING | MISSING | ok |
127
+ | api | ok | ok | ok | MISSING |
128
+
129
+ ## Section 2: Stale content
130
+
131
+ Files not updated in 30+ days:
132
+ - my-app/FINDINGS.md: last updated 45 days ago
133
+ - frontend/CLAUDE.md: last updated 62 days ago
134
+
135
+ ## Section 3: Skill gaps
136
+
137
+ Things you do repeatedly that could be skills:
138
+ - "Update changelog before release" appears in 3 project tasks. Consider a `/changelog` skill.
139
+ - my-app FINDINGS.md mentions "always run parity check" 4 times. Already have `/parity`, but it's not in the workflow skill.
140
+
141
+ ## Section 4: Task health
142
+
143
+ - my-app: 12 items (3 completed, 2 stale > 60 days)
144
+ - backend: 5 items (0 completed, all stale)
145
+ - frontend: 8 items (6 completed, healthy)
146
+
147
+ Stuck items:
148
+ - backend#2: "Add rate limiting" (added 90 days ago, no progress)
149
+ - my-app#7: "Improve query performance" (added 75 days ago, no progress)
150
+
151
+ ## Top 3 things to work on next
152
+
153
+ 1. **Add FINDINGS.md to myapp.** You've been working on it actively but capturing nothing. Use `add_finding()` during your next session.
154
+ 2. **Unstick api-server task.** 5 items, 0 completed. Either work them or trim them. Stale tasks are worse than no task.
155
+ 3. **Create a `/changelog` skill.** You're doing it manually in 3 projects. 15 minutes to write the skill saves hours over time.
156
+ ```
157
+
158
+ The "Top 3" section is the most important part. Make these:
159
+ - Concrete (not "improve documentation" but "add FINDINGS.md to myapp")
160
+ - Prioritized (highest impact first)
161
+ - Actionable (someone could start right now)
162
+
163
+ ## What not to do
164
+
165
+ - Don't flag missing files in projects that are archived or inactive
166
+ - Don't recommend creating files just for completeness; only flag what would actually help
167
+ - Don't be vague in the Top 3. Every item should be a clear next action.
168
+ - Don't pad the report with things that are fine. Focus on what needs attention.
169
+
170
+ ## Related skills
171
+
172
+ - `phren-init`: scaffold missing files for a project
173
+ - `add_finding()`: capture findings via MCP (fixes "missing FINDINGS.md")
174
+ - `phren-consolidate`: synthesize cross-project patterns
175
+ - `/tasks`: work on stuck task items