@ai-content-space/loopx 0.1.9 → 0.2.0

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

@@ -1,295 +1,173 @@
 ---
 name: plan
-description: "Creates a consensus-first loopx plan package with Planner, Architect, and Critic review from an approved spec. Not for unresolved requirements or direct implementation."
-when_to_use: "plan, planning, consensus planning, PRD, architecture plan, test plan, approved clarify spec, 规划, 方案, 架构评审"
+description: "Creates bite-sized implementation plans from approved requirements, clarify output, or design specs with exact files, tests, commands, expected output, and execution handoff. Not for unresolved requirements, design decisions, PRD generation, or code changes."
+when_to_use: "plan, implementation plan, execution plan, task breakdown, approved requirements, approved design spec, docs/loopx/design, 实施计划, 执行计划, 任务拆分"
 metadata:
-  version: "0.1.9"
-argument-hint: "[--interactive] [--deliberate] [--direct <spec-path>] <clarified task or spec path>"
+  version: "0.2.0"
+argument-hint: "[--direct <design-spec-path>] <design spec path or feature name>"
 ---
 
 # 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.
-- Preserve accepted intent as durable change artifacts: proposal, spec delta, design, tasks, and artifact dependency graph.
-- 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/intake/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>
+## Overview
 
-<Pre_Context_Intake>
-Before planning:
+Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, and how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
 
-1. Derive a task slug.
-2. Reuse the latest relevant `.loopx/context/{slug}-*.md` snapshot when available.
-3. If none exists, create `.loopx/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.
+Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
 
-Critic evaluates:
-
-- principle-option consistency
-- fairness of alternatives
-- clarity of risk mitigation
-- testable acceptance criteria
-- concrete verification steps
-- execution-input completeness for each new or changed ingress / workflow entrypoint
-- explicit non-goals and decision boundaries
-- in deliberate mode: pre-mortem and expanded test plan quality
+Use this skill after requirements are clear. The source may be:
 
-Critic verdicts:
+- `docs/loopx/design/<需求名>需求设计文档.md`
+- `.loopx/intake/clarify-<slug>-<timestamp>.md`
+- an issue, PRD, or requirements document that already fixes material decisions
 
-- `APPROVE`
-- `ITERATE`
-- `REJECT`
+Do not re-decide product or architecture. If the source is incomplete, contradictory, or missing product behavior, API, data, state, permission, migration, compatibility, or architecture decisions, return to `clarify` or `spec` instead of filling those gaps inside `plan`.
 
-## Step 5. Closed Re-Review Loop
+**Announce at start:** "I'm using the plan skill to create the implementation plan."
 
-If Critic returns `ITERATE` or `REJECT`, run a full closed loop:
+**Save plans to:** `docs/loopx/plans/YYYY-MM-DD-<feature-name>.md`
 
-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
+- User preferences for plan location override this default.
 
-Do not patch only the Critic complaint in isolation if the Architect objection implies a deeper plan change.
+## Scope Check
 
-## Step 6. Final Plan Package
+If the design spec covers multiple independent subsystems, it should have been broken into sub-project specs before planning. If it wasn't, suggest breaking this into separate plans: one per subsystem. Each plan should produce working, testable software on its own.
 
-On approval, write canonical planning artifacts:
+## File Structure
 
-- `.loopx/workflows/<slug>/plan.md`
-- `.loopx/workflows/<slug>/architecture.md`
-- `.loopx/workflows/<slug>/development-plan.md`
-- `.loopx/workflows/<slug>/test-plan.md`
-- `.loopx/workflows/<slug>/requirement-traceability.md`
-- `.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`
+Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
 
-Also generate derived HTML reading views:
+- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
+- Prefer smaller, focused files over large files that do too much.
+- Files that change together should live together. Split by responsibility, not by technical layer.
+- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure. If a file you're modifying has grown unwieldy, including a split in the plan is reasonable.
 
-- `.loopx/workflows/<slug>/view/index.html`
-- `.loopx/workflows/<slug>/view/plan.html`
-- `.loopx/views/index.html`
+This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.
 
-The HTML files are derived reading views for human plan review. They are not canonical fact sources; Markdown and JSON remain authoritative.
+## Bite-Sized Task Granularity
 
-The final plan must include:
+Each step is one action, normally 2-5 minutes:
 
-- a source-requirement coverage matrix that maps the original requirements/PRD to plan, architecture, slices, spec delta, and tests
-- ADR: Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups
-- concrete implementation steps sized to the actual task
-- target long-lived spec domains and an OpenSpec-style requirements delta for archive
-- vertical slices sized as independently verifiable tracer bullets, not horizontal layer-only task groups
-- execution inputs mapped to concrete sources before build starts
-- available execution lanes and recommended lane
-- test and verification commands
-- residual risks and assumptions
-- explicit build/autopilot handoff guidance
+- "Write the failing test" is a step.
+- "Run it to make sure it fails" is a step.
+- "Implement the minimal code to make the test pass" is a step.
+- "Run the tests and make sure they pass" is a step.
+- "Commit" is a step.
 
-## Step 7. Execution Bridge
+## Plan Document Header
 
-`plan` stops at an approved plan package.
+Every plan must start with this header:
 
-In `--interactive` mode, ask for the next lane:
+```markdown
+# [Feature Name] Implementation Plan
 
-- approve for `build`
-- approve for `autopilot`
-- request plan changes
-- stop
+> **For agentic workers:** REQUIRED SUB-SKILL: Use loopx:subagent-exec (recommended) or loopx:exec to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 
-Without `--interactive`, report the approved plan and recommended next command, but do not launch execution.
-</Consensus_Workflow>
+**Source:** [Path to design, clarify bundle, issue, PRD, or requirements document]
 
-<Final_Response_Contract>
-Default build handoff after an approved plan package:
+**Goal:** [One sentence describing what this builds]
 
-```text
-Next:
-$build .loopx/plans/prd-<slug>.md
+**Architecture:** [2-3 sentences summarizing the approved approach; do not introduce new design decisions]
+
+**Tech Stack:** [Key technologies/libraries]
+
+---
+```
+
+## Task Structure
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: FAIL with "function not defined"
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+def function(input):
+    return expected
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
 ```
+````
+
+## No Placeholders
+
+Every step must contain the actual content an engineer needs. These are plan failures; never write them:
+
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "add validation" / "handle edge cases"
+- "Write tests for the above" without actual test code
+- "Similar to Task N"; repeat the code because the engineer may be reading tasks out of order
+- Steps that describe what to do without showing how when code is required
+- References to types, functions, or methods not defined in any task
+
+## Remember
+
+- Exact file paths always
+- Complete code in every step when a step changes code
+- Exact commands with expected output
+- DRY, YAGNI, TDD, frequent commits
+- The approved design spec is binding; do not expand scope
+
+## Self-Review
+
+After writing the complete plan, look at the design spec with fresh eyes and check the plan against it. This is a checklist you run yourself, not a subagent dispatch.
 
-Use the artifact-first PRD path because it pins build to the approved plan package. Do not emit `$build <slug>` as the primary handoff when `.loopx/plans/prd-<slug>.md` is known. If execution is not approved or plan gates remain blocked, state the blocker instead of emitting a build handoff.
+1. **Spec coverage:** Skim each section/requirement in the design spec. Can you point to a task that implements it? List any gaps.
+2. **Placeholder scan:** Search your plan for red flags from the "No Placeholders" section. Fix them.
+3. **Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks?
+4. **Design drift:** Did you introduce a new architecture, API, data model, or business behavior not present in the design spec? If yes, return to `spec`.
 
-Also report the generated HTML reading entrypoint so the user can review the plan without running another command:
+If you find issues, fix them inline. If you find a design requirement with no task, add the task.
+
+## Execution Handoff
+
+After saving the plan, offer execution choice:
 
 ```text
-HTML:
-.loopx/workflows/<slug>/view/index.html
+Plan complete and saved to `docs/loopx/plans/<filename>.md`.
+
+Two execution options:
+
+1. Subagent-Driven (recommended) - dispatch a fresh subagent per task, review between tasks, fast iteration
+2. Inline Execution - execute tasks in this session using exec, batch execution with checkpoints
+
+Which approach?
 ```
-</Final_Response_Contract>
-
-<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`
-- `change_artifacts_status`: `missing|partial|complete|archived`
-- `spec_delta_status`: `missing|partial|complete`
-- `slice_artifacts_status`: `missing|partial|complete`
-- `plan_acceptance_criteria_testable`: `true|false`
-- `plan_verification_steps_resolved`: `true|false`
-- `plan_execution_inputs_resolved`: `true|false`
-- `source_requirements_status`: `complete|partial`
-- `requirement_traceability_path`: `.loopx/workflows/<slug>/requirement-traceability.md`
-- `requested_transition`: remains explicit before build/autopilot
-
-The plan gate is blocked until:
-
-- plan package artifacts exist
-- change proposal, spec delta, design, tasks, vertical slices, and artifact graph exist
-- spec delta declares target domains and `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` blocks
-- every ADDED or MODIFIED requirement uses `### Requirement:`, contains SHALL or MUST text, and includes at least one `#### Scenario:`
-- vertical slices contain at least one `AFK` or `HITL` end-to-end slice with acceptance criteria and verification signal
-- Architect review is complete
-- Critic verdict is `approve`
-- acceptance criteria are testable
-- verification steps are concrete
-- execution inputs are fully mapped to concrete sources
-- source requirements are covered by `requirement-traceability.md`; uncovered original PRD requirements block build handoff
-- 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>/`
-- original source requirements and traceability matrix under `.loopx/workflows/<slug>/requirement-traceability.md`
-- canonical PRD and test spec under `.loopx/plans/`
-- change artifacts under `.loopx/changes/active/<change-id>/`
-- derived HTML reading views under `.loopx/workflows/<slug>/view/` and `.loopx/views/`
-- 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>
+
+If Subagent-Driven is chosen:
+
+- REQUIRED SUB-SKILL: Use `loopx:subagent-exec`
+- Fresh subagent per task plus two-stage review
+
+If Inline Execution is chosen:
+
+- REQUIRED SUB-SKILL: Use `loopx:exec`
+- Batch execution with checkpoints for review

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

@@ -0,0 +1,71 @@
+---
+name: refactor-plan
+description: "Creates a behavior-preserving refactor plan with user interview, repo evidence, tiny commits, scope boundaries, and testing decisions. Not for feature changes or immediate implementation."
+when_to_use: "refactor-plan, refactor request, refactoring RFC, tiny commits, behavior-preserving cleanup, architecture cleanup, 重构计划"
+metadata:
+  version: "0.2.0"
+---
+
+This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.
+
+1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
+
+2. Explore the repo to verify their assertions and understand the current state of the codebase.
+
+3. Ask whether they have considered other options, and present other options to them.
+
+4. Interview the user about the implementation. Be extremely detailed and thorough.
+
+5. Hammer out the exact scope of the implementation. Work out what you plan to change and what you plan not to change.
+
+6. Look in the codebase to check for test coverage of this area of the codebase. If there is insufficient test coverage, ask the user what their plans for testing are.
+
+7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice to "make each refactoring step as small as possible, so that you can always see the program working."
+
+8. Write the refactor plan to `docs/loopx/refactors/YYYY-MM-DD-<topic>.md`. If the repository has an issue workflow and the user wants an issue, also create a GitHub issue with the same plan. Use the following template:
+
+<refactor-plan-template>
+
+## Problem Statement
+
+The problem that the developer is facing, from the developer's perspective.
+
+## Solution
+
+The solution to the problem, from the developer's perspective.
+
+## Commits
+
+A LONG, detailed implementation plan. Write the plan in plain English, breaking down the implementation into the tiniest commits possible. Each commit should leave the codebase in a working state.
+
+## Decision Document
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this refactor.
+
+## Further Notes (optional)
+
+Any further notes about the refactor.
+
+</refactor-plan-template>