spec-feature 1.0.0

package/README.md

@@ -0,0 +1,145 @@
+# SpecFeature
+
+SpecFeature is a sequential process for preparing and maintaining features: from formulating business context to verifying completed tasks. It helps synchronize product, engineering, and QA teams, reduce the number of "on-the-fly" changes, and establish success criteria before development begins. All artifacts are generated by LLM based on a single input context.
+
+## Directory structure `/spec`
+
+### Initial structure (created during initialization)
+```
+/spec
+├── README.md             ← this guide
+├── feature.md            ← main template that launches 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 artifact update structure
+```
+
+### Full structure (after creating the first feature)
+```
+/spec
+├── README.md             ← this guide
+├── feature.md            ← main template that launches 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 artifact update structure
+└── features              ← directory 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
+```
+
+> **Note:** The `features` folder is created automatically when creating the first feature through `spec/feature.md`.
+
+## Getting started
+
+To launch specification creation, use `spec/feature.md`. It will create a specification, plan, and task list in one request.
+
+**Usage example:**
+```
+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.
+```
+
+This will create the `spec/features/user-auth/` folder with three files: `spec.md`, `plan.md`, and `tasks.md`.
+
+## Input parameter format
+
+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.
+
+## How to launch specification creation
+
+Use any AI Assistant that can create folders and files, such as: `Claude Code`, `Gemini CLI`, `Codex CLI`, `Copilot`, `Cursor`, etc.
+
+1. **Pass it a prompt in this format**
+   ```
+   Use the template from spec/feature.md.
+   @<feature>@ <context>
+   ```
+2. **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.
+
+## How to launch task execution based on created specifications
+
+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
+
+To update an existing feature, reuse `spec/feature.md`, specifying the name of the required feature folder and a list of changes:
+
+**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.
+```
+
+The AI assistant will correctly overwrite `spec.md`, `plan.md`, and `tasks.md`, preserving the structure and updating the content for new requirements.
+
+## 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

package/bin/cli.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === "init") {
+  const targetDir = process.cwd();
+  const templatesDir = path.join(__dirname, "../spec");
+
+  fs.readdirSync(templatesDir).forEach(file => {
+    const src = path.join(templatesDir, file);
+    const dest = path.join(targetDir, file);
+
+    if (!fs.existsSync(dest)) {
+      fs.copyFileSync(src, dest);
+      console.log(`Created file: ${file}`);
+    } else {
+      console.log(`Skipped (already exists): ${file}`);
+    }
+  });
+
+  console.log("✅ SpecFeature initialized!");
+} else {
+  console.log("Usage: npx spec-feature init");
+}

package/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "spec-feature",
+  "version": "1.0.0",
+  "bin": {
+    "spec-feature": "./bin/cli.js"
+  },
+  "type": "module"
+}

package/spec/core/hotfix.md

@@ -0,0 +1,35 @@
+<!-- spec-feature: feature hotfix -->
+
+Template automates feature maintenance after release: records hotfixes and synchronously updates **spec-feature** artifacts (spec, plan, and tasks).
+
+**Parameters**
+
+- **FEATURE** — name of the folder with feature artifacts. Determined by the value between the first two `@` symbols (e.g., `@billing@` → `billing`).
+- **CONTEXT** — essence of the hotfix and expected result. This is everything passed after the second `@`; multi-line descriptions with links to incidents or PRs are allowed.
+
+**General rules**
+
+- 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).
+- 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.
+- Ensure all modified documents are complete and properly formatted.
+
+**Automatic update logic**
+
+- `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.
+- `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.
+  - For each task, specify necessary checks: tests, manual scenarios, documentation updates.
+
+**Steps**
+
+1. Read `spec.md`, `plan.md`, and `tasks.md` to understand the current feature state.
+2. Form a list of changes that the hotfix should introduce and reflect them in corresponding documents. Maintain unified terms and component references.
+3. Update `tasks.md`: add or adjust tasks, set checkboxes based on actual execution, supplement with verification requirements.
+4. Ensure all modified documents are complete and ready for implementation.
+
+Write strictly in Markdown. Goal — automatically bring all feature artifacts up to date under the hotfix and synchronize checklists with actual state.

package/spec/core/plan.md

@@ -0,0 +1,55 @@
+<!-- spec-feature: implementation plan -->
+
+Template helps format the feature implementation plan in the **spec-feature** process.
+
+**Parameters**
+
+- **FEATURE** — name of the folder where the plan will be saved. Taken from the value between the first two `@` symbols (e.g., `@payments@` → `payments`).
+- **CONTEXT** — main context for preparing the plan. Consider everything after the second `@` in the parameter line; context can span multiple lines and include additional clarifications.
+
+**General rules**
+
+- Work only with specification files within `/spec` directory: automatically create necessary directories and files.
+- 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>`.
+- 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.
+- Ensure all sections are complete and properly formatted.
+
+**What needs to be revealed in the plan**
+
+- `## Data sources / schemas` — storage, migrations, indexes, data handling, and external sources.
+- `## 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.
+
+**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.
+
+**Result template**
+
+```md
+# Implementation Plan
+
+**Plan:** {CONTEXT}
+
+## Data sources / schemas
+
+## Contracts and interfaces
+
+## Architecture / Components
+
+## Risks
+
+## Assumptions
+
+```
+
+Write strictly in Markdown and automatically create/update the plan file. **Goal** — create/update file `/spec/features/{FEATURE}/plan.md` describing HOW we implement the feature based on **CONTEXT**.

package/spec/core/spec.md

@@ -0,0 +1,51 @@
+<!-- spec-feature: specification -->
+
+Template helps describe a feature before implementation in the **spec-feature** process.
+
+**Parameters**
+
+- **FEATURE** — name of the folder where the specification will be saved. Taken from the value between the first two `@` symbols (e.g., `@payments@` → `payments`).
+- **CONTEXT** — main context for describing the feature. Consider everything after the second `@` in the parameter line; context can span multiple lines and include additional clarifications.
+
+**General rules**
+
+- Work only with specification files within `/spec` directory: automatically create necessary directories and files.
+- 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.
+- If there's insufficient data for a section, explicitly write `No data — needs clarification: <what exactly>` instead of an empty header.
+- Ensure all sections are complete and properly formatted.
+
+**What needs to be revealed in the specification**
+
+- `## 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.
+
+**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.
+
+**Result template**
+
+```md
+# {FEATURE}
+
+**Specification:** {CONTEXT}
+
+## User Stories
+
+## Main scenarios and rules
+
+## Non-functional requirements
+
+## Assumptions
+
+```
+
+Write strictly in Markdown and automatically create/update the specification file. **Goal** — create/update file `/spec/features/{FEATURE}/spec.md` describing WHAT we do and WHY, based on **CONTEXT**.

package/spec/core/tasks.md

@@ -0,0 +1,59 @@
+<!-- spec-feature: task list -->
+
+Template helps form a task list for feature implementation in the **spec-feature** process.
+
+**Parameters**
+
+- **FEATURE** — name of the folder where the task list will be saved. Taken from the value between the first two `@` symbols (e.g., `@payments@` → `payments`).
+- **CONTEXT** — main context for preparing tasks. Consider everything after the second `@` in the parameter line; context can span multiple lines and include additional clarifications.
+
+**General rules**
+
+- Work only with specification files within `/spec` directory: automatically create necessary directories and files.
+- 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.
+
+**What needs to be revealed in tasks**
+
+- `## Main directions` — group tasks by key directions from **CONTEXT** (API, UI, integrations, infrastructure, etc.). For each direction, allocate a separate subheading and list tasks within it.
+- `## Supporting tasks` — documentation, observability, quality, and other cross-cutting activities. If an item is not needed, replace it with an explanation of why it can be omitted.
+- `## Definition of Done` — feature completion criteria: tests, documentation, and other mandatory conditions.
+
+**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.
+
+**Result template**
+
+```md
+# Tasks
+
+**Context:** {CONTEXT}
+
+## Main directions
+
+## Supporting tasks
+
+- [ ] Documentation: update relevant instructions and descriptions.
+- [ ] Observability: add or clarify metrics, alerts, and/or logging.
+- [ ] Code review and PR: prepare changes for review and accompanying information.
+
+## Definition of Done
+
+- [ ] All tasks are completed and tested.
+- [ ] Relevant unit/e2e/integration tests pass successfully.
+- [ ] Documentation and operational instructions are updated.
+- [ ] `/spec/core/verify.md` is executed after completing all tasks to verify the task list.
+
+```
+
+Write strictly in Markdown and automatically create/update the task list file. Do not proceed to task execution without a separate request. **Goal** — create/update file `/spec/features/{FEATURE}/tasks.md` with a list of WHAT we do and how we verify the result, based on **CONTEXT** and prepared materials.

package/spec/core/verify.md

@@ -0,0 +1,80 @@
+<!-- spec-feature: task verification -->
+
+Template helps format the results of automatic task execution verification and make a decision about feature archiving in the **spec-feature** process.
+
+**Parameters**
+
+- **FEATURE** — name of the folder where the verification report will be saved. Taken from the value between the first two `@` symbols (e.g., `@payments@` → `payments`).
+- **CONTEXT** — main context and verification purpose. Consider everything after the second `@` in the parameter line; context can span multiple lines and include additional clarifications.
+
+**General rules**
+
+- Work only with specification files: do not create code and new directories.
+- **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.
+- Save discrepancy logs in `spec/features/{FEATURE}/verify-report.md`, adding new entries with timestamps and brief problem descriptions.
+- If there are no discrepancies, explicitly add an entry "No discrepancies detected" in the appropriate section.
+- Ensure the report is complete and properly formatted.
+
+**What needs to be revealed in the verification document**
+
+- `## Task verification results` — list of verified tasks with final status and links to supporting artifacts/proofs.
+- `## Discrepancy log` — brief summary of new entries added to `verify-report.md`, with steps to resolve problems.
+- `## Archiving decision` — final status of verify launch: moving feature to `spec/archived/{FEATURE}` or list of actions for re-verification.
+
+**Steps**
+
+1. **MANDATORY:** Create the verification report file `spec/features/{FEATURE}/verify-report.md` using the template below.
+2. Add a comment at the beginning of the result to specify the save path:
+   ```md
+   <!-- SAVE_AS: spec/features/{FEATURE}/verify-report.md -->
+   ```
+3. Go through tasks in `spec/features/{FEATURE}/tasks.md` in order and update checkboxes according to actual execution status.
+4. Record results in `spec/features/{FEATURE}/verify-report.md` with logs for all tasks (completed and uncompleted).
+5. Check that Markdown is formatted correctly and contains no unfilled placeholders.
+6. Ensure the report is complete and ready for archiving decision.
+
+**verify-report.md template**
+
+```md
+# Verify Report - {FEATURE}
+
+**Date:** YYYY-MM-DD  
+**Context:** {CONTEXT}
+
+## Discrepancy log
+
+### YYYY-MM-DD - [General status description]
+
+#### 1. [Problem name]
+
+**Problem:** [Problem description]  
+**Status:** [Criticality: critical/not critical/low priority]  
+**Action:** [What needs to be done]
+
+#### 2. [Next problem]
+
+...
+
+### YYYY-MM-DD - Positive results
+
+#### Fully implemented components:
+
+- ✅ [Component 1 (file path)]
+- ✅ [Component 2 (file path)]
+- ❌ [Uncompleted component (reason)]
+- ⚠️ [Partially completed component (what remains)]
+
+```
+
+**Log entry structure:**
+
+- **Date and general status** — grouping by verification time
+- **Problems** — numbered list with problem indication, criticality status, and required actions
+- **Positive results** — list of completed tasks with emoji statuses:
+  - ✅ — fully completed
+  - ❌ — not completed
+  - ⚠️ — partially completed
+
+Write strictly in Markdown and add nothing outside the document. **Goal** — verify all tasks in `spec/features/{FEATURE}/tasks.md`, mark completed ones in the task file, create a detailed report `verify-report.md` with logs of all tasks and their statuses, or recommend moving the feature to `spec/archived/{FEATURE}` if all tasks passed.

package/spec/feature.md

@@ -0,0 +1,40 @@
+<!-- spec-feature: unified launch -->
+
+Template allows creating a complete set of feature documents in one request during the **spec-feature** process.
+
+**Parameters**
+
+- **FEATURE** — name of the folder where artifacts will be saved. Determined by the value between the first two `@` symbols (e.g., `@payments@` → `payments`).
+- **CONTEXT** — detailed feature description: goals, functional and non-functional requirements, constraints, implementation plan. Consider everything after the second `@` in the parameter line; text can span multiple lines and include lists.
+
+Parameters are passed in one line in the format `@<feature>@ <context>` without XML-like tags.
+
+**General rules**
+
+- Work only with specification files in the `spec/features/{FEATURE}` directory: automatically create necessary directories and files within `/spec` folder only.
+- 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).
+- Follow KISS, DRY, and YAGNI requirements: solutions should be implementable without excessive complexity and duplication.
+
+**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.
+
+**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
+
+Each document should be created with complete content based on the templates from `spec/core/` and the provided **CONTEXT**.
+
+Write strictly in Markdown and automatically create/update the three documents. **Goal** — create a complete set of feature materials (what we do, how we implement, and what tasks we perform) in one request based on **CONTEXT**, with automatic file creation and directory structure management.