sdd-jc-methodology 0.2.0

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

@@ -0,0 +1,251 @@
+# SEO Setup & Audit via Google Search Console
+
+Provision Google Search Console access for a domain via a Google Cloud service account, then run a full SEO audit (index coverage, sitemaps, structured data, search analytics) and generate an audit report under the spec path. Produces `seo-setup-report.md` and `seo-audit-report.md`.
+
+## Usage
+
+```
+/sdd-seo <site-domain>
+```
+
+**Examples:**
+
+- `/sdd-seo calismiledesign.com`
+- `/sdd-seo seo/calismiledesign.com`
+- `/sdd-seo agrosmartco.com`
+
+## Arguments
+
+- `$ARGUMENTS` — Either a bare apex domain (e.g. `example.com`) or a relative path under `docs/specs/` (e.g. `seo/example.com`). When a bare domain is given, the spec path defaults to `docs/specs/seo/<domain>/`.
+
+## Prerequisites
+
+The user must provide (or confirm) once per Google Cloud project:
+
+1. A Google Cloud service account JSON key file, absolute path.
+2. Three APIs enabled in that GCP project:
+   - **Site Verification API** (`siteverification.googleapis.com`)
+   - **Search Console API** (`searchconsole.googleapis.com`)
+   - **Web Search Indexing API** is **NOT required** — Google only honors it for `JobPosting` and `BroadcastEvent` schemas; do not push users to enable it for generic content sites.
+3. DNS provider access for the target domain (to add a TXT record).
+4. The GSC MCP server configured in `~/.claude.json` or project `.mcp.json` with:
+   ```json
+   "gsc": {
+     "command": "npx",
+     "args": ["-y", "@mikusnuz/gsc-mcp"],
+     "env": {
+       "GSC_SERVICE_ACCOUNT_KEY_PATH": "<absolute path to JSON key>"
+     }
+   }
+   ```
+   If `GSC_SITE_URL` is set, prefer the `sc-domain:` form (e.g. `sc-domain:example.com`) over the URL-prefix form.
+5. A local helper for the Site Verification API. The `gsc` MCP does **not** expose Site Verification endpoints (no `getToken`, no `verify`) — it only wraps the Search Console API. Use the bundled `scripts/gsc_verify.py` from `sdd-jc-methodology` (depends on `google-auth` and `google-api-python-client`). Invoke it as:
+
+   ```bash
+   GSC_KEY_PATH=/abs/path/to/key.json python3 scripts/gsc_verify.py get <domain>
+   GSC_KEY_PATH=/abs/path/to/key.json python3 scripts/gsc_verify.py verify <domain>
+   ```
+
+If any prerequisite is missing, stop and report exactly what is missing and how to obtain it.
+
+## Tool Inventory
+
+| Phase | Endpoint | Source |
+|---|---|---|
+| 1.1 Get TXT token | `siteVerification.webResource.getToken` | Site Verification API (helper script) |
+| 1.3 Verify ownership | `siteVerification.webResource.insert` | Site Verification API (helper script) |
+| 1.4 Add property | `sites_add` | `gsc` MCP |
+| 1.5 Confirm | `sites_list` | `gsc` MCP |
+| 2.1 Sitemaps | `sitemaps_list`, `sitemaps_submit` | `gsc` MCP |
+| 2.2 Index coverage | `url_inspection_inspect` | `gsc` MCP |
+| 2.4 Analytics | `search_analytics_query` | `gsc` MCP |
+| 2.5 Render | raw `curl -A Googlebot/2.1` | shell |
+
+---
+
+## Behavior
+
+### Phase 0: Setup
+
+1. Resolve the spec path. If `$ARGUMENTS` is a bare domain, set `SPEC_PATH = seo/<domain>`. Otherwise treat `$ARGUMENTS` as the literal spec path.
+2. Create directory `docs/specs/$SPEC_PATH/` if it does not exist.
+3. Read the constitutional templates and project context as defined in `sdd-specify`:
+   - `docs/specs/general-setup/`
+   - `docs/prd.md`
+   - `docs/system-design/design.md` or `docs/system-design.md`
+   - `docs/detailed-design/detailed-design.md` or `docs/detailed-design.md`
+   - Root `CLAUDE.md`
+4. Confirm the GSC MCP is reachable. If not, stop and report.
+
+---
+
+### Phase 1: Verify & Add Property
+
+**Role:** SEO Engineer — register the service account as a verified owner of the domain in Google Search Console.
+
+#### Step 1.1 — Generate the DNS TXT token
+
+Call the Site Verification API to obtain the verification token for `sc-domain:<domain>`. Present the user with the exact TXT record to add:
+
+```
+Type:  TXT
+Host:  @  (root of <domain>)
+Value: google-site-verification=<token>
+```
+
+#### Step 1.2 — Wait for DNS propagation
+
+Ask the user to confirm the TXT record is live, then verify with a DNS lookup before proceeding. Do not loop silently — fail clearly if propagation has not happened after a reasonable check.
+
+#### Step 1.3 — Verify ownership
+
+Call the Site Verification API `verify` endpoint. On success, the service account becomes an owner of the property.
+
+#### Step 1.4 — Add the property to Search Console
+
+Verification alone does not add the property to Search Console for the service account. Explicitly call `sites_add` with `sc-domain:<domain>` so the property appears in `sites_list` with `permissionLevel: siteOwner`.
+
+#### Step 1.5 — Write `seo-setup-report.md`
+
+Produce `docs/specs/$SPEC_PATH/seo-setup-report.md` documenting:
+
+1. Document Control (date, domain, service account email, GCP project)
+2. Prerequisites checked
+3. DNS TXT record value installed
+4. Verification result
+5. `sites_list` confirmation output
+6. Notes / caveats
+
+---
+
+### Phase 2: Audit
+
+**Role:** Technical SEO Auditor — measure the state of the domain in Google's index.
+
+Use `systematic-debugging` when results are inconsistent with site reality.
+
+Skill preference for any UX/UI recommendations:
+
+- `ui-ux-pro-max` if available
+- otherwise `frontend-design`
+
+#### Step 2.1 — Sitemap audit
+
+1. List submitted sitemaps via `sitemaps_list`.
+2. If none submitted but `https://<domain>/sitemap.xml` or `/sitemap-index.xml` exists, propose submission with `sitemaps_submit` and ask before submitting.
+3. Fetch each sitemap with `curl -sL` and enumerate URLs.
+
+#### Step 2.2 — Index coverage
+
+For every URL in the sitemap (cap at 25 for cost; sample evenly across locales and sections), call `url_inspection_inspect`. Bucket each URL into:
+
+- `PASS` — Submitted and indexed
+- `NEUTRAL` — Discovered – currently not indexed
+- `NEUTRAL` — URL is unknown to Google
+- `NEUTRAL` — Page with redirect
+- `FAIL` — anything else (e.g. blocked, server error, soft 404)
+
+Record `googleCanonical`, `userCanonical`, `pageFetchState`, `crawledAs`, `lastCrawlTime` for each.
+
+#### Step 2.3 — Structured data audit
+
+From `url_inspection_inspect.richResultsResult`, collect every rich-result item flagged with `WARNING` or `ERROR`. For each, fetch the page with a Googlebot user agent and extract the offending JSON-LD block so the report can show the exact bad value and the exact corrected value.
+
+Common findings to surface:
+
+- `VideoObject.uploadDate` missing time or timezone (use ISO 8601 `YYYY-MM-DDTHH:MM:SS±HH:MM`)
+- `Product`, `Review`, `Organization` missing required fields
+
+#### Step 2.4 — Search analytics
+
+Call `search_analytics_query` for the last 28 days (or last 90 if available), grouped by:
+
+- `query` (top 25)
+- `page` (top 25)
+- `country` (top 10)
+- `device` (all)
+
+If the property is newly verified and returns no rows, record that explicitly and note that data typically appears within 2–7 days.
+
+#### Step 2.5 — Render audit
+
+For 2–3 sampled pages, fetch them with `curl -sL -A "Googlebot/2.1"` and measure:
+
+- HTML size in bytes
+- Visible text length in characters and word count
+- Whether the main content is present in server-rendered HTML (vs JS-only)
+
+This separates "thin content" failures from "JS render" failures.
+
+#### Step 2.6 — Internal linking quick check
+
+Fetch the homepage and count anchor links to each sitemap URL. URLs with zero internal links from the homepage are flagged as orphan-like.
+
+---
+
+### Phase 3: Write `seo-audit-report.md`
+
+Generate `docs/specs/$SPEC_PATH/seo-audit-report.md` using `docs/specs/general-setup/validation-report.md` as the format source where it fits.
+
+Required sections:
+
+1. Document Control
+2. Executive Summary — one-paragraph verdict + 3–5 bullet headline findings.
+3. Index Coverage Table — every audited URL with its bucket and last crawl time.
+4. Sitemap Status
+5. Structured Data Findings — exact broken JSON-LD blocks with corrected versions.
+6. Search Analytics Summary — top queries / pages / devices / countries, or an explicit "no data yet" note.
+7. Render Audit
+8. Internal Linking Findings
+9. Remediation Plan — prioritized (High / Medium / Low) actionable items, each scoped enough that an implementer can execute it without further discovery.
+10. Re-audit Schedule — when to run `/sdd-seo <domain>` again.
+
+The report title must be `# SEO Audit Report — <domain>`.
+
+---
+
+### Phase 4: Generate a Fix Prompt
+
+Append to the audit report a section titled `## Implementation Prompt` containing a fenced, copy-paste prompt that can be handed to Claude Code (or any engineer) inside the site's codebase to fix every High-severity finding. The prompt must:
+
+- Reference each finding by ID from the remediation plan.
+- Include exact JSON-LD before/after snippets where structured data is broken.
+- Include exact URL pairs for hreflang corrections.
+- End with "Show me a diff of every change before applying. Do not deploy until I approve."
+
+---
+
+### Phase 5: Present & Approve
+
+Present a short summary of:
+
+- Setup status (Phase 1 outcome).
+- Audit headline findings and counts per bucket.
+- The number of High / Medium / Low remediation items.
+- Paths to the two generated reports.
+
+Ask the user whether to also run the same flow against any other properties under the same service account.
+
+---
+
+## Verification Checklist
+
+After the command completes, verify:
+
+- [ ] `docs/specs/$SPEC_PATH/seo-setup-report.md` exists and references the actual TXT token used.
+- [ ] `docs/specs/$SPEC_PATH/seo-audit-report.md` exists with all required sections.
+- [ ] `sites_list` shows the property with `permissionLevel: siteOwner`.
+- [ ] Every URL in the sitemap is either audited or explicitly excluded with a reason.
+- [ ] Every structured-data warning is reproduced with the exact bad value and the exact fix.
+- [ ] The implementation prompt is self-contained and would not require this conversation to execute.
+
+---
+
+## Error Handling
+
+- If the Site Verification API returns `failedVerification`, do not retry blindly — surface the underlying reason (TXT not visible, wrong record, DNSSEC lag) and stop.
+- If `sites_add` fails with 403, the service account is not yet a verified owner — return to Phase 1.
+- If `sites_list` returns empty after a successful `sites_add`, the MCP cached an old session — instruct the user to restart Claude Code or the `gsc` MCP and retry.
+- If `search_analytics_query` returns no rows for a newly verified property, this is expected. Do not mark as failure.
+- If the Indexing API is suggested as a fix, decline it for non-`JobPosting`/`BroadcastEvent` content and explain why.
+- If a skill is unavailable, fall back to the next documented skill and note it in the report.

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

@@ -0,0 +1,264 @@
+# Generate SDD for Module
+
+Generate a clear Spec-Driven Development document set for one bounded module, feature, bugfix, or enhancement inside `docs/specs/`.
+
+The goal is not to create long documents. The goal is to make the intended behavior, design choices, implementation tasks, and verification path easy to review before code is written.
+
+If `proposal.md` already exists for the same spec path, treat it as the approved intent and convert it into full requirements, design, and tasks. If no proposal exists, create the spec directly from the user's request and repository context.
+
+## Usage
+
+```
+/sdd-specify <spec-path>
+```
+
+**Examples:**
+
+- `/sdd-specify loan`
+- `/sdd-specify enhancements/renewals`
+- `/sdd-specify admin/user-management`
+
+## Arguments
+
+- `$ARGUMENTS` — Relative path under `docs/specs/` where the spec should live. It may be a flat module name or a nested taxonomy path.
+
+## Output
+
+Create or update these files under `docs/specs/$ARGUMENTS/`:
+
+- `proposal.md` — optional prior intent document created by `/sdd-propose`
+- `requirements.md` — what behavior must exist and why it matters
+- `design.md` — how the behavior will be implemented within the current architecture
+- `tasks.md` — small executable tasks linked to requirements and design sections
+
+Use the lightest useful depth:
+
+| Depth | Use For | Documentation Style |
+|---|---|---|
+| Lite | Small bugfixes, copy updates, narrow UI tweaks | Short sections, focused requirements, one or a few tasks |
+| Standard | Normal features and enhancements | Full requirements, scenarios, design decisions, task breakdown |
+| Full | Risky, cross-cutting, API, data, auth, or migration work | Include alternatives, rollout, risks, observability, rollback |
+
+Lite mode still requires testable requirements, scenarios, and done criteria.
+
+## Behavior
+
+### Step 0: Setup
+
+1. Create directory `docs/specs/$ARGUMENTS/` if it does not exist.
+2. Read `docs/specs/$ARGUMENTS/proposal.md` if it exists.
+3. Read the constitutional templates in `docs/specs/general-setup/`:
+   - `requirements.md`
+   - `design.md`
+   - `task.md`
+4. Read project-level reference context:
+   - `docs/prd.md`
+   - `docs/system-design/design.md`
+   - `docs/detailed-design/detailed-design.md`
+   - Root `CLAUDE.md`
+   - Package-level `CLAUDE.md` files if they exist
+5. Read nearby or dependent specs under `docs/specs/` that overlap with the requested path.
+6. Respect the repository's current package layout and naming conventions instead of assuming a fixed stack.
+
+---
+
+### Phase 1: Requirements (`requirements.md`)
+
+**Role:** Product Owner — define what is being built and why.
+
+#### Step 1.1 — Explore
+
+Use `brainstorming` and, when helpful, `product-manager-toolkit` to clarify:
+
+- user problem and target actors
+- scope boundaries and dependencies
+- primary flows and feature areas
+- success metrics and constraints
+
+#### Step 1.2 — Write
+
+Generate `requirements.md` using `docs/specs/general-setup/requirements.md` as the format source.
+
+Minimum content:
+
+1. Document Control
+2. Executive Summary
+3. Glossary
+4. System Context & Scope
+5. Stakeholders / Personas
+6. Functional Requirements
+7. Non-Functional Requirements
+8. Requirement ID Index
+
+Guidelines:
+
+- follow the repo's established requirement ID pattern from `general-setup`
+- align with `docs/prd.md`
+- align with `proposal.md` when present
+- reference existing specs when this work extends another feature
+- use measurable, testable language
+- separate goals from requirements
+- write behavior contracts, not implementation plans
+- include concrete scenarios for key requirements using `GIVEN`, `WHEN`, `THEN`, and optional `AND`
+- make requirement strength explicit with `SHALL`, `MUST`, `SHOULD`, or `MAY` where useful
+
+Recommended requirement shape:
+
+```markdown
+### Requirement: Short Behavior Name
+
+The system SHALL provide the observable behavior.
+
+#### Scenario: Main case
+
+- GIVEN the relevant starting state
+- WHEN the triggering action happens
+- THEN the expected outcome occurs
+- AND any required side effect is visible
+```
+
+Avoid putting internal class names, library choices, or step-by-step implementation details in requirements. Those belong in `design.md` or `tasks.md`.
+
+If `proposal.md` includes a Requirement Delta Preview, convert it into full requirements:
+
+- `ADDED` items become new requirements and scenarios
+- `MODIFIED` items become updated behavior descriptions with before/after context
+- `REMOVED` items become explicit deprecation or removal requirements with migration notes when relevant
+
+#### Step 1.3 — Present & Approve
+
+Present a summary and ask the user to approve or request changes before moving on.
+
+---
+
+### Phase 2: Design (`design.md`)
+
+**Role:** System Architect — define how the feature will be built.
+
+#### Step 2.1 — Explore
+
+Use `brainstorming` to explore trade-offs before writing.
+
+If the work includes meaningful UI/UX impact, use this skill preference:
+
+- `ui-ux-pro-max` if available
+- otherwise `frontend-design` + `stitch-design`
+
+Use additional technical skills as needed:
+
+- `nestjs-expert`
+- `api-design-principles`
+- `shadcn-ui`
+- `tailwind-design-system`
+- `vercel-react-best-practices`
+- `error-handling-patterns`
+- `aws-serverless`
+
+#### Step 2.2 — Write
+
+Generate `design.md` using `docs/specs/general-setup/design.md` as the format source.
+
+Minimum content:
+
+1. Document Control
+2. Executive Summary
+3. Architecture Overview
+4. Extended Directory Structure
+5. Data Model
+6. API Design
+7. Backend Module Design
+8. Frontend / UX Component Architecture
+9. Shared Contracts or Package Extensions
+10. Design Decisions
+
+Guidelines:
+
+- extend existing architecture rather than replacing it
+- use current repo paths and package names
+- include UI/UX decisions when the feature affects screens, flows, or components
+- tie design sections back to requirements explicitly
+- record meaningful trade-offs and rejected alternatives for non-trivial decisions
+- call out data, API, security, error-handling, observability, and rollback concerns when relevant
+- keep design decisions practical enough that an implementer can act without re-discovery
+
+#### Step 2.3 — Present & Approve
+
+Present a summary and ask the user to approve or request changes before moving on.
+
+---
+
+### Phase 3: Tasks (`tasks.md`)
+
+**Role:** Tech Lead — define the implementation plan.
+
+#### Step 3.1 — Explore
+
+Use `brainstorming` to determine sequencing, dependencies, parallelization, and test strategy.
+
+#### Step 3.2 — Write
+
+Generate `tasks.md` using `docs/specs/general-setup/task.md` as the format source.
+
+Each task should include:
+
+- status
+- size
+- dependencies
+- requirements covered
+- design references
+- scope
+- tests
+- done criteria
+- relevant skills
+
+Skill inventory should use real, available skills only.
+
+Task quality rules:
+
+- one task should be small enough to complete and verify in one focused session
+- every task must reference the requirements it satisfies
+- every task must include a concrete verification command or manual check
+- tasks should avoid broad instructions like "implement feature" without scoped subtasks
+- tasks may be grouped by phase, but dependencies must remain explicit
+
+Preferred UI/UX skill rule:
+
+- use `ui-ux-pro-max` when available for UI-heavy tasks
+- otherwise use `frontend-design` and/or `stitch-design`
+
+#### Step 3.3 — Present & Approve
+
+Present a summary and ask the user to approve or request changes.
+
+---
+
+## Verification Checklist
+
+After all three documents are approved, verify:
+
+- [ ] All 3 files exist with non-empty content
+- [ ] All documents follow `docs/specs/general-setup/` conventions
+- [ ] The chosen depth is appropriate for the risk and size of the work
+- [ ] Requirements describe observable behavior, not implementation details
+- [ ] Key requirements include Given/When/Then scenarios
+- [ ] Every requirement appears in at least one task
+- [ ] Every task references requirements and design sections
+- [ ] Every task has clear done criteria and verification guidance
+- [ ] The task dependency graph has no circular dependencies
+- [ ] The spec path matches the repo's chosen taxonomy under `docs/specs/`
+- [ ] Only real, available skills are referenced in tasks
+
+---
+
+## Review Handoff
+
+When the spec is ready, present a short handoff summary:
+
+1. Spec path and chosen depth: Lite, Standard, or Full
+2. Problem being solved
+3. Requirements and key scenarios
+4. Important design decisions and risks
+5. Task count and recommended first task
+6. Open questions or assumptions that still need user confirmation
+
+If a proposal existed, mention whether the generated spec stayed aligned with it or changed based on implementation discovery.

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

@@ -0,0 +1,128 @@
+# Test SDD Implementation
+
+Run automated and, when needed, manual tests against a spec path's implementation. Produce `test-report.md` with results, requirement coverage, scenario traceability, and failures.
+
+Testing should prove the behavior promised in `requirements.md`, not only increase test count.
+
+## Usage
+
+```
+/sdd-test <spec-path>
+```
+
+**Examples:**
+
+- `/sdd-test loan`
+- `/sdd-test enhancements/renewals`
+
+## Arguments
+
+- `$ARGUMENTS` — Relative path under `docs/specs/` that contains `requirements.md`, `design.md`, and `tasks.md`.
+
+## Output
+
+Create or update `docs/specs/$ARGUMENTS/test-report.md` with:
+
+- commands run and their results
+- requirement-to-test matrix
+- scenario coverage status
+- failures and remediation steps
+- accepted gaps with reasons when full automation is not practical
+
+---
+
+## Behavior
+
+### Phase 0: Load Context
+
+1. Read:
+   - `docs/specs/$ARGUMENTS/requirements.md`
+   - `docs/specs/$ARGUMENTS/design.md`
+   - `docs/specs/$ARGUMENTS/tasks.md`
+2. Read project-level context:
+   - `docs/prd.md`
+   - `docs/system-design/design.md`
+   - `docs/detailed-design/detailed-design.md`
+   - root and package-level `CLAUDE.md` files
+3. Identify backend, frontend, and end-to-end scope from the design and tasks.
+4. Extract key requirements and Given/When/Then scenarios from `requirements.md`.
+
+### Phase 1: Unit Tests
+
+- Create or improve backend unit tests where needed.
+- Create or improve frontend unit tests where needed.
+- Map tests back to requirements and scenarios.
+- Prefer focused tests that prove one behavior clearly over broad tests with unclear intent.
+
+Use skills as needed:
+
+- `nestjs-expert`
+- `systematic-debugging`
+- `vercel-react-best-practices`
+- `react-doctor`
+
+### Phase 2: Integration Tests
+
+- Create or improve API integration tests where relevant.
+- Validate auth, request/response shape, and major flows.
+- Cover cross-module behavior that cannot be proven by unit tests alone.
+
+### Phase 3: End-to-End Tests
+
+- Create or improve E2E tests for user-visible workflows.
+- If the work is UI-heavy, prefer `ui-ux-pro-max` when available.
+- Otherwise use `frontend-design` and the system design doc as the UX reference.
+- Use E2E tests for critical user journeys, not every small component state.
+
+### Phase 4: Coverage & Traceability
+
+Create a requirement-to-test matrix so every key requirement has test evidence or an explicit gap.
+
+Recommended matrix columns:
+
+| Requirement | Scenario | Test Type | Test File or Command | Result | Gap or Notes |
+|---|---|---|---|---|---|
+
+### Phase 5: Generate Test Report
+
+Create `docs/specs/$ARGUMENTS/test-report.md`.
+
+The report must include:
+
+1. Document Control
+2. Summary
+3. Backend Unit Tests
+4. Frontend Unit Tests
+5. Integration Tests
+6. E2E Tests
+7. Coverage & Traceability
+8. Remediation
+9. Accepted Gaps, if any
+
+### Phase 6: Report to User
+
+Present overall test status, test counts, requirement coverage, scenario gaps, and top failures. If failures exist, ask whether to fix failures, add missing tests, fix all, or keep only the report.
+
+---
+
+## UX Testing Guidance
+
+When a spec includes meaningful UI/UX behavior, verify more than raw functionality:
+
+- flow clarity
+- responsive behavior
+- state transitions
+- accessibility basics
+- visual consistency with `docs/system-design/design.md`
+
+If `ui-ux-pro-max` is unavailable, use `frontend-design` plus the system design document as the fallback reference.
+
+---
+
+## Testing Rules
+
+- Do not mark a requirement covered just because related code exists.
+- Do not hide missing coverage; record it as an explicit gap with remediation.
+- Prefer repository-specific test commands over hardcoded framework assumptions.
+- If a test is flaky, record the flake and avoid treating it as passing evidence until stabilized.
+- If no automated test is practical, document the manual verification steps and why automation was deferred.