Skip to content

Commit 2887d6a

Browse files
matscodematscode
committed
feat: update persona template and examples
1 parent 92b6385 commit 2887d6a

13 files changed

+351
-24
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ The persona system ensures you get exactly the right level of detail and communi
115115
| **Trae AI** | IDE | `.trae > rules > project_rules.md` | ✅ Tested |
116116
| **Cursor** | IDE | `AGENTS.md` | ✅ Tested |
117117
| **Windsurf** | IDE | `.windsurf > rules > project_rules.md` | ✅ Tested |
118-
| **Kiro** | IDE | `.kiro > steering > rules.md` | ✅ Tested |
118+
| **Kiro (Vibe Mode)** | IDE | `.kiro > steering > rules.md` | ✅ Tested |
119119
| **Codex** | IDE | `AGENTS.md` | ⏳ Not Tested Yet |
120120
| **Claude Code** | IDE | `AGENTS.md` | ⏳ Not Tested Yet |
121121
| **GitHub Copilot** | IDE | `AGENTS.md` | ❌ Not Working Yet |

‎rules/core-principles.rules.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,8 @@ This file defines the fundamental workflow and core principles that ALL coding a
6262
- **MAINTAIN** consistency with established patterns
6363
- **IMPLEMENT** only what was approved
6464
- **AVOID** adding unrequested features
65+
- **MANDATORY SPEC REFERENCES:** ALL generated code files MUST include spec reference comments - **FOLLOW:** [rules/spec-reference.rules.md](./spec-reference.rules.md) for complete requirements and language-specific formats
66+
- **LEGACY CODE ENFORCEMENT:** When modifying existing code without spec references, **IMMEDIATELY HALT** and follow the "LEGACY CODE SPECIFICATION WORKFLOW" defined in [rules/spec-management.rules.md](./spec-management.rules.md) - **NO EXCEPTIONS**
6567

6668
### 8. LOOP BACK IF NEW DECISIONS ARISE
6769
- **STOP IMMEDIATELY** if new decisions emerge during implementation
@@ -110,6 +112,7 @@ This file defines the fundamental workflow and core principles that ALL coding a
110112
3. **UNDOCUMENTED DECISIONS** - Making architectural choices without specification
111113
4. **UNAUTHORIZED IMPLEMENTATION** - Coding without explicit approval
112114
5. **PATTERN VIOLATIONS** - Ignoring established architectural patterns
115+
6. **LEGACY CODE VIOLATIONS** - Modifying existing code without following the mandatory legacy code specification workflow defined in [rules/spec-management.rules.md](./spec-management.rules.md)
113116

114117
**VIOLATION CONSEQUENCES:**
115118
- **FIRST VIOLATION:** Stop immediately, follow proper workflow, restart implementation

‎rules/index.rules.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,9 @@
1313
1. **[rules/core-principles.rules.md](./core-principles.rules.md)** - Core workflow and principles
1414
2. **[rules/interactive-input.rules.md](./interactive-input.rules.md)** - Interactive input protocols and run_command usage
1515
3. **[rules/user-persona.rules.md](./user-persona.rules.md)** - User persona management
16-
4. **[rules/spec-management.rules.md](./spec-management.rules.md)** - Specification creation and management
17-
5. **[rules/violation-enforcement.rules.md](./violation-enforcement.rules.md)** - Universal violation enforcement system
16+
4. **[rules/spec-management.rules.md](./spec-management.rules.md)** - Specification creation and management (includes legacy code specification workflow)
17+
5. **[rules/spec-reference.rules.md](./spec-reference.rules.md)** - Mandatory spec reference requirements for all generated code
18+
6. **[rules/violation-enforcement.rules.md](./violation-enforcement.rules.md)** - Universal violation enforcement system
1819

1920
**FAILURE TO READ AND FOLLOW ALL RULES = CRITICAL VIOLATION**
2021

‎rules/spec-management.rules.md‎

Lines changed: 55 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,9 @@ When coding agents need context for:
7272
6. **PROPOSE SPECIFICATION** - Create spec file with decision rationale
7373
7. **WAIT FOR APPROVAL** - **USE `run_command` TOOL** for approval questions - **MUST FOLLOW** [rules/interactive-input.rules.md](./interactive-input.rules.md) for context on using run_command tool
7474
8. **DOCUMENT USER DECISIONS** - **MANDATORY:** After ANY user decision or choice, ask: "Should this decision be documented in the relevant spec file for future reference?" - **USE `run_command` TOOL** - **MUST FOLLOW** [rules/interactive-input.rules.md](./interactive-input.rules.md) for context on using run_command tool
75-
9. **RE-READ SPECIFICATIONS** - **MANDATORY:** Read all relevant specs immediately before implementation to ensure most current information
76-
10. **IMPLEMENT ACCORDING TO SPEC** - Follow approved specification exactly
75+
9. **ADD SPEC REFERENCES TO CODE** - **MANDATORY:** When implementing features based on specifications, ALL generated code files MUST include spec reference comments - **FOLLOW:** [rules/spec-reference.rules.md](./spec-reference.rules.md) for complete requirements and formats
76+
10. **RE-READ SPECIFICATIONS** - **MANDATORY:** Read all relevant specs immediately before implementation to ensure most current information
77+
11. **IMPLEMENT ACCORDING TO SPEC** - Follow approved specification exactly
7778

7879
**AGENT QUESTIONING PROTOCOL FOR SPECIFICATION DOCUMENTATION:**
7980
Before creating any specification file, agents MUST ask these questions to ensure optimal documentation:
@@ -199,6 +200,58 @@ Before creating any specification file, agents MUST ask these questions to ensur
199200

200201
---
201202

203+
## LEGACY CODE SPECIFICATION WORKFLOW
204+
205+
**TRIGGER CONDITION:** When modifying existing code files that lack specification references or when encountering undocumented legacy code
206+
207+
**MANDATORY WORKFLOW FOR LEGACY CODE:**
208+
209+
### 1. IMMEDIATE STOP AND ANALYZE
210+
- **HALT** all modification activities immediately upon detecting code without spec references
211+
- **ANALYZE** the existing code logic, patterns, and functionality comprehensively
212+
- **IDENTIFY** the purpose, requirements, and design decisions embedded in the code
213+
- **DOCUMENT** current behavior, dependencies, and implementation approach
214+
- **MAP** relationships between different code components and modules
215+
216+
### 2. CREATE SPECIFICATION FROM CODE ANALYSIS
217+
- **GENERATE** a comprehensive specification file based on thorough code analysis
218+
- **INCLUDE** all identified requirements, patterns, design decisions, and architectural choices
219+
- **STRUCTURE** the spec according to the mandatory template from `rules/templates/spec.template.md`
220+
- **PLACE** the new spec file in the appropriate `project-specs/` directory
221+
- **NAME** the spec file descriptively using kebab-case (e.g., `legacy-authentication.spec.md`, `existing-user-management.spec.md`)
222+
- **DOCUMENT** rationale for reverse-engineered decisions based on code analysis
223+
- **INCLUDE** any discovered technical debt, limitations, or improvement opportunities
224+
225+
### 3. ADD SPEC REFERENCE TO EXISTING CODE
226+
- **INSERT** proper spec reference comment at the top of the existing file
227+
- **USE** the standard format defined in [rules/spec-reference.rules.md](./spec-reference.rules.md)
228+
- **ENSURE** correct comment syntax for the file's programming language
229+
- **MAINTAIN** consistency with existing spec reference patterns in the codebase
230+
231+
### 4. MANDATORY USER APPROVAL
232+
- **PRESENT** the newly created specification to the user for review
233+
- **EXPLAIN** the analysis process and identified requirements clearly
234+
- **HIGHLIGHT** any assumptions made during the reverse-engineering process
235+
- **REQUEST** explicit approval using `run_command` tool - **FOLLOW** [rules/interactive-input.rules.md](./interactive-input.rules.md)
236+
- **ASK:** "I've created a specification based on the existing code analysis. Please review and approve before I proceed with modifications."
237+
- **WAIT** for user confirmation before continuing with any modifications
238+
- **ADDRESS** any user feedback or corrections to the specification
239+
240+
### 5. PROCEED WITH APPROVED MODIFICATIONS
241+
- **ONLY** after explicit user approval, proceed with the requested modifications
242+
- **FOLLOW** the newly created and approved specification exactly
243+
- **MAINTAIN** consistency with the documented requirements and patterns
244+
- **UPDATE** the specification if modifications require new requirements or reveal additional insights
245+
- **ENSURE** all new code includes proper spec references as defined in [rules/spec-reference.rules.md](./spec-reference.rules.md)
246+
247+
**VIOLATION CONSEQUENCES FOR LEGACY CODE WORKFLOW:**
248+
- **CRITICAL VIOLATION:** Modifying legacy code without creating and getting approval for specifications
249+
- **MAJOR VIOLATION:** Proceeding without user approval of generated specifications
250+
- **MINOR VIOLATION:** Incomplete analysis or specification creation
251+
- **ENFORCEMENT:** All violations are subject to the universal violation enforcement system defined in [rules/violation-enforcement.rules.md](./violation-enforcement.rules.md)
252+
253+
---
254+
202255
## MANDATORY ACTIONS FOR AGENTS
203256

204257
**SPECIFICATION MANAGEMENT REQUIREMENTS:**

‎rules/spec-reference.rules.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# Spec Reference Enforcement Rules
2+
3+
**MANDATORY: ALL CODING AGENTS MUST FOLLOW THESE SPEC REFERENCE REQUIREMENTS**
4+
5+
This file defines the mandatory requirements for including specification references in all generated code files. These rules ensure maintainability, traceability, and consistency across the codebase.
6+
7+
**VIOLATION ENFORCEMENT:** All violations of rules in this file are subject to the universal violation enforcement system defined in [violation-enforcement.rules.md](./violation-enforcement.rules.md).
8+
9+
---
10+
11+
## CORE REQUIREMENT
12+
13+
**MANDATORY SPEC REFERENCES:**
14+
ALL generated code files MUST include spec reference comments that clearly identify:
15+
1. The specification file that guided the implementation
16+
2. The specific section within that specification
17+
3. The relationship between the code and the spec requirements
18+
19+
---
20+
21+
## COMMENT FORMAT REQUIREMENTS
22+
23+
### STANDARD FORMAT
24+
```
25+
[COMMENT_SYNTAX] Implementation based on: [project-specs/<filename>.spec.md] - Section: [Specific Section Name]
26+
```
27+
28+
### LANGUAGE-SPECIFIC COMMENT ADAPTATION
29+
30+
**AGENT RESPONSIBILITY:**
31+
- **KNOW** the appropriate comment syntax for the target programming language
32+
- **ADAPT** the spec reference format to use the correct comment syntax
33+
- **RESEARCH** comment syntax if uncertain about a language
34+
35+
**COMMON LANGUAGE EXAMPLES:**
36+
```javascript
37+
// Implementation based on: [project-specs/ui-components.spec.md] - Section: Button Component Design
38+
```
39+
40+
```python
41+
# Implementation based on: [project-specs/data-processing.spec.md] - Section: CSV Parser Requirements
42+
```
43+
44+
```css
45+
/* Implementation based on: [project-specs/styling.spec.md] - Section: Color Palette and Typography */
46+
```
47+
48+
```html
49+
<!-- Implementation based on: [project-specs/layout.spec.md] - Section: Header Navigation Structure -->
50+
```
51+
52+
```sql
53+
-- Implementation based on: [project-specs/database.spec.md] - Section: User Table Schema
54+
```
55+
56+
**UNKNOWN LANGUAGE PROTOCOL:**
57+
1. **RESEARCH** the language's comment syntax using available tools
58+
2. **WEB SEARCH** if necessary to find official documentation
59+
3. **ASK USER** if research yields no results or conflicting information - **USE `run_command` TOOL** - **MUST FOLLOW** [interactive-input.rules.md](./interactive-input.rules.md) for context on using run_command tool
60+
4. **USE** the format: "What is the proper comment syntax for [language name]?" - **USE `run_command` TOOL** - **MUST FOLLOW** [interactive-input.rules.md](./interactive-input.rules.md) for context on using run_command tool
61+
5. **DOCUMENT** the decision for future reference - **FOLLOW** [spec-management.rules.md](./spec-management.rules.md) for specification documentation workflow
62+
63+
---
64+
65+
## PLACEMENT REQUIREMENTS
66+
67+
### PRIMARY PLACEMENT
68+
**TOP OF FILE** - Immediately after any license/copyright headers, before any imports or code
69+
70+
### SECONDARY PLACEMENTS
71+
1. **Before imports** - Spec references come before any import statements
72+
2. **Function-specific** - Additional references before complex functions implementing different spec sections
73+
3. **Class-specific** - Additional references before class definitions implementing specific spec components
74+
4. **Module-specific** - References at module level for large implementations
75+
76+
---
77+
78+
## MULTIPLE SPEC REFERENCES
79+
80+
When code implements multiple specifications, use multi-line format:
81+
82+
```javascript
83+
// Implementation based on:
84+
// - [project-specs/authentication.spec.md] - Section: Login Flow
85+
// - [project-specs/ui-components.spec.md] - Section: Form Validation
86+
// - [project-specs/security.spec.md] - Section: Password Requirements
87+
```
88+
89+
**ORGANIZATION:**
90+
- List specs in order of implementation priority
91+
- Include specific section names for each spec
92+
- Maintain consistent formatting across all references
93+
94+
---
95+
96+
## EXISTING CODE ENFORCEMENT
97+
98+
### MANDATORY CHECKS
99+
When modifying existing code files, agents MUST:
100+
101+
1. **CHECK** for existing spec reference comments
102+
2. **READ** and understand all referenced specifications
103+
3. **FOLLOW** the patterns and requirements from referenced specs
104+
4. **MAINTAIN** consistency with existing spec-driven implementations
105+
5. **UPDATE** spec references when adding new functionality
106+
107+
### MODIFICATION PROTOCOL
108+
- **PRESERVE** existing spec references unless they become obsolete
109+
- **ADD** new spec references for additional functionality
110+
- **UPDATE** section references if spec sections change
111+
- **MAINTAIN** the same comment format as existing references
112+
113+
### LEGACY CODE HANDLING
114+
115+
**TRIGGER CONDITION:** When modifying existing code files that lack spec reference comments
116+
117+
**MANDATORY WORKFLOW REFERENCE:**
118+
For complete workflow requirements when handling legacy code without specifications, agents MUST follow the comprehensive workflow defined in [spec-management.rules.md](./spec-management.rules.md) under the "LEGACY CODE SPECIFICATION WORKFLOW" section.
119+
120+
**IMMEDIATE REQUIREMENTS:**
121+
- **HALT** all modification activities when encountering code without spec references
122+
- **FOLLOW** the complete legacy code workflow in [spec-management.rules.md](./spec-management.rules.md)
123+
- **ADD** proper spec reference comments after workflow completion
124+
- **ENSURE** correct comment syntax for the file's programming language
125+
126+
---
127+
128+
## MAINTENANCE BENEFITS
129+
130+
**QUICK SPEC IDENTIFICATION:**
131+
- Developers can immediately identify relevant specifications
132+
- Maintenance tasks can quickly locate governing requirements
133+
- Code reviews can verify spec compliance
134+
- Refactoring can maintain spec alignment
135+
136+
**TRACEABILITY:**
137+
- Clear connection between code and requirements
138+
- Audit trail for implementation decisions
139+
- Documentation of architectural choices
140+
- Historical context for code changes
141+
142+
---
143+
144+
## ENFORCEMENT PROTOCOL
145+
146+
**MANDATORY COMPLIANCE:**
147+
- **NO EXCEPTIONS** - All generated code files must include spec references
148+
- **IMMEDIATE IMPLEMENTATION** - Add references during initial code generation
149+
- **CONSISTENT FORMAT** - Use language-appropriate comment syntax
150+
- **COMPLETE INFORMATION** - Include both spec file and section names
151+
152+
**VIOLATION CONSEQUENCES:**
153+
All violations are subject to the universal violation enforcement system defined in [violation-enforcement.rules.md](./violation-enforcement.rules.md).
154+
155+
---
156+
157+
## INTEGRATION WITH OTHER RULES
158+
159+
**CROSS-REFERENCES:**
160+
- **Spec Management:** [spec-management.rules.md](./spec-management.rules.md) - Overall specification workflow and legacy code handling
161+
- **Core Principles:** [core-principles.rules.md](./core-principles.rules.md) - Implementation workflow integration
162+
- **Interactive Input:** [interactive-input.rules.md](./interactive-input.rules.md) - User clarification procedures
163+
- **Violation Enforcement:** [violation-enforcement.rules.md](./violation-enforcement.rules.md) - Universal violation enforcement system
164+
165+
**WORKFLOW INTEGRATION:**
166+
This rule integrates with the core agent workflow at the "IMPLEMENT ACCORDING TO SPECIFICATIONS" step, ensuring all generated code maintains proper spec traceability. For legacy code without specifications, agents must follow the "LEGACY CODE SPECIFICATION WORKFLOW" defined in [spec-management.rules.md](./spec-management.rules.md).

‎rules/templates/persona.template.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
- **Role:** Primary job function (free text)
66
- **Experience Level:** none, enthusiast, beginner, intermediate, senior, expert
7+
- **Agent Collaboration Style:** Based on experience level adaptations (see user-persona.rules.md)
78

89
---
910

@@ -17,11 +18,31 @@
1718
**Role:** [Primary job function - engineer, pm, qa, designer, manager, student, etc.]
1819
**Experience Level:** [Select one: none, enthusiast, beginner, intermediate, senior, expert]
1920
21+
## AGENT COLLABORATION STYLE
22+
23+
**Communication Approach:** [Based on experience level - ENFORCEMENT: see [rules/user-persona.rules.md](../user-persona.rules.md) "Experience Level Adaptations" section]
24+
- **Terminology:** [How technical terms should be handled - reference specific level from rules]
25+
- **Explanations:** [Level of detail required - reference specific level from rules]
26+
- **Decisions:** [How options should be presented - reference specific level from rules]
27+
28+
**VIOLATION ENFORCEMENT:** All agents MUST follow the communication requirements defined in [rules/user-persona.rules.md](../../rules/user-persona.rules.md) → "Experience Level Adaptations" → {experience_level}. Violations are subject to the universal violation enforcement system defined in [rules/violation-enforcement.rules.md](../../rules/violation-enforcement.rules.md).
29+
30+
---
31+
32+
*Note: Changes to this persona configuration require starting a new chat session to take effect.*
33+
2034
---
2135
2236
*User persona specification for adaptive communication*
2337
```
2438

2539
---
2640

41+
## IMPORTANT NOTE FOR USERS
42+
43+
⚠️ **CONFIGURATION CHANGES REQUIRE NEW CHAT SESSION**
44+
Any changes to this user persona configuration will only take effect when you start a new chat session. Most agents loads persona settings at the beginning of each conversation.
45+
46+
---
47+
2748
*Template for user persona specifications with required fields and shell formatting*

0 commit comments

Comments
 (0)