worclaude 2.3.0 → 2.4.1

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to worclaude are documented in this file. Format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [semver](https://semver.org/). Older releases (pre-2.3.0) are documented in [docs/spec/PROGRESS.md](./docs/spec/PROGRESS.md) and the [GitHub releases page](https://github.com/sefaertunc/Worclaude/releases).
 
+## [Unreleased]
+
+## [2.4.1] — 2026-04-18
+
+Internal CI tooling — no change to the scaffolded output or npm package surface.
+
+### Added
+
+- Daily `upstream-check` GitHub Actions workflow (09:30 UTC cron) that fetches the anthropic-watch feeds, diffs against committed state, and opens a GitHub issue when a Worclaude-relevant change appears. Completes the emit half of the anthropic-watch integration ([#69](https://github.com/sefaertunc/Worclaude/pull/69)).
+- `scripts/upstream-precheck.mjs` — zero-dep Node 20 parallel feed fetch with 10s timeout, Set-based delta detection, 90-day firstSeen prune, and a 3-strike feed-unreachable watchdog with auto-recovery.
+- `scripts/upstream-parse.mjs` — reads `claude-code-action` execution JSONL, applies a strict `SKIP_ISSUE` / `# Title:` / `# Body` contract with a plaintext fallback.
+- `scripts/_gha-outputs.mjs` — shared zero-dep GitHub Actions helpers.
+- `.github/upstream-state.json` — schema v2 state file (seeded from live `all.json`); every mutation gated on `github.ref == 'refs/heads/main'` so feature-branch dispatches stay read-only.
+- `tests/fixtures/upstream/` — four parser fixtures (skip, issue, malformed, plaintext-fallback).
+- `docs/reference/upstream-automation.md` — operations runbook and required branch-protection settings for the workflow.
+
+### Changed
+
+- `docs/reference/slash-commands.md` — cross-link to the new upstream-automation reference page.
+- `docs/.vitepress/config.mjs` — sidebar entry for upstream-automation; `phases/**` added to `srcExclude`.
+
+### Removed
+
+- `docs/research/PHASE-1-DIAGNOSIS-REPORT.md` — retired investigation scratchpad (preserved in git history).
+
+## [2.4.0] — 2026-04-16
+
+Worclaude 2.4.0 adds **upstream awareness**: every scaffolded project now ships a `/upstream-check` command and an `upstream-watcher` universal agent that consume the [anthropic-watch](https://github.com/sefaertunc/anthropic-watch) feeds at runtime (16 Anthropic sources — Claude Code releases, SDK changelogs, docs, engineering blog, status page, and more) and report what's new, what's critical, and what affects the current project. No new npm dependencies — fetching happens via `curl` inside Claude Code.
+
+### Added
+
+- `/upstream-check` command (scaffolded template) — on-demand, stateless status check. Fetches `run-report.json` and `all.json`, reports source health (`Y/16 healthy`) and the 10 most recent items grouped by category, and flags items from `claude-code-releases`, `claude-code-changelog`, `npm-claude-code`, `agent-sdk-ts-changelog`, or `agent-sdk-py-changelog` as `[CRITICAL]`. Graceful fetch-failure handling.
+- `upstream-watcher` universal agent — deep upstream impact analysis (Sonnet, `isolation: none`, read-only: `disallowedTools: [Edit, Write, NotebookEdit]`). Cross-references new upstream items against the project's scaffolded `.claude/` surface area (agents, commands, hooks, skills, settings) and produces a three-part report: direct impact, informational, recommended actions. Feeds fetched in parallel to bound worst-case latency by a single `--max-time`.
+- Agent routing entry for `upstream-watcher` (manual trigger, Stage 1: Context, `/upstream-check` as the paired command).
+- Worclaude-internal `.claude/commands/upstream-check.md` (dogfood) — same fetch/flag behavior as the scaffolded template, plus a Worclaude-specific cross-reference layer that checks each `[CRITICAL]` item against `src/data/agents.js`, `src/data/agent-registry.js`, `src/core/scaffolder.js`, `src/core/merger.js`, `templates/hooks/*.cjs`, `docs/spec/BACKLOG-v2.1.md`, `templates/skills/universal/*.md`, and `CLAUDE.md` Critical Rules. Each cross-reference classified as Action needed / No impact detected / Needs investigation.
+
+### Changed
+
+- `UNIVERSAL_AGENTS` 5 → 6, `COMMAND_FILES` 17 → 18, `AGENT_REGISTRY` 25 → 26. Manifest audit tests and `init` / `merger` / `agent-routing` generator tests updated to iterate over `UNIVERSAL_AGENTS` instead of hardcoded lists — adding future universals no longer requires updating those tests.
+- Stale literal counts dropped from `src/data/agent-registry.js` doc-comment and Universal section header so they stop drifting.
+
 ## [2.3.0] — 2026-04-15
 
 Worclaude 2.3.0 expands the workflow from a setup scaffold into a full **learning system**: Claude captures corrections automatically, replays them across sessions, and now generates cross-tool rule files so switching from Claude Code to Cursor or Codex does not mean re-writing your conventions. Eight lifecycle hooks (up from three) plus a dedicated `coding-principles` reference card tighten the feedback loop between you and Claude.

package/README.md

@@ -25,13 +25,13 @@
 
 # Worclaude — The Workflow Layer for Claude Code
 
-Worclaude scaffolds a complete Claude Code workflow into any project in seconds. One `init` command installs 25 agents, 17 slash commands, 16 skills, 8 lifecycle hooks, a two-store memory system, and a CLAUDE.md template tuned for your tech stack. It implements the patterns in [howborisusesclaudecode.com](https://www.howborisusesclaudecode.com/) as a reusable, upgradable scaffold, so you stop rebuilding the same configuration for every new project.
+Worclaude scaffolds a complete Claude Code workflow into any project in seconds. One `init` command installs 26 agents, 18 slash commands, 16 skills, 8 lifecycle hooks, a two-store memory system, and a CLAUDE.md template tuned for your tech stack. It implements the patterns in [howborisusesclaudecode.com](https://www.howborisusesclaudecode.com/) as a reusable, upgradable scaffold, so you stop rebuilding the same configuration for every new project.
 
 <div align="center">
 
 | CLI Commands |          Agents           | Slash Commands |        Skills         |      Hooks       |  Tech Stacks  |
 | :----------: | :-----------------------: | :------------: | :-------------------: | :--------------: | :-----------: |
-|      8       | 5 universal + 20 optional |       17       |          16           |     8 events     |      16       |
+|      8       | 6 universal + 20 optional |       18       |          16           |     8 events     |      16       |
 | subcommands  |    across 6 categories    | session tools  | universal + templates | lifecycle events | auto-detected |
 
 </div>
@@ -42,16 +42,16 @@ Worclaude scaffolds a complete Claude Code workflow into any project in seconds.
 
 `worclaude init` installs a production-ready Claude Code workflow:
 
-### Agents (25 total)
+### Agents (26 total)
 
-- **5 universal:** plan-reviewer (Opus), code-simplifier (Sonnet, worktree), test-writer (Sonnet, worktree), build-validator (Haiku), verify-app (Sonnet, worktree)
+- **6 universal:** plan-reviewer (Opus), code-simplifier (Sonnet, worktree), test-writer (Sonnet, worktree), build-validator (Haiku), verify-app (Sonnet, worktree), upstream-watcher (Sonnet)
 - **20 optional** across 6 categories — Backend, Frontend, DevOps, Quality, Documentation, Data/AI. Worclaude recommends agents based on your project type.
 
-### Slash Commands (17)
+### Slash Commands (18)
 
-Session lifecycle, review, verification, memory, and git automation:
+Session lifecycle, review, verification, memory, upstream awareness, and git automation:
 
-`/start` `/end` `/commit-push-pr` `/review-plan` `/techdebt` `/verify` `/compact-safe` `/status` `/update-claude-md` `/learn` `/setup` `/sync` `/conflict-resolver` `/review-changes` `/build-fix` `/refactor-clean` `/test-coverage`
+`/start` `/end` `/commit-push-pr` `/review-plan` `/techdebt` `/verify` `/compact-safe` `/status` `/update-claude-md` `/learn` `/setup` `/sync` `/conflict-resolver` `/review-changes` `/build-fix` `/refactor-clean` `/test-coverage` `/upstream-check`
 
 ### Skills (16)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "The Workflow Layer for Claude Code — scaffold agents, commands, skills, hooks, and memory into any project",
   "type": "module",
   "bin": {

package/src/data/agent-registry.js

@@ -1,11 +1,11 @@
 /**
- * Agent routing metadata for all 25 agents.
+ * Agent routing metadata for every agent in the registry.
  * Used by the agent-routing generator to produce the routing skill file.
  * Separate from agents.js because this data is only consumed by the generator,
  * not by CLI prompts or display logic.
  */
 export const AGENT_REGISTRY = {
-  // --- Universal agents (5) ---
+  // --- Universal agents ---
 
   'plan-reviewer': {
     category: 'universal',
@@ -73,6 +73,21 @@ export const AGENT_REGISTRY = {
     expectBack: 'Detailed verification report. Blocking issues listed.',
     situationLabel: 'Finished a task, ready for PR',
   },
+  'upstream-watcher': {
+    category: 'universal',
+    model: 'Sonnet',
+    isolation: 'none',
+    pipelineStage: 'Stage 1: Context',
+    triggerType: 'manual',
+    triggerCommand: '/upstream-check',
+    whenToUse:
+      'At the start of a session to check for upstream Claude Code changes. After Claude Code updates. When behavior seems different from last session.',
+    whatItDoes:
+      "Fetches anthropic-watch feeds, cross-references upstream changes against the project's scaffolded agents/commands/hooks/skills, and produces an impact report.",
+    expectBack:
+      'Impact report: which upstream changes affect this project, which are informational, and recommended actions.',
+    situationLabel: 'Want to check for upstream Claude Code changes',
+  },
 
   // --- Frontend agents (2) ---
 

package/src/data/agents.js

@@ -4,6 +4,7 @@ export const UNIVERSAL_AGENTS = [
   'test-writer',
   'build-validator',
   'verify-app',
+  'upstream-watcher',
 ];
 
 export const AGENT_CATALOG = {
@@ -195,6 +196,7 @@ export const COMMAND_FILES = [
   'refactor-clean',
   'test-coverage',
   'learn',
+  'upstream-check',
 ];
 
 export const UNIVERSAL_SKILLS = [

package/templates/agents/universal/upstream-watcher.md

@@ -0,0 +1,120 @@
+---
+name: upstream-watcher
+description: "Cross-references new Anthropic upstream changes against the current project's scaffolded infrastructure and produces an impact report"
+model: sonnet
+isolation: none
+memory: project
+disallowedTools:
+  - Edit
+  - Write
+  - NotebookEdit
+maxTurns: 30
+criticalSystemReminder: "CRITICAL: You CANNOT edit files. Report findings only. Suggest actions but do not implement them."
+---
+
+You are an upstream-awareness specialist. You fetch the anthropic-watch feeds,
+read the current project's Claude Code infrastructure, and produce a focused
+impact report describing which upstream changes matter for THIS project.
+
+You are read-only. Report findings and recommend actions — do not implement them.
+
+## 1. Fetch Upstream Feeds
+
+Feed base: `https://sefaertunc.github.io/anthropic-watch/feeds/`
+
+Fetch both feeds in parallel to keep the worst-case wait bounded by a single
+`--max-time`:
+
+```bash
+curl -s --max-time 10 https://sefaertunc.github.io/anthropic-watch/feeds/run-report.json &
+curl -s --max-time 10 https://sefaertunc.github.io/anthropic-watch/feeds/all.json &
+wait
+```
+
+If either fetch fails (non-zero exit, empty body, or non-JSON), report
+"Could not reach anthropic-watch feeds" and stop — no impact analysis is
+possible without the feed data.
+
+`run-report.json` gives per-source health and `newItemCount`. `all.json` gives
+the full list of items across all 16 sources, sorted newest-first. Each item
+carries `source`, `sourceCategory`, `title`, `date`, `url`, `snippet`.
+
+## 2. Read Project Infrastructure
+
+Enumerate the scaffolded surface area so you know what upstream changes could
+affect:
+
+- `.claude/agents/*.md` — every agent and its frontmatter (model, isolation, tools)
+- `.claude/commands/*.md` — every slash command
+- `.claude/skills/*/SKILL.md` — every skill
+- `.claude/hooks/*` — every hook script, especially `pre-compact-save.cjs`
+- `.claude/settings.json` and `.claude/settings.local.json` — permissions, env, hooks wiring
+- `CLAUDE.md` and `AGENTS.md` — project conventions
+- `package.json` (or equivalent) — whether the project imports `@anthropic-ai/sdk`
+  or `anthropic` directly
+
+Use `ls`, `cat`, and `grep` via the Read/Bash tools. You do not need to read
+every file in full — frontmatter and imports are usually enough.
+
+## 3. Impact Classification
+
+For each new upstream item, classify it into one of these buckets:
+
+| Source family | What to check in this project |
+|---|---|
+| Claude Code releases / changelog / npm-claude-code | Agent frontmatter syntax, hook event names, command syntax, tool names used by agents |
+| Agent SDK TS/Py changelog | Spawned-agent capabilities, tool schemas, isolation semantics, hook input/output shapes |
+| Anthropic API SDK / docs | Relevant **only** if the project imports the SDK directly — skip otherwise |
+| Engineering blog | New patterns or best practices worth adopting; never blocking |
+| Status page | Informational only; no action required |
+| Other sources | Classify by content — prefer informational unless it names something the project uses |
+
+## 4. Report Format
+
+Produce three sections:
+
+### Direct impact
+
+Items that affect this project's scaffolded infrastructure. For each item:
+
+- **[Source] Title** — `url`
+- Affected: which agent / command / hook / skill / setting, and why
+- Why it matters: 1-2 sentences
+
+### Informational
+
+Items worth knowing about but requiring no action. One bullet per item: title,
+source, one-line reason it is informational.
+
+### Recommended actions
+
+Concrete, actionable follow-ups tied to direct-impact items. Examples:
+
+- "Review `pre-compact-save.cjs` — PreCompact hook input shape changed in Claude Code vX.Y"
+- "Update `verify-app` agent frontmatter — new `isolation: ephemeral` option available"
+- "Check `@anthropic-ai/sdk` pinned version — Y.Z deprecates {feature} used in src/foo.js"
+
+Each action must name the specific file and the specific upstream change that
+prompts it.
+
+## 5. Empty Case
+
+If the feeds report no new items, or if no new items affect this project, say
+so in one line. Do not pad the report.
+
+> No new upstream items since {timestamp}.
+
+or
+
+> {N} new upstream items. None affect this project's scaffolded infrastructure.
+
+## Rules
+
+- You are read-only. Never edit files. Never run destructive commands.
+- Be specific: name the affected file, frontmatter field, or import — not "some agents".
+- Skip items that are clearly informational (blog think-pieces, status incidents)
+  after a one-line mention.
+- If confidence is low that an upstream change affects this project, list it as
+  informational rather than direct-impact. Do not cry wolf.
+- Keep the report scannable. Direct-impact and actions are the parts the user
+  will act on — lead with them.

package/templates/commands/upstream-check.md

@@ -0,0 +1,85 @@
+---
+description: "On-demand check of Anthropic upstream feeds (Claude Code releases, SDK changelogs, blog, status)"
+---
+
+Fetch the anthropic-watch feeds and report a concise summary of upstream changes.
+This is a stateless, on-demand status check — no caching, no persistence.
+
+Feed base URL: `https://sefaertunc.github.io/anthropic-watch/feeds/`
+
+## 1. Fetch Run Report
+
+```bash
+curl -s --max-time 10 https://sefaertunc.github.io/anthropic-watch/feeds/run-report.json
+```
+
+If the fetch fails (non-zero exit, empty body, or non-JSON output), report:
+
+```
+Could not reach anthropic-watch feeds.
+```
+
+and stop.
+
+Otherwise, parse the JSON and extract:
+
+- `timestamp` — when the scraper last ran
+- `sources[]` — list of all 16 sources with `{key, name, category, status, newItemCount, error}`
+
+Count how many sources have `status: "ok"` vs errored sources. List each errored source
+with its error message.
+
+## 2. Fetch All Items
+
+```bash
+curl -s --max-time 10 https://sefaertunc.github.io/anthropic-watch/feeds/all.json
+```
+
+Apply the same failure handling.
+
+Otherwise, parse and take the **10 most recent items** (they are already sorted
+newest-first). Group them by `sourceCategory` (`core` vs `extended`).
+
+For each item show:
+
+- Title
+- Source name (`sourceName`)
+- Date (relative like "2 days ago" when you can compute it, otherwise ISO date)
+- URL
+
+## 3. Highlight Claude Code-Critical Items
+
+Any item whose `source` is one of:
+
+- `claude-code-releases`
+- `claude-code-changelog`
+- `npm-claude-code`
+- `agent-sdk-ts-changelog`
+- `agent-sdk-py-changelog`
+
+directly affects scaffolded worclaude infrastructure. Flag these with a `[CRITICAL]`
+prefix in the listing so the user notices them first.
+
+## 4. Closing Summary
+
+End with a single line:
+
+```
+X new items since {timestamp}. Y/16 sources healthy.
+```
+
+Where X is the total item count across all sources (sum of `newItemCount` from the
+run report) and Y is the healthy-source count.
+
+## Rules
+
+- Use only `curl` and shell builtins. Do not invoke `node` or `npm`.
+- Do not cache, persist, or diff against prior runs — this command is stateless.
+- Keep the output concise. This is a status check, not a research report.
+- If both feeds fail, stop after the first failure message.
+
+## Trigger Phrases
+- "check upstream"
+- "what changed in claude code"
+- "any anthropic updates"
+- "upstream status"