[P0] Add commit counter to orchestrator prompt

[rjmurillo-bot]

Context

PR #908 exceeded 20-commit limit by 3× (59 commits) without agent awareness. Limit was invisible until violated.

Problem Statement

No visibility into commit count during session:

• Agents don't know how many commits accumulated
• ADR-008 limit (20 commits) is invisible
• Violations discovered only when it's too late

Proposed Solution

Modify orchestrator to:

1. Run git rev-list --count HEAD ^origin/main after each commit
2. Display as "Commit X/20 (ADR-008)" in session output
3. Warn when approaching limit (≥15 commits)
4. Block at limit (≥20 commits, suggest squash)

Acceptance Criteria

• Commit counter runs automatically after each commit
• Format: "Commit X/20 (ADR-008)"
• Warning at 15+ commits
• Blocking error at 20+ commits with remediation guidance
• Works for all agents (orchestrator, implementer, etc.)

Effort Estimate

2 hours

Priority

P0 - Critical (This Week)

Related

• Issue feat(workflow): auto-flag PRs exceeding commit threshold #362 (commit count governance)
• Issue [P0] Create pre-PR validation script (Validate-PRReadiness.ps1) #934 (pre-PR validation script)
• PR feat(skill): add reflect skill and auto-learning hook #908 (59 commits, 3× over limit)
• ADR-008 (20-commit limit)
• Root Cause: Governance Without Enforcement

References

.agents/retrospective/2026-01-15-pr-908-comprehensive-retrospective.md (lines 1263-1267)

[traycerai]

Plan

Observations

The codebase uses a multi-agent architecture with orchestrator, implementer, and other specialized agents. Agent prompts are organized in a template-based structure with shared templates in file:templates/agents/ that are instantiated for different platforms (Claude, GitHub Copilot, VS Code). The repository enforces a 20-commit limit per PR (documented in file:CONTRIBUTING.md lines 374-414) with warnings at 10 and 15 commits, and blocking at 20. Currently, this limit is only enforced at PR time via GitHub workflows, not during active sessions. The codebase uses PowerShell-based PreToolUse hooks for enforcement (per ADR-005), with existing patterns in file:.claude/hooks/PreToolUse/ for branch protection, session logging, and ADR review guards.

Approach

The solution adds commit counter visibility to agent prompts by inserting instructions to run git rev-list --count HEAD ^origin/main after each commit and display the result in a standardized format. This will be implemented in the shared orchestrator and implementer templates, which propagate to all platform-specific variants. The counter will include warning thresholds (≥15 commits) and blocking guidance (≥20 commits) with remediation steps. A PostToolUse hook will be created to automatically display the counter after git commit operations, ensuring consistent enforcement across all agents without requiring manual invocation.

Implementation Steps

1. Update Shared Orchestrator Template

File: file:templates/agents/orchestrator.shared.md

Add a new section after the "Execution Style" section (around line 127) titled "Commit Counter Protocol":

• Instruct orchestrator to run git rev-list --count HEAD ^origin/main after each commit
• Display format: "Commit X/20 (ADR-008)" where X is the count
• Add warning logic: if count ≥15, display warning message suggesting to consider squashing or splitting work
• Add blocking logic: if count ≥20, display error message with remediation guidance (squash commits using git rebase -i HEAD~N or split into multiple PRs)
• Reference CONTRIBUTING.md commit thresholds section
• Include example output showing the counter display

2. Update Shared Implementer Template

File: file:templates/agents/implementer.shared.md

Add similar commit counter instructions in the "Commit Message Format" section (around line 437):

• Same git command and display format as orchestrator
• Emphasize that implementer must check counter after each atomic commit
• Include the same warning and blocking thresholds
• Add to the "Pre-PR Validation Gate" checklist (around line 449) a new item: "Commit count verified (≤20 commits per ADR-008)"

3. Create PostToolUse Hook for Automatic Counter Display

File: file:.claude/hooks/PostToolUse/Show-CommitCounter.ps1

Create a new PowerShell hook that:

• Triggers after git commit commands (matcher: Bash(git commit*))
• Runs git rev-list --count HEAD ^origin/main to get commit count
• Handles edge cases: no origin/main branch (use HEAD count), detached HEAD, not a git repo
• Formats output as "Commit X/20 (ADR-008)"
• Adds warning emoji/indicator at ≥15 commits with message: "WARNING: Approaching commit limit. Consider squashing or splitting work."
• Adds blocking emoji/indicator at ≥20 commits with message: "BLOCKED: Exceeded commit limit. MUST squash commits or split PR. See CONTRIBUTING.md."
• Returns exit code 0 (informational only, does not block)
• Includes error handling with fail-open behavior (don't break commits on infrastructure issues)

4. Update Hook Utilities Module

File: file:.claude/hooks/Common/HookUtilities.psm1

Add helper function Get-CommitCount:

• Accepts optional base branch parameter (default: origin/main)
• Returns commit count or -1 on error
• Handles fallback scenarios (no remote, detached HEAD)
• Includes proper error handling and logging

5. Update SESSION-PROTOCOL.md

File: file:.agents/SESSION-PROTOCOL.md

Add commit counter requirement to "Session End Protocol" Phase 3 (around line 434):

• Add SHOULD requirement: "The agent SHOULD verify commit count before ending session"
• Add to Session End Checklist (around line 494): "SHOULD | Verify commit count ≤20 | [ ] | Count: X/20"
• Reference ADR-008 and CONTRIBUTING.md commit thresholds
• Include guidance on what to do if approaching or exceeding limit

6. Update Platform-Specific Agent Files

Regenerate platform-specific agent files from shared templates:

Orchestrator files:

• file:.claude/agents/orchestrator.md
• file:src/claude/orchestrator.md
• file:.github/agents/orchestrator.agent.md
• file:src/copilot-cli/orchestrator.agent.md
• file:src/vs-code-agents/orchestrator.agent.md

Implementer files:

• file:.claude/agents/implementer.md
• file:src/claude/implementer.md
• file:.github/agents/implementer.agent.md
• file:src/copilot-cli/implementer.agent.md
• file:src/vs-code-agents/implementer.agent.md

Ensure all platform-specific files include the commit counter protocol from their respective shared templates.

7. Update CONTRIBUTING.md

File: file:CONTRIBUTING.md

Enhance the "Commit Count Thresholds" section (around line 374):

• Add note that agents now display commit counter automatically after each commit
• Reference the PostToolUse hook that provides real-time feedback
• Clarify that the 20-commit limit is now visible during sessions, not just at PR time
• Add example of what agents will display when approaching/exceeding limits

8. Create Documentation for Commit Counter Feature

File: file:.agents/architecture/commit-counter-implementation.md

Document the implementation:

• Problem statement (PR feat(skill): add reflect skill and auto-learning hook #908 exceeded limit without awareness)
• Solution architecture (PostToolUse hook + agent prompt updates)
• How it works (git rev-list command, threshold logic)
• Integration points (orchestrator, implementer, hooks)
• Testing approach (manual verification, edge cases)
• Maintenance notes (updating thresholds, adding new agents)

Verification Steps

1. Test PostToolUse hook manually by making a commit and verifying counter displays
2. Verify counter shows correct count relative to origin/main
3. Test warning threshold (create 15+ commits on a branch)
4. Test blocking threshold (create 20+ commits on a branch)
5. Test edge cases: no origin/main, detached HEAD, not a git repo
6. Verify all platform-specific agent files include commit counter instructions
7. Confirm SESSION-PROTOCOL.md checklist includes commit count verification
8. Validate that agents reference the counter in their session logs

Mermaid Diagram

sequenceDiagram
    participant Agent as Agent (Orchestrator/Implementer)
    participant Git as Git Repository
    participant Hook as PostToolUse Hook
    participant User as User/Session Log

    Agent->>Git: git commit -m "message"
    Git-->>Agent: Commit successful
    Git->>Hook: Trigger PostToolUse hook
    Hook->>Git: git rev-list --count HEAD ^origin/main
    Git-->>Hook: Return count (e.g., 12)
    
    alt Count < 15
        Hook->>User: Display "Commit 12/20 (ADR-008)"
    else Count >= 15 and < 20
        Hook->>User: Display "⚠️ Commit 16/20 (ADR-008)<br/>WARNING: Approaching limit"
    else Count >= 20
        Hook->>User: Display "🚫 Commit 21/20 (ADR-008)<br/>BLOCKED: Must squash or split"
    end
    
    Agent->>User: Document commit count in session log
    Agent->>Agent: Check if approaching limit
    
    alt Count >= 20
        Agent->>User: Suggest remediation:<br/>- git rebase -i HEAD~N<br/>- Split into multiple PRs
    end

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase uses a multi-agent architecture with orchestrator, implementer, and other specialized agents. Agent prompts are organized in a template-based structure with shared templates in `file:templates/agents/` that are instantiated for different platforms (Claude, GitHub Copilot, VS Code). The repository enforces a 20-commit limit per PR (documented in `file:CONTRIBUTING.md` lines 374-414) with warnings at 10 and 15 commits, and blocking at 20. Currently, this limit is only enforced at PR time via GitHub workflows, not during active sessions. The codebase uses PowerShell-based PreToolUse hooks for enforcement (per ADR-005), with existing patterns in `file:.claude/hooks/PreToolUse/` for branch protection, session logging, and ADR review guards.

## Approach

The solution adds commit counter visibility to agent prompts by inserting instructions to run `git rev-list --count HEAD ^origin/main` after each commit and display the result in a standardized format. This will be implemented in the shared orchestrator and implementer templates, which propagate to all platform-specific variants. The counter will include warning thresholds (≥15 commits) and blocking guidance (≥20 commits) with remediation steps. A PostToolUse hook will be created to automatically display the counter after git commit operations, ensuring consistent enforcement across all agents without requiring manual invocation.

## Implementation Steps

### 1. Update Shared Orchestrator Template

**File**: `file:templates/agents/orchestrator.shared.md`

Add a new section after the "Execution Style" section (around line 127) titled "Commit Counter Protocol":

- Instruct orchestrator to run `git rev-list --count HEAD ^origin/main` after each commit
- Display format: "Commit X/20 (ADR-008)" where X is the count
- Add warning logic: if count ≥15, display warning message suggesting to consider squashing or splitting work
- Add blocking logic: if count ≥20, display error message with remediation guidance (squash commits using `git rebase -i HEAD~N` or split into multiple PRs)
- Reference CONTRIBUTING.md commit thresholds section
- Include example output showing the counter display

### 2. Update Shared Implementer Template

**File**: `file:templates/agents/implementer.shared.md`

Add similar commit counter instructions in the "Commit Message Format" section (around line 437):

- Same git command and display format as orchestrator
- Emphasize that implementer must check counter after each atomic commit
- Include the same warning and blocking thresholds
- Add to the "Pre-PR Validation Gate" checklist (around line 449) a new item: "Commit count verified (≤20 commits per ADR-008)"

### 3. Create PostToolUse Hook for Automatic Counter Display

**File**: `file:.claude/hooks/PostToolUse/Show-CommitCounter.ps1`

Create a new PowerShell hook that:

- Triggers after `git commit` commands (matcher: `Bash(git commit*)`)
- Runs `git rev-list --count HEAD ^origin/main` to get commit count
- Handles edge cases: no origin/main branch (use HEAD count), detached HEAD, not a git repo
- Formats output as "Commit X/20 (ADR-008)"
- Adds warning emoji/indicator at ≥15 commits with message: "WARNING: Approaching commit limit. Consider squashing or splitting work."
- Adds blocking emoji/indicator at ≥20 commits with message: "BLOCKED: Exceeded commit limit. MUST squash commits or split PR. See CONTRIBUTING.md."
- Returns exit code 0 (informational only, does not block)
- Includes error handling with fail-open behavior (don't break commits on infrastructure issues)

### 4. Update Hook Utilities Module

**File**: `file:.claude/hooks/Common/HookUtilities.psm1`

Add helper function `Get-CommitCount`:

- Accepts optional base branch parameter (default: `origin/main`)
- Returns commit count or -1 on error
- Handles fallback scenarios (no remote, detached HEAD)
- Includes proper error handling and logging

### 5. Update SESSION-PROTOCOL.md

**File**: `file:.agents/SESSION-PROTOCOL.md`

Add commit counter requirement to "Session End Protocol" Phase 3 (around line 434):

- Add SHOULD requirement: "The agent SHOULD verify commit count before ending session"
- Add to Session End Checklist (around line 494): "SHOULD | Verify commit count ≤20 | [ ] | Count: X/20"
- Reference ADR-008 and CONTRIBUTING.md commit thresholds
- Include guidance on what to do if approaching or exceeding limit

### 6. Update Platform-Specific Agent Files

Regenerate platform-specific agent files from shared templates:

**Orchestrator files**:
- `file:.claude/agents/orchestrator.md`
- `file:src/claude/orchestrator.md`
- `file:.github/agents/orchestrator.agent.md`
- `file:src/copilot-cli/orchestrator.agent.md`
- `file:src/vs-code-agents/orchestrator.agent.md`

**Implementer files**:
- `file:.claude/agents/implementer.md`
- `file:src/claude/implementer.md`
- `file:.github/agents/implementer.agent.md`
- `file:src/copilot-cli/implementer.agent.md`
- `file:src/vs-code-agents/implementer.agent.md`

Ensure all platform-specific files include the commit counter protocol from their respective shared templates.

### 7. Update CONTRIBUTING.md

**File**: `file:CONTRIBUTING.md`

Enhance the "Commit Count Thresholds" section (around line 374):

- Add note that agents now display commit counter automatically after each commit
- Reference the PostToolUse hook that provides real-time feedback
- Clarify that the 20-commit limit is now visible during sessions, not just at PR time
- Add example of what agents will display when approaching/exceeding limits

### 8. Create Documentation for Commit Counter Feature

**File**: `file:.agents/architecture/commit-counter-implementation.md`

Document the implementation:

- Problem statement (PR #908 exceeded limit without awareness)
- Solution architecture (PostToolUse hook + agent prompt updates)
- How it works (git rev-list command, threshold logic)
- Integration points (orchestrator, implementer, hooks)
- Testing approach (manual verification, edge cases)
- Maintenance notes (updating thresholds, adding new agents)

## Verification Steps

1. Test PostToolUse hook manually by making a commit and verifying counter displays
2. Verify counter shows correct count relative to origin/main
3. Test warning threshold (create 15+ commits on a branch)
4. Test blocking threshold (create 20+ commits on a branch)
5. Test edge cases: no origin/main, detached HEAD, not a git repo
6. Verify all platform-specific agent files include commit counter instructions
7. Confirm SESSION-PROTOCOL.md checklist includes commit count verification
8. Validate that agents reference the counter in their session logs

## Mermaid Diagram

```mermaid
sequenceDiagram
    participant Agent as Agent (Orchestrator/Implementer)
    participant Git as Git Repository
    participant Hook as PostToolUse Hook
    participant User as User/Session Log

    Agent->>Git: git commit -m "message"
    Git-->>Agent: Commit successful
    Git->>Hook: Trigger PostToolUse hook
    Hook->>Git: git rev-list --count HEAD ^origin/main
    Git-->>Hook: Return count (e.g., 12)
    
    alt Count < 15
        Hook->>User: Display "Commit 12/20 (ADR-008)"
    else Count >= 15 and < 20
        Hook->>User: Display "⚠️ Commit 16/20 (ADR-008)<br/>WARNING: Approaching limit"
    else Count >= 20
        Hook->>User: Display "🚫 Commit 21/20 (ADR-008)<br/>BLOCKED: Must squash or split"
    end
    
    Agent->>User: Document commit count in session log
    Agent->>Agent: Check if approaching limit
    
    alt Count >= 20
        Agent->>User: Suggest remediation:<br/>- git rebase -i HEAD~N<br/>- Split into multiple PRs
    end
```

---

Execution Information

Branch: main
Commit: e0318e3

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#301 - docs: autonomous PR monitoring prompt and retrospective [merged]
#484 - feat(workflow): auto-flag PRs exceeding commit threshold [merged]
#501 - docs(protocol): add needs-split label documentation [merged]
#610 - fix(ci): reconcile pre-commit session validation with CI requirements [merged]
#853 - docs: Document exit code 2 bypass failure and establish Claude hooks enforcement [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

Product Requirements Document

Important

This PRD was automatically generated based on issue triage escalation.
Complexity Score: 7/12 (Detailed)
Escalation Criteria: feature_request,multi_phase_work,architectural_impact

About this PRD

This PRD was generated by the Explainer Agent after the issue was flagged
for detailed analysis. The document is designed to be self-contained - it can
be passed to a separate AI agent instance for implementation without additional
context.

PRD Depth Levels:

• Standard (4-6): Brief analysis, clear requirements
• Detailed (7-9): Research section, blocking questions
• Comprehensive (10-12): Phased implementation, risk analysis

---

ADR-008 covers protocol automation via lifecycle hooks, but I need to find the specific commit limit policy. Let me search for it.

I need to search for the 20-commit limit policy and find more context about issue #362 and PR #908.

Now I need to search for the 20-commit limit specifically and find the related retrospective. Let me search for it.

Excellent! Now I have all the context I need. Let me also look at the pr-validation workflow to understand the current commit threshold implementation and check for any retrospective about PR #908.

Now I have the full context. The commit threshold monitoring exists in the PR validation workflow, but the issue is that agents are not aware of their commit count during a session. Let me search for any retrospective about PR #908.

The retrospective for PR #908 was referenced in the issue as .agents/retrospective/2026-01-15-pr-908-comprehensive-retrospective.md which does not exist yet (it's referenced in the issue body). Let me now create the comprehensive PRD.

The PRD cannot be written to the file system. I will output the complete PRD directly.

---

PRD: Add Commit Counter to Orchestrator Prompt

Executive Summary

PR #908 exceeded the 20-commit limit by 3x (59 commits) without agent awareness. The governance mechanism implemented in Issue #362 validates commit counts at PR creation time, but agents have zero visibility into their commit accumulation during a session. This creates a "governance without enforcement" gap where limits exist but are invisible until violated.

Scope	Status	Blocker
Commit counter display after each commit	🟢 READY	None
Warning threshold at 15 commits	🟢 READY	None
Blocking error at 20 commits	🟢 READY	None
Integration with all agents	🟢 READY	None

Verdict: READY

Problem Statement

Current State

Component	Current Behavior
pr-validation.yml	Validates commit count at PR creation (lines 302-343)
Thresholds	Warning at 10, Alert at 15, Block at 20 commits
Agent visibility	None during session
Enforcement timing	Post-hoc (at PR validation)
ADR-008 reference	Protocol automation via lifecycle hooks

Gap Analysis

1. Blind accumulation: Agents commit changes without knowing how many commits have accumulated on the branch
2. Late discovery: The 20-commit limit is only enforced at PR validation time
3. No session feedback: Orchestrator and implementer agents have no commit count awareness
4. ADR reference mismatch: Issue cites ADR-008 as the source of the 20-commit limit, but ADR-008 covers lifecycle hooks. The actual limit is from Issue feat(workflow): auto-flag PRs exceeding commit threshold #362

User Impact

User	Impact
AI agents	Cannot self-correct before exceeding limits
Maintainers	Must manually intervene on large PRs
CI system	Wasted cycles on PRs that will be blocked
PR reviewers	59-commit PRs are unreviewable

Research Findings

Primary Sources

Issue #362 Critique Findings (CONFIRMED):

• Thresholds: Warning 10, Alert 15, Block 20
• Location: .github/workflows/pr-validation.yml lines 302-343
• Evidence-based thresholds from historical PR data (PRs had 15-48 commits)

pr-validation.yml Implementation (CONFIRMED):

$warningThreshold = 10
$alertThreshold = 15
$blockThreshold = 20

SESSION-PROTOCOL.md (CONFIRMED):

• Phase 3: Git Operations (REQUIRED) includes commit verification
• Branch verification before EVERY commit is already a MUST requirement
• Session end gate requires clean git worktree

Secondary Sources

orchestrator.md Pattern (CONFIRMED):

• Session End Gate is already a blocking gate
• Validation runs via Validate-SessionJson.ps1
• Pattern exists for verification requirements with exit codes

Empirical Data

PR #908 Incident:

• 59 commits (3x over limit)
• Discovered only at PR validation
• Root cause: Governance without enforcement

Confidence Levels:

Finding	Confidence
20-commit limit from Issue #362	CONFIRMED
Agents have no commit visibility	CONFIRMED
PR validation enforces limit post-hoc	CONFIRMED
ADR-008 is lifecycle hooks, not commit limit	CONFIRMED

Proposed Solution

Phase 1: Orchestrator Commit Counter (Status: READY)

Estimated Effort: S (2 hours as per issue)
Blockers: None

Task	Description
1.1	Add commit counter section to orchestrator.md
1.2	Define counter command: git rev-list --count HEAD ^origin/main
1.3	Specify output format: "Commit X/20 (Issue #362)"
1.4	Add warning threshold behavior at 15+ commits
1.5	Add blocking behavior at 20+ commits with remediation

Phase 2: Agent Integration (Status: READY)

Estimated Effort: S
Blockers: None

Task	Description
2.1	Add commit counter to implementer.md
2.2	Add commit counter to devops.md
2.3	Ensure counter runs after every commit operation

Functional Requirements

FR-1: Commit Counter Command

Priority: P0

ID	Requirement	Acceptance Criteria
FR-1.1	System MUST count commits on current branch vs origin/main	git rev-list --count HEAD ^origin/main returns integer
FR-1.2	System MUST display count after each commit	Output visible in session after every git commit
FR-1.3	System MUST use format "Commit X/20 (Issue #362)"	Format matches specification exactly

FR-2: Warning Threshold

Priority: P0

ID	Requirement	Acceptance Criteria
FR-2.1	System MUST display warning when commits >= 15	Warning message visible at threshold
FR-2.2	Warning message MUST include remediation guidance	Message suggests "Consider shipping current changes"
FR-2.3	Warning MUST NOT block further commits	Agent can continue working

FR-3: Blocking Threshold

Priority: P0

ID	Requirement	Acceptance Criteria
FR-3.1	System MUST display error when commits >= 20	Error message visible at threshold
FR-3.2	Error message MUST include squash/split guidance	Message suggests "Squash commits or split PR"
FR-3.3	Error SHOULD strongly discourage further commits	Agent understands limit is reached

Non-Functional Requirements

Consistency

• Counter format matches existing pr-validation.yml thresholds
• Integrates with existing SESSION-PROTOCOL.md commit requirements
• References Issue feat(workflow): auto-flag PRs exceeding commit threshold #362 (not ADR-008) as source of truth

Testability

• Counter command is a simple git command, verifiable locally
• Output format is deterministic and parseable

Documentation

• orchestrator.md updated with commit counter section
• implementer.md updated with commit counter reference
• Issue feat(workflow): auto-flag PRs exceeding commit threshold #362 remains authoritative source for thresholds

Technical Design

orchestrator.md Changes

Add new section after "Session End Gate":

## Commit Counter (REQUIRED)

After EVERY `git commit` command, run the commit counter:

### Counter Command

```bash
COMMIT_COUNT=$(git rev-list --count HEAD ^origin/main 2>/dev/null || echo "0")
echo "Commit $COMMIT_COUNT/20 (Issue #362)"

Threshold Behavior

Count	Status	Action
1-14	OK	Continue normally
15-19	WARNING	Display: "Approaching limit. Consider shipping current changes."
20+	BLOCKED	Display: "Limit reached. Squash commits or split PR before continuing."

Why This Matters

PR #908 had 59 commits (3x over limit) because the limit was invisible during the session. This counter ensures agents self-correct before limits are violated.

Reference: Issue #362 defines the commit thresholds. The PR validation workflow enforces these at PR creation.

### implementer.md Changes

Add to "Git Operations" or equivalent section:

```markdown
### Commit Counter

After every commit, verify commit count:

```bash
COMMIT_COUNT=$(git rev-list --count HEAD ^origin/main 2>/dev/null || echo "0")
echo "Commit $COMMIT_COUNT/20 (Issue #362)"

If count >= 15: Consider shipping current work before adding more commits.
If count >= 20: Stop and remediate (squash or split).

Reference: orchestrator.md Commit Counter section.

## Implementation Plan

### Prerequisites

- [x] Issue #362 commit threshold monitoring is merged
- [x] pr-validation.yml contains threshold enforcement
- [ ] No blocking dependencies

### Decision Tree

```text
Is orchestrator.md already documenting commit limits?
├── YES → Update existing section with counter command
└── NO → Add new "Commit Counter" section
         │
         └── Are thresholds correct (10/15/20)?
             ├── YES → Reference Issue #362
             └── NO → Align with Issue #362 thresholds

Phase 1 Tasks (S effort)

1. Read orchestrator.md to identify insertion point
2. Add Commit Counter section with counter command, thresholds, and rationale
3. Update implementer.md with counter reference
4. Update devops.md if it performs commits
5. Validate markdown linting passes
6. Test counter command locally

Phase 2 Tasks (Optional)

1. Add counter to other agents that perform commits
2. Consider lifecycle hook integration per ADR-008 (future enhancement)

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
Agents ignore counter output	Medium	Medium	Make counter REQUIRED, not RECOMMENDED
Counter command fails on new branch	Low	Low	Use `2>/dev/null
Threshold drift from pr-validation.yml	Low	High	Reference Issue #362 as single source of truth
Agent prompts become too long	Low	Low	Counter section is 15 lines

Success Metrics

Metric	Target
PRs exceeding 20 commits	0 per month
Agent commit count visibility	100% of commit operations
Warning threshold response	Agents mention limit in session when >= 15

Blocking Questions

None. All requirements are clear and implementation path is straightforward.

Open Questions (Non-Blocking)

1. Q: Should the counter be a PowerShell script for consistency?

   • Hypothesis: Inline bash/pwsh is simpler for agent prompts
   • Status: Recommend inline command, script is over-engineering

2. Q: Should counter update memory for cross-session tracking?

   • Hypothesis: Not needed; counter resets per branch
   • Status: Defer to future enhancement

3. Q: Should counter integrate with lifecycle hooks (ADR-008)?

   • Hypothesis: Future enhancement; prompt-level is MVP
   • Status: Out of scope for this issue

Appendices

Appendix A: Research Sources

• Issue feat(workflow): auto-flag PRs exceeding commit threshold #362: Commit threshold monitoring implementation
• .serena/memories/issue-362-critique-findings.md: Critique review
• .github/workflows/pr-validation.yml lines 302-343: Threshold implementation
• .agents/SESSION-PROTOCOL.md: Git operations requirements
• src/claude/orchestrator.md: Current orchestrator prompt

Appendix B: Git Command Reference

# Count commits on branch vs origin/main
git rev-list --count HEAD ^origin/main

# Alternative if origin/main doesn't exist
git rev-list --count HEAD ^$(git merge-base HEAD origin/main)

Appendix C: Related Issues/PRs

• Issue feat(workflow): auto-flag PRs exceeding commit threshold #362: Commit threshold monitoring (source of thresholds)
• Issue [P0] Create pre-PR validation script (Validate-PRReadiness.ps1) #934: Pre-PR validation script (related governance)
• PR feat(skill): add reflect skill and auto-learning hook #908: 59 commits, 3x over limit (incident that triggered this issue)
• ADR-008: Protocol automation via lifecycle hooks (future integration)

---

_{Generated by AI PRD Generation | View Workflow}

[github-actions]

AI Triage Summary

Note

This issue has been automatically triaged by AI agents

What is AI Triage?

This issue was analyzed by AI agents:

• Analyst Agent: Categorizes the issue and suggests appropriate labels
• Roadmap Agent: Aligns the issue with project milestones and priorities
• Explainer Agent (if escalated): Generates comprehensive PRD

Triage Results

Property	Value
Category	enhancement
Labels	["enhancement","agent-orchestrator","agent-implementer","area-prompts"]
Priority	P0
Milestone	v1.1
PRD Escalation	Generated (see below)

Categorization Analysis

```json
{
  "labels": ["enhancement", "agent-orchestrator", "agent-implementer", "area-prompts"],
  "category": "enhancement",
  "confidence": 0.9,
  "reasoning": "Issue proposes adding new commit counter functionality to orchestrator prompt to enforce ADR-008 limit visibility"
}

</details>

<details>
<summary>Roadmap Alignment</summary>

```json
```json
{
  "milestone": "v1.1",
  "priority": "P0",
  "epic_alignment": "",
  "confidence": 0.85,
  "reasoning": "Issue addresses governance enforcement gap identified in PR #908 retrospective; prevents ADR-008 violations through visible commit counting",
  "escalate_to_prd": true,
  "escalation_criteria": ["feature_request", "multi_phase_work", "architectural_impact"],
  "complexity_score": 7
}

</details>

---

<sub>Powered by [AI Issue Triage](https://github.com/rjmurillo/ai-agents) workflow</sub>