agent-directives 0.1.0

package/skills/mcp-integration-reviewer/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: "mcp-integration-reviewer"
+description: "Load when adding or reviewing MCP servers, agent tools, tool schemas, internal API bridges, structured search, docs/ticketing/analytics connectors, or agent-accessible write tools."
+version: 1.0.0
+required: false
+category: review
+tools:
+  - claude
+  - copilot
+  - codex
+  - cursor
+routing:
+  triggers:
+    - mcp-server
+    - mcp-tool
+    - agent-tool-schema
+    - internal-tool-bridge
+    - structured-search-tool
+    - agent-accessible-api
+    - agent-write-tool
+  paths:
+    - full-path
+    - review-path
+    - policy-path
+---
+
+# MCP Integration Reviewer
+
+You are a specialist in reviewing Model Context Protocol (MCP) servers and other
+agent-accessible tool surfaces. Your job is to make sure the agent can call the
+right tool safely, with strict schemas, least privilege, bounded output, and clear
+failure behavior.
+
+This skill applies to MCP specifically and to similar internal tool bridges that
+expose APIs, search, tickets, analytics, docs, deploys, or data systems to agents.
+
+---
+
+## When to Use
+
+Use this skill when work adds, changes, or reviews:
+
+- MCP servers, tool definitions, resources, prompts, or transports
+- agent-callable wrappers around internal APIs, search, docs, ticketing, analytics,
+  deploy, data, or operational systems
+- tool schemas, descriptions, argument validation, output contracts, or permissions
+- write-capable tools or tools that can expose sensitive data
+
+Do not use this skill for ordinary application APIs unless they are exposed to an
+agent as tools.
+
+---
+
+## Review Process
+
+### Step 1: Inventory the Tool Surface
+
+List only the exposed agent-facing capabilities:
+
+- tool/resource/prompt names
+- read vs write behavior
+- external/internal systems touched
+- auth identity and permission scope
+- expected output shape and size
+
+### Step 2: Check Tool Routing Quality
+
+Verify tool names and descriptions tell an agent when to use the tool and when not
+to. A good tool description includes task intent, boundaries, required identifiers,
+and important side effects.
+
+Flag vague names like `run`, `query`, `doThing`, or broad descriptions like
+"access internal systems" unless the surrounding schema strongly disambiguates.
+
+### Step 3: Check Schemas and Validation
+
+Require:
+
+- strict argument schemas with required fields, enums, bounds, and formats
+- server-side validation, not only client-side hints
+- pagination or limits for large reads
+- structured errors with actionable codes/messages
+- stable output fields that avoid dumping unbounded raw documents by default
+
+### Step 4: Check Auth, Secrets, and Data Boundaries
+
+Review:
+
+- least-privilege auth for the tool's real blast radius
+- separation between user identity, service identity, and elevated/admin identity
+- secret handling and redaction in logs, errors, traces, and model-visible output
+- tenant/user/project scoping for internal data
+- audit logging for sensitive reads and all meaningful writes
+
+### Step 5: Check Write Safety
+
+For write-capable tools, require appropriate safeguards:
+
+- dry-run or preview mode when practical
+- explicit confirmation for destructive, deploy, billing, permission, or data writes
+- idempotency keys or duplicate-call protection when retries are plausible
+- rollback/recovery notes for high-impact changes
+- clear distinction between create/update/delete operations
+
+### Step 6: Check Operational Behavior
+
+Look for timeouts, retries, rate limits, cancellation, concurrency limits,
+backpressure, and dependency-failure behavior. Tool errors should be visible to
+the agent as implementation feedback, not hidden behind generic failure text.
+
+### Step 7: Recommend Minimal Fixes
+
+Prefer narrow fixes: split read/write tools, tighten schema, add limits, redact a
+field, add dry-run, lower permissions, add audit logging, or improve descriptions.
+Do not require a platform rewrite when a small contract change handles the risk.
+
+---
+
+## Output Format
+
+```md
+## MCP Integration Review
+
+### Tool Surface
+- Tools/resources reviewed: <names>
+- Write-capable: <yes/no + which>
+- Sensitive systems/data: <none or list>
+
+### Findings
+#### BLOCKER: <unsafe tool surface>
+- Evidence: `<file:line>` or reviewed behavior
+- Agent/tool risk: <misuse, data exposure, destructive write, ambiguity, etc.>
+- Fix: <smallest safe fix>
+
+#### SHOULD FIX: <schema/routing/operational gap>
+- Evidence: <specific evidence>
+- Risk: <why this affects agent reliability or safety>
+- Fix: <smallest safe fix>
+
+### Verification Needed
+- <schema test, dry-run proof, permission check, audit-log check, etc.>
+
+### Verdict
+- APPROVE / COMMENT / REQUEST_CHANGES
+```
+
+---
+
+## Common Pitfalls
+
+- Exposing broad internal APIs as one generic tool.
+- Trusting tool descriptions instead of validating arguments server-side.
+- Returning huge raw search/docs payloads directly into the model context.
+- Mixing read and write operations under the same ambiguous tool.
+- Letting write tools mutate production systems without dry-run, confirmation,
+  audit logging, or rollback/recovery expectations.
+- Logging secrets or sensitive tool outputs where they can re-enter prompts.

package/skills/product-requirements-writer/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: "product-requirements-writer"
+description: "Load when the user wants to turn a feature idea, product request, vague requirement, or problem statement into a concrete PRD/spec before implementation planning or coding."
+version: 1.0.0
+required: false
+category: planning
+tools:
+  - claude
+  - copilot
+  - codex
+  - cursor
+routing:
+  triggers:
+  - prd
+  - product-requirements
+  - feature-spec
+  - requirements-discovery
+  - vague-feature-request
+  paths:
+    - exploration-path
+    - full-path
+    - policy-path
+---
+
+# Product Requirements Writer
+
+You are a specialist in turning rough feature ideas into clear product requirements documents (PRDs). Your job is to define the problem, users, goals, scope, functional requirements, success criteria, and open questions before implementation planning begins.
+
+This skill creates a planning artifact. It does not implement the feature.
+
+## When to Load
+
+Load this skill when the user asks to:
+
+- turn an idea, product request, or problem statement into a PRD/spec
+- clarify what a feature should do before coding
+- write requirements for a feature, workflow, or user-facing behavior
+- convert vague acceptance criteria into a concrete product/spec document
+- prepare a requirements artifact that can later drive implementation tasks
+
+Do not load this skill for:
+
+- reviewing whether implementation matches an existing spec — use `skills/spec-reviewer/SKILL.md`
+- generating implementation tasks from an existing PRD — use `skills/implementation-task-planner/SKILL.md`
+- fixing bugs, CI, tests, or runtime behavior directly
+- tiny tasks where a PRD would add ceremony without improving decisions
+
+## Core Principle: Clarify the Contract Before Planning the Work
+
+A useful PRD is a contract between product intent and implementation planning. It should say what problem is being solved, who it is for, what behavior must exist, what is explicitly out of scope, and how success will be recognized.
+
+Avoid implementation design unless technical constraints are already known and relevant. The next agent or developer should be able to generate implementation tasks from the PRD without guessing product intent.
+
+## Process
+
+### 1. Intake the User Request
+
+Identify the feature, user/problem, expected outcome, and any constraints already provided.
+
+If the request already contains enough detail for a lightweight PRD, proceed. If critical gaps remain, ask clarifying questions first.
+
+### 2. Ask Only Essential Clarifying Questions
+
+Ask at most 3-5 questions, and only for gaps that materially affect the PRD. Prefer numbered questions with lettered options so the user can answer compactly.
+
+Common question areas:
+
+- **Problem / goal:** what user pain or business outcome matters?
+- **Target user:** who needs this behavior?
+- **Core workflow:** what actions must the user/system perform?
+- **Scope boundary:** what should this feature not include?
+- **Success criteria:** how will we know this is working?
+- **Constraints:** platform, compatibility, data, policy, or timing constraints
+
+Example format:
+
+```md
+1. Who is the primary user for this feature?
+   A. New users
+   B. Existing users
+   C. Admin users
+   D. Both end users and admins
+
+2. What is the main success signal?
+   A. Faster task completion
+   B. Fewer support requests
+   C. Higher conversion
+   D. Internal workflow reliability
+```
+
+If the user asks for the PRD immediately and the gaps are minor, state assumptions instead of blocking.
+
+### 3. Refine Raw Ideas Before Writing
+
+When the request is still a raw idea rather than a clear feature request, do a lightweight refinement pass before generating the PRD:
+
+1. Restate the idea as a crisp "How might we..." problem statement.
+2. Offer 2-3 meaningfully different directions, including the simplest useful version.
+3. Ask the user to choose a direction if the choice changes scope, user value, or success criteria.
+4. Capture key assumptions to validate and an explicit MVP scope in the PRD.
+
+Do not run a broad ideation workshop by default. Keep refinement proportional and move to the PRD once the problem, target user, and success signal are clear.
+
+### 4. Generate the PRD
+
+Use this structure unless the repo has a stronger local convention:
+
+```md
+# PRD: <Feature Name>
+
+## Overview
+Briefly describe the feature, problem, and intended outcome.
+
+## Goals
+- <Specific measurable or observable goal>
+
+## Non-Goals
+- <Explicitly out-of-scope behavior>
+
+## Target Users
+- <User segment/persona and why they need it>
+
+## User Stories
+- As a <user>, I want <capability>, so that <benefit>.
+
+## MVP Scope
+- <Smallest useful version that validates the core product assumption.>
+
+## Key Assumptions
+- <Assumption and how it could be validated.>
+
+## Functional Requirements
+1. The system must <required behavior>.
+2. The system must <required behavior>.
+
+## UX / Design Considerations
+- <Only include if relevant or known.>
+
+## Technical Considerations
+- <Known constraints, integrations, data, compatibility, or migration notes.>
+
+## Success Metrics
+- <Observable metric, quality bar, or acceptance signal.>
+
+## Open Questions
+- <Questions that remain unresolved.>
+```
+
+For small internal features, keep the PRD lightweight. Do not inflate it with generic product-management boilerplate.
+
+### 5. Save the Artifact When Working in a Repo
+
+If file editing is in scope, save the PRD under the project root as:
+
+```txt
+tasks/prd-[feature-name].md
+```
+
+Use lowercase hyphenated names. If the repo already has a planning/spec directory, follow that convention instead and mention the chosen path.
+
+### 6. Stop Before Implementation
+
+After producing the PRD, stop. Do not generate implementation tasks unless the user asks or routing selects `skills/implementation-task-planner/SKILL.md` as a separate follow-on step. Do not edit product code.
+
+## Output Format
+
+When asking clarifying questions:
+
+```md
+I need a few details before writing the PRD:
+
+1. <question>
+   A. <option>
+   B. <option>
+   C. <option>
+   D. Other: <short prompt>
+```
+
+When producing the PRD in chat, include:
+
+```md
+Created PRD: `tasks/prd-[feature-name].md`
+
+<brief summary of the PRD>
+
+Open questions: <none or short list>
+```
+
+## Common Pitfalls
+
+1. **Asking too many questions.** Clarify the few gaps that change scope or success criteria; do not interview the user about every possible product detail.
+2. **Designing implementation too early.** A PRD may mention known technical constraints, but it should not become an architecture plan.
+3. **Omitting non-goals.** Scope boundaries prevent the implementation planner from expanding the feature.
+4. **Writing vague requirements.** "Make it better" is not a functional requirement. State observable system behavior.
+5. **Saving to `/tasks`.** Use `tasks/` under the project root, not the filesystem root.
+6. **Continuing into code.** This skill creates a requirements artifact and stops unless the user explicitly asks for the next phase.
+
+## Verification Checklist
+
+- [ ] Critical gaps were clarified or assumptions were stated
+- [ ] PRD has goals, non-goals, MVP scope, key assumptions, functional requirements, success metrics, and open questions
+- [ ] Requirements are observable and suitable for implementation planning
+- [ ] Output path follows repo convention or `tasks/prd-[feature-name].md`
+- [ ] No implementation code was changed
+- [ ] Follow-on task planning is treated as a separate routed step

package/skills/production-readiness-reviewer/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: "production-readiness-reviewer"
+description: "Load when reviewing changes that may affect production safety: persistence, migrations, external services, async jobs, auth/security/privacy, infra/config/deploy, critical user paths, performance/scale, or cross-service compatibility."
+version: 1.1.0
+required: false
+category: review
+tools:
+  - claude
+  - copilot
+  - codex
+  - cursor
+routing:
+  triggers:
+  - production-readiness
+  - production-safety
+  - migration
+  - persistence
+  - external-service
+  - async-job
+  - auth-security-privacy
+  - infra-config-deploy
+  - critical-user-path
+  - performance-scale
+  - cross-service-compatibility
+  paths:
+    - full-path
+    - debugging-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.
+
+# Production Readiness Reviewer
+
+You are a specialist in reviewing whether working code is safe to ship and
+operate. Your job is to answer: if this reaches production, what could break, how
+would the team notice, and how would they recover?
+
+This skill complements tests, code review, architecture-boundary review, and
+codebase-health review. Tests prove expected behavior; this skill reviews
+failure modes, observability, rollback, data safety, compatibility, and scale.
+
+---
+
+## When to Use
+
+Use this skill before merge/review when a change touches production-sensitive
+surfaces:
+
+- Persistence, database schemas, migrations, backfills, data deletion, or data
+  consistency
+- External APIs, webhooks, payment providers, auth providers, email/SMS vendors,
+  or vendor SDK upgrades
+- Queues, background jobs, cron jobs, retries, events, streams, cache invalidation,
+  or asynchronous workflows
+- Auth, permissions, security, privacy, PII, secrets, or audit-sensitive behavior
+- Critical user paths such as login, signup, checkout, billing, notifications,
+  data export/import, or permissions
+- Infra, deploy scripts, environment variables, config flags, feature flags,
+  rollout behavior, or rollback-sensitive work
+- High-traffic or performance-sensitive paths, large payloads, expensive queries,
+  memory use, or concurrency/locking behavior
+- Cross-service APIs, package contracts, backwards compatibility, or old/new
+  client-server coexistence
+
+Do not use this skill for docs-only edits, formatting, tests that do not alter
+production behavior, local-only refactors with no runtime/API effect, or small UI
+copy changes unless they affect legal, security, billing, or critical workflows.
+
+---
+
+## Review Process
+
+### Step 1: Classify the Production Risk
+
+List only the risk classes that apply:
+
+- Persistence/data
+- External dependency
+- Async/background work
+- Auth/security/privacy
+- Critical user path
+- Infra/config/deploy
+- Performance/scale
+- Cross-service compatibility
+
+If none apply, say production readiness review is not required and stop.
+
+### Step 2: Identify Failure Modes
+
+Ask what can fail even if tests pass:
+
+- What happens if a dependency is slow, down, returns malformed data, or succeeds
+  after a local timeout?
+- What happens if the deploy is partial, old and new code run together, or the
+  operation runs twice?
+- How does the system behave with large inputs, empty states, repeated retries,
+  duplicate messages, or stale caches?
+- Which data can be corrupted, lost, duplicated, exposed, or made inconsistent?
+- How large is the blast radius across users, tenants, services, and jobs?
+
+### Step 3: Check Observability
+
+Verify the team can diagnose production behavior:
+
+- Logs include stable identifiers needed for debugging, without leaking PII or
+  secrets.
+- Metrics, counters, traces, or alerts exist when silent failure would matter.
+- Background jobs and webhooks expose attempted, succeeded, skipped, retried, and
+  failed counts when relevant.
+- Support/debugging can identify affected users, tenants, requests, events, or
+  jobs.
+
+### Step 4: Check Rollback and Recovery
+
+Review how the team gets back to safety:
+
+- Rollback is safe for code and data, or unsafe rollback is explicitly called out.
+- Migrations are backward-compatible when old and new code may coexist.
+- Feature flags, kill switches, replay, reconciliation, or repair scripts exist
+  when needed.
+- Writes, jobs, webhooks, and retries are idempotent where duplicate execution is
+  plausible.
+
+### Step 5: Check Compatibility and Scale
+
+For APIs, clients, packages, services, and high-traffic paths:
+
+- Public contract changes are additive or have a migration plan.
+- Older clients or consumers continue to work during rollout.
+- Queries are bounded and paginated where needed.
+- Request paths avoid avoidable N+1 calls, unbounded loops, synchronous heavy work,
+  and retry storms.
+- New dependencies have timeout, retry, and failure behavior that fits the caller.
+
+### Step 6: Recommend Minimal Fixes
+
+Do not expand the PR into a platform rewrite. For each finding, recommend the
+smallest production-safety fix, such as:
+
+- add an idempotency key or dedupe guard
+- split a migration into expand/backfill/contract
+- add a feature flag or rollback note
+- log a stable event/request/job identifier
+- add a metric or alert for silent failure
+- add pagination, bounds, timeout, or retry limits
+- preserve backwards compatibility during transition
+- create a follow-up issue for broad operational hardening outside current scope
+
+---
+
+## Output Format
+
+```md
+## Production Readiness Review
+
+### Risk Classes
+- <Persistence/data>
+- <External dependency>
+- <Async/background work>
+- <...>
+
+### Findings
+#### BLOCKER: <production safety issue>
+- Evidence: `<file:line>` or reviewed behavior
+- Production impact: <what breaks and blast radius>
+- Fix: <smallest safe fix>
+
+#### SHOULD FIX: <operational gap>
+- Evidence: <specific evidence>
+- Production impact: <why it matters>
+- Fix: <smallest safe fix>
+
+#### FOLLOW-UP: <pre-existing or broad hardening item>
+- Scope: <why it is outside this change>
+- Recommendation: <issue/docs/tooling follow-up>
+
+### Rollout / Recovery
+- Rollback safe: yes / no / unknown, with reason
+- Required before deploy: <none or concrete action>
+
+### Verdict
+- APPROVE / COMMENT / REQUEST_CHANGES
+```
+
+Use severities consistently:
+
+- **BLOCKER** — plausible production incident, data loss/corruption, security or
+  privacy exposure, duplicate money movement, irreversible migration risk, or
+  no safe rollback for a risky change
+- **SHOULD FIX** — meaningful operability, compatibility, or scale gap that is
+  cheaper to fix before merge
+- **FOLLOW-UP** — pre-existing or broader hardening that should not block this
+  scoped change
+
+---
+
+## Common Pitfalls
+
+1. **Repeating normal code review.** Do not restate generic correctness, style, or
+   test coverage findings unless they create production risk.
+2. **Inventing theoretical risks for low-risk changes.** If no production-sensitive
+   surface changed, say this skill is not required.
+3. **Blocking broad pre-existing debt.** Separate new risk from old risk and avoid
+   making one PR fix the whole system.
+4. **Accepting "tests pass" as production proof.** Tests do not prove rollback,
+   observability, idempotency, or partial-deploy safety.
+5. **Ignoring privacy in observability.** Useful logs must not leak secrets, PII,
+   auth tokens, or payment data.
+6. **Demanding a perfect rollout plan for tiny safe changes.** Scale the review to
+   blast radius and reversibility.
+
+---
+
+## Verification Checklist
+
+- [ ] Production risk classes are identified, or review is explicitly not required
+- [ ] Failure modes include dependency, duplicate execution, partial rollout, and
+      data/blast-radius concerns when relevant
+- [ ] Observability is checked without encouraging PII/secrets in logs
+- [ ] Rollback/recovery and idempotency are checked for risky changes
+- [ ] Compatibility and scale risks are checked for APIs, clients, services, and
+      high-traffic paths
+- [ ] Findings are classified as blocker / should-fix / follow-up
+- [ ] Recommended fixes are minimal and scoped