using-platty

name	using-platty
description	Use when any request is about Platty, the Platty CLI, Platty agent skills, project or repository setup, repo/project analysis, static analysis, generated docs, retrieval/search over Platty outputs, epics, business docs, memory, sync, or choosing the right Platty workflow across Codex and Claude Code.

Using Platty Skills

Use this skill as the entry point for Platty CLI and documentation workflows.

Update Preamble

Run this before routing every Platty request:

1. Resolve ../../bin/platty-update-check relative to this SKILL.md.
2. Run bash <resolved-checker-path> platty.
3. If it prints nothing or only JUST_UPGRADED <old> <new>, continue normally.
4. If any output line is UPGRADE_AVAILABLE <old> <new>, update the already installed platty@platty plugin through the active runtime:
   • Codex: run codex plugin marketplace upgrade platty, then verify platty@platty is installed at <new> with codex plugin list --json.
   • Claude Code: run claude plugin marketplace update platty, then claude plugin update platty@platty --scope user, and verify <new> with claude plugin list --json. Version verification compares the installed base version before any + build metadata with <new>.
5. Never install a missing plugin from this preamble. If the marketplace is local, the runtime command fails, or the installed version remains unchanged, report the failed refresh briefly and continue with the currently loaded skill. Do not run direct git pull, reset, stash, or checkout.
6. After a verified update, run bash <resolved-checker-path> platty --mark-upgraded <old>, tell the user to start a new agent session, and stop before platty-cli-router.

The check is enabled by default and uses the same quiet, cached preamble pattern as gstack. PLATTY_PLUGIN_UPDATE_CHECK=0 disables it for local development. The checker updates agent skills only; it never updates the Platty CLI.

Analytics Attribution

The active user-facing workflow owns one fixed allowlisted workflow label for CLI analytics. Prefix every Platty CLI process with PLATTY_INVOCATION_SOURCE=<workflow-label>. Preserve that same label across routed sub-skills, retries, resumes, and commands returned through nextCommand or nextAction.command; reapply the prefix because returned commands contain argv only. Never derive the label from user text, repository data, project names, paths, or other runtime content.

Tool Mapping

Platty skills are runtime-neutral. Codex and Claude Code are equal, first-class execution runtimes — use whichever runtime the user is already working in, and do not switch runtimes to follow a skill.

Skill bodies use runtime-neutral actions such as "read a file", "search files", "run Platty CLI", "track multi-step work", and "dispatch a worker". Runtime-neutral actions keep the shared catalog usable across Codex and Claude Code.

When a runtime-specific tool name appears, translate it through the mapping for the runtime you are working in:

• Codex: references/codex-tools.md
• Claude Code: references/claude-code-tools.md

Both mappings cover the same set of Platty actions. The runtimes differ only in tool surface, not in the Platty CLI command order, JSON inspection rules, approval gates, or document-generation safety rules — keep those identical across runtimes.

Remote MCP retrieval is handled by the separate platty-mcp plugin. This operator plugin does not route MCP retrieval and must not fall back to MCP when a local lifecycle command is unavailable.

Use platty-mcp-server-setup when the user is configuring, starting, validating, exposing, or troubleshooting the Platty context backend that serves direct HTTP MCP at /api/mcp. Use platty-mcp only when the user's runtime already exposes configured Platty MCP tools and the task is read-only retrieval or client registration.

Skill Router

Use platty-cli-router when deciding which Platty root command or skill applies.

Common routes:

• Ordinary non-MCP agent plugin installation for Codex/Claude Code: platty install --json via platty-cli-router
• Installed first end-to-end project journey through repositories, analysis, one LLM approval, and verified SOT output: platty-onboarding
• Human setup workflow and project management dashboard state: platty-setup
• Context-backend MCP server setup, host/port exposure, and /api/mcp validation: platty-mcp-server-setup
• Static analysis progress: platty-static-analysis
• Technical docs target review: platty-docs-target-curation
• Generated technical/product/business outputs: platty-generated-docs
• Generated output synchronization: platty-sync
• SDD product spec and user stories from an idea: platty-sdd-spec
• SDD technical design and tasks from approved spec/stories: platty-sdd-design
• Recording or maintaining human knowledge (why, corrections, constraints) on epics or documents: platty-memory

Core Rules

• Use prd.md -> user_stories.md -> system_design.md -> tasks.md as the canonical SDD artifact sequence. Treat non-canonical legacy filenames only as read-only input aliases, never as names for newly authored output.

• Prefer --json for CLI commands so results can be inspected precisely.

• Start with bare platty setup for human-guided project management. Use Manage current project to inspect repository, analysis, docs, EPIC, business-doc, sync, and active-job state before choosing a workflow action. For agents, inspect with platty setup --json or platty status --project <project> --json, then explain the next action in plain language. Do not ask users to run --json unless debugging machine-readable output.

• Treat public README workflow text as orientation, not as a static command checklist. The CLI owns current state and next-action hints; routed Platty skills own exact command selection, approval gates, stop conditions, and recovery rules.

• Platty CLI state lives in the user-global Platty home by default (~/.platty on macOS/Linux, %APPDATA%\Platty on Windows). PLATTY_HOME overrides that location. The CLI config field projectRoot refers to this state root, not to an analyzed repository.

• Use the installed global platty binary for Platty workflows. If the binary is missing or appears stale (UNKNOWN_COMMAND or UNEXPECTED_ERROR for a command that should exist), stop and report that the global @paradigmshift/platty package needs to be reinstalled or updated. Keep the workflow on the global CLI. Inside the private source checkout, maintainer verification uses the local build, not the global binary:

  node packages/cli/dist/main.js <command> --json
  

  Public/plugin workflow examples still use the installed global platty binary.

• If the shell reports command not found: platty, check command resolution once with command -v platty. If it returns a path, treat it as a transient shell/PATH issue and retry the original Platty command once. If it returns nothing, stop and report the missing global CLI.

• Resolve the project before running project-scoped commands.

• Use platty status --json when the next action is unclear.

• For remote MCP retrieval or client-side MCP registration, use the separate platty-mcp plugin. For context-backend server setup, use platty-mcp-server-setup in this operator plugin.

• For a known active generated-docs stage run, use platty generate-docs status --project <project> --stage <stage> --run-id <run-id> --json as the stable lifecycle check. Read top-level status, taskCountsByStatus, nextAction, and nextCommand.

• Follow nextCommand or nextAction.command from JSON output unless a gate says to pause. Check the top level, data.nextCommand, and data.nextAction. Gate precedence overrides blindly following 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. Preserve returned command arguments verbatim when possible. When reconstructing a command, carry forward --project, --stage, --run-id, existing --provider, and --json if the suggested command omits them.

• Do not use generation skills for retrieval-only questions.

Main-Aligned Public Workflow

For humans, describe the workflow as these stages and start with bare platty setup as the project-management entry point:

setup -> analyze -> targets -> generate-docs

generate-docs includes technical document generation, EPIC draft generation, automatic EPIC confirmation through the returned CLI command, and business-doc generation after confirmation. sync is a separate incremental refresh workflow after source/repository changes and fresh static analysis.

Do not present that stage list as a required shell script. platty setup and platty status surface the next state-derived action.

For agents, inspect state with JSON output and explain the next action in plain language:

1. platty setup --json to inspect setup and current project dashboard state.
2. platty analyze --project <project> --json to converge static analysis.
3. platty targets list --project <project> --json to inspect documentation targets.
4. platty targets deprecate --project <project> --ids <target-id> --json to exclude unwanted targets.
5. platty generate-docs run --project <project> --json to run technical docs and EPIC generation.
6. If the CLI returns epics_confirmation_required, run the returned platty generate-docs confirm-epics ... --json command automatically unless the user explicitly asked to review EPICs before confirmation.
7. Use platty sync static-map --project <project> --json, then platty sync plan/run/confirm ... --json only for incremental refresh after source or repository changes and fresh static analysis.

Internal compatibility commands:

Lower-level platty run, platty docs, platty epics, and platty business-docs commands exist only for internal compatibility, inspection, and recovery. Do not expose them as public workflows or route normal users to them. Use them only when platty-generated-docs explicitly requires a recovery action, a Platty maintainer asks for one, or repo-local debugging requires it.

Compatibility recovery note:

Do not route workflows through the legacy static-analysis confirm root. Compatibility recovery: if a stale global CLI asks for that legacy confirm command, stop and tell the user to reinstall or update the global @paradigmshift/platty package.

Ordinary Agent Plugin Installation

Use platty install --json when the user wants to install or refresh the ordinary non-MCP Platty agent plugin after installing the global CLI. The command detects Codex and Claude Code, installs a missing platty@platty plugin, and updates an existing installation from the registered marketplace. Use --runtime codex, --runtime claude, or --runtime all only when the user or automation needs an explicit target. Start a new agent session after a successful install or refresh so the updated skills are loaded.

The separate platty-mcp plugin is never installed by platty install. Keep MCP client registration and MCP-only skill installation on the separate platty-mcp route.

Project Context Gate

Before any project-scoped command, make the project/repository sequence explicit:

1. If Platty is not initialized, run platty init --json.
2. If no selected project is known, run platty project list --json.
3. If no project exists, guide the user to create one: platty project create "<name>" --description "<description>" --json.
4. If exactly one existing project is the intended target, run platty project use <project-id-or-name> --json.
5. If multiple projects could match, ask the user which project to use. Do not choose one yourself.
6. After selecting a project, inspect repositories with platty repo list --project <project> --json.
7. Only then add repositories with platty repo add <path> --project <project> --branch <branch> --json when the intended analysis branch is known.

Branch rule:

• If the user names an analysis branch, including main, master, develop, or a feature branch, pass it through --branch. Do not rely on the source checkout being on that branch.
• When the user omits the analysis branch, resolve origin/HEAD, then an existing main, then an existing master. Recommend that verified default candidate, normally main or master. If the current branch differs, present it second as an explicit alternative instead. Wait for confirmation, then pass the confirmed value to repo add or repo update as --branch <branch>; never silently register the feature checkout.
• platty analyze uses the repository registration's stored analysis branch and prepares an app-managed worktree from that branch. It does not repair an omitted branch from repo add.
• For an existing registration on the wrong branch, run platty repo update <repo-id-or-name> --branch <branch> --project <project> --json before running analysis again.

Phrase setup guidance as "create or select a project, then register repositories inside that project." A filesystem repository path is never a project selector. Use platty project use for selecting the current project context; do not create a separate "use project" workflow unless the user is explicitly comparing or switching between multiple projects.

Uninstall / Reset

Use platty uninstall --json to inspect what would be removed and get the npm package removal command. The command is a dry run by default. Use platty uninstall --yes --json only when the user explicitly wants to remove the Platty state root (~/.platty or PLATTY_HOME). The global npm package still needs to be removed outside Platty with:

npm uninstall -g @paradigmshift/platty

Operator UX

Follow this communication shape for every Platty workflow. Keep it short, consistent, and easy to scan. The user should always know what work started, what changed, and what to do next.

CLI output is evidence, not the user experience. Do not paste raw Platty JSON or full CLI output by default. Summarize verified CLI state in natural language: what was checked, what that state means, and what the next user decision or agent action is. Preserve exact project selectors, run ids, task ids, document ids, commands, and error codes when they matter for debugging, gates, or handoff.

Use user-facing words in progress and blocker messages. Internal queue terms may appear in commands or JSON, but explain them in plain language:

Internal term	User-facing phrase
lease / leased task	assigned task / task assignment
lease token	task token
lease expired	task assignment expired
lease conflict / invalid lease token	this task is no longer assigned to this worker
no leaseable tasks	no task is currently ready to assign

Start Notice

Before running commands, announce the work with this card:

Platty: starting <workflow>
- Goal: <plain-language task>
- Project: <project selector or "not selected yet">
- Checking: <state to inspect first, or exact command when useful for handoff>
- Next: <one user decision or agent action expected after inspection>

Progress Checkpoint

For long workflows, report only useful deltas after state-changing commands or natural checkpoints:

Platty: progress
- Done: <completed action>
- State: <plain-language summary of verified JSON fields>
- Evidence: <ids, counts, commands, or error codes inspected when useful>
- Next: <one user decision, agent action, or routed skill>

Handoff Card

At pause, stop condition, completion, or context handoff, end with this card:

Platty handoff
- Workflow: <task/workflow name>
- State: <plain-language summary of verified JSON fields, not a guess>
- Evidence: <commands, ids, counts, or error codes inspected; no raw JSON unless debugging>
- Recommended next: <one user decision, command, or skill>
- Blocker: <none, or plain-language blocker with exact error code in parentheses>

Do not bury the next action in prose. If a CLI response includes nextAction, the Recommended next line should use that command or explain the user decision that blocks it. Do not paste raw JSON unless the user is debugging or asks for machine-readable evidence.

Stop Conditions

• A command fails with UNKNOWN_COMMAND or UNEXPECTED_ERROR on the global platty binary: stop and tell the user to reinstall or update the global @paradigmshift/platty package before continuing. Do not invent an alternative command or execution path.
• The shell reports command not found: platty and command -v platty returns no path: stop and report that the global CLI is not available in PATH.
• The shell reports command not found: platty but command -v platty returns a path: retry the same Platty command once. If the retry fails the same way, stop with the exact PATH and resolved binary path as evidence.
• A command fails with PROJECT_AMBIGUOUS: stop and ask the user which project to use. Never pick one of the matches yourself.
• You routed to a skill, followed it, and ended up at the same routing decision with no CLI state change in between: stop re-routing and ask the user, citing the last status --json output.