Skip to content

feat(setup): add zero-token /magpie-status Claude Code mod command (part of #1497) - #1601

Open
Kaap10 wants to merge 3 commits into
apache:mainfrom
Kaap10:feat/claude-code-mod-status-command-1497
Open

Kaap10 wants to merge 3 commits into
apache:mainfrom
Kaap10:feat/claude-code-mod-status-command-1497

Conversation

@Kaap10

@Kaap10 Kaap10 commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Zero-token status command (Pilot 2 of Explore Claude Code mods across the skill families #1497): Implemented /magpie-status in plugins/magpie-setup using Claude Code's mod system ($.command.register and command.run), rendering the adoption and health dashboard instantly with zero LLM turns and zero tokens consumed.
  • Deterministic collector parity & vendor neutrality: Mod executes the canonical collect_status.py via $.process.run (supporting --format md default and --format json / --format=json / --json overrides, with automatic python3 -> python fallback). This avoids duplicating 770+ lines of Python adoption logic in TypeScript while keeping the universal /magpie-setup status skill 100% operational for non-Claude harnesses.
  • Cross-platform robustness: Defensively ensured UTF-8 stdout reconfiguration in collect_status.py against Windows console cp1252 encoding errors, and normalized path separators in drift-check.test.ts for cross-platform mock matching.

Type of change

  • Skill change (.claude/skills/<name>/) — eval fixtures updated below
  • Tool / bridge contract (tools/<system>/*.md)
  • Python package (tools/*/ with pyproject.toml)
  • Groovy reference impl
  • Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
  • Documentation (docs/, README.md, CONTRIBUTING.md)
  • Project template (projects/_template/)
  • CI / dev loop (prek, workflows, validators)
  • Other: Claude Code mod / plugin command (plugins/magpie-setup/hooks/)

Test plan

  • check-claude-mods script (tools/dev/check-claude-mods.sh) passes:
    • claude plugin validate --strict plugins/magpie-setup passes with zero errors.
    • claude plugin test plugins/magpie-setup passes all 19 tests across 2 files (9 in drift-check.test.ts, 10 in status-command.test.ts).
  • For Python packages touched:
    • uv run pytest plugins/magpie-setup/skills/status/tests/ passes all 18 tests (100%).
    • uv run ruff check plugins/magpie-setup/skills/status/scripts/collect_status.py passes with zero violations.
    • uv run ruff format --check plugins/magpie-setup/skills/status/scripts/collect_status.py passes (already formatted).
  • Git hygiene:
    • git diff --check passes with zero whitespace or line-ending warnings.
    • End-to-end CLI tested: verified both collect_status.py --format md --repo . and --format json --pretty --repo . execute cleanly.

RFC-AI-0004 compliance

  • HITL — /magpie-status is strictly read-only; mutation remains gated via the setup skill.
  • Sandbox — No unsandboxed background daemons, no network requests; subprocess executes an argument array directly without a shell.
  • Vendor neutrality — The universal Markdown workflow (/magpie-setup status) remains completely functional for non-Claude harnesses (Gemini CLI, Codex, Cursor).
  • Conversational + correctable — agentic-override path documented if behaviour is adopter-tunable
  • Write-access discipline — Read-only telemetry; no autonomous outbound messages or file mutations.
  • Privacy LLM — Pure local deterministic execution; no data sent to external models.

Linked issues

Refs #1497 (Pilot 2)

Notes for reviewers (optional)

  • Single Source of Truth: Rather than reimplementing adoption and symlink parsing logic in TypeScript, the mod executes collect_status.py deterministically via $.process.run.
  • Static AST Analysis Constraint: Claude Code's static analyzer prohibits passing $ across imported module boundaries. Hook registration (session.start and command.run) lives directly in drift-check.ts (keeping hooks/hooks.json to a single module entrypoint), while execution logic is delegated to the pure, testable executeMagpieStatus helper in status-command.ts.
  • Path Normalization in Tests: drift-check.test.ts was updated to normalize Windows backslashes (\) to / in mock path endsWith checks so that the plugin test suite passes locally on Windows as well as in CI.
  • Defensive Unicode Handling: collect_status.py now defensively reconfigures stdout encoding to UTF-8 (try...except) to prevent charmap encode exceptions on Windows cp1252 terminals when rendering status indicator emojis.

…art of apache#1497)

Implement Pilot 2 of Issue apache#1497: add zero-token /magpie-status slash
command in plugins/magpie-setup using Claude Code's mod system.

- Register /magpie-status during session.start hook with immediate: true.
- Hook command.run on magpie-status to execute canonical collect_status.py
  deterministically via $.process.run with zero tokens and zero model turns.
- Support default markdown table format and --format json / --format=json /
  --json flag overrides.
- Try python3 first, falling back cleanly to python on command-not-found or
  process failure, with actionable diagnostic error text.
- Pass PYTHONIOENCODING: utf-8 and defensively wrap stdout reconfiguration
  in collect_status.py to guarantee safe unicode output across all platforms.
- Add 10 comprehensive unit and engine tests in status-command.test.ts.
- Normalize path separators in drift-check.test.ts for cross-platform
  mock matching on Windows, macOS, and Linux.
- Update docs/when-to-use-mods.md and status/SKILL.md to document the
  new command while preserving universal /magpie-setup status skill for
  non-Claude harnesses.

Generated-by: Antigravity
@github-actions github-actions Bot added family:setup setup-* skills family:docs Docs, MISSION.md, READMEs capability:stats Read-only dashboards, metrics, governance evidence capability:platform Framework / agent substrate skills (install, verify, doctor, override, status, setup bootstrap) labels Oct 12, 2026
Comment thread plugins/magpie-setup/skills/status/scripts/collect_status.py Fixed
@Kaap10

Kaap10 commented Oct 12, 2026

Copy link
Copy Markdown
Contributor Author

Ready for review!
Implemented Pilot 2 zero-token /magpie-status mod with test coverage.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

capability:platform Framework / agent substrate skills (install, verify, doctor, override, status, setup bootstrap) capability:stats Read-only dashboards, metrics, governance evidence family:docs Docs, MISSION.md, READMEs family:setup setup-* skills

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants