chore: consolidate slash commands from 26 to 14

[joshsmithxrm]

Summary

• Consolidates 26 slash commands down to 14 for a streamlined workflow
• Adds workflow documentation in .claude/workflows/
• Defines clear human injection points (design, planning, PR review)
• Implements file-based session orchestration (V1)

Command Changes

New Commands

Command	Purpose	Replaces
/design	Design conversation for features	design-session, new-feature
/design-ui	Reference-driven UI design	tui-polish (upstream fix)
/test	Unified testing with auto-detection	fix-tests, test-cli, tui-test, run-integration-local
/spec	Contributor-ready implementation guides	NEW
/setup	New machine setup	setup-ecosystem, setup-terminal

Enhanced Commands

Command	Enhancement
/ship	Now handles CI-fix and bot-comments autonomously
/start-work	Creates session status file for orchestration

Retired Commands (14)

• design-session, new-feature → /design
• fix-tests, test-cli, tui-test, run-integration-local → /test
• pre-pr, debug-ci-failure, review-bot-comments → /ship
• setup-ecosystem, setup-terminal → /setup
• next-work, create-worktree → subsumed by /plan-work
• handoff, retrospective → auto-retrospective (future)
• tui-polish → replaced by /design-ui flow

New Workflow Documentation

Added .claude/workflows/ with process docs:

• parallel-work.md - How orchestration works
• autonomous-session.md - What worker sessions do
• human-gates.md - When to escalate to human
• ui-development.md - Reference-driven UI design process

Human Injection Points

DESIGN PHASE
    /design → human collaborates on what to build

PLANNING PHASE
    /plan-work → human approves work distribution

IMPLEMENTATION PHASE (mostly autonomous)
    └─ GATE: Auth/Security changes → ask before implementing
    └─ GATE: Performance-critical code → ask before implementing

SHIP PHASE (fully autonomous)
    /ship → PR created, CI-fix, bot-comments handled

REVIEW PHASE
    Human reviews PR ← CRITICAL GATE

Follow-Up Issues

• feat: TUI/VS Code Design System #307 - TUI/VS Code Design System
• feat: V2 Orchestration via ppds serve #308 - V2 Orchestration via ppds serve
• feat: Auto-Retrospective Hook #309 - Auto-Retrospective Hook

Test plan

• Verify new commands are discoverable (/design, /test, etc.)
• Verify retired commands no longer appear
• Verify CLAUDE.md shows updated command list
• Verify workflow docs are readable

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello @joshsmithxrm, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request represents a significant effort to refine and optimize the development experience by consolidating and enhancing the available slash commands. The primary goal is to simplify interactions, automate routine tasks, and provide a more structured approach to development through new unified commands and detailed workflow documentation. These changes aim to improve efficiency, reduce manual steps, and ensure clearer communication within the development process.

Highlights

• Command Consolidation: The total number of slash commands has been reduced from 26 to 14, significantly streamlining the developer workflow and reducing cognitive overhead.
• New Unified Commands: Several new commands have been introduced: /design for general feature design, /design-ui for reference-driven UI design, /test for unified testing across unit, TUI, integration, and CLI smoke tests, /spec for generating contributor-ready implementation guides, and /setup for environment setup.
• Enhanced Existing Commands: The /ship command now autonomously handles pre-PR validation, CI fixes, and bot comments, while /start-work creates a session status file to integrate with the new orchestration system.
• New Workflow Documentation: Comprehensive workflow documentation has been added under .claude/workflows/, detailing processes for parallel work, autonomous sessions, human gates, and UI development.
• Defined Human Injection Points: Clear human intervention points have been established for critical stages such as design, planning, and PR review, ensuring human oversight where it matters most.
• File-Based Session Orchestration: A V1 implementation of file-based session orchestration has been introduced, allowing for better management and monitoring of parallel workstreams.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request is an excellent and significant step forward in streamlining the development workflow. The consolidation of 26 slash commands into 14 more powerful and intuitive commands is a great improvement. The new commands like /design, /test, and the enhanced /ship with its autonomous capabilities are particularly impressive. The addition of comprehensive workflow documentation in .claude/workflows/ provides much-needed clarity on the new orchestration model and human-in-the-loop gates. My review found the changes to be well-structured and internally consistent. I have one suggestion regarding the removal of a bash script in the /setup command, which appears to reduce cross-platform support for a developer experience feature.

I am having trouble creating individual review comments. Click here to see my feedback.

.claude/commands/setup-ecosystem.md (160-178)

The bash script for setting up the status line on macOS/Linux has been removed. This drops a useful feature for developers on non-Windows systems who may not use PowerShell as their primary shell. Was this intentional? If cross-platform support is still desired for this feature, it would be beneficial to retain the bash script and the corresponding setup instructions.

[Copilot]

Pull request overview

This PR consolidates 26 slash commands down to 14 for a streamlined workflow, adds comprehensive workflow documentation in .claude/workflows/, and implements file-based session orchestration for parallel work management (V1).

Key Changes:

• Consolidates testing commands (fix-tests, test-cli, tui-test, run-integration-local) into unified /test command with auto-detection
• Merges planning commands (design-session, new-feature) into /design and adds new /design-ui for reference-driven UI design
• Enhances /ship to autonomously handle CI failures and bot comments (absorbing pre-pr, debug-ci-failure, review-bot-comments)
• Introduces session orchestration via status files in ~/.ppds/sessions/ with clear human injection points

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
CLAUDE.md	Updates command reference table to list 14 consolidated commands with references to new workflow documentation
.claude/workflows/ui-development.md	Documents reference-driven UI design process for TUI and VS Code with wireframe-first approach
.claude/workflows/parallel-work.md	Describes file-based session orchestration pattern enabling multiple parallel Claude sessions
.claude/workflows/human-gates.md	Defines when autonomous sessions should escalate to human decision-making (design, security, performance)
.claude/workflows/autonomous-session.md	Documents worker session lifecycle from /start-work through implementation to /ship with PR creation
.claude/commands/test.md	New unified testing command with auto-detection, consolidating 4 previous testing commands
.claude/commands/ship.md	Enhanced to autonomously handle full shipping flow including CI-fix and bot comment resolution
.claude/commands/setup.md	Consolidated setup command absorbing setup-ecosystem and setup-terminal
.claude/commands/start-work.md	Enhanced to create session status files for orchestrator monitoring
.claude/commands/spec.md	New command for generating contributor-ready implementation guides from triaged issues
.claude/commands/design.md	New consolidated design command replacing design-session and new-feature
.claude/commands/design-ui.md	New command for reference-driven UI design with wireframes
.claude/commands/tui-test.md	Removed - functionality absorbed into /test command
.claude/commands/tui-polish.md	Removed - replaced by /design-ui flow
.claude/commands/test-cli.md	Removed - functionality absorbed into /test command
.claude/commands/run-integration-local.md	Removed - functionality absorbed into /test --integration
.claude/commands/fix-tests.md	Removed - functionality absorbed into /test iterative fix loop
.claude/commands/pre-pr.md	Removed - functionality absorbed into /ship
.claude/commands/retrospective.md	Removed - to be replaced by auto-retrospective hook (future)
.claude/commands/handoff.md	Removed - subsumed by session status files
.claude/commands/new-feature.md	Removed - functionality absorbed into /design
.claude/commands/design-session.md	Removed - replaced by /design
.claude/commands/next-work.md	Removed - subsumed by /plan-work
.claude/commands/setup-terminal.md	Removed - functionality absorbed into /setup --terminal
.claude/commands/create-worktree.md	Removed - subsumed by /plan-work

[Copilot]

The reference to /tui-test should be updated to /test --tui since the /tui-test command has been retired and replaced by the unified /test command.

Suggested change

	- Test with `/tui-test`
	- Test with `/test --tui`

[Copilot]

The reference to /pre-pr is outdated since that command has been retired and its functionality absorbed into /ship. Consider removing this table row or updating the description to clarify the historical context.

Suggested change

| `/pre-pr` | Full validation (absorbed into /ship) |

[Copilot]

The gh issue comment <number> --body "<spec content>" pattern is vulnerable to command injection because <spec content> will include untrusted data such as the GitHub issue title and potentially parts of the body. If this content is interpolated directly into a shell command within double quotes, an attacker can craft an issue title/body containing shell metacharacters or command substitutions (e.g., $(...)) to execute arbitrary commands on the developer’s machine when /spec runs. To fix this, avoid inlining the spec text into a shell command string: either pass it to gh via a safe API (arguments array) or --body-file, or ensure all untrusted content is robustly escaped before being used in the shell.

Suggested change

	gh issue comment <number> --body "<spec content>"
	# Save the generated spec to a file, e.g. spec.md, then:
	gh issue comment <number> --body-file spec.md