--- description: Create, validate, and enforce engineering standards through AI consensus and automated PR monitoring. category: general --- flowchart TD _HEADER_[""]:::headerStyle classDef headerStyle fill:none,stroke:none subgraph _MAIN_[" "] direction LR %% Phase 1: Parallel Discovery subgraph Discovery["Phase 1: Parallel Discovery"] D1[Analyze Codebase] & D2[Mine PR Comments] & D3[Review RFCs & Standards] & D4[Company Standards] & D5[Industry Norms] --> A[Draft Standards] end %% Phase 2: Validation Loop subgraph Validation["Phase 2: Validation Loop"] A --> B[Contradiction Check] B --> C{Contradictions?} C -->|Yes| D[Review Findings] D --> E[Resolve] E --> B C -->|No| F[Human Review] F --> G{Approved?} G -->|No| H[Incorporate Feedback] H --> B G -->|Yes| I[Finalized v1.0] end %% Phase 3: Implementation subgraph Implementation["Phase 3: Implementation"] I --> J[Update Claude Rules] I --> K[Update Graphite AI Rules] J --> RC2[council review] J --> RC3[claude review] J --> RC4[cursor-agent review] K --> L[PR Watch Agent] J --> L end %% Phase 4: Enforcement subgraph Enforcement["Phase 4: Enforcement"] K & L & RC2 & RC3 & RC4 --> M[Monitor PRs] M --> N{Divergence?} N -->|Yes| O[Flag PR] N -->|No| P[PR Approved] O --> Q[Developer Reviews] Q --> R{Update Standards?} R -->|Yes| H R -->|No| S[Fix PR] S --> M end click D1 "#" "**Analyze Existing Codebase**\n- Extract code patterns and naming conventions\n- Catalog architectural decisions\n- Identify inconsistencies across the repo\n- Tools: `ast-grep`, `semgrep`, static analysis\n\n`council analyze --codebase . --output codebase-patterns.md`" click D2 "#" "**Mine PR Comments & Reviews**\n- Analyze historical PR review comments\n- Extract implicit standards from reviewer feedback\n- Identify recurring themes and rejection patterns\n- Tools: GitHub API, comment mining\n\n`gh api repos/:owner/:repo/pulls/comments --paginate | council analyze --pr-comments --output pr-standards.md`" click D3 "#" "**Review RFCs & Language Standards**\nFocus only on standards that match your actual tech stack.\n\n*Published RFCs:*\n- [REST/HTTP (RFC 7231, 9110)](https://www.rfc-editor.org/) — standardizing endpoints\n- [OAuth (RFC 6749)](https://www.rfc-editor.org/) — authentication\n- [JSON (RFC 8259)](https://www.rfc-editor.org/) — data structures\n- [WebSocket (RFC 6455)](https://www.rfc-editor.org/) — real-time connections\n\n*Language standards:*\n- [Python: PEP 8, PEP 20, PEP 257](https://peps.python.org/) — style + docstrings\n- [JavaScript: TC39](https://github.com/tc39/proposals) — language proposals\n- [Go: Effective Go](https://go.dev/doc/effective_go) — idiomatic Go\n- [Rust: API Guidelines](https://rust-lang.github.io/api-guidelines/) — Rust patterns\n\n`council research --rfcs --language python --output rfc-standards.md`" click D4 "#" "**Analyze Company Standards**\n- [Google Style Guides](https://google.github.io/styleguide/) — Python, Go, Java, JS\n- [Airbnb JavaScript/React](https://github.com/airbnb/javascript) — JS/React patterns\n- [Microsoft TypeScript](https://github.com/microsoft/TypeScript/wiki/Coding-guidelines) — TS guidelines\n- Meta, Amazon, Netflix engineering standards\n\n`council research --companies google,airbnb,microsoft --output company-standards.md`" click D5 "#" "**Research Industry Norms**\n- Framework best practices: React, Django, Flask, K8s\n- Security standards: OWASP\n- Testing methodologies\n- Common architectural patterns\n\n`council research --industry --frameworks react,django --output industry-norms.md`" click A "#" "**Draft Standards Document**\nAll 5 discovery streams run in parallel (with `&`), then synthesized:\n\n`council synthesize codebase-patterns.md pr-standards.md rfc-standards.md company-standards.md industry-norms.md --output standards-draft.md`\n\n*Draft contains:*\n- Coding conventions (naming, formatting, structure)\n- Architecture patterns (existing + proven practices)\n- Security requirements (auth, secrets, validation)\n- Testing requirements (coverage + patterns)\n- Documentation standards (comments, docstrings, READMEs)\n- Conflict identification where sources disagree\n- Gap analysis where no standard exists\n- Rationale documentation for each choice" click B "#" "**Council Internal Contradiction Check**\nRun `council review` on the draft itself:\n- Internal contradictions between standards\n- Ambiguous or interpretable language\n- Logical inconsistencies that can't coexist\n- Missing context or insufficient explanation\n- Redundant or overlapping rules\n\n`council review --file standards-draft.md`" click C "#" "**Decision: Contradictions Found?**\nIf Yes → review and resolve contradictions, then re-check\nIf No → proceed to human review" click D "#" "**Review Council Findings**\nAnalyze specific contradiction reports from the council review output." click E "#" "**Resolve Contradictions**\nUpdate the draft to eliminate contradictions and clarify ambiguities.\nLoops back to re-run the council contradiction check." click F "#" "**Human Review & Agreement**\n- Share draft with all relevant stakeholders\n- Schedule and conduct review meeting\n- Walk through standards document together\n- Capture team input and concerns\n- Vote or reach consensus on standards" click G "#" "**Decision: Team Approves?**\nIf Yes → finalize as v1.0\nIf No → incorporate feedback and re-validate" click H "#" "**Incorporate Feedback**\nDocument all requested changes from team review.\nUpdate the draft, then loop back through the full validation cycle (council check + human review)." click I "#" "**Finalized v1.0 Standards Document**\nBoth council (no contradictions) and humans (team approval) agree.\n- Tagged as v1.0 — a living document\n- Subject to future revision based on enforcement feedback\n- Each future version goes through the same validation loop\n\n*Version philosophy:*\n- v1.0 = first validated, approved version\n- v1.1 = minor clarifications from enforcement learnings\n- v2.0 = major update after significant enforcement feedback\n`git tag -a standards-v1.0 -m Initial`" click J "#" "**Update Claude Rules**\nConvert v1.0 into modular `.claude/rules/` files (auto-loaded by all Claude AI tools):\n- `coding-style.md` — naming, formatting, conventions\n- `architecture-patterns.md` — design patterns, structure\n- `security-requirements.md` — auth, secrets, validation\n- `testing-standards.md` — coverage, patterns\n- `documentation.md` — comments, docstrings, READMEs\n\n`./scripts/standards-to-claude-rules.sh standards-v1.0.md`\n`cp -r .claude/rules/* .cursor/rules/`\n`git add .claude/rules/ .cursor/rules/`\n`git commit -m 'Deploy standards v1.0'`\n\nAuto-loaded by `council`, `claude`, and `cursor-agent`. Update rules and enforcement is instant across all consumers." click K "#" "**Update Graphite AI Rules**\nGraphite uses its own rules from `.github/graphite-rules/*.md` — separate from `.claude/rules/`.\nDefine Graphite Agent violation patterns for automated PR review.\n\n`cp standards-v1.0.md .github/graphite-rules/standards.md`\n`git add .github/graphite-rules/`\n`git commit -m 'Deploy Graphite standards v1.0'`\n\nSee the [graphite-rules skill](https://joseph.schlesinger/.claude/skills/graphite-rules/SKILL.md) for how to create and manage them." click L "#" "**PR Watch Agent** *(Future Implementation)*\nNot yet implemented. Planned: automated agent monitoring new PRs for standards divergence.\n\nWill source from:\n- Graphite AI rules (`.github/graphite-rules/*.md`)\n- Cursor rules (`.cursor/rules/`, synced from `.claude/rules/`)\n\nWill post review comments flagging violations before a human reviewer looks." click RC2 "#" "**council review**\nMulti-model AI consensus review. Standards auto-loaded from `.claude/rules/`.\n- `council review --pr 123`\n- `council review --file path/to/code.py`\n- `council review --diff main...feature-branch`" click RC3 "#" "**claude review**\nClaude Code review. Standards auto-loaded from `.claude/rules/`.\n- `claude --pr 123`\n- `claude --file code.py`" click RC4 "#" "**cursor-agent review**\nCursor Agent review. Standards auto-loaded from `.cursor/rules/` (synced from `.claude/rules/`).\n- `cursor-agent review --pr 123`\n- `cursor-agent ask review-this-code`" click M "#" "**Monitor Pull Requests**\nContinuous monitoring via:\n- Graphite AI automated review\n- PR watch agent divergence detection\n- On-demand `council review` / `claude review` commands" click N "#" "**Decision: Standards Divergence Detected?**\nAutomated check — does the PR violate any validated standards?" click O "#" "**Flag PR for Review**\nAutomated comment explaining the specific violation and which standard it breaks." click P "#" "**PR Approved**\nPR meets all validated standards and can be merged." click Q "#" "**Developer Reviews Feedback**\nDeveloper evaluates the automated flag:\n- Is the standard correct and the PR wrong?\n- Or is the standard outdated/too strict?" click R "#" "**Decision: Update Standards?**\nIf Yes → standard needs revision (toward v1.1, v2.0):\n- Council enforcement logs revealed unclear points\n- Standard is too strict, outdated, or contradictory\n- Feed back into Phase 2 (Incorporate Human Feedback)\n- Re-run council check → human review → new version tag\n- v1.1 for minor updates, v2.0 for major changes\n\nTrack enforcement learnings as they accumulate:\n`echo Issue: Unclear guidance on X >> standards-feedback.md`\n`council review --file standards-feedback.md`\n\nIf No → PR needs fixing" click S "#" "**Fix PR to Meet Standards**\nDeveloper updates PR to comply with standards.\nCycles back through monitoring for re-check." classDef discovery fill:#d1ecf1,stroke:#7ec8d8 classDef validation fill:#fff3cd,stroke:#f0c040 classDef human fill:#e8daef,stroke:#b07cc6 classDef approved fill:#d4edda,stroke:#5cb85c classDef flagged fill:#f8d7da,stroke:#e06070 classDef impl fill:#ffeaa7,stroke:#e0c040 classDef future fill:#dc3545,stroke:#ff4d5e,color:#ffffff,stroke-width:2px class D1,D2,D3,D4,D5,A discovery class B,C,D,E,N validation class F,G,H human class I,P approved class O,Q flagged class J,K,M,R,S impl class RC2,RC3,RC4 impl class L future end style _MAIN_ fill:none,stroke:none,padding:0 _HEADER_ ~~~ _MAIN_