synarcx 0.2.0 → 0.2.1

package/README.md

@@ -1,20 +1,82 @@
-# SynArcX — Synapse Architecture Code Extension
+# SynArcX
 
-Spec-driven development workflow for AI coding agents.
+![npm version](https://img.shields.io/npm/v/synarcx) ![license](https://img.shields.io/npm/l/synarcx) ![node](https://img.shields.io/node/v/synarcx)
+
+> Structured engineering workflows for AI coding assistants — persistent project memory, spec-driven development, and architecture drift prevention across every session.
+
+Works with **Claude Code, Cursor, GitHub Copilot, Cline, Windsurf, Codex**, and more AI coding tools.
+
+---
+
+## The Problem: Architecture Drift in AI-Assisted Development
+
+AI coding assistants like Claude Code and Cursor lose context fast. Requirements live in chat history. Architecture decisions vanish between sessions. Generated code drifts from design intent.
+
+Without an explicit workflow, AI-generated code gradually drifts from your architecture — each session introduces small misalignments that compound into structural debt. This is architecture drift, and it gets worse the longer the project runs.
+
+SynArcX fixes this by adding a lightweight spec layer between you and your AI — so both you and the assistant agree on what to build before any code is written.
+
+---
+
+## Why Not Just Prompt Better?
+
+Better prompts help, but they don't survive session resets, tool switches, or team handoffs. Every new session starts cold. Every new contributor re-explains the same constraints.
+
+SynArcX makes your engineering decisions durable. The `constitution.md` is always there. The specs don't live in someone's chat history.
+
+---
+
+## Why Not Just Use Another Spec Format?
+
+Spec formats describe *what* to build. 
+
+SynArcX structures *how you get there*  from exploration to proposal to implementation, and helps keep AI-generated changes aligned with the evolving codebase at every stage, not just at planning time.
+
+If you already have markdown specs in your repo, `/syn:sync` will incorporate them into the `constitution.md`.
+
+---
+
+## What Happens If You Ignore SynArcX?
+
+Nothing breaks immediately. That's the problem.
+
+```
+Week 1   AI reads the codebase, builds the feature correctly.
+
+Week 3   New session. AI re-derives context from code alone.
+         Small assumptions diverge from your actual design.
+
+Week 6   Three sessions in. The auth module now does things 
+         no spec ever said it should. The AI was "helpful."
+
+Week 10  You're untangling AI-introduced architecture violations
+         instead of shipping features. The specs live in a chat
+         log nobody can find.
+```
+
+SynArcX makes the spec the source of truth, not the chat history.
+
+---
 
 ## Install
 
+Requires **Node.js 20+**
+
 ```bash
 npm install -g synarcx
 ```
 
-Or with pnpm:
-
 ```bash
 pnpm add -g synarcx
 ```
 
-Run `synarcx --help` to verify.
+Verify:
+
+```bash
+synarcx --help
+```
+
+---
 
 ## Quick Start
 
@@ -23,66 +85,196 @@ cd your-project
 synarcx init
 ```
 
-Then in your AI tool:
+Then in your AI coding tool:
 
-1. `/syn:sync` — validate README and generate project constitution with guardrail Q&A
-2. `/syn:explore "your idea"` — think through the problem, then follow the suggestion to `/syn:propose`
-3. `/syn:propose my-feature` — create proposal, specs, design, and tasks in one step
-4. `/syn:clarify` — sharpen the artifacts with targeted questions
+1. `/syn:sync` — scan the project and generate the `constitution.md` (persistent project memory)
+2. `/syn:explore "your idea"` — think through the problem with your AI
+3. `/syn:propose "my-feature"` — create proposal, specs, design, and tasks in one step
+4. `/syn:clarify` — sharpen artifacts with targeted questions
 5. `/syn:analyze` — cross-artifact consistency check
 6. `/syn:apply` — implement the tasks
 7. `/syn:archive` — archive when done
 
-For bugs, use `/syn:debug` instead of `/syn:explore` — same flow, starting from a known error.
-For structural improvements, use `/syn:refactor`.
-For small, low-risk changes (typos, config tweaks), use `/syn:quick` — no artifacts, inline preview, then apply.
+For specific cases, use these instead of `/syn:explore`:
 
-## Commands
+* For bugs: use `/syn:debug`.
+* For structural improvements: use `/syn:refactor`.
+* For small low-risk changes (typos, config tweaks): use `/syn:quick` with no artifacts, just apply.
+
+---
+
+## How It Works: Spec-Driven AI Coding Workflow
+
+**Without SynArcX, development drift compounds silently:**
+
+```
+Session 1  ──►  Session 2  ──►  Session 3  ──►  Session N
+✓ correct       ~ close        ✗ diverged     ✗✗ structural debt
+                             (nobody noticed)
+```
+
+**With SynArcX — alignment is maintained explicitly:**
 
-| Command           | Description                                                                                      |
-| ----------------- | ------------------------------------------------------------------------------------------------ |
-| `/syn:sync`     | Validate README, scan project files, run guardrail Q&A, generate constitution                    |
-| `/syn:explore`  | Thinking partner — explore ideas, investigate problems, clarify requirements                    |
-| `/syn:debug`    | Diagnose a known error (3-phase analysis), then prompts `/syn:propose` explicitly              |
-| `/syn:refactor` | Investigate structural refactoring — map current vs target shape, then prompts `/syn:propose` |
-| `/syn:quick`    | Fast-path for small low-risk changes — inline preview, confirm, apply — no artifacts           |
-| `/syn:propose`  | Create a new change with proposal, specs, design, and tasks in one step                          |
-| `/syn:clarify`  | Ask up to 5 targeted questions to sharpen artifacts before implementation                        |
-| `/syn:analyze`  | Cross-artifact consistency check across proposal, specs, design, and tasks                       |
-| `/syn:apply`    | Implement tasks from a change's task list                                                        |
-| `/syn:archive`  | Archive a completed change and sync specs                                                        |
+```
+Session 1  ──►  constitution.md  ──►  Session 2  ──►  constitution.md  ──►  Session N
+✓ correct          (updated)          ✓ correct         (updated)          ✓ correct
+      
+ 		specs · architecture · intent preserved across every reset
+```
 
-## How It Works
+---
 
-AI coding assistants are powerful but lose context fast when requirements live only in chat history. SynArcX adds a lightweight spec layer so you and your AI agree on what to build before any code is written.
+**The workflow:**
 
 ```
-sync ─────────────────────────────────────────► constitution
+sync ──────────────────────────────────────────────────► constitution
 
 explore  ──┐
 debug    ──┤
            ├──► propose ──► clarify ──► analyze ──► apply ──► archive
 refactor ──┘
 
-quick ────────────────────────────────────────────► apply
+quick ────────────────────────────────────────────────────────► apply
 ```
 
-Each step suggests the next — you decide when to advance.
+Each step suggests the next — you decide when to advance. Works in Claude Code, Cursor, Cline, and any AI coding tool that supports slash commands.
 
-- `sync` generates/updates the constitution — run once, re-run when the project shifts
+- `sync` generates the `constitution.md` — run once, re-run when the project shifts
 - `explore`, `debug`, and `refactor` are entry points that hand off to `propose`
-- `quick` is a fast-path that skips the pipeline entirely — for small, low-risk changes
+- `quick` skips the pipeline for small, low-risk changes
 
 Each change gets its own folder under `synspec/changes/` with:
 
-- `proposal.md` — what and why
-- `specs/` — what the system shall do
-- `design.md` — how to build it
-- `tasks.md` — implementation checklist
+```
+synspec/changes/my-feature/
+├── proposal.md     # what and why
+├── design.md       # how to build it
+├── tasks.md        # implementation checklist
+└── specs/
+    └── *.md        # what the system shall do
+```
+
+### Persistent Project Memory
+
+`constitution.md` is the core of SynArcX. Generated by `/syn:sync`, it preserves architectural intent, conventions, constraints, and engineering decisions across AI sessions — keeping specifications, architecture, and implementation in sync.
+
+Unlike documentation, the constitution is optimized for AI operational context — not human reading.
+
+A typical `constitution.md` includes:
+
+```markdown
+## Architecture Principles
+- All API routes are RESTful, no GraphQL
+- Business logic lives in /services, not controllers
+
+## Module Boundaries
+- auth/ owns all token lifecycle — nothing else touches JWTs
+
+## Known Pitfalls
+- DB migrations must be backwards-compatible (rolling deploys)
+
+## Coding Patterns
+- Use Result<T, E> for fallible operations, never throw in services
+```
+
+---
+
+## Commands
+
+Used inside your AI coding tool (Claude Code, Cursor, Cline, etc.):
+
+| Command           | Description                                                              |
+| ----------------- | ------------------------------------------------------------------------ |
+| `/syn:sync`     | Scan project, run guardrail Q&A, generate/update `constitution.md`     |
+| `/syn:explore`  | Think through ideas, investigate problems, clarify requirements          |
+| `/syn:debug`    | Diagnose a known error (3-phase analysis), then prompts `/syn:propose` |
+| `/syn:refactor` | Map current vs target structure, then prompts `/syn:propose`           |
+| `/syn:quick`    | Fast-path for small low-risk changes — inline preview, confirm, apply   |
+| `/syn:propose`  | Create a new change with proposal, specs, design, and tasks              |
+| `/syn:clarify`  | Ask up to 5 targeted questions to sharpen artifacts                      |
+| `/syn:analyze`  | Cross-artifact consistency check across all change artifacts             |
+| `/syn:apply`    | Implement tasks from a change's task list                                |
+| `/syn:archive`  | Archive a completed change and sync specs                                |
+
+### CLI Commands
+
+Used in your terminal:
+
+| Command             | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `synarcx init`    | Set up SynArcX workflow structure in your repository |
+| `synarcx sync`    | Regenerate `constitution.md`                       |
+| `synarcx explore` | Open explore session                                 |
+| `synarcx propose` | Create a structured change proposal                  |
+| `synarcx clarify` | Refine requirements into explicit specifications     |
+| `synarcx analyze` | Evaluate architecture impact and tradeoffs           |
+| `synarcx apply`   | Execute implementation tasks                         |
+| `synarcx quick`   | Fast-path execution for small changes                |
 
-## Supported Tools
+---
 
-Works with 25+ AI coding assistants: Claude Code, OpenCode, Cursor, Gemini, GitHub Copilot, Cline, Windsurf, Codex, and more. Slash commands are generated per tool on `synarcx init`.
+## Artifacts
+
+Each workflow stage produces explicit, reviewable files:
+
+| Artifact            | Purpose                                            |
+| ------------------- | -------------------------------------------------- |
+| `proposal.md`     | Problem framing : what, why, and scope             |
+| `specs/*.md`      | Clarified requirements : what the system shall do |
+| `design.md`       | Architectural reasoning : how to build it          |
+| `tasks.md`        | Implementation checklist                           |
+| `constitution.md` | Persistent project memory for AI agents            |
+
+Artifacts create a traceable chain from requirements → reasoning → implementation → architecture decisions.
+
+---
+
+## SynArcX vs. Unstructured AI Coding
+
+| Capability                            | AI Coding Without SynArcX | With SynArcX                         |
+| ------------------------------------- | ------------------------- | ------------------------------------ |
+| Persistent engineering memory         | Lost between sessions     | Preserved in `constitution.md`     |
+| Structured specification flow         | Informal, chat-based      | Explicit staged workflow             |
+| Architecture-aware changes            | Inconsistent              | Built into every step                |
+| Artifact traceability                 | None                      | Proposal → spec → design → tasks  |
+| Session continuity                    | Weak                      | Persistent across tools and sessions |
+| Structured, traceable workflow stages | Rare                      | Core design                          |
+| Low-risk fast path                    | Manual                    | `/syn:quick`                       |
+
+---
+
+## Supported AI Coding Tools
+
+SynArcX works with Claude Code, Cursor, GitHub Copilot, Cline, Windsurf, Codex, Gemini, OpenCode, and more. Slash commands are generated per tool on `synarcx init` — each tool gets its own command syntax automatically.
+
+---
+
+## Built for AI-Assisted Software Engineering Teams
+
+SynArcX is evolving toward an architecture-aware workflow system for long-running AI-assisted software engineering. It is designed for:
+
+- long-running projects with evolving requirements
+- architecture-sensitive systems where drift is costly
+- AI-assisted engineering teams
+- spec-driven development practices
+- multi-session and multi-tool workflows
+- controlled implementation pipelines
+
+---
+
+## Status
+
+**v0.2.x** — core workflow stable (init, sync, propose, clarify, analyze, apply, archive, quick)
+
+Active development roadmap:
+
+- stronger repository cognition
+- architecture-aware execution validation
+- workflow guardrails
+- context continuity across tool switches
+- structured, traceable AI engineering pipelines
+
+---
 
 ## Development
 
@@ -97,6 +289,8 @@ pnpm link --global
 pnpm build
 ```
 
+---
+
 ## License
 
 MIT

package/dist/commands/config.js

@@ -3,7 +3,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { getGlobalConfigPath, getGlobalConfig, saveGlobalConfig, } from '../core/global-config.js';
 import { getNestedValue, setNestedValue, deleteNestedValue, coerceValue, formatValueYaml, validateConfigKeyPath, validateConfig, DEFAULT_CONFIG, } from '../core/config-schema.js';
-import { CORE_WORKFLOWS, ALL_WORKFLOWS, getProfileWorkflows } from '../core/profiles.js';
+import { getProfileWorkflows } from '../core/profiles.js';
+import { CORE_WORKFLOWS, ALL_WORKFLOWS } from '../core/shared/workflow-registry.js';
 import { SYNSPEC_DIR_NAME } from '../core/config.js';
 import { hasProjectConfigDrift } from '../core/profile-sync-drift.js';
 const WORKFLOW_PROMPT_META = {
@@ -133,8 +134,8 @@ export function diffProfileState(before, after) {
     };
 }
 function maybeWarnConfigDrift(projectDir, state, colorize) {
-    const openspecDir = path.join(projectDir, SYNSPEC_DIR_NAME);
-    if (!fs.existsSync(openspecDir)) {
+    const synspecDir = path.join(projectDir, SYNSPEC_DIR_NAME);
+    if (!fs.existsSync(synspecDir)) {
         return;
     }
     if (!hasProjectConfigDrift(projectDir, state.workflows, state.delivery)) {
@@ -517,10 +518,10 @@ export function registerConfigCommand(program) {
             config.delivery = nextState.delivery;
             config.workflows = nextState.workflows;
             saveGlobalConfig(config);
-            // Check if inside an OpenSpec project
+            // Check if inside a synarcx project
             const projectDir = process.cwd();
-            const openspecDir = path.join(projectDir, SYNSPEC_DIR_NAME);
-            if (fs.existsSync(openspecDir)) {
+            const synspecDir = path.join(projectDir, SYNSPEC_DIR_NAME);
+            if (fs.existsSync(synspecDir)) {
                 const applyNow = await confirm({
                     message: 'Apply changes to this project now?',
                     default: true,

package/dist/core/command-generation/adapters/bob.js

@@ -6,20 +6,7 @@
  */
 import path from 'path';
 import { transformToHyphenCommands } from '../../../utils/command-references.js';
-/**
- * Escapes a string value for safe YAML output.
- * Quotes the string if it contains special YAML characters.
- */
-function escapeYamlValue(value) {
-    // Check if value needs quoting (contains special YAML characters or starts/ends with whitespace)
-    const needsQuoting = /[:\n\r#{}[\],&*!|>'"%@`]|^\s|\s$/.test(value);
-    if (needsQuoting) {
-        // Use double quotes and escape internal double quotes and backslashes
-        const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
-        return `"${escaped}"`;
-    }
-    return value;
-}
+import { escapeYamlValue } from '../yaml-utils.js';
 /**
  * Bob Shell adapter for command generation.
  * File path: .bob/commands/syn-<id>.md
@@ -33,12 +20,12 @@ export const bobAdapter = {
     formatFile(content) {
         // Transform command references from colon to hyphen format for Bob
         const transformedBody = transformToHyphenCommands(content.body);
-        return `---
-description: ${escapeYamlValue(content.description)}
-argument-hint: command arguments
----
-
-${transformedBody}
+        return `---
+description: ${escapeYamlValue(content.description)}
+argument-hint: command arguments
+---
+
+${transformedBody}
 `;
     },
 };

package/dist/core/command-generation/adapters/claude.js

@@ -4,27 +4,7 @@
  * Formats commands for Claude Code following its frontmatter specification.
  */
 import path from 'path';
-/**
- * Escapes a string value for safe YAML output.
- * Quotes the string if it contains special YAML characters.
- */
-function escapeYamlValue(value) {
-    // Check if value needs quoting (contains special YAML characters or starts/ends with whitespace)
-    const needsQuoting = /[:\n\r#{}[\],&*!|>'"%@`]|^\s|\s$/.test(value);
-    if (needsQuoting) {
-        // Use double quotes and escape internal double quotes and backslashes
-        const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
-        return `"${escaped}"`;
-    }
-    return value;
-}
-/**
- * Formats a tags array as a YAML array with proper escaping.
- */
-function formatTagsArray(tags) {
-    const escapedTags = tags.map((tag) => escapeYamlValue(tag));
-    return `[${escapedTags.join(', ')}]`;
-}
+import { escapeYamlValue, formatTagsArray } from '../yaml-utils.js';
 /**
  * Claude Code adapter for command generation.
  * File path: .claude/commands/syn/<id>.md
@@ -36,14 +16,14 @@ export const claudeAdapter = {
         return path.join('.claude', 'commands', 'syn', `${commandId}.md`);
     },
     formatFile(content) {
-        return `---
-name: ${escapeYamlValue(content.name)}
-description: ${escapeYamlValue(content.description)}
-category: ${escapeYamlValue(content.category)}
-tags: ${formatTagsArray(content.tags)}
----
-
-${content.body}
+        return `---
+name: ${escapeYamlValue(content.name)}
+description: ${escapeYamlValue(content.description)}
+category: ${escapeYamlValue(content.category)}
+tags: ${formatTagsArray(content.tags)}
+---
+
+${content.body}
 `;
     },
 };

package/dist/core/command-generation/adapters/cursor.js

@@ -5,20 +5,7 @@
  * Cursor uses a different frontmatter format and file naming convention.
  */
 import path from 'path';
-/**
- * Escapes a string value for safe YAML output.
- * Quotes the string if it contains special YAML characters.
- */
-function escapeYamlValue(value) {
-    // Check if value needs quoting (contains special YAML characters or starts/ends with whitespace)
-    const needsQuoting = /[:\n\r#{}[\],&*!|>'"%@`]|^\s|\s$/.test(value);
-    if (needsQuoting) {
-        // Use double quotes and escape internal double quotes and backslashes
-        const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
-        return `"${escaped}"`;
-    }
-    return value;
-}
+import { escapeYamlValue } from '../yaml-utils.js';
 /**
  * Cursor adapter for command generation.
  * File path: .cursor/commands/syn-<id>.md
@@ -30,14 +17,14 @@ export const cursorAdapter = {
         return path.join('.cursor', 'commands', `syn-${commandId}.md`);
     },
     formatFile(content) {
-        return `---
-name: /syn-${content.id}
-id: syn-${content.id}
-category: ${escapeYamlValue(content.category)}
-description: ${escapeYamlValue(content.description)}
----
-
-${content.body}
+        return `---
+name: /syn-${content.id}
+id: syn-${content.id}
+category: ${escapeYamlValue(content.category)}
+description: ${escapeYamlValue(content.description)}
+---
+
+${content.body}
 `;
     },
 };

package/dist/core/command-generation/adapters/pi.js

@@ -6,6 +6,7 @@
  */
 import path from 'path';
 import { transformToHyphenCommands } from '../../../utils/command-references.js';
+import { escapeYamlValue } from '../yaml-utils.js';
 const PI_INPUT_HEADING = /^\*\*Input\*\*:[^\n]*$/m;
 function injectPiArgs(body) {
     if (body.includes('$@') || body.includes('$ARGUMENTS')) {
@@ -13,20 +14,6 @@ function injectPiArgs(body) {
     }
     return body.replace(PI_INPUT_HEADING, (heading) => `${heading}\n**Provided arguments**: $@`);
 }
-/**
- * Escapes a string value for safe YAML output.
- * Quotes the string if it contains special YAML characters.
- */
-function escapeYamlValue(value) {
-    // Check if value needs quoting (contains special YAML characters or starts/ends with whitespace)
-    const needsQuoting = /[:\n\r#{}[\],&*!|>'"%@`]|^\s|\s$/.test(value);
-    if (needsQuoting) {
-        // Use double quotes and escape internal double quotes and backslashes
-        const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
-        return `"${escaped}"`;
-    }
-    return value;
-}
 /**
  * Pi adapter for prompt template generation.
  * File path: .pi/prompts/syn-<id>.md
@@ -44,11 +31,11 @@ export const piAdapter = {
     formatFile(content) {
         // Transform /syn: references to /syn- and inject $@ for template args
         const transformedBody = transformToHyphenCommands(content.body);
-        return `---
-description: ${escapeYamlValue(content.description)}
----
-
-${injectPiArgs(transformedBody)}
+        return `---
+description: ${escapeYamlValue(content.description)}
+---
+
+${injectPiArgs(transformedBody)}
 `;
     },
 };

package/dist/core/command-generation/adapters/windsurf.js

@@ -5,27 +5,7 @@
  * Windsurf uses a similar format to Claude but may have different conventions.
  */
 import path from 'path';
-/**
- * Escapes a string value for safe YAML output.
- * Quotes the string if it contains special YAML characters.
- */
-function escapeYamlValue(value) {
-    // Check if value needs quoting (contains special YAML characters or starts/ends with whitespace)
-    const needsQuoting = /[:\n\r#{}[\],&*!|>'"%@`]|^\s|\s$/.test(value);
-    if (needsQuoting) {
-        // Use double quotes and escape internal double quotes and backslashes
-        const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
-        return `"${escaped}"`;
-    }
-    return value;
-}
-/**
- * Formats a tags array as a YAML array with proper escaping.
- */
-function formatTagsArray(tags) {
-    const escapedTags = tags.map((tag) => escapeYamlValue(tag));
-    return `[${escapedTags.join(', ')}]`;
-}
+import { escapeYamlValue, formatTagsArray } from '../yaml-utils.js';
 /**
  * Windsurf adapter for command generation.
  * File path: .windsurf/workflows/syn-<id>.md
@@ -37,14 +17,14 @@ export const windsurfAdapter = {
         return path.join('.windsurf', 'workflows', `syn-${commandId}.md`);
     },
     formatFile(content) {
-        return `---
-name: ${escapeYamlValue(content.name)}
-description: ${escapeYamlValue(content.description)}
-category: ${escapeYamlValue(content.category)}
-tags: ${formatTagsArray(content.tags)}
----
-
-${content.body}
+        return `---
+name: ${escapeYamlValue(content.name)}
+description: ${escapeYamlValue(content.description)}
+category: ${escapeYamlValue(content.category)}
+tags: ${formatTagsArray(content.tags)}
+---
+
+${content.body}
 `;
     },
 };

package/dist/core/command-generation/yaml-utils.d.ts

@@ -0,0 +1,3 @@
+export declare function escapeYamlValue(value: string): string;
+export declare function formatTagsArray(tags: string[]): string;
+//# sourceMappingURL=yaml-utils.d.ts.map

package/dist/core/command-generation/yaml-utils.js

@@ -0,0 +1,12 @@
+export function escapeYamlValue(value) {
+    const needsQuoting = /[:\n\r#{}[\],&*!|>'"%@`]|^\s|\s$/.test(value);
+    if (needsQuoting) {
+        const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+        return `"${escaped}"`;
+    }
+    return value;
+}
+export function formatTagsArray(tags) {
+    return `[${tags.map(escapeYamlValue).join(', ')}]`;
+}
+//# sourceMappingURL=yaml-utils.js.map

package/dist/core/completions/installers/bash-installer.d.ts

@@ -9,6 +9,7 @@ export declare class BashInstaller {
      * Markers for .bashrc configuration management
      */
     private readonly BASHRC_MARKERS;
+    private readonly LEGACY_MARKERS;
     constructor(homeDir?: string);
     /**
      * Check if bash-completion is installed

package/dist/core/completions/installers/bash-installer.js

@@ -12,6 +12,10 @@ export class BashInstaller {
      * Markers for .bashrc configuration management
      */
     BASHRC_MARKERS = {
+        start: '# SYNARCX:START',
+        end: '# SYNARCX:END',
+    };
+    LEGACY_MARKERS = {
         start: '# OPENSPEC:START',
         end: '# OPENSPEC:END',
     };
@@ -147,15 +151,22 @@ export class BashInstaller {
             }
             // Read file content
             const content = await fs.readFile(bashrcPath, 'utf-8');
+            // Determine which markers to use (check new first, fall back to legacy)
+            const startMarker = content.includes(this.BASHRC_MARKERS.start)
+                ? this.BASHRC_MARKERS.start
+                : this.LEGACY_MARKERS.start;
+            const endMarker = content.includes(this.BASHRC_MARKERS.end)
+                ? this.BASHRC_MARKERS.end
+                : this.LEGACY_MARKERS.end;
             // Check if markers exist
-            if (!content.includes(this.BASHRC_MARKERS.start) || !content.includes(this.BASHRC_MARKERS.end)) {
+            if (!content.includes(startMarker) || !content.includes(endMarker)) {
                 // Markers don't exist, nothing to remove
                 return true;
             }
             // Remove content between markers (including markers)
             const lines = content.split('\n');
-            const startIndex = lines.findIndex((line) => line.trim() === this.BASHRC_MARKERS.start);
-            const endIndex = lines.findIndex((line) => line.trim() === this.BASHRC_MARKERS.end);
+            const startIndex = lines.findIndex((line) => line.trim() === startMarker);
+            const endIndex = lines.findIndex((line) => line.trim() === endMarker);
             if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
                 // Invalid marker placement
                 return false;