get-shit-done-ios 1.1.0 → 1.3.0

package/README.md

@@ -9,7 +9,7 @@
 **Solves context rot — the quality degradation that happens as Claude fills its context window.**
 
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
-[![Based on GSD](https://img.shields.io/badge/Based_on-GSD_1.22.4-orange?style=for-the-badge)](https://github.com/glittercowboy/get-shit-done)
+[![Based on GSD](https://img.shields.io/badge/Based_on-GSD_1.25.1-orange?style=for-the-badge)](https://github.com/gsd-build/get-shit-done)
 
 ```bash
 npx get-shit-done-ios@latest
@@ -19,7 +19,7 @@ npx get-shit-done-ios@latest
 
 <br>
 
-> **Built on [Get Shit Done](https://github.com/glittercowboy/get-shit-done) by TÂCHES.**
+> **Built on [Get Shit Done](https://github.com/gsd-build/get-shit-done) by TÂCHES.**
 > This is an iOS-native fork — all agents, references, templates, and workflows
 > have been adapted for Swift, SwiftUI, and native iOS development patterns.
 
@@ -359,7 +359,7 @@ Then `/gsd:new-milestone` starts the next version — same flow as `new-project`
 Quick mode gives you GSD guarantees (atomic commits, state tracking) with a faster path:
 
 - **Same agents** — Planner + executor, same quality
-- **Skips optional steps** — No research, no plan checker, no verifier
+- **Skips optional steps** — No research, no plan checker, no verifier (use `--research` to add domain research)
 - **Separate tracking** — Lives in `.planning/quick/`, not phases
 
 Use for: bug fixes, small features, config changes, one-off tasks.
@@ -467,7 +467,7 @@ You're never locked in. The system adapts.
 | Command | What it does |
 |---------|--------------|
 | `/gsd:new-project [--auto]` | Full initialization: questions → research → requirements → roadmap |
-| `/gsd:discuss-phase [N] [--auto]` | Capture implementation decisions before planning |
+| `/gsd:discuss-phase [N] [--auto] [--batch]` | Capture implementation decisions before planning |
 | `/gsd:plan-phase [N] [--auto]` | Research + plan + verify for a phase |
 | `/gsd:execute-phase <N>` | Execute all plans in parallel waves, verify when complete |
 | `/gsd:verify-work [N]` | Manual user acceptance testing ¹ |
@@ -482,12 +482,13 @@ You're never locked in. The system adapts.
 | `/gsd:progress` | Where am I? What's next? |
 | `/gsd:help` | Show all commands and usage guide |
 | `/gsd:update` | Update GSD with changelog preview |
+| `/gsd:join-discord` | Join the GSD community Discord |
 
 ### Brownfield
 
 | Command | What it does |
 |---------|--------------|
-| `/gsd:map-codebase` | Analyze existing codebase before new-project |
+| `/gsd:map-codebase [area]` | Analyze existing codebase before new-project |
 
 ### Phase Management
 
@@ -511,13 +512,23 @@ You're never locked in. The system adapts.
 | Command | What it does |
 |---------|--------------|
 | `/gsd:settings` | Configure model profile and workflow agents |
-| `/gsd:set-profile <profile>` | Switch model profile (quality/balanced/budget) |
+| `/gsd:set-profile <profile>` | Switch model profile (quality/balanced/budget/inherit) |
+| `/gsd:do <text>` | Execute a task directly without interactive prompt |
+| `/gsd:note <text>` | Add a note to the current session state |
+| `/gsd:stats` | Show project statistics and metrics |
 | `/gsd:add-todo [desc]` | Capture idea for later |
 | `/gsd:check-todos` | List pending todos |
 | `/gsd:debug [desc]` | Systematic debugging with persistent state |
-| `/gsd:quick [--discuss] [--full]` | Execute ad-hoc task with GSD guarantees (`--discuss` for pre-planning context, `--full` adds plan-checking and verification) |
+| `/gsd:quick [--discuss] [--full] [--research]` | Execute ad-hoc task with GSD guarantees (`--discuss` for pre-planning context, `--full` adds plan-checking and verification, `--research` adds domain research) |
 | `/gsd:health [--repair]` | Validate `.planning/` directory integrity, auto-repair with `--repair` |
 
+### UI Design
+
+| Command | What it does |
+|---------|--------------|
+| `/gsd:ui-phase [N]` | Create SwiftUI design contract (color assets, typography tokens, accessibility) before planning |
+| `/gsd:ui-review [N]` | Retroactive 6-pillar visual audit of implemented SwiftUI views |
+
 <sup>¹ Contributed by reddit user OracleGreyBeard</sup>
 
 ---
@@ -531,7 +542,7 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd:n
 | Setting | Options | Default | What it controls |
 |---------|---------|---------|------------------|
 | `mode` | `yolo`, `interactive` | `interactive` | Auto-approve vs confirm at each step |
-| `granularity` | `coarse`, `standard`, `fine` | `standard` | Planning thoroughness (phases × plans) |
+| `granularity` | `coarse`, `standard`, `fine` | `standard` | Phase granularity — how finely scope is sliced |
 
 ### Model Profiles
 
@@ -542,6 +553,9 @@ Control which Claude model each agent uses. Balance quality vs token spend.
 | `quality` | Opus | Opus | Sonnet |
 | `balanced` (default) | Opus | Sonnet | Sonnet |
 | `budget` | Sonnet | Sonnet | Haiku |
+| `inherit` | Inherit | Inherit | Inherit |
+
+Use `inherit` to follow the current session model selection.
 
 Switch profiles:
 ```

package/agents/gsd-codebase-mapper.md

@@ -3,8 +3,6 @@ name: gsd-codebase-mapper
 description: Explores codebase and writes structured analysis documents. Spawned by map-codebase with a focus area (tech, arch, quality, concerns). Writes documents directly to reduce orchestrator context load.
 tools: Read, Bash, Grep, Glob, Write
 color: cyan
-skills:
-  - gsd-mapper-workflow
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"

package/agents/gsd-debugger.md

@@ -3,8 +3,6 @@ name: gsd-debugger
 description: Investigates iOS/Swift/SwiftUI bugs using scientific method, manages debug sessions, handles checkpoints. Spawned by /gsd:debug orchestrator.
 tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
 color: orange
-skills:
-  - gsd-debugger-workflow
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"
@@ -887,6 +885,48 @@ Can I observe the behavior directly?
 
 </research_vs_reasoning>
 
+<knowledge_base_protocol>
+
+## Purpose
+
+The knowledge base is a persistent, append-only record of resolved debug sessions. It lets future debugging sessions skip straight to high-probability hypotheses when symptoms match a known pattern.
+
+## File Location
+
+```
+.planning/debug/knowledge-base.md
+```
+
+## Entry Format
+
+Each resolved session appends one entry:
+
+```markdown
+## {slug} — {one-line description}
+- **Date:** {ISO date}
+- **Error patterns:** {comma-separated keywords extracted from symptoms.errors and symptoms.actual}
+- **Root cause:** {from Resolution.root_cause}
+- **Fix:** {from Resolution.fix}
+- **Files changed:** {from Resolution.files_changed}
+---
+```
+
+## When to Read
+
+At the **start of `investigation_loop` Phase 0**, before any file reading or hypothesis formation.
+
+## When to Write
+
+At the **end of `archive_session`**, after the session file is moved to `resolved/` and the fix is confirmed by the user.
+
+## Matching Logic
+
+Matching is keyword overlap, not semantic similarity. Extract nouns and error substrings from `Symptoms.errors` and `Symptoms.actual`. Scan each knowledge base entry's `Error patterns` field for overlapping tokens (case-insensitive, 2+ word overlap = candidate match).
+
+**Important:** A match is a **hypothesis candidate**, not a confirmed diagnosis. Surface it in Current Focus and test it first — but do not skip other hypotheses or assume correctness.
+
+</knowledge_base_protocol>
+
 <debug_file_protocol>
 
 ## File Location
@@ -1037,6 +1077,16 @@ Gather symptoms through questioning. Update file after EACH answer.
 <step name="investigation_loop">
 **Autonomous investigation. Update file continuously.**
 
+**Phase 0: Check knowledge base**
+- If `.planning/debug/knowledge-base.md` exists, read it
+- Extract keywords from `Symptoms.errors` and `Symptoms.actual` (nouns, error substrings, identifiers)
+- Scan knowledge base entries for 2+ keyword overlap (case-insensitive)
+- If match found:
+  - Note in Current Focus: `known_pattern_candidate: "{matched slug} — {description}"`
+  - Add to Evidence: `found: Knowledge base match on [{keywords}] → Root cause was: {root_cause}. Fix was: {fix}.`
+  - Test this hypothesis FIRST in Phase 2 — but treat it as one hypothesis, not a certainty
+- If no match: proceed normally
+
 **Phase 1: Initial evidence gathering**
 - Update Current Focus with "gathering initial evidence"
 - If errors exist, search codebase for error text
@@ -1210,6 +1260,37 @@ Then commit planning docs via CLI (respects `commit_docs` config automatically):
 node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: resolve debug {slug}" --files .planning/debug/resolved/{slug}.md
 ```
 
+**Append to knowledge base:**
+
+Read `.planning/debug/resolved/{slug}.md` to extract final `Resolution` values. Then append to `.planning/debug/knowledge-base.md` (create file with header if it doesn't exist):
+
+If creating for the first time, write this header first:
+```markdown
+# GSD Debug Knowledge Base
+
+Resolved debug sessions. Used by `gsd-debugger` to surface known-pattern hypotheses at the start of new investigations.
+
+---
+
+```
+
+Then append the entry:
+```markdown
+## {slug} — {one-line description of the bug}
+- **Date:** {ISO date}
+- **Error patterns:** {comma-separated keywords from Symptoms.errors + Symptoms.actual}
+- **Root cause:** {Resolution.root_cause}
+- **Fix:** {Resolution.fix}
+- **Files changed:** {Resolution.files_changed joined as comma list}
+---
+
+```
+
+Commit the knowledge base update alongside the resolved session:
+```bash
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: update debug knowledge base with {slug}" --files .planning/debug/knowledge-base.md
+```
+
 Report completion and offer next steps.
 </step>
 

package/agents/gsd-executor.md

@@ -3,8 +3,6 @@ name: gsd-executor
 description: Executes GSD plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by execute-phase orchestrator or execute-plan command.
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: yellow
-skills:
-  - gsd-executor-workflow
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"
@@ -14,9 +12,7 @@ skills:
 ---
 
 **iOS References:**
-- @~/.claude/get-shit-done/references/ios-swift-guidelines.md — Swift coding standards, SwiftUI patterns, architecture
-- @~/.claude/get-shit-done/references/ios-frameworks.md — Framework preference hierarchy (native > third-party)
-- @~/.claude/get-shit-done/references/ios-testing.md — Testing patterns (Swift Testing primary, XCTest for UI)
+- @~/.claude/get-shit-done/references/ios-conventions.md — Mandatory enforcement rules (anti-patterns, validation checklist, localization, accessibility minimums)
 
 <role>
 You are a GSD plan executor **for iOS native projects (Swift / SwiftUI)**. You execute PLAN.md files atomically, creating per-task commits, handling deviations automatically, pausing at checkpoints, and producing SUMMARY.md files.
@@ -36,14 +32,21 @@ Before executing, discover project context:
 
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
-**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+**iOS skills (built-in):** Read `~/.claude/get-shit-done/skills/INDEX.md` to identify relevant skills for the current task.
+1. Read INDEX.md — maps task keywords to skill domains
+2. Read `SKILL.md` for 1-3 relevant skills (lightweight routers, ~5KB each)
+3. Follow SKILL.md routing to load specific `references/*.md` as needed
+4. If skill has `workflows/`, follow the applicable workflow for the task type
+5. Do NOT load all skills — load only those relevant to the current task
+
+**Project skills (override):** Check `.claude/skills/` or `.agents/skills/` if either exists:
 1. List available skills (subdirectories)
-2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
-3. Load specific `rules/*.md` files as needed during implementation
-4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
-5. Follow skill rules relevant to your current task
+2. Read `SKILL.md` for each skill
+3. Load specific `references/*.md` or `rules/*.md` files as needed
+4. Project-level skills override built-in skills for the same domain
+5. Do NOT load full `AGENTS.md` files (100KB+ context cost)
 
-This ensures project-specific patterns, conventions, and best practices are applied during execution.
+This ensures both built-in iOS intelligence and project-specific patterns are applied.
 </project_context>
 
 ## iOS Validation Ladder
@@ -198,7 +201,7 @@ For each task:
 - Service/repository returning hardcoded data or empty `async` functions
 - `fatalError("Not implemented")` or `TODO:` / `FIXME:` markers
 - `print("debug")` — leftover debug statements
-- `Text("Settings")` or any `Text("literal string")` — hardcoded user-facing strings not using `String(localized:)` or `LocalizedStringKey` (see ios-swift-guidelines.md § Localization)
+- `Text("Settings")` or any `Text("literal string")` — hardcoded user-facing strings not using `String(localized:)` or `LocalizedStringKey` (see ios-conventions.md § Localization Enforcement)
 
 If stubs are found, implement real functionality before proceeding.
 </step>
@@ -226,7 +229,7 @@ No user permission needed for Rules 1-3.
 
 **Trigger:** Code missing essential features for correctness, security, or basic operation
 
-**Examples:** Missing error handling, no input validation, missing nil checks, missing accessibility labels/traits on interactive elements, hardcoded user-facing strings without `String(localized:)` (localization is mandatory per ios-swift-guidelines.md), missing privacy usage descriptions in Info.plist (NSCameraUsageDescription, etc.), no Keychain usage for sensitive data (storing secrets in UserDefaults), missing `@MainActor` annotations on ViewModels, no error handling in async calls (missing do/catch or Task error handling), no loading/error states in views, missing permission checks before accessing protected resources (camera, location, photos), no rate limiting on network calls, no error logging
+**Examples:** Missing error handling, no input validation, missing nil checks, missing accessibility labels/traits on interactive elements, hardcoded user-facing strings without `String(localized:)` (localization is mandatory per ios-conventions.md), missing privacy usage descriptions in Info.plist (NSCameraUsageDescription, etc.), no Keychain usage for sensitive data (storing secrets in UserDefaults), missing `@MainActor` annotations on ViewModels, no error handling in async calls (missing do/catch or Task error handling), no loading/error states in views, missing permission checks before accessing protected resources (camera, location, photos), no rate limiting on network calls, no error logging
 
 **Critical = required for correct/secure/performant operation.** These aren't "features" — they're correctness requirements.
 
@@ -459,6 +462,8 @@ git commit -m "{type}({phase}-{plan}): {concise task description}
 ```
 
 **5. Record hash:** `TASK_COMMIT=$(git rev-parse --short HEAD)` — track for SUMMARY.
+
+**6. Check for untracked files:** After running scripts or tools, check `git status --short | grep '^??'`. For any new untracked files: commit if intentional, add to `.gitignore` if generated/runtime output. Never leave generated files untracked.
 </task_commit_protocol>
 
 <summary_creation>

package/agents/gsd-integration-checker.md

@@ -3,8 +3,6 @@ name: gsd-integration-checker
 description: Verifies cross-phase integration and E2E flows. Checks that phases connect properly and user workflows complete end-to-end.
 tools: Read, Bash, Grep, Glob
 color: blue
-skills:
-  - gsd-integration-workflow
 ---
 
 <role>

package/agents/gsd-nyquist-auditor.md

@@ -9,8 +9,6 @@ tools:
   - Glob
   - Grep
 color: "#8B5CF6"
-skills:
-  - gsd-nyquist-auditor-workflow
 ---
 
 <role>

package/agents/gsd-phase-researcher.md

@@ -3,8 +3,6 @@ name: gsd-phase-researcher
 description: Researches how to implement a phase before planning for iOS native apps (Swift/SwiftUI). Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd:plan-phase orchestrator.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
 color: cyan
-skills:
-  - gsd-researcher-workflow
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"
@@ -34,14 +32,21 @@ Before researching, discover project context:
 
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
-**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+**iOS skills (built-in):** Read `~/.claude/get-shit-done/skills/INDEX.md` to identify relevant skills for the current task.
+1. Read INDEX.md — maps task keywords to skill domains
+2. Read `SKILL.md` for 1-3 relevant skills (lightweight routers, ~5KB each)
+3. Follow SKILL.md routing to load specific `references/*.md` as needed
+4. If skill has `workflows/`, follow the applicable workflow for the task type
+5. Do NOT load all skills — load only those relevant to the current task
+
+**Project skills (override):** Check `.claude/skills/` or `.agents/skills/` if either exists:
 1. List available skills (subdirectories)
-2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
-3. Load specific `rules/*.md` files as needed during implementation
-4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
-5. Follow skill rules relevant to your current task
+2. Read `SKILL.md` for each skill
+3. Load specific `references/*.md` or `rules/*.md` files as needed
+4. Project-level skills override built-in skills for the same domain
+5. Do NOT load full `AGENTS.md` files (100KB+ context cost)
 
-This ensures project-specific patterns, conventions, and best practices are applied during research.
+This ensures both built-in iOS intelligence and project-specific patterns are applied during research.
 </project_context>
 
 <upstream_input>
@@ -113,17 +118,17 @@ When researching "best library for X": find what the ecosystem actually uses, do
 
 | Priority | Tool | Use For | Trust Level |
 |----------|------|---------|-------------|
-| 0th | GSD References | Framework preferences, coding conventions, testing patterns — read `ios-swift-guidelines.md`, `ios-frameworks.md`, and `ios-testing.md` BEFORE external research to ensure consistency | AUTHORITATIVE |
+| 0th | GSD Skills | iOS built-in skills — read `skills/INDEX.md` to identify relevant skills, then load SKILL.md + references as needed BEFORE external research | AUTHORITATIVE |
 | 1st | Apple Developer Docs | Official framework APIs, HIG, App Store Review Guidelines | HIGH |
 | 2nd | Context7 | Third-party SPM library APIs, features, configuration, versions | HIGH |
 | 3rd | WebFetch | Official docs/READMEs not in Context7, WWDC session notes, changelogs | HIGH-MEDIUM |
 | 4th | WebSearch | Ecosystem discovery, community patterns, pitfalls | Needs verification |
 
-**GSD References flow:**
-1. Read `get-shit-done/references/ios-frameworks.md` to check if the phase domain has a recommended native framework (preference levels: primary/secondary/legacy/conditional)
-2. Read `get-shit-done/references/ios-testing.md` to identify the correct testing approach for the phase (Swift Testing for unit, XCUITest for UI)
-3. Read `get-shit-done/references/ios-swift-guidelines.md` for coding conventions and patterns the planner must follow
-4. Only THEN proceed to external sources for details not covered by GSD references
+**GSD Skills flow:**
+1. Read `get-shit-done/skills/INDEX.md` to identify 1-3 relevant skills for the phase domain
+2. Read each relevant `SKILL.md` (~5KB) and follow routing to load specific `references/*.md`
+3. Read `get-shit-done/references/ios-conventions.md` for mandatory enforcement rules (anti-patterns, localization, accessibility)
+4. Only THEN proceed to external sources for details not covered by built-in skills
 
 **Apple Docs flow:**
 1. WebFetch `https://developer.apple.com/documentation/[framework]` for official API reference
@@ -283,7 +288,7 @@ Priority: Apple Developer Docs > WWDC Sessions > Context7 (3rd-party libs) > Off
 |------------|-----------|----------|
 | [standard] | [alternative] | [when alternative makes sense] |
 
-**Native-first principle:** Always prefer Apple-native frameworks over third-party. Consult `get-shit-done/references/ios-frameworks.md` for the authoritative preference hierarchy (primary/secondary/legacy/conditional) before recommending any third-party SPM package.
+**Native-first principle:** Always prefer Apple-native frameworks over third-party. Consult `get-shit-done/skills/app-architecture/references/framework-selection.md` for the authoritative preference hierarchy (primary/secondary/legacy/conditional) before recommending any third-party SPM package.
 
 **Dependencies (Package.swift / Xcode SPM):**
 \`\`\`swift
@@ -293,6 +298,12 @@ dependencies: [
 ]
 \`\`\`
 
+**Version verification:** Before writing the Standard Stack table, verify each recommended package version is current:
+\`\`\`bash
+npm view [package] version
+\`\`\`
+Document the verified version and publish date. Training data versions may be months stale — always confirm against the registry.
+
 ## Architecture Patterns
 
 ### Recommended Project Structure
@@ -633,11 +644,11 @@ Quality indicators:
 
 ## iOS Development References
 
-Always consult these GSD references for iOS-specific guidance before external research:
+Always consult GSD built-in skills for iOS-specific guidance before external research:
 
-- `get-shit-done/references/ios-swift-guidelines.md` — Swift coding standards, SwiftUI patterns, architecture, and best practices
-- `get-shit-done/references/ios-frameworks.md` — Apple framework preference hierarchy (native > third-party), framework recommendations by domain
-- `get-shit-done/references/ios-testing.md` — Testing patterns (Swift Testing primary, XCTest for UI), TDD workflow, what to test vs skip
+- `get-shit-done/skills/INDEX.md` — Keyword→skill routing table (identify 1-3 relevant skills for the current research domain)
+- `get-shit-done/references/ios-conventions.md` — Mandatory enforcement rules (anti-patterns, validation checklist, localization, accessibility)
+- Load relevant `SKILL.md` + `references/*.md` as needed for the specific domain (app-architecture, swiftui, swift-concurrency, swiftdata, networking, etc.)
 
 External authoritative sources:
 

package/agents/gsd-plan-checker.md

@@ -3,8 +3,6 @@ name: gsd-plan-checker
 description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /gsd:plan-phase orchestrator.
 tools: Read, Bash, Glob, Grep
 color: green
-skills:
-  - gsd-plan-checker-workflow
 ---
 
 <role>
@@ -33,14 +31,21 @@ Before verifying, discover project context:
 
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
-**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+**iOS skills (built-in):** Read `~/.claude/get-shit-done/skills/INDEX.md` to identify relevant skills for the current task.
+1. Read INDEX.md — maps task keywords to skill domains
+2. Read `SKILL.md` for 1-3 relevant skills (lightweight routers, ~5KB each)
+3. Follow SKILL.md routing to load specific `references/*.md` as needed
+4. If skill has `workflows/`, follow the applicable workflow for the task type
+5. Do NOT load all skills — load only those relevant to the current task
+
+**Project skills (override):** Check `.claude/skills/` or `.agents/skills/` if either exists:
 1. List available skills (subdirectories)
-2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
-3. Load specific `rules/*.md` files as needed during implementation
-4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
-5. Follow skill rules relevant to your current task
+2. Read `SKILL.md` for each skill
+3. Load specific `references/*.md` or `rules/*.md` files as needed
+4. Project-level skills override built-in skills for the same domain
+5. Do NOT load full `AGENTS.md` files (100KB+ context cost)
 
-This ensures project-specific patterns, conventions, and best practices are applied during verification.
+This ensures both built-in iOS intelligence and project-specific patterns are applied during verification.
 </project_context>
 
 <upstream_input>

package/agents/gsd-planner.md

@@ -3,8 +3,6 @@ name: gsd-planner
 description: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. Spawned by /gsd:plan-phase orchestrator.
 tools: Read, Write, Bash, Glob, Grep, WebFetch, mcp__context7__*
 color: green
-skills:
-  - gsd-planner-workflow
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"
@@ -41,14 +39,21 @@ Before planning, discover project context:
 
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
-**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
+**iOS skills (built-in):** Read `~/.claude/get-shit-done/skills/INDEX.md` to identify relevant skills for the current task.
+1. Read INDEX.md — maps task keywords to skill domains
+2. Read `SKILL.md` for 1-3 relevant skills (lightweight routers, ~5KB each)
+3. Follow SKILL.md routing to load specific `references/*.md` as needed
+4. If skill has `workflows/`, follow the applicable workflow for the task type
+5. Do NOT load all skills — load only those relevant to the current task
+
+**Project skills (override):** Check `.claude/skills/` or `.agents/skills/` if either exists:
 1. List available skills (subdirectories)
-2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
-3. Load specific `rules/*.md` files as needed during implementation
-4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
-5. Follow skill rules relevant to your current task
+2. Read `SKILL.md` for each skill
+3. Load specific `references/*.md` or `rules/*.md` files as needed
+4. Project-level skills override built-in skills for the same domain
+5. Do NOT load full `AGENTS.md` files (100KB+ context cost)
 
-This ensures project-specific patterns, conventions, and best practices are applied during planning.
+This ensures both built-in iOS intelligence and project-specific patterns are applied.
 </project_context>
 
 <context_fidelity>
@@ -218,7 +223,7 @@ Every task that creates or modifies a SwiftUI View with user-facing text MUST in
 
 If a task's `<action>` creates a View with user-facing text and does NOT use `String(localized:)` or `LocalizedStringKey`, the plan is incomplete. Add it.
 
-See `ios-swift-guidelines.md` § Localization for mandatory patterns.
+See `ios-conventions.md` § Localization Enforcement for mandatory patterns.
 
 ## Task Sizing
 
@@ -485,9 +490,7 @@ Output: [Artifacts created]
 <execution_context>
 @~/.claude/get-shit-done/workflows/execute-plan.md
 @~/.claude/get-shit-done/templates/summary.md
-@~/.claude/get-shit-done/references/ios-swift-guidelines.md
-@~/.claude/get-shit-done/references/ios-frameworks.md
-@~/.claude/get-shit-done/references/ios-testing.md
+@~/.claude/get-shit-done/references/ios-conventions.md
 </execution_context>
 
 <context>
@@ -552,7 +555,7 @@ After determining `files_modified`, extract the key protocols/types/exports from
 
 ```bash
 # Extract type definitions, protocols, and public APIs from relevant files
-grep -n "protocol\|struct\|class\|enum\|func\|public" {relevant_source_files} 2>/dev/null | head -50
+grep -n "protocol\\|struct\\|class\\|enum\\|func\\|public" {relevant_source_files} 2>/dev/null | head -50
 ```
 
 Embed these in the plan's `<context>` section as an `<interfaces>` block:

package/agents/gsd-project-researcher.md

@@ -3,8 +3,6 @@ name: gsd-project-researcher
 description: Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /gsd:new-project or /gsd:new-milestone orchestrators.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
 color: cyan
-skills:
-  - gsd-researcher-workflow
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"
@@ -16,7 +14,7 @@ skills:
 <role>
 You are a GSD project researcher spawned by `/gsd:new-project` or `/gsd:new-milestone` (Phase 6: Research), specialized in **iOS native development** with Swift and SwiftUI.
 
-Answer "What does this domain ecosystem look like for iOS?" Write research files in `.planning/research/` that inform roadmap creation. Always prioritize Apple-native frameworks and patterns. Consult `get-shit-done/references/ios-swift-guidelines.md` and `get-shit-done/references/ios-frameworks.md` as authoritative references.
+Answer "What does this domain ecosystem look like for iOS?" Write research files in `.planning/research/` that inform roadmap creation. Always prioritize Apple-native frameworks and patterns. Consult `get-shit-done/skills/INDEX.md` to discover relevant built-in skills and `get-shit-done/references/ios-conventions.md` for mandatory enforcement rules.
 
 **CRITICAL: Mandatory Initial Read**
 If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
@@ -98,7 +96,7 @@ For Apple frameworks, APIs, platform capabilities, and Human Interface Guideline
 - **Swift Documentation:** `https://docs.swift.org/swift-book/`
 - **WWDC Sessions:** `https://developer.apple.com/videos/`
 
-Use WebFetch with exact Apple URLs. Always check iOS version availability for APIs. Prefer Apple-native frameworks over third-party (see `get-shit-done/references/ios-frameworks.md`).
+Use WebFetch with exact Apple URLs. Always check iOS version availability for APIs. Prefer Apple-native frameworks over third-party (see `get-shit-done/skills/app-architecture/references/framework-selection.md`).
 
 ### 3. Official Docs via WebFetch — Third-Party Sources
 For SPM packages not in Context7, changelogs, release notes, official announcements.
@@ -296,7 +294,7 @@ Based on research, suggested phase structure:
 |---------|---------|---------|-------------|
 | [package] | [ver] | [what] | [conditions] |
 
-**Guideline:** Prefer Apple-native frameworks over third-party. See `get-shit-done/references/ios-frameworks.md` for framework preference levels.
+**Guideline:** Prefer Apple-native frameworks over third-party. See `get-shit-done/skills/app-architecture/references/framework-selection.md` for framework preference levels.
 
 ## Alternatives Considered
 
@@ -472,7 +470,7 @@ struct ProfileView: View {
 }
 \`\`\`
 
-**When to use which:** Use `@State` for ViewModels created locally with no shared dependencies. Use `@Environment` when the ViewModel has dependencies that should be injectable (preferred for testability — see `ios-swift-guidelines.md`).
+**When to use which:** Use `@State` for ViewModels created locally with no shared dependencies. Use `@Environment` when the ViewModel has dependencies that should be injectable (preferred for testability — see `ios-conventions.md`).
 
 ## Anti-Patterns to Avoid
 
@@ -499,7 +497,7 @@ struct ProfileView: View {
 ## Sources
 
 - [Architecture references, Apple documentation, HIG]
-- See: `get-shit-done/references/ios-swift-guidelines.md`
+- See: `get-shit-done/references/ios-conventions.md` and `get-shit-done/skills/app-architecture/`
 ```
 
 ## PITFALLS.md
@@ -761,10 +759,10 @@ Research is complete when:
 - [ ] Files written (DO NOT commit — orchestrator handles this)
 - [ ] Structured return provided to orchestrator
 
-**Quality:** Comprehensive not shallow. Opinionated not wishy-washy. Verified not assumed. Honest about gaps. Actionable for roadmap. Current (year in searches). Native-first (prefer Apple frameworks per ios-frameworks.md).
+**Quality:** Comprehensive not shallow. Opinionated not wishy-washy. Verified not assumed. Honest about gaps. Actionable for roadmap. Current (year in searches). Native-first (prefer Apple frameworks per skills/app-architecture framework-selection.md).
 
 **iOS-Specific References:**
-- `get-shit-done/references/ios-swift-guidelines.md` — Swift coding conventions and patterns
-- `get-shit-done/references/ios-frameworks.md` — Apple framework preference levels and recommendations
+- `get-shit-done/skills/INDEX.md` — Keyword→skill routing for all iOS domains
+- `get-shit-done/references/ios-conventions.md` — Mandatory enforcement rules (anti-patterns, localization, accessibility)
 
 </success_criteria>

package/agents/gsd-research-synthesizer.md

@@ -3,8 +3,6 @@ name: gsd-research-synthesizer
 description: Synthesizes research outputs from parallel researcher agents into SUMMARY.md. Spawned by /gsd:new-project after 4 researcher agents complete.
 tools: Read, Write, Bash
 color: purple
-skills:
-  - gsd-synthesizer-workflow
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"

package/agents/gsd-roadmapper.md

@@ -3,8 +3,6 @@ name: gsd-roadmapper
 description: Creates iOS project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation. Spawned by /gsd:new-project orchestrator. Specialized for native iOS development with Swift/SwiftUI.
 tools: Read, Write, Bash, Glob, Grep
 color: purple
-skills:
-  - gsd-roadmapper-workflow
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"