ai-workflow-init 3.2.3 → 3.6.0

package/AGENTS.md

@@ -1,24 +1,124 @@
-# AI Agent Guidelines
+# AI Agent Workflow Standards
 
-## Workflow alignment (Plan → Implement → Test → Review)
-- Plan: Before coding, create a feature execution checklist (todo) from the plan. Do not start Implementation until the todo list exists and is agreed.
-- Implementation: Before each operation, write a short status update (1–3 sentences). Perform edits via file editing tools, not by printing code for copy-paste.
-- Testing: After each batch of edits, run linter/typing/build on the changed files; auto-fix issues (up to 3 attempts) before asking for help.
-- Review: When todos are completed and checks pass, provide a concise summary highlighting key changes and their impact.
+## Core Coding Philosophy
 
-## Tooling strategy
-- Prefer semantic search across the codebase; use grep only for exact matches.
-- Default to parallel execution for independent operations; use sequential steps only when dependencies exist.
+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; use backticks for `files/dirs/functions/classes`.
-- Provide status updates before/after important actions; provide a high-signal summary at completion.
-- Mirror the user's chat language in responses (respond in the user's language); default to English if the user's language is unclear or ambiguous.
 
-## Code presentation
-- Existing code: cite using a code reference block with `startLine:endLine:filepath` (no language tag).
-- New code: use fenced code blocks with a language tag, no line numbers, no extra leading indentation.
+- 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]`
 
-## TODO policy
-- For medium/large tasks, create todos (≤14 words, verb-led). Keep only one `in_progress` item.
-- Update the todo list immediately after progress; mark completed and close upon finish.
+---

package/cli.js

@@ -75,9 +75,9 @@ function cloneDocsAI(source, dest) {
   run(`npx degit ${source} ${tempDir} --force`);
 
   // Xử lý từng subfolder
-  const subfolders = ["planning", "testing"];
+  const subfolders = ["planning", "testing", "requirements"];
 
-  // Xử lý folders: planning, testing
+  // Xử lý folders: planning, testing, requirements
   for (const subfolder of subfolders) {
     const tempSubfolder = path.join(tempDir, subfolder);
     const destSubfolder = path.join(dest, subfolder);
@@ -86,7 +86,7 @@ function cloneDocsAI(source, dest) {
       mkdirSync(destSubfolder, { recursive: true });
 
       // Chỉ copy file template và README.md
-      const filesToCopy = ["README.md", "feature-template.md"];
+      const filesToCopy = ["README.md", "feature-template.md", "req-template.md"];
 
       for (const file of filesToCopy) {
         const srcFile = path.join(tempSubfolder, file);
@@ -96,6 +96,15 @@ function cloneDocsAI(source, dest) {
           cpSync(srcFile, destFile, { force: true });
         }
       }
+
+      // Tạo folder archive nếu là requirements hoặc planning
+      if (subfolder === "requirements" || subfolder === "planning") {
+        const archiveDir = path.join(destSubfolder, "archive");
+        if (!existsSync(archiveDir)) {
+          mkdirSync(archiveDir, { recursive: true });
+          console.log(`📁 Created archive folder: docs/ai/${subfolder}/archive`);
+        }
+      }
     }
   }
 

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

@@ -2,6 +2,12 @@
 
 Note: All content in this document must be written in English.
 
+## 0. Requirements Reference (Optional)
+
+- **Requirement Doc**: [req-{feature-name}.md](../requirements/req-{feature-name}.md)
+
+---
+
 ## 1. Codebase Context
 
 > **Note**: This section is auto-generated by `/create-plan` exploration phase. Include only if relevant patterns were found.
@@ -23,9 +29,10 @@ Note: All content in this document must be written in English.
 
 ---
 
-## 2. Design Specifications
+## 2a. Design Specifications
 
 > **Note**: This section is for design specifications from any source (Figma, screenshot, detailed description, etc.). Include only if design source was provided.
+> **Important**: Use EITHER Section 2a (Design Specifications) OR Section 2b (Theme Specification), not both. Delete the unused section.
 
 ### Reference
 - **File**: {Figma file name}
@@ -101,10 +108,10 @@ Note: All content in this document must be written in English.
 
 ---
 
-## 2. Theme Specification
+## 2b. Theme Specification (Alternative to 2a)
 
 > **Note**: This section is auto-generated by `/create-plan` theme selection. Include only if theme was selected (no design source provided).
-> **Important**: Use EITHER "Design Specifications" OR "Theme Specification", not both. Any design source (Figma, screenshot, description) takes precedence over theme.
+> **Important**: Use EITHER Section 2a (Design Specifications) OR Section 2b (Theme Specification), not both. Delete the unused section.
 
 ### Selected Theme
 - **Name**: {Theme Name}

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

@@ -0,0 +1,137 @@
+# Requirement: {Feature Name}
+
+Note: All content in this document must be written in English.
+
+---
+
+## 1. Problem Statement
+
+### Context
+[Business/technical context that led to this requirement]
+
+### Problem
+[The specific problem to be solved]
+
+### Impact
+[Consequences if not addressed - business value, user pain points]
+
+---
+
+## 2. User Stories (Optional)
+
+- As a [role], I want [action], so that [benefit]
+- As a [role], I want [action], so that [benefit]
+
+---
+
+## 3. Business Rules (Optional)
+
+| ID | Rule | Description |
+|----|------|-------------|
+| BR-01 | {Rule Name} | {Detailed description} |
+| BR-02 | {Rule Name} | {Detailed description} |
+
+---
+
+## 4. Functional Requirements
+
+| ID | Requirement | Priority | Notes |
+|----|-------------|----------|-------|
+| FR-01 | {Description} | Must | |
+| FR-02 | {Description} | Should | |
+| FR-03 | {Description} | Could | |
+
+**Priority Legend:**
+- **Must**: Critical for release
+- **Should**: Important but not blocking
+- **Could**: Nice to have
+
+---
+
+## 5. Non-Functional Requirements (Optional)
+
+| Category | Requirement |
+|----------|-------------|
+| **Performance** | {e.g., Response time < 200ms, support 1000 concurrent users} |
+| **Security** | {e.g., Authentication required, data encryption} |
+| **Compatibility** | {e.g., Chrome 90+, Safari 14+, mobile responsive} |
+| **Accessibility** | {e.g., WCAG 2.1 AA compliance} |
+| **Scalability** | {e.g., Handle 10x traffic growth} |
+
+---
+
+## 6. Edge Cases & Constraints (Optional)
+
+### Edge Cases
+
+| Case | Expected Behavior |
+|------|-------------------|
+| {Edge case description} | {How system should handle it} |
+| {Edge case description} | {How system should handle it} |
+
+### Constraints
+
+- **Technical**: {e.g., Must use existing auth system}
+- **Business**: {e.g., Budget limit, timeline}
+- **Dependencies**: {e.g., Requires API v2 ready}
+
+---
+
+## 7. Clarifications Log (Optional)
+
+> Questions resolved during requirement gathering sessions
+
+| # | Question | Answer |
+|---|----------|--------|
+| 1 | {Question asked} | {Answer received} |
+| 2 | {Question asked} | {Answer received} |
+
+---
+
+## 8. Out of Scope (Optional)
+
+> Explicitly excluded from this requirement
+
+- {Feature/functionality not included}
+- {Deferred to future iteration}
+- {Related but separate concern}
+
+---
+
+## 9. Acceptance Criteria
+
+### Scenario 1: {Happy Path - Main Flow}
+
+- **Given** [initial context/state]
+- **When** [action performed]
+- **Then** [expected outcome]
+
+### Scenario 2: {Alternative Flow} (Optional)
+
+- **Given** [context]
+- **When** [action]
+- **Then** [outcome]
+
+### Scenario 3: {Error Handling} (Optional)
+
+- **Given** [context]
+- **When** [invalid action/error condition]
+- **Then** [error handling behavior]
+
+---
+
+## 10. References (Optional)
+
+- **Related Docs**: [links to related requirements, designs, etc.]
+- **External Links**: [Jira tickets, Figma, API docs, etc.]
+
+---
+
+## 11. Glossary (Optional)
+
+> Domain-specific terms and definitions. Include only if specialized terminology is used.
+
+| Term | Definition |
+|------|------------|
+| {Term 1} | {Clear definition in project context} |
+| {Term 2} | {Clear definition in project context} |

package/package.json

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