Skip to content

Commit 80044e5

Browse files
matscodematscode
committed
feat: tackle stale file state and detailed command execution info
1 parent 5a24ed6 commit 80044e5

8 files changed

+888
-121
lines changed

‎rules/command-execution.rules.md‎

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
1+
# Command Execution Rules
2+
3+
**MANDATORY: ALL AGENTS MUST FOLLOW THESE COMMAND EXECUTION PROTOCOLS**
4+
5+
---
6+
7+
## 🚨 VIOLATION REFERENCE
8+
**VIOLATION ENFORCEMENT:** All violations of rules in this file are subject to the universal violation enforcement system defined in [rules/violation-enforcement.rules.md](./violation-enforcement.rules.md).
9+
10+
---
11+
12+
## Overview
13+
14+
This document establishes **MANDATORY** standards for command execution during coding sessions. Communication style must adapt to the user's persona as defined in `specs/user-persona.spec.md` following the guidelines in [rules/user-persona.rules.md](./user-persona.rules.md).
15+
16+
**These rules are STRICTLY MANDATORY and NON-NEGOTIABLE. VIOLATION = CRITICAL FAILURE. Always ask clarifying questions when in doubt. NO EXCEPTIONS.**
17+
18+
---
19+
20+
## Core Principles
21+
22+
<!-- Command execution standards by @matscode -->
23+
24+
1. **Mandatory Documentation** ⚠️ **CRITICAL**
25+
- **ALL non-interactive commands MUST include detailed multiline comments**
26+
- **INTERACTIVE commands (using `read`, `set /p`, `Read-Host`) do NOT require the `# ---\n` separator**
27+
- **NEVER** execute commands without proper documentation
28+
- **FAILURE TO DOCUMENT = RULE VIOLATION**
29+
30+
2. **Approval-Based Execution** ⚠️ **CRITICAL**
31+
- **MUST** request user permission for build and development commands
32+
- **FORBIDDEN** to execute build/dev commands without explicit approval
33+
- **MANDATORY**: Provide detailed testing steps if approval is denied
34+
35+
3. **Shell-Specific Formatting** ⚠️ **MANDATORY**
36+
- **REQUIRED**: Use appropriate comment syntax for target operating system
37+
- **NEVER** use generic comments - adapt to shell environment
38+
- **NON-NEGOTIABLE** - failure to use proper syntax = rule violation
39+
40+
**🚨 COMMAND TYPE DISTINCTION:**
41+
- **Regular Commands**: Require multiline comments with `# ---\n` separator
42+
- **Interactive Commands**: Follow [rules/interactive-input.rules.md](./interactive-input.rules.md) format (no `# ---\n` separator)
43+
44+
---
45+
46+
## 🚨 MANDATORY COMMENT REQUIREMENTS
47+
48+
**ALL NON-INTERACTIVE COMMANDS MUST INCLUDE:**
49+
50+
### Comment Format by Operating System
51+
52+
**Unix/Linux/macOS (bash/zsh):**
53+
```bash
54+
# Command: Install Express.js package for Node.js web server
55+
# Purpose: Adds Express framework to project dependencies
56+
# Impact: Enables web server functionality and routing capabilities
57+
# ---
58+
59+
npm install express
60+
```
61+
62+
**Windows (Command Prompt):**
63+
```cmd
64+
REM Command: Install Express.js package for Node.js web server
65+
REM Purpose: Adds Express framework to project dependencies
66+
REM Impact: Enables web server functionality and routing capabilities
67+
REM ---
68+
69+
npm install express
70+
```
71+
72+
**Windows (PowerShell):**
73+
```powershell
74+
<#
75+
Command: Install Express.js package for Node.js web server
76+
Purpose: Adds Express framework to project dependencies
77+
Impact: Enables web server functionality and routing capabilities
78+
79+
#>
80+
81+
npm install express
82+
```
83+
84+
### Required Comment Elements
85+
86+
**MANDATORY COMMENT STRUCTURE:**
87+
1. **Command**: Brief description of what the command does
88+
2. **Purpose**: Why this command is being executed
89+
3. **Impact**: What changes or effects this will have on the project
90+
91+
**🚨 CRITICAL FORMATTING REQUIREMENT:**
92+
- **ALL command comments MUST be multiline** (minimum 3 lines)
93+
- **VIOLATION**: Single-line or missing comments = CRITICAL FAILURE
94+
95+
---
96+
97+
## 🛑 BUILD & DEVELOPMENT COMMAND APPROVAL
98+
99+
**COMMANDS REQUIRING MANDATORY APPROVAL:**
100+
101+
### Build Commands
102+
- `npm run build`, `yarn build`, `pnpm build`
103+
- `flutter build`, `dart compile`
104+
- `cargo build`, `go build`
105+
- `mvn compile`, `gradle build`
106+
- `python setup.py build`, `pip install -e .`
107+
- `make`, `cmake --build`
108+
- Any command containing "build", "compile", or "package"
109+
110+
### Development Server Commands
111+
- `npm run dev`, `yarn dev`, `npm start`
112+
- `flutter run`, `dart run`
113+
- `python manage.py runserver`, `flask run`
114+
- `rails server`, `php artisan serve`
115+
- `cargo run`, `go run`
116+
- Any command containing "serve", "server", "run", or "dev"
117+
118+
### Testing Commands
119+
- `npm test`, `yarn test`, `pytest`
120+
- `flutter test`, `cargo test`
121+
- `mvn test`, `gradle test`
122+
- Any command containing "test" or "spec"
123+
124+
---
125+
126+
## 🔧 NON-INTERACTIVE COMMAND APPROVAL WORKFLOW
127+
128+
**MANDATORY APPROVAL PROCESS FOR BUILD/DEV/TEST COMMANDS:**
129+
130+
### Step 1: Request Permission Using Interactive Input
131+
**MUST follow interactive input format and tool usage requirements from [rules/interactive-input.rules.md](./interactive-input.rules.md).**
132+
133+
**Example approval request (see interactive-input.rules.md for complete format requirements):**
134+
```bash
135+
echo -e "\n\n🚨 BUILD/DEV COMMAND APPROVAL REQUIRED\n\nCommand to execute:\n# Command: Start development server for React application\n# Purpose: Launch local development environment for testing changes \n# Impact: Opens localhost server on port 3000, enables hot reloading\nnpm run dev\n\nApprove execution? (yes/no): "; read approval; echo "You selected: $approval"
136+
```
137+
138+
### Step 2A: If Approved - Execute Command
139+
```bash
140+
# Command: Start development server for React application
141+
# Purpose: Launch local development environment for testing changes
142+
# Impact: Opens localhost server on port 3000, enables hot reloading
143+
# ---
144+
145+
npm run dev
146+
```
147+
148+
### Step 2B: If Denied - Provide Testing Steps
149+
**MANDATORY FALLBACK - Provide detailed manual testing instructions:**
150+
151+
```bash
152+
echo -e "\n\n📋 MANUAL TESTING STEPS\n\nSince build/dev command was not approved, here are detailed steps to test the implemented features:\n\n1. Navigate to project directory: cd /path/to/project\n2. Install dependencies: npm install\n3. Start development server: npm run dev\n4. Open browser to: http://localhost:3000\n5. Test specific features:\n - Feature A: Click button X, verify behavior Y\n - Feature B: Navigate to page Z, check element W\n6. Verify responsive design on mobile viewport\n7. Check browser console for errors\n\nPress Enter to continue..."; read continue
153+
```
154+
155+
---
156+
157+
## 🎯 COMMAND CATEGORIZATION
158+
159+
### Interactive Commands (Exempt from Comment Requirements)
160+
- Commands using `read`, `input()`, or similar user input functions
161+
- Commands following [rules/interactive-input.rules.md](./interactive-input.rules.md) format
162+
- **EXEMPTION**: Interactive commands already have built-in documentation
163+
164+
### Command Classification Rules
165+
166+
**🚨 UNIVERSAL RULE: ALL non-interactive commands MUST have multiline comments**
167+
168+
**Interactive Commands (NO comments required):**
169+
- Commands using `read`, `set /p`, `Read-Host` for user input
170+
- Follow [rules/interactive-input.rules.md](./interactive-input.rules.md) format
171+
172+
**Non-Interactive Commands (REQUIRE multiline comments with `# ---\n` separator):**
173+
- **ALL commands that don't request user input**
174+
- **Examples include but NOT LIMITED TO:**
175+
- Package installation: `npm install`, `pip install`, `cargo add`
176+
- File operations: `cp`, `mv`, `mkdir`, `rm`, `wc`, `ls`, `cat`
177+
- Git operations: `git add`, `git commit`, `git push`, `git status`
178+
- Database operations: `psql`, `mysql`, `mongosh`
179+
- System commands: `chmod`, `chown`, `systemctl`, `ps`, `top`
180+
- Text processing: `grep`, `sed`, `awk`, `sort`, `uniq`
181+
- Network commands: `curl`, `wget`, `ping`, `ssh`
182+
- **ANY other command that executes without user interaction**
183+
184+
**🚨 CRITICAL: If unsure whether a command is interactive, assume it requires comments**
185+
186+
### Approval-Required Commands (Build/Dev/Test)
187+
- All build, development server, and testing commands
188+
- **DOUBLE REQUIREMENT**: Must have comments AND approval
189+
190+
---
191+
192+
## 📋 PRE-COMMAND VALIDATION CHECKLIST
193+
194+
**MANDATORY VALIDATION - Before executing ANY run_command:**
195+
196+
- [ ] **Is this an interactive command?**
197+
- If YES: Follow interactive-input.rules.md format
198+
- If NO: Continue to next check
199+
200+
- [ ] **Does this command have proper multiline comments?**
201+
- Must include Command, Purpose, and Impact
202+
- Must use shell-appropriate comment syntax
203+
- Must be minimum 3 lines
204+
205+
- [ ] **Is this a build/dev/test command?**
206+
- If YES: Must request approval using interactive format
207+
- If NO: Can execute with comments
208+
209+
- [ ] **Are comments using correct shell syntax?**
210+
- Unix/macOS: Use `#` comments
211+
- Windows CMD: Use `REM` comments
212+
- PowerShell: Use `<# #>` block comments
213+
214+
- [ ] **Is the command syntax valid for target OS?**
215+
- Verify command exists on target platform
216+
- Check for proper path separators and syntax
217+
218+
**VIOLATION DETECTION TRIGGERS:**
219+
- Any non-interactive command without multiline comments
220+
- Build/dev commands executed without approval
221+
- Comments using wrong syntax for target shell
222+
- Missing Command, Purpose, or Impact in comments
223+
224+
---
225+
226+
## 📋 ENHANCED COMPLIANCE CHECKLIST
227+
228+
**Before ANY command execution:**
229+
- [ ] Identified command type (interactive/regular/build-dev)?
230+
- [ ] Added proper multiline comments for non-interactive commands?
231+
- [ ] Used correct shell syntax for comments?
232+
- [ ] Requested approval for build/dev/test commands?
233+
- [ ] Prepared fallback testing steps if approval denied?
234+
- [ ] Verified command syntax for target operating system?
235+
- [ ] Set appropriate requires_approval flag in tool usage?
236+
237+
**After command execution:**
238+
- [ ] Verified command executed successfully?
239+
- [ ] Provided output interpretation if needed?
240+
- [ ] Offered next steps or follow-up actions?
241+
242+
**If approval denied:**
243+
- [ ] Provided detailed manual testing steps?
244+
- [ ] Explained how to verify implemented features?
245+
- [ ] Offered alternative approaches?
246+
247+
**🚨 VIOLATION PROTOCOL:**
248+
1. STOP immediately upon detecting missing comments or unauthorized execution
249+
2. ACKNOWLEDGE violation type and specific rule broken
250+
3. **EXECUTE** required documentation or approval process
251+
4. WAIT for user response before proceeding
252+
5. **NEVER** execute build/dev commands without explicit approval
253+
254+
---
255+
256+
## Examples
257+
258+
### Regular Command with Proper Documentation
259+
```bash
260+
# Command: Create new React component directory structure
261+
# Purpose: Organize component files following project conventions
262+
# Impact: Creates components/Button folder with index.js and styles
263+
# ---
264+
265+
mkdir -p src/components/Button && touch src/components/Button/index.js src/components/Button/Button.module.css
266+
```
267+
268+
### Build Command with Approval Workflow
269+
**Follow interactive input format from [rules/interactive-input.rules.md](./interactive-input.rules.md) for approval requests.**
270+
271+
**Example approval workflow (see interactive-input.rules.md for complete format requirements):**
272+
```bash
273+
# First: Request approval using interactive input format
274+
echo -e "\n\n🚨 BUILD COMMAND APPROVAL REQUIRED\n\nCommand to execute:\n# Command: Build production-ready React application\n# Purpose: Compile and optimize code for deployment\n# Impact: Creates optimized build folder, minifies assets\nnpm run build\n\nApprove execution? (yes/no): "; read approval; echo "You selected: $approval"
275+
```
276+
277+
If approved, then execute:
278+
279+
```bash
280+
# Command: Build production-ready React application
281+
# Purpose: Compile and optimize code for deployment
282+
# Impact: Creates optimized build folder, minifies assets
283+
# ---
284+
285+
npm run build
286+
```
287+
288+
### Fallback Testing Steps (If Approval Denied)
289+
```bash
290+
echo -e "\n\n📋 MANUAL TESTING STEPS\n\nTo test the new Button component:\n\n1. Navigate to project: cd /path/to/project\n2. Install dependencies: npm install\n3. Start dev server: npm run dev\n4. Open: http://localhost:3000\n5. Test Button component:\n - Verify button renders correctly\n - Test click functionality\n - Check hover states\n - Validate accessibility\n\nPress Enter to continue..."; read continue
291+
```
292+
293+
---
294+
295+
## 🎯 MANDATORY PRACTICES
296+
297+
1. **Universal Documentation** - Every non-interactive command must have multiline comments
298+
2. **Approval-First Execution** - Never execute build/dev commands without permission
299+
3. **Shell-Appropriate Syntax** - Use correct comment format for target operating system
300+
4. **Comprehensive Fallbacks** - Always provide testing steps when approval denied
301+
5. **Violation Prevention** - Validate all requirements before command execution
302+
6. **User Respect** - Honor approval decisions and provide alternatives
303+
7. **File Content Verification** - Re-read all configuration and project files before executing commands that depend on them
304+
8. **Fresh Content Protocol** - Never execute commands based on stale file content or cached understanding
305+
9. **Mandatory Closure** - Always end with session closure following [rules/interactive-input.rules.md](./interactive-input.rules.md)
306+
307+
**FILE READING INTEGRATION:**
308+
- **MANDATORY:** Follow [rules/file-caching.rules.md](./file-caching.rules.md) for all file content verification
309+
- **BEFORE COMMANDS:** Re-read dependency files, configuration files, and project specs before executing related commands
310+
- **VERIFY DEPENDENCIES:** Check current file state before running build, test, or development commands
311+
312+
---
313+
314+
*Created by [@matscode](https://www.tiktok.com/@matscode) | [LinkedIn](https://www.linkedin.com/in/matscode)*

‎rules/core-principles.rules.md‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,8 @@ This file defines the fundamental workflow and core principles that ALL coding a
5858

5959
### 7. IMPLEMENT ACCORDING TO SPECIFICATIONS
6060
- **RE-READ** all relevant specifications immediately before implementation
61+
- **COMPARE** current file content with agent memory to detect changes
62+
- **UPDATE** understanding when content differs from memory
6163
- **FOLLOW** approved specifications exactly
6264
- **MAINTAIN** consistency with established patterns
6365
- **IMPLEMENT** only what was approved
@@ -95,12 +97,6 @@ This file defines the fundamental workflow and core principles that ALL coding a
9597
- **RESPECT** user decisions and preferences
9698
- **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
9799

98-
### CONSISTENCY ENFORCEMENT
99-
- **FOLLOW** established patterns and conventions
100-
- **MAINTAIN** architectural consistency
101-
- **REFERENCE** existing specifications for guidance
102-
- **AVOID** introducing conflicting patterns
103-
104100
---
105101

106102
## CRITICAL VIOLATIONS

0 commit comments

Comments
 (0)