specky-sdd 3.10.1 → 3.11.0

package/.apm/agents/specky-design-architect.agent.md

@@ -3,7 +3,7 @@ name: specky-design-architect
 description: Phase 4 agent that writes DESIGN.md with system architecture, API contracts, data models, and Mermaid diagrams. All design decisions trace to specification requirements.
 
 color: blue
-tools: ["search", "specky/sdd_write_design", "specky/sdd_generate_all_diagrams", "specky/sdd_generate_diagram"]
+capabilities: ["workspace.read", "mcp.specky.sdd_write_design", "mcp.specky.sdd_generate_all_diagrams", "mcp.specky.sdd_generate_diagram"]
 ---
 
 <example>

package/.apm/agents/specky-implementer.agent.md

@@ -3,7 +3,7 @@ name: specky-implementer
 description: Use this agent to generate implementation plans, quality checklists, test stubs, and infrastructure scaffolding from specifications.
 
 color: blue
-tools: ["search", "specky/sdd_implement", "specky/sdd_checklist", "specky/sdd_generate_tests", "specky/sdd_generate_pbt", "specky/sdd_generate_iac", "specky/sdd_generate_dockerfile", "specky/sdd_generate_devcontainer", "specky/sdd_setup_local_env", "specky/sdd_setup_codespaces"]
+capabilities: ["workspace.read", "workspace.command.git", "mcp.specky.sdd_implement", "mcp.specky.sdd_checklist", "mcp.specky.sdd_generate_tests", "mcp.specky.sdd_generate_pbt", "mcp.specky.sdd_generate_iac", "mcp.specky.sdd_generate_dockerfile", "mcp.specky.sdd_generate_devcontainer", "mcp.specky.sdd_setup_local_env", "mcp.specky.sdd_setup_codespaces", "mcp.github.create_or_update_file"]
 ---
 
 <example>
@@ -30,7 +30,7 @@ You are a senior implementation engineer. You bridge the gap between specificati
 
 **Workflow:**
 1. Read the `specky-implementer` SKILL.md for implementation patterns and tool reference
-2. Verify you are on the correct `spec/NNN-*` branch (not develop/stage/main)
+2. Use Git to verify you are on the correct `spec/NNN-*` branch (not develop/stage/main)
 3. Verify TASKS.md and DESIGN.md exist for the feature
 4. Call sdd_implement — ordered plan (Foundation → Core → Integration → Polish)
 5. Call sdd_checklist for security + testing + relevant NFR domains

package/.apm/agents/specky-onboarding.agent.md

@@ -3,7 +3,7 @@ name: specky-onboarding
 description: Default entry point and interactive wizard for Specky SDD. Detects project context, explains the plugin, guides through project type selection, work mode, and branch setup. Triggered when user says "specky" without specifics.
 
 color: green
-tools: ["search", "specky/sdd_get_status", "specky/sdd_scan_codebase", "specky/sdd_check_ecosystem", "specky/sdd_context_status", "specky/sdd_auto_pipeline", "specky/sdd_batch_import", "specky/sdd_create_branch", "specky/sdd_discover", "specky/sdd_figma_to_spec", "specky/sdd_import_document", "specky/sdd_import_transcript"]
+capabilities: ["workspace.read", "workspace.command.git", "mcp.specky.sdd_get_status", "mcp.specky.sdd_scan_codebase", "mcp.specky.sdd_check_ecosystem", "mcp.specky.sdd_context_status", "mcp.specky.sdd_auto_pipeline", "mcp.specky.sdd_batch_import", "mcp.specky.sdd_create_branch", "mcp.specky.sdd_discover", "mcp.specky.sdd_figma_to_spec", "mcp.specky.sdd_import_document", "mcp.specky.sdd_import_transcript"]
 ---
 
 <example>
@@ -55,7 +55,7 @@ You are the Specky SDD onboarding wizard. You are the **default entry point** wh
 - **Direct MCP tools** → Show tool reference by category, user calls directly
 
 **Step 5 — Branch Setup:**
-- Auto-create `spec/NNN-feature` from develop → call sdd_create_branch
+- Auto-create `spec/NNN-feature` from develop → call sdd_create_branch, then execute its returned Git command after user confirmation
 - Manual → show git commands
 - Skip → proceed without branching
 

package/.apm/agents/specky-orchestrator.agent.md

@@ -3,7 +3,7 @@ name: specky-orchestrator
 description: Master agent that coordinates the full SDD 10-phase pipeline end-to-end, routing to phase agents, validating artifacts between phases, and enforcing hooks and LGTM gates.
 
 color: purple
-tools: ["search", "agent", "specky/sdd_get_status", "specky/sdd_checkpoint", "specky/sdd_advance_phase", "specky/sdd_validate_ears", "specky/sdd_model_routing", "specky/sdd_context_status"]
+capabilities: ["workspace.read", "workspace.command.git", "agent.delegate", "mcp.specky.sdd_get_status", "mcp.specky.sdd_checkpoint", "mcp.specky.sdd_advance_phase", "mcp.specky.sdd_validate_ears", "mcp.specky.sdd_model_routing", "mcp.specky.sdd_context_status"]
 ---
 
 <example>
@@ -30,7 +30,7 @@ You are the Specky SDD pipeline orchestrator. You coordinate the full 10-phase p
 
 **Workflow:**
 1. Call sdd_get_status → determine current phase and feature
-2. Validate branch matches phase expectations:
+2. Use Git to validate that the branch matches phase expectations:
    - Phases 0-7: must be on `spec/NNN-*` branch
    - Phase 8: must be on `develop` branch
    - Phase 9: must be on `stage` branch

package/.apm/agents/specky-quality-reviewer.agent.md

@@ -3,7 +3,7 @@ name: specky-quality-reviewer
 description: Phase 6 agent that runs completeness audit, cross-analysis, and compliance checks. Produces ANALYSIS.md with gate decision (APPROVE/CONDITIONAL/REJECT) and COMPLIANCE.md.
 
 color: red
-tools: ["search", "specky/sdd_run_analysis", "specky/sdd_cross_analyze", "specky/sdd_compliance_check", "specky/sdd_check_sync", "specky/sdd_metrics"]
+capabilities: ["workspace.read", "mcp.specky.sdd_run_analysis", "mcp.specky.sdd_cross_analyze", "mcp.specky.sdd_compliance_check", "mcp.specky.sdd_check_sync", "mcp.specky.sdd_metrics"]
 ---
 
 <example>

package/.apm/agents/specky-release-engineer.agent.md

@@ -3,7 +3,7 @@ name: specky-release-engineer
 description: Use this agent to prepare features for release — run blocking gates, generate documentation, create PR, and export work items.
 
 color: green
-tools: ["search", "specky/sdd_create_pr", "specky/sdd_generate_all_docs", "specky/sdd_generate_docs", "specky/sdd_generate_api_docs", "specky/sdd_generate_runbook", "specky/sdd_generate_onboarding", "specky/sdd_export_work_items"]
+capabilities: ["workspace.read", "workspace.command.git", "workspace.command.release-gates", "mcp.specky.sdd_create_pr", "mcp.specky.sdd_generate_all_docs", "mcp.specky.sdd_generate_docs", "mcp.specky.sdd_generate_api_docs", "mcp.specky.sdd_generate_runbook", "mcp.specky.sdd_generate_onboarding", "mcp.specky.sdd_export_work_items", "mcp.github.create_pull_request", "mcp.github.create_issue"]
 ---
 
 <example>
@@ -28,7 +28,7 @@ You are a senior release engineer. You prepare features for delivery.
 
 **Workflow:**
 1. Read the `specky-release-engineer` SKILL.md for gate criteria and PR templates
-2. Verify work is on the correct branch for the merge target:
+2. Use Git to verify work is on the correct branch for the merge target:
    - `spec/NNN-*` → PR targets `develop`
    - `develop` → PR targets `stage`
    - `stage` → PR targets `main`
@@ -38,9 +38,10 @@ You are a senior release engineer. You prepare features for delivery.
    - specky-release-gate.sh (BLOCKING: exit 2 = cannot release)
 5. If either fails: explain what failed, suggest fix. Do NOT proceed.
 6. Call sdd_generate_all_docs — parallel documentation generation
-7. Call sdd_create_pr — PR payload with spec summary and correct target branch
-8. Optionally call sdd_export_work_items — update external trackers
-9. Deliver release summary with branch, target, and merge instructions
+7. Call sdd_create_pr — generate the PR payload with spec summary and correct target branch
+8. Call GitHub MCP `create_pull_request` with the generated payload. If GitHub MCP is not configured or authenticated, present the payload and stop before claiming a PR was created.
+9. Optionally call sdd_export_work_items, then call GitHub MCP `create_issue` for each exported GitHub work item. Do not route to unconfigured external trackers.
+10. Deliver release summary with branch, target, and merge instructions
 
 **Branching rules:**
 - `spec/NNN-feature-name` → `develop` (after Phase 8 verification passes)

package/.apm/agents/specky-requirements-engineer.agent.md

@@ -3,7 +3,7 @@ name: specky-requirements-engineer
 description: Use this agent to analyze raw input and produce validated FRD and NFRD documents ready for sdd_init.
 
 color: magenta
-tools: ["search", "edit", "specky/sdd_init", "specky/sdd_discover", "specky/sdd_import_document", "specky/sdd_import_transcript", "specky/sdd_batch_import", "specky/sdd_validate_ears"]
+capabilities: ["workspace.read", "workspace.edit", "mcp.specky.sdd_init", "mcp.specky.sdd_discover", "mcp.specky.sdd_import_document", "mcp.specky.sdd_import_transcript", "mcp.specky.sdd_batch_import", "mcp.specky.sdd_validate_ears"]
 ---
 
 <example>

package/.apm/agents/specky-research-analyst.agent.md

@@ -3,7 +3,7 @@ name: specky-research-analyst
 description: Use this agent to gather technical context before specification. Scans codebases, imports documents, and produces RESEARCH.md.
 
 color: cyan
-tools: ["search", "fetch", "specky/sdd_scan_codebase", "specky/sdd_discover", "specky/sdd_research", "specky/sdd_import_document", "specky/sdd_import_transcript", "specky/sdd_check_ecosystem"]
+capabilities: ["workspace.read", "web.fetch", "mcp.specky.sdd_scan_codebase", "mcp.specky.sdd_discover", "mcp.specky.sdd_research", "mcp.specky.sdd_import_document", "mcp.specky.sdd_import_transcript", "mcp.specky.sdd_check_ecosystem"]
 ---
 
 <example>

package/.apm/agents/specky-sdd-clarify.agent.md

@@ -3,7 +3,7 @@ name: specky-sdd-clarify
 description: Use this agent to find and resolve ambiguities in requirements, validate EARS patterns, and produce a clarification log.
 
 color: yellow
-tools: ["search", "specky/sdd_clarify", "specky/sdd_validate_ears", "specky/sdd_turnkey_spec"]
+capabilities: ["workspace.read", "mcp.specky.sdd_clarify", "mcp.specky.sdd_validate_ears", "mcp.specky.sdd_turnkey_spec"]
 ---
 
 <example>

package/.apm/agents/specky-sdd-init.agent.md

@@ -3,7 +3,7 @@ name: specky-sdd-init
 description: Use this agent to initialize the SDD pipeline for a new feature. Creates the .specs/ directory structure and CONSTITUTION.md.
 
 color: green
-tools: ["search", "specky/sdd_init", "specky/sdd_scan_codebase", "specky/sdd_create_branch"]
+capabilities: ["workspace.read", "workspace.command.git", "mcp.specky.sdd_init", "mcp.specky.sdd_scan_codebase", "mcp.specky.sdd_create_branch"]
 ---
 
 <example>
@@ -31,7 +31,7 @@ You are the SDD pipeline initializer. Your only job is to scaffold the spec pipe
 2. Gather feature name, project type (greenfield/brownfield/migration/API), and constraints
 3. Read existing FRD/NFRD from `docs/requirements/` if they exist
 4. Call `sdd_init` to create `.specs/NNN-feature/` with CONSTITUTION.md and .sdd-state.json
-5. Call `sdd_create_branch` to create `spec/NNN-feature-name` from `develop` for all pipeline work
+5. Call `sdd_create_branch`, then execute its returned Git command to create `spec/NNN-feature-name` from `develop` for all pipeline work
 6. For brownfield projects, call `sdd_scan_codebase` to detect the tech stack
 7. Present CONSTITUTION.md to the developer for review
 8. Suggest handoff to `@specky-research-analyst`

package/.apm/agents/specky-spec-engineer.agent.md

@@ -3,7 +3,7 @@ name: specky-spec-engineer
 description: Phase 2 agent that writes SPECIFICATION.md using EARS notation. Every requirement gets a unique REQ-ID, one of the 6 EARS patterns, and measurable acceptance criteria.
 
 color: magenta
-tools: ["search", "specky/sdd_write_spec", "specky/sdd_turnkey_spec", "specky/sdd_validate_ears", "specky/sdd_figma_to_spec"]
+capabilities: ["workspace.read", "mcp.specky.sdd_write_spec", "mcp.specky.sdd_turnkey_spec", "mcp.specky.sdd_validate_ears", "mcp.specky.sdd_figma_to_spec"]
 ---
 
 <example>

package/.apm/agents/specky-task-planner.agent.md

@@ -3,7 +3,7 @@ name: specky-task-planner
 description: Phase 5 agent that writes TASKS.md with dependency-resolved task sequences, REQ-ID traceability, complexity estimates, and parallel markers. Also generates CHECKLIST.md.
 
 color: orange
-tools: ["search", "specky/sdd_write_tasks", "specky/sdd_checklist"]
+capabilities: ["workspace.read", "mcp.specky.sdd_write_tasks", "mcp.specky.sdd_checklist"]
 ---
 
 <example>

package/.apm/agents/specky-test-verifier.agent.md

@@ -3,7 +3,7 @@ name: specky-test-verifier
 description: Use this agent to verify test coverage, detect phantom completions, and check spec-code drift.
 
 color: yellow
-tools: ["search", "specky/sdd_verify_tests", "specky/sdd_verify_tasks", "specky/sdd_check_sync", "specky/sdd_validate_ears", "specky/sdd_get_status"]
+capabilities: ["workspace.read", "workspace.command.test", "mcp.specky.sdd_verify_tests", "mcp.specky.sdd_verify_tasks", "mcp.specky.sdd_check_sync", "mcp.specky.sdd_validate_ears", "mcp.specky.sdd_get_status"]
 ---
 
 <example>
@@ -28,11 +28,12 @@ You are a test verification specialist. You verify that implementation satisfies
 
 **Workflow:**
 1. Read the `specky-test-verifier` SKILL.md for verification criteria and gate thresholds
-2. Call sdd_verify_tests — parse results, map to REQ-IDs, build coverage report
-3. Call sdd_verify_tasks — detect phantom completions
-4. Call sdd_check_sync — detect spec-code drift
-5. Call sdd_validate_ears — re-validate EARS integrity
-6. Present VERIFICATION.md with gate decision
+2. Run the detected test command and collect its machine-readable results
+3. Call sdd_verify_tests — parse results, map to REQ-IDs, build coverage report
+4. Call sdd_verify_tasks — detect phantom completions and write VERIFICATION.md
+5. Call sdd_check_sync — detect spec-code drift
+6. Call sdd_validate_ears — re-validate EARS integrity
+7. Present VERIFICATION.md with gate decision
 
 **Gate criteria (ALL must pass):**
 - Test pass rate ≥90%

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.11.0] - 2026-07-13
+
+### Added
+
+- Canonical agent `capabilities:` declarations compiled into target-native tool identifiers for Copilot, Claude Code, Cursor, and OpenCode.
+- `--permission-profile=scoped|prompt` installation modes. The scoped Claude profile derives narrow native, command, and MCP allow rules from installed agent capabilities.
+- Optional GitHub MCP registration with `--integration=github`, including target-aware diagnostics in `specky doctor`.
+- [Target Capabilities](docs/TARGET-CAPABILITIES.md) reference for target rendering, approval boundaries, and GitHub MCP routing.
+
+### Changed
+
+- Initializer, orchestrator, verifier, implementer, and release workflows now declare the Git/test/release capabilities their instructions require.
+- Release workflows distinguish Specky payload generation from authenticated GitHub MCP mutations.
+- APM runtime references are pinned to the package release version rather than `@latest`.
+
+## [3.10.2] - 2026-07-13
+
+Patch release: Specky logo in VS Code and Cursor MCP / Agent Plugins UI.
+
+### Added
+
+- **`mcpServerIcons`** (`src/utils/server-icon.ts`) — resolves `site/specky-icon.png` to a `file://` URI with `sizes` for stdio MCP clients (VS Code requires local URIs; HTTPS icons are ignored).
+- **Cursor plugin manifest on install** — `specky install --target=cursor` writes `.cursor-plugin/plugin.json` and copies `.cursor/assets/specky-icon.png` so the Specky logo appears in Cursor Agent Plugins.
+- **Repo plugin scaffold** — root `.cursor-plugin/plugin.json` and `mcp.json` for Cursor Marketplace / Git plugin installs.
+- Regression tests for server-icon resolution and cursor-plugin-writer.
+
+### Fixed
+
+- **VS Code / Copilot MCP icon** — server handshake no longer advertises `raw.githubusercontent.com` URLs; uses the packaged PNG via `file://`.
+- **Cursor generic plug icon** — workspace installs get an explicit plugin manifest with logo instead of relying on MCP `serverInfo.icons` alone (still inconsistent in some Cursor MCP views).
+
+### Changed
+
+- `.gitignore` block ignores vendored `.cursor/assets/`; keeps `.cursor-plugin/plugin.json` team-shareable (same as `.cursor/mcp.json`).
+
 ## [3.10.1] - 2026-07-13
 
 Patch release: dual TASKS.md parser (table + checkbox), honest COMPLIANCE/VERIFICATION persistence, Analyze-phase remediation for blocked gates, and generation quality fixes.

package/README.md

@@ -50,7 +50,8 @@
 | | [Where Specifications Live](#where-specifications-live) | File structure and naming conventions |
 | | [Input Methods](#input-methods-6-ways-to-start) | 6 ways to feed Specky |
 | | [Three Project Types](#three-project-types-one-pipeline) | Greenfield, Brownfield, Modernization |
-| | [Staying up to date](#staying-up-to-date) | Update notifications and one-command upgrade |
+| | [How to upgrade](#how-to-upgrade) | Bump npm + refresh project assets (no `--target` needed) |
+| | [Staying up to date](#staying-up-to-date) | Update notifications and opt-out |
 | **Pipeline** | [Pipeline and LGTM Gates](#pipeline-and-lgtm-gates) | 10 phases with human review gates |
 | | [All 58 Tools](#all-58-tools) | Complete tool reference by category |
 | | [EARS Notation](#ears-notation) | The 6 requirement patterns |
@@ -100,7 +101,7 @@ specky install --target=copilot      # VS Code + GitHub Copilot (recommended)
 specky install --target=claude       # Claude Code
 specky install --target=cursor       # Cursor
 specky install --target=opencode     # OpenCode
-specky install --target=agent-skills # Shared .agents/skills bundle
+specky install --target=agent-skills # Skills-only shared .agents/skills bundle
 ```
 
 > **Important:** Prefer `--target=...`. The legacy `--ide` flag still works for `copilot`, `claude`, `both`, and `auto`, but it is deprecated in favor of APM-style targets. If Copilot is installed in a workspace, Specky strips Claude hooks from `.claude/settings.json` to prevent Copilot cross-read blocks. See [docs/INSTALL.md](docs/INSTALL.md) for details.
@@ -113,14 +114,44 @@ npm install --save-dev specky-sdd@latest
 npx specky install --target=copilot
 ```
 
-The CLI installs 13 agents, 22 prompts, 14 skills, 16 hooks, the target MCP server registration (pinned to the installed version), and pre-authorizes or scopes tools according to the selected harness. It does **not** pre-authorize arbitrary shell, `rm`, or network access; those still prompt. Run `specky doctor` anytime to validate integrity and config.
+The CLI installs 13 agents, 22 prompts, 14 skills, 16 hooks, and target-local MCP registration pinned to the installed version. Canonical agent capabilities compile to the selected harness's native tools; they are not inferred from workflow prose. Use `--permission-profile=scoped` (default) for narrow Claude pre-authorization, or `--permission-profile=prompt` to leave every approval with the host. Specky does **not** pre-authorize arbitrary shell, `rm`, network access, or credentials. Add `--integration=github` only when GitHub MCP routing is required. Run `specky doctor` anytime to validate integrity and configuration.
 
-Generated assets are platform-native. `specky install --target=copilot` writes GitHub Copilot agents/prompts with VS Code tool names such as `search`, `agent`, and `specky/sdd_get_status`, plus prompt `agent: agent` frontmatter. `specky install --target=claude` writes Claude Code agents/commands with `Read`, `Glob`, `Grep`, `Task`, and `mcp__specky__sdd_get_status`, with Copilot-only prompt metadata removed. Wave 1 APM targets also include Cursor, OpenCode, and the neutral `agent-skills` target.
+Generated assets are platform-native. `specky install --target=copilot` writes GitHub Copilot agents/prompts with VS Code tool names such as `search`, `agent`, and `specky/sdd_get_status`, plus prompt `agent: agent` frontmatter. `specky install --target=claude` writes Claude Code agents/commands with `Read`, `Glob`, `Grep`, `Task`, and `mcp__specky__sdd_get_status`, with Copilot-only prompt metadata removed. Cursor and OpenCode receive their own native vocabulary. `agent-skills` is intentionally skills-only. See [Target Capabilities](docs/TARGET-CAPABILITIES.md) for the full capability matrix, GitHub MCP opt-in, and host approval boundaries.
 
 Specky also has an APM governance layer for enterprise package control. `apm.yml` declares the package primitives, targets, and MCP runtime; `apm.lock.yaml` pins primitive hashes; `apm-policy.yml` enforces MCP and tool-name policy. Maintainers and CI can run `specky apm validate`, `specky apm policy`, `specky apm verify-lock`, and `specky apm sbom` before publishing or installing. See [Uso do APM pelo Specky](docs/APM-USAGE.md) for the detailed model, including why APM is not a runtime proxy and why users do not need to install the Microsoft APM CLI.
 
 Full walkthroughs per OS, offline install, and CLI reference: [docs/INSTALL.md](docs/INSTALL.md) · [docs/CLI.md](docs/CLI.md).
 
+### How to upgrade
+
+When a new Specky version is out (banner from `specky doctor` / `specky status`, or [GitHub Releases](https://github.com/paulasilvatech/specky/releases)):
+
+```bash
+# Global CLI (most users)
+npm install -g specky-sdd@latest
+cd your-project
+specky upgrade
+```
+
+```bash
+# Per-project pin (teams)
+npm install --save-dev specky-sdd@latest
+npx specky upgrade
+```
+
+**You do not need `--target` on upgrade.** `specky upgrade` reads the harness you already installed from `.specky/install.json` and refreshes the same targets — agents, prompts, skills, hooks, and MCP registration (`.mcp.json`, `.vscode/mcp.json`, `.cursor/mcp.json`, or `opencode.json`). It preserves `.specs/` (pipeline artifacts) and `.specky/profile.json` (onboarding answers).
+
+Updating only the npm package is not enough: without `specky upgrade`, MCP pins can still point at the old server version.
+
+Use `--target` only for a **first install** or when **switching harness** (e.g. Copilot → Cursor):
+
+```bash
+specky install --target=cursor          # new target set
+specky install --force --target=copilot   # reinstall / repair one target
+```
+
+See also [Staying up to date](#staying-up-to-date) for update notifications and opt-out.
+
 ## Why Specifications Matter in the AI Era
 
 ```mermaid
@@ -989,12 +1020,16 @@ Specky tells you about new versions in two ways:
 - **Version drift warning (always on, zero network):** `specky doctor` and `specky status` warn when the assets installed in your project differ from the version of the CLI running them, and suggest `specky upgrade`. The MCP server prints the same warning at startup. This is a local file comparison — no network involved.
 - **Update banner (once daily):** after `install`, `doctor`, `status`, `upgrade`, or `--version`, the CLI checks the npm registry at most once per day and prints `Update available: vX → vY` when a newer release exists. This is a single GET to `registry.npmjs.org` — no telemetry, nothing sent beyond the request itself. It fails silently offline, is disabled in CI (`CI=true`), and **never runs in `specky serve`** — the MCP server itself never phones home.
 
-Upgrading is one command:
+Upgrading is two steps — bump the package, then refresh the project:
 
 ```bash
-npm install -g specky-sdd@latest && specky upgrade
+npm install -g specky-sdd@latest && cd your-project && specky upgrade
 ```
 
+Per-project installs: `npm install --save-dev specky-sdd@latest && npx specky upgrade`.
+
+**No `--target` on upgrade** — Specky reuses the targets recorded in `.specky/install.json`. See [How to upgrade](#how-to-upgrade) for the full flow and when `--target` is still required (first install or harness switch).
+
 `specky upgrade` matters: it refreshes the installed agents, prompts, skills, and hooks **and re-pins `.mcp.json` / `.vscode/mcp.json` to the new version** — updating the npm package alone leaves the MCP registration pointing at the old pinned server.
 
 Teams pinning per-project (`npm install --save-dev specky-sdd`) should let [Renovate](https://docs.renovatebot.com/) or [Dependabot](https://docs.github.com/en/code-security/dependabot) propose the `package.json` bump. For release emails, use **Watch → Custom → Releases** on the [GitHub repo](https://github.com/paulasilvatech/specky).
@@ -1218,9 +1253,9 @@ npm run dev
 echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js 2>/dev/null
 
 # Run the published image from GHCR (multi-arch: linux/amd64 + linux/arm64)
-docker pull ghcr.io/paulasilvatech/specky:latest        # or pin a release: :3.10.1
+docker pull ghcr.io/paulasilvatech/specky:latest        # or pin a release: :3.11.0
 docker run --rm -p 3200:3200 ghcr.io/paulasilvatech/specky:latest
-curl http://localhost:3200/health                       # -> {"status":"ok","version":"3.10.1"}
+curl http://localhost:3200/health                       # -> {"status":"ok","version":"3.11.0"}
 
 # Or build and run locally from source
 docker build -t specky-sdd:dev .

package/SECURITY.md

@@ -46,6 +46,10 @@ AI Client → JSON-RPC → Zod .strict() validation → Service layer
 
 Specky does **not** use `eval()`, `Function()`, `vm.runInNewContext()`, or any dynamic code execution. Template rendering uses string replacement only — no template engines that execute code.
 
+### Agent Capability Boundaries
+
+The Specky MCP server does not execute arbitrary shell commands or persist GitHub credentials. Generated agents may declare narrowly scoped Git, test, or release-gate capabilities, but the selected host runtime executes and approves those native tools. The optional GitHub MCP integration is registered only with `specky install --integration=github`; GitHub authentication and repository authorization remain with the signed-in host identity. See [Target Capabilities](docs/TARGET-CAPABILITIES.md).
+
 ### Network Calls
 
 The **MCP server makes zero outbound network calls**. All data stays on the user's machine. It communicates only via stdio (JSON-RPC over stdin/stdout) or optional HTTP transport on localhost, and this holds unconditionally — `specky serve` never performs the update check described below.
@@ -127,7 +131,7 @@ The audit trail's plain hash chain detects corruption but not deliberate rewriti
 - Zero `any` types in source code — enforced by CI
 - All schemas use `.strict()` — rejects unknown fields
 - `FileManager` is the sole I/O boundary — no direct `fs` calls in tools or other services
-- No shell command execution — branch names and PR payloads are data only, not executed
+- The Specky MCP server does not execute shell commands; target runtimes may execute only the explicitly declared, host-approved agent capabilities
 
 ## Security Best Practices for Users
 

package/apm-policy.yml

@@ -16,6 +16,8 @@ mcp:
   allowTransitive: false
   allowedServers:
     - specky
+  optionalCapabilityServers:
+    - github
 
 # Hook governance. Hook manifests may only register these event types.
 hooks:

package/apm.lock.yaml

@@ -2,21 +2,21 @@
 schemaVersion: 1
 package:
   name: specky-sdd
-  version: 3.10.1
+  version: 3.11.0
 primitives:
-  .apm/agents/specky-design-architect.agent.md: sha256:a9411a98bd2fe4c4aa1e6eab66e84eaf9a010897d408e1737a279fe58f7023b2
-  .apm/agents/specky-implementer.agent.md: sha256:76c546fe70fe3f5399ba25f0e6de3d9b280880fe7c12d88f093cee55c0b02ece
-  .apm/agents/specky-onboarding.agent.md: sha256:755a51c27eb1fe044ce4940fe6dda3a8eb0ff983c04d1c00e1d59be59723aa9d
-  .apm/agents/specky-orchestrator.agent.md: sha256:aae379a2dd8833fc9861ee9302f244032856a739b3fb31f568713f866a16f0c8
-  .apm/agents/specky-quality-reviewer.agent.md: sha256:cdcbe7bee2a4c669b52b8a67d5f31bc01ea0b518ca6daabf57a4603af2312c83
-  .apm/agents/specky-release-engineer.agent.md: sha256:b33e0f64b6fe23fb427c9368945d76e780aff1d8d848ab67bbcb2fa1a03f50e9
-  .apm/agents/specky-requirements-engineer.agent.md: sha256:69f84bf9a9f7d76475f7a21e9067c906b73c2a867db9fefe50abee2a4942b762
-  .apm/agents/specky-research-analyst.agent.md: sha256:4bc469d91b8c573cde9097efdbf1ba9fc0bc9580b4e0148e679bb689fbf744b0
-  .apm/agents/specky-sdd-clarify.agent.md: sha256:6dcd4879b2fff198a1fa80d61003eec852d4b1a82b7da1bf46c037a00bd463b6
-  .apm/agents/specky-sdd-init.agent.md: sha256:dff5a301375885781085f0421524cd58ef2305c43084c71e09625c2255182e8a
-  .apm/agents/specky-spec-engineer.agent.md: sha256:1a119fb44d1e48189726d61a1fbe11b2291535defed71316a8dba01f43401efd
-  .apm/agents/specky-task-planner.agent.md: sha256:5be3951932c925d09ff7c0a6066ccad2e25bc9fcc3950088b6966cefe6b98fde
-  .apm/agents/specky-test-verifier.agent.md: sha256:26291f7940f909649da55f8755f0b4a03bbaeae15e2fd61c18f00e7488d44220
+  .apm/agents/specky-design-architect.agent.md: sha256:206bb609b3f1547ede880a61f9e4b3a3a9c1df22dc33310fd5af1452dbeaff0f
+  .apm/agents/specky-implementer.agent.md: sha256:4768d48f96d6826a06a1a7ead47c0f74a3caa3afc7d0f93e03faa3b6c5ad49df
+  .apm/agents/specky-onboarding.agent.md: sha256:eb3e04effaedfece9b74233f0f1e59ceceafe78db2ec940c97d785b318b2e8d2
+  .apm/agents/specky-orchestrator.agent.md: sha256:fea1cc4d8498fa762eba4409f44f624a7b256de49d0215bce1c5a4013032f4cb
+  .apm/agents/specky-quality-reviewer.agent.md: sha256:bb81e074e4fa8887745e3da341cf11eb8c10978cc4989cd3a2c221798fad2ce0
+  .apm/agents/specky-release-engineer.agent.md: sha256:679125e0fe1b2da40ca0142848eecdd0e518eb279a927acdbf006bf7de638df5
+  .apm/agents/specky-requirements-engineer.agent.md: sha256:9393480399ced54dd8b201e6821103c9ed9e27fdbdf7426745e0da9535f60ddb
+  .apm/agents/specky-research-analyst.agent.md: sha256:92cd4041e0b021efa310e2cf12abb3c45e8f08e490e4b9bb275a81f4c4845cd9
+  .apm/agents/specky-sdd-clarify.agent.md: sha256:0dac1b774dc616eecddd5937e6ee520de32cdb12482fe3c25181a9e199d82302
+  .apm/agents/specky-sdd-init.agent.md: sha256:7dbba26d70b4fa9aada59e9a1efb8fa811cbe94fbf4c7429940ce7941393f3f2
+  .apm/agents/specky-spec-engineer.agent.md: sha256:dc639dde08405d06199b0257363d8ae70e5e14f3dcf991b43e5529e56d241ae8
+  .apm/agents/specky-task-planner.agent.md: sha256:124ebb0dde85dded8d7dd57ef728fa9838a78884bbd9de0f89f74879ae6d0e85
+  .apm/agents/specky-test-verifier.agent.md: sha256:e1386f81ae1fe9694c34d5b518e408804f2709237e137ce28bab48819e82f924
   .apm/hooks/scripts/specky-artifact-validator.sh: sha256:2c255e3221cca919ace520ce319c66cc4904aa9c917ce08a52547fe63f8d9770
   .apm/hooks/scripts/specky-auto-checkpoint.sh: sha256:46d5a336b20c844469574b2281b5cae24ee5116547a262bb160135aaef38d62e
   .apm/hooks/scripts/specky-branch-validator.sh: sha256:73256941bdc4aaac518935214c6f0029f32b1529307088243142fe7423594cf6
@@ -77,5 +77,5 @@ primitives:
   .apm/skills/specky-spec-engineer/SKILL.md: sha256:b5722dacc513a69b54a2d474e1dfa4a25029c5f6f2a930fae3b0ed8f3c9eb49e
   .apm/skills/specky-task-planner/SKILL.md: sha256:bf391eaa0541ae507f99eacd18a8747b597bcde4ff84d9a389fdc4aad5e76ed7
   .apm/skills/specky-test-verifier/SKILL.md: sha256:7e663a68f597f409a7209e07830b90b467052583bde8557eed389848baaa8609
-  apm-policy.yml: sha256:421910c17b1a7431f1336d8374538c111245c0c1de58adc6d8eddc185010a639
-  apm.yml: sha256:faaad94df10783caf1226b684caac659685a418e70e3f4172610bdbfc89cdb5e
+  apm-policy.yml: sha256:560cfde2c8efe36bdc2cbb095f259506d51312249d3b4cee67640e244e972530
+  apm.yml: sha256:ac0a62e81a271f1a2de440018d3463991a8c1ee8dd376e4024eea27d1b1c5b3f

package/apm.yml

@@ -1,5 +1,5 @@
 name: specky-sdd
-version: 3.10.1
+version: 3.11.0
 description: "Agentic Spec-Driven Development — 10-phase pipeline with 58 MCP tools, 13 agents, 22 prompts, 14 skills, 16 hooks, EARS notation, model routing, and enterprise security"
 author: Paula Silva
 license: MIT
@@ -32,7 +32,7 @@ mcp:
       registry: false
       transport: stdio
       command: npx
-      args: ["-y", "specky-sdd@latest", "serve"]
+      args: ["-y", "specky-sdd@3.11.0", "serve"]
       tools: ["sdd_*"]
 
 dependencies:
@@ -41,7 +41,7 @@ dependencies:
       registry: false
       transport: stdio
       command: npx
-      args: ["-y", "specky-sdd@latest"]
+      args: ["-y", "specky-sdd@3.11.0"]
       tools: ["*"]
 
 scripts:

package/config.yml

@@ -1,5 +1,8 @@
 audit_enabled: true
-version: "3.10.1"
+version: "3.11.0"
+installation:
+  permission_profile: scoped
+  integrations: []
 pipeline:
   phases: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
   phase_names:

package/dist/cli/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAwdD,wBAAsB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAkEpE"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAwgBD,wBAAsB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAuEpE"}