diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 0000000..9c7f5c0 --- /dev/null +++ b/.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. diff --git a/.claude/commands/CLAUDE.md b/.claude/commands/CLAUDE.md new file mode 100644 index 0000000..8448a71 --- /dev/null +++ b/.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. diff --git a/.github/CLAUDE.md b/.github/CLAUDE.md new file mode 100644 index 0000000..e610e1f --- /dev/null +++ b/.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. diff --git a/.github/workflows/CLAUDE.md b/.github/workflows/CLAUDE.md new file mode 100644 index 0000000..c9ef42f --- /dev/null +++ b/.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. diff --git a/.gitignore b/.gitignore index 73cba21..6d5600a 100644 --- a/.gitignore +++ b/.gitignore @@ -78,3 +78,5 @@ skills-lock.json # specs (development-only, not shipped) specs/ + +doc diff --git a/.specify/CLAUDE.md b/.specify/CLAUDE.md new file mode 100644 index 0000000..7173013 --- /dev/null +++ b/.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. diff --git a/.specify/memory/CLAUDE.md b/.specify/memory/CLAUDE.md index f172918..2647e48 100644 --- a/.specify/memory/CLAUDE.md +++ b/.specify/memory/CLAUDE.md @@ -1,10 +1,12 @@ - -# 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 | - \ No newline at end of file +## 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. diff --git a/.specify/scripts/CLAUDE.md b/.specify/scripts/CLAUDE.md new file mode 100644 index 0000000..4a14f9f --- /dev/null +++ b/.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. diff --git a/.specify/scripts/powershell/CLAUDE.md b/.specify/scripts/powershell/CLAUDE.md index f172918..6f77d8c 100644 --- a/.specify/scripts/powershell/CLAUDE.md +++ b/.specify/scripts/powershell/CLAUDE.md @@ -1,10 +1,12 @@ - -# 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 | - \ No newline at end of file +## 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. diff --git a/.specify/templates/CLAUDE.md b/.specify/templates/CLAUDE.md index f172918..fafdb61 100644 --- a/.specify/templates/CLAUDE.md +++ b/.specify/templates/CLAUDE.md @@ -1,10 +1,11 @@ - -# 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 | - \ No newline at end of file +## 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. diff --git a/CLAUDE.md b/CLAUDE.md index d06dc51..f19ca8f 100644 --- a/CLAUDE.md +++ b/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,7 +79,7 @@ - **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) @@ -21,7 +87,7 @@ - **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 diff --git a/doc/plugin-sdk-api.md b/doc/plugin-sdk-api.md new file mode 120000 index 0000000..9a6cf37 --- /dev/null +++ b/doc/plugin-sdk-api.md @@ -0,0 +1 @@ +D:/openSource/opencode/docs/plugin-sdk-api.md \ No newline at end of file diff --git a/src/CLAUDE.md b/src/CLAUDE.md index f9c698f..60572af 100644 --- a/src/CLAUDE.md +++ b/src/CLAUDE.md @@ -1,10 +1,15 @@ - -# 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 | - \ No newline at end of file +## 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. diff --git a/tests/CLAUDE.md b/tests/CLAUDE.md new file mode 100644 index 0000000..8dbe7d4 --- /dev/null +++ b/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. diff --git a/tests/unit/CLAUDE.md b/tests/unit/CLAUDE.md index fcd0cb3..5fda168 100644 --- a/tests/unit/CLAUDE.md +++ b/tests/unit/CLAUDE.md @@ -1,11 +1,11 @@ - -# 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 | - \ No newline at end of file +## 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.