portable-agent-layer 0.26.1 → 0.27.1

package/assets/skills/consulting-report/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: consulting-report
+description: Produce branded consulting-report PDFs from a structured report directory (cover page, linked TOC, headers/footers with page numbers, typography system, callout boxes, findings + recommendations). Use when generating an assessment report, strategic review, or consulting deliverable PDF.
+argument-hint: <report-dir> OR `scaffold <target-dir>` to start a new report
+---
+
+## Overview
+
+Renders a structured consulting-report directory to a branded PDF: cover page, linked table of contents, page-numbered headers/footers, typography system (Georgia body + Inter headings), colored callout boxes for findings and recommendations, tables with zebra striping.
+
+Each report lives in its own directory with data (TypeScript) + narrative (Markdown) + diagrams (images). The skill provides a scaffolder to spin up new reports from a template and a generator to render them.
+
+**Default brand:** Konvert7. Override per report via the `brand` block in `report-data.ts`.
+
+## Report Directory Layout
+
+```
+<report-dir>/
+├── content/
+│   ├── report-data.ts          # report structure (schema: ConsultingReport)
+│   ├── executive-summary.md    # narrative sections
+│   └── …
+├── diagrams/                   # source images (PNG/JPG)
+├── diagrams-compressed/        # generated — ignore
+└── <client>-<title>-<date>.{pdf,html}  # output
+```
+
+## Workflow
+
+### Step 1: Scaffold a new report (skip if the report directory already exists)
+
+```bash
+bun ~/.pal/skills/consulting-report/tools/scaffold.ts <target-dir> \
+  --client "Client Name" \
+  --title "Report Title"
+```
+
+Creates the directory, stamps today's date + client + title into `report-data.ts`, and writes a starter `executive-summary.md`. If the target directory already exists, the command errors — move or remove first.
+
+### Step 2: Fill in content
+
+Edit:
+
+- `<dir>/content/report-data.ts` — cover metadata, sections list, optional findings / recommendations / conclusion / appendix. Each `section.content` is either an inline markdown string OR a `.md` filename relative to `content/`.
+- `<dir>/content/*.md` — the narrative sections referenced from `report-data.ts`.
+- `<dir>/diagrams/` — drop PNG/JPG images. Reference them from markdown with relative paths, e.g. `![alt](../diagrams-compressed/architecture.jpg)`.
+
+### Step 3: Render
+
+```bash
+bun ~/.pal/skills/consulting-report/tools/generate-pdf.ts <report-dir>
+```
+
+Output: `<dir>/<client-slug>-<title-slug>-<date>.pdf` and matching `.html`. Override with `--pdf <path>` / `--html <path>`.
+
+The generator:
+- Loads `content/report-data.ts` dynamically
+- Compresses `diagrams/*` to JPEG 70% / 1200px via `sips` (macOS); silently skips if `sips` is absent
+- Renders cover, auto-generated linked TOC, sections, findings, recommendations, conclusion, appendix
+- Prints via Playwright with page-numbered header/footer templates
+
+### Step 4: Verify
+
+```bash
+ls -lh <dir>/*.pdf
+```
+
+Open the PDF. Check: cover centered and branded; TOC links jump; findings render in red/amber boxes by severity; recommendations in blue boxes with priority badges; every page has the CONFIDENTIAL footer and page number.
+
+## Report Schema
+
+```ts
+interface ConsultingReport {
+  clientName: string;
+  reportTitle: string;
+  reportDate: string;
+  classification: string;          // e.g., "CONFIDENTIAL"
+  version: string;
+  brand?: { businessName: string; brandLabel?: string; logoPath?: string; };
+  sections: Section[];
+  findings?: Finding[];            // renders as red/amber/blue boxes by severity
+  recommendations?: Recommendation[];  // blue boxes with priority badges
+  conclusion?: Conclusion;
+  supportingEvidence?: Record<string, string[]>;  // appendix
+}
+
+interface Section { id: string; title: string; content: string; subsections?: Section[]; }
+interface Finding { id: string; title: string; severity: "critical"|"high"|"medium"|"low"; evidence: string; impact?: string; }
+interface Recommendation { id: string; title: string; priority: "immediate"|"short-term"|"long-term"; detail: string; owner?: string; }
+interface Conclusion { assessorNote?: string; contextNote?: string; closingRemarks?: string; }
+```
+
+## Styling
+
+The typography system (Georgia body 10.5pt / Inter headings), color palette (navy #1B2A4A, blue #2E5090, red #DC2626, amber #D97706, green #059669), callout boxes, badges, table styling, cover layout, and header/footer templates are baked into `tools/generate-pdf.ts`. To customize: edit the `css()` function and the `renderPdf()` header/footer strings in one place.
+
+Do NOT combine CSS `@page` margin-box rules with the Playwright `displayHeaderFooter` templates — they duplicate.
+
+## Demo
+
+A runnable demo lives at `~/.pal/skills/consulting-report/demo/`:
+
+```bash
+bun ~/.pal/skills/consulting-report/tools/generate-pdf.ts ~/.pal/skills/consulting-report/demo
+```
+
+Inspect the produced PDF to see the full layout (cover, TOC, sections, findings, recommendations, conclusion, appendix) before writing your own report.
+
+## Important
+
+- Reports live wherever you want; the skill only needs the `<report-dir>` path
+- The scaffolder refuses to overwrite an existing directory
+- Images go in `diagrams/`; reference them from markdown via `diagrams-compressed/<name>.jpg` so the compressed output is used
+- Heading anchor IDs come from `section.id` — keep them unique and slug-safe
+- Every report re-renders deterministically from source; the PDF and HTML are disposable artifacts

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

@@ -0,0 +1,33 @@
+## 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

@@ -0,0 +1,19 @@
+## 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

@@ -0,0 +1,101 @@
+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

@@ -0,0 +1,28 @@
+# 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
+
+```
+bun ~/.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

@@ -0,0 +1,19 @@
+## 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

@@ -0,0 +1,59 @@
+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;