@ai-content-space/loopx 0.1.0 → 0.1.2

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

@@ -0,0 +1,238 @@
+---
+name: plan
+description: Consensus-first loopx planning skill with Planner, Architect, and Critic review.
+argument-hint: "[--interactive] [--deliberate] [--direct <spec-path>] <clarified task or spec path>"
+---
+
+# loopx Plan
+
+<Purpose>
+`plan` is loopx's canonical planning gate. It turns an approved clarify result or execution-ready spec into a reviewed plan package before build or autopilot starts.
+
+By default, `plan` includes the full consensus review loop formerly documented under `ralplan`: Planner -> Architect -> Critic. Planner creates the plan, Architect reviews it, Critic gates it, and the plan iterates until approved or the iteration cap is reached.
+</Purpose>
+
+<Use_When>
+- A clarify spec exists and needs a concrete execution package.
+- The user asks for `plan`, `ralplan`, consensus planning, PRD, test spec, implementation plan, or architecture review.
+- The request is clear enough to plan, but execution should not start before architecture and verification shape are reviewed.
+- The downstream path may be `build`, `autopilot`, or another execution lane, but still needs a stable plan artifact first.
+</Use_When>
+
+<Do_Not_Use_When>
+- Requirements are still vague enough that intent, non-goals, or decision boundaries are unresolved. Use `clarify` first.
+- The user explicitly asks to implement a concrete small change immediately and no planning gate is needed.
+- A current approved plan package already exists and the next action is execution.
+</Do_Not_Use_When>
+
+<Core_Principles>
+- Default planning is consensus-first, not lightweight-by-default.
+- Treat the clarify spec as source of truth; do not re-interview unless the spec is incomplete or contradictory.
+- Keep planning artifact-bound: produce PRD, architecture, development plan, and test plan outputs.
+- Separate planning approval from execution approval.
+- Do not start implementation from `plan`.
+- Prefer a smaller executable plan over a broad plan that cannot be verified.
+- Preserve non-goals, decision boundaries, and residual-risk warnings from clarify.
+</Core_Principles>
+
+<Inputs>
+Accepted inputs:
+
+- an approved loopx clarify workflow slug
+- `.loopx/specs/clarify-*.md`
+- `.omx/specs/deep-interview-*.md`
+- a direct task description when enough context is already present
+- `--direct <spec-path>` to force a specific requirements artifact
+
+If no requirements artifact is provided, derive a task slug and run pre-context intake before planning.
+</Inputs>
+
+<Flags>
+- `--interactive`: ask the user at draft review and final approval boundaries.
+- `--deliberate`: force high-rigor planning. Add pre-mortem and expanded test planning.
+- `--direct <spec-path>`: use the given artifact as the planning source of truth.
+
+`ralplan` is a compatibility alias for this default consensus behavior. It should not maintain a separate planning contract.
+</Flags>
+
+<Pre_Context_Intake>
+Before planning:
+
+1. Derive a task slug.
+2. Reuse the latest relevant `.omx/context/{slug}-*.md` snapshot when available.
+3. If none exists, create `.omx/context/{slug}-{timestamp}.md` with:
+   - task statement
+   - desired outcome
+   - source requirements artifact
+   - known facts / evidence
+   - constraints
+   - non-goals
+   - decision boundaries
+   - unknowns / open questions
+   - likely codebase touchpoints
+4. For brownfield tasks, inspect relevant repo files before finalizing the plan.
+5. If ambiguity is still high, route back to `clarify` instead of inventing missing requirements.
+6. If planning depends on unfamiliar SDKs, external APIs, or version-sensitive framework behavior, use official documentation or a researcher lane before final approval.
+</Pre_Context_Intake>
+
+<Consensus_Workflow>
+## Step 1. Planner Draft
+
+Planner creates the initial plan package and a compact RALPLAN-DR summary:
+
+- Principles: 3-5 guiding constraints
+- Decision Drivers: top 3 forces shaping the plan
+- Viable Options: at least 2 options with bounded pros / cons
+- Rejected Options: explicit invalidation when only one option remains viable
+- Plan Package:
+  - PRD / requirements translation
+  - architecture approach
+  - development plan
+  - test plan
+  - acceptance criteria
+  - risk register
+
+In `--deliberate` mode, also include:
+
+- pre-mortem with 3 plausible failure scenarios
+- expanded test plan covering unit, integration, e2e, and observability where applicable
+
+## Step 2. Draft User Review (`--interactive` only)
+
+If interactive mode is enabled, present the draft plus the DR summary and ask whether to:
+
+- proceed to Architect review
+- request changes
+- reject / stop
+
+Without `--interactive`, proceed automatically to Architect review.
+
+## Step 3. Architect Review
+
+Architect reviews the plan for soundness. This step must finish before Critic starts.
+
+Architect must provide:
+
+- strongest steelman objection to the plan
+- at least one real tradeoff tension
+- architecture risks and mitigations
+- synthesis or recommended revision when the objection is valid
+- deliberate-mode principle-violation checks when applicable
+
+## Step 4. Critic Gate
+
+Critic runs only after Architect review completes.
+
+Critic evaluates:
+
+- principle-option consistency
+- fairness of alternatives
+- clarity of risk mitigation
+- testable acceptance criteria
+- concrete verification steps
+- explicit non-goals and decision boundaries
+- in deliberate mode: pre-mortem and expanded test plan quality
+
+Critic verdicts:
+
+- `APPROVE`
+- `ITERATE`
+- `REJECT`
+
+## Step 5. Closed Re-Review Loop
+
+If Critic returns `ITERATE` or `REJECT`, run a full closed loop:
+
+1. collect Architect + Critic feedback
+2. revise the plan with Planner
+3. return to Architect review
+4. return to Critic gate
+5. repeat until `APPROVE` or 5 iterations
+
+Do not patch only the Critic complaint in isolation if the Architect objection implies a deeper plan change.
+
+## Step 6. Final Plan Package
+
+On approval, write canonical planning artifacts:
+
+- `.loopx/workflows/<slug>/plan.md`
+- `.loopx/workflows/<slug>/architecture.md`
+- `.loopx/workflows/<slug>/development-plan.md`
+- `.loopx/workflows/<slug>/test-plan.md`
+- `.loopx/plans/prd-<slug>.md`
+- `.loopx/plans/test-spec-<slug>.md`
+
+The final plan must include:
+
+- ADR: Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups
+- concrete implementation steps sized to the actual task
+- available execution lanes and recommended lane
+- test and verification commands
+- residual risks and assumptions
+- explicit build/autopilot handoff guidance
+
+## Step 7. Execution Bridge
+
+`plan` stops at an approved plan package.
+
+In `--interactive` mode, ask for the next lane:
+
+- approve for `build`
+- approve for `autopilot`
+- request plan changes
+- stop
+
+Without `--interactive`, report the approved plan and recommended next command, but do not launch execution.
+</Consensus_Workflow>
+
+<Runtime_State_Machine>
+`plan` must keep the planning gate machine-checkable. Runtime state should track:
+
+- `plan_current_iteration`: starts at `1`
+- `plan_max_iterations`: default `5`
+- `plan_consensus_mode`: `true` by default
+- `plan_deliberate_mode`: `true|false`
+- `plan_principles_resolved`: `true` after principles are explicit
+- `plan_options_reviewed`: `true` after alternatives are fairly compared
+- `plan_architect_review_status`: `not-started|complete|changes-requested`
+- `plan_critic_verdict`: `none|approve|iterate|reject`
+- `plan_package_status`: `missing|partial|complete`
+- `plan_acceptance_criteria_testable`: `true|false`
+- `plan_verification_steps_resolved`: `true|false`
+- `requested_transition`: remains explicit before build/autopilot
+
+The plan gate is blocked until:
+
+- plan package artifacts exist
+- Architect review is complete
+- Critic verdict is `approve`
+- acceptance criteria are testable
+- verification steps are concrete
+- user approval exists for any execution transition
+</Runtime_State_Machine>
+
+<Must_Not_Decide_Automatically>
+- Do not skip Architect review.
+- Do not run Architect and Critic in parallel; Critic depends on Architect.
+- Do not launch build/autopilot without explicit approval.
+- Do not widen scope beyond clarify non-goals because a broader redesign seems cleaner.
+- Do not erase residual-risk warnings inherited from clarify.
+- Do not treat a plan as approved when Critic returns `ITERATE` or `REJECT`.
+</Must_Not_Decide_Automatically>
+
+<Output_Contract>
+Primary outputs:
+
+- approved plan package under `.loopx/workflows/<slug>/`
+- canonical PRD and test spec under `.loopx/plans/`
+- consensus review summary with Planner / Architect / Critic evidence
+- next-step recommendation
+
+Status output must clearly state:
+
+- current iteration
+- Architect review status
+- Critic verdict
+- missing plan gates, if any
+- whether execution is approved
+</Output_Contract>

package/plugins/loopx/skills/{loopx-review → review}/SKILL.md

@@ -1,8 +1,13 @@
-# LoopX Review
+---
+name: review
+description: Repo-local acceptance surface for loopx.
+---
+
+# 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.
+Repo-local acceptance surface for loopx. Use it to evaluate the execution package from `build` and return an explicit go / no-go result.
 
 ## Expected Outputs
 
@@ -13,7 +18,7 @@ Repo-local acceptance surface for LoopX. Use it to evaluate the execution packag
 ## 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.
+- Stop here if review evidence is incomplete. `review` remains an independent gate and does not auto-complete the workflow.
 
 ## Must Not Decide Automatically
 
@@ -22,4 +27,4 @@ Repo-local acceptance surface for LoopX. Use it to evaluate the execution packag
 
 ## Notes
 
-- Review consumes structured outputs from the active LoopX run. It should reject thin or placeholder-only evidence.
+- Review consumes structured outputs from the active loopx run. It should reject thin or placeholder-only evidence.

package/skills/ai-slop-cleaner/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: ai-slop-cleaner
+description: Run an anti-slop cleanup/refactor/deslop workflow
+---
+
+# AI Slop Cleaner Skill
+
+Reduce AI-generated slop with a regression-tests-first, smell-by-smell cleanup workflow that preserves behavior and raises signal quality.
+
+## When to Use
+
+Use this skill when:
+- A code path works but feels bloated, noisy, repetitive, or over-abstracted
+- A user asks to “cleanup”, “refactor”, or “deslop” AI-generated output
+- Follow-up implementation left duplicate code, dead code, weak boundaries, missing tests, or unnecessary wrapper layers
+- You need a disciplined cleanup workflow without broad rewrites
+
+## GPT-5.4 Guidance Alignment
+
+- Keep outputs concise and evidence-dense unless risk or the user requests more detail.
+- Treat newer user instructions as local workflow updates without discarding earlier non-conflicting constraints.
+- Keep using inspection, tests, diagnostics, and verification until the cleanup is grounded.
+- Proceed automatically through clear, reversible cleanup steps; ask only when a choice materially changes scope or behavior.
+
+## Scoped File Lists and Ralph Workflow
+
+- This skill can accept a **file list scope** instead of a whole feature area.
+- When the caller provides a changed-files list (for example, Ralph session-owned edits), keep the cleanup strictly bounded to those files.
+- In the **Ralph workflow**, the mandatory deslop pass should run this skill on Ralph's changed files only, in standard mode unless the caller explicitly requests otherwise.
+
+## Procedure
+
+1. **Lock behavior with regression tests first**
+   - Identify the behavior that must not change
+   - Add or run targeted regression tests before editing cleanup candidates
+   - If behavior is currently untested, create the narrowest test coverage needed first
+
+2. **Create a cleanup plan before code**
+   - List the specific smells to remove
+   - Bound the pass to the requested files/scope
+   - If a file list scope is provided, keep the pass restricted to that changed-files list
+   - Order fixes from safest/highest-signal to riskiest
+   - Do not start coding until the cleanup plan is explicit
+
+3. **Categorize issues before editing**
+   - **Duplication** — repeated logic, copy-paste branches, redundant helpers
+   - **Dead code** — unused code, unreachable branches, stale flags, debug leftovers
+   - **Needless abstraction** — pass-through wrappers, speculative indirection, single-use helper layers
+   - **Boundary violations** — hidden coupling, leaky responsibilities, wrong-layer imports or side effects
+   - **Missing tests** — behavior not locked, weak regression coverage, gaps around edge cases
+
+4. **Execute passes one smell at a time**
+   - **Pass 1: Dead code deletion**
+   - **Pass 2: Duplicate removal**
+   - **Pass 3: Naming/error handling cleanup**
+   - **Pass 4: Test reinforcement**
+   - Re-run targeted verification after each pass
+   - Avoid bundling unrelated refactors into the same edit set
+
+5. **Run quality gates**
+   - Regression tests stay green
+   - Lint passes
+   - Typecheck passes
+   - Relevant unit/integration tests pass
+   - Static/security scan passes when available
+   - Diff stays minimal and scoped
+   - No new abstractions or dependencies unless explicitly required
+
+6. **Finish with an evidence-dense report**
+   - Changed files
+   - Simplifications made
+   - Tests/diagnostics/build checks run
+   - Remaining risks
+   - Residual follow-ups or consciously deferred cleanup
+
+## Output Format
+
+```text
+AI SLOP CLEANUP REPORT
+======================
+
+Scope: [files or feature area]
+Behavior Lock: [targeted regression tests added/run]
+Cleanup Plan: [bounded smells and order]
+
+Passes Completed:
+1. Pass 1: Dead code deletion - [concise fix]
+2. Pass 2: Duplicate removal - [concise fix]
+3. Pass 3: Naming/error handling cleanup - [concise fix]
+4. Pass 4: Test reinforcement - [concise fix]
+
+Quality Gates:
+- Regression tests: PASS/FAIL
+- Lint: PASS/FAIL
+- Typecheck: PASS/FAIL
+- Tests: PASS/FAIL
+- Static/security scan: PASS/FAIL or N/A
+
+Changed Files:
+- [path] - [simplification]
+
+Remaining Risks:
+- [none or short deferred item]
+```
+
+## Scenario Examples
+
+**Good:** The user says `continue` after tests already lock behavior and the next smell pass is clear. Continue with the next bounded cleanup pass.
+
+**Good:** The user narrows the scope to a specific file after planning. Keep the regression-tests-first workflow, but apply the new scope locally.
+
+**Bad:** Start rewriting architecture before protecting behavior with tests.
+
+**Bad:** Collapse multiple smell categories into one large refactor with no intermediate verification.

package/skills/autopilot/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: autopilot
+description: Richer internal-phase loopx autonomous orchestration over the public clarify/plan/build/review flow.
+argument-hint: "<workflow slug>"
+---
+
+# loopx Autopilot
+
+<Purpose>
+`autopilot` is loopx's autonomous orchestration surface. It upgrades the current bounded composition model by adding richer internal phases while keeping loopx's public stage model authoritative.
+
+Externally, the user still reasons about:
+
+- `clarify`
+- `plan`
+- `build`
+- `review`
+
+Internally, `autopilot` may orchestrate richer phases such as expansion, planning, execution, QA, and validation.
+</Purpose>
+
+<Use_When>
+- One owner wants loopx to run end-to-end with internal autonomous orchestration.
+- A clarified or workflow-local spec already exists, or the workflow is ready to begin from loopx stages.
+- The task benefits from richer internal planning/execution/QA/validation behavior without exposing a more complex public stage surface.
+</Use_When>
+
+<Do_Not_Use_When>
+- The user wants manual control over each stage gate.
+- The task should stop after planning or execution rather than run end-to-end.
+- Requirements are too ambiguous for bounded autonomous orchestration.
+</Do_Not_Use_When>
+
+<Core_Principles>
+- loopx public stage truth remains authoritative.
+- Richer internal phases are allowed, but they stay internal.
+- Internal stage approvals may be auto-consumed and must be recorded as control events.
+- Canonical loopx artifacts remain the source of truth; `run.json` is an orchestration ledger.
+- Reuse strengthened loopx stage runtimes rather than re-implementing contradictory truths.
+</Core_Principles>
+
+<Internal_Phases>
+Suggested internal phase model:
+
+- `expansion`
+- `planning`
+- `execution`
+- `qa`
+- `validation`
+
+Phase-to-stage alignment:
+
+- `expansion` -> clarified-spec reuse or clarify preparation
+- `planning` -> loopx `plan`
+- `execution` + `qa` -> loopx `build`
+- `validation` -> pre-review validation plus loopx `review`
+</Internal_Phases>
+
+<Control_Plane>
+- one autopilot invocation authorizes one bounded autopilot run
+- autopilot may internally consume stage approvals for:
+  - `clarify -> plan`
+  - `plan -> build`
+  - `build -> review`
+  - `review -> done`
+- these decisions must be recorded as internal control events
+</Control_Plane>
+
+<Artifact_Contract>
+Canonical stage artifacts remain authoritative:
+
+- clarify spec artifacts
+- `.loopx/plans/prd-<slug>.md`
+- `.loopx/plans/test-spec-<slug>.md`
+- canonical build `execution-record.md`
+- canonical review `review-report.md`
+
+Autopilot also writes an orchestration ledger:
+
+- `.loopx/autopilot/<slug>/run.json`
+
+`run.json` may include internal phase progression, blockers, and control events, but it must not replace canonical stage artifacts as the source of truth.
+</Artifact_Contract>
+
+<Must_Not_Decide_Automatically>
+- do not create a new public stage family
+- do not bypass loopx canonical artifacts
+- do not fork a second workflow truth that contradicts loopx stages
+- do not literally port the parent autopilot where it conflicts with loopx runtime contracts
+</Must_Not_Decide_Automatically>

package/skills/autoresearch/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: autoresearch
+description: Stateful validator-gated research loop with native-hook persistence
+---
+
+# Autoresearch
+
+Autoresearch is the skill-first replacement for the deprecated `omx autoresearch` command.
+It keeps the useful measured-research loop, but it now runs as a native-hook stateful workflow instead of a direct CLI or tmux launch surface.
+
+## Use when
+- You want a Ralph-ish persistent research loop
+- The task should keep nudging until explicit validation evidence exists
+- You want init-time choice between script validation and prompt+architect validation
+
+## Do not use when
+- You want the old `omx autoresearch` command surface (hard-deprecated)
+- You want detached tmux or split-pane launch parity
+- You have not decided the validation regime yet
+
+## Core contract
+1. **Init chooses validation mode.** Pick exactly one:
+   - `mission-validator-script`
+   - `prompt-architect-artifact`
+2. **Persist mode state** in `.omx/state/.../autoresearch-state.json` including:
+   - `validation_mode`
+   - `completion_artifact_path`
+   - `mission_validator_command` **or** `validator_prompt`
+   - optional `output_artifact_path`
+3. **Completion is artifact-gated.** The loop does not stop because the model says “done”, because a stop hook fired once, or because several turns were no-ops.
+4. **Direct CLI launch is gone.** Use `$deep-interview --autoresearch` for intake and `$autoresearch` for execution.
+
+## Completion artifact contract
+
+### `mission-validator-script`
+The completion artifact must exist and record a passing validator result, for example:
+
+```json
+{
+  "status": "passed",
+  "passed": true,
+  "summary": "metric improved beyond baseline"
+}
+```
+
+### `prompt-architect-artifact`
+The completion artifact must include both an architect approval verdict and an output artifact path, for example:
+
+```json
+{
+  "validator_prompt": "Review the research output against the mission.",
+  "architect_review": { "verdict": "approved" },
+  "output_artifact_path": ".omx/specs/autoresearch-demo/report.md"
+}
+```
+
+## Recommended flow
+1. Run `$deep-interview --autoresearch` to clarify mission + evaluator.
+2. Materialize `.omx/specs/autoresearch-{slug}/mission.md`, `sandbox.md`, and `result.json`.
+3. Start `$autoresearch` with the chosen validation mode stored in mode state.
+4. Let stop-hook / auto-nudge continue until the completion artifact satisfies the chosen validation mode.
+5. Finish only after the validator artifact is complete.
+
+## Migration note
+- `omx autoresearch` is hard-deprecated.
+- No direct CLI launch.
+- No tmux split-pane launch.
+- No noop-count completion gate.

package/skills/build/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: build
+description: Ralph-style loopx execution runtime under the public build stage.
+argument-hint: "[--no-deslop] <approved workflow slug>"
+---
+
+# loopx Build
+
+<Purpose>
+`build` is loopx's canonical execution lane. It executes an approved plan with Ralph-style rigor while keeping the public loopx stage surface unchanged.
+
+By default, `build` is not a one-shot draft writer. It is a persistence loop with internal parallel lanes, fresh verification, architect gating, deslop, and regression re-verification before `review` can start.
+</Purpose>
+
+<Use_When>
+- `plan -> build` has already been explicitly approved.
+- Canonical plan artifacts already exist and execution should now proceed.
+- The task needs execution persistence, verification evidence, and explicit pre-review quality gates.
+</Use_When>
+
+<Do_Not_Use_When>
+- Requirements or planning are still incomplete.
+- The user wants to skip execution and only review or inspect the plan.
+- A valid build run is already review-ready and the next action is `review`.
+</Do_Not_Use_When>
+
+<Core_Principles>
+- Public surface stays `build`; internal strength can still match Ralph-style execution.
+- Execution may parallelize internally without exposing a public `team` stage.
+- `build` does not replace `review`.
+- `execution-record.md` remains the sole canonical execution and verification artifact.
+- Fresh evidence is required before review handoff.
+- Deslop and regression re-verification are part of the default build path.
+</Core_Principles>
+
+<Preconditions>
+`build` starts only when all of the following are true:
+
+- approved `plan -> build` transition exists
+- `.loopx/plans/prd-<slug>.md` exists
+- `.loopx/plans/test-spec-<slug>.md` exists
+- workflow-local planning artifacts required by the execution lane exist
+</Preconditions>
+
+<Execution_Model>
+`build` should behave like a Ralph-style execution runtime:
+
+1. Initialize or resume build iteration state.
+2. Run internal execution / evidence / verification lanes in parallel.
+3. Aggregate lane results into canonical `execution-record.md`.
+4. Run fresh verification and read actual output.
+5. Run architect verification as a hard pre-review gate.
+6. Run deslop on build-owned changes.
+7. Re-run regression verification after deslop.
+8. Stop only when review handoff gates are satisfied or a real blocker remains.
+
+`build` may persist support artifacts for runtime inspection, but they must not replace `execution-record.md`.
+</Execution_Model>
+
+<Runtime_State_Machine>
+`build` should track at minimum:
+
+- `build_run_id`
+- `build_current_iteration`
+- `build_max_iterations` (default `10`)
+- `build_parallel_mode`
+- `build_lane_statuses`
+- `build_verification_status`
+- `build_architect_verification_status`
+- `build_deslop_status`
+- `build_regression_status`
+- `build_blockers`
+- `build_progress_artifact_paths`
+- `build_support_evidence_paths`
+- `execution_record_status`
+
+`build -> review` is blocked until:
+
+- all internal lanes are complete
+- fresh verification passes
+- architect verification is approved
+- deslop is complete, unless explicitly skipped
+- post-deslop regression passes
+- `execution-record.md` is complete
+</Runtime_State_Machine>
+
+<Artifact_Contract>
+Canonical artifact:
+
+- `execution-record.md`
+
+Support artifacts may exist for:
+
+- iteration progress
+- lane evidence summaries
+- architect gate summaries
+- deslop summaries
+- regression summaries
+
+These support artifacts are runtime aids only. They must not become new canonical review inputs.
+</Artifact_Contract>
+
+<Review_Boundary>
+- build-internal architect verification is an execution-quality gate
+- review remains the final independent stage
+- review continues to own provenance checks, evidence completeness checks, completion/rollback decisions, and code-review
+</Review_Boundary>
+
+<Flags>
+- `--no-deslop`: skip the deslop pass and the post-deslop regression loop, while still requiring the latest successful pre-deslop verification evidence
+</Flags>
+
+<Must_Not_Decide_Automatically>
+- do not self-approve review
+- do not mark the workflow complete
+- do not replace `execution-record.md` with support artifacts
+- do not widen execution into public `team`, `ultrawork`, or `ralph` command surfaces
+</Must_Not_Decide_Automatically>