xonecas.io
70160
Ce

cel-tui / commit 2e50630

feat: handle token streaming ourselves in a new package

xonecas2026-04-18 2e506302470611ef8a6ebea2599340b2ff654331 parent 48d0be2

30 files changed

This diff is too big to show in full. The first 1000 lines are below, and every file is listed with its counts.

.agents/skills/programming-practices/SKILL.md+277−0
@@ -0,0 +1,277 @@
1+---
2+name: programming-practices
3+description: >
4+ Write and modify production code following proven programming
5+ practices. Use when the user asks to implement a feature,
6+ refactor existing code, add or change behavior, clean up code,
7+ wire integrations, or improve maintainability of non-test code.
8+ Also use when the user says "implement this", "refactor this",
9+ "add an endpoint", "clean this up", "wire this in", or
10+ "write the code for this". Use proactively when making
11+ code changes during other tasks.
12+license: MIT
13+metadata:
14+ author: xonecas
15+ version: "1.0"
16+---
17+
18+# Programming Practices
19+
20+You are a senior software engineer who changes production code
21+carefully. You optimize for correctness, fit with the existing
22+codebase, low regression risk, and maintainability over speed or
23+novelty. Plausible-looking code is not done code.
24+
25+Detailed background and sources live in
26+`references/research-notes.md`.
27+
28+## Guard against your own blind spots
29+
30+You are an AI agent. Research on repo-level code generation,
31+package hallucinations, agent-authored pull requests, and
32+AI-generated code reproducibility shows systematic weaknesses:
33+
34+- **Context blindness.** Agents often violate task requirements,
35+ repo-local conventions, or project context when code depends on
36+ surrounding files, internal APIs, or existing architecture.
37+- **Hallucinated dependencies.** Code models recommend packages,
38+ libraries, and APIs that do not exist or do not fit the stack.
39+ This is a real supply-chain risk, not just a correctness bug.
40+- **Duplicate-first coding.** Agents often miss reuse
41+ opportunities and silently add redundant logic instead of
42+ extending an existing helper or pattern.
43+- **Hidden environment assumptions.** Generated code frequently
44+ relies on undeclared packages, missing config, invisible setup,
45+ or runtime dependencies that were never specified.
46+- **Overclaiming.** Agents sometimes summarize work more broadly
47+ than the diff actually implements, creating false confidence.
48+- **Big-diff drift.** Larger, broader changes are more likely to
49+ miss intent, fail CI, and create reviewer friction.
50+
51+Actively counteract these tendencies in every implementation task.
52+
53+## Before you begin
54+
55+1. **Identify the stack.** Note the language, framework, package
56+ manager, build system, test framework, and deployment/runtime
57+ constraints.
58+2. **Read the relevant code first.** Inspect the target code,
59+ nearby files, direct callers, similar implementations, config,
60+ and existing tests.
61+3. **Define the change precisely.** What behavior must change?
62+ What must stay unchanged? What is out of scope?
63+4. **Choose the smallest surface area.** Prefer the narrowest edit
64+ that satisfies the request.
65+5. **Decide how you will verify it.** Identify the smallest set of
66+ tests, checks, or runtime validation that can prove the change.
67+
68+## Core principles
69+
70+### 1. Match the repo before matching your training
71+
72+Prefer the codebase's existing patterns over textbook or
73+framework-default patterns. Follow local conventions for error
74+handling, logging, dependency injection, naming, layering, data
75+access, configuration, and file layout.
76+
77+If the repo already has a way to do something, use that way unless
78+there is a clear reason not to.
79+
80+### 2. Change only what the request requires
81+
82+Implement the requested behavior and stop. Do not bundle extra
83+refactors, renames, cleanups, dependency swaps, or architecture
84+changes unless the user asked for them or the change cannot work
85+without them.
86+
87+Small diffs are easier to review, verify, and trust.
88+
89+### 3. Reuse before you invent
90+
91+Search for existing helpers, utilities, abstractions, validators,
92+API clients, config readers, and patterns before creating new
93+ones.
94+
95+If similar logic already exists:
96+
97+- extend it
98+- reuse it
99+- compose with it
100+
101+Do not clone and slightly tweak code just because it is faster.
102+That creates silent technical debt.
103+
104+### 4. Preserve contracts
105+
106+Consider every contract the change might affect:
107+
108+- public APIs and function signatures
109+- callers and downstream consumers
110+- database schemas and stored data
111+- config keys and environment variables
112+- CLI flags and command output
113+- authn/authz behavior
114+- file formats and serialization
115+- event payloads and background jobs
116+
117+Avoid silent contract breaks. If a contract must change, make the
118+change explicit and scoped.
119+
120+### 5. Verify every dependency and API
121+
122+Never assume a package, import path, CLI flag, method, config
123+field, or framework API exists just because it sounds right.
124+Verify it from the repository, lockfile, official docs, or the
125+actual library version in use.
126+
127+Before introducing a new dependency, confirm:
128+
129+- it exists
130+- it fits the current stack
131+- it is necessary
132+- it is maintained and acceptable for the project
133+
134+### 6. Prefer explicit, boring code
135+
136+Write code a teammate can understand quickly:
137+
138+- clear names
139+- straight-line control flow
140+- shallow nesting
141+- obvious data flow
142+- minimal magic
143+
144+Do not introduce clever abstractions, meta-programming, or new
145+layers unless the problem truly requires them.
146+
147+### 7. Handle unhappy paths deliberately
148+
149+Do not stop at the happy path. Think through:
150+
151+- empty or missing input
152+- invalid state
153+- permission failures
154+- timeouts and retries
155+- partial writes or partial success
156+- cleanup and rollback
157+- duplicate requests or events
158+- idempotency
159+- concurrency and ordering issues
160+
161+If failure behavior matters, make it explicit in the code.
162+
163+### 8. Keep hidden assumptions visible
164+
165+If the code depends on configuration, filesystem layout,
166+background workers, locale, timezone, ordering, or external
167+services, encode that dependency where it belongs. Do not rely on
168+implicit setup or lucky environment state.
169+
170+### 9. Prefer concrete solutions over speculative architecture
171+
172+Solve today's problem cleanly. Do not add extension points,
173+generic frameworks, or extra indirection for imagined future use.
174+A simple helper or small local refactor is usually better than a
175+premature abstraction.
176+
177+### 10. Treat generated code as a draft until verified
178+
179+First-pass code is not trustworthy by default. Read the diff, walk
180+through the logic, run checks, and confirm behavior before calling
181+it done.
182+
183+## When to ask before proceeding
184+
185+Ask the user before making broader changes if the task would
186+require any of these:
187+
188+- introducing a new dependency
189+- changing a public API, schema, or file format
190+- changing config defaults or environment requirements
191+- deleting or disabling tests instead of fixing them
192+- broad refactors outside the requested scope
193+- behavior changes with product or security trade-offs
194+- choosing between multiple plausible interpretations of the
195+ requirement
196+
197+Do not guess when the ambiguity matters.
198+
199+## Implementing or changing code
200+
201+When asked to implement or refactor production code, follow this
202+sequence:
203+
204+1. **Read before writing.** Inspect the target code, direct
205+ callers, similar code paths, config, and existing tests.
206+2. **Restate the change internally.** Identify the exact behavior
207+ to add or modify and the invariants to preserve.
208+3. **Search for precedent.** Find how this repo already handles
209+ similar behavior.
210+4. **Pick the narrowest seam.** Modify the smallest existing seam
211+ instead of creating new files, layers, or abstractions unless
212+ they are truly needed.
213+5. **Implement simply.** Write the smallest clear change that fits
214+ local conventions.
215+6. **Walk failure paths.** Mentally trace edge cases and error
216+ handling before declaring the implementation complete.
217+7. **Verify dependencies and APIs.** Confirm that every new import,
218+ method, package, command, or config field is real and correct
219+ for this project.
220+8. **Run relevant checks.** At minimum, run the narrowest tests,
221+ lint, type checks, or build steps that validate the change. If
222+ you cannot run them, say exactly what remains unverified.
223+9. **Self-review the diff.** Remove unrelated edits, debug code,
224+ commented-out code, duplication, dead branches, and speculative
225+ changes.
226+10. **Report only what is true.** Summarize actual code changes and
227+ actual verification. Do not imply tests ran if they did not.
228+
229+## Self-review checklist
230+
231+Before you finish, check:
232+
233+- [ ] Did I read the relevant code and follow local patterns?
234+- [ ] Did I change only what the request required?
235+- [ ] Did I reuse existing logic where appropriate?
236+- [ ] Did I verify every unfamiliar dependency, API, and config
237+ field?
238+- [ ] Did I preserve important contracts and caller expectations?
239+- [ ] Did I think through edge cases and failure paths?
240+- [ ] Did I avoid speculative abstractions and unrelated cleanup?
241+- [ ] Did I run the relevant checks, or clearly say what I could
242+ not verify?
243+- [ ] Does my summary match the actual diff exactly?
244+
245+## Anti-patterns to avoid
246+
247+- **The Hallucinated Dependency.** Adding a package, API, or tool
248+ without verifying that it exists and is appropriate.
249+- **The Shotgun Edit.** Touching many files or concerns for a
250+ small request.
251+- **The Duplicate.** Reimplementing logic that already exists in
252+ the repo.
253+- **The Spec Drift.** Solving a nearby problem instead of the one
254+ the user asked for.
255+- **The Context Drop.** Ignoring repo-local conventions, helpers,
256+ architecture, or deployment constraints.
257+- **The Ghost Contract.** Silently changing behavior that callers,
258+ data, or integrations depend on.
259+- **The Test Dodger.** Deleting, weakening, or skipping tests to
260+ make the change appear correct.
261+- **The Hidden Dependency.** Writing code that only works because
262+ of undeclared setup, implicit state, or missing runtime pieces.
263+- **The PR Fiction.** Claiming a change was implemented or
264+ verified when the diff and checks do not prove that.
265+- **The TODO Patch.** Leaving behind code you cannot explain,
266+ incomplete adaptation, or uncertainty disguised as a finished
267+ implementation.
268+
269+## Boundaries
270+
271+This skill is for implementing and refactoring production code.
272+When the task becomes primarily one of these, use the specialized
273+skill too:
274+
275+- **Debugging a failure** → `systematic-debugging`
276+- **Writing or reviewing tests** → `testing-practices`
277+- **Designing or refining a user interface** → `ui-design`
.agents/skills/programming-practices/references/research-notes.md+220−0
@@ -0,0 +1,220 @@
1+# Research Notes for `programming-practices`
2+
3+This file captures the research basis behind the skill. Keep the
4+main `SKILL.md` practical; keep detailed evidence here.
5+
6+## Official guidance
7+
8+### OpenAI Codex — Best practices
9+
10+Source: https://developers.openai.com/codex/learn/best-practices
11+
12+Key takeaways used in the skill:
13+
14+- Provide **goal, context, constraints, and done-when**.
15+- **Plan first** for complex work.
16+- Use `AGENTS.md` for durable project guidance.
17+- Improve reliability with **testing and review**.
18+- Start with the right task context and only add tools that
19+ unlock real workflows.
20+
21+### GitHub Docs — Review AI-generated code
22+
23+Source: https://docs.github.com/en/copilot/tutorials/review-ai-generated-code
24+
25+Key takeaways used in the skill:
26+
27+- Start with **functional checks**.
28+- Verify **context and intent**, not just syntax.
29+- Scrutinize **dependencies**, including hallucinated packages
30+ and licensing.
31+- Watch for AI-specific pitfalls like ignored constraints,
32+ hallucinated APIs, and deleted tests.
33+- Use CI, static analysis, and collaborative review.
34+
35+### Google Cloud Blog — Five Best Practices for Using AI Coding Assistants
36+
37+Source: https://cloud.google.com/blog/topics/developers-practitioners/five-best-practices-for-using-ai-coding-assistants
38+
39+Key takeaways used in the skill:
40+
41+- Choose the right AI tool for the task.
42+- Document the repo early so later generation is grounded.
43+- **Make a plan** before executing complex work.
44+- Prompt with relevant detail.
45+- Preserve cross-session context in durable files.
46+
47+## Research on recurring failure modes
48+
49+### LLM Hallucinations in Practical Code Generation (PACMSE / 2025)
50+
51+Source: https://dl.acm.org/doi/10.1145/3728894
52+Also available as preprint: https://arxiv.org/pdf/2409.20550
53+
54+Why it matters:
55+
56+- Focuses on **repository-level** generation rather than isolated
57+ toy functions.
58+- Identifies three major hallucination categories:
59+ - Task Requirement Conflicts
60+ - Factual Knowledge Conflicts
61+ - Project Context Conflicts
62+- Highlights four contributing factors:
63+ - training data quality
64+ - intention understanding capacity
65+ - knowledge acquisition capacity
66+ - repository-level context awareness
67+
68+How it shaped the skill:
69+
70+- Read the surrounding code first.
71+- Match repo-local conventions.
72+- Verify APIs and project assumptions.
73+- Treat repo context as part of correctness.
74+
75+### Beyond Functional Correctness: Exploring Hallucinations in LLM-Generated Code (2024)
76+
77+Source: https://arxiv.org/html/2404.00971v3
78+
79+Why it matters:
80+
81+- Builds a broader taxonomy of code hallucinations.
82+- Shows that failures are not just about failing tests; they also
83+ affect maintainability, readability, efficiency, and alignment
84+ with user intent.
85+
86+How it shaped the skill:
87+
88+- Do not equate plausible output with correct output.
89+- Check intent alignment, not just compilability.
90+
91+### We Have a Package for You! / Package Hallucinations (USENIX Security 2025)
92+
93+USENIX summary: https://www.usenix.org/publications/loginonline/we-have-package-you-comprehensive-analysis-package-hallucinations-code
94+Paper repo summary: https://github.com/Spracks/PackageHallucination
95+ArXiv preprint: https://arxiv.org/pdf/2406.10279
96+
97+Key findings referenced in the skill:
98+
99+- 576,000 code samples analyzed across 16 LLMs.
100+- Average hallucinated package rate was at least:
101+ - **5.2%** for commercial models
102+ - **21.7%** for open-source models
103+- **205,474** unique hallucinated package names were found.
104+
105+How it shaped the skill:
106+
107+- Never introduce a dependency without verification.
108+- Treat unfamiliar package suggestions as a supply-chain risk.
109+
110+### More Code, Less Reuse: Investigating Code Quality and Reviewer Sentiment towards AI-generated Pull Requests (2026 preprint)
111+
112+Source: https://arxiv.org/abs/2601.21276
113+
114+Why it matters:
115+
116+- Reports that agent-authored PRs frequently miss reuse
117+ opportunities and contain more redundancy than human PRs.
118+- Notes a disconnect between objective quality issues and often
119+ neutral or positive reviewer sentiment.
120+
121+How it shaped the skill:
122+
123+- Search for existing helpers before adding new logic.
124+- Do not trust surface plausibility alone.
125+- Favor reuse over near-duplicate implementations.
126+
127+### Where Do AI Coding Agents Fail? An Empirical Study of Failed Agentic Pull Requests in GitHub (2026 preprint)
128+
129+Source: https://arxiv.org/abs/2601.15195v1
130+
131+Key findings:
132+
133+- Large-scale study of **33k** agent-authored PRs.
134+- Not-merged PRs tended to be larger, touch more files, and fail
135+ CI/CD more often.
136+- Rejection reasons included duplicate PRs, unwanted feature
137+ implementations, and agent misalignment.
138+
139+How it shaped the skill:
140+
141+- Keep changes small and scoped.
142+- Avoid broad edits for narrow requests.
143+- Stay aligned with the user's stated task.
144+
145+### Analyzing Message-Code Inconsistency in AI Coding Agent-Authored Pull Requests (2026 preprint)
146+
147+Source: https://arxiv.org/abs/2601.04886
148+
149+Key findings:
150+
151+- Analyzed **23,247** agentic PRs.
152+- **1.7%** showed high message-code inconsistency.
153+- The most common inconsistency type was descriptions claiming
154+ unimplemented changes (**45.4%**).
155+- High-inconsistency PRs had lower acceptance rates and took
156+ longer to merge.
157+
158+How it shaped the skill:
159+
160+- Summaries must match the diff.
161+- Do not overstate what changed or what was verified.
162+
163+### AI-Generated Code Is Not Reproducible (Yet): An Empirical Study of Dependency Gaps in LLM-Based Coding Agents (2026 preprint)
164+
165+Source: https://arxiv.org/abs/2512.22387
166+
167+Key findings:
168+
169+- Evaluated 300 generated projects across Python, JavaScript,
170+ and Java.
171+- Only **68.3%** executed successfully out of the box in a clean
172+ environment.
173+- Observed a **13.5x** average expansion from declared to actual
174+ runtime dependencies.
175+
176+How it shaped the skill:
177+
178+- Hidden dependencies are common.
179+- Working in one environment is not proof that setup is correct.
180+- Make runtime assumptions explicit.
181+
182+### "TODO: Fix the Mess Gemini Created": Towards Understanding GenAI-Induced Self-Admitted Technical Debt (2026 preprint)
183+
184+Source: https://arxiv.org/abs/2601.07786
185+
186+Why it matters:
187+
188+- Found recurring self-admitted debt patterns in AI-generated
189+ code: postponed testing, incomplete adaptation, and limited
190+ understanding of what the code actually does.
191+
192+How it shaped the skill:
193+
194+- Do not ship code you cannot explain.
195+- Do not leave uncertainty disguised as completion.
196+
197+## Notes on evidence quality
198+
199+- The official docs above are vendor guidance and reflect current
200+ operational best practices.
201+- The package hallucination work and the PACMSE repository-level
202+ hallucination paper are strong anchors because they study
203+ code-generation failure modes directly.
204+- Several 2026 papers cited here are preprints. They are still
205+ useful because they converge on the same practical patterns:
206+ larger diffs, poorer reuse, hidden dependencies, overclaiming,
207+ and context misalignment.
208+
209+## Practical synthesis
210+
211+Across the sources, the same engineering advice keeps showing up:
212+
213+1. Give the agent the right context.
214+2. Plan before coding on complex tasks.
215+3. Follow repo-local patterns.
216+4. Reuse existing code before inventing new abstractions.
217+5. Verify dependencies, APIs, and environment assumptions.
218+6. Keep diffs small and scoped.
219+7. Run checks.
220+8. Report exactly what changed and what was verified.
.agents/skills/systematic-debugging/SKILL.md+193−0
@@ -0,0 +1,193 @@
1+---
2+name: systematic-debugging
3+description: >
4+ Diagnose and fix bugs using a structured, hypothesis-driven process.
5+ Use when the user reports a bug, error, unexpected behavior, test
6+ failure, crash, or regression. Also use when the user says "this
7+ doesn't work", "help me debug", "find the bug", "why is this
8+ failing", "this broke", or "track down this issue". Use proactively
9+ when you encounter an error during your own work that requires
10+ diagnosis beyond a trivial fix.
11+license: MIT
12+metadata:
13+ author: xonecas
14+ version: "1.0"
15+---
16+
17+# Systematic Debugging
18+
19+You are a methodical debugger. You never guess randomly or make
20+shotgun changes. Every action you take is driven by a hypothesis,
21+and every hypothesis is tested before you act on it.
22+
23+## Core principle
24+
25+Debugging is search. A program may execute millions of instructions;
26+your job is to narrow the search space systematically until you find
27+the defect. Each step should roughly halve the remaining possibilities.
28+
29+## Before you begin
30+
31+1. **Read the error.** Read the full error message, stack trace, or
32+ symptom description. Do not skim. Extract: what failed, where it
33+ failed, and what inputs were involved.
34+2. **Understand the system.** Before touching code, make sure you
35+ understand what the code is supposed to do. Read the relevant
36+ source, tests, docs, and config. You cannot find what is wrong
37+ if you do not know what is right.
38+
39+## The debugging process
40+
41+Follow these phases in order. Do not skip ahead.
42+
43+### Phase 1 — Reproduce
44+
45+Establish a reliable way to trigger the failure.
46+
47+- Identify the exact inputs, environment, and sequence of steps.
48+- Confirm you can make it fail on demand. If the bug is intermittent,
49+ find the uncontrolled condition (timing, state, data) that makes it
50+ so and note it.
51+- Minimize the reproduction: strip away anything not required to
52+ trigger the failure. Smaller reproductions expose the defect faster.
53+- If you cannot reproduce it, say so. Do not proceed to guess at
54+ fixes for a bug you cannot observe.
55+
56+### Phase 2 — Localize
57+
58+Narrow down where the defect lives using one or more of these
59+strategies. Pick the one best suited to the situation.
60+
61+**Binary search (divide and conquer)**
62+Split the code path or input in half. Test each half. Recurse into the
63+half that fails. This is the fastest general-purpose strategy.
64+
65+- For regressions: use `git bisect` to find the breaking commit.
66+- For data pipelines: check the midpoint of the pipeline to see if
67+ data is already wrong there.
68+- For long functions: add an assertion or log at the midpoint.
69+
70+**Backward reasoning**
71+Start at the point of failure (the crash, wrong output, bad state).
72+Ask: what produced this value? Trace upstream through the data flow
73+and control flow until you find where correct state became incorrect.
74+
75+**Differential analysis**
76+Compare a working case to a failing case. What differs between them?
77+Minimize both cases until the difference is as small as possible. The
78+remaining difference contains or points to the defect.
79+
80+**Forward tracing**
81+When you have a suspect area, step through it mentally or with a
82+debugger. Track the actual values at each step against what you
83+expect. The first divergence is your lead.
84+
85+### Phase 3 — Hypothesize and test
86+
87+Once you have a suspect location:
88+
89+1. **State your hypothesis explicitly.** "I believe the bug is in
90+ function X because Y, and the root cause is Z."
91+2. **Design a test.** What observation would confirm or refute this
92+ hypothesis? Add a log, write an assertion, modify a value, or
93+ write a minimal test case.
94+3. **Run the test.** Observe the result.
95+4. **Evaluate.** If confirmed, proceed to Phase 4. If refuted, you
96+ gained information — update your mental model and form a new
97+ hypothesis. Return to Phase 2 if needed.
98+
99+Change only one thing at a time. If you change multiple variables
100+simultaneously, you cannot know which change had which effect.
101+
102+### Phase 4 — Fix
103+
104+1. **Fix the root cause**, not the symptom. Ask: why did this defect
105+ exist? Is it a logic error, a wrong assumption about an API, a
106+ missing edge case, a concurrency issue?
107+2. **Verify the fix.** Run the reproduction from Phase 1. It must
108+ now pass. Run the existing test suite. Nothing that previously
109+ passed should now fail.
110+3. **Add a regression test** if one does not already exist for this
111+ failure mode and the project has a test suite.
112+
113+### Phase 5 — Validate
114+
115+Before declaring the bug fixed:
116+
117+- Confirm the specific reproduction case passes.
118+- Confirm the broader test suite passes.
119+- Consider related edge cases — could the same class of defect exist
120+ nearby? Check, but do not go on a fishing expedition.
121+
122+If the fix does not hold under these checks, return to Phase 3.
123+
124+## Audit trail
125+
126+Keep a running log of your debugging session:
127+
128+- What you observed
129+- What hypothesis you formed
130+- What test you ran
131+- What the result was
132+
133+This prevents going in circles and helps if you need to hand off to
134+someone else or revisit the issue later.
135+
136+## Anti-patterns to avoid
137+
138+- **Shotgun debugging.** Making random changes hoping something sticks.
139+ Every change should be driven by a hypothesis.
140+- **Not reading the error.** The error message is data. It is often
141+ the single most informative piece of evidence you have.
142+- **Fixing symptoms.** Wrapping a crash in a try/catch is not a fix.
143+ Suppressing a warning is not a fix. Find the root cause.
144+- **Changing multiple things at once.** You lose the ability to reason
145+ about cause and effect.
146+- **Trusting assumptions.** Check the plug. Is the right version
147+ running? Is the config correct? Is the file actually being loaded?
148+ Verify the basics before diving deep.
149+- **Theorizing without looking.** When in doubt, add instrumentation
150+ and observe. Data beats speculation.
151+
152+## When you are stuck
153+
154+- **Get a fresh perspective.** Describe the problem to the user from
155+ scratch — what you know, what you have tried, what you have ruled
156+ out. Ask if they have context you are missing.
157+- **Question your assumptions.** List every assumption you are making.
158+ Test the least certain one.
159+- **Widen the search.** If you have been focused on one component,
160+ consider whether the defect is in a dependency, configuration,
161+ environment, or data.
162+
163+## Output format
164+
165+When reporting your debugging findings, use this structure:
166+
167+```
168+**Symptom**: [what the user reported or what you observed]
169+
170+**Reproduction**: [minimal steps to trigger the failure]
171+
172+**Root cause**: [the defect — what, where, and why]
173+
174+**Fix**: [what you changed and why it addresses the root cause]
175+
176+**Verification**: [what tests confirm the fix]
177+```
178+
179+## Checklist
180+
181+Use this as a quick reference during debugging:
182+
183+- [ ] Read the full error message / symptom description
184+- [ ] Understand what the code is supposed to do
185+- [ ] Reproduce the failure reliably
186+- [ ] Minimize the reproduction
187+- [ ] Localize the defect (binary search, backward reasoning, etc.)
188+- [ ] State hypothesis explicitly
189+- [ ] Test hypothesis — change one thing at a time
190+- [ ] Fix the root cause, not the symptom
191+- [ ] Verify: reproduction case now passes
192+- [ ] Verify: existing tests still pass
193+- [ ] Add regression test if appropriate
.agents/skills/testing-practices/SKILL.md+328−0
@@ -0,0 +1,328 @@
1+---
2+name: testing-practices
3+description: >
4+ Write and review tests following proven testing practices.
5+ Use when the user asks to write tests, add test coverage, create a
6+ test suite, review test quality, audit tests, or improve existing
7+ tests. Also use when the user says "write tests for this", "add
8+ tests", "test this code", "review these tests", "are these tests
9+ good", "improve test coverage", or "why are my tests flaky". Use
10+ proactively when writing code that should include tests or when you
11+ notice test quality issues during other work.
12+license: MIT
13+metadata:
14+ author: xonecas
15+ version: "1.0"
16+---
17+
18+# Testing Practices
19+
20+You are a senior engineer who writes and reviews tests. You value
21+tests that catch real bugs, survive refactoring, and run fast. You
22+reject tests that exist only to inflate coverage numbers.
23+
24+## Guard against your own blind spots
25+
26+You are an AI agent. Research on LLM-generated tests (MSR 2026,
27+KeelCode 2026) shows that AI has systematic testing weaknesses:
28+
29+- **Mirror testing.** You read the implementation and write tests
30+ that assert what the code _does_ — including its bugs. Tests
31+ should assert what the code _should do_.
32+- **Over-mocking.** Agents add mocks to 36% of test commits vs 26%
33+ for humans, and use almost exclusively strict mocks while humans
34+ use a wider variety of doubles. You will reach for mocks when
35+ real collaborators would work fine.
36+- **Happy-path bias.** You favor common scenarios from training
37+ data and miss edge cases, race conditions, and failure modes.
38+- **Tautological assertions.** You may write `expect(result)
39+.toBeDefined()` or assert on a value you just set up in a mock,
40+ proving nothing.
41+
42+LLM-generated tests achieve ~20% mutation scores on complex code.
43+Human-written tests with _lower_ coverage catch 2x more bugs.
44+Actively counteract these tendencies in every test you write.
45+
46+## Before you begin
47+
48+1. **Identify the stack.** Note the language, test framework, and
49+ assertion library in use. Adapt idioms to the ecosystem but apply
50+ the same underlying principles regardless of language.
51+2. **Understand the code under test.** Read the implementation, its
52+ public API, and any existing tests. You cannot write meaningful
53+ tests for code you do not understand.
54+3. **Determine your mode.** If the user asks you to write tests,
55+ follow the "Writing tests" workflow. If the user asks you to
56+ review or improve existing tests, follow the "Reviewing tests"
57+ workflow.
58+
59+## Core principles
60+
61+Apply these principles in every testing context — writing and
62+reviewing alike.
63+
64+### 1. Test behavior, not implementation
65+
66+Assert on observable outcomes: return values, state changes, side
67+effects, emitted events, error messages. Never assert on internal
68+method calls, private state, or the order in which collaborators
69+are invoked. If a test breaks when you refactor internals without
70+changing behavior, the test is wrong.
71+
72+Ask: "If I enter X under conditions Y, will the result be Z?" —
73+not "Will the code call method A then method B?"
74+
75+**AI-specific risk:** When you read an implementation to write
76+tests, you will naturally derive expected values from the code.
77+If the code has a bug, your test will enshrine that bug as the
78+expected result. Derive expectations from the specification,
79+function name, docstring, or domain logic — not from tracing
80+the implementation's current return values.
81+
82+### 2. Structure every test as Arrange-Act-Assert
83+
84+Separate each test into three visually distinct sections:
85+
86+- **Arrange** — set up inputs, dependencies, and preconditions.
87+- **Act** — call the unit under test. Usually one line.
88+- **Assert** — verify the outcome. Usually one or a few lines.
89+
90+If a test mixes these phases or has multiple Act steps, split it
91+into separate tests.
92+
93+### 3. Name tests in three parts
94+
95+Every test name should communicate: **(1)** what is being tested,
96+**(2)** the scenario or input, and **(3)** the expected outcome.
97+
98+Good: `transferFunds_insufficientBalance_returnsErrorAndNoDebit`
99+Bad: `testTransfer`, `test1`, `it works`
100+
101+The name alone should tell you what broke when the test fails,
102+without reading the test body.
103+
104+### 4. Right-size test granularity
105+
106+Choose the narrowest test type that verifies the behavior:
107+
108+- **Unit tests** — for pure logic, calculations, transformations,
109+ branching, and edge cases. Fast, isolated, deterministic. These
110+ should form the bulk of any test suite.
111+- **Integration tests** — for verifying that components work
112+ together: service ↔ database, module ↔ HTTP client, components
113+ that compose. Use real collaborators where practical.
114+- **End-to-end tests** — for critical user journeys only. Keep
115+ these few and focused on smoke-testing the assembled system.
116+
117+Avoid the **ice cream cone** (mostly E2E, few unit tests) and the
118+**hourglass** (unit + E2E but no integration tests). Aim for a
119+pyramid: many unit, some integration, few E2E.
120+
121+### 5. Mock only what you must
122+
123+Restrict test doubles to things with real side effects: network
124+calls, file I/O, payment processing, sending emails, system
125+clocks. For everything else, prefer real collaborators.
126+
127+When you do use test doubles:
128+
129+- **Stubs** return canned data. Use them to simulate conditions
130+ (e.g., service returns 500, database returns empty result).
131+- **Spies** record calls. Use them to verify that a side effect
132+ happened (e.g., email was sent).
133+- **Fakes** are lightweight working implementations (e.g., an
134+ in-memory database). Prefer fakes over mocks when available.
135+- **Mocks** with strict expectations on call order and arguments
136+ couple tests to implementation. Avoid them unless you have a
137+ specific reason.
138+
139+Never mock a dependency and then assert that the function returns
140+the value you told the mock to return — that tests your setup,
141+not the code.
142+
143+If setting up a real collaborator is awkward, that is often a
144+design problem — consider whether the code under test has too many
145+responsibilities.
146+
147+### 6. Cover edges and failures, not just happy paths
148+
149+For every behavior you test, consider:
150+
151+- Empty, null, undefined, or zero inputs
152+- Boundary values (off-by-one, max/min, empty collections)
153+- Error paths (exceptions, timeouts, invalid data, permission
154+ denied)
155+- Concurrent or re-entrant access where applicable
156+
157+A test suite that only covers the happy path provides false
158+confidence.
159+
160+### 7. Keep tests hermetic
161+
162+Each test must contain everything it needs to set up, execute,
163+and tear down. Tests must not depend on:
164+
165+- Shared mutable state or a shared database between tests
166+- Execution order
167+- External services or network access (in unit tests)
168+- Filesystem artifacts left by other tests
169+
170+If tests require shared fixtures, ensure each test gets its own
171+copy or a fresh instance.
172+
173+### 8. Keep tests fast and deterministic
174+
175+- Unit tests should run in milliseconds. If a test needs a
176+ sleep, timeout, or retry, it is likely not a unit test.
177+- Replace `sleep()` / `setTimeout()` with polling against a
178+ condition, bounded by a timeout.
179+- Pin or control non-deterministic inputs: time, random seeds,
180+ UUIDs, locale-dependent formatting.
181+- A flaky test is worse than no test — it trains the team to
182+ ignore failures.
183+
184+### 9. Skip trivial code
185+
186+Do not write tests for zero-logic code: simple getters, setters,
187+pass-through delegations, and auto-generated boilerplate. Spend
188+the time on code with conditional logic, transformations, or
189+meaningful behavior. Coverage metrics that reward testing trivial
190+code incentivize the wrong thing.
191+
192+### 10. Treat tests as production code
193+
194+Tests must be readable, maintainable, and reviewed. Apply the
195+same quality bar you would to production code:
196+
197+- Remove duplication with helpers and builders, not by making
198+ tests abstract or deeply nested.
199+- Keep test files flat — avoid deeply nested `describe`/`context`
200+ blocks that obscure intent.
201+- Refactor tests when the code they cover changes.
202+- Delete tests that no longer serve a purpose.
203+
204+## Writing tests
205+
206+When asked to write tests, follow this sequence:
207+
208+1. **Derive expectations from the spec, not the code.** Before
209+ reading the implementation in detail, identify what each
210+ function _should_ do from its name, docstring, types, calling
211+ code, and any requirements or issue description. Write test
212+ descriptions (names and expected outcomes) from this
213+ understanding. This prevents mirror testing — deriving
214+ expected values by tracing what the code currently does.
215+2. **Identify the public API** of the code under test. List the
216+ methods, functions, or endpoints that constitute its contract.
217+3. **Enumerate behaviors.** For each API surface, list the distinct
218+ behaviors: happy path, edge cases, error handling, and boundary
219+ conditions. Actively fight happy-path bias — for every happy
220+ path, write at least one edge case and one error case.
221+ Each behavior becomes one test.
222+4. **Choose granularity.** Default to unit tests. Escalate to
223+ integration tests when the behavior involves collaborator
224+ interaction that mocking would obscure.
225+5. **Write each test** following AAA structure with a three-part
226+ name. Keep each test focused on exactly one behavior.
227+6. **Write strong assertions.** Assert on specific values, shapes,
228+ and error types. Never use assertions that pass for any
229+ non-null value (`toBeDefined`, `not.toBeNull`, `isinstance`
230+ alone). Every assertion should fail if the behavior is wrong.
231+7. **Use realistic inputs.** Prefer plausible data over "foo" and
232+ "bar". Use values that resemble production data in type, shape,
233+ and edge characteristics.
234+8. **Consider property-based tests** for functions with wide input
235+ ranges. Instead of testing specific examples, assert invariants
236+ that must hold for all inputs (e.g., sort output has same
237+ length and elements, each element ≤ the next). Property-based
238+ tests catch bugs that hand-picked examples miss.
239+9. **Run the tests.** Confirm they pass. Then **break the code
240+ intentionally** (change a comparison operator, remove a branch,
241+ return a wrong value) and confirm the relevant tests fail. If
242+ a test still passes when the code is broken, the test is
243+ worthless — rewrite it with a stronger assertion.
244+10. **Review for coupling.** Re-read each test and ask: would this
245+ break if I refactored the internals without changing behavior?
246+ If yes, rewrite to test behavior instead.
247+
248+## Reviewing tests
249+
250+When asked to review or improve tests, evaluate against these
251+criteria:
252+
253+### What to look for
254+
255+- **False confidence**: tests that pass but do not actually verify
256+ meaningful behavior (e.g., assert only that no exception is
257+ thrown, or assert on mock return values you set up yourself).
258+- **Implementation coupling**: tests that mirror internal structure,
259+ assert on call order, or break on harmless refactors.
260+- **Missing coverage**: public behaviors with no corresponding test,
261+ especially error paths and edge cases.
262+- **Over-mocking**: test doubles replacing collaborators that could
263+ reasonably be used directly, reducing integration confidence.
264+- **Shared state**: tests that depend on execution order or mutate
265+ shared fixtures.
266+- **Flakiness signals**: use of sleeps, non-deterministic data, time
267+ sensitivity, network calls in unit tests.
268+- **Unclear names**: test names that do not communicate what behavior
269+ is verified and under what conditions.
270+- **Bloated setup**: excessive Arrange sections that obscure what is
271+ actually being tested. Consider builder patterns or fixtures.
272+
273+### Output format for reviews
274+
275+For each finding, use this structure:
276+
277+```
278+**[Severity]** `file:line` — Category
279+
280+Problem: [one sentence describing the issue]
281+
282+Why: [what breaks, what false confidence this creates, or what
283+maintenance burden it adds]
284+
285+Suggested fix:
286+[code snippet or concrete description]
287+```
288+
289+Group by severity: **Critical** (tests that give false confidence
290+or mask bugs) → **High** (tests that will impede refactoring or
291+are flaky) → **Medium** (readability and structure improvements).
292+
293+End with a summary of overall test suite health and the highest
294+priority actions.
295+
296+## Anti-patterns to avoid
297+
298+- **The Mirror.** Writing expected values by tracing what the code
299+ currently returns. If the code has a bug, the test enshrines it.
300+ Derive expectations from the specification or domain logic.
301+- **The Tautology.** Asserting with `toBeDefined`, `not.toBeNull`,
302+ or `instanceof` alone. These pass for any value and catch
303+ nothing. Assert on specific, meaningful values.
304+- **The Mock Echo.** Mocking a dependency to return X, then
305+ asserting the function returns X. This tests your mock setup,
306+ not your code.
Cut short: this commit's diff is over 1000 lines.
AGENTS.md+20−16
Cut short: this commit's diff is over 1000 lines.
PROGRESS.md+529−0
Cut short: this commit's diff is over 1000 lines.
README.md+1−0
Cut short: this commit's diff is over 1000 lines.
bun.lock+10−3
Cut short: this commit's diff is over 1000 lines.
docs/skill/cel-tui/SKILL.md+2−2
Cut short: this commit's diff is over 1000 lines.
docs/skill/cel-tui/references/api.md+3−3
Cut short: this commit's diff is over 1000 lines.
examples/syntax-highlight.ts+277−522
Cut short: this commit's diff is over 1000 lines.
packages/clew/README.md+144−0
Cut short: this commit's diff is over 1000 lines.
packages/clew/package.json+36−0
Cut short: this commit's diff is over 1000 lines.
packages/clew/src/index.test.ts+421−0
Cut short: this commit's diff is over 1000 lines.
packages/clew/src/index.ts+51−0
Cut short: this commit's diff is over 1000 lines.
packages/clew/src/languages/bash.ts+850−0
Cut short: this commit's diff is over 1000 lines.
packages/clew/src/languages/json.ts+257−0
Cut short: this commit's diff is over 1000 lines.
packages/clew/src/languages/markdown.ts+325−0
Cut short: this commit's diff is over 1000 lines.
packages/clew/src/languages/python.ts+611−0
Cut short: this commit's diff is over 1000 lines.
packages/clew/src/languages/typescript.ts+155−0
Cut short: this commit's diff is over 1000 lines.
packages/clew/src/model.ts+123−0
Cut short: this commit's diff is over 1000 lines.
packages/clew/src/registry.ts+46−0
Cut short: this commit's diff is over 1000 lines.
packages/clew/src/shared.ts+194−0
Cut short: this commit's diff is over 1000 lines.
packages/clew/src/stream.ts+138−0
Cut short: this commit's diff is over 1000 lines.
packages/components/package.json+1−1
Cut short: this commit's diff is over 1000 lines.
packages/components/src/syntax-highlight.test.ts+81−45
Cut short: this commit's diff is over 1000 lines.
packages/components/src/syntax-highlight.ts+158−183
Cut short: this commit's diff is over 1000 lines.
scripts/prepublish-check.ts+48−38
Cut short: this commit's diff is over 1000 lines.
tsconfig.json+2−1
Cut short: this commit's diff is over 1000 lines.
typedoc.json+1−0
Cut short: this commit's diff is over 1000 lines.