Fix 47 validation warnings: frontmatter, hooks, gitignore, TOC embeds

Emasoft · Emasoft · commit eca59d50bde1 · 2026-03-03T11:49:52.000+01:00
- Remove unknown frontmatter fields (workflow-instruction, procedure)
  from all 16 SKILL.md files (32 warnings fixed)
- Increase hook timeouts from 5ms/10ms to 30000ms (2 warnings fixed)
- Add node_modules/ to .gitignore (1 warning fixed)
- Fix TOC embed comments in amoa-developer-communication and
  amoa-orchestration-commands SKILL.md to use exact headings as
  extracted by validator (12 warnings fixed)
- Document git-hooks/ and shared/ directories in README.md

Remaining 3 warnings are irreducible (non-standard dirs, bash scripts).
Validation: 0 CRITICAL, 0 MAJOR, 0 MINOR, 0 NIT, 3 WARNING, 952 PASSED.
diff --git a/.gitignore b/.gitignore
@@ -36,6 +36,9 @@ Thumbs.db
 venv/
 env/
 
+# Node.js
+node_modules/
+
 # Dev folders (NEVER PUBLISH - development artifacts only)
 # Wildcard pattern catches all: docs_dev, scripts_dev, tests_dev, samples_dev,
 # examples_dev, downloads_dev, libs_dev, builds_dev, etc.
diff --git a/README.md b/README.md
@@ -73,6 +73,17 @@ The Orchestrator Agent handles **task distribution, agent coordination, and prog
 | `amoa-polling-reminder` | UserPromptSubmit | Remind to poll progress |
 | `amoa-file-tracker` | PostToolUse | Track file modifications |
 
+## Project Structure Notes
+
+### Non-Standard Directories
+
+- **`git-hooks/`** — Contains git hook scripts (pre-push) for plugin validation before pushing
+- **`shared/`** — Shared resources used across skills and agents
+
+### Shell Scripts Compatibility
+
+3 bash/shell scripts (`.sh` files) require **Linux or macOS** and are not natively available on Windows. Windows users should use WSL2 or equivalent.
+
 ## Workflow
 
 1. Receives plan from Architect (via Assistant Manager)
diff --git a/hooks/hooks.json b/hooks/hooks.json
@@ -23,7 +23,7 @@
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/amoa_check_verification_status.py",
-            "timeout": 10
+            "timeout": 30000
           }
         ]
       }
@@ -36,7 +36,7 @@
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/amoa_check_polling_due.py",
-            "timeout": 5
+            "timeout": 30000
           }
         ]
       }
diff --git a/skills/amoa-agent-replacement/SKILL.md b/skills/amoa-agent-replacement/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 user-invocable: false
 context: fork
 agent: amoa-main
-workflow-instruction: "support"
-procedure: "support-skill"
 ---
 
 # Agent Replacement Skill
diff --git a/skills/amoa-checklist-compilation-patterns/SKILL.md b/skills/amoa-checklist-compilation-patterns/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 context: fork
 user-invocable: false
 agent: amoa-main
-workflow-instruction: "support"
-procedure: "support-skill"
 ---
 
 # Checklist Compiler Skill
diff --git a/skills/amoa-developer-communication/SKILL.md b/skills/amoa-developer-communication/SKILL.md
@@ -12,8 +12,6 @@ metadata:
 context: fork
 user-invocable: false
 agent: amoa-main
-workflow-instruction: "Steps 14, 15, 22"
-procedure: "proc-clarify-tasks, proc-handle-feedback, proc-handle-failed-pr"
 ---
 
 # Developer Communication Skill
@@ -360,8 +358,14 @@ Copy this checklist and track your progress:
 ## Resources
 
 - [pr-comment-writing.md](references/pr-comment-writing.md) - Code review comment patterns
+<!-- TOC: 1 Writing constructive code review comments | 1 The praise-suggestion-question framework | 2 Balancing thoroughness with developer time -->
 - [issue-communication.md](references/issue-communication.md) - Bug report and feature request handling
+<!-- TOC: 1 Bug report response workflow | 1 Acknowledgment template | 2 Reproduction confirmation -->
 - [technical-explanation.md](references/technical-explanation.md) - Explaining technical decisions
+<!-- TOC: 1 Explaining technical decisions | 1 The context-decision-consequences format | 2 Acknowledging tradeoffs honestly -->
 - [conflict-resolution.md](references/conflict-resolution.md) - Handling disagreements
+<!-- TOC: 1 Disagreeing professionally | 1 Separating the idea from the person | 2 Starting with understanding -->
 - [status-updates.md](references/status-updates.md) - Progress reporting
+<!-- TOC: ### Part 1: Progress Reports | 1 Progress report format -->
 - [templates-for-humans.md](references/templates-for-humans.md) - PR and commit templates
+<!-- TOC: 1 Pull Request description template | 1 Summary section | 2 Changes section with bullets -->
diff --git a/skills/amoa-github-action-integration/SKILL.md b/skills/amoa-github-action-integration/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 agent: amoa-main
 context: fork
 user-invocable: false
-workflow-instruction: "support"
-procedure: "support-skill"
 ---
 
 # Claude Code Action Integration
diff --git a/skills/amoa-implementer-interview-protocol/SKILL.md b/skills/amoa-implementer-interview-protocol/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 context: fork
 user-invocable: false
 agent: amoa-main
-workflow-instruction: "Steps 14, 19"
-procedure: "proc-clarify-tasks, proc-complete-task"
 ---
 
 # Implementer Interview Protocol
diff --git a/skills/amoa-kanban-management/SKILL.md b/skills/amoa-kanban-management/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 context: fork
 user-invocable: false
 agent: amoa-main
-workflow-instruction: "Steps 12, 13, 14, 15"
-procedure: "proc-populate-kanban, proc-update-kanban-status, proc-add-columns, proc-sync-kanban"
 ---
 
 # Kanban Board Management Skill
diff --git a/skills/amoa-label-taxonomy/SKILL.md b/skills/amoa-label-taxonomy/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 context: fork
 user-invocable: false
 agent: amoa-main
-workflow-instruction: "support"
-procedure: "support-skill"
 ---
 
 # AMOA Label Taxonomy
diff --git a/skills/amoa-messaging-templates/SKILL.md b/skills/amoa-messaging-templates/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 context: fork
 user-invocable: false
 agent: amoa-main
-workflow-instruction: "Step 20"
-procedure: "proc-request-pr-review"
 ---
 
 # AMOA Shared Communication Templates
diff --git a/skills/amoa-module-management/SKILL.md b/skills/amoa-module-management/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 user-invocable: false
 context: fork
 agent: amoa-main
-workflow-instruction: "Steps 11, 16"
-procedure: "proc-create-task-docs, proc-update-tasks"
 ---
 
 # Module Management Commands Skill
diff --git a/skills/amoa-orchestration-commands/SKILL.md b/skills/amoa-orchestration-commands/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 user-invocable: false
 context: fork
 agent: amoa-main
-workflow-instruction: "support"
-procedure: "support-skill"
 ---
 
 # Orchestration Commands Skill
@@ -428,8 +426,14 @@ Copy this checklist and track your progress:
 ## Resources
 
 - [start-orchestration-procedure.md](references/start-orchestration-procedure.md) - Starting orchestration
+<!-- TOC: 1 When to start orchestration phase | 2 Prerequisites verification checklist | 3 Command syntax and options -->
 - [status-monitoring.md](references/status-monitoring.md) - Reading status output
+<!-- TOC: 1 Understanding the orchestration status output | 2 Reading module status indicators | 3 Interpreting agent registry information -->
 - [orchestration-loop-mechanics.md](references/orchestration-loop-mechanics.md) - Loop behavior
+<!-- TOC: 1 What the orchestrator loop does | 2 Task source monitoring and priority | 3 Iteration counting and max iterations -->
 - [cancellation-cleanup.md](references/cancellation-cleanup.md) - Cancellation procedures
+<!-- TOC: 1 When to cancel vs let loop complete naturally | 2 Cancellation procedure step-by-step | 3 Cleanup of state files and locks -->
 - [state-file-format.md](references/state-file-format.md) - State file schemas
+<!-- TOC: 1 Loop state file format and fields | 2 Execution phase state file format | 3 Frontmatter field definitions -->
 - [troubleshooting.md](references/troubleshooting.md) - Common issues and solutions
+<!-- TOC: 1 Loop won't start - common causes | 2 Stop hook not firing - debugging steps | 3 Tasks showing as pending incorrectly -->
diff --git a/skills/amoa-orchestration-patterns/SKILL.md b/skills/amoa-orchestration-patterns/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 context: fork
 user-invocable: false
 agent: amoa-main
-workflow-instruction: "Steps 10, 12, 23, 24"
-procedure: "proc-decompose-design, proc-create-task-plan, proc-handle-successful-pr, proc-iterate"
 ---
 
 # Orchestration Patterns Skill
diff --git a/skills/amoa-progress-monitoring/SKILL.md b/skills/amoa-progress-monitoring/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 context: fork
 user-invocable: false
 agent: amoa-main
-workflow-instruction: "Step 17"
-procedure: "proc-execute-task"
 ---
 
 # Progress Monitoring Skill
diff --git a/skills/amoa-remote-agent-coordinator/SKILL.md b/skills/amoa-remote-agent-coordinator/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 context: fork
 user-invocable: false
 agent: amoa-main
-workflow-instruction: "Step 17"
-procedure: "proc-execute-task"
 ---
 
 # Remote Agent Coordinator
diff --git a/skills/amoa-task-distribution/SKILL.md b/skills/amoa-task-distribution/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 context: fork
 user-invocable: false
 agent: amoa-main
-workflow-instruction: "Steps 13, 16, 18, 22"
-procedure: "proc-populate-kanban, proc-update-tasks, proc-update-kanban-status, proc-handle-failed-pr"
 ---
 
 # Task Distribution Skill
diff --git a/skills/amoa-two-phase-mode/SKILL.md b/skills/amoa-two-phase-mode/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 context: fork
 user-invocable: false
 agent: amoa-main
-workflow-instruction: "Step 10"
-procedure: "proc-decompose-design"
 ---
 
 # Two-Phase Mode Skill
diff --git a/skills/amoa-verification-patterns/SKILL.md b/skills/amoa-verification-patterns/SKILL.md
@@ -9,8 +9,6 @@ metadata:
 agent: amoa-main
 context: fork
 user-invocable: false
-workflow-instruction: "Step 19"
-procedure: "proc-complete-task"
 ---
 
 # Verification Patterns for AMOA (AI Maestro Orchestrator Agent)

Original file line number	Diff line number	Diff line change
`@@ -23,7 +23,7 @@`
`23`	`23`	`{`
`24`	`24`	`"type": "command",`
`25`	`25`	`"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/amoa_check_verification_status.py",`
`26`		`- "timeout": 10`
	`26`	`+ "timeout": 30000`
`27`	`27`	`}`
`28`	`28`	`]`
`29`	`29`	`}`
`@@ -36,7 +36,7 @@`
`36`	`36`	`{`
`37`	`37`	`"type": "command",`
`38`	`38`	`"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/amoa_check_polling_due.py",`
`39`		`- "timeout": 5`
	`39`	`+ "timeout": 30000`
`40`	`40`	`}`
`41`	`41`	`]`
`42`	`42`	`}`