johns-harness 2026.9.24 → 2026.9.26

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 2026.9.26
+
+- Family 73: the `content-story`, `dashboard` and `cold-outreach` skills are removed from the bundled set on request, leaving eight generic bundled skills (`code-ops`, `web-research`, `plan-archival`, `todos`, `arch-viz`, `gcp-logs`, `activity-logging`, `outlook`). They load by description match exactly as before, workspace copies override them, and `enabled: false` and `allowBundled` still apply. Nothing else changes from 2026.9.25.
+- Roll back with `npm i -g johns-harness@2026.9.25`.
+
+## 2026.9.25
+
+- Family 72: eleven generic skills from the author's workspace ship as bundled skills (`code-ops`, `web-research`, `plan-archival`, `todos`, `dashboard`, `arch-viz`, `content-story`, `cold-outreach`, `gcp-logs`, `activity-logging`, `outlook`), converted to fully generic wording first: no owner names, paths, repos, accounts, or products. They load by description match like every other bundled skill (none is always-on), workspace copies override them, and `enabled: false` and `allowBundled` still apply. `RULES.md` lists all of them.
+- The Family 71 packed-artifact gate now also proves all eleven bundled generic skills are inside every tarball, and verifier checks 72.1 through 72.5 enforce presence, frontmatter, the generic wording contract, and no em dashes.
+- Roll back with `npm i -g johns-harness@2026.9.24`.
+
 ## 2026.9.24
 
 - Family 71: native-first Jiti plugin loading (Family 68) is now standard on `latest`. The `extended` dist-tag moves to this same version, so both lines converge at 2026.9.24. Node loads already-built JavaScript plugin code natively first and keeps Babel only for TypeScript plugin entries; `JITI_TRY_NATIVE` is no longer needed and is harmless if set.

package/README.md

@@ -85,8 +85,8 @@ node johnness.mjs --help
 ### Verify
 
 ```bash
-npm test                        # 909 tests against the installed dependency tree
-bash scripts/verify-patches.sh  # 443 checks across every patch family
+npm test                        # 914 tests against the installed dependency tree
+bash scripts/verify-patches.sh  # 455 checks across every patch family
 ```
 
 ## Launch a swarm with one command
@@ -132,7 +132,7 @@ Coding agents today run as isolated processes. Two agents on the same repository
 - **Memory built for production.** Tiered recall that traces from consolidated reflections down to the verbatim record, surviving compaction and shared across the swarm. Installed and enabled by default.
 - **Production authority per commit.** Promotion is granted to an exact SHA, never to a branch name, so one worker's authorization never covers another worker's commits.
 - **An append-only action log.** Agents record every consequential action to `ACTION_LOG.md` and read it before acting.
-- **A fixed runtime surface.** The core does not grow on a schedule. New mechanisms enter only to solve a demonstrated production failure, one narrow, tested, reversible patch at a time: 71 patch families, each with a regression test and a rollback path.
+- **A fixed runtime surface.** The core does not grow on a schedule. New mechanisms enter only to solve a demonstrated production failure, one narrow, tested, reversible patch at a time: 73 patch families, each with a regression test and a rollback path.
 - **Reliability with a definition.** Bounded retries, explicit failure states, exact-once continuation, context-pressure recovery, durable delivery, and supervised gateway recovery.
 - **Coding first, phone optional.** Direct the work at a high level from a chat channel while agents plan, implement, test, coordinate, and stage releases unattended.
 - **Local voice.** Optional native Whisper transcription of inbound audio, entirely on your machine. Off by default. [Setup](docs/NATIVE-WHISPER-MUSE.md).
@@ -199,7 +199,7 @@ The log is a [`RULES.md`](RULES.md) workspace convention enforced through the ac
 
 ## Patch families
 
-The runtime carries 71 patch families plus the 65.1 safe-update amendment. Each is a production fix applied at the source with a regression test, a durable patch marker, and a rollback path. A verifier runs 443 checks against the package tree and installed dependencies, and 909 tests run against the installed dependency tree.
+The runtime carries 73 patch families plus the 65.1 safe-update amendment. Each is a production fix applied at the source with a regression test, a durable patch marker, and a rollback path. A verifier runs 455 checks against the package tree and installed dependencies, and 914 tests run against the installed dependency tree.
 
 Every family follows the same six steps: reproduce the failure, trace the exact runtime path, make the smallest source-level change that restores the invariant, add a regression test and a patch marker, run the verifier, and retain rollback artifacts. The full index: [`docs/PATCHES.md`](docs/PATCHES.md).
 
@@ -213,11 +213,12 @@ Every family follows the same six steps: reproduce the failure, trace the exact
 | `--dev` | Dev profile under `~/.johnness-dev` with its own gateway port and shifted derived ports |
 | Rules | [`RULES.md`](RULES.md) ships 19 operating-policy sections injected on every call. Fill in the placeholders; keep long procedures in skills. |
 | Orchestrator skill | Bundled and loaded implicitly on every install. Decide whether to pass the user's words through or expand them, then keep the briefing brief. Override with a workspace `skills/orchestrator/SKILL.md`. |
+| Bundled generic skills | Eight generic skills ship in `skills/` and load by description match: `code-ops`, `web-research`, `plan-archival`, `todos`, `arch-viz`, `gcp-logs`, `activity-logging`, `outlook`. Workspace copies override; `enabled: false` and `allowBundled` still apply. |
 
 ## Documentation
 
 - [`docs/index.md`](docs/index.md): runtime docs, from gateway and channels to plugins, nodes, and CLI reference.
-- [`docs/PATCHES.md`](docs/PATCHES.md): the 71 patch families, one record each.
+- [`docs/PATCHES.md`](docs/PATCHES.md): the 73 patch families, one record each.
 - [`docs/NATIVE-WHISPER-MUSE.md`](docs/NATIVE-WHISPER-MUSE.md): local Whisper transcription setup.
 - [`RULES.md`](RULES.md): the default operating rules, including Rule Zero on production authorization.
 

package/docs/PATCHES.md

@@ -17,7 +17,7 @@ they predate ~2026-06-06).
 
 ## Index
 
-Family 01 is retired. Families 02 through 41, 43 through 67, 69 and 70, including the 65.1 amendment, are live on `main`; Family 68 ships on the `extended` release line. Family 42 is omitted; native Codex OAuth ownership is Family 58.
+Family 01 is retired. Families 02 through 41, 43 through 72, including the 65.1 amendment, are live on `main`; the `latest` and `extended` release lines converged at 2026.9.24. Family 42 is omitted; native Codex OAuth ownership is Family 58.
 
 1. **01, announce queue TTL, retired:** Removed the five-minute age filter that could discard delayed sub-agent completion announcements. [Details](#01--announce-ttl-retired-2026-07-30)
 2. **02, failover rotation:** Returns model selection to the highest-priority profile after its cooldown ends. [Details](#02--failover-rotation-undocumented)
@@ -95,6 +95,11 @@ Family 01 is retired. Families 02 through 41, 43 through 67, 69 and 70, includin
 
 70. **70, bundled orchestrator skill:** The delegation and briefing protocol ships as an always-eligible bundled skill; every install loads it implicitly and a workspace copy still overrides it. [Details](#family-70-bundled-orchestrator-skill)
 
+71. **71, native-first Jiti standard on latest:** The Family 68 native-first loader option ships on every artifact, the `latest` and `extended` lines converge, and a packed-artifact gate proves the tarball carries it. [Details](#family-71-native-first-jiti-standard-on-latest)
+
+72. **72, bundled generic skills:** Eight workspace skills (code operations, research, todos, planning, logs, and more) ship as generic bundled skills that load by description match, with no owner names or personal paths. [Details](#family-72-bundled-generic-skills)
+73. **73, prune bundled skills:** `content-story`, `dashboard` and `cold-outreach` are removed from the Family 72 bundled set on request after `2026.9.25`; the remaining eight ship unchanged. [Details](#family-73-prune-bundled-skills)
+
 ---
 
 ## 01 - announce-ttl (RETIRED 2026-07-30)
@@ -2618,3 +2623,49 @@ Family 67 hash checks continue to compare the Family-67 surface with the Family
 **Tests:** `tests/native-jiti-standard.test.mjs` proves the gate passes a complete tarball, fails a tarball packed without Family 68 (the 2026.9.22 and 2026.9.23 shape), fails when one copy lacks the option or is absent, fails on a version mismatch, exits non-zero from the CLI, and that the real `npm pack` output of this tree carries the marker in all ten copies. Verifier checks 71.1 through 71.3 cover the shipped gate, the packed or installed artifact, and the absence of a separate extended pin in `package.json`.
 
 Roll back with `npm i -g johns-harness@2026.9.23` (no native-first Jiti) or `npm i -g johns-harness@2026.9.21-extended.1` (Family 68 without Families 69 and 70).
+
+## Family 72: bundled generic skills
+
+**Release:** `johns-harness@2026.9.25`. Published as `latest` and the `extended` dist-tag moves to it (the two lines converged at 2026.9.24).
+
+Eight skills from the author's personal workspace ship as bundled skills in `skills/<name>/SKILL.md`, made fully generic first: no owner names, no personal paths, repos, accounts, or products. Every one loads by description match like the other bundled skills (none is `always`-on, unlike the Family 70 orchestrator), a workspace or managed copy overrides it, `skills.entries.<name>.enabled: false` turns it off, and an `allowBundled` allowlist that omits it is respected. (Superseded by Family 73: from `2026.9.26` `dashboard`, `content-story` and `cold-outreach` are removed from the bundle.)
+
+Shipped skills: `code-ops` (learnings protocol, config tracing, publishing safety), `web-research` (never give up deep research method), `plan-archival` (move finished plans to plans/archive and memory/completed-plans), `todos` (workspace memory/todos protocol), `arch-viz` (sub-agent generated architecture visualization), `gcp-logs` (Cloud Run log debugging via gcloud, placeholder service names), `activity-logging` (log outcomes, not tasks, plus the ACTION_LOG), `outlook` (outlook tool quick reference).
+
+Decision table:
+
+| Skill | Decision | Reason |
+|---|---|---|
+| code-ops | ship, converted | generic protocol, anecdote generalized |
+| web-research | ship, converted | generic method, em dashes stripped |
+| plan-archival | ship, converted | personal paths replaced with workspace-relative |
+| todos | ship, converted | owner name and paths replaced |
+| dashboard | dropped | removed on request after 2026.9.25 |
+| arch-viz | ship, converted | personal paths and projects scrubbed |
+| content-story | dropped | removed on request after 2026.9.25 |
+| cold-outreach | dropped | removed on request after 2026.9.25 |
+| gcp-logs | ship, converted | baked-in service names replaced with placeholders |
+| activity-logging | ship, converted | log names and paths made workspace-relative |
+| outlook | ship, converted | account domain scrubbed |
+| hq-ops | drop | personal repo and GitHub links |
+| brain-backup | drop | personal restic bucket and paths |
+| provider-stats | drop | personal auth profiles |
+| anthropic-sub-proxy | drop | specific deployed proxy setup |
+| reddit-posting | drop | product marketing workflow |
+| comms-identity, email-format, dri-reimbursement, johns-amex-login, insyte, willow, x-original-post, memoryrouter-listings, memoryrouter-seo | drop | owner-only skills |
+| hyperframes, hyperframes-cli, hyperframes-media, website-to-hyperframes, impeccable | exclude | third-party vendored skills |
+| orchestrator | already shipped | Family 70 |
+
+Verifier checks 72.1 through 72.5 cover presence with frontmatter, the generic wording contract (no owner, product or personal names and no `always` flag), no em dashes, the RULES.md skill table, and the packed artifact (the Family 71 gate now also proves all eight skills are inside the tarball). `tests/bundled-skills.test.mjs` proves every skills chunk loads all eight from an empty workspace, a workspace copy overrides, `enabled: false` disables, and the `allowBundled` allowlist still wins. `RULES.md` section 5 lists every bundled skill.
+
+Roll back with `npm i -g johns-harness@2026.9.24`.
+
+## Family 73: prune bundled skills
+
+**Release:** `johns-harness@2026.9.26`. Published as `latest` and the `extended` dist-tag moves to it.
+
+Three of the Family 72 bundled skills are removed from the bundled set on request after `2026.9.25`: `content-story`, `dashboard` and `cold-outreach`. The remaining eight (`activity-logging`, `arch-viz`, `code-ops`, `gcp-logs`, `outlook`, `plan-archival`, `todos`, `web-research`) are unchanged, and a workspace or managed copy of a removed skill still overrides and loads as it always did. Nothing else differs from `2026.9.25`.
+
+The counters move with the set: the verifier emits one check per remaining skill through the same 72.1 loop (455 checks in total), `tests/bundled-skills.test.mjs` asserts exactly eight bundled skills, `scripts/check-packed-artifact.mjs` fails closed unless a tarball carries all eight with frontmatter, and `README.md` and the pinned copy in `patches/59-migrate-cli.patch` carry the new counts together so check 59c stays green. `RULES.md` section 5 drops the three rows.
+
+Roll back with `npm i -g johns-harness@2026.9.25`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "johns-harness",
-  "version": "2026.9.24",
+  "version": "2026.9.26",
   "description": "John's Harness: a production agent harness that runs autonomous coding agents as one cooperative swarm.",
   "keywords": [
     "ai-agents",

package/scripts/check-packed-artifact.mjs

@@ -10,6 +10,10 @@
 // carries exactly one Family 68 marker and exactly one `tryNative: true`, the tarball version
 // matches the tree version, and no copy is missing.
 //
+// Family 72: the bundled generic skills are also part of the artifact contract. Every one of
+// the Family 72 skills must be present in the tarball with a `name` and a `description` in its
+// frontmatter. The same inspection runs on installed trees.
+//
 // Usage:
 //   node scripts/check-packed-artifact.mjs [package root]        pack the tree, then inspect
 //   node scripts/check-packed-artifact.mjs --tarball <file.tgz>  inspect a tarball (for example
@@ -40,6 +44,33 @@ export const LOADERS10 = [
 
 const count = (text, needle) => text.split(needle).length - 1;
 
+// Family 72: the generic skills shipped as bundled skills. Each must be inside the artifact
+// with valid frontmatter (a `name:` and a `description:` line).
+export const F72_SKILLS = [
+  "activity-logging",
+  "arch-viz",
+  "code-ops",
+  "gcp-logs",
+  "outlook",
+  "plan-archival",
+  "todos",
+  "web-research",
+];
+
+/** Family 72: verify every bundled generic skill is present with frontmatter. Returns the count. */
+export function inspectSkills72(pkgDir) {
+  const problems = [];
+  for (const name of F72_SKILLS) {
+    const file = path.join(pkgDir, "skills", name, "SKILL.md");
+    if (!fs.existsSync(file)) { problems.push(`${name}: skills/${name}/SKILL.md missing from artifact`); continue; }
+    const text = fs.readFileSync(file, "utf8");
+    if (!/^name: [a-z0-9-]+$/m.test(text)) problems.push(`${name}: frontmatter has no name line`);
+    if (!/^description: .+$/m.test(text)) problems.push(`${name}: frontmatter has no description line`);
+  }
+  if (problems.length) throw new Error(`Family 72: packed artifact is missing bundled generic skills:\n  ${problems.join("\n  ")}`);
+  return F72_SKILLS.length;
+}
+
 /** Inspect an extracted package directory (the `package/` folder of a tarball). Throws on any gap. */
 export function inspectExtracted71(pkgDir, { expectVersion } = {}) {
   const manifestPath = path.join(pkgDir, "package.json");
@@ -62,7 +93,8 @@ export function inspectExtracted71(pkgDir, { expectVersion } = {}) {
     if (m === 1 && o === 1) markers += 1;
   }
   if (problems.length) throw new Error(`Family 71: packed artifact lacks native-first Jiti:\n  ${problems.join("\n  ")}`);
-  return { version: manifest.version, loaders: LOADERS10.length, markers };
+  const skills = inspectSkills72(pkgDir);
+  return { version: manifest.version, loaders: LOADERS10.length, markers, skills };
 }
 
 /** Extract a tarball into a temp dir and inspect it. */
@@ -105,7 +137,7 @@ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.me
       const root = path.resolve(positional[0] || path.join(path.dirname(fileURLToPath(import.meta.url)), ".."));
       result = packAndInspect71(root);
     }
-    console.log(`Family 71: ${result.markers}/${result.loaders} loader copies carry native-first Jiti in ${path.basename(result.tarball)} (version ${result.version})`);
+    console.log(`Family 71: ${result.markers}/${result.loaders} loader copies carry native-first Jiti in ${path.basename(result.tarball)} (version ${result.version}); Family 72: ${result.skills} bundled generic skills present`);
   } catch (error) {
     console.error(error.message);
     process.exit(1);

package/skills/activity-logging/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: activity-logging
+description: Activity and action logging to the workspace. Load when logging work outcomes or recording actions to ACTION_LOG.md.
+---
+
+# Activity & Action Logging
+
+## Activity Logging: Log Outcomes, Not Tasks
+
+### What to Log
+- Features built or meaningfully improved
+- Process/rule changes with real impact
+- Decisions that matter
+- Problems encountered and how they were resolved (if interesting)
+
+### What NOT to Log
+- Fixing your own mistakes (type errors, build failures, typos)
+- Minor tweaks or implementation details
+- Each tiny step of a larger task: consolidate into one entry
+- Routine maintenance
+
+### How to Decide
+Ask: *"Would the user care about this in a weekly review?"*
+- If it's an **outcome** that delivered value, log it
+- If it's **busywork** or cleanup, skip it
+- If multiple items are related, **consolidate** into one entry
+
+### Format
+- **Bold the specific outcome**: then explain what/how/why
+- Entry should make sense in 3 months without extra context
+- Ask: *"What can the user or I do now that we couldn't before?"*
+- Bad: "Improved chart system"
+- Good: "Pie charts now show percentages on slices: added data labels, mobile scroll, theme colors"
+
+### Process
+1. Update today's log: `memory/logs/YYYY-MM-DD.md`
+2. Mirror on the dashboard if one exists
+3. Push to git:
+```bash
+cd <workspace>
+git add -A && git commit -m "Update log" && git push
+```
+
+---
+
+## Action Log (Real-Time Action Tracking)
+
+**Log every action as it happens.**
+
+### Location
+`ACTION_LOG.md` in the workspace root
+
+### What to Log
+Every action you take: simple one-liner titles:
+- Spawned sub-agent for X
+- Generated image for Y
+- Fixed Z in repo
+- Created skill for W
+- Sent message to user about V
+
+### Format
+```markdown
+## YYYY-MM-DD
+
+- Action 1
+- Action 2
+- Action 3
+```
+
+### Rules
+1. **Log immediately**: after completing any action, add a one-liner
+2. **Keep it simple**: title-level, not detailed
+3. **New date section**: start each day with a new `## YYYY-MM-DD` header
+4. **Don't overthink**: if you did something, log it
+
+### Daily Recap (Scheduled Job)
+A daily scheduled job can create `memory/YYYY-MM-DD.md` from:
+1. **Conversation history**: the full journey of what was discussed, decided, built
+2. **Action Log**: the action entries
+
+Format:
+```markdown
+# YYYY-MM-DD: [Creative title capturing the day's vibe]
+
+## The Story
+[2-4 paragraph narrative, journal entry style, captures the day's energy]
+
+## Key Accomplishments
+- Major wins and shipped items
+- Decisions made
+
+## Actions Log
+[Actions from ACTION_LOG.md]
+```
+
+This captures the journey over time: both the story AND the specifics.

package/skills/arch-viz/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: arch-viz
+description: Generate a detailed visual architecture image for any codebase. Spawns a sub-agent that analyzes the code, understands the flow, and creates a cyberpunk-style visualization showing data moving through the system.
+metadata: { "johnness": { "emoji": "🎨" } }
+---
+
+# Architecture Visualizer
+
+Spawns a sub-agent to analyze a codebase and generate a detailed visual architecture image.
+
+## When to Use
+
+- User says "visualize this codebase"
+- User wants an architecture diagram that's creative/visual (not mermaid)
+- User asks for a "picture of how this works"
+- User wants to see "the flow" or "how data moves"
+
+## How It Works
+
+1. You spawn a sub-agent with the task below
+2. Sub-agent analyzes the codebase (entry points, folder structure, docs)
+3. Sub-agent identifies components and data flows
+4. Sub-agent crafts a detailed image prompt
+5. Sub-agent generates the image with an image-generation tool available in the environment
+6. Sub-agent reports back with the image path
+
+## Spawn Template
+
+```
+sessions_spawn(
+  task: "Analyze the codebase and create a detailed visual architecture image.
+
+    Working directory: [PATH]
+
+    Steps:
+    1. Read the codebase - entry points, folder structure, README, any architecture docs
+    2. Identify the core components:
+       - User-facing interfaces (mobile app, web, CLI, API consumers)
+       - Backend services/APIs (frameworks, routes, controllers)
+       - Databases and storage (what data, how structured)
+       - External services (AI providers, payments, auth, third-party APIs)
+       - Key data flows (what goes in, transforms, comes out)
+
+    3. Create a DETAILED image generation prompt following this style:
+       - Isometric 3D, dark background, neon cyberpunk aesthetic
+       - Show data MOVING through the system (binary streams, glowing packets, light pulses)
+       - Each component has INTERNAL DETAIL visible (like a cross-section of a living machine)
+       - Stage the flow left-to-right: Input → Processing → Output
+       - Visual elements to include:
+         * Binary 1s and 0s streaming between components
+         * API calls as light pulses traveling along pathways
+         * Database with visible rows/tables scrolling
+         * Storage with file thumbnails flowing in/out
+         * AI as neural network with synapses firing
+         * Auth as locks/keys/tokens
+         * Payments as cards/coins/tiers
+       - NO TEXT LABELS - everything visually self-explanatory
+       - Color palette: deep purples, electric blues, hot pinks, cyan accents
+       - Style keywords: 'hyper-detailed cyberpunk tech visualization'
+
+    4. Generate the image with an image-generation tool or skill available in your
+       environment, saving it as '[project-name]-architecture.png' at 2K resolution.
+
+    5. Report the image path so it can be sent to the user.
+
+    Be thorough in your analysis. The more you understand the codebase, the better the visualization.",
+  label: "arch-viz-[project-name]",
+  runTimeoutSeconds: 600
+)
+```
+
+## Example Usage
+
+User: "Visualize the <project> codebase"
+
+→ Spawn with the path of the codebase.
+
+User: "Make an architecture image for <project>"
+
+→ Spawn with the path of the codebase.
+
+## Output
+
+The sub-agent will generate an image and report the path. Send it to the user with:
+
+```
+message(action: "send", media: "[image_path]", message: "Here's your architecture visualization")
+```
+
+## Tips
+
+- For larger codebases, the analysis takes longer but produces better results
+- The sub-agent may ask clarifying questions if the codebase structure is unclear
+- Images are saved to the workspace by default

package/skills/code-ops/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: code-ops
+description: "Code operations: learnings protocol, config tracing, publishing safety. Load BEFORE editing the agent runtime or any codebase, starting a coding project, or publishing anything."
+---
+
+# Code Operations: Learnings, Config Tracing, Publishing
+
+## Learnings Protocol: Read First, Write After
+
+**Before starting ANY coding project, read `.learnings/` if it exists. After completing work, write learnings.**
+
+### Before Starting
+1. **Check** if `.learnings/` folder exists in the project root
+2. **If it exists**, read ALL files in `.learnings/` before writing any code
+3. **Internalize** the lessons. They are hard-won insights from past mistakes
+
+### After Completing
+When you discover something important or finish a project:
+1. **Create** `.learnings/` folder if it doesn't exist
+2. **Write** a learnings file: `.learnings/YYYY-MM-DD-brief-topic.md`
+3. **Include:**
+   - What went wrong / what we learned
+   - Root cause
+   - The fix
+   - How to prevent it next time
+
+### Format
+```markdown
+# [Topic]: Learnings from YYYY-MM-DD
+
+## What Happened
+[Brief description of the issue/discovery]
+
+## Root Cause
+[Why it happened]
+
+## The Fix
+[How we solved it]
+
+## Prevention
+[How to avoid this next time]
+```
+
+### Why
+- Don't repeat the same mistakes
+- Institutional memory lives in the codebase
+- Future you (or other agents) will thank you
+- Learnings compound over time
+
+**Read learnings FIRST. Write learnings AFTER. Always.**
+
+---
+
+## Code Edits: Trace the Full Path
+
+**When editing the agent runtime or any codebase, TRIPLE CHECK the config flow before committing.**
+
+### The Rule
+Before ANY code change that touches config, types, or exports:
+1. **Trace the variable**: follow it through EVERY file it touches
+2. **Check validation schemas**: does the schema need updating?
+3. **Check type exports**: are all functions still exported that should be?
+4. **Check config validation**: will the config loader accept this?
+5. **Build and test**: the build must pass
+6. **Test runtime**: start the gateway and verify it doesn't crash
+
+### What This Prevents
+- Orphaned exports (function removed but re-export left behind)
+- Missing schema fields (config exists but validation rejects it)
+- Type mismatches (compiles but runtime fails)
+- Partial implementations (added feature but forgot plumbing)
+
+### The Checklist (Run Before Every Commit)
+```
+□ Traced all new/changed variables through full code path
+□ Updated schema if adding config fields
+□ Removed orphaned exports if deleting functions
+□ Build passes
+□ Gateway starts without crash
+□ Feature actually works (manual test)
+```
+
+### Why This Matters
+One real incident: a search integration was added without updating the validation schema, and an orphaned export was left behind. Result: the gateway crashed and the agent had to be revived. This is unacceptable. Code changes to your own infrastructure require extra care.
+
+### Anti-Patterns (NEVER do these)
+❌ Add config field but forget the schema
+❌ Remove function but leave the export
+❌ Commit without building
+❌ Trust that "it should work" without testing
+❌ Rush the commit to ship faster
+
+**Every code edit: trace, validate, build, test. No shortcuts.**
+
+---
+
+## Publishing Rules
+
+**Before publishing ANYTHING, verify secrets are excluded.**
+
+### The Rule
+Before publishing to any registry, repo, or public location:
+1. **Check ignore files**: confirm `.env`, secrets, and dev files are excluded
+2. **Preview what's included**: dry-run or list files before publishing
+3. **Look for red flags**: `.env`, config files with keys, anything sensitive
+
+### Pre-Publish Checklist
+```
+□ Ignore files properly configured (.gitignore, .npmignore, .dockerignore, etc.)
+□ Previewed/verified file list before publishing
+□ No secrets in any included files
+□ Version bumped appropriately
+```
+
+### If Secrets Are Published
+1. **Immediately** publish a clean version
+2. **Deprecate/remove** the compromised version
+3. **Rotate** any exposed credentials
+4. **Notify** affected parties if applicable
+
+**Every publish: verify what's included. No exceptions.**

package/skills/gcp-logs/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: gcp-logs
+description: Check Google Cloud Run logs for errors, debug issues, and monitor services. Use when debugging Cloud Run deployments, checking for errors, or investigating issues.
+metadata: { "johnness": { "emoji": "📋", "requires": { "bins": ["gcloud"] } } }
+---
+
+# GCP Cloud Run Logs
+
+Check Cloud Run service logs to debug issues, find errors, and monitor services.
+
+## Service Names
+
+Run `gcloud run services list` to see the user's service names, then substitute `SERVICE_NAME` in the commands below.
+
+## Quick Commands
+
+### Check Recent Errors (any service)
+```bash
+gcloud logging read "resource.type=cloud_run_revision AND severity>=ERROR" --limit=10 --format="table(timestamp,resource.labels.service_name,textPayload)"
+```
+
+### Check Specific Service Errors
+```bash
+gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE_NAME AND severity>=ERROR" --limit=10 --format="value(textPayload)"
+```
+
+### Check Errors in Last N Minutes
+```bash
+gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE_NAME AND severity>=ERROR AND timestamp>=\"$(date -u -v-10M '+%Y-%m-%dT%H:%M:%SZ')\"" --limit=20 --format="value(textPayload)"
+```
+
+### All Logs for a Service (recent)
+```bash
+gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE_NAME" --limit=50 --format="table(timestamp,severity,textPayload)"
+```
+
+## Common Patterns
+
+### Startup Failures
+```bash
+gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE_NAME AND textPayload:\"STARTUP\"" --limit=5
+```
+
+### Database Connection Issues
+```bash
+gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE_NAME AND (textPayload:\"sqlalchemy\" OR textPayload:\"database\" OR textPayload:\"connection\")" --limit=10
+```
+
+### Python Tracebacks
+```bash
+gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE_NAME AND textPayload:\"Traceback\"" --limit=5 --format="value(textPayload)"
+```
+
+## Output Formats
+
+- `--format="table(timestamp,severity,textPayload)"`: clean table
+- `--format="value(textPayload)"`: raw text only
+- `--format="json"`: full JSON (verbose)
+
+## Examples
+
+### Check if staging is erroring
+```bash
+gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE_NAME-staging AND severity>=ERROR" --limit=5 --format="value(textPayload)"
+```
+
+### Check prod for last hour errors
+```bash
+gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE_NAME AND severity>=ERROR AND timestamp>=\"$(date -u -v-1H '+%Y-%m-%dT%H:%M:%SZ')\"" --limit=20
+```
+
+### Get health check status
+```bash
+curl -s https://SERVICE_NAME-PROJECT_NUMBER.REGION.run.app/health
+curl -s https://SERVICE_NAME-staging-PROJECT_NUMBER.REGION.run.app/health
+```
+
+## Service URLs
+
+- **Production:** `https://SERVICE_NAME-PROJECT_NUMBER.REGION.run.app`
+- **Staging:** `https://SERVICE_NAME-staging-PROJECT_NUMBER.REGION.run.app`
+
+(Find the region and project number with `gcloud run services list` or `gcloud projects describe PROJECT_ID`.)

package/skills/outlook/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: outlook
+description: Use the outlook tool to read, send, reply to, forward, and organize Microsoft 365 email, including inbox rules and folders. Load when the user asks to handle Outlook or Microsoft 365 email.
+---
+
+# Outlook Tool Skill
+
+Use the `outlook` tool to interact with Microsoft 365 email for the user's account.
+
+## Email Operations
+
+### Search Emails
+```
+outlook(action="search", query="is:unread", max=10)
+outlook(action="search", query="from:someone@example.com", max=20)
+```
+
+### Read Specific Email
+```
+outlook(action="read", messageId="<MESSAGE_ID>")
+```
+
+### Send New Email
+```
+outlook(
+  action="send",
+  to="recipient@example.com",
+  subject="Subject here",
+  body="Email body here"
+)
+```
+
+With CC/BCC:
+```
+outlook(
+  action="send",
+  to="to@example.com",
+  cc="cc@example.com",
+  bcc="bcc@example.com",
+  subject="Subject here",
+  body="Body here"
+)
+```
+
+For HTML body:
+```
+outlook(
+  action="send",
+  to="recipient@example.com",
+  subject="Subject",
+  bodyHtml="<p>Formatted content</p>"
+)
+```
+
+### Reply to Email
+```
+outlook(
+  action="reply",
+  messageId="<ORIGINAL_MSG_ID>",
+  body="Your reply text here"
+)
+```
+
+### Reply All
+```
+outlook(
+  action="reply_all",
+  messageId="<ORIGINAL_MSG_ID>",
+  body="Reply all text here"
+)
+```
+
+### Forward Email
+```
+outlook(
+  action="forward",
+  messageId="<ORIGINAL_MSG_ID>",
+  to="forward-to@example.com",
+  body="Forwarding note"
+)
+```
+
+### Mark Read/Unread
+```
+outlook(action="mark_read", messageId="<MSG_ID>")
+outlook(action="mark_unread", messageId="<MSG_ID>")
+```
+
+### Flag/Unflag
+```
+outlook(action="flag", messageId="<MSG_ID>")
+outlook(action="unflag", messageId="<MSG_ID>")
+```
+
+### Delete/Move
+```
+outlook(action="delete", messageId="<MSG_ID>")
+outlook(action="move", messageId="<MSG_ID>", destinationFolderId="<FOLDER_ID>")
+```
+
+### List Folders
+```
+outlook(action="folders_list")
+```
+
+## Inbox Rules
+
+### Create Rule
+```
+outlook(
+  action="rule_create",
+  ruleName="Auto-archive newsletters",
+  ruleSenderContains=["newsletter@", "updates@"],
+  ruleMarkAsRead=true,
+  ruleMoveToFolder="<ARCHIVE_FOLDER_ID>"
+)
+```
+
+### List/Delete Rules
+```
+outlook(action="rules_list")
+outlook(action="rule_delete", ruleId="<RULE_ID>")
+```
+
+## Quick Reference
+
+| Action | Tool Call |
+|--------|-----------|
+| Search emails | `outlook(action="search", query="...", max=10)` |
+| Read email | `outlook(action="read", messageId="...")` |
+| Send email | `outlook(action="send", to="...", subject="...", body="...")` |
+| Reply | `outlook(action="reply", messageId="...", body="...")` |
+| Reply all | `outlook(action="reply_all", messageId="...", body="...")` |
+| Forward | `outlook(action="forward", messageId="...", to="...", body="...")` |
+| Mark read | `outlook(action="mark_read", messageId="...")` |
+| Flag | `outlook(action="flag", messageId="...")` |
+| Delete | `outlook(action="delete", messageId="...")` |
+| List folders | `outlook(action="folders_list")` |
+| List rules | `outlook(action="rules_list")` |

package/skills/plan-archival/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: plan-archival
+description: Archive completed plans. Load when a plan is finished or a sub-agent completes plan work.
+---
+
+# Plan Archival
+
+## When a Plan is Completed: Archive It
+
+### Workflow
+1. **Execute the plan**: do the work outlined in the plan document
+2. **Move to archive**: `plans/` to `plans/archive/` in the workspace
+3. **Add completion metadata**: date completed, outcome summary at top of file
+4. **Link in logs**: when logging the completion, link to the archived plan
+
+### Plan Location
+`plans/` (in the workspace root)
+
+### Archive Location
+`plans/archive/`
+
+### Completion Metadata (add to top of archived plan)
+```markdown
+> **Status:** ✅ Completed
+> **Completed:** YYYY-MM-DD
+> **Outcome:** [1-2 sentence summary of what was achieved]
+> **Log Entry:** [Link to the log entry that recorded completion]
+
+---
+[Original plan content below]
+```
+
+### Why This Matters
+- Todos and logs stay clean (single title line)
+- Full context preserved for posterity
+- Can dive into any past decision/implementation
+- Creates institutional memory
+
+### Process
+```bash
+cd <workspace>
+mv plans/PLAN_NAME.md plans/archive/PLAN_NAME.md
+# Edit to add completion metadata
+git add -A && git commit -m "Archive completed plan: PLAN_NAME" && git push
+```
+
+---
+
+## Completed Plans to Memory
+
+**When a plan is completed, also move it to `memory/completed-plans/`.**
+
+### When to Move
+- Sub-agent completes work on a plan
+- All phases of a plan are done
+- You review sub-agent work and confirm completion
+
+### Process
+1. **Review** the sub-agent's work on the plan
+2. **Confirm** all objectives are met
+3. **Move** the plan file:
+```bash
+mv memory/plans/PLAN_NAME.md memory/completed-plans/PLAN_NAME.md
+# OR
+mv plans/PLAN_NAME.md memory/completed-plans/PLAN_NAME.md
+```
+4. **Add completion note** at top of file:
+```markdown
+> **Status:** ✅ Completed
+> **Completed:** YYYY-MM-DD
+> **Outcome:** [Brief summary of what was achieved]
+```
+5. **Commit + push**
+
+### Locations
+- **Active plans:** `plans/` or `memory/plans/`
+- **Completed plans:** `memory/completed-plans/`
+
+### Why
+- Keeps active plans clean and focused
+- Preserves history of completed work
+- Easy to find what's been done vs what's pending
+
+**Every time you review a sub-agent's completed work on a plan, move it to completed-plans.**

package/skills/todos/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: todos
+description: Manage the user's todos in memory/todos. Use when the user mentions tasks, todos, things to do, projects, or anything that sounds like "we need to do X". Also use for organizing, updating, or reviewing todos.
+---
+
+# Todo Management Skill
+
+Todos live in `memory/todos/` in the workspace.
+
+## Structure
+
+```
+memory/todos/
+├── README.md          # Main dashboard with TODAY section at top
+├── TODAY.md           # Copy of today's daily todos (refreshed daily)
+├── projects/          # Project folders
+│   ├── project-name/
+│   │   ├── README.md  # Project todos + context (Unassigned → In Progress → Done)
+│   │   ├── DONE.md    # Completed todos for this project
+│   │   └── *.md       # Additional context/reference files
+│   └── ...
+└── archive/           # Stale projects (no activity >30 days)
+```
+
+## Todo Format
+
+Use checkboxes for all todos. Todos can have sub-todos:
+
+```markdown
+- [ ] Main task
+  - [ ] Subtask 1
+  - [ ] Subtask 2
+    - [ ] Sub-subtask
+```
+
+## Project README Structure
+
+Each project folder has a README.md:
+
+```markdown
+# Project Name
+
+**Last Active:** YYYY-MM-DD
+
+## Context
+Brief description of the project.
+
+## Unassigned
+- [ ] Task not yet started
+
+## In Progress
+- [ ] Task being worked on
+
+## Done
+- [x] Completed task (move to DONE.md when section gets long)
+
+## References
+- [Related doc](./related.md)
+```
+
+## Main README (todos/README.md)
+
+```markdown
+# Todos Dashboard
+
+**Last Updated:** YYYY-MM-DD
+
+## 📅 Today
+<!-- Copy from TODAY.md each morning -->
+- [ ] Daily task 1
+- [ ] Daily task 2
+
+## 🔥 Active Projects
+- [Project Name](./projects/project-name/) - brief status
+
+## 📦 Archive
+- [Old Project](./archive/old-project/) - archived YYYY-MM-DD
+```
+
+## Rules
+
+1. **Capture everything**: if the user says "we need to do X" or anything todo-like, add it
+2. **Update dates**: every edit, update "Last Active" or "Last Updated"
+3. **Archive stale projects**: no activity in 30+ days, move to archive/
+4. **Group by project**: new topics become new project folders
+5. **Daily refresh**: a daily scheduled job reviews recent conversations and updates todos
+6. **Push changes**: after updating, commit and push to git:
+   ```bash
+   cd <workspace>
+   git add -A && git commit -m "Update todos" && git push
+   ```
+
+## Workflow
+
+### Adding a todo
+1. Identify the project (create folder if new)
+2. Add to appropriate section (Unassigned/In Progress)
+3. Update "Last Active" date
+4. Push to git
+
+### Completing a todo
+1. Mark with [x]
+2. Move to Done section (or DONE.md if section is long)
+3. Update dates
+4. Push to git
+
+### Archiving a project
+1. Check "Last Active" date
+2. If >30 days with no mentions, move folder to archive/
+3. Update main README.md
+4. Push to git

package/skills/web-research/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: web-research
+description: Deep web research methodology. Use when searching for information, investigating topics, or answering questions that require thorough research. Never give up until the answer is found.
+---
+
+# Web Research Skill
+
+**Objective:** Find the answer. Don't stop until you have it.
+
+---
+
+## The Process
+
+### 1. Initial Search
+```
+web_search(query="<initial query>", count=10)
+```
+- Start broad but relevant
+- Look at the results: identify which URLs look most promising
+- Note: titles and descriptions give clues about content quality
+
+### 2. Investigate Promising Links
+```
+web_fetch(url="<promising url>")
+```
+For each promising result:
+- Fetch the page content
+- Scan for the information you need
+- Note any specific terminology, names, or concepts discovered
+
+### 3. Refine & Go Deeper
+
+**If the page answers the question:**
+- Extract the answer
+- Verify with a second source if important
+- Report back
+
+**If the page gives you better search terms:**
+- Search again with the refined query
+- New terminology, proper names, or specific phrases = better results
+```
+web_search(query="<refined specific query>", count=10)
+```
+
+**If the page has promising links:**
+- Follow them with `web_fetch`
+- Go deeper into the rabbit hole
+- Source pages often link to primary sources
+
+**If the page is useless:**
+- Move to the next promising result
+- Don't waste time on dead ends
+
+### 4. Change Strategy If Stuck
+
+If initial searches aren't yielding results:
+- Try different phrasings
+- Search for adjacent topics that might lead to the answer
+- Look for expert sources (academic, official, specialized sites)
+- Try adding "reddit", "forum", "explained" for human perspectives
+- Use date filters for recent info: `startDate`, `endDate`
+- Use category filters: `news`, `papers`, `company`, etc.
+
+### 5. Never Give Up
+
+The information exists. Keep searching until you find it:
+- Try 3-5 different search strategies before considering it unfindable
+- If one angle fails, approach from another
+- Sometimes the answer is in an unexpected place
+
+---
+
+## Search Tips
+
+### Query Strategies
+| Goal | Strategy |
+|------|----------|
+| Exact phrase | `"exact phrase here"` |
+| Exclude terms | Add negative context in query |
+| Recent only | Use `startDate` parameter |
+| Specific sites | Include domain in query |
+| Technical depth | Add "documentation", "spec", "RFC" |
+| Human explanation | Add "explained", "ELI5", "guide" |
+
+### Source Quality
+| High Quality | Lower Quality |
+|--------------|---------------|
+| Official docs | Content farms |
+| Primary sources | Aggregators |
+| Expert blogs | Generic listicles |
+| Academic papers | Thin affiliate content |
+| GitHub repos | Outdated forums |
+
+### Category Filters (search APIs)
+- `news` - Recent news articles
+- `papers` - Academic/research papers
+- `company` - Company websites
+- `github` - GitHub repos
+- `tweet` - Twitter/X posts
+- `linkedin` - LinkedIn content
+
+---
+
+## Example Workflows
+
+### Finding a specific fact
+1. `web_search("who invented X")`
+2. Fetch top 2-3 results
+3. Cross-reference the answer
+4. Report with source
+
+### Understanding a concept
+1. `web_search("how does X work explained")`
+2. Fetch educational content
+3. If too shallow, search for technical docs
+4. If too deep, search for simpler explanations
+5. Synthesize understanding
+
+### Finding current information
+1. `web_search("X 2026", startDate="2026-01-01")`
+2. Fetch recent articles
+3. Follow links to primary announcements
+4. Verify with multiple sources
+
+### Investigating a company/person
+1. `web_search("Company Name")` - official site
+2. `web_search("Company Name news", category="news")`
+3. `web_search("Company Name reviews reddit")`
+4. Fetch and synthesize multiple perspectives
+
+---
+
+## Rules
+
+1. **Don't report "I couldn't find it" after one search** - try harder
+2. **Don't summarize search results without fetching** - actually read the pages
+3. **Don't stop at surface level** - dig until you hit truth
+4. **Do verify important facts** - cross-reference sources
+5. **Do follow the trail** - links lead to better links
+6. **Do adapt your strategy** - different questions need different approaches
+
+---
+
+## The Mindset
+
+You're an investigator. The answer is out there. Your job is to find it.
+
+- First search = opening a door
+- Each fetch = looking inside a room
+- Each refinement = getting closer
+- The answer = mission complete
+
+**Don't come back empty-handed.**