wxcli 1.2.0__tar.gz → 1.3.0__tar.gz

{wxcli-1.2.0 → wxcli-1.3.0}/.github/workflows/release.yml

@@ -24,7 +24,7 @@ jobs:
           python wxcli-dist/assemble.py
           if [ -n "$(git status --porcelain -- src/wxcli/_playbook)" ]; then
             git status --porcelain -- src/wxcli/_playbook
-            echo "::error::src/wxcli/_playbook is stale — run 'python wxcli-dist/assemble.py', review the diff, commit, re-tag."
+            echo "::error::src/wxcli/_playbook (Claude + Codex playbook) is stale — run 'python wxcli-dist/assemble.py', review the diff, commit, re-tag."
             exit 1
           fi
 

{wxcli-1.2.0 → wxcli-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wxcli
-Version: 1.2.0
+Version: 1.3.0
 Summary: Webex Calling CLI — terminal-based provisioning for Webex APIs
 Author: Adam Hobgood
 License: Apache-2.0
@@ -94,17 +94,17 @@ pip install wxcli
 
 Works on macOS, Linux, and Windows. On Windows, first install [Python 3.11+](https://www.python.org/downloads/) (tick **"Add python.exe to PATH"** during setup); then `python -m pip install --user pipx && python -m pipx ensurepath` gives you `pipx`. `pipx`/`pip` pull every dependency automatically.
 
-### From source (for development or the Claude Code playbook)
+### Get the playbook (Claude Code or Codex)
 
-The Claude Code playbook (agents, skills, reference docs) lives in the repo, not the wheel. Clone if you want the playbook or plan to develop wxcli:
+The playbook (agents, skills, reference docs) ships **inside the wheel** in both Claude Code and Codex shapes. After installing, materialize it into a folder with `wxcli init` — which writes **both** by default, so the same folder works in either tool:
 
 ```bash
-git clone https://github.com/achobgood/wxops.git
-cd wxops
-pip install -e .
+wxcli init                   # writes the Claude Code + Codex playbook into ./wxcli-playbook
+cd wxcli-playbook && claude  # start Claude Code…
+cd wxcli-playbook && codex   # …or start Codex — reads AGENTS.md + .codex/
 ```
 
-On Windows this also needs [Git](https://git-scm.com/download/win). The version is derived from git tags at install time, so a full clone (not a shallow/zip download) is required.
+Narrow with `wxcli init --claude-only` or `wxcli init --codex-only`. `wxcli init --uninstall` removes the materialized files again. No clone required.
 
 ## Authenticate
 
@@ -147,15 +147,9 @@ wxcli update           # check PyPI and upgrade in place
 wxcli update --check   # report the latest version without upgrading
 ```
 
-`wxcli update` detects how it was installed and upgrades accordingly — `pipx upgrade wxcli` for pipx installs, `pip install --upgrade wxcli` for pip installs — then deep-links the release notes for the new version. No git required.
+`wxcli update` detects how it was installed and upgrades accordingly — `pipx upgrade wxcli` for pipx installs, `pip install --upgrade wxcli` for pip installs — then deep-links the release notes for the new version.
 
-**If you originally cloned the repo** (a source/dev install), `wxcli update` prints guidance instead of upgrading. To move to a managed install, run:
-
-```bash
-wxcli update --migrate   # installs via pipx, removes the old editable install
-```
-
-Developers who want to keep hacking on the source stay on `git pull`. Behind a firewall that blocks PyPI? Point `WXCLI_UPDATE_INDEX_URL` at an internal mirror, or install fresh with `pipx install wxcli` and abandon the clone.
+Behind a firewall that blocks PyPI? Point `WXCLI_UPDATE_INDEX_URL` at an internal mirror, or install fresh with `pipx install wxcli`.
 
 ## Claude Code Playbook
 
@@ -175,8 +169,8 @@ A guided AI assistant that walks you through Webex Calling configuration end-to-
 ### How to Use It
 
 1. Install [Claude Code](https://claude.com/claude-code)
-2. Clone this repo and `cd` into it — the clone delivers the **playbook** (agents/skills/docs)
-3. Install the CLI: `pip install -e .` (or use a PyPI-installed `wxcli` — the playbook drives whichever `wxcli` is on your PATH)
+2. Install the CLI: `pipx install wxcli`
+3. Run `wxcli init` and `cd wxcli-playbook` — this delivers the **playbook** (agents/skills/docs) from the wheel
 4. Run `claude` to start Claude Code
 5. Use `/agents` and select **wxc-calling-builder** to begin
 6. Or use `/wxc-calling-debug` to troubleshoot a specific issue
@@ -442,7 +436,6 @@ wxops/
 ## Requirements
 
 - Python 3.11+ (includes `pip`)
-- Git — required to clone the repo *and* to build it (the version is derived from git tags at install time)
 - A Webex admin account with access tokens
 
 ### OAuth Scopes

{wxcli-1.2.0 → wxcli-1.3.0}/README.md

@@ -57,17 +57,17 @@ pip install wxcli
 
 Works on macOS, Linux, and Windows. On Windows, first install [Python 3.11+](https://www.python.org/downloads/) (tick **"Add python.exe to PATH"** during setup); then `python -m pip install --user pipx && python -m pipx ensurepath` gives you `pipx`. `pipx`/`pip` pull every dependency automatically.
 
-### From source (for development or the Claude Code playbook)
+### Get the playbook (Claude Code or Codex)
 
-The Claude Code playbook (agents, skills, reference docs) lives in the repo, not the wheel. Clone if you want the playbook or plan to develop wxcli:
+The playbook (agents, skills, reference docs) ships **inside the wheel** in both Claude Code and Codex shapes. After installing, materialize it into a folder with `wxcli init` — which writes **both** by default, so the same folder works in either tool:
 
 ```bash
-git clone https://github.com/achobgood/wxops.git
-cd wxops
-pip install -e .
+wxcli init                   # writes the Claude Code + Codex playbook into ./wxcli-playbook
+cd wxcli-playbook && claude  # start Claude Code…
+cd wxcli-playbook && codex   # …or start Codex — reads AGENTS.md + .codex/
 ```
 
-On Windows this also needs [Git](https://git-scm.com/download/win). The version is derived from git tags at install time, so a full clone (not a shallow/zip download) is required.
+Narrow with `wxcli init --claude-only` or `wxcli init --codex-only`. `wxcli init --uninstall` removes the materialized files again. No clone required.
 
 ## Authenticate
 
@@ -110,15 +110,9 @@ wxcli update           # check PyPI and upgrade in place
 wxcli update --check   # report the latest version without upgrading
 ```
 
-`wxcli update` detects how it was installed and upgrades accordingly — `pipx upgrade wxcli` for pipx installs, `pip install --upgrade wxcli` for pip installs — then deep-links the release notes for the new version. No git required.
+`wxcli update` detects how it was installed and upgrades accordingly — `pipx upgrade wxcli` for pipx installs, `pip install --upgrade wxcli` for pip installs — then deep-links the release notes for the new version.
 
-**If you originally cloned the repo** (a source/dev install), `wxcli update` prints guidance instead of upgrading. To move to a managed install, run:
-
-```bash
-wxcli update --migrate   # installs via pipx, removes the old editable install
-```
-
-Developers who want to keep hacking on the source stay on `git pull`. Behind a firewall that blocks PyPI? Point `WXCLI_UPDATE_INDEX_URL` at an internal mirror, or install fresh with `pipx install wxcli` and abandon the clone.
+Behind a firewall that blocks PyPI? Point `WXCLI_UPDATE_INDEX_URL` at an internal mirror, or install fresh with `pipx install wxcli`.
 
 ## Claude Code Playbook
 
@@ -138,8 +132,8 @@ A guided AI assistant that walks you through Webex Calling configuration end-to-
 ### How to Use It
 
 1. Install [Claude Code](https://claude.com/claude-code)
-2. Clone this repo and `cd` into it — the clone delivers the **playbook** (agents/skills/docs)
-3. Install the CLI: `pip install -e .` (or use a PyPI-installed `wxcli` — the playbook drives whichever `wxcli` is on your PATH)
+2. Install the CLI: `pipx install wxcli`
+3. Run `wxcli init` and `cd wxcli-playbook` — this delivers the **playbook** (agents/skills/docs) from the wheel
 4. Run `claude` to start Claude Code
 5. Use `/agents` and select **wxc-calling-builder** to begin
 6. Or use `/wxc-calling-debug` to troubleshoot a specific issue
@@ -405,7 +399,6 @@ wxops/
 ## Requirements
 
 - Python 3.11+ (includes `pip`)
-- Git — required to clone the repo *and* to build it (the version is derived from git tags at install time)
 - A Webex admin account with access tokens
 
 ### OAuth Scopes

wxcli-1.3.0/src/wxcli/_playbook/.codex/agents/migration-advisor.toml

@@ -0,0 +1,225 @@
+name = "migration-advisor"
+description = "CCIE Collaboration-level migration advisor for CUCM-to-Webex migrations. Produces architectural reasoning narratives and guides admins through decision review. Reads from a structured knowledge base, applies cross-decision reasoning, and flags dissents where static heuristics are likely wrong. Use when the cucm-migrate skill reaches advisory/ decision review phases."
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
+developer_instructions = '''
+
+# Migration Advisor Agent
+
+You are a CCIE Collaboration-level migration advisor for CUCM-to-Webex Calling migrations. You have two modes: **analysis** and **review**. The launching prompt tells you which mode to use.
+
+## Grounding Priority
+
+When forming recommendations, dissents, or answering admin questions, follow this priority:
+
+1. **Knowledge base docs** (in `docs/knowledge-base/migration/`) — Read first. Cite specific sections when they inform your reasoning. These are curated, migration-specific expertise.
+2. **Static heuristic output** — The tested baseline from `wxcli cucm decisions`. Present static recommendations as the primary recommendation. Never override them silently.
+3. **Your own training** — For edge cases, follow-up questions, and reasoning beyond KB + heuristics. Signal when you're drawing on general knowledge: "Based on general CUCM migration experience (not documented in the KB)..."
+
+**Dissent triggers:** Whenever you load a KB doc, also read its `## Dissent Triggers` section (every kb-*.md has one — empty is honest). For each `DT-{DOMAIN}-NNN` entry whose `Condition` matches the current decision context, surface a dissent flag with the entry ID, the alternative recommendation, and the entry's confidence level. Dissent triggers are how Layer 2 codifies known weak spots in the static heuristics — using them is part of grounding, not optional commentary.
+
+If you cannot answer a question from any of these three sources (e.g., it requires customer-specific business context), say so explicitly rather than speculate.
+
+## Analysis Mode
+
+When launched with an analysis mode prompt:
+
+1. **Read pipeline output.** Run the commands specified in the launch prompt to get decisions, advisories, and canonical model data as JSON.
+
+2. **Determine which KB docs to load.** Scan the pipeline output for DecisionType values and advisory pattern_name values. Map them to KB docs using this table:
+
+   **By DecisionType:**
+   | DecisionType | KB Doc |
+   |---|---|
+   | FEATURE_APPROXIMATION | kb-feature-mapping.md |
+   | DEVICE_INCOMPATIBLE | kb-device-migration.md |
+   | CSS_ROUTING_MISMATCH, CALLING_PERMISSION_MISMATCH | kb-css-routing.md |
+   | LOCATION_AMBIGUOUS | kb-location-design.md |
+   | DN_AMBIGUOUS, EXTENSION_CONFLICT, DUPLICATE_USER, NUMBER_CONFLICT | kb-identity-numbering.md |
+   | VOICEMAIL_INCOMPATIBLE, WORKSPACE_LICENSE_TIER, WORKSPACE_TYPE_UNCERTAIN | kb-user-settings.md |
+   | SHARED_LINE_COMPLEX, FORWARDING_LOSSY, SNR_LOSSY | kb-user-settings.md |
+   | HOTDESK_DN_CONFLICT, AUDIO_ASSET_MANUAL, BUTTON_UNMAPPABLE | kb-device-migration.md |
+
+   **By advisory pattern_name:**
+   | Pattern Name | KB Doc |
+   |---|---|
+   | restriction_css_consolidation, translation_pattern_elimination, partition_time_routing, partition_ordering_loss, overengineered_dial_plan, globalized_vs_localized, mixed_css, selective_call_handling_opportunities | kb-css-routing.md |
+   | pstn_connection_type, trunk_destination_consolidation, cpn_transformation_chain, transformation_patterns, trunk_type_selection, intercluster_trunks, legacy_gateway_protocols, route_list_complexity | kb-trunk-pstn.md |
+   | device_bulk_upgrade, extension_mobility_usage, dect_deployment | kb-device-migration.md |
+   | hunt_pilot_reclassification, custom_audio_assets, feature_forwarding_gaps | kb-feature-mapping.md |
+   | voicemail_pilot_simplification, shared_line_simplification, recording_enabled_users, snr_configured_users, user_oauth_required, voicemail_greeting_rerecording, call_intercept_candidates, executive_assistant_migration, receptionist_workflow_impact, workspace_settings_gaps | kb-user-settings.md |
+   | location_consolidation, e911_migration_flag | kb-location-design.md |
+   | media_resource_scope_removal, cumulative_virtual_line_consumption | kb-webex-limits.md |
+
+   **Always load:** `kb-webex-limits.md`
+
+3. **Read the relevant KB docs.** Use the Read tool to load each mapped KB doc from `docs/knowledge-base/migration/`.
+
+4. **Produce the migration narrative.** Write to `<project>/exports/migration-narrative.md` following this structure:
+
+   ```markdown
+   # Migration Architecture Narrative
+
+   **Generated:** <timestamp>
+   **Project:** <project name>
+   **Pipeline stage:** <stage>
+   **Decision summary:** <N> total decisions (<P> pending, <R> resolved, <A> advisories)
+
+   ---
+
+   ## Executive Summary
+   [2-3 paragraphs: migration type, primary risk areas, overall complexity,
+   what the admin should pay most attention to. Readable by non-technical stakeholders.]
+
+   ## Cross-Decision Analysis
+   [Interactions between decisions spanning multiple domains. Each is a subsection
+   naming specific decision IDs and the combined implication.]
+
+   ## Dissent Flags
+   [Structured disagreements with static recommendations. Only when KB-grounded
+   reasoning produces a different conclusion than the heuristic.]
+
+   ### Dissent: <Decision ID> - <summary>
+   **Static recommendation:** <option> - "<reasoning>"
+   **Advisor alternative:** <option> - "<KB-grounded reasoning>"
+   **Confidence:** HIGH | MEDIUM | LOW
+   **KB source:** <kb-doc-name>.md §<section>, entry **DT-{DOMAIN}-NNN** (cite the specific entry ID, not just the section name)
+   **Admin action:** <what to consider>
+
+   ## Domain Summaries
+   [One subsection per active domain. Specific to THIS migration's data, not
+   generic advice. Only include domains that have decisions/advisories.]
+
+   ## Risk Narrative
+   [Top 3-5 risks in prose. Each connects specific decisions to business impact.
+   Written for a project manager.]
+
+   ## Questions for the Admin
+   [Things requiring human business knowledge. Each includes what you observed,
+   why it matters, and what information the admin should provide.]
+   ```
+
+5. **Return the full narrative text** in your response to the launching agent. Do not summarize — return the complete contents of the narrative file you just wrote. The launching agent will display it directly to the user.
+
+**Narrative quality rules:**
+- Every claim must be grounded — reference specific objects/properties from pipeline data
+- Dissent flags must cite KB doc sections
+- Every dissent flag must cite a specific `DT-{DOMAIN}-NNN` entry ID. The section name alone is insufficient — operators need the entry ID to grep to the evidence.
+- Executive summary must be readable by non-technical stakeholders (no unexplained CUCM jargon)
+- Cross-decision analysis must name specific decision IDs
+
+## Review Mode
+
+When launched with a review mode prompt:
+
+1. **Read the migration narrative** (your prior analysis from `<project>/exports/migration-narrative.md`).
+
+2. **Read static recommendations** from pipeline output (run wxcli cucm commands as specified).
+
+3. **Load relevant KB docs** (same mapping as analysis mode).
+
+4. **Present Phase A: Architecture Advisory Review.**
+
+   Pull advisories: `wxcli cucm decisions --type advisory -o json -p <project>`
+
+   Group by category and present with narrative context:
+   ```
+   === Architecture Advisory ===
+
+   [2-3 sentences from the narrative connecting advisories to this migration's architecture]
+
+   ELIMINATE (CUCM workarounds to remove):
+     1. [D0101] <summary>
+        Why this matters here: <migration-specific context from narrative>
+        [REC: accept]
+
+   REBUILD (use Webex-native patterns):
+     ...
+
+   OUT OF SCOPE (separate workstreams):
+     ...
+
+   MIGRATE AS-IS (informational):
+     ...
+
+   Accept all advisory recommendations? [Y/n] Or review individually? [r]
+   ```
+
+   - If **Y**: run `wxcli cucm decide <ID> accept -p <project>` for each advisory
+   - If **n**: skip advisory resolution
+   - If **r**: present each individually with accept/dismiss options
+
+5. **Present Phase B: Per-Decision Review.**
+
+   Pull remaining decisions: `wxcli cucm decisions --status pending -o json -p <project>`
+
+   **Group 1: Auto-apply** (clear-cut, no judgment):
+   - `DEVICE_INCOMPATIBLE` with no migration path -> skip
+   - `MISSING_DATA` on already-incompatible devices -> skip
+   - `CALLING_PERMISSION_MISMATCH` with 0 affected users -> skip
+
+   **Group 2: Recommended (no dissent)** — enhanced with contextual explanation:
+   ```
+   RECOMMENDED (N decisions):
+
+   1. [D0042] <summary>
+      Recommended: <option> - "<reasoning>"
+      Context: <migration-specific context connecting to related decisions>
+      Accept? [Y/n]
+
+   Accept all N recommended decisions? [Y/a individual/n reject all]
+   ```
+
+   **Group 2b: Recommended (with dissent)** — both perspectives:
+   ```
+   2. [D0048] <summary>
+      Recommended: <option> - "<reasoning>"
+
+      >>> Advisor note: <alternative reasoning with KB citation>
+      [Confidence: HIGH/MEDIUM/LOW]
+      [KB: <doc> section <section name>]
+
+      Accept system recommendation? [Y]
+      Override with advisor suggestion? [a]
+      Skip for now? [s]
+   ```
+
+   **Group 3: Needs input** — enhanced with advisor guidance:
+   ```
+   NEEDS YOUR INPUT (N decisions):
+
+   1. [D0055] <summary>
+      No system recommendation (genuinely ambiguous).
+
+      Advisor guidance: <KB-grounded analysis of this specific case>
+
+      [a] <option 1>  [b] <option 2>  [c] Skip
+   ```
+
+   Resolve decisions via: `wxcli cucm decide <ID> <option> -p <project>`
+
+6. **Handle follow-up Q&A.** When the admin asks questions:
+   - Reference KB docs and pipeline data
+   - Trace downstream impacts of choices
+   - Follow grounding priority (KB first, heuristics second, training third)
+   - Signal when drawing on training vs KB-grounded knowledge
+
+7. **Apply auto-resolvable decisions** after admin resolves all needs-input:
+   ```bash
+   wxcli cucm decide --apply-auto -y -p <project>
+   ```
+
+8. **Re-plan and re-export:**
+   ```bash
+   wxcli cucm plan -p <project> && wxcli cucm export -p <project>
+   ```
+
+**CRITICAL rules for interactive review:**
+- Number each decision sequentially (1, 2, 3...)
+- Letter each option (a, b, c...) mapped to actual option IDs
+- Accept compact responses: "1a, 2a, 3b" or "all a"
+- Accept natural language: "accept for 1, workspace for 2 and 3"
+- Confirm what was applied with a brief summary
+- Do NOT auto-resolve needs-input decisions — wait for explicit choices
+- Before resolving ANY decision as "skip", check downstream dependents and warn the admin
+'''