agentera 3.0.0-dev.25 → 3.0.0-dev.27

package/bundle/agents/openai.yaml

@@ -1,87 +0,0 @@
-display_name: Agentera
-description: "Portable Agentera suite for Codex: one bundled skill with exact bare `/agentera` routing and twelve routed capabilities."
-icon: AG
-brand_color: "#111827"
-default_prompt: Use $agentera to inspect project state and route to the right capability; exact bare `/agentera` uses the agentera prime dashboard path.
-policy:
-  allow_implicit_invocation: true
-support:
-  skill_discovery: /skills
-  plugin_discovery: /plugins
-  explicit_invocation: $agentera
-  implicit_invocation: the bundled skill may be invoked implicitly; exact bare `/agentera` belongs to agentera, not the legacy hej bridge
-  lifecycle_hooks: stable via codex_hooks; bundled config lives at hooks/codex-hooks.json and can be copied to ~/.codex/hooks.json or a project .codex/hooks.json for apply_patch artifact validation
-skills:
-  - name: agentera
-    display_name: agentera
-    path: ./skills/agentera
-    metadata: ./agents/openai.yaml
-    description: Compound agent orchestration suite with exact bare `/agentera` routing and twelve capabilities in one bundled skill.
-    invocation_hint: Use $agentera, or inspect it with /skills and /plugins. For a complete bare `/agentera` message, use the agentera prime dashboard path.
-    policy:
-      allow_implicit_invocation: true
-    capabilities:
-      - name: status
-        description: Entry-point orientation and routing for fresh or returning projects, including a complete user message exactly `/agentera`.
-        invocation_hint: Use $agentera status or ask $agentera for project status; exact bare `/agentera` uses this dashboard path.
-        policy:
-          allow_implicit_invocation: true
-      - name: research
-        description: External-source analysis mapped onto a project through Agentera artifacts.
-        invocation_hint: Use $agentera research for links or external source analysis.
-        policy:
-          allow_implicit_invocation: true
-      - name: profile
-        description: Decision-profile mining. Limited to available bounded Codex history, session, or config corpus data.
-        invocation_hint: Use $agentera profile when bounded Codex history, session, or config corpus data is available.
-        policy:
-          allow_implicit_invocation: false
-        required_capabilities:
-          - name: codex_session_corpus
-            status: ok
-            action: Run profile extraction; bounded Codex history, session, or config corpus data lands in the Section 22 corpus when present, with absent source families reported in corpus metadata.
-      - name: build
-        description: Autonomous development cycles grounded in project vision, TODO, and verification.
-        invocation_hint: Use $agentera build for autonomous development cycles.
-        policy:
-          allow_implicit_invocation: true
-      - name: optimize
-        description: Metric-driven optimization loops for measurable objectives.
-        invocation_hint: Use $agentera optimize for measured optimization work.
-        policy:
-          allow_implicit_invocation: true
-      - name: discuss
-        description: Structured deliberation for consequential decisions and tradeoffs.
-        invocation_hint: Use $agentera discuss for decision framing.
-        policy:
-          allow_implicit_invocation: true
-      - name: audit
-        description: Codebase health audits with severity, confidence, and trend tracking.
-        invocation_hint: Use $agentera audit for codebase health audits.
-        policy:
-          allow_implicit_invocation: true
-      - name: plan
-        description: Scale-adaptive planning with behavioral acceptance criteria.
-        invocation_hint: Use $agentera plan for multi-step planning.
-        policy:
-          allow_implicit_invocation: true
-      - name: vision
-        description: Project vision creation and refinement.
-        invocation_hint: Use $agentera vision for project direction work.
-        policy:
-          allow_implicit_invocation: true
-      - name: document
-        description: DTC-first documentation creation, maintenance, and audit.
-        invocation_hint: Use $agentera document for documentation work.
-        policy:
-          allow_implicit_invocation: true
-      - name: design
-        description: Visual identity system creation, refinement, and audit.
-        invocation_hint: Use $agentera design for design system work.
-        policy:
-          allow_implicit_invocation: true
-      - name: orchestrate
-        description: Plan-driven orchestration that dispatches capabilities and evaluates results.
-        invocation_hint: Use $agentera orchestrate for plan execution.
-        policy:
-          allow_implicit_invocation: true

package/bundle/hooks/codex-hooks.json

@@ -1,31 +0,0 @@
-{
-  "description": "agentera v3 Codex CLI hooks (PascalCase lifecycle events PreToolUse, PostToolUse): schema-backed apply_patch artifact validation; copied to ~/.codex/hooks/codex-hooks.json by upgrade",
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "^apply_patch$",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "npx -y agentera@next hook validate-artifact",
-            "timeout": 10,
-            "statusMessage": "validating artifact"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "^apply_patch$",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "npx -y agentera@next hook validate-artifact",
-            "timeout": 10,
-            "statusMessage": "validating artifact"
-          }
-        ]
-      }
-    ]
-  }
-}

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

@@ -1,31 +0,0 @@
-{
-  "description": "agentera v3 Codex plugin hooks (PascalCase lifecycle events PreToolUse, PostToolUse): schema-backed apply_patch artifact validation bundled via .codex-plugin/plugin.json using PLUGIN_ROOT",
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "^apply_patch$",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "npx -y agentera@next hook validate-artifact",
-            "timeout": 10,
-            "statusMessage": "validating artifact"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "^apply_patch$",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "npx -y agentera@next hook validate-artifact",
-            "timeout": 10,
-            "statusMessage": "validating artifact"
-          }
-        ]
-      }
-    ]
-  }
-}

package/bundle/plugin.json

@@ -1,13 +0,0 @@
-{
-  "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": ".github/hooks",
-  "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."
-  }
-}

package/bundle/references/adapters/cursor.md

@@ -1,224 +0,0 @@
-# Cursor adapter reference
-
-Agentera ships one active Cursor registry identity: `cursor`. The accepted
-`cursor-agent` spelling is an inactive compatibility alias that resolves to
-Cursor-owned behavior and source data; it is not independently discoverable.
-
-Cursor Agent CLI is the required lifecycle surface and Cursor IDE is
-conditional. Cloud agents are unsupported. Bare prompt routing remains
-metadata-only like GitHub Copilot and Codex.
-
-## Quick install
-
-**Local plugin (no Marketplace listing required)**
-
-```bash
-git clone https://github.com/jgabor/agentera.git ~/.cursor/plugins/local/agentera
-# or: ln -s /path/to/agentera ~/.cursor/plugins/local/agentera
-```
-
-Restart Cursor or run **Developer: Reload Window**. The plugin root must contain
-`.cursor-plugin/plugin.json`. Agentera is not published to the Cursor Marketplace
-yet; use this manual local path or Cursor's local plugin loading UI instead.
-
-The plugin loads skills, managed capability agents, and plugin hooks. When you open
-a project that is not an Agentera install root, `sessionStart` exports
-`AGENTERA_HOME` from the plugin checkout (including a plugin-root fallback when env
-and project walk-up do not resolve a managed root).
-
-**Portable skill plus project upgrade**
-
-```bash
-npx skills add jgabor/agentera -g -a cursor --skill agentera -y
-npx -y agentera@next upgrade --project "$PWD" --runtime cursor --dry-run
-npx -y agentera@next upgrade --project "$PWD" --runtime cursor --yes
-npx -y agentera@next doctor --format json
-```
-
-Use the plugin path for a user-global install. Use upgrade when you need
-project-committed `.cursor/hooks.json` and `.cursor/agents/` copies. Both paths can
-be combined.
-
-User-facing install steps also live in [`README.md`](../../README.md) and
-[`UPGRADE.md`](../../UPGRADE.md).
-
-## Repo-native surfaces
-
-This repository dogfoods committed Cursor surfaces:
-
-- `.cursor/hooks.json` — sessionStart env export, preToolUse hard gate, postToolUse advisory validation
-- `.cursor/agents/agentera.md` — single managed agent descriptor (D73)
-- `.cursor-plugin/plugin.json` — marketplace submission-ready manifest
-
-Install and repair these Cursor IDE resources through the public lifecycle command
-`agentera upgrade --runtime cursor`: use `--dry-run` to preview and `--yes` to
-apply Agentera-owned operations. The installed hook file calls private lifecycle
-callbacks packaged with the CLI; those callbacks are runtime wiring, not a
-user-facing command namespace, and are intentionally absent from public CLI help.
-The managed `sessionStart` callback exports `AGENTERA_HOME` through Cursor hook JSON
-(`env`) before subsequent callbacks run.
-
-## AGENTERA_HOME wiring
-
-Primary path: the managed Cursor IDE `sessionStart` callback resolves the install
-root from `AGENTERA_HOME`, project walk-up, the plugin/checkout root, or the
-platform default app home when env and walk-up do not resolve a managed root,
-then returns `{"env": {"AGENTERA_HOME": "<root>"}}` plus optional
-`additional_context` from the shared session digest.
-
-Fallback: `packages/cli/src/setup/cursor.ts` reports persistent shell configuration
-only when live shell-tool smoke proves session env does not propagate to CLI
-subprocesses. Agentera does not write shell rc files by default.
-
-## Artifact validation
-
-| Surface | Behavior | Claim status |
-| ------- | -------- | ------------ |
-| IDE `preToolUse` (Write/Edit) | Deny invalid reconstructable artifact candidates | Verified after live preToolUse Write smoke (2026-05-24) |
-| IDE `postToolUse` (Write/Edit) | Advisory validation through the managed artifact-validation callback | Active |
-| CLI | Degraded; depends on workspace hook install and env propagation | Follows IDE smoke evidence only |
-
-Live preToolUse Write smoke passed on 2026-05-24 with invalid-block and valid-allow
-cases recorded in `.agentera/smoke-cursor-pretooluse-evidence.txt`. Conditional
-hard-gate claims for reconstructable IDE Write and Edit candidates are verified;
-release tagging and marketplace publication remain blocked pending broader release
-closeout.
-
-## Subagent dispatch
-
-IDE: managed descriptors under `.cursor/agents/` with `<!-- agentera: managed -->`
-ownership markers. Upgrade refreshes Agentera-owned targets and preserves unknown
-collisions.
-
-CLI: host-managed `cursor-agent` print mode through the inactive Cursor alias;
-there is no separate descriptor install. Eval coverage may accept the alias but
-must report the canonical runtime identity as `cursor`.
-
-## Upgrade and doctor
-
-```bash
-npx -y agentera@next upgrade --project "$PWD" --runtime cursor --dry-run
-npx -y agentera@next upgrade --project "$PWD" --runtime cursor --yes
-npx -y agentera@next doctor --format json
-```
-
-Upgrade treats Cursor Agent CLI and Cursor IDE as surfaces of one `cursor` runtime.
-It manages the shared canonical skill used by both surfaces and, for the
-conditional IDE surface, project hooks, the Agentera descriptor, and plugin
-metadata. The shared lifecycle engine creates or repairs only Agentera-owned
-resources and preserves unowned collisions.
-
-Doctor reports all active runtimes in one read-only lifecycle snapshot, including
-Cursor CLI and IDE evidence; it does not accept a Cursor-only runtime filter.
-
-## Eval
-
-```bash
-agentera check verify eval skills --runtime cursor --skill agentera --dry-run
-```
-
-Print mode uses `cursor-agent -p --output-format json --force`. Harnesses apply
-bounded timeouts because some CLI builds hang after completion.
-
-## Current limitations
-
-- Cloud agents (no project hook or managed-agent guarantees)
-- Bare prompt rewrite routing
-- Session compaction injection beyond shared hook helpers
-- No separate Cursor Agent CLI hook install distinct from Cursor workspace surfaces
-
-## Profilera session corpus (Section 22)
-
-Profilera mines five canonical record types from host session data. This section
-maps each record type to Cursor IDE local storage on disk.
-
-### Probe paths
-
-| Path | Purpose |
-| ---- | ------- |
-| `~/.cursor/projects/` | Root directory for workspace-scoped Cursor state |
-| `~/.cursor/projects/<project-slug>/agent-transcripts/<session-id>/*.jsonl` | Agent session transcripts (Composer / Agent) |
-| `~/.cursor/projects/<project-slug>/repo.json` | Workspace metadata (`id` UUID); slug mapping is primary for project scoping |
-| `~/.config/cursor/chats/<md5(project-path)>/<session-id>/store.db` | Cursor Agent CLI chat store (gap-fill when JSONL absent) |
-
-Override the projects root with `--cursor-projects-dir`, the CLI chats root with
-`--cursor-chats-dir`, or disable both Cursor source stores with `--no-cursor` on
-`agentera report refresh`. The Python extractor wrapper is a maintainer-only parity
-surface, not the user-facing command.
-
-Project slug convention: absolute project path segments joined with `-`, lowercased
-(for example `/home/user/git/agentera` → `home-user-git-agentera`). CLI workspace
-hashes use `md5(absolute-project-path)` hex (same string Cursor uses under
-`~/.config/cursor/chats/`). When `--project-root` is supplied, extraction prefers
-matching slugs and workspace hashes over unrelated stores.
-
-### Transcript JSONL shape
-
-Each line is a JSON object:
-
-```json
-{"role": "user", "message": {"content": [{"type": "text", "text": "..."}]}}
-{"role": "assistant", "message": {"content": [{"type": "text", "text": "..."}, {"type": "tool_use", "name": "grep", "input": {"pattern": "..."}}]}}
-```
-
-Roles are `user` or `assistant`. `message.content` is a list of blocks. Text blocks
-use `type: "text"`. Tool blocks use `type: "tool_use"` with `name` and `input`.
-
-### Cursor source-product `store.db` shape
-
-The inactive `cursor-agent` input alias reads Cursor-owned SQLite stores at
-`~/.config/cursor/chats/<workspace-hash>/<session-id>/store.db`. Each store has:
-
-| Table | Purpose |
-| ----- | ------- |
-| `blobs` | JSON message payloads keyed by content hash (`role`, `content`, optional tool blocks) |
-| `meta` | Session metadata (`agentId`, model, mode) |
-
-JSON blobs use `role` values such as `user`, `assistant`, and `tool`. User content is
-often a plain string; assistant content is a list that may include `text` and
-`tool-call` items (`toolName`, `args`). Sessions that already have IDE JSONL under
-`agent-transcripts/<same-session-id>/` are skipped (gap-fill only).
-
-### Portable record families
-
-| Family | Cursor source | Status |
-| ------ | ------------- | ------ |
-| Decision history | `history_prompt` from decision-rich user text blocks | Yes (local JSONL) |
-| Conversation exchanges | `conversation_turn` from user/assistant lines | Yes (local JSONL) |
-| Tool usage | `tool_call` from `tool_use` / `tool-call` blocks | Yes (bounded args) |
-| Instruction documents | Project `AGENTS.md` via shared `--project-root` scan | Yes (filesystem) |
-| Project config signals | Project manifests via shared `--project-root` scan | Yes (filesystem) |
-
-### Degradation and privacy
-
-Extraction is read-only and local-only. Runtime status uses the shared
-`runtime_statuses` vocabulary (`ok`, `missing`, `sparse`, `degraded`, `skipped`).
-Diagnostics report counts and bounded reasons only; raw transcript text must not
-appear in errors, smoke output, or test assertions.
-
-| Condition | Status | Reason |
-| --------- | ------ | ------ |
-| Store path disabled (`--no-cursor`) | `skipped` | `disabled` |
-| `~/.cursor/projects` or `~/.config/cursor/chats` absent | `missing` | `store_absent` |
-| No `*.jsonl` under `agent-transcripts` / no gap-fill `store.db` | `sparse` | `no_candidate_files` / `no_matching_records` |
-| Permission denied | `degraded` | `store_locked` |
-| Invalid JSONL lines | `degraded` | `schema_divergent` |
-| Candidates present but no normalized records | `sparse` | `no_matching_records` |
-
-### Gaps
-
-- Numeric or opaque project directory names (no slug) skip filesystem project-path
-  inference; `--project-root` mapping still scopes extraction when the slug matches.
-- Cloud agent sessions do not write local `agent-transcripts` in v1.
-- `cursor-agent` `store.db` sessions that already have IDE JSONL transcripts are skipped
-  to avoid duplicate corpus records; gap-fill covers chat-only CLI sessions.
-- Binary or non-JSON blobs in `store.db` degrade with bounded diagnostics and do not
-  leak transcript text.
-
-## Source of truth
-
-Runtime identity and surfaces live in
-`references/adapters/runtime-lifecycle-authority.yaml`; eight-category behavior
-lives in `references/adapters/runtime-lifecycle-adapters.yaml`. Host-event facts
-remain in `references/adapters/runtime-adapter-registry.yaml`, and parity
-comparisons belong in `references/adapters/runtime-feature-parity.md`.