ai-workflow-init 1.2.2 → 1.2.4

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

@@ -1,5 +1,9 @@
 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:

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

@@ -1,5 +1,9 @@
 You are helping me perform a local code review **before** I push changes. This review is restricted to standards conformance only.
 
+## Workflow Alignment
+- Provide brief status updates (1–3 sentences) before/after important actions.
+- Provide a high-signal summary at completion highlighting key findings and impact.
+
 ## Step 1: Gather Context (minimal)
 - Ask for feature name if not provided (must be kebab-case).
 - Then locate and read:
@@ -14,6 +18,15 @@ You are helping me perform a local code review **before** I push changes. This r
 - **Do NOT** provide design opinions, performance guesses, or alternative architectures.
 - **Do NOT** infer requirements beyond what standards explicitly state.
 
+### Automated Checks (recommended)
+- Detect tools from project config and run non-interactive checks:
+  - JS/TS: `npx eslint .` (or `pnpm eslint .`), consider `--max-warnings=0`; type checks with `npx tsc --noEmit`
+  - Python: `ruff .` or `flake8 .`; type checks with `mypy .` or `pyright`
+  - Go: `golangci-lint run` or `go vet ./...`
+  - Rust: `cargo clippy -- -D warnings`
+  - Java: `./gradlew check` or `mvn -q -DskipTests=false -Dspotbugs.failOnError=true verify`
+- Use results to focus the review; still report only clear violations per standards.
+
 ## 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.
 

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

@@ -2,6 +2,11 @@
 ## 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.
 
+## 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.
 
@@ -68,3 +73,7 @@ Produce a Markdown doc following the template structure:
 ## Step 4: Next Actions
 Suggest running `execute-plan` to begin task execution.
 Note: Test documentation will be created separately using the `writing-test` command.
+
+## Notes
+- This command creates planning docs only; does not modify unrelated existing files.
+- Idempotent: safe to re-run; auto-appends numeric suffix if file exists.

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

@@ -1,6 +1,12 @@
 ## Goal
 Execute the feature plan by implementing tasks 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`)
 - Planning doc exists: `docs/ai/planning/feature-{name}.md`
@@ -18,25 +24,26 @@ Execute the feature plan by implementing tasks and persisting notes to docs.
 
 ## Step 3: Implement Iteratively (per task)
 For each task in queue:
-1. Plan minimal change set:
+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
-2. Implement changes:
+3. Implement changes:
    - Write/edit code according to the plan
    - Keep changes minimal and incremental
    - Avoid speculative changes beyond plan scope
-3. Quick validation:
+4. 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:
+5. 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:
+6. Update planning doc:
    - Mark completed tasks `[x]` with brief note
    - Mark blocked tasks with reason
 
@@ -56,9 +63,19 @@ If creating implementation doc for first task:
 
 ## Step 5: Quality Checks
 After completing Step 4 for each task batch:
-- Run linting on changed files (e.g., `eslint` if JavaScript/TypeScript project).
-- Run type checks if applicable (e.g., `tsc --noEmit`).
-- Fix issues (up to 3 attempts) before proceeding to the next task.
+- 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: Next Actions
 After completing tasks:
@@ -70,3 +87,5 @@ After completing tasks:
 - 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
+- Modifies source code per plan scope; updates `docs/ai/implementation/feature-{name}.md` and checkboxes in `docs/ai/planning/feature-{name}.md`. Does not modify unrelated files.
+- Idempotent: safe to re-run; appends entries or updates checkboxes deterministically.

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

@@ -90,8 +90,9 @@ Use these exact markers to wrap generated content:
 ### Generated Content Order (for CODE_CONVENTIONS)
 - Merge templates in preload order (when present):
   1) `docs/ai/project/template-convention/common.md`
-  2) `docs/ai/project/template-convention/javascript.md` (when JS/TS repo)
+  2) `docs/ai/project/template-convention/javascript.md` (when JS/TS detected)
   3) `docs/ai/project/template-convention/react.md` (when React is detected)
+  4) `docs/ai/project/template-convention/typescript.md.md` (when TS is detected)
 - After the merged templates, append auto-discovered rules from the codebase analysis.
 
 ## Step 5: Next Actions

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

@@ -9,7 +9,7 @@ Initialize a new chat by loading and aligning to `AGENTS.md` so the AI agent con
 
 ## Steps
 1) Open and read `AGENTS.md` (project root).
-2) Detect project languages/frameworks/libraries from repository metadata (e.g., `package.json`, `pyproject.toml`, lockfiles, config files). Update `docs/ai/project/CODE_CONVENTIONS.md` to include any missing key coding conventions (only important items like React, TypeScript, TailwindCSS, etc.).
+2) Detect project languages/frameworks/libraries from repository metadata (e.g., `package.json`, `pyproject.toml`, lockfiles, config files). If `docs/ai/project/CODE_CONVENTIONS.md` is missing, create a minimal generated stub capturing key conventions (e.g., React, TypeScript, TailwindCSS). If it already exists, do not modify; instead, report any detected gaps and suggest running the standards generator.
 3) Read files in `docs/ai/project/` to understand project context and standards.
 4) Produce a short confirmation in the chat including:
    - Workflow alignment: Plan → Implement → Test → Review
@@ -26,5 +26,5 @@ Initialize a new chat by loading and aligning to `AGENTS.md` so the AI agent con
 
 ## Notes
 - This command is idempotent—safe to re-run at the start of any chat.
-- It does not modify files; it only sets expectations for subsequent commands.
+- It does not modify existing files; it only sets expectations for subsequent commands and may create missing metadata files (e.g., initial `CODE_CONVENTIONS.md`) if required.
 

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

@@ -1,12 +1,18 @@
 Use `docs/ai/testing/feature-{name}.md` as the source of truth.
 
+## 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.
+- Default to parallel execution for independent operations; use sequential steps only when dependencies exist.
+
 ## 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`
-- **Detect test framework:** Check `package.json` and project structure to identify test framework (Vitest, Jest, Mocha, pytest, etc.)
+- **Detect test framework:** Check `package.json` and project structure to identify test framework (Vitest, Jest, Mocha, pytest, etc.). Auto-detect from `package.json` first; if no test runner found, create skeleton test and report missing runner.
 - **Load standards:** Read `docs/ai/project/PROJECT_STRUCTURE.md` for test file placement rules
 - **Load conventions:** Read `docs/ai/project/CODE_CONVENTIONS.md` for coding standards
 
@@ -115,12 +121,12 @@ describe('functionToTest', () => {
 ## Step 5: Run Tests with Logging (automatic)
 After generating test code:
 
-1. **Execute test command** based on detected framework:
-   - Vitest: `npm test` or `npx vitest run`
-   - Jest: `npm test` or `npx jest`
-   - Mocha: `npm test` or `npx mocha`
-   - pytest: `pytest` or `python -m pytest`
-   - Other: detect from `package.json` scripts
+1. **Execute test command** based on detected framework (use non-interactive flags):
+   - Vitest: `npm test` or `npx vitest run --run`
+   - Jest: `npm test` or `npx jest --ci`
+   - Mocha: `npm test` or `npx mocha --reporter spec`
+   - pytest: `pytest` or `python -m pytest -v`
+   - Other: detect from `package.json` scripts, add `--no-interactive` or equivalent flags
 
 2. **Capture and display output** in terminal with detailed logging:
    - Show test execution progress (which tests are running)
@@ -214,3 +220,5 @@ Ensure all required sections from template are present. Keep the document brief
 - Test execution must show clear, detailed logging in terminal
 - AI excels at: edge case generation, parameter combinations, property-based testing, coverage analysis
 - Keep tests deterministic (avoid external dependencies, random values without seeds, time-dependent logic)
+- Creates test files only; does not edit non-test source files.
+- Idempotent: safe to re-run; appends entries or updates test doc deterministically.

package/docs/ai/project/template-convention/common.md

@@ -2,40 +2,60 @@
 
 > These rules are preloaded by the standards generator before analyzing the codebase. They establish non-negotiable, high-signal conventions. The generator should merge these rules first, then append auto-discovered patterns.
 
+## Principles — The "Why"
+- DRY (Don't Repeat Yourself): Avoid duplicating code. Abstract common logic into reusable functions, classes, or modules.
+- KISS (Keep It Simple, Stupid): Prefer simple, straightforward solutions over clever or unnecessarily complex ones. Code should be as simple as possible, but no simpler.
+- YAGNI (You Ain't Gonna Need It): Do not add functionality or create abstractions until they are actually needed. Avoid premature optimization.
+
 ## Naming — Clarity & Descriptiveness
 - Prefer meaningful, verbose names over abbreviations.
-- Avoid 1–2 character identifiers (except conventional counters in very small scopes).
+- Avoid 1–2 character identifiers (except conventional counters like `i`, `j`, `k` in very small loop scopes).
+- Be consistent. If you use `getUser` in one place, use `getProduct` in another, not `fetchProduct`.
+- Function names should be verbs; variables and classes should be nouns. (e.g., `calculateTotal()`, `const user`, `class Order`).
+
+## Functions / Methods
+- Single Responsibility Principle: A function should do one thing and do it well. If you can't describe what a function does in one simple sentence, it's likely doing too much.
+- Limit Arguments: Prefer 0-2 arguments per function. If you need more than two, consider passing a single configuration object.
+- Avoid Side Effects: Functions should be predictable. They should avoid modifying external state, global variables, or their own input arguments whenever possible. A function `calculateTotal(items)` should return a new value, not modify the original `items` array.
 
 ## Control Flow
 - Prefer guard clauses (early returns) to reduce nesting depth.
 - Handle errors and edge cases first.
-- Avoid deep nesting beyond 2–3 levels.
+- Avoid deep nesting beyond 2–3 levels. Refactor deeply nested logic into smaller, well-named functions.
+
+## Variables & Data Structures
+- Minimize Scope: Declare variables in the smallest possible scope (e.g., inside a loop or conditional block if they are only used there).
+- Avoid Magic Values: Do not use "magic" strings or numbers directly in code. Define them as named constants to provide context and avoid typos.
+  - *Bad:* `if (status === 2) { ... }`
+  - *Good:* `const STATUS_APPROVED = 2; if (status === STATUS_APPROVED) { ... }`
+- Prefer Immutability:** Do not reassign variables or mutate data structures if it can be avoided. Creating new data structures instead of changing existing ones leads to more predictable code.
 
 ## Error Handling
 - Throw errors with clear, actionable messages.
-- Do not catch errors without meaningful handling.
+- Do not catch errors without meaningful handling (e.g., logging, retrying, or re-throwing a more specific error). Swallowing exceptions silently is a major source of bugs.
 
 ## Comments
-- Add comments only for complex or non-obvious logic; explain "why", not "how".
+- Add comments only for complex or non-obvious logic; explain **"why"**, not **"how"**. Well-written code should explain the "how" by itself.
 - Place comments above code blocks or use language-specific docstrings.
-- Avoid trailing inline comments.
+- Avoid trailing inline comments as they can clutter code.
+- Remove Dead Code: Do not leave commented-out code in the codebase. Source control (like Git) is the history.
 
 ## Formatting
-- Match existing repository formatting tools and styles.
-- Prefer multi-line over long one-liners or complex ternaries.
-- Wrap long lines and do not reformat unrelated code.
+- Match existing repository formatting tools and styles (e.g., Prettier, Black, gofmt). Consistency is key.
+- Prefer multi-line over long one-liners or complex ternaries for readability.
+- Wrap long lines and do not reformat unrelated code in a change that is focused on logic.
 
 ## Types (for statically typed languages)
 - Explicitly annotate public APIs and function signatures.
-- Avoid unsafe casts or overly broad types (e.g., `any`).
+- Avoid unsafe casts or overly broad types (e.g., `any`, `Object`). Be as specific as possible.
 
 ## Change Discipline
 - Perform changes via file editing tools; avoid pasting large code blobs in reviews.
 - Re-read target files before editing to ensure accurate context.
 - After edits, run only fast, non-interactive validation on changed files:
-  - If ESLint is configured, run ESLint on changed paths (e.g., `eslint --max-warnings=0 <changed-paths>`). Use `--fix` when safe to auto-fix.
-  - If TypeScript is used, run type-check only (e.g., `tsc --noEmit` or `tsc -p . --noEmit`).
+  - If a linter is configured, run it on changed paths (e.g., `eslint --max-warnings=0 <changed-paths>`). Use `--fix` when safe to auto-fix.
+  - If a type checker is used, run type-check only (e.g., `tsc --noEmit` or `mypy <changed-paths>`).
   - Do NOT run Prettier as part of validation (formatting is enforced separately by tooling/CI).
-  - Do NOT run full build or dev server (to avoid unnecessary time cost).
+  - Do NOT run a full build or dev server (to avoid unnecessary time cost).
   - Attempt auto-fixes up to 3 times for linter issues before requesting help.
 

package/docs/ai/project/template-convention/javascript.md

@@ -6,17 +6,23 @@
 - Use strict equality `===`/`!==`.
 - Prefer optional chaining `?.` and nullish coalescing `??` over `||` when `0/''/false` are valid values.
 
+## Syntax & Readability
+- Use destructuring to access properties from objects and arrays.
+- Use the spread syntax (`...`) for creating shallow copies of arrays and objects.
+- Prefer array methods (`.map`, `.filter`, `.reduce`) over `for` loops for data transformation.
+- Use `for...of` for simple iterations over iterables.
+
 ## Functions & Data
 - Keep functions small and single-purpose.
+- Use arrow functions (`=>`) for callbacks and to preserve `this` context.
 - Avoid mutations; prefer immutable updates for objects/arrays.
 - Return early (guard clauses) to reduce nesting.
 
 ## Errors & Async
 - Use `async/await`; avoid unhandled promises (no floating promises).
-- Throw Errors with clear messages; catch only to handle meaningfully.
+- Throw `Error` objects with clear messages; catch only to handle meaningfully.
 
 ## Style & Safety
 - Avoid implicit globals; module scope only.
 - Prefer explicit returns over side effects.
-- Keep imports minimal and ordered (std/third-party/internal).
-
+- Keep imports minimal and ordered (std/third-party/internal).

package/docs/ai/project/template-convention/typescript.md

@@ -0,0 +1,25 @@
+# TypeScript Conventions (Essential)
+
+## Types & Interfaces
+- Use `interface` for public APIs and object shapes, as they are easily extended.
+- Use `type` for unions (`|`), intersections (`&`), tuples, or complex type aliases.
+
+## Naming Conventions
+- Use `PascalCase` for all type-level identifiers (Types, Interfaces, Classes, Enums, Generics).
+- Use `camelCase` for all value-level identifiers (variables, functions, properties).
+- Avoid the `I` prefix for interfaces (e.g., `User`, not `IUser`).
+- Use the `private` keyword instead of an underscore (`_`) prefix for private members.
+
+## Type Safety
+- Avoid `any`. It disables type-checking and defeats the purpose of TypeScript.
+- Prefer `unknown` over `any`. It is a type-safe alternative that forces type-checking before use.
+- Use `readonly` for properties that should not be mutated after initialization to enforce immutability.
+- Explicitly type all public function signatures to ensure a clear and stable API.
+
+## Modules & Organization
+- Always use ES Modules (`import`/`export`).
+- Prefer named exports over `default` exports. They improve consistency and refactorability.
+- Avoid `namespace`. ES Modules provide superior encapsulation and are the language standard.
+
+## Documentation
+- Use JSDoc (`/** ... */`) for all exported members (functions, classes, types). This provides context and enables rich editor tooltips.

package/package.json

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