Skip to content

Commit 4394d69

Browse files
devppratikclaude
devppratik
and
claude
authored
docs, feat(SREP-4460, SREP-4926: Add Standardized Claude hooks, skill, agents. Update standardised docs) (#270)
* feat: add Claude Code infrastructure and documentation * feat: add Claude Code infrastructure and documentation * feat: update Claude Code infrastructure - Update settings.json with prek permissions and comprehensive deny rules - Update hooks (stop-prek-validation.sh, pre-edit.sh, README.md) - Update agents with repo-specific references - Update skills with repo-specific prow-ci examples - Ensure all references are operator-specific Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * fix: improve Claude Code hook portability and completeness - Make pre-edit.sh canonicalization portable across GNU/BSD/macOS - Add python fallback for path normalization - Works with non-existent files - Fix stop-prek-validation.sh to explicitly validate changed files - Prevents validation scope ambiguity - Validates staged + unstaged + untracked files - Complete prow-ci SKILL.md title with operator name Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * Fix CodeRabbit issues - Copy latest analyze_failure.py and fetch_prow_artifacts.py from AAO - Fix gitleaks: narrow test file allowlist to testdata dirs - Remove broad .*_test.go pattern that disabled scanning for all test files * feat: add SessionStart hook and update docs-agent triggers Changes: - Added SessionStart hook to .claude/settings.json that runs session-start-prek-setup.sh - Copied session-start-prek-setup.sh hook script to .claude/hooks/ - Updated docs-agent.md to include .claude/settings.json in sync triggers The SessionStart hook ensures prek is installed and configured when Claude Code starts a session, improving developer experience. Related: CodeRabbit review feedback on hook configuration documentation --------- Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent e91018a commit 4394d69

24 files changed

Lines changed: 3791 additions & 0 deletions

‎.claude/agents/README.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# Claude Agents
2+
3+
Specialized agents for operator development workflows.
4+
5+
## Available Agents
6+
7+
### [lint-agent](./lint-agent.md)
8+
**Purpose**: Automated linting and code quality enforcement
9+
10+
**When to use**:
11+
- Pre-commit validation
12+
- After code generation
13+
- Before creating PR
14+
- Investigating CI lint failures
15+
16+
**Key capabilities**:
17+
- Run formatting checks
18+
- Execute golangci-lint
19+
- Auto-fix safe issues
20+
- Report unfixable problems
21+
22+
---
23+
24+
### [test-agent](./test-agent.md)
25+
**Purpose**: Automated testing and test quality assurance
26+
27+
**When to use**:
28+
- After code changes
29+
- Test failures in CI
30+
- Before creating PR
31+
- After regenerating mocks
32+
33+
**Key capabilities**:
34+
- Run targeted tests for changed code
35+
- Detect flaky test failures
36+
- Suggest minimal fixes
37+
- Ensure test coverage
38+
39+
---
40+
41+
### [security-agent](./security-agent.md)
42+
**Purpose**: Security scanning and policy enforcement
43+
44+
**When to use**:
45+
- Before committing code
46+
- RBAC manifests modified
47+
- Secret handling changed
48+
- CI/CD pipelines modified
49+
50+
**Key capabilities**:
51+
- Scan for hardcoded secrets
52+
- Validate RBAC configurations
53+
- Check insecure patterns
54+
- Enforce security policies
55+
56+
---
57+
58+
### [docs-agent](./docs-agent.md)
59+
**Purpose**: Documentation maintenance and synchronization
60+
61+
**When to use**:
62+
- Code changes affect workflows
63+
- New features added
64+
- Build process modified
65+
- Command examples need updating
66+
67+
**Key capabilities**:
68+
- Update docs after code changes
69+
- Ensure command examples work
70+
- Validate Markdown formatting
71+
- Keep docs synchronized
72+
73+
---
74+
75+
### [ci-agent](./ci-agent.md)
76+
**Purpose**: CI/CD validation and workflow integrity
77+
78+
**When to use**:
79+
- Tekton pipelines modified
80+
- Pre-commit hooks changed
81+
- CI failures need investigation
82+
- New validation steps added
83+
84+
**Key capabilities**:
85+
- Validate pipeline integrity
86+
- Ensure local/CI parity
87+
- Detect missing checks
88+
- Optimize execution order
89+
90+
---
91+
92+
## Usage Patterns
93+
94+
### Single Agent Invocation
95+
Use a specific agent when the task is clear:
96+
```text
97+
"Run lint-agent to check formatting"
98+
"Use security-agent to scan for secrets"
99+
"Invoke test-agent on controllers/machineset_controller.go"
100+
```
101+
102+
### Multi-Agent Workflow
103+
Agents can work together for comprehensive validation:
104+
```text
105+
1. lint-agent: Fix formatting and linting
106+
2. test-agent: Run affected tests
107+
3. security-agent: Scan for secrets and RBAC issues
108+
4. docs-agent: Update documentation
109+
5. ci-agent: Validate CI parity
110+
```
111+
112+
### Pre-Commit Workflow
113+
Recommended agent sequence before committing:
114+
```text
115+
1. security-agent (secrets, RBAC)
116+
2. lint-agent (formatting, linting)
117+
3. test-agent (targeted tests)
118+
4. docs-agent (if docs need updates)
119+
```
120+
121+
### Pre-PR Workflow
122+
Full validation before creating pull request:
123+
```text
124+
1. lint-agent --all-files
125+
2. test-agent --full-suite
126+
3. security-agent --comprehensive
127+
4. docs-agent --validate
128+
5. ci-agent --parity-check
129+
```
130+
131+
## Agent Design Principles
132+
133+
All agents follow these principles:
134+
135+
**Focused Responsibility**
136+
- Each agent has clear, narrow responsibilities
137+
- No overlap with other agents
138+
- Single purpose, well-defined scope
139+
140+
**Reuse Existing Tools**
141+
- Leverage pre-commit hooks
142+
- Use Makefile targets
143+
- Don't reinvent validations
144+
145+
**Fast Feedback**
146+
- Quick execution (<30s for targeted checks)
147+
- Fail fast on common issues
148+
- Provide actionable output
149+
150+
**CI Parity**
151+
- Mirror CI checks locally
152+
- Use same tool versions
153+
- Deterministic results
154+
155+
**Safe Automation**
156+
- Auto-fix only safe changes
157+
- Escalate risky modifications
158+
- Never bypass security checks
159+
160+
**Clear Escalation**
161+
- Define when human intervention needed
162+
- Explain what can't be auto-fixed
163+
- Provide context for decisions
164+
165+
## Integration with Pre-commit
166+
167+
Agents complement (don't replace) pre-commit hooks:
168+
169+
| Pre-commit Hook | Corresponding Agent |
170+
|-----------------|---------------------|
171+
| `gitleaks` | security-agent |
172+
| `golangci-lint` | lint-agent |
173+
| `go-build` | lint-agent |
174+
| `go-mod-tidy` | lint-agent |
175+
| `rbac-wildcard-check` | security-agent |
176+
177+
**Relationship:**
178+
- Pre-commit hooks: Automated git hooks (mandatory)
179+
- Agents: Interactive assistance (on-demand)
180+
- Both use same underlying tools
181+
182+
## Output Format
183+
184+
All agents should report findings consistently:
185+
```text
186+
[AGENT] [SEVERITY] Location: Issue
187+
Example: [lint-agent] [ERROR] pkg/handler/deployment.go:42: unreachable code
188+
Example: [security-agent] [CRITICAL] deploy/role.yaml:15: Wildcard permission
189+
```
190+
191+
Severity levels:
192+
- **CRITICAL**: Blocks commit/PR
193+
- **ERROR**: Must fix before merge
194+
- **WARNING**: Should fix
195+
- **INFO**: Informational
196+
197+
## Extension Guide
198+
199+
To add a new agent:
200+
201+
1. Create `new-agent.md` in this directory
202+
2. Add YAML frontmatter at the top:
203+
```yaml
204+
---
205+
name: new-agent
206+
description: Brief description of when to use this agent. Be specific about use cases.
207+
tools: Bash, Read, Edit, Grep
208+
model: sonnet
209+
---
210+
```
211+
3. Follow the template structure in markdown body:
212+
- **Responsibilities**: What it does
213+
- **Usage**: When to invoke
214+
- **Commands**: How it works
215+
- **Escalation**: When to defer to human
216+
4. Update this README with agent description
217+
5. Test agent workflows locally
218+
6. Document integration points
219+
220+
**Required frontmatter fields**:
221+
- `name`: Agent identifier (kebab-case, matches filename)
222+
- `description`: When to use this agent (triggers invocation)
223+
- `tools`: Comma-separated list of allowed tools
224+
- `model`: Claude model to use (`sonnet`, `opus`, or `haiku`)
225+
226+
**Agent file structure**:
227+
```text
228+
.claude/agents/
229+
├── README.md
230+
├── ci-agent.md # Frontmatter + markdown body
231+
├── docs-agent.md
232+
├── lint-agent.md
233+
├── security-agent.md
234+
└── test-agent.md
235+
```
236+
237+
## Agent Communication
238+
239+
Agents can reference each other:
240+
- `lint-agent` may suggest running `test-agent`
241+
- `security-agent` may trigger `ci-agent` for pipeline validation
242+
- `docs-agent` updates after `lint-agent` or `test-agent` changes
243+
244+
Keep communication minimal and explicit.

0 commit comments

Comments
 (0)