specweave 1.0.593 → 2.0.0

package/plugins/specweave/skills/judge-llm/SKILL.md

@@ -1,235 +0,0 @@
----
-description: Adaptive-thinking LLM-as-Judge validation of completed work. Uses the Opus model and an adaptive-thinking prompt hint for thorough, independent evaluation. Use when saying "judge my code", "judge-llm", "deep validate", or as part of sw:done closure.
-version: 1.0.0
-allowed-tools: Read, Grep, Glob, Bash
----
-
-# Adaptive-Thinking LLM-as-Judge Validation
-
-Validate completed work using the adaptive-thinking LLM-as-Judge pattern. Provides an independent second opinion separate from `sw:grill`.
-
-## Tool-Use Rationale
-
-- **Read**: Load spec.md, tasks.md, rubric.md, and the files under review to build evaluation context.
-- **Grep**: Search for AC patterns, test assertions, and implementation markers across the codebase.
-- **Glob**: Discover test files and implementation files matching the increment's scope.
-- **Bash**: Run `npx vitest run` to verify test pass rates; check file existence.
-
-## Adaptive-Thinking Prompt Hint
-
-> **think carefully and step-by-step — this evaluation is harder than it looks**
-
-With Opus 4.7, we no longer pass a `thinking` API parameter. Instead, we rely on adaptive thinking triggered by the prompt hint above. The model decides how much reasoning each evaluation requires.
-
-## Model Configuration
-
-**Default effort**: `xhigh` — recommended for all evaluation tasks per Opus 4.7 conventions.
-**Opt-in max**: `--effort max` enables maximum effort with a warning: "max effort risks overthinking on straightforward problems."
-**Legacy mode**: Set `quality.thinkingBudget: "legacy"` in config to pass a fixed `thinking` parameter (for pre-4.7 models only).
-
-## Effort Level
-
-- **Default**: `xhigh` effort — the judge runs with the highest reasoning effort level by default.
-- **Opt-in**: `--effort max` — elevates to maximum effort for exceptionally complex or high-stakes reviews.
-
-## How It Differs from sw:grill
-
-| Aspect | `sw:grill` | `sw:judge-llm` |
-|--------|-------------|-----------------|
-| Execution | In-session (same context) | **Separate Opus API call** |
-| Context | Shares conversation context | **Fresh context (no bias)** |
-| Reasoning | Standard reasoning | **Adaptive thinking via prompt hint (`xhigh` default, `--effort max` opt-in)** |
-| Output | Confidence-scored findings | Structured verdict + score |
-| Domain | Generic code review | **Built-in domain criteria** |
-
-**Key value**: Independent perspective with fresh model context catches issues that in-session review may miss.
-
-## Implementation
-
-**TypeScript**: `src/core/skills/skill-judge.ts`
-- Uses Anthropic SDK with user's `ANTHROPIC_API_KEY`
-- Model-version guard: omits the `thinking` API parameter on `claude-opus-4-7*` and newer models; falls back to adaptive-thinking prompt hint
-- AbortController-based timeout to prevent stuck states (default: 60s)
-- Progress logging to `.specweave/logs/judge-llm.log`
-- Fallback to basic pattern matching if no API key
-- Domain-specific evaluation criteria (frontend, backend, mobile, infrastructure, testing, ML)
-
-## Usage
-
-```bash
-# DEFAULT: Adaptive-thinking validation at xhigh effort
-sw:judge-llm src/file.ts
-sw:judge-llm "src/**/*.ts"
-
-# Validate git changes (adaptive thinking by default)
-sw:judge-llm --staged           # Staged changes
-sw:judge-llm --last-commit      # Last commit
-sw:judge-llm --diff main        # Diff vs branch
-
-# Quick mode (ONLY if you need speed over thoroughness)
-sw:judge-llm src/file.ts --quick
-
-# Maximum reasoning effort (opt-in)
-sw:judge-llm src/file.ts --effort max
-
-# Timeout control (default: 60s)
-sw:judge-llm src/file.ts --timeout 120000
-
-# Additional options
-sw:judge-llm src/file.ts --strict   # Fail on any concern
-sw:judge-llm src/file.ts --fix      # Include fix suggestions
-sw:judge-llm src/file.ts --export   # Export report to markdown
-sw:judge-llm src/file.ts --verbose  # Show progress to console
-```
-
-## External API Cost Consent (MANDATORY)
-
-**This skill uses the Anthropic API directly (NOT your Claude Code subscription).** Each evaluation costs approximately $0.01-0.05 depending on code size.
-
-**Before invoking the Anthropic API, you MUST check consent:**
-
-1. Read `.specweave/config.json` → check `externalModels.consent` field
-2. If `"always-allow"` → proceed silently
-3. If `"never"` → skip API call, use in-session adaptive-thinking evaluation instead
-4. If `"ask"` (default):
-   - Check if `"anthropic"` is in `externalModels.allowedProviders`
-   - If YES → proceed silently (standing permission)
-   - If NO → **ASK USER**: "Judge-LLM will call the Anthropic API using your ANTHROPIC_API_KEY. This costs ~$0.01-0.05 per evaluation. Proceed? (yes/no/always)"
-     - "yes" → proceed this time only
-     - "no" → skip API call, use in-session adaptive-thinking evaluation instead
-     - "always" → run: `grantStandingConsent('anthropic', projectRoot)` from `src/core/llm/consent.ts`, then proceed
-5. No `ANTHROPIC_API_KEY` set → falls back to pattern matching automatically (no cost, no consent needed)
-
-## Workflow
-
-### Step 1: Gather Input
-
-Determine what to validate:
-- If file paths provided: read those files
-- If `--staged`: get staged git changes
-- If `--last-commit`: get files from last commit
-- If `--diff <branch>`: get diff against branch
-- If no args: validate recent work in conversation context
-
-### Step 2: Adaptive-Thinking Analysis (Default)
-
-Prompt hint prefix (include verbatim at the start of the judge prompt):
-
-> **think carefully and step-by-step — this evaluation is harder than it looks**
-
-Use adaptive thinking (triggered by the hint) for deep LLM-as-Judge evaluation via the Opus 4.7 model at `xhigh` effort by default (`--effort max` opt-in for exceptional cases):
-
-```
-Claude MUST think carefully and step-by-step to:
-
-1. DEEP READ: Thoroughly understand all code, context, and intent
-2. MULTI-DIMENSIONAL ANALYSIS: Evaluate across ALL dimensions:
-   - Correctness: Does it work exactly as intended?
-   - Completeness: ALL edge cases handled? ALL requirements met?
-   - Security: ANY vulnerabilities? OWASP Top 10 checked?
-   - Performance: Algorithmic complexity? Memory usage? Bottlenecks?
-   - Maintainability: Clean? Clear? Follows conventions?
-   - Testability: Can it be tested? Are tests adequate?
-   - Error handling: All failure modes covered?
-3. CRITICAL EVALUATION: Weigh ALL findings by severity
-4. REASONED VERDICT: Form verdict based on thorough analysis
-```
-
-### Step 3: Return Verdict
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-JUDGE-LLM VERDICT: APPROVED | CONCERNS | REJECTED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Mode: ADAPTIVE-THINKING (xhigh effort)
-Confidence: 0.XX
-Files Analyzed: N
-
-REASONING:
-[Detailed chain-of-thought from adaptive thinking]
-
-ISSUES (if any):
-  CRITICAL: [title]
-   [description]
-   [file:line]
-   [suggestion]
-
-  HIGH: [title]
-   ...
-
-  LOW: [title]
-   ...
-
-VERDICT: [summary sentence]
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## Verdict Meanings
-
-| Verdict | Meaning | Action |
-|---------|---------|--------|
-| **APPROVED** | Work is solid, no significant issues | Safe to proceed |
-| **CONCERNS** | Issues found worth addressing | Review and fix recommended |
-| **REJECTED** | Critical issues found | MUST fix before proceeding |
-
-## Rubric Integration
-
-**Rubric Integration**: If `rubric.md` exists in the increment directory:
-1. Load the file and find all criteria where `Evaluator: sw:judge-llm`
-2. After determining your verdict, update matching criteria: `[x] PASS` if verdict is not REJECTED, `[!] FAIL — verdict: REJECTED` otherwise
-3. If rubric.md does not exist, proceed with existing behavior (no error)
-
-## Persistent Report (MANDATORY)
-
-After evaluation (including consent-denied fallback), you **MUST** write a JSON report. The CLI checks for this file during closure.
-
-**Path**: `.specweave/increments/<id>/reports/judge-llm-report.json`
-
-**Full evaluation report**:
-```json
-{
-  "version": "1.0",
-  "incrementId": "<id>",
-  "timestamp": "<ISO-8601>",
-  "verdict": "APPROVED|CONCERNS|REJECTED",
-  "score": 87,
-  "mode": "adaptive-thinking|quick|pattern-match",
-  "timedOut": false,
-  "duration_ms": 45000,
-  "consentStatus": "granted",
-  "summary": "..."
-}
-```
-
-**Consent denied / no API key**:
-```json
-{
-  "version": "1.0",
-  "incrementId": "<id>",
-  "timestamp": "<ISO-8601>",
-  "verdict": "WAIVED",
-  "consentStatus": "denied",
-  "reason": "External API consent denied by user"
-}
-```
-
-A `WAIVED` verdict is accepted by the CLI — does not block closure.
-
-## Refinement Signal Emission (0671)
-
-When the verdict is `REJECTED` or `CONCERNS` and a finding references a specific skill slug (e.g. `sw:architect` in `concerns`, `recommendations`, or `summary`), `SkillJudge.writeReport` appends a refinement signal to `.specweave/state/skill-signals.json` (best-effort, never blocks the gate). `REJECTED` → severity `high`; `CONCERNS` → `medium`. Signals are consumed later by `sw:skill-refine`.
-
-## Visibility & Stuck Detection
-
-Progress logged to `.specweave/logs/judge-llm.log`. Default timeout 60s aborts if stuck (`timedOut: true`).
-
-## Related
-
-- `sw:grill` - Confidence-scored pre-ship quality gate (in-session)
-- `sw:validate` - Rule-based increment validation
-- `sw:done` - Increment closure (runs both grill and judge-llm)
-
-## Resources
-
-- [Official Documentation](https://verified-skill.com/docs/reference/skills#judge-llm)

package/plugins/specweave/skills/multi-project/SKILL.md

@@ -1,371 +0,0 @@
----
-name: sw/multi-project
-description: Unified multi-project management skill for GitHub, Azure DevOps, and Jira. Organizes specs and splits tasks across multiple repositories or projects for monorepo, polyrepo, project-per-team, and area-path architectures. Use `--tool github|ado|jira` to select the target integration.
-version: 1.0.0
-user-invokable: true
-allowed-tools: Read, Write, Edit, Glob
----
-
-# Multi-Project Management Skill
-
-Unified skill for organizing SpecWeave specs and increments across multiple projects or repositories. Supersedes the tool-specific `sw:github-multi-project` and `sw:ado-multi-project` skills, and adds Jira multi-project support.
-
-## `--tool` Flag
-
-Select the target integration via the `--tool` flag:
-
-| Value | Backend | Use When |
-|-------|---------|----------|
-| `--tool github` | GitHub repositories | Multi-repo and monorepo GitHub projects |
-| `--tool ado` | Azure DevOps projects / area paths | Project-per-team, area-path-based, or team-based ADO organizations |
-| `--tool jira` | Jira projects / components | Multi-project Jira instances with Epics/Stories |
-
-Example invocations:
-
-```bash
-sw:multi-project --tool github
-sw:multi-project --tool ado
-sw:multi-project --tool jira
-```
-
-If `--tool` is omitted, the skill reads `integrations.primary` from `.specweave/config.json` and falls back to `github` when unset.
-
-## Core Capabilities (All Tools)
-
-1. **Spec Organization** — organizes specs in `.specweave/docs/internal/projects/{project-id}/`
-2. **Task Splitting** — analyzes `tasks.md` and splits work into project-specific tasks
-3. **Cross-project Coordination** — tracks dependencies between projects
-4. **Bidirectional Sync** — keeps local specs and remote work items in sync
-
-## Architectures
-
-### Single Repository / Single Project
-
-```
-my-app/
-├── .specweave/
-│   └── docs/internal/projects/default/
-└── src/
-```
-
-### Multi-Repository (Polyrepo — GitHub)
-
-```
-my-app-frontend/   my-app-backend/   my-app-shared/
-├── .git             ├── .git           ├── .git
-└── src/             └── src/           └── src/
-```
-
-### Parent Repository (Recommended for GitHub multi-repo)
-
-```
-my-app-parent/              # Parent repo holds .specweave
-├── .specweave/
-│   └── docs/internal/projects/
-│       ├── frontend/
-│       ├── backend/
-│       └── shared/
-└── services/
-    ├── frontend/
-    ├── backend/
-    └── shared/
-```
-
-### Monorepo (GitHub / Jira / ADO)
-
-```
-my-app/
-├── .specweave/
-│   └── docs/internal/projects/
-│       ├── frontend/
-│       ├── backend/
-│       └── shared/
-└── packages/
-```
-
-### Project-per-team (ADO / Jira recommended)
-
-```
-Organization: mycompany
-├── AuthService
-├── UserService
-├── PaymentService
-└── NotificationService
-
-.specweave/docs/internal/specs/
-├── AuthService/
-├── UserService/
-├── PaymentService/
-└── NotificationService/
-```
-
-### Area-path-based (ADO) / Component-based (Jira)
-
-```
-Organization: enterprise
-└── ERP (Project)
-    ├── Finance
-    ├── HR
-    ├── Inventory
-    └── Sales
-
-.specweave/docs/internal/specs/ERP/
-├── Finance/
-├── HR/
-├── Inventory/
-└── Sales/
-```
-
----
-
-## GitHub (`--tool github`)
-
-Merges the logic of the deprecated `sw:github-multi-project` skill.
-
-### Task Splitting Example
-
-**Increment**: Add shopping cart functionality
-
-| Repository | Tasks |
-|------------|-------|
-| `my-app-frontend` | T-001 CartItem component, T-002 cart state, T-003 cart UI |
-| `my-app-backend` | T-004 schema, T-005 API endpoints, T-006 validation |
-| `my-app-shared` | T-007 types, T-008 utilities |
-
-### Creating Repo-Specific Issues
-
-```typescript
-async function createRepoSpecificIssues(
-  increment: Increment,
-  distribution: Map<string, Task[]>
-) {
-  for (const [repo, tasks] of distribution) {
-    const issue = await createGitHubIssue({
-      repo,
-      title: `[${increment.id}] ${increment.name} - ${repo}`,
-      body: formatTasksAsChecklist(tasks),
-      labels: ['specweave', 'increment', repo],
-    });
-  }
-}
-```
-
-### GitHub Projects Integration
-
-- Org-level Project spanning multiple repos (preferred)
-- Or per-repo Projects (Frontend / Backend / Shared)
-
-### GitHub Actions Sync
-
-```yaml
-name: SpecWeave Multi-Repo Sync
-on:
-  workflow_dispatch:
-  schedule: [{ cron: '0 */6 * * *' }]
-
-jobs:
-  sync:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Sync to repositories
-        run: |
-          gh issue create --repo myorg/frontend ...
-          gh issue create --repo myorg/backend ...
-```
-
----
-
-## Azure DevOps (`--tool ado`)
-
-Merges the logic of the deprecated `sw:ado-multi-project` skill.
-
-### Intelligent Project Detection
-
-```typescript
-const projectPatterns = {
-  AuthService: {
-    keywords: ['authentication', 'login', 'oauth', 'jwt', 'session'],
-    filePatterns: ['auth/', 'login/', 'security/'],
-  },
-  UserService: {
-    keywords: ['user', 'profile', 'account', 'registration'],
-    filePatterns: ['users/', 'profiles/'],
-  },
-  PaymentService: {
-    keywords: ['payment', 'stripe', 'billing', 'invoice'],
-    filePatterns: ['payment/', 'billing/', 'checkout/'],
-  },
-};
-```
-
-**Confidence scoring**: keyword +0.2, file pattern +0.3, explicit mention +1.0, team mention +0.5. Threshold > 0.7 auto-assigns; otherwise prompts the user.
-
-### Area-path Strategy
-
-```bash
-AZURE_DEVOPS_STRATEGY=area-path-based
-AZURE_DEVOPS_PROJECT=ERP
-AZURE_DEVOPS_AREA_PATHS=Finance,HR,Inventory
-```
-
-Creates `.specweave/docs/internal/specs/ERP/{AreaPath}/` folders and maps increments to `ERP\{AreaPath}`.
-
-### Multi-project Work Items
-
-A single increment spanning three ADO projects:
-
-```
-PaymentService  → Epic "Checkout Payment Processing" (primary)
-UserService     → Feature "User Cart Management"     (linked)
-NotificationService → Feature "Order Notifications"  (linked)
-```
-
-### metadata.yml example
-
-```yaml
-projects:
-  primary: PaymentService
-  dependencies:
-    - UserService: [T-001, T-004]
-    - NotificationService: [T-003]
-
-ado_mappings:
-  PaymentService:
-    epic: 12345
-    work_items: [12346, 12347]
-  UserService:
-    feature: 12348
-    work_items: [12349, 12350]
-```
-
-### Sync Commands
-
-```bash
-sw:multi-project --tool ado sync-increment 0014
-sw:multi-project --tool ado sync-spec AuthService/spec-001
-sw:multi-project --tool ado sync-all
-```
-
----
-
-## Jira (`--tool jira`)
-
-New in v1.2. Provides Jira-specific multi-project support using the `sw-jira` plugin.
-
-### Jira Project Topologies
-
-| Topology | Structure | Mapping |
-|----------|-----------|---------|
-| **Project-per-team** | Each team owns a Jira project | Increment → Epic in owning project |
-| **Shared project + components** | One Jira project, many components | Increment → Epic tagged with component(s) |
-| **Board-per-squad** | Multiple Scrum boards in one project | Increment → Epic linked to squad board |
-
-### Creating Jira Epics and Stories
-
-Use the `sw-jira` plugin. The skill coordinates which project/component the Epic lands in:
-
-```bash
-# Epic for an increment (primary project)
-sw:jira-create --type epic --project PAY --summary "Checkout payment processing"
-
-# Stories for each user story in the increment
-sw:jira-create --type story --project PAY --epic-link PAY-101 --summary "US-001 Shopping cart API"
-sw:jira-create --type story --project USR --epic-link PAY-101 --summary "US-002 User cart state"
-sw:jira-create --type story --project NOT --epic-link PAY-101 --summary "US-003 Order notification email"
-```
-
-Each Story becomes a Jira issue in the right project; `--epic-link` preserves the cross-project relationship.
-
-### metadata.yml example
-
-```yaml
-projects:
-  primary: PAY
-  dependencies:
-    - USR: [T-001, T-004]
-    - NOT: [T-003]
-
-jira_mappings:
-  PAY:
-    epic: PAY-101
-    stories: [PAY-102, PAY-103]
-  USR:
-    stories: [USR-045, USR-046]
-  NOT:
-    stories: [NOT-012]
-```
-
-### Component vs Project Decision
-
-- **Separate projects** when teams have distinct workflows, permissions, or release cadence
-- **Components in a single project** when teams share a board and backlog but need filtering
-
-### Cross-project Epic Linking
-
-Jira supports cross-project Epic links when the instance has the "Advanced Roadmaps" / "Jira Portfolio" add-on enabled. The skill detects availability and falls back to "related to" issue links when not present.
-
-### Sync Commands
-
-```bash
-sw:multi-project --tool jira sync-increment 0014
-sw:multi-project --tool jira sync-spec PaymentService/spec-001
-sw:multi-project --tool jira sync-all
-```
-
----
-
-## Configuration
-
-### `.specweave/config.json`
-
-```json
-{
-  "integrations": {
-    "primary": "github",
-    "github": {
-      "repositories": ["myorg/frontend", "myorg/backend", "myorg/shared"]
-    },
-    "ado": {
-      "strategy": "project-per-team",
-      "projects": ["AuthService", "UserService", "PaymentService"]
-    },
-    "jira": {
-      "strategy": "project-per-team",
-      "projects": ["PAY", "USR", "NOT"]
-    }
-  }
-}
-```
-
-## Cross-project Queries
-
-```typescript
-async function getIncrementWorkItems(incrementId: string, tool: 'github' | 'ado' | 'jira') {
-  const metadata = await readMetadata(incrementId);
-  const key = `${tool}_mappings`;
-  const workItems: unknown[] = [];
-  for (const mapping of Object.values(metadata[key] ?? {})) {
-    workItems.push(...(await fetchWorkItems(tool, mapping)));
-  }
-  return workItems;
-}
-```
-
-## Best Practices
-
-1. **Consistent naming** — `spec-001-oauth-authentication.md` across all tools
-2. **Clear project boundaries** — document what each project owns and does not own
-3. **Link related specs** — when an increment spans projects, include cross-links
-4. **Use project prefixes** — `sw:increment "payment-stripe-integration"`
-
-## Related Skills
-
-- `sw:github-sync`, `sw:ado-sync`, `sw:jira-sync` — per-tool sync engines
-- `sw:github-issue-standard` — GitHub issue formatting
-- `sw:ado-mapper`, `sw:jira-mapper` — ID mapping utilities
-
----
-
-**Skill Version**: 2.0.0 — unified multi-project skill (replaces `sw:github-multi-project` and `sw:ado-multi-project`)
-**Introduced**: SpecWeave v1.2.0 (0669 Wave 4)