Add surveys.

Author: johnteee

reflective-prompt-library/PROJECT_KNOWLEDGE.md

@@ -87,6 +87,7 @@ deferred promotions are recurrence-gated — see [panel backlog](plans/multi-age
 > not duplicated here; this is a map, not an archive. Mechanical panel rounds
 > are rolled up; the round-by-round trail lives in the panel record.
 
+- 2026-07-11 Survey implementation (user-approved) — executed the survey-derived plans through their gates: Agent Skills spec conformance migrated (skills-ref 0.1.1 rejected all 11 skills' top-level governance fields, observed; fields moved under `metadata:`, packs gained `compatibility`, 11/11 now validate; `validate_links.py` enforces the spec whitelist with negative tests); loop-pack demotion trigger evaluated **not fired** (`/goal` is a model-judge stop, below the deterministic bar) with a Host-Native Alternatives note in the loop skill; pack usage log opened with zero-state; R8-compliant holdout expansion adopted H1/H2/H5/H6 with pre-tune observations (H3/H4 deferred as genuinely ambiguous) raising floors to ROUTE-002 42/118 and ROUTE-003 21/73 with four new router boundaries at 100%; SKILL_INSTALLATION gained Codex tiers, Gemini CLI (smoke-verified), spec troubleshooting, and host-side review-gate mapping → [skills ledger](plans/skills-surface-plan-2026-07-11.md), [demotion record](plans/flow-pack-demotion-evaluation-2026-07-11.md), [usage log](plans/flow-pack-usage-log.md), [routing ledger](plans/routing-holdout-plan-2026-07-11.md)
 - 2026-07-11 Skills/flow-control landscape survey and domain planning — primary-doc survey found the SKILL.md format now a 30+-host open standard (`.agents/skills` cross-host path, spec validator, context budgets) and host-native loop surfaces shipped (`/goal` model-judge loop, `/loop`, script Stop hooks, `/batch`); one prior `[search-derived]` claim confirmed (native goal mode), AgentKit wind-down kept `unknown`; three gated domain plans opened (skills-surface S1–S6, flow-control F1–F4 incl. the T4 demotion-trigger evaluation, routing-holdout H1–H6 under R8) with no adoption, demotion, or router change decided → [survey](../surveys/agent-skills-flow-control-survey-2026-07-11.md), [skills plan](plans/skills-surface-plan-2026-07-11.md), [flow roadmap](plans/flow-control-roadmap-2026-07-11.md), [routing plan](plans/routing-holdout-plan-2026-07-11.md)
 - 2026-07-11 Whole-project plan and roadmap consolidation — the open-work register (T1–T3, P6/P7/P12/P13/P15, M4–M7, E2, D4, June backlog) and all standing gates consolidated into two active, non-authoritative planning artifacts after the four earlier plans were retired as historical records; no new rules or gates introduced → [plan](plans/whole-project-plan-2026-07-11.md), [roadmap](plans/whole-project-roadmap-2026-07-11.md)
 - 2026-07-11 Governance necessity consensus — six-lens review distinguished the load-bearing bounded core routing set from the historical cardinalities nine core / two packs; explicit Human Review adopted N2–N7, N9, and N10: binding domain-pack admission, canonical two-tier pointers, core-only install defaults with opt-in packs, structural pack guards, cardinality clarification, Adoption Guard Closure, R8 canonical pointer, and required per-skill license. N8 ratio replacement was rejected; pack merge (P6) and router integration (P7) remain trigger-gated; no pack entered core routing → [panel record](plans/governance-necessity-panel-record-2026-07-11.md)

reflective-prompt-library/SKILL_INSTALLATION.md

@@ -4,7 +4,7 @@ Language: English | [繁體中文](SKILL_INSTALLATION.zh-TW.md)
 
 Last verified: 2026-07-11
 
-This guide explains how to install the nine TeaPrompt core workflow skills—and, when explicitly wanted, the optional registered domain packs—into Claude Code, Codex, Cursor, Google Antigravity CLI / IDE, and OpenCode.
+This guide explains how to install the nine TeaPrompt core workflow skills—and, when explicitly wanted, the optional registered domain packs—into Claude Code, Codex, Cursor, Gemini CLI, Google Antigravity CLI / IDE, and OpenCode.
 
 The source skills live here:
 
@@ -212,6 +212,12 @@ Codex-native install uses `$CODEX_HOME/skills`; when `CODEX_HOME` is unset, the
 ~/.codex/skills/<skill-name>/SKILL.md
 ```
 
+Current Codex docs (checked 2026-07-11) additionally document Agent Skills tiers:
+repository `.agents/skills` scanned from the working directory up to the repo
+root, user `$HOME/.agents/skills`, and admin `/etc/codex/skills`; `$skill-installer`
+installs curated skills. The `~/.codex/skills` path below is the Codex-native
+location that predates those tiers.
+
 Personal Codex install (copy):
 
 ```bash
@@ -246,6 +252,14 @@ install_core_skills_symlink .agents/skills
 
 Use `.agents/skills` when you want one project-local skill location that can also be read by other Agent Skills-compatible tools. If your Codex build does not show these skills, use the Codex-native `~/.codex/skills` path.
 
+User-scope shared option (works for every `.agents/skills`-aware host):
+
+```bash
+install_core_skills_copy "$HOME/.agents/skills"
+# or
+install_core_skills_symlink "$HOME/.agents/skills"
+```
+
 ## Cursor
 
 Cursor has two relevant instruction surfaces:
@@ -321,6 +335,42 @@ Prefer:
 
 This is not a native skill install, but it preserves the workflow behavior in Cursor's official Rules system.
 
+## Gemini CLI
+
+Gemini CLI implements the Agent Skills standard with these discovery tiers
+(lowest to highest precedence: built-in, extension, user, workspace; within a
+tier the `.agents/skills` alias beats `.gemini/skills`):
+
+| Scope | Path |
+| --- | --- |
+| Workspace | `.gemini/skills/<skill-name>/SKILL.md` or `.agents/skills/<skill-name>/SKILL.md` |
+| User | `~/.gemini/skills/<skill-name>/SKILL.md` or `~/.agents/skills/<skill-name>/SKILL.md` |
+
+The shared helpers work as for other hosts:
+
+```bash
+install_core_skills_copy .agents/skills          # workspace
+install_core_skills_symlink "$HOME/.agents/skills"  # user
+```
+
+Gemini CLI also manages skills natively:
+
+```bash
+gemini skills list --all
+gemini skills link "$(pwd)/reflective-prompt-library/skills/reflective-brief" --scope user
+gemini skills install <git-url> --path reflective-prompt-library/skills/reflective-brief --consent
+gemini skills uninstall reflective-brief --scope user
+```
+
+Notes (verified on macOS, 2026-07-11): `gemini skills list` reads
+`~/.agents/skills`; `link` asks an interactive security confirmation (`install`
+accepts `--consent` to skip it); duplicate names across tiers are reported as
+conflicts with the higher tier winning; skill activation in-session shows a
+consent prompt naming the skill and the directory it gains access to. Google
+has announced that unpaid-tier and Google One users' Gemini CLI is being
+replaced by Antigravity CLI (see the next section), so free-tier users should
+prefer the Antigravity paths.
+
 ## Antigravity CLI / Antigravity IDE
 
 Antigravity supports Agent Skills in these locations:
@@ -480,6 +530,11 @@ Use symlink installs only for your own workspace, not as the default team instal
 6. Ask the host to list available skills.
 7. If a skill triggers too often, make the `description` narrower.
 8. If a skill never triggers, make the `description` more explicit and include likely user phrases.
+9. Validate spec conformance: `python3 reflective-prompt-library/plans/validate_links.py`
+   in this repo, or the reference tool (`pip install skills-ref`, then
+   `agentskills validate <skill-dir>`). Only `name`, `description`, `license`,
+   `compatibility`, `metadata`, and `allowed-tools` are spec-valid top-level
+   frontmatter fields; TeaPrompt's governance fields live under `metadata:`.
 
 ## Security Notes
 
@@ -489,11 +544,29 @@ Use symlink installs only for your own workspace, not as the default team instal
 - Do not grant tool permissions or hooks unless the skill genuinely needs them.
 - Keep high-risk workflows behind `reflective-risk`.
 
+### Enforcing TeaPrompt's review gates host-side
+
+TeaPrompt skills declare intent via `metadata.human_review_required`; hosts, not
+TeaPrompt, enforce it. When installing `reflective-risk` or `flow-loop-harness`
+(both `human_review_required: true`), map the declaration to your host's
+invocation control:
+
+| Host | Mechanism |
+| --- | --- |
+| Claude Code | add `disable-model-invocation: true` to your installed copy so only explicit `/skill-name` runs it |
+| Codex | `agents/openai.yaml` with `policy.allow_implicit_invocation: false` |
+| Gemini CLI | activation already shows a per-skill consent prompt; keep it enabled |
+
+These are host features documented at the sources below; TeaPrompt cannot
+verify or enforce them (runtime-trust boundary).
+
 ## Sources
 
+- Agent Skills specification: https://agentskills.io/specification
 - Claude Code skills docs: https://code.claude.com/docs/en/skills
+- Codex skills docs: https://learn.chatgpt.com/docs/build-skills
+- Gemini CLI skills docs: https://geminicli.com/docs/cli/skills/
 - OpenAI skills repository: https://github.com/openai/skills
-- OpenAI Codex use cases: https://developers.openai.com/codex/use-cases
 - Google Antigravity skills docs: https://antigravity.google/docs/skills
 - OpenCode skills docs: https://opencode.ai/docs/skills
 - Cursor rules docs: https://docs.cursor.com/en/context

reflective-prompt-library/SKILL_INSTALLATION.zh-TW.md

@@ -4,12 +4,13 @@ Language: [English](SKILL_INSTALLATION.md) | 繁體中文
 
 # Skills 安裝指南
 
-最後確認日期：2026-07-06
+最後確認日期：2026-07-11
 
 本文件說明如何把 TeaPrompt 的 workflow skills 安裝到：
 
 - Claude Code
 - Codex
+- Gemini CLI
 - Cursor
 - Antigravity CLI / IDE
 - OpenCode
@@ -57,6 +58,18 @@ mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
 cp -R reflective-prompt-library/skills/reflective-* "${CODEX_HOME:-$HOME/.codex}/skills/"
 ```
 
+## Gemini CLI
+
+- 工作區層：`.gemini/skills/` 或 `.agents/skills/`（`.agents/skills` 優先）
+- 使用者層：`~/.gemini/skills/` 或 `~/.agents/skills/`
+
+```bash
+gemini skills link "$(pwd)/reflective-prompt-library/skills/reflective-brief" --scope user
+gemini skills list --all
+```
+
+啟用 skill 時會出現安全確認提示；免費層 Gemini CLI 將由 Antigravity CLI 取代（詳見英文版）。
+
 ## Cursor
 
 建議優先使用：