agent-directives 0.1.0

package/skills/code-reviewer/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: "code-reviewer"
+description: "Load when the user asks to review a PR, branch, diff, local changes, or says approve, merge, or check this change for bugs, regressions, security, maintainability, or merge risk."
+version: 1.1.0
+required: true
+category: review
+tools:
+  - claude
+  - copilot
+  - codex
+  - cursor
+routing:
+  triggers:
+  - pull-request
+  - pr-review
+  - code-review
+  - branch-review
+  - diff-review
+  - merge-risk
+  paths:
+    - 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.
+
+# Code Review Guidelines
+
+When reviewing a pull request, branch, diff, or local change:
+
+## Review Heuristics (What to Check)
+
+Do not just read the code top-to-bottom. Apply these specific checks:
+
+| Severity | Check | Heuristic / Action |
+| :--- | :--- | :--- |
+| **🛑 Critical** | **CI & Config Changes** | Look at `.github/workflows`, test configs, and lint rules first. Flag any change that weakens CI, ignores rules, or deletes tests to "fix" them. |
+| **🛑 Critical** | **Evidence Requirements** | For any non-trivial logic change, require a test that fails on the pre-change behavior. |
+| **⚠️ Warning** | **New Utilities (DRY)** | Search for new functions, helpers, or modules. Run a repo search to check for duplicates. Flag anything that reinvents existing codebase functionality. |
+| **⚠️ Warning** | **Structural Regression** | Flag changes that make the codebase harder to reason about: ad-hoc branches in busy flows, feature checks scattered through shared paths, unnecessary wrappers, cast-heavy contracts, duplicated helpers, or logic added in the wrong layer. Prefer fixes that delete complexity, reuse the canonical owner/helper, or make the data/type boundary explicit. |
+| **🔍 Trace** | **Critical Path** | Pick the most important logic change and trace it end-to-end: input → transforms → output. Check boundary conditions and unexpected branching. |
+| **🔍 Trace** | **Security Boundaries** | If the PR touches untrusted input or LLM calls, explicitly check for prompt injection, auth bypass, and missing sanitization. |
+
+## Standard Categories
+
+## Output Format
+
+For each finding:
+
+- **File:Line** — exact location
+- **Severity** — Critical / Warning / Trace / Suggestion
+- **What's wrong** — one sentence
+- **Fix** — how to fix it
+
+## Rules
+
+- Be specific. Quote the problematic code.
+- Don't flag style nitpicks unless they affect readability.
+- Before accepting a complex implementation, ask whether the same behavior can be achieved by deleting branches, reusing an existing abstraction, moving logic to the canonical owner, or making the data/type boundary explicit.
+- Do not approve merely because behavior works. If the implementation creates obvious structural debt, spaghetti branching, duplicated abstractions, or unclear type/boundary contracts, call that out as a material review finding.
+- Treat these as merge-blocking unless clearly justified: scattered feature-specific conditionals in shared flows, duplicated helpers/models, casts or optionality that hide real invariants, wrappers that add indirection without reducing complexity, or modules made materially harder to scan, test, or own.
+- If the PR looks good, say so. Don't invent problems.
+- End with: APPROVE / REQUEST_CHANGES / COMMENT

package/skills/codebase-health-reviewer/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: "codebase-health-reviewer"
+description: "Load when reviewing TypeScript/JavaScript refactors, cleanup, AI-generated code, shared utilities, dead code, duplication, complexity, circular dependencies, Fallow output, or maintainability drift."
+version: 1.1.0
+required: false
+category: review
+tools:
+  - claude
+  - copilot
+  - codex
+  - cursor
+routing:
+  triggers:
+  - typescript
+  - javascript
+  - refactor
+  - cleanup
+  - fallow
+  - codebase-health
+  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.
+
+# Codebase Health Reviewer
+
+You are a specialist in reviewing project-wide health signals, especially for
+TypeScript and JavaScript repositories where Fallow is available. Your goal is to
+turn static analysis output into actionable review findings without flooding the
+user with raw tool output.
+
+This skill complements architecture-boundary-reviewer. Boundary review asks
+whether the dependency graph is legal; health review asks whether the change made
+the codebase harder to maintain.
+
+---
+
+## When to Use
+
+Use this skill when a task includes:
+
+- Refactors or cleanup
+- Removing files, exports, types, or dependencies
+- Adding shared utilities or abstractions
+- Touching complex modules
+- Reviewing AI-generated code before merge
+- Investigating duplication, dead code, circular dependencies, or architecture drift
+- Any project where the user asks to incorporate Fallow into directives or review
+
+Do not use it as a substitute for tests. Fallow can show graph and health facts;
+tests still prove behavior.
+
+---
+
+## Primary Tool: Fallow
+
+For TypeScript/JavaScript projects, prefer Fallow when available:
+
+```bash
+npx fallow --summary
+npx fallow dead-code
+npx fallow dupes
+npx fallow health
+```
+
+Targeted checks:
+
+```bash
+npx fallow dead-code --boundary-violations
+npx fallow dead-code --circular-deps
+npx fallow fix --dry-run
+```
+
+Use `--format json` or `--format markdown` when the project needs structured
+review output. Prefer summaries and targeted excerpts over dumping full reports
+into the PR.
+
+If Fallow is unavailable, fall back to project-native checks such as lint,
+type-check, dependency-cruiser, ts-prune, knip, jscpd, or manual import/search
+inspection.
+
+---
+
+## Review Process
+
+### Step 1: Establish the Baseline
+
+Run or inspect the starting health state before judging the change. Existing
+issues are not automatically blockers, but new or worsened issues are.
+
+```md
+Baseline:
+- Dead code: existing count or not checked
+- Duplication: existing count/rate or not checked
+- Health/complexity: hotspots or not checked
+- Cycles/boundaries: existing count or not checked
+```
+
+If no baseline is available, state that the review is a snapshot rather than a
+regression comparison.
+
+### Step 2: Review Change-Specific Risk
+
+Map the task to the relevant Fallow checks:
+
+| Change type | Checks to prioritize |
+| --- | --- |
+| Delete or rename code | dead code, unused exports, dependents |
+| Add helper/shared utility | duplication, health, boundary violations |
+| Refactor module | health, duplication, circular dependencies |
+| Add package dependency | unused dependencies, unlisted dependencies |
+| Change public exports | unused exports, duplicate exports, dependents |
+| Move code between folders | boundary violations, circular dependencies |
+
+### Step 3: Interpret Findings
+
+Classify each finding:
+
+- **Blocker** — newly introduced dead code, illegal boundary, cycle, or major complexity spike
+- **Should fix** — duplicated logic or maintainability issue caused by this change
+- **Follow-up** — pre-existing issue worth tracking separately
+- **Not relevant** — unrelated existing issue outside task scope
+
+Do not demand that one PR fix the whole repository unless the task is explicitly
+cleanup. Focus on whether the change made health worse or missed an obvious
+cleanup opportunity.
+
+### Step 4: Recommend Minimal Fixes
+
+For each actionable finding, give the smallest safe fix:
+
+- remove unused export/file/dependency
+- merge duplicate helper logic
+- split a high-complexity function
+- invert a dependency to preserve boundaries
+- add a public export instead of deep import
+- create a follow-up issue for broad cleanup
+
+---
+
+## Output Format
+
+```md
+## Codebase Health Review
+
+### Tool Evidence
+- Command: `npx fallow --summary`
+- Result: pass / warnings / failed / unavailable
+
+### Findings
+#### BLOCKER: New circular dependency between auth and user modules
+- Evidence: `npx fallow dead-code --circular-deps`
+- Introduced by: `src/features/auth/login.ts` importing `src/features/user/internal.ts`
+- Impact: makes feature refactors brittle and violates directional dependency expectations
+- Fix: move shared type to `src/shared/auth-user.ts` or expose through public API
+
+#### FOLLOW-UP: Existing duplicated validation helpers
+- Evidence: 3 clone groups reported before this change
+- Scope: pre-existing; not introduced by this PR
+- Recommendation: create cleanup issue if not already tracked
+
+### Verdict
+- ✅ Pass — no new health regressions
+- ⚠️ Pass with follow-ups — no blocker, but cleanup recommended
+- ❌ Block — change introduces health regression
+```
+
+---
+
+## PR Verification Snippet
+
+When the review passes, include a concise section in the PR body:
+
+```md
+### Codebase Health
+
+- `npx fallow --summary` passed / reported no new blockers
+- Dead code: no new unused files/exports/dependencies
+- Duplication: no new duplicate clone family relevant to this change
+- Complexity: changed functions remain below project threshold
+- Cycles/boundaries: no new cycle or boundary violation
+```
+
+If Fallow is unavailable:
+
+```md
+### Codebase Health
+
+- Fallow unavailable: <reason>
+- Manual fallback: checked imports/exports/dependents with <tool/command>
+- No new dead code, duplication, cycles, or boundary regressions found in touched files
+```
+
+---
+
+## Common Pitfalls
+
+1. **Confusing pre-existing issues with PR regressions.** Flag them, but do not
+   block unless the change worsens them or depends on them.
+2. **Dumping raw reports.** Summarize evidence and link/paste only relevant lines.
+3. **Treating health checks as behavior proof.** Static analysis complements tests;
+   it does not replace RED/GREEN/REFACTOR.
+4. **Ignoring boundary findings because the task was not architectural.** Illegal
+   dependency edges are blockers even when behavior tests pass.
+5. **Letting Fallow absence stop the task.** Use manual fallback and document the
+   lower confidence.
+
+---
+
+## Verification Checklist
+
+- [ ] Baseline or snapshot status stated
+- [ ] Relevant Fallow checks selected for the change type
+- [ ] Findings classified as blocker / should-fix / follow-up / not relevant
+- [ ] New regressions separated from existing debt
+- [ ] Minimal fixes or issue follow-ups recommended
+- [ ] PR-ready health summary produced

package/skills/harness-hooks-reviewer/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: "harness-hooks-reviewer"
+description: "Load when adding or reviewing agent harness hooks, start/stop hooks, pre-write/pre-command hooks, post-change automation, or deterministic agent workflow scripts."
+version: 1.0.0
+required: false
+category: review
+tools:
+  - claude
+  - copilot
+  - codex
+  - cursor
+routing:
+  triggers:
+    - agent-hooks
+    - harness-hooks
+    - start-hook
+    - stop-hook
+    - pre-write-hook
+    - pre-command-hook
+    - post-change-automation
+    - deterministic-agent-automation
+  paths:
+    - full-path
+    - review-path
+    - policy-path
+---
+
+# Harness Hooks Reviewer
+
+You are a specialist in reviewing deterministic automation around AI coding
+agents. Your job is to decide whether hooks and harness scripts make agent work
+safer and more consistent without becoming slow, brittle, surprising, or unsafe.
+
+Hooks are for deterministic behavior: enforcing policy, preparing scoped context,
+running local checks, capturing session learnings, or producing machine-readable
+signals. Do not use hooks to hide vague LLM prompts behind automation.
+
+---
+
+## When to Use
+
+Use this skill when work adds, changes, or reviews:
+
+- start/session hooks that load dynamic project, team, module, or developer context
+- stop/session hooks that summarize work, suggest instruction updates, or emit logs
+- pre-write, pre-command, or permission hooks that block or warn on risky actions
+- post-change hooks for formatting, linting, reporting, or generated artifacts
+- agent harness scripts that run automatically around model actions
+
+Do not use this skill for normal application runtime hooks, framework lifecycle
+hooks, or CI jobs unless they are specifically part of the agent harness.
+
+---
+
+## Review Process
+
+### Step 1: Classify the Hook
+
+State the hook class and intended outcome:
+
+- Start/context setup
+- Stop/session reflection
+- Pre-action policy gate
+- Post-change formatting/check/reporting
+- Logging/telemetry/audit
+- Other deterministic automation
+
+If the hook's purpose is unclear, ask for clarification before approving it.
+
+### Step 2: Check Trigger and Scope
+
+Verify:
+
+- the trigger event is specific enough to avoid surprising execution
+- the hook only runs in intended repositories, paths, tools, or task classes
+- slow checks are scoped to changed or relevant files when possible
+- generated, vendor, dependency, or build-output paths are excluded unless they are
+  the explicit subject of work
+
+### Step 3: Check Side Effects and Failure Mode
+
+For each side effect, identify whether the hook may read, write, block, network,
+spawn processes, modify config, or expose data.
+
+Require an explicit failure mode:
+
+- **Block** for deterministic safety violations
+- **Warn** for useful but non-authoritative findings
+- **Log-only** for telemetry or improvement suggestions
+
+Hooks must not silently rewrite unrelated files, weaken checks, commit changes,
+exfiltrate secrets, or mask failures to keep an agent moving.
+
+### Step 4: Check Operational Safety
+
+Look for:
+
+- timeout and output-size bounds
+- idempotent behavior, or documented non-idempotent state
+- stable input/output contract for the harness
+- clear handling for missing tools, partial configuration, and unsupported clients
+- least-privilege environment and secret access
+- logs that avoid secrets, tokens, PII, and excessive prompt/context dumps
+
+### Step 5: Check Continuous-Improvement Use
+
+For hooks that suggest instruction updates or session learnings:
+
+- emit proposals, not automatic policy changes, unless the repo explicitly allows it
+- include evidence: trigger, affected files, repeated failure, and proposed wording
+- keep generated recommendations compact and reviewable
+- avoid append-forever logs becoming the new context sink
+
+### Step 6: Recommend Minimal Fixes
+
+Prefer small fixes such as narrowing triggers, adding dry-run mode, bounding output,
+adding a timeout, changing block to warn, adding a smoke test, or redacting logs.
+Do not turn a hook review into a broad harness rewrite.
+
+---
+
+## Output Format
+
+```md
+## Harness Hooks Review
+
+### Hook Classification
+- Type: <start | stop | pre-action | post-change | logging | other>
+- Trigger: <event/path/tool scope>
+- Failure mode: <block | warn | log-only>
+
+### Findings
+#### BLOCKER: <unsafe hook behavior>
+- Evidence: `<file:line>` or reviewed behavior
+- Risk: <what can break or leak>
+- Fix: <smallest safe fix>
+
+#### SHOULD FIX: <brittleness or usability issue>
+- Evidence: <specific evidence>
+- Risk: <why this will hurt agent/dev workflow>
+- Fix: <smallest safe fix>
+
+### Verification Needed
+- <hook smoke test, timeout proof, dry-run output, or config check>
+
+### Verdict
+- APPROVE / COMMENT / REQUEST_CHANGES
+```
+
+---
+
+## Common Pitfalls
+
+- Treating hooks as prompts instead of deterministic scripts.
+- Blocking on expensive full-repo checks for every small agent action.
+- Writing instruction updates automatically from one noisy session.
+- Logging raw prompts, secrets, tokens, or sensitive file contents.
+- Making a hook client-specific without documenting fallback behavior for other
+  agent tools.

package/skills/implementation-task-planner/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: "implementation-task-planner"
+description: "Load when the user has a PRD, issue, acceptance criteria, or requirements doc and wants a staged implementation task list with relevant files, tests, validation steps, and review checkpoints."
+version: 1.0.0
+required: false
+category: planning
+tools:
+  - claude
+  - copilot
+  - codex
+  - cursor
+routing:
+  triggers:
+  - task-planning
+  - implementation-plan
+  - prd-to-tasks
+  - acceptance-criteria-to-tasks
+  - task-list
+  paths:
+    - exploration-path
+    - full-path
+    - policy-path
+---
+
+# Implementation Task Planner
+
+You are a specialist in turning a PRD, issue, requirements document, or acceptance criteria into an implementation task list that an agent or developer can execute safely.
+
+This skill produces a plan and task artifact. It does not implement the tasks.
+
+## When to Load
+
+Load this skill when the user asks to:
+
+- generate implementation tasks from a PRD, spec, issue, or acceptance criteria
+- break a feature into staged work items before coding
+- identify likely files, test files, and validation gates for a feature
+- convert product requirements into a task checklist
+- create a task list that an implementation agent can work through one item at a time
+
+Do not load this skill for:
+
+- creating the PRD itself — use `skills/product-requirements-writer/SKILL.md`
+- reviewing code against a spec — use `skills/spec-reviewer/SKILL.md`
+- implementing tasks immediately unless the user explicitly switches to execution
+- tiny edits where a task list adds more ceremony than clarity
+
+## Core Principle: Plan Executable Slices, Not Vague Milestones
+
+A good task list reduces ambiguity for the implementation phase. Each task should be small enough to execute and verify, ordered by dependency, and connected to likely files, tests, and quality gates.
+
+Do not invent file paths from vibes. Inspect the repository structure and existing patterns before naming relevant files. If repo context is unavailable, mark file paths as tentative.
+
+## Process
+
+### 1. Intake the Source Requirements
+
+Read the PRD/spec/issue/acceptance criteria. Identify:
+
+- feature name and purpose
+- functional requirements
+- non-goals and constraints
+- user-visible behaviors
+- data/API/type changes
+- test and verification implications
+- open questions that block planning
+
+If requirements are too vague to plan safely, ask a concise clarifying question or route back to `skills/product-requirements-writer/SKILL.md`.
+
+### 2. Inspect Repo Structure Before Naming Files
+
+When working in a repo, use the lightest safe codebase navigation:
+
+- check project instructions and existing planning conventions
+- inspect top-level folders and relevant source/test roots
+- search for existing related components, services, routes, commands, or utilities
+- identify the project-native test/type/lint commands if present
+
+Only list files as concrete when they are grounded in repo evidence. Use `likely` or `tentative` labels when a path is inferred.
+
+### 3. Generate Parent Tasks First
+
+Create high-level tasks before detailed subtasks when user alignment matters. Keep parent tasks few and outcome-oriented.
+
+Default parent task shape:
+
+```md
+## Tasks
+
+- [ ] 0.0 Create feature branch
+- [ ] 1.0 Confirm requirements and existing patterns
+- [ ] 2.0 Define contracts, types, or interfaces
+- [ ] 3.0 Implement the smallest end-to-end behavior slice
+- [ ] 4.0 Add tests for required behavior and edge cases
+- [ ] 5.0 Integrate, verify, and document
+```
+
+Include task `0.0 Create feature branch` unless the user or repo workflow says not to create branches.
+
+If the user asked for an interactive planning flow, stop after parent tasks and ask:
+
+```md
+I have generated the high-level tasks based on the requirements. Ready to generate the sub-tasks? Respond with "Go" to proceed.
+```
+
+If the user asked for the full task list in one pass, continue to subtasks without the pause.
+
+### 4. Generate Subtasks
+
+Subtasks should be concrete, ordered, and independently checkable. Include verification steps as tasks, not just prose.
+
+Good subtasks:
+
+- inspect an existing pattern before editing
+- add or update a type/contract
+- write a failing test for one behavior
+- implement the minimum behavior
+- run a named validation command
+- update docs only when the feature has user-facing or operator-facing behavior
+
+Bad subtasks:
+
+- "implement feature"
+- "make it work"
+- "clean up code"
+- broad refactors not required by the PRD
+
+### 5. Identify Relevant Files
+
+List likely files before tasks. Include test files near the corresponding implementation files. Each entry needs a short reason.
+
+Use this format:
+
+```md
+## Relevant Files
+
+- `path/to/file.ts` - Why this file is relevant.
+- `path/to/file.test.ts` - Tests for `path/to/file.ts`.
+- `tasks/prd-[feature-name].md` - Source PRD for this task list (or the actual existing PRD path).
+```
+
+If a file does not exist yet, mark it as `(new)`. If it is inferred, mark it as `(tentative)`.
+
+### 6. Save the Artifact When Working in a Repo
+
+Save the task list under the project root as:
+
+```txt
+tasks/tasks-[feature-name].md
+```
+
+Follow the repo's existing planning/spec directory if one exists.
+
+## Output Format
+
+```md
+# Tasks: <Feature Name>
+
+## Source
+
+- PRD/spec/issue: `<path or description>`
+- Planning assumptions: <brief assumptions or "none">
+
+## Relevant Files
+
+- `path/to/file` - <why relevant>
+
+## Notes
+
+- Use the project-native test/type/lint commands listed in repo instructions.
+- Update each checkbox as work completes.
+- Keep implementation scoped to the PRD non-goals.
+
+## Instructions for Completing Tasks
+
+As each task is completed, change `- [ ]` to `- [x]` in this file. Update after each subtask, not just after a parent task.
+
+## Tasks
+
+- [ ] 0.0 Create feature branch
+  - [ ] 0.1 Create and check out a branch for this feature.
+- [ ] 1.0 <Parent task>
+  - [ ] 1.1 <Subtask>
+```
+
+## Verification Checklist
+
+Before returning the task list, verify:
+
+- [ ] Tasks trace back to PRD/spec requirements and non-goals
+- [ ] Relevant files are grounded in repo evidence or marked tentative
+- [ ] Tests and validation gates are included as explicit tasks
+- [ ] Parent tasks are ordered by dependency
+- [ ] Subtasks are small enough for one implementation pass
+- [ ] No implementation code was changed
+- [ ] Saved path follows repo convention or `tasks/tasks-[feature-name].md`
+
+## Common Pitfalls
+
+1. **Inventing file paths without inspecting the repo.** Either inspect first or label paths tentative.
+2. **Skipping validation tasks.** A task list without test/type/lint/check steps pushes ambiguity into implementation.
+3. **Expanding scope beyond the PRD.** Non-goals are binding unless the user changes them.
+4. **Planning giant tasks.** If a task cannot be implemented and verified in one pass, split it.
+5. **Forcing a confirmation pause when the user asked for a complete plan.** Pause by default for interactive planning; continue when the request clearly asks for full output.
+6. **Implementing while planning.** This skill creates the task artifact and stops.