sdd-jc-methodology 0.2.0

package/.claude/commands/sdd-archive.md

@@ -0,0 +1,122 @@
+# Archive SDD Spec
+
+Archive a completed SDD spec path after implementation, testing, and validation are done.
+
+Archiving preserves the full decision trail. It keeps active `docs/specs/` easier to scan while retaining proposal, requirements, design, tasks, execution notes, test evidence, and validation evidence for future review.
+
+## Usage
+
+```
+/sdd-archive <spec-path>
+```
+
+**Examples:**
+
+- `/sdd-archive changes/add-remember-me`
+- `/sdd-archive bugfix/login-redirect`
+- `/sdd-archive enhancements/renewals`
+
+## Arguments
+
+- `$ARGUMENTS` - Relative path under `docs/specs/` that should be archived.
+
+## Output
+
+Move the completed spec folder from:
+
+```text
+docs/specs/$ARGUMENTS/
+```
+
+to:
+
+```text
+docs/specs/archive/YYYY-MM-DD-$SAFE_NAME/
+```
+
+Where `$SAFE_NAME` is `$ARGUMENTS` converted to a filesystem-safe flat name by replacing `/` with `--`.
+
+Example:
+
+```text
+docs/specs/bugfix/login-redirect/
+docs/specs/archive/2026-05-16-bugfix--login-redirect/
+```
+
+## Behavior
+
+### Step 0: Load Context
+
+1. Confirm `docs/specs/$ARGUMENTS/` exists.
+2. Read all available files in that folder, especially:
+   - `proposal.md` if present
+   - `requirements.md`
+   - `design.md`
+   - `tasks.md`
+   - `execution.md` if present
+   - `test-report.md` if present
+   - `validation-report.md` if present
+3. Read project-level context only if needed to interpret archive readiness:
+   - `docs/prd.md`
+   - `docs/system-design/design.md`
+   - `docs/detailed-design/detailed-design.md`
+   - `docs/specs/general-setup/`
+
+### Step 1: Check Archive Readiness
+
+Verify the spec is ready to archive:
+
+- `requirements.md`, `design.md`, and `tasks.md` exist
+- all required tasks are marked `[x]`, or incomplete tasks are explicitly accepted as follow-up work
+- `test-report.md` exists, or the absence is explicitly accepted
+- `validation-report.md` exists, or the absence is explicitly accepted
+- no unresolved FAIL findings remain in `validation-report.md`
+- WARN findings are either accepted or assigned to follow-up tasks
+- implementation drift is reflected in the SDD docs or execution notes
+
+If readiness is unclear, stop and ask the user whether to proceed, validate first, or keep the spec active.
+
+### Step 2: Create Archive Summary
+
+Before moving the folder, create or update:
+
+```text
+docs/specs/$ARGUMENTS/archive-summary.md
+```
+
+The summary must include:
+
+1. Document Control
+2. Original Spec Path
+3. Archive Date
+4. Final Status
+5. Requirements Delivered
+6. Files Changed Summary, based on `execution.md` when available
+7. Test Evidence Summary
+8. Validation Summary
+9. Accepted Warnings Or Follow-Ups
+10. Historical Notes
+
+### Step 3: Move Folder
+
+1. Ensure `docs/specs/archive/` exists.
+2. Move `docs/specs/$ARGUMENTS/` to `docs/specs/archive/YYYY-MM-DD-$SAFE_NAME/`.
+3. If the target archive folder already exists, do not overwrite it. Add a numeric suffix such as `-2` and report the final path.
+
+### Step 4: Report To User
+
+Present:
+
+1. archived source path
+2. final archive path
+3. final validation status
+4. unresolved follow-ups, if any
+5. whether the active spec directory is now clean
+
+## Error Handling
+
+- If the spec path does not exist, report the missing path and stop.
+- If required docs are missing, ask whether to archive anyway or run the missing command first.
+- If validation has unresolved FAIL findings, recommend fixing or explicitly accepting risk before archive.
+- If moving the folder fails, leave the original folder in place and report the reason.
+- Do not delete spec folders as part of archiving; only move them into `docs/specs/archive/`.

package/.claude/commands/sdd-constitution.md

@@ -0,0 +1,240 @@
+# Establish SDD Constitution
+
+Establish or strengthen the project-wide SDD foundation. This command creates the documentation baseline that all later module-level SDD work depends on.
+
+## Usage
+
+```
+/sdd-constitution
+```
+
+## Behavior
+
+### Step 0: Foundation Setup
+
+1. Ensure `docs/` exists.
+2. Ensure `docs/specs/` exists.
+3. Ensure `docs/specs/general-setup/` exists.
+4. Default behavior is to enhance existing project docs in place instead of creating parallel copies.
+
+The constitutional baseline must cover these files:
+
+- `docs/prd.md`
+- `docs/system-design/design.md`
+- `docs/detailed-design/detailed-design.md`
+- `docs/specs/general-setup/requirements.md`
+- `docs/specs/general-setup/design.md`
+- `docs/specs/general-setup/task.md`
+- `CLAUDE.md`
+
+---
+
+### Step 1: Read Project Context First
+
+Before writing anything, read the repository context carefully:
+
+1. Root `CLAUDE.md` if it exists
+2. Package-level `CLAUDE.md` files if they exist
+3. Existing `docs/prd.md`
+4. Existing `docs/system-design/design.md`
+5. Existing `docs/detailed-design/detailed-design.md`
+6. Existing `docs/specs/` folders to extract terminology, taxonomy, and prior feature history
+7. Any architecture, infrastructure, setup, or product docs already present under `docs/`
+
+Also inspect the codebase to understand:
+
+- Product domain and business model
+- Main user roles and workflows
+- Current frontend/backend/shared architecture
+- Existing visual patterns and design system signals
+- Technical constraints already enforced by the repo
+- Existing spec taxonomy under `docs/specs/` such as domain, enhancement, bugfix, or epic folders
+
+Do not write generic placeholder documentation when the repository already contains enough context to infer a strong baseline.
+
+---
+
+### Step 2: Clarify Missing Business Context
+
+If essential product context is missing or ambiguous, ask focused user questions before drafting the documents.
+
+Focus especially on:
+
+- The core problem the product solves
+- Primary personas and user roles
+- Business goals and expected outcomes
+- Success metrics or KPIs
+- Scope boundaries and non-goals
+- Known constraints, dependencies, and risks
+- Preferred `docs/specs/` taxonomy when the repo does not already imply one
+
+Ask only what is needed to avoid unstable assumptions.
+
+---
+
+### Step 3: Create or Enhance the General PRD
+
+Create or enhance `docs/prd.md` as a concise living document.
+
+**Primary skill:** `product-manager-toolkit`
+
+**PRD rules:**
+
+- Lead with the why: problem statement, business context, user need
+- Keep it concise and maintainable
+- Define measurable success metrics before implementation begins
+- Define explicit out-of-scope items
+- Use user-centric requirements and user stories
+- Use testable acceptance criteria
+- Collaborate through assumptions and open questions rather than pretending certainty
+- Keep it AI-ready with clean headings and concise bullets
+
+**Pitfalls to avoid:**
+
+- Do not mix goals with requirements
+- Do not use vague language like "fast" or "intuitive" without measurable meaning
+- Do not treat the PRD as static
+- Do not force a predetermined technical solution into the PRD
+
+**Required PRD structure:**
+
+1. Overview & Purpose
+2. Problem Statement
+3. Target Personas
+4. Goals & Success Metrics
+5. Scope (In / Out)
+6. User Stories
+7. Acceptance Criteria
+8. Assumptions, Dependencies, & Constraints
+9. Open Questions
+
+When `docs/prd.md` already exists, preserve useful content and upgrade weak sections to follow the rules above.
+
+---
+
+### Step 4: Create or Enhance the System Design Document
+
+Create or enhance `docs/system-design/design.md` as the UI/UX system blueprint.
+
+**Preferred skill chain:**
+
+- `ui-ux-pro-max` if available
+- otherwise `frontend-design` + `stitch-design`
+
+This document represents the visual and interaction system, not the low-level technical implementation.
+
+**Required structure:**
+
+1. Product Experience Principles
+2. Information Architecture
+3. Primary User Flows
+4. Screen Inventory
+5. Navigation Model
+6. Layout Patterns
+7. Design Tokens
+8. Component Inventory
+9. Responsive Behavior
+10. Accessibility Expectations
+11. Dark Mode Behavior
+12. Design Decisions
+13. Open Gaps / Open Questions
+
+**Document intent:**
+
+- Define a reusable, consistent UI/UX system
+- Capture visual consistency, accessibility, and interaction rules
+- Reference existing brand, color, typography, and component patterns from the repository when available
+- Prefer clarity over decorative language
+
+When the file already exists, refine it in place instead of replacing established valid patterns.
+
+---
+
+### Step 5: Create or Enhance the Detailed Design Document
+
+Create or enhance `docs/detailed-design/detailed-design.md` as the technical implementation blueprint.
+
+**Use skills when relevant:**
+
+- `nestjs-expert`
+- `api-design-principles`
+- `error-handling-patterns`
+- `aws-serverless`
+- `shadcn-ui`
+- `tailwind-design-system`
+- `vercel-react-best-practices`
+
+**Required structure:**
+
+1. System Overview
+2. Domain Modules & Responsibilities
+3. Data Model & Entities
+4. API Surface & Contracts
+5. Backend Workflows & Business Rules
+6. Frontend Architecture & State Boundaries
+7. Integration Points
+8. Security & Authorization Model
+9. Error Handling & Observability
+10. Testing Strategy
+11. Technical Constraints & Assumptions
+
+---
+
+### Step 6: Create or Enhance General Setup Templates
+
+Create or enhance the canonical templates under `docs/specs/general-setup/`.
+
+These files define the format that `/sdd-specify` must follow later:
+
+1. `requirements.md` — requirement numbering, structure, and writing standards
+2. `design.md` — architecture, data model, API, frontend, and decision-record structure
+3. `task.md` — task format, dependency graph format, testing expectations, and execution conventions
+
+These are methodology templates for future specs, not a feature spec themselves.
+
+They must reflect:
+
+- The repo's current architecture and package layout
+- The chosen `docs/specs/` taxonomy
+- The approved PRD, system design, and detailed design conventions
+
+---
+
+### Step 7: Update the Root CLAUDE Guide
+
+Update root `CLAUDE.md` so it references:
+
+- `docs/prd.md`
+- `docs/system-design/design.md`
+- `docs/detailed-design/detailed-design.md`
+- `docs/specs/general-setup/`
+
+The update should explain briefly:
+
+- What each document is for
+- When Claude should consult each one
+- That these documents form the constitutional baseline for future SDD work
+- How module specs should be organized under `docs/specs/`
+
+Preserve the repository's existing `CLAUDE.md` conventions and extend them.
+
+---
+
+### Step 8: Present and Confirm
+
+After drafting or enhancing the documents, present a concise summary covering:
+
+- What was created vs enhanced
+- The chosen spec taxonomy under `docs/specs/`
+- The main problem statement and personas captured in the PRD
+- The main UX/system decisions captured in system design
+- The main technical decisions captured in detailed design
+- Any assumptions and open questions that still need validation
+
+Ask the user whether to approve or request changes. If changes are requested, revise the affected documents and re-present.
+
+---
+
+## Outcome
+
+At the end of `/sdd-constitution`, the repository should have a project-level baseline that future `/sdd-specify`, `/sdd-execute`, `/sdd-validate`, and `/sdd-test` work can rely on without guessing the structure or conventions.

package/.claude/commands/sdd-execute.md

@@ -0,0 +1,132 @@
+# Execute SDD Tasks
+
+Execute implementation tasks from an approved SDD spec path. Read `tasks.md`, choose the next eligible task, implement only that task's scope, verify it, update task status, and record progress in `execution.md`.
+
+Execution should be incremental. Do not turn one approved task into a broader refactor unless the spec explicitly requires it or the user approves the scope change.
+
+## Usage
+
+```
+/sdd-execute <spec-path>
+```
+
+**Examples:**
+
+- `/sdd-execute loan`
+- `/sdd-execute enhancements/renewals`
+
+## Arguments
+
+- `$ARGUMENTS` — Relative path under `docs/specs/` that already contains `requirements.md`, `design.md`, and `tasks.md`.
+
+## Output
+
+Each successful task execution should produce:
+
+- focused code or documentation changes within task scope
+- updated task status in `tasks.md`
+- an appended entry in `execution.md`
+- verification evidence from the command or check listed in the task
+
+Use `[~]` for a started but incomplete task, `[x]` for a completed task, and `[ ]` for pending work.
+
+---
+
+## Behavior
+
+### Step 0: Load Context
+
+1. Read the SDD documents for the spec path:
+   - `docs/specs/$ARGUMENTS/requirements.md`
+   - `docs/specs/$ARGUMENTS/design.md`
+   - `docs/specs/$ARGUMENTS/tasks.md`
+2. Read `docs/specs/$ARGUMENTS/execution.md` if it exists.
+3. Read the project constitutional docs:
+   - `docs/prd.md`
+   - `docs/system-design/design.md`
+   - `docs/detailed-design/detailed-design.md`
+   - `docs/specs/general-setup/`
+4. Read root and package-level `CLAUDE.md` files if they exist.
+5. Identify current task state: `[x]`, `[~]`, `[ ]`.
+
+### Step 1: Select Next Task
+
+1. Find the next executable task by document order where:
+   - status is `[ ]` or `[~]`
+   - all dependencies are `[x]`
+2. If a task is `[~]`, resume it using `execution.md` context.
+3. If no tasks are eligible, report completion or blocking state and stop.
+4. If multiple tasks are eligible, prefer the first task by document order unless there is a clear dependency or risk reason to choose another.
+
+### Step 2: Execute Task
+
+#### 2.1 — Read Scope & Design
+
+- Re-read the specific design sections referenced by the task.
+- Re-read the requirements and scenarios covered by the task.
+- Read the existing files that will be touched.
+- Confirm the implementation still matches the constitutional docs and module spec.
+- Identify the smallest safe change that satisfies the task.
+
+#### 2.2 — Invoke Relevant Skills
+
+- Load only the skills listed in the task.
+- If the task is UI-heavy, prefer `ui-ux-pro-max` when available.
+- Otherwise use the documented fallback skills from the task or design.
+
+#### 2.3 — Implement
+
+- Keep changes minimal and within task scope.
+- Follow the design specification exactly unless the spec is clearly incomplete or contradictory.
+- If the design is ambiguous, ask the user for clarification before making up a direction.
+- If implementation discovery invalidates the spec, stop and propose the smallest required spec update before continuing.
+- Do not mark unrelated cleanup or opportunistic refactors as part of the task unless they are necessary for correctness.
+
+#### 2.4 — Verify
+
+- Run the verification command listed in the task.
+- Fix failures before marking the task complete.
+- If the listed command is unavailable, identify the closest repository-specific build, lint, test, or manual check and record the substitution in `execution.md`.
+
+### Step 3: Update Status
+
+1. Update `tasks.md` from `[ ]` to `[x]` when complete.
+2. Use `[~]` when the task is partially complete or blocked.
+3. Append implementation notes to `execution.md`.
+
+### Step 4: Continue or Pause
+
+After completing a task, summarize the task result, verification outcome, and next eligible task. Ask whether to continue, pause, or skip the next task.
+
+---
+
+## Execution Log Format (`execution.md`)
+
+The execution log is created on first run and appended to on subsequent runs.
+
+Minimum sections:
+
+1. Document Control
+2. Task Execution History
+3. Summary when all tasks are complete
+
+Each task entry should record:
+
+- status
+- date
+- task ID and title
+- files changed
+- requirements covered
+- decisions made
+- issues encountered
+- verification result
+
+---
+
+## Error Handling
+
+- If required SDD files are missing, stop and report what is missing.
+- If the design is ambiguous, ask the user before proceeding.
+- If verification fails, debug and fix before marking complete.
+- If a task is blocked, report the blocker and move to the next eligible task if appropriate.
+- If implementation requires changing the approved requirements or design, pause and ask for approval before expanding scope.

package/.claude/commands/sdd-propose.md

@@ -0,0 +1,149 @@
+# Propose SDD Change
+
+Create a lightweight proposal for one bounded change before generating full SDD documents.
+
+The proposal is the reviewable intent layer. It should help the user decide whether the change is worth specifying before time is spent on requirements, design, tasks, or implementation.
+
+## Usage
+
+```
+/sdd-propose <change-name-or-spec-path>
+```
+
+**Examples:**
+
+- `/sdd-propose add-remember-me`
+- `/sdd-propose bugfix/login-redirect`
+- `/sdd-propose enhancements/renewals`
+
+## Arguments
+
+- `$ARGUMENTS` - A change name or a relative path under `docs/specs/`.
+
+Path resolution:
+
+- If `$ARGUMENTS` contains `/`, treat it as the literal spec path.
+- If `$ARGUMENTS` is a bare name, use `changes/$ARGUMENTS` as the spec path.
+
+Examples:
+
+| Input | Spec Path | Proposal Path |
+|---|---|---|
+| `add-remember-me` | `changes/add-remember-me` | `docs/specs/changes/add-remember-me/proposal.md` |
+| `bugfix/login-redirect` | `bugfix/login-redirect` | `docs/specs/bugfix/login-redirect/proposal.md` |
+
+## Output
+
+Create or update:
+
+```text
+docs/specs/$SPEC_PATH/proposal.md
+```
+
+Do not create `requirements.md`, `design.md`, or `tasks.md` in this command unless the user explicitly asks. Those belong to `/sdd-specify`.
+
+## Behavior
+
+### Step 0: Resolve Path And Load Context
+
+1. Resolve `$SPEC_PATH` using the path rules above.
+2. Create `docs/specs/$SPEC_PATH/` if it does not exist.
+3. Read project-level context when available:
+   - `docs/prd.md`
+   - `docs/system-design/design.md`
+   - `docs/detailed-design/detailed-design.md`
+   - `docs/specs/general-setup/`
+   - root `CLAUDE.md`
+   - package-level `CLAUDE.md` files
+4. Read nearby or related specs under `docs/specs/`.
+5. Inspect relevant code paths only enough to understand current behavior and likely impact.
+
+### Step 1: Clarify Intent
+
+Use `brainstorming` and, when helpful, `product-manager-toolkit` to clarify:
+
+- problem being solved
+- target users, actors, or systems
+- current behavior
+- desired behavior
+- scope boundaries
+- non-goals
+- dependencies and constraints
+- success criteria
+
+Ask focused questions only when the proposal would otherwise depend on unstable assumptions.
+
+### Step 2: Write `proposal.md`
+
+Create a concise proposal with this structure:
+
+1. Document Control
+2. Intent
+3. Problem / Current Behavior
+4. Proposed Outcome
+5. Scope
+6. Non-Goals
+7. Affected Users, Systems, And Specs
+8. Requirement Delta Preview
+9. Approach Options
+10. Recommended Approach
+11. Risks, Dependencies, And Open Questions
+12. Success Criteria
+13. Next Step
+
+### Requirement Delta Preview
+
+When the change affects existing behavior, include a lightweight preview using these sections where relevant:
+
+```markdown
+## Requirement Delta Preview
+
+### ADDED Requirements
+
+- New behavior that does not exist today.
+
+### MODIFIED Requirements
+
+- Existing behavior that will change.
+
+### REMOVED Requirements
+
+- Existing behavior that will be deprecated or deleted.
+```
+
+This preview is not the final spec. `/sdd-specify` converts approved intent into full requirements, scenarios, design, and tasks.
+
+### Approach Options
+
+For non-trivial work, include 2 or 3 options with trade-offs. Recommend one option and explain why it is the smallest safe path.
+
+### Next Step
+
+End the proposal with the exact next command:
+
+```text
+/sdd-specify $SPEC_PATH
+```
+
+## Review Checklist
+
+Before presenting the proposal, verify:
+
+- [ ] The problem is clear.
+- [ ] Scope and non-goals are explicit.
+- [ ] The proposed outcome is behavior-focused.
+- [ ] Affected specs or code areas are listed.
+- [ ] Risks and open questions are visible.
+- [ ] The next command uses the resolved spec path.
+
+## Report To User
+
+Present a short summary with:
+
+1. proposal path
+2. resolved spec path
+3. recommended approach
+4. main risks or open questions
+5. next command to run after approval
+
+Ask whether to approve the proposal, revise it, or stop.