@stdd/plugin 0.9.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "stdd",
+  "version": "0.9.0",
+  "description": "Native STDD workflow skills and lifecycle context",
+  "author": {
+    "name": "Azamat Almazbek uulu"
+  },
+  "hooks": "./hooks/claude-hooks.json"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "stdd",
+  "version": "0.9.0",
+  "description": "Native STDD workflow skills and lifecycle context for Codex",
+  "author": {
+    "name": "Azamat Almazbek uulu"
+  },
+  "skills": "./skills/",
+  "hooks": "./hooks/codex-hooks.json",
+  "interface": {
+    "displayName": "STDD",
+    "shortDescription": "Spec + Test Driven Development workflows.",
+    "longDescription": "Adds STDD change routing, planning, implementation, review, and delivery skills with a self-contained lifecycle runtime. Repository state and optional enforcement remain project-owned.",
+    "developerName": "Azamat Almazbek uulu",
+    "category": "Productivity",
+    "capabilities": [],
+    "defaultPrompt": [
+      "Use STDD to classify and execute this repository change."
+    ]
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Azamat Almazbek uulu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# STDD universal plugin
+
+This directory is the self-contained STDD distribution for Codex, Claude Code,
+and Pi. Every host loads the same conservative-profile skills and bundled CLI
+runtime; adopting repositories do not need a local `@stdd/cli` dependency.
+
+## Install
+
+- **Codex:** install `stdd` from a Codex marketplace that points at this
+  directory.
+- **Claude Code:** install `stdd` from a Claude Code marketplace that points at
+  this directory.
+- **Pi:** `pi install npm:@stdd/plugin@<version>`. For a source checkout, use
+  `pi install ./plugins/stdd`.
+
+The source tree is a distribution input, not proof that a registry release has
+occurred. Publishers must run the repository build and verification commands
+before releasing it.
+
+## Activation and ownership
+
+Installing the bundle changes no repository. Skills are available globally,
+but lifecycle integration stays dormant unless the current checkout contains
+`.stdd/`. Run `stdd init` separately when a repository adopts the shared
+contract. Repository state, policy, generated native routing, and optional CI
+remain repository-owned.
+
+Codex and Claude Code use fail-open SessionStart and Stop command hooks. Pi
+restores successful local status output at session start and after compaction,
+and may queue one corrective follow-up after a blocked settled turn. Runtime
+errors do not trap the host or enter model context. If the bundle cannot read
+an adopted contract, update the bundle or re-run initialization with a
+compatible STDD CLI.
+
+## Build
+
+From the STDD source root:
+
+```bash
+npm run build:plugin
+npm pack --dry-run --json ./plugins/stdd
+```
+
+The build regenerates skills, the Pi extension, and the bundled runtime;
+version-aligns all host manifests; and rejects unsafe or stale publication
+paths. Building currently requires Linux held-directory support. The generated
+bundle itself remains portable to supported Codex, Claude Code, and Pi hosts.

package/extensions/stdd.mjs

@@ -0,0 +1,77 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { resolveAdoptingRoot } from "../scripts/adopting-root.mjs";
+
+const RUNTIME = fileURLToPath(new URL("../runtime/cli/stdd.mjs", import.meta.url));
+const COMMAND_TIMEOUT_MS = 10_000;
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+const SESSION_RUNTIME_FAILURE =
+	"STDD bundled runtime failed. Update the STDD plugin or re-run `stdd init`.";
+
+function exec(command, args, cwd) {
+	return new Promise((resolve) => {
+		const child = execFile(
+			command,
+			args,
+			{
+				cwd,
+				encoding: "utf8",
+				timeout: COMMAND_TIMEOUT_MS,
+				maxBuffer: MAX_OUTPUT_BYTES,
+			},
+			(error, stdout, stderr) => {
+				const exitCode = error ? (typeof error.code === "number" ? error.code : null) : 0;
+				resolve({ exitCode, stdout, stderr });
+			},
+		);
+		child.stdin?.end();
+	});
+}
+
+async function runStdd(cwd, args) {
+	const root = resolveAdoptingRoot(cwd);
+	if (!root || !fs.existsSync(RUNTIME)) return null;
+	return exec(process.execPath, [RUNTIME, ...args], root);
+}
+
+export default function stddPlugin(pi) {
+	const restore = async (_event, ctx) => {
+		const result = await runStdd(ctx.cwd, ["status", "--local"]);
+		if (!result) return;
+		if (result.exitCode !== 0) {
+			if (ctx.hasUI) ctx.ui.notify(SESSION_RUNTIME_FAILURE, "warning");
+			return;
+		}
+		if (result.stdout.trim() === "") return;
+		pi.sendMessage(
+			{
+				customType: "stdd-status",
+				content: result.stdout,
+				display: false,
+			},
+			{ deliverAs: "nextTurn" },
+		);
+	};
+	pi.on("session_start", restore);
+	pi.on("session_compact", restore);
+
+	let skipNextGate = false;
+	pi.on("agent_settled", async (_event, ctx) => {
+		if (skipNextGate) {
+			skipNextGate = false;
+			return;
+		}
+		const result = await runStdd(ctx.cwd, ["stop-hook"]);
+		if (result?.exitCode !== 2 || result.stderr.trim() === "") return;
+		skipNextGate = true;
+		pi.sendMessage(
+			{
+				customType: "stdd-stop-gate",
+				content: result.stderr,
+				display: true,
+			},
+			{ deliverAs: "followUp", triggerTurn: true },
+		);
+	});
+}

package/hooks/claude-hooks.json

@@ -0,0 +1,28 @@
+{
+  "description": "Surface local STDD task state with the bundled runtime when the repository contains .stdd.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/scripts/stdd-hook.mjs\" session",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/scripts/stdd-hook.mjs\" stop-claude",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/codex-hooks.json

@@ -0,0 +1,28 @@
+{
+  "description": "Surface local STDD task state with the plugin's bundled runtime when the repository contains .stdd.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/scripts/stdd-hook.mjs\" session",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PLUGIN_ROOT/scripts/stdd-hook.mjs\" stop",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@stdd/plugin",
+  "version": "0.9.0",
+  "description": "Universal STDD workflow skills and lifecycle integration for Codex, Claude Code, and Pi",
+  "type": "module",
+  "license": "MIT",
+  "author": "Azamat Almazbek uulu",
+  "keywords": [
+    "stdd",
+    "pi-package",
+    "codex-plugin",
+    "claude-code-plugin"
+  ],
+  "files": [
+    ".codex-plugin/",
+    ".claude-plugin/",
+    "extensions/",
+    "hooks/",
+    "scripts/",
+    "skills/",
+    "runtime/",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ],
+    "extensions": [
+      "./extensions/stdd.mjs"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vsem-azamat/stdd.git",
+    "directory": "plugins/stdd"
+  }
+}

package/runtime/adapters/README.md

@@ -0,0 +1,158 @@
+# Adapters
+
+Playbooks are agent-neutral markdown with frontmatter (`name`, `description`,
+`when`). Adapters compile them into what each agent consumes. `stdd init`
+runs the adapters; re-run it after upgrading stdd to refresh the output.
+
+## Common output
+
+Every init installs `.stdd/` into the target repo:
+
+```
+.stdd/
+├── method.md          # the STDD contract plus the repository-policy preamble
+├── playbooks/         # agent-neutral playbooks
+├── config.json        # stdd check configuration
+└── manifest.json      # generated-file hashes and stdd version
+```
+
+The generated method, playbooks, config, and manifest under `.stdd/` are
+committed methodology. Per-checkout `.stdd/ledger.jsonl` and
+`.stdd/plan.md` are working artifacts and stay ignored by default. The
+user-owned `projectLog.enabled` policy is compiled into both the installed
+method preamble and each agent's managed routing: enabled keeps the default
+authority-aware retrieval rule; disabled explicitly forbids creating or
+searching a project log.
+
+A plain `init` does not add a package dependency or CI adapter. The universal
+Codex/Claude/Pi bundle carries its own version-aligned lifecycle runtime, so an
+adopting repository needs only `.stdd/` and no local `@stdd/cli`.
+
+Install `@stdd/cli` as an exact project development dependency only when the
+repository itself owns generated pre-push/session/stop hooks or imports the
+JavaScript SDK. That generated automation uses `npm exec --offline
+--package=@stdd/cli@<generated-version> -- stdd`, resolving the scoped package
+offline and never falling back to an unscoped registry package. This
+repository's own dogfood output runs its checked-out `cli/stdd.mjs` directly
+through the git root, so testing an unpublished source version never depends
+on npm cache state.
+
+## claude (Claude Code)
+
+Writes one skill per playbook to `.claude/skills/<name>/SKILL.md`:
+frontmatter maps `name` directly; `description` carries the playbook's
+description plus its `when:` line ("… Use when: …"), because the
+description is the only always-visible routing surface — a trigger
+condition that lives only in the body is invisible at the moment the
+agent picks its next action. The body is the playbook body. Skills are
+self-contained copies — regenerate, never hand-edit. A short managed block in
+`CLAUDE.md` carries only always-on invariants and points to the method; its
+generated source is `.stdd/CLAUDE-snippet.md`.
+
+## codex
+
+Writes the same skill contract to `.agents/skills/<name>/SKILL.md`. Codex can
+select a skill from its description or the user can invoke it as `$<name>`.
+The adapter also writes `.stdd/AGENTS-snippet.md` and maintains the repo's
+`AGENTS.md` in place. The snippet is written between
+`stdd:begin`/`stdd:end` marker comments; content outside the markers is never
+touched. `AGENTS.md` is user-owned and never manifest-tracked.
+
+## pi
+
+Pi natively discovers the Agent Skills standard registry under
+`.agents/skills/`, so its adapter deliberately shares those generated skill
+files with Codex. Both hosts resolve the cross-CLI reviewer token to Claude and
+therefore produce byte-identical skills; selecting both does not create a
+duplicate registry. Pi exposes them as `/skill:<name>`.
+
+Pi's always-on router is different and stays host-local:
+`.pi/APPEND_SYSTEM.md` carries the managed STDD section with `/skill:` routing,
+while `.stdd/PI-snippet.md` is its generated source. Using Pi's append-system
+file avoids a last-writer-wins conflict with Codex's managed `AGENTS.md`
+section.
+
+## Lifecycle hooks
+
+`--session-hook` and `--stop-hook` target every selected native agent:
+
+- Claude: `.claude/settings.json`, with one `SessionStart` hook for
+  `startup|resume|clear|compact` and optional `Stop`;
+- Codex: `.codex/hooks.json`, with one `SessionStart` hook for
+  `startup|resume|clear|compact` and optional `Stop`.
+- Pi: `.pi/extensions/stdd.js`, with `session_start` plus `session_compact`
+  restore handlers and an optional `agent_settled` gate.
+
+Session hooks run only `stdd status --local`. Stop hooks use an
+agent-specific output protocol over the same `status --gate` judgment.
+Generated hooks never contain the full method or perform network work. On
+re-init, the `compact` source is the single context-restoration path: older
+managed Claude `PostCompact` entries are removed, while unrelated user hooks
+are preserved.
+
+Pi does not expose a pre-stop veto. When its gate reports broken review claims,
+the extension queues one corrective follow-up model turn and then fails open;
+it never creates an unbounded continuation loop. A conflicting user-owned
+`.pi/extensions/stdd.js` is not overwritten.
+
+## CI
+
+CI adapters only transport provider state into portable CLI commands:
+
+- GitHub writes `.github/workflows/stdd.yml`;
+- GitLab writes `.gitlab/stdd.gitlab-ci.yml`; same-project MRs authenticate
+  with `CI_JOB_TOKEN`, while a fork source project must be on the target's
+  CI job-token allowlist. A trusted controlled fork may instead provide a
+  masked and hidden `STDD_GITLAB_READ_API_TOKEN` scoped to target-project
+  `read_api`; target secrets must never be exposed to untrusted fork code;
+- generic prints the `check` and `check-pr` command contract without writing
+  provider configuration.
+
+The public SDK exposes the built-in adapter registry and render functions so
+other packages can add a host without importing `cli/` internals.
+`defineAgentAdapter()` returns an adapter object accepted directly by
+`renderAgentInstructions()`; registration in the immutable built-in registry
+is not required for third-party composition.
+
+Host-dependent commands stay as renderer tokens in the shared playbook source.
+When the `crossCli` block is active, the agent adapter resolves its reviewer
+token to another native host: Claude skills name `--via codex`, while Codex
+and Pi skills name `--via claude`. The first selected native host is the driver
+for the repository-level `review.via` default, so a cross-CLI init records its
+opposite; each host skill still names its own explicit override. A profile
+without any dispatch route removes the `[review:]` tag and every review
+command — it never substitutes a manual self-review.
+
+The profile-agnostic universal bundle is built with the conservative default
+capabilities (`subagents` on, `crossCli` off). Its planning skill names
+`--via subagent`; it never names a cross-CLI reviewer, emits a renderer token,
+or falls back to manual self-review.
+
+## Plugin distribution
+
+`plugins/stdd/` is one generated distribution for Codex, Claude Code, and Pi.
+Codex and Claude Code consume host-native manifests and protocol-specific
+command-hook metadata backed by one helper; Pi consumes the root package
+manifest, shared skills, and a package extension. `scripts/build-plugin.mjs` regenerates skills from
+`playbooks/`, the Pi lifecycle extension from its maintained source, and
+runtime files from the CLI package's supported distribution surface. Generated
+output is never an independent source.
+
+Rebuild validates and version-aligns every host manifest, removes deleted or
+renamed skills, repairs changed extension/runtime bytes, and rejects stale
+extra output paths. Every lifecycle adapter acts only when it finds an adopting
+repository with `.stdd/`, then calls the shared bundled runtime. No
+repository-local npm package is required. Session failures report fixed
+update-or-reinitialize guidance outside model context; Stop/gate failures stay
+fail-open and never forward arbitrary child output.
+
+## Design rules for adapters
+
+- One source of truth: adapters copy or point, never fork playbook content.
+- Always-on instructions contain invariants and routing only; detailed
+  workflows live in lazy skills.
+- No agent-specific incantations inside `playbooks/` — if an agent needs
+  special framing, that framing lives in the adapter.
+- Provider YAML owns transport, never method semantics.
+- Calm imperative prose. No all-caps compliance shouting: if a rule needs
+  shouting to be followed, it needs a `stdd check` rule instead.