@ai-content-space/loopx 0.1.10 → 0.2.1

package/docs/loopx/design/loopx-skill-suite-v1-design.md

@@ -0,0 +1,80 @@
+# loopx Skill Suite v1 Design
+
+## Context
+
+loopx is moving from a CLI-runtime-first workflow into a skill-first suite for agentic coding assistants. Codex and Claude are supported targets. The CLI remains as installer, governance, diagnostics, rendering, and runtime maintenance.
+
+## Decision
+
+The v1 product surface is the installed and governed bundled skill suite:
+
+- `clarify`
+- `spec`
+- `plan`
+- `subagent-exec`
+- `exec`
+- `review`
+- `fix-review`
+- `finish`
+- `refactor-plan`
+- `tdd`
+- `debug`
+- `verify`
+- `go-style`
+- `kratos`
+
+Runtime-only skills are not installed as Codex or Claude skills in v1.
+
+The repository may retain auxiliary or compatibility skill source directories for development history or adjacent workflows. They are not part of the v1 product surface unless they are listed in the bundled install set and mirrored into the plugin skill set.
+
+## Workflow
+
+Recommended flow:
+
+```text
+clarify -> spec? -> plan -> subagent-exec | exec -> review -> fix-review? -> finish
+```
+
+`spec` is a conditional design gate. `clarify` may route directly to `plan` when the remaining questions are local implementation choices. It routes to `spec` when product behavior, APIs, state, data, permissions, migration, compatibility, or architecture decisions need to be fixed before implementation planning.
+
+`plan` is the superpowers `writing-plans` workflow under the loopx name. It writes executable plans and offers two execution options: `subagent-exec` recommended, or `exec` inline.
+
+`review` is the superpowers `requesting-code-review` workflow under the loopx name. `fix-review` is the superpowers `receiving-code-review` workflow under the loopx name.
+
+`finish` verifies completion, extracts local memory, proposes repo-tracked spec candidates when stable team rules emerged, then presents merge, PR, keep, or discard options.
+
+## Artifacts
+
+Human-maintained v1 skill-suite artifacts use `docs/loopx/`:
+
+- `docs/loopx/design/`
+- `docs/loopx/plans/`
+- `docs/loopx/reviews/`
+- `docs/loopx/refactors/`
+- `docs/loopx/specs/`
+
+Runtime state, hook diagnostics, installer metadata, manifests, generated HTML views, and runtime JSON use `.loopx/`.
+
+Local agent memory uses `.loopx/memory/`. `.loopx/memory/MEMORY.md` is bounded curated project memory. `.loopx/memory/index.jsonl` is a curated active index for agent file-search. Stable shared rules belong in `docs/loopx/specs/<domain>.md`, with `docs/loopx/specs/inbox.md` as the fallback domain.
+
+## Installer
+
+Default installation writes user-level skills and hooks for both supported targets:
+
+- Codex skills: `~/.agents/skills/`
+- Claude skills: `~/.claude/skills/`
+- Codex hook: existing loopx workflow hook
+- Claude hook: non-blocking prompt hook
+
+Project-level Claude installation and custom directories are explicit installer choices.
+
+## Claude Hook
+
+The Claude hook is advisory only. It must not block tools, mutate workflow state, or enforce git safety. It emits next-action context when loopx support context exists.
+
+## Non-Goals
+
+- No alias skills in the v1 bundled install surface for renamed superpowers skills.
+- No automatic project-level `.claude/skills` writes in postinstall.
+- No new mandatory CLI state machine for the v1 skill suite.
+- No blocking Claude hook in v1.

package/docs/loopx/plans/loopx-skill-suite-v1-implementation.md

@@ -0,0 +1,81 @@
+# loopx Skill Suite v1 Implementation Plan
+
+> **For agentic workers:** execute task-by-task. Preserve existing user edits and keep runtime maintenance behavior unless a task explicitly changes skill installation behavior.
+
+**Source Design:** `docs/loopx/design/loopx-skill-suite-v1-design.md`
+
+**Goal:** Convert loopx into a Codex and Claude ready skill suite with renamed superpowers-style workflow skills, dual-target installation, and non-blocking Claude hook support.
+
+**Architecture:** `skills/` remains the canonical source root. `plugins/loopx/skills/` mirrors the bundled v1 skill set for Codex plugin packaging, not every auxiliary source directory that may exist under `skills/`. `src/install-discovery.mjs` owns multi-target installation and lock metadata.
+
+**Tech Stack:** Node.js ESM, `node:test`, filesystem APIs from `node:fs/promises`.
+
+---
+
+### Task 1: Skill Set And Names
+
+**Files:**
+- Modify: `src/install-discovery.mjs`
+- Modify: `skills/`
+- Modify: `plugins/loopx/skills/`
+- Modify: `skills/RESOLVER.md`
+
+- [ ] Rename canonical superpowers-derived skills to v1 names.
+- [ ] Remove old runtime workflow skills from the bundled install list.
+- [ ] Keep `plan` as the canonical implementation-planning skill.
+- [ ] Mirror all bundled v1 canonical skill files into `plugins/loopx/skills/`.
+- [ ] Update internal references from old names to new `loopx:` names.
+- [ ] Keep auxiliary or compatibility skill sources outside the bundled install list unless explicitly promoted into the v1 product surface.
+
+### Task 2: Installer Targets
+
+**Files:**
+- Modify: `src/install-discovery.mjs`
+- Modify: `scripts/install-skills.mjs`
+- Modify: `src/cli.mjs`
+
+- [ ] Add Codex and Claude user skill targets.
+- [ ] Add interactive `loopx install-skills` command.
+- [ ] Keep non-interactive flags for target, mode, project, custom directory, and yes.
+- [ ] Make postinstall install Codex user skills and Claude user skills by default.
+- [ ] Preserve lock/ownership checks so non-loopx skills are not overwritten.
+
+### Task 3: Claude Hook
+
+**Files:**
+- Add: `scripts/claude-workflow-hook.mjs`
+- Modify: `src/install-discovery.mjs`
+- Modify: `scripts/install-skills.mjs`
+
+- [ ] Install Claude user hook script under `~/.claude/hooks/`.
+- [ ] Merge a non-blocking hook entry into `~/.claude/settings.json`.
+- [ ] Keep the hook advisory-only.
+- [ ] Do not overwrite unrelated Claude settings.
+
+### Task 4: Docs And Governance
+
+**Files:**
+- Modify: `README.md`
+- Modify: `README.zh-CN.md`
+- Modify: `package.json`
+- Modify: `scripts/verify-skills.mjs`
+- Modify: `test/skill-governance.test.mjs`
+- Modify: `test/workflow.test.mjs`
+
+- [ ] Reframe loopx as a skill suite for agentic coding assistants.
+- [ ] Document the new workflow and artifact paths.
+- [ ] Clarify v1 `docs/loopx/` artifacts versus generated runtime support state.
+- [ ] Document finish memory extraction and `docs/loopx/specs/` candidate promotion.
+- [ ] Clarify installed bundled skills versus auxiliary skill source directories.
+- [ ] Document Codex and Claude installation.
+- [ ] Update governance checks for the v1 bundled skill list and mirrors.
+- [ ] Update install tests for dual user targets and hooks.
+
+### Task 5: Verification
+
+**Files:**
+- Test suite only unless failures require fixes.
+
+- [ ] Run `node scripts/verify-skills.mjs`.
+- [ ] Run `npm test`.
+- [ ] Fix failures without broad unrelated refactors.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ai-content-space/loopx",
   "type": "module",
-  "version": "0.1.10",
-  "description": "Skill-first loopx workflow product for Codex",
+  "version": "0.2.1",
+  "description": "Skill-first workflow suite for agentic coding assistants",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/hugh-zhan9/loopx.git"
@@ -18,18 +18,22 @@
     "loopx": "src/cli.mjs"
   },
   "files": [
+    "AGENTS.md",
     "README.md",
     "README.zh-CN.md",
+    "docs/loopx/",
     "package.json",
     "scripts/install-skills.mjs",
     "scripts/verify-skills.mjs",
+    "scripts/claude-workflow-hook.mjs",
     "scripts/codex-stop-hook.mjs",
     "scripts/codex-workflow-hook.mjs",
     "assets/logo.svg",
     "src/",
     "skills/",
     "templates/",
-    "plugins/loopx/"
+    "plugins/loopx/",
+    "!plugins/loopx/scripts/plugin-install.test.mjs"
   ],
   "publishConfig": {
     "access": "public"

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

@@ -1,12 +1,12 @@
 {
   "name": "loopx",
-  "version": "0.1.10",
-  "description": "Skill-first loopx workflow product for Codex",
+  "version": "0.2.1",
+  "description": "Skill-first workflow suite for agentic coding assistants",
   "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.",
+    "shortDescription": "Codex plugin shell for the loopx skill bundle.",
+    "longDescription": "This plugin mirrors the canonical loopx skills and routes Codex 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/skills/clarify/SKILL.md

@@ -1,346 +1,73 @@
 ---
 name: clarify
-description: "Clarifies ambiguous loopx work into requirements, non-goals, decision boundaries, and design-ready specs before planning. Not for already-approved plans or concrete implementation tasks."
+description: "Grills ambiguous loopx work until material questions are answered, then routes to spec or plan using a design gate. Not for clear implementation tasks, approved specs, or code changes."
 when_to_use: "clarify, requirements, ambiguous request, unclear scope, non-goals, decision boundaries, acceptance criteria, 需求澄清, 范围不清"
 metadata:
-  version: "0.1.10"
+  version: "0.2.1"
 ---
 
 # loopx Clarify
 
-<Purpose>
-`clarify` is loopx's full pre-implementation clarification skill. It combines:
+Do not accept vague answers. Do not optimize for speed. The goal is shared understanding: every material question that could change scope, design, verification, rollout, safety, or ownership must be answered before handoff.
 
-- the Socratic pressure and ambiguity control of `deep-interview`
-- the design-shaping discipline of `brainstorming`
+## Core Loop
 
-Its job is not just to ask questions. Its job is to turn a vague or overloaded request into a written clarify spec that is:
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
 
-- explicit about intent
-- explicit about non-goals and decision boundaries
-- concrete enough to hand to `plan`
-- structured enough that downstream execution does not re-discover the task from scratch
-</Purpose>
+Ask the questions one at a time.
 
-<Use_When>
-- The request is broad, ambiguous, or mixes problem, solution, and implementation detail.
-- The user needs help defining scope, non-goals, acceptance criteria, or tradeoffs before planning.
-- A design direction exists only implicitly and would otherwise be invented during implementation.
-- The task will later be handed to `plan`, and you want a high-signal spec first.
-</Use_When>
+If a question can be answered by exploring the codebase, explore the codebase instead.
 
-<Do_Not_Use_When>
-- The task already has concrete file/symbol targets and clear acceptance criteria.
-- A complete and approved spec/plan already exists for the same task.
-- The user explicitly asks to skip clarification and execute immediately.
-</Do_Not_Use_When>
 
-<Why_This_Exists>
-Most implementation drift happens before coding begins. Teams often think they need “more planning,” when the real problem is weaker intent clarity, hidden assumptions, fuzzy boundaries, or a design shape that was never made explicit. `clarify` exists to solve those upstream failures before `plan` turns the clarified intent into an execution contract.
-</Why_This_Exists>
 
-<Core_Principles>
-- Ask one question at a time.
-- Prefer bounded multiple-choice questions when the option space is known; use open-ended questions only when the option space is genuinely unknown.
-- Prefer the highest-leverage unresolved question, not broad coverage.
-- Keep digging on the same thread until one assumption, one boundary, or one tradeoff becomes clearer.
-- Treat every answer as a claim to pressure-test, not a final truth to copy down.
-- Make `Non-goals` and `Decision Boundaries` mandatory gates.
-- Default to YAGNI: shrink speculative scope unless the user gives a concrete reason it belongs in the first pass.
-- Do not stop at “requirements”; shape the solution enough that the next stage has a coherent starting design.
-</Core_Principles>
+## Output
 
-<Profiles>
-- **Standard (`--standard`, default)**:
-  - default loopx clarify mode
-  - target threshold: `<= 0.20`
-  - max rounds: `15`
-- **Deep (`--deep`)**:
-  - higher-rigor clarify mode with heavier pressure-testing and design shaping
-  - target threshold: `<= 0.10`
-  - max rounds: `25`
-
-If no flag is provided, use **Standard**.
-</Profiles>
-
-<Runtime_State_Machine>
-`clarify` must maintain these runtime fields in `.loopx/workflows/<slug>/state.json` and mirror them in the clarify spec frontmatter:
-
-- `clarify_current_round` / `current_round`: starts at `0`; increments after each user-answer round.
-- `clarify_ambiguity_score` / `ambiguity_score`: starts at `1`; must be `<= clarify_target_ambiguity_threshold` before handoff.
-- `clarify_non_goals_resolved` / `non_goals_resolved`: `true` only after non-goals are explicit.
-- `clarify_decision_boundaries_resolved` / `decision_boundaries_resolved`: `true` only after human-vs-agent decision boundaries are explicit.
-- `clarify_pressure_pass_complete` / `pressure_pass_complete`: `true` only after at least one prior answer has been revisited with explicit pressure.
-
-The `clarify -> plan` gate is blocked until all of the following are true:
-
-- `unresolved_ambiguity_count` is `0`
-- `clarify_current_round` is between `1` and `clarify_max_rounds`
-- `clarify_ambiguity_score` is at or below the selected profile threshold
-- non-goals are resolved
-- decision boundaries are resolved
-- pressure pass is complete
-
-Do not mark a clarify spec handoff-ready by prose alone. Update the frontmatter fields so the runtime can enforce the same readiness decision.
-</Runtime_State_Machine>
-
-<Execution_Policy>
-- Always run a preflight context intake before the first interview question.
-- If supplied context is too large for safe prompt use, first request or create a concise prompt-safe summary that preserves goals, constraints, success criteria, non-goals, decision boundaries, and source references.
-- Explore repo context before asking the user about internals.
-- Prefer evidence-backed clarification in brownfield work:
-  - “I found X in Y. Should this clarify spec preserve that pattern?”
-- Route facts before judgment:
-  - discoverable codebase facts should be inspected directly
-  - evidence-backed inferences should be confirmed with the user
-  - product intent, tradeoffs, scope, non-goals, and decision boundaries must be treated as human decisions
-- Ask about intent and boundaries before implementation detail.
-- Respect stage priority:
-  1. intent, outcome, scope, non-goals, decision boundaries
-  2. constraints and success criteria
-  3. brownfield grounding and integration details
-- Stay on the same thread when the answer is still weak instead of rotating dimensions just for coverage.
-- Revisit at least one earlier answer with an explicit assumption, evidence, or tradeoff follow-up before crystallizing.
-- If the task is too large for one coherent spec, decompose it before pretending it is ready.
-- Keep user effort low: do not ask for facts that can be discovered directly.
-</Execution_Policy>
-
-<Dimensions>
-- **Intent**: why the user wants this
-- **Outcome**: what end state they actually want
-- **Scope**: how far the change should go
-- **Constraints**: what must remain true
-- **Success Criteria**: how completion will be judged
-- **Context**: how this fits the existing codebase (brownfield only)
-</Dimensions>
-
-<Pressure_Patterns>
-When an answer is still weak, prefer one of these next:
-
-1. Ask for a concrete example or counterexample.
-2. Expose the hidden assumption that makes the answer true.
-3. Force a boundary:
-   - what should not happen
-   - what should be deferred
-   - what should be rejected
-4. If the answer is still describing symptoms, reframe toward root cause.
-</Pressure_Patterns>
-
-<Socratic_Questioning>
-`clarify` should be Socratic without being vague.
-
-- Ask one focused round at a time.
-- Prefer bounded choices when they reduce user effort:
-  - use single-choice when one answer should drive the next branch
-  - use multi-choice when several constraints, non-goals, or success checks may all apply
-  - include `Other` only when the known options are likely incomplete
-- Lead with the recommended option when repo evidence or prior answers support it, but make the tradeoff visible.
-- Do not hide a branching interview tree inside one overloaded question. If an option would require a follow-up, ask that follow-up next.
-- After each answer, decide whether the next highest-value move is:
-  - deeper pressure on the same thread
-  - zooming out to another unresolved breadth track
-  - crystallizing the spec
-</Socratic_Questioning>
-
-<Breadth_Ledger>
-Maintain a lightweight breadth ledger across independent ambiguity tracks:
-
-- scope
-- constraints
-- outputs / deliverables
-- verification and success criteria
-- brownfield integration
-- user-mentioned workstreams or stakeholder requirements
-
-The ledger is a guard, not a rotation rule. Stay deep on the current thread until it has been pressure-tested, then zoom out only when another material track remains unresolved and would change downstream execution.
-</Breadth_Ledger>
-
-<Challenge_Modes>
-Use these assumption stress tests when applicable:
-
-- **Contrarian**: challenge a core assumption when an answer rests on an untested belief.
-- **Simplifier**: probe the smallest viable first pass when scope expands faster than outcome clarity.
-- **Ontologist**: reframe toward essence/root cause when the user keeps describing symptoms or when ambiguity stalls.
-
-Track which challenge modes have been used in the ambiguity register. Do not repeat a mode mechanically.
-</Challenge_Modes>
-
-<Design_Shaping>
-`clarify` should not stop at “what do you want?” Once the intent is understandable, it should also shape the task enough that the downstream plan is not starting from zero.
-
-When there is a real design choice:
-
-- propose 2-3 viable approaches
-- lead with the recommended one
-- explain tradeoffs briefly
-- right-size the design to the task
-- identify likely component boundaries, data flow, or user-facing flow when that would materially affect planning
-- reject speculative features unless they are necessary for the stated outcome
-
-The goal is not to produce a full architecture doc here. The goal is to make the clarify spec design-ready.
-</Design_Shaping>
-
-<Incremental_Validation>
-For non-trivial designs, validate the design in small sections before writing the final clarify spec.
-
-Present a compact design summary and ask whether it matches the user's intent. When relevant, validate these sections separately:
-
-- user-facing behavior or workflow
-- component boundaries / ownership
-- data flow or API contract
-- error handling and edge cases
-- test and verification shape
-- explicitly deferred work
-
-If the user rejects a section, continue the interview loop instead of writing a handoff-ready spec.
-</Incremental_Validation>
-
-<Practical_Closure_Audit>
-Treat a low ambiguity score as permission to audit closure, not as automatic permission to stop.
-
-Before crystallizing, ask:
-
-- Would one more question materially change implementation, test strategy, or scope?
-- Are non-goals and decision boundaries explicit enough for downstream agents?
-- Has at least one assumption or tradeoff been pressure-tested?
-- Is remaining uncertainty residual risk rather than actionable ambiguity?
-
-If remaining uncertainty would not change execution, crystallize the spec and preserve it as residual risk instead of opening a low-value branch.
-</Practical_Closure_Audit>
-
-<Spec_Self_Review>
-Before marking a clarify spec handoff-ready, perform a self-review pass:
-
-- remove placeholders such as `TBD`, `TODO`, `REPLACE_ME`, or vague “etc.”
-- check for internal contradictions
-- check whether the scope is still too broad for one coherent execution package
-- check whether any requirement can be interpreted two materially different ways
-- verify that non-goals, decision boundaries, acceptance criteria, and residual risks are explicit
-- verify that brownfield evidence is labeled separately from inference
-</Spec_Self_Review>
-
-<Process>
-
-## 1. Explore Context
-
-- Read relevant files, docs, and current patterns first.
-- Classify the work as brownfield or greenfield.
-- For brownfield work, collect concrete evidence before questioning.
-- Create or update a compact context snapshot for the task when the conversation, source docs, or repo evidence would otherwise be too large to carry safely.
-
-## 2. Interview
-
-- Ask one question per round.
-- Prefer bounded choices for known option spaces; use open-ended questions only when the valid answers cannot be enumerated.
-- Before asking each question, show a compact status line with:
-  - `round`: current round and max rounds
-  - `ambiguity_score`: current score
-  - `target`: selected profile threshold
-  - `open_items`: unresolved ambiguity count
-- Also state the current focus dimension and whether the round is fact confirmation or human judgment.
-- After the user answers and the round is updated, show the revised `ambiguity_score`, whether it moved up/down/unchanged, and the main reason for that change before asking the next question.
-- After each answered round, update `current_round`, the ambiguity register, and `ambiguity_score`.
-- Target the weakest unresolved dimension within the stage-priority order.
-- Maintain the breadth ledger; do not rotate dimensions just for coverage.
-- Keep `Non-goals` and `Decision Boundaries` explicit from early in the process.
-- Respect the selected profile:
-  - `standard`: stop only when the clarify spec is handoff-ready or `15` rounds are exhausted
-  - `deep`: stop only when the clarify spec is handoff-ready or `25` rounds are exhausted
-
-## 3. Pressure-Test
-
-- Apply explicit follow-up pressure to at least one earlier answer.
-- Set `pressure_pass_complete: true` only after the pressure follow-up is answered and reflected in the spec.
-- Do not crystallize while assumptions are still hidden or boundaries are still fuzzy.
-- In `deep`, expect more persistence on the same thread before moving on.
-
-## 4. Shape the Design
-
-- Where needed, propose a small set of options.
-- Recommend one approach.
-- Clarify what that approach implies for scope and downstream execution.
-- Apply incremental validation for non-trivial designs before finalizing the spec.
-
-## 4.5. Closure and Self-Review
-
-- Run the practical closure audit.
-- Run the spec self-review checklist before marking handoff-ready.
-- If the round cap is reached or the user chooses to proceed despite ambiguity, preserve an explicit residual-risk warning in the spec and handoff recommendation.
-
-## 5. Write the Clarify Spec
-
-Write the output to the loopx runtime namespace:
+Write the clarification context bundle to:
 
 - `.loopx/intake/clarify-<slug>-<timestamp>.md`
 
-The clarify spec should include:
+The bundle must preserve the information `spec` or `plan` needs:
 
-- metadata
-- runtime readiness frontmatter:
-  - `current_round`
-  - `ambiguity_score`
-  - `non_goals_resolved`
-  - `decision_boundaries_resolved`
-  - `pressure_pass_complete`
-  - `unresolved_ambiguity_count`
-- intent
-- desired outcome
-- in-scope
-- out-of-scope / non-goals
+- intent and desired outcome
+- in-scope work
+- non-goals
 - decision boundaries
 - constraints
 - success criteria
-- assumptions exposed and resolved
-- pressure-pass findings
+- assumptions challenged
+- key decisions and rejected alternatives
 - brownfield evidence vs inference
-- breadth ledger / unresolved tracks, if any
-- design direction / preferred approach
 - residual risks
-- explicit next handoff recommendation
+- conversation summary and important user wording
+- source requirements or external document references
+- next handoff recommendation
+
+## Handoff Decision
+
+After every material question is answered, choose one handoff:
+
+- `needs_spec`
+- `direct_to_plan`
+- `blocked`
 
-## 6. Handoff
+Use `needs_spec` when any product behavior, API, data model, state machine, permission, security, migration, compatibility, rollout, or cross-module architecture decision still needs to be fixed before implementation planning.
 
-After the clarify spec is ready:
+Use `direct_to_plan` when goals, non-goals, constraints, affected scope, and verification are clear, and all remaining choices are local implementation details.
 
-- hand off to `plan`; do not start implementation, TDD, `build`, or `autopilot` from `clarify`
-- if the user asks to execute immediately, explain that loopx requires the `plan` gate first and provide the plan invocation
-- if a task is too small to justify planning, do not use `clarify`; handle that request outside the clarify workflow from the start
+Use `blocked` when any material requirement or decision boundary is still unclear.
 
-Preferred explicit handoff contract:
+For `needs_spec`, immediately use the `spec` skill with the clarification context bundle, current conversation context, repo evidence, and source documents. `spec` writes:
 
-- Default handoff after normal loopx clarify: `$plan <slug>`
-- Conditional artifact-pinned handoff: `$plan --direct <spec-path>`
-- Recommend `$plan --direct <spec-path>` when the user explicitly wants to plan from a specific requirements artifact, when the source is external/manual/legacy, or when multiple plausible spec files exist and the user has chosen one as the planning source of truth.
-- Do not use `$plan --direct` to work around unclear workflow state, missing approvals, or an uncertain slug; inspect or repair the loopx runtime state instead.
-- For the normal loopx clarify happy path, prefer `$plan <slug>` because the active workflow slug already anchors the clarify artifact and runtime state.
-- Consumer behavior: treat the clarify spec as the source of truth for intent, non-goals, decision boundaries, constraints, and design direction; do not reopen clarification by default
+- `docs/loopx/design/<需求名>需求设计文档.md`
 
-`clarify` itself does not implement the feature. The handoff recommendation must name `plan` as the next workflow step.
+Then stop before implementation planning and report:
 
-</Process>
+```text
+$plan docs/loopx/design/<需求名>需求设计文档.md
+```
 
-<Readiness_Gates>
-- `Non-goals` are explicit
-- `Decision Boundaries` are explicit
-- At least one pressure-pass follow-up has revisited an earlier answer
-- The practical closure audit has passed
-- The spec self-review pass has removed placeholders, contradictions, and material ambiguity
-- A written clarify spec exists
-- The task is small enough and clear enough for real downstream handoff
-- The selected profile threshold is met:
-  - `standard`: weighted ambiguity `<= 0.20`
-  - `deep`: weighted ambiguity `<= 0.10`
-</Readiness_Gates>
+For `direct_to_plan`, hand off to the `plan` skill with the clarification context bundle as the source. `plan` writes:
 
-<Must_Not_Decide_Automatically>
-- approval to move from clarify into plan
-- skipping `plan` after producing a clarify spec
-- implementation details that were never clarified or grounded
-- widening the task because a broader redesign sounds cleaner
-</Must_Not_Decide_Automatically>
+- `docs/loopx/plans/YYYY-MM-DD-<feature-name>.md`
 
-<Output_Contract>
-- primary artifact: a loopx clarify spec
-- secondary artifact: an explicit ambiguity register and next-step recommendation
-- preferred handoff: `plan`
-</Output_Contract>
+Do not write implementation plans or start code changes inside `clarify`.

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

@@ -3,7 +3,7 @@ name: debug
 description: "Finds root cause for bugs, failing tests, build failures, regressions, and unexpected behavior before fixes. Not for new feature planning or routine code review."
 when_to_use: "debug, bug, test failure, build failure, regression, unexpected behavior, root cause, 报错, 失败, 回归, 排查"
 metadata:
-  version: "0.1.10"
+  version: "0.2.1"
 ---
 
 # Systematic Debugging