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

Author: InteLigent

.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>