specweave 1.0.299 → 1.0.301

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

@@ -20,9 +20,15 @@ hooks:
 
 # Plan Product Increment
 
-## CRITICAL: Plan Mode Required
+## CRITICAL: Plan Mode Required (BLOCKING)
 
-**Before executing this skill, you MUST be in plan mode.** If you are not currently in plan mode, call `EnterPlanMode` first. Increment planning is ALWAYS a planning activity — never skip straight to implementation.
+**You MUST be in plan mode before proceeding.** If not, call `EnterPlanMode` now and wait for confirmation before continuing to Step 0A.
+
+1. Call `EnterPlanMode` immediately
+2. Wait for plan mode confirmation
+3. Then proceed to Step 0A
+
+Increment planning produces specs, plans, and task breakdowns that require user review. Do not skip plan mode or defer it — the user must approve the plan before any implementation begins.
 
 ## Project Overrides
 

package/plugins/specweave/skills/team-lead/SKILL.md

@@ -27,7 +27,9 @@ description: Orchestrate multi-agent parallel development with domain-specialize
 | Action | Tool | Parameters |
 |--------|------|------------|
 | Create team | `TeamCreate` | `team_name`, `description` |
-| Spawn agent | `Task` | `team_name`, `name`, `subagent_type`, `prompt` |
+| Spawn agent | `Task` | `team_name`, `name`, `subagent_type`, `prompt`, `mode` |
+| Spawn agent (plan mode) | `Task` | `mode: "plan"` — agent must submit plan for team lead review |
+| Approve/reject plan | `SendMessage` | `type: "plan_approval_response"`, `request_id`, `recipient`, `approve`, `content` |
 | Send message | `SendMessage` | `type`, `recipient`, `content`, `summary` |
 | Shutdown agent | `SendMessage` | `type: "shutdown_request"`, `recipient` |
 
@@ -191,6 +193,58 @@ Analyze domains
 
 ---
 
+## 3b. Plan Review Workflow
+
+The team lead acts as **architectural reviewer** for all sub-agent plans. Do NOT auto-accept plans.
+
+### Why Review
+
+Without review, agents may duplicate work across domains, misinterpret scope, make conflicting architectural decisions, or produce plans misaligned with the spec.
+
+### Protocol
+
+**Spawn all agents with `mode: "plan"`.** This forces agents to call `ExitPlanMode` before implementing, which sends a `plan_approval_request` to the team lead.
+
+When you receive a plan approval request:
+
+1. **Read the plan** — check the agent's spec.md, plan.md, and tasks.md
+2. **Evaluate**:
+   - Does it align with the feature spec and ACs?
+   - Is the architecture consistent with existing codebase patterns?
+   - Does the agent stay within its file ownership boundaries?
+   - Are there conflicts with other agents' plans?
+   - Is scope correct — not too broad, not too narrow?
+3. **Approve or reject**:
+
+```
+// Approve
+SendMessage({
+  type: "plan_approval_response",
+  request_id: "<from plan_approval_request>",
+  recipient: "database-agent",
+  approve: true
+});
+
+// Reject with feedback
+SendMessage({
+  type: "plan_approval_response",
+  request_id: "<from plan_approval_request>",
+  recipient: "database-agent",
+  approve: false,
+  content: "Revise: 1) Add index on user_id for sessions. 2) Missing migration for AC-US1-03."
+});
+```
+
+### Non-Blocking Review
+
+Plan review MUST NOT block other agents. Review plans as they arrive — agents waiting for approval are idle, but other agents continue working normally.
+
+### Multi-Increment Consideration
+
+For very large features, the team lead MAY split work into multiple increments per domain for better tracking and independent closure. Decide this during initial analysis (Step 1), before spawning agents.
+
+---
+
 ## 4. Agent Spawn Prompt Templates
 
 Each agent receives a detailed prompt that includes its skill invocations, file ownership, and workflow instructions.
@@ -528,11 +582,14 @@ TeamCreate({
 
 ### Step 2: Spawn Upstream Agents (Phase 1)
 
+All agents are spawned with `mode: "plan"` so the team lead reviews their plans before implementation (see Section 3b).
+
 ```typescript
 Task({
   team_name: "feature-checkout",
   name: "database-agent",
   subagent_type: "general-purpose",
+  mode: "plan",
   prompt: `[DATABASE AGENT PROMPT - see template in Section 4c]`,
 });
 
@@ -540,6 +597,7 @@ Task({
   team_name: "feature-checkout",
   name: "shared-types-agent",
   subagent_type: "general-purpose",
+  mode: "plan",
   prompt: `[SHARED/TYPES AGENT PROMPT]`,
 });
 ```
@@ -555,6 +613,7 @@ Task({
   team_name: "feature-checkout",
   name: "backend-agent",
   subagent_type: "general-purpose",
+  mode: "plan",
   prompt: `[BACKEND AGENT PROMPT - see template in Section 4b]`,
 });
 
@@ -562,6 +621,7 @@ Task({
   team_name: "feature-checkout",
   name: "frontend-agent",
   subagent_type: "general-purpose",
+  mode: "plan",
   prompt: `[FRONTEND AGENT PROMPT - see template in Section 4a]`,
 });
 
@@ -569,6 +629,7 @@ Task({
   team_name: "feature-checkout",
   name: "testing-agent",
   subagent_type: "general-purpose",
+  mode: "plan",
   prompt: `[TESTING AGENT PROMPT - see template in Section 4d]`,
 });
 ```
@@ -625,12 +686,15 @@ Orchestrator Final Check:
 ```
 /sw:team-lead "Build checkout flow"
   │
-  ├── Step 1: Analyze feature -> identify domains
+  ├── Step 1: Analyze feature -> identify domains -> decide increment split
   ├── Step 2: Create team via TeamCreate
   ├── Step 3: Create per-domain increments
-  ├── Step 4: Contract-first spawning
-  │     ├── Phase 1: Spawn shared + database -> wait for CONTRACT_READY
-  │     └── Phase 2: Spawn backend + frontend + testing (parallel)
+  ├── Step 4: Contract-first spawning (all agents with mode: "plan")
+  │     ├── Phase 1: Spawn shared + database
+  │     │     └── Review & approve each agent's plan (Section 3b)
+  │     │     └── Wait for CONTRACT_READY after approval
+  │     └── Phase 2: Spawn backend + frontend + testing
+  │           └── Review & approve each agent's plan
   ├── Step 5: Monitor progress via SendMessage
   ├── Step 6: Quality gates (each agent runs /sw:grill)
   └── Step 7: Merge and close (/sw:team-merge)

package/plugins/specweave-jira/skills/jira-mapper/SKILL.md

@@ -87,29 +87,28 @@ JIRA_DOMAIN="$(grep '^JIRA_DOMAIN=' .env | head -1 | cut -d '=' -f2-)"
 ### Domain Validation (before ANY API call)
 
 ```bash
-# Must be a valid hostname — no special chars, no consecutive dots
-if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$ ]]; then
-  echo "Error: JIRA_DOMAIN contains invalid characters"
+# Reject IP addresses FIRST — IPv4, IPv6 brackets, hex-encoded (SSRF prevention)
+if [[ "$JIRA_DOMAIN" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+ ]] || [[ "$JIRA_DOMAIN" =~ ^\[.*\]$ ]] || [[ "$JIRA_DOMAIN" =~ ^0x ]]; then
+  echo "Error: IP addresses not allowed — use a hostname"
   exit 1
 fi
 
-# Cloud JIRA: must match <subdomain>.atlassian.net
-if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9-]+\.atlassian\.net$ ]]; then
-  echo "Error: Domain does not match <subdomain>.atlassian.net pattern"
-  echo "Self-hosted JIRA requires explicit user confirmation"
+# Reject localhost and private networks
+if [[ "$JIRA_DOMAIN" =~ ^(localhost|127\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.) ]]; then
+  echo "Error: Internal/localhost addresses not allowed"
   exit 1
-  # Agent: use AskUserQuestion to confirm non-standard domain before retrying
 fi
 
-# Reject IP addresses (SSRF prevention)
-if [[ "$JIRA_DOMAIN" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+ ]] || [[ "$JIRA_DOMAIN" =~ ^\[.*\]$ ]] || [[ "$JIRA_DOMAIN" =~ ^0x ]]; then
-  echo "Error: IP addresses not allowed — use a hostname"
+# Must be a valid hostname — no special chars, no consecutive dots
+if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$ ]]; then
+  echo "Error: JIRA_DOMAIN contains invalid characters"
   exit 1
 fi
 
-# Reject localhost and private networks
-if [[ "$JIRA_DOMAIN" =~ ^(localhost|127\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.) ]]; then
-  echo "Error: Internal/localhost addresses not allowed"
+# Cloud JIRA: must match <subdomain>.atlassian.net
+# Agent: use AskUserQuestion to confirm non-standard domain before retrying
+if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9-]+\.atlassian\.net$ ]]; then
+  echo "Error: Domain does not match <subdomain>.atlassian.net pattern"
   exit 1
 fi
 ```

package/plugins/specweave-jira/skills/jira-resource-validator/SKILL.md

@@ -9,6 +9,76 @@ allowed-tools: Read, Bash, Write, Edit
 
 **Auto-Activation**: Triggers when Jira setup or validation is needed.
 
+## Security Rules (MANDATORY)
+
+These rules apply to ALL JIRA API operations in this skill.
+
+### Credential Handling
+
+1. **Never collect credentials** — this skill reads from `.env` only, never prompts the user
+2. **Never log secrets** — never echo token values, auth headers, or base64 credentials
+3. **Never write credentials** — the user configures `.env` themselves (this skill may update non-secret keys like `JIRA_BOARDS` and `JIRA_PROJECT`)
+
+### Credential Loading
+
+```bash
+# 1. Validate presence FIRST (before reading any values)
+for KEY in JIRA_API_TOKEN JIRA_EMAIL JIRA_DOMAIN; do
+  if ! grep -qE "^${KEY}=.+" .env; then
+    echo "Error: ${KEY} missing or empty in .env"
+    exit 1
+  fi
+done
+
+# 2. Load credentials ONLY after validation passes (never display values)
+#    head -1 ensures only first match used if .env has duplicate keys
+JIRA_API_TOKEN="$(grep '^JIRA_API_TOKEN=' .env | head -1 | cut -d '=' -f2-)"
+JIRA_EMAIL="$(grep '^JIRA_EMAIL=' .env | head -1 | cut -d '=' -f2-)"
+JIRA_DOMAIN="$(grep '^JIRA_DOMAIN=' .env | head -1 | cut -d '=' -f2-)"
+```
+
+### Domain Validation (before ANY API call)
+
+```bash
+# Reject IP addresses first (SSRF prevention)
+if [[ "$JIRA_DOMAIN" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+ ]] || [[ "$JIRA_DOMAIN" =~ ^\[.*\]$ ]] || [[ "$JIRA_DOMAIN" =~ ^0x ]]; then
+  echo "Error: IP addresses not allowed — use a hostname"
+  exit 1
+fi
+
+# Reject localhost and private networks
+if [[ "$JIRA_DOMAIN" =~ ^(localhost|127\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.) ]]; then
+  echo "Error: Internal/localhost addresses not allowed"
+  exit 1
+fi
+
+# Must be a valid hostname — no special chars, no consecutive dots
+if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$ ]]; then
+  echo "Error: JIRA_DOMAIN contains invalid characters"
+  exit 1
+fi
+
+# Cloud JIRA: must match <subdomain>.atlassian.net
+if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9-]+\.atlassian\.net$ ]]; then
+  echo "Error: Domain does not match <subdomain>.atlassian.net pattern"
+  exit 1
+fi
+```
+
+### API Call Pattern (HTTPS only, quoted variables)
+
+```bash
+AUTH="$(printf '%s:%s' "$JIRA_EMAIL" "$JIRA_API_TOKEN" | base64)"
+
+# All API calls MUST use https://, double-quote all variables
+curl -s -f \
+  -H "Authorization: Basic $AUTH" \
+  -H "Content-Type: application/json" \
+  "https://${JIRA_DOMAIN}/rest/api/3/..."
+```
+
+---
+
 ## What This Skill Does
 
 This skill ensures your Jira configuration in `.env` is valid and all resources exist. It's **smart enough** to:
@@ -31,10 +101,10 @@ This skill ensures your Jira configuration in `.env` is valid and all resources
 
 ### Required .env Variables
 
-```bash
-JIRA_API_TOKEN=your_token_here
-JIRA_EMAIL=your_email@company.com
-JIRA_DOMAIN=yourcompany.atlassian.net
+```
+JIRA_API_TOKEN=<your-token>
+JIRA_EMAIL=<your-email>
+JIRA_DOMAIN=<your-company>.atlassian.net
 JIRA_STRATEGY=board-based
 JIRA_PROJECT=PROJECTKEY
 JIRA_BOARDS=1,2,3  # IDs (if exist) OR names (if creating)

package/plugins/specweave-jira/skills/jira-sync/SKILL.md

@@ -106,29 +106,28 @@ if [ -z "$JIRA_DOMAIN" ]; then
   exit 1
 fi
 
-# Must be a valid hostname — each label: alphanumeric, hyphens allowed mid-label, no consecutive dots
-if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$ ]]; then
-  echo "Error: JIRA_DOMAIN is not a valid hostname"
+# Reject IP addresses FIRST — IPv4, IPv6 brackets, hex-encoded (SSRF prevention)
+if [[ "$JIRA_DOMAIN" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+ ]] || [[ "$JIRA_DOMAIN" =~ ^\[.*\]$ ]] || [[ "$JIRA_DOMAIN" =~ ^0x ]]; then
+  echo "Error: IP addresses not allowed — use a hostname"
   exit 1
 fi
 
-# Must end with .atlassian.net for cloud JIRA
-if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9-]+\.atlassian\.net$ ]]; then
-  echo "Error: Domain does not match <subdomain>.atlassian.net pattern"
-  echo "Self-hosted JIRA requires explicit user confirmation"
+# Reject localhost and internal hostnames
+if [[ "$JIRA_DOMAIN" =~ ^(localhost|127\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.) ]]; then
+  echo "Error: Internal/localhost addresses not allowed"
   exit 1
-  # Agent: use AskUserQuestion to confirm non-standard domain before retrying
 fi
 
-# Reject IP addresses — IPv4, IPv6 brackets, hex-encoded (SSRF prevention)
-if [[ "$JIRA_DOMAIN" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+ ]] || [[ "$JIRA_DOMAIN" =~ ^\[.*\]$ ]] || [[ "$JIRA_DOMAIN" =~ ^0x ]]; then
-  echo "Error: IP addresses not allowed — use a hostname"
+# Must be a valid hostname — each label: alphanumeric, hyphens allowed mid-label, no consecutive dots
+if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$ ]]; then
+  echo "Error: JIRA_DOMAIN is not a valid hostname"
   exit 1
 fi
 
-# Reject localhost and internal hostnames
-if [[ "$JIRA_DOMAIN" =~ ^(localhost|127\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.) ]]; then
-  echo "Error: Internal/localhost addresses not allowed"
+# Must end with .atlassian.net for cloud JIRA
+# Agent: use AskUserQuestion to confirm non-standard domain before retrying
+if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9-]+\.atlassian\.net$ ]]; then
+  echo "Error: Domain does not match <subdomain>.atlassian.net pattern"
   exit 1
 fi
 ```
@@ -168,7 +167,7 @@ JIRA and Confluence are both Atlassian products and often used together. This sk
 
 ### Confluence Credentials
 
-Same authentication and security rules as JIRA — user configures `.env`, skill only validates presence. Same domain validation applies (must be `<subdomain>.atlassian.net`, HTTPS only, no IPs).
+Same authentication and security rules as JIRA — user configures `.env`, skill only validates presence. Same domain validation applies (must be `<subdomain>.atlassian.net`, HTTPS only, no IPs). `CONFLUENCE_DOMAIN` MUST pass the same validation as `JIRA_DOMAIN` (Step 4) before any Confluence API call.
 
 Required `.env` keys (configured by the user, NOT by this skill):
 ```
@@ -190,20 +189,12 @@ CONFLUENCE_SPACE_KEY=<space-key>
 
 **Every page update MUST increment the version number**:
 
-```bash
-# 1. Get current version
-curl -s GET ".../pages/{id}" | jq '.version.number'
-# Returns: 5
+1. GET current page to retrieve `version.number` (e.g., returns 5)
+2. PUT update with `version.number` set to current + 1 (e.g., 6)
 
-# 2. Update with version + 1
-PUT ".../pages/{id}"
-{ "version": { "number": 6 } }
-```
+If version is not incremented, the API returns `409 Conflict`.
 
-**Error if version not incremented**:
-```
-409 Conflict: "Version must be incremented on update. Current version is: 5"
-```
+All Confluence API calls follow the same security rules as JIRA (HTTPS only, domain validation, credential handling). See the `jira-mapper` skill's **Security Rules** section for implementation patterns.
 
 ### Reference Documentation