@ai-content-space/loopx 0.1.2 → 0.1.4

package/README.md

@@ -1,104 +1,449 @@
-# loopx
+<p align="center">
+  <img src="./assets/logo.svg" alt="loopx fox logo" width="128" height="128">
+</p>
 
-`loopx` is a skill-first workflow product for Codex. It supports two first-class distribution shells:
+<h1 align="center">loopx</h1>
 
-- npm/global install
-- Codex plugin install
+<p align="center">
+  Skill-first workflow runtime for Codex.
+</p>
 
-Both shells converge on one shared loopx core and one visible loopx skill set.
+[中文文档](./README.zh-CN.md)
 
-## Release Contract
+`loopx` is a skill-first workflow toolkit for Codex. It organizes clarification, consensus planning, persistent execution, and independent review into a local, auditable workflow exposed through both a CLI and Codex Skills.
 
-The active loopx release flow is:
+Current public flow:
 
-`clarify -> plan -> build -> review`
+```text
+clarify -> plan -> build -> review -> approve review->done -> archive
+```
+
+`done` is a runtime completion state reached by `loopx approve <slug> --from review --to done`, not a separate Codex skill.
 
-Bundled skill surfaces:
+`autopilot` is the end-to-end orchestration entrypoint. Internally it reuses the public flow instead of creating a second source of workflow truth.
 
-- `clarify`
-- `plan`
-- `build`
-- `review`
-- `autopilot`
+## Features
 
-There is no public `team` surface in this release.
+- Installs and exposes eleven bundled loopx Codex skills: workflow skills `clarify`, `plan`, `build`, `review`, `archive`, and `autopilot`; quality support skills `debug`, `tdd`, and `verify`; and Go support skills `go-style` and `kratos`.
+- Supports npm global install and Codex plugin install through the same install/discovery core.
+- Installs a managed Codex workflow hook that surfaces loopx workflow state and safe next-action hints inside Codex.
+- Stores runtime state and stage artifacts locally under `.loopx/` for auditability, recovery, and migration.
+- Stores clarify intake snapshots under `.loopx/intake/` so `.loopx/specs/` stays reserved for long-lived domain specs.
+- Runs `plan` with a Planner -> Architect -> Critic consensus loop by default.
+- Writes OpenSpec-inspired change artifacts during `plan`: proposal, spec delta, design, vertical slices, tasks, and an artifact dependency graph.
+- Provides per-repo agent context under `.loopx/agents/` and `.loopx/context/domain.md`, consumed by build/review context manifests.
+- Runs `build` with execution records, verification evidence, architect validation, deslop cleanup, and regression re-verification.
+- Keeps `review` as an independent acceptance surface with code review plus an internal architecture-smell lane.
+- Supports `archive` to sync approved change deltas into long-lived `.loopx/specs/` source-of-truth files and emit ADR candidates.
 
-## Product Positioning
+## Installation
 
-- 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/`
+### npm Global Install
 
-## Runtime Namespace
+```bash
+npm install -g @ai-content-space/loopx
+```
 
-loopx user-facing runtime state is stored under:
+Installation automatically runs:
+
+```bash
+node scripts/install-skills.mjs
+```
+
+The script materializes loopx-owned skills under:
 
 ```text
-.loopx/
+~/.agents/skills/
+```
+
+It also installs the loopx-managed Codex workflow hook at:
+
+```text
+~/.codex/hooks/codex-workflow-hook.mjs
+```
+
+and updates:
+
+```text
+~/.agents/.skill-lock.json
+```
+
+### Codex Plugin Install
+
+The plugin shell lives at:
+
+```text
+plugins/loopx/
+```
+
+Plugin install script:
+
+```bash
+node plugins/loopx/scripts/plugin-install.mjs
+```
+
+npm and plugin installs converge on the same `installationIdentity=loopx`, so Codex should expose one loopx skill set rather than duplicates.
+
+## Quick Start
+
+Initialize a workflow:
+
+```bash
+loopx init --slug my-task
+```
+
+Run clarification:
+
+```bash
+loopx clarify my-task
+```
+
+Approve and run planning:
+
+```bash
+loopx approve my-task --from clarify --to plan
+loopx plan my-task
+```
+
+Approve and run execution:
+
+```bash
+loopx approve my-task --from plan --to build
+loopx build my-task
+```
+
+Approve and run review:
+
+```bash
+loopx approve my-task --from build --to review
+loopx review my-task
+```
+
+Complete an approved review:
+
+```bash
+loopx approve my-task --from review --to done
+```
+
+Archive accepted behavior into long-lived specs:
+
+```text
+$archive my-task
 ```
 
-Key subtrees:
+Check status:
 
-- `.loopx/specs/`
-- `.loopx/plans/`
-- `.loopx/workflows/<slug>/`
-- `.loopx/autopilot/<slug>/`
+```bash
+loopx status my-task
+loopx status my-task --json
+```
 
-The `.omx/` tree remains orchestration/planning metadata and is not part of the loopx runtime rename.
+Render derived HTML reading views:
 
-## CLI Surface
+```bash
+loopx render my-task
+```
+
+You can also create a planning workflow directly from an existing spec:
+
+```bash
+loopx plan --direct ./path/to/spec.md
+```
 
-Primary runtime/debug commands:
+## CLI Commands
 
 ```bash
 loopx init [--slug <slug>]
-loopx clarify <slug>
+loopx clarify <slug> [--standard|--deep]
 loopx approve <slug> --from <stage> --to <stage>
-loopx plan <slug>
-loopx build <slug>
+loopx plan [slug] [--direct <spec-path>] [--interactive] [--deliberate]
+loopx build <slug> [--no-deslop]
+loopx build --from-review <review-report-path> [--no-deslop]
 loopx review <slug> [--reviewer <name>]
+loopx archive <slug>
 loopx autopilot <slug> [--reviewer <name>]
+loopx render [slug|--all]
 loopx status [slug] [--json]
+loopx setup-context
 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.
+The CLI is primarily for runtime, debugging, status inspection, and maintenance. The normal Codex-facing product surface is the bundled skill set, for example `$clarify`, `$plan`, `$build`, `$review`, `$archive`, `$autopilot`, `$debug`, `$tdd`, `$verify`, `$go-style`, and `$kratos`.
+
+`loopx status` remains a CLI/runtime diagnostic command rather than a Codex skill. `loopx render` generates human-readable HTML views from existing runtime artifacts; without a slug it renders every non-legacy workflow plus the workspace index. Markdown and JSON remain the canonical machine-readable and editable sources.
+
+## Skills
+
+### clarify
+
+`clarify` turns an ambiguous request into an execution-ready spec. It tracks ambiguity score, non-goals, decision boundaries, and pressure-pass completion. It only recommends handoff to `plan` after the runtime gates are satisfied.
+
+Profiles:
+
+- `--standard`: target ambiguity score `<= 0.20`, up to `15` rounds.
+- `--deep`: target ambiguity score `<= 0.10`, up to `25` rounds.
+
+### plan
+
+`plan` turns an approved clarify spec, or a directly supplied spec, into a reviewed plan package. By default it runs the Planner, Architect, and Critic review loop until approval or the iteration cap is reached.
+
+Main artifacts:
+
+- `.loopx/plans/prd-<slug>.md`
+- `.loopx/plans/test-spec-<slug>.md`
+- `.loopx/changes/active/<change-id>/proposal.md`
+- `.loopx/changes/active/<change-id>/spec-delta.md`
+- `.loopx/changes/active/<change-id>/design.md`
+- `.loopx/changes/active/<change-id>/tasks.md`
+- `.loopx/changes/active/<change-id>/slices.json`
+- `.loopx/changes/active/<change-id>/artifact-graph.json`
+- `.loopx/workflows/<slug>/plan.md`
+- `.loopx/workflows/<slug>/architecture.md`
+- `.loopx/workflows/<slug>/development-plan.md`
+- `.loopx/workflows/<slug>/test-plan.md`
+
+`spec-delta.md` uses requirement deltas: `## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`, and `## RENAMED Requirements`. ADDED and MODIFIED entries are full `### Requirement:` blocks with SHALL/MUST language and `#### Scenario:` examples, so archive can merge them into the current long-lived spec state.
+
+### build
+
+`build` executes an approved plan and records changes, evidence, and limitations in the canonical artifact:
+
+```text
+.loopx/workflows/<slug>/execution-record.md
+```
+
+Deslop cleanup is enabled by default. To skip it explicitly:
+
+```bash
+loopx build <slug> --no-deslop
+```
+
+When review requests implementation changes, the normal Codex-facing handoff uses the review artifact as the direct rework contract:
+
+```text
+$build --from-review .loopx/workflows/<slug>/review-report.md
+```
+
+The approved PRD, test spec, previous execution record, and workflow-local plan package remain supporting context.
+
+### review
+
+`review` consumes the build `execution-record.md`, runs independent acceptance, code review, and a lightweight architecture-smell lane, and generates:
+
+```text
+.loopx/workflows/<slug>/review-report.md
+```
+
+The user-facing review result is expected to be written in Chinese.
+
+If review approves the run, the workflow still requires an explicit `review -> done` approval. If review requests implementation changes, run `$build --from-review .loopx/workflows/<slug>/review-report.md`. Plan and clarify rollbacks still use `$plan <slug>` or `$clarify <slug>` when the review finding says the plan or requirements are wrong.
+
+The architecture-smell lane is part of review; it does not add a new stage. It records findings under `review-support/architecture-smell.json` and only blocks when module seams, testability, domain vocabulary, or plan architecture assumptions are materially wrong.
+
+### archive
+
+`archive` consumes a completed workflow and syncs the approved `.loopx/changes/active/<change-id>/spec-delta.md` into long-lived domain specs under `.loopx/specs/`. The change folder is moved to:
+
+```text
+.loopx/changes/archive/<change-id>/
+```
+
+Archive also writes an advisory ADR candidate under `.loopx/decisions/adr-candidates/<change-id>.md`. It is not promoted to `docs/adr/` automatically.
+
+Archive applies requirement deltas semantically instead of appending per-change history blocks. ADDED creates requirements, MODIFIED replaces a full existing requirement block, REMOVED deletes a requirement, and RENAMED changes the requirement title while preserving its body.
+
+### autopilot
+
+`autopilot` is the end-to-end orchestration entrypoint. It may run internal phases such as expansion, planning, execution, QA, and validation, but canonical artifacts still come from the public `clarify -> plan -> build -> review` flow.
+
+The orchestration ledger is written to:
+
+```text
+.loopx/autopilot/<slug>/run.json
+```
+
+### debug
+
+`debug` is a quality support skill for bugs, failures, regressions, and unexpected behavior. It requires root-cause investigation before proposing fixes, then moves through pattern analysis, hypothesis testing, and implementation.
+
+### tdd
+
+`tdd` is a quality support skill for feature work and bug fixes. It requires writing a failing test first, confirming the failure is meaningful, then implementing the smallest change needed to pass.
+
+### verify
+
+`verify` is a quality support skill for final claims. It requires fresh verification evidence before saying work is complete, fixed, passing, ready to commit, or ready for review.
+
+### go-style
+
+`go-style` is a Go language support skill. It guides `.go` edits toward idiomatic structure, local project conventions, clear error handling, small interfaces, table-driven tests, and `gofmt`/Go verification.
+
+### kratos
+
+`kratos` is a Go-Kratos framework support skill. It applies when a project uses Kratos signals such as `buf.yaml`, proto APIs, `internal/service`, `internal/biz`, `internal/data`, or `github.com/go-kratos/kratos/v2`, and includes focused references for proto design, layered architecture, config, middleware, auth, HTTP customization, and troubleshooting.
+
+## Runtime Layout
+
+loopx writes runtime state under `.loopx/` in the current project:
+
+```text
+.loopx/
+  README.md
+  config.json
+  intake/
+    clarify-<slug>-<timestamp>.md
+  views/
+    index.html
+  specs/
+    <domain>/
+      spec.md
+  changes/
+    active/
+      <change-id>/
+        proposal.md
+        spec-delta.md
+        design.md
+        tasks.md
+        slices.json
+        artifact-graph.json
+    archive/
+      <change-id>/
+  decisions/
+    adr-candidates/
+  plans/
+  agents/
+    issue-tracker.md
+    domain.md
+    triage-labels.md
+  context/
+    domain.md
+  workflows/
+    <slug>/
+      state.json
+      spec.md
+      plan.md
+      architecture.md
+      development-plan.md
+      test-plan.md
+      execution-record.md
+      review-report.md
+      view/
+        index.html
+        intake.html
+        plan.html
+        build.html
+        review.html
+      plan-reviews/
+      build-support/
+  autopilot/
+    <slug>/
+      run.json
+```
+
+`intake` contains immutable clarify snapshots for a specific request. `workflows` contains the active runtime working set. `changes` contains the proposed change delta for the current request. `specs` contains accepted long-lived behavior after archive.
+
+`views/` and `workflows/<slug>/view/` are derived HTML reading views generated by `loopx render`. They are for human review only and are safe to regenerate; agents and tooling should continue to read and update the Markdown and JSON artifacts.
+
+### Document Boundaries
+
+Documents users normally need to watch:
+
+- `README.md` / `README.zh-CN.md`: product usage, commands, and runtime layout.
+- `.loopx/workflows/<slug>/spec.md`: the current requirement working copy.
+- `.loopx/workflows/<slug>/plan.md`, `architecture.md`, `development-plan.md`, and `test-plan.md`: the current task's plan, architecture, execution, and verification contract.
+- `.loopx/workflows/<slug>/execution-record.md` and `review-report.md`: execution evidence and review result.
+- `.loopx/views/index.html` and `.loopx/workflows/<slug>/view/index.html`: reading entrypoints generated by `loopx render`.
+
+Documents users may read and modify as workflow fact sources:
+
+- `.loopx/workflows/<slug>/*.md`: editable working-copy artifacts for the active workflow; changes still need to pass the relevant stage gates.
+- `.loopx/context/domain.md` and `.loopx/agents/*.md`: project context, domain vocabulary, and agent collaboration guidance.
+- `.loopx/changes/active/<change-id>/*.md`: plan-generated change proposal, design, tasks, and spec delta; edits should be followed by plan/build/review validation.
+- `.loopx/specs/<domain>/spec.md`: long-lived archived behavior specs; normally synced by `archive`, and manual edits should stay consistent with later change deltas.
+
+Documents and data the tools depend on, or generate as derived evidence:
+
+- `.loopx/workflows/<slug>/state.json`, `build-context.jsonl`, and `review-context.jsonl`: runtime state and context manifests; tools depend on these and manual edits are discouraged.
+- `.loopx/workflows/<slug>/plan-reviews/`, `build-support/`, and `review-support/`: stage evidence and internal review outputs for diagnostics and review.
+- `.loopx/intake/clarify-*.md`: immutable clarify snapshots for audit and traceability; do not treat them as long-lived specs.
+- `.loopx/changes/active/<change-id>/slices.json` and `artifact-graph.json`: structured planning data consumed by build/review/archive.
+- `.loopx/autopilot/<slug>/run.json` and `.loopx/build-active.json`: orchestration and stop-hook runtime state.
+- `.loopx/views/` and `.loopx/workflows/<slug>/view/`: derived HTML views; they can be deleted and regenerated with `loopx render`, and should not be edited as fact sources.
+
+## Diagnostics and Repair
+
+Inspect runtime and skill installation state:
+
+```bash
+loopx doctor
+```
+
+Repair loopx-owned skill installation:
+
+```bash
+loopx repair-install
+```
+
+Check skill discovery state only:
 
-## Install and Discovery
+```bash
+node scripts/install-skills.mjs --check
+```
 
-loopx supports two install paths that both reuse the same shared install/discovery core:
+## Codex Workflow Hook
 
-- 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`
+`install-skills.mjs` and the Codex plugin installer automatically install `scripts/codex-workflow-hook.mjs` to:
 
-Bootstrap behavior:
+```text
+~/.codex/hooks/codex-workflow-hook.mjs
+```
+
+The hook reads the nearest `.loopx/workflows/<slug>/state.json` and emits advisory context for the active workflow: current stage, blockers, readiness, authorization, evidence, and the next safe loopx action. It is advisory only; runtime gates remain authoritative.
 
-- 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`
+Set `LOOPX_HOOKS=0` to disable the workflow hook output.
 
-Discovery is valid only when both are true:
+## Codex Stop Hook
+
+loopx includes a Codex stop-hook helper that prevents an active build from stopping before review handoff readiness:
+
+```bash
+node scripts/codex-stop-hook.mjs
+```
+
+During `loopx build`, runtime state is written to:
+
+```text
+.loopx/build-active.json
+```
 
-- the installed loopx skill directory exists
-- the matching loopx-owned registry row exists
+If that state says build is still `starting`, `executing`, `verifying`, or `fixing`, the hook returns `allow: false` and a continuation message. Once build is `review-ready`, blocked by a real blocker, failed, cancelled, or inactive, the hook allows the stop.
 
-If both npm and plugin installs are present, Codex should still expose one loopx skill set rather than duplicates.
+## Environment Variables
 
-## Legacy Migration
+Install and discovery logic supports these environment variables:
 
-- 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`
+- `LOOPX_HOME`: override the default home directory.
+- `LOOPX_AGENTS_ROOT`: override the `.agents` root.
+- `LOOPX_SKILLS_ROOT`: override the installed skills directory.
+- `LOOPX_SKILL_LOCK_PATH`: override the skill lock path.
+- `LOOPX_PROJECT_ROOT`: override the loopx project root.
+- `LOOPX_SKILL_SOURCE_ROOT`: override the skill source directory.
+- `LOOPX_DISTRIBUTION_CHANNEL`: set the install channel, default `npm`.
+- `LOOPX_INSTALLATION_IDENTITY`: set the install identity, default `loopx`.
+- `LOOPX_SOURCE_URL`: set the install source.
+- `LOOPX_HOOKS`: set to `0` to disable workflow hook output.
 
-## Verification
+## Development
+
+Run tests:
+
+```bash
+npm test
+```
+
+Useful verification commands:
 
 ```bash
 node --test test/*.test.mjs
@@ -108,3 +453,23 @@ node src/cli.mjs --help
 node src/cli.mjs doctor
 node src/cli.mjs status --json
 ```
+
+## Published Files
+
+`package.json` publishes:
+
+- `README.md`
+- `README.zh-CN.md`
+- `package.json`
+- `scripts/install-skills.mjs`
+- `scripts/codex-stop-hook.mjs`
+- `scripts/codex-workflow-hook.mjs`
+- `assets/logo.svg`
+- `src/`
+- `skills/`, including public loopx skills plus compatibility/internal skill sources shipped with the package
+- `templates/`
+- `plugins/loopx/`
+
+## Version
+
+Current npm package version: `0.1.4`.