specweave 1.0.577 → 1.0.578

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

@@ -0,0 +1,370 @@
+---
+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.
+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)

package/plugins/specweave/skills/plan/SKILL.md

@@ -1,9 +1,24 @@
 ---
-description: Generate plan.md and tasks.md for increment. Use when saying "create plan", "generate tasks", or "plan the increment".
+description: "[DEPRECATED] Standalone `sw:plan` is deprecated. Use `sw:increment --regenerate-plan` to regenerate plan.md for an existing increment."
 ---
 
 # sw:plan - Generate Implementation Plan
 
+## Migration
+
+> Standalone `sw:plan` is deprecated. Use `sw:increment --regenerate-plan` to regenerate `plan.md` and `tasks.md` for an existing increment.
+
+The standalone plan skill has been folded into `sw:increment` via the `--regenerate-plan` flag. This avoids two near-identical entry points and centralises planning logic. The old workflow still works during the deprecation window but will be removed in SpecWeave v1.3.0.
+
+Replace:
+```
+/sw:plan 0014
+```
+With:
+```
+/sw:increment --regenerate-plan 0014
+```
+
 **⚠️ FOR EXISTING INCREMENTS ONLY - NOT for creating new increments!**
 
 **When to use `sw:plan`:**

package/plugins/specweave/skills/pm/SKILL.md

@@ -15,27 +15,11 @@ model: opus
 
 You are a Product Manager with expertise in spec-driven development. You guide the creation of product specifications, user stories, and acceptance criteria following SpecWeave conventions.
 
-## STEP 0: Register Skill Chain Marker (MANDATORY - DO THIS FIRST)
+## Tool-Use Rationale
 
-**Before any other work**, register your invocation so the skill-chain-enforcement-guard allows spec.md writes.
-
-Extract the increment ID from your args (e.g., "Write spec for increment 0323-feature-name: ...").
-Then write the marker file:
-
-```bash
-mkdir -p .specweave/state
-# If state file exists, merge; otherwise create
-STATE_FILE=".specweave/state/skill-chain-XXXX-name.json"
-if [ -f "$STATE_FILE" ]; then
-  jq '.pm_invoked=true | .pm_invoked_at="'$(date -Iseconds)'"' "$STATE_FILE" > "${STATE_FILE}.tmp" && mv "${STATE_FILE}.tmp" "$STATE_FILE"
-else
-  echo '{"pm_invoked":true,"pm_invoked_at":"'$(date -Iseconds)'"}' > "$STATE_FILE"
-fi
-```
-
-Replace `XXXX-name` with the actual increment ID. **This unblocks the guard for spec.md writes.**
-
-**If you skip this step, your Write to spec.md will be BLOCKED by the PreToolUse guard.**
+- **Read**: Load `.specweave/config.json`, the increment's existing `spec.md` (if any), `phases/*.md`, and `templates/spec-template.md` before drafting.
+- **Write**: Produce `spec.md` inside the increment directory once requirements are clear.
+- **Edit**: Refine specific user stories and acceptance criteria during validation.
 
 ## Progressive Disclosure
 
@@ -70,30 +54,9 @@ If `true`:
 4. Cover relevant categories (skip those that don't apply)
 5. Only proceed to Research phase after sufficient clarity
 
-### Writing Interview State to Disk (CRITICAL)
+### In-Memory Interview State
 
-**When invoked via subagent (sw:sw-pm), this runs in an isolated context, but file writes persist.**
-
-When invoked from `sw:increment` with an increment ID (e.g., "Deep interview for increment 0266-foo: ..."),
-you MUST write the interview state file to disk so the enforcement guard can find it:
-
-```bash
-# Extract increment ID from the args (e.g., "Deep interview for increment 0266-foo: ...")
-# Initialize interview state file BEFORE starting questions
-mkdir -p .specweave/state
-echo '{"incrementId":"XXXX-name","startedAt":"'$(date -Iseconds)'","coveredCategories":{}}' \
-  > .specweave/state/interview-XXXX-name.json
-```
-
-After covering each category, update the state file:
-```bash
-jq '.coveredCategories.architecture = {"coveredAt": "'$(date -Iseconds)'", "summary": "..."}' \
-  .specweave/state/interview-XXXX-name.json > tmp && mv tmp .specweave/state/interview-XXXX-name.json
-```
-
-**Why this matters**: The `interview-enforcement-guard.sh` (PreToolUse hook on Write) checks
-`.specweave/state/interview-{increment-id}.json` before allowing spec.md writes. If this file
-is missing or incomplete, spec.md creation is BLOCKED in strict mode.
+Interview state lives in memory for the duration of the planning session — no state files are written to disk. Track covered categories in your working context and proceed to the Research phase once the complexity-appropriate question count is reached.
 
 ## Project Field (Mandatory on Every User Story)
 
@@ -161,11 +124,13 @@ Every user story MUST have exactly one `**Project**:` field. This is uncondition
 
 ## Token Budget Per Response
 
-- **Research phase**: < 500 tokens
-- **Spec creation**: < 600 tokens per chunk
-- **Validation**: < 400 tokens
+- **Research phase**: < 1500 tokens
+- **Spec creation**: < 1800 tokens per chunk
+- **Validation**: < 1200 tokens
+
+Override via `quality.tokenBudgets` in `.specweave/config.json` (keys: `research`, `specCreation`, `validation`). Budgets were raised 3× in SpecWeave 1.1.0 to take advantage of Opus 4.7's long-horizon coherence — smaller caps forced premature summarization and lost nuance on complex specs.
 
-**NEVER exceed 2000 tokens in a single response!**
+**Aim to stay under 6000 tokens in a single response** — beyond that, split the work into another phase/chunk.
 
 ## When This Skill Activates
 

package/plugins/specweave/skills/tdd-cycle/SKILL.md

@@ -4,6 +4,44 @@ description: Execute full TDD red-green-refactor cycle with validation gates. Us
 
 # TDD Cycle - Comprehensive Test-Driven Development
 
+## --phase Flag (v1.1.0+)
+
+`sw:tdd-cycle` supports a `--phase` flag to run a single phase of the RED → GREEN → REFACTOR cycle. Omitting the flag (or passing `--phase all`) runs the full cycle.
+
+| Flag | Behavior |
+|------|----------|
+| `--phase all` (default) | Full RED → GREEN → REFACTOR cycle. Same as omitting the flag. |
+| `--phase red` | Runs only the RED phase — write failing tests. See Phase 2 below. |
+| `--phase green` | Runs only the GREEN phase — write minimal code to make tests pass. See Phase 3 below. |
+| `--phase refactor` | Runs only the REFACTOR phase — improve code quality with tests as safety net. See Phase 4 below. |
+
+### Alias routing from deprecated skills
+
+The following deprecated single-phase skills are aliased in `marketplace.json` to route through `sw:tdd-cycle --phase <x>`:
+
+- `/sw:tdd-red` → `/sw:tdd-cycle --phase red`
+- `/sw:tdd-green` → `/sw:tdd-cycle --phase green`
+- `/sw:tdd-refactor` → `/sw:tdd-cycle --phase refactor`
+
+The aliases emit a one-time migration warning pointing users to the canonical `--phase` form. The three `tdd-*` skills are scheduled for removal in v1.3.0 — see `.specweave/docs/internal/specs/skill-deprecation-policy.md`.
+
+### Examples
+
+```bash
+# Full cycle (default)
+sw:tdd-cycle "user authentication"
+
+# Single phases
+sw:tdd-cycle --phase red "user authentication"
+sw:tdd-cycle --phase green "user authentication"
+sw:tdd-cycle --phase refactor "user authentication"
+
+# Same as default — explicit
+sw:tdd-cycle --phase all "user authentication"
+```
+
+---
+
 ## Project Overrides
 
 **Skill Memories**: If `.specweave/skill-memories/tdd-cycle.md` exists, read and apply its learnings.

package/plugins/specweave/skills/tdd-green/SKILL.md

@@ -1,5 +1,20 @@
 ---
-description: Write minimal code to make failing tests pass. Use when saying "TDD green", "make tests pass", or "implement for tests".
+description: "[DEPRECATED] Write minimal code to make failing tests pass. Use when saying \"TDD green\", \"make tests pass\", or \"implement for tests\"."
+deprecated: true
+---
+
+> ⚠️ DEPRECATED: Use `sw:tdd-cycle --phase green` instead. This skill will be removed in v1.3.0.
+
+## Migration
+
+This skill has been deprecated as part of the Opus 4.7 framework alignment (increment 0669).
+
+- **Use instead**: `sw:tdd-cycle --phase green` runs only the GREEN phase (write minimal code to make tests pass)
+- **Removal**: Scheduled for v1.3.0 (2 minor releases after v1.1.0)
+- **Why**: The three TDD phase skills (tdd-red, tdd-green, tdd-refactor) were consolidated into `sw:tdd-cycle` with a `--phase` flag. Alias routing in `marketplace.json` redirects `/sw:tdd-green` → `/sw:tdd-cycle --phase green` automatically.
+
+For the migration policy, see `.specweave/docs/internal/specs/skill-deprecation-policy.md`.
+
 ---
 
 # TDD Green Phase - Make Tests Pass

package/plugins/specweave/skills/tdd-red/SKILL.md

@@ -1,5 +1,20 @@
 ---
-description: Write failing tests that define expected behavior. Use when saying "TDD red", "write failing tests", or "test first".
+description: "[DEPRECATED] Write failing tests that define expected behavior. Use when saying \"TDD red\", \"write failing tests\", or \"test first\"."
+deprecated: true
+---
+
+> ⚠️ DEPRECATED: Use `sw:tdd-cycle --phase red` instead. This skill will be removed in v1.3.0.
+
+## Migration
+
+This skill has been deprecated as part of the Opus 4.7 framework alignment (increment 0669).
+
+- **Use instead**: `sw:tdd-cycle --phase red` runs only the RED phase (write failing tests)
+- **Removal**: Scheduled for v1.3.0 (2 minor releases after v1.1.0)
+- **Why**: The three TDD phase skills (tdd-red, tdd-green, tdd-refactor) were consolidated into `sw:tdd-cycle` with a `--phase` flag. Alias routing in `marketplace.json` redirects `/sw:tdd-red` → `/sw:tdd-cycle --phase red` automatically.
+
+For the migration policy, see `.specweave/docs/internal/specs/skill-deprecation-policy.md`.
+
 ---
 
 # TDD Red Phase - Write Failing Tests

package/plugins/specweave/skills/tdd-refactor/SKILL.md

@@ -1,5 +1,20 @@
 ---
-description: Refactor code with test safety net to improve quality. Use when saying "TDD refactor", "refactor with tests", or "improve code quality".
+description: "[DEPRECATED] Refactor code with test safety net to improve quality. Use when saying \"TDD refactor\", \"refactor with tests\", or \"improve code quality\"."
+deprecated: true
+---
+
+> ⚠️ DEPRECATED: Use `sw:tdd-cycle --phase refactor` instead. This skill will be removed in v1.3.0.
+
+## Migration
+
+This skill has been deprecated as part of the Opus 4.7 framework alignment (increment 0669).
+
+- **Use instead**: `sw:tdd-cycle --phase refactor` runs only the REFACTOR phase (improve code quality with test safety net)
+- **Removal**: Scheduled for v1.3.0 (2 minor releases after v1.1.0)
+- **Why**: The three TDD phase skills (tdd-red, tdd-green, tdd-refactor) were consolidated into `sw:tdd-cycle` with a `--phase` flag. Alias routing in `marketplace.json` redirects `/sw:tdd-refactor` → `/sw:tdd-cycle --phase refactor` automatically.
+
+For the migration policy, see `.specweave/docs/internal/specs/skill-deprecation-policy.md`.
+
 ---
 
 # TDD Refactor Phase - Improve Code Quality