diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index e1a072da..c7aedcc4 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -149,7 +149,8 @@ "authentication": "ON_INSTALL" }, "category": "Development & Workflow", - "description": "223 production-ready skills, 23 agents, and 298 Python tools across 9 domains — engineering, marketing, product, compliance, and more." + "description": "223 production-ready skills, 23 agents, and 298 Python tools across 9 domains — engineering, marketing, product, compliance, and more.", + "icon": "./plugins/alirezarezvani/claude-skills/assets/icon.png" }, { "name": "claude-octopus", @@ -412,7 +413,8 @@ "authentication": "ON_INSTALL" }, "category": "Development & Workflow", - "description": "Three-phase Requirements → Design → Tasks workflow for Claude Code and Codex — EARS notation acceptance criteria, autonomous execution loop, cross-spec dependencies, and post-implementation acceptance testing." + "description": "Three-phase Requirements → Design → Tasks workflow for Claude Code and Codex — EARS notation acceptance criteria, autonomous execution loop, cross-spec dependencies, and post-implementation acceptance testing.", + "icon": "./plugins/Habib0x0/spec-driven-plugin/assets/spec-driven-icon.svg" }, { "name": "stark", diff --git a/README.md b/README.md index 4a3184a7..1f909740 100644 --- a/README.md +++ b/README.md @@ -205,6 +205,7 @@ Third-party plugins built by the community. [PRs welcome](#contributing)! - [Remotion Plugin](https://github.com/tim-osterhus/codex-remotion-plugin) - Build parameterized Remotion videos in Codex with the official Remotion docs MCP, composition scaffolding, and a data-driven launch-video workflow. - [ru-text](https://github.com/talkstream/ru-text) - Russian text quality — ~1,040 rules for typography, info-style, editorial, UX writing, and business correspondence. - [Rust Reverse Engineering](https://github.com/jingjing2222/rust-reverse-engineering-skill) - Reverse engineer Rust binaries and libraries: triage targets, demangle symbols, recover crate namespaces, and map panic, unwind, async, and FFI paths. +- [SeparateWeb Capture](https://github.com/AUN-PN/SeparateWeb) - Give Codex eyes on real webpages with full-page screenshots, UI crops, and JSON manifests for frontend visual QA. - [sitemd](https://github.com/sitemd-cc/sitemd) - Build websites from Markdown via MCP — 22 tools for creating pages, generating content, validating, running SEO audits, configuring settings, and deploying static sites to Cloudflare Pages. - [Synta MCP](https://github.com/Synta-ai/n8n-mcp-codex-plugin-synta) - Build, edit, validate, and self-heal n8n workflows with Synta MCP tools and Codex-ready workflow guidance. - [Task Scheduler](https://github.com/6Delta9/task-scheduler-codex-plugin) - OpenAI Codex plugin and local MCP server for turning task lists into realistic schedules with blocked dates, capacity overrides, overflow tracking, and markdown planning output. diff --git a/plugins.json b/plugins.json index 4c75463f..c72eeb82 100644 --- a/plugins.json +++ b/plugins.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "name": "awesome-codex-plugins", "version": "1.0.0", - "last_updated": "2026-05-18", + "last_updated": "2026-05-19", "total": 80, "categories": [ "Development & Workflow", diff --git a/plugins/CALLE-AI/call-e-integrations/README.md b/plugins/CALLE-AI/call-e-integrations/README.md index 1ee03ce0..ba957e77 100644 --- a/plugins/CALLE-AI/call-e-integrations/README.md +++ b/plugins/CALLE-AI/call-e-integrations/README.md @@ -45,12 +45,12 @@ Keep those paths exactly as shown so the marketplace entry can resolve ## Authentication The plugin uses the repository-local CLI when available, then a global `calle` -command when available, then falls back to `npx -y @call-e/cli@0.3.2`. +command when available, then falls back to `npx -y @call-e/cli@0.3.3`. To authenticate before using the plugin: ```bash -npx -y @call-e/cli@0.3.2 auth login +npx -y @call-e/cli@0.3.3 auth login ``` When `$calle` is invoked, the skill checks authorization first. If login is diff --git a/plugins/CALLE-AI/call-e-integrations/skills/calle/SKILL.md b/plugins/CALLE-AI/call-e-integrations/skills/calle/SKILL.md index 4c3b2428..6895e2a4 100644 --- a/plugins/CALLE-AI/call-e-integrations/skills/calle/SKILL.md +++ b/plugins/CALLE-AI/call-e-integrations/skills/calle/SKILL.md @@ -77,7 +77,7 @@ env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION= If neither command works, use the pinned npm package through `npx`: ```bash -env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.2 +env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.3 ``` Only tell the user to install the CLI globally if `npx` is unavailable, diff --git a/plugins/CALLE-AI/call-e-integrations/skills/calle/references/commands.md b/plugins/CALLE-AI/call-e-integrations/skills/calle/references/commands.md index c719d08b..897a4f86 100644 --- a/plugins/CALLE-AI/call-e-integrations/skills/calle/references/commands.md +++ b/plugins/CALLE-AI/call-e-integrations/skills/calle/references/commands.md @@ -17,7 +17,7 @@ env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION= npx fallback base command: ```bash -env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.2 +env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.3 ``` ## Setup and readiness @@ -37,10 +37,10 @@ env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION= ``` ```bash -env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.2 --help -env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.2 auth status -env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.2 auth login -env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.2 mcp tools +env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.3 --help +env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.3 auth status +env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.3 auth login +env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.3 mcp tools ``` Rules: @@ -103,7 +103,7 @@ I'll keep you updated on the phone status, call content, and summary. ```bash env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 node packages/cli/bin/calle.js call plan --to-phone +15551234567 --goal "Confirm the appointment" env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 calle call plan --to-phone +15551234567 --goal "Confirm the appointment" -env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.2 call plan --to-phone +15551234567 --goal "Confirm the appointment" +env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.3 call plan --to-phone +15551234567 --goal "Confirm the appointment" ``` Supported `call plan` options: @@ -131,7 +131,7 @@ env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION= ```bash env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 node packages/cli/bin/calle.js call run --plan-id --confirm-token env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 calle call run --plan-id --confirm-token -env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.2 call run --plan-id --confirm-token +env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.3 call run --plan-id --confirm-token ``` Supported `call run` options: @@ -155,7 +155,7 @@ returned or the user asks you to stop. ```bash env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 node packages/cli/bin/calle.js call status --run-id env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 calle call status --run-id -env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.2 call status --run-id +env CALLE_SOURCE=codex CALLE_INTEGRATION=codex_plugin CALLE_INTEGRATION_VERSION=0.1.9 npx -y @call-e/cli@0.3.3 call status --run-id ``` Supported `call status` options: diff --git a/plugins/Habib0x0/spec-driven-plugin/.codex-plugin/plugin.json b/plugins/Habib0x0/spec-driven-plugin/.codex-plugin/plugin.json index 417fbb59..99df1053 100644 --- a/plugins/Habib0x0/spec-driven-plugin/.codex-plugin/plugin.json +++ b/plugins/Habib0x0/spec-driven-plugin/.codex-plugin/plugin.json @@ -13,6 +13,7 @@ "skills": "./skills/", "interface": { "displayName": "Spec Driven", + "composerIcon": "./assets/spec-driven-icon.svg", "shortDescription": "Turn feature ideas into requirements, design docs, tasks, and execution loops.", "longDescription": "A structured spec-driven development workflow for Codex. It guides features through brainstorming, EARS requirements, technical design, task breakdown, validation, execution, and post-completion review.", "developerName": "habib0x", diff --git a/plugins/Habib0x0/spec-driven-plugin/assets/spec-driven-icon.svg b/plugins/Habib0x0/spec-driven-plugin/assets/spec-driven-icon.svg new file mode 100644 index 00000000..ba0762b8 --- /dev/null +++ b/plugins/Habib0x0/spec-driven-plugin/assets/spec-driven-icon.svg @@ -0,0 +1,14 @@ + + Spec Driven + A teal document icon with structured checklist lines and a connected workflow mark. + + + + + + + + + + + diff --git a/plugins/Kanevry/session-orchestrator/README.md b/plugins/Kanevry/session-orchestrator/README.md index 5520e9a7..882ec371 100644 --- a/plugins/Kanevry/session-orchestrator/README.md +++ b/plugins/Kanevry/session-orchestrator/README.md @@ -11,8 +11,8 @@ Turn ad-hoc Claude Code sessions into a repeatable loop with verification gates. ## What you get -- **36 skills** for the session lifecycle (start, plan, execute, close, evolve), discovery, vault sync, MCP authoring, debugging, brainstorming, and more -- **16 slash commands** (`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/autopilot`, `/test`, …) +- **37 skills** for the session lifecycle (start, plan, execute, close, evolve), discovery, vault sync, MCP authoring, debugging, brainstorming, and more +- **17 slash commands** (`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/autopilot`, `/test`, …) - **11 typed sub-agents** (code-implementer, test-writer, security-reviewer, session-reviewer, qa-strategist, architect-reviewer, …) - **11 hook event handlers** enforcing scope, blocking destructive commands, capturing telemetry - **5812 vitest tests** passing on every commit, validate-plugin 94/94, typecheck 187 files OK, lint 0 @@ -175,8 +175,8 @@ Full table and follow-ups in `CLAUDE.md` (or `AGENTS.md` on Codex CLI) and CHANG ```mermaid flowchart LR USER([Operator]) -->|invokes /session| COORD[Coordinator] - COORD -->|reads| SK[Skills
36 user-facing] - COORD -->|invokes| CMD[Commands
16 slash-cmds] + COORD -->|reads| SK[Skills
37 user-facing] + COORD -->|invokes| CMD[Commands
17 slash-cmds] COORD -->|dispatches| AG[Agents
11 typed sub-agents] AG -.->|parallel waves| W1[code-implementer] AG -.-> W2[test-writer] @@ -188,9 +188,9 @@ flowchart LR ## Components -**Skills (36 user-facing).** Lifecycle: `session-start`, `session-plan`, `wave-executor`, `session-end`, `quality-gates`, `using-orchestrator`. Authoring: `skill-creator`, `mcp-builder`, `hook-development`, `frontmatter-guard`. Planning & discovery: `plan`, `discovery`, `repo-audit`, `brainstorm`, `write-executable-plan`, `debug`, `claude-md-drift-check`. Architecture: `architecture`, `domain-model`, `ubiquitous-language`. Cross-session: `evolve`, `convergence-monitoring`, `memory-cleanup`. Vault & docs: `vault-sync`, `vault-mirror`, `daily`, `docs-orchestrator`. Ecosystem: `bootstrap`, `gitlab-ops`, `gitlab-portfolio`, `ecosystem-health`, `mode-selector`, `autopilot`. Testing: `test-runner`, `playwright-driver`, `peekaboo-driver`. +**Skills (37 user-facing).** Lifecycle: `session-start`, `session-plan`, `wave-executor`, `session-end`, `quality-gates`, `using-orchestrator`. Authoring: `skill-creator`, `mcp-builder`, `hook-development`, `frontmatter-guard`. Planning & discovery: `plan`, `discovery`, `repo-audit`, `brainstorm`, `write-executable-plan`, `debug`, `claude-md-drift-check`. Architecture: `architecture`, `domain-model`, `ubiquitous-language`. Cross-session: `evolve`, `convergence-monitoring`, `memory-cleanup`. Vault & docs: `vault-sync`, `vault-mirror`, `daily`, `docs-orchestrator`. Ecosystem: `bootstrap`, `gitlab-ops`, `gitlab-portfolio`, `ecosystem-health`, `mode-selector`, `autopilot`. Testing: `test-runner`, `playwright-driver`, `peekaboo-driver`. Content review: `persona-panel`. -**Commands (16).** `/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, `/harness-audit`, `/autopilot`, `/autopilot-multi`, `/repo-audit`, `/test`, `/memory-cleanup`, `/portfolio`, `/brainstorm`, `/debug`. +**Commands (17).** `/session`, `/go`, `/close`, `/discovery`, `/plan`, `/evolve`, `/bootstrap`, `/harness-audit`, `/autopilot`, `/autopilot-multi`, `/repo-audit`, `/test`, `/memory-cleanup`, `/portfolio`, `/brainstorm`, `/debug`, `/persona-panel`. **Agents (11).** `code-implementer`, `test-writer`, `ui-developer`, `db-specialist`, `security-reviewer`, `session-reviewer`, `docs-writer`, `architect-reviewer`, `qa-strategist`, `analyst`, `ux-evaluator`. @@ -202,7 +202,11 @@ flowchart LR **Codex.** `.codex-plugin/plugin.json` (manifest), compatibility config, 3 agent role definitions, marketplace `composerIcon`. -**Scripts.** Deterministic CLI tools (parse-config, run-quality-gate, validate-wave-scope, validate-plugin, token-audit, autopilot, autopilot-multi) plus shared lib (`scripts/lib/*.mjs`) plus a vitest suite of 5632 tests. +**Scripts.** Deterministic CLI tools (parse-config, run-quality-gate, validate-wave-scope, validate-plugin, token-audit, autopilot, autopilot-multi) plus shared lib (`scripts/lib/*.mjs`) plus a vitest suite of 5900+ tests. + +### `/harness-audit` — Anthropic large-codebase rubric + +`scripts/harness-audit.mjs` runs **8 deterministic categories / 33 checks** (rubric `2026-06`) over a repo and emits `.orchestrator/metrics/audit.jsonl`. Category 8 ("Large-Codebase Readiness") operationalises Anthropic's [Claude Code large-codebase best-practices](https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start) checklist — layered `CLAUDE.md` (or `AGENTS.md` on Codex CLI), codebase-map presence, LSP/code-intelligence wiring, scoped test/lint commands, `permissions.deny`, and root-file structural leanness — as scored signals you can run on yourself and on consumer repos. The checks are intentionally orthogonal to repo-audit's baseline-compliance pass/fail (`skills/repo-audit/SKILL.md`); both surfaces ship. ## Comparison @@ -240,7 +244,7 @@ We see the two plugins as complementary rather than competing: session-orchestra | Feature | Claude Code | Codex CLI | Cursor IDE | |---------|------------|-----------|------------| | OS | macOS, Linux, **Windows (native)** | macOS, Linux, **Windows (native)** | macOS, Linux, **Windows (native)** | -| All 16 commands | Native slash commands | Native plugin commands | Rules-based (.mdc) | +| All 17 commands | Native slash commands | Native plugin commands | Rules-based (.mdc) | | Parallel agents | Agent tool | Multi-agent roles | Sequential only | | Session persistence | `.claude/STATE.md` | `.codex/STATE.md` | `.cursor/STATE.md` | | Shared knowledge | `.orchestrator/metrics/` | `.orchestrator/metrics/` | `.orchestrator/metrics/` | diff --git a/plugins/Kanevry/session-orchestrator/skills/persona-panel/SKILL.md b/plugins/Kanevry/session-orchestrator/skills/persona-panel/SKILL.md new file mode 100644 index 00000000..8bb2759a --- /dev/null +++ b/plugins/Kanevry/session-orchestrator/skills/persona-panel/SKILL.md @@ -0,0 +1,329 @@ +--- +name: persona-panel +user-invocable: true +tags: [review, personas, content, quality, multi-agent] +model: inherit +description: > + Use this skill when you need multi-persona parallel content review — domain experts, buyer + personas, compliance reviewers, or custom catalog entries reviewing a target file or output. + Dispatches N persona agents in parallel, consolidates verdicts via a configurable mode + (voting-quorum, hard-gate-threshold, or coordinator-summary), and writes a timestamped sidecar + to .orchestrator/persona-panel/. Invoked via /persona-panel . +--- + +# Persona Panel Skill + +## Overview + +Persona Panel runs any number of catalog-defined personas in parallel against a single target +(file, document, or output range). Each persona agent produces a structured verdict. The +coordinator consolidates the verdicts into a final result using one of three configurable modes +and persists a sidecar record for audit and trend-tracking. + +The catalog lives in `.claude/personas/*.md` — per-repo, never plugin-central. This is +intentional: climate-research repos need physicists; SaaS repos need buyer personas; +compliance repos need auditors. Plugin-central catalogs block that diversity. + +## Phase 0: Bootstrap Gate + +Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is CLOSED, +invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate is +OPEN, continue to Phase 1. + + +Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to +`skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints. + + +## Phase 1: Catalog Discovery + +Load the per-repo persona catalog via `loadCatalog()` from +`scripts/lib/persona-panel/catalog-loader.mjs`. + +**Failure modes — all are hard stops:** + +**(a) `.claude/personas/` directory missing:** +``` +Error (exit 2): .claude/personas/ directory not found in this repo. +Create persona files there to use /persona-panel. +See templates/personas/ for starter templates (issue #458). +``` + +**(b) `.claude/personas/` present but empty (no `.md` files):** +``` +Error (exit 2): .claude/personas/ exists but contains no persona files (*.md). +Add at least one persona file to use /persona-panel. +See templates/personas/ for starter templates (issue #458). +``` + +**(c) `--personas ` arg specified but `name` not found in catalog:** +``` +Error (exit 1): Persona "" not found in .claude/personas/. +Available personas: . +``` + +**(d) Malformed YAML frontmatter in a catalog file:** +``` +Error (exit 1): Malformed YAML in .claude/personas/.md at line : . +Fix the frontmatter before running /persona-panel. +``` + +**Model validation (H2 security guard):** The catalog loader validates each persona's `model:` +field against `MODEL_ID_RE` + `ALLOWED_MODEL_ALIASES` from `scripts/lib/agent-frontmatter.mjs` +at load time. A persona with an invalid model string triggers failure mode (d) with an +informative message: "invalid model '' — must be a Claude model ID or alias +(inherit|sonnet|opus|haiku)". + +**`output_contract` structural pre-check (H3 security guard):** After YAML parse and before +AJV compile, the loader inspects each persona's `output_contract` object for forbidden keys: +`$ref`, `$defs`, `allOf`, `anyOf`. Any occurrence triggers failure mode (d). This structural +pre-check runs BEFORE `ajv.compile()`. The AJV compile call wraps in a 2-second AbortSignal +timeout to guard against pathological schema inputs. + +After successful load, emit a one-line status banner: +``` +Catalog: [N] personas loaded from .claude/personas/. Tier breakdown: domain-expert [N], buyer-persona [N], compliance [N], custom [N]. +``` + +If `--personas ` was passed, filter to the named subset. Report the active set. + +## Phase 2: Target-Input-Resolution + +Resolve the `` argument against the project root. + +1. Expand to absolute path (relative inputs are resolved from `git rev-parse --show-toplevel`). +2. Call `validatePathInsideProject(absolutePath, projectRoot)` from + `scripts/lib/path-utils.mjs`. This function performs a two-phase lexical + realpath guard. + - If the path resolves outside the project root: exit 1 with message + "Target path escapes project root — /persona-panel only reviews files inside the repo." +3. Confirm the file exists and is readable. If not: exit 1 with "Target file not found: ". +4. If a range was specified (`--lines -`), validate that start ≤ end and both are + positive integers. + +Store the resolved absolute path as `$TARGET`. + +## Phase 3: Parallel Dispatch + +Dispatch one Agent per persona from the active catalog set. + +**Model selection per persona:** +- If `persona.model` is a full Claude model ID (`MODEL_ID_RE`): use it as-is. +- If `persona.model` is `opus` or unset AND `persona.tier == 'domain-expert'`: override to + `claude-opus-4-7` (empirically validated — Opus finds real problems Sonnet misses; see vault + learning `[[persona-opus-finds-real-failing-cibadge]]`). +- Otherwise: use the persona's declared model alias. + +**Agent dispatch contract:** +``` +Agent({ + subagent_type: "general-purpose", + model: , + prompt: , + tools: ["Read", "Grep", "Glob"] +}) +``` + +Use `buildPersonaPrompt(persona, target)` from `scripts/lib/persona-panel/persona-runner.mjs` +to compose the prompt. The runner wraps `evaluation_criteria` entries in +`...` delimiters (security M1: persona body is treated as +data, not free-form instructions; see `persona-format.md` for the full rationale). + +**Concurrency cap (security M2):** Maximum 20 personas per panel run. If the active set exceeds +20, emit a warning and truncate to the first 20 alphabetically: +``` +Warning: Persona set truncated to 20 (cap). Omitted: . +``` + +**run_in_background:** `false` for all agents. Do not proceed to Phase 4 until ALL agents +complete. + +**Dispatch summary line (before dispatch):** +``` +Dispatching [N] persona agents in parallel. Target: <$TARGET>. Mode: . +``` + +## Phase 4: Konsolidierung (Consolidation) + +After all agents complete, run consolidation via `scripts/lib/persona-panel/consolidator.mjs`. + +**Three consolidation modes** (set by `--mode` arg, default: `voting-quorum`): + +### `voting-quorum` (default) + +Deterministic M-of-N threshold. Default M = ceil(N / 2) + 1 (simple majority). Override with +`--quorum `. + +- Count personas whose `verdict == "pass"`. +- If pass-count >= M: final-verdict = `"pass"`. +- If pass-count < M: final-verdict = `"fail"`. +- Tie: impossible when M > N/2. If M == ceil(N/2) exactly and count == M - 1: final-verdict = + `"fail"` (ties go to FAIL). + +### `hard-gate-threshold` + +Strict M-of-N where default M == N (unanimity). Override with `--threshold `. + +- If ALL N personas pass: final-verdict = `"pass"`. +- If any persona returns `"fail"`: final-verdict = `"fail"`. +- If any persona returns `"warn"` and no failures: final-verdict = `"warn"`. +- Tie-break: ties go to FAIL. + +### `coordinator-summary` + +LLM aggregate via coordinator. The coordinator reads all persona outputs and produces a +synthesized summary verdict. + +**WARN (required — emit to BOTH stderr AND sidecar `consolidation.aggregator_warning`):** +``` +Warning: coordinator-summary mode triggers an additional LLM call (the coordinator aggregation +step). This incurs extra token cost. Use voting-quorum or hard-gate-threshold for deterministic, +zero-extra-LLM-call consolidation. +``` + +For each persona output, parse the structured block (see `persona-format.md` Output Contract). +Validate that `verdict ∈ {"pass", "fail", "warn"}` — if a persona output lacks a valid verdict, +treat it as `"fail"` and record it in `dissenting_personas` with reason `"missing-verdict"`. + +Emit a consolidation summary: +``` +Consolidation ([mode]): [pass-count] pass / [fail-count] fail / [warn-count] warn — Final: +Dissenting: (if any) +``` + +## Phase 5: Sidecar-Persist + Report + +Write the sidecar record and emit the final report. + +### Sidecar Persistence + +**Run ID generation (H1 security guard):** +```js +const runId = randomUUID().slice(0, 8); // format: [a-z0-9-]{8} +``` +Validate: `runId` MUST match `/^[a-z0-9-]{1,64}$/`. Reject and regenerate if it does not. + +**Timestamp format for filename:** `^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(\.\d+)?Z?$` +(filename-safe ISO — colons replaced with hyphens). + +Example: `2026-05-20T14-30-00Z-a1b2c3d4.json` + +**Path:** `.orchestrator/persona-panel/-.json` + +Validate the sidecar target path with `validatePathInsideProject(sidecarAbsPath, projectRoot)` +(H1 path guard) before writing. + +**Schema validation (security M3 — validate BEFORE write):** +Validate the sidecar object against `agents/schemas/persona-panel-sidecar.schema.json` using +`validateAgentOutput()` from `scripts/lib/agent-output-schema.mjs` (AJV 2020-12). If +validation fails: print the AJV errors to stderr and exit 1 — never write an invalid sidecar. + +**Write via `writeJsonAtomic()` from `scripts/lib/io.mjs`** (atomic tmp-then-rename to prevent +partial writes). + +**Sidecar schema shape** (matched by `agents/schemas/persona-panel-sidecar.schema.json`): + +```json +{ + "run_id": "", + "target": "", + "personas_invoked": [ + { + "name": "", + "version": "", + "model": "", + "prompt_hash": "", + "timestamp_start": "", + "timestamp_end": "", + "token_usage": { + "input": "", + "output": "", + "cache_read": "", + "cache_creation": "" + } + } + ], + "outputs": [ + { + "persona_name": "", + "verdict": "", + "rationale": "", + "recommendations": [""] + } + ], + "consolidation": { + "mode": "", + "final_verdict": "", + "pass_count": "", + "fail_count": "", + "warn_count": "", + "dissenting_personas": [""], + "audit_reason": "", + "aggregator_warning": "" + } +} +``` + +**Token-usage contract (H4):** Each `personas_invoked` entry records `token_usage` from the +Anthropic API response: `{ input, output, cache_read, cache_creation }`. Agents that do not +return usage data record all fields as `0`. + +### Final Report + +Emit to stdout: + +``` +## Persona Panel Report + +Target: <$TARGET> +Personas: invoked | Mode: +Final verdict: + +| Persona | Tier | Verdict | Rationale (excerpt) | +|---------|------|---------|---------------------| +| | ... | pass | ... | +| | ... | fail | ... | + +Dissenting: +Sidecar: .orchestrator/persona-panel/.json +``` + +If `final_verdict == "fail"`: exit with code 1 so CI and wave-executor hooks can gate on the +result. If `final_verdict == "warn"`: exit 0 with a warning line on stderr. If +`final_verdict == "pass"`: exit 0. + +## Critical Rules + +- **NEVER** dispatch more than 20 personas per panel (security M2 cap). +- **NEVER** write a sidecar that fails schema validation — validate BEFORE write (security M3). +- **NEVER** skip `validatePathInsideProject` for the target path OR the sidecar output path (H1). +- **NEVER** use `run_in_background: true` for persona agents — lose coordination ability. +- **ALWAYS** validate `model:` fields from the catalog against `MODEL_ID_RE` + aliases (H2). +- **ALWAYS** run `output_contract` structural pre-check before `ajv.compile()` (H3). +- **ALWAYS** emit the `aggregator_warning` to BOTH stderr and sidecar when using + `coordinator-summary` mode. +- **ALWAYS** treat missing persona verdict as `"fail"` — never silently skip or default to pass. +- Ties in consolidation go to FAIL, not pass or warn. + +## Anti-Patterns + +- Running without a catalog — Phase 1 must gate on catalog existence. +- Using a single persona as a "quick check" — dispatch all catalog members unless `--personas` + restricts deliberately. The value is the N-dimensional view. +- Ignoring dissenting personas in `voting-quorum` — record them in the sidecar even when the + majority passes. They are the signal for trend-tracking (#459). +- Writing the sidecar before schema validation passes — invalid sidecars corrupt trend analysis. +- Calling `ajv.compile()` without the AbortSignal timeout — pathological schemas can block the + event loop indefinitely. + +## See Also + +- `commands/persona-panel.md` — argument parsing and CLI contract +- `agents/schemas/persona-panel-sidecar.schema.json` — sidecar JSON Schema (Draft 2020-12) +- `scripts/lib/persona-panel/catalog-loader.mjs` — loadCatalog() implementation +- `scripts/lib/persona-panel/persona-runner.mjs` — buildPersonaPrompt() implementation +- `scripts/lib/persona-panel/consolidator.mjs` — consolidation logic (3 modes) +- `skills/persona-panel/persona-format.md` — persona file format specification +- `skills/wave-executor/wave-loop.md` — Persona-Gate hook (Phase 5b/3b, added in #458) +- `scripts/lib/path-utils.mjs` — validatePathInsideProject() +- `scripts/lib/io.mjs` — writeJsonAtomic() +- `scripts/lib/agent-frontmatter.mjs` — MODEL_ID_RE, ALLOWED_MODEL_ALIASES diff --git a/plugins/Kanevry/session-orchestrator/skills/persona-panel/persona-format.md b/plugins/Kanevry/session-orchestrator/skills/persona-panel/persona-format.md new file mode 100644 index 00000000..3dbaada7 --- /dev/null +++ b/plugins/Kanevry/session-orchestrator/skills/persona-panel/persona-format.md @@ -0,0 +1,163 @@ +# Persona File Format + +> Specification for persona catalog files used by `skills/persona-panel/SKILL.md`. +> Catalog location: `.claude/personas/*.md` (per-repo, never plugin-central). + +## File Layout + +Each persona is a single Markdown file with YAML frontmatter followed by a structured body. +Files live at `.claude/personas/.md` where `` matches the frontmatter `name:` field. + +``` +.claude/personas/ + ai-expert.md + buyer-persona-early-adopter.md + compliance-reviewer.md +``` + +--- + +## YAML Frontmatter (Required Fields) + +All six fields below are REQUIRED. Files missing any field are rejected at catalog load time +(Phase 1 failure mode d). + +```yaml +--- +name: ai-expert +schema_version: 1 +version: 2 +role: "AI/ML domain expert — evaluates technical accuracy and implementation quality" +model: claude-opus-4-7 +tier: domain-expert +output_contract: + type: object + required: [verdict, rationale] + properties: + verdict: + type: string + enum: [pass, fail, warn] + rationale: + type: string + maxLength: 4096 + recommendations: + type: array + items: + type: string +evaluation_criteria: + - "Technical claims are accurate and grounded in current research" + - "Implementation suggestions are actionable and correctly scoped" + - "No hallucinated API names, library versions, or model capabilities" +--- +``` + +### Field Specifications + +| Field | Type | Constraint | +|-------|------|-----------| +| `name` | string | Matches filename stem. Pattern: `^[a-z0-9-]{1,64}$`. Unique in catalog. | +| `schema_version` | integer | Must be `1`. | +| `version` | integer | Persona content version. Increment on any output-affecting change. Used in sidecar + trend-tracking (#459). | +| `role` | string | Identity statement. Injected verbatim as prompt opener. Keep under 200 chars. | +| `model` | string | Full model ID (`MODEL_ID_RE`) or alias (`inherit|sonnet|opus|haiku`). Validated at load time. Recommend `claude-opus-4-7` for `domain-expert` and `compliance` tiers (Opus finds real issues Sonnet misses — vault learning `[[persona-opus-finds-real-failing-cibadge]]`). | +| `output_contract` | object | Inline JSON Schema Draft 2020-12. `$ref/$defs/allOf/anyOf` FORBIDDEN (H3). Must require `verdict` + `rationale`. AJV compile wrapped in 2s AbortSignal timeout. | +| `evaluation_criteria` | array | Non-empty. Each string max 512 chars. Injected wrapped in `` delimiters (M1). Write as statements, not questions. | +| `tier` | enum | `domain-expert` \| `buyer-persona` \| `auditor` \| `compliance` \| `reviewer` \| `custom`. Affects model selection (Phase 3). | + +--- + +## Markdown Body + +The body contains four sections, in order. All headings are required even when a section has no +content (write "None." for empty Context Files). + +**`## Mission`** — One to three sentences. The persona's identity and review goal. Injected as +the agent's opening system context: "You are [role]. [Mission]." + +**`## Context Files`** — Optional vault refs (`[[path/to/note]]`) or project paths that the +agent reads as supplementary background before evaluating the target. Vault refs are allowed. + +**`## Evaluation Criteria`** — Expanded prose descriptions of the frontmatter criteria. Each +criterion should specify: what to look for, what a pass looks like, what a fail looks like. + +**`## Output Template`** — The exact JSON block the persona agent must return. Must match the +`output_contract`. Minimum shape: + +```json +{ + "verdict": "pass|fail|warn", + "rationale": "Detailed rationale (max 4096 chars).", + "recommendations": [] +} +``` + +--- + +## Verdict Contract + +Every persona output MUST include `verdict ∈ {"pass", "fail", "warn"}`. This is the only +required output field. The `output_contract` in the frontmatter MUST declare it as required. + +| Verdict | Meaning | +|---------|---------| +| `pass` | Persona approves the target. No blocking issues found. | +| `fail` | Persona rejects the target. One or more blocking issues found. | +| `warn` | Persona has concerns but does not block. Attention warranted. | + +A persona output that lacks a valid `verdict` field is treated as `"fail"` by the consolidator +in all three consolidation modes. This is a deliberate safety default — missing verdicts +indicate a malformed or incomplete response. + +--- + +## Security Contract: Criteria Delimiters (Security M1) + +The `evaluation_criteria` entries are injected into the persona prompt wrapped in +`...` XML delimiters: + +``` + +Technical claims are accurate and grounded in current research +Implementation suggestions are actionable and correctly scoped +No hallucinated API names, library versions, or model capabilities + +``` + +**Rationale:** The persona body is "data, not instructions." Humans authoring personas should +be aware that the body content is interpolated into a prompt that is then sent to an LLM agent. +Without delimiters, a malicious or careless persona body could inject instructions into the +agent's context. The delimiters create a clear boundary between orchestrator-controlled prompt +structure and human-authored persona content. The `buildPersonaPrompt()` function in +`scripts/lib/persona-panel/persona-runner.mjs` enforces this wrapping — it cannot be bypassed +by persona file content. + +--- + +## Prompt Hash and Determinism Contract + +To support trend-tracking (#459) and audit trails, each sidecar entry records a `prompt_hash` +— a sha256 over the canonicalized persona inputs. This allows detecting when a change in +persona content or model causes output drift across runs. + +**Canonicalization algorithm** (must be reproduced identically by `persona-runner.mjs`): + +1. Take the persona's YAML frontmatter as a JavaScript object (already parsed). +2. Sort all top-level keys alphabetically. +3. Serialize to JSON: `JSON.stringify(sortedFrontmatter)`. +4. Normalize the Markdown body: replace all `\r\n` with `\n` (LF normalization). +5. Concatenate: `jsonString + "\n" + normalizedBody + "\n" + persona.model`. +6. Compute sha256 hex digest of the UTF-8 encoded concatenated string. + +The hash changes when ANY of these change: frontmatter field values (including `version`), +Markdown body content, or the `model` field. This means a version bump without body changes +WILL change the hash, which is correct — version bumps signal intentional persona evolution. + +--- + +## See Also + +- `skills/persona-panel/SKILL.md` — full 6-phase execution flow +- `scripts/lib/persona-panel/catalog-loader.mjs` — loadCatalog() and validation logic +- `scripts/lib/persona-panel/persona-runner.mjs` — buildPersonaPrompt() and prompt hash +- `agents/schemas/persona-panel-sidecar.schema.json` — sidecar JSON Schema +- `scripts/lib/agent-frontmatter.mjs` — MODEL_ID_RE, ALLOWED_MODEL_ALIASES diff --git a/plugins/Kanevry/session-orchestrator/skills/wave-executor/wave-loop.md b/plugins/Kanevry/session-orchestrator/skills/wave-executor/wave-loop.md index 9443ff36..5373418f 100644 --- a/plugins/Kanevry/session-orchestrator/skills/wave-executor/wave-loop.md +++ b/plugins/Kanevry/session-orchestrator/skills/wave-executor/wave-loop.md @@ -361,8 +361,13 @@ After ALL agents in the wave complete: - **`mode: 'validated', ok: false`** — schema violation. Annotate the agent record with `schema_violation: true` and `schema_errors: [...]`. Then: - Under `enforce: warn` (default): log the violation in the wave progress update and continue. The wave is NOT blocked. - Under `enforce: strict`: surface the violation as a wave-blocking finding. Halt further agent processing and report to the coordinator before proceeding to the conflict check. - - Under `enforce: off`: skip violation recording entirely (schema_status is still set when ok=true). - - **`mode: 'parse-error'`** — the agent's output had no fenced ```json block or malformed JSON. Log a warning (backward-compat — agents that predate the schema contract routinely omit a JSON block). Do NOT block the wave. + - Under `enforce: off`: record the violation in `subagents.jsonl` for diagnostics (`schema_violation: true`, `schema_errors: [...]` are set on the agent record) but do NOT emit a log line in the wave progress update and do NOT block the wave. This is identical to `warn` minus the in-wave noise — forensic data is preserved; operator output is silenced. + - **`mode: 'parse-error'`** — two distinct diagnostic sub-cases collapsed into one mode for backward-compat; either: + - **parse-error (no-block)**: agent output contains no fenced ```json block at all. Common backward-compat case for agents that predate the schema contract. + - **parse-error (bad-json)**: a fenced ```json block exists but the block fails `JSON.parse`. Indicates an agent-side serialisation bug — more interesting than no-block from a diagnostic standpoint, and the operator may want to follow up. + + Both sub-cases share the same recovery: log a warning in the wave progress update, set `schema_status: 'parse-error'` on the agent record in `subagents.jsonl`, and do NOT block the wave (#474 LOW-8 distinguishes the two so future tooling can route diagnostics differently per sub-case). + - **`mode: 'schema-error'`** — the fenced ```json block parses cleanly but the parsed object fails AJV validation against the agent's declared `output-schema:`. This is a stronger signal than `parse-error`: the agent emitted JSON, but the shape diverged from its declared contract. Treat the same way as `validated, ok: false` under the configured `enforce` level (`warn` / `strict` / `off`) so the violation is recorded with `schema_violation: true` and `schema_errors: [...]`. Note: the legacy `validateAgentOutput()` returns `'validated', ok: false` for this case today — `schema-error` is the spec-level name (per #474 LOW-8) for the same condition, kept distinct from `parse-error` so the diagnostic log can route differently. - **`mode: 'unvalidated'`** — the agent has no declared `output-schema:` frontmatter. Silent skip (backward-compat path; as of #449 all 11 plugin agents are enrolled, but third-party agents installed via marketplace plugins may not be). Reference: agent contract at `agents/code-implementer.md`; runtime module at `scripts/lib/agent-output-schema.mjs::validateAgentOutput`. @@ -584,6 +589,82 @@ After each wave completes and before the progress update, update `/ST - [] Wave N: ``` +### 3b. Persona-Gate Hook (#458) + +> Opt-in mid-wave hook that fans out a `/persona-panel`-style review after a configured wave completes. Distinct from `### 5a. Persona-reviewer dispatch` (which uses the `wave-reviewers` Session Config key and dispatches code-oriented `architect-reviewer` / `qa-strategist` / `analyst` agents). This hook uses the `persona-gate-wave` Session Config key and dispatches catalog personas (domain-experts, buyer-personas, auditors) from `.claude/personas/`. The two keys are independent and may both be configured on the same project. + +**Gate conditions** — ALL must be true for the hook to fire: + +1. `persona-gate-wave.enabled: true` in Session Config (default: `false`). +2. The just-completed wave matches `persona-gate-wave.after` — one of `'quality'` or `'impl-polish'`. The hook runs AFTER step 3a (STATE.md updated) and BEFORE step 4 (progress update), so the dispatch context already reflects the completed wave's results. +3. `persona-gate-wave.mode !== 'off'` (when `mode: 'off'` the hook is a silent no-op even when `enabled: true`). + +When any gate condition is false, skip this step entirely — proceed to `### 4. Progress Update`. + +**Dispatch sequence:** + +```js +import { loadCatalog } from '$PLUGIN_ROOT/scripts/lib/persona-panel/catalog-loader.mjs'; +import { buildPersonaPrompt, validatePersonaOutput } from '$PLUGIN_ROOT/scripts/lib/persona-panel/persona-runner.mjs'; +import { consolidate } from '$PLUGIN_ROOT/scripts/lib/persona-panel/consolidator.mjs'; +import { parseThreshold } from '$PLUGIN_ROOT/scripts/lib/persona-panel/threshold.mjs'; +import { writeJsonAtomic } from '$PLUGIN_ROOT/scripts/lib/io.mjs'; +import { appendDeviation } from '$PLUGIN_ROOT/scripts/lib/state-md.mjs'; + +const cfg = $CONFIG['persona-gate-wave']; // already normalised by parseSessionConfig +const catalog = await loadCatalog(); // throws if .claude/personas/ missing or invalid +const rosterNames = cfg.personas.length > 0 + ? cfg.personas + : [...catalog.keys()]; // empty list → all catalog personas +const personas = rosterNames.map((n) => catalog.get(n)).filter(Boolean); +``` + +Dispatch each persona in parallel via the Agent tool, using `cfg['dispatch-model']` as the model and `Read, Grep, Glob` tools only (panel personas are read-only by contract). Each dispatch wraps the wave's scope summary + changed-files list in `buildPersonaPrompt(persona.persona, target, targetContent)`. + +After all agents return, collect their outputs and validate each via `validatePersonaOutput(persona.persona, agentText)`. Compose the panel verdict via `consolidate(outputs, 'hard-gate-threshold', { threshold: parseThreshold(cfg.threshold) })`. + +**Behaviour by mode:** + +| `mode` | Action on consolidator result | +|--------|--------------------------------| +| `off` | No dispatch (gate condition above). | +| `warn` | Log findings to the wave progress update under a `Persona-gate:` bullet. Continue to step 4 regardless of `final_verdict`. | +| `strict` | If `final_verdict === 'PROCEED'`: log to progress, continue. Otherwise pause and surface an `AskUserQuestion` with three options:
1. **proceed-as-is** — log Deviation, continue (Recommended only after operator inspects sidecar)
2. **revise-remaining-waves** — return `{ verdict: 'FIX_REQUIRED', revision_context: { dissenting_personas, recommendations } }` to the wave-executor caller
3. **abort-session** — return `{ verdict: 'BLOCKED' }` to the caller | + +**Sidecar write:** before reporting any verdict, validate the panel result against `agents/schemas/persona-panel-sidecar.schema.json` (via `validateAgentOutput` or a direct AJV compile) and then write atomically via `writeJsonAtomic(path, value, { schemaPath })`: + +``` +.orchestrator/persona-panel/-.json +``` + +The sidecar carries `personas_invoked`, per-persona `outputs`, and the full `consolidation` block — operators consult it from the AskUserQuestion prompt before deciding `strict`-mode follow-up. + +**STATE.md deviation contract:** on `warn` (with at least one dissenting persona) or any `strict`-mode non-PROCEED verdict, append one timestamped entry to `## Deviations` via `appendDeviation(stateContents, iso, message)`: + +``` +- [] Wave N persona-gate : dissenting=[, ], threshold=, mode=. Sidecar: . +``` + +On a clean `PROCEED` no deviation is written — the sidecar alone is sufficient evidence. + +**Wave metrics extension:** when persistence is enabled, extend the wave metrics record (step 7 of `### 2. Review Agent Outputs`) with a `persona_gate` block: + +```json +"persona_gate": { + "triggered": true, + "threshold": "", + "personas_pass": , + "personas_fail": , + "mode_used": "", + "final_verdict": "", + "sidecar_path": ".orchestrator/persona-panel/<...>.json" +} +``` + +When the hook is skipped (gate condition false), omit the `persona_gate` field entirely — never write `triggered: false` for skipped runs, so a downstream consumer can distinguish "hook did not fire" from "hook fired but found no dissent". + +**Motivating example:** the `gotzendorfer-v2` W5 Buyer-Panel pattern (six buyer personas at `hard-gate-threshold` `6-of-6`, `mode: 'strict'`, `after: 'quality'`) — UI work is gate-checked against every persona before commit, abort on any dissent. See `docs/session-config-reference.md § Persona-Gate Wave (#458)` and `commands/persona-panel.md` for the standalone CLI equivalent. + ### 4. Progress Update After each wave, provide a brief status: diff --git a/plugins/alirezarezvani/claude-skills/.codex-plugin/plugin.json b/plugins/alirezarezvani/claude-skills/.codex-plugin/plugin.json index 3a260d4f..c6c54abd 100644 --- a/plugins/alirezarezvani/claude-skills/.codex-plugin/plugin.json +++ b/plugins/alirezarezvani/claude-skills/.codex-plugin/plugin.json @@ -25,6 +25,7 @@ "skills": "./.codex/skills/", "interface": { "type": "cli", + "composerIcon": "./assets/icon.png", "displayName": "Claude Code Skills", "shortDescription": "223 production-ready skills for AI coding agents across 9 domains", "longDescription": "The largest open-source skills library for AI coding agents. 223 skills covering engineering (architecture, DevOps, security, AI/ML), marketing (SEO, CRO, content), product management, C-level advisory, regulatory compliance (ISO 13485, SOC 2, GDPR), project management, business growth, and finance. Includes 298 stdlib-only Python CLI tools, 416 reference guides, 23 orchestration agents, and 22 slash commands. Works with Codex, Claude Code, Gemini CLI, Cursor, Aider, Windsurf, and 5 more tools.", diff --git a/plugins/alirezarezvani/claude-skills/assets/icon.png b/plugins/alirezarezvani/claude-skills/assets/icon.png new file mode 100644 index 00000000..f5129181 Binary files /dev/null and b/plugins/alirezarezvani/claude-skills/assets/icon.png differ diff --git a/plugins/boshu2/agentops/skills-codex/.agentops-manifest.json b/plugins/boshu2/agentops/skills-codex/.agentops-manifest.json index b17bf78f..86796bb1 100644 --- a/plugins/boshu2/agentops/skills-codex/.agentops-manifest.json +++ b/plugins/boshu2/agentops/skills-codex/.agentops-manifest.json @@ -492,6 +492,12 @@ "wave": "catalog-parity", "reason": "This non-invocable shared-reference skill does not need bespoke Codex prompt wording." }, + { + "name": "ship-loop", + "treatment": "parity_only", + "wave": "core-execution", + "reason": "Vendor-neutral internal-PR cycle; Codex stays in parity with the Claude SKILL.md after slim-frontmatter conversion." + }, { "name": "standards", "treatment": "parity_only", @@ -673,8 +679,8 @@ { "name": "beads", "source_skill": "skills/beads", - "source_hash": "f8c4dc1bea40b11b49378e5106d0f818ee5003f0da6af70c735af301be35321b", - "generated_hash": "dd11ff257a092cd3d2d5e93524bd91d6afa9edac1bf9cf5f3d34d2990446961e" + "source_hash": "13720553f7e45574d0f4abc6d08525aaa80d9470a8b5be2045ad9fcd3f426ac5", + "generated_hash": "03a281fe283a103d67a668622f8d53ea786801f4bdf239a62b12025bb7c7b492" }, { "name": "bootstrap", @@ -751,8 +757,8 @@ { "name": "discovery", "source_skill": "skills/discovery", - "source_hash": "13571cf69999a8f494c03decaaf18c1da53d69fffb019f33e9a5a2762838f249", - "generated_hash": "686a8b634487ecadb38c6971ed3e97673749e96354be1c1eec49d7ac64b02b4c" + "source_hash": "f789b340a74c049017196792dc43ebcf8a5ca4bd990759abc843271ed6f7f271", + "generated_hash": "b8cfabc0511ff22e356756ec32257d760d7aa26326a0eb5eb23f21b2cdac11ab" }, { "name": "doc", @@ -775,8 +781,8 @@ { "name": "evolve", "source_skill": "skills/evolve", - "source_hash": "e9436e9c0b027867b71208c06f1ff5e00b850a82115cb041887afd4279eccc71", - "generated_hash": "4e9afe7d59f84ce1caa43e5a82e7af3b2a25423dbbe900333d62991bc37caafb" + "source_hash": "1dd505d4df6ec3c6b07aac0b2128ce9d6c4de935e2cd257420fa3d08dd9b9764", + "generated_hash": "a3620debc89b8c810ffb063185ed073dde2ff567a7ce6a84ebdc1e130da94f0d" }, { "name": "expert-council", @@ -877,8 +883,8 @@ { "name": "plan", "source_skill": "skills/plan", - "source_hash": "3744e9ad96c836a3f25df2c0c09b58ffb51a33ab41c97e41d5a3455beeb7d53b", - "generated_hash": "9c19e377394c3cbeda1536a683f7ad6f2e39e6f971d3baaffa351253e28a6fb8" + "source_hash": "cbde267e8094eafcd887a667e9184f52d8847d8c160c515463846a3a90a00524", + "generated_hash": "98f259c86afd2e462b62f4971af70c028963d1e617b38f856274d9e230c19209" }, { "name": "post-mortem", @@ -1015,8 +1021,8 @@ { "name": "rpi", "source_skill": "skills/rpi", - "source_hash": "c555c28f7a184e3c5ece9322ebd3cb1a7f19605475a7c149df1ecf76d30496e3", - "generated_hash": "93c42675016e1ce97a66f221884a56f964d1e70e4992db8ed4f5e0ae30adb354" + "source_hash": "33e82844fd7f80252bce56d67b7cdfb4603869e8b33515c59b054de3210f22ad", + "generated_hash": "c8f439c27965aa992f1dd9c94d0f80ddc8c2aff5f8b864c8a2a6d0820c1c814d" }, { "name": "scaffold", @@ -1051,8 +1057,14 @@ { "name": "shared", "source_skill": "skills/shared", - "source_hash": "203eda1b6558dcf65c3fecba46505f402e82f81bef2185c90934e6f7023f70fa", - "generated_hash": "3ccc9e98714bb19d3c27ada5fc55be040290b5e92baa0d02851806539236767d" + "source_hash": "4256885a364331916753754e092e7e3dc490d4b05bade2dff7e6d1bc5ff1d54e", + "generated_hash": "0758c94cf77d7fd1bde265f3bff580a57f15fe601c59f893502d14175d57b763" + }, + { + "name": "ship-loop", + "source_skill": "skills/ship-loop", + "source_hash": "4f0179eee207e186462b765a34c97cd0c868c6e1524715e5706cbf2f64bc82fb", + "generated_hash": "53907ded08ccbccdb2fb96c82a6b512d245b050a20445e7267ef5001de467254" }, { "name": "skill-auditor", @@ -1081,7 +1093,7 @@ { "name": "swarm", "source_skill": "skills/swarm", - "source_hash": "28449f5f6d3148c25682e5ceff1b488b613c7a0226a459725bd05dbc00991d0f", + "source_hash": "1a88221c6b8856c19b29d24fa44811e518bfd1d51c6b0423fa6364520a3186e2", "generated_hash": "cecb9fed1aaff7fc85958163aa2cb34d6a4b448eafd16494aa3661aa7f01a95b" }, { @@ -1111,20 +1123,20 @@ { "name": "using-agentops", "source_skill": "skills/using-agentops", - "source_hash": "8b3c3fcf6388fdfb48f502450b4eb2fb847ff06e8a1cb8d60b15c8dc926565e9", - "generated_hash": "ab3839b2128e74ae4cbbdd04153e0837917bed5f45f6c7e71a53c3dbd06dbefb" + "source_hash": "1e7086747727bced19ed8e1c6ecffcdd6bffd97d1e8568642795dc5f755c5a02", + "generated_hash": "87a288af2f4d15942f2f7f3999f7e7dbfd5242ad37b27e8db2cdc7c75ddda3d6" }, { "name": "validate", "source_skill": "skills/validate", - "source_hash": "ea6fb882cb0d9ee3717d7064dfdf1616247fe04476221acea7520c93cc16cfbe", - "generated_hash": "ea7a8797f288541ed91c3b060c7c0bdb29de9ec7e9ffd5acd40ccf4bf4f53e5d" + "source_hash": "58e0d601fa098d63359b7eca1d48efa117bf20e4e32427d303b921940da6b8fe", + "generated_hash": "eab1216146dff716bd142a5caf66ec72b66286855b21e5b95f6046e360f3af42" }, { "name": "validation", "source_skill": "skills/validation", - "source_hash": "91ab8fe0a5a31c12b3979cf34d765c8cc1b623985a8c7136375352bcfb4a721f", - "generated_hash": "f0d71e4e851b217768dd99fb1a124cb76849d5ed9bdb3d0cca6600a72244d420" + "source_hash": "7e717c1f437f102c53ef8a69249a3461dbc4ca5a22bc640de7083165eecb9b8b", + "generated_hash": "353b7a5dcc7e4720f355dbe37e63259482812f10605a9189c8a5e6eabcf6e851" }, { "name": "vibe", diff --git a/plugins/boshu2/agentops/skills-codex/beads/.agentops-generated.json b/plugins/boshu2/agentops/skills-codex/beads/.agentops-generated.json index fcc2a07d..1a7e8c42 100644 --- a/plugins/boshu2/agentops/skills-codex/beads/.agentops-generated.json +++ b/plugins/boshu2/agentops/skills-codex/beads/.agentops-generated.json @@ -2,6 +2,6 @@ "generator": "manual-maintained", "source_skill": "skills/beads", "layout": "modular", - "source_hash": "f8c4dc1bea40b11b49378e5106d0f818ee5003f0da6af70c735af301be35321b", - "generated_hash": "dd11ff257a092cd3d2d5e93524bd91d6afa9edac1bf9cf5f3d34d2990446961e" + "source_hash": "13720553f7e45574d0f4abc6d08525aaa80d9470a8b5be2045ad9fcd3f426ac5", + "generated_hash": "03a281fe283a103d67a668622f8d53ea786801f4bdf239a62b12025bb7c7b492" } diff --git a/plugins/boshu2/agentops/skills-codex/beads/SKILL.md b/plugins/boshu2/agentops/skills-codex/beads/SKILL.md index 993ebf8c..52d48cbe 100644 --- a/plugins/boshu2/agentops/skills-codex/beads/SKILL.md +++ b/plugins/boshu2/agentops/skills-codex/beads/SKILL.md @@ -124,14 +124,28 @@ NEVER run bare `bv`. Always use `--robot-*` flags. Convert a markdown plan into fully dependency-wired beads: -1. Read the plan file -2. Create beads with `br create` for each issue, including full context in the description -3. Wire dependencies with `br dep add` -4. Polish iteratively (run polish prompt 6-9 times until steady-state) -5. Validate: `br dep cycles` must be empty, `bv --robot-insights` for graph health -6. Begin: `bv --robot-next` for first bead - -Beads should be so detailed that a fresh agent can implement without consulting the original plan. +1. Read the full plan, AGENTS.md, README, linked intent issue, and acceptance criteria. +2. Create beads with `br create` for each issue, including full context in the description. +3. For every feature, bug, or product-facing behavior, include a fenced `gherkin` + block or link to a filled intent issue. Mechanical chores may omit Gherkin + only when their acceptance criteria are fully command/file based. +4. Include the `hexagon:` boundary block from + `docs/architecture/intent-to-loop-hexagon.md` for substantial beads: + inbound port, bounded context, adapters, context packet, and done state. +5. Wire dependencies with `br dep add` / `bd dep add`. Do not hand-edit JSONL or + database files. +6. Polish iteratively (usually 6-9 passes) until steady-state. Check for lost + features, oversimplification, missing tests, unclear boundaries, missing e2e + coverage, and weak logging. +7. Validate: `br dep cycles` must be empty; run `bv --robot-insights` for graph + health; use `bv --robot-next` for the first bead. Never run bare `bv`. +8. Sync explicitly before commit: `br sync --flush-only`, then `git add .beads/` + and commit tracker changes when appropriate. + +Beads should be so detailed that a fresh agent can implement without consulting +the original plan. Ready-to-implement beads have clear scope, explicit +dependencies, BDD or mechanical acceptance, unit/e2e test expectations, detailed +logging expectations, a named done state, and no dependency cycles. ## Troubleshooting diff --git a/plugins/boshu2/agentops/skills-codex/discovery/.agentops-generated.json b/plugins/boshu2/agentops/skills-codex/discovery/.agentops-generated.json index 3133d20d..8695c25f 100644 --- a/plugins/boshu2/agentops/skills-codex/discovery/.agentops-generated.json +++ b/plugins/boshu2/agentops/skills-codex/discovery/.agentops-generated.json @@ -2,6 +2,6 @@ "generator": "manual-maintained", "source_skill": "skills/discovery", "layout": "modular", - "source_hash": "13571cf69999a8f494c03decaaf18c1da53d69fffb019f33e9a5a2762838f249", - "generated_hash": "686a8b634487ecadb38c6971ed3e97673749e96354be1c1eec49d7ac64b02b4c" + "source_hash": "f789b340a74c049017196792dc43ebcf8a5ca4bd990759abc843271ed6f7f271", + "generated_hash": "b8cfabc0511ff22e356756ec32257d760d7aa26326a0eb5eb23f21b2cdac11ab" } diff --git a/plugins/boshu2/agentops/skills-codex/discovery/SKILL.md b/plugins/boshu2/agentops/skills-codex/discovery/SKILL.md index c353fcef..b91bb512 100644 --- a/plugins/boshu2/agentops/skills-codex/discovery/SKILL.md +++ b/plugins/boshu2/agentops/skills-codex/discovery/SKILL.md @@ -37,7 +37,9 @@ Leave `ao codex ensure-stop` to closeout skills; discovery owns startup only. ## Narrow Waist Discovery does not carry raw child-skill output forward. It records artifact -paths, verdicts, and the six Context Density Rule fields: +paths, verdicts, the `hexagon:` boundary block from +[`docs/architecture/intent-to-loop-hexagon.md`](../../docs/architecture/intent-to-loop-hexagon.md), +and the six Context Density Rule fields: | Field | Meaning | |-------|---------| @@ -53,7 +55,8 @@ Everything else stays in child artifacts and is linked by path. ## Discovery To Plan Port Use the [Skill Ports and Adapters](../../docs/contracts/skill-ports-and-adapters.md) -vocabulary for the boundary between Discovery and Plan: +vocabulary and the [Intent-to-Loop Hexagon](../../docs/architecture/intent-to-loop-hexagon.md) +for the boundary between Discovery and Plan: | Boundary piece | Discovery contract | |---|---| diff --git a/plugins/boshu2/agentops/skills-codex/evolve/.agentops-generated.json b/plugins/boshu2/agentops/skills-codex/evolve/.agentops-generated.json index 345ed617..e0ae34b1 100644 --- a/plugins/boshu2/agentops/skills-codex/evolve/.agentops-generated.json +++ b/plugins/boshu2/agentops/skills-codex/evolve/.agentops-generated.json @@ -2,6 +2,6 @@ "generator": "manual-maintained", "source_skill": "skills/evolve", "layout": "modular", - "source_hash": "e9436e9c0b027867b71208c06f1ff5e00b850a82115cb041887afd4279eccc71", - "generated_hash": "4e9afe7d59f84ce1caa43e5a82e7af3b2a25423dbbe900333d62991bc37caafb" + "source_hash": "1dd505d4df6ec3c6b07aac0b2128ce9d6c4de935e2cd257420fa3d08dd9b9764", + "generated_hash": "a3620debc89b8c810ffb063185ed073dde2ff567a7ce6a84ebdc1e130da94f0d" } diff --git a/plugins/boshu2/agentops/skills-codex/evolve/SKILL.md b/plugins/boshu2/agentops/skills-codex/evolve/SKILL.md index 897ca21b..52935fc4 100644 --- a/plugins/boshu2/agentops/skills-codex/evolve/SKILL.md +++ b/plugins/boshu2/agentops/skills-codex/evolve/SKILL.md @@ -268,8 +268,29 @@ Run at the TOP of every cycle: ```bash CYCLE_START_SHA=$(git rev-parse HEAD) -[ -f ~/.config/evolve/KILL ] && echo "KILL: $(cat ~/.config/evolve/KILL)" && exit 0 -[ -f .agents/evolve/STOP ] && echo "STOP: $(cat .agents/evolve/STOP 2>/dev/null)" && exit 0 +# Stale-kill auto-expire (closes F5 from 2026-05-18 post-mortem). +# A KILL/STOP file older than EVOLVE_KILL_TTL_DAYS (default 7) is treated as +# stale and surfaced loudly; the loop proceeds. Re-touch to keep blocking. +EVOLVE_KILL_TTL_DAYS="${EVOLVE_KILL_TTL_DAYS:-7}" +check_stale_kill() { + local path="$1" ttl_days="$2" + [ -f "$path" ] || return 1 + local mtime_epoch now_epoch age_days + mtime_epoch=$(stat -c %Y "$path" 2>/dev/null || stat -f %m "$path" 2>/dev/null) + now_epoch=$(date +%s) + age_days=$(( (now_epoch - mtime_epoch) / 86400 )) + if [ "$age_days" -gt "$ttl_days" ]; then + echo "WARN: ${path} is ${age_days} days old (> ${ttl_days}); STALE, proceeding." >&2 + return 1 + fi + return 0 +} +if check_stale_kill ~/.config/evolve/KILL "$EVOLVE_KILL_TTL_DAYS"; then + echo "KILL: $(cat ~/.config/evolve/KILL)"; exit 0 +fi +if check_stale_kill .agents/evolve/STOP "$EVOLVE_KILL_TTL_DAYS"; then + echo "STOP: $(cat .agents/evolve/STOP 2>/dev/null)"; exit 0 +fi ``` ### Step 2: Measure Fitness diff --git a/plugins/boshu2/agentops/skills-codex/plan/.agentops-generated.json b/plugins/boshu2/agentops/skills-codex/plan/.agentops-generated.json index c1d71993..928fe509 100644 --- a/plugins/boshu2/agentops/skills-codex/plan/.agentops-generated.json +++ b/plugins/boshu2/agentops/skills-codex/plan/.agentops-generated.json @@ -2,6 +2,6 @@ "generator": "manual-maintained", "source_skill": "skills/plan", "layout": "modular", - "source_hash": "3744e9ad96c836a3f25df2c0c09b58ffb51a33ab41c97e41d5a3455beeb7d53b", - "generated_hash": "9c19e377394c3cbeda1536a683f7ad6f2e39e6f971d3baaffa351253e28a6fb8" + "source_hash": "cbde267e8094eafcd887a667e9184f52d8847d8c160c515463846a3a90a00524", + "generated_hash": "98f259c86afd2e462b62f4971af70c028963d1e617b38f856274d9e230c19209" } diff --git a/plugins/boshu2/agentops/skills-codex/plan/SKILL.md b/plugins/boshu2/agentops/skills-codex/plan/SKILL.md index f9533116..78f9efb3 100644 --- a/plugins/boshu2/agentops/skills-codex/plan/SKILL.md +++ b/plugins/boshu2/agentops/skills-codex/plan/SKILL.md @@ -80,7 +80,11 @@ Feature: Plan converts dense intent into executable slices 8. **Decompose into issues.** Each issue needs title, file ownership, dependencies, acceptance criteria, test levels, and at least one mechanical conformance check (`files_exist`, `content_check`, `command`, `tests`, or - `lint`). + `lint`). Feature, bug, and product-facing behavior issues also need a + fenced `gherkin` block or a link to the upstream intent issue scenario. + Non-trivial plans and bead bodies should include the `hexagon:` boundary + block: inbound port, bounded context, adapters, context packet, and done + state. 9. **Compute waves.** Group independent issues by dependency. Serialize or merge same-file writes. Include generated artifacts, docs, schemas, fixtures, Codex companions, manifests, and hash markers in ownership. diff --git a/plugins/boshu2/agentops/skills-codex/rpi/.agentops-generated.json b/plugins/boshu2/agentops/skills-codex/rpi/.agentops-generated.json index 9043ef98..d9de7f9d 100644 --- a/plugins/boshu2/agentops/skills-codex/rpi/.agentops-generated.json +++ b/plugins/boshu2/agentops/skills-codex/rpi/.agentops-generated.json @@ -2,6 +2,6 @@ "generator": "manual-maintained", "source_skill": "skills/rpi", "layout": "modular", - "source_hash": "c555c28f7a184e3c5ece9322ebd3cb1a7f19605475a7c149df1ecf76d30496e3", - "generated_hash": "93c42675016e1ce97a66f221884a56f964d1e70e4992db8ed4f5e0ae30adb354" + "source_hash": "33e82844fd7f80252bce56d67b7cdfb4603869e8b33515c59b054de3210f22ad", + "generated_hash": "c8f439c27965aa992f1dd9c94d0f80ddc8c2aff5f8b864c8a2a6d0820c1c814d" } diff --git a/plugins/boshu2/agentops/skills-codex/rpi/SKILL.md b/plugins/boshu2/agentops/skills-codex/rpi/SKILL.md index d2914902..d471b2ab 100644 --- a/plugins/boshu2/agentops/skills-codex/rpi/SKILL.md +++ b/plugins/boshu2/agentops/skills-codex/rpi/SKILL.md @@ -56,6 +56,10 @@ packet objective. A child bead or one ready slice is context, not a replacement objective. `PARTIAL` from `$crank` means retry Phase 2 on the same objective. +Preserve the [Intent-to-Loop Hexagon](../../docs/architecture/intent-to-loop-hexagon.md) +boundary as the objective crosses `shape_intent`, `persist_intent`, +`plan_slices`, `execute_wave`, `validate_acceptance`, and `record_evidence`. + ## Route And Classify 1. Create `.agents/rpi/`. diff --git a/plugins/boshu2/agentops/skills-codex/shared/.agentops-generated.json b/plugins/boshu2/agentops/skills-codex/shared/.agentops-generated.json index eb823e2d..aa3127f4 100644 --- a/plugins/boshu2/agentops/skills-codex/shared/.agentops-generated.json +++ b/plugins/boshu2/agentops/skills-codex/shared/.agentops-generated.json @@ -2,6 +2,6 @@ "generator": "manual-maintained", "source_skill": "skills/shared", "layout": "modular", - "source_hash": "203eda1b6558dcf65c3fecba46505f402e82f81bef2185c90934e6f7023f70fa", - "generated_hash": "3ccc9e98714bb19d3c27ada5fc55be040290b5e92baa0d02851806539236767d" + "source_hash": "4256885a364331916753754e092e7e3dc490d4b05bade2dff7e6d1bc5ff1d54e", + "generated_hash": "0758c94cf77d7fd1bde265f3bff580a57f15fe601c59f893502d14175d57b763" } diff --git a/plugins/boshu2/agentops/skills-codex/shared/validation-contract.md b/plugins/boshu2/agentops/skills-codex/shared/validation-contract.md index d9f8e519..f977542b 100644 --- a/plugins/boshu2/agentops/skills-codex/shared/validation-contract.md +++ b/plugins/boshu2/agentops/skills-codex/shared/validation-contract.md @@ -18,6 +18,31 @@ CORRECT (new): --- +## Completion-Claim Kernel + +Apply this kernel whenever an artifact says a bead, task, epic, gate, or phase is +`DONE`, `closed`, `complete`, `green`, or ready to ship: + +1. Treat status fields and agent summaries as claims until fresh evidence proves + the contract is satisfied. +2. Rerun the narrowest checks that prove the acceptance criteria now, and keep + command, exit code, and relevant output in the verdict or linked evidence. +3. Separate test existence, command success, and non-trivial assertions against + production paths. Flag skipped tests, `assert true`, hardcoded success paths, + disabled code, and mocks where the spec required real integration. +4. Map each claimed acceptance criterion to file:line evidence, named tests, raw + logs, or explicit no-file evidence. +5. Check parent/child reconciliation, dependency graph health, orphaned + acceptance criteria, and cross-bead contract drift. +6. Label deterministic suspicion as `flagged-for-review` until rerun evidence + proves a true failure. + +The evidence minimum for a completion claim is: claimed scope, acceptance +criterion, proof artifact, rerun command when applicable, and parent/dependency +reconciliation outcome. + +--- + ## Specifying Validation Requirements diff --git a/plugins/boshu2/agentops/skills-codex/ship-loop/.agentops-generated.json b/plugins/boshu2/agentops/skills-codex/ship-loop/.agentops-generated.json new file mode 100644 index 00000000..f3370dc0 --- /dev/null +++ b/plugins/boshu2/agentops/skills-codex/ship-loop/.agentops-generated.json @@ -0,0 +1,7 @@ +{ + "generator": "manual-maintained", + "source_skill": "skills/ship-loop", + "layout": "modular", + "source_hash": "4f0179eee207e186462b765a34c97cd0c868c6e1524715e5706cbf2f64bc82fb", + "generated_hash": "53907ded08ccbccdb2fb96c82a6b512d245b050a20445e7267ef5001de467254" +} diff --git a/plugins/boshu2/agentops/skills-codex/ship-loop/SKILL.md b/plugins/boshu2/agentops/skills-codex/ship-loop/SKILL.md new file mode 100644 index 00000000..c0c55eac --- /dev/null +++ b/plugins/boshu2/agentops/skills-codex/ship-loop/SKILL.md @@ -0,0 +1,96 @@ +--- +name: ship-loop +description: 'Internal-PR fast-lane cycle.' +--- + +# $ship-loop — Bot-paired fast lane PR cycle + +> **Codex orchestration default:** when the operator types `$ship-loop`, run the 9-step cycle below. For fork-based OSS contributions use `$pr-implement` and the `$pr-*` family instead (different tier). + +Capture of the discipline that lands single-scenario internal PRs at ~15-30 min median time-to-merge in repos with an auto-review bot workflow and `gh pr merge --auto` enabled. + +## When to use + +| Use ship-loop when... | Use something else when... | +|---|---| +| Single-scenario internal PR in your own repo | Fork-based OSS contribution → `$pr-implement` | +| PR <100 lines with paired tests | Multi-wave epic → `$crank` | +| Closing a harvested next-work item | Architecture / contract change → slow lane / human review | +| Mechanical drift fix or regression closure | Work that can't fit one scenario → split or escalate | + +## The 9-step cycle + +1. **Claim.** `bd ready` → pick highest-severity unblocked, OR read `.agents/rpi/next-work.jsonl` for harvested items. `bd update --claim`. +2. **Branch off fresh main.** `git checkout main && git pull --rebase`. Then `git checkout -b /-`. Never stack off siblings. +3. **First failing test.** BDD scenario or unit test. Must fail for the right reason (asserting expected behavior). Per the project's L2-first/L1-always rule. +4. **Minimal implementation.** Smallest code change that makes the test green. Resist scope creep. +5. **`scripts/pre-push-gate.sh --fast`** (or full gate — see below). Diff-scoped CI. **Escalate to the full gate (`scripts/pre-push-gate.sh`, no `--fast`) when the PR adds a new skill, new contract, new schema, or any inventory surface** — `--fast` skips ~15 inventory validators (registry-check, codex-override-coverage, skill-integrity, manifest entries, context-map drift). Catching them once locally is one pass; chasing them one-at-a-time through CI is 5-10 passes. If a pre-existing blocker appears in unchanged-from-base content, file an atomic side-quest fix PR first (don't bundle). +6. **Commit with conventional-commit scope.** `feat():`, `fix():`. Body reproduces the failure mode the test catches. +7. **Push + `gh pr create`.** Body cites the bead, validation, and a learning-anchor reference in the script body (not a `.agents/learnings/` file — that breaks CI). +8. **`gh pr merge --squash --auto`.** Immediately. The bot fires the review check automatically on PR open. +9. **Close the bead.** `bd close --reason "Merged via PR #"`. For multi-PR chains: `scripts/gh-merge-chain.sh `. + +## Gate sequence + +| Gate | Enforces | +|---|---| +| `scripts/pre-push-gate.sh --fast` | Diff-scoped CI; unconditional shellcheck on staged `.sh`; mkdocs strict on docs/; registry-drift | +| Review-bot workflow (auto on PR open) | Bot half of the pair — no mention required | +| `.github/workflows/validate.yml` | Full 60+ job suite | +| `gh pr merge --squash --auto` | Auto-merge when all required checks pass | +| `scripts/gh-merge-chain.sh` (optional) | Chain N PRs through auto-merge with `update-branch` on each successor | + +## Failure-mode mapping (F1-F5 + meta) + +| ID | Failure | Mechanical guard | +|---|---|---| +| F1 | Script rewrite leaves dead variables | Unconditional shellcheck on staged `.sh` | +| F2 | Pre-existing blocker compounds across branches | **Open.** Rule: fix as atomic side-quest PR first | +| F3 | `--auto` doesn't auto-rebase BEHIND branches | `scripts/gh-merge-chain.sh` | +| F4 | Bot trigger doc claimed mention-only | Doc corrected; observed auto-fire on PR open | +| F5 | Stale `~/.config/evolve/KILL` silently blocks `$evolve` | `EVOLVE_KILL_TTL_DAYS=7` auto-expire | +| meta | Tests asserting local-only file existence | `grep -q '' "$SCRIPT"` instead of `[ -f .agents/learnings/.md ]` | + +## Anti-patterns + +1. **Running `--fast` pre-push on an inventory-touching PR** — new skill, contract, or schema → use FULL gate; `--fast` skips ~15 inventory validators +2. **Bundling pre-existing fixes** — file each as its own atomic PR +3. **Keeping copied variables after a rewrite** — first self-check after rewrite is "are all variable declarations used?" +4. **Asserting local-only state in CI tests** — grep the reference, don't check the file +5. **Branches off out-of-date main** — `git pull --rebase` at branch creation +6. **Skipping the failing-test-first step** — adding a test after the fix gives false confidence + +## Pair mechanics + +- The review-bot workflow fires automatically on `pull_request: opened/synchronize`. No mention required. +- If `IN_PROGRESS`, wait. If silent, check workflow permissions (`workflows: write` for forward-port scenarios). +- Self-revert loop (bot reverting its own forward-port): rebase the branch locally onto fresh main and force-push. + +## Anti-Patterns (DO NOT) + +| Anti-Pattern | Why It's Wrong | Correct Behavior | +|---|---|---| +| Stack feature branches on each other | Auto-merge serialization fails; conflicts compound | Always branch off fresh main | +| Bundle a pre-existing fix into a feature PR | Other branches will hit + duplicate the same fix | File atomic side-quest PR first, rebase | +| Assert `.agents/learnings/.md` exists in CI | `.agents/` is gitignored; test fails in fresh clone | `grep -q '' "$SCRIPT"` (reference assertion) | +| Add tests after the fix without seeing them fail | False confidence | Write the failing test FIRST, see it red | +| Push without `--auto` enabled immediately | Operator becomes the merge bottleneck | `gh pr merge --squash --auto` on PR open | + +## Examples + +**User says:** `$ship-loop` after picking `soc-` from `bd ready` +Run the 9-step cycle: branch, first failing test, minimal impl, pre-push --fast, commit, push, auto-merge, bd close. + +**User says:** "ship this fix from the post-mortem" +Read the harvested item from `.agents/rpi/next-work.jsonl`, run the 9-step cycle. + +**User says:** "land the 4 PRs we have open" +After all 4 PRs are open with auto-merge enabled: `scripts/gh-merge-chain.sh `. + +## See Also + +- `$pr-implement` — fork-based OSS contribution (different tier; different use case) +- `$crank` — multi-wave epic execution +- `$rpi` — full lifecycle orchestrator +- `$post-mortem` — harvests next-work items that ship-loop consumes +- `$beads` — task tracker that drives the claim step diff --git a/plugins/boshu2/agentops/skills-codex/ship-loop/prompt.md b/plugins/boshu2/agentops/skills-codex/ship-loop/prompt.md new file mode 100644 index 00000000..87fe377e --- /dev/null +++ b/plugins/boshu2/agentops/skills-codex/ship-loop/prompt.md @@ -0,0 +1,35 @@ +# Execution Profile — ship-loop + +You are running the bot-paired fast lane PR cycle. Operator typed `$ship-loop` or asked you to ship a single-scenario internal PR. + +## Mode + +- **Lane:** internal-ship (same-repo, branch off main, auto-merge to main). NOT a fork-based OSS contribution. +- **Default approval:** autonomous; the bot review fires automatically on PR open. +- **Stop conditions:** the 9-step cycle completes, OR a gate fails with a real blocker (not a pre-existing F2-class side-quest), OR the work won't fit one scenario. + +## Run + +1. Read `bd ready` and `.agents/rpi/next-work.jsonl`. Pick highest-severity unblocked item. Claim it: `bd update --claim`. +2. `git checkout main && git pull --rebase`. Branch: `git checkout -b /-`. +3. Write the first FAILING test. Confirm it fails for the right reason. +4. Write the minimal implementation. Confirm the test now passes. +5. Run `scripts/pre-push-gate.sh --fast`. If a pre-existing blocker fires on content you didn't change, STOP and file an atomic side-quest fix PR first. +6. Commit with conventional-commit scope. Body reproduces the failure mode. +7. Push + `gh pr create`. `gh pr merge --squash --auto`. +8. `bd close ` after the PR auto-merges. + +## Guardrails + +- Reject work that touches >5 non-uniform files or introduces a new shape (schema, contract surface, struct field). Surface to operator for slow-lane routing instead. +- Reject tests that assert local-only file existence (`[ -f .agents/learnings/.md ]`). Use `grep -q '' "$SCRIPT"` to assert the rationale reference in the script body instead. +- Reject "I'll add the test after" — write the failing test FIRST. + +## Verification + +- Local: `bats ` AND `scripts/pre-push-gate.sh --fast` both pass before push. +- Remote: `claude-review` and the full `validate.yml` suite via `gh pr view --json statusCheckRollup`. + +## Output + +A merged PR on `origin/main` and a closed bead. If the chain has >=3 PRs in flight, invoke `scripts/gh-merge-chain.sh` to serialize them. diff --git a/plugins/boshu2/agentops/skills-codex/swarm/.agentops-generated.json b/plugins/boshu2/agentops/skills-codex/swarm/.agentops-generated.json index f598bc2e..478d1d8f 100644 --- a/plugins/boshu2/agentops/skills-codex/swarm/.agentops-generated.json +++ b/plugins/boshu2/agentops/skills-codex/swarm/.agentops-generated.json @@ -2,6 +2,6 @@ "generator": "manual-maintained", "source_skill": "skills/swarm", "layout": "modular", - "source_hash": "28449f5f6d3148c25682e5ceff1b488b613c7a0226a459725bd05dbc00991d0f", + "source_hash": "1a88221c6b8856c19b29d24fa44811e518bfd1d51c6b0423fa6364520a3186e2", "generated_hash": "cecb9fed1aaff7fc85958163aa2cb34d6a4b448eafd16494aa3661aa7f01a95b" } diff --git a/plugins/boshu2/agentops/skills-codex/using-agentops/.agentops-generated.json b/plugins/boshu2/agentops/skills-codex/using-agentops/.agentops-generated.json index 74477480..3f71254b 100644 --- a/plugins/boshu2/agentops/skills-codex/using-agentops/.agentops-generated.json +++ b/plugins/boshu2/agentops/skills-codex/using-agentops/.agentops-generated.json @@ -2,6 +2,6 @@ "generator": "manual-maintained", "source_skill": "skills/using-agentops", "layout": "modular", - "source_hash": "8b3c3fcf6388fdfb48f502450b4eb2fb847ff06e8a1cb8d60b15c8dc926565e9", - "generated_hash": "ab3839b2128e74ae4cbbdd04153e0837917bed5f45f6c7e71a53c3dbd06dbefb" + "source_hash": "1e7086747727bced19ed8e1c6ecffcdd6bffd97d1e8568642795dc5f755c5a02", + "generated_hash": "87a288af2f4d15942f2f7f3999f7e7dbfd5242ad37b27e8db2cdc7c75ddda3d6" } diff --git a/plugins/boshu2/agentops/skills-codex/using-agentops/SKILL.md b/plugins/boshu2/agentops/skills-codex/using-agentops/SKILL.md index a08ff7a4..1b312227 100644 --- a/plugins/boshu2/agentops/skills-codex/using-agentops/SKILL.md +++ b/plugins/boshu2/agentops/skills-codex/using-agentops/SKILL.md @@ -145,6 +145,7 @@ These are the skills every user needs first. Everything else is available when y | `$pr-validate` | PR-specific validation and isolation checks | | `$pr-prep` | PR preparation and structured body generation | | `$pr-retro` | Learn from PR outcomes | +| `$ship-loop` | Bot-paired internal-PR fast-lane cycle | | `$complexity` | Code complexity analysis | | `$product` | Interactive PRODUCT.md generation | | `$handoff` | Session handoff for continuation | diff --git a/plugins/boshu2/agentops/skills-codex/validate/.agentops-generated.json b/plugins/boshu2/agentops/skills-codex/validate/.agentops-generated.json index e62ac30c..8cf7f398 100644 --- a/plugins/boshu2/agentops/skills-codex/validate/.agentops-generated.json +++ b/plugins/boshu2/agentops/skills-codex/validate/.agentops-generated.json @@ -2,6 +2,6 @@ "generator": "manual-maintained", "source_skill": "skills/validate", "layout": "modular", - "source_hash": "ea6fb882cb0d9ee3717d7064dfdf1616247fe04476221acea7520c93cc16cfbe", - "generated_hash": "ea7a8797f288541ed91c3b060c7c0bdb29de9ec7e9ffd5acd40ccf4bf4f53e5d" + "source_hash": "58e0d601fa098d63359b7eca1d48efa117bf20e4e32427d303b921940da6b8fe", + "generated_hash": "eab1216146dff716bd142a5caf66ec72b66286855b21e5b95f6046e360f3af42" } diff --git a/plugins/boshu2/agentops/skills-codex/validate/SKILL.md b/plugins/boshu2/agentops/skills-codex/validate/SKILL.md index 14d27b60..a9b0b5ec 100644 --- a/plugins/boshu2/agentops/skills-codex/validate/SKILL.md +++ b/plugins/boshu2/agentops/skills-codex/validate/SKILL.md @@ -9,6 +9,14 @@ description: 'Produce PASS/WARN/FAIL verdicts.' > **Status (2026-05-08):** introduced ADDITIVE in Phase 1 (m6v5.D.1 / soc-78s2v). Existing validators (council, vibe, pre-mortem, red-team, pr-validate, validation, review, scenario) stay until Phase 2 shim conversion (m6v5.D.2). Fix-C smoke (`soc-wb2aa`) gates Phase 2. +`$validate` is a driving adapter for the `validate_acceptance` port in the +[Intent-to-Loop Hexagon](../../docs/architecture/intent-to-loop-hexagon.md). +When the artifact contains a `hexagon:` block, preserve the bounded context, +context packet, guard adapters, and done state in the verdict. +When the artifact claims DONE/closed/green, apply the +[Completion-Claim Kernel](../shared/validation-contract.md#completion-claim-kernel) +before returning PASS. + ## Modes (≤8 per Fix-F mode-flag budget) | Mode | Purpose | Replaces (post-Phase 2) | diff --git a/plugins/boshu2/agentops/skills-codex/validation/.agentops-generated.json b/plugins/boshu2/agentops/skills-codex/validation/.agentops-generated.json index feb9a107..726df856 100644 --- a/plugins/boshu2/agentops/skills-codex/validation/.agentops-generated.json +++ b/plugins/boshu2/agentops/skills-codex/validation/.agentops-generated.json @@ -2,6 +2,6 @@ "generator": "manual-maintained", "source_skill": "skills/validation", "layout": "modular", - "source_hash": "91ab8fe0a5a31c12b3979cf34d765c8cc1b623985a8c7136375352bcfb4a721f", - "generated_hash": "f0d71e4e851b217768dd99fb1a124cb76849d5ed9bdb3d0cca6600a72244d420" + "source_hash": "7e717c1f437f102c53ef8a69249a3461dbc4ca5a22bc640de7083165eecb9b8b", + "generated_hash": "353b7a5dcc7e4720f355dbe37e63259482812f10605a9189c8a5e6eabcf6e851" } diff --git a/plugins/boshu2/agentops/skills-codex/validation/SKILL.md b/plugins/boshu2/agentops/skills-codex/validation/SKILL.md index beafcb1a..4dbafbdf 100644 --- a/plugins/boshu2/agentops/skills-codex/validation/SKILL.md +++ b/plugins/boshu2/agentops/skills-codex/validation/SKILL.md @@ -14,6 +14,13 @@ Validation delegates to `$vibe`, `$post-mortem`, `$retro`, and `$forge` (plus li See [`docs/learnings/orchestrator-compression-anti-pattern.md`](../../docs/learnings/orchestrator-compression-anti-pattern.md) for the live compression signature. +Validation owns the `validate_acceptance` port in the +[Intent-to-Loop Hexagon](../../docs/architecture/intent-to-loop-hexagon.md). +The roll-up must preserve bounded context, context packet, guard adapters, done +state, and fresh proof for each accepted scenario. Apply the +[Completion-Claim Kernel](../shared/validation-contract.md#completion-claim-kernel) +before accepting DONE/closed/green claims. + ## DAG — Execute This Sequentially ### Step 0: Load Prior Validation Context diff --git a/plugins/ouonet/praxis/.codex-plugin/plugin.json b/plugins/ouonet/praxis/.codex-plugin/plugin.json index d0f31120..d7f1b635 100644 --- a/plugins/ouonet/praxis/.codex-plugin/plugin.json +++ b/plugins/ouonet/praxis/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "praxis", - "version": "1.2.2", + "version": "1.2.3", "description": "Token-lean discipline skills for coding agents.", "author": { "name": "ouonet" }, "homepage": "https://github.com/ouonet/praxis", diff --git a/plugins/ouonet/praxis/package.json b/plugins/ouonet/praxis/package.json index 47dd2320..829fd05a 100644 --- a/plugins/ouonet/praxis/package.json +++ b/plugins/ouonet/praxis/package.json @@ -1,6 +1,6 @@ { "name": "praxis", - "version": "1.2.2", + "version": "1.2.3", "type": "module", "main": ".opencode/plugins/praxis.js" } diff --git a/plugins/ouonet/praxis/skills/triage/SKILL.md b/plugins/ouonet/praxis/skills/triage/SKILL.md index f2fd8069..7582cd4f 100644 --- a/plugins/ouonet/praxis/skills/triage/SKILL.md +++ b/plugins/ouonet/praxis/skills/triage/SKILL.md @@ -11,14 +11,14 @@ praxis: scope=, loading= | scope | signal | load | |---|---|---| -| trivial | typo, rename, doc, <=1-line, pure Q | none | -| small | one function, single file, <=50 LOC | `tdd` (intent unclear? clarify first) | -| standard | feature, multi-file, new behavior | `design` -> `plan` -> `tdd` -> `review` | -| complex | new system, >=5 tasks, parallel | `design` -> `plan` -> `worktree` -> `subagents` -> `review` -> `ship` | +| trivial | typo, rename, docs-only, <=1-line, pure Q | none | +| small | one function, single file, <=50 LOC, or test-only change | `tdd` (intent unclear? clarify first) | +| standard | feature change or source-code change | `design` -> `plan` -> `tdd` -> `review` | +| complex | large feature/source-code change: new system, >=5 tasks, or parallel edits | `design` -> `plan` -> `worktree` -> `subagents` -> `review` -> `ship` | | debug | broken, regression, failing test | `debug` first, then route fix | | onboard | existing project, no docs/tech-spec.md, "take over"/"add Praxis" | `onboard` | -Torn? Pick smaller. "just X" / "quickly" / "no tests" -> downgrade. "design it" / "properly" -> upgrade. +If multiple scopes fit, choose the smaller one. `feature change` = user-visible/public-contract change. `source code` = code/schema/config that changes shipped behavior; docs, tests, examples, CI, and tooling excluded. - Never load a skill not listed for the chosen scope. - Load selected skills via the Skill tool as `praxis:`, or in file-read harnesses from `skills//SKILL.md`. \ No newline at end of file