@ai-content-space/loopx 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# LoopX
+
+`LoopX` is a skill-first workflow product for Codex. It supports two first-class distribution shells:
+
+- npm/global install
+- Codex plugin install
+
+Both shells converge on one shared LoopX core and one visible LoopX skill set.
+
+## Release Contract
+
+The active LoopX release flow is:
+
+`clarify -> plan -> build -> review`
+
+Bundled skill surfaces:
+
+- `loopx-clarify`
+- `loopx-plan`
+- `loopx-build`
+- `loopx-review`
+- `loopx-autopilot`
+
+There is no public `team` surface in this release.
+
+## Product Positioning
+
+- skill-first for normal use
+- retained CLI/runtime/debug substrate for maintenance and inspection
+- explicit local artifacts and state under `.LoopX/`
+- bounded migration from legacy `.codex-helper/`
+
+## Runtime Namespace
+
+LoopX user-facing runtime state is stored under:
+
+```text
+.LoopX/
+```
+
+Key subtrees:
+
+- `.LoopX/specs/`
+- `.LoopX/plans/`
+- `.LoopX/workflows/<slug>/`
+- `.LoopX/autopilot/<slug>/`
+
+The `.omx/` tree remains orchestration/planning metadata and is not part of the LoopX runtime rename.
+
+## CLI Surface
+
+Primary runtime/debug commands:
+
+```bash
+loopx init [--slug <slug>]
+loopx clarify <slug>
+loopx approve <slug> --from <stage> --to <stage>
+loopx plan <slug>
+loopx build <slug>
+loopx review <slug> [--reviewer <name>]
+loopx autopilot <slug> [--reviewer <name>]
+loopx status [slug] [--json]
+loopx doctor
+loopx migrate
+loopx repair-install
+```
+
+The CLI is supporting runtime/debug tooling. The intended user-facing product surface is the bundled LoopX skills.
+
+## Install and Discovery
+
+LoopX supports two install paths that both reuse the same shared install/discovery core:
+
+- npm/global install:
+  - `npm install -g @ai-content-space/loopx`
+  - followed by `postinstall -> node scripts/install-skills.mjs`
+- plugin install:
+  - `plugins/loopx/scripts/plugin-install.mjs`
+
+Bootstrap behavior:
+
+- materializes LoopX-owned skills under `~/.agents/skills/`
+- updates LoopX-owned `local` rows in `~/.agents/.skill-lock.json`
+- keeps install idempotent
+- supports repair through `loopx repair-install`
+- converges npm and plugin installs onto one `installationIdentity=loopx`
+
+Discovery is valid only when both are true:
+
+- the installed LoopX skill directory exists
+- the matching LoopX-owned registry row exists
+
+If both npm and plugin installs are present, Codex should still expose one LoopX skill set rather than duplicates.
+
+## Legacy Migration
+
+- legacy `.codex-helper/` runtime state is migrated through `loopx migrate`
+- mixed `.LoopX/` and `.codex-helper/` roots are treated as a repairable error
+- public docs, package, CLI, and skill names use `LoopX`
+
+## Verification
+
+```bash
+node --test test/*.test.mjs
+node scripts/install-skills.mjs --check
+node --test plugins/loopx/scripts/plugin-install.test.mjs
+node src/cli.mjs --help
+node src/cli.mjs doctor
+node src/cli.mjs status --json
+```

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@ai-content-space/loopx",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Skill-first LoopX workflow product for Codex",
+  "keywords": [
+    "codex",
+    "loopx",
+    "skills",
+    "workflow",
+    "plugin"
+  ],
+  "bin": {
+    "loopx": "src/cli.mjs"
+  },
+  "files": [
+    "README.md",
+    "package.json",
+    "scripts/install-skills.mjs",
+    "src/",
+    "skills/",
+    "templates/",
+    "plugins/loopx/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install-skills.mjs",
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/plugins/loopx/.codex-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "loopx",
+  "version": "0.1.0",
+  "description": "Skill-first LoopX workflow product for Codex",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "LoopX",
+    "shortDescription": "Thin plugin shell for the LoopX skill bundle.",
+    "longDescription": "This plugin mirrors the canonical LoopX skills and routes plugin installs through the shared LoopX install/discovery core. It stays plugin-root-relative at the manifest boundary and does not define a second LoopX implementation.",
+    "developerName": "LoopX",
+    "category": "Developer Tools"
+  }
+}

package/plugins/loopx/scripts/plugin-install.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { installBundledSkills, verifyInstallState } from '../../../src/install-discovery.mjs';
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = resolve(MODULE_DIR, '..');
+const REPO_ROOT = resolve(PLUGIN_ROOT, '..', '..');
+const PLUGIN_SKILLS_ROOT = join(PLUGIN_ROOT, 'skills');
+const DISTRIBUTION_CHANNEL = 'plugin';
+
+function buildPluginEnv() {
+  return {
+    ...process.env,
+    LOOPX_PROJECT_ROOT: REPO_ROOT,
+    LOOPX_SKILL_SOURCE_ROOT: PLUGIN_SKILLS_ROOT,
+    LOOPX_DISTRIBUTION_CHANNEL: DISTRIBUTION_CHANNEL,
+    LOOPX_INSTALLATION_IDENTITY: 'loopx',
+    LOOPX_SOURCE_URL: PLUGIN_ROOT,
+  };
+}
+
+async function main() {
+  const checkOnly = process.argv.includes('--check');
+  const env = buildPluginEnv();
+  const result = checkOnly
+    ? await verifyInstallState(env)
+    : await installBundledSkills(env);
+  const ok = checkOnly ? result.ok : result.ok !== false;
+  const payload = checkOnly
+    ? {
+        ...result,
+        distributionChannel: DISTRIBUTION_CHANNEL,
+        pluginRoot: PLUGIN_ROOT,
+      }
+    : {
+        ok,
+        installed: result.installed,
+        conflicts: result.conflicts ?? [],
+        inspection: result.inspection,
+        distributionChannel: DISTRIBUTION_CHANNEL,
+        pluginRoot: PLUGIN_ROOT,
+      };
+
+  if (!ok) {
+    console.error(JSON.stringify(payload, null, 2));
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(JSON.stringify(payload, null, 2));
+}
+
+await main();

package/plugins/loopx/scripts/plugin-install.test.mjs

@@ -0,0 +1,94 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { mkdtemp, readdir, readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { verifyInstallState } from '../../../src/install-discovery.mjs';
+
+const execFileAsync = promisify(execFile);
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = resolve(MODULE_DIR, '..');
+const REPO_ROOT = resolve(PLUGIN_ROOT, '..', '..');
+const MANIFEST_PATH = join(PLUGIN_ROOT, '.codex-plugin', 'plugin.json');
+const INSTALL_SCRIPT = join(MODULE_DIR, 'plugin-install.mjs');
+const ROOT_SKILLS_DIR = join(REPO_ROOT, 'skills');
+const PLUGIN_SKILLS_DIR = join(PLUGIN_ROOT, 'skills');
+const LOOPX_SKILLS = [
+  'loopx-clarify',
+  'loopx-plan',
+  'loopx-build',
+  'loopx-review',
+  'loopx-autopilot',
+];
+
+function loopxEnv(home) {
+  return {
+    ...process.env,
+    HOME: home,
+    LOOPX_HOME: home,
+    LOOPX_AGENTS_ROOT: join(home, '.agents'),
+    LOOPX_SKILLS_ROOT: join(home, '.agents', 'skills'),
+    LOOPX_SKILL_LOCK_PATH: join(home, '.agents', '.skill-lock.json'),
+    LOOPX_PROJECT_ROOT: REPO_ROOT,
+    LOOPX_SKILL_SOURCE_ROOT: PLUGIN_SKILLS_DIR,
+  };
+}
+
+describe('LoopX plugin shell', () => {
+  it('defines a plugin manifest that only references plugin-root-relative assets', async () => {
+    const manifest = JSON.parse(await readFile(MANIFEST_PATH, 'utf8'));
+    const packageJson = JSON.parse(await readFile(join(REPO_ROOT, 'package.json'), 'utf8'));
+    const codexPluginEntries = await readdir(join(PLUGIN_ROOT, '.codex-plugin'));
+
+    assert.deepEqual(codexPluginEntries.sort(), ['plugin.json']);
+    assert.equal(manifest.name, 'loopx');
+    assert.equal(manifest.version, packageJson.version);
+    assert.equal(manifest.skills, './skills/');
+    assert.equal(manifest.interface.displayName, 'LoopX');
+
+    for (const key of ['skills', 'mcpServers', 'apps']) {
+      if (typeof manifest[key] === 'string') {
+        assert.equal(manifest[key].startsWith('./'), true, `${key} must stay plugin-root-relative`);
+      }
+    }
+  });
+
+  it('mirrors the canonical LoopX skill payload into the plugin shell', async () => {
+    for (const skillName of LOOPX_SKILLS) {
+      const rootSkill = await readFile(join(ROOT_SKILLS_DIR, skillName, 'SKILL.md'), 'utf8');
+      const pluginSkill = await readFile(join(PLUGIN_SKILLS_DIR, skillName, 'SKILL.md'), 'utf8');
+      assert.equal(pluginSkill, rootSkill, skillName);
+    }
+  });
+
+  it('reuses the shared install core while materializing skills from the plugin shell', async () => {
+    const home = await mkdtemp(join(tmpdir(), 'loopx-plugin-home-'));
+    const env = loopxEnv(home);
+
+    await execFileAsync(process.execPath, [INSTALL_SCRIPT], {
+      cwd: REPO_ROOT,
+      env,
+    });
+
+    const inspection = await verifyInstallState(env);
+    assert.equal(inspection.ok, true);
+    for (const skillName of LOOPX_SKILLS) {
+      const installedSkill = await readFile(join(home, '.agents', 'skills', skillName, 'SKILL.md'), 'utf8');
+      const pluginSkill = await readFile(join(PLUGIN_SKILLS_DIR, skillName, 'SKILL.md'), 'utf8');
+      assert.equal(installedSkill, pluginSkill, skillName);
+      assert.equal(inspection.inspection.skills[skillName].registryRow.installationIdentity, 'loopx');
+      assert.equal(inspection.inspection.skills[skillName].registryRow.distributionChannel, 'plugin');
+      assert.equal(inspection.inspection.skills[skillName].registryRow.sourceUrl, PLUGIN_ROOT);
+      assert.equal(
+        inspection.inspection.skills[skillName].registryRow.provenance.some(
+          (entry) => entry.distributionChannel === 'plugin' && entry.sourceUrl === PLUGIN_ROOT,
+        ),
+        true,
+      );
+    }
+  });
+});

package/plugins/loopx/skills/loopx-autopilot/SKILL.md

@@ -0,0 +1,30 @@
+# LoopX Autopilot
+
+## Purpose
+
+Repo-local bounded composition surface for LoopX. Use it when one owner wants the workflow to run end-to-end through clarify, plan, build, and review with the same stage gates still enforced.
+
+## Composition
+
+`loopx-autopilot` is a wrapper over:
+
+- `loopx-clarify`
+- `loopx-plan`
+- `loopx-build`
+- `loopx-review`
+
+## Decision Boundary
+
+- Use this when the task should stay on the repo-local LoopX path from ambiguity reduction through acceptance.
+- Stop at the first blocked stage. `loopx-autopilot` does not bypass approvals or continue past failed verification.
+
+## Must Not Decide Automatically
+
+- skipping a stage gate because the downstream task looks obvious
+- switching into a `team` lane or any parallel multi-agent dependency
+- treating CLI helpers as the primary product surface
+
+## Notes
+
+- `loopx-autopilot` is intentionally bounded. It documents composition over the four repo-local LoopX stages only.
+- The CLI remains supporting runtime and debug tooling, not the main release surface.

package/plugins/loopx/skills/loopx-build/SKILL.md

@@ -0,0 +1,25 @@
+# LoopX Build
+
+## Purpose
+
+Repo-local execution surface for LoopX. Use it to implement an approved plan and capture fresh verification evidence for the current run.
+
+## Expected Outputs
+
+- execution artifacts for the active LoopX run
+- verification evidence tied to the implementation run
+- stage status that shows readiness or blockers for review
+
+## Decision Boundary
+
+- Use this only after planning is complete and approved.
+- Stop here if execution or verification is incomplete. `loopx-build` can recommend follow-up work, but it does not self-approve review.
+
+## Must Not Decide Automatically
+
+- review approval
+- rollback or completion decisions
+
+## Notes
+
+- `loopx-build` is the active release execution surface. There is no public `team` execution lane in this repo-local skill set.

package/plugins/loopx/skills/loopx-clarify/SKILL.md

@@ -0,0 +1,25 @@
+# LoopX Clarify
+
+## Purpose
+
+Repo-local clarify surface for LoopX. Use it to turn a vague request into an execution-ready spec before planning or build work starts.
+
+## Expected Outputs
+
+- a clarify spec under the LoopX workspace
+- an explicit ambiguity list with unresolved items called out
+- stage status that makes the next action visible
+
+## Decision Boundary
+
+- Use this first when scope, acceptance, constraints, or verification are still unclear.
+- Stop here if unresolved ambiguity remains. `loopx-clarify` does not advance into planning on its own.
+
+## Must Not Decide Automatically
+
+- approval to move from clarify into plan
+- implementation details that were not established in the clarify output
+
+## Notes
+
+- This is a skill-first surface. Any CLI entrypoints are supporting runtime or debug helpers, not the primary product surface.

package/plugins/loopx/skills/loopx-plan/SKILL.md

@@ -0,0 +1,25 @@
+# LoopX Plan
+
+## Purpose
+
+Repo-local planning surface for LoopX. Use it to turn an approved clarify result into a concrete execution package.
+
+## Expected Outputs
+
+- a plan package under the LoopX workspace
+- explicit architecture, execution, and verification guidance
+- stage status that shows whether build is unblocked
+
+## Decision Boundary
+
+- Use this only after clarify has produced a usable spec.
+- Stop here if the plan package is incomplete or still awaiting approval. `loopx-plan` does not start execution on its own.
+
+## Must Not Decide Automatically
+
+- whether to skip straight to implementation without a complete plan
+- whether execution is approved
+
+## Notes
+
+- Keep the output artifact-bound and implementation-grounded. The plan should feed `loopx-build` or `loopx-autopilot`, not invent a separate workflow surface.

package/plugins/loopx/skills/loopx-review/SKILL.md

@@ -0,0 +1,25 @@
+# LoopX Review
+
+## Purpose
+
+Repo-local acceptance surface for LoopX. Use it to evaluate the execution package from `loopx-build` and return an explicit go / no-go result.
+
+## Expected Outputs
+
+- a review artifact tied to the run being evaluated
+- verdict and rationale
+- rollback guidance when execution is incomplete or unstable
+
+## Decision Boundary
+
+- Use this only after build has produced execution and verification evidence for a specific run.
+- Stop here if review evidence is incomplete. `loopx-review` remains an independent gate and does not auto-complete the workflow.
+
+## Must Not Decide Automatically
+
+- final completion without an explicit approval step
+- re-running build work inside the review surface
+
+## Notes
+
+- Review consumes structured outputs from the active LoopX run. It should reject thin or placeholder-only evidence.

package/scripts/install-skills.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import { installBundledSkills, verifyInstallState } from '../src/install-discovery.mjs';
+
+async function main() {
+  const checkOnly = process.argv.includes('--check');
+  const result = checkOnly ? await verifyInstallState(process.env) : await installBundledSkills(process.env);
+  const ok = checkOnly ? result.ok : result.ok !== false;
+  const payload = checkOnly ? result : { ok, installed: result.installed, conflicts: result.conflicts ?? [], inspection: result.inspection };
+  if (!ok) {
+    console.error(JSON.stringify(payload, null, 2));
+    process.exitCode = 1;
+    return;
+  }
+  console.log(JSON.stringify(payload, null, 2));
+}
+
+await main();

package/skills/loopx-autopilot/SKILL.md

@@ -0,0 +1,30 @@
+# LoopX Autopilot
+
+## Purpose
+
+Repo-local bounded composition surface for LoopX. Use it when one owner wants the workflow to run end-to-end through clarify, plan, build, and review with the same stage gates still enforced.
+
+## Composition
+
+`loopx-autopilot` is a wrapper over:
+
+- `loopx-clarify`
+- `loopx-plan`
+- `loopx-build`
+- `loopx-review`
+
+## Decision Boundary
+
+- Use this when the task should stay on the repo-local LoopX path from ambiguity reduction through acceptance.
+- Stop at the first blocked stage. `loopx-autopilot` does not bypass approvals or continue past failed verification.
+
+## Must Not Decide Automatically
+
+- skipping a stage gate because the downstream task looks obvious
+- switching into a `team` lane or any parallel multi-agent dependency
+- treating CLI helpers as the primary product surface
+
+## Notes
+
+- `loopx-autopilot` is intentionally bounded. It documents composition over the four repo-local LoopX stages only.
+- The CLI remains supporting runtime and debug tooling, not the main release surface.

package/skills/loopx-build/SKILL.md

@@ -0,0 +1,25 @@
+# LoopX Build
+
+## Purpose
+
+Repo-local execution surface for LoopX. Use it to implement an approved plan and capture fresh verification evidence for the current run.
+
+## Expected Outputs
+
+- execution artifacts for the active LoopX run
+- verification evidence tied to the implementation run
+- stage status that shows readiness or blockers for review
+
+## Decision Boundary
+
+- Use this only after planning is complete and approved.
+- Stop here if execution or verification is incomplete. `loopx-build` can recommend follow-up work, but it does not self-approve review.
+
+## Must Not Decide Automatically
+
+- review approval
+- rollback or completion decisions
+
+## Notes
+
+- `loopx-build` is the active release execution surface. There is no public `team` execution lane in this repo-local skill set.

package/skills/loopx-clarify/SKILL.md

@@ -0,0 +1,25 @@
+# LoopX Clarify
+
+## Purpose
+
+Repo-local clarify surface for LoopX. Use it to turn a vague request into an execution-ready spec before planning or build work starts.
+
+## Expected Outputs
+
+- a clarify spec under the LoopX workspace
+- an explicit ambiguity list with unresolved items called out
+- stage status that makes the next action visible
+
+## Decision Boundary
+
+- Use this first when scope, acceptance, constraints, or verification are still unclear.
+- Stop here if unresolved ambiguity remains. `loopx-clarify` does not advance into planning on its own.
+
+## Must Not Decide Automatically
+
+- approval to move from clarify into plan
+- implementation details that were not established in the clarify output
+
+## Notes
+
+- This is a skill-first surface. Any CLI entrypoints are supporting runtime or debug helpers, not the primary product surface.

package/skills/loopx-plan/SKILL.md

@@ -0,0 +1,25 @@
+# LoopX Plan
+
+## Purpose
+
+Repo-local planning surface for LoopX. Use it to turn an approved clarify result into a concrete execution package.
+
+## Expected Outputs
+
+- a plan package under the LoopX workspace
+- explicit architecture, execution, and verification guidance
+- stage status that shows whether build is unblocked
+
+## Decision Boundary
+
+- Use this only after clarify has produced a usable spec.
+- Stop here if the plan package is incomplete or still awaiting approval. `loopx-plan` does not start execution on its own.
+
+## Must Not Decide Automatically
+
+- whether to skip straight to implementation without a complete plan
+- whether execution is approved
+
+## Notes
+
+- Keep the output artifact-bound and implementation-grounded. The plan should feed `loopx-build` or `loopx-autopilot`, not invent a separate workflow surface.

package/skills/loopx-review/SKILL.md

@@ -0,0 +1,25 @@
+# LoopX Review
+
+## Purpose
+
+Repo-local acceptance surface for LoopX. Use it to evaluate the execution package from `loopx-build` and return an explicit go / no-go result.
+
+## Expected Outputs
+
+- a review artifact tied to the run being evaluated
+- verdict and rationale
+- rollback guidance when execution is incomplete or unstable
+
+## Decision Boundary
+
+- Use this only after build has produced execution and verification evidence for a specific run.
+- Stop here if review evidence is incomplete. `loopx-review` remains an independent gate and does not auto-complete the workflow.
+
+## Must Not Decide Automatically
+
+- final completion without an explicit approval step
+- re-running build work inside the review surface
+
+## Notes
+
+- Review consumes structured outputs from the active LoopX run. It should reject thin or placeholder-only evidence.