portable-agent-layer 0.30.1 → 0.32.0

package/assets/skills/consulting-report/tools/scaffold.ts

@@ -1,29 +1,23 @@
 #!/usr/bin/env bun
 
-// consulting-report skill tool: scaffold a new report directory from the template.
+// consulting-report skill tool: scaffold a new report directory from the template
+// and install Next.js dependencies.
 //
 // Usage:
-//   bun ~/.pal/skills/consulting-report/tools/scaffold.ts <target-dir> [--client "Client Name"] [--title "Report Title"]
+//   bun ~/.pal/skills/consulting-report/tools/scaffold.ts <target-dir> \
+//        [--client "Client Name"] [--title "Report Title"] [--no-install]
 
+import { spawnSync } from "node:child_process";
 import { constants as fsConstants } from "node:fs";
 import { access, cp, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const args = process.argv.slice(2);
-if (args.length === 0) {
-  console.error(
-    'usage: scaffold.ts <target-dir> [--client "Client Name"] [--title "Report Title"]'
-  );
-  process.exit(1);
-}
-
-const targetDir = resolve(args[0]);
-let clientName = "";
-let reportTitle = "";
-for (let i = 1; i < args.length; i++) {
-  if (args[i] === "--client") clientName = args[++i];
-  else if (args[i] === "--title") reportTitle = args[++i];
+interface ScaffoldOptions {
+  targetDir: string;
+  clientName?: string;
+  reportTitle?: string;
+  install?: boolean;
 }
 
 async function exists(p: string): Promise<boolean> {
@@ -35,40 +29,81 @@ async function exists(p: string): Promise<boolean> {
   }
 }
 
-const here = dirname(fileURLToPath(import.meta.url));
-const templateDir = resolve(here, "..", "template");
-
-if (!(await exists(templateDir))) {
-  console.error(`template not found at ${templateDir}`);
-  process.exit(1);
+function templateDir(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, "..", "template");
 }
-if (await exists(targetDir)) {
-  console.error(`target already exists: ${targetDir}`);
-  process.exit(1);
+
+export async function scaffold(opts: ScaffoldOptions): Promise<void> {
+  const tpl = templateDir();
+  if (!(await exists(tpl))) {
+    throw new Error(`template not found at ${tpl}`);
+  }
+  if (await exists(opts.targetDir)) {
+    throw new Error(`target already exists: ${opts.targetDir}`);
+  }
+
+  await mkdir(dirname(opts.targetDir), { recursive: true });
+  await cp(tpl, opts.targetDir, { recursive: true });
+
+  if (opts.clientName || opts.reportTitle) {
+    const dataPath = join(opts.targetDir, "lib", "report-data.ts");
+    let data = await readFile(dataPath, "utf8");
+    if (opts.clientName) {
+      data = data.replace(/\[CLIENT NAME\]/g, opts.clientName);
+    }
+    if (opts.reportTitle) {
+      data = data.replace(
+        /Strategic Assessment & Transformation Roadmap/,
+        opts.reportTitle
+      );
+    }
+    await writeFile(dataPath, data, "utf8");
+  }
+
+  if (opts.install !== false) {
+    console.log("Installing dependencies (bun install)...");
+    const result = spawnSync("bun", ["install"], {
+      cwd: opts.targetDir,
+      stdio: "inherit",
+      shell: true,
+    });
+    if (result.status !== 0) {
+      console.warn(
+        `bun install failed (exit ${result.status}) — run it manually in ${opts.targetDir}`
+      );
+    }
+  }
 }
 
-await mkdir(dirname(targetDir), { recursive: true });
-await cp(templateDir, targetDir, { recursive: true });
+function parseArgs(argv: string[]): ScaffoldOptions {
+  if (argv.length === 0) {
+    throw new Error(
+      'usage: scaffold.ts <target-dir> [--client "Name"] [--title "Title"] [--no-install]'
+    );
+  }
+  const opts: ScaffoldOptions = { targetDir: resolve(argv[0]) };
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i] === "--client") opts.clientName = argv[++i];
+    else if (argv[i] === "--title") opts.reportTitle = argv[++i];
+    else if (argv[i] === "--no-install") opts.install = false;
+  }
+  return opts;
+}
 
-// Stamp today's date + client/title + tool import path into the new report-data.ts.
-// Scaffolded reports live outside the skill tree, so the type-import needs an
-// absolute path to the generator rather than a relative one.
-const dataPath = join(targetDir, "content", "report-data.ts");
-const toolPath = resolve(here, "generate-pdf").replace(/\.ts$/, "");
-const today = new Date().toISOString().slice(0, 10);
-let data = await readFile(dataPath, "utf8");
-data = data.replace(/\{\{DATE\}\}/g, today);
-data = data.replace(/\{\{TOOL_PATH\}\}/g, toolPath);
-if (clientName) data = data.replace(/\{\{CLIENT_NAME\}\}/g, clientName);
-if (reportTitle) data = data.replace(/\{\{REPORT_TITLE\}\}/g, reportTitle);
-await writeFile(dataPath, data, "utf8");
+export async function run(argv: string[] = process.argv.slice(2)): Promise<void> {
+  const opts = parseArgs(argv);
+  await scaffold(opts);
+  console.log(`Scaffolded: ${opts.targetDir}`);
+  console.log("Next steps:");
+  console.log(`  1. cd ${opts.targetDir}`);
+  console.log(`  2. Edit lib/report-data.ts (metadata) and app/page.tsx (layout)`);
+  console.log(`  3. Live preview:    bun run dev`);
+  console.log(
+    `  4. Generate PDF:    node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts ${opts.targetDir}`
+  );
+}
 
-console.log(`Scaffolded: ${targetDir}`);
-console.log("Next steps:");
-console.log(`  1. Edit ${join(targetDir, "content", "report-data.ts")}`);
-console.log(`  2. Fill ${join(targetDir, "content")} with your section markdown files`);
-console.log(`  3. Drop images into ${join(targetDir, "diagrams")}`);
-console.log(`  4. Render:`);
-console.log(
-  `       node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts ${targetDir}`
-);
+if (import.meta.main) {
+  await run();
+}

package/assets/skills/presentation/SKILL.md

@@ -32,7 +32,7 @@ bun ~/.pal/skills/presentation/tools/setup-template.ts \
   --logo <abs-path-to-logo.svg> \
   --primary "#0E1335" \
   [--accent "#FFB84D"] \
-  [--footer "Konvert7 · 2026"] \
+  [--footer "Your Brand · 2026"] \
   [--logo-placement "footer"] \
   [--fonts "system"] \
   [--aspect "16:9"] \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.30.1",
+  "version": "0.32.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -61,8 +61,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.7",
-    "@commitlint/cli": "^20.5.0",
-    "@commitlint/config-conventional": "^20.5.0",
+    "@commitlint/cli": "^20.5.3",
+    "@commitlint/config-conventional": "^20.5.3",
     "@opencode-ai/plugin": "latest",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
@@ -72,14 +72,14 @@
     "@types/node": "latest",
     "husky": "^9.1.7",
     "knip": "^6.9.0",
-    "lint-staged": "^15.5.0",
+    "lint-staged": "^15.5.2",
     "semantic-release": "^25.0.3",
-    "typescript": "^5.9.0"
+    "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@clack/prompts": "^1.1.0",
-    "adm-zip": "^0.5.16",
-    "marked": "^15.0.0",
-    "playwright": "^1.49.0"
+    "@clack/prompts": "^1.3.0",
+    "adm-zip": "^0.5.17",
+    "marked": "^15.0.12",
+    "playwright": "^1.59.1"
   }
 }

package/assets/skills/consulting-report/demo/content/current-state.md

@@ -1,33 +0,0 @@
-## Production Deploy Pipeline
-
-The current pipeline is a linear GitHub Actions workflow: PR → staging → canary → production. There are health checks at each stage, and SLO-based gates block on red. What's missing is a rollback step: once traffic is shifted to a new version, reverting requires a manual re-deploy of the previous image, which in 4 out of the last 12 incidents required direct database work because schema migrations had already run.
-
-| Stage | Automated | Gate | Rollback |
-|-------|-----------|------|----------|
-| PR checks | Yes | Unit + integration tests | N/A |
-| Staging deploy | Yes | Smoke tests | One-click |
-| Canary (10%) | Yes | SLO compare 15m | Automatic |
-| Production | Yes | Manual approve | **Manual, untested** |
-
-> The "Manual, untested" cell is the single largest finding in this report.
-
-## On-Call Practice
-
-The team runs a weekly rotation. In practice, three engineers cover most of the load:
-
-- Engineer A — 28% of minutes
-- Engineer B — 24%
-- Engineer C — 19%
-- Remaining 8 engineers split the other 29%
-
-The organization's own runbook requires a shadow-rotation before any solo shift. In the last two quarters, zero new engineers completed it.
-
-## Runbook Inventory
-
-Of 14 tier-1 services:
-
-- **Fresh** (reviewed within 6 months): 5
-- **Aging** (6–18 months): 2
-- **Stale** (18+ months): 7
-
-Three of the stale services have been re-architected since their last runbook update.

package/assets/skills/consulting-report/demo/content/executive-summary.md

@@ -1,19 +0,0 @@
-## Context
-
-Acme Industries asked for an independent read on whether their engineering operations are ready to support the 3× revenue growth planned over the next 18 months. The assessment ran for six weeks and covered tier-1 production services, on-call practice, and incident response.
-
-## Key Findings
-
-- Production deploys lack a tested rollback path — the single largest operational risk.
-- Runbooks are stale across half of tier-1 services.
-- On-call coverage is concentrated in three engineers; knowledge has not diffused.
-
-## Primary Recommendations
-
-1. Add a rollback gate to the deploy pipeline within four weeks.
-2. Refresh all tier-1 runbooks in a dedicated Q3 sprint.
-3. Broaden the on-call roster from three to eight engineers over the next six months.
-
-## Scope & Method
-
-In scope: engineering operations — deploy, on-call, incident response, service ownership. Out of scope: product, sales, finance processes, though they surfaced repeatedly. Five semi-structured interviews; 12 incident post-mortems reviewed; 90 days of on-call coverage logs analyzed.

package/assets/skills/consulting-report/demo/content/report-data.ts

@@ -1,101 +0,0 @@
-import type { ConsultingReport } from "../../tools/generate-pdf";
-
-const report: ConsultingReport = {
-  clientName: "Acme Industries",
-  reportTitle: "Operational Readiness Assessment",
-  reportDate: "2026-04-21",
-  classification: "CONFIDENTIAL",
-  version: "1.0",
-
-  // No brand block — uses the Konvert7 default.
-
-  sections: [
-    {
-      id: "executive-summary",
-      title: "Executive Summary",
-      content: "executive-summary.md",
-    },
-    {
-      id: "current-state",
-      title: "Current State",
-      content: "current-state.md",
-    },
-  ],
-
-  findings: [
-    {
-      id: "f-01",
-      title: "Release pipeline lacks a rollback path",
-      severity: "critical",
-      evidence:
-        "Production deploys are one-way: the pipeline lacks a tested rollback step. Of the last 12 incidents, 4 required manual database surgery because the deploy couldn't be reverted.",
-      impact:
-        "Mean time to recovery is 3× peer benchmarks, and engineers report avoiding late-week deploys — slowing feature delivery.",
-    },
-    {
-      id: "f-02",
-      title: "Runbooks are out of date across half the critical services",
-      severity: "high",
-      evidence:
-        "7 of 14 tier-1 services have runbooks last updated more than 18 months ago. Three of those services have been re-architected since.",
-    },
-    {
-      id: "f-03",
-      title: "On-call rotation is concentrated in three engineers",
-      severity: "medium",
-      evidence:
-        "Over the last quarter, three engineers covered 71% of the on-call minutes. The shadow-rotation system exists on paper but isn't enforced.",
-    },
-  ],
-
-  recommendations: [
-    {
-      id: "r-01",
-      title: "Add a tested rollback gate to the deploy pipeline",
-      priority: "immediate",
-      detail:
-        "Before any production deploy, require a successful rollback dry-run in staging. Block the pipeline on red. Target: implemented within 4 weeks; validated monthly via chaos day.",
-      owner: "Platform team",
-    },
-    {
-      id: "r-02",
-      title: "Runbook refresh sprint",
-      priority: "short-term",
-      detail:
-        "Allocate one sprint in Q3 to refresh all tier-1 runbooks. Each owner writes a 10-minute 'what wakes me up at 3am' paragraph. Review as pair exercise with oncall.",
-      owner: "Service owners + SRE",
-    },
-    {
-      id: "r-03",
-      title: "Broaden on-call to 8 engineers within 6 months",
-      priority: "long-term",
-      detail:
-        "Rotate 2 new engineers through a 4-week shadow period each quarter. Gate solo rotation on a resolved-incident checklist, not tenure.",
-    },
-  ],
-
-  conclusion: {
-    assessorNote:
-      "The team is competent and well-intentioned; the gaps are process, not ability. The critical finding around rollback is the single highest-leverage fix available.",
-    contextNote:
-      "This assessment was scoped to engineering operations. Product, sales, and finance processes were out of scope but came up repeatedly in interviews as related bottlenecks.",
-    closingRemarks:
-      "A 30-day follow-up is recommended after the rollback gate lands to verify MTTR trend.",
-  },
-
-  supportingEvidence: {
-    Interviews: [
-      "Head of Platform — 45m",
-      "SRE Lead — 45m",
-      "Three senior engineers — 30m each",
-      "VP Engineering — 30m",
-    ],
-    "Documents reviewed": [
-      "Q1 incident post-mortems (12)",
-      "On-call schedule & coverage logs (90 days)",
-      "Current runbook index",
-    ],
-  },
-};
-
-export default report;

package/assets/skills/consulting-report/template/README.md

@@ -1,28 +0,0 @@
-# Consulting Report — Working Directory
-
-## Structure
-
-- `content/report-data.ts` — report structure (cover metadata, sections, optional findings / recommendations / conclusion / appendix)
-- `content/*.md` — narrative sections; reference them from `report-data.ts` by filename
-- `diagrams/` — drop PNG/JPG images; they're compressed to JPEG 70% / max 1200px at render time
-- `diagrams-compressed/` — generated; do not edit
-
-## Render
-
-```
-node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts .
-```
-
-Output goes into this directory as `<client>-<title>-<date>.{pdf,html}` unless you pass `--pdf <path>` or `--html <path>`.
-
-## Defaults
-
-Without a `brand` block in `report-data.ts`, reports are stamped with **Konvert7** branding. Override per engagement by adding:
-
-```ts
-brand: {
-  businessName: "Your Brand",
-  logoPath: "/absolute/path/to/logo.png",   // optional — text-only cover if omitted
-  brandLabel: "Strategic Assessment",        // optional sub-label on cover
-}
-```

package/assets/skills/consulting-report/template/content/executive-summary.md

@@ -1,19 +0,0 @@
-## Context
-
-One-paragraph framing of the engagement: who the client is, what they asked for, what's at stake.
-
-## Key Findings
-
-- Finding one — punchy, evidenced, and actionable.
-- Finding two.
-- Finding three.
-
-## Primary Recommendations
-
-1. Recommendation one — what to do, by when, and what it unblocks.
-2. Recommendation two.
-3. Recommendation three.
-
-## Scope & Method
-
-Short note on what was reviewed, who was interviewed, what was explicitly out of scope.

package/assets/skills/consulting-report/template/content/report-data.ts

@@ -1,59 +0,0 @@
-import type { ConsultingReport } from "{{TOOL_PATH}}";
-
-const report: ConsultingReport = {
-  clientName: "{{CLIENT_NAME}}",
-  reportTitle: "{{REPORT_TITLE}}",
-  reportDate: "{{DATE}}",
-  classification: "CONFIDENTIAL",
-  version: "0.1",
-
-  // Brand is optional — defaults to Konvert7. Override per report if needed:
-  // brand: { businessName: "Konvert7", logoPath: "/absolute/path/to/logo.png", brandLabel: "Strategic Assessment" },
-
-  sections: [
-    {
-      id: "executive-summary",
-      title: "Executive Summary",
-      content: "executive-summary.md",
-    },
-    // Add sections — each `content` is either an inline markdown string OR a
-    // .md filename relative to this content/ directory.
-  ],
-
-  // Optional. Delete the block if unused.
-  findings: [
-    // {
-    //   id: "f-01",
-    //   title: "Example critical finding",
-    //   severity: "critical",
-    //   evidence: "What was observed, with specifics.",
-    //   impact: "Why it matters.",
-    // },
-  ],
-
-  // Optional.
-  recommendations: [
-    // {
-    //   id: "r-01",
-    //   title: "Example recommendation",
-    //   priority: "immediate",
-    //   detail: "What to do, by when, and why.",
-    //   owner: "Team or person",
-    // },
-  ],
-
-  // Optional.
-  conclusion: {
-    // assessorNote: "Personal assessor voice.",
-    // contextNote: "Situational context the reader needs.",
-    // closingRemarks: "Where to go next.",
-  },
-
-  // Optional. Appendix — keyed by heading, each value is a list of bullets.
-  // supportingEvidence: {
-  //   "Interviews": ["Person A — 45m", "Person B — 30m"],
-  //   "Documents reviewed": ["doc-1.pdf", "doc-2.md"],
-  // },
-};
-
-export default report;