init.md is a human- and machine-readable procedure for inspecting a target, determining what it requires, applying the appropriate initialization pattern, validating the result, and reporting its operational state.
It is not one fixed scaffold. The canonical file defines the general initialization procedure. Templates specialize that procedure for specific targets.
Use init.md when a target needs to become operational. A target may be a software project, repository, AI agent, server, service, workspace, research environment, data pipeline, application, tool, local directory, remote environment, or existing system requiring restoration or reconfiguration.
The root protocol stays general. It identifies the target, chooses or adapts an initialization pattern, creates and configures only what applies, validates the intended result, and reports the operational state.
Templates provide concrete patterns for common target categories. They describe likely behavior, not mandatory output bundles.
- Inspect what exists.
- Determine what is needed.
- Create what applies.
- Configure what is required.
- Validate the result.
- Report what became operational.
init.mddefines the target-neutral procedure.templates/contains target-specific initialization patterns.- Generated outputs are conditional.
- Validation is derived from the target.
- Existing work should be adapted before creating replacements.
No output file is universally required except where the selected template or target requires it.
templates/minimal_init_protocol.md— smallest reasonable initialization pattern for narrow gaps.templates/dry_run_init_protocol.md— no-change inspection and proposed initialization plan.templates/development_project_init_protocol.md— software projects, repositories, apps, packages, CLIs, websites, and monorepos.templates/agent_init_protocol.md— agent instructions, tools, prompts, state, and startup validation.templates/server_init_protocol.md— server, service host, infrastructure, and deployment readiness.
Each template includes metadata for likely targets, modes, created artifacts, configured elements, validation checks, and optional outputs.
Agents can read the root protocol or a selected template directly. During inspection, determine whether agent instructions are applicable. Create AGENTS.md only when agent operation applies and valid target-specific instructions do not already exist.
Different projects should have different AGENTS.md files. Different targets should have different init.md implementations.
- Identify the target and intended operational result.
- Choose the closest template.
- Copy or adapt the template.
- Run the procedure in active, dry-run, repair, or reinitialize mode.
- Review the validation result.
- Keep the resulting target-specific
init.mdwith the target.
Example instructions:
Initialize this repository using the development-project template.
Inspect this server using the server template in dry-run mode.
Determine what this agent workspace needs to become operational.
Create an AGENTS.md file only if this project would benefit from one.
This repository preserves a static Vite and React website for browsing templates and copying canonical Markdown content.
Common commands:
npm install
npm run dev
npm run buildThe build runs scripts/check-templates.mjs before compiling the site. That check verifies the expected template files exist and contain the required metadata fields.
The public site is deployed with GitHub Pages from the existing Vite build. It renders the Markdown files under templates/ as the canonical source and keeps copy-to-clipboard behavior for root init.md and complete usable template bodies.
GitHub Pages must use Build and deployment > Source: GitHub Actions for this repository. Do not use Deploy from a branch > root, because that serves the unbuilt Vite source files and the browser will try to load /src/main.tsx directly.
Repository: https://github.com/bitwikiorg/init.md
Use BIThub to discuss the protocol, ask questions, share templates, propose improvements, and report implementation experiences.
- BIThub forum: https://hub.bitwiki.org/
Contributions should preserve the distinction between the general protocol and target-specific templates. Avoid adding universal requirements to the root protocol when they belong in a template.
When updating templates, keep the Markdown files canonical and maintain their metadata fields.
MIT License. See LICENSE.