ai-workflow-init 7.0.0 → 7.2.0

package/.claude/CLAUDE.md

@@ -27,7 +27,7 @@
 
 ### 2. Deep Understanding
 - If unclear about requirements, edge cases, or expected behavior → **Ask first**
-- Use `AskUserQuestion` tool to ask multiple questions at once (up to 4)
+- Batch related questions into a single block (avoid asking one at a time)
 - Never assume or guess - clarification prevents wasted effort
 - Key questions:
   - "What should happen when X occurs?"

package/.claude/commands/clarify-requirements.md

@@ -405,8 +405,9 @@ Create `docs/ai/requirements/req-{name}.md` with:
 ## Next Steps
 
 1. Review this requirement document
-2. Run `/create-plan req-{name}` to generate implementation plan
-3. Address open questions before implementation
+2. Address open questions before implementation
+3. Run `/create-plan` to generate implementation plan (small feature)
+4. Run `/manage-epic` to break into feature plans (large feature)
 ```
 
 ### File Naming & Versioning
@@ -457,8 +458,9 @@ AskUserQuestion(questions=[{
   question: "What would you like to do next?",
   header: "Next",
   options: [
+    { label: "Create plan (small feature)", description: "Run /create-plan — single feature plan" },
+    { label: "Create epic (large feature)", description: "Run /manage-epic — break into multiple feature plans" },
     { label: "View full document", description: "Display the consolidated requirement" },
-    { label: "Create plan", description: "Run /create-plan for this requirement" },
     { label: "Continue refining", description: "Run more Q&A or agent passes" }
   ],
   multiSelect: false

package/.claude/commands/create-plan.md

@@ -19,6 +19,7 @@ Generate a single planning doc at `docs/ai/planning/feature-{name}.md` using the
 
 **Parse user request to identify:**
 - **Requirement doc reference:** Check if user provided path to `docs/ai/requirements/req-{name}.md`
+- **Epic reference:** Check if user provided path to `docs/ai/planning/epic-{name}.md`
 - **Feature type:** UI/Page, API/Service, Data/Database, Full-stack, Other
 - **Explicit requirements:** Framework, libraries, constraints mentioned
 - **Design context:**
@@ -27,6 +28,13 @@ Generate a single planning doc at `docs/ai/planning/feature-{name}.md` using the
   - No design source? → Flag for Step 5 (theme selection)
 - **Scope hints:** MVP mentions, deadlines, specific exclusions
 
+**If Epic Reference Provided:**
+- Read the epic doc: `Read(file_path="docs/ai/planning/epic-{name}.md")`
+- Extract: requirement link, feature plan list, which plan to create next
+- Read the linked requirement doc (from epic's `requirement` frontmatter)
+- Set `epic_plan` and `requirement` frontmatter in the generated feature plan
+- After creating the feature plan, update the epic's Feature Plans table (status → `open`)
+
 **If Requirement Doc Provided:**
 - Read the requirement doc: `Read(file_path="docs/ai/requirements/req-{name}.md")`
 - Extract and map to planning sections:
@@ -244,8 +252,11 @@ Produce a Markdown doc following `docs/ai/planning/feature-template.md`.
    - Epic ID and title
    - Link to epic plan
 
-0. **Requirements Reference** (if requirement doc was provided):
-   - Link to requirement doc: `[req-{name}.md](../requirements/req-{name}.md)`
+0. **Related Documents** (ONLY if requirement doc or epic was provided — skip entirely if neither exists):
+   - Link to requirement doc: `[req-{name}.md](../requirements/req-{name}.md)` (if exists)
+   - Link to epic: `[epic-{name}.md](epic-{name}.md)` (if exists)
+   - Set `epic_plan` and `requirement` in frontmatter accordingly
+   - If standalone (no req, no epic): set both frontmatter to null and **omit this section**
 
 1. **Codebase Context** (if exploration was done):
    - Similar features found
@@ -286,14 +297,48 @@ Produce a Markdown doc following `docs/ai/planning/feature-template.md`.
 **For each phase:**
 - Phase name: Descriptive (e.g., "API Endpoints", "UI Components")
 - Tasks list: `[ ] [ACTION] path/to/file — Summary`
-- Pseudo-code: 3-5 lines, natural language, show inputs → logic → outputs
+- Pseudo-code: Structured format with these sections:
   ```
   Example:
-  - Parse username + password from request
-  - Validate password strength → Hash with bcrypt
-  - Store user in database → Return success + user ID
+  Function: POST /api/auth/register(email, password, name)
+
+  Input validation:
+    - email: Valid format (regex), max 255 chars, lowercase
+    - password: Min 8 chars, 1 uppercase, 1 number, 1 special
+    - name: 2-50 chars, alphanumeric + spaces only
+
+  Logic flow:
+    1. Check if email exists in users table → If exists: return 409 Conflict
+    2. Hash password using bcrypt (salt rounds: 10)
+    3. Generate UUID for user_id
+    4. Insert into users table: { id: UUID, email, password_hash, name, created_at: NOW() }
+    5. Create JWT token with payload: { user_id, email } → Expiry: 24h, Secret: from env.JWT_SECRET
+
+  Return:
+    - Success (201): { user_id, email, name, token }
+    - Error: { status: 409/400/500, message, error_code }
+
+  Edge cases:
+    - Email already exists → 409 "Email already registered"
+    - Invalid email format → 400 "Invalid email"
+    - Weak password → 400 "Password must meet requirements"
+    - DB connection error → 500 "Registration failed, try again"
+    - Missing env.JWT_SECRET → 500 (log critical error)
+
+  Dependencies:
+    - bcrypt library (hash password)
+    - jsonwebtoken library (generate JWT)
+    - Database: users table (insert)
   ```
 
+  **Pseudo-code must include:**
+  - Function signature or endpoint route
+  - Input validation rules (types, constraints, formats)
+  - Logic flow with specific values/thresholds
+  - Return types for success + error cases
+  - Edge cases with handlers (HTTP status codes, error messages)
+  - Dependencies (external modules, APIs, DB tables)
+
 Create the file automatically:
 
 - `docs/ai/planning/feature-{name}.md` - Use complete structure from `feature-template.md`
@@ -325,10 +370,35 @@ Note: Test documentation will be created separately using the `writing-test` com
 **Requirement Doc** (`req-template.md`) focuses on **WHAT**:
 - Problem, Users, Business Rules, Functional Requirements
 
+**Epic Doc** (`epic-template.md`) focuses on **TRACKING**:
+- Links requirement to multiple feature plans
+- Tracks status and dependencies between plans
+
 **Planning Doc** (`feature-template.md`) focuses on **HOW**:
 - Codebase Context, Design, Implementation Phases, Pseudo-code
 
+### Cross-Linking Flow
+
+```
+req-{name}.md  ←→  epic-{name}.md  ←→  feature-{name}.md
+   (WHAT)          (TRACKING)            (HOW)
+```
+
+**Standalone (no epic, no req):**
+- feature-template: `requirement` → null, `epic_plan` → null
+- **Remove** Section 0 "Related Documents" entirely
+
+**With requirement only (no epic):**
+- feature-template: `requirement` → req doc, `epic_plan` → null
+- Include Section 0 with requirement link only
+
+**With epic (and req from epic):**
+- feature-template: `requirement` → req doc, `epic_plan` → epic doc
+- Include Section 0 with both links
+- After creation, update epic's Feature Plans table
+
 When requirement doc exists, planning doc should:
-1. Link to requirement doc (Section 0)
+1. Link to requirement doc and epic (Section 0: Related Documents)
 2. Not duplicate requirement content - reference it instead
 3. Focus on technical implementation details
+4. After creation, update epic's Feature Plans table (if epic exists)

package/.claude/commands/manage-epic.md

@@ -0,0 +1,227 @@
+---
+name: manage-epic
+description: Create or update epic - tracks feature plans for a requirement.
+---
+
+## Goal
+
+Manage epic documents that link requirements to feature plans. An epic is a simple tracking document that lists all feature plans needed to fulfill a requirement.
+
+**When to use:**
+- A requirement is too large for a single feature plan
+- You need to break a requirement into multiple feature plans
+- You need to update an epic with new feature plans or status changes
+
+---
+
+## Workflow Alignment
+
+- Provide brief status updates (1–3 sentences) before/after important actions.
+- For medium/large tasks, create todos (≤14 words, verb-led). Keep only one `in_progress` item.
+- Update todos immediately after progress; mark completed upon finish.
+
+---
+
+## Step 1: Detect Mode
+
+**Parse user input to determine mode:**
+
+| Input | Mode | Action |
+|-------|------|--------|
+| Requirement doc path provided | **Create** | Create new epic from requirement |
+| Epic doc path provided | **Update** | Update existing epic |
+| Feature plan path + epic path | **Link** | Add feature plan to epic |
+| No specific path | **Ask** | Ask user what they want to do |
+
+**If unclear, ask:**
+
+```
+AskUserQuestion(questions=[{
+  question: "What would you like to do with the epic?",
+  header: "Mode",
+  options: [
+    { label: "Create new epic", description: "Break a requirement into feature plans" },
+    { label: "Update epic", description: "Add feature plan or update status" },
+    { label: "Sync status", description: "Update status of all linked documents" }
+  ],
+  multiSelect: false
+}])
+```
+
+---
+
+## Step 2: Create Mode
+
+### 2a: Read Requirement
+
+```
+Read(file_path="docs/ai/requirements/req-{name}.md")
+```
+
+Extract:
+- Feature name
+- Functional requirements (FR table)
+- Implementation guidance / suggested phases
+- Complexity level
+
+### 2b: Break into Feature Plans
+
+Analyze the requirement and propose how to break it into feature plans.
+
+**Guidelines:**
+- Each feature plan should be independently implementable
+- Group by: feature area, layer (frontend/backend), or dependency order
+- Aim for 2-6 feature plans per epic
+- Each plan should map to specific FRs from the requirement
+
+**Ask user to confirm breakdown:**
+
+```
+AskUserQuestion(questions=[{
+  question: "Here's the proposed breakdown. Does this look right?",
+  header: "Breakdown",
+  options: [
+    { label: "Looks good", description: "Create epic with this breakdown" },
+    { label: "Adjust", description: "I want to modify the breakdown" },
+    { label: "Fewer plans", description: "Merge some plans together" }
+  ],
+  multiSelect: false
+}])
+```
+
+### 2c: Load Template & Generate Epic
+
+```
+Read(file_path="docs/ai/planning/epic-template.md")
+```
+
+Generate `docs/ai/planning/epic-{name}.md` with:
+- `requirement` frontmatter pointing to the req doc
+- Overview: 1-3 sentences from requirement's executive summary
+- Feature Plans table: proposed feature plans with descriptions
+- Dependency graph: show dependencies between feature plans
+- Related Documents: link back to requirement
+
+**Auto-name:** Derive from requirement name (kebab-case).
+- Example: `req-user-authentication.md` → `epic-user-authentication.md`
+
+**If file already exists:**
+1. Backup to `docs/ai/planning/archive/epic-{name}_{timestamp}.md`
+2. Overwrite main file
+3. Notify user of backup
+
+### 2d: Update Requirement Doc
+
+After creating epic, update the requirement doc's frontmatter and Related Plans section:
+- Set `epic_plan` in frontmatter
+- Update Related Plans table with epic link
+
+---
+
+## Step 3: Update Mode
+
+### 3a: Read Current Epic
+
+```
+Read(file_path="docs/ai/planning/epic-{name}.md")
+```
+
+### 3b: Determine Update Type
+
+| Trigger | Action |
+|---------|--------|
+| New feature plan created | Add row to Feature Plans table |
+| Feature plan completed | Update status to `completed` |
+| Feature plan started | Update status to `in_progress` |
+| Dependency changed | Update dependency graph |
+
+### 3c: Apply Update
+
+Edit the epic document with the change. Keep all other content intact.
+
+---
+
+## Step 4: Link Mode
+
+When a new feature plan is created (e.g., via `/create-plan`), link it to the epic:
+
+1. Read the epic document
+2. Add the feature plan to the Feature Plans table
+3. Update the feature plan's `epic_plan` frontmatter to point to the epic
+4. Update dependency graph if needed
+
+---
+
+## Step 5: Sync Status
+
+Scan all linked documents and synchronize status:
+
+1. Read the epic document
+2. For each feature plan in the table:
+   - Read the feature plan
+   - Check if implementation tasks are completed
+   - Update status in epic table
+3. Update requirement doc if all feature plans are completed
+
+---
+
+## Step 6: Summary & Next Steps
+
+```markdown
+## Epic Updated
+
+**File**: docs/ai/planning/epic-{name}.md
+
+### Feature Plans
+| # | Plan | Status |
+|---|------|--------|
+| 1 | feature-{name}-part1.md | {status} |
+| 2 | feature-{name}-part2.md | {status} |
+
+### Next Steps
+- `/create-plan` → Create a feature plan listed in this epic
+- `/execute-plan` → Implement a feature plan
+- `/manage-epic` → Update status or add feature plans
+```
+
+---
+
+## Cross-Linking Rules
+
+When creating or updating documents, ensure cross-links are maintained.
+**Only add links when they exist — never add placeholder/null links.**
+
+### Creating Epic from Requirement (`/manage-epic`)
+1. Epic: set `requirement` frontmatter → req doc path
+2. Req doc: add "Related Plans" section with epic link (this section doesn't exist by default)
+
+### Adding Feature Plan to Epic (`/create-plan` with epic context)
+1. Epic: add row to Feature Plans table
+2. Feature plan: set `epic_plan` frontmatter → epic path
+3. Feature plan: set `requirement` frontmatter → req doc path (from epic)
+4. Feature plan: include Section 0 "Related Documents" with both links
+
+### Creating Feature Plan standalone (`/create-plan` without epic or req)
+1. Feature plan: frontmatter `epic_plan` = null, `requirement` = null
+2. Feature plan: **remove** Section 0 "Related Documents" entirely
+3. No cross-linking needed
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Requirement doc not found | Ask user for path or create requirement first |
+| Epic already exists | Ask: update existing or create new (backup old) |
+| Feature plan not found | Skip link, warn user |
+| Template not found | Use minimal structure from this command |
+
+---
+
+## Notes
+
+- Epic is purely a tracking document — no architecture or implementation details
+- Feature plans contain all implementation details (via `/create-plan`)
+- Requirement doc contains all WHAT details (via `/clarify-requirements`)
+- Epic bridges the gap: tracks WHICH feature plans implement WHICH requirement

package/cli.js

@@ -419,19 +419,6 @@ function installClaudeCode() {
     run(`wget -qO ${claudeMdPath} ${RAW_BASE}/.claude/CLAUDE.md`);
   }
 
-  // Download settings.json from repo (project-level, shareable with team)
-  step("🚚 Downloading Claude Code hooks (.claude/settings.json)...");
-  const claudeSettingsPath = ".claude/settings.json";
-  if (existsSync(claudeSettingsPath)) {
-    skip(`Skipping (already exists): ${claudeSettingsPath}`);
-  } else {
-    try {
-      run(`curl -fsSL ${RAW_BASE}/.claude/settings.json -o ${claudeSettingsPath}`);
-    } catch (_) {
-      run(`wget -qO ${claudeSettingsPath} ${RAW_BASE}/.claude/settings.json`);
-    }
-    success(`Downloaded: ${claudeSettingsPath}`);
-  }
 
   // Download skills folder (always overwrite to get latest)
   step("🚚 Downloading Claude Code skills (.claude/skills)...");

package/docs/ai/planning/epic-template.md

@@ -8,141 +8,39 @@ requirement: {docs/ai/requirements/req-xxx.md or null}
 
 ## 1. Overview
 
-### Problem Statement
-[Brief description of the problem this epic solves]
-
-### Goals
-- [Primary goal]
-- [Secondary goal]
-
-### Success Metrics
-- [How we measure success]
-
----
-
-## 2. Architecture
-
-> **Note**: High-level architecture overview. Detailed implementation goes in task-level plans.
-
-### System Diagram
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  Component  │────▶│  Component  │────▶│  Component  │
-└─────────────┘     └─────────────┘     └─────────────┘
-```
-
-### Key Components
-| Component | Responsibility | Location |
-|-----------|----------------|----------|
-| {Name} | {What it does} | {path/to/} |
-
-### Technology Decisions
-| Decision | Choice | Rationale |
-|----------|--------|-----------|
-| {Area} | {Technology} | {Why this choice} |
-
----
-
-## 3. Task Breakdown
-
-| # | Task | Priority | Status | Blocked By | Plan Doc |
-|---|------|----------|--------|------------|----------|
-| 1 | {Task title} | P{0-4} | {open/in_progress/closed} | {dependencies or -} | {feature-xxx.md or -} |
-| 2 | {Task title} | P{0-4} | {status} | Task 1 | {-} |
-
-### Dependency Graph
-```
-Task 1 ──────────────────────┐
-                             ▼
-Task 3 ───▶ Task 2 ───▶ Task 4
-```
+[1-3 sentences: what this epic delivers and why it needs to be broken into multiple feature plans]
 
 ---
 
-## 4. Data Flow
+## 2. Feature Plans
 
-### Primary Flow: {Flow Name}
-1. [Step 1]: {description}
-2. [Step 2]: {description}
-3. [Step 3]: {description}
+| # | Feature Plan | Priority | Status | Description |
+|---|-------------|----------|--------|-------------|
+| 1 | [feature-{name}-part1.md](feature-{name}-part1.md) | P{0-4} | open | {Brief description} |
+| 2 | [feature-{name}-part2.md](feature-{name}-part2.md) | P{0-4} | open | {Brief description} |
 
-### Alternative Flow: {Flow Name} (Optional)
-1. [Step 1]: {description}
-
-### Error Handling
-- {Error case}: {How it's handled}
+**Status values:** `open` | `in_progress` | `completed`
 
 ---
 
-## 5. API Contracts (Optional)
-
-> **Note**: Include if epic involves API changes. Keep high-level; details in task plans.
+## 3. Dependency Graph
 
-### Endpoints Overview
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| POST | /api/v1/{resource} | {What it does} |
-| GET | /api/v1/{resource}/:id | {What it does} |
-
-### Key Data Models
 ```
-{ModelName}:
-  - field1: type
-  - field2: type
+Feature 1 ──────────────────┐
+                            ▼
+Feature 3 ───▶ Feature 2 ───▶ Feature 4
 ```
 
 ---
 
-## 6. Key Decisions & Trade-offs
-
-| Decision | Options Considered | Choice | Trade-off |
-|----------|-------------------|--------|-----------|
-| {Decision area} | {Option A, Option B} | {Chosen} | {What we gain/lose} |
-
----
-
-## 7. Risks & Mitigations
-
-| Risk | Impact | Probability | Mitigation |
-|------|--------|-------------|------------|
-| {Risk description} | High/Medium/Low | High/Medium/Low | {How to mitigate} |
-
----
-
-## 8. Dependencies
-
-### External
-- {External service/API}: {What we need from it}
-
-### Internal
-- {Internal service/team}: {What we need from it}
-
-### Blockers
-- [ ] {Blocker that must be resolved before starting}
-
----
-
-## 9. Milestones (Optional)
-
-> **Note**: Focus on task groupings and sequence, not time estimates.
-
-| Milestone | Tasks | Description |
-|-----------|-------|-------------|
-| {Milestone 1} | Task 1, Task 2 | {What this milestone delivers} |
-| {Milestone 2} | Task 3, Task 4 | {What this milestone delivers} |
-
----
-
-## 10. References
+## 4. Related Documents
 
-- **Requirement Doc**: [req-{name}.md](../requirements/req-{name}.md)
-- **Related Epics**: {links to related epic plans}
-- **External Docs**: {links to external resources}
+- **Requirement**: [req-{name}.md](../requirements/req-{name}.md)
 
 ---
 
 ## Changelog
 
-| Date | Author | Change |
-|------|--------|--------|
-| {YYYY-MM-DD} | {name} | Initial epic plan created |
+| Date | Change |
+|------|--------|
+| {YYYY-MM-DD} | Epic created |

package/docs/ai/planning/feature-template.md

@@ -3,12 +3,18 @@
 Note: All content in this document must be written in English.
 
 ---
-epic_plan: {docs/ai/planning/epic-xxx.md or null}
+epic_plan: null
+requirement: null
 ---
 
-## 0. Requirements Reference (Optional)
+## 0. Related Documents (Optional — remove if no linked docs)
 
-- **Requirement Doc**: [req-{feature-name}.md](../requirements/req-{feature-name}.md)
+| Type | Document |
+|------|----------|
+| Requirement | [req-{name}.md](../requirements/req-{name}.md) |
+| Epic | [epic-{name}.md](epic-{name}.md) |
+
+> **Note**: Remove this entire section if no requirement or epic is linked. This section is added by `/manage-epic` or `/create-plan` when context is provided.
 
 ---
 
@@ -262,30 +268,75 @@ epic_plan: {docs/ai/planning/epic-xxx.md or null}
 
 - [ ] [ACTION] path/to/file — Summary of change
   ```
-  Pseudo-code:
-  - Step 1: describe what will be done
-  - Step 2: validation or key logic
-  - Step 3: output or return value
+  Function: functionName(param1: type, param2: type) OR Endpoint: METHOD /path
+
+  Input validation:
+    - param1: [validation rules, constraints, format]
+    - param2: [validation rules, constraints, format]
+
+  Logic flow:
+    1. [Step with specific values/thresholds]
+    2. [Branching: if X then Y, else Z]
+    3. [External calls: DB queries, API calls with params]
+    4. [Data transformations with format]
+
+  Return: { field1: type, field2: type } | Error(code, message)
+
+  Edge cases:
+    - [Scenario] → [Handler/Response]
+    - [Error case] → [HTTP status + message OR error handling]
+
+  Dependencies: [Other functions/modules/APIs called]
   ```
 
 - [ ] [ACTION] path/to/file — Summary of change
   ```
-  Pseudo-code:
-  - ...
+  Function: ...
+
+  Input validation:
+    - ...
+
+  Logic flow:
+    1. ...
+
+  Return: ...
+
+  Edge cases:
+    - ...
+
+  Dependencies: ...
   ```
 
 ### Phase 2: [Phase Name]
 
 - [ ] [ACTION] path/to/file — Summary of change
   ```
-  Pseudo-code:
-  - ...
+  Function: ...
+
+  Input validation:
+    - ...
+
+  Logic flow:
+    1. ...
+
+  Return: ...
+
+  Edge cases:
+    - ...
+
+  Dependencies: ...
   ```
 
 Notes:
 - ACTION must be one of: ADDED | MODIFIED | DELETED | RENAMED
 - For MODIFIED files, use sub-bullets for each distinct logic change and include line ranges
-- Pseudo-code shows logic structure and key steps, not actual implementation code
+- Pseudo-code format uses structured sections for clarity:
+  - **Function/Endpoint**: Signature or route definition
+  - **Input validation**: All validation rules, data types, constraints
+  - **Logic flow**: Step-by-step with specific values, branches, external calls
+  - **Return**: Success response structure + error formats
+  - **Edge cases**: Error scenarios with handlers (HTTP status, messages, fallbacks)
+  - **Dependencies**: External modules, APIs, database tables
 - Each phase groups related tasks; phases execute sequentially
 - Use only one phase for small features (≤ 5 tasks); use multiple phases for larger features
 

package/docs/ai/requirements/req-template.md

@@ -240,4 +240,5 @@ See: [UI/UX Design Document](agents/uiux-{name}.md)
 
 1. [ ] Review this requirement document
 2. [ ] Address open questions
-3. [ ] Run `/create-plan` to generate implementation plan
+3. [ ] Run `/create-plan` to generate implementation plan (small feature)
+4. [ ] Run `/manage-epic` to break into feature plans (large feature)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-init",
-  "version": "7.0.0",
+  "version": "7.2.0",
   "description": "Initialize AI workflow docs & commands into any repo with one command",
   "bin": {
     "ai-workflow-init": "./cli.js"

package/.claude/commands/init-chat.md

@@ -1,38 +0,0 @@
----
-name: init-chat
-description: Initializes chat by loading and aligning to AGENTS.md project rules.
----
-
-## Goal
-
-Initialize a new chat by loading and aligning to `CLAUDE.md` so the AI agent consistently follows project rules (workflow, tooling, communication, language mirroring) from the first message.
-
-## What this command does
-
-1. Read `CLAUDE.md` and extract the actionable rules.
-2. Summarize responsibilities and constraints the agent must follow in this session.
-3. Confirm language-mirroring: respond in the user's chat language; default to English if the user's language is unclear or ambiguous.
-4. Acknowledge the 4-phase workflow and TODO discipline for future commands.
-
-## Steps
-
-1. Open and read `CLAUDE.md` (project root).
-2. Read `docs/ai/project/CODE_CONVENTIONS.md` and `docs/ai/project/PROJECT_STRUCTURE.md` if they exist in the repository.
-3. Produce a short confirmation in the chat including:
-   - Workflow alignment: Plan → Implement → Test → Review
-   - Tooling strategy: semantic search first; parallelize independent steps
-   - Communication: minimal Markdown; status updates; high-signal summaries; mirror user language (default English if unclear)
-   - Code presentation: code references for existing code; fenced blocks for new code
-   - TODO policy: create/update todos; keep only one `in_progress`
-4. If any section is missing or unclear, ask a single concise clarification question; otherwise proceed silently in future commands.
-
-## Output format (concise)
-
-- Use the language of the triggering user message (mirror). If ambiguous, use English.
-- One short paragraph confirming alignment + a 4–6 bullet checklist of the above items.
-- No code unless strictly needed.
-
-## Notes
-
-- This command is idempotent—safe to re-run at the start of any chat.
-- It does not modify existing files; it only sets expectations for subsequent commands.

package/.claude/commands/modify-plan.md

@@ -1,208 +0,0 @@
----
-name: modify-plan
-description: Modify plan and code after implementation; support revert or apply new approach.
----
-
-## Goal
-
-Modify a feature plan after partial/full implementation. Support reverting to a previous git state or applying new requirement changes with both code and documentation sync.
-
-## Prerequisites
-
-- Feature name (kebab-case, e.g., `user-authentication`)
-- Planning doc exists: `docs/ai/planning/feature-{name}.md`
-- Git repo initialized (for tracking code state)
-
-## Workflow Alignment
-
-- Provide brief status updates (1–3 sentences) before/after important actions.
-- Update planning doc when making changes.
-- Do NOT auto-commit; user reviews all changes before pushing.
-
-## Step 1: Load Current State
-
-Ask for feature name (must be kebab-case).
-
-Load and summarize:
-
-1. **Planning doc**: Current goal, scope, implementation phases, completion status
-
-Display summary:
-
-```
-Feature: user-authentication
-Plan: Create user login + registration endpoints
-
-Implementation Progress:
-- Phase 1 (Database): Complete [x]
-  Files: src/db/schema.ts
-- Phase 2 (API Endpoints): In Progress [3/4]
-  Files: src/api/users.ts, src/api/auth.ts
-- Phase 3 (Frontend): Not Started [ ]
-  Files: src/components/Login.tsx
-
-Total files touched: 4
-```
-
-## Step 2: Scope of Change (Q&A)
-
-Ask user what's changing:
-
-**1. Type of modification:**
-a) Modify goal/scope (entire plan changes)
-b) Modify specific phase(s) (tactical change)
-c) Revert to previous approach (git reset)
-d) Other (describe)
-
-**2a. If modifying goal/scope:**
-
-- What's the new goal/scope?
-- How does it impact existing tasks?
-
-**2b. If modifying specific phase(s):**
-
-- Which phase(s)? (list by name)
-- What requirement/approach is changing?
-
-**2c. If reverting approach:**
-
-- Show last 5 commits; ask which to revert to
-- Or reset to specific phase (revert all code changes after phase X)?
-
-## Step 3: Apply Changes
-
-### Option A: Revert to Previous Git State
-
-If user selects revert:
-
-1. **Identify affected files & changes**:
-
-   - Parse planning doc; list all files modified in affected phase(s)
-   - Show file list that needs reverting:
-     ```
-     Files to revert (manual):
-     - src/api/users.ts (lines 45–120)
-     - src/db/schema.ts (lines 10–30)
-     - tests/api.test.ts (delete entire file)
-     ```
-
-2. **Manual revert guidance**:
-
-   - For MODIFIED files: show current state vs. target state (code snippets/line ranges)
-   - For DELETED files: ask user to delete manually
-   - Ask: "Ready to manually revert these files?"
-
-3. **If user confirms**:
-
-   - User manually reverts files (copy-paste old code back, undo in IDE, etc.)
-   - Update planning doc:
-
-     - Mark affected phases/tasks `[ ]` (reset to pending)
-     - Add "Modification History" entry:
-
-       ```
-       ## Modification History
-
-       ### Revert [Date]: {Reason}
-       - **Reverted phases**: Phase X, Y
-       - **Reason**: [user provided]
-       - **Files manually reverted**: [list]
-       - **Affected tasks reset**: [ ] Task 1, [ ] Task 2, ...
-       ```
-
-4. **Result**: Docs updated; tasks reset; ready to re-implement with new approach
-
-### Option B: Apply New Changes
-
-If user selects new approach:
-
-1. **Update planning doc**:
-
-   - Modify goal/scope section if changed
-   - Update affected task(s) with new approach
-   - Update pseudo-code to match new approach
-   - Add "Modification History" section:
-
-     ```
-     ## Modification History
-
-     ### Change [Date]: {Title}
-     - **Previous approach**: [original details]
-     - **New approach**: [new details]
-     - **Reason**: [user provided]
-     - **Affected phases**: Phase X, Y
-     ```
-
-2. **Update implementation phases**:
-
-   - For affected phases:
-     - Modify pseudo-code to match new approach
-     - Reset incomplete tasks `[ ]` (if approach changed significantly)
-   - Keep completed tasks as-is (do not re-implement)
-   - Update "Implementation Plan" section with new structure (files/logic outline)
-
-3. **Show git impact**:
-   - Highlight files that may need re-editing
-   - Ask: "Ready to re-implement with new approach?" (yes/no)
-
-## Step 4: Confirmation & Audit Trail
-
-Before finalizing, show:
-
-1. **Updated planning doc** snippet (modified sections)
-2. **Git state** (files that will be changed)
-
-Ask: **"Apply changes and update doc?"** (yes/no)
-
-If **yes**:
-
-- Save updated planning doc
-- If revert: `git status` shows reverted files (unstaged)
-- If new approach: doc updated; code changes staged for review
-
-If **no**:
-
-- Rollback changes to doc
-- Discard any temporary changes
-
-## Step 5: Next Actions
-
-**After manual revert**:
-
-- "Docs updated. Affected tasks reset to `[ ]`. Run `/execute-plan` to re-implement Phase X with new approach."
-
-**After apply new approach**:
-
-- If only pseudo-code/docs changed (no code revert needed): "Continue current phase with `/execute-plan`."
-- If code changes needed (revert old approach + implement new): "Manually update code files first, then run `/execute-plan`."
-- "When done, run `/code-review` to validate standards."
-
-## Important Notes
-
-- **Manual revert**: User manually reverts code files (no git reset); AI guides the process
-- **Multi-feature safe**: Works when implementing multiple features simultaneously (selective revert possible)
-- **Backward compatible**: Works with both phase-based and non-phase-based planning docs
-- **Audit trail**: "Modification History" section preserves decision rationale and affected files
-- **Idempotent**: Safe to re-run; modification history accumulates
-- **Safe defaults**: Asks confirmation before any changes; user always has final say
-
-## Example Flow
-
-```
-User: I want to modify plan
-Agent: Load state, show summary
-
-User: Revert Phase 2 (API Endpoints) - use different auth approach
-Agent: Identify affected files (src/api/users.ts, src/api/auth.ts)
-       Show current state vs. target state (pseudo-code + old implementation)
-       Ask: Ready to manually revert these files?
-
-User: Yes, I'll manually revert
-Agent: (User manually copies old code back or undoes changes in IDE)
-       Update planning doc:
-       - Mark Phase 2 tasks [ ] (reset)
-       - Add Modification History: Phase 2 reverted, reason: better auth strategy
-
-Agent: Phase 2 reset. Ready to re-implement with new auth approach?
-       Run: /execute-plan
-```