align context and skills consistency (#192) (#198)

* fix(context): migrate delegation references to split workflow files

* chore(ci): add markdown link validation with regex skip rules

* fix(context): migrate index references to navigation

* fix(agent): allow limited bash for task status updates

* refactor(skills): migrate to .opencode/skills and normalize skill files

* fix(agent): align subagent permissions and workflow structure

* docs: reconcile workflow examples and design iteration references

* feat(skill): enforce schema checks in task validate command

* fix(install): improve colored output and skills collision grouping

.github/workflows/validate-registry.yml

@@ -195,6 +195,30 @@ jobs:
             echo "See [CONTRIBUTING.md](docs/contributing/CONTRIBUTING.md) for details" >> $GITHUB_STEP_SUMMARY
             exit 1
           fi
+
+      - name: Validate markdown context links
+        if: github.event.inputs.skip_validation != 'true'
+        id: validate_context_links
+        run: |
+          echo "## 🔗 Context Link Validation" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          if bun run scripts/validation/validate-markdown-links.ts > /tmp/context-link-validation.txt 2>&1; then
+            echo "context_links=passed" >> $GITHUB_OUTPUT
+            echo "✅ Context markdown links are valid!" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+            cat /tmp/context-link-validation.txt >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "context_links=failed" >> $GITHUB_OUTPUT
+            echo "❌ Context markdown link validation failed!" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+            cat /tmp/context-link-validation.txt >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+            exit 1
+          fi
       
       - name: Validate registry
         if: github.event.inputs.skip_validation != 'true'
@@ -308,12 +332,14 @@ jobs:
           echo "" >> $GITHUB_STEP_SUMMARY
           
           PROMPT_VALID="${{ steps.validate_prompts.outputs.prompt_validation }}"
+          CONTEXT_LINKS_VALID="${{ steps.validate_context_links.outputs.context_links }}"
           REGISTRY_VALID="${{ steps.validate.outputs.validation }}"
-          
-          if [ "$PROMPT_VALID" = "passed" ] && [ "$REGISTRY_VALID" = "passed" ]; then
+
+          if [ "$PROMPT_VALID" = "passed" ] && [ "$CONTEXT_LINKS_VALID" = "passed" ] && [ "$REGISTRY_VALID" = "passed" ]; then
             echo "### ✅ All Validations Passed" >> $GITHUB_STEP_SUMMARY
             echo "" >> $GITHUB_STEP_SUMMARY
             echo "- ✅ Prompt library structure is valid" >> $GITHUB_STEP_SUMMARY
+            echo "- ✅ Context markdown links are valid" >> $GITHUB_STEP_SUMMARY
             echo "- ✅ Registry paths are valid" >> $GITHUB_STEP_SUMMARY
             echo "" >> $GITHUB_STEP_SUMMARY
             echo "This PR is ready for review!" >> $GITHUB_STEP_SUMMARY
@@ -326,7 +352,13 @@ jobs:
             else
               echo "- ✅ Prompt library validation passed" >> $GITHUB_STEP_SUMMARY
             fi
-            
+
+            if [ "$CONTEXT_LINKS_VALID" != "passed" ]; then
+              echo "- ❌ Context markdown link validation failed" >> $GITHUB_STEP_SUMMARY
+            else
+              echo "- ✅ Context markdown link validation passed" >> $GITHUB_STEP_SUMMARY
+            fi
+
             if [ "$REGISTRY_VALID" != "passed" ]; then
               echo "- ❌ Registry validation failed" >> $GITHUB_STEP_SUMMARY
             else
@@ -339,7 +371,7 @@ jobs:
       
       - name: Fail if validation failed
         if: |
-          (steps.validate_prompts.outputs.prompt_validation == 'failed' || steps.validate.outputs.validation == 'failed') &&
+          (steps.validate_prompts.outputs.prompt_validation == 'failed' || steps.validate_context_links.outputs.context_links == 'failed' || steps.validate.outputs.validation == 'failed') &&
           github.event.inputs.skip_validation != 'true'
         run: |
           echo "❌ Validation failed - blocking PR merge"

.opencode/agent/core/openagent.md

@@ -42,14 +42,14 @@ WHY THIS MATTERS:
 - Docs without standards/documentation.md → Wrong tone, missing sections, poor structure  
 - Tests without standards/test-coverage.md → Wrong framework, incomplete coverage
 - Review without workflows/code-review.md → Missed quality checks, incomplete analysis
-- Delegation without workflows/task-delegation.md → Wrong context passed to subagents
+- Delegation without workflows/task-delegation-basics.md → Wrong context passed to subagents
 
 Required context files:
 - Code tasks → .opencode/context/core/standards/code-quality.md
 - Docs tasks → .opencode/context/core/standards/documentation.md  
 - Tests tasks → .opencode/context/core/standards/test-coverage.md
 - Review tasks → .opencode/context/core/workflows/code-review.md
-- Delegation → .opencode/context/core/workflows/task-delegation.md
+- Delegation → .opencode/context/core/workflows/task-delegation-basics.md
 
 CONSEQUENCE OF SKIPPING: Work that doesn't match project standards = wasted effort + rework
 </critical_context_requirement>
@@ -248,7 +248,7 @@ task(
          - docs (write/edit docs) → Read .opencode/context/core/standards/documentation.md NOW
          - tests (write/edit tests) → Read .opencode/context/core/standards/test-coverage.md NOW
          - review (code review) → Read .opencode/context/core/workflows/code-review.md NOW
-         - delegate (using task tool) → Read .opencode/context/core/workflows/task-delegation.md NOW
+         - delegate (using task tool) → Read .opencode/context/core/workflows/task-delegation-basics.md NOW
          - bash-only → No context needed, proceed to 3.2
          
          NOTE: Load all files discovered by ContextScout in Stage 1.5 if not already loaded.
@@ -262,7 +262,7 @@ task(
         IF docs task → .opencode/context/core/standards/documentation.md (MANDATORY)
         IF tests task → .opencode/context/core/standards/test-coverage.md (MANDATORY)
         IF review task → .opencode/context/core/workflows/code-review.md (MANDATORY)
-        IF delegation → .opencode/context/core/workflows/task-delegation.md (MANDATORY)
+        IF delegation → .opencode/context/core/workflows/task-delegation-basics.md (MANDATORY)
         IF bash-only → No context required
         
         WHEN DELEGATING TO SUBAGENTS:
@@ -305,10 +305,10 @@ task(
          1. **Identify Parallel Batches** (use task-cli.ts):
             ```bash
             # Get all parallel-ready tasks
-            bash .opencode/skill/task-management/router.sh parallel {feature}
+            bash .opencode/skills/task-management/router.sh parallel {feature}
             
             # Get next eligible tasks
-            bash .opencode/skill/task-management/router.sh next {feature}
+            bash .opencode/skills/task-management/router.sh next {feature}
             ```
          
          2. **Build Execution Plan**:
@@ -346,7 +346,7 @@ task(
          
          4. **Verify Batch 1 Complete**:
             ```bash
-            bash .opencode/skill/task-management/router.sh status {feature}
+            bash .opencode/skills/task-management/router.sh status {feature}
             ```
             Confirm tasks 01, 02, 03 all show status: "completed"
          
@@ -611,7 +611,7 @@ task(
      </route>
    </specialized_routing>
   
-  <process ref=".opencode/context/core/workflows/task-delegation.md">Full delegation template & process</process>
+  <process ref=".opencode/context/core/workflows/task-delegation-basics.md">Full delegation template & process</process>
 </delegation_rules>
 
 <principles>
@@ -624,14 +624,14 @@ task(
 </principles>
 
 <static_context>
-  Context index: .opencode/context/index.md
+  Context index: .opencode/context/navigation.md
   
   Load index when discovering contexts by keywords. For common tasks:
   - Code tasks → .opencode/context/core/standards/code-quality.md
   - Docs tasks → .opencode/context/core/standards/documentation.md  
   - Tests tasks → .opencode/context/core/standards/test-coverage.md
   - Review tasks → .opencode/context/core/workflows/code-review.md
-  - Delegation → .opencode/context/core/workflows/task-delegation.md
+  - Delegation → .opencode/context/core/workflows/task-delegation-basics.md
   
   Full index includes all contexts with triggers and dependencies.
   Context files loaded per @critical_context_requirement.

.opencode/agent/core/opencoder.md

@@ -329,7 +329,7 @@ Code Standards
               
               3. Validate batch completion:
                  ```bash
-                 bash .opencode/skill/task-management/router.sh status {feature}
+                 bash .opencode/skills/task-management/router.sh status {feature}
                  ```
                  - Check all subtasks in batch have status: "completed"
                  - Verify deliverables exist

.opencode/agent/subagents/code/coder-agent.md

@@ -4,6 +4,10 @@ description: Executes coding subtasks in sequence, ensuring completion as specif
 mode: subagent
 temperature: 0
 permission:
+  bash:
+    "*": "deny"
+    "bash .opencode/skills/task-management/router.sh complete*": "allow"
+    "bash .opencode/skills/task-management/router.sh status*": "allow"
   edit:
     "**/*.env*": "deny"
     "**/*.key": "deny"
@@ -35,7 +39,7 @@ permission:
   <system>Subtask execution engine within the OpenAgents task management pipeline</system>
   <domain>Software implementation — coding, file creation, integration</domain>
   <task>Implement atomic subtasks from JSON definitions, following project standards discovered via ContextScout</task>
-  <constraints>No bash access. Sequential execution. Self-review mandatory before handoff.</constraints>
+  <constraints>Limited bash access for task status updates only. Sequential execution. Self-review mandatory before handoff.</constraints>
   <tier level="1" desc="Critical Operations">
     - @context_first: ContextScout ALWAYS before coding
     - @external_scout_mandatory: ExternalScout for any external package
@@ -193,17 +197,17 @@ Update subtask status and report completion to orchestrator:
 **8.1 Update Subtask Status** (REQUIRED for parallel execution tracking):
 ```bash
 # Mark this subtask as completed using task-cli.ts
-bash .opencode/skill/task-management/router.sh complete {feature} {seq} "{completion_summary}"
+bash .opencode/skills/task-management/router.sh complete {feature} {seq} "{completion_summary}"
 ```
 
 Example:
 ```bash
-bash .opencode/skill/task-management/router.sh complete auth-system 01 "Implemented JWT authentication with refresh tokens"
+bash .opencode/skills/task-management/router.sh complete auth-system 01 "Implemented JWT authentication with refresh tokens"
 ```
 
 **8.2 Verify Status Update**:
 ```bash
-bash .opencode/skill/task-management/router.sh status {feature}
+bash .opencode/skills/task-management/router.sh status {feature}
 ```
 Confirm your subtask now shows: `status: "completed"`
 

.opencode/agent/subagents/core/batch-executor.md

@@ -7,7 +7,7 @@ permission:
   bash:
     "*": "deny"
     "npx ts-node*task-cli*": "allow"
-    "bash .opencode/skill/task-management/router.sh*": "allow"
+    "bash .opencode/skills/task-management/router.sh*": "allow"
   edit:
     "**/*.env*": "deny"
     "**/*.key": "deny"
@@ -19,6 +19,7 @@ permission:
     contextscout: "allow"
     externalscout: "allow"
     coderagent: "allow"
+    OpenFrontendSpecialist: "allow"
 ---
 
 # BatchExecutor
@@ -165,7 +166,7 @@ While waiting, you can optionally:
 
 ```bash
 # Check status of all subtasks in this batch
-bash .opencode/skill/task-management/router.sh status {feature}
+bash .opencode/skills/task-management/router.sh status {feature}
 ```
 
 Expected output:
@@ -235,7 +236,7 @@ Batch 2 depends on: 01, 02, 03 (all now satisfied).
 1. **Detect failure** from CoderAgent return
 2. **Check status** of other tasks in batch:
    ```bash
-   bash .opencode/skill/task-management/router.sh status {feature}
+   bash .opencode/skills/task-management/router.sh status {feature}
    ```
 3. **Report to orchestrator**:
    ```
@@ -261,7 +262,7 @@ If CoderAgent reports completion but status doesn't show completed:
 2. **Check if CoderAgent actually ran task-cli.ts complete**
 3. **Manually mark complete** if needed:
    ```bash
-   bash .opencode/skill/task-management/router.sh complete {feature} {seq} "{summary}"
+   bash .opencode/skills/task-management/router.sh complete {feature} {seq} "{summary}"
    ```
 4. **Report discrepancy** to orchestrator
 

.opencode/agent/subagents/core/externalscout.md

@@ -6,7 +6,7 @@ temperature: 0.1
 permission:
   read:
     "**/*": "deny"
-    ".opencode/skill/context7/**": "allow"
+    ".opencode/skills/context7/**": "allow"
     ".tmp/external-context/**": "allow"
   bash:
     "*": "deny"
@@ -30,14 +30,14 @@ permission:
 <critical_rules priority="absolute" enforcement="strict">
   <rule id="tool_usage">
     ALLOWED: 
-    - read: ONLY .opencode/skill/context7/** and .tmp/external-context/**
+    - read: ONLY .opencode/skills/context7/** and .tmp/external-context/**
     - bash: ONLY curl to context7.com
     - skill: ONLY context7
     - grep: ONLY within .tmp/external-context/
     - webfetch: Any URL
     - write: ONLY to .tmp/external-context/**
     - edit: ONLY .tmp/external-context/**
-    - glob: ONLY .opencode/skill/context7/** and .tmp/external-context/**
+    - glob: ONLY .opencode/skills/context7/** and .tmp/external-context/**
     
     NEVER use: task | todoread | todowrite
     NEVER read: Project files, source code, or any files outside allowed paths
@@ -125,7 +125,7 @@ permission:
   <stage id="1" name="DetectLibrary">
     <action>Identify library/framework from user query AND understand tech stack context</action>
     <process>
-      1. Read `.opencode/skill/context7/library-registry.md`
+      1. Read `.opencode/skills/context7/library-registry.md`
       2. Match query against library names, package names, and aliases
       3. Extract library ID and official docs URL
       4. **Detect tech stack context** from user query:
@@ -244,7 +244,7 @@ permission:
 
 ## Quick Reference
 
-**Library Registry**: `.opencode/skill/context7/library-registry.md` — Supported libraries, IDs, and official docs links
+**Library Registry**: `.opencode/skills/context7/library-registry.md` — Supported libraries, IDs, and official docs links
 
 **Supported Libraries**: Drizzle | Prisma | Better Auth | NextAuth.js | Clerk | Next.js | React | TanStack Query/Router | Cloudflare Workers | AWS Lambda | Vercel | Shadcn/ui | Radix UI | Tailwind CSS | Zustand | Jotai | Zod | React Hook Form | Vitest | Playwright
 

.opencode/agent/subagents/core/task-manager.md

@@ -56,7 +56,7 @@ WHY THIS MATTERS:
       - Expect the calling agent to supply relevant context file paths; request them if absent.
       - Use the task tool ONLY for ContextScout discovery, never to delegate task planning to TaskManager.
       - Do NOT create session bundles or write `.tmp/sessions/**` files.
-      - Do NOT read `.opencode/context/core/workflows/task-delegation.md` or follow delegation workflows.
+      - Do NOT read `.opencode/context/core/workflows/task-delegation-basics.md` or follow delegation workflows.
       - Your output (JSON files) is your primary communication channel.
     </with_meta_agent>
 
@@ -85,7 +85,7 @@ WHY THIS MATTERS:
 
         2. Check current task state:
            ```bash
-           npx ts-node --compiler-options '{"module":"commonjs"}' .opencode/skill/task-management/scripts/task-cli.ts status
+           npx ts-node --compiler-options '{"module":"commonjs"}' .opencode/skills/task-management/scripts/task-cli.ts status
            ```
 
         3. If context bundle provided, load and extract:
@@ -207,13 +207,14 @@ WHY THIS MATTERS:
  
               **FRONTEND RULE**: If a task involves UI design, styling, or frontend implementation:
               1. Set `suggested_agent`: "OpenFrontendSpecialist"
-              2. Include `.opencode/context/ui/web/ui-styling-standards.md` and `.opencode/context/core/workflows/design-iteration.md` in `context_files`.
-              3. Ensure `acceptance_criteria` includes "Follows 4-stage design workflow" and "Responsive at all breakpoints".
-              4. **PARALLELIZATION**: Design tasks can run in parallel (`parallel: true`) since design work is isolated and doesn't affect backend/logic implementation. Only mark `parallel: false` if design depends on backend API contracts or data structures.
+              2. Include `.opencode/context/ui/web/ui-styling-standards.md` and `.opencode/context/core/workflows/design-iteration-overview.md` in `context_files`.
+              3. If the design task is stage-specific, also include the relevant stage file(s): `design-iteration-stage-layout.md`, `design-iteration-stage-theme.md`, `design-iteration-stage-animation.md`, `design-iteration-stage-implementation.md`.
+              4. Ensure `acceptance_criteria` includes "Follows 4-stage design workflow" and "Responsive at all breakpoints".
+              5. **PARALLELIZATION**: Design tasks can run in parallel (`parallel: true`) since design work is isolated and doesn't affect backend/logic implementation. Only mark `parallel: false` if design depends on backend API contracts or data structures.
  
          4. Validate with CLI:
            ```bash
-           npx ts-node --compiler-options '{"module":"commonjs"}' .opencode/skill/task-management/scripts/task-cli.ts validate {feature}
+           npx ts-node --compiler-options '{"module":"commonjs"}' .opencode/skills/task-management/scripts/task-cli.ts validate {feature}
            ```
 
         5. Report creation:
@@ -242,7 +243,7 @@ WHY THIS MATTERS:
 
         3. If all criteria pass:
            ```bash
-           npx ts-node --compiler-options '{"module":"commonjs"}' .opencode/skill/task-management/scripts/task-cli.ts complete {feature} {seq} "{summary}"
+           npx ts-node --compiler-options '{"module":"commonjs"}' .opencode/skills/task-management/scripts/task-cli.ts complete {feature} {seq} "{summary}"
            ```
 
         4. If criteria fail:
@@ -252,7 +253,7 @@ WHY THIS MATTERS:
 
         5. Check for next task:
            ```bash
-           npx ts-node --compiler-options '{"module":"commonjs"}' .opencode/skill/task-management/scripts/task-cli.ts next {feature}
+           npx ts-node --compiler-options '{"module":"commonjs"}' .opencode/skills/task-management/scripts/task-cli.ts next {feature}
            ```
       </process>
       <checkpoint>Task verified and status updated</checkpoint>
@@ -264,7 +265,7 @@ WHY THIS MATTERS:
       <process>
         1. Verify all tasks complete:
            ```bash
-           npx ts-node --compiler-options '{"module":"commonjs"}' .opencode/skill/task-management/scripts/task-cli.ts status {feature}
+           npx ts-node --compiler-options '{"module":"commonjs"}' .opencode/skills/task-management/scripts/task-cli.ts status {feature}
            ```
 
         2. If completed_count == subtask_count:
@@ -329,7 +330,7 @@ Use task-cli.ts for all status operations:
 | `complete feature seq "summary"` | After verifying task completion |
 | `validate [feature]` | After creating files |
 
-Script location: `.opencode/skill/task-management/scripts/task-cli.ts`
+Script location: `.opencode/skills/task-management/scripts/task-cli.ts`
 </cli_integration>
 
 <quality_standards>
@@ -364,4 +365,3 @@ Script location: `.opencode/skill/task-management/scripts/task-cli.ts`
     <lazy_loading>Reference context files, don't embed content</lazy_loading>
     <no_self_delegation>Do not create session bundles or delegate to TaskManager; execute directly</no_self_delegation>
   </principles>
-

.opencode/agent/subagents/system-builder/command-creator.md

@@ -144,7 +144,7 @@ temperature: 0.1
       ```
     </template>
     <output>Complete command files</output>
-  </step_5>
+  </step_4>
 
   <step_5>
     <action>Create command usage guide</action>

.opencode/command/add-context.md

@@ -796,28 +796,7 @@ Express: `src/routes/ controllers/ models/ middleware/`
 ✅ Version 1.4 → 1.5
 ```
 
-### Example 4: Extract External Context
-```bash
-/add-context
-
-# Found external context files in .tmp/
-#   📄 .tmp/external-context.md (2.4 KB)
-#   📄 .tmp/api-patterns.md (1.8 KB)
-# 
-# Choose: 1. Extract & use these files
-# 
-# Extracted patterns:
-#   ✓ Tech Stack: Next.js 15 + TypeScript + PostgreSQL + Tailwind
-#   ✓ API Pattern: [from external-context.md]
-#   ✓ Component: [from api-patterns.md]
-#   ✓ Naming: kebab-case files, PascalCase components
-#   ✓ Standards: TypeScript strict, Zod validation
-#   ✓ Security: Input validation, parameterized queries
-#
-# ✅ Created: technical-domain.md (merged with external patterns)
-```
-
-### Example 5: External Context Files Present
+### Example 4: External Context Files Present
 ```bash
 /add-context
 
@@ -843,7 +822,7 @@ Express: `src/routes/ controllers/ models/ middleware/`
 # After harvesting, run /add-context again.
 ```
 
-### Example 6: After Harvesting External Context
+### Example 5: After Harvesting External Context
 ```bash
 # After running: /context harvest
 

.opencode/command/openagents/check-context-deps.md

@@ -282,7 +282,7 @@ task(
     TASK:
     1. Use grep to find all references to context files in:
        - .opencode/agent/**/*.md
-       - .opencode/prompts/**/*.md
+       - .opencode/command/**/*.md
     
     2. Search for these patterns:
        - ".opencode/context/core/" (direct paths)

.opencode/context/core/navigation.md

@@ -23,10 +23,10 @@ core/
 ├── workflows/
 │   ├── navigation.md
 │   ├── code-review.md
-│   ├── task-delegation.md
+│   ├── task-delegation-basics.md
 │   ├── feature-breakdown.md
 │   ├── session-management.md
-│   └── design-iteration.md
+│   └── design-iteration-overview.md
 │
 ├── guides/
 │   └── resuming-sessions.md      # NEW: Multi-session task resumption
@@ -62,7 +62,7 @@ core/
 | **Write docs** | `standards/documentation.md` |
 | **Security patterns** | `standards/security-patterns.md` |
 | **Review code** | `workflows/code-review.md` |
-| **Delegate task** | `workflows/task-delegation.md` |
+| **Delegate task** | `workflows/task-delegation-basics.md` |
 | **Break down feature** | `workflows/feature-breakdown.md` |
 | **Resume session** | `guides/resuming-sessions.md` |
 | **Manage tasks** | `task-management/navigation.md` |

.opencode/context/core/system/context-guide.md

@@ -6,7 +6,7 @@
 
 **Key Principle**: Use context index for discovery, load specific files as needed
 
-**Index Location**: `.opencode/context/index.md` - Quick map of all contexts
+**Index Location**: `.opencode/context/navigation.md` - Quick map of all contexts
 
 **Structure**: standards/ (quality + analysis), workflows/ (process + review), system/ (internals)
 
@@ -20,7 +20,7 @@ Context files provide guidelines and templates for specific tasks. Use the index
 
 ## Context Index System
 
-**Central Index**: `.opencode/context/index.md` - Ultra-compact map of all contexts
+**Central Index**: `.opencode/context/navigation.md` - Ultra-compact map of all contexts
 
 The index provides:
 - Quick map for common tasks (code, docs, tests, review, delegation)
@@ -40,7 +40,7 @@ All files are in `.opencode/context/core/` with organized subfolders:
 - `standards/code-analysis.md` - Analysis framework [high]
 
 ### Workflows (Process Templates + Review)
-- `workflows/task-delegation.md` - Delegation template [high]
+- `workflows/task-delegation-basics.md` - Delegation template [high]
 - `workflows/feature-breakdown.md` - Complex task breakdown [high]
 - `workflows/session-management.md` - Session lifecycle [medium]
 - `workflows/code-review.md` - Code review guidelines [high]
@@ -53,7 +53,7 @@ All files are in `.opencode/context/core/` with organized subfolders:
 - Review task? → Load `workflows/code-review.md`
 
 **Step 2: Load Index** (for keyword matching)
-- Load `.opencode/context/index.md`
+- Load `.opencode/context/navigation.md`
 - Scan triggers to find relevant contexts
 - Load specific context files as needed
 
@@ -95,7 +95,7 @@ All files are in `.opencode/context/core/` with organized subfolders:
 - Investigating bugs
 - Evaluating architecture
 
-### .opencode/context/core/workflows/task-delegation.md
+### .opencode/context/core/workflows/task-delegation-basics.md
 - Delegating to general agent
 - Creating task context
 - Multi-file coordination

.opencode/context/core/visual-development.md

@@ -12,7 +12,7 @@
 | **Generate image/diagram** | This file | Image Specialist | tool:gemini |
 | **Edit existing image** | This file | Image Specialist | tool:gemini |
 | **UI mockup (static)** | This file | Image Specialist | tool:gemini |
-| **Interactive UI design** | `workflows/design-iteration.md` | - | - |
+| **Interactive UI design** | `workflows/design-iteration-overview.md` | - | - |
 | **Design system** | `ui/web/design-systems.md` | - | - |
 | **UI standards** | `ui/web/ui-styling-standards.md` | - | - |
 | **Animation patterns** | `ui/web/animation-patterns.md` | - | - |
@@ -302,7 +302,7 @@ User needs visual content
     ↓
 Is it interactive/responsive HTML/CSS?
     ↓
-  YES → Use design-iteration.md workflow
+  YES → Use design-iteration-overview.md workflow
     |    - Create HTML files
     |    - Iterate on designs
     |    - Production-ready code
@@ -322,13 +322,13 @@ Is it interactive/responsive HTML/CSS?
 
 | Need | Use |
 |------|-----|
-| **Interactive dashboard** | design-iteration.md |
+| **Interactive dashboard** | design-iteration-overview.md |
 | **Dashboard mockup (static image)** | Image Specialist |
-| **Responsive landing page** | design-iteration.md |
+| **Responsive landing page** | design-iteration-overview.md |
 | **Landing page hero graphic** | Image Specialist |
-| **Working HTML prototype** | design-iteration.md |
+| **Working HTML prototype** | design-iteration-overview.md |
 | **Architecture diagram** | Image Specialist |
-| **UI component library** | design-iteration.md |
+| **UI component library** | design-iteration-overview.md |
 | **Social media graphic** | Image Specialist |
 
 ---
@@ -447,7 +447,7 @@ After receiving output:
 
 ## Related Context
 
-- **UI Design Workflow**: `.opencode/context/core/workflows/design-iteration.md`
+- **UI Design Workflow**: `.opencode/context/core/workflows/design-iteration-overview.md`
 - **Design Systems**: `.opencode/context/ui/web/design-systems.md`
 - **UI Styling Standards**: `.opencode/context/ui/web/ui-styling-standards.md`
 - **Animation Patterns**: `.opencode/context/ui/web/animation-patterns.md`

.opencode/context/core/workflows/delegation.md

@@ -1,7 +1,7 @@
 <!-- Context: workflows/delegation | Priority: high | Version: 2.0 | Updated: 2025-01-21 -->
 # Delegation Context Template
 
-> **Note**: This is a reference file. The full content is in [`task-delegation.md`](./task-delegation.md).
+> **Note**: This is a reference file. Start with [`task-delegation-basics.md`](./task-delegation-basics.md).
 
 ## Quick Reference
 
@@ -13,4 +13,8 @@
 
 ---
 
-For the complete delegation workflow template, see [task-delegation.md](./task-delegation.md).
+For the full delegation workflow, use:
+
+- [task-delegation-basics.md](./task-delegation-basics.md)
+- [task-delegation-specialists.md](./task-delegation-specialists.md)
+- [task-delegation-caching.md](./task-delegation-caching.md)

.opencode/context/core/workflows/external-context-integration.md

@@ -457,5 +457,5 @@ CoderAgent reads subtask JSON and:
 
 - **ExternalScout**: `.opencode/agent/subagents/core/externalscout.md`
 - **External Context Management**: `.opencode/context/core/workflows/external-context-management.md`
-- **Task Delegation**: `.opencode/context/core/workflows/task-delegation.md`
+- **Task Delegation**: `.opencode/context/core/workflows/task-delegation-basics.md`
 - **Management Script**: `scripts/external-context/manage-external-context.sh`

.opencode/context/core/workflows/external-context-management.md

@@ -401,6 +401,6 @@ After deleting external context files, update `.manifest.json`:
 ## References
 
 - **ExternalScout**: `.opencode/agent/subagents/core/externalscout.md` — Fetches and persists external docs
-- **Task Delegation**: `.opencode/context/core/workflows/task-delegation.md` — How to reference external context in sessions
+- **Task Delegation**: `.opencode/context/core/workflows/task-delegation-basics.md` — How to reference external context in sessions
 - **Session Management**: `.opencode/context/core/workflows/session-management.md` — Session lifecycle
-- **Library Registry**: `.opencode/skill/context7/library-registry.md` — Supported libraries and query patterns
+- **Library Registry**: `.opencode/skills/context7/library-registry.md` — Supported libraries and query patterns

.opencode/context/core/workflows/external-libraries-faq.md

@@ -150,7 +150,7 @@ Before implementing with external libraries:
 
 ## Supported Libraries
 
-**See**: `.opencode/skill/context7/library-registry.md`
+**See**: `.opencode/skills/context7/library-registry.md`
 
 **Categories:** Database/ORM | Auth | Frontend | Infrastructure | UI | State | Validation | Testing
 

.opencode/context/core/workflows/navigation.md

@@ -45,7 +45,7 @@
 
 **For complex features**:
 1. Load `feature-breakdown.md` (high)
-2. Depends on: `task-delegation.md`
+2. Depends on: `task-delegation-basics.md`
 
 **For session management**:
 1. Load `session-management.md` (medium)

.opencode/context/core/workflows/task-delegation-specialists.md

@@ -127,4 +127,4 @@ task(
 
 - `task-delegation-basics.md` - Core delegation workflow
 - `task-delegation-caching.md` - Context caching
-- `design-iteration.md` - OpenFrontendSpecialist workflow
+- `design-iteration-overview.md` - OpenFrontendSpecialist workflow

.opencode/context/core/workflows/task-delegation.md

@@ -0,0 +1,12 @@
+<!-- Compatibility shim. Kept to avoid broken links after workflow split. -->
+# Task Delegation
+
+This workflow was split into focused files.
+
+Use these files instead:
+
+1. `task-delegation-basics.md` - Core delegation flow
+2. `task-delegation-specialists.md` - Specialist selection rules
+3. `task-delegation-caching.md` - Context caching patterns
+
+Start here: [task-delegation-basics.md](./task-delegation-basics.md)

.opencode/context/development/frontend/when-to-delegate.md

@@ -292,7 +292,7 @@ The frontend-specialist will automatically load these via ContextScout:
 - `development/frontend/react/react-patterns.md` - React patterns (if React project)
 
 **Workflows**:
-- `core/workflows/design-iteration.md` - Design iteration workflow
+- `core/workflows/design-iteration-overview.md` - Design iteration workflow
 
 ---
 
@@ -464,5 +464,5 @@ task(
 - **Design Systems** → `../../ui/web/design-systems.md`
 - **UI Styling Standards** → `../../ui/web/ui-styling-standards.md`
 - **Animation Patterns** → `../../ui/web/animation-patterns.md`
-- **Delegation Workflow** → `../../core/workflows/task-delegation.md`
+- **Delegation Workflow** → `../../core/workflows/task-delegation-basics.md`
 - **React Patterns** → `react/react-patterns.md`

.opencode/context/index.md

@@ -0,0 +1,8 @@
+<!-- Compatibility shim. Use navigation.md as canonical index. -->
+# Context Index
+
+The canonical context index is `navigation.md`.
+
+Use:
+
+- [navigation.md](./navigation.md)

.opencode/context/navigation.md

@@ -28,7 +28,7 @@
 | **Write tests** | `core/standards/test-coverage.md` |
 | **Write docs** | `core/standards/documentation.md` |
 | **Review code** | `core/workflows/code-review.md` |
-| **Delegate task** | `core/workflows/task-delegation.md` |
+| **Delegate task** | `core/workflows/task-delegation-basics.md` |
 | **Add agent** | `openagents-repo/guides/adding-agent.md` |
 | **UI development** | `development/ui-navigation.md` |
 | **API development** | `development/backend-navigation.md` |

.opencode/context/openagents-repo/blueprints/context-bundle-template.md

@@ -42,7 +42,7 @@ Status: in_progress
 - `.opencode/context/core/standards/security-patterns.md` → Error handling, security patterns
 
 **Core Workflows**:
-- `.opencode/context/core/workflows/task-delegation.md` → Delegation process
+- `.opencode/context/core/workflows/task-delegation-basics.md` → Delegation process
 - `.opencode/context/core/workflows/feature-breakdown.md` → Task breakdown methodology
 - `.opencode/context/core/workflows/code-review.md` → Code review guidelines
 

.opencode/context/openagents-repo/examples/context-bundle-example.md

@@ -90,7 +90,7 @@ Create a new data analyst agent for the OpenAgents Control repository. This agen
 
 **Modify**:
 - `registry.json` - Add data-analyst agent entry
-- `.opencode/context/index.md` - Add data category context if needed
+- `.opencode/context/navigation.md` - Add data category context if needed
 
 ## Success Criteria
 

.opencode/context/openagents-repo/guides/adding-skill-basics.md

@@ -32,12 +32,12 @@ Adding an OpenCode skill involves:
 ### Create Structure
 
 ```bash
-mkdir -p .opencode/skill/{skill-name}/scripts
+mkdir -p .opencode/skills/{skill-name}/scripts
 ```
 
 **Standard structure**:
 ```
-.opencode/skill/{skill-name}/
+.opencode/skills/{skill-name}/
 ├── SKILL.md              # Required: Main skill documentation
 ├── router.sh             # Optional: CLI router script
 └── scripts/
@@ -71,7 +71,7 @@ description: Brief description of what the skill provides
 ### Basic Commands
 
 ```bash
-npx ts-node .opencode/skill/{skill-name}/scripts/skill-cli.ts command1
+npx ts-node .opencode/skills/{skill-name}/scripts/skill-cli.ts command1
 ```
 
 ### Command Reference
@@ -126,7 +126,7 @@ esac
 ```
 
 ```bash
-chmod +x .opencode/skill/{skill-name}/router.sh
+chmod +x .opencode/skills/{skill-name}/router.sh
 ```
 
 ---

.opencode/context/openagents-repo/guides/adding-skill-example.md

@@ -7,11 +7,11 @@
 ## Directory Structure
 
 ```bash
-mkdir -p .opencode/skill/task-management/scripts
+mkdir -p .opencode/skills/task-management/scripts
 ```
 
 ```
-.opencode/skill/task-management/
+.opencode/skills/task-management/
 ├── SKILL.md
 ├── router.sh
 └── scripts/
@@ -44,13 +44,13 @@ description: Task management CLI for tracking feature subtasks
 
 ```bash
 # Show all task statuses
-npx ts-node .opencode/skill/task-management/scripts/task-cli.ts status
+npx ts-node .opencode/skills/task-management/scripts/task-cli.ts status
 
 # Show next eligible tasks
-npx ts-node .opencode/skill/task-management/scripts/task-cli.ts next
+npx ts-node .opencode/skills/task-management/scripts/task-cli.ts next
 
 # Mark complete
-npx ts-node .opencode/skill/task-management/scripts/task-cli.ts complete <feature> <seq> "summary"
+npx ts-node .opencode/skills/task-management/scripts/task-cli.ts complete <feature> <seq> "summary"
 ```
 ```
 

.opencode/context/openagents-repo/guides/adding-skill-implementation.md

@@ -75,7 +75,7 @@ main().catch(console.error)
       "id": "{skill-name}",
       "name": "Skill Name",
       "type": "skill",
-      "path": ".opencode/skill/{skill-name}/SKILL.md",
+      "path": ".opencode/skills/{skill-name}/SKILL.md",
       "description": "Brief description",
       "tags": ["tag1", "tag2"],
       "dependencies": []
@@ -106,13 +106,13 @@ main().catch(console.error)
 
 ```bash
 # Test help
-bash .opencode/skill/{skill-name}/router.sh help
+bash .opencode/skills/{skill-name}/router.sh help
 
 # Test commands
-bash .opencode/skill/{skill-name}/router.sh command1 --option value
+bash .opencode/skills/{skill-name}/router.sh command1 --option value
 
 # Test with npx
-npx ts-node .opencode/skill/{skill-name}/scripts/skill-cli.ts help
+npx ts-node .opencode/skills/{skill-name}/scripts/skill-cli.ts help
 ```
 
 ### Test OpenCode Integration
@@ -149,8 +149,8 @@ npx ts-node .opencode/skill/{skill-name}/scripts/skill-cli.ts help
 
 ## Checklist
 
-- [ ] `.opencode/skill/{skill-name}/SKILL.md` created
-- [ ] `.opencode/skill/{skill-name}/router.sh` created (if CLI-based)
+- [ ] `.opencode/skills/{skill-name}/SKILL.md` created
+- [ ] `.opencode/skills/{skill-name}/router.sh` created (if CLI-based)
 - [ ] Router script is executable (`chmod +x`)
 - [ ] Registry updated (if needed)
 - [ ] Profile updated (if needed)

.opencode/context/openagents-repo/guides/building-cli-compact.md

@@ -10,10 +10,10 @@
 
 **Don't start from scratch.** Use the standard pattern to build robust CLIs in minutes.
 
-1.  **Create**: `mkdir -p .opencode/skill/{name}/scripts`
+1.  **Create**: `mkdir -p .opencode/skills/{name}/scripts`
 2.  **Implement**: Create `skill-cli.ts` (TypeScript) and `router.sh` (Bash)
 3.  **Register**: Add to `registry.json`
-4.  **Run**: `bash .opencode/skill/{name}/router.sh help`
+4.  **Run**: `bash .opencode/skills/{name}/router.sh help`
 
 ---
 

.opencode/context/openagents-repo/lookup/file-locations.md

@@ -157,7 +157,7 @@ README.md                            # Main documentation
 .opencode/context/core/standards/documentation.md
 .opencode/context/core/standards/test-coverage.md
 .opencode/context/core/standards/security-patterns.md
-.opencode/context/core/workflows/task-delegation.md
+.opencode/context/core/workflows/task-delegation-basics.md
 .opencode/context/core/workflows/code-review.md
 ```
 

.opencode/context/openagents-repo/quality/registry-dependencies.md

@@ -127,7 +127,7 @@ Dependency:    context:core/standards/code
 dependencies:
   - context:core/standards/code           # .opencode/context/core/standards/code-quality.md
   - context:core/standards/docs           # .opencode/context/core/standards/documentation.md
-  - context:core/workflows/delegation     # .opencode/context/core/workflows/task-delegation.md
+  - context:core/workflows/delegation     # .opencode/context/core/workflows/task-delegation-basics.md
   - context:openagents-repo/guides/adding-agent  # Project-specific context
 ```
 

.opencode/plugin/docs/VALIDATOR_GUIDE.md

@@ -201,7 +201,7 @@ analyze_context_reads
 - **code.md** (2 reads)
   `.opencode/context/core/standards/code-quality.md`
 - **delegation.md** (1 read)
-  `.opencode/context/core/workflows/task-delegation.md`
+  `.opencode/context/core/workflows/task-delegation-basics.md`
 
 ### Timeline:
 1. [10:23:45] code.md
@@ -235,7 +235,7 @@ check_context_compliance
 
 ### ✅ Compliant Actions:
 - ✅ Loaded standards/code-quality.md before code writing
-- ✅ Loaded workflows/task-delegation.md before delegation
+- ✅ Loaded workflows/task-delegation-basics.md before delegation
 
 ### Context Loading Rules:
 According to OpenAgent prompt, the agent should:
@@ -251,7 +251,7 @@ According to OpenAgent prompt, the agent should:
 - Writing docs → should read `standards/documentation.md`
 - Writing tests → should read `standards/test-coverage.md`
 - Code review → should read `workflows/code-review.md`
-- Delegating → should read `workflows/task-delegation.md`
+- Delegating → should read `workflows/task-delegation-basics.md`
 
 **When to use:**
 - To verify lazy loading is working

.opencode/prompts/core/openagent/gemini.md

@@ -60,14 +60,14 @@ WHY THIS MATTERS:
 - Docs without standards/documentation.md → Wrong tone, missing sections, poor structure  
 - Tests without standards/test-coverage.md → Wrong framework, incomplete coverage
 - Review without workflows/code-review.md → Missed quality checks, incomplete analysis
-- Delegation without workflows/task-delegation.md → Wrong context passed to subagents
+- Delegation without workflows/task-delegation-basics.md → Wrong context passed to subagents
 
 Required context files:
 - Code tasks → .opencode/context/core/standards/code-quality.md
 - Docs tasks → .opencode/context/core/standards/documentation.md  
 - Tests tasks → .opencode/context/core/standards/test-coverage.md
 - Review tasks → .opencode/context/core/workflows/code-review.md
-- Delegation → .opencode/context/core/workflows/task-delegation.md
+- Delegation → .opencode/context/core/workflows/task-delegation-basics.md
 
 CONSEQUENCE OF SKIPPING: Work that doesn't match project standards = wasted effort + rework
 </critical_context_requirement>
@@ -180,7 +180,7 @@ task(
          - docs (write/edit docs) → Read .opencode/context/core/standards/documentation.md NOW
          - tests (write/edit tests) → Read .opencode/context/core/standards/test-coverage.md NOW
          - review (code review) → Read .opencode/context/core/workflows/code-review.md NOW
-         - delegate (using task tool) → Read .opencode/context/core/workflows/task-delegation.md NOW
+         - delegate (using task tool) → Read .opencode/context/core/workflows/task-delegation-basics.md NOW
          - bash-only → No context needed, proceed to 3.2
       
       3. Apply context:
@@ -192,7 +192,7 @@ task(
         IF docs task → .opencode/context/core/standards/documentation.md (MANDATORY)
         IF tests task → .opencode/context/core/standards/test-coverage.md (MANDATORY)
         IF review task → .opencode/context/core/workflows/code-review.md (MANDATORY)
-        IF delegation → .opencode/context/core/workflows/task-delegation.md (MANDATORY)
+        IF delegation → .opencode/context/core/workflows/task-delegation-basics.md (MANDATORY)
         IF bash-only → No context required
         
         WHEN DELEGATING TO SUBAGENTS:
@@ -303,7 +303,7 @@ task(
     </route>
   </specialized_routing>
   
-  <process ref=".opencode/context/core/workflows/task-delegation.md">Full delegation template & process</process>
+  <process ref=".opencode/context/core/workflows/task-delegation-basics.md">Full delegation template & process</process>
 </delegation_rules>
 
 <principles>
@@ -316,14 +316,14 @@ task(
 </principles>
 
 <static_context>
-  Context index: .opencode/context/index.md
+  Context index: .opencode/context/navigation.md
   
   Load index when discovering contexts by keywords. For common tasks:
   - Code tasks → .opencode/context/core/standards/code-quality.md
   - Docs tasks → .opencode/context/core/standards/documentation.md  
   - Tests tasks → .opencode/context/core/standards/test-coverage.md
   - Review tasks → .opencode/context/core/workflows/code-review.md
-  - Delegation → .opencode/context/core/workflows/task-delegation.md
+  - Delegation → .opencode/context/core/workflows/task-delegation-basics.md
   
   Full index includes all contexts with triggers and dependencies.
   Context files loaded per @critical_context_requirement.

.opencode/prompts/core/openagent/gpt.md

@@ -60,14 +60,14 @@ WHY THIS MATTERS:
 - Docs without standards/documentation.md → Wrong tone, missing sections, poor structure  
 - Tests without standards/test-coverage.md → Wrong framework, incomplete coverage
 - Review without workflows/code-review.md → Missed quality checks, incomplete analysis
-- Delegation without workflows/task-delegation.md → Wrong context passed to subagents
+- Delegation without workflows/task-delegation-basics.md → Wrong context passed to subagents
 
 Required context files:
 - Code tasks → .opencode/context/core/standards/code-quality.md
 - Docs tasks → .opencode/context/core/standards/documentation.md  
 - Tests tasks → .opencode/context/core/standards/test-coverage.md
 - Review tasks → .opencode/context/core/workflows/code-review.md
-- Delegation → .opencode/context/core/workflows/task-delegation.md
+- Delegation → .opencode/context/core/workflows/task-delegation-basics.md
 
 CONSEQUENCE OF SKIPPING: Work that doesn't match project standards = wasted effort + rework
 </critical_context_requirement>
@@ -180,7 +180,7 @@ task(
          - docs (write/edit docs) → Read .opencode/context/core/standards/documentation.md NOW
          - tests (write/edit tests) → Read .opencode/context/core/standards/test-coverage.md NOW
          - review (code review) → Read .opencode/context/core/workflows/code-review.md NOW
-         - delegate (using task tool) → Read .opencode/context/core/workflows/task-delegation.md NOW
+         - delegate (using task tool) → Read .opencode/context/core/workflows/task-delegation-basics.md NOW
          - bash-only → No context needed, proceed to 3.2
       
       3. Apply context:
@@ -192,7 +192,7 @@ task(
         IF docs task → .opencode/context/core/standards/documentation.md (MANDATORY)
         IF tests task → .opencode/context/core/standards/test-coverage.md (MANDATORY)
         IF review task → .opencode/context/core/workflows/code-review.md (MANDATORY)
-        IF delegation → .opencode/context/core/workflows/task-delegation.md (MANDATORY)
+        IF delegation → .opencode/context/core/workflows/task-delegation-basics.md (MANDATORY)
         IF bash-only → No context required
         
         WHEN DELEGATING TO SUBAGENTS:
@@ -303,7 +303,7 @@ task(
     </route>
   </specialized_routing>
   
-  <process ref=".opencode/context/core/workflows/task-delegation.md">Full delegation template & process</process>
+  <process ref=".opencode/context/core/workflows/task-delegation-basics.md">Full delegation template & process</process>
 </delegation_rules>
 
 <principles>
@@ -316,14 +316,14 @@ task(
 </principles>
 
 <static_context>
-  Context index: .opencode/context/index.md
+  Context index: .opencode/context/navigation.md
   
   Load index when discovering contexts by keywords. For common tasks:
   - Code tasks → .opencode/context/core/standards/code-quality.md
   - Docs tasks → .opencode/context/core/standards/documentation.md  
   - Tests tasks → .opencode/context/core/standards/test-coverage.md
   - Review tasks → .opencode/context/core/workflows/code-review.md
-  - Delegation → .opencode/context/core/workflows/task-delegation.md
+  - Delegation → .opencode/context/core/workflows/task-delegation-basics.md
   
   Full index includes all contexts with triggers and dependencies.
   Context files loaded per @critical_context_requirement.

.opencode/prompts/core/openagent/grok.md

@@ -63,14 +63,14 @@ WHY THIS MATTERS:
 - Docs without standards/documentation.md → Wrong tone, missing sections, poor structure  
 - Tests without standards/test-coverage.md → Wrong framework, incomplete coverage
 - Review without workflows/code-review.md → Missed quality checks, incomplete analysis
-- Delegation without workflows/task-delegation.md → Wrong context passed to subagents
+- Delegation without workflows/task-delegation-basics.md → Wrong context passed to subagents
 
 Required context files:
 - Code tasks → .opencode/context/core/standards/code-quality.md
 - Docs tasks → .opencode/context/core/standards/documentation.md  
 - Tests tasks → .opencode/context/core/standards/test-coverage.md
 - Review tasks → .opencode/context/core/workflows/code-review.md
-- Delegation → .opencode/context/core/workflows/task-delegation.md
+- Delegation → .opencode/context/core/workflows/task-delegation-basics.md
 
 CONSEQUENCE OF SKIPPING: Work that doesn't match project standards = wasted effort + rework
 </critical_context_requirement>
@@ -183,7 +183,7 @@ task(
          - docs (write/edit docs) → Read .opencode/context/core/standards/documentation.md NOW
          - tests (write/edit tests) → Read .opencode/context/core/standards/test-coverage.md NOW
          - review (code review) → Read .opencode/context/core/workflows/code-review.md NOW
-         - delegate (using task tool) → Read .opencode/context/core/workflows/task-delegation.md NOW
+         - delegate (using task tool) → Read .opencode/context/core/workflows/task-delegation-basics.md NOW
          - bash-only → No context needed, proceed to 3.2
       
       3. Apply context:
@@ -195,7 +195,7 @@ task(
         IF docs task → .opencode/context/core/standards/documentation.md (MANDATORY)
         IF tests task → .opencode/context/core/standards/test-coverage.md (MANDATORY)
         IF review task → .opencode/context/core/workflows/code-review.md (MANDATORY)
-        IF delegation → .opencode/context/core/workflows/task-delegation.md (MANDATORY)
+        IF delegation → .opencode/context/core/workflows/task-delegation-basics.md (MANDATORY)
         IF bash-only → No context required
         
         WHEN DELEGATING TO SUBAGENTS:
@@ -306,7 +306,7 @@ task(
     </route>
   </specialized_routing>
   
-  <process ref=".opencode/context/core/workflows/task-delegation.md">Full delegation template & process</process>
+  <process ref=".opencode/context/core/workflows/task-delegation-basics.md">Full delegation template & process</process>
 </delegation_rules>
 
 <principles>
@@ -319,14 +319,14 @@ task(
 </principles>
 
 <static_context>
-  Context index: .opencode/context/index.md
+  Context index: .opencode/context/navigation.md
   
   Load index when discovering contexts by keywords. For common tasks:
   - Code tasks → .opencode/context/core/standards/code-quality.md
   - Docs tasks → .opencode/context/core/standards/documentation.md  
   - Tests tasks → .opencode/context/core/standards/test-coverage.md
   - Review tasks → .opencode/context/core/workflows/code-review.md
-  - Delegation → .opencode/context/core/workflows/task-delegation.md
+  - Delegation → .opencode/context/core/workflows/task-delegation-basics.md
   
   Full index includes all contexts with triggers and dependencies.
   Context files loaded per @critical_context_requirement.

.opencode/prompts/core/openagent/llama.md

@@ -60,14 +60,14 @@ WHY THIS MATTERS:
 - Docs without standards/documentation.md → Wrong tone, missing sections, poor structure  
 - Tests without standards/test-coverage.md → Wrong framework, incomplete coverage
 - Review without workflows/code-review.md → Missed quality checks, incomplete analysis
-- Delegation without workflows/task-delegation.md → Wrong context passed to subagents
+- Delegation without workflows/task-delegation-basics.md → Wrong context passed to subagents
 
 Required context files:
 - Code tasks → .opencode/context/core/standards/code-quality.md
 - Docs tasks → .opencode/context/core/standards/documentation.md  
 - Tests tasks → .opencode/context/core/standards/test-coverage.md
 - Review tasks → .opencode/context/core/workflows/code-review.md
-- Delegation → .opencode/context/core/workflows/task-delegation.md
+- Delegation → .opencode/context/core/workflows/task-delegation-basics.md
 
 CONSEQUENCE OF SKIPPING: Work that doesn't match project standards = wasted effort + rework
 </critical_context_requirement>
@@ -180,7 +180,7 @@ task(
          - docs (write/edit docs) → Read .opencode/context/core/standards/documentation.md NOW
          - tests (write/edit tests) → Read .opencode/context/core/standards/test-coverage.md NOW
          - review (code review) → Read .opencode/context/core/workflows/code-review.md NOW
-         - delegate (using task tool) → Read .opencode/context/core/workflows/task-delegation.md NOW
+         - delegate (using task tool) → Read .opencode/context/core/workflows/task-delegation-basics.md NOW
          - bash-only → No context needed, proceed to 3.2
       
       3. Apply context:
@@ -192,7 +192,7 @@ task(
         IF docs task → .opencode/context/core/standards/documentation.md (MANDATORY)
         IF tests task → .opencode/context/core/standards/test-coverage.md (MANDATORY)
         IF review task → .opencode/context/core/workflows/code-review.md (MANDATORY)
-        IF delegation → .opencode/context/core/workflows/task-delegation.md (MANDATORY)
+        IF delegation → .opencode/context/core/workflows/task-delegation-basics.md (MANDATORY)
         IF bash-only → No context required
         
         WHEN DELEGATING TO SUBAGENTS:
@@ -303,7 +303,7 @@ task(
     </route>
   </specialized_routing>
   
-  <process ref=".opencode/context/core/workflows/task-delegation.md">Full delegation template & process</process>
+  <process ref=".opencode/context/core/workflows/task-delegation-basics.md">Full delegation template & process</process>
 </delegation_rules>
 
 <principles>
@@ -316,14 +316,14 @@ task(
 </principles>
 
 <static_context>
-  Context index: .opencode/context/index.md
+  Context index: .opencode/context/navigation.md
   
   Load index when discovering contexts by keywords. For common tasks:
   - Code tasks → .opencode/context/core/standards/code-quality.md
   - Docs tasks → .opencode/context/core/standards/documentation.md  
   - Tests tasks → .opencode/context/core/standards/test-coverage.md
   - Review tasks → .opencode/context/core/workflows/code-review.md
-  - Delegation → .opencode/context/core/workflows/task-delegation.md
+  - Delegation → .opencode/context/core/workflows/task-delegation-basics.md
   
   Full index includes all contexts with triggers and dependencies.
   Context files loaded per @critical_context_requirement.

.opencode/prompts/core/openagent/openrouter.md

@@ -61,14 +61,14 @@ WHY THIS MATTERS:
 - Docs without standards/documentation.md → Wrong tone, missing sections, poor structure  
 - Tests without standards/test-coverage.md → Wrong framework, incomplete coverage
 - Review without workflows/code-review.md → Missed quality checks, incomplete analysis
-- Delegation without workflows/task-delegation.md → Wrong context passed to subagents
+- Delegation without workflows/task-delegation-basics.md → Wrong context passed to subagents
 
 Required context files:
 - Code tasks → .opencode/context/core/standards/code-quality.md
 - Docs tasks → .opencode/context/core/standards/documentation.md  
 - Tests tasks → .opencode/context/core/standards/test-coverage.md
 - Review tasks → .opencode/context/core/workflows/code-review.md
-- Delegation → .opencode/context/core/workflows/task-delegation.md
+- Delegation → .opencode/context/core/workflows/task-delegation-basics.md
 
 CONSEQUENCE OF SKIPPING: Work that doesn't match project standards = wasted effort + rework
 </critical_context_requirement>
@@ -355,7 +355,7 @@ THEN:
          - Rule 5: Build validation needed?
       4. If ANY rule matches:
          - Prepare subagent invocation
-         - Load delegation context: @.opencode/context/core/workflows/task-delegation.md
+         - Load delegation context: @.opencode/context/core/workflows/task-delegation-basics.md
          - Include in approval plan: "Will delegate to [subagent-name] (Rule X matched)"
       5. If NO rules match:
          - Proceed with direct execution
@@ -412,7 +412,7 @@ THEN:
          - docs (write/edit docs) → Read @.opencode/context/core/standards/documentation.md NOW
          - tests (write/edit tests) → Read @.opencode/context/core/standards/test-coverage.md NOW
          - review (code review) → Read @.opencode/context/core/workflows/code-review.md NOW
-         - delegate (using task tool) → Read @.opencode/context/core/workflows/task-delegation.md NOW
+         - delegate (using task tool) → Read @.opencode/context/core/workflows/task-delegation-basics.md NOW
          - bash-only → No context needed, proceed to 3.2
       
       3. Apply context:
@@ -424,7 +424,7 @@ THEN:
         IF docs task → @.opencode/context/core/standards/documentation.md (MANDATORY)
         IF tests task → @.opencode/context/core/standards/test-coverage.md (MANDATORY)
         IF review task → @.opencode/context/core/workflows/code-review.md (MANDATORY)
-        IF delegation → @.opencode/context/core/workflows/task-delegation.md (MANDATORY)
+        IF delegation → @.opencode/context/core/workflows/task-delegation-basics.md (MANDATORY)
         IF bash-only → No context required
         
         WHEN DELEGATING TO SUBAGENTS:
@@ -491,12 +491,12 @@ THEN:
 <delegation_criteria>
   <route agent="TaskManager" category="features">
     <when>Feature spans 4+ files | effort >60 min | complex dependencies</when>
-    <context_inheritance>Load @.opencode/context/core/workflows/task-delegation.md</context_inheritance>
+    <context_inheritance>Load @.opencode/context/core/workflows/task-delegation-basics.md</context_inheritance>
     <invocation>
       task(
         subagent_type="TaskManager",
         description="Break down [feature]",
-        prompt="Analyze and break down [feature] into atomic subtasks. Load @.opencode/context/core/workflows/task-delegation.md for process."
+        prompt="Analyze and break down [feature] into atomic subtasks. Load @.opencode/context/core/workflows/task-delegation-basics.md for process."
       )
     </invocation>
   </route>

.opencode/skill/context/SKILL.md → .opencode/skills/context-manager/SKILL.md

@@ -38,49 +38,49 @@ I provide 8 powerful operations for managing context:
 
 ### 1. Discover Context
 ```bash
-bash .opencode/skill/context/router.sh discover authentication
+bash .opencode/skills/context-manager/router.sh discover authentication
 ```
 Finds all context files related to authentication patterns.
 
 ### 2. Fetch External Documentation
 ```bash
-bash .opencode/skill/context/router.sh fetch "Drizzle ORM" "modular schemas"
+bash .opencode/skills/context-manager/router.sh fetch "Drizzle ORM" "modular schemas"
 ```
 Retrieves live documentation from external libraries.
 
 ### 3. Harvest Context
 ```bash
-bash .opencode/skill/context/router.sh harvest ANALYSIS.md
+bash .opencode/skills/context-manager/router.sh harvest ANALYSIS.md
 ```
 Extracts key concepts from summary files into permanent context.
 
 ### 4. Extract Information
 ```bash
-bash .opencode/skill/context/router.sh extract code-quality.md "naming conventions"
+bash .opencode/skills/context-manager/router.sh extract code-quality.md "naming conventions"
 ```
 Pulls specific information from context files.
 
 ### 5. Compress Files
 ```bash
-bash .opencode/skill/context/router.sh compress .opencode/context/ 100KB
+bash .opencode/skills/context-manager/router.sh compress .opencode/context/ 100KB
 ```
 Reduces large context files to save space.
 
 ### 6. Organize Context
 ```bash
-bash .opencode/skill/context/router.sh organize .opencode/context/
+bash .opencode/skills/context-manager/router.sh organize .opencode/context/
 ```
 Restructures context by concern for better organization.
 
 ### 7. Cleanup Stale Files
 ```bash
-bash .opencode/skill/context/router.sh cleanup .tmp/ 7
+bash .opencode/skills/context-manager/router.sh cleanup .tmp/ 7
 ```
 Removes temporary or old files (older than 7 days).
 
 ### 8. Guided Workflow
 ```bash
-bash .opencode/skill/context/router.sh process "organize authentication context" .opencode/context/
+bash .opencode/skills/context-manager/router.sh process "organize authentication context" .opencode/context/
 ```
 Step-by-step guidance for complex context operations.
 
@@ -468,7 +468,7 @@ process [goal] [scope]
 ## File Structure
 
 ```
-.opencode/skill/context/
+.opencode/skills/context-manager/
 ├── SKILL.md                          # This file
 ├── router.sh                         # CLI router (entry point)
 ├── CONTEXT_SKILL_QUICK_START.md      # Quick start guide

.opencode/skill/context/router.sh → .opencode/skills/context-manager/router.sh

@@ -46,7 +46,7 @@ FEATURES:
   ✓ Clean up stale files
   ✓ Guided workflows
 
-For detailed documentation, see: .opencode/skill/context/SKILL.md
+For detailed documentation, see: .opencode/skills/context-manager/SKILL.md
 HELP
 }
 
@@ -87,42 +87,42 @@ case "$OPERATION" in
     discover)
         echo "📍 DISCOVER: Finding context files..."
         echo "Target: $*"
-        echo "See .opencode/skill/context/SKILL.md for full documentation"
+        echo "See .opencode/skills/context-manager/SKILL.md for full documentation"
         ;;
     fetch)
         echo "📥 FETCH: Retrieving external documentation..."
         echo "Libraries: $*"
-        echo "See .opencode/skill/context/SKILL.md for full documentation"
+        echo "See .opencode/skills/context-manager/SKILL.md for full documentation"
         ;;
     harvest)
         echo "🌾 HARVEST: Extracting context from summaries..."
         echo "Source: $*"
-        echo "See .opencode/skill/context/SKILL.md for full documentation"
+        echo "See .opencode/skills/context-manager/SKILL.md for full documentation"
         ;;
     extract)
         echo "🔍 EXTRACT: Pulling key information..."
         echo "Target: $*"
-        echo "See .opencode/skill/context/SKILL.md for full documentation"
+        echo "See .opencode/skills/context-manager/SKILL.md for full documentation"
         ;;
     compress)
         echo "🗜️  COMPRESS: Reducing file sizes..."
         echo "Target: $*"
-        echo "See .opencode/skill/context/SKILL.md for full documentation"
+        echo "See .opencode/skills/context-manager/SKILL.md for full documentation"
         ;;
     organize)
         echo "📂 ORGANIZE: Restructuring context..."
         echo "Target: $*"
-        echo "See .opencode/skill/context/SKILL.md for full documentation"
+        echo "See .opencode/skills/context-manager/SKILL.md for full documentation"
         ;;
     cleanup)
         echo "🧹 CLEANUP: Removing stale files..."
         echo "Target: $*"
-        echo "See .opencode/skill/context/SKILL.md for full documentation"
+        echo "See .opencode/skills/context-manager/SKILL.md for full documentation"
         ;;
     process)
         echo "⚙️  PROCESS: Guided workflow..."
         echo "Goal: $*"
-        echo "See .opencode/skill/context/SKILL.md for full documentation"
+        echo "See .opencode/skills/context-manager/SKILL.md for full documentation"
         ;;
     *)
         echo "❌ Unknown operation: $OPERATION"

.opencode/skill/context7/README.md → .opencode/skills/context7/README.md

@@ -38,7 +38,7 @@ curl -s "https://context7.com/api/v2/libs/search?libraryName=LIBRARY&query=TOPIC
 curl -s "https://context7.com/api/v2/context?libraryId=LIBRARY_ID&query=OPTIMIZED_QUERY&type=txt"
 ```
 
-See `SKILLS.MD` for detailed API documentation.
+See `SKILL.md` for detailed API documentation.
 
 ## Supported Libraries
 
@@ -76,7 +76,7 @@ User receives current, actionable docs
 
 ## Files
 
-- **`SKILLS.MD`** - Context7 API documentation and usage
+- **`SKILL.md`** - Context7 API documentation and usage
 - **`library-registry.md`** - Supported libraries, aliases, and query patterns
 - **`README.md`** - This file (overview and quick start)
 
@@ -98,5 +98,5 @@ To add a new library to the registry:
 
 ## Related
 
-- **ExternalScout**: `.opencode/agent/subagents/core/external-scout.md`
+- **ExternalScout**: `.opencode/agent/subagents/core/externalscout.md`
 - **ContextScout**: `.opencode/agent/subagents/core/contextscout.md`

.opencode/skill/context7/navigation.md → .opencode/skills/context7/navigation.md

@@ -10,7 +10,7 @@
 context7/
 ├── navigation.md              # This file
 ├── README.md                  # Quick start and workflow
-├── SKILLS.MD                  # Context7 API documentation
+├── SKILL.md                  # Context7 API documentation
 └── library-registry.md        # Supported libraries and query patterns
 ```
 
@@ -21,7 +21,7 @@ context7/
 | Task | Path |
 |------|------|
 | **Quick start** | `README.md` |
-| **API reference** | `SKILLS.MD` |
+| **API reference** | `SKILL.md` |
 | **Supported libraries** | `library-registry.md` (lines 18-181) |
 | **Query patterns** | `library-registry.md` (lines 199-261) |
 | **Add new library** | `library-registry.md` (lines 264-279) |
@@ -33,7 +33,7 @@ context7/
 
 **Using Context7**:
 - Quick start → `README.md`
-- API details → `SKILLS.MD`
+- API details → `SKILL.md`
 
 **Adding Libraries**:
 - Template → `library-registry.md` (lines 272-279)
@@ -41,11 +41,11 @@ context7/
 
 **Integration**:
 - ContextScout workflow → `README.md` (lines 54-73)
-- ExternalScout subagent → `.opencode/agent/subagents/core/external-scout.md`
+- ExternalScout subagent → `.opencode/agent/subagents/core/externalscout.md`
 
 ---
 
 ## Related
 
-- **ExternalScout**: `.opencode/agent/subagents/core/external-scout.md`
+- **ExternalScout**: `.opencode/agent/subagents/core/externalscout.md`
 - **ContextScout**: `.opencode/agent/subagents/core/contextscout.md`

.opencode/skill/smart-router-skill/SKILL.md → .opencode/skills/smart-router-skill/SKILL.md

@@ -38,7 +38,7 @@ This shows how skills can adapt behavior based on simple configuration changes!
 When you ask to use this skill, I'll present the character options and ask you to choose. Then I'll run:
 
 ```bash
-cd .opencode/skill/smart-router-skill
+cd .opencode/skills/smart-router-skill
 bash router.sh --character <your_choice>
 ```
 
@@ -60,7 +60,7 @@ Me: *runs bash router.sh --character yoda*
 
 Want to see different behavior? Edit the config file!
 
-**File:** `.opencode/skill/smart-router-skill/config/personality-config.json`
+**File:** `.opencode/skills/smart-router-skill/config/personality-config.json`
 
 ```json
 {
@@ -127,7 +127,7 @@ Want to see different behavior? Edit the config file!
 
 A bash script that loads a character personality and runs their themed workflow.
 
-**Location:** `.opencode/skill/smart-router-skill/router.sh`
+**Location:** `.opencode/skills/smart-router-skill/router.sh`
 
 ```bash
 # Basic usage

.opencode/skill/task-management/SKILL.md → .opencode/skills/task-management/SKILL.md

@@ -37,19 +37,19 @@ I provide a command-line interface for managing task breakdowns created by the T
 
 ```bash
 # Show all task statuses
-bash .opencode/skill/task-management/router.sh status
+bash .opencode/skills/task-management/router.sh status
 
 # Show next eligible tasks
-bash .opencode/skill/task-management/router.sh next
+bash .opencode/skills/task-management/router.sh next
 
 # Show blocked tasks
-bash .opencode/skill/task-management/router.sh blocked
+bash .opencode/skills/task-management/router.sh blocked
 
 # Mark a task complete
-bash .opencode/skill/task-management/router.sh complete <feature> <seq> "summary"
+bash .opencode/skills/task-management/router.sh complete <feature> <seq> "summary"
 
 # Validate all tasks
-bash .opencode/skill/task-management/router.sh validate
+bash .opencode/skills/task-management/router.sh validate
 ```
 
 ### Command Reference
@@ -72,7 +72,7 @@ bash .opencode/skill/task-management/router.sh validate
 ### Check Overall Progress
 
 ```bash
-$ bash .opencode/skill/task-management/router.sh status
+$ bash .opencode/skills/task-management/router.sh status
 
 [my-feature] My Feature Implementation
   Status: active | Progress: 45% (5/11)
@@ -82,7 +82,7 @@ $ bash .opencode/skill/task-management/router.sh status
 ### Find What's Next
 
 ```bash
-$ bash .opencode/skill/task-management/router.sh next
+$ bash .opencode/skills/task-management/router.sh next
 
 === Ready Tasks (deps satisfied) ===
 
@@ -94,7 +94,7 @@ $ bash .opencode/skill/task-management/router.sh next
 ### Mark Complete
 
 ```bash
-$ bash .opencode/skill/task-management/router.sh complete my-feature 05 "Implemented authentication module"
+$ bash .opencode/skills/task-management/router.sh complete my-feature 05 "Implemented authentication module"
 
 ✓ Marked my-feature/05 as completed
   Summary: Implemented authentication module
@@ -104,7 +104,7 @@ $ bash .opencode/skill/task-management/router.sh complete my-feature 05 "Impleme
 ### Check Dependencies
 
 ```bash
-$ bash .opencode/skill/task-management/router.sh deps my-feature 07
+$ bash .opencode/skills/task-management/router.sh deps my-feature 07
 
 === Dependency Tree: my-feature/07 ===
 
@@ -116,7 +116,7 @@ $ bash .opencode/skill/task-management/router.sh deps my-feature 07
 ### Validate Everything
 
 ```bash
-$ bash .opencode/skill/task-management/router.sh validate
+$ bash .opencode/skills/task-management/router.sh validate
 
 === Validation Results ===
 
@@ -129,7 +129,7 @@ $ bash .opencode/skill/task-management/router.sh validate
 ## Architecture
 
 ```
-.opencode/skill/task-management/
+.opencode/skills/task-management/
 ├── SKILL.md                          # This file
 ├── router.sh                         # CLI router (entry point)
 └── scripts/
@@ -258,7 +258,7 @@ The `validate` command performs comprehensive checks on task files:
 
 Run `validate` regularly to catch issues early:
 ```bash
-bash .opencode/skill/task-management/router.sh validate my-feature
+bash .opencode/skills/task-management/router.sh validate my-feature
 ```
 
 ### 6. Context and Reference Files
@@ -294,7 +294,7 @@ Working agents (CoderAgent, TestEngineer, etc.) execute subtasks and report comp
 task(subagent_type="TaskManager", description="Implement feature X", ...)
 
 # 2. Check what's ready
-bash .opencode/skill/task-management/router.sh next
+bash .opencode/skills/task-management/router.sh next
 
 # 3. Delegate first task to working agent
 task(subagent_type="CoderAgent", description="Implement subtask 01", ...)
@@ -304,36 +304,36 @@ task(subagent_type="CoderAgent", description="Implement subtask 01", ...)
 
 ```bash
 # Check overall status
-bash .opencode/skill/task-management/router.sh status my-feature
+bash .opencode/skills/task-management/router.sh status my-feature
 
 # See what's next
-bash .opencode/skill/task-management/router.sh next my-feature
+bash .opencode/skills/task-management/router.sh next my-feature
 
 # Check what's blocked
-bash .opencode/skill/task-management/router.sh blocked my-feature
+bash .opencode/skills/task-management/router.sh blocked my-feature
 ```
 
 ### Completing Tasks
 
 ```bash
 # After working agent finishes
-bash .opencode/skill/task-management/router.sh complete my-feature 05 "Implemented auth module with JWT support"
+bash .opencode/skills/task-management/router.sh complete my-feature 05 "Implemented auth module with JWT support"
 
 # Check progress
-bash .opencode/skill/task-management/router.sh status my-feature
+bash .opencode/skills/task-management/router.sh status my-feature
 
 # Find next task
-bash .opencode/skill/task-management/router.sh next my-feature
+bash .opencode/skills/task-management/router.sh next my-feature
 ```
 
 ### Validating Everything
 
 ```bash
 # Validate all tasks
-bash .opencode/skill/task-management/router.sh validate
+bash .opencode/skills/task-management/router.sh validate
 
 # Validate specific feature
-bash .opencode/skill/task-management/router.sh validate my-feature
+bash .opencode/skills/task-management/router.sh validate my-feature
 ```
 
 ---
@@ -353,19 +353,19 @@ complete my-feature 05 "Done"
 ### 2. Check Dependencies Before Starting
 ```bash
 # See what a task depends on
-bash .opencode/skill/task-management/router.sh deps my-feature 07
+bash .opencode/skills/task-management/router.sh deps my-feature 07
 ```
 
 ### 3. Identify Parallelizable Work
 ```bash
 # Find tasks that can run in parallel
-bash .opencode/skill/task-management/router.sh parallel my-feature
+bash .opencode/skills/task-management/router.sh parallel my-feature
 ```
 
 ### 4. Regular Validation
 ```bash
 # Validate regularly to catch issues early
-bash .opencode/skill/task-management/router.sh validate
+bash .opencode/skills/task-management/router.sh validate
 ```
 
 ---
@@ -388,11 +388,11 @@ Run `validate` to see specific issues, then check the JSON files in `.tmp/tasks/
 
 ## File Locations
 
-- **Skill**: `.opencode/skill/task-management/`
-- **Router**: `.opencode/skill/task-management/router.sh`
-- **CLI**: `.opencode/skill/task-management/scripts/task-cli.ts`
+- **Skill**: `.opencode/skills/task-management/`
+- **Router**: `.opencode/skills/task-management/router.sh`
+- **CLI**: `.opencode/skills/task-management/scripts/task-cli.ts`
 - **Tasks**: `.tmp/tasks/` (created by TaskManager)
-- **Documentation**: `.opencode/skill/task-management/SKILL.md` (this file)
+- **Documentation**: `.opencode/skills/task-management/SKILL.md` (this file)
 
 ---
 

.opencode/skill/task-management/router.sh → .opencode/skills/task-management/router.sh

@@ -42,7 +42,7 @@ FEATURES:
   ✓ Mark subtasks complete with summaries
   ✓ Validate task integrity
 
-For more info, see: .opencode/skill/task-management/SKILL.md
+For more info, see: .opencode/skills/task-management/SKILL.md
 HELP
 }
 

.opencode/skill/task-management/scripts/task-cli.ts → .opencode/skills/task-management/scripts/task-cli.ts

@@ -300,11 +300,45 @@ function cmdValidate(feature?: string): void {
   const features = feature ? [feature] : getFeatureDirs();
   let hasErrors = false;
 
+  const validTaskStatuses = new Set(['active', 'completed', 'blocked', 'archived']);
+  const validSubtaskStatuses = new Set(['pending', 'in_progress', 'completed', 'blocked']);
+
+  const requiredTaskFields = [
+    'id',
+    'name',
+    'status',
+    'objective',
+    'context_files',
+    'exit_criteria',
+    'subtask_count',
+    'completed_count',
+    'created_at',
+    'completed_at',
+  ];
+
+  const requiredSubtaskFields = [
+    'id',
+    'seq',
+    'title',
+    'status',
+    'depends_on',
+    'parallel',
+    'context_files',
+    'acceptance_criteria',
+    'deliverables',
+    'agent_id',
+    'started_at',
+    'completed_at',
+    'completion_summary',
+  ];
+
+  const hasField = (obj: any, field: string): boolean => Object.prototype.hasOwnProperty.call(obj, field);
+  const isStringArray = (value: any): boolean => Array.isArray(value) && value.every(v => typeof v === 'string');
+
   console.log('\n=== Validation Results ===\n');
 
   for (const f of features) {
     const errors: string[] = [];
-    const warnings: string[] = [];
 
     // Check task.json exists
     const task = loadTask(f);
@@ -314,16 +348,106 @@ function cmdValidate(feature?: string): void {
 
     // Load and validate subtasks
     const subtasks = loadSubtasks(f);
+    const seqCounts = new Map<string, number>();
+    for (const s of subtasks) {
+      const seq = typeof s.seq === 'string' ? s.seq : '';
+      seqCounts.set(seq, (seqCounts.get(seq) || 0) + 1);
+    }
     const seqs = new Set(subtasks.map(s => s.seq));
 
+    if (task) {
+      // Required fields in task.json
+      for (const field of requiredTaskFields) {
+        if (!hasField(task, field)) {
+          errors.push(`task.json: missing required field '${field}'`);
+        }
+      }
+
+      // Task ID should match feature slug
+      if (task.id !== f) {
+        errors.push(`task.json id ('${task.id}') should match feature slug ('${f}')`);
+      }
+
+      // Task status should be valid
+      if (!validTaskStatuses.has(task.status)) {
+        errors.push(`task.json: invalid status '${task.status}'`);
+      }
+
+      // Basic type checks for key task fields
+      if (!isStringArray(task.context_files)) {
+        errors.push('task.json: context_files must be string[]');
+      }
+      if (hasField(task, 'reference_files') && task.reference_files !== undefined && !isStringArray(task.reference_files)) {
+        errors.push('task.json: reference_files must be string[] when present');
+      }
+      if (!isStringArray(task.exit_criteria)) {
+        errors.push('task.json: exit_criteria must be string[]');
+      }
+      if (typeof task.subtask_count !== 'number') {
+        errors.push('task.json: subtask_count must be number');
+      }
+      if (typeof task.completed_count !== 'number') {
+        errors.push('task.json: completed_count must be number');
+      }
+    }
+
     for (const s of subtasks) {
+      // Required fields in subtask files
+      for (const field of requiredSubtaskFields) {
+        if (!hasField(s, field)) {
+          errors.push(`${s.seq || '??'}: missing required field '${field}'`);
+        }
+      }
+
+      // Sequence format and uniqueness
+      if (!/^\d{2}$/.test(s.seq)) {
+        errors.push(`${s.seq}: sequence must be 2 digits (e.g., 01, 02)`);
+      }
+      if ((seqCounts.get(s.seq) || 0) > 1) {
+        errors.push(`${s.seq}: duplicate sequence number`);
+      }
+
       // Check ID format
       if (!s.id.startsWith(f)) {
         errors.push(`${s.seq}: ID should start with feature name`);
       }
 
+      // Status should be valid
+      if (!validSubtaskStatuses.has(s.status)) {
+        errors.push(`${s.seq}: invalid status '${s.status}'`);
+      }
+
+      // Type checks
+      if (!isStringArray(s.depends_on)) {
+        errors.push(`${s.seq}: depends_on must be string[]`);
+      }
+      if (typeof s.parallel !== 'boolean') {
+        errors.push(`${s.seq}: parallel must be boolean`);
+      }
+      if (!isStringArray(s.context_files)) {
+        errors.push(`${s.seq}: context_files must be string[]`);
+      }
+      if (hasField(s, 'reference_files') && s.reference_files !== undefined && !isStringArray(s.reference_files)) {
+        errors.push(`${s.seq}: reference_files must be string[] when present`);
+      }
+      if (!isStringArray(s.acceptance_criteria)) {
+        errors.push(`${s.seq}: acceptance_criteria must be string[]`);
+      } else if (s.acceptance_criteria.length === 0) {
+        errors.push(`${s.seq}: No acceptance criteria defined`);
+      }
+      if (!isStringArray(s.deliverables)) {
+        errors.push(`${s.seq}: deliverables must be string[]`);
+      } else if (s.deliverables.length === 0) {
+        errors.push(`${s.seq}: No deliverables defined`);
+      }
+
+      // Self dependency is invalid
+      if (Array.isArray(s.depends_on) && s.depends_on.includes(s.seq)) {
+        errors.push(`${s.seq}: task cannot depend on itself`);
+      }
+
       // Check for missing dependencies
-      for (const dep of s.depends_on) {
+      for (const dep of (Array.isArray(s.depends_on) ? s.depends_on : [])) {
         if (!seqs.has(dep)) {
           errors.push(`${s.seq}: depends on non-existent task ${dep}`);
         }
@@ -348,14 +472,6 @@ function cmdValidate(feature?: string): void {
         return false;
       };
       checkCircular(s.seq, []);
-
-      // Warnings
-      if (s.acceptance_criteria.length === 0) {
-        warnings.push(`${s.seq}: No acceptance criteria defined`);
-      }
-      if (s.deliverables.length === 0) {
-        warnings.push(`${s.seq}: No deliverables defined`);
-      }
     }
 
     // Check counts match
@@ -365,16 +481,13 @@ function cmdValidate(feature?: string): void {
 
     // Print results
     console.log(`[${f}]`);
-    if (errors.length === 0 && warnings.length === 0) {
+    if (errors.length === 0) {
       console.log('  ✓ All checks passed');
     } else {
       for (const e of errors) {
         console.log(`  ✗ ERROR: ${e}`);
         hasErrors = true;
       }
-      for (const w of warnings) {
-        console.log(`  ⚠ WARNING: ${w}`);
-      }
     }
     console.log();
   }

CHANGELOG.md

@@ -33,9 +33,9 @@ All notable changes to this project will be documented in this file.
   - Added to registry with `skill:context7` dependency
 
 - **Context7 Skill**: Registered in system for external documentation fetching
-  - Path: `.opencode/skill/context7/SKILLS.MD`
-  - Library registry: `.opencode/skill/context7/library-registry.md`
-  - Navigation guide: `.opencode/skill/context7/navigation.md`
+  - Path: `.opencode/skills/context7/SKILL.md`
+  - Library registry: `.opencode/skills/context7/library-registry.md`
+  - Navigation guide: `.opencode/skills/context7/navigation.md`
 
 ### Changed
 - **ContextScout v5.1.0**: Optimized with research-backed prompt engineering patterns

install.sh

@@ -513,10 +513,10 @@ show_install_location_menu() {
     echo "     Examples:"
     case "$PLATFORM" in
         Windows)
-            echo "       ${CYAN}C:/Users/username/my-agents${NC} or ${CYAN}~/my-agents${NC}"
+            echo -e "       ${CYAN}C:/Users/username/my-agents${NC} or ${CYAN}~/my-agents${NC}"
             ;;
         *)
-            echo "       ${CYAN}/home/username/my-agents${NC} or ${CYAN}~/my-agents${NC}"
+            echo -e "       ${CYAN}/home/username/my-agents${NC} or ${CYAN}~/my-agents${NC}"
             ;;
     esac
     echo ""
@@ -952,7 +952,7 @@ show_collision_report() {
             tools+=("$file")
         elif [[ $file == *"/plugin/"* ]]; then
             plugins+=("$file")
-        elif [[ $file == *"/skill/"* ]]; then
+        elif [[ $file == *"/skills/"* ]]; then
             skills+=("$file")
         elif [[ $file == *"/context/"* ]]; then
             contexts+=("$file")
@@ -1235,12 +1235,12 @@ show_post_install() {
     # Check if env.example was installed
     if [ -f "${INSTALL_DIR}/env.example" ] || [ -f "env.example" ]; then
         echo "2. Copy env.example to .env and configure:"
-        echo "   ${CYAN}cp env.example .env${NC}"
+        echo -e "   ${CYAN}cp env.example .env${NC}"
         echo "3. Start using OpenCode agents:"
     else
         echo "2. Start using OpenCode agents:"
     fi
-    echo "   ${CYAN}opencode${NC}"
+    echo -e "   ${CYAN}opencode${NC}"
     echo ""
     
     # Show installation location info
@@ -1396,26 +1396,26 @@ main() {
                 echo ""
                 echo -e "${BOLD}Examples:${NC}"
                 echo ""
-                echo "  ${CYAN}# Interactive mode (choose location and components)${NC}"
+                echo -e "  ${CYAN}# Interactive mode (choose location and components)${NC}"
                 echo "  $0"
                 echo ""
-                echo "  ${CYAN}# Quick install with default location (.opencode/)${NC}"
+                echo -e "  ${CYAN}# Quick install with default location (.opencode/)${NC}"
                 echo "  $0 developer"
                 echo ""
-                echo "  ${CYAN}# Install to global location (Linux/macOS)${NC}"
+                echo -e "  ${CYAN}# Install to global location (Linux/macOS)${NC}"
                 echo "  $0 developer --install-dir ~/.config/opencode"
                 echo ""
-                echo "  ${CYAN}# Install to global location (Windows Git Bash)${NC}"
+                echo -e "  ${CYAN}# Install to global location (Windows Git Bash)${NC}"
                 echo "  $0 developer --install-dir ~/.config/opencode"
                 echo ""
-                echo "  ${CYAN}# Install to custom location${NC}"
+                echo -e "  ${CYAN}# Install to custom location${NC}"
                 echo "  $0 essential --install-dir ~/my-agents"
                 echo ""
-                echo "  ${CYAN}# Using environment variable${NC}"
+                echo -e "  ${CYAN}# Using environment variable${NC}"
                 echo "  export OPENCODE_INSTALL_DIR=~/.config/opencode"
                 echo "  $0 developer"
                 echo ""
-                echo "  ${CYAN}# Install from URL (non-interactive)${NC}"
+                echo -e "  ${CYAN}# Install from URL (non-interactive)${NC}"
                 echo "  curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s developer"
                 echo ""
                 echo -e "${BOLD}Platform Support:${NC}"

package.json

@@ -16,7 +16,7 @@
     ".opencode/profiles/",
     ".opencode/prompts/",
     ".opencode/scripts/",
-    ".opencode/skill/",
+    ".opencode/skills/",
     ".opencode/tool/",
     ".opencode/config.json",
     ".opencode/opencode.json",
@@ -80,6 +80,7 @@
     "dev:test": "cd evals/framework && npm test",
     "dev:clean": "cd evals/framework && rm -rf dist node_modules && npm install",
     "validate:registry": "bun run scripts/registry/validate-registry.ts",
+    "validate:context-links": "bun run scripts/validation/validate-markdown-links.ts",
     "validate:registry:verbose": "bun run scripts/registry/validate-registry.ts -v",
     "validate:registry:fix": "bun run scripts/registry/validate-registry.ts -f"
   },

packages/compatibility-layer/docs/migration-guides/claude-to-oac.md

@@ -148,7 +148,7 @@ You are a senior developer.
 | **Permissions** | Binary modes only | Granular per-path rules |
 | **Temperature** | Not supported | Full control (0.0-2.0) |
 | **Max steps** | Not supported | Configurable limit |
-| **Skills path** | `.claude/skills/` | `.opencode/skill/` |
+| **Skills path** | `.claude/skills/` | `.opencode/skills/` |
 
 ### 4. Feature Mapping
 
@@ -430,7 +430,7 @@ Features that don't fully translate between formats:
 | Max steps | Not supported | Configurable | Add limit after migration |
 | Granular permissions | Binary modes | Per-path rules | Expand after migration |
 | Permission mode `acceptEdits` | Supported | No direct equivalent | Use `permission: { edit: "allow" }` |
-| Skill directory structure | `.claude/skills/` | `.opencode/skill/` | Move and rename |
+| Skill directory structure | `.claude/skills/` | `.opencode/skills/` | Move and rename |
 | Agent directory | `.claude/agents/` | `.opencode/agent/` | Move and rename |
 
 ### 7. Validation
@@ -587,7 +587,7 @@ Valid events: `PreToolUse`, `PostToolUse`, `PermissionRequest`, `AgentStart`, `A
 .claude/skills/my-skill/SKILL.md
 
 # OAC location
-.opencode/skill/my-skill/SKILL.md
+.opencode/skills/my-skill/SKILL.md
 ```
 
 Update skill references in agent:

registry.json

@@ -705,7 +705,7 @@
         "id": "task-management",
         "name": "Task Management",
         "type": "skill",
-        "path": ".opencode/skill/task-management/SKILL.md",
+        "path": ".opencode/skills/task-management/SKILL.md",
         "description": "Task management CLI for tracking and managing feature subtasks with status, dependencies, and validation",
         "tags": [
           "tasks",
@@ -715,16 +715,16 @@
         "dependencies": [],
         "category": "essential",
         "files": [
-          ".opencode/skill/task-management/SKILL.md",
-          ".opencode/skill/task-management/router.sh",
-          ".opencode/skill/task-management/scripts/task-cli.ts"
+          ".opencode/skills/task-management/SKILL.md",
+          ".opencode/skills/task-management/router.sh",
+          ".opencode/skills/task-management/scripts/task-cli.ts"
         ]
       },
       {
         "id": "smart-router-skill",
         "name": "Smart Router Skill",
         "type": "skill",
-        "path": ".opencode/skill/smart-router-skill/SKILL.md",
+        "path": ".opencode/skills/smart-router-skill/SKILL.md",
         "description": "Movie character personality skill with configurable missions and themed workflows",
         "tags": [
           "routing",
@@ -734,19 +734,19 @@
         "dependencies": [],
         "category": "specialized",
         "files": [
-          ".opencode/skill/smart-router-skill/SKILL.md",
-          ".opencode/skill/smart-router-skill/router.sh",
-          ".opencode/skill/smart-router-skill/config/personality-config.json",
-          ".opencode/skill/smart-router-skill/scripts/sherlock-workflow.sh",
-          ".opencode/skill/smart-router-skill/scripts/stark-workflow.sh",
-          ".opencode/skill/smart-router-skill/scripts/yoda-workflow.sh"
+          ".opencode/skills/smart-router-skill/SKILL.md",
+          ".opencode/skills/smart-router-skill/router.sh",
+          ".opencode/skills/smart-router-skill/config/personality-config.json",
+          ".opencode/skills/smart-router-skill/scripts/sherlock-workflow.sh",
+          ".opencode/skills/smart-router-skill/scripts/stark-workflow.sh",
+          ".opencode/skills/smart-router-skill/scripts/yoda-workflow.sh"
         ]
       },
       {
         "id": "context7",
         "name": "Context7",
         "type": "skill",
-        "path": ".opencode/skill/context7/SKILLS.MD",
+        "path": ".opencode/skills/context7/SKILL.md",
         "description": "Fetch live, version-specific documentation for external libraries and frameworks via Context7 API",
         "tags": [
           "documentation",
@@ -757,17 +757,17 @@
         "dependencies": [],
         "category": "essential",
         "files": [
-          ".opencode/skill/context7/SKILLS.MD",
-          ".opencode/skill/context7/README.md",
-          ".opencode/skill/context7/library-registry.md",
-          ".opencode/skill/context7/navigation.md"
+          ".opencode/skills/context7/SKILL.md",
+          ".opencode/skills/context7/README.md",
+          ".opencode/skills/context7/library-registry.md",
+          ".opencode/skills/context7/navigation.md"
         ]
       },
       {
-        "id": "context",
+        "id": "context-manager",
         "name": "Context Manager",
         "type": "skill",
-        "path": ".opencode/skill/context/SKILL.md",
+        "path": ".opencode/skills/context-manager/SKILL.md",
         "description": "Comprehensive context management with 8 operations: discover, fetch, harvest, extract, compress, organize, cleanup, and process. Integrates with ContextScout and ExternalScout with lazy loading and clear guidance.",
         "tags": [
           "context-management",
@@ -783,8 +783,8 @@
         ],
         "category": "essential",
         "files": [
-          ".opencode/skill/context/SKILL.md",
-          ".opencode/skill/context/router.sh"
+          ".opencode/skills/context-manager/SKILL.md",
+          ".opencode/skills/context-manager/router.sh"
         ]
       }
     ],
@@ -2066,7 +2066,7 @@
         "name": "Delegation Workflow Reference",
         "type": "context",
         "path": ".opencode/context/core/workflows/delegation.md",
-        "description": "Quick reference to delegation workflow (see task-delegation.md for full content)",
+        "description": "Quick reference to delegation workflow (see task-delegation-basics.md and related split files)",
         "tags": [
           "workflows",
           "delegation",
@@ -3365,4 +3365,4 @@
       }
     }
   }
-}
+}

scripts/registry/validate-registry.ts

@@ -364,7 +364,7 @@ function scanDirectory(dir: string, registryPaths: Set<string>): void {
       if (relPath.endsWith('/plugin/agent-validator.ts')) continue;
       
       // Skip skill support files (only SKILL.md needs to be in registry, all other files are copied with the skill)
-      if (relPath.includes('/skill/') && !entry.name.match(/^SKILL\.md$/i)) continue;
+      if (relPath.includes('/skills/') && !entry.name.match(/^SKILL\.md$/i)) continue;
       
       // Check if in registry
       if (!registryPaths.has(relPath)) {

scripts/tests/test-installer-files.sh

@@ -202,12 +202,12 @@ print_summary() {
     echo -e "${BOLD}Test Summary${NC}"
     echo -e "${BOLD}═══════════════════════════════════════════════════════════════${NC}"
     echo ""
-    echo "Total files tested:  ${CYAN}$((SUCCESS_COUNT + FAIL_COUNT))${NC}"
-    echo "Files accessible:    ${GREEN}${SUCCESS_COUNT}${NC}"
-    echo "Files NOT FOUND:     ${RED}${FAIL_COUNT}${NC}"
+    echo -e "Total files tested:  ${CYAN}$((SUCCESS_COUNT + FAIL_COUNT))${NC}"
+    echo -e "Files accessible:    ${GREEN}${SUCCESS_COUNT}${NC}"
+    echo -e "Files NOT FOUND:     ${RED}${FAIL_COUNT}${NC}"
     
     if [ ${#SKIPPED_FILES[@]} -gt 0 ]; then
-        echo "Skipped:             ${YELLOW}${#SKIPPED_FILES[@]}${NC}"
+        echo -e "Skipped:             ${YELLOW}${#SKIPPED_FILES[@]}${NC}"
     fi
     
     echo ""
@@ -223,7 +223,7 @@ print_summary() {
             echo "    URL: ${RAW_URL}/${path}"
         done
         echo ""
-        echo "${YELLOW}These files need to be:${NC}"
+        echo -e "${YELLOW}These files need to be:${NC}"
         echo "  1. Added to the repository, OR"
         echo "  2. Removed from registry.json"
         echo ""

scripts/validation/markdown-link-skip-patterns.txt

@@ -0,0 +1,25 @@
+# Ignore placeholders and template rules.
+\{.*\}
+\*
+
+# Ignore common template path placeholders.
+literal:path/to/
+literal:another/file
+literal:optional/file
+literal:category/
+literal:/your-
+literal:/my-
+literal:/existing-
+literal:.opencode/command/build-context-system.md
+literal:.opencode/command/validate-repo.md
+
+# Ignore external and anchor links (also filtered in code, kept for clarity).
+^https?://
+^mailto:
+^#
+
+# Temporary legacy exclusions (to keep CI green while docs are migrated).
+^\.opencode/context/openagents-repo/.+?\.md$
+^\.opencode/command/prompt-engineering/.+?\.md$
+^\.opencode/agent/meta/.+?\.md$
+^\.opencode/command/openagents/.+?\.md$

scripts/validation/validate-markdown-links.ts

@@ -0,0 +1,214 @@
+#!/usr/bin/env bun
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join, normalize } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+const SKIP_RULES_FILE = join(REPO_ROOT, 'scripts', 'validation', 'markdown-link-skip-patterns.txt')
+const TARGET_DIRS = [
+  '.opencode/agent',
+  '.opencode/skills',
+  '.opencode/command',
+  '.opencode/context'
+]
+
+type MissingRef = {
+  source: string
+  line: number
+  target: string
+  resolved: string
+  kind: 'link' | 'path'
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function parseRegexRule(rule: string): RegExp {
+  const trimmed = rule.trim()
+
+  if (trimmed.startsWith('/') && trimmed.length > 2) {
+    const lastSlash = trimmed.lastIndexOf('/')
+    if (lastSlash > 0) {
+      const pattern = trimmed.slice(1, lastSlash)
+      const flags = trimmed.slice(lastSlash + 1)
+      return new RegExp(pattern, flags)
+    }
+  }
+
+  return new RegExp(trimmed)
+}
+
+function loadSkipPatterns(): RegExp[] {
+  if (!existsSync(SKIP_RULES_FILE)) {
+    throw new Error(`Skip rules file not found: ${SKIP_RULES_FILE}`)
+  }
+
+  const lines = readFileSync(SKIP_RULES_FILE, 'utf-8').split('\n')
+  const patterns: RegExp[] = []
+
+  for (const line of lines) {
+    const rule = line.trim()
+    if (!rule || rule.startsWith('#')) continue
+
+    // Literal rule: literal:foo/bar
+    if (rule.startsWith('literal:')) {
+      const literal = rule.slice('literal:'.length).trim()
+      if (!literal) continue
+      patterns.push(new RegExp(escapeRegExp(literal)))
+      continue
+    }
+
+    patterns.push(parseRegexRule(rule))
+  }
+
+  return patterns
+}
+
+function shouldSkipFile(filePath: string, skipPatterns: RegExp[]): boolean {
+  const relPath = filePath.replace(`${REPO_ROOT}/`, '')
+  return skipPatterns.some((pattern) => pattern.test(relPath))
+}
+
+function walkMdFiles(dir: string, out: string[], skipPatterns: RegExp[]): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === 'build') continue
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      walkMdFiles(full, out, skipPatterns)
+      continue
+    }
+    if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+      if (!shouldSkipFile(full, skipPatterns)) {
+        out.push(full)
+      }
+    }
+  }
+}
+
+function lineFromIndex(content: string, index: number): number {
+  return content.slice(0, index).split('\n').length
+}
+
+function shouldSkip(rawTarget: string, skipPatterns: RegExp[]): boolean {
+  const value = rawTarget.trim()
+  if (!value) return true
+  if (value.startsWith('http://') || value.startsWith('https://')) return true
+  if (value.startsWith('mailto:') || value.startsWith('#')) return true
+  return skipPatterns.some((pattern) => pattern.test(value))
+}
+
+function cleanupTarget(rawTarget: string): string {
+  let target = rawTarget.trim()
+  if (!target) return target
+
+  if (target.startsWith('<') && target.endsWith('>')) {
+    target = target.slice(1, -1)
+  }
+
+  const firstSpace = target.indexOf(' ')
+  if (firstSpace >= 0) {
+    target = target.slice(0, firstSpace)
+  }
+
+  target = target.replace(/^@/, '')
+  target = target.split('#')[0]
+  target = target.split('?')[0]
+  return target
+}
+
+function resolveTarget(sourceFile: string, rawTarget: string): string {
+  const target = cleanupTarget(rawTarget)
+  if (target.startsWith('.opencode/')) return join(REPO_ROOT, target)
+  if (target.startsWith('/')) return join(REPO_ROOT, target.slice(1))
+  return join(dirname(sourceFile), target)
+}
+
+function collectMissingRefs(file: string, skipPatterns: RegExp[]): MissingRef[] {
+  const content = readFileSync(file, 'utf-8')
+  const rel = file.replace(`${REPO_ROOT}/`, '')
+  const missing: MissingRef[] = []
+
+  const linkRegex = /\[[^\]]*\]\(([^)]+)\)/g
+  for (const match of content.matchAll(linkRegex)) {
+    const rawTarget = match[1]
+    if (!rawTarget) continue
+    if (shouldSkip(rawTarget, skipPatterns)) continue
+
+    const cleaned = cleanupTarget(rawTarget)
+    if (!cleaned) continue
+    if (!cleaned.includes('.md') && !cleaned.startsWith('.opencode/')) continue
+
+    const resolved = normalize(resolveTarget(file, cleaned))
+    if (!existsSync(resolved)) {
+      missing.push({
+        source: rel,
+        line: lineFromIndex(content, match.index ?? 0),
+        target: rawTarget,
+        resolved: resolved.replace(`${REPO_ROOT}/`, ''),
+        kind: 'link',
+      })
+    }
+  }
+
+  const pathRegex = /@?(\.opencode\/[A-Za-z0-9_./-]+\.md)/g
+  for (const match of content.matchAll(pathRegex)) {
+    const rawTarget = match[1]
+    if (!rawTarget) continue
+    if (shouldSkip(rawTarget, skipPatterns)) continue
+
+    const cleaned = cleanupTarget(rawTarget)
+    const resolved = normalize(resolveTarget(file, cleaned))
+    if (!existsSync(resolved)) {
+      missing.push({
+        source: rel,
+        line: lineFromIndex(content, match.index ?? 0),
+        target: rawTarget,
+        resolved: resolved.replace(`${REPO_ROOT}/`, ''),
+        kind: 'path',
+      })
+    }
+  }
+
+  return missing
+}
+
+function dedupe(refs: MissingRef[]): MissingRef[] {
+  const seen = new Set<string>()
+  const out: MissingRef[] = []
+  for (const ref of refs) {
+    const key = `${ref.source}:${ref.line}:${ref.target}:${ref.kind}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(ref)
+  }
+  return out
+}
+
+const skipPatterns = loadSkipPatterns()
+
+const files: string[] = []
+for (const dir of TARGET_DIRS) {
+  const absolute = join(REPO_ROOT, dir)
+  if (existsSync(absolute)) walkMdFiles(absolute, files, skipPatterns)
+}
+
+let missing: MissingRef[] = []
+for (const file of files) {
+  missing = missing.concat(collectMissingRefs(file, skipPatterns))
+}
+
+missing = dedupe(missing)
+
+if (missing.length === 0) {
+  console.log(`OK: validated ${files.length} markdown files, no broken internal references found.`)
+  process.exit(0)
+}
+
+console.log(`ERROR: found ${missing.length} broken internal markdown references:`)
+for (const ref of missing) {
+  console.log(`- ${ref.source}:${ref.line} [${ref.kind}] ${ref.target} -> ${ref.resolved}`)
+}
+
+process.exit(1)