@pzy560117/codex-harness 0.1.0 → 0.1.1

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/speckit-taskstoissues/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: speckit-taskstoissues
+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.agents/.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. From the executed script, extract the path to **tasks**.
+
+3. Get the Git remote by running:
+
+```bash
+git config --get remote.origin.url
+```
+
+> [!CAUTION]
+> ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL
+
+4. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.
+
+> [!CAUTION]
+> UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/speckit-verify/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: speckit-verify
+description: Run feature-level verification from test-manifest.json, tasks.json, verify-matrix.md, and current git diff.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## 语言要求
+
+- 与用户的验证进展、失败归因、完成汇报全部使用简体中文。
+- 实际写入仓库的 `verify-report.md`、`docs/evidence/<feature>/verify.md` 和 `test-manifest.json` 状态更新必须使用简体中文说明。
+- 保留 `FR-001`、`AE-001`、`TEST-GAP`、路径、命令、exit code 等机器敏感标记原样不变。
+
+## Goal
+
+`/speckit.verify` 是 feature 完成后的验证线，不替代需求阶段测试左移，也不替代实现期 test-first。它只负责：
+
+- fresh evidence
+- affected tests
+- baseline / required commands
+- P0/P1 regression confirmation
+- failure triage
+
+如果当前 feature 还没有 `acceptance-examples.md`、`requirements-testability-review.md`、`verify-matrix.md`、`test-strategy.md` 或 `test-manifest.json`，不要临时猜测试范围；先回到 `/speckit.plan` 补齐。
+
+## Workflow
+
+1. Run `.agents/.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks` from repo root and parse:
+   - `FEATURE_DIR`
+   - `FEATURE_SPEC`
+   - `IMPL_PLAN`
+   - `TASKS`
+
+2. Load only the verification inputs:
+   - `FEATURE_DIR/test-manifest.json`
+   - `FEATURE_DIR/tasks.json`
+   - `FEATURE_DIR/verify-matrix.md`
+   - `FEATURE_DIR/requirements-testability-review.md`
+   - `FEATURE_DIR/test-strategy.md`
+
+3. Validate readiness before running commands:
+   - `test-manifest.json` parses as JSON.
+   - All completed `integration` / `production` tasks have evidence paths.
+   - No formal requirement needed for this verification is `Blocked`.
+   - `TEST-GAP` entries are either intentionally accepted by delivery mode or converted into follow-up tasks.
+   - Every command about to run is concrete and executable from repo root.
+   - If the repository has `task.json`, `package.json` scripts, and `docs/testing/verify-matrix.md`, verify that critical test scripts are mapped to task ids and evidence boundaries before treating release evidence as complete. A release gate is not enough by itself when individual practices such as API / DB / worker / query / file / sample / mock-local / object-storage smoke are not mapped.
+   - If a guard test such as `tests/mock-local/test-practice-matrix.test.mjs` exists, include its owning command, usually `npm run test:mock-local`, in the verification command set when `task.json`, `package.json`, `tests/`, `docs/testing/verify-matrix.md`, release gate wording, or evidence boundaries changed.
+
+4. Build the verification command set:
+   - Baseline commands from `test-manifest.json.baseline.commands`.
+   - Required commands from each relevant requirement in `test-manifest.json.requirements`.
+   - Affected tests inferred from `git diff --name-only`, `tasks.json`, and `verify-matrix.md`.
+   - Always include `git -c core.safecrlf=false diff --check`.
+
+   For driver-first repositories with root `task.json`, also infer affected tests from:
+
+   - each changed task's `test_command`
+   - `package.json` scripts referenced by changed tasks or verify-matrix rows
+   - test practice mapping guard tests, when present
+   - release scripts that aggregate lower-level practices, without allowing the aggregate to hide unmapped test scripts
+
+5. Execute commands from repo root:
+   - Record command, exit code, start/end time, and compact output.
+   - Stop on hard failure unless the failure is explicitly documented as pre-existing baseline failure.
+   - Do not mark a failed requirement as verified.
+
+6. Write verification outputs:
+   - `FEATURE_DIR/verify-report.md`
+   - `docs/evidence/<feature>/verify.md`
+
+7. Update `test-manifest.json`:
+   - Set `baseline.status` to `passed`, `failed`, or `blocked`.
+   - For each requirement, set status-like fields if present; if absent, add `verificationStatus`.
+   - Preserve existing requirement IDs, blockers, paths, and command arrays.
+
+8. Report:
+   - commands run
+   - passed / failed / skipped count
+   - affected tests
+   - requirements verified
+   - unresolved blockers or `TEST-GAP`
+   - next action: proceed, create follow-up tasks, or return to plan/tasks
+
+## Output Template
+
+`verify-report.md` should use this structure:
+
+```md
+# Verify Report: <feature>
+
+## Summary
+
+| Field | Value |
+| --- | --- |
+| Feature | |
+| Delivery Mode | |
+| Result | Passed / Failed / Blocked |
+| Generated At | |
+
+## Commands
+
+| Command | Exit Code | Result | Evidence |
+| --- | --- | --- | --- |
+
+## Requirement Verification
+
+| Requirement ID | Testability | Commands | Evidence Path | Result | Notes |
+| --- | --- | --- | --- | --- | --- |
+
+## Affected Tests
+
+| Changed Path | Selected Tests | Reason |
+| --- | --- | --- |
+
+## Failure Triage
+
+| Failure | Likely Owner | Root Cause | Next Action |
+| --- | --- | --- | --- |
+```
+
+## Hard Gates
+
+- Invalid or missing `test-manifest.json` blocks verification.
+- `integration` / `production` requirements with unresolved blockers remain `blocked`.
+- Missing evidence paths for completed `integration` / `production` tasks block verification.
+- Required commands failing without a documented pre-existing baseline failure block verification.
+- `TEST-GAP` cannot be silently treated as verified.
+- In driver-first repos, critical test scripts without task ownership or verify-matrix evidence boundaries block release completion.
+- mock/local rehearsal, docker/mock release, and external live validation cannot be collapsed into one evidence category.
+
+## Next Steps
+
+- `/speckit.tasks` - create follow-up tasks for failed verification or `TEST-GAP`
+- `/speckit.implement` - fix failed tasks one boundary at a time
+- `/speckit.verify` - rerun after fixes

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/state-management/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: state-management
+description: 状态管理指南
+---
+
+# 状态管理指南
+
+## 触发条件
+Redux、Zustand、状态管理、全局状态、store
+
+## 技术选型
+
+| 方案 | 适用场景 | 复杂度 |
+|------|---------|--------|
+| React Context | 简单共享状态，低频更新 | 低 |
+| Zustand | 中小型项目，简洁 API | 低 |
+| Jotai | 原子化状态，细粒度更新 | 中 |
+| Redux Toolkit | 大型项目，复杂状态逻辑 | 中高 |
+
+## Zustand (推荐)
+
+```typescript
+import { create } from 'zustand';
+import { devtools, persist } from 'zustand/middleware';
+
+interface UserState {
+  user: User | null;
+  isLoading: boolean;
+  login: (credentials: Credentials) => Promise<void>;
+  logout: () => void;
+}
+
+/**
+ * 用户状态 Store
+ */
+export const useUserStore = create<UserState>()(
+  devtools(
+    persist(
+      (set, get) => ({
+        user: null,
+        isLoading: false,
+        
+        login: async (credentials) => {
+          set({ isLoading: true });
+          try {
+            const user = await authApi.login(credentials);
+            set({ user, isLoading: false });
+          } catch (error) {
+            set({ isLoading: false });
+            throw error;
+          }
+        },
+        
+        logout: () => {
+          set({ user: null });
+        },
+      }),
+      { name: 'user-storage' }
+    )
+  )
+);
+
+// 组件中使用
+function Profile() {
+  const { user, logout } = useUserStore();
+  // 选择性订阅，避免不必要渲染
+  const isLoading = useUserStore(state => state.isLoading);
+}
+```
+
+## Redux Toolkit
+
+```typescript
+import { createSlice, createAsyncThunk, configureStore } from '@reduxjs/toolkit';
+
+/**
+ * 异步 Action
+ */
+export const fetchUsers = createAsyncThunk(
+  'users/fetch',
+  async (_, { rejectWithValue }) => {
+    try {
+      return await userApi.getAll();
+    } catch (error) {
+      return rejectWithValue(error.message);
+    }
+  }
+);
+
+/**
+ * Slice 定义
+ */
+const usersSlice = createSlice({
+  name: 'users',
+  initialState: {
+    list: [] as User[],
+    status: 'idle' as 'idle' | 'loading' | 'succeeded' | 'failed',
+    error: null as string | null,
+  },
+  reducers: {
+    userAdded: (state, action) => {
+      state.list.push(action.payload);
+    },
+  },
+  extraReducers: (builder) => {
+    builder
+      .addCase(fetchUsers.pending, (state) => {
+        state.status = 'loading';
+      })
+      .addCase(fetchUsers.fulfilled, (state, action) => {
+        state.status = 'succeeded';
+        state.list = action.payload;
+      })
+      .addCase(fetchUsers.rejected, (state, action) => {
+        state.status = 'failed';
+        state.error = action.payload as string;
+      });
+  },
+});
+
+export const store = configureStore({
+  reducer: {
+    users: usersSlice.reducer,
+  },
+});
+```
+
+## React Context (简单场景)
+
+```typescript
+interface ThemeContextType {
+  theme: 'light' | 'dark';
+  toggleTheme: () => void;
+}
+
+const ThemeContext = createContext<ThemeContextType | null>(null);
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState<'light' | 'dark'>('light');
+  
+  const toggleTheme = useCallback(() => {
+    setTheme(prev => prev === 'light' ? 'dark' : 'light');
+  }, []);
+  
+  return (
+    <ThemeContext.Provider value={{ theme, toggleTheme }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  const context = useContext(ThemeContext);
+  if (!context) throw new Error('useTheme must be used within ThemeProvider');
+  return context;
+}
+```
+
+## 最佳实践
+- 按功能模块拆分 store
+- 异步操作统一处理 loading/error 状态
+- 使用选择器避免不必要的重渲染
+- 敏感数据不要持久化到 localStorage
+

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/strategic-compact/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: strategic-compact
+description: Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.
+---
+
+# Strategic Compact Skill
+
+Suggests manual `/compact` at strategic points in your workflow rather than relying on arbitrary auto-compaction.
+
+## Why Strategic Compaction?
+
+Auto-compaction triggers at arbitrary points:
+- Often mid-task, losing important context
+- No awareness of logical task boundaries
+- Can interrupt complex multi-step operations
+
+Strategic compaction at logical boundaries:
+- **After exploration, before execution** - Compact research context, keep implementation plan
+- **After completing a milestone** - Fresh start for next phase
+- **Before major context shifts** - Clear exploration context before different task
+
+## How It Works
+
+The `suggest-compact.sh` script runs on PreToolUse (Edit/Write) and:
+
+1. **Tracks tool calls** - Counts tool invocations in session
+2. **Threshold detection** - Suggests at configurable threshold (default: 50 calls)
+3. **Periodic reminders** - Reminds every 25 calls after threshold
+
+## Hook Setup
+
+Add to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "tool == \"Edit\" || tool == \"Write\"",
+      "hooks": [{
+        "type": "command",
+        "command": "~/.claude/skills/strategic-compact/suggest-compact.sh"
+      }]
+    }]
+  }
+}
+```
+
+## Configuration
+
+Environment variables:
+- `COMPACT_THRESHOLD` - Tool calls before first suggestion (default: 50)
+
+## Best Practices
+
+1. **Compact after planning** - Once plan is finalized, compact to start fresh
+2. **Compact after debugging** - Clear error-resolution context before continuing
+3. **Don't compact mid-implementation** - Preserve context for related changes
+4. **Read the suggestion** - The hook tells you *when*, you decide *if*
+
+## Related
+
+- 技术文档 - Token 优化章节
+- Memory persistence hooks - For state that survives compaction

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/strategic-compact/suggest-compact.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# Strategic Compact Suggester
+# Runs on PreToolUse or periodically to suggest manual compaction at logical intervals
+#
+# Why manual over auto-compact:
+# - Auto-compact happens at arbitrary points, often mid-task
+# - Strategic compacting preserves context through logical phases
+# - Compact after exploration, before execution
+# - Compact after completing a milestone, before starting next
+#
+# Hook config (in ~/.claude/settings.json):
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Edit|Write",
+#       "hooks": [{
+#         "type": "command",
+#         "command": "~/.claude/skills/strategic-compact/suggest-compact.sh"
+#       }]
+#     }]
+#   }
+# }
+#
+# Criteria for suggesting compact:
+# - Session has been running for extended period
+# - Large number of tool calls made
+# - Transitioning from research/exploration to implementation
+# - Plan has been finalized
+
+# Track tool call count (increment in a temp file)
+COUNTER_FILE="/tmp/claude-tool-count-$$"
+THRESHOLD=${COMPACT_THRESHOLD:-50}
+
+# Initialize or increment counter
+if [ -f "$COUNTER_FILE" ]; then
+  count=$(cat "$COUNTER_FILE")
+  count=$((count + 1))
+  echo "$count" > "$COUNTER_FILE"
+else
+  echo "1" > "$COUNTER_FILE"
+  count=1
+fi
+
+# Suggest compact after threshold tool calls
+if [ "$count" -eq "$THRESHOLD" ]; then
+  echo "[StrategicCompact] $THRESHOLD tool calls reached - consider /compact if transitioning phases" >&2
+fi
+
+# Suggest at regular intervals after threshold
+if [ "$count" -gt "$THRESHOLD" ] && [ $((count % 25)) -eq 0 ]; then
+  echo "[StrategicCompact] $count tool calls - good checkpoint for /compact if context is stale" >&2
+fi

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

@@ -0,0 +1,143 @@
+---
+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.

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

@@ -0,0 +1,41 @@
+# 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.

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

@@ -0,0 +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.