ai-workflow-init 1.2.2 → 1.2.3

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/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.3",
   "description": "Initialize AI workflow docs & commands into any repo with one command",
   "bin": {
     "ai-workflow-init": "./cli.js"