feat: development process v2 with alignment verification and patterns

[joshsmithxrm]

Summary

• Introduces ADR-0031 documenting Development Process V2 with alignment verification at planning gates
• Adds canonical code patterns in docs/patterns/ for bulk operations, services, TUI panels, CLI commands, and connection pools
• Enhances orchestrator workflow with full lifecycle management (spawn → planning → working → PR → merge)
• Adds /refine-process skill for process improvement based on repeated feedback signals
• Documents the "gates model" for human oversight - review entry/exit gates, not the middle
• Standardizes terminology across all workflow documentation

Test plan

• Build passes with no warnings
• All unit tests pass (9000+ tests across all frameworks)
• Manual review of pattern files for accuracy
• Verify orchestrator changes work with existing sessions

Closes #311

🤖 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 significantly refines the development process by formalizing the interaction between human developers and AI agents. It introduces a more structured approach to planning and review, provides clear code patterns for consistency, and enhances the automation of the development lifecycle. The goal is to improve efficiency, reduce rework, and ensure higher quality output through better alignment and focused human oversight.

Highlights

• Development Process V2: Introduces a new development process (ADR-0031) that emphasizes alignment verification during the planning phase, aiming to catch misunderstandings early.
• Canonical Code Patterns: Adds a new docs/patterns/ directory containing standardized code examples for common operations such as bulk operations, service layers, TUI panels, CLI commands, and connection pooling.
• Enhanced Orchestrator Workflow: Expands the orchestrator's lifecycle management to cover the full development process, from spawning workers and planning to PR creation, merging, and automated post-approval mechanics.
• Process Refinement Skill: A new /refine-process command is introduced, enabling iterative improvement of the development workflow based on observed signals and feedback.
• Gates Model for Oversight: Defines a 'Zen Model' for human oversight, advocating for review at critical entry and exit gates (plan review, PR review) rather than continuous monitoring of autonomous work.
• Standardized Terminology: Establishes a shared vocabulary for human-AI collaboration through a new terminology.md document, clarifying concepts like sessions, agents, and issue lifecycles.
• Improved PR Review Agent: Enhances the bot comment review process by introducing structured categories (MUST FIX, SHOULD FIX, CONSIDER, FILTERED) to reduce noise and streamline human review of automated feedback.

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 introduces a significant overhaul of the development process, codenamed V2. It adds a new ADR (ADR-0031) to document the process, which includes alignment verification through structured planning and the introduction of canonical code patterns. The orchestrator workflow is enhanced to cover the full development lifecycle, and a new /refine-process command is added for continuous improvement. My review focuses on ensuring consistency across the new documentation and correctness in the new code patterns. I've found some inconsistencies in terminology definitions across several new documents and a couple of bugs in the bulk operations code pattern. Overall, this is a fantastic set of improvements for standardizing and scaling development.

[Copilot]

Pull request overview

This PR introduces Development Process V2, a comprehensive framework for human-AI collaboration focused on alignment verification at planning gates and canonical code patterns. It adds ADR-0031 to document the process decisions, creates five pattern files demonstrating architectural standards, enhances the orchestrator workflow with full lifecycle management, and standardizes terminology across all workflow documentation.

Changes:

• Adds ADR-0031 documenting Development Process V2 with the "gates model" for human oversight
• Creates canonical code patterns in docs/patterns/ for bulk operations, services, TUI panels, CLI commands, and connection pools
• Enhances orchestrator and worker workflows with planning verification, PR lifecycle management, and Review Agent integration
• Introduces /refine-process command for iterative process improvement based on repeated feedback signals

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
docs/adr/0031_DEVELOPMENT_PROCESS_V2.md	Documents the Development Process V2 with alignment verification, gates model, and meta-monitoring
docs/patterns/bulk-operations.cs	Pattern for parallel bulk operations with connection pool usage
docs/patterns/service-pattern.cs	Pattern for service layer with IProgressReporter and PpdsException
docs/patterns/connection-pool-pattern.cs	Pattern for connection pool acquisition in parallel loops
docs/patterns/cli-command-pattern.cs	Pattern for CLI commands with output routing and exception handling
docs/patterns/tui-panel-pattern.cs	Pattern for TUI panels with Terminal.Gui layout and async updates
.claude/workflows/terminology.md	Defines shared vocabulary for sessions, agents, lifecycle, and gates
.claude/workflows/autonomous-session.md	Adds required plan structure for alignment verification
.claude/commands/start-work.md	Updates to require pattern citations in worker plans
.claude/commands/orchestrate.md	Enhances with full PR lifecycle including post-approval mechanics
.claude/commands/review-bot-comments.md	Updates with Review Agent categorization framework
.claude/commands/refine-process.md	New command for lightweight process refinement
CLAUDE.md	Adds rules requiring plan citations and scope boundaries