# Agent Doc Init

> Initialize baseline agent-docs files safely for new repositories using dry-run-first workflow. Use when this capability is needed.

- Skill: `tomevault-io/agent-doc-init` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/agent-doc-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/agent-doc-init/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/agent-doc-init

---


# Agent Doc Init

Initialize missing baseline policy documents with a non-destructive default.

## Contract

Prereqs:

- `agent-docs` available on `PATH`.
- `bash` and `python3` available on `PATH`.
- Write permission to target paths only when `--apply` is used.

Inputs:

- Entrypoint: `$AGENT_HOME/skills/tools/agent-doc-init/scripts/agent_doc_init.sh`.
- Optional flags:
  - `--dry-run` (default mode)
  - `--apply` (write mode)
  - `--force` (overwrite baseline docs; requires `--apply`)
  - `--target all|home|project` (default: `all`)
  - `--project-path <path>`
  - `--agent-home <path>`
  - `--project-required <context:path[:notes]>` (repeatable)

Outputs:

- Deterministic summary lines to stdout.
- Baseline checks before/after initialization.
- Optional baseline scaffolding (`scaffold-baseline --missing-only` by default).
- Project-doc hydration for baseline templates (`AGENTS.md`, `DEVELOPMENT.md`) using detected repo context (CI workflows, Formula files, git
  remote).
- Optional project extension upserts via `agent-docs add`.

Exit codes:

- `0`: success (including no-op)
- `1`: runtime/dependency failure
- `2`: usage/safety contract violation

Failure modes:

- `agent-docs` is missing from `PATH`.
- Invalid `--project-required` format or unsupported context.
- `--force` is provided without `--apply`.
- `agent-docs` reports config/schema/runtime failures.
- Template-only baseline docs remain after hydration in apply mode.
- File permission errors when writing during apply mode.

## Scripts (only entrypoints)

- `$AGENT_HOME/skills/tools/agent-doc-init/scripts/agent_doc_init.sh`

## Workflow

1. Run baseline check (`agent-docs baseline --check`) and capture missing counts.
2. If required docs are missing (or force mode is requested), run `scaffold-baseline`:
   - default: `--missing-only`
   - overwrite path: `--force` (only when explicitly requested)
3. Hydrate baseline template docs into project-aware content (dry-run: plan only; apply: write).
4. Optionally upsert project extension docs via `agent-docs add` for each `--project-required`.
5. Re-run baseline check and emit deterministic summary (including `doc_hydration` + `template_guard`).

## Safety defaults

- Dry-run by default (`--apply` is required for writes).
- No overwrite unless `--force` is explicitly provided.
- Missing-only scaffold is the default write behavior.
- Apply mode enforces template guard for project docs (fails if template-only docs remain).
- All actions are idempotent when rerun with the same inputs.

## Usage

Preview only:

```bash
$AGENT_HOME/skills/tools/agent-doc-init/scripts/agent_doc_init.sh \
  --dry-run \
  --project-path /path/to/repo
```

Apply missing baseline docs:

```bash
$AGENT_HOME/skills/tools/agent-doc-init/scripts/agent_doc_init.sh \
  --apply \
  --project-path /path/to/repo
```

Apply and add one project extension required doc:

```bash
$AGENT_HOME/skills/tools/agent-doc-init/scripts/agent_doc_init.sh \
  --apply \
  --project-path /path/to/repo \
  --project-required "project-dev:BINARY_DEPENDENCIES.md:External runtime tools"
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/graysurf) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->