ai-workflow-init 2.0.0 → 3.1.0

package/.cursor/CLAUDE.md

@@ -0,0 +1,114 @@
+# AI Agent Workflow Standards
+
+## Core Coding Philosophy
+
+Apply these principles when providing solutions, generating code, or making technical decisions:
+
+### 1. Simplicity First
+- Choose the simplest solution that meets requirements
+- Avoid over-engineering and unnecessary abstractions
+- Simple code = fewer bugs, easier to maintain, easier to understand
+- Ask: "Can this be done more simply while still working?"
+- Complexity is a last resort, not a first choice
+
+### 2. Deep Understanding
+- Understand requirements fully before planning or coding
+- If unclear about requirement, flow, edge cases, or expected behavior → Ask the user
+- Never assume or guess - clarification prevents wasted effort
+- Ask questions like:
+  - "What should happen when X occurs?"
+  - "How should the system behave if Y fails?"
+  - "Is this the expected flow: A → B → C?"
+
+### 3. Multiple Options
+- Provide 2-5 solution options for each problem when appropriate
+- Present trade-offs clearly: pros/cons, complexity, performance, maintainability
+- Format: "Option 1: [approach] - Pros: [...] Cons: [...]"
+- Let user choose based on their context and priorities
+- Not every problem has one "best" solution
+
+### 4. Think Ahead
+- While keeping solutions simple, consider future implications:
+  - How will this scale with more data/users?
+  - What if requirements change slightly?
+  - Are there security vulnerabilities?
+  - What are performance bottlenecks?
+- Balance: Simple now + adaptable for reasonable future needs
+- Do not build for hypothetical futures, but be aware of likely changes
+
+**Philosophy in practice:**
+- Simplicity: Use built-in array methods instead of custom loop logic
+- Deep Understanding: "Should this API return 404 or 400 for invalid IDs?"
+- Multiple Options: "We can use: 1) localStorage (simple), 2) IndexedDB (scalable), or 3) Backend API (persistent)"
+- Think Ahead: "This works for 100 items, but consider pagination for 10,000+"
+
+---
+
+## Core Workflow: Plan → Implement → Test → Review
+
+### Workflow Alignment
+- **Plan:** Create feature planning doc at `docs/ai/planning/feature-{name}.md` before coding. Do not start until planning exists and is agreed.
+- **Implement:** Provide 1-3 sentence status updates before operations. Use file editing tools, not copy-paste. Update checkboxes `[ ]` → `[x]` in planning doc.
+- **Test:** Run linter/type-check/build on changed files after each batch. Auto-fix issues (up to 3 attempts) before asking for help.
+- **Review:** When complete, validate against planning doc acceptance criteria and CODE_CONVENTIONS.md.
+
+## File Structure
+
+### Planning Documents
+- Location: `docs/ai/planning/feature-{name}.md` (kebab-case)
+- Must include: Goal, Acceptance Criteria (GWT), Risks, Implementation Phases, Follow-ups
+- Template: `docs/ai/planning/feature-template.md`
+
+### Project Standards
+- Coding conventions: `docs/ai/project/CODE_CONVENTIONS.md`
+- Architecture guide: `docs/ai/project/PROJECT_STRUCTURE.md`
+- Language templates: `docs/ai/project/template-convention/`
+
+## Tooling Strategy
+- Prefer semantic search across codebase; use grep only for exact matches
+- Default to parallel execution for independent operations
+- Quality tools: ESLint, TypeScript, Prettier (auto-format/auto-fix when possible)
+
+## Communication
+- Use Markdown only when necessary; backticks for `files/dirs/functions/classes`
+- Status updates before/after important actions
+- Mirror user's chat language; code/comments always in English
+
+## Code Presentation
+- Existing code: cite with `startLine:endLine:filepath` (no language tag)
+- New code: fenced blocks with language tag, no line numbers
+
+## TODO Policy
+- For medium/large tasks: create todos (≤14 words, verb-led)
+- Keep only ONE `in_progress` item
+- Update immediately after progress; mark completed upon finish
+
+## Git Workflow
+- Feature branches: `feature/{name}` (match planning doc name)
+- Commit format: `[phase] brief description`
+- Examples: `[planning] create user auth plan`, `[phase-1] implement database schema`
+
+## Slash Commands
+- `/create-plan` - Generate planning doc
+- `/execute-plan` - Implement tasks from planning doc
+- `/modify-plan` - Modify plan after implementation
+- `/code-review` - Validate against standards
+- `/generate-standards` - Update CODE_CONVENTIONS.md
+- `/writing-test` - Generate tests from acceptance criteria
+- `/init-chat` - Load project rules (AGENTS.md)
+
+## Quality Gates
+### Before marking task complete:
+- Code matches planning doc specification
+- Linting passes (no warnings)
+- Type checking passes (if applicable)
+- Build succeeds (if applicable)
+- Checkbox updated in planning doc: `[x]`
+
+---
+
+**Claude Code Specifics:**
+- This file is automatically loaded every session
+- Commands inherit these standards
+- Use `/context` to see loaded memory
+- Use `/usage` to monitor token consumption

package/.cursor/commands/check-implementation.md

@@ -1,22 +1,31 @@
-Compare current implementation against planning and implementation notes.
-
-## Workflow Alignment
-- Provide brief status updates (1–3 sentences) before/after important actions.
-- Provide a high-signal summary at completion highlighting key mismatches and next steps.
-
-1) Ask me for:
-- Feature name (if not provided)
-- Then locate docs by feature name:
-  - Planning: `docs/ai/planning/feature-{name}.md`
-  - Implementation (optional): `docs/ai/implementation/feature-{name}.md`
-
-2) Validation Scope (no inference):
-- Verify code follows the acceptance criteria from the planning doc
-- Verify code matches the steps/changes in the implementation notes (when present)
-- Do NOT invent or infer alternative logic beyond what the docs specify
-
-3) Output
-- List concrete mismatches between code and docs
-- List missing pieces the docs require but code lacks
-- Short actionable next steps
-
+---
+name: check-implementation
+description: Validates implementation against planning doc.
+---
+
+Compare current implementation against planning doc.
+
+## Workflow Alignment
+
+- Provide brief status updates (1–3 sentences) before/after important actions.
+- Provide a high-signal summary at completion highlighting key mismatches and next steps.
+
+1. Ask me for:
+
+- Feature name (if not provided)
+- Then locate planning doc by feature name:
+  - Planning: `docs/ai/planning/feature-{name}.md`
+
+2. Validation Scope (no inference):
+
+- Verify code follows the acceptance criteria from the planning doc
+- Verify code matches the steps/changes in the implementation plan phases
+- Check that completed tasks (marked `[x]`) have corresponding code changes
+- Do NOT invent or infer alternative logic beyond what the docs specify
+
+3. Output
+
+- List concrete mismatches between code and planning doc
+- List missing pieces the planning doc requires but code lacks
+- List tasks marked complete `[x]` but code not implemented
+- Short actionable next steps

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

@@ -1,132 +1,136 @@
-## Goal
-
-Generate a planning doc at `docs/ai/planning/feature-{name}.md` using the template, with minimal, actionable content aligned to the 4-phase workflow. Also initialize the implementation doc at `docs/ai/implementation/feature-{name}.md` based on the implementation template.
-
-## 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: Clarify Scope (Focused Q&A Guidelines)
-
-Purpose: the agent MUST generate a short, numbered Q&A for the user to clarify scope; keep it relevant, avoid off-topic, and do not build a static question bank.
-
-Principles:
-
-- Quickly classify context: a) Micro-UI, b) Page/Flow, c) Service/API/Data, d) Cross-cutting.
-- Ask only what is missing to produce Goal, Tasks, Risks, and DoD. Keep to 3–7 questions.
-- Do not re-ask what the user already stated; if ambiguous, confirm briefly (yes/no or single choice).
-- Keep each question short and single-purpose; avoid multi-part questions.
-- Answers may be a/b/c or free text; the agent is not required to present fixed option lists.
-
-Output format for Q&A:
-
-- Number questions sequentially starting at 1 (e.g., "1.", "2.").
-- Under each question, provide 2–4 suggested options labeled with lowercase letters + ")" (e.g., "a)", "b)").
-- Keep options short (≤7 words) and add an "other" when useful.
-- Example:
-  1. UI library?
-     a) TailwindCSS b) Bootstrap c) SCSS d) Other
-
-Scope checklist to cover (ask only missing items, based on context):
-
-1. Problem & Users: the core problem and target user groups.
-2. In-scope vs Out-of-scope: what is included and excluded (e.g., MVP, no i18n, no payments).
-3. Acceptance Criteria (GWT): 2–3 key Given–When–Then scenarios.
-4. Constraints & Dependencies: technical constraints, libraries, real API vs mock, deadlines, external deps.
-5. Risks & Assumptions: known risks and key assumptions.
-6. Tasks Overview: 3–7 high-level work items.
-7. Definition of Done: completion criteria (build/test/docs/review).
-
-Adaptive behavior:
-
-- Always reduce questions to what is necessary; once Goal/Tasks/Risks/DoD can be written, stop asking.
-- Prioritize clarifying scope and acceptance criteria before implementation details.
-- If the user already specified items (framework, API/Mock, deadlines, etc.), confirm briefly only.
-
-Then collect inputs (after Q&A):
-
-- Feature name (kebab-case, e.g., `user-authentication`)
-- Short goal and scope
-- High-level tasks overview (3–7 items)
-- Definition of Done (build/test/review/docs)
-
-## Step 2: Load Templates
-
-**Before creating docs, read the following files:**
-
-- `docs/ai/planning/feature-template.md` - Template structure to follow
-- `docs/ai/implementation/feature-template.md` - Template structure to follow for the implementation doc
-
-This template defines the required structure and format. Use it as the baseline for creating the planning doc.
-
-## Step 3: Draft the Plan (auto-generate)
-
-Using the Q&A results and templates, immediately generate the plan without asking for confirmation.
-
-Auto-name feature:
-
-- Derive `feature-{name}` from user prompt + Q&A (kebab-case, concise, specific).
-- Example: "Login Page (HTML/CSS)" → `feature-login-page`.
-- If a file with the same name already exists, append a numeric suffix: `feature-{name}-2`, `feature-{name}-3`, ...
-
-### 3a: Generate Planning Doc
-
-Produce a Markdown doc following `docs/ai/planning/feature-template.md`:
-
-- Match sections from template
-- Fill in content from Q&A inputs
-- Ensure all required sections are present
-
-### 3b: Generate Implementation Doc with Phases
-
-Before creating implementation doc, read `docs/ai/implementation/feature-template.md` to understand phase structure.
-
-**Estimate phase scope**:
-- Count total tasks from planning doc
-- If tasks ≤ 5: use single phase named "Core Implementation"
-- If tasks 6–12: suggest 2–3 phases (group by feature area or dependency order)
-- If tasks > 12: suggest 3–5 phases; prioritize logical grouping
-
-**For each phase, generate**:
-- Phase name (descriptive, e.g., "Database Schema Setup", "API Endpoints", "UI Components")
-- Tasks list: `[ ] [ACTION] path/to/file — Summary`
-- Pseudo-code outline (show logic structure, not real code):
-  ```
-  Pseudo-code:
-  - [Step 1]: what will be done
-  - [Step 2]: validation or check
-  - [Step 3]: data storage/return
-  ```
-
-**Pseudo-code guidelines**:
-- Keep to 3–5 lines per task
-- Show inputs, key logic, outputs
-- Use natural language, not actual syntax
-- Example for "Create user endpoint":
-  ```
-  Pseudo-code:
-  - Parse username + password from request
-  - Validate password strength
-  - Hash password with bcrypt
-  - Store user in database
-  - Return success + user ID
-  ```
-
-Create the following files automatically:
-
-- `docs/ai/planning/feature-{name}.md` - Use structure from `feature-template.md`
-- `docs/ai/implementation/feature-{name}.md` - Use phase structure with pseudo-code per task
-
-Notify the user when done with summary: "Created plan with X phases: Phase 1 (name), Phase 2 (name), ..."
-
-## Step 4: Next Actions
-
-Suggest running `execute-plan` to begin task execution. Implementation work will be driven from `docs/ai/implementation/feature-{name}.md` as the task source.
-Note: Test documentation will be created separately using the `writing-test` command.
-
-## Notes
-
-- This command creates the planning doc and initializes the implementation doc; it does not modify unrelated existing files.
-- Idempotent: safe to re-run; auto-appends numeric suffix if files exist.
+---
+name: create-plan
+description: Generates a feature planning doc with implementation details.
+---
+
+## Goal
+
+Generate a single planning doc at `docs/ai/planning/feature-{name}.md` using the template, with goal, acceptance criteria, risks, and detailed implementation phases with pseudo-code.
+
+## 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: Clarify Scope (Focused Q&A Guidelines)
+
+Purpose: the agent MUST generate a short, numbered Q&A for the user to clarify scope; keep it relevant, avoid off-topic, and do not build a static question bank.
+
+Principles:
+
+- Quickly classify context: a) Micro-UI, b) Page/Flow, c) Service/API/Data, d) Cross-cutting.
+- Ask only what is missing to produce Goal, Tasks, Risks, and DoD. Keep to 3–7 questions.
+- Do not re-ask what the user already stated; if ambiguous, confirm briefly (yes/no or single choice).
+- Keep each question short and single-purpose; avoid multi-part questions.
+- Answers may be a/b/c or free text; the agent is not required to present fixed option lists.
+
+Output format for Q&A:
+
+- Number questions sequentially starting at 1 (e.g., "1.", "2.").
+- Under each question, provide 2–4 suggested options labeled with lowercase letters + ")" (e.g., "a)", "b)").
+- Keep options short (≤7 words) and add an "other" when useful.
+- Example:
+  1. UI library?
+     a) TailwindCSS b) Bootstrap c) SCSS d) Other
+
+Scope checklist to cover (ask only missing items, based on context):
+
+1. Problem & Users: the core problem and target user groups.
+2. In-scope vs Out-of-scope: what is included and excluded (e.g., MVP, no i18n, no payments).
+3. Acceptance Criteria (GWT): 2–3 key Given–When–Then scenarios.
+4. Constraints & Dependencies: technical constraints, libraries, real API vs mock, deadlines, external deps.
+5. Risks & Assumptions: known risks and key assumptions.
+6. Tasks Overview: 3–7 high-level work items.
+7. Definition of Done: completion criteria (build/test/docs/review).
+
+Adaptive behavior:
+
+- Always reduce questions to what is necessary; once Goal/Tasks/Risks/DoD can be written, stop asking.
+- Prioritize clarifying scope and acceptance criteria before implementation details.
+- If the user already specified items (framework, API/Mock, deadlines, etc.), confirm briefly only.
+
+Then collect inputs (after Q&A):
+
+- Feature name (kebab-case, e.g., `user-authentication`)
+- Short goal and scope
+- High-level tasks overview (3–7 items)
+- Definition of Done (build/test/review/docs)
+
+## Step 2: Load Template
+
+**Before creating the plan doc, read the following file:**
+
+- `docs/ai/planning/feature-template.md` - Template structure to follow
+
+This template defines the required structure and format. Use it as the baseline for creating the planning doc.
+
+## Step 3: Draft the Plan (auto-generate)
+
+Using the Q&A results and template, immediately generate the plan without asking for confirmation.
+
+Auto-name feature:
+
+- Derive `feature-{name}` from user prompt + Q&A (kebab-case, concise, specific).
+- Example: "Login Page (HTML/CSS)" → `feature-login-page`.
+- If a file with the same name already exists, append a numeric suffix: `feature-{name}-2`, `feature-{name}-3`, ...
+
+### Generate Single Planning Doc
+
+Produce a Markdown doc following `docs/ai/planning/feature-template.md` with all 5 sections:
+
+1. **Goal & Acceptance Criteria**: Brief goal + Given-When-Then scenarios
+2. **Risks & Assumptions**: Known risks and key assumptions
+3. **Definition of Done**: Build/test/review/docs checklist
+4. **Implementation Plan**:
+   - Summary: Brief description of solution approach (1-3 sentences)
+   - Phases: Detailed tasks with pseudo-code
+5. **Follow-ups**: TODOs or deferred work
+
+**Estimate phase scope**:
+- Count total tasks from Q&A
+- If tasks ≤ 5: use single phase named "Core Implementation"
+- If tasks 6–12: suggest 2–3 phases (group by feature area or dependency order)
+- If tasks > 12: suggest 3–5 phases; prioritize logical grouping
+
+**For each phase, generate**:
+- Phase name (descriptive, e.g., "Database Schema Setup", "API Endpoints", "UI Components")
+- Tasks list: `[ ] [ACTION] path/to/file — Summary`
+- Pseudo-code outline (show logic structure, not real code):
+  ```
+  Pseudo-code:
+  - [Step 1]: what will be done
+  - [Step 2]: validation or check
+  - [Step 3]: data storage/return
+  ```
+
+**Pseudo-code guidelines**:
+- Keep to 3–5 lines per task
+- Show inputs, key logic, outputs
+- Use natural language, not actual syntax
+- Example for "Create user endpoint":
+  ```
+  Pseudo-code:
+  - Parse username + password from request
+  - Validate password strength
+  - Hash password with bcrypt
+  - Store user in database
+  - Return success + user ID
+  ```
+
+Create the file automatically:
+
+- `docs/ai/planning/feature-{name}.md` - Use complete structure from `feature-template.md`
+
+Notify the user when done with summary: "Created plan with X phases: Phase 1 (name), Phase 2 (name), ..."
+
+## Step 4: Next Actions
+
+Suggest running `execute-plan` to begin task execution. Implementation work will be driven from `docs/ai/planning/feature-{name}.md` as the task source.
+
+Note: Test documentation will be created separately using the `writing-test` command.
+
+## Notes
+
+- This command creates a single planning doc with both overview and implementation details.
+- Idempotent: safe to re-run; auto-appends numeric suffix if files exist.

package/.cursor/commands/execute-plan.md

@@ -1,156 +1,141 @@
-## Goal
-
-Execute the feature plan by implementing tasks from the implementation doc and persisting notes to docs.
-
-## Workflow Alignment
-
-- Provide brief status updates (1–3 sentences) before each operation.
-- 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.
-- Perform edits via file editing tools, not by printing code for copy-paste.
-
-### Prerequisites
-
-- Feature name (kebab-case, e.g., `user-authentication`)
-- Implementation doc exists: `docs/ai/implementation/feature-{name}.md`
-- Planning doc exists: `docs/ai/planning/feature-{name}.md` (reference only; tasks are driven by implementation doc)
-
-## Step 1: Gather Context
-
-- Ask for feature name if not provided (must be kebab-case).
-- Load implementation doc: `docs/ai/implementation/feature-{name}.md`.
-- **Load template:** Read `docs/ai/implementation/feature-template.md` to understand required structure.
-
-### 1a: Phase Progress Detection
-
-If implementation doc exists, scan for phase markers (`### Phase X:`):
-
-- **Count total phases** in the document
-- **Detect last completed phase**: Find the highest phase where ALL tasks (checkbox `[x]`) are marked complete
-- **Detect current phase**: Find the first phase with incomplete tasks (`[ ]` marks)
-- **Show summary to user**:
-
-  ```
-  Found 3 phases.
-  - Phase 1 (Database Setup): Complete [x]
-  - Phase 2 (API Endpoints): In Progress [2/4 tasks done]
-  - Phase 3 (Frontend): Not Started
-
-  Resuming Phase 2...
-  ```
-
-If no phases detected (old format):
-
-- Treat entire "Changes" section as single phase (backward compatible)
-
-## Step 2: Build Task Queue
-
-- Parse tasks (checkboxes `[ ]`, `[x]`) from **current phase only** (from phase detection in Step 1a):
-  - Primary source: Tasks under `### Phase X:` with `[ ] [ACTION] ...` entries (incomplete only).
-  - For `[MODIFIED]` files, parse sub-bullets representing distinct logic items with line ranges.
-  - **Skip completed phases** entirely (do not re-execute)
-- Build prioritized task queue (top-to-bottom unless dependencies block).
-- Identify blocked tasks and note reasons.
-
-Note: Do not include Follow-ups section unless explicitly in current phase.
-
-## Step 3: Implement Iteratively (per task)
-
-For each task in queue:
-
-1. **Status update**: Brief note (1–3 sentences) on what will be done.
-2. Plan minimal change set:
-   - Identify files/regions to modify
-   - Map changes to acceptance criteria from plan (reference if needed)
-3. Implement changes:
-   - Write/edit code according to the implementation doc entries (`[ACTION]` items)
-   - Keep changes minimal and incremental
-   - Avoid speculative changes beyond implementation scope
-4. Quick validation:
-   - Run build/compile if available
-   - Run fast unit/smoke tests if available
-   - Fix immediate issues before proceeding
-5. Persist notes to implementation doc:
-   - File: `docs/ai/implementation/feature-{name}.md`
-   - Update the relevant `[ ]` entry to `[x]` when completed
-   - For `MODIFIED` files with sub-bullets, mark each completed sub-bullet `[x]`
-   - Include line ranges and concise summaries as per template
-6. Update implementation doc:
-   - Mark completed tasks `[x]` with brief notes
-   - Mark blocked tasks with reason
-   - Do not mirror completion state in the planning doc
-
-## Step 4: Implementation Doc Structure
-
-**Before creating the implementation doc, ensure you have read:**
-
-- `docs/ai/implementation/feature-template.md` - Template structure to follow
-
-If creating implementation doc for the first task (should already exist from create-plan):
-
-- Use the structure from `feature-template.md` exactly
-- Ensure these sections exist:
-  - `# Implementation Notes: {Feature Name}`
-  - `## Summary` - Brief description of overall approach
-  - `## Changes` — Use `[ ] [ACTION] ...` format with allowed actions ADDED | MODIFIED | DELETED | RENAMED
-    - For MODIFIED, use sub-bullets with line ranges and per-logic summaries
-  - `## Edge Cases` - List of handled edge cases
-  - `## Follow-ups` - TODOs or deferred work
-  - `## Execution Discipline`
-
-## Step 5: Quality Checks
-
-After completing Step 4 for each task batch:
-
-- Detect available tools from project config (e.g., `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, build files) and run the appropriate non-interactive checks.
-- Linting on changed files (prefer non-interactive):
-  - JavaScript/TypeScript: `npx eslint .` or `pnpm eslint .` (add `--max-warnings=0` if desired)
-  - Python: `ruff .` or `flake8 .`
-  - Go: `golangci-lint run` or `go vet ./...`
-  - Rust: `cargo clippy -- -D warnings`
-  - Java: `./gradlew check` or `mvn -q -DskipTests=false -Dspotbugs.failOnError=true verify`
-  - Scope to changed files when possible for speed
-- Type checks (non-emitting where applicable):
-  - TypeScript: `npx tsc --noEmit`
-  - Python: `mypy .` (if configured) or `pyright` if present
-  - Go/Rust/Java: rely on compiler/type system via build step
-- Parallelize lint and type-check when safe; fix issues (up to 3 attempts) before proceeding.
-
-## Step 6: Phase Completion Check (NEW)
-
-After completing all tasks in current phase:
-
-1. **Mark phase complete** in implementation doc (optional visual marker)
-2. **Check remaining phases**:
-   - If more incomplete phases exist:
-     ```
-     ✓ Phase 2 complete!
-     Ready for Phase 3 (Frontend)?
-     Run: /execute-plan
-     ```
-   - If this is final phase:
-     ```
-     ✓ All phases complete!
-     Ready for code review?
-     Run: /code-review
-     ```
-
-## Step 7: Next Actions
-
-After all phases complete:
-
-- Suggest running `code-review` to verify against standards
-- Suggest running `writing-test` if edge cases need coverage
-- Suggest running `check-implementation` to validate alignment with implementation entries
-
-If phases remain:
-
-- User runs `/execute-plan` again; Phase detection (Step 1a) will resume correctly
-
-## Notes
-
-- Keep code changes minimal and focused on implementation tasks
-- Document all changes in the implementation doc; use checkboxes to track progress
-- Avoid implementing features not in the implementation doc scope
-- Modifies source code per implementation scope; updates `docs/ai/implementation/feature-{name}.md`. Does not modify unrelated files.
-- Idempotent: safe to re-run; updates checkboxes deterministically.
+---
+name: execute-plan
+description: Executes the planning doc tasks, edits code, and persists notes.
+---
+
+## Goal
+
+Execute the feature plan by implementing tasks from the planning doc and updating task checkboxes as work progresses.
+
+## Workflow Alignment
+
+- Provide brief status updates (1–3 sentences) before each operation.
+- 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.
+- Perform edits via file editing tools, not by printing code for copy-paste.
+
+### Prerequisites
+
+- Feature name (kebab-case, e.g., `user-authentication`)
+- Planning doc exists: `docs/ai/planning/feature-{name}.md`
+
+## Step 1: Gather Context
+
+- Ask for feature name if not provided (must be kebab-case).
+- Load planning doc: `docs/ai/planning/feature-{name}.md`.
+- **Load template:** Read `docs/ai/planning/feature-template.md` to understand required structure.
+
+### 1a: Phase Progress Detection
+
+If planning doc exists, scan for phase markers (`### Phase X:`):
+
+- **Count total phases** in the document
+- **Detect last completed phase**: Find the highest phase where ALL tasks (checkbox `[x]`) are marked complete
+- **Detect current phase**: Find the first phase with incomplete tasks (`[ ]` marks)
+- **Show summary to user**:
+
+  ```
+  Found 3 phases.
+  - Phase 1 (Database Setup): Complete [x]
+  - Phase 2 (API Endpoints): In Progress [2/4 tasks done]
+  - Phase 3 (Frontend): Not Started
+
+  Resuming Phase 2...
+  ```
+
+If no phases detected (old format):
+
+- Treat entire "Implementation Plan" section as single phase (backward compatible)
+
+## Step 2: Build Task Queue
+
+- Parse tasks (checkboxes `[ ]`, `[x]`) from **current phase only** (from phase detection in Step 1a):
+  - Primary source: Tasks under `### Phase X:` with `[ ] [ACTION] ...` entries (incomplete only).
+  - For `[MODIFIED]` files, parse sub-bullets representing distinct logic items with line ranges.
+  - **Skip completed phases** entirely (do not re-execute)
+- Build prioritized task queue (top-to-bottom unless dependencies block).
+- Identify blocked tasks and note reasons.
+
+Note: Do not include Follow-ups section unless explicitly in current phase.
+
+## Step 3: Implement Iteratively (per task)
+
+For each task in queue:
+
+1. **Status update**: Brief note (1–3 sentences) on what will be done.
+2. Plan minimal change set:
+   - Identify files/regions to modify
+   - Map changes to acceptance criteria from plan (reference if needed)
+3. Implement changes:
+   - Write/edit code according to the planning doc entries (`[ACTION]` items)
+   - Keep changes minimal and incremental
+   - Avoid speculative changes beyond implementation scope
+4. Quick validation:
+   - Run build/compile if available
+   - Run fast unit/smoke tests if available
+   - Fix immediate issues before proceeding
+5. Persist notes to planning doc:
+   - File: `docs/ai/planning/feature-{name}.md`
+   - Update the relevant `[ ]` entry to `[x]` when completed
+   - For `MODIFIED` files with sub-bullets, mark each completed sub-bullet `[x]`
+   - Include line ranges and concise summaries as per template
+6. Update planning doc:
+   - Mark completed tasks `[x]` with brief notes
+   - Mark blocked tasks with reason
+
+## Step 4: Quality Checks
+
+After completing each task batch:
+
+- Detect available tools from project config (e.g., `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, build files) and run the appropriate non-interactive checks.
+- Linting on changed files (prefer non-interactive):
+  - JavaScript/TypeScript: `npx eslint .` or `pnpm eslint .` (add `--max-warnings=0` if desired)
+  - Python: `ruff .` or `flake8 .`
+  - Go: `golangci-lint run` or `go vet ./...`
+  - Rust: `cargo clippy -- -D warnings`
+  - Java: `./gradlew check` or `mvn -q -DskipTests=false -Dspotbugs.failOnError=true verify`
+  - Scope to changed files when possible for speed
+- Type checks (non-emitting where applicable):
+  - TypeScript: `npx tsc --noEmit`
+  - Python: `mypy .` (if configured) or `pyright` if present
+  - Go/Rust/Java: rely on compiler/type system via build step
+- Parallelize lint and type-check when safe; fix issues (up to 3 attempts) before proceeding.
+
+## Step 5: Phase Completion Check
+
+After completing all tasks in current phase:
+
+1. **Mark phase complete** in planning doc (optional visual marker)
+2. **Check remaining phases**:
+   - If more incomplete phases exist:
+     ```
+     ✓ Phase 2 complete!
+     Ready for Phase 3 (Frontend)?
+     Run: /execute-plan
+     ```
+   - If this is final phase:
+     ```
+     ✓ All phases complete!
+     Ready for code review?
+     Run: /code-review
+     ```
+
+## Step 6: Next Actions
+
+After all phases complete:
+
+- Suggest running `code-review` to verify against standards
+- Suggest running `writing-test` if edge cases need coverage
+- Suggest running `check-implementation` to validate alignment with planning entries
+
+If phases remain:
+
+- User runs `/execute-plan` again; Phase detection (Step 1a) will resume correctly
+
+## Notes
+
+- Keep code changes minimal and focused on planning tasks
+- Document all changes by updating checkboxes in the planning doc
+- Avoid implementing features not in the planning doc scope
+- Modifies source code per planning scope; updates `docs/ai/planning/feature-{name}.md`. Does not modify unrelated files.
+- Idempotent: safe to re-run; updates checkboxes deterministically.

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

@@ -1,3 +1,8 @@
+---
+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.
@@ -6,13 +11,12 @@ Modify a feature plan after partial/full implementation. Support reverting to a
 
 - Feature name (kebab-case, e.g., `user-authentication`)
 - Planning doc exists: `docs/ai/planning/feature-{name}.md`
-- Implementation doc exists: `docs/ai/implementation/feature-{name}.md`
 - Git repo initialized (for tracking code state)
 
 ## Workflow Alignment
 
 - Provide brief status updates (1–3 sentences) before/after important actions.
-- Update both planning and implementation docs when making changes.
+- Update planning doc when making changes.
 - Do NOT auto-commit; user reviews all changes before pushing.
 
 ## Step 1: Load Current State
@@ -21,8 +25,7 @@ Ask for feature name (must be kebab-case).
 
 Load and summarize:
 
-1. **Planning doc**: Current goal, scope, tasks overview
-2. **Implementation doc**: Current phases, completion status, files affected
+1. **Planning doc**: Current goal, scope, implementation phases, completion status
 
 Display summary:
 
@@ -46,31 +49,35 @@ Total files touched: 4
 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 (manual revert)
-   d) Other (describe)
+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?
+
+- 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?
+
+- Which phase(s)? (list by name)
+- What requirement/approach is changing?
 
 **2c. If reverting approach:**
-   - Which phase to revert?
-   - Or revert all code changes after phase X?
+
+- 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 Approach (Manual)
+### Option A: Revert to Previous Git State
 
 If user selects revert:
 
 1. **Identify affected files & changes**:
-   - Parse implementation doc; list all files modified in affected phase(s)
+
+   - Parse planning doc; list all files modified in affected phase(s)
    - Show file list that needs reverting:
      ```
      Files to revert (manual):
@@ -80,15 +87,19 @@ If user selects revert:
      ```
 
 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 implementation doc:
+   - Update planning doc:
+
      - Mark affected phases/tasks `[ ]` (reset to pending)
      - Add "Modification History" entry:
+
        ```
        ## Modification History
 
@@ -106,9 +117,12 @@ If user selects revert:
 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
 
@@ -119,12 +133,13 @@ If user selects new approach:
      - **Affected phases**: Phase X, Y
      ```
 
-2. **Update implementation doc**:
+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 "Changes" section with new structure (files/logic outline)
+   - Update "Implementation Plan" section with new structure (files/logic outline)
 
 3. **Show git impact**:
    - Highlight files that may need re-editing
@@ -135,26 +150,29 @@ If user selects new approach:
 Before finalizing, show:
 
 1. **Updated planning doc** snippet (modified sections)
-2. **Updated implementation doc** snippet (phase changes, pseudo-code)
-3. **Files affected** (files that will be changed)
+2. **Git state** (files that will be changed)
 
-Ask: **"Apply changes and update docs?"** (yes/no)
+Ask: **"Apply changes and update doc?"** (yes/no)
 
 If **yes**:
-- Save updated docs
-- If revert: User manually reverts files (code state updated)
-- If new approach: docs updated; ready for re-implementation
+
+- 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 docs
+
+- 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."
@@ -163,7 +181,7 @@ If **no**:
 
 - **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 implementation docs
+- **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
@@ -176,12 +194,12 @@ 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?
+       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 implementation doc:
+       Update planning doc:
        - Mark Phase 2 tasks [ ] (reset)
        - Add Modification History: Phase 2 reverted, reason: better auth strategy
 

package/cli.js

@@ -75,9 +75,9 @@ function cloneDocsAI(source, dest) {
   run(`npx degit ${source} ${tempDir} --force`);
 
   // Xử lý từng subfolder
-  const subfolders = ["implementation", "planning", "testing"];
+  const subfolders = ["planning", "testing"];
 
-  // Xử lý folders: implementation, planning, testing
+  // Xử lý folders: planning, testing
   for (const subfolder of subfolders) {
     const tempSubfolder = path.join(tempDir, subfolder);
     const destSubfolder = path.join(dest, subfolder);
@@ -203,6 +203,7 @@ async function main() {
     }
     step("🚚 Downloading Cursor agent commands (.cursor/commands)...");
     run(`npx degit ${REPO}/.cursor/commands .cursor/commands --force`);
+
   }
 
   // Clone GitHub Copilot prompts (luôn ghi đè)
@@ -212,6 +213,7 @@ async function main() {
     }
     step("🚚 Downloading GitHub Copilot prompts (.github/prompts)...");
     run(`npx degit ${REPO}/.github/prompts .github/prompts --force`);
+
   }
 
   // Clone Claude Code commands (luôn ghi đè)
@@ -221,6 +223,34 @@ async function main() {
     }
     step("🚚 Downloading Claude Code commands (.claude/commands)...");
     run(`npx degit ${REPO}/.claude/commands .claude/commands --force`);
+
+    // Download CLAUDE.md (context memory) - only if not exists
+    step("🚚 Downloading Claude Code context memory (.claude/CLAUDE.md)...");
+    const claudeMdPath = ".claude/CLAUDE.md";
+    if (existsSync(claudeMdPath)) {
+      console.log(`⏭️  Skipping (already exists): ${claudeMdPath}`);
+    } else {
+      try {
+        run(`curl -fsSL ${RAW_BASE}/.claude/CLAUDE.md -o ${claudeMdPath}`);
+      } catch (_) {
+        run(`wget -qO ${claudeMdPath} ${RAW_BASE}/.claude/CLAUDE.md`);
+      }
+    }
+
+    // Download hooks.json (always overwrite to get latest)
+    step("🚚 Downloading Claude Code hooks (.claude/hooks.json)...");
+    try {
+      run(`curl -fsSL ${RAW_BASE}/.claude/hooks.json -o .claude/hooks.json`);
+    } catch (_) {
+      run(`wget -qO .claude/hooks.json ${RAW_BASE}/.claude/hooks.json`);
+    }
+
+    // Download skills folder (always overwrite to get latest)
+    step("🚚 Downloading Claude Code skills (.claude/skills)...");
+    if (!existsSync(".claude/skills")) {
+      mkdirSync(".claude/skills", { recursive: true });
+    }
+    run(`npx degit ${REPO}/.claude/skills .claude/skills --force`);
   }
 
   // Clone Cursor prompts (luôn ghi đè)

package/docs/ai/planning/README.md

@@ -7,26 +7,42 @@ description: Feature planning docs and workflow guidelines
 # Planning Documentation
 
 ## Purpose
-This directory contains planning documents for individual features. Each feature follows a structured planning process before implementation.
+This directory contains planning documents for individual features. Each feature plan includes both high-level goals and detailed implementation steps in a single file.
 
 ## Feature Planning Workflow
 
 ### Creating a Feature Plan
 Use the `create-plan` command to generate a new feature plan:
-- Command: `.cursor/commands/create-plan.md`
+- Command: Available in `.cursor/commands/`, `.claude/commands/`, or `.github/prompts/`
 - Output: `docs/ai/planning/feature-{name}.md`
 - Template: `docs/ai/planning/feature-template.md`
 
 ### Feature Plan Structure
-Each feature plan follows the template structure:
-- **Goal**: Objectives, scope, acceptance criteria (Given-When-Then format)
-- **Tasks**: Checklist of high-level work items (3–7 tasks)
-- **Risks/Assumptions**: Key risks and assumptions
-- **Metrics / Definition of Done**: Completion criteria (build/test/review/docs)
-
-### From Plan to Execution (Todos)
-- After the plan is written, generate an execution todo checklist from the plan.
-- Do not start Implementation until the todo list exists and is agreed.
+Each feature plan follows the template structure with 5 sections:
+
+1. **Goal & Acceptance Criteria**: Objectives, scope, and Given-When-Then format
+2. **Risks & Assumptions**: Key risks and assumptions to be aware of
+3. **Definition of Done**: Completion criteria (build/test/review/docs)
+4. **Implementation Plan**:
+   - Summary of solution approach
+   - Phases with detailed tasks and pseudo-code
+5. **Follow-ups**: TODOs or deferred work
+
+### What Makes a Good Plan?
+A good plan helps both humans and AI agents understand:
+- **For humans**: What problem we're solving, why, and how
+- **For AI agents**: Exactly what files to change, what logic to implement, and in what order
+
+The plan should be:
+- Clear enough for a different AI agent to execute independently
+- Detailed enough with pseudo-code to guide implementation
+- Concise enough to avoid information overload
+
+### From Plan to Execution
+- After the plan is written, use the `execute-plan` command to begin implementation
+- The AI agent will read the plan and implement tasks phase by phase
+- Tasks are tracked with checkboxes `[ ]` → `[x]` as they complete
+- Do not start coding until the plan is reviewed and agreed upon
 
 ### Feature Plan Naming Convention
 - Format: `feature-{name}.md` (kebab-case)
@@ -37,7 +53,6 @@ Each feature plan follows the template structure:
 See `feature-template.md` for the exact structure required for feature plans.
 
 ## Related Documentation
-- Implementation notes: `../implementation/`
 - Test plans: `../testing/`
 - Project standards: `../project/`
 

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

@@ -2,29 +2,68 @@
 
 Note: All content in this document must be written in English.
 
-## Goal
-- Objectives, scope, acceptance criteria (Given-When-Then)
+## 1. Goal & Acceptance Criteria
+
+### Goal
+- [Brief description: what problem this solves and why it matters]
 
 ### Acceptance Criteria (Given/When/Then)
-- Given ...
-- When ...
-- Then ...
+- Given [context or initial state]
+- When [action or event occurs]
+- Then [expected result or outcome]
+
+## 2. Risks & Assumptions
+
+### Risks
+- [Potential issues, blockers, or unknowns]
+
+### Assumptions
+- [What we assume is true for this plan to work]
+
+## 3. Definition of Done
+- [ ] Build passes (linter, type checks, compile)
+- [ ] Tests added and passing
+- [ ] Code reviewed and approved
+- [ ] Documentation updated
+
+---
+
+## 4. Implementation Plan
+
+### Summary
+[Brief description of the solution approach in 1-3 sentences]
+
+### Phase 1: [Phase Name]
+
+- [ ] [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
+  ```
 
-## Tasks (overview)
-- [ ] Task 1
-- [ ] Task 2
-- [ ] Task 3
+- [ ] [ACTION] path/to/file — Summary of change
+  ```
+  Pseudo-code:
+  - ...
+  ```
 
-## Risks/Assumptions
-- Key risks / assumptions
+### Phase 2: [Phase Name]
 
-## Observability
-- Logging requirements:
-- Metrics/telemetry:
+- [ ] [ACTION] path/to/file — Summary of change
+  ```
+  Pseudo-code:
+  - ...
+  ```
 
-## Metrics / Definition of Done
-- Build green, tests added, review passed, docs updated
+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
+- Each phase groups related tasks; phases execute sequentially
+- Use only one phase for small features (≤ 5 tasks); use multiple phases for larger features
 
-## Execution Checklist (Todo)
-- Before starting implementation, generate a todo checklist from this plan.
-- Do not start coding until the todo list exists and is agreed.
+## 5. Follow-ups
+- [ ] [TODO item or deferred work]
+- [ ] [Future improvements]

package/package.json

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

package/docs/ai/implementation/README.md

@@ -1,51 +0,0 @@
----
-phase: implementation
-title: Implementation Documentation
-description: Feature implementation notes and tracking
----
-
-# Implementation Documentation
-
-## Purpose
-This directory contains implementation notes for individual features. These docs track what code was written, why, and how it aligns with the plan.
-
-## Implementation Documentation Workflow
-
-### Creating Implementation Notes
-Implementation notes are created automatically during `execute-plan`:
-- Command: `.cursor/commands/execute-plan.md`
-- Output: `docs/ai/implementation/feature-{name}.md`
-- Template: `docs/ai/implementation/feature-template.md`
-
-### Implementation Doc Structure
-Each implementation doc follows the template structure:
-- **Summary**: Brief description of overall solution approach
-- **Changes**: Per-task entries with:
-  - File paths and line ranges
-  - Approach/pattern used
-  - Brief description of changes
-- **Edge Cases**: List of handled edge cases
-- **Follow-ups**: TODOs or deferred work
-
-### Purpose
-Implementation docs serve as:
-- **Audit trail**: What code was written for this feature
-- **Review reference**: For code-review and check-implementation commands
-- **Refactor guide**: Understanding what was done for future improvements
-
-### Execution Discipline
-- Provide a short status update before each meaningful action (1–3 sentences).
-- Perform edits via file editing tools; avoid printing large code for copy-paste.
-- After each batch of edits, run linter/type/build on changed files; auto-fix issues (up to 3 attempts) before requesting review.
-
-## Template Reference
-See `feature-template.md` for the exact structure required for implementation notes.
-
-## Related Documentation
-- Planning docs: `../planning/`
-- Test plans: `../testing/`
-- Project standards: `../project/`
-
----
-
-**Note**: For general implementation patterns and best practices, refer to `../project/CODE_CONVENTIONS.md` and `../project/PROJECT_STRUCTURE.md`.

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

@@ -1,53 +0,0 @@
-# Implementation Notes: {Feature Name}
-
-Note: All content in this document must be written in English.
-
-## Summary
-
-- Short description of the solution approach
-
-## Changes
-
-### Phase 1: [Phase Name]
-
-- [ ] [ACTION] path/to/file (lines: x–y) — Summary of change
-  ```
-  Pseudo-code:
-  - function/logic outline
-  - key variables/state
-  ```
-- [ ] [ACTION] path/to/file (lines: a–b) — Summary of change
-  ```
-  Pseudo-code:
-  - logic structure
-  ```
-
-### Phase 2: [Phase Name]
-
-- [ ] [ACTION] path/to/file — Summary of change
-  ```
-  Pseudo-code:
-  - ...
-  ```
-
-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.
-- Each phase groups related tasks; phases execute sequentially.
-- Use only one phase for small features (≤ 5 tasks); use multiple phases for larger features.
-
-## Edge Cases
-
-- List of handled edge cases
-
-## Follow-ups
-
-- TODOs or deferred work
-
-## Execution Discipline
-
-- Before each edit, provide a short status update describing the next action (1–3 sentences).
-- Perform edits via file editing tools; avoid printing large code blocks for copy-paste.
-- After each batch of edits, run linter/type/build on changed files; auto-fix issues (up to 3 attempts) before requesting review.