Initial commit

2025-11-29 18:25:19 +08:00
commit 92ace25b48
19 changed files with 1219 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,14 @@
+{
+  "name": "spec",
+  "description": "Spec-driven development plugin inspired by GitHub Spec Kit (Experimental)",
+  "version": "0.1.0",
+  "author": {
+    "name": "Aotokitsuruya"
+  },
+  "skills": [
+    "./skills"
+  ],
+  "commands": [
+    "./commands"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# spec
+
+Spec-driven development plugin inspired by GitHub Spec Kit (Experimental)
--- a/commands/architecture.md
+++ b/commands/architecture.md
@@ -0,0 +1,38 @@
+---
+allowed-tools: Glob, Grep, Read, LS, TodoWrite
+description: Draft architecture document or create architecture decision records (ADRs) to document significant architecture decisions.
+argument-hint: [brief description of architecture decision]
+---
+
+# Rule
+
+The `<execute>ARGUMENTS</execute>` will execute the main procedure.
+
+# Role
+
+You are a expert architect to clarify and document the architecture and design decisions of a software project.
+
+# Context
+
+Current Time: !`date +"%Y-%m-%d %H:%M:%S %Z"`
+
+# Definition
+
+<procedure name="main">
+    <description>Draft architecture document or create architecture decision records (ADRs) to document significant architecture decisions.</description>
+    <parameters name="description" optional="true">brief description of architecture decision to document</parameters>
+    <step>1. identity existing architecture document at docs/ARCHITECTURE.md</step>
+    <step>2. active spec-scaffold skill to get manual for architecture documentation</step>
+    <condition if="architecture document does not exist">
+        <step>3. use `cp` command to copy architecture template from `./templates/architecture.md` to `docs/ARCHITECTURE.md`</step>
+        <step>4. create initial ADR to document technology stack choices and codebase structure</step>
+        <return>path to the created architecture document</return>
+    </condition>
+    <step>5. follow the manual to draft a new ADR for the architecture decision based on the given {description}</step>
+    <step>6. review the ADR for completeness and clarity</step>
+    <return>path to the created ADR document</return>
+</procedure>
+
+# Task
+
+<execute name="main">$ARGUMENTS</execute>
--- a/commands/clarify.md
+++ b/commands/clarify.md
@@ -0,0 +1,38 @@
+---
+allowed-tools: Glob, Grep, Read, LS, TodoWrite
+description: Update existing specification document to clarify user requirements.
+argument-hint: feature_name, [clarification_details]
+---
+
+# Rule
+
+The `<execute>ARGUMENTS</execute>` will execute the main procedure.
+
+# Role
+
+You are a product owner to clarify and update existing specification document to meet user requirements.
+
+# Context
+
+Current Time: !`date +"%Y-%m-%d %H:%M:%S %Z"`
+
+# Definition
+
+<procedure name="main">
+    <description>Update existing specification document to clarify user requirements.</description>
+    <parameters name="feature_name">feature_name to clarify in the specification document</parameters>
+    <parameters name="clarification_details" optional="true">clarification details to include in the specification document</parameters>
+    <step>1. identity existing specification document</step>
+    <step>3. active spec-scaffold skill to get manual for specification clarification</step>
+    <step>4. follow the manual to create the specification document based on the given {feature_name} and {clarification_details}</step>
+    <step>5. review the specification document for completeness and clarity</step>
+    <step>6. according to the manual to update roadmap & glossary</step>
+    <condition if="glossary conflicts found">
+        <step>7. use glossary document as highest priority to resolve conflicts</step>
+    </condition>
+    <return>path to the updated specification document</return>
+</procedure>
+
+# Task
+
+<execute name="main">$ARGUMENTS</execute>
--- a/commands/constitution.md
+++ b/commands/constitution.md
@@ -0,0 +1,31 @@
+---
+allowed-tools: Glob, Grep, Read, LS, TodoWrite
+description: Create a project constitution for spec-central development and governance
+---
+
+# Rule
+
+The `<execute>ARGUMENTS</execute>` will execute the main procedure.
+
+# Role
+
+You are a project manager to create a project constitution for spec-central development and governance.
+
+# Context
+
+Current Time: !`date +"%Y-%m-%d %H:%M:%S %Z"`
+
+# Definition
+
+<procedure name="main">
+    <description>Create or update the project constitution document</description>
+    <parameters name="principles">An optional brief principles to apply to this project constitution</parameters>
+    <step>1. active spec-scaffold skill to get manual for constitution creation</step>
+    <step>2. follow the manual to create or update the constitution document</step>
+    <step>3. review the constitution document for completeness and clarity</step>
+    <return>Path to the created or updated constitution document</return>
+</procedure>
+
+# Task
+
+<execute name="main">$ARGUMENTS</execute>
--- a/commands/draft.md
+++ b/commands/draft.md
@@ -0,0 +1,41 @@
+---
+allowed-tools: Glob, Grep, Read, LS, TodoWrite
+description: Draft a new specification document as single of truth for feature development.
+argument-hint: one line brief user requirement to deliver value
+---
+
+# Rule
+
+The `<execute>ARGUMENTS</execute>` will execute the main procedure.
+
+# Role
+
+You are a product owner to draft a new specification document as single of truth for feature development.
+
+# Context
+
+Current Time: !`date +"%Y-%m-%d %H:%M:%S %Z"`
+
+# Definition
+
+<procedure name="main">
+    <description>Draft a new specification document as single of truth for feature development.</description>
+    <parameters name="requirement">one line brief user requirement to deliver value</parameters>
+    <step>1. identity existing specification document or need to create a new one</step>
+    <condition if="existing specification document found">
+        <step>2. confirm with user to expend existing specification or create a new one use AskUserQuestion tool</step>
+        <return>use `/spec:clarify` command to update existing specification document</return>
+    </condition>
+    <step>3. active spec-scaffold skill to get manual for specification creation</step>
+    <step>4. follow the manual to create the specification document based on the given {requirement}</step>
+    <step>5. review the specification document for completeness and clarity</step>
+    <step>6. according to the manual to update roadmap & glossary</step>
+    <condition if="glossary conflicts found">
+        <step>7. use glossary document as highest priority to resolve conflicts</step>
+    </condition>
+    <return>path to the created specification document</return>
+</procedure>
+
+# Task
+
+<execute name="main">$ARGUMENTS</execute>
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,105 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:elct9620/claudekit:plugins/spec",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "ce9c9167d1d27214de2073a74604fe7ebdbd2b64",
+    "treeHash": "c5c51f99e86f148b123513793937ffb70a53479dcd3c757b3399746742c47fe0",
+    "generatedAt": "2025-11-28T10:16:45.387852Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "spec",
+    "description": "Spec-driven development plugin inspired by GitHub Spec Kit (Experimental)",
+    "version": "0.1.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "2280a7631f60a2e5ecbba5b52ee150398596557fa04729015f5f6b0066c811d2"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "1e15525c7c280229d04aac25f0a8c54fc6083abad90a6db5ad2b2ff3e5446edf"
+      },
+      {
+        "path": "commands/constitution.md",
+        "sha256": "0a3fefed9de3ea27839f9a5093a1c9573a4fde401c94bf41176dc0206b1e9a94"
+      },
+      {
+        "path": "commands/architecture.md",
+        "sha256": "5f17d32f38a8948a0a128f104c3a08d5d19a75c04aa354a14173ec985b7d7c03"
+      },
+      {
+        "path": "commands/draft.md",
+        "sha256": "77eacdb2d46cf2137558e2a47b447dd766cc6c66642c8543f1e561afe7006ef0"
+      },
+      {
+        "path": "commands/clarify.md",
+        "sha256": "024d3856a0bf2b640b7bb697cf306130e8d9e26208a9ca6cf6a8c8dc4f955307"
+      },
+      {
+        "path": "skills/spec-scaffold/SKILL.md",
+        "sha256": "d2181fa7942770fd5568f3b75820e2f1f759258593d6497167433bd3ccc131c1"
+      },
+      {
+        "path": "skills/spec-scaffold/references/specification.md",
+        "sha256": "751b06d053ba4670804f7a5ad06c605e70e08cff134eb2eef33a811231120f4d"
+      },
+      {
+        "path": "skills/spec-scaffold/references/constitution.md",
+        "sha256": "e162286a4419363621f11352915523c113686128742c832ef1c314e0a055d765"
+      },
+      {
+        "path": "skills/spec-scaffold/references/architecture.md",
+        "sha256": "18da7699c9f2232626e85c80e37ce333468939ec85293d959e9a02ee671369d4"
+      },
+      {
+        "path": "skills/spec-scaffold/references/glossary.md",
+        "sha256": "4c95a55cd7a6e6c7e88c38f095752f19c0a9fad0a35e3a9de65837465badb576"
+      },
+      {
+        "path": "skills/spec-scaffold/references/roadmap.md",
+        "sha256": "952c5b06a927639d58da250ea62f6347158da73111d9351daf64ab5d835fade2"
+      },
+      {
+        "path": "skills/spec-scaffold/templates/specification.md",
+        "sha256": "88a7c70ebf26b5e27361a8c457aeb0ec61012ffed2d245b09bfe8a557278c12a"
+      },
+      {
+        "path": "skills/spec-scaffold/templates/constitution.md",
+        "sha256": "a25c7f8dc4854041b2d69b0ee5278385aebdb8aaadcda44c21999175cf5a3c3b"
+      },
+      {
+        "path": "skills/spec-scaffold/templates/architecture.md",
+        "sha256": "e3dfc50e331b9d8d09d3b61918b75bdf8402884675853bb5d44ec9d271e6f385"
+      },
+      {
+        "path": "skills/spec-scaffold/templates/glossary.md",
+        "sha256": "c9ba1966855da55ab56bd00f0b7291c99aac6399b9b284f79dce9e1db06819f2"
+      },
+      {
+        "path": "skills/spec-scaffold/templates/roadmap.md",
+        "sha256": "85a3d3fa99ade5e26a896b403d3a76fca69a44a0d2f60a0d60f18af4fa8edbc4"
+      },
+      {
+        "path": "skills/spec-scaffold/templates/adr.md",
+        "sha256": "2de0eeb4161b4455d309995289fef7689c617f44edd3bd5da07d74e32ca83e90"
+      }
+    ],
+    "dirSha256": "c5c51f99e86f148b123513793937ffb70a53479dcd3c757b3399746742c47fe0"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
--- a/skills/spec-scaffold/SKILL.md
+++ b/skills/spec-scaffold/SKILL.md
@@ -0,0 +1,56 @@
+---
+name: spec-scaffold
+description: Process any SDD (Specification-Driven Development) operations related to creating or updating specification documents. Always use this skill when dealing with specifications, e.g. constitution, specification document, architecture-related documents, roadmap, glossary, etc.
+allowed-tools: Read, Grep, Glob, Explore, Bash(cp:*), TodoWrite
+---
+
+# Spec Scaffold
+
+## Instructions
+
+1. Identify the type of specification document is working on (e.g., constitution, architecture decision record).
+2. Read the manual and templates provided for the specific document type before proceeding.
+3. Making a plan to gather necessary information from the user or existing documentation to fill out the template.
+    - Use TodoWrite to outline the steps needed to complete the document.
+    - Ensure each steps in manual is covered in the plan.
+4. Take one of following actions to create/update the document
+    - No existing document: MUST use `cp [template_path] [destination_path]` to copy the template to the desired location.
+    - Existing document needs updates: Read the existing document, identify sections that need modification, and update them accordingly.
+5. According to the plan and manual, gather required information using AskUserQuestion tool if necessary.
+
+## Document Relationship
+
+Following are independent for each other, do not make references between them.
+
+- Constitution: The foundational document that outlines the project's purpose, governance, and decision-making processes.
+- Specification: Detailed descriptions of features, user stories, and acceptance criteria.
+- Architecture: Overview of the project's architecture, design patterns, and technology stack.
+
+Following are referenced by specification documents.
+
+- Glossary: A collection of terms and definitions used throughout the specifications to ensure consistency and clarity.
+
+Following are referenced by roadmaps.
+
+- Specification: Each feature or milestone in the roadmap should link to its corresponding specification document for detailed information.
+
+## Manual
+
+- [Constitution](./references/constitution.md): How to write a project constitution.
+- [Specification](./references/specification.md): How to write a specification document.
+- [Roadmap](./references/roadmap.md): How to use roadmaps to track project progress.
+- [Glossary](./references/glossary.md): The ubiquitous terms used in the project specifications.
+- [Architecture](./references/architecture.md): How to document architecture and design decisions.
+
+## Templates
+
+- [constitution.md](./templates/constitution.md): Constitution template should be used to create project constitutions.
+- [specification.md](./templates/specification.md): Specification template should be used to create specification documents.
+- [roadmap.md](./templates/roadmap.md): Roadmap template should be used to initiate project roadmaps.
+- [glossary.md](./templates/glossary.md): Glossary template should be used to create project glossaries.
+- [architecture.md](./templates/architecture.md): Architecture template should be used to document architecture decisions.
+- [adr.md](./templates/adr.md): Architecture Decision Record (ADR) template should be used to document specific architecture decisions.
+
+## References
+
+- [GitHub's Specification-Driven Development](https://github.com/github/spec-kit/blob/main/spec-driven.md)
--- a/skills/spec-scaffold/references/architecture.md
+++ b/skills/spec-scaffold/references/architecture.md
@@ -0,0 +1,102 @@
+Architecture Manual
+===
+
+You are documenting the architecture and design decisions of a software project. This is a TEMPLATE containing placeholders in square brackets (e.g. `[STACK_NAME]`, `[PATTERN_NAME]`, etc.)
+
+## Mission
+
+- Ensure `ARCHITECTURE.md` provides a updated and comprehensive overview of the project's architecture.
+- Record significant architecture decisions using Architecture Decision Records (ADRs).
+- Maintain clarity and consistency architecture choices and patterns.
+
+## Directory Structure
+
+The architecture documentation is organized as follows:
+
+```
+|- docs/
+    |- ADRs/                # Architecture Decision Records
+        |- [date]-[decision-title].md # Individual ADR files
+    |- ARCHITECTURE.md          # Main architecture document
+```
+
+## Steps (Strict Order)
+
+### 1. Prepare Architecture Document
+
+Use `cp` command to copy the architecture template from `./templates/architecture.md` to `docs/ARCHITECTURE.md` if it does not already exist.
+
+### 2. Copy Decision Record Template
+
+Use `cp` command to copy the ADR template from `./templates/adr.md` to `docs/ADRs/[date]-[decision-title].md` for each significant architecture decision that needs to be documented.
+
+**NOTE**: The initial record should document technology stack choices made for the project and structure of the codebase which is minimal requirement for `ARCHITECTURE.md`.
+
+### 3. Read Existing Architecture Document
+
+Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]` in the template. Create a series of questions to ask the user for each decision is made.
+
+- `DATE`: Use today's date in `YYYY-MM-DD` format.
+- `DECISION_TITLE`: A concise title summarizing the decision (e.g., `use-redis-caching`).
+
+### 4. Gather Required Information
+
+Ask user for each placeholder to clarify the architecture decisions and patterns used in the project. Ask questions one by one and infer next question based on user's answers.
+
+NEVER make assumptions about architecture choices without explicit answers from the user.
+
+Example questions to ask the user:
+
+```
+Q: What programming languages are used in the project?
+- A: [User's Specified Languages]
+
+Q: Will use any specific frameworks or libraries?
+- A: Ruby on Rails # infer from user's answer
+- B: Other: [User's Specified Frameworks]
+
+Q: What database systems are utilized?
+# ...
+```
+
+### 5. Draft Decision Record
+
+Update decision record content one by one according to the user's answers and inferred information.
+
+- Replace each placeholder in the ADR template with the relevant information.
+- Preserve the heading hierarchy and formatting of the template.
+- Ensure clarity and completeness of each section in the ADR.
+
+### 6. Validate Decision Record
+
+- Ensure no placeholder tokens remain in the ADR.
+- Check for consistency and accuracy of the documented decisions.
+- Confirm with the user that the ADR accurately reflects their architecture choices.
+- `DATE`: Use today's date in `YYYY-MM-DD` format.
+
+### 7. Finalize Decision Record
+
+Save the completed ADR in the `docs/ADRs/` directory with the appropriate filename.
+
+### 8. Synchronize Architecture Document
+
+Update `docs/ARCHITECTURE.md` to reflect the newly created ADRs and any changes in architecture decisions.
+
+- The architecture document is aggregated state of all ADRs, ensure consistency between them.
+- The newer ADRs is higher priority than older ones.
+- `ARCHITECTURE.md` should provide a high-level overview of the architecture, do not explain every detail in ADRs again.
+- Ensure heading hierarchy and formatting is preserved and must same as the template.
+
+### 9. Summarize Changes
+
+- Provide a summary of the changes made to the architecture documentation.
+- Highlight any significant decisions or patterns that were added or modified.
+- The path of newly created ADR file.
+
+## Constraints
+
+- Create only one ADR per significant architecture decision.
+- Working on one ADR at a time, do not mix multiple decisions in a single record.
+- Always update `ARCHITECTURE.md` after finalizing each ADR.
+- Do not make any decisions without explicit confirmation from the user.
+
--- a/skills/spec-scaffold/references/constitution.md
+++ b/skills/spec-scaffold/references/constitution.md
@@ -0,0 +1,84 @@
+Constitution Manual
+===
+
+You are updating the project constitution at `docs/CONSTITUTION.md`. This is a TEMPLATE contatining placeholders in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`, etc.)
+
+## Mission
+
+- Collect/derive concrete values
+- Fill template precisely
+- Propagate or amendments across dependent artifacts
+
+## Steps (Strict Order)
+
+### 1. Read Existing Constitution Template
+
+Identity every placeholder token of the form `[ALL_CAPS_IDENTIFIER]` in the template. Create a todo list of required information to fill in each placeholder.
+
+**IMPORTANT**: The principles may less or more than defined in the template. Follow the user's instructions to fit the template accordingly.
+
+## 2. Gather Required Information
+
+If user already provided the necessary information, use it directly. Otherwise, infer from existing project documentation (e.g. README, docs, prior constitution versions if embedded) if possible.
+
+- `RATIFICATION_DATE` is the original date adopted, if unknown ask or mark as "TODO"
+- `LAST_AMENDMENT_DATE` is today when making changes, otherwise keep previous date
+- `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+  - MAJOR: Backward-incompatible changes applied to principles or governance
+  - MINOR: New principle/section added or guideance expanded without conflicting prior rules
+  - PATCH: Clarifications, typos, non-semantics refinements
+
+If version bump is unclear, propose reasoning before finalizing. Ask user to make each information explicit if cannot be inferred.
+
+## 3. Draft Constitution Content
+
+- Replace each placeholder with concrete text without any placeholders remaining.
+- Preserve heading hierarchy and comments can be removed unless needed for clarity.
+- Ensure each Principle section: succinctname line, paragraph (or bullet list) capturing non-negotiable rules, explict rationale if obvious.
+- Ensure Governance section listed amendment procedure, versioning policy, and compliance expectations.
+
+## 4. Consistency Check
+
+Read any guidance documents (e.g. `README.md`, `CONTRIBUTING.md`, or agent-specific guidance files if exist) and update the references to the principles changed.
+
+### 5. Produce Amendedment Report
+
+Append after the YAML frontmatter as an HTML comment after update.
+
+- Version Changes: `old -> new` (e.g. `2.0.0 -> 2.1.0`)
+- Bump Rationale: explain why made the version change
+- List of modified principles
+- List of added sections
+- List of removed sections
+- Follow-up TODOS: if any placeholders could not be filled
+
+### 7. Review
+
+- Ensure no placeholders remain without any reasonable explanation.
+- Version information is matched amendment report.
+- Dates ISO format (YYYY-MM-DD).
+- Principles are declarative, testable, and free of vague language (replace "should" with MUST/SHOULD rationale where apparopriate).
+
+### 8. Finalize
+
+Save the updated constitution back to `docs/CONSTITUTION.md` (overwrite existing file).
+
+### 9. Summarize Changes
+
+- New version and rationale
+- Any follow-up actions needed
+
+## Formatting Guidelines
+
+- Use Markdown headings exactly as in the template. (do not promote/demote heading levels)
+- Wrap long lines to keep readability (< 100 characters) but avoid breaking enforced breaks (e.g., lists, code blocks).
+- Keep single blank line between sections for clarity.
+- Avoid trailing whitespace.
+
+## Modification Rules
+
+No matter partial or full updates, always follow steps above to ensure consistency and completeness. Never create a new constitution, always operate on the existing `docs/CONSTITUTION.md` file.
+
+## Missing Information
+
+Any critical missing information (e.g. ratification date, principle details) always use `TODO(FIELD_NAME): explanation` format to indicate what is missing and why.
--- a/skills/spec-scaffold/references/glossary.md
+++ b/skills/spec-scaffold/references/glossary.md
@@ -0,0 +1,57 @@
+Glossary Manual
+===
+
+You are updating the project's glossary document located at `docs/GLOSSARY.md`. This document defines key terms used throughout the project.
+
+## Mission
+
+- Keep the glossary up-to-date with the latest terms and definitions.
+- Help team members understand the terminology used in the project and ensure consistent usage.
+
+## Steps (Strict Order)
+
+### 1. Copy Template
+
+Use `cp` command to copy the roadmap template from `./templates/roadmap.md` to `docs/ROADMAP.md` if the roadmap does not exist yet.
+
+### 2. Identify Terms
+
+Check the terms that need to be added or updated in the glossary. For each term, gather the following information:
+
+- `TERM_NAME`: The name of the term is used in the project.
+- `DEFINITION`: A brief definition of what the term means.
+
+
+### 3. Update Glossary Table
+
+Read the existing `docs/GLOSSARY.md` file and locate the glossary table. For each term identified in the previous step, do the following:
+
+If the term does not exist, add a new row to the table with the gathered information. If the term already exists in the table, ask the user to clarify the definition.
+
+Example to clarify:
+
+```
+Q: The term "User" has different meanings in different contexts. Could you please provide a clear definition for "User" in the context of this project?
+- A: Renames to "End User", defined as "The individual who ultimately uses or is intended to use a product or service."
+- B: Create new domain "System User", defined as "An individual who interacts with the system for administrative or maintenance purposes."
+- C: Keep the existing definition as is.
+- D: Other: [User specifies]
+```
+
+### 4. Review
+
+After updating the roadmap, review the entire document to ensure accuracy and completeness. Make sure all features are correctly listed with their current statuses.
+
+### 5. Finalize
+
+Summarize the changes made to the roadmap and inform the user about the updates.
+
+## Additional Sections
+
+All terms  is listed under the "Core" section by default. Only additional sections is defined by user specifically to scope a particular domain or module within the project. Do not create new sections unless user specifically requests it.
+
+If the project structure indicates distinct modules or domains, you may suggest creating additional sections to better organize the features.
+
+## Term Update Guidelines
+
+NEVER make changes to existing term definitions without explicit user confirmation. Always seek clarification from the user before modifying any definitions.
--- a/skills/spec-scaffold/references/roadmap.md
+++ b/skills/spec-scaffold/references/roadmap.md
@@ -0,0 +1,58 @@
+Roadmap Manual
+===
+
+You are updating the project's roadmap document located at `docs/ROADMAP.md`. This document tracks the progress of various features in the project.
+
+## Mission
+
+- Keep the roadmap up-to-date with the latest feature statuses.
+- As index to view all features and their progress at a glance.
+
+## Steps (Strict Order)
+
+### 1. Copy Template
+
+Use `cp` command to copy the roadmap template from `./templates/roadmap.md` to `docs/ROADMAP.md` if the roadmap does not exist yet.
+
+### 2. Identify Features
+
+Check the features that need to be added or updated in the roadmap. For each feature, gather the following information:
+
+- `FEATURE_NAME`: A concise name for the feature (2-4 words).
+- `DESCRIPTION`: A brief description of what the feature entails.
+- `STATUS`: The current status of the feature. Possible values are:
+  - Planned
+  - In Progress
+  - Completed
+- `UPDATED_AT`: The date when the feature was last updated (format: YYYY-MM-DD).
+
+**NOTE**: The roadmap usually updated when a feature is added, modified, or completed. But you can also update it based on user's specific instructions.
+
+### 3. Update Roadmap Table
+
+Read the existing `docs/ROADMAP.md` file and locate the roadmap table. For each feature identified in the previous step, do the following:
+
+- If the feature already exists in the table, update its `DESCRIPTION`, `STATUS`, and `UPDATED_AT` fields.
+- If the feature does not exist, add a new row to the table with the gathered information.
+
+If `UPDATED_AT` is not mismatched, usually means the feature is changed and mark it as "In Progress" by default.
+
+### 4. Review
+
+After updating the roadmap, review the entire document to ensure accuracy and completeness. Make sure all features are correctly listed with their current statuses.
+
+### 5. Finalize
+
+Summarize the changes made to the roadmap and inform the user about the updates.
+
+## Additional Sections
+
+All features is listed under the "Core" section by default. Only additional sections is defined by user specifically to scope a particular domain or module within the project. Do not create new sections unless user specifically requests it.
+
+If the project structure indicates distinct modules or domains, you may suggest creating additional sections to better organize the features.
+
+## Status Definitions
+
+- Planned: No any code implementation yet.
+- In Progress: Code implementation is ongoing or new scenarios are being added/modified.
+- Completed: Feature implementation is done and no more changes expected.
--- a/skills/spec-scaffold/references/specification.md
+++ b/skills/spec-scaffold/references/specification.md
@@ -0,0 +1,171 @@
+Specification Manual
+===
+
+You are updating a specification document in `docs/features/`. This is a TEMPLATE containing placeholders in square brackets (e.g. `[FEATURE_NAME]`, `[BRIEF_TITLE]`, etc.)
+
+## Mission
+
+- Create clear, testable user stories and acceptance criteria
+- Clearify **WHAT** user needs and **WHY**, not **HOW**
+- Avoid any technical information or implementation details
+
+## Directory Structure
+
+The specification documents have two modes:
+
+- Mini: For simple and small projects with limited features
+- Full: For complex projects with multiple features and detailed requirements
+
+Dependent on the project's status, use different directory structures:
+
+```
+|- docs/
+    |- features/
+        |- [feature_name]/          # Full specification mode
+            |- specification.md
+        |- [feature_name].spec.md        # Mini specification mode
+```
+
+## Steps (Strict Order)
+
+### 1. Copy Template
+
+Use `cp` command to copy the specification template from `./templates/specification.md` to the appropriate location based on the chosen mode (mini or full).
+
+### 2. Decide Feature Name
+
+According to the user's instructions, decide 2 ~ 4 words concise feature name to represent the feature being specified.
+
+- "I want to add user authentication" -> `user-auth`
+- "Please specify the payment processing feature" -> `payment-processing`
+- "We need a search functionality" -> `search-functionality`
+
+**IMPORTANT**: The user may specify an existing feature, confirm with the user to expend existing specification or create a new one.
+
+### 3. Read Existing Specification Template
+
+Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]` in the template. List unclarified items to user as questions for clarification.
+
+According the user's instructions, infer the brief information to fill in each placeholder.
+
+Interact with the user to clarify each user story and acceptance criteria, ensuring they are satisfied with actual needs.
+
+- `CREATION_DATE`: applied today's date when first creating the specification,
+- `LAST_UPDATED_DATE` is today when making changes, use `CREATION_DATE` if first created.
+- `BRIEF_DESCRIPTION`: The original instruction from the user about the feature, do not modify it.
+
+Update the specification content according to the user's answers and inferred information.
+
+### 4. Gather Required Information
+
+Based on the "draft" or "clarify" mode in current context, use different strategies to gather required information.
+
+- Draft Mode: Suggest user stories and confirm with the user.
+- Clarify Mode: Ask user to clarify each user story explicitly.
+
+Example draft questions:
+
+```
+Q: Does the authentication feature allow users to sign up with email and password?
+- A: Yes.
+- B: No, only social logins.
+- C: No, only email/password.
+- D: Other: [User specifies]
+```
+
+Example clarify questions:
+
+```
+Q: As end user, what is password validation rules when signing up?
+- A: Minimum 8 characters, at least one uppercase letter, one number, and one special character.
+- B: Minimum 6 characters, no other restrictions.
+- C: Other: [User specifies]
+```
+
+Gather information one by one until user explicitly answer "STOP". Keep asking until no unclarified items remain or out of context.
+
+### 5. Draft Specification Content
+
+Update specification content one by one based on gathered information, do not apply all changes at once.
+
+- Replace each placeholder with concrete text without any placeholders remaining.
+- Preserve heading hierarchy and comments can be removed unless needed for clarity.
+- Ensure each User Story has a brief title, priority explanation, and value delivered.
+- Use Gherkin style to define acceptance criteria for each user story which can reproduce expected outcomes.
+
+**IMPORTANT**: DO NOT fill validation checklist here, it should be done after finalizing the specification.
+
+### 6. Review
+
+- Ensure no placeholders remain without any reasonable explanation.
+- Dates ISO format (YYYY-MM-DD).
+- User stories are clear, independent, and testable without implementation details.
+- `LAST_UPDATED_DATE` is correct.
+
+### 6. Finalize
+
+Save the updated specification back to `docs/features/[feature_name]/specification.md` (full mode) or `docs/features/[feature_name].spec.md` (mini mode).
+
+> If feature mode cannot infer from existing files, ask the user to confirm which mode to use.
+
+### 7. Quality Validation
+
+Fill following checks and use HTML comments to append after the specification content. Replace existing comment if any.
+
+```
+<!--
+  Specification Quality Validation
+  ===
+
+  **Checked On:** [CHECK_DATE]
+
+  ## Content Quality
+
+  - [ ] No implementation details present (e.g., code snippets, technical jargon, framework, storage, etc.)
+  - [ ] Focus on delivering user value and outcomes
+  - [ ] Write for non-technical stakeholders
+  - [ ] All mandatory sections completed
+
+  ## Readability and Clarity
+
+  - [ ] User stories can explain operational needs clearly
+  - [ ] No implementation assumptions made
+  - [ ] All scenarios have clear acceptance criteria
+  - [ ] The outcomes are measurable and verifiable (e.g., count, response time, performance indicators, etc.)
+
+  ## Notes
+
+  - Items marked unchecked require revision.
+-->
+```
+
+### 8. Validate Quality
+
+Read the specification file and fill the checklist in the HTML comment accordingly. Then update the quality validation section append after the specification content.
+
+- If all checks are passed, mark all checkboxes as done.
+- If any check fails, leave it unchecked and provide notes on what needs to be revised.
+
+Ask the user to clarify failed checks and make necessary revisions to the specification document.
+
+### 9. Update Roadmap and Glossary
+
+- The roadmap located at `docs/ROADMAP.md` should be updated to reflect the new or modified feature specification. Read roadmap manual for detailed steps.
+- The glossary located at `docs/GLOSSARY.md` should be updated if any new terms are introduced in the specification. Read glossary manual for detailed steps.
+
+### 10. Summarize Changes
+
+- New feature name and brief description
+- Key user stories added or modified
+- Any outstanding questions for the user
+
+## Formatting Guidelines
+
+- Use Markdown syntax for headings, lists, and code blocks. (do not promote/demote heading levels)
+- Wrap long lines to keep readability (< 100 characters) but avoid breaking enforced breaks (e.g., lists, code blocks).
+- Keep single blank line between sections for clarity.
+- Use Gherkin syntax for acceptance criteria.
+
+## Modification Rules
+
+No matter partial or full updates, always follow steps above to ensure consistency and completeness. Ensure the validation is always processed after any modification and the checklist is up-to-date.
--- a/skills/spec-scaffold/templates/adr.md
+++ b/skills/spec-scaffold/templates/adr.md
@@ -0,0 +1,97 @@
+[DATE] - [ARCHITECTURE_DECISION_NAME]
+===
+
+## Motivation
+
+<!--
+  Motivation Example
+  ===
+
+  Our database is heavy on read operations than write operations. After users is growing, we need to optimize read performance to ensure low latency and high availability.
+
+  ### Stackholder
+
+    - **Users**: Expect fast response times when accessing data.
+    - **Developers**: Need to maintain and scale the database efficiently.
+
+  ### Problem Statement
+
+    The current database setup is struggling to handle the increasing read load, leading to slow response times and potential downtime during peak usage periods.
+-->
+
+[DESCRIPTION_OF_THE_DECISION_PROBLEM]
+
+### Stakeholders
+
+- [STAKEHOLDER_1]: [ROLE_AND_INTEREST]
+- [STAKEHOLDER_2]: [ROLE_AND_INTEREST]
+
+### Problem Statement
+
+[DETAILED_DESCRIPTION_OF_THE_PROBLEM]
+
+## Proposed Solution
+
+<!--
+    Proposed Solution Example
+    ===
+
+    We have considered the following solutions to address the read performance issue:
+
+    ### Redis Caching
+
+    Implementing Redis as an in-memory caching layer to store frequently accessed data. This will reduce the load on the primary database and speed up read operations.
+
+    ### Read Replicas
+
+    Setting up read replicas of the primary database to distribute read traffic. This will help in balancing the load and improving read performance.
+-->
+
+### [SOLUTION_NAME]
+
+[DESCRIPTION_OF_SOLUTION]
+
+### [SOLUTION_NAME]
+
+[DESCRIPTION_OF_SOLUTION]
+
+## Decision
+
+<!--
+    Decision Example
+    ===
+
+    After evaluating the proposed solutions, we have decided to implement Redis Caching because it provides a significant performance boost for read operations with relatively low complexity and cost.
+-->
+
+After evaluating the proposed solutions, we have decided to implement [CHOSEN_SOLUTION_NAME] because [REASON_FOR_CHOICE].
+
+## Consequences
+
+<!--
+
+    Consequences Example
+    ===
+
+    Implementing Redis Caching will have the following consequences:
+
+    ### Positive Consequences
+
+    - Improved read performance, leading to faster response times for users.
+    - Reduced load on the primary database, enhancing overall system stability.
+
+    ### Negative Consequences
+
+    - Additional infrastructure to manage and maintain (Redis server).
+    - Potential data consistency issues if cache is not properly invalidated.
+-->
+
+### Positive Consequences
+
+- [POSITIVE_CONSEQUENCE_1]
+- [POSITIVE_CONSEQUENCE_2]
+
+### Negative Consequences
+
+- [NEGATIVE_CONSEQUENCE_1]
+- [NEGATIVE_CONSEQUENCE_2]
--- a/skills/spec-scaffold/templates/architecture.md
+++ b/skills/spec-scaffold/templates/architecture.md
@@ -0,0 +1,82 @@
+Architecture
+===
+
+This document outlines the high-level architecture and design for the project.
+
+## Technology Stack
+
+<!--
+    Technology Stack Example
+    ===
+
+    - **Ruby**: Primarily used for backend development.
+    - **Ruby on Rails**: Web application framework for building the backend services.
+    - **PostgreSQL**: Relational database for data storage.
+    - **StimulusJS**: JavaScript framework for enhancing frontend interactivity.
+    - **Amazon Web Services (AWS)**: Cloud platform for hosting and deploying the application.
+    - **RDS**: Managed relational database service provided by AWS.
+
+    Replace the above with actual technologies and versions used in your project.
+-->
+
+- [STACK_NAME]: [REQUIREMENT_DESCRIPTION]
+- [STACK_NAME]: [REQUIREMENT_DESCRIPTION]
+
+## Structure
+
+<!--
+    Replace the example structure below with the actual directory structure of your project.
+-->
+
+```
+|- app/
+    |- controllers/       # Controllers for handling requests
+    |- models/            # Data models
+    |- views/             # View templates
+|- lib/                 # Application-specific libraries
+    |- domains/         # Domain-specific logic
+        |- [DOMAIN_NAME]/  # Replace with actual domain names
+            |- services/   # Domain services
+            |- repositories/ # Data access layer
+|- config/              # Configuration files
+    |- routes.rb        # Application routes
+```
+
+## [PATTERN_NAME]
+
+[PATTERN_EXPLANATION]
+
+<!--
+   Add more sections related to architecture patterns, design decisions, and rationale as needed.
+
+   Pattern Example
+   ===
+
+   ## Service-Oriented Architecture (SOA)
+
+   This project follows a Service-Oriented Architecture (SOA) pattern to promote modularity and scalability. Each domain is encapsulated within its own service, allowing for independent development and deployment.
+
+   ```ruby
+   # path: lib/domains/notification/services/send_email_service.rb
+    module Domains
+      module Notification
+         module Services
+            class SendEmailService
+              def initialize(user, message)
+                 @user = user
+                 @message = message
+              end
+
+              def call
+                 # Logic to send email
+              end
+            end
+         end
+      end
+    end
+   ```
+
+   - Use `#call` method to execute the service.
+   - Naming convention: `[Action]Service` for service classes.
+   - Place services under `lib/domains/[DOMAIN_NAME]/services/`.
+-->
--- a/skills/spec-scaffold/templates/constitution.md
+++ b/skills/spec-scaffold/templates/constitution.md
@@ -0,0 +1,55 @@
+---
+version: [CONSTITUTION_VERSION]
+ratified: [RATIFICATION_DATE]
+lastAmended: [LAST_AMENDMENT_DATE]
+---
+<!-- Example: version: 2.1.1, ratified: 2025-10-21, lastAmended: 2025-10-21 -->
+<!--
+  AMENDMENT REPORT
+  ===
+
+  [SUMMARY_OF_CHANGES]
+-->
+
+# [PROJECT_NAME] Constitution
+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+
+## Principles
+
+### [PRINCIPLE_1_NAME]
+<!-- Example: I. Test-First (NON-NEGOTIABLE) -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+
+### [PRINCIPLE_2_NAME]
+<!-- Example: II. Integration Testing -->
+[PRINCIPLE_2_DESCRIPTION]
+<!-- Example: Focus areas requiring integration tests: user-facing oriented over unit tests, making sure new features work end-to-end -->
+
+### [PRINCIPLE_3_NAME]
+<!-- Example: III. Simplicity and YAGNI -->
+[PRINCIPLE_3_DESCRIPTION]
+<!-- Example: Start simple and stupid, only implement what is necessary now; Incrementally enhance as needed -->
+
+### [PRINCIPLE_4_NAME]
+<!-- Example: IV. Cohesion over Coupling -->
+[PRINCIPLE_4_DESCRIPTION]
+<!-- Example: Group related functionality together as modules, libraries, or services; Use simple and clear interfaces for interaction -->
+
+### [PRINCIPLE_5_NAME]
+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Convention over Configuration -->
+[PRINCIPLE_5_DESCRIPTION]
+<!-- Example: Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: minimize configuration files by following conventions -->
+
+## [SECTION_2_NAME]
+<!-- Example: Other Requirements, Technical Standards, etc. -->
+<!-- Omit if not applicable or not needed -->
+
+[SECTION_2_CONTENT]
+<!-- Example: Performance requirements, security standards, coding style guidelines, etc. -->
+
+## Governance
+<!-- Example: Approval processes, review requirements, compliance checks, etc. -->
+
+[GOVERNANCE_RULES]
+<!-- Example: All changes must be reviewed by at least two team members; Self-reviews before submission; All changes must pass CI tests before merging, the security review for sensitive modules, etc. -->
--- a/skills/spec-scaffold/templates/glossary.md
+++ b/skills/spec-scaffold/templates/glossary.md
@@ -0,0 +1,28 @@
+Glossary
+===
+
+# Core
+
+<!--
+  Glossary Table Template
+  ===
+
+  | Term         | Definition                                      |
+  |--------------|-------------------------------------------------|
+  | User         | An individual who interacts with the system.    |
+
+
+-->
+
+| Term         | Definition                                      |
+|--------------|-------------------------------------------------|
+| [TERM]       | [DEFINITION]                                    |
+
+<!--
+  Additional Sections
+  ===
+
+  The additional sections is designed to domain-specific features. Each section should scope a particular domain or module within the project.
+  Do not create new sections unless user specifically requests it.
+  This usually happens in large projects with multiple domains, e.g. `User` has different meanings in `Authentication` and `Analytics` domains.
+-->
--- a/skills/spec-scaffold/templates/roadmap.md
+++ b/skills/spec-scaffold/templates/roadmap.md
@@ -0,0 +1,31 @@
+Roadmap
+===
+
+# Core
+
+<!--
+  Roadmap Table Template
+  ===
+
+  | Updated At | Feature Name                                        | Description                                     | Status      |
+  |------------|-----------------------------------------------------|-------------------------------------------------|-------------|
+  | 2024-01-15 | [User Authentication](./features/user-auth.spec.md) | Implement user login and registration features. | In Progress |
+  | 2024-02-10 | [Data Export](./features/data-export/spec.md)       | Allow users to export their data in CSV format. | Planned     |
+
+  Available Status:
+  - Planned: No any code implementation yet.
+  - In Progress: Code implementation is ongoing or new scenarios are being added/modified.
+  - Completed: Feature implementation is done and no more changes expected.
+-->
+
+| Updated At   | Feature Name   | Description   | Status   |
+|--------------|----------------|---------------|----------|
+| [UPDATED_AT] | [FEATURE_NAME] | [DESCRIPTION] | [STATUS] |
+
+<!--
+  Additional Sections
+  ===
+
+  The additional sections is designed to domain-specific features. Each section should scope a particular domain or module within the project.
+  Do not create new sections unless user specifically requests it.
+-->
--- a/skills/spec-scaffold/templates/specification.md
+++ b/skills/spec-scaffold/templates/specification.md
@@ -0,0 +1,128 @@
+[FEATURE NAME]
+===
+
+**Created On:** [CREATION_DATE]
+**Last Updated:** [LAST_UPDATED_DATE]
+**Brief Description:** [BRIEF_DESCRIPTION]
+
+## Purpose
+
+<!--
+  Explain why this feature is needed and what problem it solves. And what value it delivers to users.
+-->
+
+[PURPOSE_DESCRIPTION]
+
+## User Stories and Acceptance Criteria **(mandatory)**
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each story should be INDEPENDENTLY TESTABLE - meaning implementing ONE story at a time,
+  you should focus on delivering viable MVP (Minimum Viable Product) to produce value early and often.
+
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+<!--
+  User Story Template
+  ===
+
+  ### User Story X - [BRIEF_TITLE] (Priority: PX)
+    **Priority Explanation:** [Explain why this priority was assigned]
+    **Value Deliveried:** [Describe how this story delivers value independently with testable outcomes]
+
+    ```gherkin
+    A brief description of the user story.
+
+    Scenario: [Title of the scenario]
+      When [event occurs]
+      Then [ensure some outcomes]
+
+    Rule: [If any specific business rules apply which group multiple scenarios]
+
+      Scenario: [Title of another scenario]
+        Given [initial context]
+        When [event occurs]
+        Then [ensure some outcomes]
+    ```
+
+    - Use `Background:` to define any common preconditions if needed.
+    - Use `Rule:` to define any specific business rules if needed.
+    - Use `Examples:` to provide data tables for scenarios if needed.
+--->
+
+### User Story 1 - [BRIEF_TITLE] (Priority: P1)
+
+**Priority Explanation:** [Explain why this priority was assigned]
+**Value Deliveried:** [Describe how this story delivers value independently with testable outcomes]
+
+<!--
+ Use Gherkin style to define acceptance criteria for the user story.
+-->
+
+```gherkin
+A brief description of the user story.
+
+Background:
+  Given [initial context]
+  And [more initial context]
+
+Scenario: [Title of the scenario]
+  When [event occurs]
+  Then [ensure some outcomes]
+
+Scenario: [Title of another scenario]
+  Given [initial context]
+  When [event occurs]
+  Then [ensure some outcomes]
+```
+
+---
+
+### User Story 2 - [BRIEF_TITLE] (Priority: P2)
+
+**Priority Explanation:** [Explain why this priority was assigned]
+**Value Deliveried:** [Describe how this story delivers value independently with testable outcomes]
+
+```gherkin
+A brief description of the user story.
+
+Scenario: [Title of the scenario]
+  When [event occurs]
+  Then [ensure some outcomes]
+```
+
+---
+
+### User Story 3 - [BRIEF_TITLE] (Priority: P3)
+
+**Priority Explanation:** [Explain why this priority was assigned]
+**Value Deliveried:** [Describe how this story delivers value independently with testable outcomes]
+
+```gherkin
+A brief description of the user story.
+
+Scenario: [Title of the scenario]
+  Given [initial context]
+  When [event occurs]
+  Then [ensure some outcomes]
+```
+
+---
+
+[Add more user stories as needed, following the same format]
+
+## Unclarified Items
+
+<!--
+  IMPORTANT: This section only include items which user allowed to be left unclear after asking for clarifications.
+  The edge cases not covered by existing information should be explicitly listed here for future resolution.
+-->
+
+- [NAME_OF_ITEM]: explanation of what is unclear and why.
+- [NAME_OF_ITEM]: explanation of what is unclear and why.