Add reference index and tighten architecture routing flow (#27)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

CONTRIBUTING.md

@@ -2,13 +2,14 @@
 
 Thanks for contributing to `swift-architecture-skill`.
 
-This repository is documentation-first: it defines a routing skill (`SKILL.md`) and architecture playbooks (`references/*.md`) used by coding agents.
+This repository is documentation-first: it defines a routing skill (`SKILL.md`), a references index (`references/_index.md`), and architecture playbooks (`references/*.md`) used by coding agents.
 
 ## Before You Start
 
 1. Read `swift-architecture-skill/SKILL.md` to understand how architecture selection and routing works.
-2. Review `swift-architecture-skill/references/selection-guide.md` to see current decision criteria.
-3. Skim one or two existing playbooks (for example `mvvm.md`, `tca.md`) to match structure and tone.
+2. Review `swift-architecture-skill/references/_index.md` to see the current navigation and routing model.
+3. Review `swift-architecture-skill/references/selection-guide.md` to see current decision criteria.
+4. Skim one or two existing playbooks (for example `mvvm.md`, `tca.md`) to match structure and tone.
 
 ## Repository Structure
 
@@ -17,6 +18,7 @@ swift-architecture-skill/
   SKILL.md
   agents/openai.yaml
   references/
+    _index.md
     selection-guide.md
     mvvm.md
     mvi.md
@@ -37,7 +39,7 @@ swift-architecture-skill/
 
 ## Add or Update a Playbook
 
-When editing any file in `swift-architecture-skill/references/`, keep this structure:
+When editing any architecture playbook in `swift-architecture-skill/references/`, keep this structure:
 
 1. Overview and when to use it
 2. Core concepts and principles
@@ -58,13 +60,16 @@ Content expectations:
 1. Create a new playbook in `swift-architecture-skill/references/<architecture>.md`.
 2. Follow the required playbook structure listed above.
 3. Update `swift-architecture-skill/SKILL.md`:
-   - Add the architecture to the mapping in **Step 2: Select the Architecture**
+   - Add the architecture to the mapping in **Architecture Router**
    - Mention it in any architecture list that should include it
-4. Update `swift-architecture-skill/references/selection-guide.md`:
+4. Update `swift-architecture-skill/references/_index.md`:
+   - Add a one-line description
+   - Add or adjust any problem-router entries
+5. Update `swift-architecture-skill/references/selection-guide.md`:
    - Add decision criteria signals
    - Add it to the decision matrix/flow if applicable
    - Document valid combinations with other patterns when relevant
-5. If needed, update `README.md` so supported architectures and project structure stay accurate.
+6. If needed, update `README.md` so supported architectures and project structure stay accurate.
 
 ## Swift Example Conventions
 

README.md

@@ -12,6 +12,7 @@ Supports the [Agent Skills open format](https://agentskills.io/home).
 
 - **Routes to the right architecture**: Describe your feature and the skill selects the best fit based on UI stack, state complexity, and existing conventions. Name a pattern yourself and it validates the fit before you commit.
 - **Scoped playbooks**: Each architecture has its own reference — code patterns, anti-pattern fixes, testing strategy, and a PR checklist. Guidance never bleeds across patterns.
+- **Reference index**: A dedicated `_index.md` gives agents a fast navigation hub and problem router before diving into a playbook.
 - **SwiftUI and UIKit**: Every playbook covers both stacks with modern async/await and actor-based concurrency patterns throughout.
 
 ## Supported Architectures
@@ -19,6 +20,7 @@ Supports the [Agent Skills open format](https://agentskills.io/home).
 MVP · MVVM · MVI · TCA · Clean Architecture · VIPER · Coordinator · Reactive
 
 Each has a dedicated [playbook](swift-architecture-skill/references/) with overview, patterns, anti-pattern fixes, testing strategy, and PR checklist.
+Start with the [reference index](swift-architecture-skill/references/_index.md) for quick routing, or use the [selection guide](swift-architecture-skill/references/selection-guide.md) when the architecture is still undecided.
 
 ## Quick Start
 
@@ -62,6 +64,7 @@ period where both coexist?
 swift-architecture-skill/
   SKILL.md                       # Routing logic and output requirements
   references/
+    _index.md                    # Navigation hub and problem router
     selection-guide.md           # Decision framework across architectures
     mvp.md                       # MVP playbook
     mvvm.md                      # MVVM playbook

swift-architecture-skill/SKILL.md

@@ -10,17 +10,51 @@ license: MIT
 
 Use this skill to pick the best Swift architecture playbook for SwiftUI/UIKit codebases and apply it to the user’s task.
 
-## Workflow
+For quick navigation across playbooks, use `references/_index.md`.
 
-### Step 1: Analyze the Request Context
+## Fast Path
 
-Before selecting an architecture, capture:
+Before selecting an architecture, always capture:
 - task type (new feature, refactor, PR review, debugging)
 - UI stack (SwiftUI, UIKit, or mixed)
 - scope (single screen, multi-screen, app-wide)
+- state and effect complexity
+- team familiarity and dependency tolerance
 - existing conventions to preserve
 
-### Step 2: Select the Architecture
+Then:
+- if the user explicitly names an architecture, treat it as the initial candidate and run a fit check first
+- if no architecture is named, load `references/selection-guide.md` and infer the best fit from the stated constraints
+- choose **Quick Recommendation Mode** for single-feature guidance with clear constraints
+- choose **Deep Refactor Mode** for migrations, mixed architectures, or module boundary changes
+
+## Quick Recommendation Mode
+
+Use this mode when:
+- the scope is one feature or screen
+- constraints are clear enough to recommend one primary pattern
+- the user mainly needs a recommendation, scaffold, or review checklist
+
+Deliver:
+- fit result (`fit` or `mismatch`)
+- 1-2 reasons grounded in the request
+- the selected reference file
+- concrete structure, state, dependency, async, and testing guidance scoped to the feature
+
+## Deep Refactor Mode
+
+Use this mode when:
+- the request spans multiple modules or screens
+- the codebase already mixes architectures
+- the user is migrating from one pattern to another
+
+Deliver:
+- current-state assessment
+- target architecture recommendation with fit or mismatch result
+- incremental migration path with boundary changes called out
+- risks, trade-offs, and verification points for the transition
+
+## Architecture Router
 
 If the user explicitly names an architecture, treat it as the initial candidate and run a fit check before committing:
 - validate against UI stack fit (SwiftUI/UIKit/mixed), state complexity, effect orchestration needs, team familiarity, and existing codebase conventions
@@ -28,8 +62,6 @@ If the user explicitly names an architecture, treat it as the initial candidate
 - if it mismatches key constraints, explicitly explain the mismatch and recommend the closest-fit alternative from `references/selection-guide.md`
 - if the user still insists on a mismatched architecture, proceed with a risk-mitigated plan and state the risks up front
 
-When no architecture is named, load `references/selection-guide.md` and infer the best fit from stated constraints (state complexity, team familiarity, testing goals, effect orchestration needs, and framework preferences). Explain the recommendation briefly.
-
 Architecture reference mapping:
 - MVVM → `references/mvvm.md`
 - MVI → `references/mvi.md`
@@ -40,14 +72,22 @@ Architecture reference mapping:
 - MVP → `references/mvp.md`
 - Coordinator → `references/coordinator.md`
 
-### Step 3: Analyze Existing Codebase (When Applicable)
+## Analyze Existing Codebase (When Applicable)
 
 When code already exists:
 - detect current architecture and DI style
 - note concurrency model (async/await, Combine, GCD, mixed)
 - align recommendations to local conventions
 
-### Step 4: Produce Concrete Deliverables
+## Guardrails
+
+- Do not force an architecture switch for a small feature when the current local pattern is still a reasonable fit.
+- Preserve existing conventions unless the mismatch is severe enough to justify change.
+- Do not introduce new framework dependencies such as TCA unless the user explicitly accepts that trade-off or the codebase already uses them.
+- Prefer the smallest architecture change that solves the request cleanly.
+- Keep guidance architecture-specific; do not blend playbooks unless the boundary between patterns is explicit.
+
+## Produce Concrete Deliverables
 
 Read the selected architecture reference and convert its guidance into deliverables tailored to the user's request:
 
@@ -58,10 +98,6 @@ Read the selected architecture reference and convert its guidance into deliverab
 - **Migration path** (for refactors): incremental steps to move from current to target architecture
 - **UI stack adaptation**: where SwiftUI and UIKit guidance should differ for the chosen architecture
 
-### Step 5: Validate with Checklist
-
-End with the architecture-specific PR review checklist from the reference file, adapted to the user's feature.
-
 ## Output Requirements
 
 - Keep recommendations scoped to the requested feature or review task.
@@ -74,3 +110,12 @@ End with the architecture-specific PR review checklist from the reference file,
 - Treat reference snippets as illustrative by default; add full compile scaffolding only if the user asks for runnable code.
 - Ask only minimum blocking questions; otherwise proceed with explicit assumptions stated up front.
 - When reviewing PRs, use the architecture-specific checklist and call out specific violations with line-level fixes.
+
+## Verification Checklist
+
+Before finalizing:
+
+1. confirm the selected pattern matches the user’s constraints and stack
+2. confirm dependency injection, state ownership, effects, and testing strategy are covered
+3. call out migration risk explicitly when recommending an architecture change
+4. end with the selected architecture’s PR review checklist adapted to the user’s feature

swift-architecture-skill/references/_index.md

@@ -0,0 +1,29 @@
+# Reference Index
+
+Quick navigation for the Swift Architecture skill.
+
+## Core Routing
+
+| File | Use it for |
+|---|---|
+| `selection-guide.md` | choosing the best-fit architecture from user constraints |
+| `mvvm.md` | low-to-medium complexity features with lightweight state binding |
+| `mvi.md` | reducer-style state machines without adding a framework dependency |
+| `tca.md` | complex, highly composable features with strict effect orchestration |
+| `clean-architecture.md` | strict layer boundaries and replaceable infrastructure |
+| `viper.md` | large UIKit modules needing explicit role separation |
+| `reactive.md` | Combine or RxSwift stream-heavy features and event pipelines |
+| `mvp.md` | UIKit-first passive views with presenter-driven rendering |
+| `coordinator.md` | decoupled navigation flows and deep-linkable screen orchestration |
+
+## Problem Router
+
+- "I need help choosing an architecture" → `selection-guide.md`
+- "The feature is simple and screen-scoped" → `mvvm.md`
+- "I want deterministic state transitions without TCA" → `mvi.md`
+- "The feature has complex state, child composition, and strict effects" → `tca.md`
+- "I need use cases, repositories, and clean boundaries" → `clean-architecture.md`
+- "This is a large UIKit module with clear presenter/interactor/router roles" → `viper.md`
+- "The problem is stream-heavy or driven by Combine/RxSwift" → `reactive.md`
+- "I want a passive UIKit view with a presenter" → `mvp.md`
+- "The main issue is navigation flow and screen coordination" → `coordinator.md`

tooling/scripts/validate/architecture.py

@@ -43,7 +43,7 @@ def expected_reference_slugs() -> Set[str]:
     slugs = {
         p.stem
         for p in REFERENCES_DIR.glob("*.md")
-        if p.stem != "selection-guide"
+        if p.stem not in {"selection-guide", "_index"}
     }
     return slugs