agentic-init

agentic-init — the installer

You scaffold a governed multi-agent architecture into the target repo (the current working directory's git root, TARGET below). Everything you copy, render, or generate is journaled so an interrupted run resumes and a re-run is idempotent.

Conventions (read once, apply everywhere)

• PLUGIN = the agentic-os plugin root (${CLAUDE_PLUGIN_ROOT} when set; otherwise the directory two levels above this SKILL.md). It contains templates/, generators/, presets/, manifest/.

• AGENTIC_OS_VERSION = "version" from PLUGIN/.claude-plugin/plugin.json.

• Journal = TARGET/.agentic/agentic-os/install.json. Shape:

  {
    "agentic_os_version": "<AGENTIC_OS_VERSION>",
    "stack_discovery": { "...": "the structured record from generators/stack-discovery.md — see templates/VARIABLES.md § The stack-fact record" },
    "answers": { "<interview key>": "<value>" },
    "phase": "preflight|interview|dependencies|scaffold|generate|verify|done",
    "files": {
      "<repo-relative path>": {
        "sha256": "<hex of the file as written>",
        "template": "<template ID, gen/* slot, or 'derived'>",
        "owner": "managed|user|generated",
        "origin": "plugin|adopted-existing|generated"
      }
    },
    "follow_ups": ["<human-readable follow-up items>"]
  }
  

  Update the journal after every phase (and after every file write in Phase 4/5). sha256 of a file: shasum -a 256 <file> | cut -d' ' -f1.

• Owner semantics: managed = agentic-os wrote it and may overwrite it on upgrade when unmodified; user = pre-existed or user-declined — never touched again; generated = produced by a generator subagent — upgrades offer regeneration, never overwrite.

• Origin semantics: origin records where a file came from, which owner alone cannot express. Assets adopted from a fleet the repo already had carry owner: "user" with origin: "adopted-existing" — they are inputs to verification and never destinations for scaffolding or upgrade.

• Rendering (registry: PLUGIN/templates/VARIABLES.md): substitution of {{VAR}} — no logic in templates; every conditional lives here. Files without .tmpl are copied verbatim. How you substitute depends on the file type:

  • .py.tmpl and .json.tmpl — escape every scalar. Substitute json.dumps(value, ensure_ascii=False)[1:-1]: the value with ", \, and control characters (newlines included) escaped, and no surrounding quotes. The template already supplies the quotes — do not strip them, and do not hand-escape. Mandatory in every position: whole literal, interpolated literal, triple-quoted block, comment. Templates quote with " only; json.dumps does not escape '.