ai-workflow-init 1.1.2 → 1.2.1

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

@@ -34,9 +34,15 @@ Analyze repository to infer:
   - Other architectural patterns
 
 ## Step 3: Draft Standards
-Generate two documents:
+Generate two documents (with template preload):
 
 ### CODE_CONVENTIONS.md
+- Template preload (in order, if present):
+  1) `docs/ai/project/template-convention/common.md` — always preload first.
+  2) `docs/ai/project/template-convention/javascript.md` — preload if the repository primarily uses JavaScript/TypeScript.
+  3) `docs/ai/project/template-convention/react.md` — preload if the repository uses React (detect via dependencies like `react`, file patterns like `.jsx/.tsx`, or imports from `react`).
+  
+  These templates take precedence and should appear at the top of the generated document, followed by auto-discovered rules.
 - Naming conventions (variables, functions, classes, constants)
 - Import order and grouping
 - Formatting tools (ESLint/Prettier/etc.) if detected
@@ -55,11 +61,38 @@ Generate two documents:
 - Test placement and naming conventions
 - Config/secrets handling summary
 
-## Step 4: Persist
-- Overwrite or create:
+## Step 4: Persist (Update-in-place, Non-destructive)
+- Target files:
   - `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."
+- Do NOT blindly overwrite entire files. Update only the managed blocks using markers:
+
+### Managed Block Markers
+Use these exact markers to wrap generated content:
+```
+<!-- GENERATED: CODE_CONVENTIONS:START -->
+... generated content ...
+<!-- GENERATED: CODE_CONVENTIONS:END -->
+```
+```
+<!-- GENERATED: PROJECT_STRUCTURE:START -->
+... generated content ...
+<!-- GENERATED: PROJECT_STRUCTURE:END -->
+```
+
+### Update Rules
+1) If the target file exists and contains the corresponding markers, replace only the content between START/END with the newly generated content.
+2) If the file exists but does not contain markers, append a new managed block to the end of the file (preserve all existing manual content).
+3) If the file does not exist, create it with the header note and a single managed block.
+4) Never modify content outside the managed blocks.
+
+### 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)
+  3) `docs/ai/project/template-convention/react.md` (when React is detected)
+- After the merged templates, append auto-discovered rules from the codebase analysis.
 
 ## Step 5: Next Actions
 - Suggest running `code-review` to validate new standards are being followed

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

@@ -0,0 +1,28 @@
+## Goal
+Initialize a new chat by loading and aligning to `AGENTS.md` so the AI agent consistently follows project rules (workflow, tooling, communication, language mirroring) from the first message.
+
+## What this command does
+1. Read `AGENTS.md` and extract the actionable rules.
+2. Summarize responsibilities and constraints the agent must follow in this session.
+3. Confirm language-mirroring: respond in the user's chat language; default to English if the user's language is unclear or ambiguous.
+4. Acknowledge the 4-phase workflow and TODO discipline for future commands.
+
+## Steps
+1) Open and read `AGENTS.md` (project root).
+2) Produce a short confirmation in the chat including:
+   - Workflow alignment: Plan → Implement → Test → Review
+   - Tooling strategy: semantic search first; parallelize independent steps
+   - Communication: minimal Markdown; status updates; high-signal summaries; mirror user language (default English if unclear)
+   - Code presentation: code references for existing code; fenced blocks for new code
+   - TODO policy: create/update todos; keep only one `in_progress`
+3) If any section is missing or unclear, ask a single concise clarification question; otherwise proceed silently in future commands.
+
+## Output format (concise)
+- Use the language of the triggering user message (mirror). If ambiguous, use English.
+- One short paragraph confirming alignment + a 4–6 bullet checklist of the above items.
+- No code unless strictly needed.
+
+## 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.
+

package/AGENTS.md

@@ -1,21 +1,24 @@
-# AI DevKit Rules (Personal Workflow)
+# AI Agent Guidelines
 
-## 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`)
+## 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.
 
-## 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
+## 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.
 
-## Code Style & Standards
-- Follow `docs/ai/project/CODE_CONVENTIONS.md`
-- Use clear names and keep comments focused on non-obvious logic
+## 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.
 
-## AI Interaction Guidelines
-- Reference the active feature docs in planning/implementation/testing
-- Keep docs concise and aligned with actual work
+## 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.
+
+## 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/docs/ai/implementation/README.md

@@ -33,6 +33,11 @@ Implementation docs serve as:
 - **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.
 

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

@@ -12,3 +12,8 @@
 
 ## 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.

package/docs/ai/planning/README.md

@@ -24,6 +24,10 @@ Each feature plan follows the template structure:
 - **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.
+
 ### Feature Plan Naming Convention
 - Format: `feature-{name}.md` (kebab-case)
 - Example: `feature-user-authentication.md`

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

@@ -3,6 +3,11 @@
 ## Goal
 - Objectives, scope, acceptance criteria (Given-When-Then)
 
+### Acceptance Criteria (Given/When/Then)
+- Given ...
+- When ...
+- Then ...
+
 ## Tasks (overview)
 - [ ] Task 1
 - [ ] Task 2
@@ -11,5 +16,13 @@
 ## Risks/Assumptions
 - Key risks / assumptions
 
+## Observability
+- Logging requirements:
+- Metrics/telemetry:
+
 ## Metrics / Definition of Done
 - Build green, tests added, review passed, docs updated
+
+## 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.

package/docs/ai/project/CODE_CONVENTIONS.md

@@ -1,31 +1,10 @@
 # Code Conventions
 
-> This document can be auto-generated via `generate-standards`. Edit manually as needed.
+This document is auto-generated by the `generate-standards` command.
 
-## Naming
-- camelCase: variables, functions
-- PascalCase: classes, types
-- CONSTANT_CASE: constants
+Do not edit manually. To influence the generated content, edit the preload templates instead:
+- `docs/ai/project/template-convention/common.md` (always loaded first)
+- `docs/ai/project/template-convention/javascript.md` (loaded if JS/TS repo)
+- `docs/ai/project/template-convention/react.md` (loaded if React is detected)
 
-## 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)?
+The generator merges the above templates (when present) and then appends auto-discovered rules from the codebase.

package/docs/ai/project/PROJECT_STRUCTURE.md

@@ -17,6 +17,12 @@
 - Import/module conventions
 - Config & secrets handling (if applicable)
 
+## AI Docs Roles (existing only)
+- `docs/ai/project/`: repository-wide conventions and structure; workflow overview and navigation live in `README.md`.
+- `docs/ai/planning/`: feature plans using `feature-template.md` with Acceptance Criteria; plans should drive a todo checklist before coding.
+- `docs/ai/implementation/`: per-feature implementation notes tracking what changed and why.
+- `docs/ai/testing/`: per-feature test plans and results; include quality checks and coverage targets.
+
 ## 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?

package/docs/ai/project/README.md

@@ -41,11 +41,17 @@ Both files can be edited manually at any time. They are marked with a note indic
 
 ## Usage in Workflow
 
+### Development Workflow (4 phases)
+1) Plan: define goals, scope, and Acceptance Criteria; create a todo checklist from the plan before any coding.
+2) Implementation: make small, shippable edits; provide status updates before actions; perform edits via file editing tools.
+3) Testing: cover main and edge flows; run linter/type/build on changed files and auto-fix issues (up to 3 attempts).
+4) Review: self-review; when todos are done and checks pass, provide a concise summary and ship.
+
 ### 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
+The `code-review` command checks conformance to these standards and project structure:
+- Reports violations of explicit rules
+- Avoids subjective design opinions or performance guesses
+- Focuses on adherence to conventions and structure
 
 ### Implementation
 When implementing features (`execute-plan`), follow these standards:
@@ -59,6 +65,13 @@ When implementing features (`execute-plan`), follow these standards:
 - Implementation notes: `../implementation/`
 - Test plans: `../testing/`
 
+## Navigation
+- Code conventions: `CODE_CONVENTIONS.md`
+- Project structure: `PROJECT_STRUCTURE.md`
+- Planning template: `../planning/feature-template.md`
+- Implementation template: `../implementation/feature-template.md`
+- Testing template: `../testing/feature-template.md`
+
 ---
 
 **Note**: These standards are project-specific and should reflect actual patterns in your codebase. Regenerate when codebase evolves significantly.

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

@@ -0,0 +1,41 @@
+# CODE_CONVENTIONS Common Rules (Template Preload)
+
+> 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.
+
+## Naming — Clarity & Descriptiveness
+- Prefer meaningful, verbose names over abbreviations.
+- Avoid 1–2 character identifiers (except conventional counters in very small scopes).
+
+## Control Flow
+- Prefer guard clauses (early returns) to reduce nesting depth.
+- Handle errors and edge cases first.
+- Avoid deep nesting beyond 2–3 levels.
+
+## Error Handling
+- Throw errors with clear, actionable messages.
+- Do not catch errors without meaningful handling.
+
+## Comments
+- Add comments only for complex or non-obvious logic; explain "why", not "how".
+- Place comments above code blocks or use language-specific docstrings.
+- Avoid trailing inline comments.
+
+## 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.
+
+## Types (for statically typed languages)
+- Explicitly annotate public APIs and function signatures.
+- Avoid unsafe casts or overly broad types (e.g., `any`).
+
+## 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`).
+  - 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).
+  - Attempt auto-fixes up to 3 times for linter issues before requesting help.
+

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

@@ -0,0 +1,22 @@
+# JavaScript Conventions (Essential)
+
+## Language
+- Use ES Modules (`import`/`export`).
+- Prefer `const` (default) and `let`; avoid `var`.
+- Use strict equality `===`/`!==`.
+- Prefer optional chaining `?.` and nullish coalescing `??` over `||` when `0/''/false` are valid values.
+
+## Functions & Data
+- Keep functions small and single-purpose.
+- 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.
+
+## Style & Safety
+- Avoid implicit globals; module scope only.
+- Prefer explicit returns over side effects.
+- Keep imports minimal and ordered (std/third-party/internal).
+

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

@@ -0,0 +1,24 @@
+# React Conventions (Essential)
+
+## Components
+- Use PascalCase for component names; one component per file (primary export).
+- Props are immutable; derive minimal state. Lift state up when shared.
+- Use stable `key` for lists (not index) when order can change.
+
+## Hooks
+- Follow the Rules of Hooks (top-level, consistent order).
+- Declare all hook dependencies explicitly; prefer stable callbacks with `useCallback` when passed to children.
+- Memoize expensive computations with `useMemo` only when measured bottlenecks exist.
+
+## State & Effects
+- Keep state minimal and serializable; avoid duplicating derived data.
+- Side effects belong in `useEffect` with correct deps; cleanup subscriptions/timers.
+
+## Performance
+- Avoid unnecessary re-renders: memo child components when props are stable.
+- Prefer split code (lazy + Suspense) for large routes/widgets.
+
+## Accessibility
+- Use semantic elements first; include `aria-*` only when needed.
+- Ensure interactive elements are keyboard-accessible and have discernible labels.
+

package/docs/ai/testing/README.md

@@ -87,6 +87,13 @@ See `feature-template.md` for the exact structure required for test plans.
 - Implementation notes: `../implementation/`
 - Project standards: `../project/`
 
+## Validation Requirements
+- After each batch of implementation edits, run:
+  - Linter on changed files (must pass; auto-fix up to 3 attempts)
+  - Type checks (must pass)
+  - Build (must be green)
+- Map test cases to the feature's Acceptance Criteria.
+
 ---
 
 **Note**: For complex E2E tests, performance testing, or bug tracking strategies, document these separately or in project-level documentation. The `writing-test` command focuses on automated, logic-focused testing that AI agents excel at.

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

@@ -46,3 +46,12 @@ npx vitest run
 - Test results logged to terminal with detailed output
 - Focus on logic testing, edge cases, and parameter variations
 - No complex integration or UI rendering tests
+
+## Quality Checks
+- Linter: pass on changed files
+- Type checks: pass
+- Build: green
+
+## Process
+- After each batch of implementation edits, run linter/type/build on changed files.
+- Auto-fix linter issues (up to 3 attempts) before requesting review.

package/package.json

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