@mrciphersmith/keryx 0.2.9

package/src/gdskills/bundled/rules/core/subagent-status-protocol.md

@@ -0,0 +1,169 @@
+---
+title: Subagent Status Protocol
+category: agent-discipline
+version: 1.0.0
+applies_to: all subagents dispatched by an orchestrator
+---
+
+# Subagent Status Protocol
+
+## Why This Exists
+
+Orchestrators cannot make good decisions based on free-text responses. When a subagent returns a wall of prose ending with "everything looks good", the orchestrator has three bad options: parse it, guess, or trust it blindly. All three fail at scale.
+
+**Known failure modes this protocol prevents:**
+
+- **Silent failures** — subagent hits a blocker, works around it, says "Done". Orchestrator continues. The workaround breaks something downstream.
+- **Ambiguous "done"** — task is "complete" but half the acceptance criteria were skipped. Orchestrator only finds out during review.
+- **Buried blockers** — "I couldn't find the config file so I assumed X" appears in paragraph 4. Orchestrator never re-dispatches with the right information.
+- **Context gaps** — subagent guesses at missing context and gets it wrong. Four tasks downstream are now built on a wrong assumption.
+
+This protocol makes subagent state machine-readable on the first line.
+
+---
+
+## Iron Law
+
+**THE FIRST LINE OF EVERY SUBAGENT FINAL RESPONSE MUST BE `STATUS: <STATUS>`**
+
+No exceptions. No preamble. No "Here's my report:" before the status line.
+
+If the first line is not `STATUS: <STATUS>`, the orchestrator MUST treat the response as `NEEDS_CONTEXT` and request a properly formatted response.
+
+---
+
+## The Four Statuses
+
+### `DONE`
+Task fully complete. All acceptance criteria met. Orchestrator can continue the pipeline.
+
+### `DONE_WITH_CONCERNS`
+Task complete, but the orchestrator should know something before continuing. This is NOT a failure — it is a completed task that carries information the orchestrator needs to make a good decision.
+
+Use when:
+- Implementation required a meaningful interpretation of ambiguous criteria
+- A workaround was used for a non-blocking issue
+- Something unexpected was discovered that may affect later steps
+- Verification passed but with warnings the orchestrator should see
+
+### `BLOCKED`
+Cannot continue. A specific decision or action from the orchestrator is required before the subagent can make progress.
+
+Use when:
+- A required file, resource, or dependency does not exist
+- Two valid approaches exist with significantly different tradeoffs and the subagent cannot choose alone
+- A command failed in a way that requires orchestrator-level intervention (not a self-fixable error)
+- The task scope needs to be clarified before proceeding
+
+Do NOT use `BLOCKED` for errors you can fix yourself. Self-fix first (up to your retry limit), then report `BLOCKED` if still stuck.
+
+### `NEEDS_CONTEXT`
+Specific information is missing that would allow the subagent to proceed correctly. Different from `BLOCKED`: the subagent knows what it needs and believes the orchestrator has it.
+
+Use when:
+- A required input field in the task object is missing or empty
+- Module patterns, library docs, or API signatures are needed but weren't provided
+- The task references files or components that don't exist and no context explains them
+- Acceptance criteria use terms not defined anywhere in the provided context
+
+---
+
+## Exact Response Formats
+
+### `STATUS: DONE`
+
+```
+STATUS: DONE
+
+## Completed
+- [concrete list of what was done, one item per acceptance criterion]
+
+## Files changed
+- path/to/file — description of change
+- path/to/other — description of change
+
+## Verification
+- lint: pass
+- type-check: pass
+- tests: 14 passed, 0 failed
+```
+
+### `STATUS: DONE_WITH_CONCERNS`
+
+```
+STATUS: DONE_WITH_CONCERNS
+
+## Completed
+- [concrete list of what was done]
+
+## Files changed
+- path/to/file — description of change
+
+## Concerns for orchestrator
+- [specific concern] — [why it matters and what the orchestrator might want to do about it]
+- [second concern if any]
+
+## Verification
+- lint: pass
+- type-check: pass
+- tests: 14 passed, 0 failed
+```
+
+### `STATUS: BLOCKED`
+
+```
+STATUS: BLOCKED
+
+## Reason
+[One specific blocker, stated plainly. Not a list of everything that could go wrong — just the one thing stopping progress right now.]
+
+## What I need from orchestrator
+[Specific ask. "Please provide X" or "Please decide between A and B" — not "more information".]
+
+## Work completed so far
+- [list anything that was finished before hitting the blocker, so the orchestrator knows what to preserve]
+```
+
+### `STATUS: NEEDS_CONTEXT`
+
+```
+STATUS: NEEDS_CONTEXT
+
+## Missing information
+[What specifically is needed — name the field, file, pattern, or decision that is absent.]
+
+## Where it might be found
+[Suggestion: "likely in package.json", "the context-collector output", "the issue body", etc.]
+
+## Work completed so far
+- [list anything that was finished before the gap was discovered]
+```
+
+---
+
+## What the Orchestrator Does for Each Status
+
+| Status | Orchestrator action |
+|--------|---------------------|
+| `DONE` | Accept result. Extract files changed, commits, verification results. Continue to next step. |
+| `DONE_WITH_CONCERNS` | Read concerns section. Decide: (a) continue as-is, (b) note concern for later step, or (c) re-dispatch with adjusted scope. Do NOT silently discard concerns. |
+| `BLOCKED` | Stop pipeline on this task. Resolve the specific blocker (provide the file, make the decision, fix the dependency). Re-dispatch. Do NOT proceed to dependent steps while blocked. |
+| `NEEDS_CONTEXT` | Provide the missing information. Re-dispatch the task with the enriched context. If the information is not available, escalate to user. |
+
+---
+
+## Red Flags — Rationalizations That Must Be Rejected
+
+The following thoughts indicate a subagent is about to violate the protocol. Reject them before writing the response.
+
+- **"The result is obvious, I'll just say Done"** — If you are summarizing the result in prose and appending "Done" at the end, you are not following the protocol. Move `STATUS: DONE` to the first line and structure the rest.
+
+- **"I'll add a note at the end instead of BLOCKED"** — Notes at the end are invisible to automated orchestrators. If you are blocked, the status must be `BLOCKED`. The note goes in the `## Reason` field.
+
+- **"It's mostly done, DONE_WITH_CONCERNS feels like admitting failure"** — `DONE_WITH_CONCERNS` is not a failure status. It is a success status with an attached signal. Use it freely when something is worth the orchestrator knowing.
+
+- **"NEEDS_CONTEXT would slow things down, I'll just guess"** — Guessing propagates errors downstream. One `NEEDS_CONTEXT` and a re-dispatch is cheaper than four tasks built on a wrong assumption.
+
+- **"I didn't meet one criterion but I'll say DONE and mention it in notes"** — If an acceptance criterion is not met, the status is not `DONE`. Use `DONE_WITH_CONCERNS` and name the unmet criterion in the concerns section.
+
+- **"The orchestrator will figure it out from my explanation"** — The orchestrator reads `STATUS:` on line 1. Everything else is secondary. Do not make the orchestrator parse free text to determine the outcome.

package/src/gdskills/bundled/rules/core/tdd-workflow.mdc

@@ -0,0 +1,96 @@
+---
+description: "TDD workflow rules: red-green-refactor cycle, test-first mandate, no-done-without-green invariant. Use when implementing features, fixing bugs, or verifying acceptance criteria."
+alwaysApply: false
+---
+
+# TDD Workflow
+
+## Purpose
+Enforce Test-Driven Development: tests are written before implementation code. An agent MUST NOT claim `STATUS: DONE` unless all tests pass.
+
+## When To Apply
+Apply during any implementation task. Always loaded alongside `task-implementer` and `tests-creator` workflows.
+
+---
+
+## The Red-Green-Refactor Cycle
+
+Every implementation must follow this exact sequence:
+
+```
+1. RED    → Write a failing test that describes the desired behaviour
+2. GREEN  → Write the minimal code to make that test pass
+3. REFACTOR → Clean up code without breaking the test
+```
+
+**CRITICAL: Never skip RED.** Writing code before a failing test exists violates TDD. Even if the test seems trivial, it must be written first.
+
+---
+
+## Mandatory Steps
+
+### Step 1: Receive Acceptance Criteria
+- Parse `acceptance_criteria` from the task object (provided by `issue-analyzer` or `tests-creator`)
+- Each criterion maps to ≥1 test case
+- If no criteria exist, derive them from the task description before proceeding
+
+### Step 2: Run tests-creator (or use pre-generated specs)
+- If `test_case_specs` are provided in the task object → use them directly
+- If not → invoke `tests-creator` to generate specs before writing any code
+- **DO NOT start implementation until test specs are confirmed**
+
+### Step 3: Write tests (RED phase)
+- Create test file(s) at the correct location (co-located or in `__tests__/`)
+- Run the test suite — confirm tests FAIL for the right reason
+- A test that passes before implementation is a broken test
+
+### Step 4: Implement (GREEN phase)
+- Write the minimal code to satisfy each failing test
+- Do not add features not covered by tests
+- Run tests after each logical chunk — do not batch all implementation before running
+
+### Step 5: Refactor
+- Clean up code: extract helpers, rename variables, remove duplication
+- Re-run full test suite after every refactor step
+- Refactoring is complete only when all tests are green
+
+### Step 6: Verify and Report
+- Final `bun test` / `npm test` / `pytest` / equivalent must pass with 0 failures
+- Include test output summary in the result object
+- Report `STATUS: DONE` only when all criteria are covered by passing tests
+
+---
+
+## Output Contract Extension
+
+When reporting task completion, include:
+
+```
+tests_written: <N>
+tests_passing: <N>
+tests_failing: 0
+coverage_notes: "<which acceptance criteria are covered>"
+```
+
+---
+
+## Iron Laws
+
+**IRON LAW 1: NEVER claim STATUS: DONE with failing tests. Zero exceptions.**
+**IRON LAW 2: NEVER write implementation before a failing test exists for that behaviour.**
+**IRON LAW 3: NEVER delete tests to make the suite green. Fix the code instead.**
+
+---
+
+## Red Flags — Stop and re-read this rule if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "The logic is simple, I don't need a test first" | Simplicity is never a reason to skip TDD — the cycle builds confidence, not just test coverage |
+| "I'll add tests after to save time" | Tests written after implementation verify what the code does, not what it should do |
+| "The tests are flaky, I'll skip them for now" | Flaky tests signal real design problems — fix the flakiness, not the test |
+| "All the important logic is covered, a few edge tests can wait" | Untested edge cases are exactly where bugs live |
+| "I'll mark it DONE and add tests in a follow-up PR" | STATUS: DONE means done — not "done except for tests" |
+| "The test framework setup is complex, I'll just verify manually" | Manual verification is not reproducible and cannot be reviewed by other agents |
+
+**IRON LAW: AN AGENT THAT SHIPS CODE WITHOUT PASSING TESTS HAS NOT COMPLETED ITS TASK.**

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.codex.md

@@ -0,0 +1,47 @@
+---
+name: code-verifier
+description: "Full quality gate: lint, type-check, tests, circular imports. Mandatory post-implementation step in job-orchestrator. Use when: verifying code after implementation, running quality gate before review, checking code health standalone."
+triggers:
+  - "Run verification"
+  - "Quality gate"
+  - "Run lint and tests"
+  - "Verify implementation"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "verification"
+license: "MIT"
+compatibility: "cursor,codex,zed,opencode"
+---
+
+# Code Verifier
+
+Full quality gate: lint → type-check → tests → circular imports.
+
+**Position:** task-implementer → **code-verifier** → review
+
+## Steps
+1. Detect PM and tooling (bun/npm/pnpm/yarn/python/go)
+2. Run lint (ESLint/Biome/ruff)
+3. Run type-check (tsc --noEmit / mypy / pyright)
+4. Run tests (vitest/jest/pytest/go test)
+5. Check circular imports (madge, if available)
+6. Classify findings by severity, determine gate
+7. Emit VERIFICATION_RESULT
+
+## Gate
+- CRITICAL (type errors, test failures) or HIGH (lint errors, cycles) → GATE: FAIL
+- LOW only → GATE: PASS_WITH_WARNINGS
+
+## Output
+```
+VERIFICATION_RESULT:
+  gate: PASS | PASS_WITH_WARNINGS | FAIL
+  checks: { lint, type_check, tests, circular_imports }
+  findings: [{ severity, check, file, line, rule, message }]
+  summary: "..."
+
+STATUS: DONE
+```
+
+Full spec: `.metaproject/skills/gdskills/orchestration/code-verifier/SKILL.md`

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.cursor.md

@@ -0,0 +1,55 @@
+---
+name: code-verifier
+description: "Full quality gate: lint, type-check, tests, circular imports. Mandatory post-implementation step in job-orchestrator. Use when: verifying code after implementation, running quality gate before review, checking code health standalone."
+triggers:
+  - "Run verification"
+  - "Quality gate"
+  - "Run lint and tests"
+  - "Verify implementation"
+  - "Run checks"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "verification"
+license: "MIT"
+compatibility: "cursor,codex,zed,opencode"
+---
+
+# Code Verifier
+
+Quality gate sub-agent: lint → type-check → tests → circular imports.
+
+**Pipeline position:** task-implementer → **code-verifier** → review
+
+## Phases
+1. **DETECT** — auto-detect PM (bun/pnpm/npm/yarn/python/go), available check commands
+2. **RUN** — lint → type-check → tests → circular-import check (all, never abort early)
+3. **ANALYZE** — classify findings: CRITICAL (type errors, test failures) | HIGH (lint errors, cycles) | LOW (warnings)
+4. **REPORT** — emit `VERIFICATION_RESULT`
+
+## Gate Logic
+```
+CRITICAL or HIGH findings → GATE: FAIL   (orchestrator triggers fix)
+LOW/INFO only             → GATE: PASS_WITH_WARNINGS
+No findings               → GATE: PASS
+```
+
+## Output
+```
+VERIFICATION_RESULT:
+  gate: PASS | PASS_WITH_WARNINGS | FAIL
+  checks:
+    lint:         { status, errors, warnings, command_used }
+    type_check:   { status, errors, command_used }
+    tests:        { status, passed, failed, skipped, command_used }
+    circular_imports: { status, cycles }
+  findings:
+    - { severity, check, file, line, rule, message }
+  summary: "<human-readable>"
+
+STATUS: DONE | DONE_WITH_CONCERNS | BLOCKED
+```
+
+**Key rule:** Always run ALL checks even if one fails — orchestrator needs complete picture.
+
+Full spec: `.metaproject/skills/gdskills/orchestration/code-verifier/SKILL.md`