spec-feature 1.0.7 → 1.1.0

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,141 @@ 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];
 
+const AGENTS_START = "<!-- spec-feature:agents:start -->";
+const AGENTS_END = "<!-- spec-feature:agents:end -->";
+
 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);
+
+  if (!fs.existsSync(templateDir)) {
+    console.error(`❌ Template directory not found: ${templateDir}`);
+    process.exit(1);
+  }
 
-  function copyRecursive(src, dest) {
+  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);
+  copyRecursive(templateDir, destinationDir);
+
+  const agentsWorkflowBlock = `${AGENTS_START}
+
+## spec-feature workflow
+
+This repository uses **spec-feature** to define features as structured documents before implementation.
+
+### Templates origin
+
+The \`spec/\` directory is generated by running \`npx spec-feature init\` in the repository root (typically by a human during project setup). Treat files under \`spec/core/\` as canonical templates for creating and updating feature artifacts.
+
+### Structure
+
+- \`spec/core/\` — templates: \`spec.md\`, \`plan.md\`, \`tasks.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>/verify-report.md\` — verification output (after tasks / manual verify)
+
+### Create or update a feature
 
-    if (!fs.existsSync(dest)) {
-      copyRecursive(src, dest);
-      console.log(`Created: ${folderName}/${file}`);
+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\`.
+
+### Execute tasks
+
+When implementation is requested, execute tasks from:\n\n- \`spec/features/<feature>/tasks.md\`
+
+### Verify
+
+Use \`spec/core/verify.md\` to verify \`spec/features/<feature>/\` and write \`verify-report.md\`.
+
+### Quality bar (for generated artifacts)
+
+- No empty headers, no placeholders
+- \`spec.md\`: at least 3 user stories + explicit assumptions
+- \`plan.md\`: references concrete decisions from \`spec.md\` (avoid generic plans)
+- \`tasks.md\`: checkable, ordered, references concrete paths under \`spec/features/<feature>/\`
+- If updating an existing feature, prefer updating existing files; use \`spec/core/hotfix.md\` to describe changes
+
+${AGENTS_END}
+`;
+
+  const agentsPath = path.join(targetDir, "AGENTS.md");
+  const agentsBlockRegex = new RegExp(
+    `${escapeRegExp(AGENTS_START)}[\\s\\S]*?${escapeRegExp(AGENTS_END)}`,
+    "m",
+  );
+
+  try {
+    if (!fs.existsSync(agentsPath)) {
+      const initialAgents = `# AGENTS\n\n${agentsWorkflowBlock}\n`;
+      fs.writeFileSync(agentsPath, initialAgents, "utf8");
+      console.log("Created: AGENTS.md");
     } else {
-      console.log(`Skipped (already exists): ${folderName}/${file}`);
+      const existingAgents = fs.readFileSync(agentsPath, "utf8");
+      if (existingAgents.includes(AGENTS_START) && existingAgents.includes(AGENTS_END)) {
+        const updatedAgents = existingAgents.replace(agentsBlockRegex, agentsWorkflowBlock).replace(/\s*$/, "\n");
+        if (updatedAgents !== existingAgents) {
+          fs.writeFileSync(agentsPath, updatedAgents, "utf8");
+          console.log("Updated: AGENTS.md (spec-feature block)");
+        } else {
+          console.log("Skipped: AGENTS.md (spec-feature block unchanged)");
+        }
+      } else {
+        const trimmed = existingAgents.replace(/\s*$/, "");
+        const appendedAgents = `${trimmed}\n\n${agentsWorkflowBlock}\n`;
+        fs.writeFileSync(agentsPath, appendedAgents, "utf8");
+        console.log("Appended: AGENTS.md (spec-feature workflow)");
+      }
     }
-  });
+  } catch (err) {
+    console.error("❌ Failed to write AGENTS.md:", err?.message || err);
+    process.exit(1);
+  }
 
   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);
+
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "spec-feature",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "bin": {
-    "spec-feature": "./bin/cli.js"
+    "spec-feature": "bin/cli.js"
   },
   "type": "module",
   "keywords": [

package/spec/constitution/00-purpose-and-precedence.md

@@ -0,0 +1,19 @@
+# Purpose and precedence
+
+## Rules
+
+- MUST treat `spec/constitution/*` as the highest-priority constraints for agent behavior and project workflow.
+- MUST NOT override a constitution rule by “common sense” or best practices unless the constitution explicitly allows it.
+- MUST keep rules **specific and testable** (avoid vague statements like “write clean code”).
+- SHOULD record constitution changes as small diffs and mention the reason.
+
+## How to verify
+
+- Check that any instruction set or template used for work includes “Read and follow `spec/constitution/*` first”.
+- If a conflict is detected, confirm the chosen action matches the precedence described in `spec/constitution/README.md`.
+
+## Exceptions
+
+- If the user explicitly requests to violate a constitution rule, MUST pause and ask for confirmation acknowledging the deviation.
+
+

package/spec/constitution/01-scope-and-non-goals.md

@@ -0,0 +1,19 @@
+# Scope and non-goals
+
+## Rules
+
+- MUST only do what the user explicitly requested and/or what is explicitly listed in the current `spec/features/{FEATURE}/tasks.md`.
+- MUST NOT add “nice-to-have” improvements, refactors, cleanups, dependency upgrades, formatting-only changes, or architectural rewrites unless explicitly requested.
+- MUST keep changes limited to the minimal set of files required to satisfy the request.
+- SHOULD clarify scope boundaries in writing before starting implementation if scope is ambiguous.
+
+## How to verify
+
+- Every changed file can be mapped to a specific task item or explicit user request.
+- No unrelated changes (renames, reformatting, refactors) are present in diffs.
+
+## Exceptions
+
+- Emergency fixes (security/production outage) are allowed only if explicitly declared as such by the user or incident context.
+
+

package/spec/constitution/02-evidence-and-no-hallucinations.md

@@ -0,0 +1,23 @@
+# Evidence and no hallucinations
+
+## Rules
+
+- MUST NOT invent facts about the codebase, infrastructure, requirements, or runtime behavior.
+- MUST base any claim about the repository on observable evidence:
+  - existing files, configs, logs, tests, or explicit user messages.
+- MUST cite the exact source when making a factual claim (file path; ideally the relevant snippet).
+- MUST write `No data — needs clarification: <specific question>` when information is missing.
+- SHOULD separate facts from proposals:
+  - Facts: evidence-backed.
+  - Proposals: clearly labeled as suggestions.
+
+## How to verify
+
+- For every statement like “the project uses X”, there is a matching file/config reference.
+- Unknown areas are marked with “No data — needs clarification…”, not guessed.
+
+## Exceptions
+
+- None. If evidence is not available, ask or stop.
+
+

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

@@ -0,0 +1,23 @@
+# Questions and unknowns
+
+## Rules
+
+- MUST ask clarifying questions when:
+  - requirements are ambiguous,
+  - success criteria are unclear,
+  - there are multiple valid implementations with different tradeoffs,
+  - actions would be destructive or expensive.
+- 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.
+
+## How to verify
+
+- Ambiguous inputs always produce clarifying questions and a short list of options.
+- Blocking unknowns are not silently assumed.
+
+## Exceptions
+
+- If the user explicitly authorizes choosing defaults, the chosen defaults MUST be recorded in the spec/plan/tasks.
+
+

package/spec/constitution/04-change-discipline-minimal-diff.md

@@ -0,0 +1,21 @@
+# Change discipline and minimal diff
+
+## Rules
+
+- MUST make the smallest possible change set that satisfies acceptance criteria.
+- MUST NOT reformat or reorder unrelated code.
+- MUST NOT change public contracts (APIs, CLI, schemas) without explicit requirement and explicit migration notes.
+- MUST keep edits localized; avoid wide refactors unless explicitly requested.
+- SHOULD document any non-obvious change rationale in a short note (spec/plan/tasks or PR description).
+
+## How to verify
+
+- Diff contains only relevant files/lines.
+- No purely stylistic changes outside the requested scope.
+- Contract changes include explicit notes and verification steps.
+
+## Exceptions
+
+- Mechanical renames or formatting changes are allowed only if explicitly requested by the user.
+
+

package/spec/constitution/05-tools-and-command-policy.md

@@ -0,0 +1,20 @@
+# Tools and command policy
+
+## Rules
+
+- MUST prefer repository-local evidence over external assumptions.
+- MUST NOT run destructive commands without explicit user approval (delete, reset, force, migrations on production, etc.).
+- MUST keep command execution minimal and non-interactive by default.
+- MUST describe why a command is needed before running it.
+- MUST NOT introduce new dependencies, services, or build steps unless explicitly requested.
+
+## How to verify
+
+- Every command has a clear purpose tied to a task.
+- No new dependencies appear without an explicit requirement.
+
+## Exceptions
+
+- None unless explicitly requested by the user.
+
+

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

@@ -0,0 +1,22 @@
+# spec-feature workflow guardrails
+
+## Rules
+
+- 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`).
+- 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 update `tasks.md` checkboxes to reflect actual state during verification.
+- SHOULD update the constitution when a feature introduces a new invariant or process rule.
+
+## How to verify
+
+- No implementation begins before an explicit request referencing `spec/features/{FEATURE}/tasks.md`.
+- Artifacts exist and are consistent (no contradictory terms/constraints).
+
+## Exceptions
+
+- Hotfixes: follow `spec/core/hotfix.md` rules for synchronized updates of `spec.md`, `plan.md`, `tasks.md`.
+
+

package/spec/constitution/07-quality-gates-definition-of-done.md

@@ -0,0 +1,19 @@
+# Quality gates and Definition of Done
+
+## Rules
+
+- MUST define “done” as meeting the criteria in `tasks.md` Definition of Done.
+- MUST NOT mark tasks as complete without running the required checks (tests, linters, manual scenarios) stated in the task.
+- MUST record verification output under `spec/features/{FEATURE}/verify-report.md` when the workflow requires it.
+- SHOULD prefer automated checks and keep manual steps explicit and repeatable.
+
+## How to verify
+
+- Completed checkboxes have corresponding evidence (test output, report, or documented manual steps).
+- Verification report exists when required and reflects the real state.
+
+## Exceptions
+
+- If checks cannot run (environment limits), MUST document the reason and the alternative evidence required.
+
+

package/spec/constitution/08-security-secrets-and-privacy.md

@@ -0,0 +1,19 @@
+# Security, secrets, and privacy
+
+## Rules
+
+- MUST NOT expose secrets (tokens, keys, passwords) in code, logs, specs, or examples.
+- MUST treat user data and sensitive data as confidential by default.
+- MUST avoid copying sensitive production data into tickets/specs.
+- SHOULD prefer secure-by-default settings and least-privilege access.
+
+## How to verify
+
+- No secrets appear in diffs, specs, or logs.
+- Any introduced config or documentation does not include real credentials.
+
+## Exceptions
+
+- None. Use placeholders for secrets.
+
+

package/spec/constitution/09-communication-contract.md

@@ -0,0 +1,20 @@
+# Communication contract
+
+## Rules
+
+- MUST communicate constraints and uncertainty explicitly.
+- MUST separate facts from proposals.
+- MUST provide short, high-signal progress updates during long tasks.
+- MUST keep the final summary concise and actionable.
+- MUST follow repository-specific language rules if defined by the user or the project.
+
+## How to verify
+
+- Updates are tied to progress and do not contain invented facts.
+- Output includes clear next steps when blockers exist.
+
+## Exceptions
+
+- None.
+
+

package/spec/constitution/10-git-and-release-policy.md

@@ -0,0 +1,19 @@
+# Git and release policy
+
+## Rules
+
+- MUST NOT create commits unless the user explicitly requests it.
+- MUST keep commit messages in English if project rules require it.
+- MUST not change git history (rebase, force-push) without explicit approval.
+- SHOULD keep changes reviewable and grouped by purpose.
+
+## How to verify
+
+- No commits exist unless requested.
+- Any commit message format follows project rules.
+
+## Exceptions
+
+- None unless explicitly requested by the user.
+
+

package/spec/constitution/99-glossary.md

@@ -0,0 +1,8 @@
+# Glossary
+
+- **Constitution**: a set of highest-priority, project-wide rules constraining agent and contributor behavior.
+- **Evidence**: observable repository/user-provided sources (files, configs, logs, tests, explicit messages) used to justify factual claims.
+- **Scope**: the work explicitly requested by the user and/or explicitly listed in `spec/features/{FEATURE}/tasks.md`.
+- **Hallucination**: any invented fact or claim not supported by evidence.
+
+

package/spec/constitution/README.md

@@ -0,0 +1,30 @@
+# Project Constitution (spec-feature)
+
+This folder contains **project-wide rules** that constrain AI agents and human contributors.
+The goal is to prevent hallucinations, scope creep, and unreviewed changes by enforcing a strict, verifiable workflow.
+
+## How to use
+
+- Read and follow **all** files in `spec/constitution/` before making any changes.
+- If there is a conflict between documents:
+  - Constitution rules override feature specs and plans.
+  - Feature specs override implementation plans.
+  - Plans override task list details only where explicitly stated.
+- Update the constitution when a feature introduces a new invariant, workflow constraint, or quality gate.
+
+## File index
+
+- `00-purpose-and-precedence.md`
+- `01-scope-and-non-goals.md`
+- `02-evidence-and-no-hallucinations.md`
+- `03-questions-and-unknowns.md`
+- `04-change-discipline-minimal-diff.md`
+- `05-tools-and-command-policy.md`
+- `06-spec-feature-workflow-guardrails.md`
+- `07-quality-gates-definition-of-done.md`
+- `08-security-secrets-and-privacy.md`
+- `09-communication-contract.md`
+- `10-git-and-release-policy.md`
+- `99-glossary.md`
+
+

package/spec/core/hotfix.md

@@ -9,8 +9,11 @@ Template automates feature maintenance after release: records hotfixes and synch
 
 **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.
 - 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

@@ -9,7 +9,10 @@ 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.
 - 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

@@ -9,7 +9,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.
 - 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

@@ -9,13 +9,17 @@ 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.
 - 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**
 
@@ -44,6 +48,7 @@ Template helps form a task list for feature implementation in the **spec-feature
 ## Supporting tasks
 
 - [ ] Documentation: update relevant instructions and descriptions.
+- [ ] Constitution: update `spec/constitution/*` if this feature introduced a new invariant, workflow constraint, or quality gate. If not required — reason: <explanation>.
 - [ ] Observability: add or clarify metrics, alerts, and/or logging.
 - [ ] Code review and PR: prepare changes for review and accompanying information.
 
@@ -52,6 +57,7 @@ Template helps form a task list for feature implementation in the **spec-feature
 - [ ] All tasks are completed and tested.
 - [ ] Relevant unit/e2e/integration tests pass successfully.
 - [ ] Documentation and operational instructions are updated.
+- [ ] Constitution compliance is checked and `spec/constitution/*` is updated if required (otherwise explicitly marked as not required with a reason).
 - [ ] `/spec/core/verify.md` is executed after completing all tasks to verify the task list.
 
 ```

package/spec/core/verify.md

@@ -9,7 +9,10 @@ Template helps format the results of automatic task execution verification and m
 
 **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.
 - 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.
@@ -22,6 +25,7 @@ Template helps format the results of automatic task execution verification and m
 - `## 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.
+- Constitution compliance — verify that `tasks.md` includes the Constitution checkbox, and that its status matches the changes introduced by the feature. If it should be updated but was not, record a discrepancy.
 
 **Steps**
 

package/spec/feature.md

@@ -11,12 +11,16 @@ 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.
 - 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**