sequant 1.11.0 → 1.13.0

package/templates/skills/spec/SKILL.md

@@ -41,6 +41,116 @@ 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.
 
+**Flag:** `--skip-ac-lint`
+- Usage: `/spec 123 --skip-ac-lint`
+- Effect: Skips the AC Quality Check step
+- Use when: AC are intentionally high-level or you want to defer linting
+
+### AC Extraction and Storage — REQUIRED
+
+**After fetching the issue body**, extract and store acceptance criteria in workflow state:
+
+```bash
+# Extract AC from issue body and store in state
+npx tsx -e "
+import { extractAcceptanceCriteria } from './src/lib/ac-parser.js';
+import { StateManager } from './src/lib/workflow/state-manager.js';
+
+const issueBody = \`<ISSUE_BODY_HERE>\`;
+const issueNumber = <ISSUE_NUMBER>;
+const issueTitle = '<ISSUE_TITLE>';
+
+const ac = extractAcceptanceCriteria(issueBody);
+console.log('Extracted AC:', JSON.stringify(ac, null, 2));
+
+if (ac.items.length > 0) {
+  const manager = new StateManager();
+  // Initialize issue if not exists
+  const existing = await manager.getIssueState(issueNumber);
+  if (!existing) {
+    await manager.initializeIssue(issueNumber, issueTitle);
+  }
+  await manager.updateAcceptanceCriteria(issueNumber, ac);
+  console.log('AC stored in state for issue #' + issueNumber);
+}
+"
+```
+
+**Why this matters:** Storing AC in state enables:
+- Dashboard visibility of AC progress per issue
+- `/qa` skill to update AC status during review
+- Cross-skill AC tracking throughout the workflow
+
+**AC Format Detection:**
+The parser supports multiple formats:
+- `- [ ] **AC-1:** Description` (bold with hyphen)
+- `- [ ] **B2:** Description` (letter + number)
+- `- [ ] AC-1: Description` (no bold)
+
+**If no AC found:**
+- Log a warning but continue with planning
+- The plan output should note that AC will need to be defined
+
+### AC Quality Check — REQUIRED (unless --skip-ac-lint)
+
+**After extracting AC**, run the AC linter to flag vague, untestable, or incomplete requirements:
+
+```bash
+# Lint AC for quality issues (skip if --skip-ac-lint flag is set)
+npx tsx -e "
+import { parseAcceptanceCriteria } from './src/lib/ac-parser.js';
+import { lintAcceptanceCriteria, formatACLintResults } from './src/lib/ac-linter.js';
+
+const issueBody = \`<ISSUE_BODY_HERE>\`;
+
+const criteria = parseAcceptanceCriteria(issueBody);
+const lintResults = lintAcceptanceCriteria(criteria);
+console.log(formatACLintResults(lintResults));
+"
+```
+
+**Why this matters:** Vague AC lead to:
+- Ambiguous implementations that don't match expectations
+- Subjective /qa verdicts ("does it work properly?")
+- Wasted iteration cycles when requirements are clarified late
+
+**Pattern Detection:**
+
+| Pattern Type | Examples | Issue |
+|--------------|----------|-------|
+| Vague | "should work", "properly", "correctly" | Subjective, no measurable outcome |
+| Unmeasurable | "fast", "performant", "responsive" | No threshold defined |
+| Incomplete | "handle errors", "edge cases" | Specific scenarios not enumerated |
+| Open-ended | "etc.", "and more", "such as" | Scope is undefined |
+
+**Example Output:**
+
+```markdown
+## AC Quality Check
+
+⚠️ **AC-2:** "System should handle errors gracefully"
+   → Incomplete: error types not specified
+   → Suggest: List specific error types and expected responses (e.g., 400 for invalid input, 503 for service unavailable)
+
+⚠️ **AC-4:** "Page loads quickly"
+   → Unmeasurable: "quickly" has no threshold
+   → Suggest: Specify time limit (e.g., completes in <5 seconds)
+
+✅ AC-1, AC-3, AC-5: Clear and testable
+
+**Summary:** 2/5 AC items flagged for review
+```
+
+**Behavior:**
+- **Warning-only**: AC Quality Check does NOT block planning
+- Issues are surfaced in the output but plan generation continues
+- Include flagged AC in the issue comment draft with suggestions
+- Recommend refining vague AC before implementation
+
+**If `--skip-ac-lint` flag is set:**
+- Output: `AC Quality Check: Skipped (--skip-ac-lint flag set)`
+- Continue directly to plan generation
+
 ### 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`).
@@ -49,13 +159,62 @@ When called like `/spec <freeform description>`:
 
 **You MUST spawn sub-agents for context gathering.** Do NOT explore the codebase inline with Glob/Grep commands. Sub-agents provide parallel execution, better context isolation, and consistent reporting.
 
+**Check agent execution mode first:**
+```bash
+parallel=$(cat .sequant/settings.json 2>/dev/null | jq -r '.agents.parallel // false')
+```
+
+#### If parallel mode enabled:
+
 **Spawn ALL THREE agents in a SINGLE message:**
 
-1. `Task(subagent_type="pattern-scout", model="haiku", prompt="Find similar features for [FEATURE]. Check components/admin/, lib/queries/, docs/patterns/. Report: file paths, patterns, recommendations.")`
+1. `Task(subagent_type="Explore", model="haiku", prompt="Find similar features for [FEATURE]. Check components/admin/, lib/queries/, docs/patterns/. Report: file paths, patterns, recommendations.")`
 
 2. `Task(subagent_type="Explore", model="haiku", prompt="Explore [CODEBASE AREA] for [FEATURE]. Find: main components, data flow, key files. Report structure.")`
 
-3. `Task(subagent_type="schema-inspector", model="haiku", prompt="Inspect database for [FEATURE]. Check: table schema, RLS policies, existing queries. Report findings.")`
+3. `Task(subagent_type="Explore", model="haiku", prompt="Inspect database for [FEATURE]. Check: table schema, RLS policies, existing queries. Report findings.")`
+
+#### If sequential mode (default):
+
+**Spawn each agent ONE AT A TIME, waiting for each to complete:**
+
+1. **First:** `Task(subagent_type="Explore", model="haiku", prompt="Find similar features for [FEATURE]. Check components/admin/, lib/queries/, docs/patterns/. Report: file paths, patterns, recommendations.")`
+
+2. **After #1 completes:** `Task(subagent_type="Explore", model="haiku", prompt="Explore [CODEBASE AREA] for [FEATURE]. Find: main components, data flow, key files. Report structure.")`
+
+3. **After #2 completes:** `Task(subagent_type="Explore", model="haiku", prompt="Inspect database for [FEATURE]. Check: table schema, RLS policies, existing queries. Report findings.")`
+
+### Feature Branch Context Detection
+
+Before creating the implementation plan, check if a custom base branch should be recommended:
+
+1. **Check for feature branch references in issue body**:
+   ```bash
+   gh issue view <issue> --json body --jq '.body' | grep -iE "(feature/|branch from|based on|part of.*feature)"
+   ```
+
+2. **Check issue labels for feature context**:
+   ```bash
+   gh issue view <issue> --json labels --jq '.labels[].name' | grep -iE "(dashboard|feature-|epic-)"
+   ```
+
+3. **Check if project has defaultBase configured**:
+   ```bash
+   cat .sequant/settings.json 2>/dev/null | jq -r '.run.defaultBase // empty'
+   ```
+
+4. **If feature branch context detected**, include in plan output:
+   ```markdown
+   ## Feature Branch Context
+
+   **Detected base branch**: `feature/dashboard`
+   **Source**: Issue body mentions "Part of dashboard feature" / Project config / Label
+
+   **Recommended workflow**:
+   \`\`\`bash
+   npx sequant run <issue> --base feature/dashboard
+   \`\`\`
+   ```
 
 ### In-Flight Work Analysis (Conflict Detection)
 
@@ -66,9 +225,9 @@ Before creating the implementation plan, scan for potential conflicts with in-fl
    git worktree list --porcelain
    ```
 
-2. **For each worktree, get changed files**:
+2. **For each worktree, get changed files** (use detected base branch or default to main):
    ```bash
-   git -C <worktree-path> diff --name-only main...HEAD
+   git -C <worktree-path> diff --name-only <base-branch>...HEAD
    ```
 
 3. **Analyze this issue's likely file touches** based on:
@@ -127,6 +286,14 @@ Before creating the implementation plan, scan for potential conflicts with in-fl
 3. **Check existing dependencies**
    - Review `package.json` for libraries
    - Prefer existing dependencies over new ones
+   - For "solved problem" domains, recommend established packages in the plan:
+     | Domain | Recommended Packages |
+     |--------|---------------------|
+     | Date/time | `date-fns`, `dayjs` |
+     | Validation | `zod`, `yup`, `valibot` |
+     | HTTP with retry | `ky`, `got`, `axios` |
+     | Form state | `react-hook-form` |
+     | State management | `zustand`, `jotai` |
 
 4. **For database-heavy features**
    - Verify table schemas against TypeScript types
@@ -190,7 +357,82 @@ Ask the user to confirm or adjust:
 
 **Do NOT start implementation** - this is planning-only.
 
-### 4. Recommended Workflow
+### 4. Content Analysis (AC-1, AC-2, AC-3, AC-4)
+
+**Before** determining the recommended workflow, analyze the issue content for phase-relevant signals:
+
+#### Step 1: Check for Solve Comment (AC-4)
+
+First, check if a `/solve` comment already exists for this issue:
+
+```bash
+# Check issue comments for solve workflow
+gh issue view <issue-number> --json comments --jq '.comments[].body' | grep -l "## Solve Workflow for Issues:"
+```
+
+**If solve comment found:**
+- Extract phases from the solve workflow (e.g., `spec → exec → test → qa`)
+- Use solve recommendations as the primary source (after labels)
+- Skip content analysis for phases (solve already analyzed)
+- Include in output: `"Solve comment found - using /solve workflow recommendations"`
+
+#### Step 2: Analyze Title for Keywords (AC-1)
+
+If no solve comment, analyze the issue title for phase-relevant keywords:
+
+| Pattern | Detection | Suggested Phase |
+|---------|-----------|-----------------|
+| `extract`, `component` | UI work | Add `/test` |
+| `refactor.*ui`, `ui refactor` | UI work | Add `/test` |
+| `frontend`, `dashboard` | UI work | Add `/test` |
+| `auth`, `permission`, `security` | Security-sensitive | Add `/security-review` |
+| `password`, `credential`, `token` | Security-sensitive | Add `/security-review` |
+| `refactor`, `migration`, `restructure` | Complex work | Enable quality loop |
+| `breaking change` | Complex work | Enable quality loop |
+
+#### Step 3: Analyze Body for Patterns (AC-2)
+
+Analyze the issue body for file references and keywords:
+
+| Pattern | Detection | Suggested Phase |
+|---------|-----------|-----------------|
+| References `.tsx` or `.jsx` files | UI work likely | Add `/test` |
+| References `components/` directory | UI work | Add `/test` |
+| References `scripts/` or `bin/` | CLI work | May need `/verify` |
+| References `auth/` directory | Security-sensitive | Add `/security-review` |
+| References `middleware.ts` | May be auth-related | Consider `/security-review` |
+| Contains "breaking change" | Complex work | Enable quality loop |
+
+#### Step 4: Merge Signals (AC-3)
+
+Content analysis **supplements** label detection - it can only ADD phases, never remove them.
+
+**Priority order (highest first):**
+1. **Labels** (explicit, highest priority)
+2. **Solve comment** (if exists)
+3. **Title keywords**
+4. **Body patterns** (lowest priority)
+
+**Output format:**
+
+```markdown
+## Content Analysis
+
+### Signal Sources
+
+| Phase | Source | Confidence | Reason |
+|-------|--------|------------|--------|
+| /test | title | high | "Extract component" detected |
+| /security-review | body | medium | References auth/ directory |
+
+### Merged Recommendations
+
+**From labels:** /test (ui label)
+**From content:** /security-review (added)
+**Final phases:** spec → exec → test → security-review → qa
+```
+
+### 5. Recommended Workflow
 
 Analyze the issue and recommend the optimal workflow phases:
 
@@ -199,6 +441,7 @@ Analyze the issue and recommend the optimal workflow phases:
 
 **Phases:** spec → exec → qa
 **Quality Loop:** disabled
+**Signal Sources:** [labels | solve | content]
 **Reasoning:** [Brief explanation of why these phases were chosen]
 ```
 
@@ -209,7 +452,11 @@ Analyze the issue and recommend the optimal workflow phases:
 - **Security-sensitive** → Add `security-review` phase
 - **Documentation only** → Skip `spec`, just `exec → qa`
 
-### 5. Label Review
+**Content Analysis Integration:**
+- Include content-detected phases in the workflow
+- Note signal source in reasoning (e.g., "Added /test based on title keyword 'extract component'")
+
+### 6. Label Review
 
 Analyze current labels vs implementation plan and suggest updates:
 
@@ -239,7 +486,7 @@ Analyze current labels vs implementation plan and suggest updates:
 - Check if API contracts are changing
 - Match against quality loop trigger labels
 
-### 6. Issue Comment Draft
+### 7. Issue Comment Draft
 
 Generate a Markdown snippet with:
 - AC checklist with verification criteria
@@ -255,7 +502,7 @@ Label clearly as:
 --- DRAFT GITHUB ISSUE COMMENT (PLAN) ---
 ```
 
-### 7. Update GitHub Issue
+### 8. Update GitHub Issue
 
 Post the draft comment to GitHub:
 ```bash
@@ -265,15 +512,54 @@ gh issue edit <issue-number> --add-label "planned"
 
 ---
 
+## State Tracking
+
+**IMPORTANT:** Update workflow state when running standalone (not orchestrated).
+
+### Check Orchestration Mode
+
+At the start of the skill, check if running orchestrated:
+```bash
+# Check if orchestrated - if so, skip state updates
+if [[ -n "$SEQUANT_ORCHESTRATOR" ]]; then
+  echo "Running orchestrated - state managed by orchestrator"
+fi
+```
+
+### State Updates (Standalone Only)
+
+When NOT orchestrated (`SEQUANT_ORCHESTRATOR` is not set):
+
+**At skill start:**
+```bash
+npx tsx scripts/state/update.ts start <issue-number> spec
+```
+
+**On successful completion:**
+```bash
+npx tsx scripts/state/update.ts complete <issue-number> spec
+```
+
+**On failure:**
+```bash
+npx tsx scripts/state/update.ts fail <issue-number> spec "Error description"
+```
+
+**Why this matters:** State tracking enables dashboard visibility, resume capability, and workflow orchestration. Skills update state when standalone; orchestrators handle state when running workflows.
+
+---
+
 ## Output Verification
 
 **Before responding, verify your output includes ALL of these:**
 
+- [ ] **AC Quality Check** - Lint results (or "Skipped" if --skip-ac-lint)
 - [ ] **AC Checklist** - Numbered AC items (AC-1, AC-2, etc.) with descriptions
 - [ ] **Verification Criteria** - Each AC has Verification Method and Test Scenario
 - [ ] **Conflict Risk Analysis** - Check for in-flight work, include if conflicts found
 - [ ] **Implementation Plan** - 3-7 concrete steps with codebase references
-- [ ] **Recommended Workflow** - Phases, Quality Loop setting, and Reasoning
+- [ ] **Content Analysis** - Title/body analysis results (or "Solve comment found" if using /solve)
+- [ ] **Recommended Workflow** - Phases, Quality Loop setting, Signal Sources, and Reasoning
 - [ ] **Label Review** - Current vs recommended labels based on plan analysis
 - [ ] **Open Questions** - Any ambiguities with recommended defaults
 - [ ] **Issue Comment Draft** - Formatted for GitHub posting
@@ -285,6 +571,12 @@ gh issue edit <issue-number> --add-label "planned"
 You MUST include these sections in order:
 
 ```markdown
+## AC Quality Check
+
+[Output from AC linter, or "Skipped (--skip-ac-lint flag set)"]
+
+---
+
 ## Acceptance Criteria
 
 ### AC-1: [Description]
@@ -320,10 +612,31 @@ You MUST include these sections in order:
 
 ---
 
+## Content Analysis
+
+<!-- If solve comment found: -->
+**Source:** Solve comment found - using /solve workflow recommendations
+
+<!-- If no solve comment, show analysis: -->
+### Signal Sources
+
+| Phase | Source | Confidence | Reason |
+|-------|--------|------------|--------|
+| /test | title | high | "[matched keyword]" detected |
+| /security-review | body | medium | References [pattern] |
+
+### Merged Recommendations
+
+**From labels:** [label-detected phases]
+**From content:** [content-detected phases]
+
+---
+
 ## Recommended Workflow
 
 **Phases:** exec → qa
 **Quality Loop:** disabled
+**Signal Sources:** [labels | solve | content]
 **Reasoning:** [Why these phases based on issue analysis]
 
 ---