agent-directives 0.1.0

package/skills/self-audit/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: "self-audit"
+description: "Load when implementation is past GREEN/REFACTOR and the user asks for pre-PR verification, self-audit, scope check, weakest-assumption review, anomaly triage, or a confidence check."
+version: 1.0.0
+required: false
+category: review
+tools:
+  - claude
+  - copilot
+  - codex
+  - cursor
+routing:
+  triggers:
+  - after-refactor
+  - before-verification
+  - full-path
+  - pre-pr
+  paths:
+    - full-path
+---
+
+# Self-Audit
+
+After GREEN/REFACTOR, before verification. This is a triage point — some
+findings loop back to TDD, others flow forward into the PR body.
+
+```
+TDD (RED → GREEN → REFACTOR)
+        │
+        ▼
+    SELF-AUDIT (triage)
+        │
+        ├─ 🔁 Fix now ──▶ RED (one targeted TDD cycle)
+        │                       │
+        │                       ▼
+        │                 SELF-AUDIT pass 2 (document only)
+        │                       │
+        ├─ 📋 Document ────────┤
+        │                       │
+        ├─ 🧑 Ask human ───────┤
+        │                       ▼
+        └──────────────▶ Verification → PR
+```
+
+**One-loop-max:** Pass 1 triages. If it sends a fix to RED, pass 2 is
+documentation only. There is no pass 3.
+
+---
+
+## The Jenga Test (always required)
+
+Name the **single weakest assumption** in your implementation — the block
+that, if pulled, collapses the most.
+
+For each entry, state:
+
+- **Weakest assumption** — specific and falsifiable, not vague
+- **It would break if** — the concrete condition that makes it false
+- **Evidence supporting it** — what you verified, or "none"
+- **Routing** — 🔁 Fix now / 📋 Document / 🧑 Ask human
+
+If you can't identify a weak assumption, that *is* the Jenga entry:
+"My assumption is that I have no weak assumptions."
+
+### Routing criteria
+
+- **🔁 Fix now** — One TDD cycle. In scope. Shipping without it is irresponsible.
+- **📋 Document** — Architectural, out of scope, or multi-cycle. Known gap, not a blocker.
+- **🧑 Ask human** — Can't assess fixability, or the fix changes the approach.
+
+---
+
+## Anomaly Register (required when anomalies exist)
+
+Log every warning, deprecation notice, flaky test, or unexpected side effect
+observed during the TDD cycle. For each, record what it was, whether it's new
+or recurring, what it might signal, and a routing decision.
+
+**"It's always been like that" is not a valid disposition.** Recurring anomalies
+get the highest suspicion, not the lowest.
+
+A suspiciously empty register is itself a signal.
+
+---
+
+## Diff and Boundary Reality Check (required when code changed)
+
+Before finalizing self-audit, inspect the actual diff. If `difit` is available,
+prefer it for a local GitHub-style review:
+
+```bash
+npx difit .
+npx difit staged
+```
+
+Use the diff to look for:
+
+- unrelated edits that expanded beyond the task
+- imports or exports that cross an architectural boundary
+- missing tests adjacent to changed behavior
+- public API changes not reflected in docs or verification
+- risky deletions, broad rewrites, or new shared utilities
+
+If Fallow is available in a TypeScript/JavaScript project, use relevant summary
+checks as self-audit evidence for architecture drift, dead code, duplication, and
+cycles. Route any boundary uncertainty into the Jenga Test.
+
+---
+
+## Sunk Cost Check (required after 3+ TDD cycles in a session)
+
+Assess trajectory across cycles. If two or more of these are true, surface it:
+
+1. Jenga entries are getting more severe each cycle
+2. Anomaly Register is growing rather than stabilizing
+3. Later cycles work around limitations of earlier cycles
+
+The question to surface: *"If I started fresh with what I know now, would I
+choose this same approach?"* The human decides. You surface.
+
+---
+
+## Output Routing
+
+Each destination fires on a specific condition:
+
+| When | Route to | What |
+| --- | --- | --- |
+| **Always**, when opening a PR and self-audit produced routed findings | `## Self-Audit` in the PR body, **before** `## Verification` | Full Jenga + Anomaly Register + Sunk Cost (if triggered). Reviewer sees uncertainty before proof. |
+| **When** self-audit has no routed findings | One-line PR note | `Self-audit completed; no routed findings.` Avoid boilerplate sections with no information. |
+| **Always**, when running verification after self-audit | Verification focus areas (same session) | Verification's functional proof must target any 📋 documented Jenga assumption. |
+| **When** an anomaly matches one you've seen in a previous PR's self-audit | `docs/ERRORS.md` (error-memory format) | Recurrence across PRs promotes an anomaly from one-time observation to systemic pattern. Check by grepping recent merged PRs for the same warning text. |
+| **When** the human decides to change approach after a Sunk Cost Signal | `docs/decisions/` (session-decisions format) | Captures why the approach changed. If the human says "continue," no log needed — the signal is already in the PR body. |
+| **When** starting work in a module that has been self-audited before (during codebase navigation) | Read previous `## Self-Audit` sections from recent merged PRs | Previous Jenga entries are the known weak spots. If your change makes a previous break condition more likely, include it in your own self-audit. |

package/skills/spec-reviewer/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: "spec-reviewer"
+description: "Load when the user asks whether implementation matches a spec, requirements doc, acceptance criteria, or design plan, or says check what is missing, incomplete, or divergent before merge."
+version: 1.1.0
+required: false
+category: review
+tools:
+  - claude
+  - copilot
+  - codex
+  - cursor
+routing:
+  triggers:
+  - written-spec
+  - specification
+  - acceptance-criteria
+  - design-review
+  paths:
+    - full-path
+    - review-path
+---
+
+## Review Depth
+
+Default to the lightest useful review.
+
+### Fast Path
+Use only when the change is small, localized, low-risk, and project gates are already passing or not relevant.
+
+Output:
+- Top 1-3 material findings only
+- `No material findings` if clean
+- Verification gaps only when they affect merge confidence
+
+Do not emit the full checklist when there are no findings.
+
+### Deep Path
+Use the full review process when the change is high-risk, cross-cutting, production-sensitive, security/data-sensitive, behavior-changing without adequate tests, has failing or missing gates, or is explicitly requested.
+
+# Spec Reviewer
+
+You are a specialist in reviewing whether an implementation matches its written
+specification. Your primary focus is ensuring every requirement has code, every
+scenario has coverage, and the implementation follows the design it was built
+against.
+
+This skill complements the test-reviewer skill. Test-reviewer catches bad tests.
+Spec-reviewer catches missing or divergent implementations.
+
+## Core Principle: The Spec Is the Contract
+
+The specification is the agreement between intent and implementation. If the
+code doesn't match the spec, one of them is wrong — and you need to identify
+which. The spec is not aspirational; it is the contract.
+
+---
+
+## Three-Dimensional Review
+
+Every spec review checks three dimensions. Each has its own severity level.
+
+### Dimension 1: Completeness (CRITICAL)
+
+**Question:** Is everything the spec requires actually implemented?
+
+#### Check 1: Requirement Coverage
+
+For each requirement in the specification:
+
+1. **Find the requirement** — look for `### Requirement:` or similar markers
+2. **Search for implementation evidence** — grep for keywords, class names,
+   function names, or behavior described in the requirement
+3. **Assess coverage:**
+   - **Found** — implementation exists, note the file and line range
+   - **Partial** — some aspects implemented, others missing
+   - **Missing** — no evidence of implementation
+
+```
+### Requirement: User authentication
+Status: FOUND
+Evidence: src/auth/login.ts:45-82, src/auth/session.ts:12-34
+
+### Requirement: Password reset flow
+Status: PARTIAL
+Evidence: src/auth/reset.ts:1-30 (token generation only, email sending missing)
+
+### Requirement: Rate limiting on login attempts
+Status: MISSING
+Evidence: No rate-limiting middleware found in auth routes
+```
+
+#### Check 2: Scenario Coverage
+
+For each scenario in the specification:
+
+1. **Find the scenario** — look for `#### Scenario:` or `WHEN/THEN` patterns
+2. **Check for test coverage** — does a test verify this scenario?
+3. **Check for implementation coverage** — does the code handle this case?
+
+| Scenario Status    | Meaning                                |
+| ------------------ | -------------------------------------- |
+| Covered            | Both test and implementation exist     |
+| Untested           | Implementation exists, no test         |
+| Unimplemented      | Test exists (possibly skipped), no code |
+| Missing            | Neither test nor implementation exists |
+
+### Dimension 2: Correctness (WARNING)
+
+**Question:** Does the code do what the spec says, or something different?
+
+#### Check 3: Implementation-Spec Alignment
+
+For each implemented requirement:
+
+1. Read the specification's description of expected behavior
+2. Read the implementation
+3. Compare: does the code produce the behavior the spec describes?
+
+```typescript
+// Spec says: "The system SHALL return a 409 Conflict when creating
+// a user with an email that already exists."
+
+// Implementation review:
+// src/users/create.ts:67-72
+if (existingUser) {
+  return { status: 409, body: { error: "User exists" } };
+}
+
+// DIVERGENCE: Error message is generic "User exists" but spec might
+// expect "Email already registered" — check spec for exact wording.
+```
+
+**Key signals of divergence:**
+
+- Different error messages or status codes than the spec describes
+- Different function signatures or return types than the spec defines
+- Different ordering or flow than the spec prescribes
+- Different edge case handling than the spec requires
+- Implementation handles cases the spec doesn't mention (scope creep)
+- Implementation skips cases the spec requires (incomplete)
+
+#### Check 4: Scenario Behavior Matching
+
+For each testable scenario:
+
+1. Read the scenario's expected outcome
+2. Read the corresponding test (if it exists)
+3. Does the test actually verify what the scenario describes?
+
+```
+Scenario: "User submits empty registration form"
+Expected: "The system SHALL return validation errors for each required field"
+Test: it("should reject empty form", () => { ... })
+
+Issue: Test checks that status is 400 but does not verify that ALL
+required fields have error messages. Scenario expects per-field errors.
+```
+
+### Dimension 3: Coherence (SUGGESTION)
+
+**Question:** Does the implementation follow the design decisions?
+
+#### Check 5: Design Adherence
+
+If a design document exists:
+
+1. Extract key decisions (look for "Decision:", "Approach:", "Architecture:",
+   "Pattern:")
+2. Verify the implementation follows those decisions
+3. If it contradicts a decision, flag it
+
+```
+Design says: "Use repository pattern for data access"
+Implementation: Direct SQL queries in route handlers
+
+DIVERGENCE: Design specifies repository pattern but implementation
+uses inline queries in src/routes/users.ts:34-41
+```
+
+#### Check 6: Pattern Consistency
+
+Review new code for consistency with project patterns:
+
+- File naming and directory structure
+- Error handling approach
+- Logging patterns
+- Import/export conventions
+- Configuration patterns
+
+---
+
+## Review Process
+
+For every spec review:
+
+1. **Read the specification** — understand all requirements and scenarios
+2. **Read the design** (if it exists) — understand architectural decisions
+3. **Map requirements to code** — completeness check
+4. **Map scenarios to tests** — scenario coverage check
+5. **Spot-check implementations** — correctness check on critical paths
+6. **Check design adherence** — coherence check
+7. **Generate the review report** — structured output below
+
+---
+
+## Output Format
+
+### Summary Scorecard
+
+```markdown
+## Spec Review: [Change/Feature Name]
+
+### Summary
+
+| Dimension    | Status                          |
+| ------------ | ------------------------------- |
+| Completeness | X/Y requirements, Z/W scenarios |
+| Correctness  | N issues found                  |
+| Coherence    | M notes                         |
+```
+
+### Issues by Severity
+
+#### CRITICAL (must fix before merge)
+
+```
+### CRITICAL: Missing requirement — [requirement name]
+
+**Spec location:** specs/feature/spec.md, line N
+**Requirement:** [the requirement text]
+**Evidence:** No implementation found in codebase
+**Recommendation:** Implement [requirement] in [suggested location]
+```
+
+#### WARNING (should fix)
+
+```
+### WARNING: Implementation diverges from spec — [requirement name]
+
+**Spec says:** [what the spec expects]
+**Code does:** [what the implementation actually does]
+**File:** path/to/file.ts:line-range
+**Recommendation:** [update code to match spec OR update spec to match code, with reasoning]
+```
+
+#### SUGGESTION (nice to fix)
+
+```
+### SUGGESTION: Design decision not followed — [decision name]
+
+**Design says:** [the decision]
+**Implementation:** [what was done instead]
+**File:** path/to/file.ts:line-range
+**Recommendation:** [align implementation with design OR update design to reflect reality]
+```
+
+### Graceful Degradation
+
+If only partial specifications exist, review what you can and clearly state
+what was skipped:
+
+```markdown
+### Scope of Review
+
+- ✅ Requirements checked (spec.md found, 8 requirements)
+- ✅ Scenarios checked (12 scenarios in spec)
+- ⚠️ Design adherence skipped (no design.md found)
+```
+
+---
+
+## Severity Guidelines
+
+| Condition                          | Severity    |
+| ---------------------------------- | ----------- |
+| Required behavior not implemented  | CRITICAL    |
+| Spec scenario completely uncovered | CRITICAL    |
+| Implementation contradicts spec    | WARNING     |
+| Spec scenario partially covered    | WARNING     |
+| Design decision ignored            | SUGGESTION  |
+| Pattern inconsistency              | SUGGESTION  |
+
+**When uncertain:** Prefer the lower severity. False CRITICALs waste time;
+missed SUGGESTIONs are low-cost.
+
+**Every issue must include:** a specific, actionable recommendation with file
+and line references where applicable. No vague suggestions like "review this
+section."
+
+---
+
+## Forbidden Patterns
+
+| Pattern                                         | Why Forbidden                                             |
+| ----------------------------------------------- | --------------------------------------------------------- |
+| Flagging issues without specific recommendations | Issues without fixes are complaints, not reviews          |
+| Reviewing without reading the spec              | You cannot verify against a contract you haven't read     |
+| Treating spec as suggestions rather than contract | The spec IS the standard — if it's wrong, update it      |
+| Skipping scenarios during review                | Scenarios are the testable surface — skipping them misses bugs |
+| Using only CRITICAL severity                    | Not everything is critical; over-flagging causes alert fatigue |
+
+---
+
+_This skill is used after implementation and before merge to verify that the code matches its specification._

package/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: "subagent-driven-development"
+description: "Load when executing an existing implementation plan with multiple mostly independent tasks using delegated subagents, fresh task context, parent-owned review, and final integration verification."
+version: 1.0.0
+required: false
+category: workflow
+tools:
+  - claude
+  - copilot
+  - codex
+  - cursor
+routing:
+  triggers:
+    - subagent-orchestration
+    - delegated-implementation
+    - implementation-plan-execution
+    - multi-task-plan
+    - parallel-agent-work
+  paths:
+    - full-path
+    - debugging-path
+    - policy-path
+---
+
+# Subagent-Driven Development
+
+You are an implementation orchestrator. Your job is to execute an existing plan by
+splitting safe work into delegated agent tasks while keeping responsibility for
+scope, sequencing, review, integration, and final verification.
+
+This skill does not replace planning, TDD, review, or verification. It coordinates
+those workflows when fresh subagent contexts are safer than one long-running
+implementation session.
+
+## When to Load
+
+Load this skill when all are true:
+
+- an implementation plan, issue task list, PRD-derived task list, or clear staged
+  work plan already exists
+- the work contains multiple tasks that can be scoped independently or sequenced
+  cleanly
+- the active client/runtime supports delegated subagents, parallel agents, or
+  equivalent isolated worker sessions
+- each task can be given self-contained context, constraints, non-goals, and
+  verification expectations
+- the parent agent can inspect results and run final combined verification
+
+Do not load this skill when:
+
+- requirements are still vague — use `skills/product-requirements-writer/SKILL.md`
+  or `skills/implementation-task-planner/SKILL.md` first
+- one coherent system model is required before any safe edit can happen
+- tasks would edit the same files concurrently or compete for the same mutable
+  resources
+- the active runtime lacks safe delegation support; use the normal Full Path and
+  state that subagent orchestration is unavailable
+- the orchestration overhead is larger than the risk of simply doing a small edit
+
+## Core Principle: Parent Owns Scope, Subagents Own Slices
+
+A subagent is a worker with isolated context, not a replacement for the parent
+agent's judgment. The parent agent must decide what can be delegated, provide the
+right context, and verify that the combined result is safe.
+
+Do not dispatch broad prompts such as "implement the plan." Dispatch narrow,
+self-contained task slices with explicit constraints and expected evidence.
+
+## Parent-Agent Responsibilities
+
+Before dispatching any subagent:
+
+1. Read the plan or task list once.
+2. Extract tasks, dependencies, likely touched files, and verification gates.
+3. Classify each task as parallel-safe, sequential, or not delegable.
+4. Identify tasks that may share files, shared state, test fixtures, migrations,
+   generated outputs, or external resources.
+5. Decide the smallest safe delegation units.
+
+During execution:
+
+1. Provide each subagent with the exact task text and relevant local context.
+2. Set allowed edit scope, forbidden areas, constraints, and non-goals.
+3. Require status, changed files, verification, and concerns in the subagent
+   response.
+4. Review subagent results before accepting them.
+5. Stop unsafe parallel work if changed-file overlap or shared-state coupling
+   appears.
+
+Before completion:
+
+1. Inspect the combined diff.
+2. Check changed-file overlap and integration risk.
+3. Run the selected review skills from `directives/adaptive-routing.md`.
+4. Run relevant project verification and quality gates.
+5. Report final evidence from the parent session, not only subagent claims.
+
+## Delegation Decision Rules
+
+Use delegated subagents for tasks that are:
+
+- isolated to different files, modules, packages, tests, or research questions
+- small enough to explain in one focused prompt
+- independently verifiable
+- low-conflict if completed in parallel, or clearly ordered if sequential
+
+Keep work in the parent session or execute sequentially when:
+
+- one task's result determines another task's design
+- tasks touch the same files or generated artifacts
+- tasks involve migrations, production data, auth/security/privacy, deployment,
+  or other high-risk shared state
+- broad architecture understanding is required before editing
+- the plan itself may be wrong
+
+Parallel delegation is optional. Sequential fresh-context delegation can still be
+valuable for long plans when each task needs a clean scope and review checkpoint.
+
+## Subagent Prompt Contract
+
+Every implementation subagent prompt should include:
+
+- **Task goal:** the specific task to complete
+- **Original task text:** copied from the plan, not summarized from memory
+- **Relevant context:** files, commands, existing patterns, dependencies, prior task
+  outcomes that matter
+- **Edit scope:** allowed files/areas and forbidden areas
+- **Constraints and non-goals:** what not to build, refactor, or clean up
+- **Workflow expectations:** TDD, type-first work, debugging, or review rules that
+  apply to this task
+- **Verification:** exact or best-known checks to run, plus what to report if a
+  check is unavailable
+- **Output contract:** required status, changed files, verification evidence,
+  unresolved risks, and questions
+
+Use this status vocabulary:
+
+| Status | Meaning | Parent action |
+| --- | --- | --- |
+| `DONE` | Task complete with evidence and no material concerns | Review before accepting |
+| `DONE_WITH_CONCERNS` | Task complete but the worker found risks, assumptions, or weak evidence | Inspect concerns before review |
+| `NEEDS_CONTEXT` | Worker cannot proceed safely without missing information | Provide context or re-scope |
+| `BLOCKED` | Worker cannot complete with current plan/tooling/scope | Reassess task size, assumptions, or ask the human |
+
+Never ignore `NEEDS_CONTEXT`, `BLOCKED`, or material concerns. Retrying the same
+prompt without changing context usually repeats the failure.
+
+## Review Sequence
+
+For non-trivial delegated implementation, review in this order:
+
+1. **Spec compliance review**
+   - Does the change satisfy the original task/spec?
+   - Are required paths, APIs, behaviors, and tests present?
+   - Did the subagent avoid extra scope?
+
+2. **Quality review**
+   - Does the code follow project conventions?
+   - Are tests meaningful and behavior-focused?
+   - Are error handling, security, data, and operational risks addressed for the
+     touched surface?
+   - Did the worker introduce unnecessary abstraction, duplication, or broad
+     cleanup?
+
+Use existing routed reviewer skills only when their normal routing triggers match
+the touched surface or risk:
+
+- `skills/spec-reviewer/SKILL.md` for spec-governed work
+- `skills/test-reviewer/SKILL.md` for tests and eval scenarios
+- `skills/code-reviewer/SKILL.md` for baseline diff review when a PR, branch,
+  local diff, or review checkpoint is in scope
+- `skills/architecture-boundary-reviewer/SKILL.md` for imports, exports, moves,
+  package boundaries, or shared utilities
+- `skills/production-readiness-reviewer/SKILL.md` for production-sensitive work
+
+Do not load every reviewer by default. Implementer self-review is useful but never
+replaces parent-side or routed reviewer validation when the risk calls for it.
+
+## Failure Handling
+
+If a subagent finds spec gaps:
+
+1. Re-dispatch a focused fix task or fix in the parent session if safer.
+2. Re-run the spec review after the fix.
+3. Do not move to quality review until material spec gaps are closed.
+
+If a quality reviewer requests changes:
+
+1. Fix only material issues tied to the task.
+2. Re-review when the fix changes behavior, tests, or architecture.
+3. Track minor follow-ups separately if they are outside scope.
+
+If subagent outputs conflict:
+
+1. Stop accepting further worker changes.
+2. Inspect changed-file overlap and assumptions.
+3. Resolve conflicts in the parent session or re-scope sequentially.
+4. Run combined verification before continuing.
+
+## Common Pitfalls
+
+1. **Dispatching the whole plan.** Broad delegation recreates the same context
+   problem in another agent. Slice the plan first.
+
+2. **Parallelizing shared files.** If two workers touch the same file, generated
+   output, fixture, migration, or shared resource, treat the work as sequential
+   unless you have explicit isolation.
+
+3. **Letting workers infer constraints.** Subagents do not inherit the parent
+   session's hidden context. Provide exact task text, constraints, non-goals, and
+   verification requirements.
+
+4. **Trusting claims without evidence.** A worker saying tests passed is weaker
+   than parent-side verification. Run final combined checks before reporting done.
+
+5. **Turning every small task into a review gauntlet.** Use review depth that
+   matches risk. Tiny mechanical tasks may need parent inspection and targeted
+   verification; non-trivial behavior changes need spec and quality review.
+
+6. **Skipping integration review.** Independent task success does not prove the
+   combined diff is coherent. Always inspect the integrated result.
+
+## Verification Checklist
+
+Before completing a subagent-driven implementation:
+
+- [ ] The parent agent read and classified the full plan before dispatching work.
+- [ ] Each subagent received self-contained context, constraints, non-goals, edit
+      scope, and verification expectations.
+- [ ] Parallel work did not edit the same files or shared mutable resources.
+- [ ] `NEEDS_CONTEXT`, `BLOCKED`, and `DONE_WITH_CONCERNS` statuses were handled
+      explicitly.
+- [ ] Spec compliance was checked before quality review for non-trivial tasks.
+- [ ] Relevant routed reviewer skills were used only when their normal triggers
+      matched the touched surfaces or risks.
+- [ ] The parent agent inspected the combined diff and ran final verification.