@pzy560117/codex-harness 0.1.2 → 0.1.4

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/sync-project-root-docs/SKILL.md

@@ -1,143 +1,145 @@
----
-name: sync-project-root-docs
-description: Analyze the current repository and rewrite the root AGENTS.md and README.md so they match the actual project instead of template or stale content. Use when either root doc is placeholder text, copied from another repo, outdated after harness/package changes, or when project positioning must be inferred from scripts, task/runtime files, docs, and optional GitHub research.
----
-
-# Sync Project Root Docs
-
-## Overview
-
-Use this skill to refresh the repository-root `AGENTS.md` and `README.md` from the repo's real source of truth. Prefer local evidence first, then use GitHub research only to resolve structure or convention gaps.
-
-## Scope
-
-- Default write set: `AGENTS.md`, `README.md`
-- Default read set: root runtime files, `docs/harness/*`, `docs/testing/*`, `.agents/*`, `docs/codex-harness-engineering/*`, and `.codex/task-run-profile.json`
-- Do not edit `README.md`, `.agents/README.md`, template copies, or `task.json` unless the user explicitly asks to propagate the change beyond the root docs
-
-## Workflow
-
-### 1. Identify the repository surface
-
-- Inspect the root tree and decide whether the repo is primarily an application, a reusable package, a template, or a harness/runtime repo.
-- Read `git status --short` before drafting so you do not overwrite unrelated user edits.
-- Detect placeholder signals such as generated boilerplate, smoke-task wording, or copied template sections.
-
-If available, run:
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\.agents\skills\sync-project-root-docs\scripts\collect-root-doc-facts.ps1
-```
-
-Use the output as discovery input, not as final prose.
-
-### 2. Build the truth-source stack
-
-Read only what is needed, roughly in this order:
-
-1. Root docs: `AGENTS.md`, `README.md`
-2. Runtime and entry files:
-   `tools/install/bootstrap-codex-harness.ps1`, `tools/harness/codex-loop.ps1`, `tools/harness/verify.ps1`, `tools/install/env-check.ps1`, `task.json`, `tools/harness/templates/project-task-template.json`, `.codex/task-run-profile.json`
-3. Human-facing docs:
-   `docs/harness/*.md`, `docs/testing/*.md`
-4. Package and export surfaces when present:
-   `.agents/README.md`, `.agents/PACKAGE.md`, `README.md`, `PACKAGE.md`, install scripts
-5. Role and delegation rules:
-   `.codex/rules/agents.md`
-
-For the current harness repo, read [references/current-repo-notes.md](references/current-repo-notes.md).
-
-When generating `AGENTS.md` for a project, use the generic template at `docs/codex-harness-engineering/templates/docs/project-agents-template.md` if it exists. Treat it as a decision framework, not as text to copy verbatim.
-
-### 3. Research GitHub only when it changes the answer
-
-Use GitHub examples when the local repo tells you what exists but not how to present it well.
-
-Prioritize these patterns:
-
-- `agentsmd/agents.md`: treat `AGENTS.md` as a README for agents
-- `openai/codex`: keep AGENTS concrete, command-heavy, and tied to real files
-- `vercel-labs/skills` and `github/awesome-copilot`: validate skill naming/frontmatter and keep README sync in mind
-
-Use the notes in [references/github-samples.md](references/github-samples.md). Do not copy external wording verbatim into the repo docs.
-
-### 4. Split responsibilities between the two root docs
-
-Write `README.md` for humans:
-
-- what the repo is
-- what the important directories are
-- how to install, verify, and run it
-- where deeper docs live
-
-Write `AGENTS.md` for coding agents:
-
-- short project-specific entry rules
-- real commands and source-of-truth files
-- architecture or directory constraints that cannot be inferred from code
-- task, workspace, and verification expectations
-- repo-specific caveats and Bad Cases that affect execution
-- links to deeper docs instead of long embedded explanations
-
-Avoid duplicating the same long instruction blocks in both files. Prefer short cross-references when possible.
-
-### 5. Draft the section outline before editing
-
-Use a minimal outline unless the repo truly needs more:
-
-`README.md`
-
-1. Project summary
-2. Repository structure
-3. Common PowerShell commands
-4. Runtime and package boundaries
-5. Suggested workflow
-6. Further reading
-
-`AGENTS.md`
-
-1. Project boundary and actual entry points
-2. Common commands
-3. Architecture and directory decision table
-4. Hard constraints with alternatives
-5. Verification and completion definition
-6. Workspace / Git rules
-7. Deep doc index
-
-Keep the root `AGENTS.md` concise. For most projects, aim for 60-120 lines. If the draft grows past that, move details into `docs/`, `rules/`, `specs/`, or test docs and link them from the index.
-
-### 6. Apply repository-aware wording
-
-- Prefer Windows and PowerShell commands when the repo is Windows-first.
-- State placeholder or smoke-template status plainly when it is still true.
-- If both `.agents/` and template/package-assets mirrors exist, explain the distinction exactly.
-- If install/bootstrap scripts derive files from templates, make that relationship explicit.
-- Preserve important existing constraints unless the code or docs clearly contradict them.
-- Do not copy README product introductions into `AGENTS.md`; README explains what the project is, while `AGENTS.md` explains how agents should safely change it.
-- Do not add generic coding advice that would be true in any repository.
-- Every prohibition must include the expected alternative path, helper, command, or owner.
-- Prefer decision tables when multiple valid implementation paths exist.
-- If a rule can be enforced by lint, schema, hook, CI, or a verify script, mention the enforcement point rather than writing a long reminder.
-
-### 7. Verify after editing
-
-Run at least:
-
-```powershell
-git diff --check
-rg -n "generated by install-agent|Replace it with project-specific content|\\[TODO|placeholder" AGENTS.md README.md
-```
-
-If commands were added or changed, confirm the referenced files and scripts actually exist.
-
-Also review `AGENTS.md` against the template checks:
-
-- It is a short entry point, not a full project manual.
-- Deep docs referenced from the file exist.
-- Prohibitions include alternatives.
-- Real commands and paths are used instead of placeholders.
-- Any repeated Bad Case is captured as a rule or linked knowledge item.
-
-## Shipping note
-
-If the repo is itself a distributable harness or template, updating `.agents/skills/<name>` may not be enough. Follow the package duplication chain used by the repo before considering the work complete.
+---
+name: sync-project-root-docs
+description: Analyze the current repository and rewrite the root AGENTS.md and README.md so they match the actual project instead of template or stale content. Use when either root doc is placeholder text, copied from another repo, outdated after harness/package changes, or when project positioning must be inferred from scripts, task/runtime files, docs, and optional GitHub research.
+---
+
+# Sync Project Root Docs
+
+## Overview
+
+Use this skill to refresh the repository-root `AGENTS.md` and `README.md` from the repo's real source of truth. Prefer local evidence first, then use GitHub research only to resolve structure or convention gaps.
+
+## Scope
+
+- Default write set: `AGENTS.md`, `README.md`
+- Default read set: root runtime files, `docs/harness/*`, `docs/testing/*`, `.agents/*`, `docs/codex-harness-engineering/*`, and `.codex/task-run-profile.json`
+- Do not edit `README.md`, `.agents/README.md`, template copies, or `task.json` unless the user explicitly asks to propagate the change beyond the root docs
+
+If the target repository is a thin install project and `docs/harness/*` or `docs/testing/*` are absent from the project root, read `.codex-harness/state/config.json` first and use the same relative paths under `packageRoot`.
+
+## Workflow
+
+### 1. Identify the repository surface
+
+- Inspect the root tree and decide whether the repo is primarily an application, a reusable package, a template, or a harness/runtime repo.
+- Read `git status --short` before drafting so you do not overwrite unrelated user edits.
+- Detect placeholder signals such as generated boilerplate, smoke-task wording, or copied template sections.
+
+If available, run:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\.agents\skills\sync-project-root-docs\scripts\collect-root-doc-facts.ps1
+```
+
+Use the output as discovery input, not as final prose.
+
+### 2. Build the truth-source stack
+
+Read only what is needed, roughly in this order:
+
+1. Root docs: `AGENTS.md`, `README.md`
+2. Runtime and entry files:
+   `tools/install/bootstrap-codex-harness.ps1`, `tools/harness/codex-loop.ps1`, `tools/harness/verify.ps1`, `tools/install/env-check.ps1`, `task.json`, `tools/harness/templates/project-task-template.json`, `.codex/task-run-profile.json`
+3. Human-facing docs:
+   `docs/harness/*.md`, `docs/testing/*.md`
+4. Package and export surfaces when present:
+   `.agents/README.md`, `.agents/PACKAGE.md`, `README.md`, `PACKAGE.md`, install scripts
+5. Role and delegation rules:
+   `.codex/rules/agents.md`
+
+For the current harness repo, read [references/current-repo-notes.md](references/current-repo-notes.md).
+
+When generating `AGENTS.md` for a project, use the generic template at `docs/codex-harness-engineering/templates/docs/project-agents-template.md` if it exists. Treat it as a decision framework, not as text to copy verbatim.
+
+### 3. Research GitHub only when it changes the answer
+
+Use GitHub examples when the local repo tells you what exists but not how to present it well.
+
+Prioritize these patterns:
+
+- `agentsmd/agents.md`: treat `AGENTS.md` as a README for agents
+- `openai/codex`: keep AGENTS concrete, command-heavy, and tied to real files
+- `vercel-labs/skills` and `github/awesome-copilot`: validate skill naming/frontmatter and keep README sync in mind
+
+Use the notes in [references/github-samples.md](references/github-samples.md). Do not copy external wording verbatim into the repo docs.
+
+### 4. Split responsibilities between the two root docs
+
+Write `README.md` for humans:
+
+- what the repo is
+- what the important directories are
+- how to install, verify, and run it
+- where deeper docs live
+
+Write `AGENTS.md` for coding agents:
+
+- short project-specific entry rules
+- real commands and source-of-truth files
+- architecture or directory constraints that cannot be inferred from code
+- task, workspace, and verification expectations
+- repo-specific caveats and Bad Cases that affect execution
+- links to deeper docs instead of long embedded explanations
+
+Avoid duplicating the same long instruction blocks in both files. Prefer short cross-references when possible.
+
+### 5. Draft the section outline before editing
+
+Use a minimal outline unless the repo truly needs more:
+
+`README.md`
+
+1. Project summary
+2. Repository structure
+3. Common PowerShell commands
+4. Runtime and package boundaries
+5. Suggested workflow
+6. Further reading
+
+`AGENTS.md`
+
+1. Project boundary and actual entry points
+2. Common commands
+3. Architecture and directory decision table
+4. Hard constraints with alternatives
+5. Verification and completion definition
+6. Workspace / Git rules
+7. Deep doc index
+
+Keep the root `AGENTS.md` concise. For most projects, aim for 60-120 lines. If the draft grows past that, move details into `docs/`, `rules/`, `specs/`, or test docs and link them from the index.
+
+### 6. Apply repository-aware wording
+
+- Prefer Windows and PowerShell commands when the repo is Windows-first.
+- State placeholder or smoke-template status plainly when it is still true.
+- If both `.agents/` and template/package-assets mirrors exist, explain the distinction exactly.
+- If install/bootstrap scripts derive files from templates, make that relationship explicit.
+- Preserve important existing constraints unless the code or docs clearly contradict them.
+- Do not copy README product introductions into `AGENTS.md`; README explains what the project is, while `AGENTS.md` explains how agents should safely change it.
+- Do not add generic coding advice that would be true in any repository.
+- Every prohibition must include the expected alternative path, helper, command, or owner.
+- Prefer decision tables when multiple valid implementation paths exist.
+- If a rule can be enforced by lint, schema, hook, CI, or a verify script, mention the enforcement point rather than writing a long reminder.
+
+### 7. Verify after editing
+
+Run at least:
+
+```powershell
+git diff --check
+rg -n "generated by install-agent|Replace it with project-specific content|\\[TODO|placeholder" AGENTS.md README.md
+```
+
+If commands were added or changed, confirm the referenced files and scripts actually exist.
+
+Also review `AGENTS.md` against the template checks:
+
+- It is a short entry point, not a full project manual.
+- Deep docs referenced from the file exist.
+- Prohibitions include alternatives.
+- Real commands and paths are used instead of placeholders.
+- Any repeated Bad Case is captured as a rule or linked knowledge item.
+
+## Shipping note
+
+If the repo is itself a distributable harness or template, updating `.agents/skills/<name>` may not be enough. Follow the package duplication chain used by the repo before considering the work complete.

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/sync-project-root-docs/references/current-repo-notes.md

@@ -1,41 +1,42 @@
-# Current Repo Notes
-
-## Identity
-
-- This repository currently reads as a Codex Harness runtime plus package templates, not as a finished business application.
-- The root runtime surface includes `AGENTS.md`, `tools/install/bootstrap-codex-harness.ps1`, `tools/harness/codex-loop.ps1`, `tools/harness/doctor.ps1`, `tools/install/env-check.ps1`, `tools/harness/verify.ps1`, `task.json`, `tools/harness/templates/project-task-template.json`, `progress.txt`, and `docs/harness/trace.schema.json`.
-- `.agents/` is the active capability surface used inside this repo.
-- `docs/codex-harness-engineering/templates/` and package-assets are the distributable template/package surfaces used to install the harness into other projects.
-- `docs/harness/` contains runtime usage rules for installed projects.
-- `docs/testing/` contains verification and test-planning truth sources.
-
-## Commands Worth Surfacing
-
-- Bootstrap root runtime:
-  `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/install/bootstrap-codex-harness.ps1`
-- Environment check:
-  `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/install/env-check.ps1`
-- Verification:
-  `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/verify.ps1`
-- Doctor:
-  `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/doctor.ps1`
-- Driver once / until done:
-  `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/codex-loop.ps1`
-  `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/codex-loop.ps1 -RunUntilDone`
-- Install from package:
-  `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -Mode full -InitSmoke -InitGitIfNeeded`
-
-## Content Signals
-
-- The root `README.md` is still placeholder content generated by `tools/install/install-agent.ps1`.
-- The root `task.json` is still the smoke template with `SMOKE-001`.
-- `tools/harness/templates/project-task-template.json` already contains the real driver-first handoff template.
-- `.codex/task-run-profile.json` defines the fresh-process default, context sources, and allowed writer/read-only roles.
-- `tools/install/bootstrap-codex-harness.ps1` copies root runtime files, `.codex/agents`, `docs/harness/`, and `docs/testing/` from template sources.
-- `tools/install/install-agent.ps1` installs `.agents/` from `docs/codex-harness-engineering/templates/package-assets/` and then bootstraps the project root.
-
-## Implications For Root Docs
-
-- `README.md` should position the repo as a harness/package repo and explain both runtime and distributable-package surfaces.
-- `AGENTS.md` should remain operational, but add a short project overview and explicit truth-source boundaries when that helps agents avoid reading the wrong copy.
-- When a new skill is intended to ship with installed projects, syncing only `.agents/skills/` is incomplete in this repo; the package-facing copies may also need to be updated.
+# Current Repo Notes
+
+## Identity
+
+- This repository currently reads as a Codex Harness runtime plus package templates, not as a finished business application.
+- The root runtime surface includes `AGENTS.md`, `tools/install/bootstrap-codex-harness.ps1`, `tools/harness/codex-loop.ps1`, `tools/harness/doctor.ps1`, `tools/install/env-check.ps1`, `tools/harness/verify.ps1`, `task.json`, `tools/harness/templates/project-task-template.json`, `progress.txt`, and `docs/harness/trace.schema.json`.
+- `.agents/` is the active capability surface used inside this repo.
+- `docs/codex-harness-engineering/templates/` and package-assets are the distributable template/package surfaces used to install the harness into other projects.
+- `docs/harness/` contains runtime usage rules for installed projects.
+- `docs/testing/` contains verification and test-planning truth sources.
+- For thin install projects, the same deep docs may live only under `.codex-harness/state/config.json` -> `packageRoot`, not under the project root.
+
+## Commands Worth Surfacing
+
+- Bootstrap root runtime:
+  `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/install/bootstrap-codex-harness.ps1`
+- Environment check:
+  `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/install/env-check.ps1`
+- Verification:
+  `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/verify.ps1`
+- Doctor:
+  `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/doctor.ps1`
+- Driver once / until done:
+  `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/codex-loop.ps1`
+  `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/codex-loop.ps1 -RunUntilDone`
+- Install from package:
+  `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -Mode full -InitSmoke -InitGitIfNeeded`
+
+## Content Signals
+
+- The root `README.md` is still placeholder content generated by `tools/install/install-agent.ps1`.
+- The root `task.json` is still the smoke template with `SMOKE-001`.
+- `tools/harness/templates/project-task-template.json` already contains the real driver-first handoff template.
+- `.codex/task-run-profile.json` defines the fresh-process default, context sources, and allowed writer/read-only roles.
+- `tools/install/bootstrap-codex-harness.ps1` copies root runtime files, `.codex/agents`, `docs/harness/`, and `docs/testing/` from template sources.
+- `tools/install/install-agent.ps1` installs `.agents/` from `docs/codex-harness-engineering/templates/package-assets/` and then bootstraps the project root.
+
+## Implications For Root Docs
+
+- `README.md` should position the repo as a harness/package repo and explain both runtime and distributable-package surfaces.
+- `AGENTS.md` should remain operational, but add a short project overview and explicit truth-source boundaries when that helps agents avoid reading the wrong copy.
+- When a new skill is intended to ship with installed projects, syncing only `.agents/skills/` is incomplete in this repo; the package-facing copies may also need to be updated.

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/sync-project-root-docs/references/github-samples.md

@@ -1,33 +1,33 @@
-# GitHub Samples
-
-Use these repositories for structure and quality signals, not for copy-pasting text.
-
-## AGENTS.md patterns
-
-- `https://github.com/agentsmd/agents.md`
-  - Treat `AGENTS.md` as a predictable "README for agents".
-  - Include concrete development and testing instructions.
-
-- `https://github.com/openai/codex/blob/main/AGENTS.md`
-  - Keep AGENTS tied to real files, commands, and change-impact rules.
-  - Update docs when behavior or APIs change.
-
-## Skills and README sync patterns
-
-- `https://github.com/vercel-labs/skills/blob/main/AGENTS.md`
-  - Skill ecosystems usually document the exact create/validate/sync commands.
-  - README maintenance is treated as part of shipping a new capability.
-
-- `https://github.com/github/awesome-copilot/blob/main/AGENTS.md`
-  - Skill folders use kebab-case names and valid frontmatter.
-  - New resources are validated and then made discoverable through README regeneration.
-
-- `https://github.com/microsoft/skills`
-  - Large skill catalogs treat discoverability and validation as first-class concerns.
-  - Adding a new skill is expected to follow a repeatable quality workflow.
-
-## Practical takeaway
-
-- Let the local repo decide the facts.
-- Let GitHub samples influence the shape of the docs, the level of specificity, and the validation steps.
-- Prefer short, repo-specific rules over broad generic guidance.
+# GitHub Samples
+
+Use these repositories for structure and quality signals, not for copy-pasting text.
+
+## AGENTS.md patterns
+
+- `https://github.com/agentsmd/agents.md`
+  - Treat `AGENTS.md` as a predictable "README for agents".
+  - Include concrete development and testing instructions.
+
+- `https://github.com/openai/codex/blob/main/AGENTS.md`
+  - Keep AGENTS tied to real files, commands, and change-impact rules.
+  - Update docs when behavior or APIs change.
+
+## Skills and README sync patterns
+
+- `https://github.com/vercel-labs/skills/blob/main/AGENTS.md`
+  - Skill ecosystems usually document the exact create/validate/sync commands.
+  - README maintenance is treated as part of shipping a new capability.
+
+- `https://github.com/github/awesome-copilot/blob/main/AGENTS.md`
+  - Skill folders use kebab-case names and valid frontmatter.
+  - New resources are validated and then made discoverable through README regeneration.
+
+- `https://github.com/microsoft/skills`
+  - Large skill catalogs treat discoverability and validation as first-class concerns.
+  - Adding a new skill is expected to follow a repeatable quality workflow.
+
+## Practical takeaway
+
+- Let the local repo decide the facts.
+- Let GitHub samples influence the shape of the docs, the level of specificity, and the validation steps.
+- Prefer short, repo-specific rules over broad generic guidance.