Openspec AwareSAFE

The Agent Harness for AI-Human Collaboration, inspired by the AI-DLC (AI-Driven Development Lifecycle)

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: openspec-aware
description: OpenSpec-mode authoring for Chorus PM workflows in Codex. The default whenever OpenSpec is usable; consumes the resolved `## Spec Mode` (never re-detects). Scaffolds `openspec/changes/<slug>/` on disk, and mirrors Markdown files into Chorus document drafts via `chorus mcp call --arg-file` (bash `chorus-mcp-call.sh` wrapper as fallback). Required reading for the proposal, develop, and yolo skills. When OpenSpec is not the resolved mode, this skill no-ops and the caller follows the resolved mode (spec-lite or free-form).
license: AGPL-3.0
metadata:
  author: chorus
  version: "0.22.1"
  category: project-management
  mcp_server: chorus
---

# OpenSpec-aware Authoring (Codex plugin)

This skill is a **shared sub-procedure** invoked by the Chorus stage skills (proposal, develop, yolo) whenever the user wants spec-driven authoring through the [OpenSpec CLI](https://github.com/Fission-AI/OpenSpec). It is opt-in:

- Activates when the resolved spec mode is a **usable OpenSpec** (see §1): `CHORUS_SPEC_MODE=openspec` *or* unset, **and** `CHORUS_OPENSPEC_MODE` not `off`, an `openspec/` directory at the project root, and the `openspec` CLI on `PATH`.
- Otherwise the calling skill follows the resolved `SPEC_MODE` — **spec-lite** (the default when OpenSpec isn't usable) or free-form (`=off`).

> **See also — `spec-lite` (the lightweight fallback):** OpenSpec (this skill) stays the default whenever it is usable. When OpenSpec is absent or disabled — or `CHORUS_SPEC_MODE=lite` — the mode resolves to **spec-lite**: a durable local `.chorus/specs/<slug>/spec.md` (never synced) + per-change dated folders `<slug>/<YYYY-MM-DD>-<change-slug>/` of Chorus-typed docs mirrored 1:1 into Chorus via the same `--arg-file` transport. See the `spec-lite` skill.

When you reach a point in proposal / develop / yolo where this skill is referenced, **read the value of `CHORUS_OPENSPEC_ACTIVE` from the SessionStart context** (see §1) and branch on it. Do not re-run the detection block — the SessionStart hook has already done it once for this session.

> **Codex specifics:** the preferred document-mirror transport is the `chorus` CLI (`chorus mcp call ... --arg-file content=<file>`, §2 Rule 1). The bundled `chorus-mcp-call.sh` wrapper is the **fallback** when `chorus` is not on `PATH`: it is Codex's stateless MCP wrapper, located at `$CHORUS_PLUGIN_DIR/hooks/chorus-mcp-call.sh` after resolving `$CHORUS_PLUGIN_DIR` with §2.1, and is invoked as `chorus-mcp-call.sh <TOOL_NAME> '<JSON_ARGUMENTS>'` — no `mcp-tool` subcommand (unlike the Claude Code variant). The Codex port has no on-disk session state; every call is self-contained.
>
> The helper snippets below are Bash snippets. Codex executes shell commands through the user's configured shell, which may be `zsh`; run multi-line helper blocks under `bash -lc` (or save them as a `.sh` script with a Bash shebang) before using `json_encode_file` / `chorus_check_response`.

---

## §1. Detection — already done at SessionStart

The Chorus plugin's SessionStart hook (`hooks/on-session-start.sh`, via the shared `hooks/resolve-spec-mode.sh`) resolves the spec mode once when the session opens and writes a `## Spec Mode` section into the developer-message context; when the resolved mode is a usable OpenSpec it also carries a `CHORUS_OPENSPEC_ACTIVE=1` line. That happens only when `CHORUS_SPEC_MODE` is `openspec` **or unset**, **and all three** of these hold:

1. `CHORUS_OPENSPEC_MODE` is **not** set to `off` (explicit opt-out wins).
2. The project root contains an `openspec/` directory (i.e. someone ran `openspec init` here).
3. The `openspec` CLI is on `PATH`.

Both signals (2) and (3) are required because the OpenSpec authoring path needs the working directory **and** the CLI — having one without the other leaves the workflow unrunnable. If signal (2) holds but (3) does not, the SessionStart hook surfaces a "OpenSpec repo detected — install with: `npm i -g @fission-ai/openspec`" hint to the user; the agent should pass this through if asked rather than silently choosing free-form.

### How to read the value

You should already see something like this in your context (look for the `## Spec Mode` section near the top of the developer message):

```
## Spec Mode

CHORUS_SPEC_MODE=openspec (default — openspec/ directory + openspec CLI both present)

CHORUS_OPENSPEC_ACTIVE=1 (openspec/ directory + openspec CLI both present)
```

or (resolved to lite / off — no `CHORUS_OPENSPEC_ACTIVE=1` line):

```
## Spec Mode

CHORUS_SPEC_MODE=lite (default — OpenSpec not usable: no openspec/ directory at /path/to/repo/openspec)
```

Branch:

- `CHORUS_OPENSPEC_ACTIVE=1` line present → follow §3 (OpenSpec authoring).
- No `CHORUS_OPENSPEC_ACTIVE=1` line → this skill is a no-op; return to the caller, which follows the resolved `SPEC_MODE` (**spec-lite** or free-form). **Do not** scaffold `openspec/changes/`. **Do not** add the slug line to the proposal description.

### Manual fallback

If you're in a sub-agent that did not see the `## Spec Mode` context (e.g. spawned mid-session with the parent's context not forwarded), **do not hand-roll the detection** — source the *same* resolver the hook uses, so there is one computation of the mode (Codex hooks run from `$PWD`, which the resolver uses as `PROJECT_ROOT`):

```bash
# 1. Resolve $CHORUS_PLUGIN_DIR first (per §2.1). 2. Then source the shared resolver:
. "$CHORUS_PLUGIN_DIR/hooks/resolve-spec-mode.sh"
# sets SPEC_MODE (lite|openspec|off), SPEC_FAIL (non-empty ⇒ halt), CHORUS_OPENSPEC_ACTIVE (1 only for a usable openspec)
```

Then: if `SPEC_FAIL` is non-empty, halt and surface it; if `CHORUS_OPENSPEC_ACTIVE=1` follow §3; otherwise no-op — return to the caller per the resolved `SPEC_MODE`. **Never re-derive the rule inline** — the hook/helper is the single source of truth. If you genuinely cannot locate the helper, set `CHORUS_SPEC_MODE` explicitly and re-launch rather than guessing.

---

## §2. Wrapper setup and non-n

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

.agents/skills

Gates applied: no_behavioural_pass.