Merge pull request #120 from cyberfabric/bugfix/load-system-prompts-wrong-rules

refactor(init): unify root AGENTS.md and CLAUDE.md managed blocks

Author: ainetx

.bootstrap/.core/skills/cypilot/SKILL.md

@@ -8,22 +8,23 @@ description: "Invoke when user asks to do something with Cypilot, or wants to an
 
 <!-- toc -->
 
-- [Goal](#goal)
-- [Preconditions](#preconditions)
-- [⚠️ MUST Instruction Semantics ⚠️](#must-instruction-semantics)
-- [Agent Acknowledgment](#agent-acknowledgment)
-- [Execution Logging](#execution-logging)
-- [Variables](#variables)
-  - [Template Variable Resolution](#template-variable-resolution)
-- [CLI Resolution](#cli-resolution)
-- [Protocol Guard](#protocol-guard)
-- [Cypilot Mode](#cypilot-mode)
-- [Agent-Safe Invocation](#agent-safe-invocation)
-- [Quick Commands (No Protocol)](#quick-commands-no-protocol)
-- [Workflow Routing](#workflow-routing)
-- [Command Reference](#command-reference)
-- [Auto-Configuration](#auto-configuration)
-- [Project Configuration](#project-configuration)
+- [Cypilot Unified Tool](#cypilot-unified-tool)
+  - [Goal](#goal)
+  - [Preconditions](#preconditions)
+  - [⚠️ MUST Instruction Semantics ⚠️](#️-must-instruction-semantics-️)
+  - [Agent Acknowledgment](#agent-acknowledgment)
+  - [Execution Logging](#execution-logging)
+  - [Variables](#variables)
+    - [Template Variable Resolution](#template-variable-resolution)
+  - [CLI Resolution](#cli-resolution)
+  - [Protocol Guard](#protocol-guard)
+  - [Cypilot Mode](#cypilot-mode)
+  - [Agent-Safe Invocation](#agent-safe-invocation)
+  - [Quick Commands (No Protocol)](#quick-commands-no-protocol)
+  - [Workflow Routing](#workflow-routing)
+  - [Command Reference](#command-reference)
+  - [Auto-Configuration](#auto-configuration)
+  - [Project Configuration](#project-configuration)
 
 <!-- /toc -->
 
@@ -73,7 +74,7 @@ Example:
 
 | Variable | Value | Use |
 |---|---|---|
-| `{cypilot_path}` | Directory containing this `../../SKILL.md` | Base path for all Cypilot-relative references |
+| `{cypilot_path}` | Directory path resolved from root `AGENTS.md` | Base path for all Cypilot-relative references |
 | `{cypilot_mode}` | `on` or `off` | Current Cypilot mode state |
 | `{cpt_cmd}` | `cpt` or `python3 {cypilot_path}/.core/skills/cypilot/scripts/cypilot.py` | Resolved CLI entrypoint |
 | `{cpt_installed}` | `true` or `false` | Whether the `cpt` CLI is available |

.bootstrap/.core/skills/cypilot/scripts/cypilot/__init__.py

@@ -17,7 +17,7 @@ def main(argv: Optional[List[str]] = None) -> int:
     from .cli import main as _main
     return _main(argv)
 
-__version__ = "v3.2.0-beta"
+__version__ = "v3.2.1-beta"
 
 __all__ = [
     # Main entry point

.bootstrap/.core/skills/cypilot/scripts/cypilot/commands/init.py

@@ -273,22 +273,9 @@ def _compute_managed_block(install_dir: str) -> str:
     # @cpt-begin:cpt-cypilot-algo-core-infra-inject-root-agents:p1:inst-compute-block
     return (
         f"{MARKER_START}\n"
-        f"## Cypilot AI Agent Navigation\n"
-        f"\n"
-        f"**Remember these variables while working in this project:**\n"
-        f"\n"
         f"```toml\n"
         f'cypilot_path = "{install_dir}"\n'
         f"```\n"
-        f"\n"
-        f"## Navigation Rules\n"
-        f"\n"
-        f"ALWAYS open and follow `{{cypilot_path}}/.gen/AGENTS.md` FIRST\n"
-        f"\n"
-        f"ALWAYS open and follow `{{cypilot_path}}/config/AGENTS.md` FIRST\n"
-        f"\n"
-        f"ALWAYS invoke `{{cypilot_path}}/.core/skills/cypilot/SKILL.md` WHEN user asks to do something with Cypilot\n"
-        f"\n"
         f"{MARKER_END}"
     )
     # @cpt-end:cpt-cypilot-algo-core-infra-inject-root-agents:p1:inst-compute-block
@@ -340,38 +327,9 @@ def _inject_root_agents(project_root: Path, install_dir: str, dry_run: bool = Fa
     return _inject_managed_block(project_root / "AGENTS.md", install_dir, dry_run)
 
 # @cpt-begin:cpt-cypilot-flow-core-infra-project-init:p1:inst-init-inject-claude
-def _compute_claude_block() -> str:
-    return (
-        f"{MARKER_START}\n"
-        f"STOP and READ `AGENTS.md` in project root before ANY tool calls or skill invocation\n"
-        f"{MARKER_END}"
-    )
-
 def _inject_root_claude(project_root: Path, install_dir: str, dry_run: bool = False) -> str:
     """Inject or update root CLAUDE.md managed block. Returns action taken."""
-    claude_file = project_root / "CLAUDE.md"
-    expected_block = _compute_claude_block()
-
-    if not claude_file.is_file():
-        if not dry_run:
-            claude_file.write_text(expected_block + "\n", encoding="utf-8")
-        return "created"
-
-    content = claude_file.read_text(encoding="utf-8")
-
-    if MARKER_START in content and MARKER_END in content:
-        start_idx = content.index(MARKER_START)
-        end_idx = content.index(MARKER_END) + len(MARKER_END)
-        current_block = content[start_idx:end_idx]
-        if current_block == expected_block.strip():
-            return "unchanged"
-        new_content = content[:start_idx] + expected_block + content[end_idx:]
-    else:
-        new_content = expected_block + "\n\n" + content
-
-    if not dry_run:
-        claude_file.write_text(new_content, encoding="utf-8")
-    return "updated"
+    return _inject_managed_block(project_root / "CLAUDE.md", install_dir, dry_run)
 # @cpt-end:cpt-cypilot-flow-core-infra-project-init:p1:inst-init-inject-claude
 
 def cmd_init(argv: List[str]) -> int:

.bootstrap/.core/whatsnew.toml

@@ -181,4 +181,12 @@ details = """\
 - **Checklist and methodology normalization** — streamlined `code-checklist.md`, `consistency-checklist.md`, `plan-checklist.md`, `prompt-engineering.md`, `reverse-engineering.md`, and `auto-config.md` into denser formats optimized for agent consumption
 - **Post-compaction TOC fix** — marker-based `validate-toc` now expects the same heading set that `toc` generates, so documents with secondary `H1` sections such as `# MUST HAVE` / `# MUST NOT HAVE` validate correctly with `--max-level 2`
 - **Regression coverage added** — test coverage now includes the marker-based TOC validation case with secondary `H1` sections in a single document\
+"""
+
+["v3.2.1-beta"]
+summary = "Compact root markers, unified CLAUDE.md injection"
+details = """\
+- **Compact root marker blocks** — removed verbose navigation rules from `AGENTS.md` and `CLAUDE.md` managed blocks; now contains only the `cypilot_path` TOML definition
+- **Unified CLAUDE.md injection** — `_inject_root_claude()` now reuses `_inject_managed_block()` for consistent block generation
+- **Variable description fix** — `{cypilot_path}` documentation updated to clarify it's resolved from root `AGENTS.md`\
 """

AGENTS.md

@@ -1,35 +1,5 @@
 <!-- @cpt:root-agents -->
-## Cypilot AI Agent Navigation
-
-**Remember these variables while working in this project:**
-
 ```toml
 cypilot_path = ".bootstrap"
 ```
-
-## Navigation Rules
-
-ALWAYS open and follow `{cypilot_path}/.gen/AGENTS.md` FIRST
-
-ALWAYS open and follow `{cypilot_path}/config/AGENTS.md` FIRST
-
-ALWAYS invoke `{cypilot_path}/.core/skills/cypilot/SKILL.md` WHEN user asks to do something with Cypilot
-
 <!-- /@cpt:root-agents -->
-
-## Cypilot AI Agent Navigation
-
-**Version**: 1.1
-
----
-
-## Navigation Rules
-
-ALWAYS open and follow `{cypilot_path}/config/AGENTS.md` WHEN starting any Cypilot work
-
-### Dependency Error Handling
-
-**If referenced file not found**:
-- Log warning to user: "Cypilot dependency not found: {path}"
-- Continue with available files — do NOT fail silently
-- If critical dependency missing (SKILL.md, workflow), inform user and suggest `/cypilot` to reinitialize

CLAUDE.md

@@ -1,3 +1,5 @@
 <!-- @cpt:root-agents -->
-STOP and READ `AGENTS.md` in project root before ANY tool calls or skill invocation
+```toml
+cypilot_path = ".bootstrap"
+```
 <!-- /@cpt:root-agents -->

architecture/DESIGN.md

@@ -890,18 +890,19 @@ sequenceDiagram
 
 **Description**: User initializes Cypilot in a project. The skill engine asks for install directory and agent selection. It defines a **root system** (name and slug derived from the project directory name), creates core configs (`core.toml` with root system, `artifacts.toml` with default autodetect rules), generates agent entry points, and sets up `{cypilot_path}/config/AGENTS.md` with default WHEN rules. After core setup, the tool prompts `Install SDLC kit? [a]ccept [d]ecline`. If accepted, the kit is downloaded from GitHub. If the kit source contains `manifest.toml`, the Kit Manager validates the manifest, reads declared resources, prompts the user for destination paths on `user_modifiable` resources, copies each resource to its resolved path, resolves template variables in kit files, and registers all resource bindings in `core.toml`. If no `manifest.toml` is present, files are copied to the default kit config directory. If declined, the user can install kits later via `cpt kit install`.
 
-**Root AGENTS.md injection**: During initialization (and verified on every CLI invocation), the engine ensures the project root `AGENTS.md` file contains a managed block that points agents to the Cypilot navigation entry:
+**Root AGENTS.md / CLAUDE.md injection**: During initialization (and verified on every CLI invocation), the engine ensures the project root `AGENTS.md` and `CLAUDE.md` files contain the same managed block with only the configured adapter path:
 
-```markdown
+````markdown
 <!-- @cpt:root-agents -->
-ALWAYS open and follow `{cypilot_path}/.gen/AGENTS.md` FIRST
-ALWAYS open and follow `{cypilot_path}/config/AGENTS.md` WHEN it exists
-<!-- @/cpt:root-agents -->
+```toml
+cypilot_path = ".bootstrap"
 ```
+<!-- @/cpt:root-agents -->
+````
 
-The block is inserted at the **beginning** of the file. If the file does not exist, it is created. The path inside the block reflects the actual install directory (e.g., `@/{cypilot_path}/config/AGENTS.md`). Content between the `<!-- @cpt:root-agents -->` and `<!-- @/cpt:root-agents -->` comment markers is fully managed by Cypilot — it is overwritten on every check, so manual edits inside the block are discarded.
+The block is inserted at the **beginning** of each file. If a file does not exist, it is created. The managed content is a TOML fence that declares only `cypilot_path`, and the path reflects the actual install directory. Content between the `<!-- @cpt:root-agents -->` and `<!-- @/cpt:root-agents -->` comment markers is fully managed by Cypilot — it is overwritten on every check, so manual edits inside the block are discarded.
 
-**Integrity invariant**: every Cypilot CLI command (not just `init`) verifies the root `AGENTS.md` block exists and is correct before proceeding. If the block is missing or the path is stale (e.g., install directory changed), the engine silently re-injects it. This guarantees that any agent opening the project will be routed to Cypilot regardless of how the IDE session started.
+**Integrity invariant**: every Cypilot CLI command (not just `init`) verifies the root `AGENTS.md` and `CLAUDE.md` blocks exist and are correct before proceeding. If a block is missing or the path is stale (e.g., install directory changed), the engine silently re-injects it. This guarantees that root agent files always expose the current `cypilot_path` without duplicating navigation rules.
 
 #### Artifact Validation
 

architecture/features/agent-integration.md

@@ -83,7 +83,7 @@ Without this feature, users would need to manually create and maintain agent-spe
    1. - `p1` - Generate agent-native entry points (skill shims, workflow proxies, rules) - `inst-generate-entry-points`
    2. - `p1` - Write files to agent directory (e.g., `.windsurf/workflows/`, `.cursor/rules/`) - `inst-write-files`
 8. - `p1` - Compose and write main SKILL.md from collected skill sections - `inst-compose-skill`
-9. - `p1` - Inject managed block into root AGENTS.md - `inst-inject-agents`
+9. - `p1` - Inject the same managed `cypilot_path` block into root AGENTS.md and CLAUDE.md - `inst-inject-agents`
 10. [x] - `p1` - **RETURN** generation report (agents, files written, workflows discovered) - `inst-return-report`
 
 ### Execute Generic Workflow

architecture/specs/sysprompts.md

@@ -89,25 +89,24 @@ All sysprompt files are optional. Only files referenced in `AGENTS.md` are loade
 
 ## Root AGENTS.md Entry
 
-Cypilot injects a managed block into the **project root** `AGENTS.md` that routes agents to `{cypilot_path}/config/AGENTS.md`:
+Cypilot injects the same managed block into the **project root** `AGENTS.md` and `CLAUDE.md`, exposing only the configured adapter path:
 
-```markdown
+````markdown
 <!-- @cpt:root-agents -->
-ALWAYS open and follow `{cypilot_path}/.gen/AGENTS.md` FIRST
-ALWAYS open and follow `{cypilot_path}/config/AGENTS.md` WHEN it exists
-<!-- @/cpt:root-agents -->
+```toml
+cypilot_path = ".bootstrap"
 ```
+<!-- @/cpt:root-agents -->
+````
 
 **Behavior**:
-- Inserted at the **beginning** of the root `AGENTS.md` file
-- If the file does not exist, it is created
-- The path reflects the actual install directory (e.g., `@/{cypilot_path}/config/AGENTS.md`)
+- Inserted at the **beginning** of the root `AGENTS.md` and `CLAUDE.md` files
+- If a file does not exist, it is created
+- The path reflects the actual install directory via `cypilot_path`
 - Content between the `<!-- @cpt:root-agents -->` and `<!-- @/cpt:root-agents -->` markers is **fully managed** by Cypilot — overwritten on every check
 - Manual edits inside the block are discarded
 
-**Integrity check**: every Cypilot CLI invocation (not just `init`) verifies the block exists and the path is correct. If the block is missing or stale, it is silently re-injected.
-
-This ensures any agent that opens the project is immediately routed to Cypilot's navigation entry point.
+**Integrity check**: every Cypilot CLI invocation (not just `init`) verifies both blocks exist and the path is correct. If a block is missing or stale, it is silently re-injected. This ensures any agent that opens the project is immediately routed to Cypilot's navigation entry point.
 
 ---
 

skills/cypilot/SKILL.md

@@ -8,22 +8,23 @@ description: "Invoke when user asks to do something with Cypilot, or wants to an
 
 <!-- toc -->
 
-- [Goal](#goal)
-- [Preconditions](#preconditions)
-- [⚠️ MUST Instruction Semantics ⚠️](#must-instruction-semantics)
-- [Agent Acknowledgment](#agent-acknowledgment)
-- [Execution Logging](#execution-logging)
-- [Variables](#variables)
-  - [Template Variable Resolution](#template-variable-resolution)
-- [CLI Resolution](#cli-resolution)
-- [Protocol Guard](#protocol-guard)
-- [Cypilot Mode](#cypilot-mode)
-- [Agent-Safe Invocation](#agent-safe-invocation)
-- [Quick Commands (No Protocol)](#quick-commands-no-protocol)
-- [Workflow Routing](#workflow-routing)
-- [Command Reference](#command-reference)
-- [Auto-Configuration](#auto-configuration)
-- [Project Configuration](#project-configuration)
+- [Cypilot Unified Tool](#cypilot-unified-tool)
+  - [Goal](#goal)
+  - [Preconditions](#preconditions)
+  - [⚠️ MUST Instruction Semantics ⚠️](#️-must-instruction-semantics-️)
+  - [Agent Acknowledgment](#agent-acknowledgment)
+  - [Execution Logging](#execution-logging)
+  - [Variables](#variables)
+    - [Template Variable Resolution](#template-variable-resolution)
+  - [CLI Resolution](#cli-resolution)
+  - [Protocol Guard](#protocol-guard)
+  - [Cypilot Mode](#cypilot-mode)
+  - [Agent-Safe Invocation](#agent-safe-invocation)
+  - [Quick Commands (No Protocol)](#quick-commands-no-protocol)
+  - [Workflow Routing](#workflow-routing)
+  - [Command Reference](#command-reference)
+  - [Auto-Configuration](#auto-configuration)
+  - [Project Configuration](#project-configuration)
 
 <!-- /toc -->
 
@@ -73,7 +74,7 @@ Example:
 
 | Variable | Value | Use |
 |---|---|---|
-| `{cypilot_path}` | Directory containing this `../../SKILL.md` | Base path for all Cypilot-relative references |
+| `{cypilot_path}` | Directory path resolved from root `AGENTS.md` | Base path for all Cypilot-relative references |
 | `{cypilot_mode}` | `on` or `off` | Current Cypilot mode state |
 | `{cpt_cmd}` | `cpt` or `python3 {cypilot_path}/.core/skills/cypilot/scripts/cypilot.py` | Resolved CLI entrypoint |
 | `{cpt_installed}` | `true` or `false` | Whether the `cpt` CLI is available |