opencode-conductor-cdd-plugin 1.0.0-beta.13

package/dist/prompts/cdd/setup.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+
+describe('setup.json prompt structure', () => {
+  let setupPrompt: string;
+
+  beforeAll(() => {
+    const setupJsonPath = path.join(__dirname, 'setup.json');
+    const setupJson = JSON.parse(fs.readFileSync(setupJsonPath, 'utf-8'));
+    setupPrompt = setupJson.prompt;
+  });
+
+  describe('Autogenerate option mandate', () => {
+    const requiredText = 'E) Autogenerate and review';
+    const mandatoryInstructionPattern = /\*\*Mandatory:\*\*.*autogenerate and review/is;
+
+    it('should contain Section 2.1 (Product Guide) with autogenerate mandate', () => {
+      expect(setupPrompt).toContain('### 2.1 Generate Product Guide');
+      
+      const section21Start = setupPrompt.indexOf('### 2.1 Generate Product Guide');
+      const section22Start = setupPrompt.indexOf('### 2.2 Generate Product Guidelines');
+      const section21 = setupPrompt.substring(section21Start, section22Start);
+      
+      expect(section21).toMatch(mandatoryInstructionPattern);
+      expect(section21).toContain(requiredText);
+    });
+
+    it('should contain Section 2.2 (Product Guidelines) with autogenerate mandate', () => {
+      expect(setupPrompt).toContain('### 2.2 Generate Product Guidelines');
+      
+      const section22Start = setupPrompt.indexOf('### 2.2 Generate Product Guidelines');
+      const section23Start = setupPrompt.indexOf('### 2.3 Define Technology Stack');
+      const section22 = setupPrompt.substring(section22Start, section23Start);
+      
+      expect(section22).toMatch(mandatoryInstructionPattern);
+      expect(section22).toContain(requiredText);
+    });
+
+    it('should contain Section 2.3 (Tech Stack) with autogenerate mandate', () => {
+      expect(setupPrompt).toContain('### 2.3 Define Technology Stack');
+      
+      const section23Start = setupPrompt.indexOf('### 2.3 Define Technology Stack');
+      const section24Start = setupPrompt.indexOf('### 2.4 Select Code Styleguides');
+      const section23 = setupPrompt.substring(section23Start, section24Start);
+      
+      expect(section23).toMatch(mandatoryInstructionPattern);
+      expect(section23).toContain(requiredText);
+    });
+
+    it('should contain Section 2.4 (Code Styleguides) with autogenerate mandate', () => {
+      expect(setupPrompt).toContain('### 2.4 Select Code Styleguides');
+      
+      const section24Start = setupPrompt.indexOf('### 2.4 Select Code Styleguides');
+      const section25Start = setupPrompt.indexOf('### 2.5 Define Workflow');
+      const section24 = setupPrompt.substring(section24Start, section25Start);
+      
+      expect(section24).toMatch(mandatoryInstructionPattern);
+      expect(section24).toContain(requiredText);
+    });
+
+    it('should contain Section 2.5 (Workflow) with autogenerate mandate', () => {
+      expect(setupPrompt).toContain('### 2.5 Define Workflow');
+      
+      const section25Start = setupPrompt.indexOf('### 2.5 Define Workflow');
+      const section30Start = setupPrompt.indexOf('## 3.0 INITIAL TRACK');
+      const section25 = setupPrompt.substring(section25Start, section30Start);
+      
+      expect(section25).toMatch(mandatoryInstructionPattern);
+      expect(section25).toContain(requiredText);
+    });
+  });
+
+  describe('Sequential questioning instructions', () => {
+    const sequentialPattern = /ask questions sequentially.*one by one/is;
+
+    it('should enforce sequential questioning in Section 2.1', () => {
+      const section21Start = setupPrompt.indexOf('### 2.1 Generate Product Guide');
+      const section22Start = setupPrompt.indexOf('### 2.2 Generate Product Guidelines');
+      const section21 = setupPrompt.substring(section21Start, section22Start);
+      
+      expect(section21).toMatch(sequentialPattern);
+    });
+
+    it('should enforce sequential questioning in Section 2.2', () => {
+      const section22Start = setupPrompt.indexOf('### 2.2 Generate Product Guidelines');
+      const section23Start = setupPrompt.indexOf('### 2.3 Define Technology Stack');
+      const section22 = setupPrompt.substring(section22Start, section23Start);
+      
+      expect(section22).toMatch(sequentialPattern);
+    });
+
+    it('should enforce sequential questioning in Section 2.4', () => {
+      const section24Start = setupPrompt.indexOf('### 2.4 Select Code Styleguides');
+      const section25Start = setupPrompt.indexOf('### 2.5 Define Workflow');
+      const section24 = setupPrompt.substring(section24Start, section25Start);
+      
+      expect(section24).toMatch(sequentialPattern);
+    });
+
+    it('should enforce sequential questioning in Section 2.5', () => {
+      const section25Start = setupPrompt.indexOf('### 2.5 Define Workflow');
+      const section30Start = setupPrompt.indexOf('## 3.0 INITIAL TRACK');
+      const section25 = setupPrompt.substring(section25Start, section30Start);
+      
+      expect(section25).toMatch(sequentialPattern);
+    });
+  });
+
+  describe('Basic prompt structure validation', () => {
+    it('should have description field', () => {
+      const setupJsonPath = path.join(__dirname, 'setup.json');
+      const setupJson = JSON.parse(fs.readFileSync(setupJsonPath, 'utf-8'));
+      
+      expect(setupJson).toHaveProperty('description');
+      expect(setupJson.description).toBeTruthy();
+    });
+
+    it('should have prompt field', () => {
+      const setupJsonPath = path.join(__dirname, 'setup.json');
+      const setupJson = JSON.parse(fs.readFileSync(setupJsonPath, 'utf-8'));
+      
+      expect(setupJson).toHaveProperty('prompt');
+      expect(setupJson.prompt).toBeTruthy();
+      expect(typeof setupJson.prompt).toBe('string');
+    });
+
+    it('should contain all major setup phases', () => {
+      expect(setupPrompt).toContain('## 1.0 SYSTEM DIRECTIVE');
+      expect(setupPrompt).toContain('## 1.1 BEGIN `RESUME` CHECK');
+      expect(setupPrompt).toContain('## 1.3 PROJECT MATURITY DETECTION');
+      expect(setupPrompt).toContain('## 2.0 INITIALIZATION PHASE');
+      expect(setupPrompt).toContain('## 3.0 INITIAL TRACK');
+      expect(setupPrompt).toContain('## 4.0 COMPLETION');
+    });
+
+    it('should contain all 5 interactive sections', () => {
+      expect(setupPrompt).toContain('### 2.1 Generate Product Guide');
+      expect(setupPrompt).toContain('### 2.2 Generate Product Guidelines');
+      expect(setupPrompt).toContain('### 2.3 Define Technology Stack');
+      expect(setupPrompt).toContain('### 2.4 Select Code Styleguides');
+      expect(setupPrompt).toContain('### 2.5 Define Workflow');
+    });
+  });
+
+  describe('Backward compatibility', () => {
+    it('should maintain existing resume logic', () => {
+      expect(setupPrompt).toContain('last_successful_step');
+      expect(setupPrompt).toContain('setup_state.json');
+      expect(setupPrompt).toContain('2.1_product_guide');
+      expect(setupPrompt).toContain('2.2_product_guidelines');
+      expect(setupPrompt).toContain('2.3_tech_stack');
+      expect(setupPrompt).toContain('2.4_code_styleguides');
+      expect(setupPrompt).toContain('2.5_workflow');
+    });
+
+    it('should maintain brownfield detection logic', () => {
+      expect(setupPrompt).toContain('BROWNFIELD');
+      expect(setupPrompt).toContain('GREENFIELD');
+      expect(setupPrompt).toContain('PROJECT MATURITY DETECTION');
+    });
+
+    it('should allow manual Q&A flow (no hard requirement for autogenerate)', () => {
+      expect(setupPrompt).not.toContain('MUST autogenerate');
+      expect(setupPrompt).not.toContain('MUST use autogenerate');
+    });
+  });
+});

package/dist/prompts/cdd/status.json

@@ -0,0 +1,4 @@
+{
+  "description": "Displays the current progress of the project",
+  "prompt": "## 1.0 SYSTEM DIRECTIVE\nYou are an AI agent. Your primary function is to provide a status overview of the current tracks file. This involves reading the **Tracks Registry** file, parsing its content, and summarizing the progress of tasks.\n\nCRITICAL: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions.\n\n---\n\n\n## 1.1 SETUP CHECK\n**PROTOCOL: Verify that the Orchestrator environment is properly set up.**\n\n1.  **Verify Core Context:** Using the **Universal File Resolution Protocol**, resolve and verify the existence of:\n    -   **Tracks Registry**\n    -   **Product Definition**\n    -   **Tech Stack**\n    -   **Workflow**\n\n2.  **Handle Failure:**\n    -   If ANY of these files are missing, you MUST halt the operation immediately.\n    -   Announce: \"Orchestrator is not set up. Please run `/orchestrator:setup` to set up the environment.\"\n    -   Do NOT proceed to Status Overview Protocol.\n\n---\n\n## 2.0 STATUS OVERVIEW PROTOCOL\n**PROTOCOL: Follow this sequence to provide a status overview.**\n\n**TOKEN BUDGET RULES:**\n- Default to a concise summary (counts of tracks and task statuses).\n- Only read full plan files if the user explicitly asks for details.\n- For any file larger than 1MB, read only the first and last 20 lines.\n\n### 2.1 Read Project Plan\n1.  **Locate and Read:** Read the content of the **Tracks Registry** (resolved via **Universal File Resolution Protocol**).\n2.  **Locate and Read Tracks:**\n    -   Parse the **Tracks Registry** to identify all registered tracks and their paths.\n        *   **Parsing Logic:** When reading the **Tracks Registry** to identify tracks, look for lines matching either the new standard format `- [ ] **Track:` or the legacy format `## [ ] Track:`.\n    -   For each track, resolve and read its **Implementation Plan** (using **Universal File Resolution Protocol** via the track's index file).\n\n### 2.2 Parse and Summarize Plan\n1.  **Parse Content:**\n    -   Identify major project phases/sections (e.g., top-level markdown headings).\n    -   Identify individual tasks and their current status (e.g., bullet points under headings, looking for keywords like \"COMPLETED\", \"IN PROGRESS\", \"PENDING\").\n2.  **Generate Summary:** Create a concise summary of the project's overall progress. This should include:\n    -   The total number of major phases.\n    -   The total number of tasks.\n    -   The number of tasks completed, in progress, and pending.\n\n### 2.3 Present Status Overview\n1.  **Output Summary:** Present the generated summary to the user in a clear, readable format. The status report must include:\n    -   **Current Date/Time:** The current timestamp.\n    -   **Project Status:** A high-level summary of progress (e.g., \"On Track\", \"Behind Schedule\", \"Blocked\").\n    -   **Current Phase and Task:** The specific phase and task currently marked as \"IN PROGRESS\".\n    -   **Next Action Needed:** The next task listed as \"PENDING\".\n    -   **Blockers:** Any items explicitly marked as blockers in the plan.\n    -   **Phases (total):** The total number of major phases.\n    -   **Tasks (total):** The total number of tasks.\n    -   **Progress:** The overall progress of the plan, presented as tasks_completed/tasks_total (percentage_completed%).\n\n"
+}

package/dist/prompts/strategies/delegate.md

@@ -0,0 +1,11 @@
+**MODE: SYNERGY (Architectural Delegation)**
+You are acting as the **Architect**. Your responsibility is to oversee the track while delegating execution to **Sisyphus**.
+
+**DIRECTIVE:**
+1.  **Do NOT implement code yourself.**
+2.  **Delegate:** For each task in `plan.md`, call `@sisyphus`.
+    *   *Note:* The system will automatically inject the full project context for you.
+    *   *Instruction:* Tell Sisyphus: "Execute this task. You have authority to update `plan.md` if needed. Report 'PLAN_UPDATED' if you do."
+3.  **Verify:**
+    *   If Sisyphus reports 'PLAN_UPDATED', you MUST **reload** `plan.md` before the next task.
+    *   If success, verify against the plan and proceed to the next task.

package/dist/prompts/strategies/manual.md

@@ -0,0 +1,9 @@
+**MODE: STANDARD (Manual Implementation)**
+You are acting as the **Developer**. Your responsibility is to implement the code, tests, and documentation yourself.
+
+**DIRECTIVE:**
+1.  **Implement Manually:** Loop through each task in `plan.md` one by one.
+2.  **Workflow:** Follow the `workflow.md` TDD protocol precisely (Red -> Green -> Refactor).
+3.  **Commits:**
+    *   **AUTHORITY OVERRIDE:** You have explicit authority to create Git commits as defined in the workflow. 
+    *   Do not ask for further permission for the granular task commits defined in `workflow.md`.

package/dist/templates/code_styleguides/c.md

@@ -0,0 +1,28 @@
+# C Style Guide Summary
+
+This document summarizes key rules and best practices for C development, based on the GNU Coding Standards and common industrial practices.
+
+## 1. Naming Conventions
+- **Files**: `snake_case.c` and `snake_case.h`.
+- **Functions**: `snake_case()` (e.g., `calculate_total`).
+- **Variables**: `snake_case` (e.g., `user_id`).
+- **Constants**: `UPPER_CASE_WITH_UNDERSCORES` (e.g., `BUFFER_SIZE`).
+- **Types (typedefs)**: `snake_case_t` (e.g., `config_t`).
+
+## 2. Formatting
+- **Indentation**: 2 or 4 spaces (be consistent).
+- **Braces**: Use the standard K&R style or Allman style, as long as it is consistent throughout the project.
+- **Line Length**: Limit lines to 80 characters.
+
+## 3. Programming Practices
+- **Header Guards**: Always use `#ifndef HEADER_NAME_H` guards.
+- **Memory Management**: Always check the return value of `malloc`, `calloc`, and `realloc`. Always `free` dynamically allocated memory.
+- **Pointers**: Initialize pointers to `NULL` if they are not immediately assigned a valid address.
+- **Error Handling**: Use return codes (e.g., `int` with `0` for success) for error propagation.
+
+## 4. Documentation
+- Use `/* ... */` for block comments.
+- Use `//` for short, single-line comments (C99 and later).
+- Document function parameters and return values in the header file.
+
+*Source: [GNU Coding Standards](https://www.gnu.org/prep/standards/)*

package/dist/templates/code_styleguides/cpp.md

@@ -0,0 +1,46 @@
+# C++ Style Guide Summary
+
+This document summarizes key rules and best practices for modern C++ development, based on the Google C++ Style Guide and the C++ Core Guidelines.
+
+## 1. Naming Conventions
+- **Files**: `snake_case.cc` and `snake_case.h`.
+- **Types (Classes, Structs, Type Aliases, Enums)**: `UpperCamelCase` (e.g., `HttpRequest`).
+- **Variables (Local and Class Members)**: `lowerCamelCase` (e.g., `localVariable`). 
+  - *Note: Some styles use `snake_case` or `trailing_underscore_` for private members.*
+- **Functions & Methods**: `UpperCamelCase` (e.g., `OpenFile`).
+- **Constants**: `kUpperCamelCase` (e.g., `kDaysInAWeek`).
+- **Namespaces**: `lower_snake_case`.
+
+## 2. Header Files
+- **Self-contained Headers**: Headers should be self-contained and have `#define` guards (e.g., `PROJECT_PATH_FILE_H_`).
+- **Include Order**: 
+  1. Related header
+  2. C system headers
+  3. C++ library headers
+  4. Other library headers
+  5. Project headers
+
+## 3. Scoping and Classes
+- **Namespaces**: Wrap code in namespaces to avoid name collisions. Do not use `using namespace std;` in header files.
+- **Classes**: 
+  - Keep constructors small. Use `explicit` for single-argument constructors.
+  - Avoid complex initialization in constructors; use an `Init()` method if necessary.
+  - Mark overriding methods with `override`.
+- **Structs vs. Classes**: Use `struct` only for passive data carriers (POD). Everything else should be a `class`.
+
+## 4. Modern C++ Features (C++11 and later)
+- **`auto`**: Use `auto` to avoid repeating type names, but only when it improves readability.
+- **Smart Pointers**: Prefer `std::unique_ptr` for ownership. Use `std::shared_ptr` only when ownership must be shared. Never use `std::auto_ptr`.
+- **`nullptr`**: Always use `nullptr` instead of `NULL` or `0`.
+- **Brace Initialization**: Use `{}` for initialization where appropriate.
+
+## 5. Memory Management
+- **Avoid Raw Pointers**: Use smart pointers or references.
+- **RAII**: Resource Acquisition Is Initialization is a fundamental pattern. Manage resources (memory, file handles, locks) via object lifetimes.
+
+## 6. Formatting
+- **Indentation**: 2 spaces (Google style).
+- **Line Length**: 80 characters limit is preferred.
+- **Braces**: Opening brace on the same line as the statement.
+
+*Source: [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html)*

package/dist/templates/code_styleguides/csharp.md

@@ -0,0 +1,115 @@
+# Google C# Style Guide Summary
+
+This document summarizes key rules and best practices from the Google C# Style Guide.
+
+## 1. Naming Conventions
+- **PascalCase:** For class names, method names, constants, properties, namespaces, and public fields.
+  - Example: `MyClass`, `GetValue()`, `MaxValue`
+- **_camelCase:** For private, internal, and protected fields (with leading underscore).
+  - Example: `_myField`, `_internalState`
+- **camelCase:** For local variables and parameters.
+  - Example: `localVariable`, `methodParameter`
+- **Interfaces:** Prefix with `I` (e.g., `IMyInterface`).
+- **Type Parameters:** Use descriptive names prefixed with `T` (e.g., `TValue`, `TKey`), or just `T` for simple cases.
+
+## 2. Formatting Rules
+- **Indentation:** Use 2 spaces (never tabs).
+- **Braces:** K&R style—no line break before the opening brace; keep `} else` on one line; braces required even when optional.
+  ```csharp
+  if (condition) {
+    DoSomething();
+  } else {
+    DoSomethingElse();
+  }
+  ```
+- **Line Length:** Column limit 100.
+- **One Statement Per Line:** Each statement on its own line.
+
+## 3. Declaration Order
+Class member ordering:
+- Group members in this order:
+  1. Nested classes, enums, delegates, and events
+  2. Static, const, and readonly fields
+  3. Fields and properties
+  4. Constructors and finalizers
+  5. Methods
+- Within each group, order by accessibility:
+  1. Public
+  2. Internal
+  3. Protected internal
+  4. Protected
+  5. Private
+- Where possible, group interface implementations together.
+
+## 4. Language Features
+- **var:** Use of `var` is encouraged if it aids readability by avoiding type names that are noisy, obvious, or unimportant. Prefer explicit types when it improves clarity.
+  ```csharp
+  var apple = new Apple();  // Good - type is obvious
+  bool success = true;  // Preferred over var for basic types
+  ```
+- **Expression-bodied Members:** Use sparingly for simple properties and lambdas; don't use on method definitions.
+  ```csharp
+  public int Age => _age;
+  // Methods: prefer block bodies.
+  ```
+- **String Interpolation:** In general, use whatever is easiest to read, particularly for logging and assert messages.
+  - Be aware that chained `operator+` concatenations can be slower and cause memory churn.
+  - If performance is a concern, `StringBuilder` can be faster for multiple concatenations.
+  ```csharp
+  var message = $"Hello, {name}!";
+  ```
+- **Collection Initializers:** Use collection and object initializers when appropriate.
+  ```csharp
+  var list = new List<int> { 1, 2, 3 };
+  ```
+- **Null-conditional Operators:** Use `?.` and `??` to simplify null checks.
+  ```csharp
+  var length = text?.Length ?? 0;
+  ```
+- **Pattern Matching:** Use pattern matching for type checks and casts.
+  ```csharp
+  if (obj is string str) { /* use str */ }
+  ```
+
+## 5. Best Practices
+- **Structs vs Classes**:
+  - Almost always use a class.
+  - Consider structs only for small, value-like types that are short-lived or frequently embedded.
+  - Performance considerations may justify deviations from this guidance.
+- **Access Modifiers:** Always explicitly declare access modifiers (don't rely on defaults).
+- **Ordering Modifiers:** Use standard order: `public protected internal private new abstract virtual override sealed static readonly extern unsafe volatile async`.
+- **Namespace Imports:** Place `using` directives at the top of the file (outside namespaces); `System` first, then alphabetical.
+- **Constants:** Always make variables `const` when possible; if not, use `readonly`. Prefer named constants over magic numbers.
+- **IEnumerable vs IList vs IReadOnlyList:** When method inputs are intended to be immutable, prefer the most restrictive collection type possible (e.g., IEnumerable, IReadOnlyList); for return values, prefer IList when transferring ownership of a mutable collection, and otherwise prefer the most restrictive option.
+- **Array vs List:** Prefer `List<>` for public variables, properties, and return types. Use arrays when size is fixed and known at construction time, or for multidimensional arrays.
+- **Extension Methods:** Only use when the source is unavailable or changing it is infeasible. Only for core, general features. Be aware they obfuscate code.
+- **LINQ:** Use LINQ for readability, but be mindful of performance in hot paths.
+
+## 6. File Organization
+- **One Class Per File:** Typically one class, interface, enum, or struct per file.
+- **File Name:** Prefer the file name to match the name of the primary type it contains.
+- **Folders and File Locations:**
+  - Be consistent within the project.
+  - Prefer a flat folder structure where possible.
+  - Don’t force file/folder layout to match namespaces.
+- **Namespaces:**
+  - In general, namespaces should be no more than 2 levels deep.
+  - For shared library/module code, use namespaces.
+  - For leaf application code, namespaces are not necessary.
+  - New top-level namespace names must be globally unique and recognizable.
+
+## 7. Parameters and Returns
+- **out Parameters:** Permitted for output-only values; place `out` parameters after all other parameters. Prefer tuples or return types when they improve clarity.
+- **Argument Clarity:** When argument meaning is nonobvious, use named constants, replace `bool` with `enum`, use named arguments, or create a configuration class/struct.
+  ```csharp
+  // Bad
+  DecimalNumber product = CalculateProduct(values, 7, false, null);
+  
+  // Good
+  var options = new ProductOptions { PrecisionDecimals = 7, UseCache = CacheUsage.DontUseCache };
+  DecimalNumber product = CalculateProduct(values, options, completionDelegate: null);
+  ```
+
+**BE CONSISTENT.** When editing code, follow the existing style in the codebase.
+
+*Source: [Google C# Style Guide](https://google.github.io/styleguide/csharp-style.html)*

package/dist/templates/code_styleguides/dart.md

@@ -0,0 +1,238 @@
+# Dart Code Style Guide
+
+This guide summarizes key recommendations from the official Effective Dart documentation, covering style, documentation, language usage, and API design principles. Adhering to these guidelines promotes consistent, readable, and maintainable Dart code.
+
+## 1. Style
+
+### 1.1. Identifiers
+
+- **DO** name types, extensions, and enum types using `UpperCamelCase`.
+- **DO** name packages, directories, and source files using `lowercase_with_underscores`.
+- **DO** name import prefixes using `lowercase_with_underscores`.
+- **DO** name other identifiers (class members, top-level definitions, variables, parameters) using `lowerCamelCase`.
+- **PREFER** using `lowerCamelCase` for constant names.
+- **DO** capitalize acronyms and abbreviations longer than two letters like words (e.g., `Http`, `Nasa`, `Uri`). Two-letter acronyms (e.g., `ID`, `TV`, `UI`) should remain capitalized.
+- **PREFER** using wildcards (`_`) for unused callback parameters in anonymous and local functions.
+- **DON'T** use a leading underscore for identifiers that aren't private.
+- **DON'T** use prefix letters (e.g., `kDefaultTimeout`).
+- **DON'T** explicitly name libraries using the `library` directive.
+
+### 1.2. Ordering
+
+- **DO** place `dart:` imports before other imports.
+- **DO** place `package:` imports before relative imports.
+- **DO** specify exports in a separate section after all imports.
+- **DO** sort sections alphabetically.
+
+### 1.3. Formatting
+
+- **DO** format your code using `dart format`.
+- **CONSIDER** changing your code to make it more formatter-friendly (e.g., shortening long identifiers, simplifying nested expressions).
+- **PREFER** lines 80 characters or fewer.
+- **DO** use curly braces for all flow control statements (`if`, `for`, `while`, `do`, `try`, `catch`, `finally`).
+
+## 2. Documentation
+
+### 2.1. Comments
+
+- **DO** format comments like sentences (capitalize the first word, end with a period).
+- **DON'T** use block comments (`/* ... */`) for documentation; use `//` for regular comments.
+
+### 2.2. Doc Comments
+
+- **DO** use `///` doc comments to document members and types.
+- **PREFER** writing doc comments for public APIs.
+- **CONSIDER** writing a library-level doc comment.
+- **CONSIDER** writing doc comments for private APIs.
+- **DO** start doc comments with a single-sentence summary.
+- **DO** separate the first sentence of a doc comment into its own paragraph.
+- **AVOID** redundancy with the surrounding context (e.g., don't repeat the class name in its doc comment).
+- **PREFER** starting comments of a function or method with third-person verbs if its main purpose is a side effect (e.g., "Connects to...").
+- **PREFER** starting a non-boolean variable or property comment with a noun phrase (e.g., "The current day...").
+- **PREFER** starting a boolean variable or property comment with "Whether" followed by a noun or gerund phrase (e.g., "Whether the modal is...").
+- **PREFER** a noun phrase or non-imperative verb phrase for a function or method if returning a value is its primary purpose.
+- **DON'T** write documentation for both the getter and setter of a property.
+- **PREFER** starting library or type comments with noun phrases.
+- **CONSIDER** including code samples in doc comments using triple backticks.
+- **DO** use square brackets (`[]`) in doc comments to refer to in-scope identifiers (e.g., `[StateError]`, `[anotherMethod()]`, `[Duration.inDays]`, `[Point.new]`).
+- **DO** use prose to explain parameters, return values, and exceptions.
+- **DO** put doc comments before metadata annotations.
+
+### 2.3. Markdown
+
+- **AVOID** using markdown excessively.
+- **AVOID** using HTML for formatting.
+- **PREFER** backtick fences (```) for code blocks.
+
+### 2.4. Writing
+
+- **PREFER** brevity.
+- **AVOID** abbreviations and acronyms unless they are obvious.
+- **PREFER** using "this" instead of "the" to refer to a member's instance.
+
+## 3. Usage
+
+### 3.1. Libraries
+
+- **DO** use strings in `part of` directives.
+- **DON'T** import libraries that are inside the `src` directory of another package.
+- **DON'T** allow an import path to reach into or out of `lib`.
+- **PREFER** relative import paths when not crossing the `lib` boundary.
+
+### 3.2. Null Safety
+
+- **DON'T** explicitly initialize variables to `null`.
+- **DON'T** use an explicit default value of `null`.
+- **DON'T** use `true` or `false` in equality operations (e.g., `if (nonNullableBool == true)`).
+- **AVOID** `late` variables if you need to check whether they are initialized; prefer nullable types.
+- **CONSIDER** type promotion or null-check patterns for using nullable types.
+
+### 3.3. Strings
+
+- **DO** use adjacent strings to concatenate string literals.
+- **PREFER** using interpolation (`$variable`, `${expression}`) to compose strings and values.
+- **AVOID** using curly braces in interpolation when not needed (e.g., `'$name'` instead of `'${name}'`).
+
+### 3.4. Collections
+
+- **DO** use collection literals (`[]`, `{}`, `<type>{}`) when possible.
+- **DON'T** use `.length` to check if a collection is empty; use `.isEmpty` or `.isNotEmpty`.
+- **AVOID** using `Iterable.forEach()` with a function literal; prefer `for-in` loops.
+- **DON'T** use `List.from()` unless you intend to change the type of the result; prefer `.toList()`.
+- **DO** use `whereType()` to filter a collection by type.
+- **AVOID** using `cast()` when a nearby operation (like `List<T>.from()` or `map<T>()`) will do.
+
+### 3.5. Functions
+
+- **DO** use a function declaration to bind a function to a name.
+- **DON'T** create a lambda when a tear-off will do (e.g., `list.forEach(print)` instead of `list.forEach((e) => print(e))`).
+
+### 3.6. Variables
+
+- **DO** follow a consistent rule for `var` and `final` on local variables (either `final` for non-reassigned and `var` for reassigned, or `var` for all locals).
+- **AVOID** storing what you can calculate (e.g., don't store `area` if you have `radius`).
+
+### 3.7. Members
+
+- **DON'T** wrap a field in a getter and setter unnecessarily.
+- **PREFER** using a `final` field to make a read-only property.
+- **CONSIDER** using `=>` for simple members (getters, setters, single-expression methods).
+- **DON'T** use `this.` except to redirect to a named constructor or to avoid shadowing.
+- **DO** initialize fields at their declaration when possible.
+
+### 3.8. Constructors
+
+- **DO** use initializing formals (`this.field`) when possible.
+- **DON'T** use `late` when a constructor initializer list will do.
+- **DO** use `;` instead of `{}` for empty constructor bodies.
+- **DON'T** use `new`.
+- **DON'T** use `const` redundantly in constant contexts.
+
+### 3.9. Error Handling
+
+- **AVOID** `catch` clauses without `on` clauses.
+- **DON'T** discard errors from `catch` clauses without `on` clauses.
+- **DO** throw objects that implement `Error` only for programmatic errors.
+- **DON'T** explicitly catch `Error` or types that implement it.
+- **DO** use `rethrow` to rethrow a caught exception to preserve the original stack trace.
+
+### 3.10. Asynchrony
+
+- **PREFER** `async`/`await` over using raw `Future`s.
+- **DON'T** use `async` when it has no useful effect.
+- **CONSIDER** using higher-order methods to transform a stream.
+- **AVOID** using `Completer` directly.
+
+## 4. API Design
+
+### 4.1. Names
+
+- **DO** use terms consistently.
+- **AVOID** abbreviations unless more common than the unabbreviated term.
+- **PREFER** putting the most descriptive noun last (e.g., `pageCount`).
+- **CONSIDER** making the code read like a sentence when using the API.
+- **PREFER** a noun phrase for a non-boolean property or variable.
+- **PREFER** a non-imperative verb phrase for a boolean property or variable (e.g., `isEnabled`, `canClose`).
+- **CONSIDER** omitting the verb for a named boolean parameter (e.g., `growable: true`).
+- **PREFER** the "positive" name for a boolean property or variable (e.g., `isConnected` over `isDisconnected`).
+- **PREFER** an imperative verb phrase for a function or method whose main purpose is a side effect (e.g., `list.add()`, `window.refresh()`).
+- **PREFER** a noun phrase or non-imperative verb phrase for a function or method if returning a value is its primary purpose (e.g., `list.elementAt(3)`).
+- **CONSIDER** an imperative verb phrase for a function or method if you want to draw attention to the work it performs (e.g., `database.downloadData()`).
+- **AVOID** starting a method name with `get`.
+- **PREFER** naming a method `to___()` if it copies the object's state to a new object (e.g., `toList()`).
+- **PREFER** naming a method `as___()` if it returns a different representation backed by the original object (e.g., `asMap()`).
+- **AVOID** describing the parameters in the function's or method's name.
+- **DO** follow existing mnemonic conventions when naming type parameters (e.g., `E` for elements, `K`, `V` for map keys/values, `T`, `S`, `U` for general types).
+
+### 4.2. Libraries
+
+- **PREFER** making declarations private (`_`).
+- **CONSIDER** declaring multiple classes in the same library if they logically belong together.
+
+### 4.3. Classes and Mixins
+
+- **AVOID** defining a one-member abstract class when a simple function (`typedef`) will do.
+- **AVOID** defining a class that contains only static members; prefer top-level functions/variables or a library.
+- **AVOID** extending a class that isn't intended to be subclassed.
+- **DO** use class modifiers (e.g., `final`, `interface`, `sealed`) to control if your class can be extended.
+- **AVOID** implementing a class that isn't intended to be an interface.
+- **DO** use class modifiers to control if your class can be an interface.
+- **PREFER** defining a pure mixin or pure class to a `mixin class`.
+
+### 4.4. Constructors
+
+- **CONSIDER** making your constructor `const` if the class supports it (all fields are `final` and initialized in the constructor).
+
+### 4.5. Members
+
+- **PREFER** making fields and top-level variables `final`.
+- **DO** use getters for operations that conceptually access properties (no arguments, returns a result, no user-visible side effects, idempotent).
+- **DO** use setters for operations that conceptually change properties (single argument, no result, changes state, idempotent).
+- **DON'T** define a setter without a corresponding getter.
+- **AVOID** using runtime type tests to fake overloading.
+- **AVOID** public `late final` fields without initializers.
+- **AVOID** returning nullable `Future`, `Stream`, and collection types; prefer empty containers or non-nullable futures of nullable types.
+- **AVOID** returning `this` from methods just to enable a fluent interface; prefer method cascades.
+
+### 4.6. Types
+
+- **DO** type annotate variables without initializers.
+- **DO** type annotate fields and top-level variables if the type isn't obvious.
+- **DON'T** redundantly type annotate initialized local variables.
+- **DO** annotate return types on function declarations.
+- **DO** annotate parameter types on function declarations.
+- **DON'T** annotate inferred parameter types on function expressions.
+- **DON'T** type annotate initializing formals.
+- **DO** write type arguments on generic invocations that aren't inferred.
+- **DON'T** write type arguments on generic invocations that are inferred.
+- **AVOID** writing incomplete generic types.
+- **DO** annotate with `dynamic` instead of letting inference fail silently.
+- **PREFER** signatures in function type annotations.
+- **DON'T** specify a return type for a setter.
+- **DON'T** use the legacy `typedef` syntax.
+- **PREFER** inline function types over `typedef`s.
+- **PREFER** using function type syntax for parameters.
+- **AVOID** using `dynamic` unless you want to disable static checking.
+- **DO** use `Future<void>` as the return type of asynchronous members that do not produce values.
+- **AVOID** using `FutureOr<T>` as a return type.
+
+### 4.7. Parameters
+
+- **AVOID** positional boolean parameters.
+- **AVOID** optional positional parameters if the user may want to omit earlier parameters.
+- **AVOID** mandatory parameters that accept a special "no argument" value.
+- **DO** use inclusive start and exclusive end parameters to accept a range.
+
+### 4.8. Equality
+
+- **DO** override `hashCode` if you override `==`.
+- **DO** make your `==` operator obey the mathematical rules of equality (reflexive, symmetric, transitive, consistent).
+- **AVOID** defining custom equality for mutable classes.
+- **DON'T** make the parameter to `==` nullable.
+
+_Sources:_
+
+- [Effective Dart: Style](https://dart.dev/effective-dart/style)
+- [Effective Dart: Documentation](https://dart.dev/effective-dart/documentation)
+- [Effective Dart: Usage](https://dart.dev/effective-dart/usage)
+- [Effective Dart: Design](https://dart.dev/effective-dart/design)

package/dist/templates/code_styleguides/general.md

@@ -0,0 +1,23 @@
+# General Code Style Principles
+
+This document outlines general coding principles that apply across all languages and frameworks used in this project.
+
+## Readability
+- Code should be easy to read and understand by humans.
+- Avoid overly clever or obscure constructs.
+
+## Consistency
+- Follow existing patterns in the codebase.
+- Maintain consistent formatting, naming, and structure.
+
+## Simplicity
+- Prefer simple solutions over complex ones.
+- Break down complex problems into smaller, manageable parts.
+
+## Maintainability
+- Write code that is easy to modify and extend.
+- Minimize dependencies and coupling.
+
+## Documentation
+- Document *why* something is done, not just *what*.
+- Keep documentation up-to-date with code changes.