Skip to content

Commit c7302cf

Browse files
joshsmithxrmclaude
joshsmithxrm
and
claude
committed
feat: development process v2 with alignment verification and patterns
Process engineering overhaul for parallel orchestration: - Add docs/patterns/ with 5 canonical code examples (bulk ops, services, TUI, CLI, connection pooling) - Add required plan structure for alignment verification at planning phase - Enhance /orchestrate with full lifecycle (spawn → merge), dashboard view - Add /refine-process command for meta-monitoring signals - Create ADR-0031 documenting process decisions - Add terminology.md with shared vocabulary (sessions, agents, states) - Enhance /review-bot-comments with Review Agent categorization - Add GitHub labels: needs-design, designed, ready, in-progress, pr-ready, blocked - Update CLAUDE.md with plan citation and scope boundary rules Key principle: verify alignment at planning (cheap), not PR review (expensive). The Zen Model: monitor gates (entry/exit), not the autonomous zone. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 7aeca4e commit c7302cf

13 files changed

+1725
-20
lines changed

‎.claude/commands/orchestrate.md‎

Lines changed: 120 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -197,17 +197,128 @@ ppds session cancel 123 --keep-worktree
197197
## Session Lifecycle
198198

199199
```
200-
REGISTERED -> WORKING -> [STUCK|PAUSED] -> COMPLETE|CANCELLED
200+
REGISTERED -> PLANNING -> PLANNING_COMPLETE -> WORKING -> PR_READY -> MERGING -> COMPLETE
201+
| | |
202+
↓ ↓ ↓
203+
STUCK STUCK STUCK
201204
```
202205

203-
| State | Meaning |
204-
|-------|---------|
205-
| `registered` | Worktree created, worker starting |
206-
| `working` | Actively implementing, code changing |
207-
| `stuck` | Hit domain gate or repeated failure, needs human guidance |
208-
| `paused` | Human requested pause, worker idle |
209-
| `complete` | PR created and CI passed |
210-
| `cancelled` | Human cancelled, worktree cleaned up |
206+
| State | Meaning | Your Action |
207+
|-------|---------|-------------|
208+
| `registered` | Worktree created, worker starting | None |
209+
| `planning` | Exploring codebase, creating plan | None |
210+
| `planning_complete` | Plan ready for review | Review plan, approve or redirect |
211+
| `working` | Actively implementing | None |
212+
| `stuck` | Blocked, needs guidance | Provide guidance |
213+
| `pr_ready` | PR created, awaiting review | Review PR |
214+
| `merging` | PR approved, handling rebase/CI | None |
215+
| `complete` | PR merged | None |
216+
| `paused` | Human requested pause | Resume when ready |
217+
| `cancelled` | Human cancelled, cleaned up | None |
218+
219+
## PR Review Flow
220+
221+
When a session shows `pr_ready`:
222+
223+
1. **Review PR:**
224+
```bash
225+
ppds session get <id>
226+
```
227+
Shows PR URL, files changed, and Review Agent summary (if available).
228+
229+
2. **If PR looks good:**
230+
- Say "approve 123" to approve
231+
- Orchestrator handles rebase and merge mechanics
232+
233+
3. **If changes needed:**
234+
- Say "changes 123 'need better error handling'"
235+
- Worker resumes to make changes
236+
237+
## Post-Approval Mechanics
238+
239+
After you approve a PR, the orchestrator handles:
240+
241+
1. **Update branch with main:**
242+
```bash
243+
gh pr update-branch <pr-number>
244+
```
245+
- If conflict → worker resolves, back to PR review
246+
247+
2. **Wait for CI:**
248+
- If pass → continue to merge
249+
- If fail → worker fixes, back to PR review
250+
251+
3. **Merge PR:**
252+
```bash
253+
gh pr merge <pr-number> --squash
254+
```
255+
256+
4. **Cleanup:**
257+
- Mark session complete
258+
- Worktree queued for `/prune`
259+
260+
**Key principle:** You review CODE. Orchestrator handles MECHANICS.
261+
262+
## Commands (Complete Reference)
263+
264+
| User Says | Action |
265+
|-----------|--------|
266+
| **Planning Phase** | |
267+
| "list issues" / "what's open?" | Show issues, bugs first |
268+
| "show 123" / "what's 123?" | Show issue details |
269+
| "plan 123" | Analyze issue, discuss approach |
270+
| **Worker Spawning** | |
271+
| "spawn 123" / "work on 123" | Create worktree, spawn worker |
272+
| "spawn 123, 124, 125" | Batch spawn |
273+
| **Status & Monitoring** | |
274+
| "status" / "dashboard" | Show all workers, PRs, stuck items |
275+
| "check 123" | Detailed status for one session |
276+
| **Plan Review** | |
277+
| "approve plan 123" | Worker proceeds to implementation |
278+
| "redirect 123 'use X instead'" | Worker re-plans with feedback |
279+
| **PR Review** | |
280+
| "review 123" | Show PR, Review Agent summary |
281+
| "approve 123" | Orchestrator handles merge mechanics |
282+
| "changes 123 'feedback'" | Worker resumes with your feedback |
283+
| **Problem Resolution** | |
284+
| "resolve 123" | Open stuck item for resolution |
285+
| "tell 123: 'guidance'" | Forward guidance to worker |
286+
| **Session Control** | |
287+
| "pause 123" | Pause worker |
288+
| "resume 123" | Resume paused worker |
289+
| "cancel 123" | Cancel and cleanup |
290+
291+
## Dashboard View
292+
293+
When showing status, present a dashboard like:
294+
295+
```
296+
┌─────────────────────────────────────────────────────────────────┐
297+
│ ORCHESTRATOR STATUS │
298+
├─────────────────────────────────────────────────────────────────┤
299+
│ WORKERS (3 active) │
300+
│ ├── #123 data-export [working] ████████░░ 80% │
301+
│ ├── #124 plugin-deploy [planning] ██░░░░░░░░ 20% │
302+
│ └── #125 tui-refresh [working] ██████░░░░ 60% │
303+
│ │
304+
│ NEEDS PLAN REVIEW (1) │
305+
│ └── #126 auth-refactor Plan ready - "approve plan 126" │
306+
│ │
307+
│ READY FOR PR REVIEW (2) │
308+
│ ├── PR #45 → #120 Review: 1 must-fix, 2 filtered │
309+
│ └── PR #46 → #121 Review: clean │
310+
│ │
311+
│ MERGING (1) │
312+
│ └── PR #44 → #119 rebasing... CI running... │
313+
│ │
314+
│ STUCK (1) │
315+
│ └── #122 auth-flow [merge conflict on PR #43] │
316+
│ │
317+
│ COMPLETED TODAY (2) │
318+
│ ├── #118 → merged 10:32am │
319+
│ └── #117 → merged 09:15am │
320+
└─────────────────────────────────────────────────────────────────┘
321+
```
211322

212323
## Resilience
213324

‎.claude/commands/refine-process.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Refine Process
2+
3+
Lightweight process refinement when signals indicate the workflow needs adjustment.
4+
5+
## When to Use
6+
7+
Run this command when you observe these signals appearing 3+ times:
8+
9+
| Signal | Indicates |
10+
|--------|-----------|
11+
| Workers frequently stuck at same point | Workflow gap or unclear handoff |
12+
| PRs need major rework after review | Design phase inadequate |
13+
| You check on workers frequently | Trust not calibrated |
14+
| Claude does unexpected things | Terminology/expectation mismatch |
15+
| Context-switching more than expected | Session boundaries wrong |
16+
| Same feedback given on multiple PRs | Missing pattern or rule |
17+
18+
Also run after major milestones (e.g., v1 shipped) or when you feel friction but can't name it.
19+
20+
## Usage
21+
22+
`/refine-process`
23+
24+
No arguments. This command guides a conversational review.
25+
26+
## Process
27+
28+
### 1. Collect Signals
29+
30+
Review recent work to identify friction:
31+
32+
```bash
33+
# Recent PRs and their review cycles
34+
gh pr list --state merged --limit 10 --json number,title,reviews
35+
36+
# Recent stuck sessions
37+
ppds session list --status stuck --json
38+
39+
# Recent issues that had scope problems
40+
gh issue list --label blocked --state closed --limit 5
41+
```
42+
43+
### 2. Categorize Findings
44+
45+
| Category | Examples | Fix Type |
46+
|----------|----------|----------|
47+
| **Pattern gap** | Same code feedback 3x | Add to `docs/patterns/` |
48+
| **Rule gap** | Claude keeps doing X | Add to CLAUDE.md |
49+
| **Workflow gap** | Workers stuck at same point | Update workflow doc |
50+
| **Terminology gap** | Claude misinterprets term | Add to terminology.md |
51+
| **Gate calibration** | Too tight or loose oversight | Adjust gate criteria |
52+
53+
### 3. Propose Changes
54+
55+
For each identified gap, propose a minimal fix:
56+
57+
**Pattern gap:**
58+
```markdown
59+
Add `docs/patterns/example-pattern.cs`:
60+
- Demonstrates: [what]
61+
- Related: [ADRs]
62+
- Source: [existing code to extract]
63+
```
64+
65+
**Rule gap:**
66+
```markdown
67+
Add to CLAUDE.md NEVER/ALWAYS:
68+
| Rule | Why |
69+
```
70+
71+
**Workflow gap:**
72+
```markdown
73+
Update `.claude/workflows/[file].md`:
74+
- Section: [which]
75+
- Change: [what to add/modify]
76+
```
77+
78+
### 4. Apply Changes
79+
80+
After discussion and approval:
81+
1. Make the changes
82+
2. Test with one issue to verify improvement
83+
3. Monitor for the signal to stop appearing
84+
85+
## Output
86+
87+
At the end of refinement, summarize:
88+
89+
```
90+
## Process Refinement Summary
91+
92+
### Signals Observed
93+
- [Signal 1]: appeared X times
94+
- [Signal 2]: appeared Y times
95+
96+
### Changes Made
97+
1. Added pattern: `docs/patterns/X.cs`
98+
2. Added CLAUDE.md rule: "Never do Y"
99+
3. Updated workflow: added Z section
100+
101+
### Verification Plan
102+
- [ ] Test with issue #NNN
103+
- [ ] Monitor for 5 PRs
104+
- [ ] Check if signal stops
105+
```
106+
107+
## Related
108+
109+
- [Meta-Monitoring](../workflows/terminology.md#115-meta-monitoring)
110+
- [Trust Calibration](../workflows/terminology.md#117-trust-calibration)

‎.claude/commands/review-bot-comments.md‎

Lines changed: 46 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,40 @@
1-
# Review Bot Comments
1+
# Review Bot Comments (Review Agent)
22

3-
Systematically address PR review comments from Copilot, Gemini, and CodeQL.
3+
Filter, categorize, and address PR review comments from Copilot, Gemini, and CodeQL.
44

55
## Usage
66

77
`/review-bot-comments [pr-number]`
88

9+
## Review Agent Categories
10+
11+
The goal is to reduce noise. Categorize each finding:
12+
13+
| Category | Meaning | Your Action | Examples |
14+
|----------|---------|-------------|----------|
15+
| **MUST FIX** | Security issues, bugs, breaking changes | Fix before merge | SQL injection, null dereference, resource leak |
16+
| **SHOULD FIX** | Pattern violations, quality issues | Fix or justify | Missing Dispose, generic catch, unused code |
17+
| **CONSIDER** | Suggestions, minor improvements | Optional | Style preferences, LINQ alternatives |
18+
| **FILTERED** | Style noise, false positives | Ignored | Wrong suggestions, preference-only |
19+
20+
**Output summary format:**
21+
```
22+
## Review Agent Summary - PR #XX
23+
24+
MUST FIX (1):
25+
- [CodeQL] Foo.cs:42 - SQL injection vulnerability
26+
27+
SHOULD FIX (2):
28+
- [Copilot] Bar.cs:10 - Resource not disposed
29+
- [Gemini] Baz.cs:25 - Generic catch clause
30+
31+
CONSIDER (1):
32+
- [Copilot] Qux.cs:5 - Could use LINQ expression
33+
34+
FILTERED (25):
35+
- Style preferences, false positives - see details below if needed
36+
```
37+
938
## Process
1039

1140
### 1. Fetch All Bot Findings
@@ -49,14 +78,21 @@ Autofix suggestions are NOT PR comments - they require different handling:
4978

5079
### 2. Triage Each Comment
5180

52-
For each bot comment, determine verdict and rationale:
53-
54-
| Verdict | Meaning |
55-
|---------|---------|
56-
| **Valid** | Bot is correct, code should be changed |
57-
| **False Positive** | Bot is wrong, explain why |
58-
| **Duplicate** | Same issue reported by another bot - still needs reply |
59-
| **Unclear** | Need to investigate before deciding |
81+
For each bot comment, categorize using Review Agent categories:
82+
83+
| Category | Criteria |
84+
|----------|----------|
85+
| **MUST FIX** | Security vulnerabilities, actual bugs, data loss risk, breaking changes |
86+
| **SHOULD FIX** | Pattern violations, quality issues (resource leaks, generic catch, unused code) |
87+
| **CONSIDER** | Valid suggestions that are optional (LINQ alternatives, naming) |
88+
| **FILTERED** | False positives, style-only, duplicate of higher-severity finding |
89+
90+
**Categorization rules:**
91+
- CodeQL security findings → usually MUST FIX
92+
- Resource disposal → SHOULD FIX (verify interface first)
93+
- "Use LINQ" suggestions → usually CONSIDER or FILTERED
94+
- Style preferences → FILTERED
95+
- Duplicate findings (same file+line) → keep highest severity, mark others FILTERED
6096

6197
**IMPORTANT:** Every comment needs a reply, including duplicates. Track all comment IDs to ensure none are missed.
6298

‎.claude/commands/start-work.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,29 @@ Output the generated session prompt content.
102102

103103
Use the EnterPlanMode tool to begin planning.
104104

105+
**Required Plan Structure** (see [autonomous-session.md](../workflows/autonomous-session.md)):
106+
107+
Your plan MUST include these sections:
108+
109+
1. **My Understanding** - Restate the issue in your own words
110+
2. **Patterns I'll Follow** - Cite specific ADRs and pattern files:
111+
- `docs/patterns/bulk-operations.cs` - For multi-record operations
112+
- `docs/patterns/service-pattern.cs` - For Application Services
113+
- `docs/patterns/tui-panel-pattern.cs` - For TUI development
114+
- `docs/patterns/cli-command-pattern.cs` - For CLI commands
115+
- `docs/patterns/connection-pool-pattern.cs` - For Dataverse connections
116+
3. **Approach** - Implementation steps
117+
4. **What I'm NOT Doing** - Explicit scope boundaries
118+
5. **Questions Before Proceeding** - If any
119+
120+
**Example citation:**
121+
```
122+
Following the service layer pattern (docs/patterns/service-pattern.cs):
123+
- Accepting IProgressReporter for long operations
124+
- Throwing PpdsException with ErrorCode
125+
- Registering in AddCliApplicationServices()
126+
```
127+
105128
## Output Format
106129

107130
```

0 commit comments

Comments
 (0)