contextcompass 2.15.0__py3-none-any.whl

contextcompass_cli/_package/agent_onboarding/default/design_engineer/skills/architecture_contexts.md

@@ -0,0 +1,40 @@
+
+
+# architecture_contexts
+
+Purpose
+- Maintain C4/C3/C2/C1 architecture and component context for this repo.
+
+Artifacts
+- `system_docs/src_architecture.md`
+- `system_docs/tests_architecture.md`
+- `system_docs/src_components.md`
+- `system_docs/tests_components.md`
+- `agent_onboarding/default/engineer/skills/src_graph_usage.md`
+- `system_docs/src_graph.md`
+- `system_docs/src_graph_index.md`
+- `system_docs/patches/active/<patch_id>/architecture_patch.md` (when patch lane is active)
+- `system_docs/patches/active/<patch_id>/component_patch_<component>.md` (when patch lane is active)
+- `system_docs/patches/active/<patch_id>/code_description_patch_<component>.md` (conditional)
+
+Strict source rule
+- Architecture and component docs must reflect the actual codebase and ticket context.
+- If docs are stale, update them before relying on them for design decisions.
+
+Update cadence
+- Update docs when boundaries, lifecycle, invariants, or wiring change.
+- Keep `src_graph.md` synchronized with canonical graph state when
+  architecture/components work changes source wiring coverage.
+- Keep ASCII and Mermaid diagrams current.
+- Keep active patch docs synchronized with canonical docs until merge+cleanup closes the patch lane.
+
+References
+- `agent_onboarding/default/design_engineer/skills/src_architecture_instructions.md`
+- `agent_onboarding/default/design_engineer/skills/src_components_instructions.md`
+- `agent_onboarding/default/design_engineer/skills/tests_architecture_instructions.md`
+- `agent_onboarding/default/design_engineer/skills/tests_components_instructions.md`
+- `agent_onboarding/default/design_engineer/skills/patch_framework_design.md`
+- `agent_onboarding/default/design_engineer/skills/architecture_patch_contracts.md`
+- `agent_onboarding/default/design_engineer/skills/component_patch_contracts.md`
+- `agent_onboarding/default/design_engineer/skills/code_description_patch_contracts.md`
+

contextcompass_cli/_package/agent_onboarding/default/design_engineer/skills/architecture_patch_contracts.md

@@ -0,0 +1,43 @@
+# architecture_patch_contracts
+
+Purpose
+- Define the authoring contract for
+  `system_docs/patches/active/<patch_id>/architecture_patch.md`.
+- Ensure architecture-level deltas are explicit before implementation is routed.
+
+When required
+- Any patch that changes architecture boundaries, cross-component interactions,
+  policy gates, lifecycle sequencing, or canonical `src_architecture` behavior.
+
+Required sections (minimum)
+1) Patch scope and non-goals
+2) Changed-components matrix
+3) Interface and boundary deltas
+4) Cross-component invariants
+5) Migration/rollout order
+6) Rollback strategy
+7) Validation expectations and evidence plan
+8) Ticket coverage map (epic/story/task linkage)
+9) Unknowns and decision requests
+
+Authoring rules
+- Keep this document domain-agnostic and reusable.
+- Write constraints as enforceable statements, not preferences.
+- Use explicit ordering for migrations and rollback.
+- If a claim cannot be evidenced, mark `UNKNOWN` and route investigation.
+
+Quality gate
+- Patch id is explicit and stable.
+- Every changed boundary has an explicit delta statement.
+- Every new or changed invariant is testable.
+- Migration and rollback are internally consistent.
+- Ticket linkage is complete and current.
+
+Handoff requirements
+- Link architecture patch in the active ticket artifact section.
+- Do not route implementation ready-state until this contract is complete.
+
+References
+- `agent_onboarding/default/design_engineer/skills/patch_framework_design.md`
+- `agent_onboarding/default/design_engineer/skills/src_architecture_instructions.md`
+- `agent_onboarding/default/general/skills/workflow.md`

contextcompass_cli/_package/agent_onboarding/default/design_engineer/skills/architecture_tradeoffs.md

@@ -0,0 +1,33 @@
+
+# architecture_tradeoffs
+
+Purpose
+- Make tradeoffs explicit, comparable, and reviewable.
+- Prevent "default architecture" choices from being made without rationale.
+
+Minimum tradeoff set
+For any non-trivial design, capture:
+- Option A (baseline / simplest approach)
+- Option B (preferred approach)
+- Option C (if relevant: higher complexity / higher leverage)
+
+Tradeoff dimensions (use as a table)
+- Value delivered
+- Complexity
+- Time to implement
+- Operational risk
+- Performance/scalability
+- Reliability/resilience
+- Security/privacy risk
+- Testability
+- Maintainability
+
+Rules
+- If you cannot justify the chosen option on at least 2-3 dimensions, stop and gather more evidence.
+- If a tradeoff is a risk acceptance, label it as such and request approval.
+
+References
+- `agent_onboarding/default/design_engineer/policies/decision_record_policy.md`
+- `agent_onboarding/default/design_engineer/skills/adr_and_decision_hygiene.md`
+
+

contextcompass_cli/_package/agent_onboarding/default/design_engineer/skills/code_description_patch_contracts.md

@@ -0,0 +1,46 @@
+# code_description_patch_contracts
+
+Purpose
+- Define the conditional authoring contract for
+  `system_docs/patches/active/<patch_id>/code_description_patch_<component>.md`.
+- Capture implementation-relevant control-flow intent when component patches
+  are not sufficient by themselves.
+
+When required
+- Complex control-flow or state-machine changes.
+- New or changed policy gate pipelines.
+- Multi-branch error/rollback semantics.
+- Concurrency, ordering, or idempotency-sensitive behavior.
+
+When not required
+- Simple interface or data-shape changes already fully covered by
+  `component_patch_<component>.md`.
+- Low-risk behavior changes with no non-trivial control-flow deltas.
+
+Required section contract
+1) Trigger justification (why this file is required)
+2) Control-flow description (pseudocode level, not production code)
+3) Edge/error behavior and rollback semantics
+4) Invariants and idempotency expectations
+5) Explicit non-goals
+6) Validation focus points
+
+Authoring rules
+- Keep this file implementation-guiding, not implementation-copying.
+- Avoid line-level code prescriptions unless required by invariant safety.
+- Keep language deterministic so engineer mapping can be unambiguous.
+
+Quality gate
+- Trigger reason is explicit and evidence-backed.
+- Control-flow and error semantics are concrete and testable.
+- Non-goals prevent unintended scope expansion.
+- Validation focus points map to ticketed verification steps.
+
+Handoff requirements
+- Link this artifact when trigger criteria are met.
+- Engineer lane is blocked if required code-description patches are missing.
+
+References
+- `agent_onboarding/default/design_engineer/skills/patch_framework_design.md`
+- `agent_onboarding/default/design_engineer/skills/component_patch_contracts.md`
+- `agent_onboarding/default/engineer/skills/patch_framework_gating.md`

contextcompass_cli/_package/agent_onboarding/default/design_engineer/skills/component_patch_contracts.md

@@ -0,0 +1,41 @@
+# component_patch_contracts
+
+Purpose
+- Define the authoring contract for
+  `system_docs/patches/active/<patch_id>/component_patch_<component>.md`.
+- Ensure each changed component has a concrete delta contract before code work.
+
+When required
+- One component patch is required for every changed component in the patch
+  scope.
+
+Required section contract (per component)
+1) Component purpose and boundary in current architecture
+2) Before/after behavior summary
+3) Interface deltas (inputs, outputs, error semantics)
+4) State and lifecycle deltas
+5) Failure mode deltas
+6) Dependency and ordering constraints
+7) Validation expectations
+8) Unknowns and open decisions
+
+Authoring rules
+- Keep one component per file; do not merge multiple components.
+- Keep behavior deltas concrete and externally observable.
+- Include ownership and cleanup implications when lifecycle changes.
+- Use explicit language for constraints (`MUST`, `MUST NOT`, `REQUIRED`).
+
+Quality gate
+- Component name matches architecture patch matrix.
+- Interface/state/failure deltas are all present.
+- Dependency order is explicit for implementation sequencing.
+- Validation expectations map to test/verification actions.
+
+Handoff requirements
+- Link every component patch from the active ticket.
+- Do not route implementation until all changed components have patch files.
+
+References
+- `agent_onboarding/default/design_engineer/skills/patch_framework_design.md`
+- `agent_onboarding/default/design_engineer/skills/src_components_instructions.md`
+- `agent_onboarding/default/general/skills/workflow.md`

contextcompass_cli/_package/agent_onboarding/default/design_engineer/skills/data_modeling.md

@@ -0,0 +1,34 @@
+
+# data_modeling
+
+Purpose
+- Provide a disciplined approach to data modeling, schemas, and migrations.
+- Ensure designs are correct under concurrency, growth, and change.
+
+Modeling checklist
+- Entities and relationships
+- Ownership boundaries (which component owns which data)
+- Consistency model:
+  - strong consistency vs eventual consistency,
+  - transaction boundaries,
+  - conflict resolution.
+- Query patterns:
+  - expected reads/writes,
+  - indexing strategy,
+  - cardinality and growth expectations.
+- Migration plan:
+  - backward compatible steps,
+  - data backfill strategy,
+  - rollback/backout plan.
+
+Design questions
+- What is the source of truth for each field?
+- What invariants must hold?
+- What are the failure modes during migration?
+- How will you validate data correctness post-migration?
+
+References
+- `agent_onboarding/default/design_engineer/skills/nonfunctional_requirements.md`
+- `agent_onboarding/default/qa_engineer/skills/test_data_and_environments.md`
+
+

contextcompass_cli/_package/agent_onboarding/default/design_engineer/skills/decomposition_and_boundaries.md

@@ -0,0 +1,42 @@
+
+# decomposition_and_boundaries
+
+Purpose
+- Teach a consistent way to decompose systems into components with clean boundaries.
+- Reduce coupling and increase change safety.
+
+Boundary rules (practical)
+- Prefer stable seams:
+  - public interfaces, adapters, service boundaries, domain modules.
+- Keep dependencies directional:
+  - dependencies flow from higher-level policy to lower-level mechanisms (not the reverse).
+- Avoid "shared mutable state" across boundaries unless explicitly designed.
+- Use contracts:
+  - data contracts (schemas),
+  - behavior contracts (docstrings, invariants),
+  - interface contracts (API versioning, error semantics).
+
+Decomposition workflow
+1) Identify the smallest set of responsibilities required.
+2) Group responsibilities that must change together.
+3) Split responsibilities that change for different reasons.
+4) Define boundaries and interfaces.
+5) Identify cross-cutting concerns:
+   - logging, auth, retries, caching, migrations.
+6) Define dependency rules:
+   - what is allowed to import/call what.
+7) Validate with scenarios:
+   - "What changes when requirement X changes?"
+
+Output checklist
+- Components list with responsibilities
+- Dependency graph (even a bullet list)
+- Interfaces between components
+- Failure-handling strategy per boundary
+- Test boundaries (unit vs integration)
+
+References
+- `agent_onboarding/default/design_engineer/skills/architecture_contexts.md`
+- `agent_onboarding/default/design_engineer/skills/api_and_interface_design.md`
+
+

contextcompass_cli/_package/agent_onboarding/default/design_engineer/skills/design_engineer_execution.md

@@ -0,0 +1,65 @@
+
+# design_engineer_execution
+
+Purpose
+- Define how `design_engineer` agents produce decision-quality software designs.
+- Convert ambiguous goals into implementable plans with explicit tradeoffs and handoff artifacts.
+
+Core rules
+- Follow `AGENTS.MD` and the shared baseline skills in `agent_onboarding/default/general/`.
+- This role inherits `engineer` implementation discipline; do not invent new execution contracts.
+- Enforce `patch_framework_design.md` for system-impacting design changes before
+  handing off implementation.
+- Author patch contracts using:
+  - `architecture_patch_contracts.md`,
+  - `component_patch_contracts.md`,
+  - `code_description_patch_contracts.md` (when triggered).
+- Design work is only "done" when it is actionable:
+  - clear scope, clear interfaces, clear risks, clear next tickets.
+
+Design output contract (minimum)
+Every meaningful design response must include:
+1) Problem statement (goal) + non-goals
+2) Constraints (time, compatibility, operational, user requirements)
+3) Assumptions + UNKNOWNs (with verification plan)
+4) Option set (at least 2 when feasible)
+5) Tradeoff comparison (why the chosen option wins)
+6) Proposed architecture (components/boundaries)
+7) Interfaces (API/schema/event contracts + error semantics)
+8) Failure modes + mitigations
+9) Test/validation strategy
+10) Rollout/observability plan
+11) Ticketization: how to break work into epics/stories/tasks
+12) Patch artifacts (for system-impacting changes):
+    - architecture patch,
+    - component patches,
+    - conditional code-description patches.
+
+Preferred workflow
+1) Clarify goal and constraints (ask questions before proposing architecture).
+2) Identify current state sources:
+   - existing tickets,
+   - `system_docs/*`,
+   - code symbols if docs are missing/stale.
+3) Produce a first-pass design with explicit UNKNOWNs and tradeoffs.
+4) Propose checkpoints:
+   - "Design review checkpoint" before any implementation.
+5) Build required patch artifacts when design is system-impacting.
+6) Convert design into tickets and next actions.
+7) Hand off cleanly to `engineer` execution only after design patch gate passes.
+
+Artifact discipline (design)
+- Durable design belongs in tickets and artifacts:
+  - ticket `## Notes` for concise design summary and evidence,
+  - `artifacts/` for longer design docs (linked from ticket + `artifact_board.md`).
+- Do not leave durable design in chat-only form when it influences implementation decisions.
+
+References
+- `agent_onboarding/default/design_engineer/policies/design_quality_policy.md`
+- `agent_onboarding/default/design_engineer/policies/decision_record_policy.md`
+- `agent_onboarding/default/general/skills/workflow.md`
+- `agent_onboarding/default/engineer/skills/engineer_execution.md`
+- `agent_onboarding/default/design_engineer/skills/patch_framework_design.md`
+- `agent_onboarding/default/design_engineer/skills/architecture_patch_contracts.md`
+- `agent_onboarding/default/design_engineer/skills/component_patch_contracts.md`
+- `agent_onboarding/default/design_engineer/skills/code_description_patch_contracts.md`

contextcompass_cli/_package/agent_onboarding/default/design_engineer/skills/design_review_protocol.md

@@ -0,0 +1,34 @@
+
+# design_review_protocol
+
+Purpose
+- Define how designs are reviewed, validated, and approved before implementation.
+- Ensure the handoff is deterministic and non-performative.
+
+Review checkpoints (recommended)
+1) Problem framing checkpoint
+   - verify goal/non-goals, constraints, and acceptance criteria.
+2) Architecture checkpoint
+   - verify boundaries, interfaces, data model, and tradeoffs.
+3) Operational checkpoint
+   - verify rollout, observability, failure handling, and test strategy.
+4) Implementation readiness checkpoint
+   - verify tickets are actionable and scoped.
+
+Review artifacts
+- For any checkpoint, provide:
+  - a concise summary,
+  - explicit open questions,
+  - explicit decision points requiring approval.
+
+Rules
+- Do not start implementation unless a checkpoint is explicitly approved when:
+  - design changes public contracts, schemas, or major boundaries,
+  - the user requested "design only" first,
+  - risk is high or rollback is complex.
+
+References
+- `agent_onboarding/default/design_engineer/policies/design_review_policy.md`
+- `agent_onboarding/default/general/skills/ticketing_skill_contract.md`
+
+

contextcompass_cli/_package/agent_onboarding/default/design_engineer/skills/nonfunctional_requirements.md

@@ -0,0 +1,34 @@
+
+# nonfunctional_requirements
+
+Purpose
+- Ensure designs address non-functional requirements (NFRs) explicitly.
+- Prevent late surprises in performance, reliability, security, and operability.
+
+NFR categories (minimum coverage)
+1) Performance
+   - latency budgets, throughput expectations, hotspots, caching.
+2) Scalability
+   - growth assumptions, horizontal scaling limits, state management.
+3) Reliability
+   - failure modes, retries, idempotency, recovery, backpressure.
+4) Operability
+   - logging/metrics/tracing, alerting, runbooks, debugging hooks.
+5) Security & Privacy
+   - threat model, secrets handling, least privilege, data exposure.
+6) Cost
+   - compute/storage/network cost drivers, guardrails.
+
+Rules
+- If an NFR is unknown, declare it UNKNOWN and propose a verification step.
+- If the user cares about an NFR, translate it into measurable acceptance criteria.
+- If security posture is required, route to security specialist guidance:
+  - `agent_onboarding/default/general/skills/security_and_secrets.md`
+  - `agent_onboarding/default/security_engineer/SKILLS.MD` (if available/selected)
+
+References
+- `agent_onboarding/default/general/skills/unknowns_gate_reference.md`
+- `agent_onboarding/default/platform_engineer/skills/observability_and_monitoring.md`
+- `agent_onboarding/default/security_engineer/skills/threat_modeling.md`
+
+

contextcompass_cli/_package/agent_onboarding/default/design_engineer/skills/patch_framework_design.md

@@ -0,0 +1,79 @@
+
+# patch_framework_design
+
+Purpose
+- Define how `design_engineer` builds and maintains patch-framework contracts.
+- Make patch design artifacts mandatory and consistent before engineer
+  implementation starts.
+- Orchestrate the three contract skills:
+  - `architecture_patch_contracts.md`,
+  - `component_patch_contracts.md`,
+  - `code_description_patch_contracts.md`.
+
+Design ownership
+- Own system-level patch intent in `architecture_patch.md`.
+- Own component-level delta contracts in `component_patch_<component>.md`.
+- Decide when `code_description_patch_<component>.md` is required.
+- Own patch-to-ticket mapping and merge/cleanup design criteria.
+- Keep contract language domain-agnostic and reusable.
+
+When this gate applies
+- Any design that changes architecture/component contracts, lifecycle, or
+  cross-component behavior.
+- Any design expected to update canonical `system_docs/src_architecture.md` or
+  `system_docs/src_components.md`.
+- Any design expected to refresh `system_docs/src_graph.md` because
+  documented source wiring or ownership moved.
+
+Required design outputs (before implementation)
+1) `system_docs/patches/active/<patch_id>/architecture_patch.md`
+2) `system_docs/patches/active/<patch_id>/component_patch_<component>.md` for
+   each changed component
+3) `system_docs/patches/active/<patch_id>/code_description_patch_<component>.md`
+   when complexity triggers apply
+
+Mandatory authoring protocol
+- Build `architecture_patch.md` using
+  `architecture_patch_contracts.md`.
+- Build each `component_patch_<component>.md` using
+  `component_patch_contracts.md`.
+- Build required `code_description_patch_<component>.md` files using
+  `code_description_patch_contracts.md`.
+
+`code_description_patch` complexity triggers
+- State-machine or policy-gate flow changes.
+- Multi-branch error/rollback semantics.
+- Concurrency/idempotency-sensitive logic.
+- Non-trivial orchestration or mediator behavior.
+
+Design quality gate checklist
+- [ ] Patch id is explicit and stable.
+- [ ] Architecture patch includes invariants, interfaces, migration order, and rollback.
+- [ ] Component patches include before/after behavior and validation expectations.
+- [ ] Conditional code-description patches exist for triggered components.
+- [ ] Patch docs are linked from active ticket(s) and coverage matrix is complete.
+
+Design-to-engineer handoff rule
+- Do not route implementation as ready until design quality gate is satisfied.
+- If gate fails, keep design lane active and raise `BLOCKER` or
+  `DECISION_REQUEST` in ticket notes.
+- Engineer lane must be blocked if required patch docs are missing, unlinked, or
+  fail contract quality checks.
+
+Closure design obligations
+- Ensure implementation evidence is sufficient for canonical merge.
+- Ensure temporary patch artifacts are removed or explicitly retained by policy.
+
+Manual validation expectation
+- Confirm architecture/component/code-description patch artifacts exist as
+  required for the active patch id.
+- Confirm each required artifact is linked from active ticket(s).
+- Confirm design quality checklist is satisfied before handoff.
+
+References
+- `agent_onboarding/default/engineer/skills/patch_framework_gating.md`
+- `agent_onboarding/default/general/skills/ticketing.md`
+- `agent_onboarding/default/general/skills/workflow.md`
+- `agent_onboarding/default/design_engineer/skills/architecture_patch_contracts.md`
+- `agent_onboarding/default/design_engineer/skills/component_patch_contracts.md`
+- `agent_onboarding/default/design_engineer/skills/code_description_patch_contracts.md`

contextcompass_cli/_package/agent_onboarding/default/design_engineer/skills/requirements_to_architecture.md

@@ -0,0 +1,39 @@
+
+# requirements_to_architecture
+
+Purpose
+- Turn ambiguous requests into explicit requirements and constraints.
+- Prevent "design drift" by anchoring design choices to stated needs.
+
+Method
+1) Extract the user goal (what success looks like).
+2) Define non-goals (what is explicitly out of scope).
+3) Identify constraints:
+   - compatibility (API, schema, behavior),
+   - performance/SLA expectations,
+   - operational constraints (deployments, observability),
+   - security/privacy constraints,
+   - timeline and risk tolerance.
+4) Capture assumptions and UNKNOWNs:
+   - label UNKNOWN explicitly,
+   - define the minimal verification path (what doc/code to read).
+5) Define acceptance criteria:
+   - functional,
+   - non-functional,
+   - testability criteria.
+
+Output format (recommended)
+- Goal:
+- Non-goals:
+- Constraints:
+- Assumptions:
+- UNKNOWNs + verification plan:
+- Acceptance criteria:
+- Proposed next step (design draft / source reads / ticket creation):
+
+References
+- `agent_onboarding/default/general/skills/unknowns_gate_reference.md`
+- `agent_onboarding/default/general/skills/ticketing_skill_contract.md`
+- `agent_onboarding/default/design_engineer/skills/system_design_method.md`
+
+