@mrciphersmith/keryx 0.2.72 → 0.2.73

package/src/gdskills/bundled/skills/orchestration/feature-analyzer/orchestrator-prompt.md

@@ -308,7 +308,7 @@ FOCUS AREA:
 ```javascript
 Task({
   description: "Feature analysis: pipeline-variables",
-  subagent_type: "general",
+  subagent_type: "general-purpose",
   prompt: "<сгенерированный промпт выше>"
 })
 ```

package/src/gdskills/bundled/skills/orchestration/feature-dev/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: feature-dev
-description: "7-phase feature development workflow: requirements → design → implement → test → review → fix → PR. Full cycle from idea or GitHub issue to merge-ready PR. Confirms requirements and design with user before autonomous execution."
+description: "Use when taking a feature from idea or GitHub issue all the way to a merge-ready PR in one guided workflow."
 triggers:
   - "/feature-dev"
   - "Develop feature"
@@ -9,12 +9,18 @@ triggers:
   - "Feature from scratch"
 metadata:
   author: "MrCipherSmith"
-  version: "1.0.0"
+  version: "2.0.0"
   category: "workflow"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
 
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill entirely.
+This skill is for interactive feature development sessions only.
+Proceed directly with your assigned task.
+</SUBAGENT-STOP>
+
 # Feature Development (7-Phase)
 
 End-to-end feature development workflow from idea to merge-ready PR.
@@ -25,66 +31,104 @@ End-to-end feature development workflow from idea to merge-ready PR.
 - `/feature-dev #<issue>` — start from a GitHub issue
 - `/feature-dev --resume` — resume interrupted feature-dev (checks for existing worktree/branch)
 
-## 7-Phase Architecture
+## 8-Phase Architecture
+
+> **Rules always loaded:** `tdd-workflow.mdc`, `implementation-doc-mandate.mdc`, `error-handling.mdc`
+> **Sub-agents used:** `tests-creator` (before implement), `code-verifier` (after implement)
+
+### Phase 1: REQUIREMENTS + SPEC
 
-### Phase 1: REQUIREMENTS
 1. Parse input (description or GitHub issue via `gh issue view`)
 2. Clarify ambiguities — ask the user up to 3 questions max
-3. Produce a brief spec:
+3. Produce the **Implementation Spec** (per `implementation-doc-mandate.mdc`):
    - **What**: feature description in 2-3 sentences
    - **Why**: user value / business reason
    - **Scope**: what's in, what's explicitly out
    - **Acceptance criteria**: testable bullet points
-4. **Get user confirmation before proceeding**
+   - **Approach**: which files will change, key design decisions
+   - **Test strategy**: framework, which scenarios will be covered
+4. **Save spec** to `.feature-spec.md` in project root (add to .gitignore if not already)
+5. **Get user confirmation before proceeding**
 
 ### Phase 2: DESIGN
+
 1. Research the codebase:
    - Find related modules via search tools
    - Read neighboring implementations for patterns
-   - Check existing tests for testing conventions
+   - **Detect test framework** (package.json, existing test files) — needed for tests-creator
 2. Produce implementation plan:
    - Files to create/modify (with brief description of changes)
    - Dependencies or packages needed
    - Data model changes if any
    - Estimated complexity: S / M / L
-3. **Get user confirmation on the plan**
+3. Load relevant rules from `.metaproject/rules/core/` based on what will be built:
+   - Always: `tdd-workflow.mdc`, `error-handling.mdc`, `solid-principles.mdc`
+   - API/service code: `api-contracts.mdc`, `clean-architecture.mdc`
+   - Database: `database-patterns.mdc`
+   - Async: `async-patterns.mdc`
+   - Security-sensitive: `security-baseline.mdc`
+4. **Get user confirmation on the plan**
 
 ### Phase 3: PREPARE
-1. Create a feature branch: `git checkout -b feat/<name>`
-2. If large feature, consider `git worktree add` for isolation
-3. Install any new dependencies
-
-### Phase 4: IMPLEMENT
-1. Implement changes file by file, following the plan
-2. Follow existing code patterns discovered in Phase 2
-3. After each logical chunk, run available checks:
-   - Lint: `npm run lint` or equivalent
-   - Type-check: `npx tsc --noEmit` or equivalent
-   - Fix issues immediately before moving on
-
-### Phase 5: TEST
-1. Write tests matching the project's testing patterns
-2. Unit tests for new functions/modules
-3. Integration tests for API/data flow changes
-4. Run full test suite
-5. Fix failing tests (max 3 attempts per test)
-
-### Phase 6: REVIEW (Self)
+
+1. Create a feature branch: `wt switch -c feat/<name>`
+2. Install any new dependencies
+
+### Phase 4: TESTS-CREATOR (TDD — RED phase)
+
+**Run before writing any implementation code.**
+
+1. For each group of acceptance criteria, invoke `tests-creator`:
+   - Input: acceptance criteria from Phase 1 spec + target files from Phase 2 plan
+   - tests-creator detects framework and generates failing test stubs
+   - tests-creator commits the stubs and verifies RED state
+2. Confirm test stubs are in place and failing before proceeding to Phase 5
+
+### Phase 5: IMPLEMENT (TDD — GREEN phase)
+
+1. Implement changes file by file, following the plan from Phase 2
+2. Goal: make the failing tests from Phase 4 GREEN
+3. Follow existing code patterns and loaded rules
+4. After each file group, run quick inline check: `npx tsc --noEmit` (type errors only)
+5. Commit with conventional message after each logical chunk
+
+### Phase 6: VERIFY (code-verifier gate)
+
+Run `code-verifier` on the full diff:
+
+```
+Invoke: skills/orchestration/code-verifier/SKILL.md
+Input:  codebase_path=<project_root>, scope=changed, base_branch=<base>
+```
+
+- `gate: PASS` → proceed to Phase 7
+- `gate: FAIL` → fix findings, re-run code-verifier (max 2 cycles)
+- Still FAIL after 2 cycles → report blocker to user, stop
+
+### Phase 7: REVIEW (Self)
+
 1. Launch the `review-orchestrator` skill on own changes
 2. Or run a focused self-review:
    - `git diff main...HEAD` — review the full diff
    - Check for: TODOs left behind, console.logs, hardcoded values
-   - Verify all acceptance criteria from Phase 1
+   - Verify all acceptance criteria from Phase 1 spec
 3. Fix any findings (max 2 review-fix cycles)
+4. Re-run `code-verifier` after any fixes
+
+### Phase 8: DELIVER + CHANGE REPORT
 
-### Phase 7: DELIVER
-1. Final checks: lint + type-check + tests all pass
-2. Commit with conventional message: `feat(<scope>): <description>`
-3. Push branch
-4. Create PR:
+1. Push branch
+2. Create PR:
    - Link to issue if applicable
-   - Include acceptance criteria as checklist
-   - Add test plan
+   - Include acceptance criteria checklist
+   - Add test plan and code-verifier results
+3. **Produce Change Report** (per `implementation-doc-mandate.mdc`):
+   - Files created/modified with descriptions
+   - Test count and results
+   - code-verifier gate result
+   - Acceptance criteria checklist (checked off)
+   - Commits list
+4. Print Change Report to user
 5. Report PR URL to user
 
 ## Status Updates
@@ -97,9 +141,25 @@ At each phase transition, report progress:
 
 ## Rules
 
-- ALWAYS get user confirmation after Phase 1 (requirements) and Phase 2 (design)
-- Phases 4-6 are autonomous — no user interaction needed
+- ALWAYS get user confirmation after Phase 1 (requirements + spec) and Phase 2 (design)
+- Phases 4-7 are autonomous — no user interaction needed
 - If stuck for >3 attempts on any step, report the blocker and ask user
-- NEVER skip Phase 5 (testing) even if user says "skip tests"
-- NEVER commit broken code (lint/type-check must pass)
-- Keep commits atomic: one commit per logical change, not one giant commit
+- NEVER skip Phase 4 (tests-creator) even if user says "skip tests" — this is TDD, not optional testing
+- NEVER skip Phase 6 (code-verifier) — it is the quality gate, not a suggestion
+- NEVER commit broken code (code-verifier gate must pass before PR)
+- Keep commits atomic: one commit per logical chunk, not one giant commit
+- ALWAYS produce the Change Report in Phase 8 — even if the PR was not created
+
+## Red Flags — Stop and re-read this skill if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "Requirements are clear enough, I'll skip the design phase" | Skipping design means discovering mismatches after code is written, not before |
+| "The user already approved this approach verbally, no need to document" | Undocumented approval is invisible to reviewers and future agents; it doesn't exist |
+| "Tests can be written after — implementation first to check if the approach works" | Writing tests after implementation makes you test what you built, not what was required |
+| "This phase isn't needed for such a straightforward feature" | Every skipped phase is a deferred bug report |
+| "I understand the requirements, confirmation is just a formality" | The confirmation step exists to catch the gap between what you understood and what was meant |
+
+**IRON LAW 1: NEVER START IMPLEMENTING BEFORE THE SPEC IS WRITTEN AND CONFIRMED.**
+**IRON LAW 2: NEVER WRITE IMPLEMENTATION CODE BEFORE TESTS-CREATOR HAS GENERATED FAILING STUBS.**
+**IRON LAW 3: NEVER DELIVER WITHOUT A PASSING CODE-VERIFIER GATE AND A CHANGE REPORT.**

package/src/gdskills/bundled/skills/orchestration/feature-dev/SKILL.cursor.md

@@ -1,6 +1,6 @@
 ---
 name: feature-dev
-description: "7-phase feature development workflow: requirements → design → implement → test → review → fix → PR. Full cycle from idea or GitHub issue to merge-ready PR. Confirms requirements and design with user before autonomous execution."
+description: "Use when taking a feature from idea or GitHub issue all the way to a merge-ready PR in one guided workflow."
 triggers:
   - "/feature-dev"
   - "Develop feature"
@@ -9,12 +9,18 @@ triggers:
   - "Feature from scratch"
 metadata:
   author: "MrCipherSmith"
-  version: "1.0.0"
+  version: "2.0.0"
   category: "workflow"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
 
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill entirely.
+This skill is for interactive feature development sessions only.
+Proceed directly with your assigned task.
+</SUBAGENT-STOP>
+
 # Feature Development (7-Phase)
 
 End-to-end feature development workflow from idea to merge-ready PR.
@@ -25,66 +31,104 @@ End-to-end feature development workflow from idea to merge-ready PR.
 - `/feature-dev #<issue>` — start from a GitHub issue
 - `/feature-dev --resume` — resume interrupted feature-dev (checks for existing worktree/branch)
 
-## 7-Phase Architecture
+## 8-Phase Architecture
+
+> **Rules always loaded:** `tdd-workflow.mdc`, `implementation-doc-mandate.mdc`, `error-handling.mdc`
+> **Sub-agents used:** `tests-creator` (before implement), `code-verifier` (after implement)
+
+### Phase 1: REQUIREMENTS + SPEC
 
-### Phase 1: REQUIREMENTS
 1. Parse input (description or GitHub issue via `gh issue view`)
 2. Clarify ambiguities — ask the user up to 3 questions max
-3. Produce a brief spec:
+3. Produce the **Implementation Spec** (per `implementation-doc-mandate.mdc`):
    - **What**: feature description in 2-3 sentences
    - **Why**: user value / business reason
    - **Scope**: what's in, what's explicitly out
    - **Acceptance criteria**: testable bullet points
-4. **Get user confirmation before proceeding**
+   - **Approach**: which files will change, key design decisions
+   - **Test strategy**: framework, which scenarios will be covered
+4. **Save spec** to `.feature-spec.md` in project root (add to .gitignore if not already)
+5. **Get user confirmation before proceeding**
 
 ### Phase 2: DESIGN
+
 1. Research the codebase:
    - Find related modules via search tools
    - Read neighboring implementations for patterns
-   - Check existing tests for testing conventions
+   - **Detect test framework** (package.json, existing test files) — needed for tests-creator
 2. Produce implementation plan:
    - Files to create/modify (with brief description of changes)
    - Dependencies or packages needed
    - Data model changes if any
    - Estimated complexity: S / M / L
-3. **Get user confirmation on the plan**
+3. Load relevant rules from `.metaproject/rules/core/` based on what will be built:
+   - Always: `tdd-workflow.mdc`, `error-handling.mdc`, `solid-principles.mdc`
+   - API/service code: `api-contracts.mdc`, `clean-architecture.mdc`
+   - Database: `database-patterns.mdc`
+   - Async: `async-patterns.mdc`
+   - Security-sensitive: `security-baseline.mdc`
+4. **Get user confirmation on the plan**
 
 ### Phase 3: PREPARE
-1. Create a feature branch: `git checkout -b feat/<name>`
-2. If large feature, consider `git worktree add` for isolation
-3. Install any new dependencies
-
-### Phase 4: IMPLEMENT
-1. Implement changes file by file, following the plan
-2. Follow existing code patterns discovered in Phase 2
-3. After each logical chunk, run available checks:
-   - Lint: `npm run lint` or equivalent
-   - Type-check: `npx tsc --noEmit` or equivalent
-   - Fix issues immediately before moving on
-
-### Phase 5: TEST
-1. Write tests matching the project's testing patterns
-2. Unit tests for new functions/modules
-3. Integration tests for API/data flow changes
-4. Run full test suite
-5. Fix failing tests (max 3 attempts per test)
-
-### Phase 6: REVIEW (Self)
+
+1. Create a feature branch: `wt switch -c feat/<name>`
+2. Install any new dependencies
+
+### Phase 4: TESTS-CREATOR (TDD — RED phase)
+
+**Run before writing any implementation code.**
+
+1. For each group of acceptance criteria, invoke `tests-creator`:
+   - Input: acceptance criteria from Phase 1 spec + target files from Phase 2 plan
+   - tests-creator detects framework and generates failing test stubs
+   - tests-creator commits the stubs and verifies RED state
+2. Confirm test stubs are in place and failing before proceeding to Phase 5
+
+### Phase 5: IMPLEMENT (TDD — GREEN phase)
+
+1. Implement changes file by file, following the plan from Phase 2
+2. Goal: make the failing tests from Phase 4 GREEN
+3. Follow existing code patterns and loaded rules
+4. After each file group, run quick inline check: `npx tsc --noEmit` (type errors only)
+5. Commit with conventional message after each logical chunk
+
+### Phase 6: VERIFY (code-verifier gate)
+
+Run `code-verifier` on the full diff:
+
+```
+Invoke: skills/orchestration/code-verifier/SKILL.md
+Input:  codebase_path=<project_root>, scope=changed, base_branch=<base>
+```
+
+- `gate: PASS` → proceed to Phase 7
+- `gate: FAIL` → fix findings, re-run code-verifier (max 2 cycles)
+- Still FAIL after 2 cycles → report blocker to user, stop
+
+### Phase 7: REVIEW (Self)
+
 1. Launch the `review-orchestrator` skill on own changes
 2. Or run a focused self-review:
    - `git diff main...HEAD` — review the full diff
    - Check for: TODOs left behind, console.logs, hardcoded values
-   - Verify all acceptance criteria from Phase 1
+   - Verify all acceptance criteria from Phase 1 spec
 3. Fix any findings (max 2 review-fix cycles)
+4. Re-run `code-verifier` after any fixes
+
+### Phase 8: DELIVER + CHANGE REPORT
 
-### Phase 7: DELIVER
-1. Final checks: lint + type-check + tests all pass
-2. Commit with conventional message: `feat(<scope>): <description>`
-3. Push branch
-4. Create PR:
+1. Push branch
+2. Create PR:
    - Link to issue if applicable
-   - Include acceptance criteria as checklist
-   - Add test plan
+   - Include acceptance criteria checklist
+   - Add test plan and code-verifier results
+3. **Produce Change Report** (per `implementation-doc-mandate.mdc`):
+   - Files created/modified with descriptions
+   - Test count and results
+   - code-verifier gate result
+   - Acceptance criteria checklist (checked off)
+   - Commits list
+4. Print Change Report to user
 5. Report PR URL to user
 
 ## Status Updates
@@ -97,9 +141,25 @@ At each phase transition, report progress:
 
 ## Rules
 
-- ALWAYS get user confirmation after Phase 1 (requirements) and Phase 2 (design)
-- Phases 4-6 are autonomous — no user interaction needed
+- ALWAYS get user confirmation after Phase 1 (requirements + spec) and Phase 2 (design)
+- Phases 4-7 are autonomous — no user interaction needed
 - If stuck for >3 attempts on any step, report the blocker and ask user
-- NEVER skip Phase 5 (testing) even if user says "skip tests"
-- NEVER commit broken code (lint/type-check must pass)
-- Keep commits atomic: one commit per logical change, not one giant commit
+- NEVER skip Phase 4 (tests-creator) even if user says "skip tests" — this is TDD, not optional testing
+- NEVER skip Phase 6 (code-verifier) — it is the quality gate, not a suggestion
+- NEVER commit broken code (code-verifier gate must pass before PR)
+- Keep commits atomic: one commit per logical chunk, not one giant commit
+- ALWAYS produce the Change Report in Phase 8 — even if the PR was not created
+
+## Red Flags — Stop and re-read this skill if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "Requirements are clear enough, I'll skip the design phase" | Skipping design means discovering mismatches after code is written, not before |
+| "The user already approved this approach verbally, no need to document" | Undocumented approval is invisible to reviewers and future agents; it doesn't exist |
+| "Tests can be written after — implementation first to check if the approach works" | Writing tests after implementation makes you test what you built, not what was required |
+| "This phase isn't needed for such a straightforward feature" | Every skipped phase is a deferred bug report |
+| "I understand the requirements, confirmation is just a formality" | The confirmation step exists to catch the gap between what you understood and what was meant |
+
+**IRON LAW 1: NEVER START IMPLEMENTING BEFORE THE SPEC IS WRITTEN AND CONFIRMED.**
+**IRON LAW 2: NEVER WRITE IMPLEMENTATION CODE BEFORE TESTS-CREATOR HAS GENERATED FAILING STUBS.**
+**IRON LAW 3: NEVER DELIVER WITHOUT A PASSING CODE-VERIFIER GATE AND A CHANGE REPORT.**

package/src/gdskills/bundled/skills/orchestration/issue-analyzer/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: issue-analyzer
-description: "Autonomous GitHub issue analysis and decomposition into atomic implementation tasks. Fetches issue data via gh CLI, analyzes codebase for affected areas, decomposes into Gherkin Scenarios with full context for implementer sub-agents. Use when: decomposing issues for AI implementation, planning task breakdown, preparing work for task-implementer agents."
+description: "Use when decomposing a GitHub issue into atomic tasks for AI implementation, planning task breakdown, or preparing work for task-implementer agents."
 triggers:
   - "Analyze issue"
   - "Decompose issue"
@@ -9,8 +9,9 @@ triggers:
   - "Plan issue implementation"
 metadata:
   author: "MrCipherSmith"
-  version: "1.0.0"
+  version: "1.1.0"
   category: "analysis"
+  agent_worthy: true
   compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
 ---
@@ -22,7 +23,7 @@ license: "MIT"
 Analyzes a GitHub issue and decomposes it into atomic implementation tasks that can be dispatched to `task-implementer` sub-agents. Designed to run autonomously as a sub-agent — no user interaction required.
 
 **Input:** GitHub issue URL (or repo + number) + codebase path(s)
-**Output:** Gherkin Feature with one Scenario per task, each containing full context for implementation
+**Output:** JSON analysis object with one task entry per atomic task, each containing full context for implementation
 
 ## When to Use
 
@@ -36,7 +37,7 @@ Analyzes a GitHub issue and decomposes it into atomic implementation tasks that
 Phase 1: COLLECT   →  Fetch all issue data from GitHub
 Phase 2: ANALYZE   →  Extract intent, find affected code areas
 Phase 3: DECOMPOSE →  Break into atomic tasks with dependencies
-Phase 4: FORMALIZE →  Emit Gherkin Feature with Scenarios
+Phase 4: FORMALIZE →  Emit structured JSON analysis object
 ```
 
 ---
@@ -48,7 +49,7 @@ Issue Analyzer Progress:
 - [ ] Phase 1: Collect issue data from GitHub
 - [ ] Phase 2: Analyze intent and search codebase
 - [ ] Phase 3: Decompose into atomic tasks
-- [ ] Phase 4: Formalize as Gherkin output
+- [ ] Phase 4: Formalize as JSON output
 ```
 
 ### Phase 1: COLLECT
@@ -201,49 +202,102 @@ TASKS:
 
 ### Phase 4: FORMALIZE
 
-Convert the task list into Gherkin Feature format.
+Convert the task list into a structured JSON object for reliable machine parsing.
 
 **Output structure:**
 
-```gherkin
-Feature: Issue #<N> — <Issue Title>
-
-  Background: Issue Context
-    Given GitHub issue #<N> "<title>"
-    And issue type is "<issue_type>"
-    And repository "<owner/repo>"
-    And target codebase at "<codebase_path>"
-
-    | Aspect | Detail |
-    | Intent | <1-2 sentence intent> |
-    | Labels | <comma-separated labels> |
-    | Assignees | <comma-separated assignees> |
-    | Total Tasks | <N> |
-
-  Scenario: task-1 — <Task Name>
-    Given task type is "<task_type>"
-    And estimated complexity is "<low|medium|high>"
-    And this task has no dependencies
-
-    | Aspect | Detail |
-    | Description | <full description of what to implement> |
-    | Target Files | <comma-separated file paths> |
-    | Acceptance Criteria | <criteria 1>; <criteria 2> |
-    | Context | <relevant code context, key types, function signatures> |
-    | Existing Tests | <paths to existing test files, or "none"> |
-    | Existing Stories | <paths to existing story files, or "none"> |
-    | Module Patterns | <brief note on how similar code is written in this module> |
-
-  Scenario: task-2 — <Task Name>
-    Given task type is "<task_type>"
-    And estimated complexity is "<low|medium|high>"
-    And this task depends on "task-1"
-
-    | Aspect | Detail |
-    | ... | ... |
-
-  Scenario: task-N — <Task Name>
-    ...
+```json
+{
+  "issue": {
+    "number": "<issue_number>",
+    "title": "<issue_title>",
+    "type": "<bug|feature|enhancement|refactoring|chore>",
+    "repo": "<owner/repo>",
+    "intent": "<1-2 sentence intent summary>",
+    "labels": ["<label1>", "<label2>"],
+    "assignees": ["<user1>"],
+    "total_tasks": "<N>"
+  },
+  "tasks": [
+    {
+      "task_id": "task-1",
+      "task_name": "<Descriptive Task Name>",
+      "task_type": "<ui_component|store_logic|service_api|refactoring|fix|mixed>",
+      "complexity": "<low|medium|high>",
+      "dependencies": [],
+      "description": "<full description of what to implement>",
+      "target_files": ["src/path/file.ts"],
+      "acceptance_criteria": ["criterion 1", "criterion 2"],
+      "context": "<relevant code context, key types, function signatures>",
+      "existing_tests": ["src/path/file.test.ts"],
+      "existing_stories": [],
+      "module_patterns": "<how similar code is written in this module>",
+      "requires_tests_creator": true
+    },
+    {
+      "task_id": "task-2",
+      "task_name": "<Descriptive Task Name>",
+      "task_type": "<type>",
+      "complexity": "<low|medium|high>",
+      "dependencies": ["task-1"],
+      "description": "<description>",
+      "target_files": ["src/path/other.ts"],
+      "acceptance_criteria": ["criterion 1"],
+      "context": "<context>",
+      "existing_tests": [],
+      "existing_stories": [],
+      "module_patterns": "<patterns>",
+      "requires_tests_creator": true
+    }
+  ],
+  "dependency_order": ["task-1", "task-2"]
+}
+```
+
+**Each task object is the explicit context for task-implementer.**
+
+When `job-orchestrator` dispatches `task-implementer`, it passes the task object directly as the subagent's context. This means:
+- `task.context`, `task.target_files`, and `task.acceptance_criteria` are **required fields** — never omit or leave them empty when the information exists.
+- `task.context` must contain enough information for the implementer to start without reading the full codebase: key types, function signatures, relevant patterns, and any design decisions.
+- `task.module_patterns` must describe how similar code is written nearby — the implementer uses this for style consistency.
+
+**Red Flag: "The implementer can figure out the context from the codebase"**
+
+→ It cannot — not reliably. An implementer with no context will make assumptions, produce inconsistent code, or ask questions. Every omitted field is a gap the implementer will fill with a guess.
+
+## Reporting Results
+
+Every final response to the orchestrator MUST begin with `STATUS: DONE` or `STATUS: BLOCKED`.
+
+```
+STATUS: DONE
+
+## Analysis
+[structured JSON analysis object]
+```
+
+Use `STATUS: BLOCKED` only if the issue cannot be fetched (404) or the codebase cannot be accessed.
+
+**IRON LAW: THE FIRST LINE OF YOUR FINAL RESPONSE IS ALWAYS "STATUS: DONE" OR "STATUS: BLOCKED". THE JSON ANALYSIS FOLLOWS AFTER.**
+
+**Rules for JSON output:**
+- `dependency_order` must be topologically sorted — tasks with no dependencies come first
+- `task_id` format: `task-1`, `task-2`, ... (sequential)
+- `dependencies` lists task_ids that must complete before this task
+- All string arrays may be empty `[]` but not omitted
+- `context` and `module_patterns` may be empty string if not applicable
+- `requires_tests_creator` is always `true` — orchestrator must dispatch `tests-creator` before `task-implementer` for each task
+- Output the JSON block as the **final message** to the orchestrator, preceded by a brief summary (issue type, number of tasks, overall complexity)
+
+**Return format** (final message to orchestrator):
+```
+Analysis complete.
+- Issue type: <type>
+- Total tasks: <N>
+- Overall complexity: <low|medium|high>
+- Dependency order: task-1 → task-2 → task-3
+
+<json block>
 ```
 
 ---
@@ -280,22 +334,34 @@ This skill is designed to run fully autonomously. The following settings control
 1. **DO NOT** ask the user any questions. All input comes from the input contract.
 2. **DO NOT** modify any files. This is a read-only analysis skill.
 3. **DO NOT** make assumptions about implementation approach — describe WHAT, not HOW.
-4. **DO** include enough context in each Scenario for a task-implementer to start without asking questions.
+4. **DO** include enough context in each task entry for a task-implementer to start without asking questions.
 5. **DO** respect the 3-layer architecture: Service → Store → Component ordering.
 6. **DO** identify existing tests and stories so implementer knows what to update.
 7. **DO** note module patterns (how similar code is written nearby) for consistency.
-8. Return the Gherkin Feature as your **final message** to the orchestrator.
+8. Return the JSON analysis result as your **final message** to the orchestrator.
 
 ---
 
+## Red Flags — Stop and re-read this skill if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "The issue title is clear enough, I'll skip reading the full body" | Acceptance criteria, repro steps, and constraints live in the body — the title is just a label |
+| "I know this codebase, I don't need to search for affected files" | Prior knowledge drifts; the search step catches files that have changed since you last looked |
+| "I'll create one big task instead of decomposing — simpler to track" | A monolithic task cannot be parallelized or independently verified; it defeats the whole system |
+| "The dependencies between tasks seem obvious, no need to map them" | Untracked dependencies cause agents to overwrite each other's work or build on stale code |
+| "The issue body is mostly boilerplate, I've got the gist" | Edge cases and acceptance criteria are often buried in what looks like boilerplate |
+
+**IRON LAW: ALWAYS READ THE FULL ISSUE BODY AND SEARCH THE CODEBASE BEFORE DECOMPOSING INTO TASKS.**
+
 ## Job Context Awareness
 
 When dispatched by `job-orchestrator`, the prompt MAY include:
 
 ```
 JOB_NAME:     <job-name>
-JOBS_ROOT:    .metaproject/jobs
-CONTEXT_PATH: .metaproject/jobs/<job-name>/ai/context.md
+JOBS_ROOT:    <JOBS_ROOT>
+CONTEXT_PATH: <JOBS_ROOT>/<job-name>/ai/context.md
 ```
 
 If `CONTEXT_PATH` is provided and the file exists, read it during Phase 2 (ANALYZE) to: