ai-workflow-init 1.0.0

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

@@ -0,0 +1,18 @@
+Compare current implementation against planning and implementation notes.
+
+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
+

package/.cursor/commands/code-review.md

@@ -0,0 +1,67 @@
+You are helping me perform a local code review **before** I push changes. This review is restricted to standards conformance only.
+
+## Step 1: Gather Context (minimal)
+- Ask for feature name if not provided (must be kebab-case).
+- Then locate and read:
+  - Planning doc: `docs/ai/planning/feature-{name}.md` (for file list context only)
+  - Implementation doc: `docs/ai/implementation/feature-{name}.md` (for file list context only)
+
+## Step 2: Standards Focus (only)
+- Load project standards:
+  - `docs/ai/project/CODE_CONVENTIONS.md`
+  - `docs/ai/project/PROJECT_STRUCTURE.md`
+- Review code strictly for violations against these two documents.
+- **Do NOT** provide design opinions, performance guesses, or alternative architectures.
+- **Do NOT** infer requirements beyond what standards explicitly state.
+
+## Step 3: File-by-File Review (standards violations only)
+For every relevant file, report ONLY standards violations per the two docs above. Do not assess broader design or run git commands.
+
+## Step 4: Cross-Cutting Concerns (standards only)
+- Naming consistency and adherence to CODE_CONVENTIONS
+- Structure/module boundaries per PROJECT_STRUCTURE
+
+### Standards Conformance Report (required)
+- After reviewing `CODE_CONVENTIONS.md` and `PROJECT_STRUCTURE.md`, list violations in this exact format:
+```
+- path/to/file.ext — [Rule]: short description of the violated rule
+```
+- Only include clear violations. Group similar violations by file when helpful.
+
+## Step 5: Summarize Findings (rules-focused)
+Provide results in this structure:
+```
+### Summary
+- Blocking issues: [count]
+- Important follow-ups: [count]
+- Nice-to-have improvements: [count]
+
+Severity criteria:
+- Blocking: Violates CODE_CONVENTIONS or PROJECT_STRUCTURE causing build/test failure, security risk, or clear architectural breach.
+- Important: Violations that don't break build but degrade maintainability/performance or developer ergonomics.
+- Nice-to-have: Style/consistency improvements with low impact.
+
+### Detailed Notes
+1. **[File or Component]**
+   - Issue/Observation: ...
+   - Impact: (blocking / important / nice-to-have)
+   - Rule violated: [Rule name from CODE_CONVENTIONS or PROJECT_STRUCTURE]
+   - Recommendation: Fix to comply with [Rule]
+
+2. ... (repeat per finding)
+
+### Recommended Next Steps
+- [ ] Address blocking issues
+- [ ] Fix important violations
+- [ ] Consider nice-to-have improvements
+- [ ] Re-run code review command after fixes
+```
+
+## Step 6: Final Checklist (rules-focused)
+Confirm whether each item is complete (yes/no/needs follow-up):
+- Naming and formatting adhere to CODE_CONVENTIONS
+- Structure and boundaries adhere to PROJECT_STRUCTURE
+
+---
+
+Let me know when you're ready to begin the review.

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

@@ -0,0 +1,71 @@
+
+## 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.
+
+## 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/testing/feature-template.md` - Template structure for test plan skeleton
+
+These templates define the required structure and format. Use them as the baseline for creating feature docs.
+
+## 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`, ...
+
+Create the following files automatically and populate initial content:
+- `docs/ai/planning/feature-{name}.md` - Use structure from `feature-template.md`
+- `docs/ai/testing/feature-{name}.md` - Use structure from testing `feature-template.md` (skeleton)
+
+Do NOT create the implementation file at this step.
+Notify the user when done.
+
+Produce a Markdown doc following the template structure:
+- Match sections from `docs/ai/planning/feature-template.md`
+- Fill in content from Q&A inputs
+- Ensure all required sections are present
+
+## Step 4: Next Actions
+Suggest running `execute-plan` to begin task execution.

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

@@ -0,0 +1,66 @@
+## Goal
+Execute the feature plan by implementing tasks and persisting notes to docs.
+
+### 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 plan: `docs/ai/planning/feature-{name}.md`.
+- **Load template:** Read `docs/ai/implementation/feature-template.md` to understand required structure.
+- Ensure implementation doc exists or will be created: `docs/ai/implementation/feature-{name}.md`.
+
+## Step 2: Build Task Queue
+- Parse tasks (checkboxes `[ ]`, `[x]`) from the plan.
+- Build prioritized task queue (top-to-bottom unless dependencies block).
+- Identify blocked tasks and note reasons.
+
+## Step 3: Implement Iteratively (per task)
+For each task in queue:
+1. Plan minimal change set:
+   - Identify files/regions to modify
+   - Map changes to acceptance criteria from plan
+2. Implement changes:
+   - Write/edit code according to the plan
+   - Keep changes minimal and incremental
+   - Avoid speculative changes beyond plan scope
+3. Quick validation:
+   - Run build/compile if available
+   - Run fast unit/smoke tests if available
+   - Fix immediate issues before proceeding
+4. Persist notes to implementation doc:
+   - File: `docs/ai/implementation/feature-{name}.md`
+   - Append entry per completed task:
+     - Files touched: `path/to/file.ext` (lines: x–y)
+     - Approach/pattern used: brief description
+     - Edge cases handled: list if any
+     - Risks/notes: any concerns
+5. Update planning doc:
+   - Mark completed tasks `[x]` with brief note
+   - Mark blocked tasks with reason
+
+## 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 first task:
+- Use the structure from `feature-template.md` exactly
+- Create `docs/ai/implementation/feature-{name}.md` with:
+  - `# Implementation Notes: {Feature Name}`
+  - `## Summary` - Brief description of overall approach
+  - `## Changes` - Per-task entries with file paths, line ranges, approach
+  - `## Edge Cases` - List of handled edge cases
+  - `## Follow-ups` - TODOs or deferred work
+- Follow the template format strictly
+
+## Step 5: Next Actions
+After completing tasks:
+- 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 plan
+
+## Notes
+- Keep code changes minimal and focused on plan tasks
+- Document all changes in implementation doc for later review/refactor
+- Avoid implementing features not in the plan

package/.cursor/commands/generate-standards.md

@@ -0,0 +1,72 @@
+## Goal
+Generate or update `docs/ai/project/CODE_CONVENTIONS.md` and `PROJECT_STRUCTURE.md` from the current codebase with brief Q&A refinement.
+
+## Step 1: Clarify Scope (3–6 questions max)
+Quick classification and targeted questions:
+- Languages/frameworks detected: confirm correct? (a/b/other)
+- Import/style tools in use: (a) ESLint/Prettier  (b) Other formatter  (c) None
+- Test placement preference: (a) Colocated `*.spec.*`  (b) `__tests__/` directory  (c) Other
+- Error handling strategy: (a) Exceptions/try-catch  (b) Result types  (c) Other
+- Module organization: (a) By feature  (b) By layer  (c) Mixed
+- Any performance/security constraints to encode? (yes/no, brief)
+
+Keep questions short and single-purpose. Stop once sufficient info gathered.
+
+## Step 2: Auto-Discovery
+Analyze repository to infer:
+- Dominant naming patterns:
+  - Variables/functions: camelCase/PascalCase/snake_case
+  - Classes/types: PascalCase
+  - Constants: CONSTANT_CASE/UPPER_SNAKE_CASE
+- Import patterns:
+  - Import order (node/builtin, third-party, internal)
+  - Grouping style
+- Typical folder structure:
+  - Organization under `src/` (by feature/by layer/mixed)
+  - Common directories (components/, utils/, services/, etc.)
+- Test file locations/naming if present:
+  - Colocated patterns
+  - Test directory structure
+- Common patterns observed:
+  - Repository/Service patterns
+  - Factory patterns
+  - Strategy patterns
+  - Other architectural patterns
+
+## Step 3: Draft Standards
+Generate two documents:
+
+### CODE_CONVENTIONS.md
+- Naming conventions (variables, functions, classes, constants)
+- Import order and grouping
+- Formatting tools (ESLint/Prettier/etc.) if detected
+- Function size and complexity guidelines
+- Error handling strategy (exceptions/result types)
+- Test rules (unit first, integration when needed)
+- Comments policy (only for complex logic)
+- Async/await patterns if applicable
+
+### PROJECT_STRUCTURE.md
+- Folder layout summary:
+  - `src/`: source code organization
+  - `docs/ai/**`: documentation structure
+- Module boundaries and dependency direction
+- Design patterns actually observed in codebase
+- Test placement and naming conventions
+- Config/secrets handling summary
+
+## Step 4: Persist
+- Overwrite or create:
+  - `docs/ai/project/CODE_CONVENTIONS.md`
+  - `docs/ai/project/PROJECT_STRUCTURE.md`
+- Add header note: "This document is auto-generated from codebase analysis + brief Q&A. Edit manually as needed."
+
+## Step 5: Next Actions
+- Suggest running `code-review` to validate new standards are being followed
+- Inform user they can manually edit these files anytime
+
+## Notes
+- Focus on patterns actually present in codebase, not ideal patterns
+- Keep generated docs concise and actionable
+- User can refine standards manually after generation
+

package/.cursor/commands/writing-test.md

@@ -0,0 +1,54 @@
+Use `docs/ai/testing/feature-{name}.md` as the source of truth.
+
+## Step 1: Gather Context (minimal)
+- Ask for feature name if not provided (must be kebab-case).
+- **Load template:** Read `docs/ai/testing/feature-template.md` to understand required structure.
+- Then locate docs by convention:
+  - Planning: `docs/ai/planning/feature-{name}.md`
+  - Implementation (optional): `docs/ai/implementation/feature-{name}.md`
+
+Always align test cases with acceptance criteria from the planning doc. If implementation notes are missing, treat planning as the single source of truth.
+
+## Step 2: Scope (simple tests only)
+- Focus on pure functions, small utilities, and isolated component logic.
+- Test edge cases and logic branches.
+- **Do NOT** write complex rendering tests, E2E flows, or integration tests requiring heavy setup.
+- Keep tests simple and fast to run via command line.
+
+## Step 3: Generate Unit Tests
+- List scenarios: happy path, edge cases, error cases.
+- Propose concrete test cases/snippets per main function/module.
+- Ensure tests are deterministic (avoid external IO when possible).
+- Focus on logic validation, not complex UI rendering or user flows.
+
+## Step 4: Placement & Commands
+- Place tests per `PROJECT_STRUCTURE.md`:
+  - Colocated `*.spec.*` files with source, or
+  - Under `__tests__/` mirroring source structure
+- Provide run commands consistent with project:
+  - Example: `npm test -- --run <pattern>` or language-specific runner
+  - Ensure tests can be run individually for quick iteration
+- Keep each test file small and focused.
+
+## Step 5: Coverage Strategy (lightweight)
+- Suggest coverage command if available (e.g., `npm test -- --coverage`).
+- Default targets (adjust if project-specific):
+  - Lines: 80%
+  - Branches: 70%
+- Highlight files still lacking coverage for critical paths.
+
+## Step 6: Update Testing Doc
+- Use structure from `docs/ai/testing/feature-template.md` to populate `docs/ai/testing/feature-{name}.md`.
+- Fill cases/snippets/coverage notes following the template sections:
+  - `## Unit Tests`
+  - `## Integration Tests`
+  - `## Manual Checklist`
+  - `## Coverage Targets`
+- Keep the document brief and actionable.
+- Include run commands for quick verification.
+- Ensure all required sections from template are present.
+
+## Notes
+- Tests should be simple enough to run quickly and verify logic correctness.
+- Avoid complex test setup or mocking unless necessary.
+- Focus on catching logic errors and edge cases, not testing frameworks or flows.

package/.npmignore

@@ -0,0 +1,2 @@
+node_modules
+.git

package/AGENTS.md

@@ -0,0 +1,21 @@
+# AI DevKit Rules (Personal Workflow)
+
+## Documentation Structure
+- `docs/ai/project/` — Project docs (PROJECT_STRUCTURE, CODE_CONVENTIONS, patterns)
+- `docs/ai/planning/` — Feature plans (`feature-{name}.md`)
+- `docs/ai/implementation/` — Implementation notes per feature (`feature-{name}.md`)
+- `docs/ai/testing/` — Test plans per feature (`feature-{name}.md`)
+
+## Development Workflow (4 phases)
+1. Plan: define goals, scope, and acceptance criteria
+2. Implementation: code against acceptance criteria, small and shippable changes
+3. Testing: cover main flows and critical edges
+4. Review: self-review + tool-assisted review, then ship
+
+## Code Style & Standards
+- Follow `docs/ai/project/CODE_CONVENTIONS.md`
+- Use clear names and keep comments focused on non-obvious logic
+
+## AI Interaction Guidelines
+- Reference the active feature docs in planning/implementation/testing
+- Keep docs concise and aligned with actual work

package/README.md

@@ -0,0 +1,58 @@
+# AI DevKit Workflow Quick Start
+
+This repository contains standardized project documentation, workflow templates, and AI agent configuration for structured development in any codebase.
+
+## How to Integrate into Any Project
+
+You have two methods to quickly add the workflow docs & agent commands into ANY repo:
+
+---
+
+## 1. Using degit (**Recommended, cross-platform**)
+
+> **Requires:** [Node.js](https://nodejs.org/) (includes npx & degit on Windows, Ubuntu, Mac)
+
+**Step 1:** Install degit *(optional—can use npx degit directly)*
+```bash
+npm install -g degit
+```
+
+**Step 2:** Run (in your target repo root):
+```bash
+npx degit your-username/ai-devkit-workflow-template/docs/ai docs/ai
+npx degit your-username/ai-devkit-workflow-template/.cursor/commands .cursor/commands
+```
+- This will copy all workflow docs and AI command templates to the current project.
+- Compatible with Windows Powershell, CMD, GitBash, WSL, Ubuntu/macOS terminals.
+
+---
+
+## 2. Using npx script (when available)
+
+> **Requires:** Node.js (>= v14). No other global install required.
+
+When a published init package is available, just run:
+```bash
+npx @your-org/ai-devkit-workflow-init
+```
+- The script will automatically fetch the workflow files and set up your repo.
+
+---
+
+## 3. Manual method (fallback)
+
+Clone this repo and copy files:
+```bash
+git clone https://github.com/your-username/ai-devkit-workflow-template.git ai-template-tmp
+cp -r ai-template-tmp/docs/ai ./docs/
+cp -r ai-template-tmp/.cursor/commands ./.cursor/
+rm -rf ai-template-tmp
+```
+
+---
+## Notes
+- All commands work identically on Windows, Ubuntu, Mac if Node.js is installed.
+- If you want to contribute updates to templates, fork this repo!
+
+---
+*See INTEGRATE.md in this repo for more advanced integration and troubleshooting.*

package/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const { existsSync, mkdirSync } = require('fs');
+
+// Repo workflow gốc của bạn
+const REPO = 'phananhtuan09/ai-agent-workflow';
+const RAW_BASE = 'https://raw.githubusercontent.com/phananhtuan09/ai-agent-workflow/main';
+
+// In ra helper log
+function step(msg) {
+  console.log('\x1b[36m%s\x1b[0m', msg); // cyan
+}
+
+function run(cmd) {
+  try {
+    execSync(cmd, { stdio: 'inherit' });
+  } catch (e) {
+    console.error('❌ Failed:', cmd);
+    process.exit(1);
+  }
+}
+
+// Kiểm tra và tạo folder nếu chưa có
+if (!existsSync('docs/ai')) {
+  mkdirSync('docs/ai', { recursive: true });
+}
+if (!existsSync('.cursor/commands')) {
+  mkdirSync('.cursor/commands', { recursive: true });
+}
+
+step('🚚 Downloading workflow template (docs/ai)...');
+run(`npx degit ${REPO}/docs/ai docs/ai --force`);
+
+step('🚚 Downloading agent commands (.cursor/commands)...');
+run(`npx degit ${REPO}/.cursor/commands .cursor/commands --force`);
+
+step('🚚 Downloading AGENTS.md ...');
+// degit không hỗ trợ tải 1 file đơn lẻ -> dùng raw github
+try {
+  run(`curl -fsSL ${RAW_BASE}/AGENTS.md -o AGENTS.md`);
+} catch (_) {
+  // Fallback cho môi trường không có curl
+  run(`wget -qO AGENTS.md ${RAW_BASE}/AGENTS.md`);
+}
+
+step('✅ All AI workflow docs, command templates, and AGENTS.md have been copied!');
+console.log('\n🌱 You can now use your AI workflow! Edit docs/ai/ and AGENTS.md as needed.\n');

package/docs/ai/implementation/README.md

@@ -0,0 +1,46 @@
+---
+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
+
+## 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

@@ -0,0 +1,14 @@
+# Implementation Notes: {Feature Name}
+
+## Summary
+- Short description of the solution approach
+
+## Changes
+- File: path/to/file1 (lines: x–y) — solution/ API/ pattern
+- File: path/to/file2 (lines: a–b) — change summary
+
+## Edge Cases
+- List of handled edge cases
+
+## Follow-ups
+- TODOs or deferred work

package/docs/ai/planning/README.md

@@ -0,0 +1,42 @@
+---
+phase: planning
+title: Planning Documentation
+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.
+
+## Feature Planning Workflow
+
+### Creating a Feature Plan
+Use the `create-plan` command to generate a new feature plan:
+- Command: `.cursor/commands/create-plan.md`
+- 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)
+
+### Feature Plan Naming Convention
+- Format: `feature-{name}.md` (kebab-case)
+- Example: `feature-user-authentication.md`
+- If duplicate name exists, append suffix: `feature-{name}-2.md`
+
+## Template Reference
+See `feature-template.md` for the exact structure required for feature plans.
+
+## Related Documentation
+- Implementation notes: `../implementation/`
+- Test plans: `../testing/`
+- Project standards: `../project/`
+
+---
+
+**Note**: For project-level planning (milestones, phases, timelines), use a separate project planning document outside this directory structure.

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

@@ -0,0 +1,15 @@
+# Plan: {Feature Name}
+
+## Goal
+- Objectives, scope, acceptance criteria (Given-When-Then)
+
+## Tasks (overview)
+- [ ] Task 1
+- [ ] Task 2
+- [ ] Task 3
+
+## Risks/Assumptions
+- Key risks / assumptions
+
+## Metrics / Definition of Done
+- Build green, tests added, review passed, docs updated

package/docs/ai/project/CODE_CONVENTIONS.md

@@ -0,0 +1,31 @@
+# Code Conventions
+
+> This document can be auto-generated via `generate-standards`. Edit manually as needed.
+
+## Naming
+- camelCase: variables, functions
+- PascalCase: classes, types
+- CONSTANT_CASE: constants
+
+## Structure
+- One primary concept per file
+- Prefer functions < 50 lines; refactor into helpers when needed
+
+## Error Handling & Logging
+- Throw errors with clear messages
+- Use appropriate log levels: debug/info/warn/error
+
+## Tests
+- Write unit tests first; add integration tests when necessary
+- Test names should describe behavior
+
+## Comments
+- Only for complex logic or non-obvious decisions
+
+## Guiding Questions (for AI regeneration)
+- What languages/frameworks are used, and do they impose naming/structure patterns?
+- What are the preferred file/module boundaries for this project?
+- What error handling strategy is standard (exceptions vs result types), and logging levels?
+- What is the minimum test level required per change (unit/integration/E2E)?
+- Are there performance/security constraints that influence coding style?
+- Any repository-wide conventions (imports order, lint rules, formatting tools)?

package/docs/ai/project/PROJECT_STRUCTURE.md

@@ -0,0 +1,27 @@
+# Project Structure
+
+> This document can be auto-generated via `generate-standards`. Edit manually as needed.
+
+## Folders
+- src/: source code
+- docs/ai/project/: project docs (structure, conventions, patterns)
+- docs/ai/planning/: feature plans
+- docs/ai/implementation/: implementation notes per feature
+- docs/ai/testing/: test plans per feature
+
+## Design Patterns (in use)
+- Pattern A: short description + when to use
+- Pattern B: short description + when to use
+
+## Notes
+- Import/module conventions
+- Config & secrets handling (if applicable)
+
+## Guiding Questions (for AI regeneration)
+- How is the codebase organized by domain/feature vs layers?
+- What are the module boundaries and dependency directions to preserve?
+- Which design patterns are officially adopted and where?
+- Where do configs/secrets live and how are they injected?
+- What is the expected test file placement and naming?
+- Any build/deployment constraints affecting structure (monorepo, packages)?
+

package/docs/ai/project/README.md

@@ -0,0 +1,65 @@
+---
+phase: project
+title: Project Standards
+description: Code conventions and project structure standards
+---
+
+# Project Standards
+
+## Purpose
+This directory contains project-wide standards that govern code quality, structure, and conventions. These standards are used by the `code-review` command to validate code.
+
+## Standards Documentation
+
+### CODE_CONVENTIONS.md
+Defines coding standards including:
+- Naming conventions (variables, functions, classes, constants)
+- Import order and formatting
+- Function size and complexity guidelines
+- Error handling strategy
+- Test rules
+- Comments policy
+
+### PROJECT_STRUCTURE.md
+Defines project organization including:
+- Folder layout and directory structure
+- Module boundaries and dependency direction
+- Design patterns in use
+- Test file placement and naming
+- Config/secrets handling
+
+## Generating Standards
+
+### Auto-Generation
+Use the `generate-standards` command to auto-generate these files from your codebase:
+- Command: `.cursor/commands/generate-standards.md`
+- Output: Updates `CODE_CONVENTIONS.md` and `PROJECT_STRUCTURE.md`
+- Process: Analyzes codebase + brief Q&A to infer standards
+
+### Manual Editing
+Both files can be edited manually at any time. They are marked with a note indicating they can be auto-generated.
+
+## Usage in Workflow
+
+### Code Review
+The `code-review` command strictly checks code against these two standards:
+- Only reports violations of explicit rules
+- Does not provide design opinions or performance guesses
+- Focuses on conformance to standards
+
+### Implementation
+When implementing features (`execute-plan`), follow these standards:
+- Adhere to naming conventions
+- Respect module boundaries
+- Follow error handling patterns
+- Place tests according to structure rules
+
+## Related Documentation
+- Feature planning: `../planning/`
+- Implementation notes: `../implementation/`
+- Test plans: `../testing/`
+
+---
+
+**Note**: These standards are project-specific and should reflect actual patterns in your codebase. Regenerate when codebase evolves significantly.
+

package/docs/ai/testing/README.md

@@ -0,0 +1,51 @@
+---
+phase: testing
+title: Testing Documentation
+description: Feature test plans and testing guidelines
+---
+
+# Testing Documentation
+
+## Purpose
+This directory contains test plans for individual features. These docs focus on simple, fast-running tests to verify logic correctness.
+
+## Testing Workflow
+
+### Creating Test Plans
+Use the `writing-test` command to generate test plans:
+- Command: `.cursor/commands/writing-test.md`
+- Output: `docs/ai/testing/feature-{name}.md`
+- Template: `docs/ai/testing/feature-template.md`
+
+### Test Plan Structure
+Each test plan follows the template structure:
+- **Unit Tests**: Simple test cases for functions/components
+  - Happy path scenarios
+  - Edge cases
+  - Error cases
+- **Integration Tests**: Simple component interaction tests (if needed)
+- **Manual Checklist**: Steps for manual verification
+- **Coverage Targets**: Coverage goals and gaps
+
+### Testing Philosophy
+- **Focus**: Pure functions, small utilities, isolated component logic
+- **Speed**: Tests must run quickly via command line
+- **Simplicity**: Avoid complex rendering tests, E2E flows, or heavy setup
+- **Purpose**: Catch logic errors and edge cases, not test frameworks
+
+### Coverage Targets
+Default targets (adjust if project-specific):
+- Lines: 80%
+- Branches: 70%
+
+## Template Reference
+See `feature-template.md` for the exact structure required for test plans.
+
+## Related Documentation
+- Planning docs: `../planning/`
+- Implementation notes: `../implementation/`
+- Project standards: `../project/`
+
+---
+
+**Note**: For complex E2E tests, performance testing, or bug tracking strategies, document these separately or in project-level documentation.

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

@@ -0,0 +1,16 @@
+# Test Plan: {Feature Name}
+
+## Unit Tests
+- Case 1: ...
+- Case 2: ...
+- Edge: ...
+
+## Integration Tests
+- Main flow: ...
+- Failure modes: ...
+
+## Manual Checklist
+- Steps for manual verification
+
+## Coverage Targets
+- Coverage goals and remaining gaps

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "ai-workflow-init",
+  "version": "1.0.0",
+  "description": "Initialize AI workflow docs & commands into any repo with one command",
+  "bin": {
+    "ai-workflow-init": "./cli.js"
+  },
+  "author": "your-name",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phananhtuan09/ai-agent-workflow.git"
+  },
+  "homepage": "https://github.com/phananhtuan09/ai-agent-workflow#readme",
+  "keywords": ["ai", "workflow", "docs", "degit", "init"],
+  "dependencies": {
+    "degit": "^2.8.4"
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}