3.0 dev

.agents/skills/chatnow-creating-issues/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: chatnow-creating-issues
+description: Use when any ChatNow repository change is requested, when no valid primary Issue exists, or when implementation uncovers an out-of-scope problem
+---
+
+# Creating ChatNow Issues
+
+## Core principle
+
+```
+NO IMPLEMENTATION BRANCH OR REPOSITORY CHANGE WITHOUT A VALID PRIMARY ISSUE.
+```
+
+Urgency, a one-line change, or permission to document later does not weaken this rule. Continue only read-only investigation until the Issue exists and has a number or URL.
+
+## Create the Issue first
+
+1. Verify the request against source, logs, tests, or observed behavior. Do not turn an unverified suspected fix into the requirement.
+2. Select the target version line. Stop if multiple targets remain valid after checking available Issue, milestone, and repository evidence.
+3. Define exactly one primary problem or deliverable. Split independent work into separate Issues.
+4. Write an English title and a body whose prose is Chinese. Use every heading below exactly once and in this order.
+5. Validate the Issue contract, create the Issue, and record its number or URL before creating a task branch or changing the repository.
+
+## Required body contract
+
+```markdown
+## Target Version
+
+## Evidence
+
+## Problem or Goal
+
+## Scope
+
+## Non-goals
+
+## Acceptance Criteria
+
+## Test-first Plan
+
+## Risk and Security
+
+## Architecture Impact
+
+## Core-flow Impact
+
+## Required Skill Updates
+```
+
+Fill the sections as follows:
+
+| Section | Required content |
+|---|---|
+| `Target Version` | One existing development version line and the evidence for selecting it. |
+| `Evidence` | Specific source paths, logs, failing tests, or reproducible behavior. Mark unknown facts as unknown; never invent evidence. |
+| `Problem or Goal` | Current behavior or need, affected users or systems, and the observable desired outcome without assuming an implementation. |
+| `Scope` | Files, services, behavior, and deliverables included in this Issue. |
+| `Non-goals` | Closely related work explicitly excluded. |
+| `Acceptance Criteria` | Observable, measurable checkboxes, including relevant boundaries and failure behavior. Do not encode an unverified implementation as acceptance. |
+| `Test-first Plan` | The smallest RED case, its command and expected failure reason, the minimum GREEN behavior, and relevant regression coverage. |
+| `Risk and Security` | Security, privacy, data, compatibility, migration, operational, and rollback risks, or an evidence-based `None`. |
+| `Architecture Impact` | `Yes` or `No` plus reasoning about service boundaries and infrastructure topology. |
+| `Core-flow Impact` | `Yes` or `No` plus reasoning about communication, auth, persistence, indexing, caching, sequencing, idempotency, retry, Outbox, Push, or ACK behavior. |
+| `Required Skill Updates` | Exact affected ChatNow Skill/reference paths, or `None` with reasoning. Any architecture, core-flow, or test-architecture change requires relevant Skill updates in the same PR; a follow-up Issue is not a substitute. |
+
+## Preserve the contract
+
+Update evidence as investigation improves it. Never rewrite acceptance criteria after implementation merely to fit the produced code. If a genuine requirement change is approved, record the reason and changed requirement in the Issue before continuing, then restart planning and RED against the revised contract.
+
+An unrelated defect, typo, cleanup, or cross-version port is not current scope. Create a follow-up Issue and keep it out of the current branch and PR. One PR resolves one primary Issue.
+
+## Security containment exception
+
+Immediate containment may precede the normal Issue-first order only when delaying action materially increases security harm. Create the Issue immediately, and record the exception, the harm caused by delay, containment actions, timestamps, evidence, and remaining follow-up. This exception permits only the minimum containment; it does not permit a post-hoc ordinary Issue or hidden scope.
+
+## Stop conditions
+
+Stop implementation and continue only read-only research when:
+
+- GitHub is unavailable and no valid Issue exists;
+- the target version remains ambiguous;
+- the Issue combines multiple primary problems;
+- evidence is missing or contradicts the proposed goal;
+- acceptance or the RED plan is not measurable;
+- security or data risk cannot be bounded safely.
+
+## Common rationalizations
+
+| Rationalization | Required response |
+|---|---|
+| "It is only one line." | Create and validate the Issue first. Size does not remove risk or traceability. |
+| "Open the Issue after the fix." | Stop. Post-hoc documentation cannot authorize implementation. |
+| "The deadline is too close for RED." | Define measurable acceptance and an observed RED plan before implementation. |
+| "We already know the operator change." | Record verified behavior and outcome; do not make an assumed patch the contract. |
+| "Fix this unrelated typo while here." | Create a follow-up Issue and exclude it from the current branch and PR. |
+| "Update the architecture Skill later." | Update every relevant Skill/reference in the same architecture or core-flow PR. |

.agents/skills/chatnow-creating-issues/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Create ChatNow Issues"
+  short_description: "Create scoped, testable ChatNow engineering Issues"
+  default_prompt: "Use $chatnow-creating-issues to create a valid Issue before changing ChatNow."

.agents/skills/chatnow-developing/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: chatnow-developing
+description: Use when changing ChatNow production C++, Protobuf contracts, configuration, databases, caches, message queues, service discovery, or runtime infrastructure
+---
+
+# Develop ChatNow Services
+
+## Core principle
+
+Preserve ownership, trust, failure, and repeated-execution invariants with the smallest Issue-scoped change. A successful response is valid only when every required dependency and asynchronous handoff has defined bounded behavior.
+
+## Entry gates
+
+1. Confirm a valid primary Issue defines the target version, scope, acceptance criteria, risks, architecture/core-flow impact, and required Skill updates. Stop before implementation if it does not.
+2. Use `chatnow-orienting` to verify affected owners, trust boundaries, durable sources of truth, caches, calls, queues, stores, and current invariants from executable evidence.
+3. Use `chatnow-testing` before production code. Record a pure-Go behavioral test that failed for the expected missing behavior. If production code predates the observed RED, delete it and restart test-first.
+4. Find the nearest repository pattern in the same subsystem and version line. Cite the files and preserve their contracts unless the Issue explicitly changes them.
+
+## Implementation workflow
+
+1. State the invariant being changed and the invariants that must remain true.
+2. Assign ownership for identity, durable state, cached or coordination state, transactions, asynchronous work, and cleanup. Derive authority from authenticated server context, never an untrusted client field.
+3. Specify success, synchronous failure, asynchronous failure, timeout, cancellation, retry, duplicate execution, partial completion, and recovery before editing code.
+4. Make the minimum diff required by the observed RED. Do not mix unrelated refactors, formatting, generated output, or speculative abstractions.
+5. Apply every relevant boundary rule below.
+6. Reach GREEN with the target Go test, run relevant same-layer regressions, then refactor only while green. Report actual commands and results; do not invent unavailable commands or runtime evidence.
+7. Recheck compatibility, observability, deployment/configuration, cleanup, and same-PR Skill synchronization.
+
+## Boundary rules
+
+### RPC and asynchronous callbacks
+
+- Preserve server-derived authentication and authorization context across the brpc attachment; validate required metadata at the receiver.
+- Map transport, timeout, authentication, validation, dependency, and application failures deliberately. Do not turn every exception into success.
+- Set a bounded timeout and define whether a timed-out operation is safe to retry. Make retry limits and backoff explicit.
+- Guarantee the brpc closure runs exactly once on every path. Keep response, controller, callback captures, channels, and dependent objects alive until the final callback; prevent double completion and use-after-free.
+
+### RabbitMQ
+
+- Identify the exchange type/name, routing key, queue owner, binding, durability, publisher-only or consumer role, and deployment configuration. Do not declare an orphan or conflicting topology.
+- Define publisher-confirm handling for acknowledged, rejected, lost/unknown, synchronous-error, and timeout outcomes. Return success only after the contract's success boundary.
+- Treat delivery as at-least-once. Define retry ownership, bounded retry/backoff, redelivery behavior, idempotency key/effect, duplicate result, and any Outbox or reaper recovery path.
+- Preserve trace headers and ensure consumers acknowledge only after the owned durable effect reaches its declared boundary.
+
+### Redis
+
+- Classify each key as cache, coordination/lease, idempotency state, sequence state, routing/presence state, or authoritative security state. Name the durable source of truth when Redis is not authoritative.
+- Choose fail-open, fail-closed, or explicit degraded behavior from that classification. Authorization, revocation, uniqueness, sequencing, and destructive decisions must not silently use cache-miss or exception as success.
+- Bound each lookup or lock acquisition by timeout and cancellation behavior. Define retry limits, fallback, stale-data policy, TTL, key ownership, and cleanup.
+- Distinguish miss, confirmed absence, timeout, connection failure, parse failure, and partial write in code, logs, responses, and tests.
+
+### State, concurrency, and resources
+
+- Define the database transaction boundary, commit point, rollback behavior, and relationship between database writes and external side effects. Never imply atomicity across MySQL, Redis, Elasticsearch, RabbitMQ, or RPC without an implemented protocol.
+- For repeated execution, state the idempotency key, uniqueness or monotonic guard, result after prior success, behavior after partial failure, and retry owner.
+- Protect shared state with the nearest established synchronization pattern. State lock scope/order, contention and timeout behavior, and object lifetime across threads, event loops, goroutines in tests, callbacks, shutdown, and cancellation.
+- Assign one owner to close or release every lock, socket, channel, Redis lease/key, database handle, callback, thread, and temporary test resource on all paths.
+
+## Compatibility and observability
+
+- Preserve Protobuf field numbers, wire meanings, response envelopes, public error text, configuration defaults, exchange/queue contracts, database compatibility, and rolling mixed-version behavior unless the Issue explicitly authorizes a compatibility change.
+- Treat intentional public compatibility or settled-semantic changes as requiring human approval.
+- Use English for new identifiers, comments, and structured log messages. Include safe request/trace and outcome context; never log credentials, tokens, full message content, or unnecessary personal data.
+- Update affected ChatNow Skills and references in the same PR when architecture, service boundaries, infrastructure topology, core flows, or test architecture change. A follow-up Issue is not a substitute.
+
+## Required output
+
+Return these fields in order:
+
+1. **Changed invariants** — the Issue-scoped behavior change and preserved ownership, trust, ordering, and source-of-truth rules.
+2. **Files/ownership** — minimal changed files, nearest patterns used, and owners of state, side effects, callbacks, and cleanup.
+3. **Failure behavior** — bounded synchronous, asynchronous, timeout, cancellation, partial-failure, and recovery semantics.
+4. **Retry/idempotency** — retry owner, limits/backoff, idempotency key or guard, duplicate result, and repeated-execution behavior.
+5. **Compatibility** — wire, error, configuration, topology, data, rollout, and public-behavior impact.
+6. **Tests** — selected Go layer/case ID, exact observed RED, GREEN and regression commands/results, cleanup ownership, and checks not run.
+7. **Skill updates** — exact Skill/reference files changed in the same PR, or `None` with evidence that no governed architecture, core-flow, infrastructure, or test rule changed.
+
+## Common mistakes
+
+| Mistake | Required correction |
+|---|---|
+| Returning success for every Redis exception | Classify the key and failure, select an explicit safe mode, bound the call, and test each outcome. |
+| Retrying an unknown MQ publish as a new effect | Use publisher confirms and an idempotency guard; define the duplicate result and retry owner. |
+| Completing an RPC before its callback or capture lifetime ends | Keep dependencies alive and use an exactly-once completion guard. |
+| Updating a database and broker as if one transaction | Define the commit boundary and use the established Outbox/recovery pattern where required. |
+| Copying a nearby pattern without checking trust or ownership | Cite the pattern, then verify its boundary matches this operation. |
+| Calling a compile or static check a behavior test | Report only an observed Go behavioral RED/GREEN as runtime evidence. |

.agents/skills/chatnow-developing/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Develop ChatNow Services"
+  short_description: "Implement safe changes in ChatNow services"
+  default_prompt: "Use $chatnow-developing to implement this ChatNow production change safely."

.agents/skills/chatnow-maintaining-documentation/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: chatnow-maintaining-documentation
+description: Use when creating or changing ChatNow Skills, architecture references, API or operations documentation, engineering instructions, Issue text, or pull request text
+---
+
+# Maintain ChatNow Documentation
+
+## Core principle
+
+Keep one verified account of each engineering fact. Derive current-state claims from executable evidence, label proposals as proposals, and synchronize every affected Skill and reference in the same PR.
+
+## Evidence and labeling
+
+Use evidence in this order:
+
+1. Production source and Protobuf contracts.
+2. Executable configuration, CMake, Docker Compose, tests, and CI workflows.
+3. Git history for version-specific intent.
+4. README files, plans, specifications, roadmaps, changelogs, and other prose as secondary context only.
+
+Verify secondary claims against higher-precedence evidence. Cite repository paths and symbols or lines for material facts. Do not state an unverified, planned, partially implemented, unavailable, or historical capability as current.
+
+For an engineering reference or proposal, record the applicable version line, verification or proposal date, and one explicit status: `Current`, `Proposed`, `Historical`, `Deprecated`, or `Unverified`. Keep current and proposed behavior in separate sections. A date or confident tone does not turn a proposal into current behavior.
+
+## Mandatory workflow
+
+1. Resolve the primary Issue, target version line, current commit, audience, and canonical document for the subject.
+2. Inspect the executable evidence that owns every changed claim. Record contradictions and unknowns instead of resolving them by assumption.
+3. Update the canonical artifact in English. Preserve existing compatibility text unless the Issue explicitly changes the contract.
+4. Compute synchronization from the substance of the change, not the file extension:
+
+| Changed subject | Required same-PR updates |
+|---|---|
+| Architecture, service boundary, infrastructure topology, or core flow | `chatnow-orienting` and every affected reference under `.agents/skills/chatnow-orienting/references/` |
+| Test architecture, layers, tags, commands, fixtures, case IDs, or test workflow | `chatnow-orienting` where architecture context changes, plus affected `chatnow-testing` instructions and references |
+| Mandatory engineering workflow or policy | Every Skill and template that teaches or enforces that workflow |
+| Skill trigger or interface | The Skill plus matching `agents/openai.yaml` metadata |
+
+A follow-up Issue is not a substitute for these same-PR updates. Name the exact affected paths.
+
+5. Check every relative link, anchor, repository path, and command against the target commit. Remove stale links; do not link to a path or capability that does not exist.
+6. Review the full PR diff for contradictory status labels, duplicated facts, missing Skill synchronization, language violations, and claims unsupported by executable evidence.
+
+## Language contract
+
+- Write Skills, engineering references, API and operations documentation, automation, identifiers, new code comments, and new log messages in English.
+- Write Issue and PR titles in English. Write authored Issue and PR body prose in Chinese; preserve required English headings, field names, code, commands, and machine markers.
+- Write commit messages in English Conventional Commits.
+- Do not rewrite existing Chinese comments merely for translation without an Issue-local reason.
+
+## Canonical-artifact rule
+
+Extend the existing canonical document or Skill. Do not create a duplicate README, quick-reference, changelog, installation guide, migration narrative, process-history file, or stale status snapshot to explain the same facts. Active rollout or compatibility instructions belong in the canonical change document and must carry target version, date, and status.
+
+## Output contract
+
+Report:
+
+1. target version line, commit, document status, and date;
+2. executable evidence inspected and unresolved contradictions;
+3. canonical files changed;
+4. exact same-PR Skill, reference, and template updates, or `None` with evidence that no governed subject changed;
+5. language and link-integrity checks performed;
+6. unverified claims retained as explicitly `Unverified` or removed.
+
+## Stop conditions
+
+Stop and resolve the contract before claiming documentation current when the target version is ambiguous, executable sources conflict, a material claim is unverified, a proposal is presented as implemented, links are invalid, or required same-PR Skill updates are excluded.
+
+## Common mistakes
+
+| Mistake | Required correction |
+|---|---|
+| "Only a Markdown file changed." | Classify the changed engineering fact and synchronize affected Skills. |
+| "The proposal is approved, so call it current." | Keep it `Proposed` until executable evidence implements it. |
+| "The README already says so." | Verify against source, contracts, executable config, tests, and CI. |
+| "Update the Skill later." | Include exact affected Skill/reference paths in this PR. |
+| "Add a quick guide for visibility." | Update the canonical artifact and link to it; do not create parallel truth. |
+| "The link looks right." | Resolve and check the actual target and anchor at the target commit. |

.agents/skills/chatnow-maintaining-documentation/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Maintain ChatNow Documentation"
+  short_description: "Keep ChatNow engineering facts and Skills synchronized"
+  default_prompt: "Use $chatnow-maintaining-documentation to update ChatNow engineering documentation."