forgedev 1.2.0 → 1.3.0

package/templates/claude-code/commands/generate-uat.md

@@ -1,35 +1,107 @@
-Generate UAT (User Acceptance Test) scenarios for this project.
-
-## Instructions
-
-1. Read the codebase to identify all user-facing features:
-   - API endpoints and their purposes
-   - UI pages and forms
-   - Authentication flows
-   - Business logic and workflows
-
-2. For each feature, create test scenarios covering:
-   - Happy path (expected usage)
-   - Edge cases (empty inputs, max values, special characters)
-   - Error cases (invalid data, unauthorized access, network failures)
-   - Integration points (features that depend on each other)
-
-3. Prioritize scenarios:
-   - P0: Critical path — app is broken if these fail (login, core CRUD, data integrity)
-   - P1: Important — significant user impact (permissions, validation, error handling)
-   - P2: Nice to have — minor features, cosmetic issues
-
-## Output
-
-Generate two files:
-
-### docs/uat/UAT_TEMPLATE.md
-Markdown table with columns:
-| ID | Feature | Scenario | Steps | Expected Result | Priority |
-
-### docs/uat/UAT_CHECKLIST.csv
-CSV with columns:
-ID,Feature,Scenario,Priority,Status,Tester,Date,Notes
-
-Include at least 5 P0 scenarios, 10 P1 scenarios, and 5 P2 scenarios.
-Do NOT modify any code — this is a documentation-only task.
+Generate comprehensive UAT (User Acceptance Test) scenarios by analyzing the actual codebase, not guessing.
+
+## Phase 1: Deep Code Analysis
+
+Read the codebase systematically to build a complete feature inventory:
+
+### 1.1 Route/Endpoint Discovery
+- Read ALL route files (API routes, page routes, middleware)
+- For each route: extract HTTP method, path, parameters, request body schema, response schema
+- Note which routes require authentication and which roles can access them
+
+### 1.2 Business Logic Extraction
+- Read service/logic files (not just routes, the actual business logic)
+- For each function that transforms data: extract the input, the rule, and the expected output
+- Examples: "if order total > $100, apply 10% discount", "if user.role !== 'admin', return 403"
+- Record these as testable assertions with computed expected values
+
+### 1.3 UI Page Inventory (frontend projects)
+- Read all page/view components
+- For each page: list all interactive elements (forms, buttons, dropdowns, modals, tabs)
+- Note form validation rules (required fields, min/max, regex patterns)
+- Note conditional rendering (what appears/disappears based on state)
+
+### 1.4 Data Flow Mapping
+- Trace CRUD lifecycles: where is data created, read, updated, deleted?
+- Map cross-page dependencies: "creating X on page A should show X on page B"
+- Identify cascade effects: "deleting user should delete their posts"
+
+### 1.5 Integration Points
+- External API calls (payment, email, auth providers)
+- File uploads/downloads
+- WebSocket/real-time features
+- Background jobs/queues
+
+## Phase 2: Scenario Generation
+
+For EVERY feature discovered in Phase 1, generate scenarios in these categories:
+
+### Category A: Happy Path
+- Standard usage with valid data
+- Include specific test data values and computed expected results
+- Example: "Submit order with 3 items totaling $150 -> expect 10% discount applied, total $135"
+
+### Category B: Business Logic Verification
+- Test every conditional branch found in Phase 1.2
+- Include boundary values (exactly at threshold, one above, one below)
+- Example: "Order total $99.99 -> no discount; $100.00 -> 10% discount; $100.01 -> 10% discount"
+
+### Category C: Data Flow / Multi-Step Workflows
+- CRUD lifecycle: create -> verify exists -> update -> verify changed -> delete -> verify gone
+- Cross-page: create on page A -> navigate to page B -> verify appears
+- Concurrent: two users modifying same resource
+
+### Category D: Validation & Error Handling
+- Every form field: empty, too short, too long, special characters, SQL injection attempt, XSS attempt
+- API: missing required fields, wrong types, invalid values
+- Auth: unauthenticated access, wrong role, expired token
+
+### Category E: Edge Cases
+- Empty states (no data, first-time user)
+- Maximum load (list with 1000 items, very long text input)
+- Rapid actions (double-click submit, back button during save)
+- Network failure (what happens if API call fails mid-operation?)
+
+### Category F: Permissions & Roles
+- For each role: what can they access, what is denied?
+- Role escalation: can a regular user access admin endpoints?
+- Test every route/page against each role
+
+## Phase 3: Prioritization
+
+- **P0 (Critical)**: Authentication, core CRUD, data integrity, payment flows, security boundaries
+- **P1 (Important)**: Validation, permissions, error handling, search/filter, export
+- **P2 (Standard)**: UI polish, empty states, loading states, edge cases
+- **P3 (Low)**: Cosmetic issues, minor UX improvements
+
+Target: Generate scenarios proportional to the codebase size. A typical app should have:
+- 1-2 scenarios per API endpoint
+- 1-2 scenarios per UI page
+- 3-5 scenarios per business logic rule
+- At minimum: 10 P0, 20 P1, 15 P2, 5 P3
+
+## Output
+
+Generate three files:
+
+### docs/uat/UAT_TEMPLATE.md
+Full scenario document with columns:
+| ID | Feature | Scenario | Steps | Expected Result | Priority | Source |
+
+The **Source** column references the file and line where the logic was found (e.g., `src/services/order.js:45`).
+
+### docs/uat/UAT_CHECKLIST.csv
+CSV for tracking:
+ID,Feature,Scenario,Priority,Status,Tester,Date,Notes
+
+### docs/uat/BUSINESS_RULES.md
+Extracted business rules with test values:
+```
+## Rule: [name]
+- Source: [file:line]
+- Logic: [description]
+- Test cases:
+  | Input | Expected Output | Boundary? |
+```
+
+Do NOT modify any code. This is a documentation-only task.

package/templates/claude-code/commands/help.md

@@ -0,0 +1,68 @@
+Ask the developer: "What are you trying to do?" Then guide them to the right workflow.
+
+## Decision Tree
+
+Based on the developer's answer, recommend the appropriate workflow:
+
+### "I want to start building a feature"
+→ Run `/plan` to create an implementation plan first
+
+### "I want to build frontend UI"
+→ Run `/build-ui` to generate UI with AI-powered tools
+
+### "I want to write tests first"
+→ Run `/tdd` to follow test-driven development
+
+### "I have build errors / lint errors / type errors"
+→ Run `/build-fix` to fix them incrementally
+
+### "I want to check if everything is working"
+→ Run `/status` for a quick dashboard
+→ Run `/verify-all` for a thorough check
+
+### "My code is messy / I have duplicate code / files are too long"
+→ Run `/simplify` to find duplicates, split long files, and extract shared utilities
+
+### "I want to review my code before committing"
+→ Run `/code-review` for security + quality review
+
+### "I'm ready to make a PR"
+→ Run `/pre-pr` for the complete pre-PR checklist
+
+### "I want to run UAT"
+→ Run `/run-uat` for one-off or sandbox UAT runs using the checklist/template flow
+→ Run `/live-uat` for UAT against live-like data or long-lived UAT environments
+
+### "I want a full audit of the project"
+→ Run `/full-audit` to run every review agent
+
+### "I want to check security"
+→ Run `/audit-security` for a focused security audit
+
+### "I want to generate documentation"
+→ `/generate-prd` for a Product Requirements Document
+→ `/generate-sdd` for a Software Design Document
+→ `/generate-uat` for UAT test scenarios
+
+### "I don't know what to work on"
+→ Run `/next` to figure out the highest-priority task
+
+### "I think I'm done with this task"
+→ Just commit. The pre-commit gate automatically runs lint, tests, and security checks.
+→ If the gate blocks the commit, run `/build-fix` to resolve issues.
+
+### "I want to save my progress and come back later"
+→ Run `/save-session` to save context
+→ Run `/resume-session` to pick up where you left off
+
+### "I want to see all available workflows"
+→ Run `/workflows` for the complete list
+
+## All Commands Reference
+
+**Daily:** `/workflows`, `/status`, `/next`
+**Development:** `/plan`, `/tdd`, `/build-fix`, `/fix-loop`, `/build-ui`, `/code-review`, `/simplify`
+**Verification:** `/verify-all`, `/full-audit`, `/audit-spec`, `/audit-wiring`, `/audit-security`, `/verify-intent`
+**Release:** `/pre-pr`, `/run-uat`, `/live-uat`
+**Generation:** `/generate-prd`, `/generate-sdd`, `/generate-uat`, `/optimize-claude-md`
+**Session:** `/save-session`, `/resume-session`

package/templates/claude-code/commands/live-uat.md

@@ -0,0 +1,268 @@
+Run a comprehensive live UAT by interacting with the running application in a real browser or via API calls.
+
+This is NOT a code review or automated test run. You will physically navigate the app, click buttons, fill forms, test every feature, and verify outputs against ground truth.
+
+## Step 1: Detect Testing Mode
+
+Determine what kind of application this is by reading the project structure:
+
+- **Has frontend** (Next.js, React, Vue, etc.) → Browser-based testing. Requires a browser automation tool.
+- **API only** (FastAPI, Express, etc.) → Endpoint testing via curl, httpie, or API client MCP.
+- **Full-stack** → Both browser AND API testing.
+
+### Browser Testing Setup (frontend projects only)
+Check which browser tool is available:
+- `mcp__Claude_in_Chrome__*` tools (Claude in Chrome extension) — preferred
+- Playwright MCP or similar browser automation MCP
+- Any other browser MCP tool
+
+If none are available, tell the user: "Install a browser automation tool (Claude in Chrome extension, Playwright MCP, etc.) to run live UI testing. Alternatively, I can test API endpoints only."
+
+## Step 2: Gather Test Parameters
+
+Ask the user these questions before starting. Skip questions that don't apply to the detected stack.
+
+1. **App URL**: What URL should I test against? (e.g., `http://localhost:3000`, a staging URL)
+2. **Login**: What account(s) should I use? (You will type passwords yourself)
+3. **Multiple roles?**: Are there different user roles to test? (admin, user, viewer, etc.)
+4. **Existing UAT document**: Check if `docs/uat/UAT_TEMPLATE.md` exists. If it does, ask: "I found your UAT scenarios. Should I test against these, or do a full exploratory pass?"
+5. **Ground truth documents**: Do you have source documents that the app's outputs should be evaluated against? (e.g., a dataset the app should parse correctly, a document it should analyze accurately)
+6. **Scope**: Test ALL pages/endpoints, or specific ones?
+7. **Server logs**: How do I check server logs when errors occur? (e.g., terminal output, `docker logs`, cloud logging command)
+
+## Step 3: Testing Rules
+
+### Rule 1: Test Every Interactive Element
+For every page or endpoint:
+- Every button, link, tab, toggle, dropdown, filter
+- Every form (fill, submit, check validation and error states)
+- Every export/download (verify correct file format for the content type)
+- Every AI/ML feature (verify output quality, not just that it runs)
+- Every modal/dialog (open, interact, close)
+- Every navigation path (sidebar, breadcrumbs, back button)
+
+For API-only projects:
+- Every endpoint (all HTTP methods)
+- Every query parameter and request body variation
+- Authentication and authorization on each endpoint
+- Error responses (400, 401, 403, 404, 422, 500)
+- Response schema validation
+
+### Rule 2: Verify Output Quality
+Do NOT just check if features respond. Verify the CONTENT:
+- Compare outputs against ground truth documents (if provided)
+- Compare against existing UAT scenarios in `docs/uat/UAT_TEMPLATE.md` (if they exist)
+- Flag hallucinated data, missing findings, incorrect results
+- If a feature says "0 results" for input that clearly has results, that is CRITICAL
+- Check that outputs reference actual data, not generic boilerplate
+
+### Rule 3: Fix Bugs in Parallel
+When a bug is found:
+- Log it immediately in the results file with severity (Critical / High / Medium / Low)
+- If the bug is in the codebase and fixable: spawn a background agent to fix it while you continue testing
+- Do NOT stop testing to fix bugs unless they completely block further testing — except when the 15+ bug quality gate in Rule 4 is met (then stop immediately, save state, list all bugs, and generate the resume prompt)
+- Track fix status: Found, Fixing, Fixed, Wont Fix
+
+### Rule 4: Quality Gate (Overrides Rule 3) + Screenshot and Evidence Strategy
+- **Bugs 0-10**: Screenshots of failures AND key milestones (page loads, successful operations)
+- **Bugs 11-15**: Screenshots on FAILURES only. Use text-based page reads for passes.
+- **Bugs 15+**: STOP TESTING IMMEDIATELY (this overrides Rule 3). Save state, list all bugs found so far, and generate the resume prompt before continuing any further work.
+
+### Rule 5: Save Progress Continuously
+- **Every 3-4 pages or endpoints**: Write results to `docs/sessions/live-uat-YYYY-MM-DD.md`
+- **Every bug**: Update the bug table immediately
+- **At ~70% context usage**: Proactively save ALL results, generate a self-contained resume prompt, and tell the user where to find it
+
+### Rule 6: Check Server Logs on Every Error
+On any 500, timeout, or unexpected behavior:
+- Run the log check command the user provided
+- Include error details in the bug report
+- Note the timestamp and endpoint
+
+### Rule 7: Create Test Data When Needed
+If a feature requires data that doesn't exist:
+- Create it (add a record, upload a file, seed data)
+- Don't skip testing because data is missing
+- Document what test data you created so it can be cleaned up
+
+### Rule 8: Quality Audit
+Before marking any feature PASS, verify:
+- Destructive actions use confirmation modals (not browser `confirm()`)
+- Forms have validation and clear error messages
+- Loading states are present (skeletons or spinners)
+- Empty states have descriptions and call-to-action buttons
+- Exports use the correct format for the content type (e.g., reports = PDF/DOCX, data = CSV/XLSX)
+
+### Rule 9: Business Logic Verification
+Before testing, read the source code for business rules. For each rule found:
+- Test the exact boundary values (at threshold, one above, one below)
+- Verify computed outputs match what the code should produce
+- Example: if code says `if (total > 100) applyDiscount(0.1)`, test with total=99.99, 100.00, 100.01
+- Log the source file and line for each business rule tested
+
+### Rule 10: Data Flow / CRUD Lifecycle Testing
+For every entity type in the app (users, orders, posts, etc.):
+1. **Create** an item with valid data, verify it appears in listings
+2. **Read** the item detail page/endpoint, verify all fields are correct
+3. **Update** the item, verify changes persist after page reload
+4. **Delete** the item, verify it disappears from all listings and related pages
+5. Test cascade effects: deleting a parent should handle children correctly
+
+### Rule 11: Regression Tracking
+Check if a previous live-uat session exists (`docs/sessions/live-uat-*.md`):
+- If yes, load the previous bug table and results
+- After testing, compare: flag any previously-passing features that now fail as **REGRESSION**
+- Flag any previously-fixed bugs that have returned as **REGRESSION: BUG RETURNED**
+- Include a regression summary section in the results
+
+## Step 4: Testing Workflow
+
+### Phase 1: Pre-Flight
+1. Verify the app URL is accessible
+2. Get browser tab or API client ready
+3. Login (let user type passwords)
+4. Verify the app loads correctly
+
+### Phase 2: Systematic Testing
+**For frontend apps** — test page by page:
+1. Navigate to page, verify it loads
+2. Read page content, note what is displayed
+3. Click every tab, verify content changes
+4. Click every button, verify behavior
+5. Test every form: fill, submit, verify
+6. Test every filter/search, verify results
+7. Test every export/download, verify format
+8. Test every AI feature, verify output against ground truth
+9. Log PASS or FAIL with what you observed
+
+**For API-only apps** — test endpoint by endpoint:
+1. Send request, verify response status and schema
+2. Test with valid data (happy path)
+3. Test with invalid data (validation errors)
+4. Test without auth (should get 401)
+5. Test with wrong role (should get 403)
+6. Test edge cases (empty body, large payload, special characters)
+7. Log PASS or FAIL with response details
+
+### Phase 3: Business Logic Verification
+1. Read source code for business rules (see Rule 9)
+2. For each rule, test boundary values and computed expected outputs
+3. If `docs/uat/BUSINESS_RULES.md` exists (from `/generate-uat`), use it as the test plan
+4. Log each rule tested with: source file, input, expected output, actual output, PASS/FAIL
+
+### Phase 4: Data Flow / CRUD Lifecycle
+1. Identify all entity types from the database schema or API routes
+2. For each entity: run the Create -> Read -> Update -> Delete cycle (see Rule 10)
+3. Test cross-page visibility: create on page A, verify on page B
+4. Test cascade deletes and referential integrity
+
+### Phase 5: Cross-Cutting Concerns
+- Role-based access: login as different roles, verify permissions
+- AI/ML features: test with real data, verify accuracy
+- Reports and exports: generate every type, verify content
+- Settings and admin: test every configuration option
+
+### Phase 6: Regression Check
+1. Load previous live-uat results if they exist (see Rule 11)
+2. Compare current results against previous pass/fail status
+3. Flag any regressions prominently
+
+### Phase 7: Server Health
+- Check server logs for errors generated during testing
+- Report any unhandled exceptions or warnings
+
+## Step 5: Results Format
+
+Write results to `docs/sessions/live-uat-YYYY-MM-DD.md`:
+
+```
+# Live UAT Results — [Date]
+
+## Environment
+- URL: [app url]
+- Stack: [detected stack]
+- Roles tested: [list]
+
+## Page/Endpoint: [Name]
+| # | Action | Result | Notes |
+|---|--------|--------|-------|
+| 1 | Page loads | PASS | Shows expected content |
+| 2 | Submit form | FAIL | Bug #3: validation missing |
+
+## Bugs Found
+| # | Bug | Severity | Location | Status |
+|---|-----|----------|----------|--------|
+| 1 | Missing validation on email | Medium | /signup | Fixed |
+| 2 | AI returns empty results | Critical | /analysis | Fixing |
+
+## Output Quality (if applicable)
+| Feature | Expected | Actual | Score |
+|---------|----------|--------|-------|
+| Data parsing | 26 items | 24 found | 8/10 |
+| Report generation | Full report | Missing section 3 | 6/10 |
+
+## Business Logic Verification
+| # | Rule | Source | Input | Expected | Actual | Result |
+|---|------|--------|-------|----------|--------|--------|
+| 1 | Discount > $100 | src/order.js:45 | $150 | $135 | $135 | PASS |
+| 2 | Admin-only endpoint | src/api/admin.js:12 | role=user | 403 | 200 | FAIL |
+
+## Data Flow / CRUD Lifecycle
+| Entity | Create | Read | Update | Delete | Cascade | Notes |
+|--------|--------|------|--------|--------|---------|-------|
+| User | PASS | PASS | PASS | FAIL | N/A | Bug #5 |
+| Order | PASS | PASS | PASS | PASS | PASS | |
+
+## Regressions (vs previous session)
+| Feature | Previous | Current | Status |
+|---------|----------|---------|--------|
+| Login flow | PASS | PASS | Stable |
+| Export PDF | PASS | FAIL | REGRESSION |
+
+## Summary
+- Total actions tested: X | PASS: X | FAIL: X
+- Business rules tested: X | PASS: X | FAIL: X
+- CRUD lifecycles tested: X | PASS: X | FAIL: X
+- Regressions found: X
+- Bugs: X (Critical: X, High: X, Medium: X, Low: X)
+- Fixed during testing: X | Remaining: X
+- Recommendation: Ship / Fix and retest / Needs rework
+```
+
+## Step 6: Session Resume Prompt
+
+When saving a resume prompt (on pause, bug overflow, or context limit), write to `docs/sessions/live-uat-resume-YYYY-MM-DD.md`:
+
+```
+# Resume Live UAT — [Date] Session [N+1]
+
+## Context
+Read these files first:
+1. docs/sessions/live-uat-YYYY-MM-DD.md — results so far
+2. docs/uat/UAT_TEMPLATE.md — test scenarios (if exists)
+
+## Tested So Far
+[list pages/endpoints with PASS/FAIL counts]
+
+## Remaining
+[list untested pages/endpoints]
+
+## Open Bugs
+[full bug table with status]
+
+## Test Data Created
+[list of data created during testing, for cleanup]
+
+## Login
+User will re-enter passwords
+
+## App URL
+[url]
+
+## Resume From
+[exact page/endpoint and step number]
+```
+
+---
+
+**Ready to start. Tell me the app URL, how to login, and whether you have ground truth documents to test against.**

package/templates/claude-code/commands/optimize-claude-md.md

@@ -1,5 +1,19 @@
 Analyze and optimize CLAUDE.md for this project.
 
+## Intent Contract
+
+Before invoking any agent, construct this block and pass it as context:
+
+```
+INTENT_CONTRACT:
+  INTENT: "[User's original request verbatim]"
+  SCOPE: "[Files/areas to examine]"
+  SUCCESS_CRITERIA: "[What done looks like]"
+  INTENT_HASH: "[First 8 chars of SHA256(INTENT|SCOPE|SUCCESS_CRITERIA)]"
+```
+
+Every agent invocation MUST include this block. If an agent's output does not echo back the INTENT_HASH, its results are considered unverified.
+
 ## Instructions
 
 1. Read the current CLAUDE.md and measure its size (line count).
@@ -27,5 +41,5 @@ Analyze and optimize CLAUDE.md for this project.
 ## Rules
 - Do NOT modify any files until I explicitly approve the proposal
 - Show the current line count and target line count
-- Preserve all information — nothing gets deleted, only relocated
+- Preserve all information. Nothing gets deleted, only relocated
 - Each skill file needs frontmatter: name, description, and relevant file patterns

package/templates/claude-code/commands/plan.md

@@ -16,6 +16,6 @@ Invoke the **planner** agent to create a comprehensive implementation plan befor
 ## Integration
 
 After planning, use these commands:
-- `/tdd` — implement with test-driven development
-- `/build-fix` — fix any build errors that come up
-- `/code-review` — review the completed implementation
+- `/tdd` - implement with test-driven development
+- `/build-fix` - fix any build errors that come up
+- `/code-review` - review the completed implementation

package/templates/claude-code/commands/pre-pr.md

@@ -1,19 +1,57 @@
-Run the complete pre-PR checklist before creating a pull request.
-
-1. Run lint: `{{LINT_COMMAND}}`
-2. Run type check: `{{TYPE_CHECK_COMMAND}}`
-3. Run tests: `{{TEST_COMMAND}}`
-4. Check for uncommitted changes
-5. Launch code-quality-reviewer agent on the PR diff
-6. Launch security-reviewer agent on the PR diff
-7. Check that no `.env` files or secrets are staged
-
-If all checks pass, output:
-- Summary of changes (files changed, lines added/removed)
-- Suggested PR title and description
-- Any warnings (non-blocking issues)
-
-If any check fails, output:
-- Which checks failed
-- How to fix each failure
-- Do NOT proceed with PR creation
+Prepare a pull request. Quality checks (lint, tests, code review, security) already ran at commit time via the pre-commit gate. This command handles PR-specific preparation.
+
+## Intent Contract
+
+Before invoking any agent, construct this block and pass it as context:
+
+```
+INTENT_CONTRACT:
+  INTENT: "[User's original request verbatim]"
+  SCOPE: "[Files/areas to examine]"
+  SUCCESS_CRITERIA: "[What done looks like]"
+  INTENT_HASH: "[First 8 chars of SHA256(INTENT|SCOPE|SUCCESS_CRITERIA)]"
+```
+
+Every agent invocation MUST include this block. If an agent's output does not echo back the INTENT_HASH, its results are considered unverified.
+
+## Step 1: Verify Commit State
+
+1. Check that all changes are committed (no uncommitted changes)
+2. Check that the branch is pushed to remote
+3. If there are uncommitted changes, tell the user to commit first (the pre-commit gate will handle quality checks)
+
+## Step 2: Review the Full PR Diff
+
+1. Get the base branch: `git rev-parse --abbrev-ref HEAD@{upstream} 2>/dev/null || echo main`
+2. Get the full diff: `git diff <base-branch>...HEAD`
+3. Get all commits in this branch: `git log <base-branch>..HEAD --oneline`
+4. Review the full diff for:
+   - Coherence: do all changes serve the same purpose?
+   - Completeness: are there any half-finished features?
+   - Any `.env` files, secrets, or debug code that slipped through
+
+## Step 3: Generate PR Description
+
+Based on the diff and commit history, generate:
+
+```
+## Summary
+<1-3 bullet points describing what changed and why>
+
+## Changes
+<grouped list of changes by area>
+
+## Test plan
+<bulleted checklist of what to test>
+```
+
+## Step 4: Create PR
+
+Use `gh pr create` with the generated title and description.
+If the user hasn't pushed yet, push first with `git push -u origin <branch>`.
+
+## Output
+
+- PR URL
+- Summary of what was included
+- Any warnings (large diff, many files, etc.)

package/templates/claude-code/commands/product-strategist.md

@@ -0,0 +1,21 @@
+Run the product-strategist agent to evaluate this project against real competitors and industry best practices.
+
+## What This Does
+
+The product-strategist agent will:
+1. Read your project structure, CLAUDE.md, and any product docs
+2. **Web search** for 5-7 direct competitors and best-in-class examples
+3. Evaluate your project against them across DX, API design, testing, security, observability, deployment, and docs
+4. Score each category: AHEAD, ON PAR, or BEHIND with specific competitor benchmarks
+5. Recommend strategic improvements with a prioritized roadmap
+
+## How To Use
+
+Run this command. The agent will ask no questions — it researches autonomously and returns a full competitive analysis with actionable recommendations.
+
+## When To Use
+
+- Before planning a new major feature (to avoid building what competitors already do better)
+- Before a launch or public release (to identify gaps)
+- Quarterly, to track how your project compares to the evolving landscape
+- When deciding between build vs. buy for a capability

package/templates/claude-code/commands/resume-session.md

@@ -2,8 +2,8 @@ Load a saved session file and orient before doing any work.
 
 ## Process
 
-1. **Find the session file** — Check `docs/sessions/` for the most recent `*-session.md` file
-2. **Read the entire file** — Do not summarize yet
+1. **Find the session file**: Check `docs/sessions/` for the most recent `*-session.md` file
+2. **Read the entire file**: Do not summarize yet
 3. **Present a briefing** in this format:
 
 ```
@@ -33,18 +33,18 @@ NEXT STEP:
 Ready to continue. What would you like to do?
 ```
 
-4. **WAIT for the user** — Do NOT start working automatically
+4. **WAIT for the user**. Do NOT start working automatically
 
 ## Edge Cases
 
-- **No session files found** — Tell the user to run `/save-session` first
-- **Session references deleted files** — Note "⚠️ file.ts referenced but not found on disk"
-- **Session is > 7 days old** — Note "⚠️ This session is N days old, things may have changed"
-- **Empty or malformed file** — Report and suggest creating a new session
+- **No session files found**: Tell the user to run `/save-session` first
+- **Session references deleted files**: Note "file.ts referenced but not found on disk"
+- **Session is > 7 days old**: Note "This session is N days old, things may have changed"
+- **Empty or malformed file**: Report and suggest creating a new session
 
 ## Rules
 
-- Never modify the session file — it's a read-only historical record
-- Never skip the "What Not To Retry" section — it's the most important
+- Never modify the session file. It's a read-only historical record
+- Never skip the "What Not To Retry" section. It's the most important
 - Always wait for the user before starting work
-- If the next step is defined and the user says "continue" — proceed with that exact step
+- If the next step is defined and the user says "continue", proceed with that exact step