Skip to content

Commit cec7993

Browse files
jeremyederAmbient Code Botclaude
authored
feat: overhaul Claude Code automation — agents, skills, hooks, docs (#1307)
<!-- acp:session_id=session-5ce0e6c9-6412-4f9a-ad4f-9b531be297d2 source=#1307 last_action=2026-04-14T14:43:23Z retry_count=1 --> ## Summary - **Consolidate convention docs** from `.claude/context/` and `.claude/patterns/` into component-level files (`components/*/DEVELOPMENT.md`, `*_PATTERNS.md`), eliminating stale paths - **Create 6 per-component review agents** (backend, frontend, operator, runner, security, convention-eval) with consistent structure, severity levels, and grep-based checks - **Overhaul 3 existing skills** (dev-cluster, pr-fixer, unleash-flag) and **promote 2 commands to skills** (amber-review, cypress-demo) per Anthropic skill-creator standard with evals - **Add 3 new skills** (`/align` for convention scoring, `/scaffold` for integration/endpoint templates, `/memory` for auto-memory management) - **Add 7 enforcement hooks** in `.claude/settings.json` (Shadcn UI, no manual fetch, service account misuse, no panic, skill-creator standard, feature flag nudge, stop review nudge) - **Delete 11 obsolete commands** (9 speckit + acp-compile + 2 promoted); keep `jira.log.md` as-is Supersedes #1293 (moved from fork to org branch for Amber compatibility). ## Test plan - [ ] Verify all newly-added paths exist in the repo - [ ] Confirm BOOKMARKS.md links resolve correctly - [ ] Test hooks: create a `.tsx` file with `<button` → verify Shadcn reminder fires - [ ] Test hooks: edit a handler with `panic(` → verify panic reminder fires - [ ] Invoke `/align` → verify convention-eval agent dispatches and produces scored report - [ ] Invoke `/amber-review` → verify it loads component-level docs (not old `.claude/context/` paths) - [ ] Invoke `/scaffold integration test-provider` → verify checklist output - [ ] Invoke `/memory audit` → verify it scans memory directory 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added multiple automated review agents and a convention-alignment check plus new skills: align, memory, scaffold, cypress-demo, dev-cluster, amber-review/pr-fixer updates, and feature-flag tooling with evaluation fixtures. * **Removed** * Deleted several speckit workflow command docs and legacy compile/demo command docs. * **Docs** * Consolidated and updated development, operator, and security conventions and component guides. * **Chores** * Added editor pre-write hooks and a stop-hook script to surface best-practice reminders. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Ambient Code Bot <bot@ambient-code.local> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent ed01caa commit cec7993

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+1691
-1774
lines changed

‎.claude/agents‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎.claude/agents/backend-review.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
name: backend-review
3+
description: >
4+
Review Go backend code for convention violations. Use after modifying files
5+
under components/backend/. Checks for panic usage, service account misuse,
6+
type assertion safety, error handling, token security, and file size.
7+
tools:
8+
- Read
9+
- Grep
10+
- Glob
11+
- Bash
12+
---
13+
14+
# Backend Review Agent
15+
16+
Review backend Go code against documented conventions.
17+
18+
## Context
19+
20+
Load these files before running checks:
21+
22+
1. `components/backend/DEVELOPMENT.md`
23+
2. `components/backend/ERROR_PATTERNS.md`
24+
3. `components/backend/K8S_CLIENT_PATTERNS.md`
25+
26+
## Checks
27+
28+
### B1: No panic() in production (Blocker)
29+
30+
```bash
31+
grep -rn "panic(" components/backend/ --include="*.go" | grep -v "_test.go"
32+
```
33+
34+
Any match is a Blocker. Production code must return `fmt.Errorf` with context.
35+
36+
### B2: User-scoped clients for user operations (Blocker)
37+
38+
In `components/backend/handlers/`:
39+
- `DynamicClient.Resource` or `K8sClient` used for List/Get operations should use `GetK8sClientsForRequest(c)` instead
40+
- Acceptable uses: after RBAC validation for writes, token minting, cleanup
41+
42+
```bash
43+
grep -rnE "DynamicClient\.|K8sClient\." components/backend/handlers/ --include="*.go" | grep -v "_test.go"
44+
```
45+
46+
Cross-reference each match against the decision tree in `K8S_CLIENT_PATTERNS.md`.
47+
48+
### B3: No direct type assertions on unstructured (Critical)
49+
50+
```bash
51+
grep -rnE 'Object\["[^"]+"\]\.\(' components/backend/ --include="*.go" | grep -v "_test.go"
52+
```
53+
54+
Must use `unstructured.NestedMap`, `unstructured.NestedString`, etc.
55+
56+
### B4: No silent error handling (Critical)
57+
58+
Look for empty error handling blocks:
59+
```bash
60+
rg -nUP 'if err != nil \{\s*\n\s*\}' --type go --glob '!*_test.go' components/backend/
61+
```
62+
63+
Also manually inspect `if err != nil` blocks for cases where the body only contains a comment (no actual handling).
64+
65+
### B5: No internal error exposure in API responses (Major)
66+
67+
```bash
68+
grep -rn 'gin.H{"error":.*fmt\.Sprintf\|gin.H{"error":.*err\.' components/backend/handlers/ --include="*.go" | grep -v "_test.go"
69+
```
70+
71+
API responses should use generic messages. Detailed errors go to logs.
72+
73+
### B6: No tokens in logs (Blocker)
74+
75+
```bash
76+
grep -rn 'log.*[Tt]oken\b\|log.*[Ss]ecret\b' components/backend/ --include="*.go" | grep -v "len(token)\|_test.go"
77+
```
78+
79+
Use `len(token)` for logging, never the token value itself.
80+
81+
### B7: Error wrapping with %w (Major)
82+
83+
```bash
84+
grep -rnP 'fmt.Errorf.*%v.*\berr\b' components/backend/ --include="*.go" | grep -v "_test.go"
85+
```
86+
87+
Should use `%w` for error wrapping to preserve the error chain.
88+
89+
### B8: Files under 400 lines (Minor)
90+
91+
```bash
92+
find components/backend/handlers/ -name "*.go" -not -name "*_test.go" -print0 | xargs -0 wc -l | sort -rn
93+
```
94+
95+
Flag files exceeding 400 lines. Note: `sessions.go` is a known exception.
96+
97+
## Output Format
98+
99+
```markdown
100+
# Backend Review
101+
102+
## Summary
103+
[1-2 sentence overview]
104+
105+
## Findings
106+
107+
### Blocker
108+
[Must fix — or "None"]
109+
110+
### Critical
111+
[Should fix — or "None"]
112+
113+
### Major
114+
[Important — or "None"]
115+
116+
### Minor
117+
[Nice-to-have — or "None"]
118+
119+
## Score
120+
[X/8 checks passed]
121+
```
122+
123+
Each finding includes: file:line, problem description, convention violated, suggested fix.

‎.claude/agents/convention-eval.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
name: convention-eval
3+
description: >
4+
Runs all convention checks across the full codebase and produces a scored
5+
alignment report. Dispatched by the /align skill.
6+
tools:
7+
- Read
8+
- Grep
9+
- Glob
10+
- Bash
11+
---
12+
13+
# Convention Evaluation Agent
14+
15+
Evaluate codebase adherence to documented conventions. Produce a scored report.
16+
17+
## Context Files
18+
19+
Load these before running checks:
20+
21+
1. `components/backend/DEVELOPMENT.md`
22+
2. `components/backend/ERROR_PATTERNS.md`
23+
3. `components/backend/K8S_CLIENT_PATTERNS.md`
24+
4. `components/frontend/DEVELOPMENT.md`
25+
5. `components/frontend/REACT_QUERY_PATTERNS.md`
26+
6. `components/operator/DEVELOPMENT.md`
27+
7. `docs/security-standards.md`
28+
29+
## Checks by Category
30+
31+
### Backend (8 checks, weight: 25%)
32+
33+
| # | Check | Severity |
34+
|---|-------|----------|
35+
| B1 | No `panic()` in production | Blocker |
36+
| B2 | User-scoped clients for user ops | Blocker |
37+
| B3 | No direct type assertions | Critical |
38+
| B4 | No silent error handling | Critical |
39+
| B5 | No internal error exposure | Major |
40+
| B6 | No tokens in logs | Blocker |
41+
| B7 | Error wrapping with %w | Major |
42+
| B8 | Files under 400 lines | Minor |
43+
44+
### Frontend (8 checks, weight: 25%)
45+
46+
| # | Check | Severity |
47+
|---|-------|----------|
48+
| F1 | No raw HTML elements | Critical |
49+
| F2 | No manual fetch() | Critical |
50+
| F3 | No `interface` declarations | Major |
51+
| F4 | No `any` types | Critical |
52+
| F5 | Components under 200 lines | Minor |
53+
| F6 | Loading/error states | Major |
54+
| F7 | Colocated single-use components | Minor |
55+
| F8 | Feature flag on new pages | Major |
56+
57+
### Operator (7 checks, weight: 20%)
58+
59+
| # | Check | Severity |
60+
|---|-------|----------|
61+
| O1 | OwnerReferences on child resources | Blocker |
62+
| O2 | Proper reconciliation patterns | Critical |
63+
| O3 | SecurityContext on Job pods | Critical |
64+
| O4 | Resource limits/requests | Major |
65+
| O5 | No `panic()` in production | Blocker |
66+
| O6 | Status condition updates | Critical |
67+
| O7 | No `context.TODO()` | Minor |
68+
69+
### Runner (4 checks, weight: 10%)
70+
71+
| # | Check | Severity |
72+
|---|-------|----------|
73+
| R1 | Proper async patterns | Major |
74+
| R2 | Credential handling | Blocker |
75+
| R3 | Error propagation | Critical |
76+
| R4 | No hardcoded secrets | Blocker |
77+
78+
### Security (7 checks, weight: 20%)
79+
80+
| # | Check | Severity |
81+
|---|-------|----------|
82+
| S1 | User token for user ops | Blocker |
83+
| S2 | RBAC before resource access | Critical |
84+
| S3 | Token redaction | Blocker |
85+
| S4 | Input validation | Major |
86+
| S5 | SecurityContext on pods | Critical |
87+
| S6 | OwnerReferences on Secrets | Critical |
88+
| S7 | No hardcoded credentials | Blocker |
89+
90+
## Scoring
91+
92+
- Each check: Pass (1) or Fail (0)
93+
- Category score: passes / total
94+
- Overall score:
95+
- Full scope: weighted average across all categories
96+
- Scoped runs: renormalize weights to selected categories (e.g., backend-only uses 100% backend weight)
97+
98+
## Output Format
99+
100+
```markdown
101+
# Convention Alignment Report
102+
103+
**Scope:** [full | backend | frontend | ...]
104+
**Date:** [ISO date]
105+
**Overall Score:** [X%]
106+
107+
## Category Scores
108+
109+
| Category | Score | Pass | Fail | Blockers |
110+
|----------|-------|------|------|----------|
111+
| Backend | X/8 | X | X | X |
112+
| Frontend | X/8 | X | X | X |
113+
| Operator | X/7 | X | X | X |
114+
| Runner | X/4 | X | X | X |
115+
| Security | X/7 | X | X | X |
116+
117+
## Failures
118+
119+
### Blockers
120+
[List with file:line references]
121+
122+
### Critical
123+
[List with file:line references]
124+
125+
### Major / Minor
126+
[List]
127+
128+
## Recommendations
129+
[Top 3 priorities to improve alignment]
130+
```

‎.claude/agents/frontend-review.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
name: frontend-review
3+
description: >
4+
Review frontend TypeScript/React code for convention violations. Use after
5+
modifying files under components/frontend/src/. Checks for raw HTML elements,
6+
manual fetch, any types, interface usage, component size, and missing states.
7+
tools:
8+
- Read
9+
- Grep
10+
- Glob
11+
- Bash
12+
---
13+
14+
# Frontend Review Agent
15+
16+
Review frontend code against documented conventions.
17+
18+
## Context
19+
20+
Load these files before running checks:
21+
22+
1. `components/frontend/DEVELOPMENT.md`
23+
2. `components/frontend/REACT_QUERY_PATTERNS.md`
24+
3. `components/frontend/DESIGN_GUIDELINES.md` (if it exists)
25+
26+
## Checks
27+
28+
### F1: No raw HTML elements (Critical)
29+
30+
```bash
31+
grep -rn "<button\|<input\|<select\|<dialog\|<textarea" components/frontend/src/ --include="*.tsx" | grep -v "components/ui/"
32+
```
33+
34+
Must use Shadcn UI components from `@/components/ui/`.
35+
36+
### F2: No manual fetch() in components (Critical)
37+
38+
```bash
39+
grep -rn "fetch(" components/frontend/src/app/ components/frontend/src/components/ --include="*.tsx" --include="*.ts" | grep -v "src/app/api/"
40+
```
41+
42+
Use React Query hooks from `@/services/queries/`.
43+
44+
### F3: No interface declarations (Major)
45+
46+
```bash
47+
grep -rn "^export interface \|^interface " components/frontend/src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules"
48+
```
49+
50+
Use `type` instead of `interface`.
51+
52+
### F4: No any types (Critical)
53+
54+
```bash
55+
grep -rn ": any\b\|as any\b\|<any>" components/frontend/src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules\|\.d\.ts"
56+
```
57+
58+
Use proper types, `unknown`, or generic constraints.
59+
60+
### F5: Components under 200 lines (Minor)
61+
62+
```bash
63+
find components/frontend/src/ -name "*.tsx" -print0 | xargs -0 wc -l | sort -rn | head -20
64+
```
65+
66+
Flag components exceeding 200 lines. Consider splitting.
67+
68+
### F6: Loading/error/empty states (Major)
69+
70+
For components using `useQuery`:
71+
- Must reference `isLoading` or `isPending`
72+
- Must reference `error`
73+
- Should handle empty data
74+
75+
```bash
76+
grep -rl "useQuery\|useSessions\|useSession" \
77+
components/frontend/src/app/ components/frontend/src/components/ --include="*.tsx"
78+
```
79+
80+
Then check each file for `isLoading\|isPending` and `error` references.
81+
82+
### F7: Single-use components in shared directories (Minor)
83+
84+
Check `components/frontend/src/components/` for components imported only once. These should be co-located with their page in `_components/`.
85+
86+
### F8: Feature flag on new pages (Major)
87+
88+
New `page.tsx` files should reference `useWorkspaceFlag` or `useFlag` for feature gating.
89+
90+
## Output Format
91+
92+
```markdown
93+
# Frontend Review
94+
95+
## Summary
96+
[1-2 sentence overview]
97+
98+
## Findings
99+
100+
### Blocker
101+
[Must fix — or "None"]
102+
103+
### Critical
104+
[Should fix — or "None"]
105+
106+
### Major
107+
[Important — or "None"]
108+
109+
### Minor
110+
[Nice-to-have — or "None"]
111+
112+
## Score
113+
[X/8 checks passed]
114+
```
115+
116+
Each finding includes: file:line, problem description, convention violated, suggested fix.

0 commit comments

Comments
 (0)