synarcx 0.1.0 → 0.2.0

package/README.md

@@ -25,7 +25,7 @@ synarcx init
 
 Then in your AI tool:
 
-1. `/syn:sync` — generate project context (run once, re-run when the project shifts significantly)
+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
@@ -34,35 +34,47 @@ Then in your AI tool:
 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.
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `/syn:sync` | Generate or update the project constitution from README, AGENTS.md, package.json |
-| `/syn:explore` | Thinking partner — explore ideas, investigate problems, clarify requirements |
-| `/syn:debug` | Investigation tool — diagnose a known error and hand off findings to `/syn:propose` |
-| `/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 |
+| 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                                                        |
 
 ## 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.
 
 ```
-syn:sync (once)
+sync ─────────────────────────────────────────► constitution
 
-explore ──┐
+explore  ──┐
+debug    ──┤
            ├──► propose ──► clarify ──► analyze ──► apply ──► archive
-debug   ──┘
+refactor ──┘
+
+quick ────────────────────────────────────────────► apply
 ```
 
 Each step suggests the next — you decide when to advance.
 
+- `sync` generates/updates the constitution — 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
+
 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

package/dist/core/init.js

@@ -41,6 +41,8 @@ const WORKFLOW_TO_SKILL_DIR = {
     'clarify': 'syn-clarify',
     'analyze': 'syn-analyze',
     'debug': 'syn-debug',
+    'refactor': 'syn-refactor',
+    'quick': 'syn-quick',
 };
 // -----------------------------------------------------------------------------
 // Init Command Class

package/dist/core/profile-sync-drift.js

@@ -16,6 +16,8 @@ export const WORKFLOW_TO_SKILL_DIR = {
     'clarify': 'syn-clarify',
     'analyze': 'syn-analyze',
     'debug': 'syn-debug',
+    'refactor': 'syn-refactor',
+    'quick': 'syn-quick',
 };
 function toKnownWorkflows(workflows) {
     return workflows.filter((workflow) => ALL_WORKFLOWS.includes(workflow));

package/dist/core/profiles.d.ts

@@ -9,11 +9,11 @@ import type { Profile } from './global-config.js';
  * Core workflows included in the 'core' profile.
  * These provide the streamlined experience for new users.
  */
-export declare const CORE_WORKFLOWS: readonly ["explore", "propose", "clarify", "analyze", "apply", "debug", "archive", "sync"];
+export declare const CORE_WORKFLOWS: readonly ["explore", "propose", "clarify", "analyze", "apply", "debug", "archive", "sync", "refactor", "quick"];
 /**
  * All available workflows in the system.
  */
-export declare const ALL_WORKFLOWS: readonly ["explore", "propose", "clarify", "analyze", "apply", "debug", "archive", "sync"];
+export declare const ALL_WORKFLOWS: readonly ["explore", "propose", "clarify", "analyze", "apply", "debug", "archive", "sync", "refactor", "quick"];
 export type WorkflowId = (typeof ALL_WORKFLOWS)[number];
 export type CoreWorkflowId = (typeof CORE_WORKFLOWS)[number];
 /**

package/dist/core/profiles.js

@@ -8,7 +8,7 @@
  * Core workflows included in the 'core' profile.
  * These provide the streamlined experience for new users.
  */
-export const CORE_WORKFLOWS = ['explore', 'propose', 'clarify', 'analyze', 'apply', 'debug', 'archive', 'sync'];
+export const CORE_WORKFLOWS = ['explore', 'propose', 'clarify', 'analyze', 'apply', 'debug', 'archive', 'sync', 'refactor', 'quick'];
 /**
  * All available workflows in the system.
  */
@@ -21,6 +21,8 @@ export const ALL_WORKFLOWS = [
     'debug',
     'archive',
     'sync',
+    'refactor',
+    'quick',
 ];
 /**
  * Resolves which workflows should be active for a given profile configuration.

package/dist/core/shared/skill-generation.js

@@ -3,7 +3,7 @@
  *
  * Shared utilities for generating skill and command files.
  */
-import { getSynExploreSkillTemplate, getSynApplySkillTemplate, getSynArchiveSkillTemplate, getSynProposeSkillTemplate, getSynSyncSkillTemplate, getSynClarifySkillTemplate, getSynAnalyzeSkillTemplate, getSynDebugSkillTemplate, getSynExploreCommandTemplate, getSynApplyCommandTemplate, getSynArchiveCommandTemplate, getSynProposeCommandTemplate, getSynSyncCommandTemplate, getSynClarifyCommandTemplate, getSynAnalyzeCommandTemplate, getSynDebugCommandTemplate, } from '../templates/skill-templates.js';
+import { getSynExploreSkillTemplate, getSynApplySkillTemplate, getSynArchiveSkillTemplate, getSynProposeSkillTemplate, getSynSyncSkillTemplate, getSynClarifySkillTemplate, getSynAnalyzeSkillTemplate, getSynDebugSkillTemplate, getSynRefactorSkillTemplate, getSynQuickSkillTemplate, getSynExploreCommandTemplate, getSynApplyCommandTemplate, getSynArchiveCommandTemplate, getSynProposeCommandTemplate, getSynSyncCommandTemplate, getSynClarifyCommandTemplate, getSynAnalyzeCommandTemplate, getSynDebugCommandTemplate, getSynRefactorCommandTemplate, getSynQuickCommandTemplate, } from '../templates/skill-templates.js';
 /**
  * Gets skill templates with their directory names, optionally filtered by workflow IDs.
  *
@@ -19,6 +19,8 @@ export function getSkillTemplates(workflowFilter) {
         { template: getSynClarifySkillTemplate(), dirName: 'syn-clarify', workflowId: 'clarify' },
         { template: getSynAnalyzeSkillTemplate(), dirName: 'syn-analyze', workflowId: 'analyze' },
         { template: getSynDebugSkillTemplate(), dirName: 'syn-debug', workflowId: 'debug' },
+        { template: getSynRefactorSkillTemplate(), dirName: 'syn-refactor', workflowId: 'refactor' },
+        { template: getSynQuickSkillTemplate(), dirName: 'syn-quick', workflowId: 'quick' },
     ];
     if (!workflowFilter)
         return all;
@@ -40,6 +42,8 @@ export function getCommandTemplates(workflowFilter) {
         { template: getSynClarifyCommandTemplate(), id: 'clarify' },
         { template: getSynAnalyzeCommandTemplate(), id: 'analyze' },
         { template: getSynDebugCommandTemplate(), id: 'debug' },
+        { template: getSynRefactorCommandTemplate(), id: 'refactor' },
+        { template: getSynQuickCommandTemplate(), id: 'quick' },
     ];
     if (!workflowFilter)
         return all;

package/dist/core/shared/tool-detection.d.ts

@@ -6,12 +6,12 @@
 /**
  * Names of skill directories created by synarcx init.
  */
-export declare const SKILL_NAMES: readonly ["syn-explore", "syn-apply", "syn-archive", "syn-propose", "syn-sync", "syn-clarify", "syn-analyze", "syn-debug"];
+export declare const SKILL_NAMES: readonly ["syn-explore", "syn-apply", "syn-archive", "syn-propose", "syn-sync", "syn-clarify", "syn-analyze", "syn-debug", "syn-refactor", "syn-quick"];
 export type SkillName = (typeof SKILL_NAMES)[number];
 /**
  * IDs of command templates created by synarcx init.
  */
-export declare const COMMAND_IDS: readonly ["explore", "apply", "archive", "propose", "sync", "clarify", "analyze", "debug"];
+export declare const COMMAND_IDS: readonly ["explore", "apply", "archive", "propose", "sync", "clarify", "analyze", "debug", "refactor", "quick"];
 export type CommandId = (typeof COMMAND_IDS)[number];
 /**
  * Status of skill configuration for a tool.

package/dist/core/shared/tool-detection.js

@@ -18,6 +18,8 @@ export const SKILL_NAMES = [
     'syn-clarify',
     'syn-analyze',
     'syn-debug',
+    'syn-refactor',
+    'syn-quick',
 ];
 /**
  * IDs of command templates created by synarcx init.
@@ -31,6 +33,8 @@ export const COMMAND_IDS = [
     'clarify',
     'analyze',
     'debug',
+    'refactor',
+    'quick',
 ];
 /**
  * Gets the list of tools with skillsDir configured.

package/dist/core/templates/skill-templates.d.ts

@@ -12,4 +12,6 @@ export { getSynSyncSkillTemplate, getSynSyncCommandTemplate } from './workflows/
 export { getSynClarifySkillTemplate, getSynClarifyCommandTemplate } from './workflows/clarify.js';
 export { getSynAnalyzeSkillTemplate, getSynAnalyzeCommandTemplate } from './workflows/analyze.js';
 export { getSynDebugSkillTemplate, getSynDebugCommandTemplate } from './workflows/debug.js';
+export { getSynRefactorSkillTemplate, getSynRefactorCommandTemplate } from './workflows/refactor.js';
+export { getSynQuickSkillTemplate, getSynQuickCommandTemplate } from './workflows/quick.js';
 //# sourceMappingURL=skill-templates.d.ts.map

package/dist/core/templates/skill-templates.js

@@ -11,4 +11,6 @@ export { getSynSyncSkillTemplate, getSynSyncCommandTemplate } from './workflows/
 export { getSynClarifySkillTemplate, getSynClarifyCommandTemplate } from './workflows/clarify.js';
 export { getSynAnalyzeSkillTemplate, getSynAnalyzeCommandTemplate } from './workflows/analyze.js';
 export { getSynDebugSkillTemplate, getSynDebugCommandTemplate } from './workflows/debug.js';
+export { getSynRefactorSkillTemplate, getSynRefactorCommandTemplate } from './workflows/refactor.js';
+export { getSynQuickSkillTemplate, getSynQuickCommandTemplate } from './workflows/quick.js';
 //# sourceMappingURL=skill-templates.js.map

package/dist/core/templates/workflows/debug.js

@@ -1,8 +1,8 @@
 export function getSynDebugSkillTemplate() {
     return {
         name: 'syn-debug',
-        description: 'Investigate a known error or failure — root cause analysis, pattern recognition, and hypothesis formulation. Hands off to /syn:propose for task creation.',
-        instructions: `Investigate a known error or failure systematically in 3 phases. Produces a diagnosis and suggests \`/syn:propose\` for creating the fix change.
+        description: 'Investigate a known error or failure — root cause analysis, pattern recognition, and hypothesis formulation. Hands off explicitly to /syn:propose.',
+        instructions: `Investigate a known error or failure systematically in 3 phases. Produces a diagnosis and explicitly prompts the user to run \`/syn:propose\` — does NOT auto-create artifacts or auto-hand off.
 
 **Input**: Error message, symptom, or failure description. If no input provided, ask what went wrong.
 
@@ -47,7 +47,7 @@ Use that context to understand what was intended vs. what went wrong.
 
 ## Output
 
-After completing the 3-phase investigation, summarize:
+After completing the 3-phase investigation, present findings and prompt explicitly:
 
 \`\`\`
 ### Diagnosis
@@ -56,10 +56,10 @@ After completing the 3-phase investigation, summarize:
 **Pattern**: <similar issues or novel>
 **Hypothesis**: <proposed fix approach>
 
-**Next Step**: Ready to formalize a change? Run \`/syn:propose\` with these findings.
+**Ready to formalize?** Run \`/syn:propose\` to create a change with these findings.
 \`\`\`
 
-If no change exists yet, suggest creating one via \`/syn:propose\` with the diagnosis as the starting context.`,
+Do NOT create any artifacts, do NOT start the pipeline automatically. The user must explicitly run \`/syn:propose\` to formalize.`,
         license: 'MIT',
         compatibility: 'Requires synarcx CLI.',
         metadata: { author: 'synarcx', version: '0.1' },
@@ -68,7 +68,7 @@ If no change exists yet, suggest creating one via \`/syn:propose\` with the diag
 export function getSynDebugCommandTemplate() {
     return {
         name: 'syn:debug',
-        description: 'Investigate a known error — root cause analysis through hypothesis, suggests /syn:propose',
+        description: 'Investigate a known error — root cause analysis through hypothesis, explicitly prompts /syn:propose',
         category: 'Workflow',
         tags: ['workflow', 'debug', 'fix'],
         content: `Investigate a known error or failure systematically in 3 phases. Produces a diagnosis and suggests \`/syn:propose\` for creating the fix change.
@@ -111,7 +111,7 @@ If a change is active, read its artifacts first to understand what was intended
 
 ## Output
 
-After completing, summarize with a diagnosis and suggest \`/syn:propose\` with the findings.`
+After completing, present the diagnosis and explicitly prompt the user to run \`/syn:propose\` to formalize the fix. Do NOT auto-create artifacts.`
     };
 }
 //# sourceMappingURL=debug.js.map

package/dist/core/templates/workflows/quick.d.ts

@@ -0,0 +1,4 @@
+import type { SkillTemplate, CommandTemplate } from '../types.js';
+export declare function getSynQuickSkillTemplate(): SkillTemplate;
+export declare function getSynQuickCommandTemplate(): CommandTemplate;
+//# sourceMappingURL=quick.d.ts.map

package/dist/core/templates/workflows/quick.js

@@ -0,0 +1,129 @@
+export function getSynQuickSkillTemplate() {
+    return {
+        name: 'syn-quick',
+        description: 'Fast-path for small, low-risk changes — reads context, shows change inline, asks confirmation, applies. No artifacts created.',
+        instructions: `Apply a small, low-risk change directly — no proposal, no specs, no artifacts. Describes the change inline, asks the user to confirm, then applies after confirmation.
+
+**Input**: The user describes the change to make. If no description provided, ask what they want to change.
+
+---
+
+## Scope Check
+
+Before proceeding, evaluate whether the described change is small enough for the quick path:
+
+**Good for /syn:quick:**
+- Typo fixes
+- Single-line config changes
+- Renaming a variable or function (single file, no callers to update across modules)
+- Simple dependency version bump
+- One-off formatting fix
+- Small comment or documentation fix
+
+**Too large for /syn:quick (warn and suggest alternative):**
+- Multi-file changes
+- Changes that add new behavior or logic
+- Architectural or structural changes
+- Changes requiring design decisions
+- Refactoring that touches multiple modules
+- Any change that would normally warrant a proposal
+
+If the change description implies multi-file, new behavior, or architectural impact:
+1. Warn: "This looks too large for \`/syn:quick\`. Consider \`/syn:explore\` to think it through or \`/syn:propose\` to create a full change."
+2. If the user acknowledges and chooses to proceed anyway, continue with the quick apply.
+
+---
+
+## Read Context
+
+Read the relevant source files to understand current state.
+
+---
+
+## Show Change Inline
+
+Present the proposed change clearly:
+
+\`\`\`
+### Proposed Change
+
+**File**: path/to/file.ts
+**Current**: <existing code or content>
+**Proposed**: <modified code or content>
+**Reason**: <brief explanation>
+\`\`\`
+
+---
+
+## Ask Confirmation
+
+Use the AskUserQuestion tool to confirm:
+> "Apply this change?"
+
+Options: Yes (proceed), No (cancel).
+
+Apply only after explicit confirmation.
+
+---
+
+## Apply
+
+Make the change. Commit is optional based on user preference.
+
+---
+
+## Output
+
+After applying:
+- Summarize what was changed
+- Note that no synspec artifacts were created`,
+        license: 'MIT',
+        compatibility: 'Requires synarcx CLI.',
+        metadata: { author: 'synarcx', version: '0.1' },
+    };
+}
+export function getSynQuickCommandTemplate() {
+    return {
+        name: 'syn:quick',
+        description: 'Apply a small, low-risk change directly — no artifacts, inline preview, confirmation step',
+        category: 'Workflow',
+        tags: ['workflow', 'quick', 'fast'],
+        content: `Apply a small, low-risk change directly — no proposal, no specs, no artifacts. Describes the change inline, asks the user to confirm, then applies after confirmation.
+
+**Input**: The argument after \`/syn:quick\` describes the change to make.
+
+---
+
+## Scope Check
+
+- **Good for**: typo fixes, single-line config changes, renames (single file), dep bumps, minor formatting, comment fixes.
+- **Too large**: multi-file changes, new behavior, architectural changes, design decisions, multi-module refactoring.
+
+If too large → warn and suggest \`/syn:explore\` or \`/syn:propose\`. If user confirms anyway, proceed.
+
+---
+
+## Read Context
+
+Read the relevant source files to understand current state.
+
+---
+
+## Show Change Inline
+
+Present: file, current content, proposed content, reason.
+
+---
+
+## Ask Confirmation
+
+Ask "Apply this change?" with Yes/No options. Apply only after confirmation.
+
+---
+
+## Apply
+
+Make the change. No synspec artifacts are created.`
+    };
+}
+//# sourceMappingURL=quick.js.map

package/dist/core/templates/workflows/refactor.d.ts

@@ -0,0 +1,4 @@
+import type { SkillTemplate, CommandTemplate } from '../types.js';
+export declare function getSynRefactorSkillTemplate(): SkillTemplate;
+export declare function getSynRefactorCommandTemplate(): CommandTemplate;
+//# sourceMappingURL=refactor.d.ts.map

package/dist/core/templates/workflows/refactor.js

@@ -0,0 +1,126 @@
+export function getSynRefactorSkillTemplate() {
+    return {
+        name: 'syn-refactor',
+        description: 'Investigate structural changes that must not alter behavior. Entry point for refactoring — explores, then hands off to /syn:propose.',
+        instructions: `Investigate a structural refactoring opportunity. Focuses on improving code structure without changing observable behavior. When thinking is clear, explicitly prompts the user to run \`/syn:propose\` — does NOT auto-create artifacts.
+
+**Input**: The user can describe what they want to restructure, or just run the command to start exploring.
+
+---
+
+## Initial Context
+
+Check for existing context:
+\`\`\`bash
+synarcx list --json
+\`\`\`
+
+If a relevant change exists, read its artifacts. Otherwise, start fresh.
+
+---
+
+## Reframing the Problem
+
+This is a structural-change investigation. The goal is to improve code organization, reduce duplication, increase cohesion, or decrease coupling — without changing what the system does.
+
+### Opening Question
+
+Start by asking (use AskUserQuestion tool, open-ended):
+> "What part of the codebase feels like it needs restructuring?"
+
+Let the user describe the pain point before diving in.
+
+---
+
+## Investigation
+
+Explore the codebase to understand the current structure:
+
+1. **Map the current shape** — read relevant source files, identify:
+   - Module boundaries and responsibilities
+   - Dependency direction
+   - Code duplication or overlapping concerns
+   - Testing patterns
+
+2. **Identify the target shape** — work with the user to define:
+   - What the ideal structure would look like
+   - Which modules or files move where
+   - How dependencies should flow
+
+3. **Surface risks** — flag areas of concern:
+   - Implicit dependencies that aren't visible in imports
+   - Areas where refactoring could make things worse
+   - Testing hazards (brittle tests, high coupling to internals)
+
+4. **Visualize** — use ASCII diagrams to show:
+   - Current vs. target module structure
+   - Dependency direction changes
+   - File/move relationships
+
+---
+
+## Analyze-Gate Note (for the /syn:analyze phase)
+
+When a proposal is created from this investigation, the analyze phase MUST check:
+- Does the proposed change alter any public API signature?
+- Does it change output format, error messages, or user-facing behavior?
+- Does it add new functionality beyond what existed?
+
+If any of these is true → flag as a **behavior contract violation** and suggest reclassifying as a feature (not a refactor).
+
+---
+
+## Hand-Off
+
+When the investigation reaches a clear conclusion, present findings and explicitly prompt:
+
+\`\`\`
+### Refactoring Plan
+
+**Current Shape**: <summary of current structure>
+**Target Shape**: <proposed structure>
+**Key Changes**: <list of structural moves>
+**Risks**: <potential issues>
+
+**Ready to formalize?** Run \`/syn:propose\` to create a change with these findings.
+\`\`\`
+
+Do NOT create any artifacts or start the pipeline. The user must explicitly run \`/syn:propose\`.`,
+        license: 'MIT',
+        compatibility: 'Requires synarcx CLI.',
+        metadata: { author: 'synarcx', version: '0.1' },
+    };
+}
+export function getSynRefactorCommandTemplate() {
+    return {
+        name: 'syn:refactor',
+        description: 'Investigate structural refactoring — map current vs. target shape, then hands off to /syn:propose',
+        category: 'Workflow',
+        tags: ['workflow', 'refactor', 'restructure'],
+        content: `Investigate a structural refactoring opportunity. Focuses on improving code structure without changing observable behavior. When thinking is clear, explicitly prompts the user to run \`/syn:propose\` — does NOT auto-create artifacts.
+
+**Input**: The argument after \`/syn:refactor\` describes what the user wants to restructure.
+
+---
+
+## Investigation
+
+1. **Map the current shape** — read relevant source files, identify module boundaries, dependencies, duplication.
+2. **Identify the target shape** — define what the ideal structure looks like.
+3. **Surface risks** — flag implicit dependencies, testing hazards, areas that could get worse.
+4. **Visualize** — use ASCII diagrams to show current vs. target structure.
+
+---
+
+## Analyze-Gate Note
+
+When artifacts are created, the analyze phase MUST check for behavior contract violations — no public API changes, no output format changes, no new functionality. If violated, flag and suggest reclassifying as a feature.
+
+---
+
+## Hand-Off
+
+Present a summary with Current Shape, Target Shape, Key Changes, and Risks. Then explicitly prompt: "Ready to formalize? Run \`/syn:propose\` to create a change with these findings."`
+    };
+}
+//# sourceMappingURL=refactor.js.map

package/dist/core/templates/workflows/sync.js

@@ -1,38 +1,88 @@
 export function getSynSyncSkillTemplate() {
     return {
         name: 'syn-sync',
-        description: 'Auto-generate or update synspec/constitution.md from project files (README, AGENTS.md, package.json, src structure) with semver versioning and Sync Impact Report.',
-        instructions: `Generate or update the project constitution — a living document in \`synspec/constitution.md\` that captures the project's purpose, principles, tech stack, conventions, architecture, and decision log.
+        description: 'Generate or update synspec/constitution.md with README validation, supporting file scan, guardrail Q&A, and structured constitution generation.',
+        instructions: `Generate or update the project constitution — a living document in \`synspec/constitution.md\` that captures validated project context.
 
-**Input**: The user can specify a description of what to focus on, or just run the command to regenerate from sources.
+**Input**: The user can specify a focus area, or just run the command to proceed through the validation flow.
 
 ---
 
-## First Run
+## README Gate (Required)
 
-1. **Read project sources**
-   - \`README.md\` — project description, features, purpose
-   - \`AGENTS.md\` — AI agent conventions
-   - \`package.json\` — dependencies, scripts, metadata
-   - \`src/\` structure — code organization (top-level directories)
+Before any generation, the README MUST pass quality validation.
 
-2. **Generate \`synspec/constitution.md\`** with these sections:
-   - \`# Constitution: <project-name>\` — derived from package.json name
-   - \`Version: 0.1.0\`
-   - \`## Purpose\` — 2-3 sentences from README
-   - \`## Principles\` — key design principles inferred from codebase
-   - \`## Tech Stack\` — languages, frameworks, key dependencies
-   - \`## Conventions\` — code style, naming, patterns observed
-   - \`## Architecture\` — high-level structure overview
-   - \`## Decision Log\` — table with Date, Decision, Rationale
+1. **Check that README.md exists and is not empty.**
+   - If missing or blank → stop, output: "SYNC BLOCKED: README.md is missing or empty. Please write a README that describes what this project does and what problem it solves, then re-run \`/syn:sync\`."
+   - Do NOT write any files. Do NOT proceed.
 
-3. **Verify** the file was created at \`synspec/constitution.md\`
+2. **Check that README meaningfully describes the project.**
+   - A passing README must have both:
+     - At least one sentence describing what the project does
+     - At least one sentence describing the problem it solves or who it is for
+   - AI judges quality at runtime. Examples of THIN content that should fail:
+     - Only a title and install instructions
+     - Auto-generated placeholder text ("# My Project", "## Getting Started")
+     - Single-line descriptions with no substance
+   - If README is too thin → stop, output: "SYNC BLOCKED: README is too thin. A passing README must describe (1) what the project does and (2) what problem it solves, in at least one sentence each. Please update README.md and re-run \`/syn:sync\`."
+
+3. **If README passes**, proceed to the next phase.
+
+---
+
+## Supporting File Scan
+
+After README passes, read supporting project files for context:
+- \`AGENTS.md\` — AI agent conventions
+- \`package.json\` — dependencies, scripts, metadata
+- \`src/\` structure — code organization (top-level directories)
+- Any other notable config files (\`tsconfig.json\`, \`.eslintrc.*\`, etc.)
+
+Note what information is already well-covered by the README so guardrail questions avoid repeating it.
+
+---
+
+## Guardrail Q&A
+
+Generate up to 5 targeted questions. Each question should probe areas that CANNOT be reliably inferred from code or README alone:
+
+| Topic Area | Example Question |
+|------------|-----------------|
+| Off-limits areas | "Are there any parts of the codebase AI should never modify?" |
+| Hard constraints | "Are there compliance, security, or infrastructure constraints?" |
+| Coding rules | "Are there coding conventions not obvious from the code?" |
+| Out-of-scope | "What is explicitly out of scope for this project right now?" |
+| Dependencies | "Are there any planned or pending dependency changes?" |
+
+**Rules:**
+- Adapt questions to the project's stack, structure, and domain — don't ask generic questions that don't apply
+- Skip questions already answered by the README, AGENTS.md, or other supporting files
+- Maximum 5 questions per session
+- Ask one at a time using the AskUserQuestion tool, wait for each answer
+
+---
+
+## Constitution Generation
+
+With README validated, supporting files scanned, and Q&A answers collected, generate \`synspec/constitution.md\` with these sections:
+
+1. **\`# Constitution: <project-name>\`** — derived from package.json name, with Version field
+2. **\`## Purpose\`** — 2-3 sentences synthesized from README
+3. **\`## Principles\`** — key design principles inferred from codebase and Q&A
+4. **\`## Tech Stack\`** — languages, frameworks, key dependencies from package.json
+5. **\`## Constraints\`** — from Q&A answers: hard constraints, compliance, infra limits
+6. **\`## Off-Limits\`** — from Q&A answers: areas AI must not touch, out-of-scope items
+7. **\`## Conventions\`** — code style, naming, patterns observed from code and AGENTS.md
+8. **\`## Architecture\`** — high-level structure overview from src/ scan
+9. **\`## Decision Log\`** — table with Date, Decision, Rationale (append-only)
+
+**The Constraints and Off-Limits sections MUST be written from Q&A answers, not inferred from docs.**
 
 ---
 
 ## Re-run (Update)
 
-When re-run, offer a semver bump choice:
+When re-run and \`synspec/constitution.md\` already exists, still run the README gate — README may have degraded since last sync. Offer a semver bump choice:
 - **MAJOR** — constitution structure changed or reorganized
 - **MINOR** — new section added
 - **PATCH** — content update, typo fixes
@@ -46,7 +96,7 @@ Append a Sync Impact Report as an HTML comment at the top:
 
 ## Output
 
-After completion, summarize what was created or updated, and note the version.`,
+After completion, summarize what was created or updated, note the version, and list how many Q&A questions were answered.`,
         license: 'MIT',
         compatibility: 'Requires synarcx CLI.',
         metadata: { author: 'synarcx', version: '0.1' },
@@ -55,54 +105,61 @@ After completion, summarize what was created or updated, and note the version.`,
 export function getSynSyncCommandTemplate() {
     return {
         name: 'syn:sync',
-        description: 'Auto-generate or update synspec/constitution.md from project files',
+        description: 'Generate/update project constitution with README validation, guardrail Q&A, and constraint capture',
         category: 'Workflow',
         tags: ['workflow', 'sync', 'project'],
-        content: `Generate or update the project constitution — a living document in \`synspec/constitution.md\` that captures the project's purpose, principles, tech stack, conventions, architecture, and decision log.
+        content: `Generate or update the project constitution — a living document in \`synspec/constitution.md\` that captures validated project context.
 
-**Input**: The user can specify a description of what to focus on, or just run the command to regenerate from sources.
+**Input**: The user can specify a focus area, or just run the command to proceed through the validation flow.
 
 ---
 
-## First Run
+## README Gate (Required)
 
-1. **Read project sources**
-   - \`README.md\` — project description, features, purpose
-   - \`AGENTS.md\` — AI agent conventions
-   - \`package.json\` — dependencies, scripts, metadata
-   - \`src/\` structure — code organization (top-level directories)
+Before any generation, the README MUST pass quality validation.
 
-2. **Generate \`synspec/constitution.md\`** with these sections:
-   - \`# Constitution: <project-name>\` — derived from package.json name
-   - \`Version: 0.1.0\`
-   - \`## Purpose\` — 2-3 sentences from README
-   - \`## Principles\` — key design principles inferred from codebase
-   - \`## Tech Stack\` — languages, frameworks, key dependencies
-   - \`## Conventions\` — code style, naming, patterns observed
-   - \`## Architecture\` — high-level structure overview
-   - \`## Decision Log\` — table with Date, Decision, Rationale
+1. **Check that README.md exists and is not empty.**
+   - If missing or blank → stop with message explaining README must exist and describe the project.
+   - Do NOT write any files.
 
-3. **Verify** the file was created at \`synspec/constitution.md\`
+2. **Check that README meaningfully describes the project.**
+   - A passing README must have both: (1) what the project does, (2) what problem it solves.
+   - AI judges quality at runtime.
+   - If too thin → stop with message explaining what's needed.
+
+3. **If README passes**, proceed.
 
 ---
 
-## Re-run (Update)
+## Supporting File Scan
 
-When re-run, offer a semver bump choice:
-- **MAJOR** — constitution structure changed or reorganized
-- **MINOR** — new section added
-- **PATCH** — content update, typo fixes
+Read AGENTS.md, package.json, src/ structure, and other notable config files. Note what's already covered by README to avoid redundant questions.
 
-Append a Sync Impact Report as an HTML comment at the top:
-\`\`\`
-<!-- Sync Impact: MAJOR — constitution structure reorganized -->
-\`\`\`
+---
+
+## Guardrail Q&A
+
+Generate up to 5 targeted questions about off-limits areas, hard constraints, coding rules, out-of-scope items, and dependency plans. Adapt to the project's stack and domain. Skip questions already answered by README or supporting files.
+
+---
+
+## Constitution Generation
+
+Generate \`synspec/constitution.md\` with sections: Purpose, Principles, Tech Stack, Constraints (from Q&A), Off-Limits (from Q&A), Conventions, Architecture, Decision Log.
+
+**Constraints and Off-Limits MUST come from Q&A answers, not inferred.**
+
+---
+
+## Re-run (Update)
+
+Still run the README gate even when constitution exists — README may have degraded. Offer semver bump. Append Sync Impact Report HTML comment.
 
 ---
 
 ## Output
 
-After completion, summarize what was created or updated, and note the version.`
+Summarize what was created/updated, note the version, and show how many Q&A questions were answered.`
     };
 }
 //# sourceMappingURL=sync.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synarcx",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SynArcX — Synapse Architecture Code Extension. Spec-driven development workflow for AI coding agents.",
   "keywords": [
     "synarcx",