fix(docs): resolve consistency issues across all 6 rule documents

- Add missing `sleep 3 &&` to project-template.md Agent Automation commands
- Add Terminal Delay guidance line to analyze-project.ts generated output
- Rename make_plan.md "Integration with Other Rules" to "Cross-References"
- Add `sleep 3 &&` prefix to all command examples in testing.md, git-commands.md
- Add Quick Reference Card and .gitignore guidance to agents.md
- Remove ghost plans.md references from README, analyze-project, get-setup-guide
- Add exec/execution aliases for make_plan in types/index.ts
- Update test fixtures to match new generated output format
- All 106 tests passing

Author: gevik

README.md

@@ -4,7 +4,7 @@ MCP (Model Context Protocol) server providing AI coding agents with universal, l
 
 ## What It Does
 
-**codeops-mcp** bundles 7 curated rule documents that teach AI agents how to code, test, plan, commit, and behave — across any programming language and project type. It exposes these rules via 5 MCP tools.
+**codeops-mcp** bundles 6 curated rule documents that teach AI agents how to code, test, plan, commit, and behave — across any programming language and project type. It exposes these rules via 5 MCP tools.
 
 ### Rule Documents
 
@@ -14,7 +14,6 @@ MCP (Model Context Protocol) server providing AI coding agents with universal, l
 | **testing**          | Test commands, workflows, coverage requirements, debugging strategies                |
 | **git-commands**     | Git commit protocols (`gitcm`/`gitcmp`), message format, push workflow               |
 | **make_plan**        | Complete protocol for creating and executing multi-document implementation plans     |
-| **plans**            | 10 rules for structuring plans: phases, tasks, dependencies, architecture            |
 | **agents**           | Mandatory AI agent behavior: compliance, context management, multi-session execution |
 | **project-template** | Template for `.clinerules/project.md` — project-specific toolchain configuration     |
 

docs/agents.md

@@ -19,6 +19,20 @@ This file contains **universal agent rules** that work for any software project.
 
 ---
 
+## **Quick Reference Card**
+
+> **The 5 most critical rules at a glance — read the full sections below for details.**
+
+| # | Rule | Key Point |
+|---|------|-----------|
+| 🔒 | **Mandatory Compliance** | Load `code.md` + `testing.md` before ANY work. All tests must pass. |
+| 📊 | **Context Window** | Continue until 90% of 200K input. Max 60K output per response. |
+| 📦 | **Script-First** | NEVER use inline scripts (`node -e`, `python -c`). Create files in `scripts/`. |
+| 🔒 | **Git Protocol** | NEVER use `git commit -m`. Always `gitcm`/`gitcmp` with file-based messages. |
+| 📜 | **No Complex Chains** | No `&&` + pipes/redirects combos. Use script files instead. |
+
+---
+
 ## **🚨 ULTRA-CRITICAL: MANDATORY COMPLIANCE WITH CODING STANDARDS 🚨**
 
 **Before ANY planning or implementation, you MUST consult `code.md` and `testing.md`.**
@@ -392,6 +406,19 @@ rm scripts/tmp-check-data-format.ts
 
 Temporary scripts should NOT be committed to version control. If a temporary script proves useful, rename it to use a permanent prefix (`debug-`, `test-`, `verify-`, `run-`).
 
+#### Git Tracking Recommendations for Generated Directories
+
+| Directory | Recommendation | Rationale |
+|-----------|---------------|-----------|
+| `plans/` | ✅ **Commit** — these are project documentation | Plans are valuable context for future sessions and team members |
+| `scripts/tmp-*` | ❌ **Do NOT commit** — clean up after use | Temporary exploration scripts have no lasting value |
+| `scripts/debug-*`, `scripts/run-*`, etc. | ✅ **Commit if reusable** | Permanent utility scripts are project infrastructure |
+
+Consider adding to your project's `.gitignore`:
+```
+scripts/tmp-*
+```
+
 ---
 
 ### **Rule 9: Compact Conversation After Task Completion**
@@ -412,40 +439,45 @@ Temporary scripts should NOT be committed to version control. If a temporary scr
 
 ---
 
-### **Rule 11: Mandatory `gitcm`/`gitcmp` for All Git Operations — File-Based Commits ONLY**
+### **Rule 10: VS Code Settings Automation (Optional)**
 
-**🚨 NEVER execute raw git staging, committing, or pushing commands. ALWAYS use `gitcm` or `gitcmp`.**
+If the project uses `scripts/agent.sh` for VS Code settings automation:
 
-The `gitcm` and `gitcmp` protocols (defined in `git-commands.md`) are the **ONLY** permitted methods for git staging, committing, and pushing. Running loose git commands bypasses the required commit message format, verification steps, and workflow safeguards.
+**Act Mode Requirements:**
 
-**🚨 CRITICAL: The `-m` flag is BANNED.** Commit messages MUST be written to `/tmp/git_commit_msg.txt` using `write_to_file` and committed with `git commit -F /tmp/git_commit_msg.txt`. This is because inline `-m` messages fail due to shell escaping, length limits, and multi-line formatting issues. See `git-commands.md` for the full explanation.
+1. **✅ Execute `clear && sleep 3 && scripts/agent.sh start` as THE FIRST COMMAND of any Act Mode task**
+   - Switches VS Code to development mode
 
-#### PROHIBITED (NEVER DO):
+2. **✅ Execute `clear && sleep 3 && scripts/agent.sh finished` as THE LAST COMMAND of any Act Mode task**
+   - Switches VS Code to completion mode (full linting, formatting, cleanup)
+
+**Workflow Pattern:**
 
 ```bash
-❌ git commit -m "some message"
-❌ git commit -m 'some message'
-❌ git commit -am "some message"
-❌ git commit -m "feat(scope): ..." -m "- detail 1" -m "- detail 2"
-❌ ANY use of the -m flag with git commit
-❌ git push origin main
-❌ git add . && git commit -m "message" && git push
+# FIRST COMMAND - Start of any Act Mode task
+clear && sleep 3 && scripts/agent.sh start
+
+# ... perform all task implementation work ...
+
+# LAST COMMAND - End of any Act Mode task
+clear && sleep 3 && scripts/agent.sh finished
 ```
 
-#### REQUIRED (ALWAYS DO):
+**When NOT to Apply:**
 
-- **To stage and commit:** Use the `gitcm` protocol (see `git-commands.md`)
-- **To stage, commit, and push:** Use the `gitcmp` protocol (see `git-commands.md`)
-- **ALWAYS** write the commit message to `/tmp/git_commit_msg.txt` using `write_to_file` first
-- **ALWAYS** commit using `git commit -F /tmp/git_commit_msg.txt`
-- **ALWAYS** clean up with `rm /tmp/git_commit_msg.txt` after committing
+- ❌ Do not use in Plan Mode
+- ❌ Do not use if `scripts/agent.sh` does not exist in the project
+- ❌ Do not use if already in the middle of a task (only at start/end boundaries)
+
+---
 
-**There are NO exceptions.** Even for "quick" or "small" commits, the agent MUST use `gitcm` or `gitcmp` with the file-based approach. These protocols ensure:
-- Proper commit message format with scope and prefix
-- Commit message written via temp file (no shell escaping issues)
-- Multi-line messages with special characters work reliably
-- Verification steps are followed
-- Consistent workflow across all sessions
+### **Rule 11: Mandatory `gitcm`/`gitcmp` for All Git Operations — File-Based Commits ONLY**
+
+**🚨 NEVER execute raw git staging, committing, or pushing commands. ALWAYS use `gitcm` or `gitcmp`.**
+
+All git operations MUST use the `gitcm`/`gitcmp` protocol defined in `git-commands.md`. **The `-m` flag is BANNED** — commit messages MUST be written to `/tmp/git_commit_msg.txt` via `write_to_file`, then committed with `git commit -F`. There are **NO exceptions**, even for "quick" or "small" commits.
+
+> **📖 See `git-commands.md` for the full protocol**, including step-by-step instructions, commit message format, scope conventions, prohibited commands, and the rationale for file-based commits.
 
 ---
 
@@ -526,38 +558,6 @@ Examples:
 
 ---
 
-### **Rule 10: VS Code Settings Automation (Optional)**
-
-If the project uses `scripts/agent.sh` for VS Code settings automation:
-
-**Act Mode Requirements:**
-
-1. **✅ Execute `clear && sleep 3 && scripts/agent.sh start` as THE FIRST COMMAND of any Act Mode task**
-   - Switches VS Code to development mode
-
-2. **✅ Execute `clear && sleep 3 && scripts/agent.sh finished` as THE LAST COMMAND of any Act Mode task**
-   - Switches VS Code to completion mode (full linting, formatting, cleanup)
-
-**Workflow Pattern:**
-
-```bash
-# FIRST COMMAND - Start of any Act Mode task
-clear && sleep 3 && scripts/agent.sh start
-
-# ... perform all task implementation work ...
-
-# LAST COMMAND - End of any Act Mode task
-clear && sleep 3 && scripts/agent.sh finished
-```
-
-**When NOT to Apply:**
-
-- ❌ Do not use in Plan Mode
-- ❌ Do not use if `scripts/agent.sh` does not exist in the project
-- ❌ Do not use if already in the middle of a task (only at start/end boundaries)
-
----
-
 ## **Summary: Applying These Rules**
 
 **Every Single Time You Respond:**

docs/code.md

@@ -114,6 +114,7 @@ These rules are **mandatory** and must be applied **strictly and consistently**
     - Methods and properties must be either:
       - `public`, or
       - `protected` (used instead of `private`)
+    - **Override:** If `private` is idiomatic for your language/framework (e.g., Java, C#, Kotlin), this convention can be overridden in `.clinerules/project.md` under "Special Rules".
 
 13. **Encapsulation Through Convention**
     - `protected` members are considered internal and must not be accessed outside subclasses.
@@ -391,4 +392,4 @@ These rules are **mandatory** and must be applied **strictly and consistently**
 - See **agents.md** for verification procedures and task completion criteria
 - See **testing.md** for test commands and AI testing workflow
 - See **git-commands.md** for git workflow instructions
-- See **agents.md Rule 8** for debugging rules (NO inline debug scripts — ALWAYS create script files)
+- See **agents.md** — Script-First Execution rule for debugging rules (NO inline debug scripts — ALWAYS create script files)

docs/git-commands.md

@@ -162,19 +162,60 @@ git push
 
 ---
 
+## **Conflict Resolution Protocol**
+
+When `git pull --rebase` encounters conflicts during `gitcmp`:
+
+1. **🛑 STOP** — Do not attempt automatic conflict resolution
+2. **📋 Report** — List the conflicting files and the nature of the conflict
+3. **❓ Ask the user** — Present the situation and ask how to proceed:
+   - **Option 1:** "Abort rebase and keep local commit" (`git rebase --abort`)
+   - **Option 2:** "I'll resolve manually — show me the conflicts"
+   - **Option 3:** "Abort and discard my commit" (rarely wanted)
+4. **⏳ Wait** — Do not proceed until the user responds
+5. **✅ After resolution** — Run the project's verify command before pushing
+
+**The agent MUST NOT:**
+- ❌ Automatically resolve merge conflicts
+- ❌ Accept "theirs" or "ours" without user approval
+- ❌ Force-push to bypass conflicts
+- ❌ Delete or reset commits without explicit user instruction
+
+---
+
+## **Push Failure Recovery**
+
+If `git push` fails after a successful commit:
+
+| Failure | Cause | Recovery |
+|---------|-------|----------|
+| Authentication error | SSH key or token issue | Report to user — cannot fix programmatically |
+| Remote rejection | Branch protection rules | Report to user — may need PR workflow |
+| Non-fast-forward | Remote has new commits | Run `git pull --rebase`, resolve conflicts if any, then retry push |
+| Network error | Connectivity issue | Wait briefly, retry once. If still failing, report to user |
+
+**In all cases:**
+- ✅ The local commit is safe — no work is lost
+- ✅ Report the error clearly to the user
+- ✅ Suggest the most likely fix
+- ❌ Do NOT retry more than once without user approval
+- ❌ Do NOT force-push (`git push --force`) unless explicitly instructed
+
+---
+
 ## **Important Notes**
 
 1. **Always perform `gitcmp` or `gitcm` in a new Cline task with context** when possible — this creates a clean task boundary for git operations while maintaining previous context.
 
 2. **Always run the project's verify command before committing:**
    ```bash
-   # Use the verify command from .clinerules/project.md
-   # Examples:
-   #   clear && yarn build && yarn test
-   #   clear && cargo build && cargo test
-   #   clear && docker compose config && docker compose build
-   #   clear && pytest
-   ```
+    # Use the verify command from .clinerules/project.md
+    # Examples:
+    #   clear && sleep 3 && yarn build && yarn test
+    #   clear && sleep 3 && cargo build && cargo test
+    #   clear && sleep 3 && docker compose config && docker compose build
+    #   clear && sleep 3 && pytest
+    ```
    Only commit if verification passes.
 
 3. **Never force-push** unless explicitly asked by the user.