spec-feature 1.0.7 → 1.0.8

package/README.md

@@ -4,203 +4,98 @@
 
 **Turn your idea into a ready development plan in minutes!**
 
-`Spec Feature` is your personal assistant for creating technical specifications. Simply describe what you want to build, and get a complete specification, technical plan, and task list for your development team. All documents are created by AI from a single description.
+Create technical specifications, plans, and tasks for your development team using AI from a single description.
 
-## 🎯 Why use Spec Feature?
+## 🎯 Benefits
 
-### **⭐ Clear project start**
-The specification becomes the single source of truth — no more guessing about what you intended to build.
-
-### **🤝 Fewer misunderstandings between human and AI**
-Clear "contracts" / specifications help avoid "vibe coding" — when AI "guesses" your intentions and often builds something not quite what you need.
-
-### **📚 Architecture and decisions are documented**
-"Why did we choose this solution?" will be captured in the specification, not in emails, chats, or someone's head.
-
-### **✅ Controlled task breakdown**
-Small tasks are easier to review, test, and correct — fewer "big commits that are hard to understand".
-
-### **🔄 Flexibility and evolution**
-Specifications are not "dead" — they can be updated, refactored, and revised when requirements change.
-
-### **🤖 AI assistant integration**
-Specification + plan + tasks give AI "context" and boundaries within which it can generate code more safely.
+✨ Clear project start • 🤝 Fewer misunderstandings • 📚 Documented architecture • ✅ Controlled tasks • 🔄 Easy updates • 🤖 Better AI integration
 
 ## ⚡ Quick Start
 
-### 🚀 Using npx (recommended)
-
-The easiest way to get started with Spec Feature:
-
 ```bash
-# Initialize Spec Feature in current directory
+# Initialize in current directory
 npx spec-feature init
 
-# Initialize with custom folder name
+# Or with custom folder name
 npx spec-feature init my-project-docs
 ```
 
-This will create a `spec` folder (or your custom name) with the complete Spec Feature structure ready to use.
-
-### 🌍 Global installation
-
-For frequent use, install Spec Feature globally:
-
-```bash
-npm install -g spec-feature
-
-# Now you can use it anywhere
-spec-feature init
-spec-feature init my-features
+Creates the Spec Feature structure inside `spec/` by default, or inside the folder name you provide.
+
+## 📁 Structure
+
+```mermaid
+graph TD
+    A[spec/] --> B[README.md]
+    A --> C[feature.md]
+    A --> D[core/]
+    A --> E[features/]
+    
+    D --> F[spec.md]
+    D --> G[plan.md]
+    D --> H[tasks.md]
+    D --> I[verify.md]
+    D --> J[hotfix.md]
+    
+    E --> K[user-auth/]
+    K --> L[spec.md]
+    K --> M[plan.md]
+    K --> N[tasks.md]
+    K --> O[verify-report.md]
 ```
 
-### 📦 Local installation
+**Templates** (core/) → **Features** (features/)
 
-To install Spec Feature in your project:
+## 🎬 Workflow
 
-```bash
-npm install spec-feature
-
-# Add to package.json scripts
-{
-  "scripts": {
-    "init-spec": "spec-feature init",
-    "init-docs": "spec-feature init documentation"
-  }
-}
-```
+**Send these prompts to your AI assistant** (Claude, Cursor, Copilot, etc.) to create, execute, and update features.
 
-## 📁 Project Structure `/spec`
-
-### 🏗️ Initial structure (created during initialization)
-```
-/spec
-├── README.md             ← this guide
-├── feature.md            ← main template for launching spec-feature
-└── core                  ← base templates for specific stages
-    ├── spec.md           ← specification structure
-    ├── plan.md           ← technical plan structure
-    ├── tasks.md          ← task list structure
-    ├── verify.md         ← verification report structure
-    └── hotfix.md         ← hotfix and update structure
-```
+### 1️⃣ Create Feature
 
-### 🎯 Full structure (after creating the first feature)
 ```
-/spec
-├── README.md             ← this guide
-├── feature.md            ← main template for launching spec-feature
-├── core                  ← base templates for specific stages
-│   ├── spec.md           ← specification structure
-│   ├── plan.md           ← technical plan structure
-│   ├── tasks.md          ← task list structure
-│   ├── verify.md         ← verification report structure
-│   └── hotfix.md         ← hotfix and update structure
-└── features              ← folder with feature materials (created automatically)
-    ├── <feature>         ← specific feature folder (e.g., `user-auth`)
-    │   ├── spec.md       ← current specification
-    │   ├── plan.md       ← technical plan
-    │   ├── tasks.md      ← implementation checklist
-    │   └── verify-report.md (optional) — verification log
-    └── ...               ← other features created from templates
+Use the template from spec/feature.md.
+#feature-name# Your description here
 ```
 
-> **💡 Tip:** The `features` folder is created automatically when creating the first feature through `spec/feature.md`.
-
-## 🎬 Getting Started
-
-To create a feature specification, use the `spec/feature.md` template with any AI Assistant that can create folders and files (such as `Claude Code`, `Gemini CLI`, `Codex CLI`, `Copilot`, `Cursor`, etc.).
-
-### 📝 Input parameter format
+Format: `#feature# description` → creates `spec/features/feature-name/` with 3 files:
 
-Pass parameters in one line in the format `#<feature># <context>`:
-
-- the value between the first two `#` symbols is used as **FEATURE** and determines the feature folder (`#payments#` → `spec/features/payments`);
-- everything following the second `#` is **CONTEXT**. It can span multiple lines, include lists, links, and additional clarifications.
+```mermaid
+flowchart LR
+    A[feature.md template] --> B[spec.md]
+    A --> C[plan.md]
+    A --> D[tasks.md]
+```
 
-### 🚀 Usage example
+### 2️⃣ Execute Tasks
 
 ```
-Use the template from spec/feature.md.
-#user-auth# Need to add user authentication via email and password. The user should be able to register, log in, and recover their password. Integration with the existing notification system is mandatory.
+Execute all tasks in spec/features/{FEATURE}/tasks.md
 ```
 
-### ✨ What happens next
-
-The AI assistant generates three Markdown documents in sequence:
-- `spec/features/{FEATURE}/spec.md` — specification describing value and user scenarios.
-- `spec/features/{FEATURE}/plan.md` — technical plan based on specification and context.
-- `spec/features/{FEATURE}/tasks.md` — checklist of tasks for implementation and testing.
-
-For example, the above command will create the `spec/features/user-auth/` folder with three files: `spec.md`, `plan.md`, and `tasks.md`.
-
-## 🚀 Launching Task Execution
-
-After creating the specification and plan, you can proceed with implementation:
-
-1. **🎯 Launch task execution**
-   ```
-   Execute all tasks in `spec/features/{FEATURE}/tasks.md`
-   ```
-
-2. **⚡ What happens during execution**
-   - AI assistant sequentially executes tasks from the checklist
-   - Each completed task is marked as finished
-   - When problems arise, the assistant may request clarifications
-   - Progress can be tracked by updating checkboxes in `tasks.md`
-
-3. **📝 Example for user-auth feature**
-   ```
-   Execute all tasks in `spec/features/user-auth/tasks.md`
-   ```
-
-## ✅ What Happens After Task Execution
-
-After completing all tasks, automatic verification is launched:
-
-1. **🔍 Automatic verification**
-   - AI assistant uses the `spec/core/verify.md` template
-   - Compares implemented functionality with requirements from `spec.md`
-   - Checks compliance with the technical plan from `plan.md`
-
-2. **📊 Verification results**
-   - A report `spec/features/{FEATURE}/verify-report.md` is created
-   - Task statuses in `tasks.md` are updated (✅ completed / ❌ requires refinement)
-   - Found discrepancies and recommendations are recorded
-
-3. **📋 Verification report content**
-   - Summary of completed tasks
-   - List of found problems
-   - Recommendations for fixes
-   - Assessment of feature readiness for production
-
-## 🔄 Updating Existing Feature
+```mermaid
+flowchart TD
+    A[tasks.md] --> B[Task 1]
+    B --> C[Task 2]
+    C --> D[Task N]
+    D --> E[All Complete]
+    E --> F[Auto Verification]
+    F --> G[verify-report.md]
+```
 
-To update an existing feature, reuse `spec/feature.md`, specifying the name of the required feature folder and a list of changes:
+### 3️⃣ Update Feature
 
-**📝 Update example:**
 ```
 Use the template from spec/feature.md.
-#user-auth# Add two-factor authentication (2FA) via SMS. The user should be able to enable/disable 2FA in profile settings. Integration with existing SMS provider.
+#feature-name# New requirements
 ```
 
-The AI assistant will correctly overwrite `spec.md`, `plan.md`, and `tasks.md`, preserving the structure and updating the content for new requirements.
+Overwrites spec.md, plan.md, tasks.md with updated content.
 
 ## 🛠️ Troubleshooting
 
-### 🚨 Common problems and solutions
-
-**❌ Problem:** AI assistant doesn't create feature folder
-- **✅ Solution:** Make sure you're using the correct format `#feature# context` and that the assistant has file creation permissions
-
-**❌ Problem:** Tasks are executed in wrong order
-- **✅ Solution:** Check task numbering in `tasks.md` and reorder if necessary
-
-**❌ Problem:** Verification doesn't launch automatically
-- **✅ Solution:** Make sure all tasks in `tasks.md` are marked as completed, then manually launch verification:
-  ```
-  Use the template from spec/core/verify.md to verify spec/features/{FEATURE}/
-  ```
-
-**❌ Problem:** Conflict when updating existing feature
-- **✅ Solution:** Create a backup of current files before updating or use git to track changes
+| Problem | Solution |
+|---------|----------|
+| No feature folder created | Check format `#feature# context` |
+| Wrong task order | Reorder numbers in tasks.md |
+| Verification not launched | All tasks must be checked, or run manually: `Use template from spec/core/verify.md to verify spec/features/{FEATURE}/` |
+| Update conflicts | Use git to track changes |

package/bin/cli.js

@@ -7,48 +7,56 @@ import { fileURLToPath } from "url";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+const DEFAULT_FOLDER = "spec";
 const args = process.argv.slice(2);
 const command = args[0];
 
 if (command === "init") {
   const targetDir = process.cwd();
-  const folderName = args[1] || "spec"; // Use provided folder name or default to "spec"
+  const folderName = args[1] || DEFAULT_FOLDER;
   const destinationDir = path.join(targetDir, folderName);
-  const templatesDir = path.join(__dirname, "../spec");
+  const templateDir = path.join(__dirname, "..", DEFAULT_FOLDER);
 
-  function copyRecursive(src, dest) {
+  if (!fs.existsSync(templateDir)) {
+    console.error(`❌ Template directory not found: ${templateDir}`);
+    process.exit(1);
+  }
+
+  function copyRecursive(src, dest, relative = "") {
     const stat = fs.statSync(src);
-    
+
     if (stat.isDirectory()) {
       if (!fs.existsSync(dest)) {
         fs.mkdirSync(dest, { recursive: true });
+        if (relative) {
+          console.log(`Created: ${folderName}/${relative}`);
+        }
       }
-      fs.readdirSync(src).forEach(file => {
-        copyRecursive(path.join(src, file), path.join(dest, file));
+
+      fs.readdirSync(src).forEach(entry => {
+        const nextRelative = relative ? `${relative}/${entry}` : entry;
+        copyRecursive(path.join(src, entry), path.join(dest, entry), nextRelative);
       });
-    } else {
-      fs.copyFileSync(src, dest);
+      return;
+    }
+
+    if (fs.existsSync(dest)) {
+      console.log(`Skipped (already exists): ${folderName}/${relative}`);
+      return;
     }
+
+    fs.copyFileSync(src, dest);
+    console.log(`Created: ${folderName}/${relative}`);
   }
 
-  // Create the destination directory if it doesn't exist
   if (!fs.existsSync(destinationDir)) {
     fs.mkdirSync(destinationDir, { recursive: true });
   }
 
-  fs.readdirSync(templatesDir).forEach(file => {
-    const src = path.join(templatesDir, file);
-    const dest = path.join(destinationDir, file);
-
-    if (!fs.existsSync(dest)) {
-      copyRecursive(src, dest);
-      console.log(`Created: ${folderName}/${file}`);
-    } else {
-      console.log(`Skipped (already exists): ${folderName}/${file}`);
-    }
-  });
-
+  copyRecursive(templateDir, destinationDir);
   console.log(`✅ Spec Feature initialized in '${folderName}' folder!`);
-} else {
-  console.log("Usage: npx spec-feature init [folder-name]");
+  process.exit(0);
 }
+
+console.log("Usage: npx spec-feature init [folder-name]");
+process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-feature",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "bin": {
     "spec-feature": "./bin/cli.js"
   },

package/spec/core/hotfix.md

@@ -11,6 +11,7 @@ Template automates feature maintenance after release: records hotfixes and synch
 
 - Work only in the `spec/features/{FEATURE}/` directory: allowed to edit `spec.md`, `plan.md`, and `tasks.md`.
 - Do not create new files in the feature folder (including `hotfix.md` and verification reports).
+- Do not generate application code, configuration snippets, scripts, or patches while documenting the hotfix.
 - Preserve the structure of existing documents: do not delete sections, do not leave empty headers and hints from templates.
 - All changes should consider requirements from specification and plan, maintaining consistency of terms and references.
 - Actual task state must be reflected in `tasks.md`: do not allow desynchronization between checkboxes and actual state.

package/spec/core/plan.md

@@ -10,6 +10,7 @@ Template helps format the feature implementation plan in the **spec-feature** pr
 **General rules**
 
 - 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**.
 - Substitute specific values instead of placeholders (`{FEATURE}`, `{CONTEXT}`, etc.). If a section is not applicable — explicitly write `Not required — reason: <explanation>`.

package/spec/core/spec.md

@@ -10,6 +10,7 @@ Template helps describe a feature before implementation in the **spec-feature**
 **General rules**
 
 - 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.
 - The specification header should contain a clear feature name (adapt the **FEATURE** value if necessary).
 - The structure from the template below needs to be filled with content: theses, lists, and tables are allowed, empty sections are not.

package/spec/core/tasks.md

@@ -10,12 +10,14 @@ Template helps form a task list for feature implementation in the **spec-feature
 **General rules**
 
 - 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**.
 - 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>`.
 - After filling the document, mark self-check checkboxes in the "Instruction execution control" section.
+- Do not start executing tasks until a separate user request explicitly references `spec/features/{FEATURE}/tasks.md`; ignore execution requests without that reference.
 
 **What needs to be revealed in tasks**
 

package/spec/core/verify.md

@@ -10,6 +10,7 @@ Template helps format the results of automatic task execution verification and m
 **General rules**
 
 - Work only with specification files: do not create code and new directories.
+- Do not generate application code, configuration snippets, scripts, or patches during verification.
 - **REQUIRED:** Always create `spec/features/{FEATURE}/verify-report.md` file as the main output of verification process.
 - Use `spec/features/{FEATURE}/spec.md`, `plan.md`, and `tasks.md` as source data for verification.
 - Check tasks sequentially: after successful verification, mark the corresponding checkbox in `spec/features/{FEATURE}/tasks.md` as `[x]`; when discrepancies are found, leave `[ ]` and record details in the report file.

package/spec/feature.md

@@ -12,11 +12,13 @@ Parameters are passed in one line in the format `#<feature># <context>` without
 **General rules**
 
 - 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.
 - 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).
+- Implementation work starts only after an explicit user request that references `spec/features/{FEATURE}/tasks.md`; ignore requests to execute tasks if they do not contain that reference.
 - Follow KISS, DRY, and YAGNI requirements: solutions should be implementable without excessive complexity and duplication.
 
 **Steps**

package/ui/README.md

@@ -0,0 +1,75 @@
+# Nuxt Minimal Starter
+
+Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more.
+
+## Setup
+
+Make sure to install dependencies:
+
+```bash
+# npm
+npm install
+
+# pnpm
+pnpm install
+
+# yarn
+yarn install
+
+# bun
+bun install
+```
+
+## Development Server
+
+Start the development server on `http://localhost:3000`:
+
+```bash
+# npm
+npm run dev
+
+# pnpm
+pnpm dev
+
+# yarn
+yarn dev
+
+# bun
+bun run dev
+```
+
+## Production
+
+Build the application for production:
+
+```bash
+# npm
+npm run build
+
+# pnpm
+pnpm build
+
+# yarn
+yarn build
+
+# bun
+bun run build
+```
+
+Locally preview production build:
+
+```bash
+# npm
+npm run preview
+
+# pnpm
+pnpm preview
+
+# yarn
+yarn preview
+
+# bun
+bun run preview
+```
+
+Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.

package/ui/app/app.vue

@@ -0,0 +1,6 @@
+<template>
+  <div>
+    <NuxtRouteAnnouncer />
+    <NuxtWelcome />
+  </div>
+</template>

package/ui/eslint.config.mjs

@@ -0,0 +1,6 @@
+// @ts-check
+import withNuxt from './.nuxt/eslint.config.mjs'
+
+export default withNuxt(
+  // Your custom configs here
+)

package/ui/nuxt.config.ts

@@ -0,0 +1,13 @@
+// https://nuxt.com/docs/api/configuration/nuxt-config
+export default defineNuxtConfig({
+  compatibilityDate: '2025-07-15',
+  devtools: { enabled: true },
+
+  modules: [
+    '@nuxt/eslint',
+    '@nuxt/image',
+    '@nuxt/scripts',
+    '@nuxt/fonts',
+    '@nuxt/icon'
+  ]
+})

package/ui/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "ui",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "nuxt build",
+    "dev": "nuxt dev",
+    "generate": "nuxt generate",
+    "preview": "nuxt preview",
+    "postinstall": "nuxt prepare"
+  },
+  "dependencies": {
+    "@nuxt/eslint": "1.9.0",
+    "@nuxt/fonts": "0.11.4",
+    "@nuxt/icon": "2.1.0",
+    "@nuxt/image": "1.11.0",
+    "@nuxt/scripts": "0.13.0",
+    "@unhead/vue": "^2.0.3",
+    "eslint": "^9.0.0",
+    "nuxt": "^4.2.0",
+    "vue": "^3.5.22",
+    "vue-router": "^4.6.3"
+  }
+}

package/ui/public/robots.txt

@@ -0,0 +1,2 @@
+User-Agent: *
+Disallow:

package/ui/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  // https://nuxt.com/docs/guide/concepts/typescript
+  "files": [],
+  "references": [
+    {
+      "path": "./.nuxt/tsconfig.app.json"
+    },
+    {
+      "path": "./.nuxt/tsconfig.server.json"
+    },
+    {
+      "path": "./.nuxt/tsconfig.shared.json"
+    },
+    {
+      "path": "./.nuxt/tsconfig.node.json"
+    }
+  ]
+}