feat(opencode): skill parity — generate the tree from canonical ctx skills

.context/LEARNINGS.md

@@ -1,5 +1,16 @@
 # Learnings
 
+<!-- INDEX:START -->
+| Date | Learning |
+|----|--------|
+| 2026-08-19 | Exact zensical pin does not prevent site/ churn: underlying libs drift |
+| 2026-07-25 | Using the proprietary sibling repo as design evidence leaks its internals into tracked files |
+| 2026-07-25 | Skill and doc examples of a serialized structure must round-trip through the real parser |
+| 2026-07-25 | A guard derived from a capability accessor silently lifts when the accessor is extended |
+| 2026-07-19 | The disclosure parser is a deliberately dumb line-scanner (skips <!-- --> comments, not code fences) |
+| 2026-07-19 | Measurement gates surface a real bug in every disclosure milestone |
+<!-- INDEX:END -->
+
 <!--
 UPDATE WHEN:
 - Discover a gotcha, bug, or unexpected behavior
@@ -15,6 +26,16 @@ DO NOT UPDATE FOR:
 -->
 
 
+## [2026-08-19-221024] Exact zensical pin does not prevent site/ churn: underlying libs drift
+
+**Context**: make site with the exactly-pinned zensical 0.0.51 (fresh pipx install) still churned 100+ committed site/ pages with HTML-entity encoding differences (&#39; vs ') untouched by the docs change — the pin fixes the generator version, not its Python dependency tree.
+
+**Lesson**: The generator pin is necessary but not sufficient for reproducible site builds; markdown-renderer deps under zensical encode entities differently across environments, and CI never rebuilds the site to catch it.
+
+**Application**: After make site, review git status -- site/ and commit ONLY pages your docs change affects (plus search.json); restore the rest. If full-site churn is ever intended, do it as its own chore commit.
+
+---
+
 ## [2026-07-25-124457] Using the proprietary sibling repo as design evidence leaks its internals into tracked files
 
 **Context**: While deciding the pd-m4 add-path shape, I read the sibling repo's convention file to settle the question, then quoted its guide text and attributed the decision to it in a tracked plan file. An unrelated build warning prompted the sweep that caught it.

.context/TASKS.md

@@ -2617,6 +2617,10 @@ shipped.
 
 ### Misc
 
+- [ ] Full-site regen as standalone chore: make site with pinned zensical 0.0.51 rewrites 100+ pages with HTML-entity encoding differences (lib drift beneath the pin). Decide the canonical encoding, regenerate the whole site/ in one chore commit, and consider pinning zensical's dep tree (pipx runpip freeze) so future builds are reproducible. See LEARNINGS 2026-08-19 zensical-pin entry. #priority:medium #session:45d47165 #branch:feat/158-opencode-skill-parity #commit:f3f73875 #added:2026-08-19-221230
+
+- [x] Regenerate site/ for docs/home/opencode.md (OpenCode skill parity, issue #158): zensical not installed on this machine, so make site could not run; run make site on a machine with the pinned zensical and commit the site/ churn #priority:medium #session:45d47165 #branch:feat/158-opencode-skill-parity #commit:ce5a8328 #added:2026-08-19-211552
+
 - [x] [Epic F] ctx index: docs (remove reindex, add ctx index) + final build/lint/test gate (T23-T24). Plan: specs/plans/computed-index-projection.md #session:75be038e #branch:main #commit:f382bee7 #added:2026-07-14-054851
 
 - [x] [Epic E] ctx index: strip INDEX blocks from .context files, remove marker constants, add guards (T19-T22). Plan: specs/plans/computed-index-projection.md #session:75be038e #branch:main #commit:f382bee7 #added:2026-07-14-054851

Makefile

@@ -6,7 +6,7 @@
 clean all release build-all help \
 test-coverage smoke site site-guard site-feed site-serve site-serve-lan site-setup audit check plugin-reload \
 journal journal-serve journal-serve-lan gpg-fix gpg-test register-mcp reinstall check-tools \
-sync-version check-version-sync sync-why check-why sync-copilot-skills check-copilot-skills sync-steering check-steering gemini-search \
+sync-version check-version-sync sync-why check-why sync-copilot-skills check-copilot-skills sync-opencode-skills check-opencode-skills sync-steering check-steering gemini-search \
 gitnexus-version gitnexus-update gitnexus-index gitnexus-mcp strip-gitnexus install-ctxctl reinstall-ctxctl
 
 # Default binary name and output
@@ -35,8 +35,8 @@ sync-version:
 	mv internal/assets/claude/.claude-plugin/plugin.json.tmp internal/assets/claude/.claude-plugin/plugin.json; \
 	echo "Plugin version synced to $$V"
 
-## build: Build for current platform (syncs version + embedded docs + copilot skills first)
-build: sync-version sync-why sync-copilot-skills
+## build: Build for current platform (syncs version + embedded docs + copilot/opencode skills first)
+build: sync-version sync-why sync-copilot-skills sync-opencode-skills
 	CGO_ENABLED=0 go build -ldflags="-X github.com/ActiveMemory/ctx/internal/bootstrap.version=$$(cat VERSION | tr -d '[:space:]')" -o $(OUTPUT) ./cmd/ctx
 
 ## ctxctl: Build the maintainer-only ctxctl binary (audit channel) into dist/
@@ -173,6 +173,8 @@ audit:
 	@$(MAKE) --no-print-directory check-why
 	@echo "==> Checking Copilot skills freshness..."
 	@$(MAKE) --no-print-directory check-copilot-skills
+	@echo "==> Checking OpenCode skills freshness..."
+	@$(MAKE) --no-print-directory check-opencode-skills
 	@echo "==> Checking steering outputs freshness..."
 	@$(MAKE) --no-print-directory check-steering
 	@echo "==> Running tests..."
@@ -375,6 +377,10 @@ check-version-sync:
 sync-copilot-skills:
 	@./hack/sync-copilot-skills.sh
 
+## sync-opencode-skills: Sync OpenCode skills from canonical ctx skills
+sync-opencode-skills:
+	@./hack/sync-opencode-skills.sh
+
 ## sync-steering: Regenerate tool-native steering outputs from .context/steering
 sync-steering:
 	@CGO_ENABLED=0 go run ./cmd/ctx steering sync --all
@@ -404,6 +410,21 @@ check-copilot-skills:
 	rm -rf "$$TMPDIR"; \
 	echo "Copilot CLI skills are in sync."
 
+## check-opencode-skills: Verify OpenCode skills match ctx source skills
+check-opencode-skills:
+	@TMPDIR=$$(mktemp -d) && \
+	cp -r internal/assets/integrations/opencode/skills/ "$$TMPDIR/before" && \
+	./hack/sync-opencode-skills.sh > /dev/null && \
+	if ! diff -rq "$$TMPDIR/before" internal/assets/integrations/opencode/skills/ > /dev/null 2>&1; then \
+		echo "FAIL: OpenCode skills are stale — run 'make sync-opencode-skills'"; \
+		diff -rq "$$TMPDIR/before" internal/assets/integrations/opencode/skills/ || true; \
+		cp -r "$$TMPDIR/before/"* internal/assets/integrations/opencode/skills/; \
+		rm -rf "$$TMPDIR"; \
+		exit 1; \
+	fi; \
+	rm -rf "$$TMPDIR"; \
+	echo "OpenCode skills are in sync."
+
 ## check-why: Verify embedded why docs match source docs
 check-why:
 	@diff -q docs/index.md internal/assets/why/manifesto.md || (echo "FAIL: manifesto.md is stale — run 'make sync-why'" && exit 1)

docs/home/opencode.md

@@ -112,14 +112,48 @@ unnecessary.
 
 ## Slash Commands
 
-Four skills are available as slash commands:
+The skills are generated from the canonical ctx skill tree at build
+time, so their names and behavior match the Claude Code integration
+one-to-one.
+
+Session lifecycle:
 
 | Command | When to use |
 |---------|-------------|
 | `/ctx-agent` | Load full context packet. Use at session start or when context feels stale. |
 | `/ctx-remember` | "Do you remember?"; reads tasks, decisions, learnings, and recent journal entries. Returns a structured readback. |
 | `/ctx-status` | Context summary at a glance: file count, token estimate, recent activity. |
 | `/ctx-wrap-up` | End-of-session ceremony. Captures learnings, decisions, conventions, and outstanding tasks to `.context/` files. |
+| `/ctx-handover` | Write a per-session handover note for the next agent (invoked by `/ctx-wrap-up`). |
+
+The planning arc from the
+[Design Before Coding](../recipes/design-before-coding.md)
+recipe:
+
+| Command | When to use |
+|---------|-------------|
+| `/ctx-brainstorm` | Design before implementation: turn a vague idea into a validated design. |
+| `/ctx-plan` | Stress-test a plan through adversarial interview; produces a debated brief. |
+| `/ctx-spec` | Scaffold a feature spec from the project template. |
+| `/ctx-task-out` | Decompose a committed spec into a per-milestone implementation plan. |
+| `/ctx-implement` | Execute a plan step-by-step with verification. |
+
+Capture:
+
+| Command | When to use |
+|---------|-------------|
+| `/ctx-task-add` | Add a task when follow-up work is identified. |
+| `/ctx-decision-add` | Record an architectural decision with rationale. |
+
+Knowledge-base editorial pipeline (active when `.context/kb/` exists):
+
+| Command | When to use |
+|---------|-------------|
+| `/ctx-kb-ingest` | Editorial knowledge-ingestion pass over supplied sources. |
+| `/ctx-kb-ask` | Q&A grounded in the existing kb. |
+| `/ctx-kb-note` | Park a finding for the next ingest pass. |
+| `/ctx-kb-site-review` | Mechanical structural audit of the kb. |
+| `/ctx-kb-ground` | Read-only freshness audit over the kb's tracked sources. |
 
 You don't need to use these often. The plugin handles most context loading
 automatically. These are for when you want explicit control.

hack/sync-opencode-skills.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+
+#   /    ctx:                         https://ctx.ist
+# ,'`./    do you remember?
+# `.,'\
+#   \    Copyright 2026-present Context contributors.
+#                 SPDX-License-Identifier: Apache-2.0
+
+# sync-opencode-skills.sh — sync OpenCode skills from canonical ctx skills.
+#
+# ctx skills (internal/assets/claude/skills/) are the source of truth.
+# OpenCode skills (internal/assets/integrations/opencode/skills/) are
+# generated from them with the `allowed-tools` frontmatter key stripped
+# (Claude Code-specific, not applicable to OpenCode).
+#
+# Enrollment is opt-in by directory presence: a skill syncs iff its
+# directory exists under the OpenCode tree. Skills that exist only in
+# the OpenCode directory (no ctx counterpart) are left untouched.
+
+set -euo pipefail
+
+CTX_SKILLS="internal/assets/claude/skills"
+OPENCODE_SKILLS="internal/assets/integrations/opencode/skills"
+
+synced=0
+skipped=0
+
+for opencode_dir in "$OPENCODE_SKILLS"/*/; do
+  skill_name=$(basename "$opencode_dir")
+  ctx_skill="$CTX_SKILLS/$skill_name/SKILL.md"
+  opencode_skill="$opencode_dir/SKILL.md"
+
+  if [ ! -f "$ctx_skill" ]; then
+    # No ctx counterpart — OpenCode-only skill, leave untouched.
+    skipped=$((skipped + 1))
+    continue
+  fi
+
+  # Strip `allowed-tools:` line from frontmatter (Claude Code-specific).
+  sed '/^allowed-tools:/d' "$ctx_skill" > "$opencode_skill"
+  synced=$((synced + 1))
+done
+
+echo "OpenCode skills synced: $synced updated, $skipped OpenCode-only (unchanged)."

internal/assets/integrations/opencode/skills/ctx-agent/SKILL.md

@@ -13,7 +13,7 @@ Load the full context packet for AI consumption.
 
 ## When NOT to Use
 
-- The plugin hook already runs `ctx agent` on session start:
+- The PreToolUse hook already runs `ctx agent` automatically with a cooldown:
   you rarely need to invoke this manually
 - Don't run it just to "refresh" if you already have the context loaded in
   this session
@@ -27,3 +27,38 @@ any code.
 Confirm to the user: "I have read the required context files and I'm
 following project conventions." Read and confirm before beginning
 implementation.
+
+## Flags
+
+| Flag         | Default | Description                                       |
+|--------------|---------|---------------------------------------------------|
+| `--budget`   | 8000    | Token budget for context packet                   |
+| `--format`   | md      | Output format: `md` or `json`                     |
+| `--cooldown` | 10m     | Suppress repeated output within this duration     |
+| `--session`  | (none)  | Session ID for cooldown isolation (e.g., `$PPID`) |
+
+## Execution
+
+```bash
+ctx agent $ARGUMENTS
+```
+
+**Example: default load:**
+```bash
+ctx agent
+```
+
+**Example: smaller packet for limited contexts:**
+```bash
+ctx agent --budget 4000
+```
+
+**Example: with cooldown (how the PreToolUse hook invokes it):**
+```bash
+ctx agent --budget 4000 --session $PPID
+```
+
+**Example: JSON for programmatic use:**
+```bash
+ctx agent --format json --budget 8000
+```