spec-feature 1.1.3 → 1.1.5

package/README.md

@@ -40,23 +40,25 @@ npx spec-feature view <feature-slug> --folder my-docs
 
 ```mermaid
 graph TD
-    A[spec/] --> B[README.md]
-    A --> C[feature.md]
-    A --> D[core/]
-    A --> E[features/]
-    A --> F[constitution/]
+    spec_root[spec/] --> readme[README.md]
+    spec_root --> feature_template[feature.md]
+    spec_root --> core_dir[core/]
+    spec_root --> features_dir[features/]
+    spec_root --> constitution_dir[constitution/]
     
-    D --> G[spec.md]
-    D --> H[plan.md]
-    D --> I[tasks.md]
-    D --> J[verify.md]
-    D --> K[hotfix.md]
+    core_dir --> core_spec[spec.md]
+    core_dir --> core_plan[plan.md]
+    core_dir --> core_tasks[tasks.md]
+    core_dir --> core_clarifications[clarifications.md]
+    core_dir --> core_verify[verify.md]
+    core_dir --> core_hotfix[hotfix.md]
     
-    E --> L[user-auth/]
-    L --> M[spec.md]
-    L --> N[plan.md]
-    L --> O[tasks.md]
-    L --> P[verify-report.md]
+    features_dir --> feat[user-auth/]
+    feat --> feat_spec[spec.md]
+    feat --> feat_plan[plan.md]
+    feat --> feat_tasks[tasks.md]
+    feat --> feat_clarifications[clarifications.md]
+    feat --> feat_verify[verify-report.md]
 ```
 
 **Templates** (core/) → **Features** (features/)
@@ -79,13 +81,14 @@ Use the template from spec/feature.md.
 #feature-name# Your description here
 ```
 
-Format: `#feature# description` → creates `spec/features/feature-name/` with 3 files:
+Format: `#feature# description` → creates `spec/features/feature-name/` with up to 4 files (adds `clarifications.md` when needed):
 
 ```mermaid
 flowchart LR
     A[feature.md template] --> B[spec.md]
     A --> C[plan.md]
     A --> D[tasks.md]
+    A --> E[clarifications.md]
 ```
 
 ### 2️⃣ Execute Tasks

package/bin/cli.js

@@ -73,9 +73,9 @@ The \`spec/\` directory is generated by running \`npx spec-feature init\` in the
 
 ### Structure
 
-- \`spec/core/\` — templates: \`spec.md\`, \`plan.md\`, \`tasks.md\`, \`verify.md\`, \`hotfix.md\`
+- \`spec/core/\` — templates: \`spec.md\`, \`plan.md\`, \`tasks.md\`, \`clarifications.md\`, \`verify.md\`, \`hotfix.md\`
 - \`spec/feature.md\` — unified prompt template to create/update a feature
-- \`spec/features/<feature>/{spec.md,plan.md,tasks.md}\` — generated feature artifacts
+- \`spec/features/<feature>/{spec.md,plan.md,tasks.md,clarifications.md}\` — generated feature artifacts
 - \`spec/features/<feature>/verify-report.md\` — verification output (after tasks / manual verify)
 
 ### Create or update a feature
@@ -84,7 +84,7 @@ Use the template from \`spec/feature.md\` and provide input as:
 
 \`#<feature># <context>\`
 
-Result: create/update the folder \`spec/features/<feature>/\` and produce \`spec.md\` → \`plan.md\` → \`tasks.md\`.
+Result: create/update the folder \`spec/features/<feature>/\` and produce \`clarifications.md\` (if needed) → \`spec.md\` → \`plan.md\` → \`tasks.md\`.
 
 ### Execute tasks
 
@@ -312,7 +312,7 @@ function readFeatures(featuresRoot) {
     .map(dirent => {
       const featureId = dirent.name;
       const featurePath = path.join(featuresRoot, featureId);
-      const files = ["spec.md", "plan.md", "tasks.md", "verify-report.md"]
+      const files = ["spec.md", "plan.md", "tasks.md", "clarifications.md", "verify-report.md"]
         .filter(name => fs.existsSync(path.join(featurePath, name)))
         .map(name => {
           const content = fs.readFileSync(path.join(featurePath, name), "utf8");
@@ -322,6 +322,8 @@ function readFeatures(featuresRoot) {
               ? "plan"
               : name.startsWith("tasks")
                 ? "tasks"
+                : name.startsWith("clarifications")
+                  ? "clarifications"
                 : "verify";
           return {
             id: type,
@@ -358,6 +360,7 @@ function describeFile(type) {
   if (type === "spec") return "Specification";
   if (type === "plan") return "Plan";
   if (type === "tasks") return "Tasks";
+  if (type === "clarifications") return "Clarifications";
   if (type === "verify") return "Verify report";
   return "Document";
 }

package/bin/viewer.html

@@ -73,6 +73,7 @@
         const FolderGit = (p) => <IconBase {...p}><path d="M4 20h16a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.93a2 2 0 0 1-1.66-.9l-.82-1.2A2 2 0 0 0 7.93 2H4a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2Z"/><circle cx="12" cy="13" r="2"/><path d="M12 10v1"/><path d="M12 15v2"/></IconBase>;
         const Sun = (p) => <IconBase {...p}><circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/></IconBase>;
         const Moon = (p) => <IconBase {...p}><path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"/></IconBase>;
+        const HelpCircle = (p) => <IconBase {...p}><circle cx="12" cy="12" r="10"/><path d="M9.09 9a3 3 0 0 1 5.82 1c0 2-3 2-3 4"/><circle cx="12" cy="17" r="1"/></IconBase>;
 
         // --- DATA FETCHING ---
         const fetchFeatures = async () => {
@@ -116,6 +117,124 @@
             </div>
         );
 
+        const renderFormattedText = (text) => {
+            if (!text || typeof text !== 'string') return text;
+            
+            const parts = [];
+            let keyCounter = 0;
+            let lastIndex = 0;
+            
+            // Find all matches (code and bold) with their positions
+            const matches = [];
+            
+            // Find inline code matches - matches `text` but not `` (empty backticks)
+            // Pattern: backtick, one or more non-backtick characters, backtick
+            const codeRegex = /`([^`]+)`/g;
+            let match;
+            while ((match = codeRegex.exec(text)) !== null) {
+                // Only add non-empty matches (at least one character between backticks)
+                if (match[1] && match[1].length > 0) {
+                    matches.push({
+                        start: match.index,
+                        end: match.index + match[0].length,
+                        content: match[1],
+                        type: 'code'
+                    });
+                }
+            }
+            
+            // Find bold text matches - matches **text**
+            // Pattern: **, one or more non-asterisk characters (non-greedy), **
+            // This handles: **bold**, but not *** or ** (empty) or **bold*text** (nested asterisks)
+            const boldRegex = /\*\*([^*]+?)\*\*/g;
+            while ((match = boldRegex.exec(text)) !== null) {
+                // Only add non-empty matches (at least one character between **)
+                if (match[1] && match[1].length > 0) {
+                    matches.push({
+                        start: match.index,
+                        end: match.index + match[0].length,
+                        content: match[1],
+                        type: 'bold'
+                    });
+                }
+            }
+            
+            // If no matches found, return original text
+            if (matches.length === 0) {
+                return text;
+            }
+            
+            // Sort matches by position
+            matches.sort((a, b) => a.start - b.start);
+            
+            // Remove overlapping matches (prioritize code over bold)
+            // First pass: mark overlapping matches for removal
+            const toRemove = new Set();
+            for (let i = 0; i < matches.length; i++) {
+                if (toRemove.has(i)) continue;
+                const current = matches[i];
+                for (let j = i + 1; j < matches.length; j++) {
+                    if (toRemove.has(j)) continue;
+                    const other = matches[j];
+                    // Check if matches overlap
+                    if (current.start < other.end && current.end > other.start) {
+                        // Prioritize code over bold
+                        if (current.type === 'code' && other.type === 'bold') {
+                            toRemove.add(j);
+                        } else if (current.type === 'bold' && other.type === 'code') {
+                            toRemove.add(i);
+                            break; // Current is removed, no need to check further
+                        } else {
+                            // Same type overlapping - keep the first one
+                            toRemove.add(j);
+                        }
+                    }
+                }
+            }
+            
+            // Filter out removed matches
+            const filteredMatches = matches.filter((_, index) => !toRemove.has(index));
+            
+            // Build result array
+            filteredMatches.forEach(match => {
+                // Add text before match (handles case when match is at start of string)
+                if (match.start > lastIndex) {
+                    const beforeText = text.substring(lastIndex, match.start);
+                    if (beforeText) {
+                        parts.push(beforeText);
+                    }
+                }
+                
+                // Add formatted match (always add, even if content is empty to preserve structure)
+                if (match.type === 'code') {
+                    parts.push(
+                        <code key={keyCounter++} className="px-1.5 py-0.5 bg-slate-100 dark:bg-slate-700 text-slate-800 dark:text-slate-200 rounded text-sm font-mono">
+                            {match.content}
+                        </code>
+                    );
+                } else if (match.type === 'bold') {
+                    parts.push(
+                        <strong key={keyCounter++} className="font-semibold text-slate-900 dark:text-slate-100">
+                            {match.content}
+                        </strong>
+                    );
+                }
+                
+                lastIndex = match.end;
+            });
+            
+            // Add remaining text (handles case when match is at end of string)
+            if (lastIndex < text.length) {
+                const remainingText = text.substring(lastIndex);
+                if (remainingText) {
+                    parts.push(remainingText);
+                }
+            }
+            
+            // Return formatted parts or original text if something went wrong
+            return parts.length > 0 ? parts : text;
+        };
+
         const renderBoldText = (text) => {
             const parts = text.split('**');
             return parts.map((part, idx) => 
@@ -124,10 +243,10 @@
         };
 
         const LinkRenderer = ({ text, onNavigate }) => {
-            const fileRegex = /(spec\.md|plan\.md|tasks\.md|verify-report\.md)/g;
+            const fileRegex = /(spec\.md|plan\.md|tasks\.md|clarifications\.md|verify-report\.md)/g;
             const parts = text.split(fileRegex);
             if (parts.length === 1) {
-                return <span className="text-slate-600 dark:text-slate-400">{renderBoldText(text)}</span>;
+                return <span className="text-slate-600 dark:text-slate-400">{renderFormattedText(text)}</span>;
             }
             return (
                 <span className="text-slate-600 dark:text-slate-400">
@@ -136,6 +255,7 @@
                             let targetId = 'spec';
                             if (part.includes('plan')) targetId = 'plan';
                             if (part.includes('tasks')) targetId = 'tasks';
+                            if (part.includes('clarifications')) targetId = 'clarifications';
                             if (part.includes('verify')) targetId = 'verify';
                             return (
                                 <button key={i} onClick={() => onNavigate(targetId)} className="inline-flex items-center gap-0.5 px-1.5 py-0.5 -my-1 mx-0.5 text-blue-600 dark:text-blue-400 bg-blue-50 dark:bg-blue-900/30 hover:bg-blue-100 dark:hover:bg-blue-900/50 rounded text-sm font-medium transition-colors cursor-pointer" title={`Go to ${part}`}>
@@ -143,7 +263,7 @@
                                 </button>
                             );
                         }
-                        return renderBoldText(part);
+                        return renderFormattedText(part);
                     })}
                 </span>
             );
@@ -174,15 +294,15 @@
                 if (inCodeBlock) { codeBlockContent.push(line); continue; }
                 if (line.startsWith('# ')) {
                     const h1Text = line.replace('# ', '');
-                    renderLines.push(<h1 key={i} className="text-2xl font-bold text-slate-900 dark:text-slate-100 mb-6 pb-2 border-b border-slate-200 dark:border-slate-700">{renderBoldText(h1Text)}</h1>);
+                    renderLines.push(<h1 key={i} className="text-2xl font-bold text-slate-900 dark:text-slate-100 mb-6 pb-2 border-b border-slate-200 dark:border-slate-700">{renderFormattedText(h1Text)}</h1>);
                 }
                 else if (line.startsWith('## ')) {
                     const h2Text = line.replace('## ', '');
-                    renderLines.push(<h2 key={i} className="text-lg font-bold text-slate-800 dark:text-slate-200 mt-8 mb-3 flex items-center gap-2">{renderBoldText(h2Text)}</h2>);
+                    renderLines.push(<h2 key={i} className="text-lg font-bold text-slate-800 dark:text-slate-200 mt-8 mb-3 flex items-center gap-2">{renderFormattedText(h2Text)}</h2>);
                 }
                 else if (line.startsWith('### ')) {
                     const h3Text = line.replace('### ', '');
-                    renderLines.push(<h3 key={i} className="text-md font-semibold text-slate-700 dark:text-slate-300 mt-6 mb-2">{renderBoldText(h3Text)}</h3>);
+                    renderLines.push(<h3 key={i} className="text-md font-semibold text-slate-700 dark:text-slate-300 mt-6 mb-2">{renderFormattedText(h3Text)}</h3>);
                 }
                 else if (line.trim().startsWith('- [ ]') || line.trim().startsWith('- [x]')) {
                     const isChecked = line.trim().startsWith('- [x]');
@@ -193,7 +313,7 @@
                                 {isChecked && <Check size={12} strokeWidth={3} />}
                             </div>
                             <span className={`${isChecked ? 'text-slate-400 dark:text-slate-500 line-through' : 'text-slate-700 dark:text-slate-300'}`}>
-                                {renderBoldText(text)}
+                                {renderFormattedText(text)}
                             </span>
                         </div>
                     );
@@ -202,7 +322,7 @@
                     const listText = line.replace('- ', '');
                     renderLines.push(
                         <li key={i} className="ml-5 list-disc text-slate-700 dark:text-slate-300 pl-1">
-                            {renderBoldText(listText)}
+                            {renderFormattedText(listText)}
                         </li>
                     );
                 }
@@ -212,7 +332,7 @@
                         renderLines.push(
                             <div key={i} className="ml-5 text-slate-700 dark:text-slate-300 flex gap-2">
                                 <span className="font-mono text-slate-400 dark:text-slate-500 font-bold w-4 text-right">{numMatch[1]}.</span>
-                                <span>{renderBoldText(numMatch[2])}</span>
+                                <span>{renderFormattedText(numMatch[2])}</span>
                             </div>
                         );
                     }
@@ -228,6 +348,7 @@
                 case 'spec': return <BookOpen size={18} className="text-blue-600" />;
                 case 'plan': return <MapIcon size={18} className="text-amber-500" />;
                 case 'tasks': return <ListTodo size={18} className="text-emerald-500" />;
+                case 'clarifications': return <HelpCircle size={18} className="text-cyan-500" />;
                 case 'verify': return <ShieldCheck size={18} className="text-purple-500" />;
                 default: return <FileText size={18} className="text-slate-400" />;
             }
@@ -287,6 +408,26 @@
             );
         };
 
+        const PreviewText = ({ content, maxLength = 150 }) => {
+            if (!content) return <span>No description</span>;
+            
+            // Extract first paragraph, remove headers and code blocks
+            const lines = content.split('\n');
+            let previewText = '';
+            for (let i = 0; i < lines.length && previewText.length < maxLength; i++) {
+                const line = lines[i].trim();
+                if (line && !line.startsWith('#') && !line.startsWith('```') && !line.startsWith('- [') && !line.startsWith('- ')) {
+                    previewText += (previewText ? ' ' : '') + line;
+                }
+            }
+            
+            if (previewText.length > maxLength) {
+                previewText = previewText.substring(0, maxLength) + '...';
+            }
+            
+            return <span>{renderFormattedText(previewText || 'No description')}</span>;
+        };
+
         const Dashboard = ({ features, onSelectFeature }) => {
             return (
                 <div className="p-8 max-w-6xl mx-auto">
@@ -304,6 +445,7 @@
                         <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
                             {features.map(feature => {
                                 const progress = calculateProgress(feature.files);
+                                const specFile = feature.files.find(f => f.type === 'spec');
                                 return (
                                     <div key={feature.id} onClick={() => onSelectFeature(feature.id)} 
                                          className="bg-white dark:bg-slate-800 border border-slate-200 dark:border-slate-700 rounded-xl p-5 shadow-sm hover:shadow-md hover:border-blue-300 dark:hover:border-blue-600 transition-all cursor-pointer group flex flex-col h-full">
@@ -317,7 +459,7 @@
                                         
                                         <div className="flex-1">
                                             <p className="text-xs text-slate-500 dark:text-slate-400 mb-4 line-clamp-2">
-                                                {feature.files.find(f => f.type === 'spec')?.content.slice(0, 100).replace(/#/g, '') || 'No description'}...
+                                                <PreviewText content={specFile?.content} maxLength={150} />
                                             </p>
                                         </div>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-feature",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "bin": {
     "spec-feature": "./bin/cli.js"
   },
@@ -11,6 +11,7 @@
     "feature",
     "sdd",
     "ai",
-    "llm"
+    "llm",
+    "cli"
   ]
 }

package/spec/constitution/03-questions-and-unknowns.md

@@ -7,14 +7,16 @@
   - success criteria are unclear,
   - there are multiple valid implementations with different tradeoffs,
   - actions would be destructive or expensive.
+- MUST write all clarifying questions to `spec/features/{FEATURE}/clarifications.md` (within the feature folder). Do not embed questions in `spec.md`, `plan.md`, `tasks.md`, or chat messages.
 - MUST prefer 1–2 high-impact questions over a long questionnaire.
 - MUST propose sensible defaults as options (without executing them unless confirmed).
-- MUST stop and wait if the missing information blocks a correct implementation.
+- MUST stop and wait if the missing information blocks a correct implementation. In this case, create/update `spec/features/{FEATURE}/clarifications.md` and do not proceed with generating/updating other artifacts until answers are provided.
 
 ## How to verify
 
 - Ambiguous inputs always produce clarifying questions and a short list of options.
 - Blocking unknowns are not silently assumed.
+- Questions are present in `spec/features/{FEATURE}/clarifications.md` and not duplicated elsewhere.
 
 ## Exceptions
 

package/spec/constitution/06-spec-feature-workflow-guardrails.md

@@ -4,9 +4,9 @@
 
 - MUST keep all spec-feature artifacts under `spec/`.
 - MUST follow the sequence:
-  - specification (`spec.md`) → plan (`plan.md`) → tasks (`tasks.md`) → execution → verification (`verify-report.md`).
+  - clarifications (`clarifications.md`, if needed) → specification (`spec.md`) → plan (`plan.md`) → tasks (`tasks.md`) → execution → verification (`verify-report.md`).
 - MUST NOT execute implementation tasks unless the user explicitly requests execution and references `spec/features/{FEATURE}/tasks.md`.
-- MUST keep `spec.md`, `plan.md`, and `tasks.md` consistent (terms, components, constraints).
+- MUST keep `spec.md`, `plan.md`, `tasks.md`, and `clarifications.md` consistent (terms, components, constraints, decisions).
 - MUST update `tasks.md` checkboxes to reflect actual state during verification.
 - SHOULD update the constitution when a feature introduces a new invariant or process rule.
 

package/spec/core/clarifications.md

@@ -0,0 +1,47 @@
+<!-- spec-feature: clarifications -->
+
+Template collects all clarifying questions for a feature in the **spec-feature** process.
+
+**Parameters**
+
+- **FEATURE** — name of the folder where the clarifications will be saved. Taken from the value between the first two `#` symbols (e.g., `#payments#` → `payments`).
+- **CONTEXT** — main context that triggered the questions. Consider everything after the second `#` in the parameter line; context can span multiple lines.
+
+**General rules**
+
+- Before doing anything, read and follow `spec/constitution/*`.
+- Work only with specification files within `/spec` directory: automatically create necessary directories and files.
+- Do not generate application code, configuration snippets, scripts, or patches while preparing clarifications.
+- All clarifying questions MUST be written to `spec/features/{FEATURE}/clarifications.md` (this file) and MUST NOT be embedded in `spec.md`, `plan.md`, `tasks.md`, or chat messages.
+- Prefer 1–2 high-impact questions over a long questionnaire; provide options/defaults when possible.
+- If the missing information blocks correct planning/specification, create/update this file and stop. Do not proceed to generate/update `spec.md`, `plan.md`, or `tasks.md` until answers are provided.
+
+**Steps**
+
+1. Create the directory structure `spec/features/{FEATURE}/` if it doesn't exist.
+2. Create/update the file `spec/features/{FEATURE}/clarifications.md` using the template below:
+   - Add new questions at the end.
+   - Keep previously answered questions and do not overwrite user answers.
+3. Ensure the document is valid Markdown and contains no placeholders.
+
+**Result template**
+
+```md
+# Clarifications — {FEATURE}
+
+**Context:** {CONTEXT}
+
+## Open questions
+
+| # | Question | Options / suggested default | User answer | Status |
+|---|----------|----------------------------|------------|--------|
+| 1 | <question> | <options or default> | <fill in> | open |
+
+## Resolved decisions
+
+| # | Decision | Rationale | Source question |
+|---|----------|-----------|-----------------|
+| 1 | <decision> | <why> | #1 |
+```
+
+Write strictly in Markdown and automatically create/update the clarifications file. **Goal** — create/update file `/spec/features/{FEATURE}/clarifications.md` to capture all clarifying questions and user answers for this feature.

package/spec/core/hotfix.md

@@ -23,6 +23,7 @@ Template automates feature maintenance after release: records hotfixes and synch
 
 - `spec.md` — update sections affected by the hotfix: clarify user scenarios, rules, or non-functional requirements, add new Assumptions when open questions arise.
 - `plan.md` — adjust technical solutions: data sources, contracts, architectural constraints, and risks, so the plan reflects the current feature structure.
+- `clarifications.md` — if `spec/features/{FEATURE}/clarifications.md` already exists and the hotfix introduces new open questions, append them there (do not overwrite user answers). If it does not exist, record open questions as assumptions in `spec.md` (this template forbids creating new files).
 - `tasks.md` —
   - Add new checkboxes for work required by the hotfix, group them in appropriate sections. Names should start with prefix `hotfix_<date>` in `YYYY-MM-DD` format.
   - Update statuses of existing tasks (`[ ]`/`[x]`), considering actual execution and hotfix results.

package/spec/core/plan.md

@@ -10,11 +10,14 @@ Template helps format the feature implementation plan in the **spec-feature** pr
 **General rules**
 
 - Before doing anything, read and follow `spec/constitution/*`.
-- If information is missing, write `No data — needs clarification: <what exactly>` and do not guess.
+- If information is missing:
+  - add a clarifying question to `spec/features/{FEATURE}/clarifications.md` (use `spec/core/clarifications.md` as a template),
+  - in this document, write `No data — needs clarification (see clarifications.md: #<n>)`,
+  - do not guess.
 - Work only with specification files within `/spec` directory: automatically create necessary directories and files.
 - Do not generate application code, configuration snippets, scripts, or patches while preparing the implementation plan.
 - Use `spec/core/spec.md` as the specification source on which the plan is formed.
-- Use `spec/features/{FEATURE}/spec.md` as additional context. If the file is unavailable, continue working based on **CONTEXT**.
+- Use `spec/features/{FEATURE}/spec.md` and `spec/features/{FEATURE}/clarifications.md` (resolved answers/decisions) as additional context. If files are unavailable, continue working based on **CONTEXT**.
 - Substitute specific values instead of placeholders (`{FEATURE}`, `{CONTEXT}`, etc.). If a section is not applicable — explicitly write `Not required — reason: <explanation>`.
 - Form meaningful paragraphs or lists: do not leave empty headers, hint comments, and `...` markers.
 - Follow basic software development principles: KISS, DRY, and YAGNI, so solutions remain simple, without duplication and unnecessary logic.
@@ -26,15 +29,16 @@ Template helps format the feature implementation plan in the **spec-feature** pr
 - `## Contracts and interfaces` — public APIs, events, queues, UI/CLI, error formats, and validation expectations.
 - `## Architecture / Components` — services, modules, integrations, constraints, and chosen stack (DB, API, UI, queues, background processes, etc.).
 - `## Risks` — potential problems and mitigation methods.
-- `## Assumptions` — explicit assumptions and missing information.
+- `## Assumptions` — explicit assumptions and open dependencies. Do not embed clarifying questions here; link to `clarifications.md` if any.
 
 **Steps**
 
 1. Create the directory structure `spec/features/{FEATURE}/` if it doesn't exist.
-2. Form the plan according to the sections above, based on **CONTEXT** and available additional context. For each section, fix what exactly needs to be done, not just list components.
-3. Create/update the file `spec/features/{FEATURE}/plan.md` with the complete plan content.
-4. Check that the document contains no unfilled placeholders and that the output is formatted in valid Markdown.
-5. Ensure the document is complete and ready for implementation.
+2. If any clarifying questions are needed, create/update `spec/features/{FEATURE}/clarifications.md` using `spec/core/clarifications.md` and stop if unanswered questions block correct planning.
+3. Form the plan according to the sections above, based on **CONTEXT** and available additional context. For each section, fix what exactly needs to be done, not just list components.
+4. Create/update the file `spec/features/{FEATURE}/plan.md` with the complete plan content.
+5. Check that the document contains no unfilled placeholders and that the output is formatted in valid Markdown.
+6. Ensure the document is complete and ready for implementation.
 
 **Result template**
 

package/spec/core/spec.md

@@ -10,7 +10,10 @@ Template helps describe a feature before implementation in the **spec-feature**
 **General rules**
 
 - Before doing anything, read and follow `spec/constitution/*`.
-- If information is missing, write `No data — needs clarification: <what exactly>` and do not guess.
+- If information is missing:
+  - add a clarifying question to `spec/features/{FEATURE}/clarifications.md` (use `spec/core/clarifications.md` as a template),
+  - in this document, write `No data — needs clarification (see clarifications.md: #<n>)`,
+  - do not guess.
 - Work only with specification files within `/spec` directory: automatically create necessary directories and files.
 - Do not generate application code, configuration snippets, scripts, or patches while preparing the specification.
 - Substitute specific values instead of placeholders (`{FEATURE}`, `{CONTEXT}`, etc.). The final document should not contain hints, examples, or `...` markers.
@@ -24,15 +27,16 @@ Template helps describe a feature before implementation in the **spec-feature**
 - `## User Stories` — minimum three completed stories. For each, fix the role, action, and result/value.
 - `## Main scenarios and rules` — key usage scenarios, constraints, error variants.
 - `## Non-functional requirements` — SLA, performance, security, localization, accessibility, and other non-functional criteria.
-- `## Assumptions` — explicit assumptions and questions that need clarification before development.
+- `## Assumptions` — explicit assumptions and open dependencies. Do not embed clarifying questions here; link to `clarifications.md` if any.
 
 **Steps**
 
 1. Create the directory structure `spec/features/{FEATURE}/` if it doesn't exist.
-2. Form the specification according to the sections above, based on **CONTEXT** and available additional context.
-3. Create/update the file `spec/features/{FEATURE}/spec.md` with the complete specification content.
-4. Check that the document is formatted in Markdown and contains no unfilled placeholders.
-5. Ensure the document is complete and ready for implementation.
+2. If any clarifying questions are needed, create/update `spec/features/{FEATURE}/clarifications.md` using `spec/core/clarifications.md`.
+3. Form the specification according to the sections above, based on **CONTEXT** and available additional context (including clarified answers, if present).
+4. Create/update the file `spec/features/{FEATURE}/spec.md` with the complete specification content.
+5. Check that the document is formatted in Markdown and contains no unfilled placeholders.
+6. Ensure the document is complete and ready for implementation.
 
 **Result template**
 

package/spec/core/tasks.md

@@ -10,11 +10,14 @@ Template helps form a task list for feature implementation in the **spec-feature
 **General rules**
 
 - Before doing anything, read and follow `spec/constitution/*`.
-- If information is missing, write `No data — needs clarification: <what exactly>` and do not guess.
+- If information is missing:
+  - add a clarifying question to `spec/features/{FEATURE}/clarifications.md` (use `spec/core/clarifications.md` as a template),
+  - in this document, write `No data — needs clarification (see clarifications.md: #<n>)`,
+  - do not guess.
 - Work only with specification files within `/spec` directory: automatically create necessary directories and files.
 - Do not generate application code, configuration snippets, scripts, or patches while preparing the task list.
 - Use `spec/core/spec.md` and `spec/core/plan.md` as base sources of specification and plan when preparing tasks.
-- Use `spec/features/{FEATURE}/spec.md` and `spec/features/{FEATURE}/plan.md` as additional context. If any file is missing, continue working based on available materials and **CONTEXT**.
+- Use `spec/features/{FEATURE}/spec.md`, `spec/features/{FEATURE}/plan.md`, and `spec/features/{FEATURE}/clarifications.md` (resolved answers/decisions) as additional context. If any file is missing, continue working based on available materials and **CONTEXT**.
 - Substitute specific values instead of placeholders (`{FEATURE}`, `{CONTEXT}`, etc.). The final document should not contain hints, examples, or `...` markers.
 - Each task is a checkbox with result formulation and description of mandatory checks/tests.
 - If a direction is not required, explicitly indicate under the corresponding subheading `Not required — reason: <explanation>`.
@@ -31,11 +34,12 @@ Template helps form a task list for feature implementation in the **spec-feature
 **Steps**
 
 1. Create the directory structure `spec/features/{FEATURE}/` if it doesn't exist.
-2. Form the task list according to the sections above, based on **CONTEXT** and available additional context.
-3. Create/update the file `spec/features/{FEATURE}/tasks.md` with the complete task list content.
-4. Ensure that tasks cover implementation, verification, and release of the feature. The final Markdown should not contain unfilled placeholders.
-5. Record in the `## Definition of Done` section that `/spec/core/verify.md` execution is performed after completing all tasks, so executors do this automatically upon completion of the list.
-6. Ensure the document is complete and ready for implementation.
+2. If any clarifying questions are needed, create/update `spec/features/{FEATURE}/clarifications.md` using `spec/core/clarifications.md` and stop if unanswered questions block correct task definition.
+3. Form the task list according to the sections above, based on **CONTEXT** and available additional context.
+4. Create/update the file `spec/features/{FEATURE}/tasks.md` with the complete task list content.
+5. Ensure that tasks cover implementation, verification, and release of the feature. The final Markdown should not contain unfilled placeholders.
+6. Record in the `## Definition of Done` section that `/spec/core/verify.md` execution is performed after completing all tasks, so executors do this automatically upon completion of the list.
+7. Ensure the document is complete and ready for implementation.
 
 **Result template**
 

package/spec/feature.md

@@ -12,11 +12,14 @@ Parameters are passed in one line in the format `#<feature># <context>` without
 **General rules**
 
 - Before doing anything, read and follow `spec/constitution/*`.
-- If information is missing, write `No data — needs clarification: <what exactly>` and do not guess.
+- If information is missing:
+  - write clarifying questions to `spec/features/{FEATURE}/clarifications.md` (use `spec/core/clarifications.md` as a template),
+  - in other documents, write `No data — needs clarification (see clarifications.md: #<n>)`,
+  - do not guess.
 - Work only with specification files in the `spec/features/{FEATURE}` directory: automatically create necessary directories and files within `/spec` folder only.
 - Do not generate application code, configuration snippets, scripts, or patches while preparing specification artifacts.
 - If the **FEATURE** value matches an already existing feature, update its current materials instead of creating a new folder and use the `spec/core/hotfix.md` template when making changes.
-- Within one request, create/update three separate Markdown documents: `spec.md`, `plan.md`, and `tasks.md` in the appropriate directory structure.
+- Within one request, create/update feature documents in the appropriate directory structure. If clarifications are needed and answers are missing, create/update `clarifications.md` and stop before generating/updating `spec.md`, `plan.md`, and `tasks.md`.
 - Automatically create the directory structure `spec/features/{FEATURE}/` if it doesn't exist.
 - All sections from templates must be filled with content: do not leave empty headers, placeholders, or hint comments.
 - Use sequence: first specification, then plan (based on specification), then task list (based on specification and plan).
@@ -26,18 +29,20 @@ Parameters are passed in one line in the format `#<feature># <context>` without
 **Steps**
 
 1. Check if `spec/features/{FEATURE}/` directory exists, create it if necessary.
-2. Prepare and create/update specification `spec/features/{FEATURE}/spec.md` using the template from `spec/core/spec.md`, using **CONTEXT** as primary context.
-3. Based on the completed specification and **CONTEXT**, form and create/update plan `spec/features/{FEATURE}/plan.md` using the structure from `spec/core/plan.md`.
-4. Considering specification, plan, and **CONTEXT**, compile and create/update task list `spec/features/{FEATURE}/tasks.md` according to requirements from `spec/core/tasks.md`.
-5. Check that each document is formatted in valid Markdown and contains no unfilled sections.
+2. If any clarifying questions are needed, create/update `spec/features/{FEATURE}/clarifications.md` using `spec/core/clarifications.md`. If answers are missing and this blocks correct generation, stop here.
+3. Prepare and create/update specification `spec/features/{FEATURE}/spec.md` using the template from `spec/core/spec.md`, using **CONTEXT** as primary context (and clarified answers, if present).
+4. Based on the completed specification and **CONTEXT**, form and create/update plan `spec/features/{FEATURE}/plan.md` using the structure from `spec/core/plan.md`.
+5. Considering specification, plan, and **CONTEXT**, compile and create/update task list `spec/features/{FEATURE}/tasks.md` according to requirements from `spec/core/tasks.md`.
+6. Check that each document is formatted in valid Markdown and contains no unfilled sections.
 
 **Result structure**
 
 The process should automatically create/update the following files:
 
-1. `spec/features/{FEATURE}/spec.md` - Feature specification document
-2. `spec/features/{FEATURE}/plan.md` - Implementation plan document  
-3. `spec/features/{FEATURE}/tasks.md` - Task list document
+1. `spec/features/{FEATURE}/clarifications.md` - Clarifying questions and user answers (if needed)
+2. `spec/features/{FEATURE}/spec.md` - Feature specification document
+3. `spec/features/{FEATURE}/plan.md` - Implementation plan document  
+4. `spec/features/{FEATURE}/tasks.md` - Task list document
 
 Each document should be created with complete content based on the templates from `spec/core/` and the provided **CONTEXT**.