hirmos 1.3.2 → 1.3.4

package/README.md

@@ -1,85 +1,39 @@
 # HIRMOS CLI
 
-Product-facing HIRMOS CLI.
+The HIRMOS CLI is the terminal installer for the HIRMOS framework payload and AI-tool integration files.
 
-Implemented command:
+It is intentionally small. HIRMOS framework workflow commands such as `hirmos start`, `hirmos status`, `hirmos continue`, and `hirmos close` are commands for the LLM/agent inside supported integration tools after initialization. They are not terminal CLI commands.
+
+## Implemented CLI commands
 
 ```bash
 hirmos init [project-path] [--integration <ids>] [--source <path>] [--version <version>] [--offline]
 ```
 
-The CLI makes an installed HIRMOS project discoverable to selected agent-native tools by generating thin bootstrap integration files from `_hirmos/integrations/agent-tools/`.
-
-It does not invoke agents, run HIRMOS workflows, install extensions, or generate slash-command packs.
-
-## Usage
-
-From a project root:
 
-```bash
-hirmos init
-```
+## Integration template ownership
 
-If `_hirmos/` is not present, the CLI downloads the latest HIRMOS framework release package and installs `_hirmos/` before generating integrations.
-
-This defaults to:
+`tools/cli` installs integration templates; it does not own them. The canonical integration registry and templates live in the framework payload at:
 
 ```text
-project-path = .
-integration = agents
-source = existing _hirmos/ in the project, otherwise latest GitHub release
-version = latest
-```
-
-Generate specific integrations:
-
-```bash
-hirmos init --integration claude,cursor,copilot
-```
-
-Initialize another project path:
-
-```bash
-hirmos init /path/to/project --integration agents,claude
-```
-
-Install a specific HIRMOS release:
-
-```bash
-hirmos init --version 1.3.1
+_hirmos/integrations/agent-tools/
 ```
 
-Install `_hirmos/` from a local source folder or release zip instead of downloading:
+Maintainers should update integration definitions in `_private/_hirmos/integrations/agent-tools/`, propagate them to `_public/_hirmos/integrations/agent-tools/`, regenerate `ops/dist/hirmos-framework.zip`, and then verify `hirmos init` against the regenerated framework payload.
 
-```bash
-hirmos init /path/to/project --source /path/to/hirmos-framework.zip --integration agents
-```
-
-Disable remote download and require an existing `_hirmos/` or local `--source`:
-
-```bash
-hirmos init --offline
-```
+## What `hirmos init` does
 
-## CLI update notice
+`hirmos init` prepares a project to use HIRMOS by:
 
-When `hirmos init` runs online, it checks whether a newer published HIRMOS CLI version is available on npm. If a newer version exists, the CLI prints a non-blocking message such as:
-
-```text
-A newer HIRMOS CLI is available: 1.3.2.
-Update with: npm install -g hirmos@latest
-```
-
-The notice does not stop initialization. Network failures, registry errors, or timeouts are ignored.
-
-Use `--offline` to disable both remote framework download and the update check. To disable only the update notice while keeping remote framework download available, run:
-
-```bash
-HIRMOS_CLI_UPDATE_CHECK=0 hirmos init
-```
+1. Installing `_hirmos/` if the project does not already have it.
+2. Validating that the installed framework payload is complete enough for initialization.
+3. Generating or updating selected AI-tool integration files using managed HIRMOS blocks.
+4. Recording selected integrations in `_hirmos/hirmos.config.json`.
 
 ## Supported integrations
 
+`--integration` accepts comma-separated integration ids. Current ids:
+
 ```text
 agents
 claude
@@ -92,48 +46,59 @@ windsurf
 kiro
 ```
 
-Some integrations share the same target file. For example, `agents`, `codex`, and `opencode` all use `AGENTS.md` as the safe generic bootstrap target.
+Default:
 
-## Managed-block behavior
+```bash
+hirmos init
+```
 
-For existing files, the CLI updates only the HIRMOS managed block:
+This installs the generic `agents` integration.
 
-```md
-<!-- HIRMOS:START -->
-...
-<!-- HIRMOS:END -->
+Examples:
+
+```bash
+hirmos init --integration agents,claude,cursor
+hirmos init ./my-project --integration agents,copilot,codex,opencode
+hirmos init ./my-project --source ./hirmos-framework.zip --offline
 ```
 
-If the file exists and has no HIRMOS block, the CLI appends one. User-owned content outside the block is preserved.
+## Source selection
 
-## Project config behavior
+By default, if the target project already has `_hirmos/`, the CLI uses that framework payload. If the target project does not have `_hirmos/`, the CLI downloads the selected GitHub release unless `--source` or `--offline` changes that behavior.
 
-The CLI merges selected integration IDs into:
+`--source` may point to:
 
-```text
-_hirmos/project.json
-```
+- an `_hirmos/` directory
+- a folder containing `_hirmos/`
+- a `hirmos-framework.zip` release package
+
+`--offline` disables remote release download and requires either an existing `_hirmos/` or `--source`.
+
+## Update notice
 
-under:
+When `hirmos init` runs online, it checks whether a newer published HIRMOS CLI version is available on npm. If a newer version exists, the CLI prints a non-blocking message. The check can be disabled:
 
-```json
-{
-  "integrations": {
-    "installed": []
-  }
-}
+```bash
+HIRMOS_CLI_UPDATE_CHECK=0 hirmos init
 ```
 
-Re-running `hirmos init --integration ...` is additive and does not remove previously recorded integrations.
+## After initialization
+
+Open the project in the selected AI coding tool. The generated integration file is the normal bootstrap path for that tool.
 
-## Workflow commands are not CLI commands
+If the integration file is not available or the tool did not load it, use this fallback bootstrap prompt inside the agent conversation:
+
+```text
+Read and follow _hirmos/AGENTS.md
+```
 
-These are HIRMOS workflow commands to use inside the AI tool after HIRMOS Core has loaded:
+Then use HIRMOS framework workflow commands inside the agent conversation, for example:
 
 ```text
-hirmos requirements
-hirmos system-design
-hirmos implementation
+hirmos start
+hirmos status
+hirmos continue
+hirmos close
 ```
 
-The CLI implements `hirmos init`.
+Those workflow commands are governed by the framework instructions and active session artifacts, not by this terminal CLI.

package/dist/commands/init.js

@@ -58,7 +58,16 @@ function formatInitSummary(first, selected, added, alreadyInstalled, targets, in
         for (const target of targets)
             lines.push(`- ${target}`);
         lines.push("", "Next step:");
-        lines.push("Open your AI coding tool and ask it to read and follow _hirmos/HIRMOS_CORE.md.");
+        lines.push("Open your AI coding tool in this project and ask the agent to run a HIRMOS framework workflow command, for example:");
+        lines.push("");
+        lines.push("hirmos start");
+        lines.push("hirmos status");
+        lines.push("hirmos continue");
+        lines.push("");
+        lines.push("Fallback agent instruction:");
+        lines.push("If your tool does not automatically pick up the selected agent/tool integration files, copy and paste this prompt into your agent:");
+        lines.push("");
+        lines.push("Read and follow the instructions on _hirmos/AGENTS.md.");
         lines.push("", "To add more integrations later:");
         lines.push("hirmos init --integration claude,cursor,copilot");
         return `${lines.join("\n")}\n`;

package/dist/lib/args.js

@@ -14,8 +14,8 @@ function parseArgs(argv) {
         return { command: "help" };
     }
     const command = argv[0];
-    if (command !== "init") {
-        (0, errors_1.fail)(`Unsupported command: ${command}. This CLI currently supports: hirmos init`);
+    if (!command || command !== "init") {
+        (0, errors_1.fail)(`Unsupported command: ${command}. This CLI supports: hirmos init`);
     }
     let projectPath = ".";
     let projectPathSet = false;
@@ -101,5 +101,24 @@ function parseIntegrationList(value) {
     return ids;
 }
 function helpText() {
-    return `HIRMOS CLI\n\nUsage:\n  hirmos init [project-path] [--integration <ids>] [--source <path>] [--version <version>] [--offline]\n\nDefaults:\n  project-path: .\n  integration: agents\n  source: existing _hirmos/ in the project, otherwise the latest GitHub release\n  version: latest\n\nNotes:\n  --source installs from a local _hirmos folder, framework folder, or hirmos-framework.zip.\n  --version selects a GitHub release when _hirmos/ is missing and --source is not provided.\n  --offline disables remote release download and requires an existing _hirmos/ or --source.\n\nThis CLI implements hirmos init. Workflow commands such as hirmos requirements are interpreted by an agent after HIRMOS Core is loaded.\n`;
+    return `HIRMOS CLI
+
+Usage:
+  hirmos init [project-path] [--integration <ids>] [--source <path>] [--version <version>] [--offline]
+
+Defaults:
+  project-path: .
+  integration: agents
+  source: existing _hirmos/ in the project, otherwise the latest GitHub release
+  version: latest
+
+Notes:
+  hirmos init installs the HIRMOS framework payload when needed and writes selected AI-tool integration files.
+  --integration accepts comma-separated ids, for example: agents,claude,cursor,copilot,codex,opencode,gemini,windsurf,kiro.
+  --source installs from a local _hirmos folder, framework folder, or hirmos-framework.zip.
+  --version selects a GitHub release when _hirmos/ is missing and --source is not provided.
+  --offline disables remote release download and requires an existing _hirmos/ or --source.
+
+Framework workflow commands such as hirmos start, hirmos status, hirmos continue, and hirmos close are used inside supported AI tools after init, not as terminal CLI commands.
+`;
 }

package/dist/lib/project-config.js

@@ -3,14 +3,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_INTERACTION_MODE = exports.INTERACTION_MODES = void 0;
 exports.loadProjectConfig = loadProjectConfig;
 exports.mergeProjectConfig = mergeProjectConfig;
+exports.resolveInteractionMode = resolveInteractionMode;
 exports.writeProjectConfig = writeProjectConfig;
 const path_1 = __importDefault(require("path"));
 const filesystem_1 = require("./filesystem");
 const integration_registry_1 = require("./integration-registry");
+exports.INTERACTION_MODES = [
+    "domain_expert",
+    "technical_supervisor",
+    "framework_dogfooding",
+];
+exports.DEFAULT_INTERACTION_MODE = "domain_expert";
 function loadProjectConfig(projectRoot) {
-    return (0, filesystem_1.readJson)(path_1.default.join(projectRoot, "_hirmos", "project.json"), "_hirmos/project.json");
+    return (0, filesystem_1.readJson)(path_1.default.join(projectRoot, "_hirmos", "hirmos.config.json"), "_hirmos/hirmos.config.json");
 }
 function mergeProjectConfig(config, selected, registry) {
     const previousInstalled = Array.isArray(config.integrations?.installed)
@@ -40,6 +48,19 @@ function mergeProjectConfig(config, selected, registry) {
         wasFirstInitialization: previousInstalled.length === 0
     };
 }
+function resolveInteractionMode(config) {
+    const raw = config.interaction_mode;
+    if (raw === undefined || raw === null || raw === "")
+        return exports.DEFAULT_INTERACTION_MODE;
+    if (typeof raw !== "string") {
+        throw new Error("_hirmos/hirmos.config.json#interaction_mode must be a string when present.");
+    }
+    const normalized = raw.trim();
+    if (exports.INTERACTION_MODES.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`_hirmos/hirmos.config.json#interaction_mode must be one of: ${exports.INTERACTION_MODES.join(", ")}. Got: ${raw}`);
+}
 function writeProjectConfig(projectRoot, config) {
-    (0, filesystem_1.writeJson)(path_1.default.join(projectRoot, "_hirmos", "project.json"), config);
+    (0, filesystem_1.writeJson)(path_1.default.join(projectRoot, "_hirmos", "hirmos.config.json"), config);
 }

package/dist/lib/source-install.js

@@ -78,7 +78,8 @@ function installFromDirectory(projectRoot, sourceDir) {
     if (!(0, filesystem_1.pathExists)(sourceHirmos) || !fs_1.default.statSync(sourceHirmos).isDirectory()) {
         (0, errors_1.fail)(`Source folder does not contain _hirmos/: ${sourceDir}`);
     }
-    copyHirmos(projectRoot, sourceHirmos);
+    const sourceReadme = resolveSourceReadmeForDirectory(sourceDir);
+    copyHirmos(projectRoot, sourceHirmos, sourceReadme);
 }
 function installFromZip(projectRoot, zipPath) {
     const tmp = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), "hirmos-cli-"));
@@ -93,7 +94,8 @@ function installFromZip(projectRoot, zipPath) {
         if (!sourceHirmos) {
             (0, errors_1.fail)(`Framework zip does not contain an _hirmos/ folder: ${zipPath}`);
         }
-        copyHirmos(projectRoot, sourceHirmos);
+        const sourceReadme = resolveSourceReadmeForZip(tmp, sourceHirmos);
+        copyHirmos(projectRoot, sourceHirmos, sourceReadme);
     }
     finally {
         fs_1.default.rmSync(tmp, { recursive: true, force: true });
@@ -113,23 +115,57 @@ function findHirmosDir(root) {
     }
     return null;
 }
-function copyHirmos(projectRoot, sourceHirmos) {
+function resolveSourceReadmeForDirectory(sourceDir) {
+    if (path_1.default.basename(sourceDir) === "_hirmos") {
+        return null;
+    }
+    const repoReadme = path_1.default.join(sourceDir, "README.md");
+    if ((0, filesystem_1.pathExists)(repoReadme))
+        return repoReadme;
+    return null;
+}
+function resolveSourceReadmeForZip(extractRoot, sourceHirmos) {
+    const parentReadme = path_1.default.join(path_1.default.dirname(sourceHirmos), "README.md");
+    if ((0, filesystem_1.pathExists)(parentReadme))
+        return parentReadme;
+    const direct = path_1.default.join(extractRoot, "README.md");
+    if ((0, filesystem_1.pathExists)(direct))
+        return direct;
+    return null;
+}
+function copyHirmos(projectRoot, sourceHirmos, sourceReadme = null) {
     const target = path_1.default.join(projectRoot, "_hirmos");
     if ((0, filesystem_1.pathExists)(target)) {
         (0, errors_1.fail)(`Refusing to overwrite existing _hirmos/: ${target}`);
     }
     (0, filesystem_1.ensureDir)(projectRoot);
     fs_1.default.cpSync(sourceHirmos, target, { recursive: true, errorOnExist: true });
+    if (sourceReadme && (0, filesystem_1.pathExists)(sourceReadme)) {
+        const readmeBody = fs_1.default.readFileSync(sourceReadme, "utf8");
+        fs_1.default.writeFileSync(path_1.default.join(target, "README.md"), normalizeReadmeForInstalledHirmos(readmeBody), "utf8");
+    }
     validateCopiedHirmos(projectRoot);
 }
+function normalizeReadmeForInstalledHirmos(readmeBody) {
+    return readmeBody
+        .replace(/\(\.\/_hirmos\//gu, "(./")
+        .replace(/\(_hirmos\//gu, "(./");
+}
 function validateCopiedHirmos(projectRoot) {
-    const required = ["_hirmos/HIRMOS_CORE.md", "_hirmos/VERSION", "_hirmos/project.json"];
+    const required = ["_hirmos/AGENTS.md", "_hirmos/README.md", "_hirmos/hirmos.config.json", "_hirmos/core/bootstrap.md", "_hirmos/inputs/README.md", "_hirmos/inputs/uploads/README.md"];
     for (const relative of required) {
         if (!(0, filesystem_1.pathExists)(path_1.default.join(projectRoot, relative))) {
             fs_1.default.rmSync(path_1.default.join(projectRoot, "_hirmos"), { recursive: true, force: true });
             (0, errors_1.fail)(`Installed framework is incomplete; missing ${relative}. Removed partial _hirmos/ install.`);
         }
     }
+    const installedReadme = fs_1.default.readFileSync(path_1.default.join(projectRoot, "_hirmos", "README.md"), "utf8");
+    for (const phrase of ["Why HIRMOS exists", "Simple by default", "hirmos start", "Understand System State"]) {
+        if (!installedReadme.includes(phrase)) {
+            fs_1.default.rmSync(path_1.default.join(projectRoot, "_hirmos"), { recursive: true, force: true });
+            (0, errors_1.fail)(`Installed framework README is incomplete; missing onboarding phrase: ${phrase}. Removed partial _hirmos/ install.`);
+        }
+    }
 }
 function extractZip(zipPath, destination) {
     if (process.platform === "win32") {

package/dist/lib/validation.js

@@ -19,9 +19,12 @@ function validateProjectRoot(projectRoot) {
 }
 function validateHirmosFramework(projectRoot) {
     const required = [
-        "_hirmos/HIRMOS_CORE.md",
-        "_hirmos/project.json",
-        "_hirmos/integrations/agent-tools/registry.json"
+        "_hirmos/AGENTS.md",
+        "_hirmos/README.md",
+        "_hirmos/hirmos.config.json",
+        "_hirmos/integrations/agent-tools/registry.json",
+        "_hirmos/inputs/README.md",
+        "_hirmos/inputs/uploads/README.md"
     ];
     for (const relative of required) {
         const absolute = path_1.default.join(projectRoot, relative);
@@ -29,6 +32,13 @@ function validateHirmosFramework(projectRoot) {
             (0, errors_1.fail)(`Required HIRMOS file is missing: ${relative}`);
         }
     }
+    const readmePath = path_1.default.join(projectRoot, "_hirmos", "README.md");
+    const readmeBody = fs_1.default.readFileSync(readmePath, "utf8");
+    for (const phrase of ["Why HIRMOS exists", "Simple by default", "hirmos start", "Understand System State"]) {
+        if (!readmeBody.includes(phrase)) {
+            (0, errors_1.fail)(`Installed HIRMOS README is missing onboarding phrase: ${phrase}`);
+        }
+    }
     const templatesDir = path_1.default.join(projectRoot, "_hirmos", "integrations/agent-tools", "templates");
     if (!(0, filesystem_1.pathExists)(templatesDir) || !fs_1.default.statSync(templatesDir).isDirectory()) {
         (0, errors_1.fail)("Required HIRMOS directory is missing: _hirmos/integrations/agent-tools/templates/");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hirmos",
-  "version": "1.3.2",
-  "description": "HIRMOS product-facing CLI.",
+  "version": "1.3.4",
+  "description": "HIRMOS framework installer and AI-tool integration CLI.",
   "license": "Apache-2.0",
   "type": "commonjs",
   "bin": {