ritebook 0.1.0__tar.gz

ritebook-0.1.0/.agents/skills/add-hexagonal-feature/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: add-hexagonal-feature
+description: Implement a new vertical feature slice or use case in a Python hexagonal project, including domain modeling, ports, application service, adapters when needed, and tests.
+metadata:
+  version: "1.0.0"
+---
+
+# Add a Hexagonal Vertical Feature Slice
+
+Use this skill to implement a new feature, use case, or business capability as a
+vertical slice in a Python hexagonal project.
+
+This skill focuses on a complete slice through domain, application, ports,
+adapters when needed, and tests. When the change requires detailed port or
+adapter work, use the specialized skill for that procedure instead of duplicating
+it here.
+
+## Prerequisites
+
+- The project already has the standard hexagonal vertical-slice `src/` layout.
+- The feature is clear enough that you understand its inputs, outputs, and core
+  business rules.
+- The relevant inbound port already exists, or creating it is part of the same
+  change through `python-add-port`.
+
+## Steps
+
+### 1. Name the slice and use case
+
+Choose a clear verb-noun name for the use case, for example `PlaceOrder`,
+`RegisterUser`, or `SendNotification`. Use that name consistently for the
+related files and classes.
+
+Choose a `snake_case` slice name for the business capability, for example
+`orders`, `user_registration`, or `notifications`. Use this as the package under
+`src/<app_name>/features/<feature_name>/`.
+
+### 2. Model the domain if needed
+
+Create or update files under
+`src/<app_name>/features/<feature_name>/domain/`:
+
+- **Entity** — an object with identity that changes over time.
+- **Value object** — an immutable descriptor (e.g. `EmailAddress`, `Money`).
+- **Domain event** — something that happened (e.g. `OrderPlaced`).
+
+Rules:
+
+- Domain objects must be pure Python with no framework imports or I/O.
+- Use `@dataclass(frozen=True)` for value objects.
+- Raise domain-specific exceptions, not HTTP or database errors.
+
+```python
+# src/<app_name>/features/<feature_name>/domain/<entity>.py
+from dataclasses import dataclass
+
+@dataclass
+class <Entity>:
+    id: str
+```
+
+### 3. Define or confirm the required ports
+
+Identify the application boundaries the feature needs:
+
+- an inbound port when an external caller invokes a new use case
+- one or more outbound ports when the application needs infrastructure
+  dependencies such as repositories, publishers, or gateways
+
+If a required port does not exist yet, use `python-add-port` for the detailed
+procedure. In this skill, keep the focus on deciding which boundaries the
+feature needs. Inbound adapters should depend on inbound port contracts;
+application services should satisfy those contracts and depend on outbound port
+contracts for infrastructure.
+
+If the use case needs command, query, or result objects, create or update them
+under `src/<app_name>/features/<feature_name>/application/dtos/`.
+
+### 4. Implement the application service
+
+Create the use case implementation under
+`src/<app_name>/features/<feature_name>/application/use_cases/`:
+
+```python
+class <UseCaseName>:
+    def __init__(self, repository: <EntityRepositoryPort>) -> None:
+        self._repository = repository
+
+    def execute(self, command: <Command>) -> <Result>:
+        ...
+```
+
+Rules:
+
+- The application service depends only on domain objects and port interfaces.
+- If an inbound port exists for the use case, the application service must satisfy
+  that contract.
+- Keep command, query, and result DTOs under the owning slice's
+  `application/dtos/` and use them at the application boundary when dedicated
+  boundary types help clarify the use case.
+- It must not import from `adapters/`.
+- It must not perform I/O directly, including `open()`, HTTP calls, or database
+  access.
+- If the feature needs a new adapter implementation for an existing or new
+  port, use `python-add-adapter` for that procedure.
+
+### 5. Write unit tests
+
+Create application-service tests under
+`tests/unit/features/<feature_name>/application/`. If the change adds or changes
+domain invariants, add or update domain tests under
+`tests/unit/features/<feature_name>/domain/` as well.
+
+```python
+class FakeRepository:
+    def __init__(self) -> None:
+        self.saved: list[object] = []
+
+    def save(self, entity: object) -> None:
+        self.saved.append(entity)
+
+def test_<use_case_name>_happy_path() -> None:
+    repo = FakeRepository()
+    use_case = <UseCaseName>(repository=repo)
+    use_case.execute(<Command>(...))
+    assert len(repo.saved) == 1
+```
+
+TDD is encouraged when it fits the change. Writing tests before the
+implementation is fine and often preferable.
+
+- Prefer a hand-written fake for outbound ports. Use `MagicMock` only when a
+  narrow interaction assertion is clearer than asserting on fake state.
+- Cover the happy path and at least one failure or edge case.
+
+## Dependency direction reminder
+
+Follow the target project's architecture guardrails when they are available. This
+diagram is a quick dependency-direction reference only.
+
+```
+adapters/inbound   →  application  →  domain
+adapters/outbound  →  (implements application/ports)
+```
+
+Never let an arrow point in the opposite direction.
+
+Keep this diagram inside the owning feature slice. Cross-slice calls must go
+through explicit inbound ports, published application APIs, or events rather than
+private modules.

ritebook-0.1.0/.agents/skills/add-observability/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: add-observability
+description: Add logs, metrics, traces, profiling, or operational notes for meaningful workflows without unsupported performance claims.
+metadata:
+  version: "1.1.2"
+  dependencies:
+    tools: []
+    skills:
+      - debugging-and-error-recovery
+      - performance-optimization
+      - shipping-and-launch
+      - update-project-docs
+---
+
+# Add Observability
+
+Use this skill when a workflow needs better runtime visibility, measurable
+performance evidence, or operator-facing troubleshooting support.
+
+## When to use this skill
+
+Use this skill when you need to:
+
+- profile an important path before or after a change
+- add metrics or tracing around meaningful workflow boundaries
+- improve logging context for operator-visible paths
+- document dashboards, alerts, failures, or troubleshooting notes
+- support investigation of latency, throughput, reliability, or resource usage
+
+Do not use this skill to justify toy benchmarks, noisy logs, speculative
+performance claims, or instrumentation that exposes sensitive data.
+
+Use `performance-optimization` when the goal is to diagnose and fix a known or
+suspected bottleneck. Use this skill when the goal is to add or improve the
+signals that make runtime behavior observable. Use
+`debugging-and-error-recovery` when an active failure needs reproduction,
+localization, and root-cause repair. Use `shipping-and-launch` when observability
+is part of a release checklist, rollout, or rollback plan.
+
+## Steps
+
+### 1. Define the workflow and signal
+
+Identify the specific path, such as:
+
+- a user-facing request or command
+- an external service call chain
+- persistence, parsing, rendering, or processing work
+- a high-volume or latency-sensitive workflow
+- a background job, queue, or scheduled task
+
+State what you want to observe, for example latency, throughput, failure rate,
+retry behavior, queue depth, memory growth, saturation, or error categories.
+
+### 2. Measure before making claims
+
+Before claiming an optimization or reliability improvement, capture a baseline
+using representative inputs and environment notes.
+
+Record:
+
+- workload or dataset shape
+- relevant environment assumptions
+- before numbers
+- what changed
+- after numbers when applicable
+- limitations of the measurement
+
+If the outcome is better visibility rather than better performance, say that
+plainly.
+
+### 3. Instrument meaningful boundaries
+
+Prefer instrumentation at boundaries where an operator or maintainer can act on
+the signal, such as:
+
+- workflow start and completion
+- external I/O calls
+- long-running processing steps
+- retry loops and failure boundaries
+- queue enqueue, dequeue, and completion points
+
+Avoid scattering instrumentation across low-value internal helpers.
+
+### 4. Add safe logs, metrics, or traces
+
+Inspect existing observability conventions before adding new instrumentation.
+Prefer established loggers, metric clients, tracing APIs, naming patterns, and
+documentation locations. Do not introduce a new observability dependency or
+vendor-specific tool unless the project already uses it or the user explicitly
+asks for it.
+
+Choose signals that fit the project conventions.
+
+- Add logs for state transitions, decisions, and operator-visible failures.
+- Add metrics for duration, volume, success, failure, and saturation where
+  supported.
+- Add traces or spans around external I/O and cross-service boundaries where
+  supported.
+- Propagate request, correlation, job, or tenant identifiers when available and
+  safe.
+
+Do not log or emit secrets, credentials, personal data, or highly variable labels
+that would create high cardinality.
+
+### 5. Keep operational semantics clear
+
+Use stable names and fields. Document what a signal means, when it increments or
+records, and what action a maintainer should take when it changes.
+
+When alerting or dashboards are affected, document thresholds, ownership, and
+known limitations if those details are available.
+
+### 6. Update documentation when needed
+
+When the change matters operationally, update project-facing docs with:
+
+- troubleshooting notes
+- dashboard or alert references
+- new failure modes
+- rollout, migration, or on-call implications
+- measurement caveats
+
+Use `update-project-docs` for durable documentation updates.
+
+### 7. Validate the signal
+
+Exercise the instrumented workflow when practical and confirm the expected logs,
+metrics, traces, or profile outputs are emitted. Check that labels and fields are
+stable, low-cardinality, and free of sensitive data.
+
+## Output checklist
+
+- workflow and observed signal are explicit
+- baseline and environment are captured when claims depend on numbers
+- instrumentation is placed at meaningful boundaries
+- logs, metrics, and traces use safe low-cardinality context
+- operational documentation is updated when needed
+- emitted signals were validated when practical

ritebook-0.1.0/.agents/skills/api-and-interface-design/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: api-and-interface-design
+description: Design stable APIs, module contracts, schemas, component boundaries, command interfaces, or other public integration surfaces that are predictable, documented, and hard to misuse.
+metadata:
+  version: "1.1.3"
+  dependencies:
+    tools: []
+    skills: []
+---
+
+# API and Interface Design
+
+Use this skill when designing or changing a surface that another caller,
+component, service, team, user, or automated process depends on. The goal is to
+make the interface explicit, stable, observable enough to verify, and difficult
+to misuse.
+
+This applies to HTTP APIs, message contracts, library interfaces, module
+boundaries, plugin hooks, command-line interfaces, component inputs, schemas,
+configuration surfaces, and any other boundary where one part of a system talks
+to another.
+
+## When to use this skill
+
+Use this skill when you need to:
+
+- design a new public or cross-boundary interface
+- change an existing interface without surprising consumers
+- define input, output, error, or event contracts
+- choose compatibility, versioning, pagination, or naming conventions
+- review whether an interface is predictable and hard to misuse
+
+Do not use this skill to standardize internal helper shapes that have no durable
+consumer or observable boundary.
+
+## Principles
+
+### Hyrum's Law
+
+With a sufficient number of users of an API, all observable behaviors of your
+system will be depended on by somebody, regardless of what you promise in the
+contract.
+
+Treat observable behavior as a commitment. This includes response shape, error
+codes, message text, ordering, timing, default values, side effects, and
+undocumented quirks.
+
+Design implications:
+
+- expose only behavior you are willing to support
+- avoid leaking implementation details through names, errors, timing, or data
+  shape
+- plan deprecation before consumers depend on the old behavior
+- remember that tests cannot prove a change is safe for undocumented consumer
+  dependencies
+
+### One-version rule
+
+Avoid forcing consumers to choose between multiple active versions of the same
+interface or dependency. Multiple versions increase maintenance cost and create
+compatibility problems when different consumers need different versions at the
+same time.
+
+Prefer extending one stable interface over forking it. If multiple versions are
+unavoidable, document the support window, migration path, and removal criteria.
+
+## Steps
+
+### 1. Identify the boundary and consumers
+
+State what boundary is being designed and who or what consumes it.
+
+Capture:
+
+- consumer types, such as users, services, modules, plugins, clients, scripts, or
+  operators
+- whether the interface is public, internal but cross-team, or private to one
+  implementation
+- expected stability and compatibility requirements
+- inputs, outputs, side effects, errors, and ordering guarantees
+- operational constraints such as latency, rate limits, retries, or idempotency
+
+The more durable or widely consumed the interface is, the more explicit the
+contract should be.
+
+### 2. Define the contract before implementation
+
+Describe the interface before building the implementation. Use the contract
+format that fits the project, such as an OpenAPI document, schema file,
+protocol definition, type definition, command help text, ADR, README section, or
+test fixture.
+
+At minimum, define:
+
+- operation names and responsibilities
+- required and optional inputs
+- output shape and generated fields
+- default values and side effects
+- error shape and retry semantics
+- compatibility expectations
+- examples for common and edge cases
+
+For example, a neutral resource contract might state:
+
+```md
+Operation: create item
+Input: required name, optional description
+Output: item identifier, name, description, creation timestamp
+Errors: validation failed, duplicate name, unauthorized
+Compatibility: future optional fields may be added to output
+```
+
+### 3. Choose consistent error semantics
+
+Pick one error strategy for the boundary and apply it consistently.
+
+Define:
+
+- how callers detect success or failure
+- whether errors are returned, raised, emitted, logged, or encoded as status
+  values
+- machine-readable error identifiers
+- human-readable messages
+- which details are safe to expose
+- whether an operation can be retried
+
+For request-response APIs, this might be a status code plus a structured error
+body. For libraries, it might be typed exceptions or result values. For command
+interfaces, it might be exit codes plus structured output.
+
+Do not mix patterns at the same boundary without a documented reason. If some
+operations return empty values, some raise errors, and others return structured
+errors, consumers cannot reliably predict behavior.
+
+### 4. Validate at trust boundaries
+
+Validate external or less-trusted data where it enters the system. After
+validation, keep internal code focused on domain behavior instead of repeatedly
+revalidating the same already-trusted data.
+
+Validate data from:
+
+- user input
+- network requests
+- files and configuration
+- environment variables
+- message queues or events
+- third-party service responses
+- generated or model-produced content
+
+Treat third-party responses as untrusted. Validate their shape and content before
+using them in logic, rendering, persistence, or security decisions.
+
+Avoid scattering duplicate validation between internal functions that share the
+same trusted contract.
+
+### 5. Prefer additive compatible changes
+
+Extend interfaces without breaking existing consumers.
+
+Usually compatible:
+
+- adding optional input fields
+- adding output fields consumers can ignore
+- adding new operations without changing existing ones
+- adding new enum or status values only when consumers are expected to handle
+  unknown values
+- relaxing overly strict validation when it does not create ambiguity
+
+Usually breaking:
+
+- removing fields, operations, status values, or error codes
+- changing field meaning, type, units, default values, or ordering
+- making optional fields required
+- narrowing accepted input values
+- changing idempotency, side effects, or authorization semantics
+
+When a breaking change is unavoidable, use a deprecation and migration workflow
+to plan communication, migration, compatibility support, and removal timing. If
+the `deprecation-and-migration` skill is available, use it for that follow-up
+planning.
+
+### 6. Make naming predictable
+
+Use names that match the existing interface style and domain language. Prefer
+one convention per boundary over mixing styles.
+
+Check names for:
+
+- resource or concept names that reflect the domain rather than implementation
+  details
+- operation names that describe intent without duplicating transport mechanics
+- field names that use consistent casing, tense, and units
+- boolean names that read clearly as true or false
+- status values that are stable, documented, and safe for unknown-value handling
+- identifiers that are hard to confuse across entity types
+
+Do not import a naming convention from another language, framework, or transport
+unless it is already the project convention or required by consumers.
+
+### 7. Design collections and partial updates explicitly
+
+For list or search operations, define:
+
+- pagination or streaming behavior
+- filtering and sorting options
+- default limits and maximum limits
+- result ordering stability
+- empty result behavior
+- consistency expectations when data changes during iteration
+
+For partial updates, define:
+
+- how omitted fields differ from explicit empty or null values
+- whether updates are idempotent
+- how conflicts are detected
+- whether generated fields can be changed by consumers
+
+### 8. Separate caller input from system output
+
+Do not require callers to provide fields that the system owns, such as generated
+identifiers, creation timestamps, computed values, or audit fields.
+
+Keep separate shapes for:
+
+- creation input
+- update input
+- persisted or returned output
+- internal representation when it differs from the public contract
+
+This separation keeps callers from depending on implementation details and makes
+future changes easier.
+
+### 9. Verify the interface from the consumer perspective
+
+Validate the design and implementation with consumer-facing checks.
+
+Useful verification includes:
+
+- contract tests or schema validation
+- examples that can be executed or copied safely
+- compatibility tests for old and new consumers
+- negative tests for validation and error behavior
+- documentation review against actual behavior
+- migration tests when changing an existing interface
+
+Verification should prove the contract is understandable and stable from the
+consumer's point of view, not only that the provider implementation works.
+
+## Red flags
+
+- observable behavior is undocumented but likely to be consumed
+- operations at the same boundary use inconsistent error shapes
+- input validation is missing at external boundaries
+- third-party responses are trusted without validation or sanitization
+- fields expose storage, framework, or implementation details unnecessarily
+- collection operations have no pagination, streaming, or limit strategy
+- partial updates do not define omitted, empty, and null value behavior
+- compatibility impact is unclear for changed fields or status values
+- examples require a specific framework even though the skill is meant to be
+  reusable
+
+## Output checklist
+
+- boundary and consumers are explicit
+- contract is documented before or alongside implementation
+- input, output, error, and side-effect semantics are consistent
+- validation happens at trust boundaries
+- changes are additive or have a migration plan
+- naming follows the local interface convention
+- collection and partial-update behavior is defined when relevant
+- consumer-facing tests, examples, or documentation verify the contract