diff --git a/AGENTS.md b/AGENTS.md index b41d6a9..4905a90 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,6 +25,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/README.ja.md b/README.ja.md index db4288b..156ca04 100644 --- a/README.ja.md +++ b/README.ja.md @@ -36,6 +36,14 @@ Codex、Claude Code、OpenCode向けのプロセス重視AIコーディング環 > この文書は `README.md` の日本語訳です。正本は英語版です。 +## 現在の公開スコープ + +Codex と Claude Code が現在の first-class setup target です。OpenCode と OpenClaw は optional/reference surface として残し、互換性維持に役立つ場合だけ既存文書を参照します。これらをデフォルトのセットアップ経路として扱わないでください。 + +## Private Project Skills + +auto-eva のような private project skill はこの public repository にコミットしません。実際のプロジェクト別 skill は、Codex 用の `~/.codex/skills` や Claude Code 用の `~/.claude/skills` などローカル runtime home に置きます。このリポジトリには templates and public-safe process guidance だけを置き、private access path、credential、auth state、browser profile、customer data、machine-specific trust setting は入れません。 + ## agent-bootstrap を使う理由 - Codex、Claude Code、OpenCodeごとに別々のプロンプトスタックを管理せず、1つの `superpowers` ベースのワークフローを共有できます。 diff --git a/README.ko.md b/README.ko.md index bea6585..74d7fe1 100644 --- a/README.ko.md +++ b/README.ko.md @@ -36,6 +36,14 @@ Codex, Claude Code, OpenCode를 위한 프로세스 중심 AI 코딩 환경 부 > 이 문서는 `README.md`의 한국어 번역본입니다. 기준 문서는 영어판입니다. +## 현재 공개 범위 + +Codex와 Claude Code가 현재 first-class setup target입니다. OpenCode와 OpenClaw는 optional/reference surface로 남겨 두며, 호환성 유지에 도움이 될 때만 기존 문서를 참고하고 기본 설정 경로로 취급하지 않습니다. + +## Private Project Skills + +auto-eva 같은 private project skill은 이 public repository에 커밋하지 않습니다. 실제 프로젝트별 skill은 Codex용 `~/.codex/skills`와 Claude Code용 `~/.claude/skills` 같은 로컬 runtime home에 둡니다. 이 레포에는 templates and public-safe process guidance만 남기고, private access path, credential, auth state, browser profile, customer data, machine-specific trust setting은 넣지 않습니다. + ## 왜 agent-bootstrap을 써야 하나? - Codex, Claude Code, OpenCode 각각에 따로 프롬프트 스택을 유지하지 않고, 하나의 `superpowers` 기반 워크플로우를 공유할 수 있습니다. diff --git a/README.md b/README.md index 036a067..acec558 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,14 @@ Bootstrap a process-first AI coding environment for Codex, Claude Code, and Open `agent-bootstrap` gives you a shared `superpowers` workflow, role-based subagents, token-efficient execution, and multilingual setup docs for modern AI coding tools. +## Current Public Focus + +Codex and Claude Code are the current first-class setup targets for this public repository. OpenCode and OpenClaw remain optional/reference surfaces: keep their existing docs only when they help preserve compatibility, but do not treat them as the default setup path. + +## Private Project Skills + +Do not commit private project skills such as auto-eva to this public repository. Keep actual project-specific skills in local runtime homes such as `~/.codex/skills` for Codex and `~/.claude/skills` for Claude Code. This repository should contain templates and public-safe process guidance, not private access paths, credentials, auth state, browser profiles, customer data, or machine-specific trust settings. + ## Why use agent-bootstrap? - Shared `superpowers` workflow across Codex, Claude Code, and OpenCode instead of maintaining separate prompt stacks for each tool. @@ -53,6 +61,7 @@ Use this repository as an operating guide, not only as an installer. - Install global defaults: use [docs/global-guardrail-setup.md](docs/global-guardrail-setup.md) to install the shared guardrails into Codex, Claude Code, or OpenCode user-level defaults. - Apply guardrails to a project: paste [prompts/apply-vibe-coding-guardrails.md](prompts/apply-vibe-coding-guardrails.md) into an agent session inside a target repository. - Start feature work inside a guarded project: paste [prompts/start-with-vibe-coding-guardrails.md](prompts/start-with-vibe-coding-guardrails.md) before asking for a feature, bugfix, or refactor. +- Review optional Codex skills: read [skills/README.md](skills/README.md) and [docs/codex-skills.md](docs/codex-skills.md), then use [prompts/setup-codex-skills.md](prompts/setup-codex-skills.md) when you want an agent to browse, compare, and install approved skills. - Update this bootstrap after repository changes: paste [prompts/update-agent-bootstrap.md](prompts/update-agent-bootstrap.md) after pulling new changes or when you want an agent to re-audit this repository. - Explain this repository's own structure: read [docs/agent-bootstrap-structure.md](docs/agent-bootstrap-structure.md) before editing shared prompts, installers, generated plugin output, or setup docs. @@ -123,6 +132,7 @@ Choose the scope first. Most failed agent setup work starts by configuring too m - `prompts/setup-claude-current-harness.md`: use inside Claude Code when the Claude plugin and shared role prompts should be set up. - `prompts/setup-opencode-current-harness.md`: use inside OpenCode when OpenCode should receive the generated agents and native plugin wiring. - `prompts/setup-shared-core.md`: use when the target environment is unclear and the safest answer is only the shared prompt/skills layer. +- `prompts/setup-codex-skills.md`: use when you want an agent to inspect this repository's optional Codex skill catalog, compare selected skills with `~/.codex/skills`, and install only approved skills. - `prompts/apply-vibe-coding-guardrails.md`: use in an application repository that needs structure maps, edge-case-first tests, dependency-boundary checks, and local project knowledge. - `prompts/start-with-vibe-coding-guardrails.md`: use for day-to-day feature, bugfix, or refactor work after a repository already has a project map and guardrail workflow. - `prompts/update-agent-bootstrap.md`: use for this repository when new changes need to be pulled, rendered, installed, audited, documented, and reviewed. @@ -203,6 +213,7 @@ These copy-paste prompts are the fastest way to keep another agent inside the in - Generic shared core setup: [prompts/setup-shared-core.md](prompts/setup-shared-core.md) - OpenClaw shared core only: [prompts/setup-openclaw-shared-core.md](prompts/setup-openclaw-shared-core.md) - OpenClaw ACP integration: [prompts/setup-openclaw-acp.md](prompts/setup-openclaw-acp.md) +- Optional Codex skill catalog setup: [prompts/setup-codex-skills.md](prompts/setup-codex-skills.md) - Apply vibe-coding guardrails to another repository: [prompts/apply-vibe-coding-guardrails.md](prompts/apply-vibe-coding-guardrails.md) - Start work with vibe-coding guardrails: [prompts/start-with-vibe-coding-guardrails.md](prompts/start-with-vibe-coding-guardrails.md) - Update this bootstrap after repository changes: [prompts/update-agent-bootstrap.md](prompts/update-agent-bootstrap.md) @@ -277,6 +288,8 @@ The intent is to reuse upstream `superpowers` instead of copying the skill libra - repository-level Claude marketplace entry - `plugins/process-first-agents/` - generated Claude plugin package +- `skills/` + - optional Codex skill catalog; see [docs/codex-skills.md](docs/codex-skills.md) - `scripts/render_claude_plugin.py` - rebuilds the Claude plugin package from the shared prompt corpus - `docs/` diff --git a/README.zh-CN.md b/README.zh-CN.md index 6056d02..4db3186 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -36,6 +36,14 @@ > 本文档是 `README.md` 的简体中文翻译。以英文版为准。 +## 当前公开范围 + +Codex 和 Claude Code 是当前 first-class setup target。OpenCode 和 OpenClaw 保持为 optional/reference surface；只有在需要兼容性说明时才参考现有文档，不要把它们当作默认设置路径。 + +## Private Project Skills + +不要把 auto-eva 这类 private project skill 提交到这个 public repository。实际项目专用 skill 应放在本地 runtime home，例如 Codex 的 `~/.codex/skills` 和 Claude Code 的 `~/.claude/skills`。这个仓库只保留 templates and public-safe process guidance，不放 private access path、credential、auth state、browser profile、customer data 或 machine-specific trust setting。 + ## 为什么使用 agent-bootstrap？ - 不需要为 Codex、Claude Code、OpenCode 分别维护不同的提示词栈，而是共享一套基于 `superpowers` 的工作流。 diff --git a/codex-home/AGENTS.md b/codex-home/AGENTS.md index b41d6a9..4905a90 100644 --- a/codex-home/AGENTS.md +++ b/codex-home/AGENTS.md @@ -25,6 +25,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/docs/agent-bootstrap-structure.md b/docs/agent-bootstrap-structure.md index 3e0531c..6248c80 100644 --- a/docs/agent-bootstrap-structure.md +++ b/docs/agent-bootstrap-structure.md @@ -47,6 +47,10 @@ Harness adapters translate the shared core into each host's native shape. - `plugins/process-first-agents/` - Generated Claude Code plugin package. - Built by `scripts/render_claude_plugin.py`. +- `skills/` + - Optional Codex skill catalog. + - `skills/README.md` lists available catalog skills. + - Skill source directories such as `skills/chatgpt-collaboration-harness/` are reviewable catalog copies, not automatically installed runtime state. ## Generated Artifacts @@ -76,6 +80,8 @@ python3 scripts/render_claude_plugin.py --partner-name "Hun" - Guardrail workflow explanation: `docs/vibe-coding-guardrails.md`. - Global installation and optional tooling rules: `docs/global-guardrail-setup.md`. - Project-local knowledge shape: `docs/local-project-knowledge-template.md`. +- Optional Codex skill catalog workflow: `docs/codex-skills.md`. +- Optional Codex skill setup prompt: `prompts/setup-codex-skills.md`. ## Dependency Direction @@ -147,6 +153,7 @@ Check these areas carefully: - Claude renderer changes that silently accept unknown placeholders. - Docs that mention commands not implemented by this repository. - Optional tool docs that imply installation without user approval. +- Skill catalog changes that confuse the repo catalog source with the runtime copy under `~/.codex/skills`. ## Privacy Boundary diff --git a/docs/agent-setup-playbook.md b/docs/agent-setup-playbook.md index a6d0e8c..79a5faa 100644 --- a/docs/agent-setup-playbook.md +++ b/docs/agent-setup-playbook.md @@ -57,6 +57,7 @@ Choose the smallest valid scope that satisfies the user's request. | Harness is unclear | shared-core-only | Apply only shared operating guidance and ask before harness-specific setup. | | User points at an application repository | project guardrails | Add project-local knowledge guidance and repo-appropriate checks. Do not install global harness defaults unless requested. | | User says this repository was updated | agent-bootstrap maintenance | Read the structure doc, regenerate generated output when needed, verify tests and audit. | +| User asks what Codex skills are available in this repository | skill catalog review | Read `skills/README.md` and `docs/codex-skills.md`. Compare selected skills with `~/.codex/skills`, then ask before installing or overwriting anything. | | User asks for OpenClaw ACP | explicit integration path | Follow OpenClaw docs. Do not infer provider, backend, or gateway choices. | When two valid scopes could apply, prefer the smaller one and explain what is intentionally left untouched. @@ -196,6 +197,16 @@ python3 scripts/audit_agent_stack.py This writes user-level Codex defaults. Existing sessions may need a restart or a focused instruction to apply the new guardrails. +### Optional Codex Skills + +Read: + +- `skills/README.md` +- `docs/codex-skills.md` +- `prompts/setup-codex-skills.md` + +This is a browse and selective install path, not a blanket installer. The repo copy is the catalog source, and the runtime copy lives under `~/.codex/skills/`. Ask before installing or overwriting any skill, then run the documented `quick_validate.py` validation path. + ### Claude Code Read: diff --git a/docs/codex-skills.md b/docs/codex-skills.md new file mode 100644 index 0000000..2e9f0ad --- /dev/null +++ b/docs/codex-skills.md @@ -0,0 +1,110 @@ +# Codex Skills + +This repository includes a Skill Catalog for Codex skills that may be useful across projects. + +The workflow is browse, review, select, install. The repo copy is the catalog source. The installed copy is the runtime copy used by Codex under `~/.codex/skills/`. + +Do not install every skill automatically. A setup agent should inspect this repository's catalog, compare a selected skill with the installed runtime copy, explain the change, ask Hun before installing or overwriting, and then validate the installed skill. + +The current catalog intentionally separates upstream guidance from Hun-specific operation: + +- `karpathy-guidelines` is the original catalog/vendor skill preserved from `multica-ai/andrej-karpathy-skills`. +- `hun-engineering-loop` is the Hun-specific operational wrapper that combines Karpathy-style caution with memory preflight, source-of-truth ordering, a high-risk stop/ask boundary, artifact-first execution, and a QA evidence contract. + +## Source Boundaries + +- Catalog source: `skills/` in this repository. +- Runtime copy: `~/.codex/skills/`. +- Template files: `skills/_template/*.template`; these are not installable skills. +- System validator: `~/.codex/skills/.system/skill-creator/scripts/quick_validate.py`. +- Original catalog/vendor skills keep attribution and license notes in their own directory. +- Hun-specific workflow belongs in wrapper skills, not in upstream-preserved catalog/vendor skills. + +Keep private paths, credentials, MCP endpoints, auth state, browser profiles, and machine-specific trust settings out of tracked files. Public docs may mention `~/.codex/skills`, but they must not record a personal absolute home path. + +Remember: memory is a recall layer, not a source of truth. If memory, ChatGPT Pro, or another external review conflicts with repo docs, scripts, tests, AGENTS files, or observed runtime output, the current project source wins. + +Private project skills such as auto-eva belong in local runtime skill homes, not this public catalog. Use `~/.codex/skills` for Codex and `~/.claude/skills` for Claude Code. Keep templates and public-safe process guidance in git; keep private access paths, credentials, auth state, browser profiles, customer data, and machine-specific trust settings local. + +## Catalog Workflow + +1. Run `git status --short --branch`. +2. Stop if there are uncommitted changes or untracked files, unless Hun has already approved how to handle them. +3. Read `skills/README.md`. +4. Inspect the selected skill directory. +5. Check whether `~/.codex/skills/` already exists. +6. Compare the catalog copy with the installed runtime copy. +7. Ask before installing or overwriting the runtime copy. +8. Install only the approved skill. +9. Run `quick_validate.py` against the installed runtime copy. +10. Report changed files, install target, validation result, and any remaining risk. + +If a project depends on a skill, keep a minimal source-of-truth pointer in that project's `AGENTS.md` or project docs. Do not put all routing knowledge only in global skills; that creates trigger ambiguity and makes the repo harder to operate without the same local runtime. + +## Skill QA Contract + +Treat skill changes as tested workflow code. Start with a failing test or explicit pressure scenario when the host or repo can support it. Then run the skill validator, run relevant repo tests, check for private paths and secrets, and verify the installed runtime copy separately from the repo catalog source before calling the skill ready. + +## Validation + +The skill validator imports `yaml`, so on systems where Python is PEP 668 protected or lacks PyYAML, use a disposable virtual environment instead of modifying system Python. + +```bash +python3 -m venv /tmp/codex-skill-validate-pyyaml +/tmp/codex-skill-validate-pyyaml/bin/python -m pip install PyYAML +/tmp/codex-skill-validate-pyyaml/bin/python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py ~/.codex/skills/ +``` + +If validation cannot run, report the exact error and do not claim the skill is installed correctly. + +## First Catalog Skill + +`chatgpt-collaboration-harness` is intentionally listed first because it is useful for broad, staged, research-heavy, or review-heavy work. + +Use it when Codex should coordinate with ChatGPT Pro as a reviewer, delegated worker, Search Mode or deep research researcher, or bounded web-task agent. Do not use it for every local edit. Do not share files, diffs, logs, URLs, browser state, or private data with ChatGPT Pro unless the sharing scope is approved. + +Use `references/file-artifact-exchange.md` when the stage needs approved screenshots, files, and generated artifacts. Downloaded artifacts stay untrusted until Codex validates them locally. + +The skill requires source-backed evidence. ChatGPT Pro must not answer from inference alone when project source behavior, official documentation, rankings, preferences, or public sentiment matter. Technical claims should prefer local project source, reproducible evidence, official docs, primary sources, release notes, specifications, and source-backed research. Preference, popularity, adoption, or taste claims may use community-sentiment evidence, but those signals must be labeled separately from official facts. + +By default, ChatGPT Pro prompts and Codex summaries should be in Korean unless Hun asks for another language or the deliverable requires it. + +## Engineering Loop Skills + +`karpathy-guidelines` should stay close to the upstream skill. It exists to reduce common coding-agent mistakes: hidden assumptions, unnecessary abstractions, broad diffs, and vague success criteria. Preserve its source attribution instead of modifying it for local policy. + +`hun-engineering-loop` is the daily workflow wrapper. Use it when a task should start with memory preflight, then resolve the current source of truth, check the high-risk stop/ask boundary, create or update an artifact, verify with evidence, and report what was proven. + +The high-risk stop/ask boundary applies even when the host has broad access. Stop and ask before destructive deletion, credential or permission changes, production/deployment/billing actions, external account changes, public sharing, auth state or browser profile changes, history rewrites, hook bypasses, or disabling tests. + +Use permission profiles, hooks, or approval layers as deferred implementation tools, not a replacement for judgment. Use them where the host supports them, but do not make broad access the default recommendation in public templates. + +## Project Skill Template + +Use `skills/_template` for project workflow skills. Each project skill should include: + +- `Scope / Non-goals` +- `Memory Preflight` +- `Source Of Truth` +- `Access And Approval Boundary` +- `Artifact-First Execution` +- `Verification Contract` +- `QA / Refactor Loop` +- `Final Report` + +The `Verification Contract` is the important part. Replace placeholders with executable project evidence: fast check, targeted regression, type/lint/build, browser/manual QA, deployment smoke, and negative/regression test where relevant. + +## Multi-Project Use + +The global skill can be used from multiple projects, but project state must remain separate. + +- Use one goal per project. +- Use one ChatGPT work tab or conversation per project. +- Keep one approved external sharing scope per project. +- Keep validation records per project. +- Do not mix unrelated repository context in the same ChatGPT conversation. +- Do not let multiple sessions edit the same repo, branch, or file without coordination. + +## When To Add More Skills + +Add a cataloged skill only when the workflow is reusable across projects and should be discoverable later. Do not create a skill for one-off implementation details, private project notes, or mechanical checks that should be automated instead. diff --git a/docs/repo-metadata.md b/docs/repo-metadata.md index b023a13..45b1b74 100644 --- a/docs/repo-metadata.md +++ b/docs/repo-metadata.md @@ -6,7 +6,7 @@ This document tracks the repository metadata that improves GitHub discoverabilit Use this repository description on GitHub: -> Process-first bootstrap for Codex, Claude Code, and OpenCode with superpowers, role-based subagents, token-efficient workflows, and multilingual setup docs. +> Process-first bootstrap for Codex and Claude Code with superpowers, role-based subagents, token-efficient workflows, and multilingual setup docs. ## Topics @@ -20,7 +20,6 @@ Recommended GitHub topics: - `codex` - `developer-tools` - `multilingual` -- `opencode` - `prompt-engineering` - `subagents` - `superpowers` @@ -32,13 +31,13 @@ GitHub social preview is a repository setting, not a tracked file format. Recommended social preview copy: - Title: `Process-First AI Coding Bootstrap` -- Subtitle: `Codex, Claude Code, OpenCode, superpowers, subagents, multilingual docs` +- Subtitle: `Codex, Claude Code, superpowers, subagents, multilingual docs` Recommended visual direction: - clean light background - one bold headline -- three harness labels: `Codex`, `Claude Code`, `OpenCode` +- two harness labels: `Codex`, `Claude Code` - one supporting row: `superpowers`, `subagents`, `token-efficient workflows` ## Notes @@ -53,7 +52,7 @@ You can reapply the recommended GitHub metadata with: ```bash gh repo edit hun99999/agent-bootstrap \ - --description "Process-first bootstrap for Codex, Claude Code, and OpenCode with superpowers, role-based subagents, token-efficient workflows, and multilingual setup docs." \ + --description "Process-first bootstrap for Codex and Claude Code with superpowers, role-based subagents, token-efficient workflows, and multilingual setup docs." \ --add-topic agent-bootstrap \ --add-topic ai-agents \ --add-topic ai-coding \ @@ -62,7 +61,6 @@ gh repo edit hun99999/agent-bootstrap \ --add-topic codex \ --add-topic developer-tools \ --add-topic multilingual \ - --add-topic opencode \ --add-topic prompt-engineering \ --add-topic subagents \ --add-topic superpowers diff --git a/docs/superpowers/specs/2026-06-24-codex-long-running-work-settings-design.md b/docs/superpowers/specs/2026-06-24-codex-long-running-work-settings-design.md new file mode 100644 index 0000000..d15c22d --- /dev/null +++ b/docs/superpowers/specs/2026-06-24-codex-long-running-work-settings-design.md @@ -0,0 +1,214 @@ +# Codex Long-Running Work Settings Design + +## Summary + +Improve only the Codex-side setup so Hun's local Codex defaults better support long-running work, while leaving Claude Code, OpenCode, OpenClaw, and shared cross-harness prompt surfaces unchanged. + +The target is not a new automation system. The target is a tighter Codex operating loop: + +- high-autonomy Codex permissions remain intentional: `approval_policy = "never"` and `sandbox_mode = "danger-full-access"` +- long-running work uses verifiable goals, checkpoints, progress logs, and explicit stopping conditions +- memory stays enabled as a local recall layer, while durable rules remain in checked-in Codex docs and templates +- Codex setup prompts explain when to use `/goal`, skills, browser, Chrome, computer use, and memory notes +- the repository's Codex templates remain the source of truth for future `~/.codex` installs + +## Sources + +This design is based on the current repository state plus current OpenAI Codex guidance reviewed on 2026-06-24: + +- OpenAI article: `https://openai.com/index/codex-maxxing-long-running-work/` +- OpenAI whitepaper PDF: `https://cdn.openai.com/pdf/8a9f00cf-d379-4e20-b06f-dd7ba5196a11/OAI_WhitePaper_Codex-maxxing26.pdf` +- Codex best practices: `https://developers.openai.com/codex/learn/best-practices` +- Codex config basics: `https://developers.openai.com/codex/config-basic` +- Codex follow goals: `https://developers.openai.com/codex/use-cases/follow-goals` +- Codex memories: `https://developers.openai.com/codex/memories` +- Codex subagents: `https://developers.openai.com/codex/subagents` +- Codex skills: `https://developers.openai.com/codex/skills` + +The relevant guidance is: + +- Use `AGENTS.md` and configuration for reusable, durable behavior. +- Keep personal defaults in `~/.codex/config.toml` and project behavior in `.codex/config.toml` or repo-local docs. +- Use goals for work with one objective, a stopping condition, proof commands, checkpoints, and compact progress reports. +- Treat memories as helpful recall, not the only place for required rules. +- Use skills for repeated workflows instead of repeated long prompts. +- Use subagents for independent or highly parallel work, with awareness that they consume more tokens and inherit parent runtime policy. +- Separate browser, Chrome, computer-use, connector, and skill surfaces by what each task actually needs. + +## Current State + +The repository already has a strong Codex setup: + +- `.codex/templates/config.toml` and `codex-home/config.toml` define `gpt-5.5`, `xhigh` reasoning, a `balanced` profile, a `previous` profile, custom role agents, `[agents] max_threads = 6`, `[agents] max_depth = 1`, and `[features] multi_agent = true`. +- `tests/test_codex_config.py` verifies the Codex template and snapshot config stay identical, verifies model policy, verifies role configs, and prevents role-level model pins. +- `docs/README.codex.md`, `.codex/INSTALL.md`, and `prompts/setup-codex-current-harness.md` explain Codex installation and current-harness-only behavior. +- The live `~/.codex/config.toml` already includes `approval_policy = "never"`, `sandbox_mode = "danger-full-access"`, `memories = true`, and memory settings. + +The gap is that the checked-in Codex templates do not fully encode the intended high-autonomy permission and memory policy. A future reinstall from this repository can overwrite live Codex behavior with a weaker source-of-truth. The docs also do not yet provide a first-class Codex long-running-work prompt or concise operating contract. + +## Scope + +This work is Codex-only. + +Modify only Codex-scoped files: + +- `.codex/templates/config.toml` +- `codex-home/config.toml` +- `.codex/templates/local.md` +- `codex-home/local.md` +- `docs/README.codex.md` +- `.codex/INSTALL.md` +- `prompts/setup-codex-current-harness.md` +- a new Codex-only long-running-work prompt under `prompts/` +- Codex-related tests under `tests/` + +Do not modify Claude Code, OpenCode, OpenClaw, or shared cross-harness surfaces: + +- no `.claude-plugin/` changes +- no `plugins/process-first-agents/` changes +- no `docs/README.claude.md`, `docs/README.opencode.md`, or `docs/README.openclaw.md` changes +- no `prompts/setup-claude-current-harness.md`, `prompts/setup-opencode-current-harness.md`, or OpenClaw prompt changes +- no `scripts/render_claude_plugin.py` or generated Claude plugin refresh +- no shared `AGENTS.md` or `agents/*.md` changes, because those are shared prompt corpus files and can affect Claude Code plugin output +- no new broad automation runner unless a later design explicitly approves it + +## Design + +### 1. Codex Config Source Of Truth + +Add the intentional high-autonomy default to both Codex config source files: + +```toml +approval_policy = "never" +sandbox_mode = "danger-full-access" +``` + +Add long-running-work feature defaults: + +```toml +[features] +goals = true +multi_agent = true +memories = true + +[memories] +generate_memories = true +use_memories = true +disable_on_external_context = true +``` + +Keep the existing model, profile, and agent role policy unless a test exposes a concrete mismatch. Do not change role-level `sandbox_mode` or `approval_policy` in this pass. Role-specific read-only/write behavior is separate from root session autonomy and was already intentionally tested. + +The installer already replaces `{{CODEX_HOME_ABS}}` in agent TOML files and verifies role config references. No installer architecture change is expected. + +### 2. Codex Local Notes Template + +Replace the minimal `local.md` template with a Codex-only note surface for long-running state. + +The template should remain short and machine-safe: + +- state that durable rules belong in checked-in docs, not generated memory +- reserve space for active long-running work notes +- reserve space for local-only tool or environment notes +- remind agents not to commit credentials, private paths, MCP endpoints, auth state, browser profiles, or machine-specific trust settings + +This file is installed into `~/.codex/local.md`, so it may contain local note headings, but the checked-in template must not include Hun's private project paths or live secrets. + +### 3. Codex Long-Running Prompt + +Add `prompts/start-codex-long-running-work.md`. + +The prompt should be public-shareable and path-neutral. It should ask Codex to: + +- read the repository's Codex instructions and task-relevant docs first +- confirm the current working tree before changes +- define one objective and one stopping condition +- identify files, docs, logs, issues, or plans to read first +- define proof commands or artifacts +- break the work into checkpoints +- use `/goal` or goal tooling when available +- keep a compact progress log +- separate tool surfaces: local browser for local previews, Chrome for authenticated browser state, computer use for GUI-only work, MCP/connectors only when the source of truth lives outside the repo, skills for repeatable workflows +- keep memory-worthy facts as explicit notes for review, not hidden assumptions +- stop before irreversible, destructive, production, account, billing, external-send, or broad architecture actions unless the user approved that exact action + +The prompt should not include private local paths. + +### 4. Codex Docs + +Update `docs/README.codex.md` and `.codex/INSTALL.md` only. + +The docs should explain: + +- the setup intentionally installs high-autonomy Codex defaults +- high autonomy does not remove user approval requirements for irreversible or external side-effect actions +- long-running work should use a goal with one objective, a stopping condition, checkpoints, and proof commands +- memory is enabled but required rules stay in checked-in docs +- Codex App and CLI may need a restart after config changes +- the new long-running prompt is the recommended starting point for broad Codex-only work + +Update `prompts/setup-codex-current-harness.md` so setup workers preserve and report these Codex-only defaults. + +Do not update translated README files in this pass unless a Codex-only test already requires it. The narrower Codex docs are enough for the requested scope. + +### 5. Tests + +Use TDD for behavior changes: + +1. Add failing tests in `tests/test_codex_config.py` proving both `.codex/templates/config.toml` and `codex-home/config.toml` include: + - root `approval_policy = "never"` + - root `sandbox_mode = "danger-full-access"` + - `[features] goals = true` + - `[features] memories = true` + - `[memories] generate_memories = true` + - `[memories] use_memories = true` + - `[memories] disable_on_external_context = true` + +2. Add or extend a Codex docs test proving: + - `docs/README.codex.md` references long-running work, goals, memory, and `prompts/start-codex-long-running-work.md` + - `.codex/INSTALL.md` documents the high-autonomy defaults + - `prompts/setup-codex-current-harness.md` mentions preserving high-autonomy Codex defaults + - `prompts/start-codex-long-running-work.md` exists and does not contain private local paths + +3. Verify the new tests fail before implementation. + +4. Make the smallest changes to pass. + +5. Run the relevant focused tests, then the normal repository verification stack: + - `python3 -m unittest discover -s tests -p 'test_*.py'` + - `python3 scripts/audit_agent_stack.py` + - `python3 scripts/check_private_paths.py` + - `git diff --check` + +### 6. Global Install + +After tests pass and Hun approves the implementation plan, run the Codex installer: + +```bash +bash .codex/install.sh --partner-name "Hun" +``` + +Then verify the live config: + +```bash +codex features list +``` + +The live feature list should show `goals`, `multi_agent`, and `memories` enabled. The live `~/.codex/config.toml` should retain the high-autonomy permission defaults. + +## Risks + +- Updating root/shared prompt files would accidentally affect Claude Code or OpenCode. This design avoids that by limiting edits to Codex-specific files. +- `~/.codex/config.toml` contains local plugin, MCP, project trust, and desktop state that should not be copied into tracked templates. Only stable Codex setup defaults belong in the repo templates. +- High autonomy can execute destructive local commands without approval. Hun explicitly approved the high-autonomy default, so the mitigation is documentation and prompt-level action boundaries for irreversible or external side effects. +- Memory generation can lag and should not be treated as a reliable rule store. Required rules stay in checked-in Codex docs and templates. + +## Acceptance Criteria + +- The work changes only Codex-scoped files listed in this design. +- Checked-in Codex templates encode high-autonomy root defaults and long-running-work features. +- Codex docs and setup prompts explain long-running goals, checkpoints, memory boundaries, tool-surface separation, and high-autonomy action boundaries. +- A public-shareable Codex long-running-work prompt exists. +- Tests cover the new Codex config and docs expectations. +- Full repository verification passes. +- The final global install updates `~/.codex` without touching Claude Code, OpenCode, or OpenClaw setup. diff --git a/plugins/process-first-agents/agents/backend-engineer.md b/plugins/process-first-agents/agents/backend-engineer.md index 9c7a855..b895088 100644 --- a/plugins/process-first-agents/agents/backend-engineer.md +++ b/plugins/process-first-agents/agents/backend-engineer.md @@ -32,6 +32,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/data-engineer.md b/plugins/process-first-agents/agents/data-engineer.md index 04c8e12..9015ba4 100644 --- a/plugins/process-first-agents/agents/data-engineer.md +++ b/plugins/process-first-agents/agents/data-engineer.md @@ -32,6 +32,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/debugger.md b/plugins/process-first-agents/agents/debugger.md index bec77fb..e79da7d 100644 --- a/plugins/process-first-agents/agents/debugger.md +++ b/plugins/process-first-agents/agents/debugger.md @@ -36,6 +36,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/eng-lead.md b/plugins/process-first-agents/agents/eng-lead.md index 20cc5b6..7aca31b 100644 --- a/plugins/process-first-agents/agents/eng-lead.md +++ b/plugins/process-first-agents/agents/eng-lead.md @@ -31,6 +31,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/frontend-engineer.md b/plugins/process-first-agents/agents/frontend-engineer.md index e18e819..f9051a8 100644 --- a/plugins/process-first-agents/agents/frontend-engineer.md +++ b/plugins/process-first-agents/agents/frontend-engineer.md @@ -32,6 +32,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/integrations-engineer.md b/plugins/process-first-agents/agents/integrations-engineer.md index fdbefcf..9517b69 100644 --- a/plugins/process-first-agents/agents/integrations-engineer.md +++ b/plugins/process-first-agents/agents/integrations-engineer.md @@ -32,6 +32,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/performance-engineer.md b/plugins/process-first-agents/agents/performance-engineer.md index fe9258f..6b5abdf 100644 --- a/plugins/process-first-agents/agents/performance-engineer.md +++ b/plugins/process-first-agents/agents/performance-engineer.md @@ -32,6 +32,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/planner.md b/plugins/process-first-agents/agents/planner.md index 93a8fbc..2fc1482 100644 --- a/plugins/process-first-agents/agents/planner.md +++ b/plugins/process-first-agents/agents/planner.md @@ -36,6 +36,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/platform-engineer.md b/plugins/process-first-agents/agents/platform-engineer.md index 7b7eab4..c76684f 100644 --- a/plugins/process-first-agents/agents/platform-engineer.md +++ b/plugins/process-first-agents/agents/platform-engineer.md @@ -32,6 +32,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/release-manager.md b/plugins/process-first-agents/agents/release-manager.md index 3e31c4c..2ec4ed8 100644 --- a/plugins/process-first-agents/agents/release-manager.md +++ b/plugins/process-first-agents/agents/release-manager.md @@ -36,6 +36,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/researcher.md b/plugins/process-first-agents/agents/researcher.md index 0efdfac..010f2aa 100644 --- a/plugins/process-first-agents/agents/researcher.md +++ b/plugins/process-first-agents/agents/researcher.md @@ -36,6 +36,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/reviewer.md b/plugins/process-first-agents/agents/reviewer.md index 74a76cc..1b0fbe6 100644 --- a/plugins/process-first-agents/agents/reviewer.md +++ b/plugins/process-first-agents/agents/reviewer.md @@ -36,6 +36,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/security-engineer.md b/plugins/process-first-agents/agents/security-engineer.md index e919da4..6e5e7ef 100644 --- a/plugins/process-first-agents/agents/security-engineer.md +++ b/plugins/process-first-agents/agents/security-engineer.md @@ -32,6 +32,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/skill-author.md b/plugins/process-first-agents/agents/skill-author.md index 7501757..63f128c 100644 --- a/plugins/process-first-agents/agents/skill-author.md +++ b/plugins/process-first-agents/agents/skill-author.md @@ -32,6 +32,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/verifier.md b/plugins/process-first-agents/agents/verifier.md index c27166b..e916b38 100644 --- a/plugins/process-first-agents/agents/verifier.md +++ b/plugins/process-first-agents/agents/verifier.md @@ -36,6 +36,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/plugins/process-first-agents/agents/worker.md b/plugins/process-first-agents/agents/worker.md index 319df31..e8f596a 100644 --- a/plugins/process-first-agents/agents/worker.md +++ b/plugins/process-first-agents/agents/worker.md @@ -32,6 +32,28 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - We discuss architectural decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion. - You may use sub-agents or parallel agents for independent work without asking again each time when the current host/runtime provides the capability. This is a standing preference, not a requirement: use them when they create clear leverage, and stay local when they do not. +## Access and approval boundary + +- Broad filesystem or tool access is operational capability, not blanket approval. +- High-risk actions require an explicit stop and ask before proceeding. +- High-risk actions include anything that would delete data, prune history, rotate credentials, change permissions, touch production, deployment, billing, external accounts, secrets, auth state, browser profiles, public sharing, protected branches, hooks, or test enforcement. +- Use permission profiles, hooks, or approval layers when the current host/runtime supports them, but never treat those mechanisms as a replacement for judgment. + +## Source of truth and memory + +- Memory is a recall layer, not a source of truth. +- When memory or prior summaries conflict with current evidence, repo docs, scripts, tests, AGENTS files, and observed runtime output win. +- Project-specific operating knowledge belongs in project docs or project skills, with repo-local source-of-truth pointers when a skill is required. + +## Skill creation and QA + +- When creating or editing a skill, treat the skill as tested process code, not just prose. +- Start with a failing test or explicit pressure scenario before writing the skill change when the host or repo can support it. +- Keep skill bodies concise and move detailed procedures into reference files when that makes the trigger behavior clearer. +- After skill edits, run the skill validator, run relevant repo tests, check for private paths and secrets, and inspect the rendered or installed result when applicable. +- When a skill has both a repo catalog source and runtime copy, verify any runtime copy separately from the repo catalog source. +- Do not claim a skill is ready only because the Markdown looks reasonable. + # Proactiveness When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly. diff --git a/prompts/setup-codex-skills.md b/prompts/setup-codex-skills.md new file mode 100644 index 0000000..e0e3321 --- /dev/null +++ b/prompts/setup-codex-skills.md @@ -0,0 +1,59 @@ +# Setup Codex Skills + +```text +Review and optionally install Codex skills from this repository. + +First read AGENTS.md if it exists. Then read README.md, skills/README.md, and docs/codex-skills.md. Do not invent commands, package names, configuration options, install paths, or API details. + +Before changing anything, run: + +git status --short --branch + +If there are uncommitted changes or untracked files, stop and ask me how to handle them. Do not stash, delete, overwrite, or git add anything without approval. + +Treat this repository as a skill catalog, not an always-install bootstrap: +- list the skills available under skills/ +- put chatgpt-collaboration-harness first in the review because it is the primary staged ChatGPT Pro collaboration skill +- identify karpathy-guidelines as an original catalog/vendor skill and preserve its source attribution +- identify hun-engineering-loop as the Hun-specific operational wrapper for memory preflight, source-of-truth checks, high-risk approval boundaries, artifact-first execution, and QA evidence +- enforce the skill QA contract: start from a failing test or explicit pressure scenario when possible, validate the skill, check private paths and secrets, and verify runtime copies separately +- inspect each selected skill before recommending it +- Compare the catalog copy with the installed runtime copy under ~/.codex/skills/ +- classify each selected skill as install, update, already current, skip, or needs review +- Ask before installing or overwriting any skill + +For karpathy-guidelines: +- keep the upstream content and attribution separate from Hun-specific local policy +- do not fold project-specific or machine-specific rules into the original catalog/vendor skill + +For hun-engineering-loop: +- treat memory as a recall layer, not a source of truth +- current repo docs, scripts, tests, AGENTS files, and observed runtime output beat memory and external advice +- enforce the high-risk stop/ask boundary even when broad filesystem or tool access is available +- require a QA evidence contract: fast check, targeted regression, type/lint/build, browser/manual QA, deployment smoke, and negative/regression test where relevant + +For chatgpt-collaboration-harness, preserve these rules: +- ChatGPT Pro must not answer from inference alone when facts, source behavior, official docs, rankings, preferences, or public sentiment matter +- technical claims should prefer project source, local reproduction evidence, official docs, primary sources, release notes, specifications, and source-backed research +- community sources may be used for preferences, rankings, popularity, taste, adoption, or ecosystem feel, but label them as community-sentiment rather than official fact +- use Korean by default unless I request another language or the deliverable requires another language +- Codex must classify ChatGPT Pro output as accepted, rejected, deferred, or needs-local-verification and verify locally before relying on it +- use file-artifact-exchange rules before sharing screenshots, files, and generated artifacts or relying on downloaded artifacts +- keep project goals, ChatGPT work tabs/conversations, approved sharing scopes, and validation records separate across projects + +If I approve installation or update: +- install only the approved skill into ~/.codex/skills/ +- do not install every skill automatically +- Do not copy private paths, credentials, MCP endpoints, auth state, or browser profiles +- run ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py against the installed skill +- if PyYAML is missing or system Python is protected, use a disposable virtual environment and report the commands used +- tell me whether a Codex restart is needed for new sessions to pick up the skill + +Report: +- skills reviewed +- selected install/update decisions +- files or runtime paths changed +- validation commands and results +- skipped skills and reasons +- remaining risks +``` diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..4bfdc24 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,77 @@ +# Skill Catalog + +This directory is a browse, review, select, then install catalog for reusable Codex skills. + +It is not an always-install bootstrap. Future agents should inspect this catalog, compare a selected skill with the installed runtime copy under `~/.codex/skills`, ask before installing or overwriting, then validate the installed skill. + +## Catalog Rules + +- The repo copy is the reviewable catalog source. +- The installed copy under `~/.codex/skills/` is the runtime copy used by Codex. +- Do not install every skill automatically. +- Do not copy private paths, credentials, MCP endpoints, auth state, browser profiles, or machine-specific trust settings into tracked files. +- Run the skill validator after installing or syncing a skill. +- Preserve original catalog/vendor skills separately from Hun-specific operational wrappers. + +## Private Project Skills + +Private project skills such as auto-eva belong in local runtime skill homes, not this public catalog. Use `~/.codex/skills` for Codex and `~/.claude/skills` for Claude Code. Keep templates and public-safe process guidance here; keep private access paths, credentials, auth state, browser profiles, customer data, and machine-specific trust settings out of git. + +## Skill QA Contract + +Treat skill changes as tested workflow code. Start with a failing test or explicit pressure scenario when possible, run the skill validator, run relevant repo tests, check for private paths and secrets, and verify the installed runtime copy separately from the repo catalog source before calling the skill ready. + +### chatgpt-collaboration-harness + +Use this first when work should be coordinated with ChatGPT Pro across staged implementation, delegated subtasks, Search Mode, deep research, source-backed investigation, or final review. + +Key policy: + +- Codex owns local files, validation, and final judgment. +- Use `references/file-artifact-exchange.md` when the stage needs approved screenshots, files, and generated artifacts. +- ChatGPT Pro must not answer from inference alone when facts, project source behavior, official docs, rankings, preferences, or public sentiment matter. +- Technical claims should use project source, local evidence, official documentation, primary sources, or source-backed research first. +- Community evidence is allowed for taste, popularity, adoption, or preference questions, but it must be labeled `community-sentiment`, not treated as official fact. +- ChatGPT Pro and Codex summaries are Korean by default unless Hun asks otherwise or the deliverable requires another language. +- Keep one goal, one ChatGPT work tab or conversation, one approved sharing scope, and one validation record per project. + +Catalog path: `skills/chatgpt-collaboration-harness` + +Runtime install target: `~/.codex/skills/chatgpt-collaboration-harness` + +### karpathy-guidelines + +Use this when writing, reviewing, or refactoring code and the main risk is overcomplication, hidden assumptions, broad diffs, or weak success criteria. + +Key policy: + +- This is an original catalog/vendor skill preserved from `multica-ai/andrej-karpathy-skills`. +- Keep upstream attribution and the MIT license note in `skills/karpathy-guidelines/references/SOURCE.md`. +- Do not add Hun-specific local workflow rules to this skill. +- Use `hun-engineering-loop` when the work also needs memory preflight, source-of-truth ordering, access approval boundaries, and QA evidence contracts. + +Catalog path: `skills/karpathy-guidelines` + +Runtime install target: `~/.codex/skills/karpathy-guidelines` + +### hun-engineering-loop + +Use this for Hun-specific non-trivial engineering work across planning, implementation, review, refactor, QA, or handoff. + +Key policy: + +- This is the Hun-specific operational wrapper around `karpathy-guidelines`, repo rules, memory preflight, and executable verification. +- Memory is a recall layer, not a source of truth. +- Current repo docs, scripts, tests, `AGENTS.md`, and observed runtime output beat memory and external advice. +- Broad access is allowed only as capability; high-risk actions still require a stop/ask approval boundary. +- Every project skill should name a concrete QA evidence contract instead of saying only "test it". + +Catalog path: `skills/hun-engineering-loop` + +Runtime install target: `~/.codex/skills/hun-engineering-loop` + +### _template + +Use this only as a starting skeleton for future catalog entries. The files are intentionally named with `.template` suffixes so they are not installed as a working skill by accident. + +Catalog path: `skills/_template` diff --git a/skills/_template/SKILL.md.template b/skills/_template/SKILL.md.template new file mode 100644 index 0000000..a2e12ca --- /dev/null +++ b/skills/_template/SKILL.md.template @@ -0,0 +1,95 @@ +--- +name: example-skill-name +description: Use when a future agent needs this reusable workflow, project operating guide, evidence pattern, or reference boundary. +--- + +# Example Skill Name + +## Scope / Non-goals + +State what this skill covers and what it must not cover. + +- Use for recurring project or workflow operations that future agents should discover. +- Do not store credentials, private paths, auth state, browser profiles, MCP endpoints, or machine-specific trust settings. +- Do not duplicate source-of-truth details that belong in repo docs, scripts, tests, or `AGENTS.md`. + +## Memory Preflight + +Tell the agent what memory keywords to search before work starts. + +- Remember: memory is a recall layer, not a source of truth. +- Re-check drift-prone facts against current files, live output, or official docs. +- If memory conflicts with the repo or observed runtime behavior, the current source wins. + +## Source Of Truth + +List the current authoritative sources in order. + +Example: + +1. User's latest instruction. +2. Repo `AGENTS.md`, README, docs, scripts, tests, CI, and runtime output. +3. This skill. +4. Memory and prior summaries. +5. External review after local verification. + +Leave a minimal source-of-truth pointer in repo docs or `AGENTS.md` when this skill is required for a project. + +## Access And Approval Boundary + +Define what the agent may do directly and what requires Hun's explicit approval. + +Require a stop/ask before deletion, credential or permission changes, production/deploy/billing changes, external account actions, public sharing, auth state changes, browser profile changes, history rewrites, force-pushes, hook bypasses, or test disabling. + +## Artifact-First Execution + +Name the durable artifact that should exist before open-ended implementation. + +Examples: + +- design/spec plus implementation plan; +- failing regression test; +- checklist with acceptance criteria; +- source-backed research note; +- migration or rollout plan. + +## Verification Contract + +Replace placeholders with real project commands and evidence. + +- `fast check`: TODO, for example `npm run lint` or `python3 -m compileall`. +- `targeted regression`: TODO, test or repro for the changed behavior. +- `type/lint/build`: TODO, project-level static and build checks. +- `browser/manual QA`: TODO, UI workflow, screenshot, or manual check when relevant. +- `deployment smoke`: TODO, preview or production check when release state is in scope. +- `negative/regression test`: TODO, proof that old failure or unsafe path is blocked. + +Separate smoke checks from official proof. Do not overclaim from narrow evidence. + +## Skill QA Contract + +When editing this skill, prove the workflow still works: + +- `skill validator`: TODO, command for validating this skill. +- `pressure scenario`: TODO, one realistic prompt or task that should trigger this skill. +- `private data check`: TODO, command or review step for private paths, credentials, secrets, auth state, browser profiles, and machine-specific trust settings. +- `runtime copy check`: TODO, how to compare and validate the installed copy when this skill is synced into runtime. + +## QA / Refactor Loop + +After the first artifact works: + +1. Run targeted verification. +2. Review for duplicate helpers, hidden coupling, weak tests, swallowed errors, unrelated formatting churn, and over-broad diffs. +3. Refactor only when it reduces real duplication, clarifies boundaries, or matches established local patterns. +4. Re-run relevant verification. + +## Final Report + +Report: + +- files or runtime paths changed; +- commands and checks run; +- accepted/rejected/deferred external advice; +- verification not run and why; +- remaining risks or follow-up work. diff --git a/skills/_template/agents/openai.yaml.template b/skills/_template/agents/openai.yaml.template new file mode 100644 index 0000000..d865acd --- /dev/null +++ b/skills/_template/agents/openai.yaml.template @@ -0,0 +1,4 @@ +interface: + display_name: "Example Skill Name" + short_description: "Short user-facing description" + default_prompt: "Use $example-skill-name to ..." diff --git a/skills/_template/references/README.md b/skills/_template/references/README.md new file mode 100644 index 0000000..f827e75 --- /dev/null +++ b/skills/_template/references/README.md @@ -0,0 +1,5 @@ +# Template References + +Put heavy reference material, prompt packets, scripts, or reusable examples here only when the skill body would become too large. + +Keep the main `SKILL.md` focused on trigger conditions, workflow, safety boundaries, and validation. diff --git a/skills/chatgpt-collaboration-harness/SKILL.md b/skills/chatgpt-collaboration-harness/SKILL.md new file mode 100644 index 0000000..3678618 --- /dev/null +++ b/skills/chatgpt-collaboration-harness/SKILL.md @@ -0,0 +1,108 @@ +--- +name: chatgpt-collaboration-harness +description: Use when work should be coordinated with web ChatGPT Pro, including broad goals, staged implementation, delegated subtasks, ChatGPT agent mode, Search Mode, deep research, source-backed web investigation, screenshots, files, or generated artifacts, validation feedback loops, or final review. +--- + +# ChatGPT Collaboration Harness + +## Purpose + +Use this skill to run a goal-driven harness where Codex remains the local implementation owner and web ChatGPT Pro can act as a reviewer, delegated worker, research partner, or web-task agent. + +Harness mode is not a single ChatGPT question. It is a controlled staged loop: confirm the user's objective, split broad work into concrete stages, route each stage to the right ChatGPT Pro capability when useful, validate local changes, then request final review before reporting back to the user. + +## Required Components + +- Use Codex goal setting or the `/goal` feature when available. +- Use `@chrome` or Chrome plugin capabilities for the web ChatGPT Pro session. +- Treat `@chrome` as a plugin/skill route, not as proof that a literal tool named `Chrome` must appear. If direct Chrome tools are not visible, read `references/chrome-chatgpt-pro.md` and follow the Chrome skill's browser-client route before reporting a blocker. +- Prefer web ChatGPT Pro extended mode, Pro conversation mode, Search Mode, deep research, or agent mode when the stage calls for that capability and the UI makes it available. +- When a stage needs screenshots, files, or generated artifacts, read `references/file-artifact-exchange.md` before uploading, downloading, or relying on them. +- Codex owns local files, execution, validation, final judgment, and user-facing reporting. +- ChatGPT Pro can provide critique, risks, alternatives, debugging ideas, design feedback, source-backed research, delegated draft work, web task execution, and final review. + +## Evidence And Language Rules + +- ChatGPT Pro must not answer from reasoning alone when the stage depends on factual claims, current facts, project source behavior, official documentation, rankings, popularity, preferences, or community sentiment. +- For project work, provide ChatGPT Pro with approved source excerpts or ask it to inspect approved project context before it concludes. Codex still verifies locally. +- Prefer official documentation, source code, primary sources, release notes, specifications, and reproducible local evidence for factual or technical claims. +- For preferences, rankings, taste, adoption, or "what people like" questions that official sources cannot answer, ChatGPT Pro may consult reputable public communities, forums, issue threads, reviews, social discussions, and expert commentary. Treat these as opinion signals, not facts. +- Ask ChatGPT Pro to label evidence quality: official/source-backed, primary-source, secondary-source, community-sentiment, or speculation. Speculation is not enough to make decisions without user judgment. +- Unless the user asks otherwise or the work product must be in another language, keep the ChatGPT Pro conversation and Codex's user-facing summaries in Korean. + +## Operating Modes + +- **Review-first mode**: ChatGPT Pro critiques Codex's plan, patch, tests, risks, or final result before Codex changes meaningful local state. +- **Preapproved harness mode**: Codex proceeds through the approved stage plan and applies clear low-risk suggestions without stopping after every ChatGPT Pro turn. +- **Delegated-worker mode**: Codex gives ChatGPT Pro a bounded work packet, then locally inspects, adapts, validates, and accepts or rejects the result. +- **Research-first mode**: Codex uses ChatGPT Search Mode or deep research for source-backed web investigation before planning or editing. +- **Agent-task mode**: Codex uses ChatGPT agent mode for bounded online tasks when available, while keeping user approvals and local validation under Codex control. + +## Startup Procedure + +1. Restate the user's final objective as one actionable outcome. +2. If the objective is unclear, explain Codex's understanding and confirm before implementation or external sharing. +3. If goal tooling is available, inspect the current goal state; if no goal is active, set a goal from the confirmed objective. +4. If the objective is broad, long-running, or ambiguous, decompose it into 1 to 10 concrete stages before starting work. +5. Choose the collaboration mode that fits the user's request. Ask only when the choice affects approval scope, external sharing, architecture, safety, cost, or correctness. +6. Confirm the external sharing scope before sending project summaries, files, diffs, logs, Git URLs, repository URLs, browser state, or private data to ChatGPT Pro. +7. Open or reuse a ChatGPT Pro conversation through `@chrome`. +8. Select the visible ChatGPT capability for the stage: normal chat, Search Mode, deep research, or agent mode. If the requested mode is not visible, verify through `references/chrome-chatgpt-pro.md` before reporting a blocker. +9. Decide whether the stage needs screenshots, files, or generated artifacts. If yes, confirm the attachment or download scope and follow `references/file-artifact-exchange.md`. +10. Send the first prompt with the objective, stage plan, current state, approved context, constraints, ChatGPT role, evidence requirements, Korean-language preference, and desired response format. + +## Stage Loop + +Work stages sequentially unless independent stages can safely run in parallel without sharing files, state, or external effects. + +For each stage: + +1. Restate the current stage outcome. +2. Perform the local work required for that stage. +3. If useful, send ChatGPT Pro a review, delegation, research, attachment, artifact, or agent-task packet matched to the stage. +4. Classify ChatGPT Pro output as accepted, rejected, deferred, or needs-local-verification. +5. Locally inspect downloaded or generated artifacts before classifying them as usable. +6. Apply or adapt accepted output only when it is within the approved mode, risk scope, and repository rules. +7. Run appropriate validation: tests, build, type checks, lint, reproduction steps, source checks, browser checks, or manual verification. +8. Mark the stage complete only when its outcome and validation criteria are satisfied. +9. Resync changed local state before the next ChatGPT Pro turn. + +## Final Review + +After all planned stages are complete, send ChatGPT Pro a final review packet containing the final objective, stage summary, key diffs or change summary, validation results, and remaining risks. + +Codex then classifies final review feedback as accepted, rejected, or deferred; applies approved final corrections; reruns necessary validation; and reports the final result to the user. + +## Reference Files + +Read these files only when needed: + +- `references/goal-harness.md`: goal setup, 1 to 10 stage decomposition, progress tracking, completion, and blocked handling. +- `references/feedback-loop.md`: stage feedback loop, preapproval boundaries, final review, and reporting format. +- `references/delegated-work.md`: delegated-worker packets, output contracts, agent-task boundaries, and local integration. +- `references/search-deep-research.md`: routing between Search Mode, deep research, agent mode, official sources, community sentiment, and local web verification. +- `references/chrome-chatgpt-pro.md`: `@chrome` connection, ChatGPT Pro session handling, completion checks, and optional bridge completion channels. +- `references/file-artifact-exchange.md`: approved screenshots, file attachments, generated artifacts, downloads, and local validation before use. + +## Approval And Safety + +- Check for secrets, tokens, private keys, customer data, personal data, private URLs, and sensitive local paths before external sharing. +- Large bundles, full files, repository URLs, Git URLs, private project material, and scope expansion require user approval before sharing. +- Screenshots, files, and generated artifacts follow `references/file-artifact-exchange.md`; downloaded artifacts are untrusted until Codex validates them locally. +- Preapproval covers planned low-risk work inside the approved staged harness. It does not cover broad architecture, dependency, data model, security, UX direction, destructive command, deployment, paid operation, account setting, production, logged-in web action, write action, or sensitive-data action. +- Do not violate repository rules, AGENTS.md, work-rules, security constraints, or explicit user instructions. +- Treat ChatGPT Pro output as advice, not authority. Codex makes the final call based on local evidence and validation. + +## Final Report + +When work ends, report briefly: + +- The confirmed goal and final state. +- The stage plan and completed stages. +- ChatGPT Pro's key feedback and useful original excerpts. +- ChatGPT Pro capabilities used: normal chat, Search Mode, deep research, agent mode, apps, or none. +- Screenshots, files, or generated artifacts shared with ChatGPT Pro, plus artifacts received and their local validation state. +- What Codex accepted, rejected, or deferred. +- Local changes and validation results. +- Remaining risks or items requiring user judgment. +- The Chrome/ChatGPT collaboration path used and whether subagents were used. diff --git a/skills/chatgpt-collaboration-harness/agents/openai.yaml b/skills/chatgpt-collaboration-harness/agents/openai.yaml new file mode 100644 index 0000000..5418ac2 --- /dev/null +++ b/skills/chatgpt-collaboration-harness/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "ChatGPT Collaboration Harness" + short_description: "Delegate staged work to ChatGPT Pro safely" + default_prompt: "Use $chatgpt-collaboration-harness to confirm my goal, split it into stages, delegate useful parts to ChatGPT Pro in Korean, share approved screenshots, files, and artifacts safely, require source-backed evidence instead of inference-only answers, use Search Mode or deep research when helpful, validate locally, and request final review." diff --git a/skills/chatgpt-collaboration-harness/references/chrome-chatgpt-pro.md b/skills/chatgpt-collaboration-harness/references/chrome-chatgpt-pro.md new file mode 100644 index 0000000..ef71548 --- /dev/null +++ b/skills/chatgpt-collaboration-harness/references/chrome-chatgpt-pro.md @@ -0,0 +1,85 @@ +# Chrome ChatGPT Pro + +## Connection Principles + +- If the user requested `@chrome`, or this skill requires Chrome integration, use Chrome plugin capabilities. +- Run ChatGPT collaboration in the user's Chrome session. +- Do not silently substitute the in-app browser or another browser path. +- If the Chrome connection, extension state, login state, or Pro conversation mode state is unclear, report the exact blocker. +- Do not conclude that Chrome is unavailable merely because no direct tool named `Chrome`, `chrome`, or `browser` appears in the active tool list. In Codex, Chrome automation is often exposed through the Chrome skill plus a browser-client runtime reached from the JavaScript/Node REPL tool. +- Before reporting "Chrome tools are not exposed", try the Chrome skill workflow: use the available JavaScript/Node REPL tool to initialize the Chrome browser-client, acquire the extension-backed browser, and list or open tabs. If the JavaScript/Node REPL tool itself is hidden, use tool discovery for the Node REPL JavaScript execution tool before declaring a blocker. +- Report a Chrome blocker only after the Chrome skill troubleshooting path fails: no JavaScript/Node REPL execution tool can be found, the Chrome extension cannot be reached after retry, the native host or extension is missing/disabled, Chrome is not running and the user does not approve launching it, or ChatGPT requires user-gated login/CAPTCHA/payment action. + +## Session Selection + +- If an existing ChatGPT tab is open, verify it by title, URL, and recency before reusing it. +- Prefer a Codex-owned ChatGPT work tab for staged harness loops. +- Do not borrow arbitrary user ChatGPT tabs unless the user explicitly asks for that. +- If a new tab is needed, open the ChatGPT web session and check whether Pro extended mode or Pro conversation mode is available. +- Do not assume a specific Chrome profile name, account name, local username, or fixed path. + +## Capability Selection + +- If a pinned or "고정됨" ChatGPT area visibly offers Search Mode, use it for search stages after confirming the selected mode in the composer or tool state. +- If pinned Search Mode is not visible, check the current ChatGPT tool menu, composer controls, or available mode picker before declaring it unavailable. +- Use normal chat for critique, synthesis, code review, and short reasoning tasks that do not need current web evidence. +- Use Search Mode for quick current web answers, source discovery, official docs checks, or narrow fact verification. +- Use deep research for multi-source investigation, market scans, long comparisons, literature-style synthesis, or questions that need a documented cited report. +- Use agent mode for bounded online tasks where ChatGPT needs to navigate websites or take actions on behalf of the user. Do not use agent mode for local filesystem work. +- If a requested capability is unavailable, report the exact visible state and fall back only with user approval or a clear local alternative. + +## Completion Channel + +- Use normal Chrome UI checks when no trusted local response bridge is installed. +- If CS WebLatch or another trusted local response bridge is installed and approved by the user, prefer it as the ChatGPT Web completion channel. +- Keep this harness responsible for goal tracking, stage control, approval gates, feedback classification, local edits, validation, and final reporting. +- Treat bridge completion events as completion signals, not as permission to bypass approval or safety rules. + +## Prompt Sending + +Include the following in each ChatGPT Pro prompt: + +- Confirmed final goal. +- Current stage number and desired stage outcome. +- Current local state summary. +- Context approved for sharing. +- Constraints and non-goals. +- Validation already run or planned. +- Desired output format. +- Capability Codex wants ChatGPT Pro to use: normal chat, Search Mode, deep research, agent mode, or apps. +- Output type Codex wants: critique, risks, alternatives, validation plan, implementation concerns, code-review findings, delegated draft, source-backed report, web task report, or final review. +- Evidence requirement: do not rely on reasoning alone when facts, source behavior, official docs, rankings, preferences, or public sentiment matter. +- Language: answer in Korean unless the user requested another language or the deliverable must be in another language. + +If sensitive data may be present, stop before sending and ask the user. + +## Research And Agent Prompts + +- For Search Mode, ask for source links, publication or update dates when visible, evidence quality labels, and a short claim-to-source mapping. +- For deep research, ask for a documented report with source table, confidence notes, gaps, community-sentiment notes when relevant, and follow-up checks Codex should perform locally. +- For agent mode, define the exact website task, allowed accounts or logged-out requirement, actions requiring confirmation, stop conditions, and what evidence to return. +- For preference, ranking, taste, popularity, or adoption questions, allow reputable public community sources and ask ChatGPT Pro to present them as opinion signals rather than official truth. +- Do not paste secrets, private credentials, customer data, private file contents, or full repository bundles into ChatGPT Pro unless the user explicitly approves that exact sharing scope. + +## Response Waiting + +- In Pro conversation mode, recheck whether the response is complete every 2 minutes after sending the question unless a trusted bridge provides a completion event. +- Do not repeat unnecessary intermediate status reports before the response is complete. +- If a UI error, disconnection, expired login, failed send, or bridge error is clear, report it immediately without waiting 2 minutes. + +## Completion Checks + +When using Chrome UI checks, treat the response as complete only when multiple signals agree: + +- The generating indicator or stop button is gone or inactive. +- The composer is not busy. +- The latest response text is stable across rechecks. +- Completion signals such as a copy button, response boundary, or final message are visible. + +Do not treat a visible send button alone as completion. + +## Session Cleanup + +- When work is done, clean up Chrome tabs or keep only tabs the user needs to continue viewing. +- Keep a Codex-owned ChatGPT work tab as a handoff only when the staged harness may continue later. +- If the page is waiting for user input, login, CAPTCHA, approval, or payment, leave the tab as a handoff. diff --git a/skills/chatgpt-collaboration-harness/references/delegated-work.md b/skills/chatgpt-collaboration-harness/references/delegated-work.md new file mode 100644 index 0000000..2e4daef --- /dev/null +++ b/skills/chatgpt-collaboration-harness/references/delegated-work.md @@ -0,0 +1,60 @@ +# Delegated Work + +## When To Delegate + +Use delegated-worker mode when ChatGPT Pro can produce a bounded artifact that Codex can verify locally: + +- Source-backed research brief. +- Alternative comparison. +- Bug triage or hypothesis list from shared logs. +- Test plan or edge-case matrix. +- Documentation, copy, migration notes, or release notes draft. +- Implementation sketch, patch suggestion, or refactor plan. + +Do not delegate work that requires unapproved secrets, broad architecture changes, local filesystem access, irreversible external actions, production changes, payment, account settings, or private data. + +## Delegation Packet + +Send a packet with: + +- Goal: one outcome for this subtask. +- Role: researcher, bug triager, test planner, implementation sketcher, copy drafter, or web task agent. +- Approved context: exact summary, excerpts, logs, URLs, screenshots, files, or diffs allowed for sharing. +- Constraints: repository rules, non-goals, forbidden actions, privacy limits, source preferences, and time or scope limits. +- Evidence rule: do not answer from inference alone when facts, source behavior, official docs, rankings, preferences, or public sentiment matter. +- Language rule: answer in Korean unless the user requested another language or the deliverable must be in another language. +- Deliverable: exact output format and maximum length. +- Acceptance criteria: what Codex will verify before accepting. +- Stop conditions: what requires user approval or a narrower prompt. + +## Output Contract + +Ask ChatGPT Pro to return: + +- Assumptions and unknowns. +- Main answer or artifact. +- Evidence: source links for research, local evidence references for code reasoning, official docs or primary sources when available, community sources only as opinion signals, or visible UI observations for web tasks. +- Evidence quality label for each material claim: official/source-backed, primary-source, secondary-source, community-sentiment, or speculation. +- Risks and failure modes. +- Concrete next steps for Codex. +- Items that require user judgment. + +For code-related delegation, ask for grouped file-level suggestions rather than a large unreviewed patch unless the user explicitly approved sharing enough context for a patch. + +## Local Integration + +Codex must: + +1. Read the result as untrusted input. +2. Verify claims against local files, official sources, tests, logs, or browser evidence. +3. Classify each useful point as accepted, rejected, deferred, or needs-local-verification. +4. Apply accepted work locally using the repository's normal workflow. +5. Run validation before marking the stage complete. + +## Agent Mode Boundaries + +Use ChatGPT agent mode only for bounded online tasks where the web session itself is the work surface. Prefer logged-out mode unless the user explicitly approves using a logged-in session. + +Agent mode still requires user approval for high-impact actions, sensitive sites, account changes, purchases, submissions, messages, publishing, production changes, or actions that are difficult to undo. + +Agent mode does not make ChatGPT Pro the owner of local code. Codex remains responsible for local files, commits, validation, and final reporting. diff --git a/skills/chatgpt-collaboration-harness/references/feedback-loop.md b/skills/chatgpt-collaboration-harness/references/feedback-loop.md new file mode 100644 index 0000000..d33044b --- /dev/null +++ b/skills/chatgpt-collaboration-harness/references/feedback-loop.md @@ -0,0 +1,140 @@ +# Feedback Loop + +## Loop State + +Track the following state during each stage: + +- Confirmed final goal. +- Current stage number, outcome, and validation criteria. +- What was shared with ChatGPT Pro. +- Which ChatGPT Pro capability was used: normal chat, Search Mode, deep research, agent mode, apps, or none. +- ChatGPT Pro's key feedback and useful original excerpts. +- Codex's judgment: accepted, rejected, or deferred. +- Local changes made. +- Validation results. +- Next stage or remaining risk. + +## Preapproval Mode + +At session startup, ask whether the user wants review-first mode or preapproved harness mode. + +In preapproved harness mode, the user may approve the whole planned staged loop in advance. This allows Codex to: + +- Proceed through planned stages sequentially. +- Send approved project summaries, selected diffs, or redacted logs to ChatGPT Pro. +- Apply clear, low-risk ChatGPT Pro suggestions. +- Send bounded delegated-worker packets and integrate low-risk output locally. +- Use Search Mode or deep research for approved public-web research. +- Run validation commands. +- Continue to the next stage when the current stage passes validation. +- Request final ChatGPT Pro review automatically. + +Preapproval does not cover: + +- Expanding external sharing beyond the approved scope. +- Sharing repository URLs, Git URLs, private files, secrets, credentials, customer data, or sensitive personal data unless explicitly approved. +- Broad architecture, dependency, data model, security, or UX direction changes. +- Destructive commands. +- Deployment, paid operations, account settings, production changes, credential changes, logged-in web actions, or write actions in external services. +- Actions that conflict with repository rules, AGENTS.md, work-rules, or explicit user instructions. + +When in doubt, stop and ask the user. + +## Stage Feedback Loop + +For each stage: + +1. Restate the current stage outcome and validation criteria. +2. Perform the local work required for the stage. +3. Ask ChatGPT Pro for focused feedback, delegated output, research, or agent work unless the stage is simple, mechanical, explicitly exempted, or the user asked to skip Pro involvement. +4. Request one primary output type from ChatGPT Pro: code review, implementation risk, debugging hypothesis, UX critique, test plan, alternative comparison, source-backed research brief, delegated draft, web task report, or final-stage readiness review. +5. Require Korean output and explicit evidence labels unless the user requested another language or the deliverable requires another language. +6. Classify feedback as accepted, rejected, deferred, or needs-local-verification. +7. Apply accepted feedback within the approved risk and sharing scope. +8. Run validation. +9. If validation fails, summarize the failure back to ChatGPT Pro and request narrow correction hypotheses. +10. Complete the stage only after validation passes or the user accepts a documented residual risk. + +## Delegated Work Loop + +Use delegated-worker mode when ChatGPT Pro can complete a bounded subtask more effectively than a simple review, such as source-backed research, alternative comparison, bug triage, test planning, copy drafting, implementation sketching, or documentation drafting. + +For delegated work: + +1. Send a packet with the goal, allowed context, constraints, exact deliverable, acceptance criteria, and what not to do. +2. Ask ChatGPT Pro to answer in Korean, state assumptions, cite sources when research is involved, and separate facts, community sentiment, speculation, and recommendations. +3. Treat the result as untrusted input until Codex verifies it locally. +4. Apply only the parts Codex can justify with repository evidence, source evidence, or validation output. +5. Record accepted, rejected, and deferred portions before continuing. + +## Codex Review Criteria + +Classify ChatGPT Pro feedback using these criteria: + +- Accepted: it matches local evidence, is low risk, and directly contributes to the goal. +- Rejected: it conflicts with repository rules, user instructions, security constraints, approved scope, or technical evidence. +- Deferred: it needs more information, user judgment, additional validation, or later-stage context. +- Needs-local-verification: it may be useful, but Codex has not yet reproduced, source-checked, or tested it. + +## Validation + +Run appropriate validation after edits: + +- Tests or build. +- Type checks or lint. +- Reproduction steps. +- Browser or manual flow checks. +- Logs and error message review. + +If validation cannot be run, report why and keep the residual risk visible. + +## Resync + +Before the next ChatGPT Pro turn, if local changes were made, send a delta packet: + +- Stage completed or in progress. +- Summary of changed files. +- Core diff or explanation. +- Validation commands and results. +- Remaining unresolved issue. +- Prior ChatGPT output classification and what Codex changed after local verification. + +Share full files, large diffs, logs, Git URLs, or repository URLs only after user approval. + +## Final Review + +After all planned stages are complete, ask ChatGPT Pro to review the final result. + +The final review packet should include: + +- Confirmed final goal. +- Stage list and completion summary. +- Key changes or relevant diff excerpts. +- Validation commands and results. +- Known tradeoffs and residual risks. +- ChatGPT Pro capabilities used and why each was appropriate. +- Specific request for defects, missed constraints, unsafe assumptions, and final corrections. + +Codex must treat final review feedback as advice. Apply only feedback that fits the user goal, repository rules, approved risk scope, and local validation evidence. + +## Exit Criteria + +End the loop when: + +- The goal is achieved and required validation is complete. +- Final ChatGPT Pro review has been handled. +- Product or design judgment from the user is needed. +- External sharing or broad change approval is required. +- The same blocking condition repeats and Codex cannot proceed. + +## Final Report Format + +The final report should include: + +- Goal and result. +- Stage completion summary. +- ChatGPT Pro capability summary and short original excerpts. +- Changes Codex applied. +- Validation results. +- Suggestions Codex rejected or deferred. +- Remaining risks. diff --git a/skills/chatgpt-collaboration-harness/references/file-artifact-exchange.md b/skills/chatgpt-collaboration-harness/references/file-artifact-exchange.md new file mode 100644 index 0000000..49d8b64 --- /dev/null +++ b/skills/chatgpt-collaboration-harness/references/file-artifact-exchange.md @@ -0,0 +1,89 @@ +# File Artifact Exchange + +Use this reference when a ChatGPT Pro collaboration stage needs screenshots, files, or generated artifacts. Codex remains responsible for approval scope, local validation, and final judgment. + +## Screenshot Attachments + +Use screenshots when visible UI state, remote screens, layout, design fidelity, chart output, document rendering, browser errors, or app behavior matters. + +Before upload: + +- Check for secrets, API keys, tokens, cookies, private URLs, internal hostnames, account details, customer data, personal data, private file paths, notifications, browser profile details, and unrelated windows. +- Crop or retake the screenshot when unrelated sensitive content is visible. +- State what the screenshot is supposed to prove and what ChatGPT Pro should inspect. +- Ask ChatGPT Pro to call out uncertainty when the evidence is not visible in the screenshot. + +Do not treat a screenshot critique as proof. Verify the relevant behavior locally after applying advice. + +## File Attachments + +Share the smallest approved file set that lets ChatGPT Pro do the stage. Prefer focused excerpts, diffs, failing logs, test output, screenshots, or generated reports over full repositories. + +Do not upload credentials, private keys, API tokens, database passwords, cookies, auth state, browser profiles, raw production data, customer data, private endpoints, or machine-specific trust settings. + +Large bundles, full source files, private repository material, Git URLs, repository URLs, browser state, and scope expansion require Hun's approval before sharing. + +## Attachment Packet + +When sending screenshots or files, include a compact manifest: + +```text +Objective: +Stage: +Attachments: +- : +Omitted on purpose: +- +Allowed inferences: +- +Not allowed: +- +Requested output: +- Classify advice as accepted, rejected, deferred, or needs-local-verification. +``` + +## Receiving Generated Artifacts + +Downloaded artifacts are untrusted until Codex validates them locally. + +Before using a returned file: + +- Record artifact name, type, source conversation, intended use, and any assumptions ChatGPT Pro stated. +- Save it to a review or temporary location before moving it into a project. +- For archives, inspect an archive listing before extraction and reject unexpected absolute paths, path traversal, hidden executables, oversized contents, or unrelated files. +- For documents, PDFs, images, slides, or spreadsheets, render or open them locally and inspect the visible result. +- For code, patches, configs, prompts, or data files, diff them against the target project and run the relevant validator, tests, or parser. +- For scripts, binaries, macros, installers, browser extensions, auth files, or anything executable, stop and ask before running or installing. + +## Artifact Return Contract + +Ask ChatGPT Pro to return generated artifacts with: + +- artifact name and file type; +- intended use; +- source inputs used; +- assumptions and omitted context; +- safety notes; +- validation steps Codex should run; +- any dependency, runtime, or format requirement. + +## Classification + +Classify every ChatGPT Pro artifact or attachment-derived answer as: + +- `accepted`: safe enough to integrate after local validation. +- `rejected`: incorrect, unsafe, off-scope, or not useful. +- `deferred`: potentially useful later but outside the current stage. +- `needs-local-verification`: plausible but not yet proven by local evidence. + +Do not advance a stage only because ChatGPT Pro generated a plausible file. The local evidence contract still decides completion. + +## Final Reporting + +When the stage or harness ends, report: + +- screenshots or files shared; +- artifacts received; +- artifacts accepted, rejected, deferred, or needs-local-verification; +- local validation run for accepted artifacts; +- anything withheld or requiring Hun's approval. diff --git a/skills/chatgpt-collaboration-harness/references/goal-harness.md b/skills/chatgpt-collaboration-harness/references/goal-harness.md new file mode 100644 index 0000000..3aa6e4a --- /dev/null +++ b/skills/chatgpt-collaboration-harness/references/goal-harness.md @@ -0,0 +1,55 @@ +# Goal Harness + +## Goal Setup + +- Compress the user's final objective into one actionable outcome. +- If the goal is unclear, do not start implementation or external sharing; explain Codex's understanding and confirm with the user. +- If goal tooling is available, inspect the current goal state first. +- If no goal is active and the user provided a confirmed goal, set that goal. +- If a goal is already active, check whether the new request conflicts with it; if it does, ask the user to choose the priority. + +## Stage Decomposition + +If the goal is broad, long-running, multi-file, ambiguous, or likely to need multiple review passes, decompose it into 1 to 10 concrete stages before implementation. + +Each stage should define: + +- Outcome: what must be true when the stage is complete. +- Scope: files, modules, or behavior likely to be touched. +- Context: what can be shared with ChatGPT Pro. +- ChatGPT role: reviewer, delegated worker, Search Mode researcher, deep research reporter, agent task executor, or skipped with reason. +- Validation: the command, test, browser check, or manual evidence required. +- Stop condition: what would require user judgment before continuing. + +Prefer fewer stages for small tasks and more stages for broad work. Do not create more than 10 stages unless the user explicitly approves a larger plan. + +## Stage Ordering + +- Work stages sequentially by default. +- Parallelize only when stages are independent and cannot edit the same files, mutate the same state, or rely on the same external resource. +- Keep the final objective stable while narrowing the current stage and next validation item. +- If new information changes the stage plan, explain the change and update the plan before continuing. + +## Goal Operating Rules + +- Write goals as outcomes. Example: "Reproduce the login error, fix it, and make the tests pass." +- Do not put browser session details, temporary prompts, or internal reasoning into the goal. +- Keep current evidence, completed stages, blocked stages, and next validation visible in working notes or status updates. +- When a stage is complete, record what changed, what was validated, which ChatGPT Pro capability was used, and what Codex accepted, rejected, or deferred. + +## Completion Handling + +- Mark a stage complete only when its outcome and validation criteria are satisfied. +- Mark the whole goal complete only when all required stages and final review handling are done. +- Do not mark the goal complete because the budget is low or the task is taking a long time. +- Report the goal as blocked only when the same blocking condition repeats and Codex cannot proceed without user input or an external state change. + +## When User Judgment Is Needed + +Stop the loop and ask the user when: + +- Product direction or UX direction would change. +- A large dependency, data model, architecture, or security policy change is needed. +- ChatGPT Pro and Codex disagree and local evidence is not enough to decide. +- External sharing scope would expand beyond the approved scope. +- The sensitivity of material to be shared externally is unclear. diff --git a/skills/chatgpt-collaboration-harness/references/search-deep-research.md b/skills/chatgpt-collaboration-harness/references/search-deep-research.md new file mode 100644 index 0000000..0795514 --- /dev/null +++ b/skills/chatgpt-collaboration-harness/references/search-deep-research.md @@ -0,0 +1,71 @@ +# Search And Deep Research + +## Routing + +Use the smallest research capability that can produce reliable evidence: + +- **Search Mode**: current facts, official documentation checks, source discovery, narrow comparisons, and quick verification. +- **Deep research**: multi-source synthesis, strategic research, technical landscape scans, competitive analysis, literature-style review, or any question that needs a documented cited report. +- **Agent mode**: online tasks where ChatGPT must navigate sites or perform bounded actions on behalf of the user. +- **Local Codex web search**: independent verification, official-source checks, or fallback when ChatGPT Pro search is unavailable. + +Do not treat a normal ChatGPT answer as source-backed research unless it contains inspectable sources. For high-impact legal, medical, financial, security, or production decisions, verify critical claims against primary sources. + +## Evidence Ladder + +Use the strongest evidence available for the question: + +1. Project source, reproducible local behavior, tests, logs, or screenshots from approved context. +2. Official documentation, specifications, release notes, API references, and first-party announcements. +3. Primary sources such as standards bodies, repositories, issue trackers, papers, filings, and product pages. +4. Reputable secondary sources when primary sources are unavailable or incomplete. +5. Public community sentiment: well-known communities, forums, issue threads, reviews, social discussions, and expert commentary. + +Use community sentiment for preferences, rankings, taste, adoption, ecosystem feel, and "what people like" questions that official sources cannot answer. Present it as directional opinion evidence, not verified fact, and keep enough detail for the user to decide whether to trust it. + +If ChatGPT Pro cannot inspect sources, it must say so and avoid making a confident recommendation from inference alone. + +## Search Mode Procedure + +1. In Chrome, open or reuse the ChatGPT Pro work tab. +2. If a pinned or "고정됨" area visibly exposes Search Mode, select it and confirm the composer or mode state shows search before sending. +3. If pinned Search Mode is absent, check the visible tool menu or mode picker for Search. +4. Ask for source links, publication or update dates when visible, and a claim-to-source table. +5. After the response, Codex checks the sources or reruns local web verification for claims that affect implementation, safety, or user-facing conclusions. + +## Deep Research Procedure + +Use deep research when the task needs broad source coverage or synthesis rather than quick lookup. + +Prompt for: + +- Research question and decision context. +- Source preferences: project source or official docs first for technical facts; primary sources next; reputable secondary sources only when primary sources are unavailable; community sources allowed for preference or popularity signals. +- Exclusions: low-quality SEO pages, unsourced claims, stale docs, irrelevant regions or versions, and confident claims based only on model inference. +- Output: Korean answer-first summary, source table, dated evidence, evidence quality labels, contradictions, confidence, community-sentiment notes when relevant, and follow-up checks for Codex. +- Stop condition: ask before using private files, connected apps, logged-in data, paid sources, or sensitive workspace material. + +## Agent Mode Procedure + +Use agent mode only when the work is an online task, not a local coding task. + +Prompt for: + +- Exact site or task. +- Logged-out or approved logged-in state. +- Actions allowed without asking. +- Actions requiring confirmation. +- Evidence to return: URLs visited, screenshots if appropriate, final state, blockers, and any user action needed. + +If agent mode encounters authentication, CAPTCHA, payment, account settings, sensitive data, production controls, or irreversible action, stop and ask the user. + +## Research Result Handling + +Codex should record: + +- Capability used: Search Mode, deep research, agent mode, apps, or local search. +- What was searched or delegated. +- Key sources and dates. +- Evidence quality and whether each important claim is official/source-backed, primary-source, secondary-source, community-sentiment, or speculation. +- Claims accepted, rejected, deferred, or needing local verification. +- How the research changed the stage plan or implementation. diff --git a/skills/hun-engineering-loop/SKILL.md b/skills/hun-engineering-loop/SKILL.md new file mode 100644 index 0000000..43a8036 --- /dev/null +++ b/skills/hun-engineering-loop/SKILL.md @@ -0,0 +1,100 @@ +--- +name: hun-engineering-loop +description: Use when Hun asks Codex to plan, implement, review, refactor, or QA software work using Hun's local engineering loop, memory preflight, source-of-truth checks, high-risk approval boundaries, and evidence-backed verification. +--- + +# Hun Engineering Loop + +## Purpose + +Run Hun's day-to-day engineering workflow as an operational wrapper around `karpathy-guidelines`, repository rules, memory recall, and executable verification. + +Use this for non-trivial project work. Do not use it as a replacement for repo `AGENTS.md`, scripts, tests, docs, or explicit user instructions. + +## Memory Preflight + +Before meaningful work, check available memory or journal context for the current repo, project name, feature, prior blocker, or user preference. + +- Remember: memory is a recall layer, not a source of truth. +- If memory conflicts with repo docs, scripts, tests, `AGENTS.md`, or observed runtime output, the current source wins. +- Verify drift-prone memory before using it for decisions. +- Record meaningful learnings only through the host's approved memory mechanism. + +## Source Of Truth + +Establish the current source-of-truth stack before editing: + +1. User's latest instruction. +2. Repo-local `AGENTS.md`, README, docs, scripts, tests, CI, and runtime output. +3. Project skill or project routing docs. +4. Memory and prior summaries. +5. External advice, including ChatGPT Pro, after local verification. + +Keep at least a minimal source-of-truth pointer in repo docs or `AGENTS.md` when a project depends on a skill. Do not hide all project routing inside global skills. + +## Access And Approval Boundary + +Broad access is operational capability, not permission to perform every action. + +Use a high-risk stop/ask boundary before actions that can delete, expose, spend, deploy, rotate, revoke, or materially change trust: + +- deleting source, sessions, history, databases, user data, or large directories; +- changing permissions, credentials, API keys, auth state, browser profiles, MCP endpoints, or security settings; +- touching production, deployment, billing, external accounts, or public-facing systems; +- rewriting history, force-pushing, bypassing hooks, disabling tests, or changing protected branches. + +Prefer natural-language rules plus permission profiles, hooks, or approval layers where the host supports them. In public templates, do not present broad access as the default recommendation. + +## Artifact-First Execution + +Convert broad intent into durable artifacts before open-ended work: + +- For implementation: write or update tests, specs, plans, or checklists that define success. +- For planning: produce a design/spec plus a stepwise implementation plan when architecture or rollout choices matter. +- For external review: summarize accepted, rejected, deferred, and needs-local-verification items. +- For reusable policy: put project-specific behavior in project docs or project skills, not global prose. + +## Verification Contract + +Name the evidence required before claiming completion. + +- `fast check`: smallest command that proves the touched surface is syntactically or structurally healthy. +- `targeted regression`: test or repro that covers the changed behavior or fixed bug. +- `type/lint/build`: project-level static checks when available. +- `browser/manual QA`: real UI check for browser, visual, or workflow changes. +- `deployment smoke`: live or preview check only when deploy/release state is in scope. +- `negative/regression test`: prove the old failure or unsafe path is blocked when applicable. + +Separate smoke evidence from official proof. Do not overclaim from HTTP 200, a local render, or a passing narrow test. + +## Skill QA Contract + +When the task creates or edits a skill, treat the skill as tested process code: + +- Start with a failing test, validation failure, or explicit pressure scenario when the repo can support it. +- Keep the skill trigger clear: when to use it, when not to use it, and which reference files to read. +- Run the skill validator and relevant repo tests. +- Check for private paths, credentials, secrets, browser profiles, auth state, and machine-specific trust settings. +- If the skill has a runtime copy, validate the installed runtime copy separately from the repo catalog source. +- Do not call the skill ready only because the Markdown reads well. + +## QA / Refactor Loop + +After the first working artifact: + +1. Run the targeted verification. +2. Review the diff for excess scope, duplicate helpers, hidden coupling, weak tests, swallowed errors, and unrelated formatting churn. +3. Refactor only where it reduces real duplication, clarifies boundaries, or matches existing project patterns. +4. Re-run the relevant verification after refactoring. + +Use `karpathy-guidelines` to keep the change simple, surgical, assumption-aware, and goal-driven. + +## Final Report + +Report only what is evidenced: + +- files or runtime paths changed; +- tests, checks, browser QA, or smoke checks run; +- accepted/rejected/deferred external advice; +- unresolved risks or verification not run; +- whether any runtime install or Codex restart is still needed. diff --git a/skills/hun-engineering-loop/agents/openai.yaml b/skills/hun-engineering-loop/agents/openai.yaml new file mode 100644 index 0000000..a4cb93a --- /dev/null +++ b/skills/hun-engineering-loop/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Hun Engineering Loop" + short_description: "Run Hun-specific engineering workflow" + default_prompt: "Use $hun-engineering-loop to work with memory preflight, source-of-truth checks, high-risk approval boundaries, artifact-first execution, and QA evidence before reporting completion." diff --git a/skills/karpathy-guidelines/SKILL.md b/skills/karpathy-guidelines/SKILL.md new file mode 100644 index 0000000..6a62d04 --- /dev/null +++ b/skills/karpathy-guidelines/SKILL.md @@ -0,0 +1,67 @@ +--- +name: karpathy-guidelines +description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria. +license: MIT +--- + +# Karpathy Guidelines + +Behavioral guidelines to reduce common LLM coding mistakes, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls. + +**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. + +## 1. Think Before Coding + +**Don't assume. Don't hide confusion. Surface tradeoffs.** + +Before implementing: +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them - don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +## 2. Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +## 3. Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it - don't delete it. + +When your changes create orphans: +- Remove imports/variables/functions that YOUR changes made unused. +- Don't remove pre-existing dead code unless asked. + +The test: Every changed line should trace directly to the user's request. + +## 4. Goal-Driven Execution + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: +- "Add validation" → "Write tests for invalid inputs, then make them pass" +- "Fix the bug" → "Write a test that reproduces it, then make it pass" +- "Refactor X" → "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan: +``` +1. [Step] → verify: [check] +2. [Step] → verify: [check] +3. [Step] → verify: [check] +``` + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. diff --git a/skills/karpathy-guidelines/agents/openai.yaml b/skills/karpathy-guidelines/agents/openai.yaml new file mode 100644 index 0000000..6163fd2 --- /dev/null +++ b/skills/karpathy-guidelines/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Karpathy Guidelines" + short_description: "Apply cautious, simple, surgical coding guidelines" + default_prompt: "Use $karpathy-guidelines to surface assumptions, prefer simple implementation, keep changes surgical, and define verifiable success criteria before coding or reviewing." diff --git a/skills/karpathy-guidelines/references/SOURCE.md b/skills/karpathy-guidelines/references/SOURCE.md new file mode 100644 index 0000000..f49a930 --- /dev/null +++ b/skills/karpathy-guidelines/references/SOURCE.md @@ -0,0 +1,10 @@ +# Source + +This catalog skill preserves the upstream `karpathy-guidelines` skill from: + +- Repository: https://github.com/multica-ai/andrej-karpathy-skills +- Upstream commit inspected: `2c606141936f1eeef17fa3043a72095b4765b9c2` +- Upstream file: `skills/karpathy-guidelines/SKILL.md` +- License declared by upstream skill frontmatter: MIT + +Treat this directory as an original catalog/vendor skill. Do not fold Hun-specific workflow rules into it. Put local operational policy in `hun-engineering-loop` instead. diff --git a/tests/test_prompt_corpus_policy.py b/tests/test_prompt_corpus_policy.py index 9247c4b..4f69789 100644 --- a/tests/test_prompt_corpus_policy.py +++ b/tests/test_prompt_corpus_policy.py @@ -77,6 +77,37 @@ def test_root_prompt_contains_structure_guardrails(self): for phrase in expected_phrases: self.assertIn(phrase, root_prompt) + def test_root_prompt_contains_access_and_memory_boundaries(self): + root_prompt = (REPO_ROOT / "AGENTS.md").read_text() + + expected_phrases = ( + "Access and approval boundary", + "Broad filesystem or tool access is operational capability, not blanket approval", + "High-risk actions require an explicit stop and ask", + "delete data, prune history, rotate credentials, change permissions", + "production, deployment, billing, external accounts, secrets, auth state, browser profiles", + "Memory is a recall layer, not a source of truth", + "repo docs, scripts, tests, AGENTS files, and observed runtime output win", + "Project-specific operating knowledge belongs in project docs or project skills", + ) + for phrase in expected_phrases: + self.assertIn(phrase, root_prompt) + + def test_root_prompt_contains_skill_creation_qa_contract(self): + root_prompt = (REPO_ROOT / "AGENTS.md").read_text() + + expected_phrases = ( + "Skill creation and QA", + "When creating or editing a skill, treat the skill as tested process code", + "Start with a failing test or explicit pressure scenario", + "run the skill validator", + "check for private paths and secrets", + "verify any runtime copy separately from the repo catalog source", + "Do not claim a skill is ready only because the Markdown looks reasonable", + ) + for phrase in expected_phrases: + self.assertIn(phrase, root_prompt) + def test_role_agents_include_guardrail_responsibilities(self): expectations = { "planner.md": ( diff --git a/tests/test_readme_docs.py b/tests/test_readme_docs.py index 1ee5450..2f0f1cb 100644 --- a/tests/test_readme_docs.py +++ b/tests/test_readme_docs.py @@ -16,6 +16,49 @@ def test_main_readme_has_language_switcher_and_value_props(self) -> None: self.assertIn("subagents", readme) self.assertIn("token-efficient", readme) + def test_readmes_mark_codex_claude_as_current_public_focus(self) -> None: + expectations = { + "README.md": ( + "Current Public Focus", + "Codex and Claude Code are the current first-class setup targets", + "OpenCode and OpenClaw remain optional/reference surfaces", + ), + "README.ko.md": ( + "현재 공개 범위", + "Codex와 Claude Code가 현재 first-class setup target", + "OpenCode와 OpenClaw는 optional/reference surface", + ), + "README.ja.md": ( + "現在の公開スコープ", + "Codex と Claude Code が現在の first-class setup target", + "OpenCode と OpenClaw は optional/reference surface", + ), + "README.zh-CN.md": ( + "当前公开范围", + "Codex 和 Claude Code 是当前 first-class setup target", + "OpenCode 和 OpenClaw 保持为 optional/reference surface", + ), + } + + for relative, phrases in expectations.items(): + with self.subTest(relative=relative): + readme = (REPO_ROOT / relative).read_text(encoding="utf-8") + for phrase in phrases: + self.assertIn(phrase, readme) + + def test_main_readme_documents_private_project_skills_stay_local(self) -> None: + readme = (REPO_ROOT / "README.md").read_text(encoding="utf-8") + + expected_phrases = ( + "Private Project Skills", + "Do not commit private project skills such as auto-eva", + "`~/.codex/skills`", + "`~/.claude/skills`", + "templates and public-safe process guidance", + ) + for phrase in expected_phrases: + self.assertIn(phrase, readme) + def test_translated_readmes_exist_with_language_switcher(self) -> None: for relative in ("README.ko.md", "README.ja.md", "README.zh-CN.md"): contents = (REPO_ROOT / relative).read_text(encoding="utf-8") diff --git a/tests/test_skill_catalog.py b/tests/test_skill_catalog.py new file mode 100644 index 0000000..373dad5 --- /dev/null +++ b/tests/test_skill_catalog.py @@ -0,0 +1,242 @@ +from pathlib import Path +import unittest + + +REPO_ROOT = Path(__file__).resolve().parents[1] +PRIVATE_HOME_PATH = "/" + "Users/hooooonje" + + +class SkillCatalogTests(unittest.TestCase): + def test_catalog_lists_chatgpt_collaboration_harness_first(self) -> None: + catalog = (REPO_ROOT / "skills" / "README.md").read_text(encoding="utf-8") + + first_entry = catalog.index("### chatgpt-collaboration-harness") + karpathy_entry = catalog.index("### karpathy-guidelines") + hun_loop_entry = catalog.index("### hun-engineering-loop") + template_entry = catalog.index("### _template") + self.assertLess(first_entry, template_entry) + self.assertLess(first_entry, karpathy_entry) + self.assertLess(karpathy_entry, hun_loop_entry) + self.assertLess(hun_loop_entry, template_entry) + self.assertIn("browse, review, select, then install", catalog) + self.assertIn("not an always-install bootstrap", catalog) + self.assertIn("~/.codex/skills", catalog) + self.assertIn("community-sentiment", catalog) + self.assertIn("Korean by default", catalog) + self.assertIn("original catalog/vendor skill", catalog) + self.assertIn("Hun-specific operational wrapper", catalog) + self.assertNotIn(PRIVATE_HOME_PATH, catalog) + + def test_karpathy_guidelines_source_is_preserved(self) -> None: + skill_root = REPO_ROOT / "skills" / "karpathy-guidelines" + + self.assertTrue((skill_root / "SKILL.md").exists()) + self.assertTrue((skill_root / "references" / "SOURCE.md").exists()) + + skill = (skill_root / "SKILL.md").read_text(encoding="utf-8") + source = (skill_root / "references" / "SOURCE.md").read_text( + encoding="utf-8" + ) + + self.assertIn("name: karpathy-guidelines", skill) + self.assertIn("license: MIT", skill) + self.assertIn("Think Before Coding", skill) + self.assertIn("Simplicity First", skill) + self.assertIn("Surgical Changes", skill) + self.assertIn("Goal-Driven Execution", skill) + self.assertIn("https://github.com/multica-ai/andrej-karpathy-skills", source) + self.assertIn("2c606141936f1eeef17fa3043a72095b4765b9c2", source) + self.assertIn("MIT", source) + self.assertNotIn(PRIVATE_HOME_PATH, source) + + def test_hun_engineering_loop_wraps_karpathy_with_local_policy(self) -> None: + skill_root = REPO_ROOT / "skills" / "hun-engineering-loop" + + self.assertTrue((skill_root / "SKILL.md").exists()) + self.assertTrue((skill_root / "agents" / "openai.yaml").exists()) + + skill = (skill_root / "SKILL.md").read_text(encoding="utf-8") + + expected_sections = ( + "Memory Preflight", + "Source Of Truth", + "Access And Approval Boundary", + "Artifact-First Execution", + "Verification Contract", + "QA / Refactor Loop", + "Final Report", + ) + for section in expected_sections: + self.assertIn(section, skill) + + expected_phrases = ( + "karpathy-guidelines", + "memory is a recall layer, not a source of truth", + "high-risk stop/ask boundary", + "permission profiles, hooks, or approval layers", + "fast check", + "targeted regression", + "type/lint/build", + "deployment smoke", + ) + for phrase in expected_phrases: + self.assertIn(phrase, skill) + + def test_project_skill_template_contains_qa_evidence_contract(self) -> None: + template = (REPO_ROOT / "skills" / "_template" / "SKILL.md.template").read_text( + encoding="utf-8" + ) + + expected_sections = ( + "Scope / Non-goals", + "Memory Preflight", + "Source Of Truth", + "Access And Approval Boundary", + "Artifact-First Execution", + "Verification Contract", + "QA / Refactor Loop", + "Final Report", + ) + for section in expected_sections: + self.assertIn(section, template) + + expected_phrases = ( + "fast check", + "targeted regression", + "type/lint/build", + "browser/manual QA", + "deployment smoke", + "negative/regression test", + "memory is a recall layer, not a source of truth", + ) + for phrase in expected_phrases: + self.assertIn(phrase, template) + + def test_private_project_skills_are_not_cataloged(self) -> None: + catalog = (REPO_ROOT / "skills" / "README.md").read_text(encoding="utf-8") + + self.assertFalse((REPO_ROOT / "skills" / "auto-eva").exists()) + expected_phrases = ( + "Private project skills such as auto-eva", + "not this public catalog", + "~/.codex/skills", + "~/.claude/skills", + "templates and public-safe process guidance", + ) + for phrase in expected_phrases: + self.assertIn(phrase, catalog) + self.assertNotIn(PRIVATE_HOME_PATH, catalog) + + def test_chatgpt_collaboration_harness_source_is_cataloged(self) -> None: + skill_root = REPO_ROOT / "skills" / "chatgpt-collaboration-harness" + expected_files = ( + "SKILL.md", + "agents/openai.yaml", + "references/goal-harness.md", + "references/feedback-loop.md", + "references/chrome-chatgpt-pro.md", + "references/delegated-work.md", + "references/search-deep-research.md", + "references/file-artifact-exchange.md", + ) + + for relative in expected_files: + with self.subTest(relative=relative): + self.assertTrue((skill_root / relative).exists()) + + skill = (skill_root / "SKILL.md").read_text(encoding="utf-8") + self.assertIn("Evidence And Language Rules", skill) + self.assertIn("community-sentiment", skill) + self.assertIn("keep the ChatGPT Pro conversation", skill) + self.assertIn("screenshots, files, or generated artifacts", skill) + self.assertIn("file-artifact-exchange.md", skill) + + prompt = (skill_root / "agents" / "openai.yaml").read_text(encoding="utf-8") + self.assertIn("source-backed evidence", prompt) + self.assertIn("Korean", prompt) + self.assertIn("screenshots, files, and artifacts", prompt) + + def test_chatgpt_collaboration_harness_documents_file_artifact_exchange(self) -> None: + reference = ( + REPO_ROOT + / "skills" + / "chatgpt-collaboration-harness" + / "references" + / "file-artifact-exchange.md" + ).read_text(encoding="utf-8") + + expected_phrases = ( + "Screenshot Attachments", + "File Attachments", + "Receiving Generated Artifacts", + "Attachment Packet", + "Artifact Return Contract", + "Check for secrets", + "Do not upload credentials", + "Downloaded artifacts are untrusted until Codex validates them locally", + "archive listing before extraction", + "accepted, rejected, deferred, or needs-local-verification", + ) + for phrase in expected_phrases: + self.assertIn(phrase, reference) + self.assertNotIn(PRIVATE_HOME_PATH, reference) + + def test_skill_setup_guide_documents_selective_install_flow(self) -> None: + guide = (REPO_ROOT / "docs" / "codex-skills.md").read_text(encoding="utf-8") + + expected_phrases = ( + "Skill Catalog", + "browse, review, select, install", + "repo copy is the catalog source", + "installed copy is the runtime copy", + "Do not install every skill automatically", + "git status --short --branch", + "quick_validate.py", + "PyYAML", + "community-sentiment", + "one ChatGPT work tab or conversation per project", + "screenshots, files, and generated artifacts", + "karpathy-guidelines", + "hun-engineering-loop", + "memory is a recall layer, not a source of truth", + "high-risk stop/ask boundary", + "permission profiles, hooks, or approval layers", + "source-of-truth pointer", + "QA evidence contract", + ) + for phrase in expected_phrases: + self.assertIn(phrase, guide) + self.assertNotIn(PRIVATE_HOME_PATH, guide) + + def test_setup_prompt_keeps_installation_approval_gated(self) -> None: + prompt = (REPO_ROOT / "prompts" / "setup-codex-skills.md").read_text( + encoding="utf-8" + ) + + expected_phrases = ( + "Review and optionally install Codex skills from this repository.", + "git status --short --branch", + "skills/README.md", + "docs/codex-skills.md", + "chatgpt-collaboration-harness", + "Compare the catalog copy with the installed runtime copy", + "Ask before installing or overwriting", + "quick_validate.py", + "Do not copy private paths, credentials, MCP endpoints, auth state, or browser profiles", + "file-artifact-exchange", + "skill QA contract", + ) + for phrase in expected_phrases: + self.assertIn(phrase, prompt) + self.assertNotIn(PRIVATE_HOME_PATH, prompt) + + def test_readme_links_skill_catalog_workflow(self) -> None: + readme = (REPO_ROOT / "README.md").read_text(encoding="utf-8") + + self.assertIn("docs/codex-skills.md", readme) + self.assertIn("prompts/setup-codex-skills.md", readme) + self.assertIn("skills/README.md", readme) + + +if __name__ == "__main__": + unittest.main()