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.