WP-0001: feedback channels, CI, pre-commit, telemetry docs
Some checks failed
ci / test (3.12) (push) Has been cancelled
ci / test (3.10) (push) Has been cancelled

Add kaizen-agentic feedback CLI, Gitea issue templates, CI workflow,
pre-commit hooks, FEEDBACK/TELEMETRY docs, and cross-platform path tests.
Improve CLI registry error messages; remove agents_backup scaffolding.
Apply black formatting across src/tests for CI consistency.

State Hub message sent to agentic-resources for Helix correlation doc link.
This commit is contained in:
2026-06-16 01:58:07 +02:00
parent 79883aa25b
commit 80c60ebd7a
30 changed files with 556 additions and 110 deletions

41
docs/FEEDBACK.md Normal file
View File

@@ -0,0 +1,41 @@
# Feedback
How to share bugs, ideas, and adoption experience for kaizen-agentic.
## Quick channels
| Channel | Use for |
|---------|---------|
| **Gitea Issues** | Bugs, features, general feedback (templates below) |
| **`kaizen-agentic feedback`** | Print links and template guidance from the CLI |
| **Pull requests** | Code and agent-definition contributions (see CONTRIBUTING.md) |
| **State Hub messages** | Cross-repo coordination between custodian agents (advanced) |
## Gitea issue templates
Choose a template when opening a new issue:
- **Bug report** — reproducible defects
- **Feature request** — enhancements with proposed scope
- **General feedback** — experience and adoption notes
Repository: [coulomb/kaizen-agentic](https://gitea.coulomb.social/coulomb/kaizen-agentic/issues)
## CLI
```bash
kaizen-agentic feedback # human-readable channel list
kaizen-agentic feedback --json # machine-readable for tooling
```
## What helps us most
- Python version and `kaizen-agentic --version`
- Minimal reproduction steps for bugs
- Which agents you used and whether memory/metrics were enabled
- For integration issues: whether artifact-store, Helix Forge, or activity-core is involved
## Privacy
Do not include secrets, tokens, or private project content in public issues. Redact
`.kaizen/` memory contents unless you intentionally share sanitized examples.

48
docs/TELEMETRY.md Normal file
View File

@@ -0,0 +1,48 @@
# Telemetry and Agent Effectiveness Tracking
WP-0001 T04 design — aligned with ADR-004 and WP-0004 ecosystem integration.
## Two layers (do not merge)
| Layer | Question | Mechanism |
|-------|----------|-----------|
| **Project** | How is agent *X* performing in *this repo*? | `kaizen-agentic metrics record``.kaizen/metrics/` |
| **Fleet** | How are coding sessions performing *across repos*? | agentic-resources Helix Forge |
kaizen-agentic **does not** ship a parallel session transcript ingestion pipeline.
## Project telemetry (implemented)
Memory-enabled agents record per-session outcomes at close:
```bash
kaizen-agentic metrics record <agent> --success --time <s> --quality <0-1>
kaizen-agentic metrics optimize [agent]
kaizen-agentic memory brief <agent> # includes Performance Summary
```
Optional fleet correlation via `HELIX_SESSION_UID` (see
[integrations/helix-forge-correlation.md](integrations/helix-forge-correlation.md)).
## Fleet telemetry (agentic-resources)
Helix Forge owns session capture, digest storage, baselines, and weekly retro.
kaizen-agentic consumes correlation fields only.
## CLI install / usage analytics (future)
Potential v1.1 additions (not yet implemented):
- Opt-in anonymous counters on `install` / `memory init` (no PII, no project paths)
- Aggregate effectiveness reports via `metrics list` across a monorepo checkout
## tele-mcp evaluation (deferred)
[tele-mcp](https://gitea.coulomb.social/coulomb/tele-mcp) is a candidate MCP adapter
for IDE-level telemetry (WP-0001 note). Assess before depending on it. Project and
fleet layers above satisfy INTENT's "measurable agents" requirement without tele-mcp.
## Feedback loop
User experience feedback uses [FEEDBACK.md](FEEDBACK.md) and Gitea issue templates —
separate from execution metrics.