Skip to content

Commit 50a2a72

Browse files
Stev WayneStev Wayne
Stev Wayne
authored and
Stev Wayne
committed
feat: add Claude Code Agent Skill packaging
Add AI-DLC as an Agent Skill (https://agentskills.io) for Claude Code. Structure: - aidlc/SKILL.md: YAML frontmatter + core-workflow.md (path refs updated) - aidlc/references/: mirrors aws-aidlc-rule-details/ (all files verbatim) Installation: cp -r aidlc ~/.claude/skills/ # personal cp -r aidlc .claude/skills/ # project-level Invoke with /aidlc or let Claude activate automatically on dev tasks. Compatible with any Agent Skills-compliant tool (Cursor, Gemini CLI, etc.).
1 parent 94cdfe8 commit 50a2a72

28 files changed

+5436
-0
lines changed

‎aidlc/SKILL.md‎

Lines changed: 548 additions & 0 deletions
Large diffs are not rendered by default.

‎aidlc/references/common/ascii-diagram-standards.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# ASCII Diagram Standards
2+
3+
## MANDATORY: Use Basic ASCII Only
4+
5+
**CRITICAL**: ALWAYS use basic ASCII characters for diagrams (maximum compatibility).
6+
7+
### ✅ ALLOWED: `+` `-` `|` `^` `v` `<` `>` and alphanumeric text
8+
9+
### ❌ FORBIDDEN: Unicode box-drawing characters
10+
- NO: `┌` `─` `│` `└` `┐` `┘` `├` `┤` `┬` `┴` `┼` `▼` `▲` `►` `◄`
11+
- Reason: Inconsistent rendering across fonts/platforms
12+
13+
## Standard ASCII Diagram Patterns
14+
15+
### CRITICAL: Character Width Rule
16+
**Every line in a box MUST have EXACTLY the same character count (including spaces)**
17+
18+
✅ CORRECT (all lines = 67 chars):
19+
```
20+
+---------------------------------------------------------------+
21+
| Component Name |
22+
| Description text here |
23+
+---------------------------------------------------------------+
24+
```
25+
26+
❌ WRONG (inconsistent widths):
27+
```
28+
+---------------------------------------------------------------+
29+
| Component Name |
30+
| Description text here |
31+
+---------------------------------------------------------------+
32+
```
33+
34+
### Box Pattern
35+
```
36+
+-----------------------------------------------------+
37+
| |
38+
| Calculator Application |
39+
| |
40+
| Provides basic arithmetic operations for users |
41+
| through a web-based interface |
42+
| |
43+
+-----------------------------------------------------+
44+
```
45+
46+
### Nested Boxes
47+
```
48+
+-------------------------------------------------------+
49+
| Web Server (PHP Runtime) |
50+
| +-------------------------------------------------+ |
51+
| | index.php (Monolithic Application) | |
52+
| | +-------------------------------------------+ | |
53+
| | | HTML Template (View Layer) | | |
54+
| | | - Form rendering | | |
55+
| | | - Result display | | |
56+
| | +-------------------------------------------+ | |
57+
| +-------------------------------------------------+ |
58+
+-------------------------------------------------------+
59+
```
60+
61+
### Arrows and Connections
62+
```
63+
+----------+
64+
| Source |
65+
+----------+
66+
|
67+
| HTTP POST
68+
v
69+
+----------+
70+
| Target |
71+
+----------+
72+
```
73+
74+
### Horizontal Flow
75+
```
76+
+-------+ +-------+ +-------+
77+
| Step1 | --> | Step2 | --> | Step3 |
78+
+-------+ +-------+ +-------+
79+
```
80+
81+
### Vertical Flow with Labels
82+
```
83+
User Action Flow:
84+
|
85+
v
86+
+----------+
87+
| Input |
88+
+----------+
89+
|
90+
| validates
91+
v
92+
+----------+
93+
| Process |
94+
+----------+
95+
|
96+
| returns
97+
v
98+
+----------+
99+
| Output |
100+
+----------+
101+
```
102+
103+
## Validation
104+
105+
Before creating diagrams:
106+
- [ ] Basic ASCII only: `+` `-` `|` `^` `v` `<` `>`
107+
- [ ] No Unicode box-drawing
108+
- [ ] Spaces (not tabs) for alignment
109+
- [ ] Corners use `+`
110+
- [ ] **ALL box lines same character width** (count characters including spaces)
111+
- [ ] Test: Verify corners align vertically in monospace font
112+
113+
## Alternative
114+
115+
For complex diagrams, use Mermaid (see `content-validation.md`)
116+

‎aidlc/references/common/content-validation.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Content Validation Rules
2+
3+
## MANDATORY: Content Validation Before File Creation
4+
5+
**CRITICAL**: All generated content MUST be validated before writing to files to prevent parsing errors.
6+
7+
## ASCII Diagram Standards
8+
9+
**CRITICAL**: Before creating ANY file with ASCII diagrams:
10+
11+
1. **LOAD** `common/ascii-diagram-standards.md`
12+
2. **VALIDATE** each diagram:
13+
- Count characters per line (all lines MUST be same width)
14+
- Use ONLY: `+` `-` `|` `^` `v` `<` `>` and spaces
15+
- NO Unicode box-drawing characters
16+
- Spaces only (NO tabs)
17+
3. **TEST** alignment by verifying box corners align vertically
18+
19+
**See `common/ascii-diagram-standards.md` for patterns and validation checklist.**
20+
21+
## Mermaid Diagram Validation
22+
23+
### Required Validation Steps
24+
1. **Syntax Check**: Validate Mermaid syntax before file creation
25+
2. **Character Escaping**: Ensure special characters are properly escaped
26+
3. **Fallback Content**: Provide text alternative if Mermaid fails validation
27+
28+
### Mermaid Validation Rules
29+
```markdown
30+
## BEFORE creating any file with Mermaid diagrams:
31+
32+
1. Check for invalid characters in node IDs (use alphanumeric + underscore only)
33+
2. Escape special characters in labels: " → \" and ' → \'
34+
3. Validate flowchart syntax: node connections must be valid
35+
4. Test diagram parsing with simple validation
36+
37+
## FALLBACK: If Mermaid validation fails, use text-based workflow representation
38+
```
39+
40+
### Implementation Pattern
41+
```markdown
42+
## Workflow Visualization
43+
44+
### Mermaid Diagram (if syntax valid)
45+
```mermaid
46+
[validated diagram content]
47+
```
48+
49+
### Text Alternative (always include)
50+
```
51+
Phase 1: INCEPTION
52+
- Stage 1: Workspace Detection (COMPLETED)
53+
- Stage 2: Requirements Analysis (COMPLETED)
54+
[continue with text representation]
55+
```
56+
57+
## General Content Validation
58+
59+
### Pre-Creation Validation Checklist
60+
- [ ] Validate embedded code blocks (Mermaid, JSON, YAML)
61+
- [ ] Check special character escaping
62+
- [ ] Verify markdown syntax correctness
63+
- [ ] Test content parsing compatibility
64+
- [ ] Include fallback content for complex elements
65+
66+
### Error Prevention Rules
67+
1. **Always validate before using tools/commands to write files**: Never write unvalidated content
68+
2. **Escape special characters**: Particularly in diagrams and code blocks
69+
3. **Provide alternatives**: Include text versions of visual content
70+
4. **Test syntax**: Validate complex content structures
71+
72+
## Validation Failure Handling
73+
74+
### When Validation Fails
75+
1. **Log the error**: Record what failed validation
76+
2. **Use fallback content**: Switch to text-based alternative
77+
3. **Continue workflow**: Don't block on content validation failures
78+
4. **Inform user**: Mention simplified content was used due to parsing constraints

‎aidlc/references/common/depth-levels.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Adaptive Depth
2+
3+
**Purpose**: Explain how AI-DLC adapts detail level to problem complexity
4+
5+
## Core Principle
6+
7+
**When a stage executes, ALL its defined artifacts are created. The "depth" refers to the level of detail and rigor within those artifacts, which adapts to the problem's complexity.**
8+
9+
## Stage Selection vs Detail Level
10+
11+
### Stage Selection (Binary)
12+
- **Workflow Planning** decides: EXECUTE or SKIP for each stage
13+
- **If EXECUTE**: Stage runs and creates ALL its defined artifacts
14+
- **If SKIP**: Stage doesn't run at all
15+
16+
### Detail Level (Adaptive)
17+
- **Simple problems**: Concise artifacts with essential detail
18+
- **Complex problems**: Comprehensive artifacts with extensive detail
19+
- **Model decides**: Based on problem characteristics, not prescriptive rules
20+
21+
## Factors Influencing Detail Level
22+
23+
The model considers these factors when determining appropriate detail:
24+
25+
1. **Request Clarity**: How clear and complete is the user's request?
26+
2. **Problem Complexity**: How intricate is the solution space?
27+
3. **Scope**: Single file, component, multiple components, or system-wide?
28+
4. **Risk Level**: What's the impact of errors or omissions?
29+
5. **Available Context**: Greenfield vs brownfield, existing documentation
30+
6. **User Preferences**: Has user expressed preference for brevity or detail?
31+
32+
## Example: Requirements Analysis Artifacts
33+
34+
**All scenarios create the same artifacts**:
35+
- `requirement-verification-questions.md` (if needed)
36+
- `requirements.md`
37+
38+
**Note**: User's initial request is captured in `audit.md` (no separate user-intent.md needed)
39+
40+
**Detail level varies by complexity**:
41+
42+
### Simple Scenario (Bug Fix)
43+
- **requirement-verification-questions.md**: necessary clarifying questions
44+
- **requirements.md**: Concise functional requirement, minimal sections
45+
46+
### Complex Scenario (System Migration)
47+
- **requirement-verification-questions.md**: Multiple rounds, 10+ questions
48+
- **requirements.md**: Comprehensive functional + non-functional requirements, traceability, acceptance criteria
49+
50+
## Example: Application Design Artifacts
51+
52+
**All scenarios create the same artifacts**:
53+
- `application-design.md`
54+
- `component-diagram.md`
55+
56+
**Detail level varies by complexity**:
57+
58+
### Simple Scenario (Single Component)
59+
- **application-design.md**: Basic component description, key methods
60+
- **component-diagram.md**: Simple diagram with essential relationships
61+
62+
### Complex Scenario (Multi-Component System)
63+
- **application-design.md**: Detailed component responsibilities, all methods with signatures, design patterns, alternatives considered
64+
- **component-diagram.md**: Comprehensive diagram with all relationships, data flows, integration points
65+
66+
## Guiding Principle for Model
67+
68+
**"Create exactly the detail needed for the problem at hand - no more, no less."**
69+
70+
- Don't artificially inflate simple problems with unnecessary detail
71+
- Don't shortchange complex problems by omitting critical detail
72+
- Let problem characteristics drive detail level naturally
73+
- All required artifacts are always created when stage executes

0 commit comments

Comments
 (0)