Skip to content

Commit a44d522

Browse files
michaeljabbourclaude
michaeljabbour
and
claude
committed
feat: add principle builder CLI tool
Add comprehensive CLI tool for managing AI-first principle specifications. **Features:** - List principles (with filtering by category/status) - Validate specifications against quality standards - Quality scoring with comprehensive checks - Progress tracking across all specifications - Stub generation for new principles **Tool Commands:** - list: View all principles with filtering - validate: Check specification structure - check-quality: Comprehensive quality scoring - update-progress: Statistics by category - create: Generate new principle stubs **Quality Checks:** - Required sections present - Minimum 5 example pairs - 6+ related principles - 8-12 checklist items - 5-7 common pitfalls - Complete metadata **Documentation:** - tools/README.md: Complete tool guide - Main README updated with Quick Start and usage **Demonstrates Principles:** - microsoft#28 CLI-First Design - microsoft#29 Tool Ecosystems as Extensions - microsoft#25 Simple Interfaces by Design - microsoft#31 Idempotency by Design - microsoft#9 Tests as Quality Gate Provides path for maintaining and expanding the specification library as Amplifier grows. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent 95cb149 commit a44d522

File tree

3 files changed

+666
-5
lines changed

3 files changed

+666
-5
lines changed

‎ai-first-principles/README.md‎

Lines changed: 65 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -118,19 +118,79 @@ When debugging issues:
118118
3. Review Related Principles for systemic issues
119119
4. Update the principle spec if you discover new pitfalls
120120

121+
## Principle Builder Tool
122+
123+
The specification library includes a CLI tool for managing and maintaining principles.
124+
125+
### Quick Start
126+
127+
```bash
128+
# List all principles
129+
cd ai-first-principles
130+
python3 tools/principle_builder.py list
131+
132+
# Validate a principle
133+
python3 tools/principle_builder.py validate 31
134+
135+
# Check quality score
136+
python3 tools/principle_builder.py check-quality 31
137+
138+
# Update progress statistics
139+
python3 tools/principle_builder.py update-progress
140+
```
141+
142+
### Common Operations
143+
144+
**Validate all specifications:**
145+
```bash
146+
for i in {1..44}; do python3 tools/principle_builder.py validate $i; done
147+
```
148+
149+
**Quality check high-priority principles:**
150+
```bash
151+
for i in 7 8 9 26 31 32; do python3 tools/principle_builder.py check-quality $i; done
152+
```
153+
154+
**List incomplete specifications:**
155+
```bash
156+
python3 tools/principle_builder.py list --status incomplete
157+
```
158+
159+
### Tool Features
160+
161+
- **Validation**: Check specifications against quality standards
162+
- **Quality Scoring**: Comprehensive quality metrics (structure, examples, cross-references)
163+
- **Progress Tracking**: Automatic completion statistics by category
164+
- **Listing**: Filter by category, status, or view all
165+
- **Stub Generation**: Create new principle specifications from template
166+
167+
See [tools/README.md](tools/README.md) for complete documentation.
168+
169+
### Principles Demonstrated
170+
171+
The tool itself demonstrates AI-first principles:
172+
- **#28 - CLI-First Design**: Command-line interface for automation
173+
- **#29 - Tool Ecosystems**: Extends library functionality through tools
174+
- **#25 - Simple Interfaces**: Clear, focused commands
175+
- **#31 - Idempotency**: Validation operations are repeatable
176+
- **#09 - Tests as Quality Gate**: Automated quality checking
177+
121178
## File Structure
122179

123180
```
124181
ai-first-principles/
125182
├── README.md # This file
126183
├── TEMPLATE.md # Template for creating new specs
127-
├── PROGRESS.md # Tracking completion status
184+
├── PROGRESS.md # Tracking completion status (44/44 complete)
128185
├── cross-reference-index.md # Map of principle relationships
186+
├── tools/ # Principle management tools
187+
│ ├── README.md # Tool documentation
188+
│ └── principle_builder.py # CLI for validation, quality checks, listing
129189
└── principles/
130-
├── people/ # Human-focused principles
131-
├── process/ # Workflow and methodology principles
132-
├── technology/ # Technical implementation principles
133-
└── governance/ # Policy and operations principles
190+
├── people/ # Human-focused principles (6 specs)
191+
├── process/ # Workflow and methodology principles (13 specs)
192+
├── technology/ # Technical implementation principles (18 specs)
193+
└── governance/ # Policy and operations principles (7 specs)
134194
```
135195

136196
## Contributing

‎ai-first-principles/tools/README.md‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
# Principle Builder Tool
2+
3+
CLI tool for creating, validating, and managing AI-first principle specifications.
4+
5+
## Installation
6+
7+
The tool is standalone Python and requires no additional dependencies beyond Python 3.11+.
8+
9+
```bash
10+
cd ai-first-principles
11+
python3 tools/principle_builder.py --help
12+
```
13+
14+
## Usage
15+
16+
### List All Principles
17+
18+
```bash
19+
# List all principles
20+
python3 tools/principle_builder.py list
21+
22+
# List by category
23+
python3 tools/principle_builder.py list --category technology
24+
25+
# List only complete specifications
26+
python3 tools/principle_builder.py list --status complete
27+
```
28+
29+
**Example Output:**
30+
```
31+
📋 Found 44 principles:
32+
33+
✅ #01 - small-ai-first-working-groups (people)
34+
✅ #02 - strategic-human-touchpoints (people)
35+
...
36+
```
37+
38+
### Validate a Principle
39+
40+
Check if a principle specification meets structural requirements:
41+
42+
```bash
43+
python3 tools/principle_builder.py validate 31
44+
```
45+
46+
**Example Output:**
47+
```
48+
✅ Principle #31 is valid
49+
50+
⚠️ Warnings:
51+
- Only 5 examples found, should have 5
52+
```
53+
54+
### Check Quality
55+
56+
Perform comprehensive quality check with scoring:
57+
58+
```bash
59+
python3 tools/principle_builder.py check-quality 31
60+
```
61+
62+
**Example Output:**
63+
```
64+
🎯 Quality Check for Principle #31:
65+
Score: 100.0%
66+
67+
Checks:
68+
✅ Structure
69+
✅ Examples
70+
✅ Code Blocks
71+
✅ Related Principles
72+
✅ Checklist Items
73+
✅ Common Pitfalls
74+
✅ Tools Section
75+
✅ Metadata Complete
76+
```
77+
78+
### Update Progress Statistics
79+
80+
Scan all specifications and show completion statistics:
81+
82+
```bash
83+
python3 tools/principle_builder.py update-progress
84+
```
85+
86+
**Example Output:**
87+
```
88+
📊 Progress Update:
89+
✅ 44/44 specifications complete (100.0%)
90+
91+
By category:
92+
People: 6/6
93+
Process: 13/13
94+
Technology: 18/18
95+
Governance: 7/7
96+
```
97+
98+
### Create a New Principle Stub
99+
100+
Generate a new specification from the template:
101+
102+
```bash
103+
# Create principle #45 (if extending the library)
104+
python3 tools/principle_builder.py create 45 "new-principle-name"
105+
106+
# Create with explicit category
107+
python3 tools/principle_builder.py create 45 "new-principle-name" --category governance
108+
```
109+
110+
**Note:** The tool automatically determines category based on principle number ranges:
111+
- People: 1-6
112+
- Process: 7-19
113+
- Technology: 20-37
114+
- Governance: 38-44
115+
116+
## Quality Checks
117+
118+
The tool validates specifications against quality standards:
119+
120+
### Required Sections
121+
- Plain-Language Definition
122+
- Why This Matters for AI-First Development
123+
- Implementation Approaches
124+
- Good Examples vs Bad Examples (5 pairs minimum)
125+
- Related Principles (6 minimum)
126+
- Common Pitfalls (5-7 recommended)
127+
- Tools & Frameworks
128+
- Implementation Checklist (8-12 items)
129+
- Metadata (complete)
130+
131+
### Quality Scoring
132+
133+
The `check-quality` command scores specifications on:
134+
- **Structure**: All required sections present
135+
- **Examples**: At least 5 example pairs
136+
- **Code Blocks**: At least 10 code blocks (good/bad pairs)
137+
- **Related Principles**: At least 6 cross-references
138+
- **Checklist Items**: At least 8 actionable items
139+
- **Common Pitfalls**: At least 5 documented
140+
- **Tools Section**: Properly organized by category
141+
- **Metadata**: Complete with category, number, status
142+
143+
## Workflow
144+
145+
### Adding a New Principle
146+
147+
1. **Create Stub**:
148+
```bash
149+
python3 tools/principle_builder.py create 45 "new-principle-name"
150+
```
151+
152+
2. **Edit Specification**:
153+
- Open the created file
154+
- Fill in all sections following `TEMPLATE.md`
155+
- Use `#31-idempotency-by-design.md` as quality reference
156+
157+
3. **Validate**:
158+
```bash
159+
python3 tools/principle_builder.py validate 45
160+
```
161+
162+
4. **Check Quality**:
163+
```bash
164+
python3 tools/principle_builder.py check-quality 45
165+
```
166+
167+
5. **Update Progress**:
168+
```bash
169+
python3 tools/principle_builder.py update-progress
170+
```
171+
172+
### Maintaining Existing Principles
173+
174+
1. **List specifications by status**:
175+
```bash
176+
python3 tools/principle_builder.py list --status incomplete
177+
```
178+
179+
2. **Validate all complete specs**:
180+
```bash
181+
for i in {1..44}; do
182+
python3 tools/principle_builder.py validate $i
183+
done
184+
```
185+
186+
3. **Quality check high-priority specs**:
187+
```bash
188+
for i in 7 8 9 26 31 32; do
189+
python3 tools/principle_builder.py check-quality $i
190+
done
191+
```
192+
193+
## Integration with Development Workflow
194+
195+
### Pre-Commit Hook
196+
197+
Add validation to your git pre-commit hook:
198+
199+
```bash
200+
# .git/hooks/pre-commit
201+
#!/bin/bash
202+
cd ai-first-principles
203+
for file in $(git diff --cached --name-only | grep 'principles/.*\.md$'); do
204+
number=$(basename "$file" | cut -d'-' -f1)
205+
python3 tools/principle_builder.py validate $number || exit 1
206+
done
207+
```
208+
209+
### CI/CD Integration
210+
211+
Include quality checks in CI pipeline:
212+
213+
```yaml
214+
# .github/workflows/principles-quality.yml
215+
name: Principles Quality Check
216+
on: [pull_request]
217+
jobs:
218+
validate:
219+
runs-on: ubuntu-latest
220+
steps:
221+
- uses: actions/checkout@v3
222+
- name: Validate all principles
223+
run: |
224+
cd ai-first-principles
225+
for i in {1..44}; do
226+
python3 tools/principle_builder.py validate $i
227+
done
228+
```
229+
230+
## Principles Demonstrated
231+
232+
This tool demonstrates several AI-first principles:
233+
234+
- **#28 CLI-First Design**: Command-line interface as primary interaction
235+
- **#29 Tool Ecosystems as Extensions**: Extends the principles library with tooling
236+
- **#25 Simple Interfaces by Design**: Clear, focused commands
237+
- **#31 Idempotency by Design**: Validation is idempotent
238+
- **#09 Tests as Quality Gate**: Quality checks validate specifications
239+
- **#16 Docs Define, Not Describe**: Template defines what specs should contain
240+
- **#37 Declarative Over Imperative**: Declare what to validate, not how
241+
242+
## Future Enhancements
243+
244+
Potential additions:
245+
- Generate cross-reference index automatically
246+
- Export specifications to different formats (PDF, HTML)
247+
- Dependency graph visualization
248+
- Automated quality report generation
249+
- Integration with AI agents for spec completion
250+
- Batch operations for bulk validation/quality checks
251+
252+
## Contributing
253+
254+
When extending this tool:
255+
1. Follow the existing command structure
256+
2. Add tests for new functionality
257+
3. Update this README with new commands
258+
4. Ensure tool remains dependency-free (stdlib only)
259+
5. Keep CLI output clear and actionable

0 commit comments

Comments
 (0)