microduck-cli 0.7.0__tar.gz → 0.8.0__tar.gz

{microduck_cli-0.7.0 → microduck_cli-0.8.0}/.claude/skills/cicd/SKILL.md

@@ -163,14 +163,16 @@ only when the user explicitly asks for one of them.
 
 For every comment, decide **FIX** or **PUSHBACK** with reasoning.
 
-Default to **FIX** for: portability complaints (always valid for
-Steward — recurring bug class), test or doc requests, style nits
+Default to **FIX** for: portability complaints (a recurring bug
+class across AgentCulture repos), test or doc requests, style nits
 aligned with workspace conventions.
 
 Default to **PUSHBACK** for: architecture opinions that conflict with
-workspace `CLAUDE.md` or the all-backends rule; greenfield
-false-positives (e.g. "add tests" before there's any source — defer
-to a later PR, don't refuse).
+`CLAUDE.md` or the all-backends rule; scaffold false-positives — this
+repo has no MicroDuck control code yet, so "this CLI doesn't do
+anything with the robot" is a roadmap item, not a PR defect. Anything
+proposing a second runtime loop in `microduck_cli/` is a PUSHBACK too:
+that code belongs upstream in `neurosymbolic-system` (see `CLAUDE.md`).
 
 ### Alignment-delta rule
 
@@ -179,18 +181,29 @@ If the PR touches `CLAUDE.md`, `culture.yaml`, or anything under
 PUSHBACK on each comment. Note any sibling that needs a follow-up PR
 and mention it in your reply.
 
-## Greenfield-aware steps
+## Pre-PR steps (microduck-cli)
 
-The lint and the workflow script are always-on. Stack-specific steps
-are conditional and currently no-op (greenfield repo):
+**Consumer adaptation** — upstream ships this section as conditional
+"greenfield-aware" no-ops. microduck-cli's stack has landed, so the steps
+below are unconditional here; run all of them before `workflow.sh open`.
+Recorded as a tracked divergence in `docs/skill-sources.md`.
 
 ```bash
-[ -d tests ] && [ -f pyproject.toml ] && uv run pytest tests/ -x -q
-[ -f pyproject.toml ] && bump_version_per_project_convention   # see project README
-[ -f .markdownlint-cli2.yaml ] && markdownlint-cli2 "$(git diff --name-only --cached '*.md')"
+uv run pytest -n auto                                # full suite must be green
+uv run black --check microduck_cli tests             # the CI lint job, locally
+uv run isort --check-only microduck_cli tests
+uv run flake8 microduck_cli tests
+uv run bandit -c pyproject.toml -r microduck_cli
+uv run teken cli doctor . --strict                   # the agent-first rubric gate
+markdownlint-cli2 "**/*.md" "#node_modules" "#.local" "#.claude/skills" "#.teken"
+/version-bump patch|minor|major                      # REQUIRED on every PR
 ```
 
-Revisit each line as the corresponding stack element actually lands.
+The version bump is not optional: the `version-check` job compares
+`pyproject.toml` against `origin/main` and fails the PR when they match — even
+for docs/config/CI-only changes. Use the `version-bump` skill so `CHANGELOG.md`
+gets its Keep-a-Changelog entry in the same pass.
+
 A `pr lint --extra=tests,version,markdown` ask is filed upstream
 ([devex#41](https://github.com/agentculture/devex/issues/41)).
 
@@ -203,6 +216,9 @@ in the fix-up commit message.
 The `status` extension queries SonarCloud directly (it predates the
 upstream Sonar integration in `devex pr read`). Both surfaces are
 trustworthy — `devex pr read` for display in the briefing, `status` for
-the gate. Steward isn't yet a registered mesh agent, so the
+the gate. microduck-cli isn't yet a registered mesh agent, so the
 post-merge IRC ping that Culture's `pr-review` includes is still
-skipped — that returns when Steward joins the mesh.
+skipped — that returns when microduck-cli joins the mesh. (Until then,
+a cross-repo follow-up — e.g. a runtime gap that belongs to
+`neurosymbolic-system` — goes out as a tracked issue via the
+`communicate` skill.)

{microduck_cli-0.7.0 → microduck_cli-0.8.0}/.claude/skills.local.yaml.example

@@ -14,3 +14,8 @@ sibling_projects:
   - ../guildmaster
   - ../steward
   - ../teken
+  # Robot-family siblings — the architecture microduck-cli composes.
+  # See CLAUDE.md "The three sibling repos, and what to take from each".
+  - ../neurosymbolic-system
+  - ../reachy-mini-cli
+  - ../arm101-cli

{microduck_cli-0.7.0 → microduck_cli-0.8.0}/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-08-29
+
+### Changed
+
+- **`CLAUDE.md` re-initialized from the seed into a real runtime prompt** (`/init`).
+  Replaces the self-initializing placeholder with: what the repo actually is today
+  (the mesh-agent scaffold — **no MicroDuck control code exists yet**), the
+  `microduck` vs `microduck-cli` console-script gotcha, the common command + lint
+  stack, the agent-first CLI contracts (registration, error, output, explain
+  catalog, identity/`doctor`) and the rubric shapes that must not be "simplified"
+  away, hard constraints, CI/release, the vendored-skill rule, and the workflow
+  conventions (worktrees in `../.worktrees.microduck-cli/`, in-repo public eidetic
+  memory, PR flow).
+- **A "three sibling repos" section** naming what to take from each and what not
+  to: `neurosymbolic-system` is the runtime to **import** — but it is itself still
+  a bare scaffold, so it is not a dependency yet and a tick loop must never be
+  re-implemented here; `reachy-mini-cli` is the architecture (noun groups, one tick
+  seam, single-SDK-owner model); `arm101-cli` is the hardware-safety baseline
+  (gated motion, release-on-abnormal-exit, hardware deps behind an extra).
+- **README rewritten** — a `Status: scaffold` section stating plainly that no duck
+  control code ships yet, a corrected quickstart (`uv run microduck …`; the old
+  `uv run microduck-cli …` line failed with "Failed to spawn"), a sibling-projects
+  table, and the removal of the template's "Make it your own" rename instructions.
+- **`cicd` skill adapted to this repo's landed stack** — the upstream
+  "Greenfield-aware steps" no-ops become unconditional "Pre-PR steps
+  (microduck-cli)", the triage defaults name this repo's real false-positive class
+  (scaffold complaints; a second runtime loop that belongs in
+  `neurosymbolic-system`), and the mesh-ping paragraph names microduck-cli.
+  `SKILL.md` prose only — no script bodies touched — and recorded as a tracked
+  divergence in `docs/skill-sources.md`.
+- **`.claude/skills.local.yaml.example`** lists the three robot-family siblings
+  under `sibling_projects`, so `cicd`'s alignment-delta step sees them.
+
 ## [0.7.0] - 2026-08-24
 
 ### Added

microduck_cli-0.8.0/CLAUDE.md

@@ -0,0 +1,273 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo actually is right now
+
+`microduck-cli` is an **AgentCulture mesh agent** whose destination is
+*controlling the MicroDuck robot — one CLI that any agent or human drives*
+(`culture.yaml`, [README](README.md)).
+
+**No MicroDuck control code exists yet.** What is on disk is the mesh-agent
+scaffold cloned from `culture-agent-template` (`git log` is two commits: the
+initial commit and the scaffold): an agent-first introspection CLI (`whoami`,
+`learn`, `explain`, `overview`, `doctor`, `cli`), a mesh identity, the vendored
+guildmaster skill kit, and a build/CI/deploy baseline. Treat that CLI as the
+chassis you extend, and the three sibling repos below as the architecture you
+extend it *toward*.
+
+Two things to internalize before touching anything:
+
+- **The runtime agent prompt is `AGENTS.colleague.md`, not this file.**
+  `culture.yaml` declares `backend: colleague`, and the backend→prompt-file map
+  (see `doctor`) resolves `colleague` → `AGENTS.colleague.md`. This `CLAUDE.md`
+  is guidance for *Claude Code working in the repo*; editing it does not change
+  the mesh agent's runtime behavior.
+- **The installed console script is `microduck`, not `microduck-cli`.**
+  `[project.scripts]` defines `microduck = "microduck_cli.cli:main"`, so
+  `uv run microduck-cli whoami` fails with "Failed to spawn." Use `uv run
+  microduck …` or `python -m microduck_cli …`. The *internal* prog name is
+  `microduck-cli`, so `--help` text, error messages, `learn`/`explain` bodies and
+  JSON payloads all say `microduck-cli` — that string is intentional in output,
+  just not as the binary. (Same half-rename `arm101-cli` carries; `reachy-mini-cli`
+  resolved its by shipping *both* console scripts. Either fix is fine — do it as
+  one deliberate pass across `pyproject.toml`, `prog=`, `_commands/`,
+  `explain/catalog.py`, the README and the test assertions, never piecemeal.)
+
+## Common commands
+
+```bash
+uv sync                                              # create .venv, install runtime + dev deps
+uv run microduck whoami                              # run the CLI (note: 'microduck')
+uv run pytest -n auto                                # full suite (xdist parallel)
+uv run pytest tests/test_cli.py::test_whoami_text    # a single test
+uv run pytest -n auto --cov=microduck_cli --cov-report=term   # coverage (CI gate: fail_under=60)
+uv run teken cli doctor . --strict                   # the agent-first rubric gate CI enforces
+```
+
+Lint stack (the CI `lint` job runs all of these; line length is 100 everywhere):
+
+```bash
+uv run black --check microduck_cli tests
+uv run isort --check-only microduck_cli tests
+uv run flake8 microduck_cli tests
+uv run bandit -c pyproject.toml -r microduck_cli     # B101/B404/B603 skipped in pyproject
+markdownlint-cli2 "**/*.md" "#node_modules" "#.local" "#.claude/skills" "#.teken"
+```
+
+## Architecture: the agent-first CLI
+
+Everything routes through `microduck_cli/cli/__init__.py:main()` → `_build_parser()`.
+Three cross-cutting contracts are enforced by tests and by the rubric gate.
+
+- **Adding a verb.** Write `cli/_commands/<verb>.py` exposing `register(sub)`
+  (add `--json`, `set_defaults(func=…)`), then add one import + call inside
+  `_build_parser()`. That is the only wiring step; `whoami.py` is the canonical
+  example. For a **noun group** (a subcommand with its own verbs — how duck
+  control will land, e.g. `microduck duck walk`), mirror `_commands/cli.py`:
+  build the child subparsers with `parser_class=type(p)` so nested parse errors
+  keep the structured error contract instead of argparse's default exit-2. A noun
+  with action-verbs must also expose its own `overview` (rubric requirement).
+- **Error contract** (`cli/_errors.py` + `_dispatch`/`_CliArgumentParser`).
+  Every failure raises `CliError(code, message, remediation)`; `_dispatch` catches
+  it and wraps *any* other exception, so no Python traceback ever leaks. Argparse
+  errors route through `_CliArgumentParser.error()` too — and because parse errors
+  fire before `args.json` exists, `main()` pre-scans raw argv for `--json` into the
+  class-level `_json_hint`. **Handlers raise `CliError` — never `sys.exit`, never
+  print-and-return.** Text errors are always two lines: `error: …` then `hint: …`
+  (the `hint:` prefix is rubric-required).
+- **Output contract** (`cli/_output.py`). Results → stdout, errors and diagnostics
+  → stderr, **never mixed**, in text and JSON mode alike. Use `emit_result` /
+  `emit_error` / `emit_diagnostic`, not `print`. Exit codes: `0` success, `1`
+  user-input error, `2` environment error, `3+` reserved (constants in `_errors.py`).
+- **The explain catalog** (`microduck_cli/explain/catalog.py`). `ENTRIES` is keyed
+  by command-path tuples (`("whoami",)`, `("cli","overview")`; `()`,
+  `("microduck-cli",)` and `("microduck",)` all resolve to root).
+  `test_every_catalog_path_resolves` asserts each *existing* entry renders, but
+  nothing forces a *new* verb to have one — so adding a verb means updating
+  **three places in lockstep** or the docs silently drift: the catalog entry, the
+  `_VERBS` list in `overview.py`, and the `_TEXT` + `_as_json_payload` blocks in
+  `learn.py`.
+- **Identity** (`_commands/whoami.py`). `culture.yaml` is hand-parsed line by line
+  (no YAML dependency, to keep runtime deps empty) — only the documented flat
+  `suffix`/`backend`/`model` shape is understood. `find_culture_yaml()` walks up
+  from `__file__`, so identity is the agent's own even when invoked elsewhere; a
+  wheel install (no `culture.yaml` beside the package) falls back to literal
+  defaults and `doctor` reports a single info check.
+
+### The agent-first rubric (why some code looks odd)
+
+`teken cli doctor . --strict` gates CI on a seven-bundle rubric. Several shapes
+exist only to satisfy it — don't "simplify" them away:
+
+- `learn` must be ≥200 chars and mention purpose, command map, exit codes,
+  `--json`, and `explain`.
+- Any noun with action-verbs must also expose `overview` — the entire reason the
+  `cli` noun group exists (`cli overview` describes the CLI; the global `overview`
+  describes the *agent*).
+- Descriptive verbs must never hard-fail on a bad path — hence `overview` takes an
+  ignored positional `target` and still exits 0.
+
+Separate from the in-package `microduck doctor`, which checks **agent-identity
+invariants**: `prompt-file-present`, `backend-consistency` (`claude`→`CLAUDE.md`,
+`colleague`→`AGENTS.colleague.md`, `acp`→`AGENTS.md`, `gemini`→`GEMINI.md`), and
+`skills-present`. Change the backend in `culture.yaml` and you must teach `doctor`
+the matching prompt file.
+
+## The three sibling repos, and what to take from each
+
+The duck domain is meant to be built by *composing* these, not by inventing a
+fourth architecture. Read the named file before you start the corresponding work.
+
+### `../neurosymbolic-system` — the intended runtime (not usable yet)
+
+The description says microduck-cli is "built on the neurosymbolic-system runtime":
+senses, rules, arbitration and motion composed onto one 50 Hz tick, extracted from
+reachy-mini-cli and imported as a library by robot CLIs. **That library does not
+exist yet.** `neurosymbolic-system` 0.7.0 is the *same* bare template scaffold this
+repo is — `neurosymbolic_system/` contains only `cli/` and `explain/`, no runtime
+modules, and its `CLAUDE.md` is still the un-`/init`'ed seed.
+
+Consequences: it is **not** a dependency of this repo and must not be added as one
+until it actually ships runtime modules. When it does, **import it — do not
+re-implement the tick here.** If you find yourself writing an engine loop,
+arbitration, or a sense driver in `microduck_cli/`, that code belongs upstream in
+`neurosymbolic-system`; file it there (the `communicate` skill posts cross-repo
+issues) rather than forking a second runtime. Until then, duck work that needs a
+runtime is blocked on that repo, and a CLI-only surface (config, discovery,
+inventory, dry-run planning) is what can land here.
+
+### `../reachy-mini-cli` — the architecture to follow
+
+The mature robot CLI in the family (`reachy/`, ~2000-line `CLAUDE.md`). Its
+`CLAUDE.md` "Architecture: the agent-first CLI" and "Noun internals" sections are
+the reference. The load-bearing lessons:
+
+- **One noun per capability, each with `overview`**, engine logic in a sibling
+  package (`reachy/behavior/`, `reachy/motion/`…) and only argparse wiring in
+  `_commands/`. Keep that split here: `microduck_cli/cli/_commands/` stays thin.
+- **The single-SDK-owner model.** The hardware exposes one client and one head;
+  every sense process contends for them, and the loser throttles. So **compose
+  senses onto ONE tick seam, never as two processes** (`_compose_run_seam`). Two
+  standalone sense nouns were deleted for exactly this reason — don't recreate the
+  mistake in duck form.
+- **Don't arbitrate across processes on a flag file.** A flag cannot expire; a
+  heartbeat in `state.json` can. Refuse early (`refuse_if_engine_live()`) instead
+  of running a silently useless second process.
+- **Sense-stage logging.** A named drop reason (`self-mute`, `cooldown`,
+  `audio-muted`…) on a dedicated logger, stderr-only, so JSONL export on stdout
+  stays pure. A layer whose drops are invisible is indistinguishable from one that
+  silently no-ops.
+
+### `../arm101-cli` — the hardware-safety patterns at this maturity
+
+The closest peer: same template, same half-rename gotcha, a real hardware layer
+grown on top (`arm101/hardware/`, `arm101/explore/`). Copy its two shipped
+disciplines when duck motion lands:
+
+- **Gated motion.** Every verb that moves hardware confirms on a TTY, prints a
+  zero-side-effect dry-run plan on a non-TTY without `--apply`, and proceeds on a
+  non-TTY *with* `--apply` (agent mode).
+- **Own what you energize.** Release on any abnormal exit (exception, bus fault,
+  Ctrl-C), each actuator released independently so one failure doesn't abort the
+  rest; leave torque untouched on a *clean* exit so a deliberate hold survives.
+  State the limits you cannot cover (a bus that is physically gone) rather than
+  implying safety you don't have.
+- **Hardware deps go in an extra, lazy-imported** (`[seeed]` there), so the base
+  install stays zero-dep and introspection works on a box with no robot attached.
+
+## Hard constraints
+
+- **Zero third-party runtime dependencies** (`dependencies = []`) — on purpose.
+  `teken`, pytest and the lint stack are dev-only. Keep it that way unless the duck
+  layer genuinely needs a hardware library, and if it does, put it behind an extra
+  with a lazy import so the introspection CLI still imports clean on a bare box.
+  Adding a *base* dep (including `neurosymbolic-system`, once it exists) is an
+  explicit decision, not a drive-by.
+- **Python ≥ 3.12** (`X | None`, `tomllib`).
+- **Every PR bumps the version — even docs/config/CI-only changes.** The
+  `version-check` job in `.github/workflows/tests.yml` compares `pyproject.toml`
+  against `origin/main` and fails the PR when they match (a duplicate version would
+  fail the PyPI publish on merge). Use the `version-bump` skill; it also prepends
+  the Keep-a-Changelog entry.
+
+## CI / release
+
+- `.github/workflows/tests.yml`: `test` (pytest + coverage + SonarCloud), `lint`
+  (the stack above + the rubric gate), `version-check` (PR-only).
+- SonarCloud gates the `test` job (`sonar-project.properties`,
+  `sonar.qualitygate.wait=true`) — but only when `SONAR_TOKEN` is set; token-less
+  repos and fork PRs skip the scan and stay green. `coverage.run.relative_files =
+  true` is load-bearing: without it `coverage.xml` paths don't map to
+  `sonar.sources=microduck_cli` and coverage reports 0%.
+- `publish.yml`: PyPI Trusted Publishing over OIDC — push to `main` → PyPI,
+  same-repo PR → a `.devN` build to TestPyPI. No stored credentials.
+
+## Skills (`.claude/skills/`) — cite-don't-import
+
+The kit is **vendored** from `guildmaster` (a few from `colleague`/`devague`);
+`docs/skill-sources.md` is the authoritative provenance ledger and holds the
+per-skill re-sync procedure. **Do not hand-edit skill script bodies** — lift real
+changes upstream and re-vendor; a copy that diverges silently is the failure mode
+that rule exists to prevent. The sanctioned local edits are (a) consumer-identifying
+prose in `SKILL.md` and (b) adding `type: command` to the frontmatter (load-bearing:
+the culture backend's `core.skill_loader` silently skips any `SKILL.md` without it).
+Every divergence beyond that gets a row in the ledger — `cicd`'s repo-specific
+pre-PR steps and `ask-colleague`'s direct-from-colleague vendoring are the tracked
+ones today. There are **no first-party skills here yet**; when you add one (a duck
+wrapper would be the natural first, as `find-reachy` is in reachy-mini-cli), say so
+in this section — otherwise a reviewer can't tell "ours" from "vendored".
+
+Day to day: **`cicd`** (the PR lane; needs `devex` ≥0.21 on PATH),
+**`communicate`** (cross-repo issues + mesh messages; needs `agtag`; posts auto-sign
+`- microduck-cli (Claude)`), **`version-bump`**, **`run-tests`**, **`sonarclaude`**,
+**`ask-colleague`**, and the devague chain (`scope` → `think` → `challenge` →
+`spec-to-plan` → `assign-to-workforce` → `summarize-delivery`, with `deviate` as the
+mid-run escape hatch).
+
+Reach for **`ask-colleague`** reflexively for a diverse second opinion —
+`review`/`explore` are read-only and always safe; side-effecting `write --apply` /
+`--pr` needs the user's go-ahead.
+
+## Conventions and workflow
+
+**Git worktrees live in `../.worktrees.microduck-cli/<name>/`.** ALL worktrees of
+this repo, without exception — workforce fan-out lanes, `ask-colleague` throwaways,
+scratch checkouts:
+
+```bash
+git worktree add ../.worktrees.microduck-cli/<name> -b <branch>
+```
+
+Never `/tmp`, never a shared `../worktrees/`. This workspace holds many sibling
+projects, and a generic shared folder accumulates orphaned trees from several repos
+with nothing indicating ownership — a stale-tree sweep can't tell a live lane from
+junk. Use a branch prefix scoped to the work (`duck/t2`, not plain `agent/t2`, which
+collides with leftovers from earlier fan-outs and makes `git worktree add -b` fail).
+Remove with `git worktree remove <path>`; `git worktree prune` only clears metadata.
+The vendored `assign-to-workforce` skill's fan-out example uses the shared path *and*
+`agent/<task-id>` branches — it is cited verbatim and must not be edited, so override
+both when following it.
+
+**Memory discipline — recall before, remember after.** This repo's eidetic memory is
+**in-repo and public**: records resolve to `<repo-root>/.eidetic/memory` (committed,
+shared with the team and mesh peers — the `claude` and `colleague` backends read the
+same `microduck-cli` scope). Note the `/remember` and `/recall` skill *descriptions*
+still claim a private `~/.eidetic` default; the vendored wrappers here default to
+`--visibility public`, and the script is what runs.
+
+- **`/recall` before you start** a non-trivial task — prior decisions, gotchas,
+  "have we done this before?" — so you build on what's known instead of re-deriving it.
+- **`/remember` when something worth keeping surfaces** — a decision and its
+  rationale, a constraint, a fix and *why*, a gotcha that cost time. Capture it as it
+  happens.
+
+Pass `--visibility private` to keep a record in `$HOME` (uncommitted); `/recall` reads
+both stores and merges. In-repo routing needs `eidetic >= 0.10.0`. Don't store what the
+repo already records (code structure, git history, this file, `CHANGELOG.md`) — store
+what you'd have to re-derive.
+
+**PR flow.** Branch (`fix/…`, `feat/…`, `docs/…`, `skill/…`), implement, bump the
+version, then go straight to `workflow.sh open` — in AgentCulture the standing default
+is always "push and create a Pull Request", no interactive merge/keep/discard menu.
+Signatures resolve from `culture.yaml` via `devex`; don't hand-sign inside `cicd`.

microduck_cli-0.8.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: microduck-cli
+Version: 0.8.0
+Summary: Agent-agnostic CLI for controlling the MicroDuck robot. Any agent, any human, one CLI. Built on the neurosymbolic-system runtime and following the reachy-mini-cli architecture.
+Project-URL: Homepage, https://github.com/agentculture/microduck-cli
+Project-URL: Issues, https://github.com/agentculture/microduck-cli/issues
+Author: AgentCulture
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# microduck-cli
+
+Agent-agnostic CLI for controlling the MicroDuck robot. Any agent, any human,
+one CLI. Built on the [neurosymbolic-system](https://github.com/agentculture/neurosymbolic-system)
+runtime and following the
+[reachy-mini-cli](https://github.com/agentculture/reachy-mini-cli) architecture.
+
+## Status: scaffold
+
+**There is no MicroDuck control code yet.** What ships today is the
+AgentCulture mesh-agent baseline — an agent-first introspection CLI, a mesh
+identity, the vendored guildmaster skill kit, and a build/CI/deploy pipeline.
+The duck domain is the destination; the CLI below is the chassis it grows on.
+
+The `neurosymbolic-system` runtime it is meant to import (senses, rules,
+arbitration and motion on one 50 Hz tick) is itself still a scaffold, so it is
+**not** a dependency of this package yet.
+
+## What you get
+
+- **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
+  (`afi-cli`) — the runtime package has no third-party dependencies.
+- **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
+  prompt file (`AGENTS.colleague.md` for this agent's `backend: colleague`).
+- **The vendored guildmaster skill kit** under `.claude/skills/`, cite-don't-import.
+  See [`docs/skill-sources.md`](docs/skill-sources.md).
+- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
+  PyPI Trusted Publishing wired into GitHub Actions.
+
+## Quickstart
+
+The installed console script is **`microduck`** (not `microduck-cli` — that is
+the distribution name and the name the CLI prints in its own output):
+
+```bash
+uv sync
+uv run pytest -n auto                 # run the test suite
+uv run microduck whoami               # identity from culture.yaml
+uv run microduck learn                # self-teaching prompt (add --json)
+uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
+```
+
+## CLI
+
+| Verb | What it does |
+|------|--------------|
+| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
+| `learn` | Print a structured self-teaching prompt. |
+| `explain <path>` | Markdown docs for any noun/verb path. |
+| `overview` | Read-only descriptive snapshot of the agent. |
+| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
+| `cli overview` | Describe the CLI surface itself. |
+
+Every command supports `--json`. Results go to stdout, errors/diagnostics to
+stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
+error, `3+` reserved.
+
+## Sibling projects
+
+microduck-cli is built by composing three siblings rather than inventing a
+fourth architecture:
+
+| Repo | Role here |
+|------|-----------|
+| [`neurosymbolic-system`](https://github.com/agentculture/neurosymbolic-system) | The robot runtime to **import** once it ships — never re-implement the tick loop in this repo. |
+| [`reachy-mini-cli`](https://github.com/agentculture/reachy-mini-cli) | The architecture to follow: noun groups, one tick seam for all senses, the single-SDK-owner model. |
+| [`arm101-cli`](https://github.com/agentculture/arm101-cli) | The hardware-safety patterns: gated motion (`--apply` / dry-run / TTY confirm), release-on-abnormal-exit, hardware deps behind an extra. |
+
+## Contributing
+
+See [`CLAUDE.md`](CLAUDE.md) for the full conventions: the CLI contracts, what
+to take from each sibling, version-bump-every-PR, the `cicd` PR lane, worktree
+layout, and memory discipline.
+
+## License
+
+Apache 2.0 — see [`LICENSE`](LICENSE).

microduck_cli-0.8.0/README.md

@@ -0,0 +1,77 @@
+# microduck-cli
+
+Agent-agnostic CLI for controlling the MicroDuck robot. Any agent, any human,
+one CLI. Built on the [neurosymbolic-system](https://github.com/agentculture/neurosymbolic-system)
+runtime and following the
+[reachy-mini-cli](https://github.com/agentculture/reachy-mini-cli) architecture.
+
+## Status: scaffold
+
+**There is no MicroDuck control code yet.** What ships today is the
+AgentCulture mesh-agent baseline — an agent-first introspection CLI, a mesh
+identity, the vendored guildmaster skill kit, and a build/CI/deploy pipeline.
+The duck domain is the destination; the CLI below is the chassis it grows on.
+
+The `neurosymbolic-system` runtime it is meant to import (senses, rules,
+arbitration and motion on one 50 Hz tick) is itself still a scaffold, so it is
+**not** a dependency of this package yet.
+
+## What you get
+
+- **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
+  (`afi-cli`) — the runtime package has no third-party dependencies.
+- **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
+  prompt file (`AGENTS.colleague.md` for this agent's `backend: colleague`).
+- **The vendored guildmaster skill kit** under `.claude/skills/`, cite-don't-import.
+  See [`docs/skill-sources.md`](docs/skill-sources.md).
+- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
+  PyPI Trusted Publishing wired into GitHub Actions.
+
+## Quickstart
+
+The installed console script is **`microduck`** (not `microduck-cli` — that is
+the distribution name and the name the CLI prints in its own output):
+
+```bash
+uv sync
+uv run pytest -n auto                 # run the test suite
+uv run microduck whoami               # identity from culture.yaml
+uv run microduck learn                # self-teaching prompt (add --json)
+uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
+```
+
+## CLI
+
+| Verb | What it does |
+|------|--------------|
+| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
+| `learn` | Print a structured self-teaching prompt. |
+| `explain <path>` | Markdown docs for any noun/verb path. |
+| `overview` | Read-only descriptive snapshot of the agent. |
+| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
+| `cli overview` | Describe the CLI surface itself. |
+
+Every command supports `--json`. Results go to stdout, errors/diagnostics to
+stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
+error, `3+` reserved.
+
+## Sibling projects
+
+microduck-cli is built by composing three siblings rather than inventing a
+fourth architecture:
+
+| Repo | Role here |
+|------|-----------|
+| [`neurosymbolic-system`](https://github.com/agentculture/neurosymbolic-system) | The robot runtime to **import** once it ships — never re-implement the tick loop in this repo. |
+| [`reachy-mini-cli`](https://github.com/agentculture/reachy-mini-cli) | The architecture to follow: noun groups, one tick seam for all senses, the single-SDK-owner model. |
+| [`arm101-cli`](https://github.com/agentculture/arm101-cli) | The hardware-safety patterns: gated motion (`--apply` / dry-run / TTY confirm), release-on-abnormal-exit, hardware deps behind an extra. |
+
+## Contributing
+
+See [`CLAUDE.md`](CLAUDE.md) for the full conventions: the CLI contracts, what
+to take from each sibling, version-bump-every-PR, the `cicd` PR lane, worktree
+layout, and memory discipline.
+
+## License
+
+Apache 2.0 — see [`LICENSE`](LICENSE).

{microduck_cli-0.7.0 → microduck_cli-0.8.0}/docs/skill-sources.md

@@ -31,7 +31,7 @@ is load-bearing, even where guildmaster's upstream copy omits it.
 
 | Skill | Upstream | Origin | Notes | Last synced |
 |-------|----------|--------|-------|-------------|
-| `cicd` | `../guildmaster/.claude/skills/cicd/` | guildmaster | CI/CD lane layered on `devex pr`: the 5 thin scripts (`workflow.sh`, `pr-status.sh`, `pr-reply.sh`, `_resolve-nick.sh`, `portability-lint.sh`) delegate lint/open/read/reply/delta to `devex` and add the `status` / `await` SonarCloud-gating extensions. Consumer-identifying prose (`guildmaster` → `microduck-cli`) adapted in the description + heading; upstream history (`Renamed from pr-review in steward 0.7.0; rebased on devex in 0.12.0`) and env-var literals (`STEWARD_*`) kept verbatim. The PR signature resolves at runtime from `culture.yaml` via `_resolve-nick.sh` (→ `microduck-cli`). Requires `devex` on PATH. | 2026-05-26 (guildmaster 0.6.0) |
+| `cicd` | `../guildmaster/.claude/skills/cicd/` | guildmaster | CI/CD lane layered on `devex pr`: the 5 thin scripts (`workflow.sh`, `pr-status.sh`, `pr-reply.sh`, `_resolve-nick.sh`, `portability-lint.sh`) delegate lint/open/read/reply/delta to `devex` and add the `status` / `await` SonarCloud-gating extensions. Consumer-identifying prose (`guildmaster` → `microduck-cli`) adapted in the description + heading; upstream history (`Renamed from pr-review in steward 0.7.0; rebased on devex in 0.12.0`) and env-var literals (`STEWARD_*`) kept verbatim. The PR signature resolves at runtime from `culture.yaml` via `_resolve-nick.sh` (→ `microduck-cli`). Requires `devex` on PATH. **Prose divergence (2026-08-29):** the "Greenfield-aware steps", triage-defaults and mesh-ping paragraphs were adapted to this repo's actual stack — see [local divergence](#local-divergence--cicd-pre-pr-steps-adapted-to-this-repos-stack-2026-08-29). | 2026-05-26 (guildmaster 0.6.0) |
 | `communicate` | `../guildmaster/.claude/skills/communicate/` | guildmaster | Cross-repo + mesh communication. Consumer-identifying prose adapted in the description (incl. the `- microduck-cli (Claude)` signature line). **No hard-coded signature literal in the scripts** — `post-issue.sh` is `agtag`-backed and resolves the signing nick from `culture.yaml`; requires `agtag` (>=0.1) on PATH. The supplier `scripts/templates/` (`skill-update-brief.md`, `skill-new-brief.md`) are kept verbatim — inert for a consumer (they cite guildmaster as upstream). Renamed from `coordinate` in steward 0.8.0; absorbed `gh-issues` in 0.9.1. | 2026-05-26 (guildmaster 0.6.0) |
 | `version-bump` | `../guildmaster/.claude/skills/version-bump/` | guildmaster | Pure-Python, CWD-aware (`scripts/bump.py`). Verbatim except added `type: command`. | 2026-05-26 (guildmaster 0.6.0) |
 | `agent-config` | `../guildmaster/.claude/skills/agent-config/` | guildmaster (origin steward) | Shows a Culture agent's full config; run `scripts/show.sh` directly (no `guild` binary required). `scripts/show.sh` + `data/backend-fingerprints.yaml` verbatim. Verbatim except added `type: command`. | 2026-05-26 (guildmaster 0.6.0) |
@@ -174,6 +174,33 @@ wrapper (i.e. its copy goes back to matching devague byte-for-byte), switch
 the upstream column back to `../guildmaster/.claude/skills/<skill>/` and
 re-sync from there per the normal procedure.
 
+### Local divergence — `cicd` pre-PR steps adapted to this repo's stack (2026-08-29)
+
+Guildmaster ships `cicd`'s `SKILL.md` with a **"Greenfield-aware steps"** section
+whose pre-PR commands are conditional no-ops (`[ -d tests ] && …`), plus triage
+defaults phrased for a greenfield supplier repo. microduck-cli's stack has
+landed — tests, the lint stack, the rubric gate and the `version-check` job all
+run — so those steps are unconditional here and the section is rewritten as
+**"Pre-PR steps (microduck-cli)"**, listing the commands this repo's CI actually
+enforces. Two smaller prose adaptations ride along: the triage defaults name this
+repo's real false-positive class (scaffold complaints, and any proposal to grow a
+second runtime loop in `microduck_cli/` instead of upstream in
+`neurosymbolic-system`), and the closing mesh-ping paragraph names microduck-cli
+rather than steward.
+
+**No script bodies are edited** — the divergence is confined to `SKILL.md` prose,
+which is the sanctioned adaptation surface. On a re-sync, pull guildmaster's copy
+fresh and re-apply the three edits:
+
+```bash
+diff -u ../guildmaster/.claude/skills/cicd/SKILL.md .claude/skills/cicd/SKILL.md
+```
+
+If guildmaster's upstream ever grows a per-consumer pre-PR mechanism (the
+`pr lint --extra=tests,version,markdown` ask filed at
+[devex#41](https://github.com/agentculture/devex/issues/41)), drop this
+divergence and delegate to it instead.
+
 ## Tooling prerequisites
 
 - **`devex`** (>=0.21) on PATH — `cicd` delegates the PR lifecycle to `devex pr`.

{microduck_cli-0.7.0 → microduck_cli-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "microduck-cli"
-version = "0.7.0"
+version = "0.8.0"
 description = "Agent-agnostic CLI for controlling the MicroDuck robot. Any agent, any human, one CLI. Built on the neurosymbolic-system runtime and following the reachy-mini-cli architecture."
 readme = "README.md"
 license = "Apache-2.0"

{microduck_cli-0.7.0 → microduck_cli-0.8.0}/uv.lock

@@ -154,37 +154,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/61/e8/cb8e80d6f9f55b99588625062822bf946cf03ed06315df4bd8397f5632a1/coverage-7.14.0-py3-none-any.whl", hash = "sha256:8de5b61163aee3d05c8a2beab6f47913df7981dad1baf82c414d99158c286ab1", size = 211764, upload-time = "2026-05-10T18:02:29.538Z" },
 ]
 
-[[package]]
-name = "microduck-cli"
-version = "0.7.0"
-source = { editable = "." }
-
-[package.dev-dependencies]
-dev = [
-    { name = "bandit" },
-    { name = "black" },
-    { name = "flake8" },
-    { name = "isort" },
-    { name = "pytest" },
-    { name = "pytest-cov" },
-    { name = "pytest-xdist" },
-    { name = "teken" },
-]
-
-[package.metadata]
-
-[package.metadata.requires-dev]
-dev = [
-    { name = "bandit", specifier = ">=1.7.5" },
-    { name = "black", specifier = ">=23.7.0" },
-    { name = "flake8", specifier = ">=6.1" },
-    { name = "isort", specifier = ">=5.12.0" },
-    { name = "pytest", specifier = ">=8.0" },
-    { name = "pytest-cov", specifier = ">=4.1" },
-    { name = "pytest-xdist", specifier = ">=3.0" },
-    { name = "teken", specifier = ">=0.8" },
-]
-
 [[package]]
 name = "execnet"
 version = "2.1.2"
@@ -256,6 +225,37 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
 ]
 
+[[package]]
+name = "microduck-cli"
+version = "0.8.0"
+source = { editable = "." }
+
+[package.dev-dependencies]
+dev = [
+    { name = "bandit" },
+    { name = "black" },
+    { name = "flake8" },
+    { name = "isort" },
+    { name = "pytest" },
+    { name = "pytest-cov" },
+    { name = "pytest-xdist" },
+    { name = "teken" },
+]
+
+[package.metadata]
+
+[package.metadata.requires-dev]
+dev = [
+    { name = "bandit", specifier = ">=1.7.5" },
+    { name = "black", specifier = ">=23.7.0" },
+    { name = "flake8", specifier = ">=6.1" },
+    { name = "isort", specifier = ">=5.12.0" },
+    { name = "pytest", specifier = ">=8.0" },
+    { name = "pytest-cov", specifier = ">=4.1" },
+    { name = "pytest-xdist", specifier = ">=3.0" },
+    { name = "teken", specifier = ">=0.8" },
+]
+
 [[package]]
 name = "mypy-extensions"
 version = "1.1.0"

microduck_cli-0.7.0/CLAUDE.md

@@ -1,28 +0,0 @@
-# CLAUDE.md — seed / bootstrap placeholder
-
-> **This is a self-initializing seed, not a finished runtime prompt.**
-> Run `/init` (or describe the agent's domain to your AI assistant) to
-> re-initialize this file into a full runtime prompt, using the description
-> below and the scaffolded repo as context.
-
-## Agent
-
-This repository hosts the **microduck-cli** agent.
-
-## Description
-
-Agent-agnostic CLI for controlling the MicroDuck robot. Any agent, any human, one CLI. Built on the neurosymbolic-system runtime and following the reachy-mini-cli architecture.
-
-## Re-init instruction
-
-This file is a seed. To expand it into your full runtime prompt:
-
-1. Open this repo in Claude Code (or your preferred AI assistant).
-2. Run `/init` — the assistant will read the repo, incorporate the description
-   above, and replace this seed with a complete `CLAUDE.md`.
-3. Commit the result.
-
-Until you run `/init`, `microduck-cli` satisfies the `steward doctor`
-`prompt-file-present` and `backend-consistency` invariants (a `CLAUDE.md`
-exists and `culture.yaml` declares `backend: claude`) but the prompt is not
-yet tailored to this agent's domain.

microduck_cli-0.7.0/PKG-INFO

@@ -1,76 +0,0 @@
-Metadata-Version: 2.5
-Name: microduck-cli
-Version: 0.7.0
-Summary: Agent-agnostic CLI for controlling the MicroDuck robot. Any agent, any human, one CLI. Built on the neurosymbolic-system runtime and following the reachy-mini-cli architecture.
-Project-URL: Homepage, https://github.com/agentculture/microduck-cli
-Project-URL: Issues, https://github.com/agentculture/microduck-cli/issues
-Author: AgentCulture
-License-Expression: Apache-2.0
-License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-
-# microduck-cli
-
-Agent-agnostic CLI for controlling the MicroDuck robot. Any agent, any human, one CLI. Built on the neurosymbolic-system runtime and following the reachy-mini-cli architecture.
-
-## What you get
-
-- **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
-  (`afi-cli`) — the runtime package has no third-party dependencies.
-- **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
-  resident prompt file (`AGENTS.colleague.md`, since this template runs
-  `backend: colleague`).
-- **The canonical guildmaster skill kit** (11 skills) under `.claude/skills/`,
-  vendored cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
-- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
-  PyPI Trusted Publishing wired into GitHub Actions.
-
-## Quickstart
-
-```bash
-uv sync
-uv run pytest -n auto                 # run the test suite
-uv run microduck-cli whoami  # identity from culture.yaml
-uv run microduck-cli learn   # self-teaching prompt (add --json)
-uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
-```
-
-## CLI
-
-| Verb | What it does |
-|------|--------------|
-| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
-| `learn` | Print a structured self-teaching prompt. |
-| `explain <path>` | Markdown docs for any noun/verb path. |
-| `overview` | Read-only descriptive snapshot of the agent. |
-| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
-| `cli overview` | Describe the CLI surface itself. |
-
-Every command supports `--json`. Results go to stdout, errors/diagnostics to
-stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
-error, `3+` reserved.
-
-## Make it your own
-
-1. Rename the package `microduck_cli/` and the `microduck-cli`
-   CLI/dist name throughout `pyproject.toml`, the package, `tests/`,
-   `sonar-project.properties`, and this `README.md`. The name is hard-coded in
-   ~100 places, so list every occurrence first — see the `git grep` discovery
-   command in [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
-2. Edit `culture.yaml` with your `suffix` and `backend`.
-3. Rewrite `CLAUDE.md` for your agent and run `/init`.
-4. Re-vendor only the skills you need from guildmaster (see
-   [`docs/skill-sources.md`](docs/skill-sources.md)).
-
-See [`CLAUDE.md`](CLAUDE.md) for the full conventions (version-bump-every-PR,
-the `cicd` PR lane, deploy setup).
-
-## License
-
-Apache 2.0 — see [`LICENSE`](LICENSE).

microduck_cli-0.7.0/README.md

@@ -1,59 +0,0 @@
-# microduck-cli
-
-Agent-agnostic CLI for controlling the MicroDuck robot. Any agent, any human, one CLI. Built on the neurosymbolic-system runtime and following the reachy-mini-cli architecture.
-
-## What you get
-
-- **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
-  (`afi-cli`) — the runtime package has no third-party dependencies.
-- **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
-  resident prompt file (`AGENTS.colleague.md`, since this template runs
-  `backend: colleague`).
-- **The canonical guildmaster skill kit** (11 skills) under `.claude/skills/`,
-  vendored cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
-- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
-  PyPI Trusted Publishing wired into GitHub Actions.
-
-## Quickstart
-
-```bash
-uv sync
-uv run pytest -n auto                 # run the test suite
-uv run microduck-cli whoami  # identity from culture.yaml
-uv run microduck-cli learn   # self-teaching prompt (add --json)
-uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
-```
-
-## CLI
-
-| Verb | What it does |
-|------|--------------|
-| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
-| `learn` | Print a structured self-teaching prompt. |
-| `explain <path>` | Markdown docs for any noun/verb path. |
-| `overview` | Read-only descriptive snapshot of the agent. |
-| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
-| `cli overview` | Describe the CLI surface itself. |
-
-Every command supports `--json`. Results go to stdout, errors/diagnostics to
-stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
-error, `3+` reserved.
-
-## Make it your own
-
-1. Rename the package `microduck_cli/` and the `microduck-cli`
-   CLI/dist name throughout `pyproject.toml`, the package, `tests/`,
-   `sonar-project.properties`, and this `README.md`. The name is hard-coded in
-   ~100 places, so list every occurrence first — see the `git grep` discovery
-   command in [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
-2. Edit `culture.yaml` with your `suffix` and `backend`.
-3. Rewrite `CLAUDE.md` for your agent and run `/init`.
-4. Re-vendor only the skills you need from guildmaster (see
-   [`docs/skill-sources.md`](docs/skill-sources.md)).
-
-See [`CLAUDE.md`](CLAUDE.md) for the full conventions (version-bump-every-PR,
-the `cicd` PR lane, deploy setup).
-
-## License
-
-Apache 2.0 — see [`LICENSE`](LICENSE).