docs: update CLAUDE.md with behavioral guidelines and project-specifi…

.claude/CLAUDE.md

@@ -0,0 +1,12 @@
+# .claude
+
+## Role
+- Owns Claude-specific repo automation, commands, and local assistant state.
+
+## Owns
+- Slash-command definitions in `commands/`.
+- Claude-local workflow assets that do not ship in the npm package.
+
+## Avoid
+- Do not place runtime plugin code here.
+- Do not make product behavior depend on local worktree or cache content.

.claude/commands/CLAUDE.md

@@ -0,0 +1,12 @@
+# .claude/commands
+
+## Role
+- Owns slash-command entry files for spec-kit and related Claude workflows.
+
+## Owns
+- One markdown command file per command.
+- Command wording, arguments, and invocation flow only.
+
+## Avoid
+- Do not duplicate product documentation here.
+- Do not encode runtime plugin logic in command files.

.github/CLAUDE.md

@@ -0,0 +1,12 @@
+# .github
+
+## Role
+- Owns repository automation and CI/CD configuration.
+
+## Owns
+- Workflow definitions in `workflows/`.
+- Review, publish, and repo-policy automation.
+
+## Avoid
+- Do not move product logic from `src/` into GitHub automation.
+- Do not broaden permissions or secret usage without a release or security need.

.github/workflows/CLAUDE.md

@@ -0,0 +1,11 @@
+# .github/workflows
+
+## Role
+- Owns executable GitHub Actions workflows for review and publish paths.
+
+## Owns
+- Trigger rules, job graphs, permissions, and release automation.
+
+## Avoid
+- Keep workflow permissions least-privilege.
+- Keep steps reproducible from tracked repo files; avoid hidden local assumptions.

.gitignore

@@ -78,3 +78,5 @@ skills-lock.json
 
 # specs (development-only, not shipped)
 specs/
+
+doc

.specify/CLAUDE.md

@@ -0,0 +1,13 @@
+# .specify
+
+## Role
+- Owns spec-kit scaffolding, templates, memory, and helper scripts for planning workflows.
+
+## Owns
+- Generated planning context in `memory/`.
+- Bootstrap scripts in `scripts/`.
+- Reusable artifact templates in `templates/`.
+
+## Avoid
+- Do not couple runtime plugin behavior to files here.
+- Root `CLAUDE.md` is managed by `scripts/powershell/update-agent-context.ps1`; treat it as generated context.

.specify/memory/CLAUDE.md

@@ -1,10 +1,12 @@
-<claude-mem-context>
-# Recent Activity
+# .specify/memory
 
-### Mar 13, 2026
+## Role
+- Owns generated spec-kit memory and long-lived planning context.
 
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #1610 | 10:13 PM | 🟣 | OpenCode property forwarding feature completed and submitted for review | ~1768 |
-| #1605 | 10:03 PM | 🟣 | Feature planning completed for OpenCode property forwarding to observability backends | ~1466 |
-</claude-mem-context>
+## Owns
+- `constitution.md` and other machine-maintained memory inputs.
+- Context snapshots consumed by spec-kit update scripts.
+
+## Avoid
+- Treat files here as tooling state, not product docs.
+- Do not store runtime source rules here when they belong in repo-level instructions.

.specify/scripts/CLAUDE.md

@@ -0,0 +1,12 @@
+# .specify/scripts
+
+## Role
+- Owns automation entrypoints that bootstrap and update spec-kit artifacts.
+
+## Owns
+- Shell-specific implementations in child folders.
+- Cross-script orchestration boundaries and invocation contracts.
+
+## Avoid
+- Do not add product runtime logic here.
+- Keep script behavior aligned with templates and generated-context expectations.

.specify/scripts/powershell/CLAUDE.md

@@ -1,10 +1,12 @@
-<claude-mem-context>
-# Recent Activity
+# .specify/scripts/powershell
 
-### Mar 13, 2026
+## Role
+- Owns PowerShell implementations of spec-kit setup and agent-context update flows.
 
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #1610 | 10:13 PM | 🟣 | OpenCode property forwarding feature completed and submitted for review | ~1768 |
-| #1605 | 10:03 PM | 🟣 | Feature planning completed for OpenCode property forwarding to observability backends | ~1466 |
-</claude-mem-context>
+## Owns
+- Feature bootstrap scripts.
+- Shared PowerShell helpers and repo-context update scripts.
+
+## Avoid
+- Preserve compatibility with generated root agent-context files.
+- Do not add repo product behavior here beyond scaffolding support.

.specify/templates/CLAUDE.md

@@ -1,10 +1,11 @@
-<claude-mem-context>
-# Recent Activity
+# .specify/templates
 
-### Mar 13, 2026
+## Role
+- Owns reusable markdown templates that seed future spec, plan, task, and agent-context artifacts.
 
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #1610 | 10:13 PM | 🟣 | OpenCode property forwarding feature completed and submitted for review | ~1768 |
-| #1605 | 10:03 PM | 🟣 | Feature planning completed for OpenCode property forwarding to observability backends | ~1466 |
-</claude-mem-context>
+## Owns
+- Template structure, placeholders, and generated-file boilerplate.
+
+## Avoid
+- Template changes affect future generated files, not current source directly.
+- Keep templates generic; do not hard-code one-off feature decisions here.

CLAUDE.md

@@ -1,10 +1,76 @@
 # CLAUDE.md
 
-## What This Project Is
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+
+## Project-Specific Guidelines
+
+### What This Project Is
 
 **opencode-otel** — an OpenCode npm plugin that forwards runtime stderr logs to any OTLP-compatible log collector via gRPC or HTTP. Business events (traces/spans) are handled by opencode-plugin-langfuse.
 
-## Technical Context
+### Technical Context
 
 - **Language**: TypeScript 5.5+ / Bun runtime
 - **Project Type**: npm library (OpenCode plugin)
@@ -13,15 +79,15 @@
 - **Build**: tsup (ESM output, external `@opencode-ai/*`)
 - **Testing**: `bun test`
 
-## Key Constraints
+### Key Constraints
 
 - **Cannot modify OpenCode source code** — integration via npm plugin mechanism only
 - **Monkey-patch `process.stderr.write`** — runtime interception of log output (JS dynamic proxy pattern)
 - **gRPC primary, HTTP fallback** — company TripLog collector only accepts gRPC on :8080
 - **Uses `event` hook for session lifecycle tracking** (`session.created`/`idle`/`deleted`) — creates root spans per session so all logs share the same traceId
 - **No business traces/spans** — business events handled by opencode-plugin-langfuse
 
-## Architecture
+### Architecture
 
 ```text
 Plugin Entry (src/index.ts)
@@ -31,7 +97,7 @@ Plugin Entry (src/index.ts)
   └─ Shutdown (src/shutdown.ts) ← graceful flush on process exit
 ```
 
-## Configuration
+### Configuration
 
 | Env Variable | Default | Description |
 |-------------|---------|-------------|
@@ -41,7 +107,7 @@ Plugin Entry (src/index.ts)
 | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | — | Traces endpoint (optional, for session span export) |
 | `OTEL_RESOURCE_ATTRIBUTES` | — | Additional resource attributes (auto-parsed by SDK) |
 
-## Design Documents
+### Design Documents
 
 All specs are in `specs/` directory:
 - `constitution.md` — project constitution and principles

doc/plugin-sdk-api.md

@@ -0,0 +1 @@
+D:/openSource/opencode/docs/plugin-sdk-api.md

src/CLAUDE.md

@@ -1,10 +1,15 @@
-<claude-mem-context>
-# Recent Activity
+# src
 
-### Mar 13, 2026
+## Role
+- Owns the shipped plugin runtime and OTEL integration logic.
 
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #1614 | 10:31 PM | 🟣 | PR #12 merged: OpenCode property forwarding to observability backends | ~1032 |
-| #1610 | 10:13 PM | 🟣 | OpenCode property forwarding feature completed and submitted for review | ~1768 |
-</claude-mem-context>
+## Owns
+- Plugin entry, config parsing, exporter/provider wiring, stderr interception, session state, and shutdown flow.
+
+## Boundaries
+- Keep `index.ts` orchestration-only.
+- Keep config parsing in `config.ts`, transport wiring in `provider.ts`, and stderr interception in `interceptor.ts`.
+
+## Avoid
+- Do not place tests, workflow automation, or planning artifacts here.
+- Do not let one module absorb another module's responsibility just to avoid a new file.

tests/CLAUDE.md

@@ -0,0 +1,12 @@
+# tests
+
+## Role
+- Owns automated verification for the plugin.
+
+## Owns
+- Test organization, fixtures, and shared testing conventions.
+- Fast unit coverage in `unit/`.
+
+## Avoid
+- Do not duplicate production logic in tests.
+- Keep flaky timing, network access, and external collector dependencies out of this tree.

tests/unit/CLAUDE.md

@@ -1,11 +1,11 @@
-<claude-mem-context>
-# Recent Activity
+# tests/unit
 
-### Mar 13, 2026
+## Role
+- Owns fast, deterministic unit tests for modules under `src/`.
 
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #1614 | 10:31 PM | 🟣 | PR #12 merged: OpenCode property forwarding to observability backends | ~1032 |
-| #1612 | 10:21 PM | 🔴 | Fixed provider.shutdown() to await properly in resource attribute tests | ~432 |
-| #1610 | 10:13 PM | 🟣 | OpenCode property forwarding feature completed and submitted for review | ~1768 |
-</claude-mem-context>
+## Owns
+- Module-level behavior checks for config parsing, interception, provider setup, and session-safe changes.
+
+## Avoid
+- Do not turn these tests into integration or e2e suites.
+- Prefer direct behavior assertions over duplicating implementation details.