# AI Native

> Turn a repo into an AI-native project — lay down AGENTS.md, standard verbs, gates, and the spec directory. Works on new and existing repos.

- Skill: `initxy/ai-native` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add initxy/ai-native`
- Raw SKILL.md: https://api.skillmd.com/api/skills/initxy/ai-native/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: initxy (https://skillmd.com/u/initxy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/initxy/ai-native

---


# AI Native

Turn a repo into an AI-native project. Same entry point for new and existing repos, same output: slots in place, verbs unified, gates explicit. This is a one-time setup: day-to-day work afterwards runs on the conventions written into the repo — the agent reads `AGENTS.md`, not this skill.

Before you start, read `references/harness.md` (the spec) and `references/templates.md` (the templates) in this directory.

## Which path

Repo nearly empty → new project; existing code → retrofit. A repo that already has an `AGENTS.md` — from an earlier run of this skill or any other tooling — is still the retrofit path, and the run becomes a reconcile: diff what's there against the spec, apply only the delta (see the merge step below). Re-running is safe by design.

## New project

1. Don't ask about the tech stack — that decision belongs to the first spec, not the harness. If the repo already carries scaffolding (a manifest, a toolchain config), read the stack from it silently.
2. Ask only the questions that change the initialization outcome: the working language and style (see "Language & style"), and the two conditional-slot questions — does the project publish anything (→ `docs/releasing.md`), and are outside contributors expected (→ `CONTRIBUTING.md` + PR template).
3. Lay down `AGENTS.md`, the stage runbooks (`docs/reviewing.md`, `docs/gc.md`), and `docs/specs/` from the templates (including the spec template `docs/specs/TEMPLATE.md`), plus whichever conditional slots apply; `CLAUDE.md` only references `AGENTS.md`.
4. Write real commands into the verbs and gates where a toolchain exists, including the `check` aggregate; mark the rest "TODO" in `AGENTS.md` rather than fabricating one — they get filled in when the stack lands. If CI exists or is being set up, point it at the same `check` command.
5. Don't pre-create an empty `CONTEXT.md` / ADR; create them only when there's real content.

## Existing project

1. **Map the repo before deciding anything.** Fan out parallel subagents (read directly if the environment has none) to cover: toolchain — test / build / lint commands, CI config, release automation; code shape — entry points, module boundaries, domain concepts; docs and conventions — README, contributor files (CONTRIBUTING / issue / PR templates), legacy conventions (`AGENTS.md` / `CLAUDE.md` / cursor rules, etc.), old docs, dev logs; history — git log for active areas and past direction changes. Synthesize one findings report and show it to the user before asking any question or writing any file; every later step cites this report, not fresh guesses.
2. **Wrap the verbs**: wrap existing commands into standard verbs behind a unified entry point; aim only for a unified entry point, don't require changing tools. A verb you don't have stays honestly absent. Provide the `check` aggregate and reconcile it with CI: everything CI runs is either inside `check` or listed as CI-only in `AGENTS.md`; if CI runs different commands than `check`, point CI at `check` (or record the gap as a `proposed` spec) — local green must mean CI green.
3. **Mine context — on a strict budget**: draft `CONTEXT.md` and ADRs from the findings report, **then confirm with the human before writing them in**. An entry earns its place only if an agent couldn't recover it from code quickly and getting it wrong would cause real damage — a few lines each, pointing at code; ADRs only for decisions still binding and non-obvious. When unsure, leave it out: a gap a task trips over gets added then, a speculative entry just rots.
4. **Merge with any existing `AGENTS.md` — never replace it**: an existing `AGENTS.md` is the working agreement the team already follows, so it stays the base document. Diff it against the harness spec: what's missing (task flow, verbs, gates, spec directory) gets added in the existing doc's own voice; what's already covered keeps its wording — don't rewrite for style; what conflicts goes to the user before anything changes, never silently overwritten. Project-specific rules the template doesn't know about are the most valuable part — keep them. Scattered conventions without a home (`CLAUDE.md` content, cursor rules, convention fragments in the README) fold into it, and those tool-private files shrink to a reference. Keep the merged result self-contained — no references to skills, tools, or setup only this environment has. Lay the stage runbooks (`docs/reviewing.md`, `docs/gc.md`) from the templates; if the repo already has equivalents, merge the same way. A `docs/shaping.md` from an earlier run folds into the `AGENTS.md` task flow (shaping rules are resident now) and is removed.
5. **Assess the verification gap and report it honestly**: estimate how much regression protection the existing tests give behavior, and state plainly "the agent can safely operate autonomously within X; widening that requires shoring up Y first." This step can't be skipped or sugarcoated — it sets how strict the gates are.
6. **Set gates by the gap**: weak coverage → stricter gates, more approval points, loosening gradually as coverage fills in; write "shore up verification" as the first batch of `proposed` specs into `docs/specs/`.
7. **Lay conditional slots**: if the project publishes anything, write `docs/releasing.md` from what the existing release automation actually does; if outside contributors are expected, lay down `CONTRIBUTING.md` and the PR template, folding in any existing ones rather than replacing them.
8. **Migrate legacy artifacts**: move a legacy `docs/implementation-specs/` into `docs/specs/` (completed ones straight into `archive/`, unfinished ones get a status). Don't delete old material outright; get confirmation before migrating, archiving, or replacing.

## Language & style

For both new and existing repos, ask the user, then write the answers into the AGENTS.md `## Language` section:

- What language the docs (`CONTEXT.md`, ADR, `docs/specs/`) should be written in.
- What language replies / conversation should use.
- Any tone or style preference (optional).

Carry a sensible default so the user just confirms instead of answering cold. If the user has no preference, drop the section rather than leaving a placeholder.

## Questioning rules

- Show findings and recommendations before writing files.
- Ask at most 3 questions at a time, and only ones that change the initialization outcome.
- Don't ask what you can determine from the repo's existing files.

## Completion criteria

- `AGENTS.md` exists and is thin, covering task flow (the resident shaping rules included), verbs (real commands, including `check`), gates, approval points, and the language / style the user chose — self-contained, with no reference to anything only the maintainer has.
- `docs/specs/` with the spec template `docs/specs/TEMPLATE.md`, and the stage runbooks (`docs/reviewing.md`, `docs/gc.md`), are in place (both new and existing projects).
- Standard verbs each run via one command, or the gap and fill-in plan are noted honestly; where CI exists, it runs the same `check`, or the difference is written down.
- Conditional slots (`docs/releasing.md`, `CONTRIBUTING.md` + PR template) are laid down where they apply, or explicitly skipped with the reason.
- Existing project: the findings report was shown before any write; the verification gap is reported honestly; an existing `AGENTS.md` is merged, not replaced — its project-specific rules survive, and every conflict was decided by the user; scattered legacy conventions are folded in or explicitly flagged for later.
- Docs written at init obey the budget: every `CONTEXT.md` entry is a few lines pointing at code; no speculative entries, no ADRs for decisions nobody will question.
- Closing note: which legacy content was folded in, what context was converted, what the first batch of `proposed` specs are, and what remains unhandled.