get-tbd 0.1.8

package/dist/docs/guidelines/general-coding-rules.md

@@ -0,0 +1,36 @@
+---
+title: General Coding Rules
+description: Rules for constants, magic numbers, and general coding practices
+---
+# General Coding Rules
+
+## Constants and Magic Numbers
+
+- NEVER hardcode numeric values directly in code.
+  Always use descriptive named constants.
+
+- All numeric constants must have clear, descriptive names and docstrings explaining
+  their purpose.
+
+- Constants should be defined in appropriate settings files (e.g., `settings.ts`) for
+  easy maintenance.
+
+  ```typescript
+  // BAD: Hardcoded numbers
+  const tradeCount = Math.min(trades.length, 50);
+  
+  // GOOD: Named constants with documentation
+  /**
+   * Execution statistics counting limits for dialog tab display.
+   * These control the "X+" display thresholds and query performance.
+   */
+  export const EXECUTION_STATS_LIMITS = {
+    /** Maximum trades to count before showing "50+" */
+    maxTradeCount: 50,
+    /** Maximum conversation turns to count before showing "100+" */
+    maxConversationTurnCount: 100,
+  } as const;
+  
+  // Usage:
+  const tradeCount = Math.min(trades.length, EXECUTION_STATS_LIMITS.maxTradeCount);
+  ```

package/dist/docs/guidelines/general-comment-rules.md

@@ -0,0 +1,45 @@
+---
+title: General Comment Rules
+description: Language-agnostic rules for writing clean, maintainable comments
+---
+# General Comment Rules
+
+## Comment Usage
+
+- Keep all comments concise and clear and suitable for inclusion in final production.
+
+- DO use comments whenever the intent of a given piece of code is subtle or confusing or
+  avoids a bug or is not obvious from the code itself.
+
+- DO NOT repeat in comments what is obvious from the names of functions or variables or
+  types.
+
+- DO NOT make any other obvious comments that duplicate messages, such as a comment that
+  repeats what is in a log message.
+
+- DO NOT include comments that reflect what you did, such as “Added this function” as
+  this is meaningless to anyone reading the code later.
+
+- DO NOT use fancy or needlessly decorated headings like “===== MIGRATION TOOLS =====”
+  in comments.
+
+- DO NOT number steps in comments.
+  These are hard to maintain if the code changes.
+  NEVER: “// Step 3: Fetch the data from the cache” OK: “// Now fetch the data from the
+  cache”
+
+- DO NOT use emojis or special unicode characters like ① or • or – or — in comments.
+
+- DO NOT leave comments about code changes that have been completed.
+
+- DO NOT put values of constants in comments (redundant and clutters the code).
+
+- DO NOT leave straggling comments that refer to past implementations or refactors.
+
+## Comment Syntax
+
+- Use appropriate syntax for IDE-compatible comments whenever possible, e.g. TypeScript,
+  prefer `/** ... */` comments wherever appropriate on variables, functions, methods,
+  and at the top of files.
+
+- See language-specific comment rules for more details.

package/dist/docs/guidelines/general-eng-assistant-rules.md

@@ -0,0 +1,54 @@
+---
+title: General Engineering Assistant Rules
+description: Rules for AI assistants acting as senior engineers, including objectivity and communication guidelines
+---
+# General Engineering Assistant Rules
+
+**Your responsibility:** Remember you are a senior engineer and have a serious
+responsibility to be clear, factual, think step by step and be systematic.
+Your fundamental responsibility is to achieve objectives and make use of the user’s
+attention wisely.
+
+**Rules must be followed:** It is your responsibility to carefully read these rules as
+well as all other rules, such as language-specific rules in the `rules/` or `docs/`
+folder or supplied by the user.
+
+**Do not be overly agreeable:** You should offer expert opinions, not blindly follow
+common practices. You must be willing to disagree with common practice when that is the
+best course of action for a given situation.
+You must be willing to express disagreement with the user and suggest alternative
+solutions if they are technically relevant.
+
+**Do not be a people-pleaser:** Do not try to make the user happy or give positive spin
+on technical issues: Even if the user might be happier if you exaggerate quality or talk
+about your work in subjective, positive terms, *this is dishonest and not the job of a
+professional engineer*. Your responsibility is to be insightful, accurate, and fair.
+
+Therefore:
+
+- Be concise. State answers or responses directly, without extra commentary.
+  Or (if it is clear) directly do what is asked.
+
+- If instructions are unclear or there are two or more ways to fulfill the request that
+  are substantially different, make a tentative plan (or offer options) and ask for
+  confirmation.
+
+- If you can think of a much better approach that the user requests, be sure to mention
+  it. It’s your responsibility to suggest approaches that lead to better, simpler
+  solutions.
+
+- Give thoughtful opinions on better/worse approaches, but NEVER say “great idea!”
+  or “good job” or other compliments, encouragement, or non-essential banter.
+  Your job is to give expert opinions and to solve problems, not to motivate the user.
+
+- Do not say code is “production-ready” if you have no direct factual basis for this.
+  Say it passes the tests and describe the tests, but if it’s not been tested in
+  production-like situations it is not production ready.
+
+- Avoid gratuitous enthusiasm or generalizations.
+  Use thoughtful comparisons like saying which code is “cleaner” but don’t congratulate
+  yourself. Avoid subjective descriptions.
+  For example, don’t say “I’ve meticulously improved the code and it is in great shape!”
+  That is useless generalization.
+  Instead, specifically say what you’ve done, e.g., "I’ve added types, including
+  generics, to all the methods in `Foo` and fixed all linter errors."

package/dist/docs/guidelines/general-style-rules.md

@@ -0,0 +1,37 @@
+---
+title: General Style Rules
+description: Style guidelines for auto-formatting, emoji usage, and output formatting
+---
+# General Style Rules
+
+## Always Auto-Format
+
+Always use auto-formatting on every file type possible.
+Defer to rules on auto-formatting for exact coding style in each language.
+
+## Use of Emojis
+
+These rules apply to output and other messages, comments, log messages, user messages,
+and UI messages.
+
+- **Use of emojis:**
+
+  - **Do not use emojis gratuitously:** Use emojis in output only if it enhances the
+    clarity and can be done with a consistent semantic vocabulary.
+
+  - DO use ✅ and ❌ (or if the codebase already uses them, ✔︎ and ✘) to indicate success
+    and failure and ⚠️ and ‼️ (or if the codebase already uses them, ∆ and ‼︎)
+    user-facing warnings and errors.
+    Whatever you use, just be sure to do it consistently across the codebase.
+
+  - You MAY use the following emojis if you use them consistently:
+
+    - 📈 for reports and quantitative summaries
+
+    - ⏰ for timings and scheduling
+
+    - 🧪 for tests and experiments
+
+  - DO NOT use emojis in comments or output just because they are fun or cute.
+    Unless the user says otherwise, avoid emojis and Unicode in comments as it adds
+    distraction without the benefit of systematic meaning.

package/dist/docs/guidelines/general-tdd-guidelines.md

@@ -0,0 +1,52 @@
+---
+title: TDD Guidelines
+description: Test-Driven Development methodology and best practices
+---
+# Test-Driven Development (TDD) Guidelines
+
+## Core Development Principles
+
+- Run Red -> Green -> Refactor in small slices.
+- Start with the simplest failing test that describes behavior.
+- Write only the code needed to pass; defer polish until Green.
+- Separate structural vs behavioral work; tidy first when both are needed.
+- Keep quality high at every step; avoid speculative work.
+
+## TDD Methodology
+
+- Write one failing test at a time; keep the failure clear and specific.
+- Name tests by observable behavior (e.g., `should_sum_two_positive_numbers`).
+- Prefer state-based assertions; only mock external boundaries.
+- Keep tests fast, deterministic, and isolated (no real time, network, randomness).
+- Minimize test setup; use simple helpers/builders when they improve clarity.
+- When a test passes, refactor code and tests to remove duplication and reveal intent.
+- Grow functionality by adding the next smallest behavior-focused test.
+
+## Tidy First Approach
+
+- Structural change: only reshape code (rename, extract, move) without altering
+  behavior.
+- Behavioral change: add or modify functionality.
+- Do not mix structural and behavioral changes in one commit.
+- When both are needed, tidy first, then implement behavior; run tests before and after.
+
+## Commit Discipline
+
+- Commit only when all tests pass and linters are clean.
+- Each commit should be a single logical unit; prefer small, frequent commits.
+- State in the message whether the commit is structural or behavioral.
+
+## Code Quality Standards
+
+- Remove duplication aggressively in both code and tests.
+- Make intent obvious through naming and small, focused functions.
+- Keep dependencies explicit; prefer pure functions where practical.
+- Use the simplest solution that works; avoid premature abstractions.
+- Keep side effects contained at boundaries.
+
+## Refactoring Guidelines
+
+- Refactor only in Green; keep steps reversible.
+- Apply one refactoring at a time, with known patterns when appropriate.
+- Re-run tests after each refactor and resolve errors or ambiguities.
+- Prioritize refactors that simplify design, clarify intent, or remove duplication.

package/dist/docs/guidelines/general-testing-rules.md

@@ -0,0 +1,26 @@
+---
+title: General Testing Rules
+description: Rules for writing minimal, effective tests with maximum coverage
+---
+## General Testing Rules
+
+- Write the minimal set of tests with the maximal coverage.
+  Write as few tests as possible that *also* cover the desired functionality.
+  If you see many similar tests, review to see if any can be removed or rewritten to be
+  shorter without reducing test coverage.
+
+- Do NOT write unit tests that are obviously going to pass (like creating objects and
+  validating they are set on an object).
+  These needlessly clutter the codebase.
+  For example:
+  - Do not write a test that simply instantiates a class and the object’s fields are
+    set.
+
+- Do NOT write a test that is trivial enough it is obviously tested as part of another
+  test in the same codebase.
+
+- Don’t test implementation details: Focus on behavior and outcomes, not internal
+  mechanics, so tests remain valid when you refactor.
+
+- Test edge cases and boundaries: Include tests for empty inputs, nulls, maximums,
+  minimums, and error conditions—not just happy paths.

package/dist/docs/guidelines/golden-testing-guidelines.md

@@ -0,0 +1,72 @@
+---
+title: Golden Testing Guidelines
+description: Guidelines for implementing golden/snapshot testing for complex systems
+---
+# Golden Testing Guidelines
+
+## TL;DR
+
+- Define a session schema (events) with stable vs unstable fields.
+- Capture full execution for scenarios (inputs, outputs, side effects) as YAML.
+- Normalize or remove unstable fields at serialization time.
+- Provide a mock mode for all nondeterminism and slow dependencies.
+- Add a CLI to run scenarios, update goldens, and print diffs.
+- Keep scenarios few but end-to-end; tests must run fast in CI (<100ms each).
+- Prefer many small artifacts (shard by scenario/phase) over monolithic traces.
+- Layer domain-focused assertions alongside raw diffs for critical invariants.
+- Review and commit session files with code; treat them as behavioral specs.
+
+## When to Use Golden Tests
+
+Golden session testing excels for complex systems where writing and maintaining hundreds
+of unit or integration tests is burdensome.
+Traditional unit tests struggle to capture the full behavior of systems with many
+interacting components, non-deterministic outputs, and complex state transitions.
+
+## Core Principles
+
+### 1. Model Events Formally
+
+All events should be modeled with type-safe schemas (Zod, Pydantic, TypeScript
+interfaces). Events are serialized to YAML for human readability.
+
+### 2. Classify Fields as Stable or Unstable
+
+- **Stable**: Deterministic values that must match exactly (symbols, actions,
+  quantities)
+- **Unstable**: Non-deterministic values filtered during comparison (timestamps, IDs)
+
+Filter unstable fields before writing session files by replacing with placeholders like
+`"[TIMESTAMP]"` or omitting entirely.
+
+### 3. Use Switchable Mock Modes
+
+- **Live mode**: Calls real external services for debugging and updating golden files
+- **Mocked mode**: Uses recorded/stubbed responses for fast, deterministic CI
+
+### 4. Design for Fast CI
+
+Golden tests should run in under 100ms per scenario:
+- Run in mocked mode (no network, no external services)
+- Use in-memory mocks over file-based fixtures
+- Parallelize independent scenarios
+- Cache expensive setup
+
+## Do / Don’t
+
+- Do capture full payloads and side effects that influence behavior.
+- Do normalize/remap unstable values at write time, not in comparisons.
+- Do keep scenarios few, representative, and fast.
+- Do prefer many small artifacts over monolithic traces.
+- Don’t depend on real clocks, random, network, or database in CI.
+- Don’t hide differences with overly broad placeholders.
+- Don’t fork logic for tests vs production; share code paths.
+- Don’t let artifacts grow unbounded.
+
+## Common Pitfalls
+
+- Missing unstable field classification -> flaky diffs.
+- File I/O captured without contents/checksums -> silent regressions.
+- Slow or network-bound scenarios -> skipped in practice, regressions leak.
+- LLM output not recorded or scrubbed -> non-deterministic sessions.
+- Monolithic traces that grow unbounded -> hard to review, slow to diff.

package/dist/docs/guidelines/python-cli-patterns.md

@@ -0,0 +1,84 @@
+---
+title: Python CLI Patterns
+description: Modern patterns for Python CLI application architecture
+---
+# Python CLI Patterns
+
+## Recommended Stack
+
+- **uv** for package management, venvs, Python versions
+- **Typer** or **argparse + rich_argparse** for CLI framework
+- **Rich** for terminal output, tables, progress
+- **Ruff** for linting and formatting
+- **BasedPyright** for type checking
+- **pytest** for testing
+
+## Key Patterns
+
+### Directory Structure
+
+```
+src/myproject/
+├── __init__.py             # Package entry, VERSION export
+├── cli.py                  # Main entry point, app setup
+├── commands/               # Command implementations
+├── lib/                    # Shared utilities and base classes
+│   ├── base_command.py     # Base class for handlers
+│   ├── output_manager.py   # Unified output handling
+│   └── formatters.py       # Domain-specific formatters
+└── types/
+    └── options.py          # TypedDict for command options
+```
+
+### Agent & CI Compatibility
+
+Support automation with explicit flags:
+- `--non-interactive`: Disable prompts, fail if input required
+- `--yes` / `-y`: Assume yes to confirmations
+- `--format text|json|jsonl`: Output format
+- `--no-progress`: Disable spinners (critical for AI agents)
+
+Respect environment variables:
+- `CI`: Set by GitHub Actions, GitLab CI, etc.
+- `NO_COLOR`: Disable colors (https://no-color.org/)
+
+### Dual Output Mode (Text + JSON)
+
+Use OutputManager for format switching:
+- Data (results) -> stdout, always
+- Success messages -> stdout, text mode only
+- Errors/warnings -> stderr, always
+- Spinners/progress -> stderr, TTY only
+
+### Base Command Pattern
+
+Centralize common functionality:
+- Context extraction from Typer context
+- Output management initialization
+- Error handling with consistent formatting
+- Dry-run checking
+
+### Error Handling
+
+Define custom exceptions with exit codes:
+- `CLIError`: Base exception (exit code 1)
+- `ValidationError`: Input validation failed (exit code 2)
+- `UserCancelled`: User cancelled (exit code 0)
+
+Exit codes: 0 success, 1 error, 2 validation, 130 interrupted (SIGINT)
+
+### Version Handling
+
+Use `uv-dynamic-versioning` for git-based versions:
+- Version derived from git tags
+- No manual version bumping required
+- Use `importlib.metadata.version()` for runtime lookup
+
+## Best Practices
+
+1. Disable spinners/progress in non-TTY contexts
+2. Route output correctly: data to stdout, errors to stderr
+3. Support `--dry-run` for safe testing of destructive commands
+4. Separate handlers from command definitions for testability
+5. Use TypedDict or dataclasses for type-safe options
+6. Test with Typer’s CliRunner for isolated, fast tests

package/dist/docs/guidelines/python-rules.md

@@ -0,0 +1,60 @@
+---
+title: Python Rules
+description: Python coding rules and best practices
+---
+# Python Rules
+
+## Type Hints
+
+- **Function signatures**: Always add type hints to function parameters and returns
+- **Complex types**: Use `typing` module for generics, unions, optionals
+- **Type aliases**: Create aliases for complex types
+- **Runtime checking**: Use `isinstance()` for runtime type validation
+
+## Docstrings
+
+- **All public functions**: Document with Google or NumPy style docstrings
+- **Include types in docstrings**: When not using type hints
+- **Document exceptions**: List exceptions that may be raised
+- **Examples**: Include usage examples for complex functions
+
+## Exception Handling
+
+- **Specific exceptions**: Catch specific exceptions, not bare `except:`
+- **Context in errors**: Include helpful context in error messages
+- **Re-raise properly**: Use `raise ... from e` to preserve stack trace
+- **Custom exceptions**: Create domain-specific exception classes
+
+## Resource Management
+
+- **Context managers**: Use `with` statements for files, connections, locks
+- **Cleanup**: Ensure resources are released in finally blocks
+- **Generator cleanup**: Use try/finally in generators that manage resources
+
+## Functions
+
+- **No mutable defaults**: Never use `[]` or `{}` as default arguments
+- **Single responsibility**: Keep functions focused on one task
+- **Return early**: Exit early for error cases to reduce nesting
+- **Keyword arguments**: Use for functions with many parameters
+
+## Imports
+
+- **Organization**: stdlib, third-party, local (separated by blank lines)
+- **Absolute imports**: Prefer absolute over relative imports
+- **No star imports**: Never use `from module import *`
+- **Import what you use**: Don’t import entire modules if using one function
+
+## Code Style
+
+- **PEP 8**: Follow PEP 8 naming conventions
+- **List comprehensions**: Use when clearer than loops
+- **F-strings**: Prefer f-strings for string formatting
+- **Pathlib**: Use `pathlib.Path` over `os.path`
+
+## Security
+
+- **No eval/exec**: Never use with untrusted input
+- **Parameterized queries**: Use placeholders for SQL/commands
+- **Input validation**: Validate and sanitize all external input
+- **Secrets management**: Use environment variables or secret managers