agentera 3.0.0-dev.15 → 3.0.0-dev.16

package/README.md

@@ -1,43 +1,64 @@
-# Agentera CLI (npm)
+# Agentera CLI
 
-Native TypeScript CLI for Agentera 3.x, published as [`agentera`](https://www.npmjs.com/package/agentera).
+Native TypeScript CLI for Agentera 3.0, published as
+[`agentera`](https://www.npmjs.com/package/agentera). The npm package is
+self-contained: compiled commands live in `dist/` and runtime data, manifests,
+hooks, agents, skills, contracts, and documentation live in `bundle/`.
 
-| Dist tag | Channel | Use for |
-| --- | --- | --- |
-| `@latest` | stable (2.x) | Supported production line |
-| `@next` | development (3.x pre-releases) | Early testing of the self-contained npm CLI |
-
-## Quick start
+Until the stable dist-tag is promoted, run 3.0 through `@next`:
 
 ```bash
 npx -y agentera@next prime --format json
-npx -y agentera@next upgrade --dry-run --channel development
+npx -y agentera@next doctor --format json
 ```
 
-Run those from a project root. `prime` reports `project_integration.recommendation`
-(`stay` or `upgrade`) and suggested commands for the current repo.
+`prime` returns a bounded project and four-runtime lifecycle summary. `doctor`
+returns detailed read-only evidence and exact user actions.
 
-Full preview instructions, channels, and migration paths: [`UPGRADE.md`](../../UPGRADE.md).
+## Runtime lifecycle
 
-## Editor runtime installs
+The four active runtimes are OpenCode, Codex, Cursor, and GitHub Copilot; their
+IDs are exactly `opencode`, `codex`, `cursor`, and `copilot`.
+Cursor Agent CLI and Cursor IDE are surfaces of one `cursor` identity; CLI is
+required and IDE is conditional. The canonical shared skill path is
+`~/.agents/skills/agentera`.
 
-Agentera ships a skill bundle for supported editor runtimes (Claude Code, OpenCode, Cursor, Copilot CLI, Codex CLI). Install steps and parity details live in the [repository README — Internals](../../README.md#internals) and [`references/adapters/runtime-feature-parity.md`](../../references/adapters/runtime-feature-parity.md).
+```bash
+npx -y agentera@next upgrade --runtime all --dry-run
+npx -y agentera@next upgrade --runtime all --yes
+```
 
-## Package layout
+Use one active ID instead of `all` to scope the operation. `--dry-run` has zero
+filesystem or state side effects. `--yes` approves only declared Agentera-owned
+operations; native install/update, authentication, enablement, and trust remain
+user-owned. Secure automatic apply is Linux-only and reports
+`action_required` elsewhere.
 
-- `dist/` — compiled CLI (`agentera` bin)
-- `bundle/` — shipped app data (`skills/`, `references/`, `registry.json`)
+Retired Claude cleanup is intentionally separate:
 
-Requires Node.js 22+.
+```bash
+npx -y agentera@next upgrade --legacy-cleanup claude --dry-run
+```
+
+It can remove only the exact Agentera-owned legacy link. Historical transcript
+import is also explicit (`agentera report refresh --import-source claude`) and
+is excluded from default active-runtime analytics.
+
+See [UPGRADE.md](../../UPGRADE.md) for ownership, recovery, and migration
+details and [runtime feature parity](../../references/adapters/runtime-feature-parity.md)
+for host-specific behavior.
 
 ## Contributors
 
-Build and test from the monorepo:
+Requires Node.js 22+ and pnpm 10.30.3.
 
 ```bash
-pnpm -C packages/cli build
 pnpm -C packages/cli test
-pnpm -C packages/cli run publish:dev   # publishes with @next tag
+pnpm -C packages/cli run typecheck
+pnpm -C packages/cli build
+pnpm -C packages/cli run lint
 ```
 
-See [`AGENTS.md`](../../AGENTS.md) for capability validation and commit conventions.
+Use `npm pack --dry-run --json --ignore-scripts` after `build` and
+`bundle:data` to inspect the exact publication surface. Do not publish from a
+normal development or capability cycle.

package/bundle/.codex-plugin/plugin.json

@@ -0,0 +1,92 @@
+{
+  "name": "agentera",
+  "version": "3.0.0",
+  "description": "Compound agent orchestration suite \u2014 12 capabilities in one bundled skill; exact bare /agentera belongs to the bundled agentera dashboard path",
+  "author": {
+    "name": "Jonathan Gabor",
+    "url": "https://github.com/jgabor"
+  },
+  "homepage": "https://github.com/jgabor/agentera",
+  "repository": "https://github.com/jgabor/agentera",
+  "license": "Apache-2.0",
+  "keywords": ["agentera", "skills", "agents", "coding", "memory", "orchestration"],
+  "skills": "./skills/",
+  "hooks": "./hooks/codex-plugin-hooks.json",
+  "interface": {
+    "displayName": "Agentera",
+    "shortDescription": "Portable skills that give Codex exact bare /agentera routing, project memory, planning, execution, and review workflows.",
+    "longDescription": "Agentera turns Codex into a coordinated engineering partner with shared project artifacts, decision memory, planning, autonomous execution, audits, documentation, visual identity, research, optimization, and orchestration. A complete user message exactly `/agentera` belongs to the bundled agentera skill and its agentera status dashboard path, not the legacy hej bridge.",
+    "developerName": "Jonathan Gabor",
+    "category": "Coding",
+    "capabilities": ["Interactive", "Read", "Write"],
+    "websiteURL": "https://github.com/jgabor/agentera",
+    "privacyPolicyURL": "https://github.com/jgabor/agentera",
+    "termsOfServiceURL": "https://github.com/jgabor/agentera/blob/main/LICENSE",
+    "defaultPrompt": [
+      "Use $agentera to inspect this project and suggest the next best action. If the complete user message is exactly `/agentera`, use $agentera's status dashboard path."
+    ],
+    "brandColor": "#111827",
+    "screenshots": []
+  },
+  "codex": {
+    "uiMetadata": "./agents/openai.yaml",
+    "discovery": {
+      "skills": "/skills",
+      "plugins": "/plugins"
+    },
+    "invocationHint": "Use $agentera for explicit invocation. If the complete user message is exactly `/agentera`, route it through $agentera and the status dashboard path; $hej is only a legacy explicit bridge.",
+    "limitations": [
+      "profile collects bounded Codex session corpus data when present and reports any absent source families in corpus metadata.",
+      "Agentera lifecycle upgrade can install the canonical shared skill and Agentera-owned hooks or agents. AGENTERA_HOME configuration, Codex plugin enablement, and trust remain user-owned."
+    ]
+  },
+  "agentera": {
+    "packageShape": "suite-bundle",
+    "installRoot": "..",
+    "sharedPaths": ["skills", "hooks", "registry.json", "plugin.json", "README.md", "UPGRADE.md"],
+    "singleSkillInstall": "Single-skill installs keep core SKILL.md workflow behavior; suite tools are bundle-only enhancements."
+  },
+  "lifecycleHooks": {
+    "runtime": "codex-cli",
+    "status": "stable",
+    "configured": false,
+    "limitations": [
+      "codex_hooks ships stable and default-on as of v0.124.0 (2026-04-23). The bundled hooks/codex-hooks.json wires apply_patch PreToolUse and PostToolUse handlers per openai/codex#18391 (merged 2026-04-22).",
+      "The shipped Codex hook config validates touched artifact paths through `npx -y agentera hook validate-artifact`, but it does not reconstruct final patch content for hard-gate validation. SessionStart and Stop are supported by the runtime but are not wired by the bundled config."
+    ],
+    "supportedEvents": [
+      "SessionStart",
+      "Stop",
+      "UserPromptSubmit",
+      "PreToolUse",
+      "PostToolUse",
+      "PermissionRequest"
+    ],
+    "unsupportedEvents": [
+      {
+        "event": "SubagentStop",
+        "reason": "This event is outside the supported Codex lifecycle contract."
+      },
+      {
+        "event": "PreCompact",
+        "reason": "This event is outside the supported Codex lifecycle contract."
+      },
+      {
+        "event": "Notification",
+        "reason": "This event is outside the supported Codex lifecycle contract."
+      }
+    ]
+  },
+  "skillMetadata": [
+    {
+      "name": "agentera",
+      "description": "Compound agent orchestration suite \u2014 12 capabilities in one bundled skill; use for exact bare /agentera dashboard routing",
+      "path": "./skills/agentera",
+      "runtimeSupport": "portable",
+      "invocationHint": "$agentera; for a complete bare `/agentera`, use the agentera status dashboard path",
+      "policy": {
+        "allow_implicit_invocation": true
+      }
+    }
+  ]
+}

package/bundle/.cursor/agents/agentera.md

@@ -0,0 +1,7 @@
+---
+description: Turn your coding agent into an engineering team.
+---
+
+<!-- agentera: managed -->
+
+Load the Agentera skill for request routing and project orientation. When a capability is invoked, run `agentera prime --context build --format json` (or the relevant capability name) to fetch the authoritative instructions as a JSON capsule, then dispatch to a general-purpose subagent with the `prose` field as the task prompt. Do not invent unsupported capability-name CLI commands. Do not invoke per-capability subagents; the single Agentera agent handles all capability dispatch.

package/bundle/.cursor/hooks.json

@@ -0,0 +1,32 @@
+{
+  "version": 1,
+  "description": "agentera v3 Cursor IDE hooks (camelCase lifecycle events sessionStart, sessionEnd, preToolUse, postToolUse): session context export, artifact hard gate, and advisory validation",
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "npx -y agentera@next hook cursor-session-start",
+        "timeout": 15
+      }
+    ],
+    "sessionEnd": [
+      {
+        "command": "npx -y agentera@next hook session-stop",
+        "timeout": 15
+      }
+    ],
+    "preToolUse": [
+      {
+        "command": "npx -y agentera@next hook cursor-pre-tool-use",
+        "matcher": "Write|Edit",
+        "timeout": 15
+      }
+    ],
+    "postToolUse": [
+      {
+        "command": "npx -y agentera@next hook validate-artifact",
+        "matcher": "Write|Edit",
+        "timeout": 15
+      }
+    ]
+  }
+}

package/bundle/.cursor-plugin/plugin.json

@@ -0,0 +1,34 @@
+{
+  "name": "agentera",
+  "version": "3.0.0",
+  "description": "Agentera compound agent orchestration suite — twelve capabilities in one bundled skill; exact bare /agentera belongs to the bundled agentera dashboard path. Cloud agents are unsupported in v1.",
+  "author": {
+    "name": "Jonathan Gabor",
+    "url": "https://github.com/jgabor"
+  },
+  "homepage": "https://github.com/jgabor/agentera",
+  "repository": "https://github.com/jgabor/agentera",
+  "license": "Apache-2.0",
+  "keywords": ["agentera", "skills", "agents", "orchestration", "planning", "memory"],
+  "skills": "./skills/",
+  "hooks": "./.cursor/hooks.json",
+  "agents": "./.cursor/agents/",
+  "agentera": {
+    "packageShape": "suite-bundle",
+    "installRoot": "..",
+    "sharedPaths": ["skills", "hooks", "registry.json", "plugin.json", "README.md", "UPGRADE.md"],
+    "singleSkillInstall": "Single-skill installs keep core SKILL.md workflow behavior; suite tools are bundle-only enhancements."
+  },
+  "cursor": {
+    "limitations": [
+      "Cloud agents are unsupported in v1; use repo-native or upgraded project hooks and managed agents instead.",
+      "Bare /agentera routing is metadata-only; use the bundled agentera skill and status dashboard path explicitly.",
+      "Conditional hard-gate validation for reconstructable Write and Edit candidates is verified after live preToolUse Write smoke (2026-05-24); release tagging remains blocked pending broader release closeout."
+    ],
+    "distribution": {
+      "repoNativeHooks": ".cursor/hooks.json",
+      "managedAgents": ".cursor/agents/",
+      "marketplaceManifest": ".cursor-plugin/plugin.json"
+    }
+  }
+}

package/bundle/.github/hooks/postToolUse.json

@@ -0,0 +1,9 @@
+{
+  "description": "agentera v3 GitHub Copilot CLI hook (camelCase name field postToolUse): advisory artifact validation after Edit or Write",
+  "name": "postToolUse",
+  "matcher": "Edit|Write",
+  "type": "command",
+  "bash": "npx -y agentera@next hook validate-artifact",
+  "powershell": "npx -y agentera@next hook validate-artifact",
+  "timeoutSec": 10
+}

package/bundle/.github/hooks/preToolUse.json

@@ -0,0 +1,8 @@
+{
+  "description": "agentera v3 GitHub Copilot CLI hook (camelCase name field preToolUse): artifact hard gate before tool use",
+  "name": "preToolUse",
+  "type": "command",
+  "bash": "npx -y agentera@next hook validate-artifact",
+  "powershell": "npx -y agentera@next hook validate-artifact",
+  "timeoutSec": 10
+}

package/bundle/.github/hooks/sessionEnd.json

@@ -0,0 +1,8 @@
+{
+  "description": "agentera v3 GitHub Copilot CLI hook (camelCase name field sessionEnd): session bookmark persistence",
+  "name": "sessionEnd",
+  "type": "command",
+  "bash": "npx -y agentera@next hook session-stop",
+  "powershell": "npx -y agentera@next hook session-stop",
+  "timeoutSec": 10
+}

package/bundle/.github/hooks/sessionStart.json

@@ -0,0 +1,8 @@
+{
+  "description": "agentera v3 GitHub Copilot CLI hook (camelCase name field sessionStart): session context preload",
+  "name": "sessionStart",
+  "type": "command",
+  "bash": "npx -y agentera@next hook session-start",
+  "powershell": "npx -y agentera@next hook session-start",
+  "timeoutSec": 10
+}

package/bundle/.github/plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "agentera",
+  "version": "3.0.0",
+  "description": "Agentera 3.0.0 for GitHub Copilot CLI: one portable skill, twelve capabilities, shared project state, lifecycle hooks, and exact /agentera dashboard routing. profile uses bounded Copilot corpus metadata when present and reports missing source families. Runtime installation, enablement, authentication, and trust remain user-owned.",
+  "skills": "../../skills",
+  "hooks": "../hooks"
+}

package/bundle/.opencode/agents/agentera.md

@@ -0,0 +1,12 @@
+---
+color: "#fcd116"
+description: Turn your coding agent into an engineering team.
+mode: primary
+permission:
+  write: allow
+  bash: allow
+---
+
+<!-- agentera: managed -->
+
+Load the Agentera skill for request routing and project orientation. When a capability is invoked, run `agentera prime --context build --format json` (or the relevant capability name) to fetch the authoritative instructions as a JSON capsule, then dispatch to a general-purpose subagent with the `prose` field as the task prompt. Do not invent unsupported capability-name CLI commands. Do not invoke per-capability subagents; the single Agentera agent handles all capability dispatch.

package/bundle/.opencode/commands/agentera.md

@@ -0,0 +1,5 @@
+---
+description: "Compound agent orchestration suite: 12 capabilities in one bundled skill"
+agentera_managed: true
+---
+Load and execute the agentera bundled skill for this project.

package/bundle/.opencode/package.json

@@ -0,0 +1,31 @@
+{
+  "files": [
+    "plugins/agentera.js",
+    "commands",
+    "agents",
+    "package.json"
+  ],
+  "type": "module",
+  "main": "./plugins/agentera.js",
+  "exports": {
+    ".": "./plugins/agentera.js"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "1.14.33"
+  },
+  "agentera": {
+    "packageShape": "npm-loadable-plugin",
+    "opencodePlugin": "./plugins/agentera.js",
+    "localPluginPath": ".opencode/plugins/agentera.js",
+    "installRoot": "..",
+    "sharedPaths": [
+      "skills",
+      "hooks",
+      "registry.json",
+      "plugin.json",
+      "README.md",
+      "UPGRADE.md"
+    ],
+    "singleSkillInstall": "Single-skill installs keep core SKILL.md workflow behavior; suite tools are bundle-only enhancements."
+  }
+}