agentsys 5.8.2 → 5.8.4

package/.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "name": "agentsys",
   "description": "19 specialized plugins for AI workflow automation - task orchestration, PR workflow, slop detection, code review, drift detection, enhancement analysis, documentation sync, unified static analysis, perf investigations, topic research, agent config linting, cross-tool AI consultation, structured AI debate, workflow pattern learning, codebase onboarding, and contributor guidance",
-  "version": "5.8.2",
+  "version": "5.8.4",
   "owner": {
     "name": "Avi Fenesh",
     "url": "https://github.com/avifenesh"
@@ -29,7 +29,7 @@
         "url": "https://github.com/agent-sh/next-task.git"
       },
       "description": "Master workflow orchestrator: autonomous workflow with model optimization (opus/sonnet/haiku), two-file state management, workflow enforcement gates, 8 specialist agents",
-      "version": "1.1.0",
+      "version": "1.1.1",
       "category": "productivity",
       "homepage": "https://github.com/agent-sh/next-task"
     },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentsys",
-  "version": "5.8.2",
+  "version": "5.8.4",
   "description": "Professional-grade slash commands for Claude Code with cross-platform support",
   "keywords": [
     "workflow",

package/.kiro/agents/worktree-manager.json

@@ -1,7 +1,7 @@
 {
   "name": "worktree-manager",
   "description": "Create and manage git worktrees for isolated task development. Use this agent after task selection to create a clean working environment.",
-  "prompt": "# Worktree Manager Agent\n\nYou manage git worktrees to provide isolated development environments for each task.\nThis prevents work-in-progress from polluting the main working directory.\n\n## Phase 1: Pre-flight Checks\n\nVerify git is available and check current status:\n\n```bash\n# Verify git\ngit --version || { echo \"ERROR: git not available\"; exit 1; }\n\n# Check if already in a worktree\nCURRENT_DIR=$(pwd)\nMAIN_WORKTREE=$(git worktree list --porcelain | head -1 | cut -d' ' -f2)\n\nif [ \"$CURRENT_DIR\" != \"$MAIN_WORKTREE\" ]; then\n  echo \"WARNING: Already in a worktree at $CURRENT_DIR\"\n  echo \"ALREADY_IN_WORKTREE=true\"\nfi\n\n# Get current branch\nORIGINAL_BRANCH=$(git branch --show-current)\necho \"ORIGINAL_BRANCH=$ORIGINAL_BRANCH\"\n\n# Check for uncommitted changes\nif [ -n \"$(git status --porcelain)\" ]; then\n  echo \"HAS_UNCOMMITTED_CHANGES=true\"\n  git status --short\nfi\n```\n\n## Phase 2: Generate Worktree Path\n\nCreate a slug from the task title and generate paths:\n\n```javascript\nfunction generateWorktreePath(task) {\n  // Create slug from task title\n  const slug = task.title\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-|-$/g, '')\n    .substring(0, 40); // Limit slug length for filesystem compatibility\n\n  // Include task ID for uniqueness\n  const fullSlug = task.id ? `${slug}-${task.id}` : slug;\n\n  return {\n    slug: fullSlug,\n    branchName: `feature/${fullSlug}`,\n    worktreePath: `../worktrees/${fullSlug}`\n  };\n}\n```\n\n## Phase 3: Check for Existing Worktree\n\nCheck if worktree already exists (for resume scenarios):\n\n```bash\nWORKTREE_PATH=\"../worktrees/${SLUG}\"\nBRANCH_NAME=\"feature/${SLUG}\"\n\n# Check if worktree exists\nif git worktree list | grep -q \"$WORKTREE_PATH\"; then\n  echo \"WORKTREE_EXISTS=true\"\n  echo \"Worktree already exists at $WORKTREE_PATH\"\nfi\n\n# Check if branch exists\nif git branch --list \"$BRANCH_NAME\" | grep -q \"$BRANCH_NAME\"; then\n  echo \"BRANCH_EXISTS=true\"\nfi\n\n# Check remote branch\nif git ls-remote --heads origin \"$BRANCH_NAME\" | grep -q \"$BRANCH_NAME\"; then\n  echo \"REMOTE_BRANCH_EXISTS=true\"\nfi\n```\n\n## Phase 4: Handle Uncommitted Changes\n\nIf there are uncommitted changes, handle them:\n\n```bash\nif [ \"$HAS_UNCOMMITTED_CHANGES\" = \"true\" ]; then\n  echo \"Stashing uncommitted changes...\"\n  git stash push -m \"Auto-stash before worktree creation for task ${TASK_ID}\"\n  STASH_CREATED=\"true\"\nfi\n```\n\n## Phase 5: Create Worktree\n\nCreate the worktree with a new feature branch:\n\n```bash\n# Ensure worktrees directory exists\nmkdir -p ../worktrees\n\n# Create worktree with new branch\nif [ \"$WORKTREE_EXISTS\" = \"true\" ]; then\n  echo \"Using existing worktree at $WORKTREE_PATH\"\nelse\n  if [ \"$BRANCH_EXISTS\" = \"true\" ]; then\n    # Branch exists, create worktree from it\n    git worktree add \"$WORKTREE_PATH\" \"$BRANCH_NAME\"\n  elif [ \"$REMOTE_BRANCH_EXISTS\" = \"true\" ]; then\n    # Remote branch exists, track it\n    git worktree add --track -b \"$BRANCH_NAME\" \"$WORKTREE_PATH\" \"origin/$BRANCH_NAME\"\n  else\n    # Create new branch from main\n    git worktree add -b \"$BRANCH_NAME\" \"$WORKTREE_PATH\"\n  fi\n\n  if [ $? -eq 0 ]; then\n    echo \"[OK] Created worktree at $WORKTREE_PATH\"\n    echo \"[OK] Created branch $BRANCH_NAME\"\n  else\n    echo \"ERROR: Failed to create worktree\"\n    exit 1\n  fi\nfi\n```\n\n## Phase 6: Claim Task in Registry\n\nAdd task to `${STATE_DIR}/tasks.json` to prevent other workflows from claiming it:\n\n```javascript\nconst fs = require('fs');\nconst stateDir = process.env.AI_STATE_DIR || '.claude';\nif (!fs.existsSync(stateDir)) fs.mkdirSync(stateDir, { recursive: true });\n\nlet registry = fs.existsSync(`${stateDir}/tasks.json`)\n  ? JSON.parse(fs.readFileSync(`${stateDir}/tasks.json`))\n  : { version: '1.0.0', tasks: [] };\n\nconst entry = {\n  id: task.id, source: task.source, title: task.title,\n  branch, worktreePath: path.resolve(worktreePath),\n  claimedAt: new Date().toISOString(), claimedBy: state.workflow.id,\n  status: 'claimed', lastActivityAt: new Date().toISOString()\n};\n\nconst idx = registry.tasks.findIndex(t => t.id === task.id);\nif (idx >= 0) registry.tasks[idx] = entry;\nelse registry.tasks.push(entry);\n\nfs.writeFileSync(`${stateDir}/tasks.json`, JSON.stringify(registry, null, 2));\n```\n\n## Phase 7: Anchor PWD to Worktree\n\n**Important**: Change to the worktree directory to anchor all subsequent operations.\n\n**Note**: The `cd` command within a single Bash call does not persist across separate Bash tool invocations. The orchestrator must handle PWD anchoring at the workflow level by passing absolute paths or updating the working directory context between agent invocations.\n\n```bash\ncd \"$WORKTREE_PATH\"\n\n# Verify we're in the right place\nCURRENT_BRANCH=$(git branch --show-current)\nif [ \"$CURRENT_BRANCH\" != \"$BRANCH_NAME\" ]; then\n  echo \"ERROR: Not on expected branch. Expected $BRANCH_NAME, got $CURRENT_BRANCH\"\n  exit 1\nfi\n\necho \"[OK] Working directory anchored to: $(pwd)\"\necho \"[OK] On branch: $CURRENT_BRANCH\"\n# Note: Orchestrator must use this path for subsequent operations\necho \"WORKTREE_ABSOLUTE_PATH=$(pwd)\"\n```\n\n## Phase 8: Create Worktree Status File\n\nCreate `${STATE_DIR}/workflow-status.json` with task, workflow, git info, and resume state.\n\nKey fields: `task` (id, source, title), `workflow` (id, status, currentPhase), `git` (branch, baseSha, mainRepoPath), `resume` (canResume, resumeFromStep).\n\n## Phase 9: Update Workflow State\n\nCall `workflowState.updateState()` with git info (originalBranch, workingBranch, worktreePath, baseSha, isWorktree: true), then `workflowState.completePhase()`.\n\n## Phase 10: Output Summary\n\nReport: branch name, worktree path, base commit. Confirm PWD anchored to worktree.\n\n## Cleanup Responsibilities\n\n| Component | Creates | Cleans Up |\n|-----------|---------|-----------|\n| worktree-manager | worktrees, tasks.json entries, workflow-status.json | Nothing |\n| ship | - | worktrees (after merge), tasks.json entries |\n| --abort | - | worktrees, tasks.json entries |\n\n**Agents MUST NOT**: clean up worktrees, remove tasks from registry, or delete branches.\n\n## Cleanup Reference (for ship and --abort)\n\n```bash\ncleanup_worktree() {\n  cd \"$ORIGINAL_DIR\"\n  git worktree remove \"$WORKTREE_PATH\" --force 2>/dev/null\n  git worktree prune\n  [ -f \"${STATE_DIR}/tasks.json\" ] && node -e \"\n    const fs = require('fs');\n    const r = JSON.parse(fs.readFileSync('${STATE_DIR}/tasks.json'));\n    r.tasks = r.tasks.filter(t => t.id !== '$TASK_ID');\n    fs.writeFileSync('${STATE_DIR}/tasks.json', JSON.stringify(r, null, 2));\n  \"\n}\n```\n\n## Error Handling\n\nOn failure: remove partial worktree, prune refs, update state with `failPhase()`, exit 1.\n\n## Success Criteria\n\n- **Task claimed in main repo's tasks.json** (prevents collisions)\n- Worktree created at `../worktrees/{task-slug}`\n- Feature branch created: `feature/{task-slug}`\n- **workflow-status.json created in worktree** (for resume capability)\n- PWD anchored to worktree directory\n- Workflow state updated with git info\n- Phase advanced to exploration\n\n## Constraints\n\n- Only create worktrees - never delete them (cleanup is handled by ship or --abort)\n- Do not remove tasks from tasks.json registry\n- Do not delete branches\n- Do not modify files in the main repository after switching to worktree\n- Always claim tasks in registry before creating worktree\n- Always create workflow-status.json in the new worktree\n- Do not proceed if uncommitted changes exist without stashing first\n\n## Model Choice: Haiku\n\nThis agent uses **haiku** because:\n- Executes scripted git commands (deterministic)\n- No complex reasoning about code or architecture\n- Simple string manipulation for slugs/paths\n- Fast execution for setup operations",
+  "prompt": "# Worktree Manager Agent\n\nYou manage git worktrees to provide isolated development environments for each task.\nThis prevents work-in-progress from polluting the main working directory.\n\n## Phase 1: Pre-flight Checks\n\nVerify git is available and check current status:\n\n```bash\n# Verify git\ngit --version || { echo \"ERROR: git not available\"; exit 1; }\n\n# Check if already in a worktree\nCURRENT_DIR=$(pwd)\nMAIN_WORKTREE=$(git worktree list --porcelain | head -1 | cut -d' ' -f2)\n\nif [ \"$CURRENT_DIR\" != \"$MAIN_WORKTREE\" ]; then\n  echo \"WARNING: Already in a worktree at $CURRENT_DIR\"\n  echo \"ALREADY_IN_WORKTREE=true\"\nfi\n\n# Get current branch\nORIGINAL_BRANCH=$(git branch --show-current)\necho \"ORIGINAL_BRANCH=$ORIGINAL_BRANCH\"\n\n# Check for uncommitted changes\nif [ -n \"$(git status --porcelain)\" ]; then\n  echo \"HAS_UNCOMMITTED_CHANGES=true\"\n  git status --short\nfi\n```\n\n## Phase 2: Generate Worktree Path\n\nCreate a slug from the task title and generate paths:\n\n```javascript\nfunction generateWorktreePath(task) {\n  // Create slug from task title\n  const slug = task.title\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-|-$/g, '')\n    .substring(0, 40); // Limit slug length for filesystem compatibility\n\n  // Include task ID for uniqueness\n  const fullSlug = task.id ? `${slug}-${task.id}` : slug;\n\n  return {\n    slug: fullSlug,\n    branchName: `feature/${fullSlug}`,\n    worktreePath: `../worktrees/${fullSlug}`\n  };\n}\n```\n\n## Phase 3: Check for Existing Worktree\n\nCheck if worktree already exists (for resume scenarios):\n\n```bash\nWORKTREE_PATH=\"../worktrees/${SLUG}\"\nBRANCH_NAME=\"feature/${SLUG}\"\n\n# Check if worktree exists\nif git worktree list | grep -q \"$WORKTREE_PATH\"; then\n  echo \"WORKTREE_EXISTS=true\"\n  echo \"Worktree already exists at $WORKTREE_PATH\"\nfi\n\n# Check if branch exists\nif git branch --list \"$BRANCH_NAME\" | grep -q \"$BRANCH_NAME\"; then\n  echo \"BRANCH_EXISTS=true\"\nfi\n\n# Check remote branch\nif git ls-remote --heads origin \"$BRANCH_NAME\" | grep -q \"$BRANCH_NAME\"; then\n  echo \"REMOTE_BRANCH_EXISTS=true\"\nfi\n```\n\n## Phase 4: Handle Uncommitted Changes\n\nIf there are uncommitted changes, handle them:\n\n```bash\nif [ \"$HAS_UNCOMMITTED_CHANGES\" = \"true\" ]; then\n  echo \"Stashing uncommitted changes...\"\n  git stash push -m \"Auto-stash before worktree creation for task ${TASK_ID}\"\n  STASH_CREATED=\"true\"\nfi\n```\n\n## Phase 5: Create Worktree\n\nCreate the worktree with a new feature branch:\n\n```bash\n# Ensure worktrees directory exists\nmkdir -p ../worktrees\n\n# Create worktree with new branch\nif [ \"$WORKTREE_EXISTS\" = \"true\" ]; then\n  echo \"Using existing worktree at $WORKTREE_PATH\"\nelse\n  if [ \"$BRANCH_EXISTS\" = \"true\" ]; then\n    # Branch exists, create worktree from it\n    git worktree add \"$WORKTREE_PATH\" \"$BRANCH_NAME\"\n  elif [ \"$REMOTE_BRANCH_EXISTS\" = \"true\" ]; then\n    # Remote branch exists, track it\n    git worktree add --track -b \"$BRANCH_NAME\" \"$WORKTREE_PATH\" \"origin/$BRANCH_NAME\"\n  else\n    # Create new branch from main\n    git worktree add -b \"$BRANCH_NAME\" \"$WORKTREE_PATH\"\n  fi\n\n  if [ $? -eq 0 ]; then\n    echo \"[OK] Created worktree at $WORKTREE_PATH\"\n    echo \"[OK] Created branch $BRANCH_NAME\"\n  else\n    echo \"ERROR: Failed to create worktree\"\n    exit 1\n  fi\nfi\n```\n\n## Phase 6: Claim Task in Registry\n\nAdd task to `${STATE_DIR}/tasks.json` to prevent other workflows from claiming it.\n\nUse the library function — do NOT write raw `fs.writeFileSync` here (it bypasses atomic write-rename and has no optimistic locking):\n\n```javascript\nconst path = require('path');\nconst workflowState = require('../../lib/state/workflow-state');\n\n// PROJECT_PATH is the main repo root (not the worktree); passed in from the orchestrator\n// or resolved from the worktree git config: git -C worktreePath rev-parse --show-toplevel\nconst projectPath = process.env.PROJECT_PATH || process.cwd();\n\nconst ok = workflowState.claimTask({\n  id: task.id,\n  source: task.source,\n  title: task.title,\n  branch,\n  worktreePath: path.resolve(worktreePath),\n  claimedBy: state.workflow.id\n}, projectPath);\n\nif (!ok) {\n  // claimTask already logged the reason (concurrent write conflict after max retries).\n  // Fail hard so the orchestrator surfaces this to the user instead of continuing\n  // with an unclaimed task that could collide with another workflow.\n  throw new Error(`[ERROR] claimTask failed for task ${task.id} in ${projectPath} — see log above for details.`);\n}\n```\n\n## Phase 7: Anchor PWD to Worktree\n\n**Important**: Change to the worktree directory to anchor all subsequent operations.\n\n**Note**: The `cd` command within a single Bash call does not persist across separate Bash tool invocations. The orchestrator must handle PWD anchoring at the workflow level by passing absolute paths or updating the working directory context between agent invocations.\n\n```bash\ncd \"$WORKTREE_PATH\"\n\n# Verify we're in the right place\nCURRENT_BRANCH=$(git branch --show-current)\nif [ \"$CURRENT_BRANCH\" != \"$BRANCH_NAME\" ]; then\n  echo \"ERROR: Not on expected branch. Expected $BRANCH_NAME, got $CURRENT_BRANCH\"\n  exit 1\nfi\n\necho \"[OK] Working directory anchored to: $(pwd)\"\necho \"[OK] On branch: $CURRENT_BRANCH\"\n# Note: Orchestrator must use this path for subsequent operations\necho \"WORKTREE_ABSOLUTE_PATH=$(pwd)\"\n```\n\n## Phase 8: Create Worktree Status File\n\nCreate `${STATE_DIR}/workflow-status.json` with task, workflow, git info, and resume state.\n\nKey fields: `task` (id, source, title), `workflow` (id, status, currentPhase), `git` (branch, baseSha, mainRepoPath), `resume` (canResume, resumeFromStep).\n\n## Phase 9: Update Workflow State\n\nCall `workflowState.updateState()` with git info (originalBranch, workingBranch, worktreePath, baseSha, isWorktree: true), then `workflowState.completePhase()`.\n\n## Phase 10: Output Summary\n\nReport: branch name, worktree path, base commit. Confirm PWD anchored to worktree.\n\n## Cleanup Responsibilities\n\n| Component | Creates | Cleans Up |\n|-----------|---------|-----------|\n| worktree-manager | worktrees, tasks.json entries, workflow-status.json | Nothing |\n| ship | - | worktrees (after merge), tasks.json entries |\n| --abort | - | worktrees, tasks.json entries |\n\n**Agents MUST NOT**: clean up worktrees, remove tasks from registry, or delete branches.\n\n## Cleanup Reference (for ship and --abort)\n\nUse the library function — do NOT write raw `fs.writeFileSync` here (it bypasses atomic write-rename and has no optimistic locking):\n\n```bash\ncleanup_worktree() {\n  cd \"$ORIGINAL_DIR\"\n  git worktree remove \"$WORKTREE_PATH\" --force 2>/dev/null\n  git worktree prune\n  # Release task claim atomically via library (retry-safe, version-checked).\n  # PROJECT_PATH = main repo root (not the worktree). Use $ORIGINAL_DIR if available,\n  # or resolve from git: git -C \"$ORIGINAL_DIR\" rev-parse --show-toplevel\n  MAIN_REPO_PATH=\"${PROJECT_PATH:-$ORIGINAL_DIR}\"\n  node -e \"\n    const wf = require('./lib/state/workflow-state');\n    const ok = wf.releaseTask('$TASK_ID', process.env.MAIN_REPO_PATH || process.cwd());\n    if (!ok) {\n      process.stderr.write('[ERROR] releaseTask failed for task $TASK_ID after max retries. Registry entry may still be marked claimed. Retry: node -e \\'require(\\\\\"./lib/state/workflow-state\\\\\").releaseTask(\\\\\"\\'$TASK_ID\\'\\\\\")\\' \\n');\n      process.exit(1);\n    }\n  \" MAIN_REPO_PATH=\"$MAIN_REPO_PATH\"\n}\n```\n\n## Error Handling\n\nOn failure: remove partial worktree, prune refs, update state with `failPhase()`, exit 1.\n\n## Success Criteria\n\n- **Task claimed in main repo's tasks.json** (prevents collisions)\n- Worktree created at `../worktrees/{task-slug}`\n- Feature branch created: `feature/{task-slug}`\n- **workflow-status.json created in worktree** (for resume capability)\n- PWD anchored to worktree directory\n- Workflow state updated with git info\n- Phase advanced to exploration\n\n## Constraints\n\n- Only create worktrees - never delete them (cleanup is handled by ship or --abort)\n- Do not remove tasks from tasks.json registry\n- Do not delete branches\n- Do not modify files in the main repository after switching to worktree\n- Always claim tasks in registry before creating worktree\n- Always create workflow-status.json in the new worktree\n- Do not proceed if uncommitted changes exist without stashing first\n\n## Model Choice: Haiku\n\nThis agent uses **haiku** because:\n- Executes scripted git commands (deterministic)\n- No complex reasoning about code or architecture\n- Simple string manipulation for slugs/paths\n- Fast execution for setup operations",
   "tools": [
     "read",
     "write",

package/.kiro/skills/discover-tasks/SKILL.md

@@ -25,9 +25,9 @@ const workflowState = require('../../lib/state/workflow-state.js');
 const state = workflowState.readState();
 const policy = state.policy;
 
-// Load claimed tasks from registry
-const claimedTasks = workflowState.readTasks().tasks || [];
-const claimedIds = new Set(claimedTasks.map(t => t.id));
+// Load claimed task IDs from registry (tasks[] contains worktree-manager claims)
+const tasksRegistry = workflowState.readTasks();
+const claimedIds = new Set(tasksRegistry.tasks.map(t => t.id));
 ```
 
 ### Phase 2: Fetch Tasks by Source

package/CHANGELOG.md

@@ -9,6 +9,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.8.4] - 2026-04-20
+
+### Fixed
+- **tasks.json atomic optimistic locking** (#331) - Concurrent `/next-task` and `/ship` runs could silently lose claims or leave stale registry entries due to unguarded read-modify-write on `tasks.json`. Fix uses `_version` + per-write `_writerId` optimistic locking (mirrors existing `flow.json` pattern): write atomically via rename, re-read and verify both fields match before declaring success, retry up to 5× with jitter on mismatch.
+- **tasks.json schema unification** - `worktree-manager` wrote `{ version, tasks[] }` while `workflow-state.js` read `{ active }`, causing claim exclusion in `discover-tasks` to always return an empty set. Unified schema is `{ active, tasks[], _version, _writerId }` with on-read normalization of both legacy formats — no migration needed.
+- **Silent corruption risk** - `readTasks()` now throws on corrupted JSON instead of returning a safe default, preventing `updateTasks` from silently overwriting potentially recoverable data.
+- **Agent prompt raw file writes** - `worktree-manager` Phase 6 and Cleanup Reference replaced inline `fs.writeFileSync` with `workflowState.claimTask()` / `workflowState.releaseTask()` library calls that are atomic and retry-safe.
+
+### Added
+- `updateTasks(mutatorFn)` - optimistic-lock loop for `tasks.json` mutations (mirrors `updateFlow`)
+- `claimTask(entry, projectPath)` - atomic upsert into `tasks[]` registry for worktree-manager
+- `releaseTask(taskId, projectPath)` - atomic removal from `tasks[]` registry for ship/abort; idempotent
+
+## [5.8.3] - 2026-04-11
+
+### Fixed
+- **next-task v1.1.1** - SubagentStop hook now only fires during active /next-task workflows, not on every subagent stop (agent-sh/agentsys#325). Cross-platform guard script replaces unconditional prompt injection that wasted 136K+ tokens per unrelated agent.
+
+### Changed
+- Bump next-task marketplace version to 1.1.1
+
 ## [5.8.2] - 2026-04-11
 
 ### Added

package/README.md

@@ -19,8 +19,8 @@
 </p>
 
 <p align="center">
-  <b>19 plugins · 47 agents · 40 skills (across all repos) · 30k lines of lib code · 3,583 tests · 5 platforms</b><br>
-  <em>Plugins distributed as standalone repos under <a href="https://github.com/agent-sh">agent-sh</a> org — agentsys is the marketplace &amp; installer</em>
+  <b>19 plugins · 49 agents · 41 skills (across all repos) · 30k lines of lib code · 3,507 tests · 5 platforms</b><br>
+  <em>Plugins distributed as standalone repos under <a href="https://github.com/agent-sh">agent-sh</a> org - agentsys is the marketplace &amp; installer</em>
 </p>
 
 <p align="center">
@@ -38,14 +38,14 @@
 
 ---
 
-AI models can write code. That's not the hard part anymore. The hard part is everything around it — task selection, branch management, code review, artifact cleanup, CI, PR comments, deployment. **AgentSys is the runtime that orchestrates agents to handle all of it** — structured pipelines, gated phases, specialized agents, and persistent state that survives session boundaries.
+AI models can write code. That's not the hard part anymore. The hard part is everything around it - task selection, branch management, code review, artifact cleanup, CI, PR comments, deployment. **AgentSys is the runtime that orchestrates agents to handle all of it** - structured pipelines, gated phases, specialized agents, and persistent state that survives session boundaries.
 
 ---
-> Building custom skills, agents, hooks, or MCP tools? [agnix](https://github.com/agent-sh/agnix) is the CLI + LSP linter that catches config errors before they fail silently - real-time IDE validation, auto suggestions, auto-fix, and 385 rules for Claude Code, Codex, OpenCode, Cursor, Kiro, Copilot, Gemini CLI, Cline, Windsurf, Roo Code, Amp, and more.
+> Building custom skills, agents, hooks, or MCP tools? [agnix](https://github.com/agent-sh/agnix) is the CLI + LSP linter that catches config errors before they fail silently - real-time IDE validation, auto suggestions, auto-fix, and 399 rules for Claude Code, Codex, OpenCode, Cursor, Kiro, Copilot, Gemini CLI, Cline, Windsurf, Roo Code, Amp, and more.
 
 ## What This Is
 
-An agent orchestration system — 19 plugins, 47 agents, and 40 skills that compose into structured pipelines for software development. Each plugin lives in its own standalone repo under the [agent-sh](https://github.com/agent-sh) org. agentsys is the marketplace and installer that ties them together.
+An agent orchestration system - 19 plugins, 49 agents (39 file-based + 10 role-based specialists in audit-project), and 41 skills that compose into structured pipelines for software development. Each plugin lives in its own standalone repo under the [agent-sh](https://github.com/agent-sh) org. agentsys is the marketplace and installer that ties them together.
 
 Each agent has a single responsibility, a specific model assignment, and defined inputs/outputs. Pipelines enforce phase gates so agents can't skip steps. State persists across sessions so work survives interruptions.
 
@@ -57,8 +57,8 @@ The system runs on Claude Code, OpenCode, Codex CLI, Cursor, and Kiro. Install v
 
 **Code does code work. AI does AI work.**
 
-- **Detection**: regex, AST analysis, static analysis—fast, deterministic, no tokens wasted
-- **Judgment**: LLM calls for synthesis, planning, review—where reasoning matters
+- **Detection**: regex, AST analysis, static analysis - fast, deterministic, no tokens wasted
+- **Judgment**: LLM calls for synthesis, planning, review - where reasoning matters
 - **Result**: 77% fewer tokens for [/drift-detect](#drift-detect) vs multi-agent approaches, certainty-graded findings throughout
 
 **Certainty levels exist because not all findings are equal:**
@@ -118,7 +118,7 @@ The investment shifts from model spend to pipeline design. Better prompts, riche
 | [`/next-task`](#next-task) | Task workflow: discovery, implementation, PR, merge |
 | [`/prepare-delivery`](#prepare-delivery) | Pre-ship quality gates: deslop, review, validation, docs sync |
 | [`/gate-and-ship`](#gate-and-ship) | Quality gates then ship (/prepare-delivery + /ship) |
-| [`/agnix`](#agnix) | Lint agent configurations (385 rules) |
+| [`/agnix`](#agnix) | Lint agent configurations (399 rules) |
 | [`/ship`](#ship) | PR creation, CI monitoring, merge |
 | [`/deslop`](#deslop) | Clean AI slop patterns |
 | [`/perf`](#perf) | Performance investigation with baselines and profiling |
@@ -142,7 +142,7 @@ Each command works standalone. Together, they compose into end-to-end pipelines.
 
 ## Skills
 
-40 skills included across the plugins:
+41 skills included across the plugins:
 
 | Category | Skills |
 |----------|--------|
@@ -157,6 +157,7 @@ Each command works standalone. Together, they compose into end-to-end pipelines.
 | **Web** | `web-auth`, `web-browse` |
 | **Release** | `release` |
 | **Analysis** | `drift-analysis`, `repo-intel` |
+| **Linting** | `agnix` |
 
 **External skill plugins** (standalone repos, installed separately):
 
@@ -175,7 +176,7 @@ Skills are the reusable implementation units. Agents invoke skills; commands orc
 | [The Approach](#the-approach) | Why it's built this way |
 | [Benchmarks](#benchmarks) | Sonnet + agentsys vs raw Opus |
 | [Commands](#commands) | All 20 commands overview |
-| [Skills](#skills) | 40 skills across plugins |
+| [Skills](#skills) | 41 skills across plugins |
 | [Skill-Only Plugins](#skill-only-plugins) | glide-mq and other non-command plugins |
 | [Command Details](#command-details) | Deep dive into each command |
 | [How Commands Work Together](#how-commands-work-together) | Standalone vs integrated |
@@ -328,7 +329,7 @@ agnix catches these issues before they cause problems.
 | **Best Practices** | Tool restrictions, model selection, trigger phrase quality |
 | **Cross-Platform** | Compatibility across Claude Code, Codex, OpenCode, Cursor, Kiro, Copilot, Gemini CLI, Cline, Windsurf, Roo Code, Amp, and more |
 
-**385 validation rules** (102 auto-fixable) derived from:
+**399 validation rules** (126 auto-fixable) derived from:
 - Official tool specifications (Claude Code, Codex CLI, OpenCode, Cursor, Kiro, GitHub Copilot, Gemini CLI, Cline, Windsurf, Roo Code, Amp, and more)
 - Research papers on agent reliability and prompt injection
 - Real-world testing across 500+ repositories
@@ -442,7 +443,7 @@ If something can't be fixed, the workflow replies explaining why and resolves th
 
 ### /deslop
 
-**Purpose:** Finds AI slop—debug statements, placeholder text, verbose comments, TODOs—and removes it.
+**Purpose:** Finds AI slop - debug statements, placeholder text, verbose comments, TODOs - and removes it.
 
 **How detection works:**
 
@@ -613,13 +614,14 @@ Findings are collected and categorized by severity (critical/high/medium/low). A
 
 **Purpose:** Analyzes your prompts, plugins, agents, docs, hooks, and skills for improvement opportunities.
 
-**Seven analyzers run in parallel:**
+**Eight analyzers run in parallel:**
 
 | Analyzer | What it checks |
 |----------|----------------|
 | plugin-enhancer | Plugin structure, MCP tool definitions, security patterns |
 | agent-enhancer | Agent frontmatter, prompt quality |
 | claudemd-enhancer | CLAUDE.md/AGENTS.md structure, token efficiency |
+| cross-file-enhancer | Cross-file consistency (tools vs frontmatter, duplicate rules, conflicts) |
 | docs-enhancer | Documentation readability, RAG optimization |
 | prompt-enhancer | Prompt engineering patterns, clarity, examples |
 | hooks-enhancer | Hook frontmatter, structure, safety |
@@ -656,7 +658,7 @@ Findings are collected and categorized by severity (critical/high/medium/low). A
 - AST symbol mapping: exports, functions, classes, imports
 - Project metadata and health metrics
 
-Output is cached at `{state-dir}/repo-intel.json` and `{state-dir}/repo-map.json`.
+Output is cached at `{state-dir}/repo-intel.json` (external repo-intel plugin) and `{state-dir}/repo-map.json` (agentsys internal repo-map library). `{state-dir}` is `.claude/`, `.opencode/`, or `.codex/` depending on your platform.
 
 **Why it matters:**
 
@@ -678,7 +680,7 @@ Backed by [agent-analyzer](https://github.com/agent-sh/agent-analyzer) Rust bina
 
 ### /sync-docs
 
-**Purpose:** Sync documentation with actual code changes—find outdated refs, update CHANGELOG, flag stale examples.
+**Purpose:** Sync documentation with actual code changes - find outdated refs, update CHANGELOG, flag stale examples.
 
 **The problem it solves:**
 
@@ -958,7 +960,7 @@ No per-turn overhead - it reads transcripts that Claude Code already saves.
 **What happens when you run it:**
 
 1. **Collect** (68ms median) - Pure JavaScript scans manifest, structure, README, CI, git info. Normal depth adds CLAUDE.md/AGENTS.md and repo-intel. No LLM tokens.
-2. **Synthesize** - Opus agent produces a structured overview: tech stack, key files, active areas, conventions
+2. **Synthesize** - Sonnet agent produces a structured overview: tech stack, key files, active areas, conventions
 3. **Guide** - Interactive Q&A: ask about specific files, areas, or patterns
 
 **74% fewer tokens** than manual onboarding. Validated on 100 repos across JS/TS, Rust, Go, Python, C/C++, Java, and Deno.
@@ -981,7 +983,7 @@ No per-turn overhead - it reads transcripts that Claude Code already saves.
 /onboard --depth=deep       # Include AST data
 ```
 
-**Agent:** onboard-agent (opus model)
+**Agent:** onboard-agent (sonnet model)
 
 [Full documentation →](https://github.com/agent-sh/onboard)
 
@@ -994,7 +996,7 @@ No per-turn overhead - it reads transcripts that Claude Code already saves.
 **What happens when you run it:**
 
 1. **Collect** - Gathers project data + contributor signals (test gaps, doc drift, bugspots, good-first areas, open issues). Validated on 100 repos.
-2. **Match** - Opus agent asks about developer background and matches skills to project needs
+2. **Match** - Sonnet agent asks about developer background and matches skills to project needs
 3. **Guide** - For each recommendation: reads code, explains what needs doing, gives a concrete first step
 
 **Matching:**
@@ -1015,7 +1017,7 @@ No per-turn overhead - it reads transcripts that Claude Code already saves.
 /can-i-help --depth=deep          # Include AST data
 ```
 
-**Agent:** can-i-help-agent (opus model)
+**Agent:** can-i-help-agent (sonnet model)
 
 [Full documentation →](https://github.com/agent-sh/can-i-help)
 
@@ -1092,7 +1094,7 @@ Same principle as good code: single responsibility. The exploration-agent explor
 
 **2. Pipeline with gates, not a monolith**
 
-Same principle as DevOps. Each step must pass before the next begins. Can't push before review. Can't merge before CI passes. Hooks enforce this—agents literally cannot skip phases.
+Same principle as DevOps. Each step must pass before the next begins. Can't push before review. Can't merge before CI passes. Hooks enforce this - agents literally cannot skip phases.
 
 **3. Tools do tool work, agents do agent work**
 
@@ -1235,7 +1237,7 @@ The system is built on research, not guesswork.
 - Instruction following reliability
 
 **Testing:**
-- 3,583 tests passing
+- 3,507 tests passing
 - Drift-detect validated on 1,000+ repositories
 - E2E workflow testing across all commands
 - Cross-platform validation (Claude Code, OpenCode, Codex CLI, Cursor, Kiro)

package/lib/state/workflow-state.js

@@ -117,62 +117,248 @@ function getTasksPath(projectPath = process.cwd()) {
 }
 
 /**
- * Read tasks.json from main project
- * Returns { active: null } if file doesn't exist or is corrupted
- * Logs critical error on corruption to prevent silent data loss
+ * Read tasks.json from main project.
+ *
+ * Unified schema (v2):
+ *   { active: null|Object, tasks: [], _version: number }
+ *
+ * - active: single active workflow entry (set by createFlow / cleared by completeWorkflow)
+ * - tasks:  worktree claim registry (set by worktree-manager / cleared by ship or --abort)
+ * - _version: monotonic counter for optimistic locking (managed by writeTasks)
+ * - _writerId: per-write unique token used by updateTasks to detect concurrent wins
+ *
+ * Legacy formats are normalized on read — no migration script needed.
+ * Throws on corruption so callers can decide whether to abort or recover,
+ * rather than silently overwriting potentially recoverable data.
+ *
+ * @param {string} projectPath
+ * @returns {{ active: null|Object, tasks: Array, _version: number, _writerId?: string }}
+ * @throws {Error} If tasks.json exists but cannot be parsed
  */
 function readTasks(projectPath = process.cwd()) {
   const tasksPath = getTasksPath(projectPath);
   if (!fs.existsSync(tasksPath)) {
-    return { active: null };
+    return { active: null, tasks: [], _version: 0 };
   }
+  const raw = fs.readFileSync(tasksPath, 'utf8');
+  let data;
   try {
-    const data = JSON.parse(fs.readFileSync(tasksPath, 'utf8'));
-    // Normalize legacy format that may not have 'active' field
-    if (!Object.prototype.hasOwnProperty.call(data, 'active')) {
-      return { active: null };
-    }
-    return data;
+    data = JSON.parse(raw);
   } catch (e) {
-    console.error(`[CRITICAL] Corrupted tasks.json at ${tasksPath}: ${e.message}`);
-    return { active: null };
+    throw new Error(`[CRITICAL] Corrupted tasks.json at ${tasksPath}: ${e.message}. File must be repaired or deleted manually before writes are allowed.`);
   }
+  // Normalize: ensure every field exists (handles legacy { active } and legacy { version, tasks[] })
+  return {
+    active: Object.prototype.hasOwnProperty.call(data, 'active') ? data.active : null,
+    tasks: Array.isArray(data.tasks) ? data.tasks : [],
+    _version: typeof data._version === 'number' ? data._version : 0,
+    _writerId: typeof data._writerId === 'string' ? data._writerId : undefined
+  };
 }
 
 /**
- * Write tasks.json to main project
+ * Write tasks.json atomically.
+ * Increments _version and stamps a unique _writerId per write.
+ *
+ * Both fields are used by updateTasks to verify it was the winning writer:
+ * if two processes both read _version N, both write _version N+1 (last
+ * renameSync wins), the loser re-reads and finds a _writerId that does not
+ * match its own — it knows it lost and retries.
+ *
+ * @returns {string} The _writerId stamped into this write
  */
 function writeTasks(tasks, projectPath = process.cwd()) {
   ensureStateDir(projectPath);
+  const copy = structuredClone(tasks);
+  copy._version = (copy._version || 0) + 1;
+  copy._writerId = crypto.randomBytes(8).toString('hex');
   const tasksPath = getTasksPath(projectPath);
-  writeJsonAtomic(tasksPath, tasks);
-  return true;
+  writeJsonAtomic(tasksPath, copy);
+  return copy._writerId;
 }
 
 /**
- * Set active task in main project
+ * Apply a mutation to tasks.json with optimistic locking.
+ *
+ * Uses _version + _writerId to detect wins in concurrent-writer races:
+ *   1. Read current state, snapshot _version
+ *   2. Apply mutatorFn(clone) → new state; skip write if state unchanged
+ *   3. Stamp a unique writerId, write atomically (increments _version)
+ *   4. Re-read: if _version === initialVersion + 1 AND _writerId matches → we won
+ *   5. Otherwise another writer raced us → back off with jitter, retry
+ *
+ * @param {function(Object): Object} mutatorFn - Pure function that receives a
+ *   deep clone of current tasks state and returns the desired new state.
+ *   Must not have side effects; may be called multiple times on retry.
+ * @param {string} projectPath
+ * @returns {boolean} true on success, false after MAX_RETRIES exhausted or on corruption
+ */
+function updateTasks(mutatorFn, projectPath = process.cwd()) {
+  const MAX_RETRIES = 5;
+
+  let current;
+  try {
+    current = readTasks(projectPath);
+  } catch (e) {
+    console.error(`[ERROR] updateTasks: cannot read tasks.json — ${e.message}`);
+    return false;
+  }
+
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    const initialVersion = current._version || 0;
+
+    let updated;
+    try {
+      updated = mutatorFn(structuredClone(current));
+    } catch (e) {
+      console.error(`[ERROR] updateTasks: mutatorFn threw on attempt ${attempt + 1}: ${e.message}`);
+      return false;
+    }
+
+    // Skip write if mutatorFn made no changes — avoids spurious version bumps
+    if (JSON.stringify(updated) === JSON.stringify(current)) {
+      return true;
+    }
+
+    // Carry forward the pre-write version so writeTasks increments it by exactly 1
+    updated._version = initialVersion;
+
+    const writerId = writeTasks(updated, projectPath);
+
+    // Verify we won: version must be exactly initialVersion + 1 AND writerId must match ours.
+    // If another process also wrote _version: initialVersion + 1, only one writerId survives.
+    let afterWrite;
+    try {
+      afterWrite = readTasks(projectPath);
+    } catch (e) {
+      console.error(`[ERROR] updateTasks: tasks.json corrupted after write on attempt ${attempt + 1}: ${e.message}`);
+      return false;
+    }
+
+    if (afterWrite._version === initialVersion + 1 && afterWrite._writerId === writerId) {
+      return true;
+    }
+
+    // Lost the race — retry from the current on-disk state
+    if (attempt < MAX_RETRIES - 1) {
+      const delay = Math.floor(Math.random() * 50) + 10;
+      sleepForRetry(delay);
+      try {
+        current = readTasks(projectPath);
+      } catch (e) {
+        console.error(`[ERROR] updateTasks: tasks.json corrupted during retry ${attempt + 1}: ${e.message}`);
+        return false;
+      }
+    }
+  }
+
+  const tasksPath = getTasksPath(projectPath);
+  let lastVersion = '(unreadable)';
+  try { lastVersion = readTasks(projectPath)._version; } catch {}
+
+  // Final fallback: if a concurrent writer happened to apply the exact same
+  // mutation (idempotent operations like releaseTask on an already-absent entry),
+  // treat the outcome as a success rather than reporting a spurious failure.
+  let latest;
+  try { latest = readTasks(projectPath); } catch {}
+  if (latest) {
+    // Re-run the mutator on what's on disk; if the result is identical to
+    // what's already there, our desired state is already achieved.
+    try {
+      const wouldBe = mutatorFn(structuredClone(latest));
+      // Normalize _version/_writerId before comparing content
+      wouldBe._version = latest._version;
+      wouldBe._writerId = latest._writerId;
+      if (JSON.stringify(wouldBe) === JSON.stringify(latest)) {
+        return true;
+      }
+    } catch {}
+  }
+
+  console.error(
+    `[ERROR] updateTasks: all ${MAX_RETRIES} attempts failed due to concurrent writers on ${tasksPath}. ` +
+    `Another agent process is modifying the registry simultaneously. ` +
+    `Last known _version: ${lastVersion}. ` +
+    `Suggested recovery: wait for the competing process to finish, then retry the operation.`
+  );
+  return false;
+}
+
+/**
+ * Set active task in main project (uses optimistic locking)
  */
 function setActiveTask(task, projectPath = process.cwd()) {
-  const tasks = readTasks(projectPath);
-  tasks.active = {
-    ...task,
-    startedAt: new Date().toISOString()
-  };
-  return writeTasks(tasks, projectPath);
+  return updateTasks(tasks => {
+    tasks.active = { ...task, startedAt: new Date().toISOString() };
+    return tasks;
+  }, projectPath);
 }
 
 /**
- * Clear active task
+ * Clear active task (uses optimistic locking)
  */
 function clearActiveTask(projectPath = process.cwd()) {
-  const tasks = readTasks(projectPath);
-  tasks.active = null;
-  return writeTasks(tasks, projectPath);
+  return updateTasks(tasks => {
+    tasks.active = null;
+    return tasks;
+  }, projectPath);
+}
+
+/**
+ * Claim a task in the registry (uses optimistic locking).
+ * Used by worktree-manager; replaces the raw fs.writeFileSync inline in agent prompts.
+ *
+ * @param {Object} entry - { id, source, title, branch, worktreePath, claimedBy }
+ * @param {string} projectPath
+ */
+function claimTask(entry, projectPath = process.cwd()) {
+  if (!entry || !entry.id) {
+    console.error('[ERROR] claimTask: entry.id is required');
+    return false;
+  }
+  return updateTasks(tasks => {
+    const idx = tasks.tasks.findIndex(t => t.id === entry.id);
+    const record = {
+      ...entry,
+      status: 'claimed',
+      claimedAt: entry.claimedAt || new Date().toISOString(),
+      lastActivityAt: new Date().toISOString()
+    };
+    if (idx >= 0) {
+      tasks.tasks[idx] = record;
+    } else {
+      tasks.tasks.push(record);
+    }
+    return tasks;
+  }, projectPath);
+}
+
+/**
+ * Release a claimed task from the registry (uses optimistic locking).
+ * Used by ship and --abort; replaces the raw fs.writeFileSync inline cleanup.
+ *
+ * @param {string} taskId
+ * @param {string} projectPath
+ */
+function releaseTask(taskId, projectPath = process.cwd()) {
+  if (!taskId) {
+    console.error('[ERROR] releaseTask: taskId is required');
+    return false;
+  }
+  return updateTasks(tasks => {
+    const before = tasks.tasks.length;
+    tasks.tasks = tasks.tasks.filter(t => t.id !== taskId);
+    if (tasks.tasks.length === before) {
+      // Not found — that's fine, idempotent
+      console.error(`[WARN] releaseTask: task ${taskId} was not found in tasks.json registry. It may have already been released or never claimed.`);
+    }
+    return tasks;
+  }, projectPath);
 }
 
 /**
- * Check if there's an active task
- * Uses != null to catch both null and undefined (legacy format safety)
+ * Check if there's an active task.
+ * Uses != null to catch both null and undefined (legacy format safety).
  */
 function hasActiveTask(projectPath = process.cwd()) {
   const tasks = readTasks(projectPath);
@@ -548,8 +734,11 @@ module.exports = {
   getTasksPath,
   readTasks,
   writeTasks,
+  updateTasks,
   setActiveTask,
   clearActiveTask,
+  claimTask,
+  releaseTask,
   hasActiveTask,
 
   // Flow (worktree)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentsys",
-  "version": "5.8.2",
+  "version": "5.8.4",
   "description": "A modular runtime and orchestration system for AI agents - works with Claude Code, OpenCode, and Codex CLI",
   "main": "lib/platform/detect-platform.js",
   "type": "commonjs",

package/scripts/generate-docs.js

@@ -109,7 +109,8 @@ const STATIC_SKILLS = [
   { plugin: 'audit-project', name: 'audit-project' },
   { plugin: 'glidemq', name: 'glide-mq' },
   { plugin: 'glidemq', name: 'glide-mq-migrate-bullmq' },
-  { plugin: 'glidemq', name: 'glide-mq-migrate-bee' }
+  { plugin: 'glidemq', name: 'glide-mq-migrate-bee' },
+  { plugin: 'agnix', name: 'agnix' }
 ];
 
 // Purpose mapping for architecture table
@@ -192,7 +193,7 @@ function generateCommandsTable(commands) {
     'next-task': 'Task workflow: discovery, implementation, PR, merge',
     'prepare-delivery': 'Pre-ship quality gates: deslop, review, validation, docs sync',
     'gate-and-ship': 'Quality gates then ship (/prepare-delivery + /ship)',
-    'agnix': 'Lint agent configurations (385 rules)',
+    'agnix': 'Lint agent configurations (399 rules)',
     'ship': 'PR creation, CI monitoring, merge',
     'deslop': 'Clean AI slop patterns',
     'perf': 'Performance investigation with baselines and profiling',
@@ -395,9 +396,34 @@ function generateAgentCounts(agents, plugins) {
 /**
  * Update counts in site/content.json programmatically.
  */
-// Static counts for cross-repo plugins not discoverable locally
-const STATIC_PLUGIN_COUNT = 19;
-const STATIC_AGENT_COUNT = 47;
+// Static counts for cross-repo plugins not discoverable locally.
+// Per-plugin file-based agent counts. Update this map when agents are added/removed
+// in a plugin repo - it's the canonical source for the STATIC_AGENT_COUNT fallback.
+const STATIC_PLUGIN_AGENT_COUNTS = {
+  'next-task': 8,
+  'prepare-delivery': 3,
+  'gate-and-ship': 0,
+  'ship': 1,
+  'deslop': 1,
+  'audit-project': 0,
+  'drift-detect': 1,
+  'enhance': 8,
+  'sync-docs': 1,
+  'repo-intel': 1,
+  'perf': 6,
+  'learn': 1,
+  'agnix': 1,
+  'consult': 1,
+  'debate': 1,
+  'web-ctl': 1,
+  'skillers': 2,
+  'onboard': 1,
+  'can-i-help': 1
+};
+const STATIC_PLUGIN_COUNT = Object.keys(STATIC_PLUGIN_AGENT_COUNTS).length;
+const STATIC_FILE_BASED_AGENT_COUNT = Object.values(STATIC_PLUGIN_AGENT_COUNTS).reduce((sum, count) => sum + count, 0);
+// Total = file-based + role-based (audit-project specialists, spawned dynamically)
+const STATIC_AGENT_COUNT = STATIC_FILE_BASED_AGENT_COUNT + ROLE_BASED_AGENT_COUNT;
 
 function updateSiteContent(plugins, agents, skills) {
   const contentPath = path.join(ROOT_DIR, 'site', 'content.json');
@@ -652,6 +678,8 @@ module.exports = {
   PURPOSE_MAP,
   ROLE_BASED_AGENT_COUNT,
   STATIC_SKILLS,
+  STATIC_PLUGIN_AGENT_COUNTS,
   STATIC_PLUGIN_COUNT,
+  STATIC_FILE_BASED_AGENT_COUNT,
   STATIC_AGENT_COUNT
 };

package/site/content.json

@@ -1,11 +1,11 @@
 {
   "meta": {
     "title": "agentsys",
-    "description": "A modular runtime and orchestration system for AI agents. 19 plugins, 47 agents, 40 skills - structured pipelines for Claude Code, OpenCode, Codex CLI, Cursor, and Kiro.",
+    "description": "A modular runtime and orchestration system for AI agents. 19 plugins, 49 agents, 41 skills - structured pipelines for Claude Code, OpenCode, Codex CLI, Cursor, and Kiro.",
     "url": "https://agent-sh.github.io/agentsys",
     "repo": "https://github.com/agent-sh/agentsys",
     "npm": "https://www.npmjs.com/package/agentsys",
-    "version": "5.8.2",
+    "version": "5.8.4",
     "author": "Avi Fenesh",
     "author_url": "https://github.com/avifenesh"
   },
@@ -28,12 +28,12 @@
       "suffix": ""
     },
     {
-      "value": "47",
+      "value": "49",
       "label": "Agents",
       "suffix": ""
     },
     {
-      "value": "40",
+      "value": "41",
       "label": "Skills",
       "suffix": ""
     },
@@ -43,7 +43,7 @@
       "suffix": ""
     },
     {
-      "value": "3,750",
+      "value": "3,507",
       "label": "Tests",
       "suffix": ""
     },
@@ -112,7 +112,7 @@
     {
       "name": "/agnix",
       "tagline": "Lint agent configs before they break",
-      "description": "385 validation rules (102 auto-fixable) for Skills, Memory, Hooks, MCP, and Plugins across 10+ AI tools including Claude Code, Cursor, GitHub Copilot, Codex CLI, OpenCode, Gemini CLI, Cline, Windsurf, Roo Code, and Amp. SARIF output for GitHub Code Scanning.",
+      "description": "399 validation rules (126 auto-fixable) for Skills, Memory, Hooks, MCP, and Plugins across 10+ AI tools including Claude Code, Cursor, GitHub Copilot, Codex CLI, OpenCode, Gemini CLI, Cline, Windsurf, Roo Code, and Amp. SARIF output for GitHub Code Scanning.",
       "example": "/agnix --fix",
       "category": "linting"
     },
@@ -154,7 +154,7 @@
     {
       "name": "/enhance",
       "tagline": "Analyze everything that shapes agent behavior",
-      "description": "Seven parallel analyzers check your prompts, agents, plugins, docs, hooks, and skills. Certainty-graded findings with auto-fix support. Auto-learns false positives over time.",
+      "description": "Eight parallel analyzers check your prompts, agents, plugins, docs, hooks, and skills. Certainty-graded findings with auto-fix support. Auto-learns false positives over time.",
       "example": "/enhance",
       "category": "analysis"
     },
@@ -373,19 +373,28 @@
     }
   ],
   "agents": {
-    "total": 47,
-    "file_based": 37,
+    "total": 49,
+    "file_based": 39,
     "role_based": 10,
     "by_model": [
       {
         "model": "Opus",
         "use_case": "Complex reasoning, analysis",
         "agents": [
-          "exploration-agent",
           "planning-agent",
           "implementation-agent",
           "perf-orchestrator",
-          "learn-agent"
+          "perf-analyzer",
+          "perf-theory-gatherer",
+          "perf-theory-tester",
+          "agent-enhancer",
+          "claudemd-enhancer",
+          "docs-enhancer",
+          "hooks-enhancer",
+          "prompt-enhancer",
+          "skills-enhancer",
+          "debate-orchestrator",
+          "skillers-recommender"
         ]
       },
       {
@@ -393,10 +402,26 @@
         "use_case": "Validation, pattern matching",
         "agents": [
           "task-discoverer",
+          "exploration-agent",
+          "prepare-delivery-agent",
           "delivery-validator",
           "ci-fixer",
+          "test-coverage-checker",
           "deslop-agent",
-          "enhancement reporters"
+          "cross-file-enhancer",
+          "plugin-enhancer",
+          "perf-code-paths",
+          "perf-investigation-logger",
+          "plan-synthesizer",
+          "learn-agent",
+          "sync-docs-agent",
+          "agnix-agent",
+          "consult-agent",
+          "web-session",
+          "skillers-compactor",
+          "release-agent",
+          "onboard-agent",
+          "can-i-help-agent"
         ]
       },
       {
@@ -405,7 +430,8 @@
         "agents": [
           "worktree-manager",
           "ci-monitor",
-          "simple-fixer"
+          "simple-fixer",
+          "map-validator"
         ]
       }
     ]
@@ -505,7 +531,7 @@
   ],
   "research": {
     "knowledge_base": "8,000 lines of curated documentation from Anthropic, OpenAI, Google, and Microsoft",
-    "testing": "3,750 tests passing",
+    "testing": "3,507 tests passing",
     "drift_detect_repos": "1,000+ repositories validated",
     "token_reduction": "77% fewer tokens for drift-detect vs multi-agent approaches"
   },

package/site/index.html

@@ -4,12 +4,12 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>AgentSys - Agent Runtime &amp; Orchestration System</title>
-  <meta name="description" content="A modular runtime and orchestration system for AI agents. 19 plugins, 47 agents, 40 skills — structured pipelines for Claude Code, OpenCode, Codex CLI, Cursor, and Kiro.">
+  <meta name="description" content="A modular runtime and orchestration system for AI agents. 19 plugins, 49 agents, 41 skills - structured pipelines for Claude Code, OpenCode, Codex CLI, Cursor, and Kiro.">
   <meta name="theme-color" content="#09090b">
 
   <!-- Open Graph -->
   <meta property="og:title" content="AgentSys">
-  <meta property="og:description" content="A modular runtime and orchestration system for AI agents. 19 plugins, 47 agents, 40 skills.">
+  <meta property="og:description" content="A modular runtime and orchestration system for AI agents. 19 plugins, 49 agents, 41 skills.">
   <meta property="og:image" content="https://agent-sh.github.io/agentsys/assets/logo.png">
   <meta property="og:url" content="https://agent-sh.github.io/agentsys/">
   <meta property="og:type" content="website">
@@ -17,7 +17,7 @@
   <!-- Twitter Card -->
   <meta name="twitter:card" content="summary_large_image">
   <meta name="twitter:title" content="AgentSys">
-  <meta name="twitter:description" content="AI workflow automation. 19 plugins, 47 agents, 40 skills.">
+  <meta name="twitter:description" content="AI workflow automation. 19 plugins, 49 agents, 41 skills.">
   <meta name="twitter:image" content="https://agent-sh.github.io/agentsys/assets/logo.png">
 
   <!-- Content Security Policy -->
@@ -107,14 +107,14 @@
       <div class="hero__inner">
         <div class="hero__content">
           <div class="hero__badge anim-fade-in" data-delay="100">
-            19 plugins &middot; 47 agents &middot; 40 skills
+            19 plugins &middot; 49 agents &middot; 41 skills
           </div>
           <h1 class="hero__title anim-fade-up" id="hero-title" data-delay="200">
             A modular <span class="text-gradient">runtime and orchestration system</span><br>
             for AI agents.
           </h1>
           <p class="hero__subtitle anim-fade-up" data-delay="350">
-            Structured pipelines, gated phases, specialized agents. Works with Claude Code, OpenCode, Codex CLI, Cursor, and Kiro. 3,750 tests. Production-grade.
+            Structured pipelines, gated phases, specialized agents. Works with Claude Code, OpenCode, Codex CLI, Cursor, and Kiro. 3,507 tests. Production-grade.
           </p>
           <div class="hero__ctas anim-fade-up" data-delay="500">
             <a href="#install" class="btn btn--primary">Get Started</a>
@@ -160,15 +160,15 @@
           <span class="stats__label">Plugins</span>
         </div>
         <div class="stats__item">
-          <span class="stats__number" aria-live="polite" data-target="47">0</span>
+          <span class="stats__number" aria-live="polite" data-target="49">0</span>
           <span class="stats__label">Agents</span>
         </div>
         <div class="stats__item">
-          <span class="stats__number" aria-live="polite" data-target="40">0</span>
+          <span class="stats__number" aria-live="polite" data-target="41">0</span>
           <span class="stats__label">Skills</span>
         </div>
         <div class="stats__item">
-          <span class="stats__number" aria-live="polite" data-target="3750">0</span>
+          <span class="stats__number" aria-live="polite" data-target="3507">0</span>
           <span class="stats__label">Tests Passing</span>
         </div>
       </div>
@@ -228,9 +228,9 @@
             <h3 class="tabs__panel-name">/agnix</h3>
             <p class="tabs__panel-tagline">Lint agent configs before they break</p>
             <ul class="tabs__panel-features">
-              <li>385 validation rules across 36 categories</li>
+              <li>399 validation rules across 36 categories</li>
               <li>10+ AI tools: Claude Code, Cursor, Copilot, Codex, OpenCode, Gemini CLI</li>
-              <li>102 auto-fixable rules with --fix flag</li>
+              <li>126 auto-fixable rules with --fix flag</li>
               <li>SARIF output for GitHub Code Scanning</li>
             </ul>
             <div class="code-block">
@@ -607,7 +607,7 @@
               <svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><circle cx="12" cy="12" r="3"/></svg>
             </div>
             <h3 class="philosophy__card-title">One agent, one job, done well</h3>
-            <p class="philosophy__card-desc"><span class="text-accent">47 specialized agents</span>, each with a narrow scope and clear success criteria. No agent tries to do everything.</p>
+            <p class="philosophy__card-desc"><span class="text-accent">49 specialized agents</span>, each with a narrow scope and clear success criteria. No agent tries to do everything.</p>
           </div>
           <div class="philosophy__card anim-fade-up" data-delay="200">
             <div class="philosophy__card-icon">
@@ -662,14 +662,14 @@
     <!-- ===== AGENTS & SKILLS ===== -->
     <section class="agents-skills" id="agents-skills" aria-labelledby="as-title">
       <div class="agents-skills__inner">
-        <h2 class="agents-skills__title anim-fade-up" id="as-title">47 Agents. 40 Skills.</h2>
+        <h2 class="agents-skills__title anim-fade-up" id="as-title">49 Agents. 41 Skills.</h2>
         <p class="agents-skills__subtitle anim-fade-up" data-delay="100">Right model for the task. Opus reasons. Sonnet validates. Haiku executes.</p>
 
         <!-- Agent tier tabs -->
         <div class="agents-skills__tabs anim-fade-up" data-delay="200">
           <div class="agent-tabs" role="tablist" aria-label="Agent tiers">
-            <button class="agent-tabs__tab agent-tabs__tab--active" role="tab" aria-selected="true" aria-controls="agent-tier-opus" id="agent-tab-opus" data-index="0">Opus <span class="agent-tabs__count">15</span></button>
-            <button class="agent-tabs__tab" role="tab" aria-selected="false" aria-controls="agent-tier-sonnet" id="agent-tab-sonnet" tabindex="-1" data-index="1">Sonnet <span class="agent-tabs__count">18</span></button>
+            <button class="agent-tabs__tab agent-tabs__tab--active" role="tab" aria-selected="true" aria-controls="agent-tier-opus" id="agent-tab-opus" data-index="0">Opus <span class="agent-tabs__count">14</span></button>
+            <button class="agent-tabs__tab" role="tab" aria-selected="false" aria-controls="agent-tier-sonnet" id="agent-tab-sonnet" tabindex="-1" data-index="1">Sonnet <span class="agent-tabs__count">21</span></button>
             <button class="agent-tabs__tab" role="tab" aria-selected="false" aria-controls="agent-tier-haiku" id="agent-tab-haiku" tabindex="-1" data-index="2">Haiku <span class="agent-tabs__count">4</span></button>
             <button class="agent-tabs__tab" role="tab" aria-selected="false" aria-controls="agent-tier-specialists" id="agent-tab-specialists" tabindex="-1" data-index="3">Specialists <span class="agent-tabs__count">10</span></button>
           </div>
@@ -677,13 +677,12 @@
           <!-- Opus agents -->
           <div class="agent-tier tabs__panel tabs__panel--active" role="tabpanel" id="agent-tier-opus" aria-labelledby="agent-tab-opus">
             <div class="agent-grid">
-              <div class="agent-card"><span class="agent-card__name">exploration-agent</span><span class="tier-badge tier-badge--opus">opus</span><p class="agent-card__desc">Deep codebase analysis and context gathering</p></div>
               <div class="agent-card"><span class="agent-card__name">planning-agent</span><span class="tier-badge tier-badge--opus">opus</span><p class="agent-card__desc">Step-by-step implementation design</p></div>
               <div class="agent-card"><span class="agent-card__name">implementation-agent</span><span class="tier-badge tier-badge--opus">opus</span><p class="agent-card__desc">Autonomous code writing and modification</p></div>
               <div class="agent-card"><span class="agent-card__name">perf-orchestrator</span><span class="tier-badge tier-badge--opus">opus</span><p class="agent-card__desc">Performance investigation coordination</p></div>
               <div class="agent-card"><span class="agent-card__name">perf-analyzer</span><span class="tier-badge tier-badge--opus">opus</span><p class="agent-card__desc">Deep performance analysis and profiling</p></div>
-              <div class="agent-card"><span class="agent-card__name">learn-agent</span><span class="tier-badge tier-badge--opus">opus</span><p class="agent-card__desc">Web research and learning guide creation</p></div>
-              <div class="agent-card"><span class="agent-card__name">plan-synthesizer</span><span class="tier-badge tier-badge--opus">opus</span><p class="agent-card__desc">Multi-source plan synthesis and merging</p></div>
+              <div class="agent-card"><span class="agent-card__name">perf-theory-gatherer</span><span class="tier-badge tier-badge--opus">opus</span><p class="agent-card__desc">Performance hypothesis generation</p></div>
+              <div class="agent-card"><span class="agent-card__name">perf-theory-tester</span><span class="tier-badge tier-badge--opus">opus</span><p class="agent-card__desc">Controlled experiment execution</p></div>
               <div class="agent-card"><span class="agent-card__name">agent-enhancer</span><span class="tier-badge tier-badge--opus">opus</span><p class="agent-card__desc">Agent configuration quality analysis</p></div>
               <div class="agent-card"><span class="agent-card__name">claudemd-enhancer</span><span class="tier-badge tier-badge--opus">opus</span><p class="agent-card__desc">CLAUDE.md file optimization</p></div>
               <div class="agent-card"><span class="agent-card__name">docs-enhancer</span><span class="tier-badge tier-badge--opus">opus</span><p class="agent-card__desc">Documentation quality improvement</p></div>
@@ -699,6 +698,8 @@
           <div class="agent-tier tabs__panel" role="tabpanel" id="agent-tier-sonnet" aria-labelledby="agent-tab-sonnet" hidden>
             <div class="agent-grid">
               <div class="agent-card"><span class="agent-card__name">task-discoverer</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Task source scanning and prioritization</p></div>
+              <div class="agent-card"><span class="agent-card__name">exploration-agent</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Deep codebase analysis and context gathering</p></div>
+              <div class="agent-card"><span class="agent-card__name">prepare-delivery-agent</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Pre-ship quality gate orchestration</p></div>
               <div class="agent-card"><span class="agent-card__name">delivery-validator</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Pre-ship quality gate validation</p></div>
               <div class="agent-card"><span class="agent-card__name">ci-fixer</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">CI failure diagnosis and auto-repair</p></div>
               <div class="agent-card"><span class="agent-card__name">test-coverage-checker</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Test coverage analysis and gap detection</p></div>
@@ -707,8 +708,8 @@
               <div class="agent-card"><span class="agent-card__name">plugin-enhancer</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Plugin configuration validation</p></div>
               <div class="agent-card"><span class="agent-card__name">perf-code-paths</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Hot code path identification</p></div>
               <div class="agent-card"><span class="agent-card__name">perf-investigation-logger</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Performance investigation logging</p></div>
-              <div class="agent-card"><span class="agent-card__name">perf-theory-gatherer</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Performance hypothesis generation</p></div>
-              <div class="agent-card"><span class="agent-card__name">perf-theory-tester</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Controlled experiment execution</p></div>
+              <div class="agent-card"><span class="agent-card__name">plan-synthesizer</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Multi-source plan synthesis and merging</p></div>
+              <div class="agent-card"><span class="agent-card__name">learn-agent</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Web research and learning guide creation</p></div>
               <div class="agent-card"><span class="agent-card__name">sync-docs-agent</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Documentation sync and update</p></div>
               <div class="agent-card"><span class="agent-card__name">agnix-agent</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Agent config linting orchestration</p></div>
               <div class="agent-card"><span class="agent-card__name">consult-agent</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Cross-tool AI consultation orchestration</p></div>
@@ -716,6 +717,7 @@
               <div class="agent-card"><span class="agent-card__name">skillers-compactor</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Transcript compaction into knowledge themes</p></div>
               <div class="agent-card"><span class="agent-card__name">release-agent</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Versioned release with ecosystem detection</p></div>
               <div class="agent-card"><span class="agent-card__name">onboard-agent</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Codebase orientation and guided onboarding</p></div>
+              <div class="agent-card"><span class="agent-card__name">can-i-help-agent</span><span class="tier-badge tier-badge--sonnet">sonnet</span><p class="agent-card__desc">Contributor guidance matching skills to project needs</p></div>
             </div>
           </div>
 
@@ -747,7 +749,7 @@
         </div>
 
         <!-- Skills grid -->
-        <h3 class="agents-skills__skills-title anim-fade-up" data-delay="300">40 Skills across 19 Plugins</h3>
+        <h3 class="agents-skills__skills-title anim-fade-up" data-delay="300">41 Skills across 19 Plugins</h3>
         <div class="skills-grid anim-fade-up" data-delay="350">
           <div class="skill-group">
             <span class="skill-group__label">prepare-delivery</span>
@@ -819,6 +821,7 @@
               <span class="skill-card">onboard</span>
               <span class="skill-card">can-i-help</span>
               <span class="skill-card">audit-project</span>
+              <span class="skill-card">agnix</span>
             </div>
           </div>
           <div class="skill-group">

package/site/ux-spec.md

@@ -94,7 +94,7 @@ Scroll order with rationale for each section. All sections are full-width, alter
 - **Single column on mobile:** Text above, terminal below. Stack with 48px gap.
 
 ### Left Column Content
-1. **Badge** (top, above title): Small pill showing version or "19 plugins . 47 agents . 40 skills"
+1. **Badge** (top, above title): Small pill showing version or "19 plugins . 49 agents . 41 skills"
    - Background: `rgba(99, 102, 241, 0.12)`, border: `1px solid rgba(99, 102, 241, 0.25)`, border-radius: 9999px
    - Font: 13px, font-weight 500, primary accent color
    - Padding: 4px 14px
@@ -104,7 +104,7 @@ Scroll order with rationale for each section. All sections are full-width, alter
    - Color: white
    - "entire dev workflow" portion highlighted with a subtle gradient text (primary-to-secondary accent via `background-clip: text`)
 
-3. **Subtitle:** "19 plugins, 47 agents, 40 skills. From task selection to merged PR. Works with Claude Code, OpenCode, Codex CLI, Cursor, and Kiro."
+3. **Subtitle:** "19 plugins, 49 agents, 41 skills. From task selection to merged PR. Works with Claude Code, OpenCode, Codex CLI, Cursor, and Kiro."
    - Font: 18px on desktop, 16px on mobile, font-weight 400, line-height 1.6
    - Color: `rgba(255, 255, 255, 0.6)`
    - Max-width: 520px
@@ -226,10 +226,10 @@ Done. Task to merged PR in 12 minutes.
 ### Stats (left to right)
 | Stat | Value | Label |
 |------|-------|-------|
-| 1 | 14 | Plugins |
-| 2 | 43 | Agents |
-| 3 | 30 | Skills |
-| 4 | 3,750 | Tests Passing |
+| 1 | 19 | Plugins |
+| 2 | 49 | Agents |
+| 3 | 40 | Skills |
+| 4 | 3,507 | Tests Passing |
 
 ### Styling
 - **Number:** 48px, font-weight 700, white, `font-variant-numeric: tabular-nums` (prevents layout shift during count)
@@ -650,13 +650,13 @@ This disables:
 ### Head Content
 ```html
 <title>AgentSys - Agent Runtime &amp; Orchestration System</title>
-<meta name="description" content="A modular runtime and orchestration system for AI agents. 19 plugins, 47 agents, 40 skills — structured pipelines for Claude Code, OpenCode, Codex CLI, Cursor, and Kiro.">
+<meta name="description" content="A modular runtime and orchestration system for AI agents. 19 plugins, 49 agents, 41 skills - structured pipelines for Claude Code, OpenCode, Codex CLI, Cursor, and Kiro.">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="theme-color" content="#0a0a0f">
 
 <!-- Open Graph -->
 <meta property="og:title" content="AgentSys">
-<meta property="og:description" content="AI workflow automation. 19 plugins, 47 agents, 40 skills. Task to merged PR.">
+<meta property="og:description" content="AI workflow automation. 19 plugins, 49 agents, 41 skills. Task to merged PR.">
 <meta property="og:image" content="https://agent-sh.github.io/agentsys/assets/og-image.png">
 <meta property="og:url" content="https://agent-sh.github.io/agentsys/">
 <meta property="og:type" content="website">
@@ -664,7 +664,7 @@ This disables:
 <!-- Twitter Card -->
 <meta name="twitter:card" content="summary_large_image">
 <meta name="twitter:title" content="AgentSys">
-<meta name="twitter:description" content="AI workflow automation. 19 plugins, 47 agents, 40 skills.">
+<meta name="twitter:description" content="AI workflow automation. 19 plugins, 49 agents, 41 skills.">
 <meta name="twitter:image" content="https://agent-sh.github.io/agentsys/assets/og-image.png">
 ```