@mrciphersmith/keryx 0.2.97 → 0.2.99

package/src/gdskills/bundled/skills/orchestration/task-implementer/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: task-implementer
 model_tier: standard
-description: "Use when implementing a single decomposed task from issue-analyzer end-to-end, or executing autonomous code changes from a JSON task object."
+description: "Use when implementing a single task out of an issue-analyzer breakdown end-to-end, or executing autonomous code changes from a JSON task object. NOT for: splitting an issue into that breakdown in the first place (use issue-analyzer)."
 triggers:
-  - "Implement task"
+  - "implement task"
+  - "execute task"
+  - "atomic task"
   - "Execute task scenario"
   - "Code this task"
   - "Run task-implementer"
@@ -11,7 +13,7 @@ triggers:
 metadata:
   author: "MrCipherSmith"
   version: "1.3.1"
-  category: "implementation"
+  category: "orchestration"
   agent_worthy: true
   compatible_harnesses: "claude,cursor,codex,zed,opencode"
 license: "MIT"
@@ -183,7 +185,7 @@ This step is read-only and inline; do not spawn a subagent for it.
   (`input-contract.schema.json`). Empty means none; the string `"none"` is not a
   legal value and a request carrying it is refused by 1.4
 - Read each file listed in either array
-- Understand existing test patterns (describe/it structure, mocks, fixtures)
+- Understand existing test patterns (describe/it structure, mocks, fixtures) and, for every file in `existing_stories`, the story patterns it uses (`Meta`/`StoryObj` shape, how variants are declared, how callbacks are stubbed) — 4.4 builds on what you record here
 
 **2.3 Read module neighbors:**
 - List sibling files in the same directory as each target file
@@ -222,18 +224,6 @@ Based on what you're implementing, load and follow the relevant project rules.
 
 Rules live at `.metaproject/rules/core/<rule>.mdc` on every harness — that is the
 one tree `keryx init` installs and the one every build of this skill reads.
-Cursor additionally mirrors them under `.cursor/rules/core/<rule>.mdc`; when both
-are present they are copies of the same file, so read either.
-
-**Output of Phase 2:** Mental model of the implementation:
-```
-RESEARCH_SUMMARY:
-  target_files_status: [{path, exists: bool, line_count, key_exports}]
-  test_pattern: <describe structure, assertion style>
-  story_pattern: <Meta/StoryObj, args pattern>
-  module_conventions: <naming, imports, exports, TS patterns>
-  relevant_rules_loaded: [<rule names>]
-```
 
 ### Phase 3: PLAN
 
@@ -288,13 +278,6 @@ Execute the change plan. Write production-quality code.
 5. Component/UI layer implementation (make component tests GREEN)
 6. Stories (if needed)
 
-**4.1 Implementation order (TDD Mode — test_case_specs provided):**
-1. Read all test stubs from `test_case_specs.test_files`
-2. Understand the expected API shape from test assertions
-3. Implement types/interfaces to satisfy test imports
-4. Implement code layer by layer until all tests are GREEN
-5. Stories (if needed)
-
 **4.2 Code standards (always follow):**
 - TypeScript strict mode — no `any`, no `as` casts unless justified
 - Use project path aliases for imports (`@components/...`, `@utils/...`)
@@ -304,28 +287,28 @@ Execute the change plan. Write production-quality code.
 - Follow existing module patterns discovered in Phase 2
 
 **4.3 Test standards:**
-- Unit tests: Vitest with `describe`/`it`, `@testing-library/react` for components
-- Use `data-testid` for test selectors
-- Follow AAA pattern (Arrange, Act, Assert)
-- Mock external dependencies, not internal module logic
+- Use the runner, selectors and structure Phase 2.2 found in this project's own tests — not a remembered stack. Arrange/Act/Assert; mock external dependencies, not internal module logic.
 
 **4.4 Story standards:**
-- `Meta` + `StoryObj` pattern
-- `args`-based variants
-- `fn()` for action callbacks
-- Cover: default state, edge cases, error states
+- Use the story patterns Phase 2.2 found (`Meta` + `StoryObj`, `args`-based variants, `fn()` callbacks); cover default state, edge cases and error states.
 
 **4.5 Commit after implementation:**
 
-When auto-commit is enabled, create a conventional commit with the changes. Include the `refs #<issue_number>` line below only when a positive real issue number was supplied; otherwise omit that entire line:
+When auto-commit is enabled, create a conventional commit with the changes. Stage explicit paths only — never `-A`/`--all`/`.` — and run every git command as `git -C "<codebase_path>"` (`rules/core/git-concurrency.mdc`). Include the `refs #<issue_number>` line below only when a positive real issue number was supplied; otherwise omit that entire line:
 ```bash
-git add <modified files>
-git commit -m "<type>(<scope>): <description>
+git -C "<codebase_path>" add <modified files, explicit paths>
+git -C "<codebase_path>" commit -m "<type>(<scope>): <description>
 
 refs #<issue_number>
 task: <task_id>"
 ```
 
+When auto-commit is disabled, do not commit. Report the exact list of files you
+changed — nothing inferred — in the Phase 6 STATUS response and the result
+file's `files_modified`/`files_created`/`files_deleted`; the orchestrator stages
+and commits those exact paths at the task boundary (`rules/core/git-concurrency.mdc`,
+"Reporting Back").
+
 Commit type mapping:
 | Task Type | Commit Type |
 |-----------|-------------|
@@ -395,21 +378,25 @@ attempts. The counter cannot tell "converging slowly" from "stuck", and three
 identical outputs cost the whole budget to learn what the second one already
 said. Report the block instead, naming what repeated.
 
-
-**ROLLBACK POLICY**: If implementation fatally fails (tests still failing after 3 attempts, or unresolvable compilation errors), restore ONLY the files this task changed — `git checkout -- <your files>` for tracked ones, delete the untracked ones you created — then report the failure in Phase 6.
+**ROLLBACK POLICY**: If implementation fatally fails (tests still failing after 3 attempts, or unresolvable compilation errors), restore ONLY the files this task changed — `git -C "<codebase_path>" checkout -- <your files>` for tracked ones, delete the untracked ones you created — then report the failure in Phase 6.
 
 **Never run `git reset --hard`, `git clean`, or any unscoped revert.** You do not own the worktree. `job-orchestrator` dispatches implementers in PARALLEL WAVES sharing a single worktree, so an unscoped reset destroys a wave-mate's uncommitted work — work that is not yours, cannot be recovered, and whose loss is invisible to you because the other agent's failure surfaces somewhere else entirely. If you cannot identify which files are yours, leave the tree exactly as it is and say so in the report: a dirty tree is recoverable, a destroyed one is not.
 
+**Same reasoning bans `git stash` and unscoped `git add`.** Never `git stash` — the stash stack is shared by every worktree, so even a scoped `push -- <file>` can be popped by another lane. Stage only the files this task changed (`git -C "<codebase_path>" add <path> <path>`), never `-A`/`--all`/`.`. Every git command runs as `git -C <this worktree's absolute path>`. See `rules/core/git-concurrency.mdc`.
+
 **5.5 Re-commit fixes if any:**
-When auto-commit is enabled, use the template below. Include `refs #<issue_number>` only for a supplied positive real issue number; otherwise omit that entire line.
+When auto-commit is enabled, use the template below — explicit paths only, `git -C "<codebase_path>"` for every command (`rules/core/git-concurrency.mdc`). Include `refs #<issue_number>` only for a supplied positive real issue number; otherwise omit that entire line.
 ```bash
-git add <fixed files>
-git commit -m "fix(<scope>): resolve lint/type/test issues
+git -C "<codebase_path>" add <fixed files, explicit paths>
+git -C "<codebase_path>" commit -m "fix(<scope>): resolve lint/type/test issues
 
 refs #<issue_number>
 task: <task_id>"
 ```
 
+When auto-commit is disabled, do not commit; report the exact fixed-file list in
+Phase 6 as in 4.5 — the orchestrator commits it at the task boundary.
+
 ### Phase 6: REPORT
 
 Write the full result to a file, then emit a compact STATUS response to the orchestrator.
@@ -438,12 +425,30 @@ Write full JSON to `<JOBS_ROOT>/<JOB_NAME>/results/<task_id>.json`:
   "story_result": "<pass|build error: details|not applicable>",
   "acceptance_criteria_met": "<all|partial: list of unmet criteria|none>",
   "skill_drift": "<none | stale: <module>/<skill> — <what diverged> | missing: <module> should have a project-skill>",
+  "noticed_not_touched": [{ "what": "<problem>", "where": "<path|symbol>" }],
+  "assumptions": ["<what you assumed where the task did not say>"],
+  "not_touched": [{ "path": "src/path/file.ts", "reason": "<why left alone>" }],
   "notes": "<any warnings, blockers, or additional context>"
 }
 ```
 
 Set `skill_drift` from Phase 2.0b: if the project-skill you used was not `fresh`, or the code you wrote diverged from what a skill documents, name the skill and the divergence. The orchestrator uses this to decide whether to trigger `skills learn` (do NOT run `learn` yourself — it is a mutating step the orchestrator dispatches; see `rules/core/skill-lifecycle.mdc`).
 
+Three of those fields have a bar, and a field that collects noise trains the
+reader to skim all three. Omit one rather than pad it. The trio is adapted (MIT)
+from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) as contract fields rather than a free-text template; the bars below are ours.
+
+- `assumptions` — what you assumed where the task was silent AND acted on. If
+  the assumption being wrong would not change a line you wrote, it is a hedge,
+  not an assumption; leave it out.
+- `noticed_not_touched` — a problem in code you actually read, stated so a
+  follow-up task could be written from it alone, with `where` it lives. Not a
+  dumping ground for every smell seen in passing, and not style opinion.
+- `not_touched` — of the files this task was aimed at (`target_files`), the ones
+  absent from `files_modified`/`files_created`/`files_deleted`, each with why.
+  It answers that one question and no other: a reader subtracts those lists and
+  this one from `target_files`, and flags the remainder as an unexplained omission.
+
 Then check the shape and record the file — two commands, both of which refuse
 rather than warn:
 
@@ -487,8 +492,14 @@ Return a compact STATUS response following `rules/core/subagent-status-protocol.
 The inline response must contain only: STATUS line + Completed bullets + Files changed + Verification summary.
 
 **Status classification:**
-- `success` → `STATUS: DONE`
-- `partial` → `STATUS: DONE_WITH_CONCERNS`
+- `success` → `STATUS: DONE`, or `DONE_WITH_CONCERNS` when work that cleared the
+  bar still carries something the orchestrator must know.
+- `partial` → `STATUS: BLOCKED` — never `DONE_WITH_CONCERNS`. An unmet criterion,
+  a failed gate or a gate that did not run breaks `rules/core/definition-of-done.mdc`,
+  and `DONE_WITH_CONCERNS` reports on work that cleared that bar, never a lower
+  one. The harness already reads it this way: `shouldEscalate`
+  (`src/harness/child/escalation.ts`) escalates on any `acceptance[].status` of
+  `not_met` whatever token arrived with it.
 - `failed` → `STATUS: BLOCKED`
 
 ---

package/src/gdskills/bundled/skills/orchestration/task-implementer/output-contract.schema.json

@@ -47,9 +47,40 @@
       "type": "string",
       "description": "Set from SKILL.md Phase 2.0b: 'none' | 'stale: <module>/<skill> — <what diverged>' | 'missing: <module> should have a project-skill'. SKILL.md has required this field since project-skill verification was added; this object is `additionalProperties: false`, so until it was declared here a compliant result was REFUSED by its own contract."
     },
+    "noticed_not_touched": {
+      "type": "array",
+      "description": "Problems seen in passing and deliberately left alone because they were out of scope. Candidate follow-up work: the location is required because a note a reader has to go searching for is a note nobody acts on. Omit the field when nothing was noticed; `[]` says the same thing explicitly.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["what", "where"],
+        "properties": {
+          "what": { "type": "string", "minLength": 1, "description": "The problem, stated so a follow-up task could be written from it alone" },
+          "where": { "type": "string", "minLength": 1, "description": "Path, directory or symbol it lives at" }
+        }
+      }
+    },
+    "assumptions": {
+      "type": "array",
+      "description": "What was assumed where the task did not say. A wrong assumption is the usual cause of a rejected result, so these are the first thing a reviewer should check. Read only by a human — nothing in the result or the request can confirm an assumption, so this is deliberately an array of sentences rather than a structure that would imply a check nobody performs.",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "not_touched": {
+      "type": "array",
+      "description": "Files a reader would expect in `files_modified` and will not find there, each with the reason. `path` is a separate field because this is machine-checkable: a reader holding the request can subtract `files_modified`/`files_created`/`files_deleted` and this list from `task.target_files` and flag whatever is left as an unexplained omission.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "reason"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string", "minLength": 1, "description": "Why it was left alone — 'already correct', 'out of scope', 'blocked by <x>'" }
+        }
+      }
+    },
     "notes": {
       "type": "string",
-      "description": "Warnings, blockers, or additional context"
+      "description": "Warnings, blockers, or additional context. The three fields above were carved out of this one: free text is where they went before they were declared, and anything that fits one of them belongs there instead."
     }
   }
 }

package/src/gdskills/bundled/skills/planning/autodoc-analyst/SKILL.md

@@ -5,6 +5,10 @@ description: >
   to extract purpose, structure, public API surface, patterns, and key dependencies.
   Use when: dispatched by autodoc-orchestrator Phase 2 (one instance per module).
   NOT for: direct user invocation.
+triggers:
+  - "autodoc analyst"
+  - "analyze module docs"
+  - "reverse engineer module"
 metadata:
   version: 1.0.0
 ---
@@ -26,6 +30,18 @@ and writers can use without re-reading the source code.
 | 4 | Document what the code DOES, not how it does it internally |
 | 5 | Extract concrete examples from code (real function names, real endpoints) |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "This module imports from the shared module, so I should analyze that too." | Iron Law 1: one module per invocation. Another analyst has `shared` and is reading it right now. Record the dependency as a dependency; analysing across the boundary duplicates their work and produces two disagreeing accounts of the same code. |
+| "The framework's conventions tell me what this service does." | Iron Law 2: understanding comes from the code in front of you. A NestJS service named `UserService` does whatever this repository made it do, and the convention-based description is the one no reader can catch as wrong. |
+| "This internal helper is the clever part, so it deserves the most detail." | Iron Law 3 and 4: public interfaces first, and document what the module DOES, not how. Internals change without notice; the exported surface is what the writers and the architect can actually build on. |
+| "A real endpoint list would be long — a representative example is clearer." | Iron Law 5 asks for concrete names from the code. A representative example is indistinguishable from an invented one to everyone downstream, and Phase 4 will publish it as if it were real. |
+| "The entry point isn't where project-map said — I'll analyze what I can find." | That mismatch is exactly what `NEEDS_CONTEXT` (and `concerns`) exist for. Quietly analysing a different starting point produces an artifact the architect will merge without knowing it describes something else. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/autodoc-architect/SKILL.md

@@ -7,6 +7,10 @@ description: >
   points, and cross-cutting concerns.
   Use when: dispatched by autodoc-orchestrator Phase 3.
   NOT for: direct user invocation.
+triggers:
+  - "autodoc architect"
+  - "architecture docs"
+  - "reverse engineer architecture"
 metadata:
   version: 1.0.0
 ---
@@ -28,6 +32,18 @@ fit together — something no single module analyst can see alone.
 | 3 | Map ALL cross-module interactions found in the analyses |
 | 4 | Identify the system's architectural style (what it IS, not what it should be) |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "One analysis file is thin — the others are enough to see the shape." | Iron Law 1: every module analysis is read, none ignored. The thin one is usually the integration edge (infra, shared, a worker) whose absence turns a real topology into a tidy diagram of the parts you liked. |
+| "This looks like clean architecture, so the layers are the usual four." | Iron Law 4: describe what the system IS. A named style imported from outside the evidence makes the document describe a project the reader does not have, and every later doc inherits it. |
+| "The frontend obviously calls the backend — that interaction needs no evidence." | Iron Law 2 and 3: every cross-module interaction is derived from something an analysis actually reported. "Obviously" is where a message queue, a BFF, or a direct database read from the frontend disappears from the map. |
+| "The analyses contradict each other about this contract, so I'll pick the more plausible one." | A contradiction is a finding. Record it in `concerns` and return `DONE_WITH_CONCERNS`. Choosing silently buries the one thing the module analysts could not see and you can. |
+| "The architecture is clear to me, so the document can stay at a high level." | The writers in Phase 4 have only this file for anything spanning modules. A high-level summary without data flows and integration points means the architecture section is written from the same summary, twice. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/autodoc-assembler/SKILL.md

@@ -5,6 +5,10 @@ description: >
   into a cohesive package: main README.md and navigation index.
   Use when: dispatched by autodoc-orchestrator Phase 5.
   NOT for: direct user invocation.
+triggers:
+  - "autodoc assemble"
+  - "assemble docs"
+  - "assemble documentation package"
 metadata:
   version: 1.0.0
 ---
@@ -25,6 +29,18 @@ verify cross-references, write the main README and navigation index.
 | 3 | All cross-links between docs must use relative paths |
 | 4 | Do NOT repeat content from sections — summarize and link |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "I know what `api-reference.md` contains from its name — no need to open it." | Iron Law 1: read every section before writing. A writer that returned `DONE_WITH_CONCERNS` may have left a half-written file or a [TODO]; the index would then link confidently to a page that does not deliver what the link promises. |
+| "The onboarding steps are the most important thing, so I'll repeat them in the README." | Iron Law 4: summarize and link. Duplicated steps drift the moment one copy is updated, and the reader has no way to tell which copy is current. |
+| "An absolute path works on my machine and is unambiguous." | Iron Law 3: relative paths only. The docs package gets moved, committed, and read from a repository checkout — an absolute path from the job directory breaks on every machine but the one that wrote it. |
+| "A writer left `[TODO: add X]`, but the section is otherwise complete." | Those TODOs are what `concerns` is for. The orchestrator's final report is the only place the user learns the documentation has known holes; an assembler that filters them out reports a complete package that is not. |
+| "A section is missing from `docs/`, so it must not have been needed." | A missing file means a Phase 4 writer failed or was never dispatched. Report it as a concern — inferring intent from an absence is how a documentation package quietly ships without its API reference. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/autodoc-orchestrator/SKILL.md

@@ -8,6 +8,8 @@ description: >
   NOT for: writing new PRDs or planning new features (use gproject-orchestrator).
 triggers:
   - "autodoc"
+  - "document codebase"
+  - "reverse engineer docs"
   - "автодок"
   - "document this codebase"
   - "generate docs for my project"
@@ -55,6 +57,21 @@ emit it when dispatched as a subagent.
 
 ---
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The subagent's response summarized its findings, so the phase is complete." | Iron Law 3 requires an artifact FILE. The next phase reads `artifacts/analysis/*.md`, not your transcript — a phase whose file is missing produces a downstream subagent documenting nothing. Check the path exists before advancing. |
+| "This module is tiny — faster to describe it myself than to dispatch an analyst." | Iron Laws 1 and 2 have no size exception. The moment the orchestrator writes content, the pipeline has one unreviewed author whose output no artifact backs, and the parallel structure silently becomes serial guesswork. |
+| "The scanner found 12 modules; I'll analyze the important ones and cover the rest later." | Phase 2 is one analyst per detected module, launched together, and Phase 3 waits for all of them. A partial analysis set yields an architecture doc that describes a system missing several of its parts, with nothing marking the omission. |
+| "A writer came back DONE_WITH_CONCERNS, but the file looks fine, so I'll drop the concern." | `DONE_WITH_CONCERNS` exists so the concern reaches the user. It goes into `state.json` and into the Final Report's `Concerns` line. A dropped concern is indistinguishable from a clean run. |
+| "The subagent asked for context twice — I know this repo, I'll answer from memory." | Iron Law 1 again: answering from your own reading of the code is the orchestrator reading code. Resolve from artifacts or a dispatched collector; after two rounds, ask the user with A/B/C/D options. |
+| "There is an interrupted job in `jobs/`, but starting fresh is cleaner." | State Resumption is the user's call, offered as A/B/C. Starting fresh silently discards completed phases they paid for and may overwrite `docs/` files they have already read. |
+
+---
+
 ## Pipeline Overview
 
 ```

package/src/gdskills/bundled/skills/planning/autodoc-scanner/SKILL.md

@@ -5,6 +5,10 @@ description: >
   detects stack, identifies module boundaries, entry points, and dependencies.
   Use when: dispatched by autodoc-orchestrator Phase 1.
   NOT for: direct user invocation.
+triggers:
+  - "autodoc scan"
+  - "scan codebase"
+  - "documentation targets"
 metadata:
   version: 1.0.0
 ---
@@ -25,6 +29,18 @@ and writers can rely on without re-scanning the codebase.
 | 3 | Always list entry points (main files, index files, app bootstraps) |
 | 4 | Return module list in `next_phase_hints.modules[]` — orchestrator uses this to spawn analysts |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "These two packages are small — I'll list them as one module." | Phase 2 spawns exactly one analyst per entry in `next_phase_hints.modules[]`. A merged entry gives one analyst two codebases and leaves a module nobody documents under its own name. |
+| "`package.json` is ambiguous about the framework, so I'll read the source to be sure." | Iron Law 1: directory listings and targeted config reads only. An unknown framework is reported as unknown — reading source here does Phase 2's job with a Phase 1 budget, and the analyst will read it properly anyway. |
+| "These directories are named like features, so they are modules." | Iron Law 2: boundaries come from directory structure AND build config. Names alone invent modules the build system does not have, and each invented one costs a full analyst dispatch. |
+| "There is no `openapi.yaml`, so `has_api` is false." | Step 5 lists five independent signals, any one of which is sufficient. A false from checking one of them tells Phase 4 not to write an API reference for a project that has an API. |
+| "The main app's entry point is obvious — one entry is enough." | Iron Law 3 asks for entry points per module. An analyst handed a module with no entry point starts from the directory listing and guesses at what bootstraps it. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/autodoc-writer/SKILL.md

@@ -5,6 +5,10 @@ description: >
   from analysis artifacts. Dispatched in parallel — one instance per section.
   Use when: dispatched by autodoc-orchestrator Phase 4.
   NOT for: direct user invocation.
+triggers:
+  - "autodoc writer"
+  - "write docs"
+  - "generate documentation pages"
 metadata:
   version: 1.0.0
 ---
@@ -26,6 +30,18 @@ for one specific section. Each instance handles exactly one output file.
 | 4 | Use concrete examples from the actual codebase (real file paths, real commands) |
 | 5 | If a section requires info not in the artifacts, note it as [TODO: add X] rather than inventing |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The artifacts don't give the install command, but `npm install` is always right." | Iron Law 2 and 5: write `[TODO: add install command]` instead. A plausible command in an onboarding doc is worse than a gap — the new developer runs it, it fails, and they stop trusting the rest of the page. |
+| "This belongs in the architecture section too, so I'll cover it here as well." | Iron Law 1: one section per invocation. Another writer owns that section right now, and two independently written accounts of the same thing will not agree by the time the assembler links them. |
+| "A generic example reads more cleanly than the real file path." | Iron Law 4 requires real paths and real commands. `src/foo/bar.ts` teaches nothing and cannot be checked; the actual path is the part the reader copies. |
+| "The API section is for developers, so more implementation detail is better." | Iron Law 3: write for the section's audience. API consumers need the contract — request, response, errors — not the service internals, which change without any promise to them. |
+| "I left a few TODOs, but the section reads as finished, so `DONE`." | Every gap goes into `concerns`, and a section held together by TODOs is `DONE_WITH_CONCERNS`. The assembler collects those TODOs in Phase 5; one that never reached `concerns` ships as finished documentation. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/brainstorm/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: brainstorm
-description: "Use when exploring architecture decisions, tech choices, feature ideas, or any open-ended problem that benefits from multiple perspectives."
+description: "Use when exploring architecture decisions, tech choices, feature ideas, or any open-ended problem that benefits from multiple perspectives. NOT for: writing the chosen option up as a formal requirements document (use prd-creator)."
 triggers:
-  - "/brainstorm"
-  - "Brainstorm"
+  - "brainstorm"
+  - "explore options"
+  - "architecture decision"
   - "Let's think about"
   - "What are options for"
   - "How should we approach"
@@ -11,7 +12,7 @@ triggers:
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
-  category: "ideation"
+  category: "planning"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
@@ -88,3 +89,27 @@ Add: **Security Analyst** (auth, data exposure, compliance) and **UX Advocate**
 - The Critic's questions must be answered by the recommendation
 - Don't dismiss "boring" solutions — they often win
 - End with concrete next steps, not just analysis
+
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "All three agents converged on the same option, so it must be right." | Three agents given one framing usually converge because the framing already decided it. Convergence is evidence about the prompt, not about the option. Check whether all three skipped the same constraint before calling agreement a result. |
+| "The best option is obvious, so the comparison matrix is busywork." | The matrix is the only part the user can audit. Without effort, risk and time-to-ship side by side, "recommended" is an assertion they have to take on trust — and the obvious option is exactly the one whose cost nobody checked. |
+| "The Critic raised risks, but they apply to the runner-up, not my pick." | The Critic's questions apply to ALL options by construction. The recommendation must answer each one or explicitly accept it as a known risk. Silently routing a question to the option you did not pick is how the risk ships. |
+| "This is early exploration, so effort estimates would be premature." | An idea without an estimate is not actionable, which is the whole output of this skill. A labelled guess (S/M/L, stated as a guess) is usable; no number is not. |
+| "The innovative option is more interesting, so it is the better recommendation." | Novelty is not a criterion in the matrix. If the boring option scores better on effort, risk and time to ship, it wins — say so, and put the interesting one in the runner-up slot with the condition that would flip the call. |
+
+## Verification
+
+Before reporting, all of these must hold:
+
+- The Ideas Map has at least two distinct options, each with approach, pros, cons, effort (S/M/L) and risk.
+- The comparison matrix has one column per option and a row per criterion — no blank cells.
+- Every Critical Question from the Critic is listed, and the recommendation either answers it or names it as an accepted risk.
+- The recommendation names a runner-up and the specific condition under which the runner-up would be chosen instead.
+- Next steps are concrete actions, each specific enough to become a task — not "investigate further".
+- In `--quick` mode: 3-5 scored options in a table and one recommendation. In `--deep` mode: the Security Analyst and UX Advocate perspectives both appear in the synthesis, not just in the agent output.
+- Options are grounded in the project's actual stack and constraints; anything assumed about the stack is labelled as an assumption.

package/src/gdskills/bundled/skills/planning/consistency-checker/SKILL.codex.md

@@ -5,6 +5,10 @@ description: >
   and best practices constraints. Catches contradictions, gaps, and violations.
   Use when: dispatched by gproject-orchestrator Phase 5.
   NOT for: direct user invocation.
+triggers:
+  - "check consistency"
+  - "validate spec"
+  - "doc contradictions"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
@@ -29,6 +33,19 @@ This agent is adversarial — its job is to find problems, not to approve.
 | 5 | NEVER fix violations yourself — only report them |
 | 6 | A clean report still lists what was checked (audit trail) |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The first decisions all check out, so the rest of the registry is fine." | Iron Law 1: every decision, no sampling. The registry's later entries are the ones added late under pressure — the most likely to contradict a PRD written before them. |
+| "This violation is one line to fix — cheaper to correct than to report." | Iron Law 5: never fix, only report. This agent is the gate; a gate that edits the artifact it is judging has approved its own change, and the spec-writer never learns its output drifted. |
+| "One CRITICAL violation, but the PRD is strong overall — `DONE` with a note." | The status logic is mechanical: any CRITICAL means `DONE_WITH_CONCERNS`. Softening it lets a document reach human approval carrying exactly the contradiction this phase exists to surface. |
+| "The PRD contradicts a decision, but the PRD's version is clearly better." | Being right is not this agent's job. Report the contradiction and let the orchestrator or the human resolve it — a checker that picks a winner has quietly changed a project decision nobody recorded. |
+| "Nothing was wrong, so a short 'all clear' is the report." | Iron Law 6: a clean report still lists what was checked. Without the audit trail, "no violations" and "did not look" produce the same document. |
+| "I found several violations already — that is enough to block approval." | Iron Law 3: report ALL violations. Stopping early guarantees a second review round for the ones you did not name, and each round costs another full pipeline pass. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/consistency-checker/SKILL.cursor.md

@@ -5,6 +5,10 @@ description: >
   and best practices constraints. Catches contradictions, gaps, and violations.
   Use when: dispatched by gproject-orchestrator Phase 5.
   NOT for: direct user invocation.
+triggers:
+  - "check consistency"
+  - "validate spec"
+  - "doc contradictions"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
@@ -29,6 +33,19 @@ This agent is adversarial — its job is to find problems, not to approve.
 | 5 | NEVER fix violations yourself — only report them |
 | 6 | A clean report still lists what was checked (audit trail) |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The first decisions all check out, so the rest of the registry is fine." | Iron Law 1: every decision, no sampling. The registry's later entries are the ones added late under pressure — the most likely to contradict a PRD written before them. |
+| "This violation is one line to fix — cheaper to correct than to report." | Iron Law 5: never fix, only report. This agent is the gate; a gate that edits the artifact it is judging has approved its own change, and the spec-writer never learns its output drifted. |
+| "One CRITICAL violation, but the PRD is strong overall — `DONE` with a note." | The status logic is mechanical: any CRITICAL means `DONE_WITH_CONCERNS`. Softening it lets a document reach human approval carrying exactly the contradiction this phase exists to surface. |
+| "The PRD contradicts a decision, but the PRD's version is clearly better." | Being right is not this agent's job. Report the contradiction and let the orchestrator or the human resolve it — a checker that picks a winner has quietly changed a project decision nobody recorded. |
+| "Nothing was wrong, so a short 'all clear' is the report." | Iron Law 6: a clean report still lists what was checked. Without the audit trail, "no violations" and "did not look" produce the same document. |
+| "I found several violations already — that is enough to block approval." | Iron Law 3: report ALL violations. Stopping early guarantees a second review round for the ones you did not name, and each round costs another full pipeline pass. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/consistency-checker/SKILL.md

@@ -5,6 +5,10 @@ description: >
   and best practices constraints. Catches contradictions, gaps, and violations.
   Use when: dispatched by gproject-orchestrator Phase 5.
   NOT for: direct user invocation.
+triggers:
+  - "check consistency"
+  - "validate spec"
+  - "doc contradictions"
 metadata:
   version: 1.0.0
 ---
@@ -28,6 +32,19 @@ This agent is adversarial — its job is to find problems, not to approve.
 | 5 | NEVER fix violations yourself — only report them |
 | 6 | A clean report still lists what was checked (audit trail) |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The first decisions all check out, so the rest of the registry is fine." | Iron Law 1: every decision, no sampling. The registry's later entries are the ones added late under pressure — the most likely to contradict a PRD written before them. |
+| "This violation is one line to fix — cheaper to correct than to report." | Iron Law 5: never fix, only report. This agent is the gate; a gate that edits the artifact it is judging has approved its own change, and the spec-writer never learns its output drifted. |
+| "One CRITICAL violation, but the PRD is strong overall — `DONE` with a note." | The status logic is mechanical: any CRITICAL means `DONE_WITH_CONCERNS`. Softening it lets a document reach human approval carrying exactly the contradiction this phase exists to surface. |
+| "The PRD contradicts a decision, but the PRD's version is clearly better." | Being right is not this agent's job. Report the contradiction and let the orchestrator or the human resolve it — a checker that picks a winner has quietly changed a project decision nobody recorded. |
+| "Nothing was wrong, so a short 'all clear' is the report." | Iron Law 6: a clean report still lists what was checked. Without the audit trail, "no violations" and "did not look" produce the same document. |
+| "I found several violations already — that is enough to block approval." | Iron Law 3: report ALL violations. Stopping early guarantees a second review round for the ones you did not name, and each round costs another full pipeline pass. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/docpack-orchestrator/SKILL.md

@@ -2,11 +2,15 @@
 name: docpack-orchestrator
 description: "Use when creating or updating a Metaproject requirements package under docs/requirements: PRD, specification, README, policies/protocols/schemas, roadmap updates, verification, and package review. Use for requests like 'create requirements package', 'prepare module documentation', 'write PRD/spec for module', or 'оформи пакет документации'. Not for reverse-engineering current codebase documentation; use autodoc-orchestrator for that."
 triggers:
-  - "create requirements package"
   - "requirements package"
+  - "create requirements package"
+  - "module documentation"
+  - "documentation package for implementation"
+  - "пакет документации"
+  - "оформи пакет документации"
+  - "подготовь пакет документации"
   - "prepare module documentation"
   - "write PRD and spec"
-  - "оформи пакет документации"
   - "создай документацию модуля"
 metadata:
   author: "MrCipherSmith"
@@ -129,6 +133,32 @@ Run a local verification pass:
 Use `docpack-review` for an adversarial pass. Fix blockers before
 final output. Warnings may remain only if called out clearly.
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "README, PRD and spec agree with each other, so the implementation status is accurate." | Agreement between three documents is agreement between three documents. Iron Law 6 requires code as the proof. Open the path, or write the status as `planned`. |
+| "`docpack-review` came back with warnings only, so the package is done." | Phase 5 permits warnings to remain *only if they are called out clearly* in the Final Response. A warning that lives in the review output and not in `remaining_gaps` has been dropped, not accepted. |
+| "This package is small — a specification alone covers it." | Iron Law 4: README, PRD and specification are all required for module packages. "Small" is the most common reason a package ships with no problem statement and no document index. |
+| "I rewrote most of the doc, so the `Version` obviously moved." | Nothing bumps it for you. Iron Law 3 is checked file by file in Phase 4, and an unbumped version is what makes a stale copy indistinguishable from the current one. |
+| "The user gave me thorough notes, so Phase 1 evidence is redundant." | User notes do not contain the existing package files, `docs/requirements/roadmap.md`, or what a prior version of this package already promised. Skipping Phase 1 is how a package contradicts its own last revision. |
+| "Review is its own skill — the user can run `docpack-review` afterwards." | Iron Law 5 makes verification and review mandatory *before* final output. An unreviewed package reported as complete is the failure this pipeline exists to prevent. |
+
+## Exit Criteria
+
+Do not emit the Final Response until all of these hold:
+
+- Every required file for the package kind exists at `docs/requirements/<package_name>/`, and each was written or deliberately left unchanged — not assumed.
+- Every Markdown file in the package carries a `Version`, and every file you changed has a bumped one.
+- `README.md` links to every file in the package; the specification links to each schema it defines.
+- Every `schemas/*.json` parses as valid JSON.
+- `docs/requirements/roadmap.md` is updated when the package represents a new module or capability, or the report states why it does not.
+- No implementation claim appears that code does not support; anything unbuilt is marked planned or future.
+- `docpack-review` has been run in Phase 5 and reports zero blockers. Remaining warnings appear verbatim in `remaining_gaps`.
+- Every field of the Final Response block is filled with a real value — no placeholder, and `verification`/`review` are never reported as `pass` when the pass did not run.
+
 ## Final Response
 
 Report: