commit 92ace25b48a8f50572b7c42725523f63650b3cfe Author: Zhongwei Li Date: Sat Nov 29 18:25:19 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..2958892 --- /dev/null +++ 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" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..bf0f8ca --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# spec + +Spec-driven development plugin inspired by GitHub Spec Kit (Experimental) diff --git a/commands/architecture.md b/commands/architecture.md new file mode 100644 index 0000000..a331b47 --- /dev/null +++ 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 `ARGUMENTS` 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 + + + Draft architecture document or create architecture decision records (ADRs) to document significant architecture decisions. + brief description of architecture decision to document + 1. identity existing architecture document at docs/ARCHITECTURE.md + 2. active spec-scaffold skill to get manual for architecture documentation + + 3. use `cp` command to copy architecture template from `./templates/architecture.md` to `docs/ARCHITECTURE.md` + 4. create initial ADR to document technology stack choices and codebase structure + path to the created architecture document + + 5. follow the manual to draft a new ADR for the architecture decision based on the given {description} + 6. review the ADR for completeness and clarity + path to the created ADR document + + +# Task + +$ARGUMENTS diff --git a/commands/clarify.md b/commands/clarify.md new file mode 100644 index 0000000..8b6f2fc --- /dev/null +++ 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 `ARGUMENTS` 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 + + + Update existing specification document to clarify user requirements. + feature_name to clarify in the specification document + clarification details to include in the specification document + 1. identity existing specification document + 3. active spec-scaffold skill to get manual for specification clarification + 4. follow the manual to create the specification document based on the given {feature_name} and {clarification_details} + 5. review the specification document for completeness and clarity + 6. according to the manual to update roadmap & glossary + + 7. use glossary document as highest priority to resolve conflicts + + path to the updated specification document + + +# Task + +$ARGUMENTS diff --git a/commands/constitution.md b/commands/constitution.md new file mode 100644 index 0000000..cc98dc5 --- /dev/null +++ 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 `ARGUMENTS` 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 + + + Create or update the project constitution document + An optional brief principles to apply to this project constitution + 1. active spec-scaffold skill to get manual for constitution creation + 2. follow the manual to create or update the constitution document + 3. review the constitution document for completeness and clarity + Path to the created or updated constitution document + + +# Task + +$ARGUMENTS diff --git a/commands/draft.md b/commands/draft.md new file mode 100644 index 0000000..e2d9d21 --- /dev/null +++ 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 `ARGUMENTS` 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 + + + Draft a new specification document as single of truth for feature development. + one line brief user requirement to deliver value + 1. identity existing specification document or need to create a new one + + 2. confirm with user to expend existing specification or create a new one use AskUserQuestion tool + use `/spec:clarify` command to update existing specification document + + 3. active spec-scaffold skill to get manual for specification creation + 4. follow the manual to create the specification document based on the given {requirement} + 5. review the specification document for completeness and clarity + 6. according to the manual to update roadmap & glossary + + 7. use glossary document as highest priority to resolve conflicts + + path to the created specification document + + +# Task + +$ARGUMENTS diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..461027f --- /dev/null +++ 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": [] + } +} \ No newline at end of file diff --git a/skills/spec-scaffold/SKILL.md b/skills/spec-scaffold/SKILL.md new file mode 100644 index 0000000..82b538e --- /dev/null +++ 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) diff --git a/skills/spec-scaffold/references/architecture.md b/skills/spec-scaffold/references/architecture.md new file mode 100644 index 0000000..9f7c6da --- /dev/null +++ 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. + diff --git a/skills/spec-scaffold/references/constitution.md b/skills/spec-scaffold/references/constitution.md new file mode 100644 index 0000000..32782b2 --- /dev/null +++ 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. diff --git a/skills/spec-scaffold/references/glossary.md b/skills/spec-scaffold/references/glossary.md new file mode 100644 index 0000000..78a3f89 --- /dev/null +++ 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. diff --git a/skills/spec-scaffold/references/roadmap.md b/skills/spec-scaffold/references/roadmap.md new file mode 100644 index 0000000..be764ab --- /dev/null +++ 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. diff --git a/skills/spec-scaffold/references/specification.md b/skills/spec-scaffold/references/specification.md new file mode 100644 index 0000000..2a9eacb --- /dev/null +++ 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. + +``` + +``` + +### 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. diff --git a/skills/spec-scaffold/templates/adr.md b/skills/spec-scaffold/templates/adr.md new file mode 100644 index 0000000..3e0ba71 --- /dev/null +++ b/skills/spec-scaffold/templates/adr.md @@ -0,0 +1,97 @@ +[DATE] - [ARCHITECTURE_DECISION_NAME] +=== + +## Motivation + + + +[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 + + + +### [SOLUTION_NAME] + +[DESCRIPTION_OF_SOLUTION] + +### [SOLUTION_NAME] + +[DESCRIPTION_OF_SOLUTION] + +## Decision + + + +After evaluating the proposed solutions, we have decided to implement [CHOSEN_SOLUTION_NAME] because [REASON_FOR_CHOICE]. + +## Consequences + + + +### Positive Consequences + +- [POSITIVE_CONSEQUENCE_1] +- [POSITIVE_CONSEQUENCE_2] + +### Negative Consequences + +- [NEGATIVE_CONSEQUENCE_1] +- [NEGATIVE_CONSEQUENCE_2] diff --git a/skills/spec-scaffold/templates/architecture.md b/skills/spec-scaffold/templates/architecture.md new file mode 100644 index 0000000..9d383da --- /dev/null +++ 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 + + + +- [STACK_NAME]: [REQUIREMENT_DESCRIPTION] +- [STACK_NAME]: [REQUIREMENT_DESCRIPTION] + +## Structure + + + +``` +|- 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] + + diff --git a/skills/spec-scaffold/templates/constitution.md b/skills/spec-scaffold/templates/constitution.md new file mode 100644 index 0000000..3474d0b --- /dev/null +++ b/skills/spec-scaffold/templates/constitution.md @@ -0,0 +1,55 @@ +--- +version: [CONSTITUTION_VERSION] +ratified: [RATIFICATION_DATE] +lastAmended: [LAST_AMENDMENT_DATE] +--- + + + +# [PROJECT_NAME] Constitution + + +## Principles + +### [PRINCIPLE_1_NAME] + +[PRINCIPLE_1_DESCRIPTION] + + +### [PRINCIPLE_2_NAME] + +[PRINCIPLE_2_DESCRIPTION] + + +### [PRINCIPLE_3_NAME] + +[PRINCIPLE_3_DESCRIPTION] + + +### [PRINCIPLE_4_NAME] + +[PRINCIPLE_4_DESCRIPTION] + + +### [PRINCIPLE_5_NAME] + +[PRINCIPLE_5_DESCRIPTION] + + +## [SECTION_2_NAME] + + + +[SECTION_2_CONTENT] + + +## Governance + + +[GOVERNANCE_RULES] + diff --git a/skills/spec-scaffold/templates/glossary.md b/skills/spec-scaffold/templates/glossary.md new file mode 100644 index 0000000..e08a317 --- /dev/null +++ b/skills/spec-scaffold/templates/glossary.md @@ -0,0 +1,28 @@ +Glossary +=== + +# Core + + + +| Term | Definition | +|--------------|-------------------------------------------------| +| [TERM] | [DEFINITION] | + + diff --git a/skills/spec-scaffold/templates/roadmap.md b/skills/spec-scaffold/templates/roadmap.md new file mode 100644 index 0000000..c8ef0f7 --- /dev/null +++ b/skills/spec-scaffold/templates/roadmap.md @@ -0,0 +1,31 @@ +Roadmap +=== + +# Core + + + +| Updated At | Feature Name | Description | Status | +|--------------|----------------|---------------|----------| +| [UPDATED_AT] | [FEATURE_NAME] | [DESCRIPTION] | [STATUS] | + + diff --git a/skills/spec-scaffold/templates/specification.md b/skills/spec-scaffold/templates/specification.md new file mode 100644 index 0000000..6dfc0fa --- /dev/null +++ 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 + + + +[PURPOSE_DESCRIPTION] + +## User Stories and Acceptance Criteria **(mandatory)** + + + + + +### 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] + + + +```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 + + + +- [NAME_OF_ITEM]: explanation of what is unclear and why. +- [NAME_OF_ITEM]: explanation of what is unclear and why.