@cbnventures/nova 0.14.0 → 0.15.0

package/build/templates/generators/must-haves/agent-conventions/conventions/php.md

@@ -0,0 +1,257 @@
+# PHP Conventions
+
+Quotes: Single (non-interpolated). Indentation: 4-space. File naming: PascalCase (PSR-4) or snake_case (e.g., `EntityRepository.php`).
+
+## Documentation Style
+
+- Comment syntax: `/** */`
+- Padding tag: `@since 1.0.0` (PHPDoc)
+- Param format: `@param type $name - Name.` (description matches the parameter name, capitalized, with a trailing period)
+- Return format: `@return type`
+- Include `@private` tag for private members.
+
+### Example
+
+```php
+/**
+ * Backup Config File.
+ *
+ * @param string $backup_name - Backup name.
+ * @param string $conf_path   - Conf path.
+ * @param string $backup_path - Backup path.
+ *
+ * @return void
+ *
+ * @since 1.0.0
+ */
+function backup_config_file(
+    string $backup_name,
+    string $conf_path,
+    string $backup_path
+): void { ... }
+```
+
+## Code Style
+
+### Strict Types Declaration
+
+Every PHP file starts with `declare(strict_types=1)` immediately after the opening `<?php` tag.
+
+```php
+<?php
+
+declare(strict_types=1);
+```
+
+### Explicit Access Modifiers
+
+All class members require explicit `public`, `private`, or `protected`. Never rely on PHP's implicit public.
+
+```php
+// BAD — implicit public
+function processData(string $input): void { ... }
+
+// GOOD — explicit modifier
+public function processData(string $input): void { ... }
+private function validateInput(string $input): void { ... }
+```
+
+### Type Declarations Everywhere
+
+All function parameters, return types, and class properties must have explicit type declarations. Use union types (`string|int`) and nullable types (`?string`) where needed.
+
+```php
+// BAD — no type declarations
+function findById($id) { ... }
+
+// GOOD — fully typed
+public function findById(string $id): ?Entity { ... }
+```
+
+### `readonly` Properties
+
+Use `readonly` on properties assigned once in the constructor, never reassigned after (PHP 8.1+).
+
+```php
+public function __construct(
+    private readonly Database $database,
+    private readonly Logger $logger,
+) { ... }
+```
+
+### Method Ordering
+
+1. Public methods first.
+2. Private methods second.
+
+Each method separated by a blank line. No blank line after opening brace or before closing brace of the class.
+
+### `match` Expression — Always Include `default`
+
+Prefer `match` over `switch` for value mapping. Always include a `default` arm.
+
+```php
+$label = match ($category) {
+    'added' => 'New feature',
+    'fixed' => 'Bug fix',
+    default => 'Unknown',
+};
+```
+
+For side-effect branches, use `switch` with block-scoped `case` and always include `default`:
+
+```php
+switch ($category) {
+    case 'added': {
+        $logger->info('New feature.');
+        break;
+    }
+
+    case 'fixed': {
+        $logger->info('Bug fix.');
+        break;
+    }
+
+    default: {
+        $logger->warn('Unknown category.');
+        break;
+    }
+}
+```
+
+### Explicit Null Checks
+
+Always use explicit comparisons. No truthy/falsy shortcuts.
+
+- `=== null` — not set.
+- `!== null` — present.
+- `=== ''` — explicit empty string check.
+- `count($array) > 0` — explicit array length check.
+- `??` — null coalescing for defaults (fine to use).
+
+```php
+// BAD — truthy check
+if ($name) { ... }
+
+// GOOD — explicit checks
+if ($name !== null) { ... }
+if ($name !== '') { ... }
+if (count($items) > 0) { ... }
+
+// GOOD — null coalescing for defaults
+$timeout = $options['timeout'] ?? 5000;
+```
+
+### Array Functions vs `foreach`
+
+- `array_filter()`, `array_map()` — transforming or searching, returns a new value.
+- `foreach` — side effects (logging, mutating external state).
+- `array_reduce()` — acceptable, but `foreach` with a mutable accumulator is also fine.
+
+### Descriptive Callback Parameter Names
+
+Derive from the collection name in singular form. Array and iterable variable names must end with a plural noun so the singular form can be derived naturally. No single-letter abbreviations.
+
+```php
+// BAD
+array_filter($valid_categories, fn($c) => $c === $value);
+
+// GOOD
+array_filter(
+    $valid_categories,
+    fn(string $valid_category) => $valid_category === $value
+);
+```
+
+### Arrow Functions vs Anonymous Functions
+
+- **Arrow function** (`fn() =>`): Single expression, no side effects.
+- **Anonymous function** (`function() { }`): Multiple statements or side effects.
+
+```php
+// Arrow function — single expression
+$names = array_map(
+    fn(Item $item) => $item->getName(),
+    $items
+);
+
+// Anonymous function — multiple statements
+$results = array_map(
+    function (Item $item) {
+        $item_name = $item->getName();
+        $item_role = $item->getRole();
+
+        return new ItemResult($item_name, $item_role);
+    },
+    $items
+);
+```
+
+### Variable Names Chain from Parent
+
+When extracting properties from an object, the variable name chains from the parent variable name.
+
+```php
+$workspace_config = $workspace->getConfig();
+$workspace_config_name = $workspace_config->getName();
+$workspace_config_role = $workspace_config->getRole();
+```
+
+### Comment Placement in Method Bodies
+
+Comments describe the process/intent. Placement rules:
+- Comment sits above the code block it describes.
+- Blank line before the comment (except at the start of a scope).
+- No comment needed on the first block if it's self-explanatory.
+- No trailing comments (same-line comments after code). Exception: multi-line conditions may use inline `//` comments after each condition line to explain the check.
+
+### No Stacked Comments
+
+One descriptive comment per code block. No consecutive comments without code between them.
+
+### Quote File Names in Comments and Log Messages
+
+Wrap file names in double quotes inside comments and log strings (e.g., `"config.json"`, `"CHANGELOG.md"`).
+
+### Blank Lines between Distinct Operations
+
+Separate function calls and different logical blocks with blank lines. Variable declarations and loops also need blank line separation.
+
+### Bare Side-Effect Statements Get Their Own Visual Group
+
+When a function call has no assignment (return value unused), separate it from surrounding assignments with a blank line.
+
+### Return Directly When Immediately Returned
+
+Don't assign to an intermediate variable just to return it on the next line.
+
+### Extract Nested Function Calls into Variables
+
+Don't nest function calls as arguments to other function calls. Extract into its own named variable for readability.
+
+### One Entry per Line in Collections
+
+Array literals and similar collections use one entry per line in multiline constructs.
+
+### Mixed Logical Conditions
+
+When mixing `&&`/`||`, parenthesized groups go on their own lines, each condition on its own line.
+
+### No Multi-Line Boolean Variable Assignments for `if`
+
+Don't extract a multi-condition boolean into a named variable just to check it once. Inline conditions directly in `if` blocks.
+
+### Ternary Expressions
+
+- No nested ternaries.
+- No ternaries inside string interpolation — extract to a variable first.
+
+### Readability — All Generated Code Must Be Human-Readable
+
+Don't inline complex expressions into string interpolation or other expressions. Break them into named variables so each step is clear.
+
+### Error Handling
+
+- **Creator** (function designer): may design a function to throw on failure — that's the API contract.
+- **Consumer** (function caller): always wraps calls to throwing functions in try/catch.
+- CLI entry points never throw — set the appropriate exit code with `exit()` and return.

package/build/templates/generators/must-haves/agent-conventions/conventions/python.md

@@ -0,0 +1,260 @@
+# Python Conventions
+
+Quotes: Double (Black/Google convention). Indentation: 4-space. File naming: snake_case (PEP 8) (e.g., `entity_repository.py`).
+
+## Documentation Style
+
+- Comment syntax: `"""` (Google-style)
+- Padding tag: `Version:\n    1.0.0` (Google-style custom section)
+- Param format: `Args:\n    name: Name.` (description matches the parameter name, capitalized, with a trailing period)
+- Return format: `Returns:\n    Type.`
+- Docstring starts with `"""` then a newline before the summary line.
+- No `@private` tag; use `_` prefix naming instead.
+
+### Example
+
+```python
+class EntityRepository:
+    """
+    Entity Repository.
+
+    Version:
+        1.0.0
+    """
+
+    def __init__(self, database):
+        """
+        Entity Repository - Constructor.
+
+        Args:
+            database: Database.
+
+        Version:
+            1.0.0
+        """
+        self._database = database
+
+    def find_by_id(self, entity_id):
+        """
+        Entity Repository - Find By ID.
+
+        Args:
+            entity_id: ID.
+
+        Returns:
+            Entity.
+
+        Version:
+            1.0.0
+        """
+        return self._database.get(entity_id)
+```
+
+## Code Style
+
+### Private Members — `_` Prefix Convention
+
+Use `_` prefix for private methods and attributes. Use `__` (name mangling) only when subclass collision avoidance is genuinely needed.
+
+```python
+# GOOD — single underscore for private
+self._database = database
+self._cache = {}
+
+def _validate_input(self, value):
+    ...
+
+# Only when subclass collision is a real concern
+def __internal_reset(self):
+    ...
+```
+
+### Type Hints Everywhere
+
+All function parameters, return types, and class attributes must have type hints. Use `from __future__ import annotations` for forward references.
+
+```python
+from __future__ import annotations
+
+def find_by_id(self, entity_id: str) -> Entity | None:
+    ...
+
+def process_items(self, items: list[Item]) -> list[Result]:
+    ...
+```
+
+### `Final` and Immutability
+
+Use `typing.Final` for constants that should never be reassigned. Python has no `const` — `Final` is the closest equivalent.
+
+```python
+from typing import Final
+
+MAX_RETRIES: Final[int] = 3
+DEFAULT_TIMEOUT: Final[int] = 5000
+```
+
+### Method Ordering
+
+1. Public methods first.
+2. Private methods second (prefix `_`).
+
+Each method separated by a blank line. No blank line after class declaration or before closing of the class.
+
+### `match` Statement — Always Include Wildcard
+
+Always include a `case _` wildcard (Python 3.10+). Each case uses a block.
+
+```python
+match category:
+    case "added":
+        logger.info("New feature.")
+
+    case "fixed":
+        logger.info("Bug fix.")
+
+    case _:
+        logger.warning("Unknown category.")
+```
+
+### Explicit `None` Checks — No Truthy/Falsy
+
+Always use explicit comparisons. No truthy/falsy shortcuts.
+
+- `is None` — not set.
+- `is not None` — present.
+- `== ""` — explicit empty string.
+- `len(items) > 0` — explicit length check.
+
+```python
+# BAD — truthy check
+if name:
+    ...
+
+# GOOD — explicit checks
+if name is not None:
+    ...
+if name != "":
+    ...
+if len(items) > 0:
+    ...
+```
+
+### List Comprehensions vs `map`/`filter` vs `for` Loop
+
+- List comprehensions — transforming or filtering, returns a new list. Prefer over `map()`/`filter()`.
+- `for` loop — side effects (logging, mutating external collections, async operations).
+- `functools.reduce()` — acceptable, but `for` with a mutable accumulator is also fine.
+
+```python
+# GOOD — list comprehension for transformation
+names = [item.name for item in items if item.is_active]
+
+# GOOD — for loop for side effects
+for item in items:
+    logger.info(item.name)
+```
+
+### Descriptive Loop Variable Names
+
+Derive from the collection name in singular form. Array and iterable variable names must end with a plural noun so the singular form can be derived naturally. No single-letter abbreviations.
+
+```python
+# BAD
+for c in valid_categories:
+    ...
+
+# GOOD
+for valid_category in valid_categories:
+    ...
+
+# More examples
+for raw_path in raw_paths:
+    ...
+for allowed_policy in allowed_policies:
+    ...
+```
+
+### Variable Names Chain from Parent
+
+When extracting properties from an object, the variable name chains from the parent variable name.
+
+```python
+workspace_config = workspace.config
+workspace_config_name = workspace_config.name
+workspace_config_role = workspace_config.role
+```
+
+### Comment Placement in Method Bodies
+
+Comments describe the process/intent. Placement rules:
+- Comment sits above the code block it describes.
+- Blank line before the comment (except at the start of a scope).
+- No comment needed on the first block if it's self-explanatory.
+- No trailing comments (same-line comments after code). Exception: multi-line conditions may use inline `#` comments after each condition line to explain the check.
+
+### No Stacked Comments
+
+One descriptive comment per code block. No consecutive comments without code between them.
+
+### Quote File Names in Comments and Log Messages
+
+Wrap file names in double quotes inside comments and log strings (e.g., `"config.json"`, `"CHANGELOG.md"`).
+
+### Blank Lines between Distinct Operations
+
+Separate function calls, `await` statements, and different logical blocks with blank lines. Variable declarations and loops also need blank line separation.
+
+```python
+# BAD — everything stuck together
+config_raw = path.read_text()
+config = parser.parse(config_raw)
+filtered = filter_items(config.items)
+
+# GOOD — each operation gets breathing room
+config_raw = path.read_text()
+
+config = parser.parse(config_raw)
+
+filtered = filter_items(config.items)
+```
+
+### Bare Side-Effect Statements Get Their Own Visual Group
+
+When a function call has no assignment (return value unused), separate it from surrounding assignments with a blank line.
+
+### Return Directly When Immediately Returned
+
+Don't assign to an intermediate variable just to return it on the next line.
+
+### Extract Nested Function Calls into Variables
+
+Don't nest function calls as arguments to other function calls. Extract into its own named variable for readability.
+
+### One Entry per Line in Collections
+
+List literals, dict literals, and similar collections use one entry per line in multiline constructs.
+
+### Mixed Logical Conditions
+
+When mixing `and`/`or`, parenthesized groups go on their own lines, each condition on its own line.
+
+### No Multi-Line Boolean Variable Assignments for `if`
+
+Don't extract a multi-condition boolean into a named variable just to check it once. Inline conditions directly in `if` blocks.
+
+### Inline `if`/`else` Expressions
+
+Python's ternary is `value_a if condition else value_b`. Same rules apply:
+- No nested inline `if`/`else` chains.
+- No inline `if`/`else` inside f-strings — extract to a variable first.
+
+### Readability — All Generated Code Must Be Human-Readable
+
+Don't inline complex expressions into f-strings or other expressions. Break them into named variables so each step is clear.
+
+### Error Handling
+
+- **Creator** (function designer): may design a function to raise on failure — that's the API contract.
+- **Consumer** (function caller): always wraps calls to raising functions in `try`/`except`.
+- CLI entry points never raise — set the appropriate exit code with `sys.exit()` and return.

package/build/templates/generators/must-haves/agent-conventions/conventions/shell.md

@@ -0,0 +1,205 @@
+# Shell Conventions
+
+Quotes: Double (for variable expansion). Indentation: 2-space. File naming: kebab-case (e.g., `backup-config.sh`).
+
+## Documentation Style
+
+Section banners and inline comments only. No doc comment blocks. Shell uses `#` with `=` borders:
+
+```bash
+# ============================
+# Section Title
+# ============================
+```
+
+## Code Style
+
+### Strict Mode
+
+Every shell script starts with `set -euo pipefail` after the shebang.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+```
+
+### `SCRIPT_DIR` Detection
+
+Every script that references relative paths must detect its own directory.
+
+```bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+```
+
+### `main()` Entry Point
+
+Scripts use a `main()` function as the entry point, called at the bottom of the file.
+
+```bash
+main() {
+  # Script logic here.
+  ...
+}
+
+main "$@"
+```
+
+### Variable Quoting
+
+Always double-quote variables. Unquoted variables cause word splitting and glob expansion.
+
+```bash
+# BAD — unquoted
+cp $source_file $dest_dir
+
+# GOOD — quoted
+cp "${source_file}" "${dest_dir}"
+```
+
+### Variable Naming
+
+- Local variables: `snake_case` (lowercase).
+- Environment/exported variables: `UPPER_SNAKE_CASE`.
+- Use `local` for function-scoped variables.
+
+```bash
+# GOOD
+local config_path="${SCRIPT_DIR}/config.json"
+local output_dir="${1:-./output}"
+
+export APP_VERSION="1.0.0"
+```
+
+### Descriptive Loop Variable Names
+
+Derive from the collection name in singular form. Array and iterable variable names must end with a plural noun so the singular form can be derived naturally. No single-letter abbreviations.
+
+```bash
+# BAD
+for f in "${workflow_files[@]}"; do
+
+# GOOD
+for workflow_file in "${workflow_files[@]}"; do
+```
+
+### Comment Placement
+
+Comments describe the process/intent. Placement rules:
+- Comment sits above the code block it describes.
+- Blank line before the comment (except at the start of a scope).
+- No comment needed on the first block if it's self-explanatory.
+- No trailing comments (same-line comments after code). Exception: multi-line conditions may use inline `#` comments after each condition line to explain the check.
+
+### No Stacked Comments
+
+One descriptive comment per code block. No consecutive comments without code between them.
+
+### Quote File Names in Comments and Log Messages
+
+Wrap file names in double quotes inside comments and log strings (e.g., `"config.json"`, `"CHANGELOG.md"`).
+
+### Blank Lines between Distinct Operations
+
+Separate commands and different logical blocks with blank lines. Variable declarations and loops also need blank line separation.
+
+```bash
+# BAD — everything stuck together
+local config_raw
+config_raw="$(cat "${config_path}")"
+local items
+items="$(echo "${config_raw}" | jq '.items')"
+process_items "${items}"
+
+# GOOD — each operation gets breathing room
+local config_raw
+config_raw="$(cat "${config_path}")"
+
+local items
+items="$(echo "${config_raw}" | jq '.items')"
+
+process_items "${items}"
+```
+
+### Return Directly When Immediately Returned
+
+Don't assign to an intermediate variable just to echo it on the next line.
+
+### Extract Nested Commands into Variables
+
+Don't nest command substitutions. Extract into its own named variable for readability.
+
+```bash
+# BAD — nested substitutions
+local result
+result="$(basename "$(dirname "${file_path}")")"
+
+# GOOD — extracted
+local parent_dir
+parent_dir="$(dirname "${file_path}")"
+
+local result
+result="$(basename "${parent_dir}")"
+```
+
+### One Entry per Line in Arrays
+
+Array literals use one entry per line in multiline constructs.
+
+```bash
+local platforms=(
+  "nodejs"
+  "swift"
+  "kotlin"
+  "docker"
+)
+```
+
+### Conditional Expressions
+
+Use `[[ ]]` over `[ ]`. Always use explicit comparisons.
+
+```bash
+# BAD — single bracket, implicit check
+if [ $name ]; then
+
+# GOOD — double bracket, explicit check
+if [[ -n "${name}" ]]; then
+if [[ "${count}" -gt 0 ]]; then
+if [[ "${value}" == "expected" ]]; then
+```
+
+### `case` Statement — Always Include Wildcard
+
+Always include a `*)` wildcard. Each pattern uses `;;` terminator.
+
+```bash
+case "${category}" in
+  "added")
+    info "New feature."
+    ;;
+
+  "fixed")
+    info "Bug fix."
+    ;;
+
+  *)
+    warn "Unknown category."
+    ;;
+esac
+```
+
+### Error Handling
+
+- Functions that can fail should return non-zero exit codes.
+- Callers check return codes or use `||` for error handling.
+- Scripts never leave errors unhandled — `set -e` catches unchecked failures.
+- Use `trap` for cleanup on exit.
+
+```bash
+trap cleanup EXIT
+
+cleanup() {
+  # Remove temporary files.
+  rm -f "${tmp_file}"
+}
+```