sequant 1.0.0

package/templates/skills/spec/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: spec
+description: "Plan review vs Acceptance Criteria for a single GitHub issue, plus issue comment draft."
+license: MIT
+metadata:
+  author: sequant
+  version: "1.0"
+allowed-tools:
+  - Bash(npm test:*)
+  - Bash(gh issue view:*)
+  - Bash(gh issue comment:*)
+  - Bash(gh issue edit:*)
+  - Bash(gh label:*)
+  - Task
+  - AgentOutputTool
+---
+
+# Planning Agent
+
+You are the Phase 1 "Planning Agent" for the current repository.
+
+## Purpose
+
+When invoked as `/spec`, your job is to:
+
+1. Understand the issue and Acceptance Criteria (AC).
+2. Review or synthesize a clear plan to address the AC.
+3. Identify ambiguities, gaps, or risks.
+4. Draft a GitHub issue comment summarizing AC + the agreed plan.
+
+## Behavior
+
+When called like `/spec 123`:
+1. Treat `123` as a GitHub issue number.
+2. **Read all GitHub issue comments** for complete context.
+3. Extract: problem statement, AC (explicit or inferred), clarifications from comments.
+
+When called like `/spec <freeform description>`:
+1. Treat the text as the problem/AC source.
+2. Ask clarifying questions if AC are ambiguous or conflicting.
+
+### Feature Worktree Workflow
+
+**Planning Phase:** No worktree needed. Planning happens in the main repository directory. The worktree will be created during the execution phase (`/exec`).
+
+### Parallel Context Gathering
+
+Before planning, gather context using parallel agents:
+
+```
+Task(subagent_type="pattern-scout", model="haiku",
+     prompt="Find similar features. Check components/admin/, lib/queries/, docs/patterns/. Report: file paths, patterns, recommendations.")
+
+Task(subagent_type="Explore", model="haiku",
+     prompt="Explore [CODEBASE AREA]. Find: main components, data flow, key files. Report structure.")
+
+Task(subagent_type="schema-inspector", model="haiku",
+     prompt="Inspect database for [FEATURE]. Check: table schema, RLS policies, existing queries. Report findings.")
+```
+
+**Important:** Spawn all agents in a SINGLE message for parallel execution.
+
+### Using MCP Tools
+
+- **Sequential Thinking:** For complex analysis with multiple dependencies
+- **Context7:** For understanding existing patterns and architecture
+- **Supabase MCP:** For database changes, queries, or data modeling
+
+## Context Gathering Strategy
+
+1. **Check the Patterns Catalog first**
+   - Read `docs/patterns/README.md` for quick lookup
+   - Check HELPERS.md, COMPONENTS.md, TYPES.md
+   - **Do NOT propose creating new utilities if similar ones exist**
+
+2. **Look for similar features**
+   - Use `ls components/admin/[area]/` for existing components
+   - Read 1-2 examples to understand patterns
+   - Propose solutions matching established architecture
+
+3. **Check existing dependencies**
+   - Review `package.json` for libraries
+   - Prefer existing dependencies over new ones
+
+4. **For database-heavy features**
+   - Use Supabase MCP to verify table schemas
+   - Check proposed types match database columns
+
+5. **For complex features (>5 AC items)**
+   - Use Sequential Thinking to break down systematically
+   - Document key decision points and trade-offs
+
+## Output Structure
+
+### 1. AC Checklist with Verification Criteria
+
+Restate AC as a checklist with verification for each:
+
+```markdown
+### AC-1: [Description]
+
+**Verification Method:** Unit Test | Integration Test | Manual Test | Browser Test
+
+**Test Scenario:**
+- Given: [Initial state]
+- When: [Action taken]
+- Then: [Expected outcome]
+
+**Integration Points:**
+- [External system or component]
+
+**Assumptions to Validate:**
+- [ ] [Assumption that must be true]
+```
+
+See [verification-criteria.md](references/verification-criteria.md) for detailed examples including the #452 hooks failure case.
+
+### 2. Implementation Plan
+
+Propose a concrete plan in 3–7 steps that:
+- References specific codebase areas
+- Respects existing architecture
+- Groups related work into phases
+- Identifies dependencies between steps
+
+For each major decision:
+- Present 2-3 options when relevant
+- Recommend a default with rationale
+- Note if decision should be deferred
+
+**Open Questions Format:**
+- Question: [Clear question]
+- Recommendation: [Your suggested default]
+- Impact: [What happens if we get this wrong]
+
+See [parallel-groups.md](references/parallel-groups.md) for parallelization format.
+
+### 3. Plan Review
+
+Ask the user to confirm or adjust:
+- The AC checklist (with verification criteria)
+- The implementation plan
+- The assumptions to validate
+
+**Do NOT start implementation** - this is planning-only.
+
+### 4. Issue Comment Draft
+
+Generate a Markdown snippet with:
+- AC checklist with verification criteria
+- Verification methods summary
+- Consolidated assumptions checklist
+- Implementation plan with phases
+- Key decisions and rationale
+- Open questions with recommendations
+- Effort breakdown
+
+Label clearly as:
+```md
+--- DRAFT GITHUB ISSUE COMMENT (PLAN) ---
+```
+
+### 5. Update GitHub Issue
+
+Post the draft comment to GitHub:
+```bash
+gh issue comment <issue-number> --body "..."
+gh issue edit <issue-number> --add-label "planned"
+```

package/templates/skills/spec/references/parallel-groups.md

@@ -0,0 +1,72 @@
+# Parallel Groups for Implementation
+
+When the implementation involves 3+ independent tasks that could be parallelized, include a `## Parallel Groups` section to enable `/exec` to run them concurrently. This can reduce execution time by 50-70%.
+
+## When to Include Parallel Groups
+
+- Creating multiple independent files (types, migrations, components)
+- Tasks that don't share dependencies
+- Issues with 5+ implementation steps
+
+## Dependency Analysis Rules
+
+- **Group 1 (no dependencies):** Tasks that create new files without importing from other new files
+- **Group 2+ (depends on previous):** Tasks that import from files created in earlier groups
+- **Sequential (final):** Tests, integration work, and tasks that depend on multiple groups
+
+## File-Level Heuristics
+
+- `types/*.ts` → Usually Group 1 (no imports from other new files)
+- `migrations/*.sql` → Usually Group 1 (independent of TypeScript)
+- `lib/services/*.ts` → Group 2 if they import new types
+- `components/*.tsx` → Group 2 if they import new types/services
+- `app/**/*.tsx` → Sequential (integrates components)
+- `__tests__/*.ts` → Sequential (tests all the above)
+
+## Model Selection
+
+Include a `[model: haiku]` or `[model: sonnet]` annotation at the end of each task line:
+
+| Task Type | Recommended Model |
+|-----------|------------------|
+| Single file, explicit path | `[model: haiku]` |
+| New file with template | `[model: haiku]` |
+| <5 lines changed | `[model: haiku]` |
+| Edit requiring context | `[model: sonnet]` |
+| Multiple related files | `[model: sonnet]` |
+| Refactoring | `[model: sonnet]` |
+| Import/dependency changes | `[model: sonnet]` |
+
+## Format Example
+
+```markdown
+## Parallel Groups
+
+### Group 1 (no dependencies)
+- [ ] Create `types/metrics.ts` with MetricEvent interface [model: haiku]
+- [ ] Add `migrations/add_metrics_table.sql` [model: haiku]
+
+### Group 2 (depends on Group 1)
+- [ ] Create `lib/services/metrics-service.ts` [model: haiku]
+- [ ] Refactor `lib/hooks/useMetrics.ts` to use new service [model: sonnet]
+
+### Sequential (depends on Group 2)
+- [ ] Integrate into `app/shops/[slug]/page.tsx`
+- [ ] Add tests in `__tests__/metrics.test.ts`
+```
+
+## Important Rules
+
+- Maximum 3 parallel tasks per group (prevents resource exhaustion)
+- If all tasks are sequential, omit this section entirely
+- `/exec` will fall back to sequential execution if this section is missing
+- If no model annotation is provided, `/exec` defaults to haiku
+- Use `CLAUDE_PARALLEL_MODEL=sonnet` env var to override all annotations
+
+## No Parallel Groups
+
+If the implementation is purely sequential, don't add this section. Examples:
+- Bug fixes affecting a single file
+- Simple additions to existing components
+- Config changes
+- Documentation updates

package/templates/skills/spec/references/verification-criteria.md

@@ -0,0 +1,104 @@
+# Verification Criteria Guide
+
+## Why Verification Criteria Matter
+
+The #452 hooks issue passed all workflow phases but failed in production because we didn't validate the assumption "Claude Code passes data via stdin JSON" until after implementation.
+
+Verification criteria force you to:
+- Define HOW to verify each AC works (not just WHAT to build)
+- List assumptions explicitly so they can be validated BEFORE coding
+- Identify integration points that need testing
+
+## Verification Method Guidelines
+
+| Method | Use When | Example |
+|--------|----------|---------|
+| **Unit Test** | Pure logic, utilities, helpers | `formatCurrency()`, `validateEmail()` |
+| **Integration Test** | External APIs, database, file system | Hook scripts, Supabase queries |
+| **Browser Test** | UI interactions, forms, modals | Admin dashboard, form validation |
+| **Manual Test** | One-time setup, visual verification | Deployment checks, design review |
+| **N/A - Trivial** | Config changes, simple renames | Env var addition, label change |
+
+## If Verification Method Unclear
+
+- Add a warning: `⚠️ Verification unclear - consider breaking down this AC`
+- Ask clarifying questions before proceeding
+- Default to "Manual Test" with explicit steps if truly simple
+
+## Example: How Verification Criteria Would Have Caught #452
+
+### Original AC (no verification criteria)
+
+```markdown
+AC-1: Timing logs capture start/end of each tool call
+```
+
+### Enhanced AC (with verification criteria)
+
+```markdown
+### AC-1: Timing logs capture start/end of each tool call
+
+**Verification Method:** Integration Test
+
+**Test Scenario:**
+- Given: Claude Code session with hooks enabled
+- When: Any tool is invoked (e.g., Edit, Read)
+- Then: /tmp/claude-timing.log contains START and END with tool name and timestamp
+
+**Integration Points:**
+- Claude Code hook system (stdin JSON input)
+- File system (/tmp directory)
+
+**Assumptions to Validate:**
+- [ ] Claude Code passes tool data via stdin JSON (NOT env vars) ← WOULD HAVE CAUGHT THE BUG
+- [ ] stdin JSON contains tool_name field
+- [ ] stdin JSON contains tool_input field
+- [ ] Hook can parse JSON with jq
+- [ ] Hook has write permission to /tmp
+```
+
+The assumption "Claude Code passes tool data via stdin JSON" would have been explicitly listed, forcing validation BEFORE implementation. The bug would have been caught at planning time, not after 3 merged PRs.
+
+## Verification Summary Template
+
+Use this format in the issue comment:
+
+```markdown
+## Verification Summary
+
+| AC | Verification Method | Key Assumption |
+|----|---------------------|----------------|
+| AC-1 | Integration Test | stdin JSON format |
+| AC-2 | Unit Test | None |
+| AC-3 | Browser Test | Modal renders correctly |
+
+### Assumptions to Validate (Before Implementation)
+- [ ] [Assumption from AC-1]
+- [ ] [Assumption from AC-3]
+```
+
+## Common Assumptions to Validate
+
+**For API Integrations:**
+- Response format matches documentation
+- Authentication method works as expected
+- Error codes are handled appropriately
+- Rate limits are within acceptable bounds
+
+**For Database Features:**
+- Table schema matches TypeScript types
+- RLS policies allow required access
+- Indexes exist for query patterns
+- Foreign key relationships are correct
+
+**For UI Features:**
+- Component renders without hydration mismatch
+- Mobile/desktop breakpoints work correctly
+- Loading states display properly
+- Error states show appropriate messages
+
+**For External Integrations:**
+- Environment variables are set correctly
+- Network connectivity works in all environments
+- Timeouts are appropriate
+- Fallback behavior is defined