Update framework skills,docs and linting pre-commit

.agents/skill-extensions/qa/EXTENSION.md

@@ -0,0 +1,15 @@
+# QA Skill Extension
+
+This file is repo-specific companion guidance for the base `qa` skill.
+Read it after `.agents/skills/qa/SKILL.md` and treat it as additive guidance for this repository.
+
+## Placeholder
+
+No additional repo-specific QA rules are defined yet.
+
+This extension path is reserved for future guidance such as:
+
+- Codex harness-specific QA workflows
+- repo-specific reviewer evidence expectations
+- screenshot, inline comment, or artifact conventions
+- local verification commands or escalation patterns

.agents/skill-extensions/worker/EXTENSION.md

@@ -0,0 +1,21 @@
+# Worker Skill Extension
+
+This file is repo-specific companion guidance for the base `worker` skill.
+Read it after `.agents/skills/worker/SKILL.md` and treat it as additive guidance for this repository.
+
+## Codex Harness Guidance
+
+This project is using Codex worker agents.
+
+When the approved PLAN or planning algorithm allows safe parallel execution:
+
+- prefer using the harness capability that spawns subagents for independent tasks
+- maximize parallel execution only when dependency order and file ownership rules remain valid
+- keep file ownership disjoint across subagents whenever possible
+- if tasks overlap in files or require tightly coupled edits, serialize them instead of forcing parallelism
+- the parent worker remains responsible for integration, verification, and truthful board state updates
+
+## Intent
+
+This extension exists to push the worker toward safe harness-aware parallelism in this repo.
+It supplements the base worker skill and does not weaken its locking, testing, escalation, or truthfulness requirements.

.agents/skills/coordinator-agent/SKILL.md → .agents/skills/coordinator/SKILL.md

@@ -1,11 +1,37 @@
-# Coordinator Agent Skill
+---
+name: coordinator
+description: Coordinates execution of an approved PLAN by materializing tasks, managing the live task graph, routing blockers and rework, and maintaining PLAN or approved SPEC changes during execution.
+---
+
+# Coordinator Skill
+
+## Repo Extension
+
+Before you start, check whether this repo provides extra local guidance at `.agents/skill-extensions/coordinator/EXTENSION.md`.
+If that file exists, read it after this skill and treat it as friendly repo-specific extension guidance for how `coordinator` should be applied in this application.
+
+## Mission
 
-**Role**: Orchestrates execution once the plan is approved. Creates tasks from the PLAN via API, hands out tasks to workers, manages the task graph, responds to blockers, creates rework tasks from QA content. Adjusts the PLAN as required when the change mechanism is invoked.
+Turn an approved PLAN into an actively managed execution flow.
+
+Primary outputs:
+
+- a truthful live task graph in Zazz Board
+- rework tasks created from QA-authored rework content
+- updated PLAN content, and approved SPEC updates when the change mechanism is invoked
+
+This skill coordinates execution. It does not implement feature code itself.
+
+## Role
+
+Orchestrates execution once the plan is approved. Creates tasks from the PLAN via API, hands out tasks to workers, manages the task graph, responds to blockers, creates rework tasks from QA content, and adjusts the PLAN when the change mechanism is invoked.
 
 **Agents Using This Skill**: Coordinator (one per deliverable during execution)
 
 **TDD emphasis**: Every task must have explicit test requirements—what tests to create, what tests to run. No task is complete without passing tests. Rework tasks include the failing test that demonstrates the issue.
 
+**Docs root convention**: Use the repo docs root declared in `AGENTS.md` as the base for framework docs. Example paths in this skill may use `<DOCS_ROOT>/...` as shorthand.
+
 ---
 
 ## System Prompt
@@ -39,7 +65,7 @@ During MVP:
 
 **Trigger**: Subscribe to Zazz Board API pub/sub for plan approval events. When a deliverable's plan is approved, it moves to Ready and a plan-approved event is published.
 
-**Input**: Approved .zazz/deliverables/{deliverable-name}-PLAN.md (created by the Planner)
+**Input**: Approved `<DOCS_ROOT>/deliverables/{deliverable-name}-PLAN.md` (created by the Planner)
 
 **Process**:
 1. Read the PLAN to understand phases, steps, and task definitions
@@ -112,6 +138,6 @@ export ZAZZ_STATE_DIR="${ZAZZ_WORKSPACE}/.zazz"
 
 ## Example Workflow
 
-See `.agents/skills/coordinator-agent/examples/` for:
+See `.agents/skills/coordinator/examples/` for:
 - example-plan.md - Sample PLAN document (output of Planner)
 - example-task-graph.json - Sample task dependency graph