Skip to content

Commit 0c9097e

Browse files
matscodematscode
committed
feat: improve persona personalization, improve interactivity and added support for project specs.
1 parent db89d4f commit 0c9097e

18 files changed

+341
-150
lines changed

‎project-specs/index.json‎ renamed to ‎feature-specs/index.json‎

File renamed without changes.

‎rules/holistic-workflow.rules.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
# Holistic Workflow: A Guide to Your Thought Process
2-
Authored by matscode
2+
<!-- Authored by @matscode -->
33

44
## 1. Purpose of This Guide
55
This document is your "mental map." You may read the various `.rules.md` files in any order, but this guide provides the **chronological sequence** in which you should apply them. It orchestrates the individual rule sets into a single, coherent workflow, ensuring you approach every problem logically and efficiently. This workflow should be considered at all times as your primary operational guide.
66

77
This is not just a set of rules; it is a framework for your thinking.
88

99
## 2. The Recommended Workflow
10-
Authored by matscode
10+
<!-- Authored by @matscode -->
1111

1212
### Step 1: First, Understand Who You're Working With
1313
* **Objective:** Know your user's background and communication preferences.

‎rules/index.rules.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Interactive Coding Agent: Mandatory Onboarding
2-
Authored by matscode
2+
<!-- Authored by @matscode -->
33

44
## 🚨 CRITICAL: YOU MUST READ AND OBEY THESE ONBOARDING RULES FIRST
55

@@ -23,7 +23,7 @@ Your single, initial task is to read and understand your operational rules.
2323
---
2424

2525
## 2. The Mandatory Reading Sequence
26-
Authored by matscode
26+
<!-- Authored by @matscode -->
2727

2828
You are required to read the project's rule files in the following sequence:
2929

‎rules/interactive-input.rules.md‎

Lines changed: 33 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,50 @@
11
# Interactive Input: Core Rules
2-
Authored by [matscode](https://www.tiktok.com/@matscode)
32

4-
## 1. Core Principle: Clarify & Verify (Mandatory)
5-
- **Vague? -> Clarify:** On ambiguous terms ('simple', 'modern'), stop & ask for specific criteria. Present options with trade-offs.
6-
- **Verify -> Then Act:** Always get explicit approval. Ask `"Should I proceed?"` before coding and `"Does this meet your expectations?"` after.
7-
- **Validate -> Scope:** Implement ONLY what is explicitly requested. Never add, modify, or remove features/code without direct permission.
3+
## 1. Core Principles (Mandatory)
4+
- **Clarify Vague Requirements:** On ambiguous terms ('simple', 'modern'), you MUST stop and ask for specific criteria. Present options with trade-offs. Failure to ask is a critical violation.
5+
- **Verify Before Acting:** You MUST get explicit approval before any implementation. Ask `"Should I proceed?"` before coding and `"Does this meet your expectations?"` after. Proceeding without approval is a critical violation.
6+
- **Validate Scope:** You MUST implement ONLY what is explicitly requested. Never add, modify, or remove features or code without direct permission. Scope creep is a critical violation.
7+
- **Decide Implementation Approach:** You MUST ask about the implementation approach (e.g., custom vs. library) before coding. If a library is chosen, present options. You MUST confirm the decision before proceeding. Failure to do so is a critical violation.
8+
- **Confirm Session Closure:** You MUST always ask if the user is finished or wants additional changes before ending the session. Exiting without confirmation is a critical violation.
89

910
## 2. When to Stop & Ask (Mandatory)
10-
Authored by matscode
11+
Agent **MUST STOP** and ask questions when encountering:
1112
- **Vague Requirements:** "modern", "simple", "clean", "responsive", "scalable".
12-
- **Multiple Valid Approaches:** Design patterns (hooks vs classes), libraries (Redux vs Zustand), or tool choices.
13+
- **Multiple Valid Approaches:** Design patterns (hooks vs classes), libraries (e.g., state-lib-1 vs state-lib-2), or tool choices.
14+
- **Implementation Strategy Choices:** Custom implementation vs external library/tool.
15+
- **Architecture Decisions:** Built-in solutions vs third-party dependencies.
16+
- **Solution Approach:** When multiple implementation paths exist (custom/library/hybrid).
1317
- **Feature Additions:** ANY feature not explicitly requested by the user.
1418
- **Significant Code Changes:** New dependencies, core architecture modifications.
1519
- **Assumptions About User Intent:** Inferring unstated requirements.
1620
- **Post-Implementation:** After completing ANY feature or implementation.
1721
- **Project Direction:** When multiple valid next steps exist.
18-
- **Project Rules:** Before codifying new coding standards.
22+
**Actions**: Ask for specifics, present ALL available options with trade-offs, explain impact of each choice, confirm assumptions, and get explicit approval before proceeding
1923

20-
### Scope & Preservation Violations
24+
<!-- Authored by @matscode -->
25+
26+
**🚨 SCOPE & PRESERVATION VIOLATIONS**
2127
- **NEVER** implement buttons, UI elements, or functionality not explicitly requested.
2228
- **NEVER** assume user wants "complete" implementations with extra features.
2329
- **NEVER** remove/modify existing working components without explicit request.
2430
- **NEVER** assume existing code is redundant or should be removed.
2531
- **CORRECT APPROACH**: Ask "Should I add features like accept/decline buttons?" or "Should I preserve existing [component] or modify it?"
2632

2733
## 3. Interactive Command Protocol (Critical)
28-
Authored by matscode
29-
- **Tool:** Use `run_command` ONLY. `blocking: true`, `requires_approval: false` for questions.
30-
- **Format:** Use `echo -e` for interactive input.
31-
- **Readability:** Every interactive command **MUST** begin with two newlines (`\n\n`).
32-
- **OS Syntax:** Use OS-appropriate syntax.
34+
**MUST** use `run_command` ONLY.
35+
<!-- Authored by @matscode -->
36+
### Question Formatting
37+
- **Recommended Method:** Use `echo -e` for interactive input. It provides reliable and consistent behavior across different shells.
38+
- **Mandatory Newlines:** All interactive questions **MUST** begin with two newlines (`\n\n`) to ensure clear visual separation in the terminal.
39+
- **Emoji Usage:** Emojis are encouraged to improve readability and user experience. Use them where appropriate to add visual cues, but use them sparingly to avoid distraction. The examples below are not exhaustive; feel free to use other emojis as you see fit.
40+
- **Examples:**
41+
- **Single-line:** `echo -e "\n\nWhat is your favorite color? "; read answer`
42+
- **Multi-line:** `echo -e "\n\nChoose an option:\n1. Option A\n2. Option B\nChoice: "; read answer`
43+
- **Emojis:** `echo -e "\n\n🚀 Ready to proceed? (y/n) "; read answer`
44+
- **Detailed Emoji Example:** `echo -e "\n\nI see you want to add a new feature. I\'ve got a few ideas on how to approach it...\n\n1. 🤠 Go in guns blazing with a custom implementation.\n2. 😒 Use a well-established library (safe, but boring).\n3. 🧪 Try a new, experimental library (might be amazing, might explode).\n\nWhat\'s your poison? "; read answer`
3345

3446
### Tool Usage Example
47+
3548
```json
3649
{
3750
"command": "echo -e '\\n\\nYour question here (option1/option2): '; read answer; echo 'You selected: $answer'",
@@ -42,29 +55,11 @@ Authored by matscode
4255
```
4356
- **JSON Escaping:** Note the use of `\\n\\n` for newlines within the JSON string.
4457

45-
### OS-Specific Commands
46-
47-
### Complex & Multi-line Questions
48-
For complex questions that require more context, you can format the question over multiple lines using `\n` for newlines within the `echo -e` command. This improves readability.
58+
### OS-Specific Commands Example
4959

50-
**Unix/Linux/macOS Example:**
51-
```bash
52-
echo -e '\n\nI need to update the user authentication flow. Which approach should I take?\n1. JWT-based authentication with refresh tokens\n2. Session-based authentication with server-side storage\n3. OAuth 2.0 with a third-party provider (e.g., Google, GitHub)\nPlease enter the number of your choice: '; read answer; echo "You selected: $answer"
53-
```
54-
**Unix/Linux/macOS:**
55-
```bash
56-
echo -e '\n\nQuestion...?'; read answer; echo "You selected: $answer"
57-
```
58-
59-
**Windows (CMD):**
60-
```cmd
61-
echo. & echo. & echo Question...? & set /p answer= & echo You selected: %answer%
62-
```
63-
64-
**Windows (PowerShell):**
65-
```powershell
66-
Write-Host "`n`nQuestion...?" -NoNewline; $answer = Read-Host; Write-Host "You selected: $answer"
67-
```
60+
**Unix/Linux/macOS:** `echo -e '\n\nQuestion...?'; read answer; echo "You selected: $answer"`
61+
**Windows (CMD):** `echo. & echo. & echo Question...? & set /p answer= & echo You selected: %answer%`
62+
**Windows (PowerShell):** `Write-Host "`n`nQuestion...?" -NoNewline; $answer = Read-Host; Write-Host "You selected: $answer"`
6863

6964
## 4. Display vs. Input (Critical Distinction)
7065
- **Display-Only:** Use `echo` to show info. MUST end with `"Press Enter to continue..."` and wait for `read` acknowledgment.
@@ -77,7 +72,7 @@ Write-Host "`n`nQuestion...?" -NoNewline; $answer = Read-Host; Write-Host "You s
7772
- **Follow-up:** Drill deeper when answers leave ambiguity.
7873

7974
## 6. Mandatory Practices
80-
Authored by matscode
75+
<!-- Authored by @matscode -->
8176
- **Early Clarification** - Ask questions at task start, resolve ambiguities before coding
8277
- **Feature Scope Verification** - MUST confirm before adding ANY feature not explicitly requested
8378
- **Display Text Acknowledgment** - ALL display-only text MUST require user acknowledgment before proceeding
@@ -142,7 +137,7 @@ Authored by matscode
142137
- **Forbidden:** Displaying interactive commands as text is strictly forbidden.
143138

144139
## 9. Information Freshness (Critical)
145-
- **Core Rule:** You MUST always use the most up-to-date file content. Before you ask a question or implement a change, re-read any relevant files to ensure you have not missed a manual update from the user.
140+
- **Core Rule:** You MUST always use the most up-to-date file content. Before you ask a question or implement a change, re-read any relevant files to ensure you have not missed a manual update from the user before acting on said file.
146141
- **Stale Content = Critical Failure:** Basing actions on outdated information is a critical violation.
147142

148143
-- Authored by [matscode](https://www.linkedin.com/in/matscode)

‎rules/spec-decision-examples.rules.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
11
# Specification Decision Examples
2-
Authored by [matscode](https://www.tiktok.com/@matscode)
32

43
This document provides a comprehensive, non-exhaustive list of examples for when a specification is required. It is intended as a reference to be used for validation when there is doubt.
4+
<!-- Authored by @matscode -->
55

66
---
77

88
## Detailed Triggers for Specification Creation
99

1010
A specification is required for **ALL** of the following:
11+
<!-- Authored by @matscode -->
1112

1213
### General Code Changes
1314
- **New Features:** Any new functionality, components, functions, endpoints, or capabilities.
@@ -27,7 +28,8 @@ A specification is required for **ALL** of the following:
2728
- **Infrastructure Changes:** Deployment, CI/CD, or environment configuration modifications.
2829

2930
### Architectural Patterns
30-
Authored by matscode
31+
32+
<!-- Authored by @matscode -->
3133
- Component architecture (atomic design, feature-based, etc.)
3234
- State management (Redux, Zustand, Context, etc.)
3335
- Data fetching (REST, GraphQL, SWR, React Query, etc.)
@@ -48,7 +50,8 @@ Authored by matscode
4850
- Schema evolution (Migration strategies, versioning approaches)
4951

5052
### Language & Runtime
51-
Authored by matscode
53+
54+
<!-- Authored by @matscode -->
5255
- Language selection (Systems programming Rust/C++, web services Go/Java, scripting Python/JavaScript, mobile Swift/Kotlin)
5356
- Compilation strategies (Ahead-of-time Go, just-in-time Java/C#, interpreted Python)
5457
- TypeScript vs JavaScript
@@ -86,4 +89,4 @@ Authored by matscode
8689
- Documentation standards (Code comments, API documentation, architectural diagrams)
8790
- Logging conventions (Log levels, structured vs unstructured, centralized collection)
8891

89-
-- Authored by [matscode](https://www.linkedin.com/in/matscode)
92+
-- Authored by [matscode](https://www.linkedin.com/in/matscode)

‎rules/spec-management.rules.md‎

Lines changed: 57 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,45 @@
11
# Spec Management & Referencing Rules (MANDATORY)
22

3-
Authored by [matscode](https://www.tiktok.com/@matscode)
3+
<!-- Authored by @matscode -->
44

55
This document outlines the mandatory workflow for creating, managing, and referencing specifications. Adherence is critical for maintainability and traceability.
66

77
---
88

9-
## 1. When to Create a Spec
9+
## 1. Specification Types
10+
11+
This section clarifies the differences between Project and Feature specifications.
12+
13+
- **Project Spec:** A high-level document that outlines the core, project-wide decisions. It is the single source of truth for the project's overall direction and branding.
14+
- **Feature Spec:** A detailed document that describes the requirements, implementation, and affected files for a specific feature or non-trivial code change.
15+
16+
---
17+
18+
## 2. Project Spec Workflow
19+
20+
<!-- Authored by @matscode -->
21+
22+
**MANDATORY**
23+
24+
1. **Read the Project Spec:** Always read the `specs/project.spec.md` file first to understand the high-level project context.
25+
2. **Project-Level Decisions:** All project-level decisions, such as project name, description, tagline, and branding, **MUST** be documented in the `specs/project.spec.md` file.
26+
3. **Spec List Integrity:** Only specification files located within the `specs/` directory are permitted to be included in the `Extra Spec List`.
27+
28+
---
29+
30+
## 3. Feature Spec Workflow
31+
32+
### Updating the Project Spec
33+
34+
If a feature introduces any new project-wide element—such as a **dependency, color, font, or other branding element**—the feature spec's implementation plan **MUST** include a step to update the corresponding section of `specs/project.spec.md`.
35+
36+
---
37+
38+
## 2. When to Create a Spec
39+
40+
<!-- Authored by @matscode -->
41+
42+
1043

1144
A spec is **MANDATORY** for any non-trivial code change (i.e., any change that is not a minor typographical fix).
1245

@@ -47,35 +80,34 @@ A spec is also required when coding agents need context for:
4780

4881
---
4982

50-
## 2. Agent Response Protocol
51-
52-
Authored by matscode
83+
## 3. Agent Response Protocol
5384

5485
Before creating any specification file, agents MUST ask these questions to ensure optimal documentation:
5586

5687
**DECISION CLARITY:**
5788
- "What is your final decision? (If not explicitly stated)"
5889
- "Can you confirm this is the approach you want to proceed with?"
5990

60-
**RATIONALE GATHERING:**
61-
- "What led you to choose this option over alternatives?"
62-
- "What factors were most important in your decision?"
91+
**SPEC DESTINATION:**
92+
- "Should this decision be documented in the project spec or a feature spec? (project/feature)"
6393

6494
**SOURCE DOCUMENTATION:**
6595
- "Are there any specific articles, documentation, or resources that influenced your decision?"
6696

67-
### 2.1 Interactive Input Compliance
97+
### 3.1 Interactive Input Compliance
6898
All questions in this protocol MUST comply with the rules for asking questions and handling user input as defined in `rules/interactive-input.rules.md`.
6999

70100
---
71101

72-
## 3. Specification Workflow
102+
## 4. Specification Workflow
103+
104+
<!-- Authored by @matscode -->
73105

74106
### Step 1: Specification Selection and Reuse Protocol
75107

76108
**MANDATORY: BEFORE CREATING A NEW SPEC, YOU MUST FOLLOW THIS PROTOCOL:**
77109

78-
1. **Search the Spec Index:** Perform a comprehensive keyword search against the `title` and `keywords` fields in `project-specs/index.json` to find all potentially relevant specs.
110+
1. **Search the Spec Index:** Perform a comprehensive keyword search against the `title` and `keywords` fields in `feature-specs/index.json` to find all potentially relevant specs.
79111

80112
2. **Select Candidate Specifications:** From the search results, identify the 2-3 specs that most closely match the current requirement.
81113

@@ -90,38 +122,37 @@ All questions in this protocol MUST comply with the rules for asking questions a
90122
5. **Resolve Conflicts:** If you are uncertain which strategy to choose or which spec to update, present the options to the user and ask for guidance using an interactive command as defined in `rules/interactive-input.rules.md`. Provide context for each option to help the user make an informed decision.
91123

92124
### Step 2: Create
93-
- **Location:** `project-specs/`
125+
- **Location:** `feature-specs/`
94126
- **Naming:** `kebab-case.spec.md` (e.g., `api-authentication.spec.md`)
95127
- **Template:** Use `rules/templates/spec.template.md` exactly.
128+
- **Implementation Steps:** The `Key Implementation Steps` section **MUST** be detailed and transparent, outlining each step of the implementation.
96129

97130
### Step 3: Get Approval
98131
- **Present:** Share the spec with the user for review.
99132
- **Ask:** Use an interactive command as defined in `rules/interactive-input.rules.md` to ask for approval. The question should be: `"I have created/updated the spec for [decision]. Please review and approve."`
100133
- **Wait:** Do not proceed without explicit approval.
101134

102135
### Step 4: Update Index
103-
- **After Approval:** Once a new spec is approved, you **MUST** add a new entry to the `project-specs/index.json` file.
136+
- **After Approval:** Once a new spec is approved, you **MUST** add a new entry to the `feature-specs/index.json` file.
104137
- **Format:** The entry must be a JSON object with `title`, `path`, and `keywords` keys.
105138
```json
106139
{
107140
"title": "Spec Title",
108-
"path": "project-specs/spec-name.spec.md",
141+
"path": "feature-specs/spec-name.spec.md",
109142
"keywords": ["keyword1", "keyword2", "technology"]
110143
}
111144
```
112145

113146
---
114147

115-
## 4. Two-Way Spec Referencing
116-
117-
Authored by matscode
148+
## 5. Two-Way Spec Referencing
118149

119150
### From Code to Spec (Mandatory)
120151
All generated code **MUST** reference its guiding spec.
121152

122153
- **Format:** Use a single-line comment.
123154
```
124-
[COMMENT_SYNTAX] Implements: [project-specs/<filename>.spec.md] - Section: [Section Name]
155+
[COMMENT_SYNTAX] Implements: [feature-specs/<filename>.spec.md] - Section: [Section Name]
125156
```
126157
- **CRITICAL:** Do NOT use multi-line formats (e.g., JSDoc).
127158
- **Placement:**
@@ -130,31 +161,28 @@ All generated code **MUST** reference its guiding spec.
130161
- **Multiple Specs:** List vertically.
131162
```javascript
132163
// Implements:
133-
// - [project-specs/authentication.spec.md] - Section: Login Flow
134-
// - [project-specs/ui-components.spec.md] - Section: Form Validation
164+
// - [feature-specs/authentication.spec.md] - Section: Login Flow
165+
// - [feature-specs/ui-components.spec.md] - Section: Form Validation
135166
```
136167

137168
### From Spec to Code (Mandatory)
138169
Every spec **MUST** list the code files that implement it.
139170

140-
- **Location:** In the spec file, under the `### 4. Affected Files` heading.
171+
- **Location:** In the spec file, under the `### 3. Affected Files` heading.
141172
- **Format:**
142173
```markdown
143-
### 4. Affected Files
144-
*A list of files created or modified.*
174+
### 3. Affected Files
145175
- `path/to/file-one.js`
146176
```
147177

148178
---
149179

150-
## 5. Legacy Code Workflow
151-
152-
Authored by matscode
180+
## 6. Legacy Code Workflow
153181

154182
For existing code that lacks a spec reference, you **MUST** follow this protocol **BEFORE** making any changes:
155183

156184
1. **STOP & Analyze:** Do not modify the code. Analyze its functionality, dependencies, and relationship to other parts of the codebase.
157-
2. **Search for Existing Spec:** Conduct a thorough search in `project-specs/index.json` to determine if a relevant spec already exists but is not referenced.
185+
2. **Search for Existing Spec:** Conduct a thorough search in `feature-specs/index.json` to determine if a relevant spec already exists but is not referenced.
158186
3. **Create Retroactive Spec:** If no spec exists, create a new one that accurately documents the behavior of the legacy code. The spec should describe the code as it currently exists.
159187
4. **Get Approval:** Present the newly created spec to the user for approval.
160188
5. **Add Spec Reference:** Once approved, add the spec reference to the legacy code.
@@ -163,9 +191,10 @@ For existing code that lacks a spec reference, you **MUST** follow this protocol
163191

164192
---
165193

166-
## 6. Maintenance & Enforcement
194+
## 7. Maintenance & Enforcement
167195

168196
- **Specs are Living Documents:** They **MUST** be updated when decisions change or the implementation deviates.
197+
- **Concurrent Updates:** The spec file **MUST** be updated in real-time as the implementation progresses. The "Key Implementation Steps" should be checked off as they are completed.
169198
- **All Changes Documented:** Any change to a specification, no matter how small, **MUST** be followed by an update to the spec file and a request for user approval.
170199
- **Your Responsibility:** Proactively identify when a new decision alters an existing spec. Update the spec and get approval before proceeding.
171200
- **Violations:** Failure to create, reference, get approval for, or **maintain** a spec is a critical violation. Stop all work until the process is followed correctly.

0 commit comments

Comments
 (0)