| name | platty-cli-router |
| description | Use when deciding which Platty CLI root command, project workflow, repository workflow, analysis workflow, document workflow, or Platty skill should handle a request. |
Platty CLI Router
Use this before choosing a Platty command when the user asks what to run next or asks broadly about Platty CLI workflows.
Default Order
setup -> analyze -> targets -> generate-docs
When project context is missing, route to platty-setup first. The user must
create or select a project before registering repositories, and repositories
must be registered inside that selected project.
Root Commands
Local, MCP-free retrieval and search over the exported SOT projection belongs to
platty-retrieval: reading ~/.platty/sot/<projectId>/, platty sot resolve/glossary search, platty graph trace, and platty code search/snippet.
Route "find/what/where/how does it work/search the codebase" questions there.
Remote read-only MCP retrieval is different: it belongs to the separate
platty-mcp plugin. Do not route MCP workflows through this operator router.
Context-backend server setup, host/port exposure, and /api/mcp validation stay
in platty-mcp-server-setup.
| Need | Command or skill |
|---|
| Answer a question about the analyzed codebase locally (domain terms, epics, docs, specs, code locations, source confirmation) | platty-retrieval (read SOT projection + platty sot resolve/glossary search, graph trace, code search/snippet) |
| Install or refresh ordinary Platty agent skills (non-MCP agent plugin) | platty install --json; restart the agent session after success; MCP installation stays separate |
| Installed first end-to-end project journey through repositories, analysis, LLM approval, and SOT output | platty-onboarding |
Initialize global Platty home (~/.platty or PLATTY_HOME) | platty init via platty-setup |
| Create/select a project | platty project ... via platty-setup |
| Register repositories | platty repo ... via platty-setup |
| Ask "what next?" | Human: platty setup; agent: platty setup --json or platty status --json via platty-setup |
| Run static analysis | platty analyze --project <project> --json via platty-static-analysis |
| Inspect/cancel pipeline runs | platty runs ... --json via platty-static-analysis |
| Curate technical targets | platty targets ... --project <project> --json via platty-docs-target-curation |
| Generated technical/product/business outputs | platty generate-docs run --project <project> --json via platty-generated-docs |
| EPIC confirmation and business-doc continuation | returned platty generate-docs confirm-epics --project <project> --run-id <run-id> --json via platty-generated-docs |
| Check active generated-docs stage status | platty generate-docs status --project <project> --stage <stage> --run-id <run-id> --json via platty-generated-docs |
| Recover failed generated docs | Inspect/recover through platty-generated-docs; use retry-failed for the failed build_docs, build_epics, or build_business_docs stage |
| Retry failed generated-docs tasks | platty generate-docs retry-failed --project <project> --stage <stage> --run-id <run-id> --json via platty-generated-docs |
| Configure or troubleshoot context-backend MCP server | platty-mcp-server-setup via using-platty |
| Continue despite failed docs | Explain repair-first policy via platty-generated-docs; do not invent --force |
| Incrementally refresh existing generated outputs after source/repository changes | platty sync static-map/plan/run/confirm --project <project> --json via platty-sync |
| Turn a rough idea into prd.md and user_stories.md | platty-sdd-spec |
| Create system_design.md and tasks.md from approved SDD docs | platty-sdd-design |
| Record/update/remove human knowledge on epics or docs | platty memory ... --json via platty-memory |
| Uninstall or reset local Platty state | platty uninstall --json; use --yes only with explicit confirmation |
Invariants
1. If CLI output includes `nextCommand` or `nextAction.command` at the top
level or under `data`, that command is the next step unless a gate says to
pause. Gate precedence overrides returned commands for malformed or missing
EPIC confirmation commands, incomplete target review, failed generated-docs
recovery, active generated-output work before sync, or recovery that must
preserve an existing run.
2. Preserve returned command arguments verbatim when possible. When
reconstructing, carry forward `--project`, `--stage`, `--run-id`, existing
`--provider`, and `--json` if the returned command omits them.
3. Static analysis no longer has a public `confirm` step. Compatibility note:
if a global CLI asks for compatibility recovery command `platty confirm`, treat it as stale and ask for CLI
reinstall or update of the global @paradigmshift/platty package.
4. The filesystem state root is the global Platty home, not cwd and not the
repository path. The CLI config field `projectRoot` names that state root.
5. `project use` selects the current Platty project context. It is not a
separate workflow skill; route it through `platty-setup`.
6. Do not invent confirmation gates. Target review is handled by
`platty targets ... --project <project> --json`; generated outputs start
with `platty generate-docs run --project <project> --json`; when the CLI
returns a concrete `generate-docs confirm-epics` or `sync confirm` command,
run that returned command automatically unless the user explicitly requested
manual review.
Routing UX
When choosing a route, produce a one-screen answer:
Platty: routing
- Goal: <what the user is trying to do>
- Route: <skill name>
- First check: <exact platty command>
- Recommended next: <skill, nextCommand, or nextAction.command>
If routing stops, include a Platty handoff card from using-platty with the
exact error code or repeated nextAction that caused the stop.
Stop Conditions
- Following the same
nextCommand or nextAction.command twice in a row with
no other state change: stop routing — this is a stalled loop; switch to the
routed skill's Stop Conditions instead of re-running the command a third time.
- A command from the table fails with
UNKNOWN_COMMAND or UNEXPECTED_ERROR: stop and report that the installed global CLI may be stale or the command may not exist. Reinstall or update the global @paradigmshift/platty package before continuing; do not substitute a guessed command or execution path.
- If the shell reports
command not found: platty, run command -v platty once. Retry the original command once only if a binary path is returned; otherwise stop and report that the global CLI is missing from PATH.
- A command fails with
PROJECT_AMBIGUOUS or PROJECT_NOT_FOUND and no nextAction resolves it: stop and ask the user for the project instead of guessing a selector.
