agent-directives 0.1.0

package/manifest.json

@@ -0,0 +1,387 @@
+{
+  "version": "1.0.0",
+  "entries": [
+    {
+      "id": "adaptive-routing",
+      "type": "directive",
+      "path": "directives/adaptive-routing.md",
+      "description": "Selects the lightest safe workflow path, relevant directives/skills, and handoff requirements based on task intent, risk, and touched surfaces.",
+      "version": "1.3.0",
+      "required": true,
+      "category": "workflow",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ]
+    },
+    {
+      "id": "architecture-boundaries",
+      "type": "directive",
+      "path": "directives/architecture-boundaries.md",
+      "description": "Preserves architecture DAG boundaries for imports, exports, packages, services, shared code, and dependency direction.",
+      "version": "1.0.0",
+      "required": false,
+      "category": "architecture",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ]
+    },
+    {
+      "id": "codebase-navigation",
+      "type": "directive",
+      "path": "directives/codebase-navigation.md",
+      "description": "Guides progressive codebase orientation with the SAFE pattern before implementation, review, or unfamiliar work.",
+      "version": "1.1.0",
+      "required": true,
+      "category": "workflow",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ]
+    },
+    {
+      "id": "context-handoff",
+      "type": "directive",
+      "path": "directives/context-handoff.md",
+      "description": "Compresses task state at directive or session boundaries so later phases can continue from a compact, current-state handoff instead of drifting through accumulated chat history.",
+      "version": "1.0.0",
+      "required": false,
+      "category": "workflow",
+      "tools": [
+        "claude",
+        "codex"
+      ]
+    },
+    {
+      "id": "error-memory",
+      "type": "directive",
+      "path": "directives/error-memory.md",
+      "description": "Captures repeated mistakes in durable error memory only when recurrence and prevention criteria are met.",
+      "version": "1.0.0",
+      "required": false,
+      "category": "memory",
+      "tools": [
+        "claude",
+        "codex"
+      ]
+    },
+    {
+      "id": "exploration-mode",
+      "type": "directive",
+      "path": "directives/exploration-mode.md",
+      "description": "Supports investigation and option discovery before committing to an implementation approach.",
+      "version": "1.0.0",
+      "required": true,
+      "category": "workflow",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ]
+    },
+    {
+      "id": "session-decisions",
+      "type": "directive",
+      "path": "directives/session-decisions.md",
+      "description": "Captures durable decisions for repo policy, architecture, workflow, and cross-cutting conventions.",
+      "version": "1.0.0",
+      "required": false,
+      "category": "memory",
+      "tools": [
+        "claude",
+        "codex"
+      ]
+    },
+    {
+      "id": "specification-driven-development",
+      "type": "directive",
+      "path": "directives/specification-driven-development.md",
+      "description": "Requires written specifications for features or changes large enough that build-and-see would risk rework.",
+      "version": "1.0.0",
+      "required": false,
+      "category": "workflow",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ]
+    },
+    {
+      "id": "task-framing",
+      "type": "directive",
+      "path": "directives/task-framing.md",
+      "description": "Frames non-trivial, ambiguous, high-risk, or cross-cutting tasks before substantial edits.",
+      "version": "1.0.0",
+      "required": true,
+      "category": "workflow",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ]
+    },
+    {
+      "id": "test-driven-development",
+      "type": "directive",
+      "path": "directives/test-driven-development.md",
+      "description": "Defines RED/GREEN/REFACTOR expectations for behavior-changing implementation work and bug fixes.",
+      "version": "1.0.0",
+      "required": false,
+      "category": "testing",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ]
+    },
+    {
+      "id": "type-driven-development",
+      "type": "directive",
+      "path": "directives/type-driven-development.md",
+      "description": "Requires type and contract definition before implementation in typed projects or public API work.",
+      "version": "1.0.0",
+      "required": false,
+      "category": "testing",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ]
+    },
+    {
+      "id": "verification",
+      "type": "directive",
+      "path": "directives/verification.md",
+      "description": "Requires structured evidence of correctness before quality gates and pull requests.",
+      "version": "1.0.0",
+      "required": true,
+      "category": "workflow",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ]
+    },
+    {
+      "id": "workspace-isolation",
+      "type": "directive",
+      "path": "directives/workspace-isolation.md",
+      "description": "Keeps mutable work in an isolated workspace by detecting existing isolation first, preferring native tools, and falling back to git worktrees only when needed.",
+      "version": "1.0.0",
+      "required": false,
+      "category": "workflow",
+      "tools": [
+        "claude",
+        "codex"
+      ]
+    },
+    {
+      "id": "architecture-boundary-reviewer",
+      "type": "skill",
+      "path": "skills/architecture-boundary-reviewer/SKILL.md",
+      "description": "Load when changes touch imports, exports, public APIs, file moves, packages, services, layers, shared code, dependency direction, cycles, or the user asks if architecture boundaries still hold.",
+      "version": "1.0.0",
+      "required": false,
+      "category": "review",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ]
+    },
+    {
+      "id": "code-reviewer",
+      "type": "skill",
+      "path": "skills/code-reviewer/SKILL.md",
+      "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"
+      ]
+    },
+    {
+      "id": "codebase-health-reviewer",
+      "type": "skill",
+      "path": "skills/codebase-health-reviewer/SKILL.md",
+      "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"
+      ]
+    },
+    {
+      "id": "harness-hooks-reviewer",
+      "type": "skill",
+      "path": "skills/harness-hooks-reviewer/SKILL.md",
+      "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"
+      ]
+    },
+    {
+      "id": "implementation-task-planner",
+      "type": "skill",
+      "path": "skills/implementation-task-planner/SKILL.md",
+      "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"
+      ]
+    },
+    {
+      "id": "mcp-integration-reviewer",
+      "type": "skill",
+      "path": "skills/mcp-integration-reviewer/SKILL.md",
+      "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"
+      ]
+    },
+    {
+      "id": "product-requirements-writer",
+      "type": "skill",
+      "path": "skills/product-requirements-writer/SKILL.md",
+      "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"
+      ]
+    },
+    {
+      "id": "production-readiness-reviewer",
+      "type": "skill",
+      "path": "skills/production-readiness-reviewer/SKILL.md",
+      "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"
+      ]
+    },
+    {
+      "id": "self-audit",
+      "type": "skill",
+      "path": "skills/self-audit/SKILL.md",
+      "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"
+      ]
+    },
+    {
+      "id": "spec-reviewer",
+      "type": "skill",
+      "path": "skills/spec-reviewer/SKILL.md",
+      "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"
+      ]
+    },
+    {
+      "id": "subagent-driven-development",
+      "type": "skill",
+      "path": "skills/subagent-driven-development/SKILL.md",
+      "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"
+      ]
+    },
+    {
+      "id": "systematic-debugging",
+      "type": "skill",
+      "path": "skills/systematic-debugging/SKILL.md",
+      "description": "Load when the user reports a bug, failing test, CI/build/lint/typecheck failure, regression, flaky behavior, unexpected behavior, or asks to fix a failure or root-cause it.",
+      "version": "1.0.0",
+      "required": true,
+      "category": "debugging",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ]
+    },
+    {
+      "id": "test-reviewer",
+      "type": "skill",
+      "path": "skills/test-reviewer/SKILL.md",
+      "description": "Load when the user asks to write or review tests, TDD cases, eval scenarios, coverage, assertions, or mocks, or says tests are shallow, flaky, brittle, or too close to implementation.",
+      "version": "1.1.0",
+      "required": true,
+      "category": "testing",
+      "tools": [
+        "claude",
+        "copilot",
+        "codex",
+        "cursor"
+      ]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "agent-directives",
+  "version": "0.1.0",
+  "description": "Reusable agent directives, skills, and CLI tooling for AI coding workflows",
+  "license": "MIT",
+  "author": "Rob Simpson <rsimpson2@me.com>",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "agent-directives": "./dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "directives/",
+    "skills/",
+    "templates/",
+    "manifest.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pertrai1/agent-directives.git"
+  },
+  "homepage": "https://github.com/pertrai1/agent-directives#readme",
+  "bugs": {
+    "url": "https://github.com/pertrai1/agent-directives/issues"
+  },
+  "scripts": {
+    "check": "npm run typecheck && npm run lint && npm run validate && npm run version:check && npm run manifest:check && npm run test:cli && npm run test:version-bumps && npm run test:package-release && npm run pack:check",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "validate": "tsx scripts/validate-directives.ts",
+    "version:check": "tsx scripts/validate-version-bumps.ts",
+    "eval:scenario": "tsx scripts/eval-scenario.ts",
+    "eval:report": "tsx evals/report-results.ts",
+    "context:audit": "tsx src/cli.ts context-audit",
+    "manifest": "tsx scripts/generate-manifest.ts",
+    "manifest:check": "npm run manifest && git diff --exit-code manifest.json",
+    "pack:check": "npm run build && npm pack --dry-run",
+    "cli": "tsx src/cli.ts",
+    "test:cli": "tsx scripts/test-cli.ts",
+    "test:version-bumps": "tsx scripts/test-version-bumps.ts",
+    "test:package-release": "tsx scripts/test-package-release.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "prepare": "npm run build",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "npm run build && changeset publish"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.7.0",
+    "@changesets/cli": "^2.31.0",
+    "@eslint/js": "^10.0.1",
+    "@eslint/markdown": "^8.0.2",
+    "@types/node": "^24.0.0",
+    "eslint": "^10.4.0",
+    "eslint-plugin-llm-core": "^0.23.0",
+    "globals": "^17.6.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.4.5",
+    "typescript-eslint": "^8.60.0"
+  }
+}

package/skills/architecture-boundary-reviewer/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: "architecture-boundary-reviewer"
+description: "Load when changes touch imports, exports, public APIs, file moves, packages, services, layers, shared code, dependency direction, cycles, or the user asks if architecture boundaries still hold."
+version: 1.0.0
+required: false
+category: review
+tools:
+  - claude
+  - copilot
+  - codex
+  - cursor
+routing:
+  triggers:
+  - imports
+  - exports
+  - packages
+  - shared-code
+  - service-boundaries
+  - architecture-review
+  paths:
+    - boundary-path
+    - review-path
+---
+
+# Architecture Boundary Reviewer
+
+You are a specialist in reviewing whether a change preserves the project's
+architectural dependency graph. Your job is to catch illegal imports, boundary
+leaks, cycles, public API bypasses, and shared-code misuse before the change is
+merged.
+
+This skill complements test-reviewer and spec-reviewer. Tests can pass while the
+architecture gets worse. Boundary review asks: *does this change still fit the
+DAG?*
+
+---
+
+## When to Use
+
+Use this skill before merging or final verification when a change includes any of
+these signals:
+
+- New or changed imports/exports
+- File moves between folders, packages, services, or layers
+- New shared utilities or changes to existing shared/common code
+- New package/workspace dependencies
+- Cross-feature, cross-service, or cross-package calls
+- Public API or package entry point changes
+- Refactors that move behavior across layers
+- Any Fallow, lint, dependency-cruiser, Nx, or GitNexus warning about boundaries,
+  cycles, dependency direction, or architecture drift
+
+Do not use this skill for pure text/docs changes unless they alter documented
+architecture rules.
+
+---
+
+## Review Principle: Every Edge Has a Direction
+
+Every dependency edge has architectural meaning. Review both explicit edges and
+implicit edges:
+
+| Edge type | Examples |
+| --- | --- |
+| Static import | `import { x } from "../infra/db"` |
+| Dynamic import | `await import("./feature")` |
+| Public export | `export * from "./internal"` |
+| Package dependency | adding a dependency to `package.json` |
+| Runtime registration | plugin registries, callbacks, dependency injection |
+| Test leakage | production code importing test fixtures/helpers |
+| Deep import | importing `feature/internal/foo` instead of the feature API |
+
+The review fails if a new edge points in a forbidden direction, bypasses the
+public contract, or creates a cycle.
+
+---
+
+## Review Process
+
+### Step 1: Load the Boundary Contract
+
+Find the strongest available source of truth:
+
+1. Project instruction files (`AGENTS.md`, `CLAUDE.md`, Copilot instructions)
+2. Architecture docs, ADRs, or decision logs
+3. Existing lint/monorepo/boundary configuration
+4. Package/workspace structure and public `exports`
+5. Existing import patterns near the changed code
+6. Tool output from Fallow or GitNexus if available
+
+Record whether each rule is **explicit** or **inferred**. Inferred rules should be
+stated with lower confidence.
+
+### Step 2: Classify Changed Files
+
+For every changed production file, classify it:
+
+```md
+- File: `src/domain/user.ts`
+  - Zone: `domain`
+  - Public API: exported through `src/domain/index.ts`? yes/no
+  - Allowed imports: `shared` only
+  - Changed role: added validation helper
+```
+
+If a file cannot be classified, flag it as an uncertainty. Do not invent a
+confident architecture label.
+
+### Step 3: List Changed Edges
+
+Inspect the diff and list every added/changed edge:
+
+```md
+- `src/features/auth/login.ts` → `src/shared/validation.ts` (allowed)
+- `src/domain/user.ts` → `src/infra/db.ts` (violation: domain imports infra)
+```
+
+Focus on changed edges first, then look for newly exposed public exports and
+file moves that affect dependents.
+
+### Step 4: Check for Five Boundary Failures
+
+| Failure | What to look for | Severity |
+| --- | --- | --- |
+| Upward import | lower/core layer imports upper/UI/app layer | Critical |
+| Sideways internal import | feature imports another feature's internals | Critical |
+| Public API bypass | package/feature deep import skips entry point | Warning/Critical |
+| Cycle introduced | circular file/package/layer dependency | Critical |
+| Shared pollution | shared/common imports app/feature specifics or receives unstable behavior | Warning |
+
+### Step 5: Use Tool Evidence When Available
+
+For TypeScript/JavaScript projects with Fallow:
+
+```bash
+npx fallow list --boundaries
+npx fallow dead-code --boundary-violations
+npx fallow dead-code --circular-deps
+```
+
+For graph-backed orientation with GitNexus:
+
+```bash
+gitnexus analyze
+gitnexus wiki
+```
+
+Use GitNexus/MCP graph context to identify dependents, clusters, services, and
+execution flows. Treat GitNexus as evidence for understanding impact unless the
+project has explicit GitNexus queries that enforce boundary rules.
+
+If a tool is unavailable, do not fail the review solely for that reason. State the
+manual evidence used instead.
+
+---
+
+## Output Format
+
+```md
+## Architecture Boundary Review
+
+### Boundary Contract
+- Source: explicit/inferred rule source
+- Zones/layers involved: ...
+- Allowed direction: ...
+
+### Changed Edges
+| From | To | Status | Notes |
+| --- | --- | --- | --- |
+| `src/...` | `src/...` | Allowed / Violation / Unclear | reason |
+
+### Findings
+#### CRITICAL: Domain imports infrastructure directly
+- Edge: `src/domain/user.ts` → `src/infra/db.ts`
+- Rule violated: domain may not import infrastructure
+- Why it matters: reverses dependency direction and couples core logic to storage
+- Fix: define a port/interface in domain/application; implement it in infra
+
+### Tool Evidence
+- Fallow: `npx fallow dead-code --boundary-violations` → 0 violations / N violations / unavailable
+- Cycle check: ...
+- GitNexus/dependency graph: ...
+
+### Verdict
+- ✅ Pass — no illegal edges found
+- ⚠️ Pass with documented uncertainty — human should review named assumptions
+- ❌ Block — boundary violation must be fixed before merge
+```
+
+---
+
+## Fix Patterns
+
+| Violation | Preferred fix |
+| --- | --- |
+| Domain imports infrastructure | Create a port/interface; inject implementation from upper layer |
+| UI imports database/client | Route through application/use-case/service boundary |
+| Feature imports sibling internals | Depend on sibling public API or extract shared behavior |
+| Shared imports feature/app code | Pass data/config in; move specific behavior out of shared |
+| Deep package import | Export through package entry point or add approved subpath export |
+| Cycle from convenience import | Split types/constants, invert dependency, or move shared concept down |
+
+---
+
+## Common Pitfalls
+
+1. **Only reviewing files, not edges.** A file can look reasonable while the new
+   import graph is invalid.
+2. **Treating `shared` as a safe dumping ground.** Shared code must be more stable
+   and less specific than its consumers.
+3. **Ignoring test-to-production leakage.** Production code must never depend on
+   test fixtures, mocks, or factories.
+4. **Approving deep imports because they compile.** Compiling does not make an
+   internal path part of the public contract.
+5. **Adding boundary enforcement during an unrelated change.** Propose a separate
+   issue/PR for new repo-wide policy unless the user requested it.
+
+---
+
+## Verification Checklist
+
+- [ ] Boundary contract source identified as explicit or inferred
+- [ ] Every changed production file classified into a zone/layer/package/service
+- [ ] Every added/changed import/export/package edge reviewed
+- [ ] Public API bypasses and deep imports checked
+- [ ] Circular dependency risk checked manually or with a tool
+- [ ] Fallow/GitNexus/lint evidence included when available
+- [ ] Verdict is Pass, Pass with uncertainty, or Block with concrete fixes