Merge remote-tracking branch 'origin/main' into HEAD

Author: haelyra

.agents/plugins/marketplace.json

@@ -6,10 +6,10 @@
   "plugins": [
     {
       "name": "ecc",
-      "version": "2.1.0",
+      "version": "2.2.0",
       "source": {
         "source": "local",
-        "path": "./plugins/ecc"
+        "path": "./"
       },
       "policy": {
         "installation": "AVAILABLE",

.agents/skills/plan-canvas/SKILL.md

@@ -46,12 +46,31 @@ Codex — or just run the `ecc-plan-canvas` commands directly.
 # 1. Open the artifact in the user's browser (returns immediately)
 ecc-plan-canvas open .claude/plans/feature.plan.md
 
-# 2. Block until the human responds. Leave running; re-run if interrupted —
-#    queued feedback is never lost. Run in the background if your harness
-#    time-limits foreground commands.
+# 2. Block until the human responds. Leave running; re-run if interrupted:
+#    queued feedback is never lost.
 ecc-plan-canvas await .claude/plans/feature.plan.md
 ```
 
+### Stay listening, or the human talks to an empty chair
+
+Feedback only reaches you while an `await` is actually parked on the session.
+If your turn ends with nothing listening, the message sits in the queue and,
+from the human's side of the glass, sending appears to do nothing at all.
+
+So **run `await` as a background task** when your harness supports one (in
+Claude Code, a Bash call with `run_in_background: true`). It exits the moment
+feedback arrives and the harness hands you the JSON, which keeps the loop alive
+across turns instead of dying with the foreground call. A foreground `await`
+works too, but only until the harness time-limits it.
+
+Two backstops exist, and neither is an excuse to skip the above:
+
+- `ecc-plan-canvas pending` lists feedback queued with no listener. Check it
+  whenever you are unsure whether you missed something.
+- The `stop:plan-canvas-pending` hook blocks your turn from ending while canvas
+  feedback is undelivered, and hands you the messages. If you are reading
+  feedback from that hook, you stopped listening too early.
+
 `await` prints JSON when the human acts:
 
 ```json
@@ -73,12 +92,31 @@ ecc-plan-canvas await .claude/plans/feature.plan.md
   end the session, and start implementing. `request-changes` means revise the
   artifact (the canvas live-reloads it) and keep the loop going.
 
-**3. Respond in the canvas**, then keep listening — one command does both:
+**3. Always respond in the canvas**, then keep listening. One command does both:
 
 ```bash
-ecc-plan-canvas await <file> --reply "Split Phase 2 as requested — take a look."
+ecc-plan-canvas await <file> --reply "Split Phase 2 as requested. Take a look."
 ```
 
+Every human message gets a reply in the canvas, even a one-liner like
+"On it, rewriting the risk table now." Silence in the chat panel is
+indistinguishable from a broken canvas, which is exactly the failure this loop
+exists to prevent. Answer there, not only in the terminal.
+
+While you work, keep the chat honest with the activity indicator:
+
+```bash
+# animated "agent is thinking..." bubble; refresh it during long work
+ecc-plan-canvas typing <file> --state thinking
+# switch to "agent is typing..." just before a reply lands
+ecc-plan-canvas typing <file> --state typing
+```
+
+`await` sets `thinking` for you the moment it hands you a batch, and `--reply`
+clears it. Both states self-expire, so a crashed agent decays to an honest
+"queued" instead of leaving the human watching dots forever. Refresh `thinking`
+if a revision takes more than a minute.
+
 **4. End** when review concludes: `ecc-plan-canvas end <file>`.
 
 ## Diagrams (Mermaid)
@@ -143,8 +181,13 @@ ecc-plan-canvas await <file> --reply "Reworked the risk table."
 
 ## Anti-Patterns
 
-- Polling with `--timeout-ms` in a loop — it exists for tests. Leave the
-  plain `await` running instead.
+- Polling with `--timeout-ms` in a loop. It exists for tests. Leave the plain
+  `await` running instead.
+- Ending your turn with no `await` listening while the review is still open.
+  That is the one failure the human experiences as "I sent a message and
+  nothing happened".
+- Reading the feedback but answering only in the terminal. The human is looking
+  at the canvas.
 - Reopening after a user-initiated end "just to show" something.
 - Pasting the whole plan into chat *and* opening a canvas — pick the canvas
   and keep the terminal summary to one line.

.claude-plugin/marketplace.json

@@ -11,8 +11,8 @@
     {
       "name": "ecc",
       "source": "./",
-      "description": "Harness-native ECC operator layer - 67 agents, 281 skills, 94 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready workflows for Claude Code, Codex, OpenCode, Cursor, and related agent harnesses",
-      "version": "2.1.0",
+      "description": "Harness-native ECC operator layer - 68 agents, 286 skills, 94 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready workflows for Claude Code, Codex, OpenCode, Cursor, and related agent harnesses",
+      "version": "2.2.0",
       "author": {
         "name": "Affaan Mustafa",
         "email": "me@affaanmustafa.com"

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ecc",
-  "version": "2.1.0",
-  "description": "Harness-native ECC plugin for engineering teams - 67 agents, 281 skills, 94 legacy command shims, reusable hooks, rules, MCP conventions, and operator workflows for Claude Code plus adjacent agent harnesses",
+  "version": "2.2.0",
+  "description": "Harness-native ECC plugin for engineering teams - 68 agents, 286 skills, 94 legacy command shims, reusable hooks, rules, MCP conventions, and operator workflows for Claude Code plus adjacent agent harnesses",
   "author": {
     "name": "Affaan Mustafa",
     "url": "https://x.com/affaanmustafa"
@@ -22,6 +22,20 @@
     "automation",
     "best-practices"
   ],
+  "userConfig": {
+    "hooks_enabled": {
+      "type": "boolean",
+      "title": "Enable ECC hooks",
+      "description": "Run ECC's local lifecycle, quality, and safety automation. Disable this to keep skills and commands without local hook automation.",
+      "default": true
+    },
+    "hook_profile": {
+      "type": "string",
+      "title": "ECC hook profile",
+      "description": "Choose minimal, standard, or strict. Invalid values safely fall back to standard.",
+      "default": "standard"
+    }
+  },
   "mcpServers": {},
   "skills": [
     "./skills/"

.codex-plugin/README.md

@@ -8,35 +8,83 @@ This directory contains the **Codex plugin manifest** for ECC.
 .codex-plugin/
 └── plugin.json   — Codex plugin manifest (name, version, skills ref, MCP ref)
 .mcp.json         — MCP server configurations at plugin root (NOT inside .codex-plugin/)
+hooks/codex-hooks.json — Codex-compatible lifecycle hook projection
 ```
 
 ## What This Provides
 
-- **249 skills** from `./skills/` — reusable Codex workflows for TDD, security,
+- **281 skills** from `./skills/` — reusable Codex workflows for TDD, security,
   code review, architecture, and more
-- **6 MCP servers** — GitHub, Context7, Exa, Memory, Playwright, Sequential Thinking
+- **1 default MCP server** — Chrome DevTools; retired connectors remain opt-in
+- **Codex lifecycle hooks** — synchronous command hooks on supported events,
+  with explicit review and trust in `/hooks`
 
 ## Installation
 
-Codex plugin support is marketplace-backed. The repo exposes a repo-scoped
-marketplace at `.agents/plugins/marketplace.json`; Codex can add and track that
-marketplace source from the CLI:
+Codex 0.146.0 and newer use `plugin add`, not `plugin install`. Add ECC's
+repository marketplace, install the native plugin, and verify the registration:
 
 ```bash
-# Add the public repo marketplace
 codex plugin marketplace add affaan-m/ECC
+codex plugin add ecc@ecc
+codex plugin list --json
+```
+
+Both add commands are safe to run again. A repeated marketplace add reports
+`alreadyAdded: true`, and a repeated plugin add keeps the same enabled plugin
+registration. To fetch a newer marketplace snapshot before applying a new ECC
+release, run:
+
+```bash
+codex plugin marketplace upgrade ecc
+codex plugin add ecc@ecc
+```
+
+For local development, the same native journey accepts a checkout path:
 
-# Or add a local checkout while developing
+```bash
 codex plugin marketplace add /absolute/path/to/ECC
+codex plugin add ecc@ecc
 ```
 
-The marketplace entry points at `plugins/ecc/` — Codex does not discover
-plugins whose local marketplace `source.path` is the marketplace root (`./`),
-so the entry must target a concrete plugin subdirectory (see
-[#2128](https://github.com/affaan-m/ECC/issues/2128)). That thin plugin folder
-references the root `skills/` and `.mcp.json` so content stays single-sourced.
-After adding or updating the marketplace, restart Codex and install or enable
-`ecc` from the plugin directory.
+ECC's marketplace entry points at the repository root. Codex copies the selected
+plugin source into its cache, so the root source keeps `skills/`, `.mcp.json`,
+`hooks/`, hook scripts, and presentation assets together. Parent-relative paths
+from a thin plugin directory would escape that cache and produce an installed
+registration with missing runtime content.
+
+Restart Codex after installation. You can also open `/plugins` in Codex CLI to
+inspect, enable, disable, or remove the plugin. The native Codex plugin does not
+use Claude's `user`, `project`, or `local` install scopes: its enabled state is
+stored once in the active `CODEX_HOME` (normally `~/.codex`) and applies to
+Codex sessions using that home.
+
+## Hooks and reconfiguration
+
+The Codex manifest uses the documented `hooks` field to bundle
+`./hooks/codex-hooks.json`. This provider-specific projection keeps the
+synchronous `SessionStart` bootstrap verified against Codex 0.146. Claude hook
+profiles are not Codex hook profiles: handlers that block tools, use unsupported
+events, run asynchronously, or fail Codex's hook protocol stay out of the native
+bundle. Codex enables hook support by default, but native plugin installation
+does not silently authorize commands. Start a new Codex session, open `/hooks`,
+then review and trust the ECC hook definition before enabling it.
+Codex records trust against each definition's hash, so changed hooks require
+review again. Use `/plugins` for plugin enablement and `/hooks` for hook trust;
+these are separate controls.
+
+Once the cached skills are available, invoke `$configure-ecc` inside Codex for
+ECC's guided configuration. Installing the plugin again is idempotent and does
+not create a second scope or duplicate hook registration.
+
+## Native plugin versus legacy managed sync
+
+The commands above are the native Codex plugin path. The legacy managed sync
+(`bash scripts/sync-ecc-to-codex.sh`) is a separate compatibility
+path that merges files into `~/.codex`. It is not a native plugin install and
+does not create a marketplace registration. Prefer the native path on current
+Codex; use the legacy managed sync only when you intentionally need its copied
+configuration layer.
 
 After install, `codex plugin list` is only a registration check. From an ECC
 checkout, run the cache check to verify that the installed manifest can resolve
@@ -46,22 +94,6 @@ its referenced skills, MCP config, and assets:
 node scripts/codex/check-plugin-cache.js
 ```
 
-> **Plugin mode is currently fragile on Codex.** Marketplace discovery and
-> install work with this layout, but runtime skill loading from local/repo
-> marketplaces is unreliable upstream
-> ([openai/codex#26037](https://github.com/openai/codex/issues/26037)) — Codex
-> copies only the plugin folder into its install cache, so parent-referenced
-> content may not be exposed in a fresh session. The safer, fully supported
-> path today is the manual sync flow:
-> `npm install && bash scripts/sync-ecc-to-codex.sh`.
-
-Official Plugin Directory publishing is coming soon. For official OpenAI
-plugin-directory review, package this repo under the `openai/plugins`
-repository shape: `plugins/ecc/.codex-plugin/plugin.json`,
-`plugins/ecc/skills/`, and the supporting README/assets. Until that listing is
-accepted, treat the public repo marketplace as the supported Codex distribution
-path and keep release copy framed as repo-marketplace/manual installation.
-
 The installed plugin registers under the short slug `ecc` so tool and command names
 stay below provider length limits.
 

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecc",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Harness-native ECC workflows for Codex: shared skills, production-ready MCP configs, and selective-install-aligned conventions for TDD, security scanning, code review, and autonomous development.",
   "author": {
     "name": "Affaan Mustafa",
@@ -13,9 +13,10 @@
   "keywords": ["codex", "agents", "skills", "tdd", "code-review", "security", "workflow", "automation"],
   "skills": "./skills/",
   "mcpServers": "./.mcp.json",
+  "hooks": "./hooks/codex-hooks.json",
   "interface": {
     "displayName": "ECC",
-    "shortDescription": "249 ECC skills plus MCP configs for TDD, security, code review, and autonomous development.",
+    "shortDescription": "281 ECC skills plus MCP configs for TDD, security, code review, and autonomous development.",
     "longDescription": "ECC is a harness-native operator system for Codex and adjacent agent harnesses. It packages reusable skills, MCP configs, TDD workflows, security scanning, code review, architecture decisions, operator workflows, and release gates in one installable plugin.",
     "developerName": "Affaan Mustafa",
     "category": "Coding",

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: ECC questions and setup help
+    url: https://github.com/affaan-m/ECC/discussions/categories/q-a
+    about: Ask a public question or get help from the community.
+  - name: Private security report
+    url: https://github.com/affaan-m/ECC/security/advisories/new
+    about: Report vulnerabilities privately. Do not put secrets in a public issue.

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,40 @@
+name: Feature idea
+description: Describe the outcome you need and your current workaround.
+title: "[Idea] "
+labels:
+  - enhancement
+  - needs-triage
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This is a public GitHub issue. Do not include secrets, prompts, customer data, private repository details, or unredacted paths.
+  - type: textarea
+    id: outcome
+    attributes:
+      label: What outcome do you need?
+      description: Describe the job to be done, not an implementation if you do not have one in mind.
+    validations:
+      required: true
+  - type: textarea
+    id: workaround
+    attributes:
+      label: What do you do today?
+      description: Optional. A workaround helps us understand urgency and scope.
+  - type: dropdown
+    id: harness
+    attributes:
+      label: Which harness is affected?
+      options:
+        - All harnesses
+        - Claude Code
+        - Codex
+        - Cursor
+        - OpenCode
+        - GitHub Copilot
+        - Another harness
+  - type: textarea
+    id: success
+    attributes:
+      label: What would success look like?
+      description: Optional acceptance criteria or a small example.