repo-harness 0.0.0 → 0.1.1

package/AGENTS.md

@@ -0,0 +1,89 @@
+# agentic-dev AGENTS.md
+
+This repository self-hosts the `agentic-dev` contract, formerly `agentic-dev-skill` and `project-initializer`. Claude and Codex should follow the same repo-local workflow surface.
+
+## Canonical Workflow Files
+
+- `tasks/todo.md` for the current execution checklist and verification notes
+- `.ai/context/capabilities.json` for the capability registry and longest-prefix context boundaries
+- `tasks/workstreams/` for capability long-running workstreams that project the current slice into `tasks/todo.md`
+- `tasks/lessons.md` for correction-derived rules
+- `tasks/research.md` for deep repo knowledge
+- `tasks/notes/` for task-local implementation decisions, deviations, tradeoffs, and open questions
+- `plans/` for timestamped plans, with `plans/archive/` for history
+- `.ai/harness/workflow-contract.json` for the installed workflow contract manifest
+- `.ai/harness/policy.json` for the machine-readable workflow contract
+- `.ai/context/context-map.json` for progressive context loading
+- `docs/architecture/index.md` for umbrella architecture status, drift requests, snapshots, and diagram links
+- `docs/reference-configs/agentic-development-flow.md` for gstack/Waza routing rules
+
+## Operating Rules
+
+- Sync `tasks/` whenever substantive repo changes are made.
+- Use `tasks/notes/<slug>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
+- Treat `.ai/hooks/` as the shared hook implementation, `.claude/settings.json` as the Claude adapter, and `.codex/hooks.json` as the Codex adapter.
+- Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todo.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
+- Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are compatibility inputs only.
+- Keep architecture drift handling split: `architecture-drift.sh` writes architecture requests/events, `workstream-sync.sh` maintains durable capability workstreams, and `context-contract-sync.sh` only updates controlled local `CLAUDE.md`/`AGENTS.md` architecture blocks.
+- Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` in sync.
+- Keep `CLAUDE.md` and `AGENTS.md` short; put detailed guidance in `docs/reference-configs/`.
+- Treat Codex auto-compact as a fallback only; use `.ai/harness/handoff/current.md` and `.ai/harness/handoff/resume.md` for long-task rollover.
+- Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `tasks/research.md`.
+- Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
+- Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
+- Treat contract-level task execution as worktree-first: `scripts/plan-to-todo.sh --plan <approved-plan>` starts `scripts/contract-worktree.sh start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `scripts/contract-worktree.sh finish`.
+- After Codex Plan mode, Waza `/think`, or `agentic-dev-plan` produces a decision-complete plan, capture it with `scripts/capture-plan.sh --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if the user has already approved implementation, capture with `--status Approved --execute` or run `scripts/plan-to-todo.sh --plan <active-plan>`.
+- If current repo state conflicts with the task, open an isolated `codex/<task-slug>` worktree, finish there, run Waza `/check`-style validation, then merge back to `main` without absorbing unrelated dirty changes.
+- Route product discovery to gstack `office-hours`, complex engineering plans to gstack `plan-eng-review`, design plans to gstack `plan-design-review`, and daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`.
+- Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `diagram-design` from `~/.codex/skills`.
+- Route knowledge sync and handoff retrieval to `gbrain`.
+- Register valuable repo-authored docs in `.ai/harness/brain-manifest.json` with `sync.direction=repo-to-brain`; `scripts/sync-brain-docs.sh` and the PostEdit hook mirror only those explicit entries into the default brain vault.
+- Treat Waza as Codex-first: `~/.codex/skills` is the Codex runtime source; `~/.agents/skills` is skills CLI staging/cache only. Update by staging upstream Waza, copying the eight managed `SKILL.md` files into Codex, and verifying with `cmp`.
+- Use `docs/reference-configs/external-tooling.md` and `bash scripts/check-agent-tooling.sh --host both --check-updates` for environment checks; this self-host repo vendors CodeGraph as a dev dependency while generated downstream repos keep the global MCP default unless local policy opts in.
+- When changing `scripts/migrate-project-template.sh` or `scripts/lib/project-init-lib.sh`, verify self-migration of this repo still works.
+- Treat `.codex/hooks.json` as a product hook adapter; do not treat generated backup files or other `.codex/*` runtime residue as product deliverables.
+
+## Required Checks
+
+```bash
+bun test
+bash scripts/check-deploy-sql-order.sh
+bash scripts/check-task-sync.sh
+bash scripts/check-task-workflow.sh --strict
+bun scripts/inspect-project-state.ts --repo . --format text
+bash scripts/migrate-project-template.sh --repo . --dry-run
+```
+
+<!-- BEGIN ARCHITECTURE CONTRACT -->
+## Architecture Contract
+
+- Functional block: `assets/hooks`
+- Capability ID: `runtime-harness-hook-adapters`
+- Matched prefix: `assets/hooks`
+- Architecture domain: `runtime-harness`
+- Architecture capability: `hook-adapters`
+- Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Last architecture event: 2026-05-28T15:48:16+0800
+- Last changed path: `assets/hooks/hook-input.sh`
+- Severity: high
+- Change type: workflow-surface
+- Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
+- Entrypoints: `assets/hooks`
+- Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.
+- Forbidden dependencies: Do not cross sibling app/service/package boundaries without an architecture snapshot or explicit plan.
+- Runtime path: `assets/hooks`
+- LSP/tooling profile: `typescript-lsp`
+- Verification: Use root required checks plus local commands recorded in this capability contract.
+- Latest snapshot: `(none yet)`
+- Latest diagram: `(none yet)`
+- Pending architecture request: `docs/architecture/requests/20260528-154816-assets-hooks-assets-hooks-hook-input-sh.md`
+
+## Active Workstreams
+
+- (none yet)
+
+## Current Session Projection
+
+- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
+- `tasks/todo.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+<!-- END ARCHITECTURE CONTRACT -->

package/CLAUDE.md

@@ -0,0 +1,89 @@
+# agentic-dev AGENTS.md
+
+This repository self-hosts the `agentic-dev` contract, formerly `agentic-dev-skill` and `project-initializer`. Claude and Codex should follow the same repo-local workflow surface.
+
+## Canonical Workflow Files
+
+- `tasks/todo.md` for the current execution checklist and verification notes
+- `.ai/context/capabilities.json` for the capability registry and longest-prefix context boundaries
+- `tasks/workstreams/` for capability long-running workstreams that project the current slice into `tasks/todo.md`
+- `tasks/lessons.md` for correction-derived rules
+- `tasks/research.md` for deep repo knowledge
+- `tasks/notes/` for task-local implementation decisions, deviations, tradeoffs, and open questions
+- `plans/` for timestamped plans, with `plans/archive/` for history
+- `.ai/harness/workflow-contract.json` for the installed workflow contract manifest
+- `.ai/harness/policy.json` for the machine-readable workflow contract
+- `.ai/context/context-map.json` for progressive context loading
+- `docs/architecture/index.md` for umbrella architecture status, drift requests, snapshots, and diagram links
+- `docs/reference-configs/agentic-development-flow.md` for gstack/Waza routing rules
+
+## Operating Rules
+
+- Sync `tasks/` whenever substantive repo changes are made.
+- Use `tasks/notes/<slug>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
+- Treat `.ai/hooks/` as the shared hook implementation, `.claude/settings.json` as the Claude adapter, and `.codex/hooks.json` as the Codex adapter.
+- Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todo.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
+- Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are compatibility inputs only.
+- Keep architecture drift handling split: `architecture-drift.sh` writes architecture requests/events, `workstream-sync.sh` maintains durable capability workstreams, and `context-contract-sync.sh` only updates controlled local `CLAUDE.md`/`AGENTS.md` architecture blocks.
+- Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` in sync.
+- Keep `CLAUDE.md` and `AGENTS.md` short; put detailed guidance in `docs/reference-configs/`.
+- Treat Codex auto-compact as a fallback only; use `.ai/harness/handoff/current.md` and `.ai/harness/handoff/resume.md` for long-task rollover.
+- Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `tasks/research.md`.
+- Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
+- Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
+- Treat contract-level task execution as worktree-first: `scripts/plan-to-todo.sh --plan <approved-plan>` starts `scripts/contract-worktree.sh start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `scripts/contract-worktree.sh finish`.
+- After Codex Plan mode, Waza `/think`, or `agentic-dev-plan` produces a decision-complete plan, capture it with `scripts/capture-plan.sh --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if the user has already approved implementation, capture with `--status Approved --execute` or run `scripts/plan-to-todo.sh --plan <active-plan>`.
+- If current repo state conflicts with the task, open an isolated `codex/<task-slug>` worktree, finish there, run Waza `/check`-style validation, then merge back to `main` without absorbing unrelated dirty changes.
+- Route product discovery to gstack `office-hours`, complex engineering plans to gstack `plan-eng-review`, design plans to gstack `plan-design-review`, and daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`.
+- Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `diagram-design` from `~/.codex/skills`.
+- Route knowledge sync and handoff retrieval to `gbrain`.
+- Register valuable repo-authored docs in `.ai/harness/brain-manifest.json` with `sync.direction=repo-to-brain`; `scripts/sync-brain-docs.sh` and the PostEdit hook mirror only those explicit entries into the default brain vault.
+- Treat Waza as Codex-first: `~/.codex/skills` is the Codex runtime source; `~/.agents/skills` is skills CLI staging/cache only. Update by staging upstream Waza, copying the eight managed `SKILL.md` files into Codex, and verifying with `cmp`.
+- Use `docs/reference-configs/external-tooling.md` and `bash scripts/check-agent-tooling.sh --host both --check-updates` for environment checks; this self-host repo vendors CodeGraph as a dev dependency while generated downstream repos keep the global MCP default unless local policy opts in.
+- When changing `scripts/migrate-project-template.sh` or `scripts/lib/project-init-lib.sh`, verify self-migration of this repo still works.
+- Treat `.codex/hooks.json` as a product hook adapter; do not treat generated backup files or other `.codex/*` runtime residue as product deliverables.
+
+## Required Checks
+
+```bash
+bun test
+bash scripts/check-deploy-sql-order.sh
+bash scripts/check-task-sync.sh
+bash scripts/check-task-workflow.sh --strict
+bun scripts/inspect-project-state.ts --repo . --format text
+bash scripts/migrate-project-template.sh --repo . --dry-run
+```
+
+<!-- BEGIN ARCHITECTURE CONTRACT -->
+## Architecture Contract
+
+- Functional block: `assets/hooks`
+- Capability ID: `runtime-harness-hook-adapters`
+- Matched prefix: `assets/hooks`
+- Architecture domain: `runtime-harness`
+- Architecture capability: `hook-adapters`
+- Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Last architecture event: 2026-05-28T15:48:16+0800
+- Last changed path: `assets/hooks/hook-input.sh`
+- Severity: high
+- Change type: workflow-surface
+- Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
+- Entrypoints: `assets/hooks`
+- Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.
+- Forbidden dependencies: Do not cross sibling app/service/package boundaries without an architecture snapshot or explicit plan.
+- Runtime path: `assets/hooks`
+- LSP/tooling profile: `typescript-lsp`
+- Verification: Use root required checks plus local commands recorded in this capability contract.
+- Latest snapshot: `(none yet)`
+- Latest diagram: `(none yet)`
+- Pending architecture request: `docs/architecture/requests/20260528-154816-assets-hooks-assets-hooks-hook-input-sh.md`
+
+## Active Workstreams
+
+- (none yet)
+
+## Current Session Projection
+
+- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
+- `tasks/todo.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+<!-- END ARCHITECTURE CONTRACT -->

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AncientTwo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,297 @@
 # repo-harness
 
-Reserved package name for the repo-local agentic development harness CLI.
+Repo-local agentic development harness CLI and skill runtime for Claude/Codex
+workflows. Formerly `agentic-dev-skill` and `project-initializer`;
+`agentic-dev-skill` remains a compatibility alias, while `project-initializer`
+install paths are retired and removed by installed-copy sync.
+Repository: `https://github.com/Ancienttwo/repo-harness`
+
+This repository now dogfoods its own tasks-first contract. It is both:
+
+- the source repo for the `repo-harness` CLI and `agentic-dev` skill runtime
+- a self-hosted example of the repo-local workflow it generates for other projects
+
+## First 5 Minutes
+
+This is the fastest path for an AI tooling owner evaluating whether the workflow is
+safe to adopt in a real repo.
+
+### Install or refresh the local runtime
+
+```bash
+npx -y repo-harness init
+```
+
+The npm package name and primary installed command are `repo-harness`.
+`agentic-dev` remains a compatibility command alias. When working from a source
+checkout instead of npm, run:
+
+```bash
+git clone https://github.com/Ancienttwo/repo-harness.git ~/Projects/repo-harness
+cd ~/Projects/repo-harness
+bun src/cli/index.ts init
+```
+
+Local path model:
+
+- Source repo: `~/Projects/repo-harness`
+- Claude skill aliases: `~/.claude/skills/agentic-dev`, `~/.claude/skills/agentic-dev-skill`
+- Codex discoverable skill alias: `~/.codex/skills/agentic-dev`
+- Codex compatibility fallback alias: `~/.codex/skills/agentic-dev-skill`
+
+The `~/Projects/repo-harness` repo is the only editable source of truth. Local
+Claude/Codex paths are symlink-backed runtime entrypoints. Only
+`~/.codex/skills/agentic-dev` should expose `SKILL.md` and
+`assets/skill-commands/`; compatibility directories exist only so renamed
+repos can still resolve upstream assets without duplicate command discovery.
+The retired `project-initializer` directories under `~/.codex/skills` and
+`~/.claude/skills` are deleted by `scripts/sync-codex-installed-copies.sh`.
+
+### Minimum prerequisites
+
+- Git working tree
+- `bash`
+- `bun` for follow-up verification and template assembly
+- `jq` is optional for `--dry-run`, but recommended when applying settings merges
+
+### Start here
+
+For an existing repo, run from the repo root:
+
+```bash
+npx -y repo-harness init --dry-run
+```
+
+Apply only after the dry-run report looks correct:
+
+```bash
+npx -y repo-harness init
+```
+
+For a new project or module, use the `agentic-dev-scaffold` command skill. For
+an existing repo, use `agentic-dev-init`; it installs or refreshes the harness
+without creating an application stack.
+
+### Success looks like this
+
+The command should end with `=== Migration Report ===` and summarize:
+
+- `Project hooks synced from:` to show where generated hook behavior comes from
+- `Claude hook config target: .claude/settings.json` to show the Claude adapter entry
+- `Codex hook config target: .codex/hooks.json` to show the Codex adapter entry
+- `Codex hook trust required:` to remind the user to trust the repo hook in Codex Settings
+- `Workflow migration:` to show the repo-local harness surfaces it will create or refresh
+- `Helper scripts:` to show the operational toolchain you get after apply
+- `--- External Tooling ---` to show default gstack/Waza/gbrain routing plus advisory install/update hints
+
+### Next two commands
+
+```bash
+bash scripts/check-task-workflow.sh --strict
+bun test
+```
+
+If the dry-run output looks wrong, stop there and inspect
+[`docs/reference-configs/hook-operations.md`](docs/reference-configs/hook-operations.md)
+before applying anything.
+
+## Hook Authority Map
+
+- `.ai/hooks/` is the only shared hook implementation you should edit first.
+- `.claude/settings.json` is the Claude adapter that dispatches into `.ai/hooks/run-hook.sh`.
+- `.codex/hooks.json` is the Codex adapter that dispatches into the same runner.
+- Codex must mark this repo hook as trusted in Codex Settings before those hooks run.
+- Debug in this order: adapter config -> `run-hook.sh` -> `.ai/hooks/*`.
+
+## Hook Failure Playbook
+
+When a hook blocks work, start with the structured output in the terminal. The core
+fields are `guard`, `reason`, `fix`, `failure_class`, and `run_id`.
+
+- Failure log: `.ai/harness/failures/latest.jsonl`
+- Trace log: `.claude/.trace.jsonl`
+- Deep guide: [`docs/reference-configs/hook-operations.md`](docs/reference-configs/hook-operations.md)
+
+Most common guards:
+
+- `PlanStatusGuard`: no active plan, or the plan is not ready to execute
+- `ContractGuard`: approved execution has not yet produced the contract/review/notes scaffold
+- `ContractGuard`: completion was claimed before the task contract passed
+- `WorktreeGuard`: writes were attempted in the primary worktree while linked worktrees are enforced
+
+## Repo Workflow
+
+- Root routing docs: `CLAUDE.md`, `AGENTS.md`
+- Shared hook layer: `.ai/hooks/`
+- Claude adapter layer: `.claude/settings.json`
+- Codex adapter layer: `.codex/hooks.json`
+- Active execution surface: `tasks/`
+- Plan source of truth: `plans/`
+- Durable progress: `tasks/workstreams/`
+- Release history: `docs/CHANGELOG.md`
+
+## Current Model (5.2.3)
+
+- Question flow uses **12 grouped decision points** with harness defaults inferred first.
+- Plan menu is tiered:
+  - **Core Plans (A-F)** first.
+  - **Custom Presets (G-K)** only when needed.
+- Skill routing is inspection-first:
+  - `scripts/inspect-project-state.ts`
+  - `scripts/migrate-workflow-docs.ts`
+  - `assets/workflow-contract.v1.json`
+- Runtime mode is configurable with template vars:
+  - `{{RUNTIME_MODE}}`
+  - `{{RUNTIME_PROFILE}}`
+  - `{{RECOVERY_PROFILE}}`
+  - `{{STATE_PROFILE}}`
+- Question-pack source of truth is in:
+  - `assets/initializer-question-pack.v4.json`
+- Generated repos default to the repo-local harness flow:
+  - `docs/spec.md -> plans/ -> tasks/contracts/ -> tasks/reviews/ -> .ai/context/context-map.json -> .ai/harness/*`
+- Generated and self-hosted repos install:
+  - `.ai/harness/workflow-contract.json`
+  - `.ai/harness/policy.json`
+- Generated and migrated repos default `external_tooling` to:
+  - `complex -> gstack`
+  - `simple -> Waza` with Codex-first runtime copies in `~/.codex/skills`
+  - `knowledge -> gbrain`
+- `agentic-dev init` bootstraps the Codex/Claude runtime pieces needed for the
+  default workflow:
+  - refreshes `agentic-dev` skill aliases
+  - installs global Codex/Claude hook adapters
+  - installs Waza skills (`check`, `design`, `health`, `hunt`, `learn`, `read`, `think`, `write`) through the skills CLI
+  - syncs `diagram-design` into Codex/Claude skill roots when a source copy exists
+- Other external tooling stays advisory-only:
+  - `bash scripts/check-agent-tooling.sh --host both --check-updates`
+  - Waza update checks compare upstream `tw93/Waza` `SKILL.md` hashes without running `npx skills check`
+  - no automatic gstack, gbrain, CodeGraph MCP, daemon, or provider setup
+- Manual distillation stays repo-local:
+  - repeated corrections -> `tasks/lessons.md`
+  - deep findings and hidden contracts -> `tasks/research.md`
+  - sprint verification evidence -> `tasks/reviews/*.review.md`
+  - durable capability progress -> `tasks/workstreams/`
+  - release history -> `docs/CHANGELOG.md`
+
+## Action Command Skills
+
+Source-owned command skill facades live in `assets/skill-commands/`. They keep
+the public surface action-style while sharing the same router, contract, scripts,
+and tests:
+
+- Planning and review: `agentic-dev-plan`, `agentic-dev-review`, `agentic-dev-autoplan`
+- Repo workflow actions: `agentic-dev-init`, `agentic-dev-migrate`, `agentic-dev-upgrade`, `agentic-dev-capability`, `agentic-dev-architecture`, `agentic-dev-handoff`, `agentic-dev-deploy`, `agentic-dev-repair`, `agentic-dev-check`
+- Project creation: `agentic-dev-scaffold`
+
+`agentic-dev-init` is for an existing repo; `agentic-dev-scaffold` creates a new
+project or module scaffold. `hooks-init`, `docs-init`, and `create-project-dirs`
+are internal steps, not public commands.
+
+Use `agentic-dev-capability` when the harness already exists and only selected
+capability boundaries should be added. It updates `.ai/context/capabilities.json`,
+syncs the requested local `AGENTS.md` / `CLAUDE.md` contract files, and validates
+the registry without running a full init, migrate, or upgrade pass.
+
+Use `agentic-dev-architecture`, `agentic-dev-handoff`, and `agentic-dev-deploy`
+for focused architecture documentation, rollover, and deploy/ops readiness
+passes. These commands call existing repo-local helpers and keep their scope
+narrow instead of refreshing the full harness.
+
+Codex installed-copy rule: only `~/.codex/skills/agentic-dev` exposes the root
+skill and `agentic-dev-*` command facades. The compatibility directory
+`~/.codex/skills/agentic-dev-skill` is a runtime fallback bundle only; it must
+not contain `SKILL.md` files or `assets/skill-commands/`. The retired
+`~/.codex/skills/project-initializer` and `~/.claude/skills/project-initializer`
+directories are removed during sync.
+
+After cloning or moving this source repo, rebuild the local runtime aliases with:
+
+```bash
+bash scripts/sync-codex-installed-copies.sh
+```
+
+By default, the script keeps local Claude/Codex runtime paths linked back to the
+source repo. Set `AGENTIC_DEV_LINK_INSTALLED_COPIES=0` for copy-based staging,
+and set `CODEX_SKILLS_ROOT` or `CLAUDE_SKILLS_ROOT` to stage under alternate
+runtime roots.
+
+## Maintainer Reference
+
+### Self-check this repository's workflow contract
+
+```bash
+bash scripts/check-task-sync.sh
+bash scripts/check-task-workflow.sh --strict
+bun scripts/inspect-project-state.ts --repo . --format text
+bash scripts/migrate-project-template.sh --repo . --dry-run
+```
+
+### Explicit template assembly
+
+```bash
+bun scripts/assemble-template.ts --plan C --name "MyProject"
+bun scripts/assemble-template.ts --target agents --plan C --name "MyProject"
+```
+
+### Local benchmark skeleton
+
+```bash
+bun run benchmark:skills --dry-run
+```
+
+### Run one eval across both Claude and Codex
+
+```bash
+bun run benchmark:skills --eval repair-agents-task-sync
+```
+
+## Key Files
+
+- Skill spec: `SKILL.md`
+- Root routing docs: `CLAUDE.md`, `AGENTS.md`
+- Plan mapping: `assets/plan-map.json`
+- Question-pack: `assets/initializer-question-pack.v4.json`
+- Shared hooks: `assets/hooks/`
+- Workflow contract: `assets/workflow-contract.v1.json`
+- Hook operations reference: `docs/reference-configs/hook-operations.md`
+- Template assembler: `scripts/assemble-template.ts`
+- Question inference helper: `scripts/initializer-question-pack.ts`
+- State inspector: `scripts/inspect-project-state.ts`
+- Legacy-doc migrator: `scripts/migrate-workflow-docs.ts`
+- External tooling detector: `scripts/check-agent-tooling.sh`
+- Scaffolding scripts:
+  - `scripts/init-project.sh`
+  - `scripts/create-project-dirs.sh`
+
+## Generated vs Self-Hosted Hook Parity
+
+- Downstream hook behavior is defined by generated output from `assets/hooks/` plus
+  `assets/reference-configs/`.
+- This repo dogfoods the same contract, but self-host behavior is not magically in
+  sync with generated repos unless a change explicitly updates both surfaces.
+- Every hook change should say whether it affects `self-host`, `generated`, or `both`.
+
+## Package Manager Defaults
+
+- General default priority: `bun > pnpm > npm`
+- **Plan G/H** (Python-centric) default to **`uv`** as primary package manager.
+
+## Runtime Profiles
+
+- `Plan-only (recommended)` (default)
+- `Plan + Permissionless`
+- `Standard (ask before each action)`
+
+Configured in `assets/initializer-question-pack.v4.json` and consumed by `scripts/initializer-question-pack.ts`.
+
+## Verification
+
+```bash
+bun test
+bash scripts/check-task-sync.sh
+bash scripts/check-task-workflow.sh --strict
+bun scripts/inspect-project-state.ts --repo . --format text
+bash scripts/migrate-project-template.sh --repo . --dry-run
+bash scripts/check-agent-tooling.sh --host both --check-updates
+bun run benchmark:skills --dry-run
+```