agent-directives 0.1.0

package/directives/adaptive-routing.md

@@ -0,0 +1,361 @@
+---
+name: adaptive-routing
+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
+triggers:
+  - every-task
+  - workflow-selection
+  - directive-selection
+routing:
+  load: first
+  applies_to:
+    - implementation
+    - debugging
+    - review
+    - exploration
+    - policy-change
+---
+
+# Adaptive Workflow Routing Directive
+
+**When to load:** Load this directive first for every task, before task framing,
+implementation, debugging, review, or exploration.
+
+The router selects the lightest workflow that still proves safety. Do not load
+every directive by default. Load the directives and skills required by the task
+intent, risk level, and touched surfaces.
+
+---
+
+## Router Output
+
+After routing, briefly display the active workflow path and directive/skill files
+being used so reviewers can verify the agent loaded the expected guidance. Keep
+this as routing evidence, not ceremony. When a harness or runtime provides logs,
+treat its loaded-file manifest as authoritative for which directive files were
+actually presented; the agent's route disclosure is useful self-report, not proof
+of internal model attention.
+
+For tiny low-risk edits, one sentence is enough:
+
+```md
+Route: Light Path; using `directives/adaptive-routing.md`; no additional directives or skills required.
+```
+
+Before major edits, output a short route decision:
+
+```md
+## Workflow Route
+
+- Intent: <feature | bug-fix | refactor | docs | review | exploration | policy-change | mechanical>
+- Path: <Light | Full | Debugging | Boundary | Workspace Isolation | Review | Exploration | Policy> or combined paths
+- Risk: <low | medium | high> with reason
+- Required directives: <paths>
+- Required skills: <paths, if any>
+- Evidence required: <tests/checks/proofs>
+- Handoff required: <yes/no and why>
+- Confirmation needed: <yes/no and why>
+```
+
+For any non-trivial, ambiguous, high-risk, or cross-cutting task, use the full
+block.
+
+---
+
+## Core Routing Rules
+
+1. **Start with project instructions.** Load project-level instructions first
+   (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, or equivalent).
+2. **Pick the lightest safe path.** Do not apply Full Path ceremony to purely
+   mechanical or docs-only work.
+3. **Escalate by risk.** User requests like "quickly" or "just" do not downgrade
+   safety for behavior, security, data, public API, or boundary changes.
+4. **Combine paths when needed.** A bug fix that changes imports uses Debugging
+   Path plus Boundary Path. A policy change with docs edits uses Policy Path plus
+   Light Path gates. Mutable work from a shared checkout may add Workspace
+   Isolation to the base path.
+5. **Prefer evidence over ritual.** Do not emit boilerplate sections with no
+   information. Show the proof that matches the selected path.
+6. **Compact context at boundaries.** Use `directives/context-handoff.md` when
+   switching major phases, handing work to another session/agent, or continuing
+   long-running work where stale context could drift.
+7. **Ask only when necessary.** If classification is uncertain and affects safety
+   or scope, ask one concise clarifying question. Otherwise choose the safer path
+   and state the assumption.
+8. **Bound the implementation.** Prefer the smallest safe change that satisfies
+   the task. Do not expand scope, rewrite adjacent code, introduce abstractions,
+   apply drive-by formatting, perform whole-file rewrites, or fix unrelated
+   issues unless current evidence requires it or the user explicitly requests it.
+
+---
+
+## Skill Discovery Map
+
+Use this map after selecting the workflow path. Do not rely on inference when a
+listed situation matches: load every matching skill before performing work it
+covers. The path column shows where the situation commonly appears; it is not a
+filter that prevents loading a matched skill when paths are combined or escalated.
+If no row matches, state that no specialist skill is required.
+
+| Situation / intent | Common path(s) | Required skill |
+| --- | --- | --- |
+| Vague feature idea, product request, or unclear requirement needs a PRD/spec | Exploration / Full / Policy | `skills/product-requirements-writer/SKILL.md` |
+| PRD, issue, spec, or acceptance criteria needs implementation tasks | Exploration / Full / Policy | `skills/implementation-task-planner/SKILL.md` |
+| Executing an existing implementation plan with multiple mostly independent tasks using delegated subagents or isolated worker sessions | Full / Debugging / Policy | `skills/subagent-driven-development/SKILL.md` |
+| Bug, regression, failing test, failing CI/build/lint/type-check, or unexpected behavior | Debugging | `skills/systematic-debugging/SKILL.md` |
+| Reviewing a PR, branch, diff, or local changes | Review | `skills/code-reviewer/SKILL.md` |
+| Writing, changing, or reviewing tests/eval scenarios | Full / Review | `skills/test-reviewer/SKILL.md` |
+| Implementation must be checked against a written spec/PRD | Full / Review | `skills/spec-reviewer/SKILL.md` |
+| Imports, exports, package boundaries, folders, services, shared utilities, or dependency direction change | Boundary / Review | `skills/architecture-boundary-reviewer/SKILL.md` |
+| TypeScript/JavaScript refactor, cleanup, shared utilities, dead-code, duplication, complexity, or static-analysis health concern | Full / Review | `skills/codebase-health-reviewer/SKILL.md` |
+| Persistence, external services, async jobs, auth/security/privacy, infra/config/deploy, critical user paths, performance/scale, or cross-service compatibility | Full / Debugging / Review | `skills/production-readiness-reviewer/SKILL.md` |
+| Agent harness hooks, start/stop hooks, pre-action hooks, post-change automation, or deterministic agent workflow scripts are added or reviewed | Full / Review / Policy | `skills/harness-hooks-reviewer/SKILL.md` |
+| MCP servers/tools, agent-accessible internal APIs, structured search, docs/ticketing/analytics connectors, tool schemas, or write-capable agent tools are added or reviewed | Full / Review / Policy | `skills/mcp-integration-reviewer/SKILL.md` |
+| Full Path work reaches post-REFACTOR pre-verification checkpoint | Full | `skills/self-audit/SKILL.md` |
+
+---
+
+## Workflow Paths
+
+### Light Path
+
+Use for low-risk, non-behavioral changes:
+
+- typo fixes
+- docs wording edits
+- comments
+- formatting-only changes
+- metadata changes that do not affect runtime, build, tests, packaging, or public API
+
+Required:
+
+- minimal orientation
+- make the change
+- run the relevant project quality gate when available
+- provide concise verification
+- skip handoff unless work will continue in another session or the user requests it
+
+Do **not** use Light Path for bug fixes, behavior changes, public API changes,
+dependency changes, boundary changes, or security/data/auth work.
+
+### Full Path
+
+Use for normal implementation work:
+
+- new features
+- behavior changes
+- meaningful refactors
+- tests added or changed for behavior
+- type/API changes
+
+Required directives:
+
+- `directives/codebase-navigation.md`
+- `directives/task-framing.md` when non-trivial, ambiguous, high-risk, or cross-cutting
+- `directives/type-driven-development.md` for typed projects or public contracts
+- `directives/test-driven-development.md` for behavior-changing code
+- `directives/verification.md`
+- `directives/context-handoff.md` when switching major phases or handing off work
+
+Required skills:
+
+- `skills/product-requirements-writer/SKILL.md` when turning a feature idea or vague request into a PRD/spec before planning
+- `skills/implementation-task-planner/SKILL.md` when turning a PRD/spec/issue into an implementation task list
+- `skills/subagent-driven-development/SKILL.md` when executing an existing implementation plan through delegated subagents or isolated worker sessions
+- `skills/self-audit/SKILL.md` after REFACTOR for Full Path work
+- `skills/test-reviewer/SKILL.md` when tests are added or substantially changed
+- `skills/spec-reviewer/SKILL.md` when reviewing implementation against a written spec or preparing spec-governed work for merge
+- `skills/production-readiness-reviewer/SKILL.md` before merge/review when a change touches persistence, external services, async jobs, auth/security/privacy, infra/config/deploy, critical user paths, performance/scale, or cross-service compatibility
+- `skills/harness-hooks-reviewer/SKILL.md` when the implementation adds or changes agent harness hooks or deterministic agent automation
+- `skills/mcp-integration-reviewer/SKILL.md` when the implementation adds or changes MCP servers/tools, agent tool schemas, or agent-accessible internal API bridges
+
+### Debugging Path
+
+Use for:
+
+- bugs
+- failing tests
+- failing CI/build/lint/type-check
+- regressions
+- flaky or unexpected behavior
+
+Required:
+
+- `skills/systematic-debugging/SKILL.md`
+- reproduce the failure before changing code
+- add or identify a failing regression test when behavior changed
+- use `directives/test-driven-development.md` for the fix when production behavior changes
+- use `directives/verification.md` for fix proof and no-regression evidence
+- use `directives/context-handoff.md` after reproduction, before a risky fix, or before resuming in a new session
+
+### Boundary Path
+
+Add this path whenever the task touches:
+
+- imports or exports
+- folder/module/package moves
+- public entry points
+- shared utilities
+- service/package boundaries
+- dependency direction or architecture rules
+
+Required:
+
+- `directives/architecture-boundaries.md`
+- `skills/architecture-boundary-reviewer/SKILL.md` before merge/review
+- boundary proof in `directives/verification.md`
+- compact changed dependency-edge evidence with `directives/context-handoff.md` before boundary review or session transfer
+
+### Workspace Isolation Path
+
+Add this path whenever the task will mutate a git-backed repository from a
+checkout that may be shared or unsafe to edit in place, especially when:
+
+- the current branch is `main`, `master`, `trunk`, or another protected/default branch
+- the working tree has unrelated local changes
+- the user asks to protect the current workspace
+- a native workspace tool or `git worktree` can provide clean isolation
+
+Required:
+
+- `directives/workspace-isolation.md`
+- detect existing isolation before creating anything
+- prefer native workspace tools over manual `git worktree`
+- ask before creating a new isolated workspace when preference is unknown
+- show either isolated-workspace proof or an explicit fallback reason before editing
+
+### Review Path
+
+Use when the user asks to review a PR, branch, diff, or local changes.
+
+Required skills:
+
+- `skills/code-reviewer/SKILL.md` for baseline PR/branch/diff/local-change review
+- `skills/test-reviewer/SKILL.md` for tests
+- `skills/spec-reviewer/SKILL.md` for spec-backed work
+- `skills/architecture-boundary-reviewer/SKILL.md` for imports/exports/packages/shared code
+- `skills/codebase-health-reviewer/SKILL.md` for TypeScript/JavaScript refactors, cleanup, shared utilities, or Fallow-relevant changes
+- `skills/production-readiness-reviewer/SKILL.md` for production-sensitive changes involving persistence, external services, async jobs, auth/security/privacy, infra/config/deploy, critical user paths, performance/scale, or cross-service compatibility
+- `skills/harness-hooks-reviewer/SKILL.md` for agent harness hooks or deterministic agent automation
+- `skills/mcp-integration-reviewer/SKILL.md` for MCP servers/tools, agent tool schemas, or agent-accessible internal API bridges
+
+Do not edit code during Review Path unless the user asks for fixes. Use `directives/context-handoff.md` for compact PR/review handoffs when review findings will be fixed later or transferred to another session.
+
+### Exploration Path
+
+Use when the user asks to investigate, compare options, explain, research, or
+think through an approach.
+
+Required:
+
+- `directives/exploration-mode.md`
+- `directives/codebase-navigation.md` when repo context is needed
+- `skills/product-requirements-writer/SKILL.md` when the exploration output is a PRD/spec
+- `skills/implementation-task-planner/SKILL.md` when the exploration output is an implementation task list
+
+Do not edit files during Exploration Path unless the user explicitly switches to
+implementation. Use `directives/context-handoff.md` when exploration produces decisions, constraints, or risks that an implementation session should inherit.
+
+### Policy Path
+
+Use for changes to:
+
+- directives or skills
+- repo workflow
+- contributor instructions
+- architecture policy
+- cross-cutting conventions
+
+Required:
+
+- `directives/task-framing.md`
+- proposal before major edits when tradeoffs exist
+- bump the frontmatter `version` for every existing `directives/*.md` or `skills/*/SKILL.md` file changed in the PR; use patch for wording/behavior tightening, minor for new heuristics/routing/evidence coverage, and major for incompatible routing/schema/path changes; raw deletions are rejected, so deprecate with a major version bump before deletion
+- `directives/session-decisions.md` if the accepted change establishes or changes durable policy
+- `directives/verification.md` before PR
+- `directives/context-handoff.md` for multi-phase directive/workflow changes or new-session handoff
+- `skills/harness-hooks-reviewer/SKILL.md` when policy changes affect agent harness hooks or deterministic automation
+- `skills/mcp-integration-reviewer/SKILL.md` when policy changes affect MCP/tool surfaces exposed to agents
+
+---
+
+## Risk Escalation
+
+Escalate to Full Path or add a specialized path when any of these are true:
+
+| Risk trigger | Add |
+| --- | --- |
+| Auth, permissions, security, privacy, payments, data loss | Full Path + Production Readiness Review + stronger verification |
+| Database schema, migrations, persistence, queues | Full Path + Production Readiness Review + explicit rollback/edge-case proof |
+| External services, async jobs, infra/config/deploy, critical user paths, performance/scale, or cross-service compatibility | Full Path + Production Readiness Review |
+| Agent harness hooks or deterministic agent automation | Policy/Full/Review Path + Harness Hooks Review |
+| MCP servers/tools, agent-accessible APIs, or write-capable agent tools | Policy/Full/Review Path + MCP Integration Review; add Production Readiness Review for sensitive production systems |
+| Public API, exported types, package entry points | Full Path + Integration Proof + Boundary Path |
+| Imports, shared utilities, packages, folders, services | Boundary Path |
+| Shared/default checkout, unrelated local changes, or explicit request for isolation before repo edits | Workspace Isolation Path |
+| Failing CI/test/build/lint/type-check | Debugging Path |
+| Cross-cutting policy or workflow | Policy Path |
+| Large diff or broad refactor | Full Path + Self-Audit + Codebase Health Review + Context Handoff |
+
+---
+
+## Tool Feedback Handling
+
+Run project-native quality gates selected by the route. Treat lint, type-check,
+build, test, static-analysis, and review-bot output as implementation feedback.
+Fix root causes rather than suppressing rules, weakening config, or making
+superficial edits. If a finding is pre-existing or outside scope, document that
+classification and avoid making the current change worse.
+
+---
+
+## Override Rules
+
+- User may request a lighter or heavier workflow.
+- Honor explicit user workflow preferences unless they would skip necessary
+  safety evidence for high-risk work.
+- If the user asks for a quick fix to a risky area, keep the route safe and make
+  the implementation small.
+- If the router chooses a heavier path than requested, state why in one sentence.
+
+---
+
+## Forbidden Patterns
+
+| Pattern | Why Forbidden |
+| --- | --- |
+| Loading every directive by default | Wastes context and creates compliance theater |
+| Using Light Path for behavior or bug fixes | Skips necessary proof |
+| Treating "quick" as permission to skip safety | Risk depends on impact, not wording |
+| Producing boilerplate verification with no evidence | Ritual is not proof |
+| Appending active handoffs forever | Recreates context drift under a different filename |
+| Ignoring lint/type/test/build feedback as "just tooling" | Tool output is implementation feedback |
+| Adding cross-cutting tooling/config as a drive-by change | Policy changes need explicit review |
+| Opportunistic refactors or cleanup outside the task | Increases review surface and hides behavior risk |
+| Adding abstractions for hypothetical future use | Produces unnecessary code and weakens local fit |
+| Printing or rewriting whole files when a targeted patch would work | Wastes context and increases accidental churn |
+
+---
+
+## Quick Reference
+
+| Intent | Default path | Evidence |
+| --- | --- | --- |
+| Docs/typo/comment only | Light | diff + relevant gate |
+| New feature | Full | RED/GREEN, functional proof, gates |
+| Bug/regression | Debugging + TDD | reproduction, failing test/command, fix proof |
+| Refactor | Full | no-behavior-change proof, tests, gates |
+| Import/export/package/shared change | Boundary + relevant base path | boundary proof |
+| Repo edits from shared/default checkout | relevant base path + Workspace Isolation | isolation proof or explicit fallback |
+| PR/diff review | Review | structured findings |
+| PRD/spec writing | Exploration | product requirements writer, essential questions, no code edits |
+| PRD/spec/issue to task list | Exploration | implementation task planner, repo-grounded file/test/validation tasks, no code edits |
+| Investigation/explanation | Exploration | repo evidence, no edits |
+| Directive/workflow/policy change | Policy | proposal/tradeoffs, verification, handoff for multi-phase work, decision log if durable |

package/directives/architecture-boundaries.md

@@ -0,0 +1,223 @@
+---
+name: architecture-boundaries
+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
+triggers:
+  - imports
+  - exports
+  - packages
+  - architecture
+  - shared-code
+  - dependency-direction
+routing:
+  load: conditional
+---
+
+# Architecture Boundaries Directive
+
+**When to load:** Load this directive before modifying imports, exports, module
+structure, feature folders, shared utilities, service/package boundaries, or any
+code whose correctness depends on dependency direction.
+
+Passing tests is not enough if the change introduces an illegal dependency edge.
+The agent must preserve the project's directed architecture graph.
+
+---
+
+## Core Rule: Preserve the DAG
+
+Before implementation, identify the boundary context for every touched file:
+
+1. **Zone** — Which architectural layer, package, feature, service, or module owns it?
+2. **Allowed dependencies** — Which zones may this file import from?
+3. **New edges** — What imports, exports, call paths, or package references will change?
+4. **Forbidden edges** — Would any edge point upward, sideways, or across an internal boundary?
+
+Forbidden by default unless the project explicitly allows it:
+
+- Domain/core code importing UI, framework, infrastructure, or application code
+- Shared/common utilities importing feature-specific or application-specific code
+- Feature modules importing another feature's internals instead of its public API
+- Presentation/UI importing database, filesystem, network, or infrastructure directly
+- Tests or test helpers becoming production dependencies
+- New circular dependencies between files, packages, layers, or services
+- Cross-package imports that bypass the package's declared public entry point
+
+If the project has explicit boundary rules, those override these defaults. If the
+project has no explicit rules, infer the likely DAG from directory names,
+package boundaries, and existing import patterns; document the inference before
+changing code. If the inferred boundary materially changes the implementation
+approach, ask the human or propose the inferred rule before coding.
+
+---
+
+## Boundary Discovery
+
+Use progressive disclosure. Do not bulk-read the repository.
+
+### 1. Find explicit rules first
+
+Look for project-owned boundary definitions before inferring your own:
+
+- `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`
+- architecture docs, ADRs, decision logs, or contribution docs
+- `package.json` workspaces and package `exports`
+- `tsconfig.json` path aliases / project references
+- lint rules such as `import/no-restricted-paths`, `boundaries`, `dependency-cruiser`, `nx`, or monorepo constraints
+- Fallow config (`.fallowrc.json`, `.fallowrc.toml`, `fallow` config)
+
+### 2. Classify touched files
+
+For each file you expect to modify, record:
+
+```md
+- `path/to/file.ts`
+  - Zone: `domain` / `application` / `ui` / `shared` / feature/package name
+  - Public API: yes/no; entry point if yes
+  - Allowed imports: list or inferred rule
+  - Existing dependents: known callers/importers
+```
+
+### 3. Identify changed edges
+
+Treat these as boundary-relevant changes:
+
+- adding or changing an `import` / `require` / dynamic import
+- moving a file between directories/packages
+- exporting a symbol from a public entry point
+- importing from a deep internal path such as `feature-x/internal/*`
+- adding a package dependency or workspace reference
+- introducing callbacks, dependency injection, or runtime registration across layers
+
+---
+
+## Tool-Assisted Boundary Checks
+
+Tools accelerate discovery, but the rule is portable: if a tool is unavailable,
+fall back to inspecting config, imports, and dependents manually.
+
+### Fallow for TypeScript/JavaScript enforcement
+
+If Fallow is available in a TypeScript/JavaScript project, prefer it for boundary
+evidence:
+
+```bash
+npx fallow list --boundaries
+npx fallow dead-code --boundary-violations
+npx fallow dead-code --circular-deps
+```
+
+Useful presets include:
+
+```jsonc
+{ "boundaries": { "preset": "layered" } }        // presentation → application → domain
+{ "boundaries": { "preset": "hexagonal" } }     // adapters → ports → domain
+{ "boundaries": { "preset": "feature-sliced" } } // app > pages > widgets > features > entities > shared
+{ "boundaries": { "preset": "bulletproof" } }   // app → features → shared/server
+```
+
+If the project has no Fallow boundary config, do not silently add one during an
+unrelated task. Either infer boundaries for the current change only, or propose a
+separate issue/PR to introduce explicit enforcement.
+
+### GitNexus for graph-backed orientation
+
+If GitNexus is available, use it to understand dependency and call-chain impact
+before cross-cutting changes:
+
+```bash
+gitnexus analyze
+gitnexus wiki
+gitnexus serve
+```
+
+Use GitNexus graph/MCP context to answer:
+
+- What imports or calls this file/symbol?
+- Which functional cluster or service owns it?
+- Which execution flows are affected?
+- Does the proposed change cross a service/package/feature boundary?
+
+GitNexus is best treated as boundary intelligence. Use project rules or a
+checker such as Fallow/lint/CI for enforcement unless the project has explicit
+GitNexus graph queries for boundary violations.
+
+---
+
+## Boundary Design Patterns
+
+When a needed dependency would violate the DAG, do not punch through the boundary.
+Use one of these instead:
+
+| Problem | Prefer |
+| --- | --- |
+| Domain needs infrastructure behavior | Define a domain/application port; implement it in infrastructure |
+| UI needs data access | Call application/use-case layer; do not import database/client directly |
+| Feature A needs Feature B behavior | Depend on Feature B's public API or move shared behavior to shared/domain |
+| Shared utility needs feature config | Pass config as data; do not import feature code |
+| Lower layer needs upper-layer callback | Invert dependency with an interface, event, or injected function |
+| Cross-package import reaches internals | Export through the package entry point or add an explicit public module |
+
+---
+
+## Boundary Verification Output
+
+Before final gates, include a boundary section in the verification summary for
+any Full Path task that touches imports, exports, folders, packages, or shared
+code:
+
+```md
+### Architecture Boundaries
+
+- Modified zones:
+  - `src/features/auth/**` → `feature/auth`
+  - `src/shared/validation.ts` → `shared`
+- Changed dependency edges:
+  - `feature/auth` imports `shared/validation`
+- Checks:
+  - [x] No upward imports
+  - [x] No sibling feature internal imports
+  - [x] No production imports from tests
+  - [x] No new circular dependency
+  - [x] Boundary tool/lint check passed, or unavailable with reason
+- Tool evidence:
+  - `npx fallow dead-code --boundary-violations` → 0 violations
+```
+
+If a violation is found, the implementation is not ready. Either fix the design
+or ask the human before proceeding.
+
+---
+
+## Forbidden Patterns
+
+| Pattern | Why Forbidden |
+| --- | --- |
+| "Tests pass, so the import is fine" | Tests do not prove architectural validity |
+| Importing across a forbidden layer to save time | Creates coupling that future changes pay for |
+| Deep-importing another feature's internals | Bypasses the public contract and breaks encapsulation |
+| Adding boundary config as a drive-by change | Boundary policy is cross-cutting and needs explicit review |
+| Ignoring cycles because runtime still works | Cycles degrade build, test, and refactor reliability |
+| Moving code to `shared` without checking dependents | `shared` can become a dumping ground and reverse the DAG |
+
+---
+
+## Quick Reference
+
+| Phase | Action | Evidence |
+| --- | --- | --- |
+| ORIENT | Load project rules and classify touched files | Zone + allowed imports |
+| PLAN | Identify changed dependency edges | Edge list |
+| IMPLEMENT | Use ports/public APIs instead of forbidden imports | No illegal import added |
+| SELF-AUDIT | Ask what boundary assumption could collapse | Jenga entry if uncertain |
+| VERIFY | Run boundary checks or document manual proof | Boundary section in PR |
+
+_This directive complements type-first development, TDD, and verification: types
+prove shapes, tests prove behavior, and boundary checks prove architectural fit._