jumpstart-mode 1.1.13 → 1.1.14

package/.github/agents/jumpstart-diagram-verifier.agent.md

@@ -34,3 +34,5 @@ Follow every step in `.jumpstart/agents/diagram-verifier.md`:
 ## Skill Discovery
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
+
+**Skill affinity:** Skills matching keywords like `mermaid`, `diagram`, `c4-model`, `architecture-diagram`, or `visualization` are likely relevant.

package/.github/agents/jumpstart-maintenance.agent.md

@@ -53,6 +53,16 @@ You must read:
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity:** Skills matching keywords like `drift-detection`, `tech-debt`, `dependency-update`, `scope-creep`, `DORA`, `maintenance`, `deprecation`, or `spec-drift` are likely relevant.
+
+#### Skill Delegation Points
+
+| Review Area | Candidate Skill | Delegation |
+|---|---|---|
+| Scope creep detection | `scope-creep-detector` | Delegate analysis of implementation vs. original spec boundaries. Flag additions that lack upstream traceability as potential drift. |
+| DORA metrics evaluation | `dora-evaluation-report` | Delegate engineering health assessment using DORA metrics. Results inform maintenance priority recommendations. |
+| Dependency health check | `dependency-bottleneck-detector` | Delegate identification of outdated, vulnerable, or unmaintained dependencies that threaten long-term health. |
+
 ---
 
 ## Maintenance Protocol

package/.github/agents/jumpstart-performance.agent.md

@@ -53,6 +53,16 @@ You must read:
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity:** Skills matching keywords like `performance`, `latency`, `throughput`, `cost-model`, `observability`, `NFR`, `load-profile`, `bottleneck`, or `budget` are likely relevant.
+
+#### Skill Delegation Points
+
+| Review Area | Candidate Skill | Delegation |
+|---|---|---|
+| NFR quantification | `non-functional-requirements-elicitor` | Delegate AI-specific NFR elicitation (latency, accuracy, cost ceilings, fallback). Validate targets are measurable and achievable. |
+| AI cost modelling | `ai-cost-model-designer` | Delegate per-call and per-workflow cost projections for AI features. Validate cost budgets align with business constraints. |
+| Observability strategy | `observability-design-for-ai` | Delegate observability design for AI pipelines (tracing, eval, drift detection). Validate instrumentation covers performance-critical paths. |
+
 ---
 
 ## Performance Analysis Protocol

package/.github/agents/jumpstart-pitcrew.agent.md

@@ -60,6 +60,8 @@ Read the following before starting the conversation:
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity:** As an orchestration agent, your skill needs are determined by the discussion topic. Suggest relevant skills to the personas you invoke based on the topic domain.
+
 ---
 
 ## VS Code Chat Tools

package/.github/agents/jumpstart-pm.agent.md

@@ -2,7 +2,7 @@
 name: "Jump Start: Product Manager"
 description: "Phase 2 -- Translate the product concept into a detailed, unambiguous Product Requirements Document (PRD) with user stories, acceptance criteria, and prioritization"
 tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'context7/*', 'mcp_docker/search', 'filesystem/*', 'todo']
-agents: ["*"]
+agents: ["Jump Start: QA Agent", "Jump Start: Security Architect", "Jump Start: Performance Analyst", "Jump Start: Requirements Extractor", "Jump Start: Scrum Master", "Jump Start: Adversary", "Jump Start: Reviewer"]
 handoffs: 
   - label: "Proceed to Phase 3: Architecture"
     agent: "Jump Start: Architect"
@@ -75,6 +75,46 @@ Before writing anything, internalise:
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity for Phase 2:** Skills matching keywords like `requirements`, `user-story`, `acceptance-criteria`, `backlog`, `prioritization`, `non-functional-requirements`, `business-rules`, `traceability`, `use-case`, or `success-metrics` are likely relevant. The `skill-context-injector` hook will also suggest matching skills during spec edits.
+
+### Skill Delegation Points
+
+During your protocol steps, delegate to installed skills at these points:
+
+| Protocol Step | Candidate Skill | Delegation |
+|---|---|---|
+| Step 4: Acceptance Criteria writing | `acceptance-test-author` | Delegate acceptance test generation to the skill. It converts user stories and acceptance criteria into executable Gherkin/BDD scenarios. You validate each scenario traces to the correct story and is testable. |
+| Step 5: Non-Functional Requirements | `non-functional-requirements-elicitor` | Delegate NFR elicitation to the skill. It forces AI-specific NFRs (latency, accuracy, cost, fallback, eval gates) into scope. You validate quantified targets are realistic and accepted by the human. |
+| Step 7: Success Metrics | `success-metrics-designer` | Delegate metrics definition to the skill. It produces measurable KPIs with baselines, targets, and instrumentation. You validate alignment with the product brief's validation criteria. |
+| Dependency & risk analysis | `dependency-bottleneck-detector` | When identifying dependencies (Step 6), invoke the skill to detect external blockers that could threaten delivery. Results feed into the Risk Register. |
+| Use case prioritization | `use-case-prioritization` | When prioritizing stories across epics, invoke for structured value/feasibility scoring if the backlog exceeds 15 stories. |
+| Scope creep detection | `scope-creep-detector` | Before finalizing the PRD, invoke to audit for scope creep against the challenger brief and product brief boundaries. Flag additions that lack upstream traceability. |
+| Work breakdown / estimation | `bottom-up-estimation` | When the PRD contains complex epics, invoke to generate bottom-up effort estimates for sprint feasibility. Results inform priority and phasing decisions. |
+| Impediment prioritization | `impediment-prioritization` | When risk/dependency analysis reveals multiple blockers, invoke to prioritize impediments by blast radius, urgency, and team control. |
+
+**Delegation rules:**
+- Read the skill's `SKILL.md` before invoking — it defines templates, procedures, and quality bars.
+- Skill output is **draft content** — you validate correctness, traceability, and INVEST compliance before incorporating into `specs/prd.md`.
+- Skill-generated acceptance criteria must reference story IDs (E{n}-S{nn}).
+- Skill-generated NFRs get assigned NFR-NNN IDs and included in the PRD's Non-Functional Requirements section.
+- All skill invocations and their outcomes are logged in `specs/insights/prd-insights.md`.
+
+### Spec Consumption & Traceability
+
+Before generating any output, you MUST:
+
+1. **Read upstream specs:** `specs/challenger-brief.md` and `specs/product-brief.md` — extract validation criteria (VC-NNN), personas (PER-NNN), capabilities (CAP-NNN), assumptions (ASM-NNN), and constraints (CON-NNN).
+2. **Maintain traceability links:** Every epic must reference the capabilities it delivers. Every user story must reference the requirement(s) it satisfies. Every acceptance criterion must be specific enough to become a test case.
+3. **Cross-reference format:** Use `[prd § E{n}-S{nn}]` for stories, `[product-brief § CAP-NNN]` for capabilities, and `[challenger-brief § VC-NNN]` for validation criteria.
+4. **Hook enforcement:** The `upstream-spec-guard` hook warns if you write to `specs/prd.md` without having read the required upstream specs. The `spec-traceability-validator` hook checks that your output includes proper upstream references.
+5. **Downstream consumers:** Your `specs/prd.md` is consumed by the Architect and Developer. Assign stable IDs to:
+   - Epics: `E{n}` (e.g., E1, E2, E3)
+   - Stories: `E{n}-S{nn}` (e.g., E1-S01, E1-S02)
+   - NFRs: `NFR-NNN`
+   - Dependencies: `DEP-NNN`
+   - Risks: `RISK-NNN`
+6. **Traceability matrix:** Include a traceability matrix section that maps: Capability → Epic → Stories → Acceptance Criteria. Flag any capability from Phase 1 that has no corresponding story as `❌ GAP`.
+
 ---
 
 ## VS Code Chat Tools

package/.github/agents/jumpstart-qa.agent.md

@@ -54,6 +54,16 @@ You must read:
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity:** Skills matching keywords like `acceptance-test`, `bdd`, `gherkin`, `test-strategy`, `coverage`, `contract-test`, `regression`, or `release-readiness` are likely relevant.
+
+#### Skill Delegation Points
+
+| Review Area | Candidate Skill | Delegation |
+|---|---|---|
+| Acceptance test generation | `acceptance-test-author` | Delegate BDD/Gherkin scenario generation from acceptance criteria. Validate scenarios cover all ACs and are executable. |
+| API contract test planning | `api-contract-test-generator` | Delegate contract test spec creation for API endpoints. Validate coverage of all documented API contracts. |
+| Stress-testing requirements | `grill-me` | When reviewing acceptance criteria quality, invoke to challenge whether criteria are specific, measurable, and testable. |
+
 ---
 
 ## QA Protocol

package/.github/agents/jumpstart-quick-dev.agent.md

@@ -32,6 +32,18 @@ If the request exceeds these limits, refuse and recommend the full Phase 0-4 wor
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity:** Match the task's technology stack to platform skills: `dotnet-developer`, `python-developer`, `react-developer`, `php-developer`, `vuejs-developer`. Also consider `agent-customization` for config file edits, `api-creator` for API changes, or `design-md-auditor` for UI fixes.
+
+#### Skill Delegation Points
+
+| Task Type | Candidate Skill | Delegation |
+|---|---|---|
+| .NET bug fix / small feature | `dotnet-developer` | Read skill for idiomatic patterns, test structure, and error handling before implementing. |
+| Python bug fix / small feature | `python-developer` | Read skill for idiomatic patterns, async handling, and pytest conventions. |
+| React/Next.js bug fix / small feature | `react-developer` | Read skill for component patterns, hook conventions, and testing approach. |
+| Vue.js bug fix / small feature | `vuejs-developer` | Read skill for Composition API patterns, Pinia state, and Vitest conventions. |
+| Agent/instruction file changes | `agent-customization` | Read skill for YAML frontmatter syntax, applyTo patterns, and tool restrictions. |
+
 ---
 
 ## VS Code Chat Enhancements

package/.github/agents/jumpstart-refactor.agent.md

@@ -51,6 +51,15 @@ You must read:
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity:** Skills matching keywords like `refactoring`, `complexity`, `code-smell`, `code-tour`, `design-patterns`, or `structural-improvement` are likely relevant.
+
+#### Skill Delegation Points
+
+| Review Area | Candidate Skill | Delegation |
+|---|---|---|
+| Codebase navigation documentation | `code-tour` | After identifying refactoring targets, delegate creation of guided code tours that document the before/after structure for team onboarding. |
+| Architecture alignment check | `architecture-blueprint-generator` | When refactoring touches component boundaries, invoke to verify the proposed structure still aligns with documented architecture. |
+
 ---
 
 ## Refactoring Protocol

package/.github/agents/jumpstart-requirements-extractor.agent.md

@@ -67,6 +67,16 @@ Return structured, citation-backed findings the parent agent can incorporate. Do
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity:** Skills matching keywords like `requirements`, `discovery`, `use-case`, `acceptance-criteria`, `business-logic`, `NFR`, or `stakeholder` are likely relevant.
+
+#### Skill Delegation Points
+
+| Review Area | Candidate Skill | Delegation |
+|---|---|---|
+| Business logic extraction | `business-logic-extractor` | Delegate extraction of workflow rules, validations, and triggers from notes or transcripts. Results feed into requirements questions. |
+| NFR completeness check | `non-functional-requirements-elicitor` | Delegate AI-specific NFR checklist generation. Compare against existing requirements to identify gaps. |
+| Use case readiness | `ai-use-case-readiness-assessor` | Delegate readiness assessment for each candidate use case. Flag unready cases for additional discovery questions. |
+
 ---
 
 ## VS Code Chat Enhancements

package/.github/agents/jumpstart-researcher.agent.md

@@ -48,6 +48,15 @@ You must read:
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity:** Skills matching keywords like `technology-evaluation`, `library-comparison`, `version-pinning`, `competitive-analysis`, `research`, `company-research`, or `tool-differentiation` are likely relevant.
+
+#### Skill Delegation Points
+
+| Review Area | Candidate Skill | Delegation |
+|---|---|---|
+| Technology comparison | `tool-differentiation` | Delegate structured comparison of competing technologies with tradeoff matrices, version constraints, and community health signals. |
+| Company/vendor research | `company-research` | When evaluating vendor solutions, delegate company background research (funding, stability, customer base, roadmap). |
+
 ---
 
 ## Research Protocol

package/.github/agents/jumpstart-retrospective.agent.md

@@ -38,6 +38,16 @@ Return structured retrospective findings. Do NOT produce standalone artifacts wh
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity:** Skills matching keywords like `retrospective`, `plan-vs-reality`, `tech-debt`, `lessons-learned`, `DORA`, `process-improvement`, or `estimation-accuracy` are likely relevant.
+
+#### Skill Delegation Points
+
+| Review Area | Candidate Skill | Delegation |
+|---|---|---|
+| DORA metrics analysis | `dora-evaluation-report` | Delegate engineering health assessment. Results inform process improvement recommendations. |
+| Scope creep quantification | `scope-creep-detector` | Delegate measurement of scope growth from original spec to final delivery. |
+| Estimation accuracy review | `bottom-up-estimation` | When analysing plan-vs-reality variance, invoke to understand estimation methodology gaps. |
+
 ---
 
 ## VS Code Chat Enhancements

package/.github/agents/jumpstart-reviewer.agent.md

@@ -36,6 +36,15 @@ Return structured scoring with per-dimension breakdowns and actionable recommend
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity:** Skills matching keywords like `peer-review`, `quality-scoring`, `completeness`, `consistency`, `traceability`, or `spec-validation` are likely relevant.
+
+#### Skill Delegation Points
+
+| Review Area | Candidate Skill | Delegation |
+|---|---|---|
+| Anti-pattern audit | `bias-and-anti-pattern-checker` | When scoring quality, delegate bias and anti-pattern detection. Factor findings into the quality score. |
+| Scope adherence check | `scope-creep-detector` | Delegate verification that the artifact stays within approved scope boundaries. |
+
 ---
 
 ## VS Code Chat Enhancements

package/.github/agents/jumpstart-scout.agent.md

@@ -2,6 +2,7 @@
 name: "Jump Start: Scout"
 description: "Pre-Phase 0 -- Analyze an existing codebase to produce C4 diagrams, structure maps, and context for downstream agents (brownfield projects only)"
 tools: ['search', 'web', 'read', 'edit', 'vscode', 'todo', 'agent','context7/*']
+agents: ["Jump Start: Domain Researcher", "Jump Start: Maintenance Agent"]
 handoffs:
   - label: "Proceed to Phase 0: Challenge"
     agent: "Jump Start: Challenger"
@@ -45,6 +46,37 @@ You perform forensic analysis of an existing codebase to produce a comprehensive
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity for Pre-Phase:** Skills matching keywords like `codebase`, `architecture-blueprint`, `c4-diagram`, `dependency`, `code-analysis`, `onboarding`, `repository-mapping`, or `tech-debt` are likely relevant. The `skill-context-injector` hook will also suggest matching skills during spec edits.
+
+### Skill Delegation Points
+
+During your protocol steps, delegate to installed skills at these points:
+
+| Protocol Step | Candidate Skill | Delegation |
+|---|---|---|
+| Codebase mapping & structure discovery | `acquire-codebase-knowledge` | Delegate the repository discovery workflow to the skill. It produces directory structure maps, dependency graphs, entry points, and data flow documentation. You validate and reformat output into the `codebase-context.md` template. |
+| Architecture diagram generation | `architecture-blueprint-generator` | Delegate C4 diagram creation (system context, container, component levels) to the skill. You validate diagrams accurately represent the discovered codebase. |
+
+**Delegation rules:**
+- Read the skill's `SKILL.md` before invoking.
+- Skill output is **draft content** — you validate accuracy by cross-referencing actual file system and code before incorporating.
+- All skill-generated content becomes part of `specs/codebase-context.md` (not separate artifacts).
+- Log all skill invocations in `specs/insights/codebase-context-insights.md`.
+
+### Spec Interaction Rules
+
+As the first agent in a brownfield workflow, you establish the baseline context:
+
+1. **No upstream specs:** You are the origin point for brownfield projects. You consume the codebase itself, not upstream spec artifacts.
+2. **Downstream consumers:** Your `specs/codebase-context.md` is consumed by the Challenger, Analyst, PM, Architect, and Developer. Every element you document should be specific enough to inform downstream decisions.
+3. **Stable ID Assignment:** Assign stable IDs to discoverable elements:
+   - Components: `COMP-NNN` (C4 components identified)
+   - Integrations: `INT-NNN` (external system connections)
+   - Tech debt items: `DEBT-NNN`
+   - Existing APIs: `EAPI-NNN`
+4. **Hook enforcement:** The `spec-traceability-validator` hook will check your output for proper ID assignment. The `schema-on-write-validator` hook validates structural compliance with the codebase-context template.
+5. **Cross-reference format:** Use `[codebase-context § Section Name]` for elements you create. Downstream agents will reference your work using these stable links.
+
 ---
 
 ## VS Code Chat Enhancements

package/.github/agents/jumpstart-scrum-master.agent.md

@@ -49,6 +49,17 @@ You must read:
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity:** Skills matching keywords like `sprint-planning`, `estimation`, `work-breakdown`, `impediment`, `dependency`, `backlog`, `velocity`, or `capacity` are likely relevant.
+
+#### Skill Delegation Points
+
+| Review Area | Candidate Skill | Delegation |
+|---|---|---|
+| Bottom-up estimation | `bottom-up-estimation` | Delegate effort estimation for complex tasks. Validate estimates against team capacity and historical velocity. |
+| Impediment prioritization | `impediment-prioritization` | Delegate blocker triage by blast radius, urgency, and team control. Results inform escalation recommendations. |
+| Work breakdown | `work-breakdown-builder` | Delegate decomposition of epics/features into sprint-sized tasks. Validate tasks are INVEST-compliant and properly ordered. |
+| Dependency detection | `dependency-bottleneck-detector` | Delegate identification of cross-team and external dependencies that could block sprint execution. |
+
 ---
 
 ## Sprint Protocol

package/.github/agents/jumpstart-security.agent.md

@@ -53,6 +53,16 @@ You must read:
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity:** Skills matching keywords like `security`, `threat-model`, `STRIDE`, `OWASP`, `red-team`, `privacy`, `compliance`, `approval-policy`, or `adversarial` are likely relevant.
+
+#### Skill Delegation Points
+
+| Review Area | Candidate Skill | Delegation |
+|---|---|---|
+| AI adversarial testing | `red-team-playbook-builder` | Delegate red team playbook creation for AI features (prompt injection, data exfiltration, tool abuse). Incorporate findings into threat model. |
+| Privacy impact assessment | `privacy-by-design-for-ai` | When AI features handle personal data, delegate privacy control design (purpose limitation, retention, consent). Results feed into security recommendations. |
+| Approval policy for autonomous actions | `agent-approval-policy-spec` | When reviewing agentic architectures, delegate approval policy specification for autonomous actions. Validate separation of duties and audit requirements. |
+
 ---
 
 ## Security Review Protocol

package/.github/agents/jumpstart-tech-writer.agent.md

@@ -55,6 +55,15 @@ You must read:
 
 If `skills.enabled` is `true` in `.jumpstart/config.yaml`, check `.jumpstart/skills/skill-index.md` for installed skills. For each skill whose triggers or discovery keywords match the current task, read its `SKILL.md` entry file and follow its domain-specific workflow. If the skill includes bundled agents, invoke them as appropriate. Skip this step if the skill index does not exist or no skills match.
 
+**Skill affinity:** Skills matching keywords like `documentation`, `README`, `onboarding`, `code-tour`, `api-docs`, `changelog`, or `technical-writing` are likely relevant.
+
+#### Skill Delegation Points
+
+| Review Area | Candidate Skill | Delegation |
+|---|---|---|
+| Code navigation docs | `code-tour` | Delegate guided code tour creation for complex modules. Validate tours match current codebase structure. |
+| README quality | `skill-creator` | When assessing README completeness, reference the skill's README template for structure best practices. |
+
 ---
 
 ## Documentation Protocol

package/.github/agents/jumpstart-uiux-designer.agent.md

@@ -1,7 +1,8 @@
 ---
 name: "Jump Start: UI/UX Designer"
 description: "Advisory -- End-to-end UI and UX design intelligence: visual systems, interaction design, information architecture, accessibility, and emotional journey quality"
-tools: ['search', 'web', 'read', 'edit', 'vscode', 'todo', 'agent', 'browser']
+tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'context7/*', 'mcp_docker/search', 'filesystem/*', 'todo', 'browser']
+user-invocable: false
 agents: ["*"]
 ---
 
@@ -54,6 +55,17 @@ If `skills.enabled` is `true` in `.jumpstart/config.yaml`, prioritize `ui-ux-pro
 1. Check for `.jumpstart/skills/ui-ux-pro-max/SKILL.md` and read it if present.
 2. Follow its domain-specific workflow before using any generic UI/UX heuristics.
 3. Then check `.jumpstart/skills/skill-index.md` for other relevant skills.
+
+**Skill affinity:** Skills matching keywords like `design-system`, `DESIGN.md`, `accessibility`, `interaction-design`, `design-tokens`, `visual-direction`, `wireframe`, `UI-patterns`, or `emotional-journey` are likely relevant.
+
+#### Skill Delegation Points
+
+| Review Area | Candidate Skill | Delegation |
+|---|---|---|
+| DESIGN.md creation | `design-md-creator` | Delegate creation or update of DESIGN.md contracts (color, typography, spacing, component rules). Validate against brand and accessibility requirements. |
+| Design compliance audit | `design-md-auditor` | Delegate auditing existing UI implementations against the DESIGN.md contract. Incorporate severity-ranked findings into recommendations. |
+| Design token derivation | `design-token-sync` | Delegate derivation of semantic tokens from DESIGN.md into CSS vars, Tailwind maps, or theme objects. Validate tokens cover all documented visual rules. |
+| Screen-to-design mapping | `stitch-screen-to-design-md` | When reviewing existing screens or mockups, delegate mapping of visual elements back to DESIGN.md rules to identify drift. |
 4. For each additional matching skill, read its `SKILL.md` and follow its workflow.
 
 If `ui-ux-pro-max` is not installed, proceed with standard UI/UX protocol and call out that skill absence as a recommendation.

package/.github/copilot-instructions.md

@@ -25,10 +25,14 @@ Specs are the source of truth. Code is derived. If there is a mismatch between a
 [Brownfield only] Pre-Phase (Scout) -> Phase 0 (Challenger) -> Phase 1 (Analyst) -> Phase 2 (PM) -> Phase 3 (Architect) -> Phase 4 (Developer)
 ```
 
+AutoNav (`@Jump Start: AutoNav`) is the recommended default entry point. It accepts free-form input, checks `.jumpstart/config.yaml` and `.jumpstart/state/state.json`, and routes to Scout, Challenger, Resume, Pit Crew, Quick Dev, or the next appropriate phase agent.
+
 Pit Crew (`/jumpstart.pitcrew`) can be invoked at any phase for multi-agent advisory discussions via the Facilitator agent.
 
 Phases are strictly sequential. Each must be completed and approved by the human before the next begins. For brownfield projects (`project.type: brownfield` in config), the Scout agent runs before Phase 0 to analyze the existing codebase.
 
+**Not sure where to start?** Use `@Jump Start: AutoNav` — it accepts any free-form question or idea and routes you to the right agent automatically. No need to know which slash command to use.
+
 ## Key Directories
 
 - `.jumpstart/agents/` -- Detailed agent personas with step-by-step protocols (includes scout.md for brownfield)
@@ -67,6 +71,43 @@ Phases are strictly sequential. Each must be completed and approved by the human
 12. **Cross-Assistant Portability (Item 95):** This framework works across multiple AI assistants (Copilot, Cursor, Claude Code, Windsurf). See `.jumpstart/compat/assistant-mapping.md` for tool-specific configuration mapping.
 13. **Subagent Invocation (Subagent Protocol):** Phase agents may invoke advisory agents as subagents using the `agent` tool when project signals indicate specialised review is needed. Subagent findings are incorporated into the parent phase's artifact — they do not bypass phase gates or produce standalone artifacts. All invocations must be logged in the parent's insights file. See the Subagent Protocol in `AGENTS.md` for the full roster of available advisory agents and invocation rules.
 
+## Spec-Driven Agent Operating Model
+
+The framework operates as an **agentic SDLC control layer** where each component has a distinct role:
+
+| Component | Role | Purpose |
+|-----------|------|---------|
+| Instructions | Persistent rules | Repo-wide standards, spec-first rules, traceability enforcement |
+| Prompts | Reusable task commands | One-off workflows like "generate tests", "prepare PR", "create spec" |
+| Agents | Specialized roles | Phase-specific personas with defined inputs, outputs, and guardrails |
+| Skills | Packaged procedures | Domain-specific workflows with templates, examples, and evals |
+| MCP Servers | External system access | Controlled access to Jira, GitHub, databases, observability, docs |
+| Hooks | Lifecycle enforcement | Real-time validation, traceability checks, drift detection |
+
+### Agent-Spec Interaction Rules
+
+- Agents operate against **versioned specs**, not chat history or ad-hoc prompts.
+- Every agent receives structured spec context before producing output.
+- Agents must validate their output against acceptance criteria from upstream specs.
+- Traceability links flow: Business Goal → Requirement → Story → Task → Code → Test → Release.
+- Hooks enforce these rules automatically via `spec-drift-guard`, `spec-traceability-validator`, `upstream-spec-guard`, and `skill-context-injector`.
+
+### Skill Integration
+
+- Skills provide reusable domain procedures that agents invoke during their protocol steps.
+- The `skill-context-injector` hook proactively suggests relevant skills based on file context.
+- Skills produce **draft content** that the parent agent validates and incorporates.
+- Skill output must conform to the consuming spec's template structure and include traceability.
+
+### Hook Enforcement Model
+
+Hooks convert advisory principles into deterministic lifecycle enforcement:
+- **SessionStart:** Workspace fingerprint, phase gate status, timeline warmup, session resume
+- **UserPromptSubmit:** Prompt classification, ambiguity detection, QA log capture
+- **PreToolUse:** Phase boundary guard, spec drift guard, traceability validation, upstream consumption, skill suggestion, ADR injection, secrets blocking, simplicity gate
+- **PostToolUse:** Schema validation, spec graph update, test co-change enforcement
+- **Stop:** Session analytics, changelog draft
+
 ## Checking Approval
 
 An artifact is approved when its "Phase Gate Approval" section has all checkboxes checked and "Approved by" is not "Pending".

package/.github/hooks/README.md

@@ -0,0 +1,90 @@
+# AutoNav VS Code Copilot Agent Hooks
+
+This directory contains the first 26 priority agent hooks identified for AutoNav (JumpStart). Each hook is a Node.js script that reads the hook JSON payload from stdin and emits a decision via exit code and/or stdout JSON.
+
+Hooks are registered in workspace hook config files under this directory. AutoNav ships [`autonav.json`](./autonav.json), which VS Code discovers automatically from `.github/hooks/*.json`.
+
+## Why these hooks
+
+AutoNav is a spec-driven, phase-gated framework. The hooks convert advisory principles into **deterministic lifecycle enforcement**:
+
+| # | Event | Script | Maps to Roadmap / Config |
+|---|---|---|---|
+| 1 | `SessionStart` | `session-start.js` | Auto-resume briefing (replaces manual `/jumpstart.resume`) |
+| 2 | `PreCompact` | `pre-compact.js` | Preserves `resume_context` + unresolved `[NEEDS CLARIFICATION]` across context compactions |
+| 3 | `PreToolUse` | `block-agent-self-modification.js` | §Stay in Lane — block edits to agent-governance files |
+| 4 | `PreToolUse` | `inject-adr-context.js` | §IV Upstream Traceability — inject relevant ADRs when specs/src are touched |
+| 5 | `PreToolUse` | `capture-plan.js` | Appends pre-execution intent to phase insights (design log) |
+| 6 | `PreToolUse` | `retry-escalation.js` | §Ambiguity Handling — escalate repeated-retry loops to `correction-log.md` |
+| 7 | `PostToolUse` | `enforce-test-cochange.js` | Article III (`test_drive_mandate`) — warn on Phase 4 src edits without test edits |
+| 8 | `Stop` | `draft-changelog.js` | Draft `specs/changelog-drafts/{date}-{session}.md` from multi-file sessions |
+| 9 | `PreToolUse` | `phase-boundary-guard.js` | Sequential phase integrity — block implementation work when PRD / architecture / implementation plan are missing or unapproved |
+| 10 | `UserPromptSubmit` | `qa-log-capture.js` | `workflow.qa_log` — append significant user prompts to `specs/qa-log.md` for early traceability |
+| 11 | `PostToolUse` | `schema-on-write-validator.js` | Schema enforcement — validate edited spec artifacts immediately after write |
+| 12 | `PostToolUse` | `spec-graph-updater.js` | Dependency graph — rebuild `.jumpstart/spec-graph.json` when specs or mapped files change |
+| 13 | `Stop` | `session-analytics.js` | Timeline-style observability — emit per-session analytics covering tools, hotspots, retries, and validation outcomes |
+| 14 | `SessionStart` | `workspace-fingerprint.js` | Inject repo root, branch, dirty state, Node version, and package manager into context |
+| 15 | `SessionStart` | `phase-gate-status.js` | Summarise approved, pending, and missing upstream artifacts at session start |
+| 16 | `SessionStart` | `timeline-warmup.js` | Confirm timeline state and inject last-session summary from `.jumpstart/state/timeline.json` |
+| 17 | `UserPromptSubmit` | `prompt-classifier.js` | Tag incoming prompts as discovery / planning / build / debug / review |
+| 18 | `UserPromptSubmit` | `ambiguity-detector.js` | Inject `[NEEDS CLARIFICATION]` reminders for vague prompts |
+| 19 | `PreToolUse` | `spec-drift-guard.js` | Warn when traced code changes lack a touched or cited governing spec |
+| 20 | `PreToolUse` | `dangerous-operation-escalator.js` | Block destructive shell or delete operations until the human explicitly approves |
+| 21 | `PreToolUse` | `dependency-risk-precheck.js` | Detect dependency add/update operations and inject advisory/security reminders |
+| 22 | `PreToolUse` | `secrets-path-blocker.js` | Block reads/writes targeting secrets, deploy keys, or restricted env files |
+| 23 | `PreToolUse` | `simplicity-gate-guard.js` | Warn when a proposed file path would introduce a new counted top-level directory beyond the configured limit |
+| 24 | `PreToolUse` | `spec-traceability-validator.js` | Validate traceability links (upstream refs, cross-references) when writing to spec files |
+| 25 | `PreToolUse` | `skill-context-injector.js` | Proactively suggest relevant installed skills based on file path and task context |
+| 26 | `PreToolUse` | `upstream-spec-guard.js` | Warn when writing to downstream specs/code without having read required upstream artifacts |
+
+## Installation
+
+The hooks are enabled for every user of this workspace — `.github/hooks/autonav.json` is committed. VS Code Copilot will pick it up automatically because `.github/hooks/*.json` is a default workspace hook location.
+
+**User-level opt-out:** set `JUMPSTART_HOOK_ALLOW_AGENT_EDITS=1` in your shell to let agents modify agent-governance files (Hook #3).
+
+**Requirements:** Node.js ≥ 14 (already required by this project's `package.json`).
+
+## Contract
+
+Each script follows the same shape:
+
+- Reads a JSON payload from **stdin** containing at minimum `{ sessionId, hookEventName, tool_name, tool_input, cwd }`.
+- Exits with one of:
+  - `0` — allow / no-op.
+  - `2` — **block** the tool call (VS Code convention); reason written to stderr.
+- Optionally emits a JSON envelope on **stdout** carrying `hookSpecificOutput.additionalContext` (injected into the agent's context) or `decision: "block"` with a `reason`.
+
+All scripts are **fail-safe**: an exception during hook execution will never crash the agent session — errors are swallowed and the hook exits 0.
+
+## Testing
+
+Hook logic is unit-tested in [`../../tests/test-hooks.test.js`](../../tests/test-hooks.test.js). Each script exposes a pure `handle(input, ctx)` function that takes the payload and a synthetic context `{ root, now }`, making the behaviour deterministic without mocking stdio.
+
+Run:
+
+```bash
+npm test -- tests/test-hooks.test.js
+```
+
+## State files touched
+
+| Path | Purpose |
+|---|---|
+| `.jumpstart/state/state.json` | `resume_context` updated by `pre-compact.js`; read by `session-start.js` |
+| `.jumpstart/state/hook-state.json` | Transient: recent tool calls, startup context, workspace metadata, tool counts, prompts, validations, blocked actions, and per-session edit logs |
+| `.jumpstart/correction-log.md` | Appended by `retry-escalation.js` when a retry loop is detected |
+| `specs/insights/{phase}-insights.md` | Appended by `capture-plan.js` with planned-step entries |
+| `specs/changelog-drafts/*.md` | Written by `draft-changelog.js` at session end |
+| `specs/qa-log.md` | Appended by `qa-log-capture.js` with significant user prompts |
+| `.jumpstart/spec-graph.json` | Refreshed by `spec-graph-updater.js` after relevant spec/code edits |
+| `.jumpstart/state/hook-state.json` → `traceability_checks` | Appended by `spec-traceability-validator.js` with per-write traceability audit results |
+| `.jumpstart/state/hook-state.json` → `skill_suggestions` | Appended by `skill-context-injector.js` with skill relevance matches |
+| `.jumpstart/state/hook-state.json` → `upstream_gaps` | Appended by `upstream-spec-guard.js` with missing upstream read warnings |
+| `.jumpstart/state/session-analytics/*.md` | Written by `session-analytics.js` with end-of-session observability summaries |
+
+All of these are existing AutoNav-managed paths — no new top-level directory is introduced (honours `simplicity_gate` in `config.yaml`).
+
+## Security note
+
+Per the VS Code hooks safety guidance, this directory **must not be writable by the agent itself**. Hook #3 (`block-agent-self-modification.js`) enforces this by blocking any edit targeting `.github/hooks/`. If you need to update a hook, edit it directly (outside the agent session) or temporarily set `JUMPSTART_HOOK_ALLOW_AGENT_EDITS=1`.

package/.github/hooks/ambiguity-detector.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Hook #18 — UserPromptSubmit: Ambiguity detector
+ *
+ * Flags vague prompts and injects a NEEDS CLARIFICATION reminder before the
+ * agent acts, reinforcing the framework's "Never Guess" rule.
+ */
+
+const {
+  runCli,
+  loadHookState,
+  saveHookState,
+  ensureSessionRecord,
+  extractSessionId,
+} = require('./lib/common');
+
+const FILE_REFERENCE_HINT_RE = /[`/]|\.md|\.js|\.ts|specs\/|src\//i;
+const SCOPE_HINT_RE = /\b(test|hook|spec|timeline|qa-log|manifest|graph|state|phase|session|file|path|readme)\b/i;
+
+function detectAmbiguity(prompt) {
+  const text = String(prompt || '').trim();
+  if (!text) return { ambiguous: false, reasons: [] };
+
+  const reasons = [];
+  if (text.length < 25) reasons.push('prompt is very short');
+  if (/\b(it|this|that|thing|stuff|issue)\b/i.test(text) && !FILE_REFERENCE_HINT_RE.test(text)) {
+    reasons.push('uses pronouns without a concrete target');
+  }
+  if (/\b(fix|update|change|do|handle|improve)\b/i.test(text) &&
+      !SCOPE_HINT_RE.test(text)) {
+    reasons.push('asks for action without naming a concrete artifact or outcome');
+  }
+  if (!/[?`/]|\.md|\.js|\.ts|phase|session|hook|spec|timeline/i.test(text) && text.split(/\s+/).length < 8) {
+    reasons.push('lacks scope or acceptance details');
+  }
+
+  return { ambiguous: reasons.length > 0, reasons };
+}
+
+function handle(input, ctx) {
+  const prompt = typeof input.prompt === 'string' ? input.prompt : '';
+  if (!prompt.trim()) return { exitCode: 0 };
+
+  const result = detectAmbiguity(prompt);
+  const sid = extractSessionId(input) || 'default';
+  const hookState = loadHookState(ctx.root);
+  const session = ensureSessionRecord(hookState, sid, ctx.now);
+  session.prompts.push({
+    at: ctx.now.toISOString(),
+    text: prompt.trim(),
+    ambiguous: result.ambiguous,
+    ambiguity_reasons: result.reasons,
+    source: 'ambiguity-detector',
+  });
+  saveHookState(ctx.root, hookState);
+
+  if (!result.ambiguous) return { exitCode: 0 };
+
+  const additionalContext =
+    `[NEEDS CLARIFICATION: ${result.reasons.join('; ')}] ` +
+    'The user prompt appears underspecified; clarify the target artifact, desired outcome, or acceptance criteria before acting.';
+
+  return {
+    exitCode: 0,
+    stdout: JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext,
+      },
+      additionalContext,
+    }) + '\n',
+  };
+}
+
+module.exports = {
+  handle,
+  detectAmbiguity,
+  FILE_REFERENCE_HINT_RE,
+  SCOPE_HINT_RE,
+};
+
+if (require.main === module) {
+  runCli(handle);
+}