Initial commit

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.
+

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.

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.

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.

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.