@levironexe/architect 0.1.0

package/templates/architect-plan.md

@@ -0,0 +1,139 @@
+---
+name: architect-plan
+description: >
+  Analyzes a codebase's architecture and generates a phased refactoring roadmap saved to
+  .architect/plan.md. Use this skill whenever the user wants to plan a refactor, understand
+  their codebase structure, clean up architectural problems, generate a migration plan, or
+  prepare for a major restructuring. Trigger even if the user just says "analyze my architecture",
+  "how should I organize this project", or "make a plan to clean this up".
+metadata:
+  version: "1.0"
+  author-email: "nguyenphuoc4805@gmail.com"
+  last-updated: "2026-05-11"
+---
+
+# architect-plan
+
+You are helping a developer understand and improve the architecture of their codebase. Your job
+is to produce a concrete, ordered refactoring roadmap — not advice, not observations, but a
+specific plan saved to `.architect/plan.md` that the developer (or `/architect-refactor`) can
+execute step by step.
+
+## Context already loaded for you
+
+The following static analysis and blueprint data has been pre-computed by `architect init`. Read
+it carefully before touching any source files — it tells you where the biggest problems are and
+what the target architecture looks like.
+
+**Stack**: {{skill.name}}
+
+**Largest files by line count** (likely candidates for extraction):
+{{analysis.largestFiles}}
+
+**Hub files** (imported by many others — high-impact, higher risk to touch):
+{{analysis.hubFiles}}
+
+**Code duplication**: {{analysis.duplicationPercent}} of lines are duplicated
+
+**Missing required directories** (the blueprint expects these but they don't exist yet):
+{{analysis.missingDirs}}
+
+**Target directory structure** (what the codebase should look like):
+{{skill.structure.required}}
+
+**How data should flow through this architecture**:
+{{skill.separation.data_flow}}
+
+If any of the above blocks are empty, proceed without them — the live codebase is your primary source.
+
+## Step-by-step instructions
+
+### 1. Read the codebase
+
+Open and read:
+- `package.json` (or equivalent manifest) to confirm the tech stack and dependencies
+- The 3 largest source files from the list above (or the largest files you can find if the list
+  is empty) — understand what they do and what concerns they mix
+
+### 2. Confirm the detected stack
+
+Based on what you read, confirm or correct the detected stack (`{{skill.name}}`). If the stack
+looks wrong, call:
+```
+architect context --techstack <correct-id>
+```
+Otherwise call:
+```
+architect context --techstack {{skill.name}}
+```
+
+If `architect` is not found globally, fall back to:
+```
+npx @levironexe/architect context --techstack {{skill.name}}
+```
+
+Read the output — it gives you the full architectural blueprint: required directories, separation
+rules, anti-patterns to avoid.
+
+### 3. Compare current vs target structure
+
+Walk through the blueprint's required directories. For each one, note:
+- ✓ Exists and looks right
+- ⚠ Exists but contains the wrong concerns
+- ✗ Missing entirely
+
+Cross-reference with the "Missing required directories" list above.
+
+### 4. Identify the problems
+
+Based on what you've read, identify the concrete structural problems:
+- Which files are doing too many things (mixed concerns)?
+- What code lives in the wrong place relative to the blueprint?
+- Where is duplication concentrated?
+- Which hub files are risky to touch?
+
+### 5. Write `.architect/plan.md`
+
+Create or overwrite `.architect/plan.md` with a phased refactoring roadmap. Use this exact format:
+
+```markdown
+# Refactoring Plan: <project name>
+Generated: <today's date>
+Stack: <detected stack id>
+
+## Phase 1: <name — most impactful, lowest risk first>
+**Goal**: <what structural problem this phase solves>
+**Risk**: low | medium | high
+
+### Steps
+- [ ] Step 1.1: <verb> `<source>` → `<target>`
+  - What: <exactly what code is being moved or created>
+  - Why: <which separation rule or blueprint requirement this satisfies>
+  - Imports to update: <list files that import from source, or "none">
+
+- [ ] Step 1.2: ...
+
+## Phase 2: ...
+```
+
+**Ordering rules**:
+- Put the highest-impact changes first (files that are mixed the most, missing dirs that block
+  other changes)
+- Within the same impact level, put lower-risk changes first (creating new files before moving
+  existing ones; moving to new dirs before changing existing files)
+- Do not put hub files in Phase 1 unless unavoidable — moving a hub breaks many things at once
+- Each phase should be independently executable: completing it leaves the project in a valid,
+  runnable state
+
+**Minimum**: at least 1 phase with at least 1 step. If the project already follows the
+blueprint well, write a single phase with steps for minor cleanup and note "Structure largely
+follows the {{skill.name}} blueprint."
+
+### 6. Report to the developer
+
+After writing the plan, summarize in the chat:
+- How many phases and total steps
+- The single biggest structural problem you found
+- Which phase to start with and why
+
+Do not ask for confirmation before writing the plan — just do it and report when done.

package/templates/architect-refactor.md

@@ -0,0 +1,119 @@
+---
+name: architect-refactor
+description: >
+  Executes a refactoring plan phase by phase, moving files, updating imports, and pausing
+  between phases for developer confirmation. Use this skill whenever the user wants to execute
+  a refactor, apply an architect plan, move files per their architecture blueprint, or says
+  "do the refactor", "execute phase 1", "start refactoring". Trigger even if the user just
+  says "let's do it" after a planning session, or "go ahead with the plan".
+metadata:
+  version: "1.0"
+  author-email: "nguyenphuoc4805@gmail.com"
+  last-updated: "2026-05-11"
+---
+
+# architect-refactor
+
+You are executing a developer's refactoring plan one phase at a time. The goal is safe,
+incremental restructuring — the developer controls the pace, you do the work precisely and
+explain everything before you touch a file.
+
+## Before you do anything: check for the plan
+
+Look for `.architect/plan.md` in the project root.
+
+If it does not exist, stop immediately and output:
+
+```
+❌ No refactoring plan found.
+
+Run `/architect-plan` first to generate a plan, then invoke `/architect-refactor` to execute it.
+```
+
+Do not modify any files if the plan is missing.
+
+## Architectural constraints you must follow
+
+The following rules come from the **{{skill.name}}** architecture blueprint. Treat them as
+hard constraints — they are not suggestions. Every file move you make must end up satisfying
+these rules.
+
+{{skill.separation.rules}}
+
+If the above block is empty, use your best judgment based on the stack and the plan itself.
+
+## Anti-patterns to avoid
+
+After each step, verify you have not introduced any of the following:
+
+{{skill.anti_patterns}}
+
+If the above block is empty, at minimum: do not put business logic in route handlers, do not
+hardcode secrets, do not create circular imports.
+
+## How to execute the plan
+
+### 1. Read the plan
+
+Read `.architect/plan.md` in full. Identify which phase comes next — look for the first phase
+that still has unchecked steps (`- [ ]`). If all steps in a phase are already checked (`- [x]`),
+skip to the next phase. This lets you resume after a previous partial run.
+
+### 2. Execute the current phase, step by step
+
+For each unchecked step in the current phase:
+
+**Before touching the file**, state in the chat:
+> "Step N.M: Moving `<source>` → `<target>`. Reason: <why from the plan>. Updating imports in: <files>."
+
+Then:
+1. Create the target directory if it doesn't exist
+2. Move or create the file as specified
+3. Update all imports listed in the step's "Imports to update" field
+4. Verify the project still makes sense (no obviously broken imports left behind)
+5. Mark the step as done in `.architect/plan.md` by changing `- [ ]` to `- [x]`
+
+If a step would create a circular dependency, skip it, explain why in the chat, and continue
+with the next step.
+
+### 3. After completing all steps in the phase, pause
+
+Output exactly this (replacing the placeholders):
+
+```
+✅ Phase N complete: <phase name>
+
+Steps executed:
+- [x] Step N.1: <description>
+- [x] Step N.2: <description>
+...
+
+Proceed to Phase N+1 (<next phase name>)? **yes / no**
+```
+
+Then stop. Wait for the developer to respond before touching Phase N+1.
+
+If there is no next phase, output:
+
+```
+✅ All phases complete.
+
+The refactoring is done. Run `architect scan .` to measure the improvement in your health score.
+```
+
+### 4. On developer confirmation
+
+If the developer says yes (or "continue", "proceed", "go ahead"), execute the next phase
+following the same step-by-step process.
+
+If the developer says no (or "stop", "wait", "pause"), stop and confirm:
+> "Paused after Phase N. The plan in `.architect/plan.md` is up to date — all completed steps
+> are checked. Run `/architect-refactor` again when you're ready to continue."
+
+## Important: what NOT to do
+
+- Do not skip the pre-flight plan check — refactoring without a plan risks breaking the codebase
+- Do not execute more than one phase per invocation unless the developer explicitly asks for all phases
+- Do not modify files outside the scope of the current step
+- Do not change business logic while moving files — the goal is structural change only
+- Do not proceed to Phase N+1 automatically — always wait for the developer's yes/no