Add devclarity commands

.claude/commands/code-explainer.md

@@ -0,0 +1,57 @@
+Use this template to explain code at a high level and surface gotchas.
+
+## INPUTS
+
+- Code - the code to explain
+- (optional) File path
+
+## INSTRUCTIONS
+
+1. Read the provided code.
+2. Describe what it does in clear, concise terms. Prefer bullets.
+3. Summarize data flow, side effects, external calls, and I/O.
+4. Note domain concepts relevant to the business/application context.
+5. Call out risks, edge cases, and TODOs you would add.
+6. Keep it actionable and brief. Avoid restating the code line-by-line.
+7. When helpful, include a small sequence diagram or pseudo-code.
+8. Keep lines ≤80 chars.
+
+## OUTPUT FORMAT
+
+### What this code does
+
+- ...
+
+### How it works (flow)
+
+- **Inputs:**
+- **Processing:**
+- **Outputs:**
+- **Side effects:**
+
+### Dependencies & contracts
+
+- **Frameworks/libraries used:**
+- **Service/API calls:**
+- **Databases/tables/queues touched:**
+
+### Assumptions
+
+- ...
+
+### Gotchas & risks
+
+- **Concurrency:**
+- **Error handling:**
+- **Performance:**
+- **Security/compliance:**
+- **Observability:**
+
+### TODOs / improvements
+
+- **Quick wins:**
+- **Follow-ups:**
+
+### Example trace (pseudo)
+
+...

.claude/commands/code-review.md

@@ -0,0 +1,94 @@
+Use this template to review a PR diff with focused, actionable feedback.
+
+## INPUTS
+
+- PR diff - the pull request diff to review
+- (optional) PR description
+- (optional) Ticket links
+
+## INSTRUCTIONS
+
+1. Scan the PR diff for correctness, style, security, and performance.
+2. Ground comments in the project context (frameworks, languages, databases, messaging systems).
+3. Prefer specific inline suggestions with minimal working patches.
+4. Flag test gaps and missing docs. Propose concrete test cases.
+5. Label severity: Blocker, Major, Minor, Nit.
+6. Keep lines ≤80 chars.
+
+## OUTPUT FORMAT
+
+### Summary
+
+- **Scope:**
+- **Impact:**
+- **Risk level:**
+
+### Positives
+
+- **Code quality wins:**
+- **Good patterns:**
+- **Tests/documentation:**
+
+### Issues by Severity
+
+#### Blockers
+
+- [file:line] Problem → Why it matters → Fix suggestion
+  ```
+  // patchlet
+  ```
+
+#### Major
+
+- ...
+
+#### Minor
+
+- ...
+
+#### Nits
+
+- ...
+
+### Security & Compliance
+
+- **Authentication/authorization:**
+- **Input validation/injection prevention:**
+- **Secrets/logging/sensitive data:**
+- **Third-party integrations:**
+- **Data privacy/compliance:**
+
+### Performance
+
+- **Hot paths:**
+- **Database query optimization:**
+- **Caching/TTL:**
+- **Async/concurrency handling:**
+
+### Testing Gaps
+
+- **Unit:**
+- **Integration/e2e:**
+- **Property/fuzz:**
+- **Load/reliability:**
+
+### Documentation
+
+- **Changelog:**
+- **Architecture notes:**
+- **README/code comments:**
+
+### Inline Review
+
+- [file path]
+  - line X: comment
+  - line Y: comment
+
+### Review Checklist
+
+- [ ] Builds/CI green
+- [ ] Lint/format pass
+- [ ] Tests updated/added
+- [ ] Backward compatible
+- [ ] Feature flagged
+- [ ] Observability added

.claude/commands/file-cleaner.md

@@ -0,0 +1,51 @@
+Use this template to improve readability of a single source file without changing behavior.
+
+## INPUTS
+
+- Code - the code to clean up
+- (optional) File path
+
+## INSTRUCTIONS
+
+1. Keep behavior identical. Avoid semantic changes.
+2. Rename unclear variables and functions to intent-revealing names.
+3. Remove redundant or noisy comments. Keep value-adding docs.
+4. Add comments where logic is non-obvious (why > what).
+5. Reformat for consistency per project standards.
+6. Ensure lints and static analysis pass.
+7. Surface any low-risk micro-optimizations as suggestions, not changes.
+8. Keep lines ≤80 chars.
+
+## OUTPUT FORMAT
+
+### Summary
+
+- **What improved:**
+- **Risks:**
+
+### Cleaned file
+
+```
+// full revised file
+```
+
+### Diff (for review)
+
+```diff
+- old
++ new
+```
+
+### Naming changes
+
+- `old_name` → `new_name`: reason
+
+### Lint & style
+
+- **Tools used** (e.g., language-specific linters, formatters):
+- **Rules touched:**
+
+### Notes for follow-up (optional)
+
+- **Larger refactors that were out of scope:**
+- **Test additions recommended:**

.claude/commands/implement-it.md

@@ -0,0 +1,77 @@
+Use this template to turn a user story into a concrete plan, skeletons, and tests.
+
+## INPUTS
+
+- Ticket - the user story or ticket to implement
+- (optional) Non-functional requirements
+- (optional) Acceptance criteria
+- (optional) Code - existing code context
+
+## INSTRUCTIONS
+
+1. Extract goals, actors, and constraints from the ticket.
+2. Make explicit assumptions and edge cases.
+3. Produce a step-by-step plan across affected layers:
+   - Frontend (web/mobile applications)
+   - APIs (backend services)
+   - Integrations (messaging, external services)
+   - Data (databases, data warehouses, ETL)
+   - Authentication/authorization systems
+4. Provide key code skeletons and interface contracts.
+5. Define tests to add (unit, integration, e2e).
+6. Include rollout, feature flag, and observability plan.
+7. Keep lines ≤80 chars.
+
+## OUTPUT FORMAT
+
+### Story summary
+
+- **Goal:**
+- **Users:**
+- **Success criteria:**
+
+### Assumptions & constraints
+
+- ...
+
+### Step-by-step plan
+
+1. ...
+2. ...
+
+### Architecture impact
+
+- **Modules/services:**
+- **Events/messaging:**
+- **Schemas/migrations:**
+
+### API & model contracts (sketch)
+
+### Key code skeletons
+
+- **Components/services:**
+- **Workers/consumers:**
+- **Repositories/queries:**
+
+### Tests to add
+
+- **Unit:**
+- **Integration:**
+- **e2e:**
+- **Property/fuzz:**
+- **Load:**
+
+### Rollout & safety
+
+- **Feature flag:**
+- **Backward compatibility:**
+- **Metrics/logs/traces:**
+- **Runbook:**
+
+### Risks & mitigations
+
+- ...
+
+### Definition of done
+
+- ...

.claude/commands/refactor.md

@@ -0,0 +1,67 @@
+Use this template to refactor legacy code toward a stated goal, with safety.
+
+## INPUTS
+
+- Code - the code to refactor
+- Refactor goal - e.g., improve readability, adopt a pattern, reduce coupling
+- (optional) Constraints
+
+## INSTRUCTIONS
+
+1. Restate the refactor goal and constraints. Preserve behavior.
+2. Propose a target design (patterns, boundaries, contracts).
+3. Provide a refactored version or representative slices.
+4. Explain rationale trade-offs (perf, readability, testability).
+5. Add safety checks: tests, metrics, and rollout steps.
+6. Show an incremental plan of small commits.
+7. Keep lines ≤80 chars.
+
+## OUTPUT FORMAT
+
+### Goal & constraints
+
+- **Goal:**
+- **Constraints:**
+
+### Diagnosis
+
+- **Smells:**
+- **Risks:**
+
+### Target design
+
+- **Patterns:**
+- **Module boundaries:**
+- **Public interfaces:**
+
+### Refactored code (slice)
+
+```diff
+- old
++ new
+```
+
+### Rationale
+
+- **Why this is better:**
+- **Alternatives considered:**
+
+### Safety & verification
+
+- **Regression tests:**
+- **Contracts/property checks:**
+- **Perf baselines:**
+- **Observability:**
+
+### Incremental plan
+
+1. ...
+2. ...
+
+### Backout plan
+
+- **How to revert safely:**
+
+### Follow-ups
+
+- ...

.claude/commands/task-creator.md

@@ -0,0 +1,66 @@
+Use this template to break a feature spec into sprint-ready engineering tasks.
+
+## INPUTS
+
+- Feature spec - the feature specification to break down
+- (optional) Code - existing code context
+
+## INSTRUCTIONS
+
+1. Parse the feature spec into vertical slices deliverable per sprint.
+2. For each task, define acceptance criteria and effort (S/M/L or hours).
+3. Capture dependencies (code, teams, data, compliance).
+4. Include testing, docs, and observability per task.
+5. Identify cross-cutting NFRs (perf, security, accessibility).
+6. Keep lines ≤80 chars.
+
+## OUTPUT FORMAT
+
+### Work breakdown
+
+| ID  | Title | Owner | Effort | Depends on |
+| --- | ----- | ----- | ------ | ---------- |
+| T1  | ...   |       | M      | T0         |
+
+### Tasks
+
+**T1:**
+
+- **Description:**
+- **Acceptance criteria:**
+- **Effort:**
+- **Dependencies:**
+- **Risk:**
+- **Test plan:**
+- **Observability:**
+- **Docs:**
+
+**T2:**
+
+- ...
+
+### Milestones
+
+- **M1:** Prototype
+- **M2:** Beta/feature-flagged
+- **M3:** GA
+
+### NFRs
+
+- **Performance:**
+- **Security/compliance:**
+- **Accessibility:**
+- **Internationalization:**
+- **Reliability/SLOs:**
+
+### Analytics & success metrics
+
+- **KPIs/dashboards:**
+
+### Definition of done (global)
+
+- Code reviewed, linted, and formatted
+- Tests written, passing, and stable
+- Feature flagged and togglable
+- Metrics/logs/traces in place
+- Docs updated (README/ADR/changelog)

.claude/commands/test-writer.md

@@ -0,0 +1,68 @@
+Use this template to generate thorough tests for a function or module.
+
+## INPUTS
+
+- Code - the code to write tests for
+- (optional) Behavior spec
+- (optional) Test tech - frameworks, runners
+
+## INSTRUCTIONS
+
+1. Identify inputs, outputs, and invariants. Derive test matrix.
+2. Cover happy path, edge cases, and failure modes.
+3. Include unit and integration tests matching the project's testing stack.
+4. Provide fixtures, mocks, and stubs with minimal boilerplate.
+5. Add property/fuzz tests for parsers and validators.
+6. Include performance and concurrency probes if relevant.
+7. Ensure tests are deterministic and parallel-safe.
+8. Keep lines ≤80 chars.
+
+## OUTPUT FORMAT
+
+### Scope
+
+- **Subject:**
+- **Responsibilities:**
+
+### Test matrix
+
+| Case | Inputs | Setup | Expected |
+| ---- | ------ | ----- | -------- |
+| 1    | ...    | ...   | ...      |
+
+### Unit tests (sketches)
+
+```[language]
+// Framework-specific unit test examples
+```
+
+### Integration tests
+
+- **Environment:**
+- **Data seeding/migrations:**
+- **External dependencies:**
+- **Service integrations:**
+
+### Property/fuzz tests
+
+- **Properties to hold:**
+- **Generators:**
+
+### Performance checks
+
+- **Baselines:**
+- **Thresholds:**
+
+### Observability assertions
+
+- **Logs/metrics/traces expected:**
+
+### Coverage goals
+
+- **Line:**
+- **Branch:**
+- **Mutation (optional):**
+
+### Run commands
+
+- ...