@ia-ccun/code-agent-cli 0.0.52 → 0.0.53-beta.2

package/config/agent/skills/ponytail-debt/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ponytail-debt
+description: >
+  Harvest every `ponytail:` comment in the codebase into a debt ledger, so the
+  deliberate shortcuts and deferrals ponytail leaves behind get tracked instead
+  of rotting into "later means never". Use when the user says "ponytail debt",
+  "/ponytail-debt", "what did ponytail defer", "list the shortcuts", "ponytail
+  ledger", or "what did we mark to do later". One-shot report, changes nothing.
+---
+
+Every deliberate ponytail shortcut is marked with a `ponytail:` comment naming
+its ceiling and upgrade path. This collects them into one ledger so a deferral
+can't quietly become permanent.
+
+## Scan
+
+Grep the repo for comment markers, skipping `node_modules`, `.git`, and build
+output:
+
+`grep -rnE '(#|//) ?ponytail:' .`  (add other comment prefixes if your stack uses them)
+
+Each hit is one ledger row. The comment prefix keeps prose that merely mentions
+the convention out of the ledger.
+
+## Output
+
+One row per marker, grouped by file:
+
+`<file>:<line> — <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.`
+
+The convention is `ponytail: <ceiling>, <upgrade path>`, so pull the ceiling
+and the trigger straight from the comment. Want an owner per row too? add
+`git blame -L<line>,<line>`.
+
+Flag the rot risk: any `ponytail:` comment that names no upgrade path or
+trigger gets a `no-trigger` tag, those are the ones that silently rot.
+
+End with `<N> markers, <M> with no trigger.` Nothing found: `No ponytail: debt. Clean ledger.`
+
+## Boundaries
+
+Reads and reports only, changes nothing. To persist it, ask and it writes the
+ledger to a file (e.g. `PONYTAIL-DEBT.md`). One-shot. "stop ponytail-debt" or
+"normal mode" to revert.

package/config/agent/skills/ponytail-help/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: ponytail-help
+description: >
+  Quick-reference card for all ponytail modes, skills, and commands.
+  One-shot display, not a persistent mode. Trigger: /ponytail-help,
+  "ponytail help", "what ponytail commands", "how do I use ponytail".
+---
+
+# Ponytail Help
+
+Display this reference card when invoked. One-shot, do NOT change mode,
+write flag files, or persist anything.
+
+## Levels
+
+| Level | Trigger | What change |
+|-------|---------|-------------|
+| **Lite** | `/ponytail lite` | Build what's asked, name the lazier alternative in one line. |
+| **Full** | `/ponytail` | The ladder enforced: YAGNI → stdlib → native → one line → minimum. Default. |
+| **Ultra** | `/ponytail ultra` | YAGNI extremist. Deletion before addition. Challenges requirements before building. |
+
+Level sticks until changed or session end.
+
+## Skills
+
+| Skill | Trigger | What it does |
+|-------|---------|--------------|
+| **ponytail** | `/ponytail` | Lazy mode itself. Simplest solution that works. |
+| **ponytail-review** | `/ponytail-review` | Over-engineering review: `L42: yagni: factory, one product. Inline.` |
+| **ponytail-help** | `/ponytail-help` | This card. |
+
+Codex uses `@ponytail`, `@ponytail-review`, and `@ponytail-help`; Claude Code
+and OpenCode use the slash-command forms above (OpenCode ships `/ponytail` and
+`/ponytail-review`).
+
+## Deactivate
+
+Say "stop ponytail" or "normal mode". Resume anytime with `/ponytail`.
+`/ponytail off` also works.
+
+## Configure Default Mode
+
+Default mode = `full`, auto-active every session. Change it:
+
+**Environment variable** (highest priority):
+```bash
+export PONYTAIL_DEFAULT_MODE=ultra
+```
+
+**Config file** (`~/.config/ponytail/config.json`, Windows: `%APPDATA%\ponytail\config.json`):
+```json
+{ "defaultMode": "lite" }
+```
+
+Set `"off"` to disable auto-activation on session start, activate manually
+with `/ponytail` when wanted.
+
+Resolution: env var > config file > `full`.
+
+## Update
+
+Enable auto-update once: open `/plugin`, go to Marketplaces, pick ponytail, Enable auto-update. Claude Code then pulls new versions at startup (run `/reload-plugins` when it prompts). Manual refresh: `/plugin marketplace update ponytail` then `/reload-plugins`.
+
+If `/plugin` is not recognized, your Claude Code is out of date. Update it (`npm install -g @anthropic-ai/claude-code@latest`, or `brew upgrade claude-code`) and restart. Other hosts use their own update flow.
+
+## More
+
+Full docs + examples: https://github.com/DietrichGebert/ponytail

package/config/agent/skills/ponytail-review/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: ponytail-review
+description: >
+  Code review focused exclusively on over-engineering. Finds what to delete:
+  reinvented standard library, unneeded dependencies, speculative abstractions,
+  dead flexibility. One line per finding: location, what to cut, what replaces
+  it. Use when the user says "review for over-engineering", "what can we
+  delete", "is this over-engineered", "simplify review", or invokes
+  /ponytail-review. Complements correctness-focused review, this one only
+  hunts complexity.
+---
+
+Review diffs for unnecessary complexity. One line per finding: location, what
+to cut, what replaces it. The diff's best outcome is getting shorter.
+
+## Format
+
+`L<line>: <tag> <what>. <replacement>.`, or `<file>:L<line>: ...` for
+multi-file diffs.
+
+Tags:
+
+- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
+- `stdlib:` hand-rolled thing the standard library ships. Name the function.
+- `native:` dependency or code doing what the platform already does. Name the feature.
+- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
+- `shrink:` same logic, fewer lines. Show the shorter form.
+
+## Examples
+
+❌ "This EmailValidator class might be more complex than necessary, have you
+considered whether all these validation rules are needed at this stage?"
+
+✅ `L12-38: stdlib: 27-line validator class. "@" in email, 1 line, real validation is the confirmation mail.`
+
+✅ `L4: native: moment.js imported for one format call. Intl.DateTimeFormat, 0 deps.`
+
+✅ `repo.py:L88: yagni: AbstractRepository with one implementation. Inline it until a second one exists.`
+
+✅ `L52-71: delete: retry wrapper around an idempotent local call. Nothing replaces it.`
+
+✅ `L30-44: shrink: manual loop builds dict. dict(zip(keys, values)), 1 line.`
+
+## Scoring
+
+End with the only metric that matters: `net: -<N> lines possible.`
+
+If there is nothing to cut, say `Lean already. Ship.` and stop.
+
+## Boundaries
+
+Complexity only, correctness bugs, security holes, and performance go to a
+normal review pass, not this one. A single smoke test or `assert`-based
+self-check is the ponytail minimum, not bloat, never flag it for deletion.
+Does not apply the fixes, only lists them.
+"stop ponytail-review" or "normal mode": revert to verbose review style.

package/config/agent/skills/zread/README.md

@@ -0,0 +1,115 @@
+# Zread Skill
+
+This repository contains a skill for `zread`, a CLI that generates wiki-style
+documentation for code repositories.
+
+The skill is meant for one job: help an agent understand an unfamiliar codebase
+through `zread` output instead of re-reading the entire repository file by file.
+
+## Installation
+
+### 1. Install the zread CLI
+
+Install `zread` first. There are two supported installation methods:
+
+```bash
+npm install -g zread_cli
+```
+
+or
+
+```bash
+brew tap ZreadAI/homebrew-tap
+brew install zread
+```
+
+Then verify the installation:
+
+```bash
+zread version
+```
+
+### 2. Install this skill
+
+Ask your AI agent to install the skill from GitHub:
+
+```text
+install this skill https://github.com/ZreadAI/zread-skill
+```
+
+If you prefer to install it manually, copy this directory into your local
+skills directory:
+
+| Agent       | Skills directory        |
+| ----------- | ----------------------- |
+| Claude Code | `~/.claude/skills/`   |
+| OpenClaw    | `~/.openclaw/skills/` |
+| Codex       | `~/.agents/skills/`   |
+
+Example:
+
+```bash
+cp -R zread ~/.claude/skills/zread
+```
+
+Your final layout should look like this:
+
+```text
+<skills-dir>/zread/
+  SKILL.md
+  README.md
+  references/
+    stdio-protocol.md
+```
+
+Once the folder is in place, an agent that supports `SKILL.md`-based skills can
+load and use it.
+
+## Features
+
+- Read existing `./.zread/wiki/` output instead of crawling source files again
+- Guide an agent to run `zread generate` safely when documentation does not
+  exist yet
+- Use `--stdio` as the default mode for agent automation, instead of parsing
+  the interactive TUI
+- Explain the role of `current`, `versions`, and `drafts` in zread output
+- Include a reference for the `zread --stdio` JSON-line protocol
+
+## When To Use
+
+Use this skill when you want to:
+
+- understand an unfamiliar repository quickly
+- read an existing zread-generated wiki
+- generate a repository overview or project wiki
+- serve docs locally with `zread browse`
+- drive `zread` programmatically from a script or agent
+
+## How It Works
+
+The skill follows a simple workflow:
+
+1. If `./.zread/wiki/current` exists, read the generated wiki files directly.
+2. If no wiki exists, run `zread generate` only when the user wants docs to be
+   generated.
+3. Before generation, confirm with the user because generation consumes LLM
+   tokens and writes under `./.zread/`.
+4. In automated workflows, use `--stdio`.
+
+## Repository Layout
+
+- `SKILL.md`: the skill definition, trigger conditions, and operating rules
+- `references/stdio-protocol.md`: the `zread --stdio` machine protocol
+- `appmap.log`: local artifact, not part of the skill itself
+
+## zread Output
+
+After a successful generation, zread typically writes:
+
+- `./.zread/wiki/current`: the active wiki version id
+- `./.zread/wiki/versions/<id>/wiki.json`: the generated page index
+- `./.zread/wiki/versions/<id>/<file>`: the actual markdown pages
+- `./.zread/wiki/drafts/`: unfinished generation state
+
+If you need to integrate with `zread` programmatically, see
+[references/stdio-protocol.md](./references/stdio-protocol.md).

package/config/agent/skills/zread/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: zread
+description: Produce and consume a wiki-style knowledge base for a code repository via the `zread` CLI and its on-disk output under `./.zread/wiki/`. Use this skill whenever the user wants to understand, onboard onto, explore, summarize, map, or get an overview of an unfamiliar codebase; asks for architecture docs, a project wiki, a repo walkthrough, module/package explanations, or "what does this repo do"; wants to generate, regenerate, resume, browse, or serve code documentation locally; or mentions zread / zread.ai directly. Also use it proactively before diving into a large unknown repo — if `./.zread/wiki/current` exists, read the generated pages instead of crawling source file-by-file; if it doesn't, consider offering to run `zread generate`. The trigger is the intent (understand a codebase through generated docs), not the literal word "zread".
+---
+
+# zread skill
+
+`zread` is a CLI that generates wiki documentation from code in the current
+workspace using an LLM. Output lives under `./.zread/wiki/` in the workspace;
+public repos can also be viewed at https://zread.ai.
+
+This skill is intended for agent use. Read generated files directly from disk,
+and use `--stdio` as the default mode for any zread command instead of trying
+to parse the human TUI.
+
+## On-disk layout (read these directly)
+
+Always run `zread` from the workspace root. After a successful generation:
+
+- `./.zread/wiki/current` — text file containing the active version id
+  (e.g. `2026-03-12-010203`).
+- `./.zread/wiki/versions/<id>/wiki.json` — TOC: `{id, generated_at, language,
+  pages: [{slug, title, file, section, group, level}]}`.
+- `./.zread/wiki/versions/<id>/<file>` — page markdown referenced by `pages[*].file`.
+- `./.zread/wiki/drafts/` — in-progress generation; presence means a previous
+  run did not finish. `drafts/wiki.json` exists once the catalog phase
+  completed.
+- `~/.zread/config.yaml` — global config (LLM provider, language, concurrency).
+- `~/.zread/login.json` — presence indicates the user has logged in.
+
+To answer questions about a codebase that already has zread output, read these
+files directly with the file tools — do not invoke `zread browse`.
+
+## Commands
+
+| Command | Purpose | Key flags |
+|---|---|---|
+| `zread generate` | Generate wiki for cwd | `-y/--yes`, `--draft resume\|clear\|cancel`, `--skip-failed`, `--stdio` |
+| `zread browse` | Serve docs at http://localhost:9681+ and open browser | `--generate`, `--version <id>`, `--host`, `--port`, `--stdio` |
+| `zread login` | OAuth into BigModel/Z.AI to obtain an API key | `--custom`, `--model`, `--stdio` |
+| `zread config` | Edit `~/.zread/config.yaml` | `--stdio` |
+| `zread update` | Self-update CLI | `--stdio` |
+| `zread version` | Print version | `--stdio` |
+
+`--stdio` is supported on every command and turns the process into a JSON-line
+machine protocol on stdin/stdout. See
+[references/stdio-protocol.md](./references/stdio-protocol.md) for the wire
+format (events, `waiting_for`, `done`, `quit`). Load it whenever zread is
+invoked from another program/agent.
+
+## Decision tree for an AI agent
+
+1. **User wants to read existing wiki content?**
+   - Check `./.zread/wiki/current`. If present, read `wiki.json` and the page
+     markdown directly. No CLI invocation needed.
+   - For known *public* GitHub repos, prefer the `mcp__zread__*` tools
+     (`get_repo_structure`, `read_file`, `search_doc`) over running the CLI.
+
+2. **User wants to (re)generate docs?**
+   - Confirm with the user first — `generate` is long-running, calls an LLM,
+     and writes files. Get explicit consent in unfamiliar directories.
+   - Verify `~/.zread/login.json` exists or `~/.zread/config.yaml` has an
+     `llm.api_key`. If neither, run `zread login` first.
+   - If `./.zread/wiki/drafts/` exists, decide:
+     - resume previous run → `zread generate --draft resume -y`
+     - throw away and start fresh → `zread generate --draft clear -y`
+   - Otherwise: `zread generate -y`.
+   - To not block on a few failing pages: add `--skip-failed`.
+
+3. **User wants to view docs in a browser?**
+   - `zread browse` (add `--generate` to bootstrap if no wiki exists yet).
+
+4. **User wants to script zread / consume output programmatically?**
+   - Use `--stdio` and follow stdio-protocol.md. Do not screen-scrape the TUI.
+
+## Non-interactive invocation rules
+
+- Always pass `-y` to `generate` when running unattended; otherwise it stops
+  at a catalog confirmation gate.
+- Always set `--draft` explicitly when a draft may exist, so the command does
+  not prompt.
+- For any command run from another agent/script, use `--stdio` so output is
+  parseable JSON instead of ANSI TUI frames.
+- `zread` writes logs to `~/.zread/log/zread.log` — read this if a run fails
+  silently.
+
+## Safety / blast radius
+
+- `generate` consumes LLM tokens (real cost) and can run for many minutes on
+  large repos. Confirm before launching.
+- `generate` writes only under `./.zread/` and does not commit anything to
+  git. It is safe to delete `./.zread/wiki/drafts/` to recover from a stuck
+  state.
+- `update` replaces the zread binary in place and is hard to reverse — only
+  run it when the user explicitly asks.
+- `login` opens a browser for OAuth; do not run it in a non-interactive
+  context unless the user has asked for it.
+
+## Reference files
+
+- [references/stdio-protocol.md](./references/stdio-protocol.md) — JSON-line
+  wire protocol shared by every command's `--stdio` mode. Load when
+  programmatically driving zread.