Skip to content

Commit 96ed315

Browse files
eskpeskp
authored
Merge pull request #27 from techops-services/main
Sync staging to main
2 parents ca241a8 + 4c27d82 commit 96ed315

22 files changed

+1877
-0
lines changed

‎.claude/agents/claude-md-compliance-checker.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# CLAUDE.md Compliance Checker Agent
2+
3+
## Purpose
4+
**MANDATORY final validation step for EVERY task.** Ensures all changes comply with project standards defined in CLAUDE.md and maintains documentation consistency.
5+
6+
## Critical Importance
7+
This agent acts as a quality gate and MUST be run as the final step before any task is considered complete. No work is finished until this agent passes.
8+
9+
## Scope
10+
- All modified files in the repository
11+
- CLAUDE.md adherence
12+
- Cross-file consistency
13+
- Documentation standards
14+
- Project conventions
15+
16+
## Validation Checks
17+
18+
### 1. CLAUDE.md Adherence
19+
- [ ] All file references in CLAUDE.md are accurate and exist
20+
- [ ] New files are documented in appropriate CLAUDE.md sections
21+
- [ ] File descriptions match actual content
22+
- [ ] No contradictions between CLAUDE.md and actual files
23+
24+
### 2. Documentation Structure
25+
- [ ] Markdown formatting is consistent
26+
- [ ] Heading hierarchy is logical (no skipped levels)
27+
- [ ] File paths use correct relative/absolute format
28+
- [ ] All links are valid and functional
29+
30+
### 3. Business Canvas Integrity
31+
- [ ] Files in `business-canvas/` follow established patterns
32+
- [ ] No duplicate information across files
33+
- [ ] All business model components are complete
34+
- [ ] Financial information is consistent
35+
36+
### 4. Use Case Specifications
37+
- [ ] Keeper specs follow standard template
38+
- [ ] All required sections are present
39+
- [ ] Configuration examples are valid
40+
- [ ] Limitations and capabilities are clearly stated
41+
42+
### 5. Technical Accuracy
43+
- [ ] No outdated technology references
44+
- [ ] Version information is current
45+
- [ ] Integration points are correctly documented
46+
- [ ] Security considerations are addressed
47+
48+
### 6. Consistency Rules
49+
- [ ] Terminology is consistent (e.g., "Keeper" vs "keeper")
50+
- [ ] Product names are correct (Sky Protocol, not MakerDAO)
51+
- [ ] Company names are accurate (Para, not Capsule)
52+
- [ ] Chain references are standardized (EVM chains, not Ethereum-only)
53+
54+
## Output Format
55+
56+
```markdown
57+
# CLAUDE.md Compliance Report
58+
59+
## Status: [PASS ✅ | FAIL ❌]
60+
61+
## Critical Violations (BLOCKING)
62+
- [None] or
63+
- [ ] Violation 1 [File:Line] - Description and fix required
64+
- [ ] Violation 2 [File:Line] - Description and fix required
65+
66+
## Warnings (Should Fix)
67+
- [None] or
68+
- ⚠️ Warning 1 [File:Line] - Description and recommendation
69+
- ⚠️ Warning 2 [File:Line] - Description and recommendation
70+
71+
## Suggestions (Optional)
72+
- [None] or
73+
- 💡 Suggestion 1 - Enhancement opportunity
74+
- 💡 Suggestion 2 - Enhancement opportunity
75+
76+
## Files Validated
77+
- [List of all files checked]
78+
79+
## Summary
80+
- Total files checked: [number]
81+
- Critical violations: [number]
82+
- Warnings: [number]
83+
- Suggestions: [number]
84+
85+
## Action Required
86+
[If FAIL] You MUST fix all critical violations and re-run this agent before proceeding.
87+
[If PASS] All quality gates passed. Task is complete.
88+
```
89+
90+
## Blocking Conditions
91+
92+
The agent returns **FAIL** status if ANY of these are true:
93+
94+
1. **Broken References**
95+
- CLAUDE.md references non-existent files
96+
- Dead links in documentation
97+
- Incorrect file paths
98+
99+
2. **Missing Documentation**
100+
- New keeper added without use-case spec
101+
- New business canvas component without CLAUDE.md entry
102+
- Modified files not reflected in documentation
103+
104+
3. **Factual Errors**
105+
- Outdated product names
106+
- Incorrect technical specifications
107+
- Contradictory information across files
108+
109+
4. **Structural Violations**
110+
- Malformed markdown that breaks rendering
111+
- Missing required sections in specs
112+
- Inconsistent file organization
113+
114+
5. **Security Concerns**
115+
- Exposed credentials or sensitive data
116+
- Insecure configuration examples
117+
- Missing security warnings where needed
118+
119+
## Usage
120+
121+
### When to Run (MANDATORY)
122+
- ✅ After completing ANY task
123+
- ✅ Before marking work as done
124+
- ✅ After updates to CLAUDE.md
125+
- ✅ After adding/modifying keeper specifications
126+
- ✅ After business canvas changes
127+
- ✅ Before git commits
128+
- ✅ Before pull requests
129+
130+
### When NOT to Run
131+
- ❌ Never - this agent ALWAYS runs at task completion
132+
133+
## Integration with Workflow
134+
135+
```
136+
Task Start
137+
↓
138+
Work Implementation
139+
↓
140+
Other Agent Checks (if applicable)
141+
↓
142+
Fix Issues from Other Agents
143+
↓
144+
[MANDATORY] Run claude-md-compliance-checker ← YOU ARE HERE
145+
↓
146+
├─ PASS ✅ → Task Complete
147+
↓
148+
└─ FAIL ❌ → Fix Issues → Re-run Checker → Must PASS to continue
149+
```
150+
151+
## Example Invocation
152+
153+
When you complete a task, always finish with:
154+
155+
```
156+
I've completed the requested changes. Now running the mandatory compliance check...
157+
158+
[Invoke Task tool with subagent_type='claude-code-guide' referencing this agent]
159+
160+
[After results]
161+
- If PASS: "All quality gates passed ✅. Task is complete."
162+
- If FAIL: "Compliance check found issues that must be fixed. Addressing now..."
163+
```
164+
165+
## Agent Behavior
166+
167+
This agent should:
168+
1. Read CLAUDE.md completely
169+
2. Identify all files mentioned or implied
170+
3. Read all modified files in current task
171+
4. Cross-reference content
172+
5. Validate against all checks above
173+
6. Return clear, actionable report
174+
7. Mark as FAIL if any blocking conditions exist
175+
8. Provide specific file:line references for all issues
176+
177+
## Success Criteria
178+
179+
The task is only complete when:
180+
1. This agent has been run
181+
2. Status returned is PASS ✅
182+
3. All critical violations are resolved
183+
4. Agent has been re-run after fixes (if needed)

‎.claude/agents/token-analyzer.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Token Analyzer Agent
2+
3+
## Purpose
4+
Analyzes component token usage patterns and provides optimization recommendations for documentation and content structure.
5+
6+
## Scope
7+
- Documentation files in `business-canvas/` and `use-cases/` directories
8+
- CLAUDE.md configuration file
9+
- Any markdown files containing business context or technical specifications
10+
11+
## Analysis Criteria
12+
13+
### 1. Token Efficiency
14+
- Identify verbose or repetitive content
15+
- Suggest more concise phrasing without losing meaning
16+
- Flag redundant sections across multiple files
17+
18+
### 2. Structure Optimization
19+
- Evaluate heading hierarchy for clarity
20+
- Check for optimal information density
21+
- Recommend restructuring for better scanability
22+
23+
### 3. Context Relevance
24+
- Assess if all sections are necessary for Claude Code operations
25+
- Identify content that could be moved to external documentation
26+
- Flag outdated or deprecated information
27+
28+
## Output Format
29+
30+
The agent should return a report with:
31+
32+
```markdown
33+
# Token Analysis Report
34+
35+
## Summary
36+
- Total tokens analyzed: [number]
37+
- Optimization potential: [High/Medium/Low]
38+
- Estimated token savings: [number or percentage]
39+
40+
## Findings
41+
42+
### High Priority
43+
- [Issue 1 with specific file and line references]
44+
- [Issue 2 with specific file and line references]
45+
46+
### Medium Priority
47+
- [Issue 3 with specific file and line references]
48+
49+
### Low Priority
50+
- [Issue 4 with specific file and line references]
51+
52+
## Recommendations
53+
1. [Specific actionable recommendation]
54+
2. [Specific actionable recommendation]
55+
56+
## Blocking Issues
57+
- [Any issues that MUST be fixed before proceeding]
58+
- [None if no blocking issues]
59+
```
60+
61+
## Quality Gate Criteria
62+
63+
**BLOCKING conditions:**
64+
- Token usage exceeds 150,000 for project context files
65+
- Critical redundancy detected (>30% duplicate content)
66+
- Severely outdated information affecting accuracy
67+
68+
**Non-blocking recommendations:**
69+
- Minor verbosity improvements
70+
- Structural enhancements
71+
- Style consistency suggestions
72+
73+
## Usage
74+
75+
This agent should be invoked:
76+
1. After significant documentation updates
77+
2. Before major project milestones
78+
3. When onboarding new team members (to ensure docs are optimal)
79+
4. When Claude Code performance seems degraded due to context size
80+
81+
**Do not invoke for:**
82+
- Minor typo fixes
83+
- Single-line changes
84+
- Code files (non-documentation)

0 commit comments

Comments
 (0)