conductor-opencode 1.0.0

package/skills/conductor-setup/SKILL.md

@@ -0,0 +1,236 @@
+# Conductor Setup
+
+Scaffolds the project and sets up the Conductor environment.
+
+---
+
+## 1.0 SYSTEM DIRECTIVE
+
+You are an AI agent. Your primary function is to set up and manage a software project using the Conductor methodology. This document is your operational protocol. Adhere to these instructions precisely and sequentially. Do not make assumptions.
+
+CRITICAL: 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.
+
+---
+
+## 1.1 PRE-INITIALIZATION OVERVIEW
+
+1. **Provide High-Level Overview:**
+   - Present the following overview of the initialization process to the user:
+     > "Welcome to Conductor. I will guide you through the following steps to set up your project:
+     > 1. **Project Discovery:** Analyze the current directory to determine if this is a new or existing project.
+     > 2. **Product Definition:** Collaboratively define the product's vision, design guidelines, and technology stack.
+     > 3. **Configuration:** Select appropriate code style guides and customize your development workflow.
+     > 4. **Track Generation:** Define the initial **track** (a high-level unit of work like a feature or bug fix) and automatically generate a detailed plan to start development.
+     >
+     > Let's get started!"
+
+---
+
+## 1.2 BEGIN RESUME CHECK
+
+**PROTOCOL: Before starting the setup, determine the project's state using the state file.**
+
+1. **Read State File:** Check for the existence of `conductor/setup_state.json`.
+   - If it does not exist, this is a new project setup. Proceed directly to Step 2.0.
+   - If it exists, read its content.
+
+2. **Resume Based on State:**
+   - Let the value of `last_successful_step` in the JSON file be `STEP`.
+   - Based on the value of `STEP`, jump to the **next logical section**:
+
+   - If `STEP` is "2.1_product_guide", announce "Resuming setup: The Product Guide (`product.md`) is already complete. Next, we will create the Product Guidelines." and proceed to **Section 2.2**.
+   - If `STEP` is "2.2_product_guidelines", announce "Resuming setup: The Product Guide and Product Guidelines are complete. Next, we will define the Technology Stack." and proceed to **Section 2.3**.
+   - If `STEP` is "2.3_tech_stack", announce "Resuming setup: The Product Guide, Guidelines, and Tech Stack are defined. Next, we will select Code Styleguides." and proceed to **Section 2.4**.
+   - If `STEP` is "2.4_code_styleguides", announce "Resuming setup: All guides and the tech stack are configured. Next, we will define the project workflow." and proceed to **Section 2.5**.
+   - If `STEP` is "2.5_workflow", announce "Resuming setup: The initial project scaffolding is complete. Next, we will generate the first track." and proceed to **Phase 2 (3.0)**.
+   - If `STEP` is "3.3_initial_track_generated":
+     - Announce: "The project has already been initialized. You can create a new track with `/conductor-new-track` or start implementing existing tracks with `/conductor-implement`."
+     - Halt the `setup` process.
+   - If `STEP` is unrecognized, announce an error and halt.
+
+---
+
+## 2.0 PHASE 1: STREAMLINED PROJECT SETUP
+
+**PROTOCOL: Follow this sequence to perform a guided, interactive setup with the user.**
+
+### 2.0 Project Inception
+
+1. **Detect Project Maturity:**
+   - **Classify Project:** Determine if the project is "Brownfield" (Existing) or "Greenfield" (New) based on the following indicators:
+   - **Brownfield Indicators:**
+     - Check for existence of version control directories: `.git`, `.svn`, or `.hg`.
+     - If a `.git` directory exists, execute `git status --porcelain`. If the output is not empty, classify as "Brownfield" (dirty repository).
+     - Check for dependency manifests: `package.json`, `pom.xml`, `requirements.txt`, `go.mod`.
+     - Check for source code directories: `src/`, `app/`, `lib/` containing code files.
+     - If ANY of the above conditions are met (version control directory, dirty git repo, dependency manifest, or source code directories), classify as **Brownfield**.
+   - **Greenfield Condition:**
+     - Classify as **Greenfield** ONLY if NONE of the "Brownfield Indicators" are found AND the current directory is empty or contains only generic documentation (e.g., a single `README.md` file) without functional code or dependencies.
+
+2. **Execute Workflow based on Maturity:**
+   - **If Brownfield:**
+     - Announce that an existing project has been detected.
+     - If the `git status --porcelain` command indicated uncommitted changes, inform the user: "WARNING: You have uncommitted changes in your Git repository. Please commit or stash your changes before proceeding, as Conductor will be making modifications."
+     - **Begin Brownfield Project Initialization Protocol:**
+       - **1.0 Pre-analysis Confirmation:**
+         1. **Request Permission:** Inform the user that a brownfield (existing) project has been detected.
+         2. **Ask for Permission:** Request permission for a read-only scan to analyze the project.
+         3. **Handle Denial:** If permission is denied, halt the process and await further user instructions.
+         4. **Confirmation:** Upon confirmation, proceed to the next step.
+
+       - **2.0 Code Analysis:**
+         1. **Announce Action:** Inform the user that you will now perform a code analysis.
+         2. **Prioritize README:** Begin by analyzing the `README.md` file, if it exists.
+         3. **Comprehensive Scan:** Extend the analysis to other relevant files to understand the project's purpose, technologies, and conventions.
+
+       - **2.1 File Size and Relevance Triage:**
+         1. **Respect Ignore Files:** Before scanning any files, check for `.gitignore` files. Use their patterns to exclude files and directories from your analysis.
+         2. **Efficiently List Relevant Files:** Use `git ls-files` or `find` commands that respect ignore files.
+         3. **Fallback to Manual Ignores:** If no `.gitignore` exists, manually ignore common directories like `node_modules`, `dist`, `build`, etc.
+         4. **Prioritize Key Files:** Focus on high-value files like `package.json`, `pom.xml`, `requirements.txt`, `go.mod`.
+         5. **Handle Large Files:** For files over 1MB, read only first and last 20 lines.
+
+       - **2.2 Extract and Infer Project Context:**
+         1. **Strict File Access:** DO NOT ask for more files. Base your analysis SOLELY on the provided file snippets.
+         2. **Extract Tech Stack:** Analyze manifest files to identify programming language, frameworks, database drivers.
+         3. **Infer Architecture:** Use the file tree to infer architecture type.
+         4. **Infer Project Goal:** Summarize the project's goal in one sentence.
+     - **Upon completing the brownfield initialization protocol, proceed to Section 2.1.**
+
+   - **If Greenfield:**
+     - Announce that a new project will be initialized.
+     - Proceed to the next step.
+
+3. **Initialize Git Repository (for Greenfield):**
+   - If a `.git` directory does not exist, execute `git init` and report to the user.
+
+4. **Inquire about Project Goal (for Greenfield):**
+   - **Ask the user:** "What do you want to build?"
+   - **CRITICAL:** You MUST NOT execute any tool calls until the user has provided a response.
+   - **Upon receiving the user's response:**
+     - Execute `mkdir -p conductor`.
+     - **Initialize State File:** Create `conductor/setup_state.json` with: `{"last_successful_step": ""}`
+     - Write the user's response into `conductor/product.md` under a header named `# Initial Concept`.
+
+5. **Continue:** Immediately proceed to the next section.
+
+### 2.1 Generate Product Guide (Interactive)
+
+1. **Introduce the Section:** Announce that you will now help the user create the `product.md`.
+2. **Ask Questions Sequentially:** Ask one question at a time. Wait for the user's response before asking the next question.
+   - **CONSTRAINT:** Limit your inquiry to a maximum of 5 questions.
+   - **SUGGESTIONS:** For each question, generate 3 high-quality suggested answers.
+   - **Example Topics:** Target users, goals, features, etc.
+   - **Format:** Present options as a vertical list (A, B, C, D, E).
+   - **Last options:** "Type your own answer" and "Autogenerate and review product.md".
+   - **AUTO-GENERATE LOGIC:** If user selects auto-generate, use your best judgment to infer remaining details.
+3. **Draft the Document:** Generate content for `product.md`. Source of truth is ONLY the user's selected answers.
+4. **User Confirmation Loop:** Present drafted content for review:
+   > "I've drafted the product guide. Please review:
+   > A) Approve
+   > B) Suggest Changes"
+5. **Write File:** Once approved, append to `conductor/product.md`.
+6. **Commit State:** Write `{"last_successful_step": "2.1_product_guide"}` to `conductor/setup_state.json`.
+7. **Continue:** Proceed to next section.
+
+### 2.2 Generate Product Guidelines (Interactive)
+
+1. **Introduce the Section:** Announce that you will help create `product-guidelines.md`.
+2. **Ask Questions Sequentially:** Maximum 5 questions about prose style, brand messaging, visual identity, etc.
+3. **Draft the Document:** Generate content for `product-guidelines.md`.
+4. **User Confirmation Loop:** Present for review.
+5. **Write File:** Write to `conductor/product-guidelines.md`.
+6. **Commit State:** Write `{"last_successful_step": "2.2_product_guidelines"}`.
+7. **Continue:** Proceed to next section.
+
+### 2.3 Generate Tech Stack (Interactive)
+
+1. **Introduce the Section:** Announce that you will define the technology stacks.
+2. **Ask Questions Sequentially:** Maximum 5 questions about languages, frameworks, databases.
+3. **For Brownfield:** State the inferred stack and ask for confirmation.
+4. **Draft the Document:** Generate content for `tech-stack.md`.
+5. **User Confirmation Loop:** Present for review.
+6. **Write File:** Write to `conductor/tech-stack.md`.
+7. **Commit State:** Write `{"last_successful_step": "2.3_tech_stack"}`.
+8. **Continue:** Proceed to next section.
+
+### 2.4 Select Code Styleguides (Interactive)
+
+1. **Initiate Dialogue:** Announce that you need user input to select style guides.
+2. **Select Code Style Guides:**
+   - List available style guides from the skill's assets.
+   - **For Greenfield:** Recommend based on Tech Stack, ask for confirmation or edit.
+   - **For Brownfield:** Infer from code analysis, ask for confirmation.
+   - **Action:** Copy selected files to `conductor/code_styleguides/`.
+3. **Commit State:** Write `{"last_successful_step": "2.4_code_styleguides"}`.
+
+### 2.5 Select Workflow (Interactive)
+
+1. **Copy Initial Workflow:** Copy the workflow template from skill assets to `conductor/workflow.md`.
+2. **Customize Workflow:** Ask user:
+   - A) Default (80% coverage, commit after each task, git notes)
+   - B) Customize
+3. **If Customize:** Ask about coverage percentage, commit frequency, summary method.
+4. **Commit State:** Write `{"last_successful_step": "2.5_workflow"}`.
+
+### 2.6 Finalization
+
+1. **Generate Index File:** Create `conductor/index.md`:
+   ```markdown
+   # Project Context
+
+   ## Definition
+   - [Product Definition](./product.md)
+   - [Product Guidelines](./product-guidelines.md)
+   - [Tech Stack](./tech-stack.md)
+
+   ## Workflow
+   - [Workflow](./workflow.md)
+   - [Code Style Guides](./code_styleguides/)
+
+   ## Management
+   - [Tracks Registry](./tracks.md)
+   - [Tracks Directory](./tracks/)
+   ```
+
+2. **Summarize Actions:** Present summary of all actions taken.
+3. **Transition:** Announce proceeding to initial track generation.
+
+---
+
+## 3.0 INITIAL PLAN AND TRACK GENERATION
+
+**PROTOCOL: Interactively define project requirements, propose a single track, and automatically create track artifacts.**
+
+### 3.1 Generate Product Requirements (Greenfield Only)
+
+1. **Transition to Requirements:** Announce defining high-level product requirements.
+2. **Analyze Context:** Read `conductor/product.md`.
+3. **Ask Questions Sequentially:** Maximum 5 questions about user stories, functional/non-functional requirements.
+4. **Continue:** Proceed to next section.
+
+### 3.2 Propose Initial Track (Automated + Approval)
+
+1. **State Your Goal:** Announce proposing an initial track.
+2. **Generate Track Title:** Based on project context, generate a track title.
+3. **User Confirmation:** Present for approval. If declined, ask for clarification.
+
+### 3.3 Create Track Artifacts (Automated)
+
+1. **State Your Goal:** Announce creating track artifacts.
+2. **Initialize Tracks File:** Create `conductor/tracks.md` with the first track.
+3. **Generate Track Artifacts:**
+   a. **Generate Track ID:** Format `shortname_YYYYMMDD`.
+   b. **Create Directory:** `conductor/tracks/<track_id>/`.
+   c. **Create metadata.json:** With track_id, type, status, timestamps, description.
+   d. **Write spec.md:** Track specification.
+   e. **Write plan.md:** Implementation plan with tasks following workflow methodology.
+   f. **Write index.md:** Track context index.
+4. **Commit State:** Write `{"last_successful_step": "3.3_initial_track_generated"}`.
+5. **Announce Progress:** Announce track creation.
+
+### 3.4 Final Announcement
+
+1. **Announce Completion:** Project setup and initial track generation complete.
+2. **Save Conductor Files:** Commit all files with message `conductor(setup): Add conductor setup files`.
+3. **Next Steps:** Inform user to run `/conductor-implement` to begin work.

package/skills/conductor-setup/assets/code_styleguides/cpp.md

@@ -0,0 +1,113 @@
+# Google C++ Style Guide Summary
+
+## 1. Naming
+- **General:** Optimize for readability. Be descriptive but concise. Use inclusive language.
+- **Files:** `.h` (headers), `.cc` (source). Lowercase with underscores (`_`) or dashes (`-`). Be consistent.
+- **Types:** PascalCase (`MyClass`, `MyEnum`). Use `int` by default; use `<cstdint>` (`int32_t`) if size matters.
+- **Concepts:** PascalCase (`MyConcept`).
+- **Variables:** snake_case (`my_var`). Class members end with underscore (`my_member_`), struct members do not.
+- **Constants/Enumerators:** `k` + PascalCase (`kDays`, `kOk`).
+- **Template Parameters:** PascalCase for types (`T`, `MyType`), snake_case/kPascalCase for non-types (`N`, `kLimit`).
+- **Functions:** PascalCase (`GetValue()`).
+- **Accessors/Mutators:** snake_case. `count()` (not `GetCount`), `set_count(v)`.
+- **Namespaces:** lowercase (`web_search`).
+- **Macros:** ALL_CAPS (`MY_MACRO`).
+
+## 2. Header Files
+- **General:** Every `.cc` usually has a `.h`. Headers must be self-contained.
+- **Guards:** Use `#define <PROJECT>_<PATH>_<FILE>_H_`.
+- **IWYU:** Direct includes only. Do not rely on transitive includes.
+- **Forward Decls:** Avoid. Include headers instead. **Never** forward declare `std::` symbols.
+- **Inline Definitions:** Only short functions (<10 lines) in headers. Must be ODR-safe (`inline` or templates).
+- **Include Order:**
+  1. Related header (`foo.h`)
+  2. C system (`<unistd.h>`)
+  3. C++ standard (`<vector>`)
+  4. Other libraries (`<Python.h>`)
+  5. Project headers (`"base/logging.h"`)
+  *Separate groups with blank lines. Alphabetical within groups.*
+
+## 3. Formatting
+- **Indentation:** 2 spaces. **Line Length:** 80 chars.
+- **Non-ASCII:** Rare, use UTF-8. Avoid `u8` prefix if possible.
+- **Braces:** `if (cond) { ... }`. **Exception:** Function definition open brace goes on the **next line**.
+- **Switch:** Always include `default`. Use `[[fallthrough]]` for explicit fallthrough.
+- **Literals:** Floating-point must have radix point (`1.0f`).
+- **Calls:** Wrap arguments at paren or 4-space indent.
+- **Init Lists:** Colon on new line, indent 4 spaces.
+- **Namespaces:** No indentation.
+- **Vertical Whitespace:** Use sparingly. Separate related chunks, not code blocks.
+- **Loops/Branching:** Use braces (optional if single line). No space after `(`, space before `{`.
+- **Return:** No parens `return result;`.
+- **Preprocessor:** `#` always at line start.
+- **Pointers:** `char* c` (attached to type).
+- **Templates:** No spaces inside `< >` (`vector<int>`).
+- **Operators:** Space around assignment/binary, no space for unary.
+- **Class Order:** `public`, `protected`, `private`.
+- **Parameter Wrapping:** Wrap parameter lists that don't fit. Use 4-space indent for wrapped parameters.
+
+## 4. Classes
+- **Constructors:** `explicit` for single-arg and conversion operators. **Exception:** `std::initializer_list`. No virtual calls in ctors. Use factories for fallible init.
+- **Structs:** Only for passive data. Prefer `struct` over `std::pair` or `std::tuple`.
+- **Copy/Move:** Explicitly `= default` or `= delete`. **Rule of 5:** If defining one, declare all.
+- **Inheritance:** `public` only. Composition > Inheritance. Use `override` (omit `virtual`). No multiple implementation inheritance.
+- **Operator Overloading:** Judicious use only. Binary ops as non-members. Never overload `&&`, `||`, `,`, or unary `&`. No User-Defined Literals.
+- **Access:** Data members `private` (except structs/constants).
+- **Declaration Order:** `public` before `protected` before `private`. Within sections: Types, Constants, Factory, Constructors, Destructor, Methods, Data Members.
+
+## 5. Functions
+- **Params:** Inputs (`const T&`, `std::string_view`, `std::span` or value) first, then outputs. **Ordering:** Inputs before outputs.
+- **Outputs:** Prefer return values/`std::optional`. For non-optional outputs, use references. For optional outputs, use pointers.
+- **Optional Inputs:** Use `std::optional` for by-value, `const T*` for reference.
+- **Nonmember vs Static:** Prefer nonmember functions in namespaces over static member functions.
+- **Length:** Prefer small (<40 lines).
+- **Overloading:** Use only when behavior is obvious. Document overload sets with a single umbrella comment.
+- **Default Args:** Allowed on non-virtual functions only (value must be fixed/constant).
+- **Trailing Return:** Only when necessary (lambdas).
+
+## 6. Scoping
+- **Namespaces:** No `using namespace`. Use `using std::string`. Never add to `namespace std`.
+- **Internal:** Use anonymous namespaces or `static` in `.cc` files. Avoid in headers.
+- **Locals:** Narrowest scope. Initialize at declaration. **Exception:** Declare complex objects outside loops.
+- **Static/Global:** Must be **trivially destructible** (e.g., `constexpr`, raw pointers, arrays). No global `std::string`, `std::map`, smart pointers. Dynamic initialization allowed only for function-static variables.
+- **Thread Local:** `thread_local` must be `constinit` if global. Prefer `thread_local` over other mechanisms.
+
+## 7. Modern C++ Features
+- **Version:** Target **C++20**. Do not use C++23. Consider portability for C++17/20 features. No non-standard extensions.
+- **Modules:** Do not use C++20 Modules.
+- **Coroutines:** Use approved libraries only. Do not roll your own promise or awaitable types.
+- **Concepts:** Prefer C++20 Concepts (`requires`) over `std::enable_if`. Use `requires(Concept<T>)`, not `template<Concept T>`.
+- **R-Value References:** Use only for move ctors/assignment, perfect forwarding, or consuming `*this`.
+- **Smart Pointers:** `std::unique_ptr` (exclusive), `std::shared_ptr` (shared). No `std::auto_ptr`.
+- **Auto:** Use when type is obvious (`make_unique`, iterators). Avoid for public APIs.
+- **CTAD:** Use only if explicitly supported (deduction guides exist).
+- **Structured Bindings:** Use for pairs/tuples. Comment aliased field names.
+- **Nullptr:** Use `nullptr`, never `NULL` or `0`.
+- **Constexpr:** Use `constexpr`/`consteval` for constants/functions whenever possible. Use `constinit` for static initialization.
+- **Noexcept:** Specify when useful/correct. Prefer unconditional `noexcept` if exceptions are disabled.
+- **Lambdas:** Prefer explicit captures (`[&x]`) if escaping scope. Avoid `std::bind`.
+- **Initialization:** Prefer brace init. **Designated Initializers:** Allowed (C++20 ordered form only).
+- **Casts:** Use C++ casts (`static_cast`). Use `std::bit_cast` for type punning.
+- **Loops:** Prefer range-based `for`.
+
+## 8. Best Practices
+- **Const:** Mark methods/variables `const` whenever possible. `const` methods must be thread-safe.
+- **Exceptions:** **Forbidden**.
+- **RTTI:** Avoid `dynamic_cast`/`typeid`. Allowed in unit tests. Do not hand-implement workarounds.
+- **Macros:** Avoid. Use `constexpr`/`inline`. If needed, define close to use and `#undef` immediately. Do not define in headers.
+- **0 and nullptr:** Use `nullptr` for pointers, `\0` for chars, not `0`.
+- **Streams:** Use streams primarily for logging. Prefer printf-style formatting or absl::StrCat.
+- **Types:** Avoid `unsigned` for non-negativity. No `long double`.
+- **Pre-increment:** Prefer `++i` over `i++`.
+- **Sizeof:** Prefer `sizeof(varname)` over `sizeof(type)`.
+- **Friends:** Allowed, usually defined in the same file.
+- **Boost:** Use only approved libraries (e.g., Call Traits, Compressed Pair, BGL, Property Map, Iterator, etc.).
+- **Aliases:** Use `using` instead of `typedef`. Public aliases must be documented.
+- **Ownership:** Single fixed owner. Transfer via smart pointers.
+- **Aliases:** Document intent. Don't use in public API for convenience. `using` > `typedef`.
+- **Switch:** Always include `default`. Use `[[fallthrough]]` for explicit fallthrough.
+- **Comments:** Document File, Class, Function (params/return). Use `//` or `/* */`. Implementation comments for tricky code. `TODO(user):` format.
+
+**BE CONSISTENT.** Follow existing code style.
+
+*Source: [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html)*

package/skills/conductor-setup/assets/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)*