agent-directives 0.1.0

package/directives/verification.md

@@ -0,0 +1,266 @@
+---
+name: verification
+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
+triggers:
+  - verification
+  - pre-pr
+  - quality-gates
+  - implementation-complete
+routing:
+  load: conditional
+---
+
+# Verification Protocol
+
+**When to load:** Load this directive after completing the REFACTOR phase and before running final quality gates (GATES).
+
+**Do not run GATES until verification output is produced.** Verification
+catches issues that passing tests alone cannot: false positives, missing
+edge cases, wrong configuration, and incomplete documentation.
+
+---
+
+## The Protocol
+
+After REFACTOR and before GATES, the agent MUST produce a verification
+summary. The summary is structured evidence that a reviewer can scan in
+30 seconds instead of reading the full implementation.
+
+### For New Features or Changes
+
+Output all applicable sections. The protocol defines three sections that apply
+to every new feature or change, plus conditional sections for architecture
+boundaries, codebase health, and documentation when relevant.
+
+#### 1. Functional Proof
+
+Demonstrate the change does what it claims. Show:
+
+- **Hit** — one input or scenario that produces the expected new behavior
+- **Clean pass** — one input or scenario that should NOT be affected, proving
+  no false positive
+
+_Example (adapt to your project):_
+
+```
+✅ Hit: calling createUser({ name: "Alice" }) returns { id: "usr_1", name: "Alice" }
+✅ Clean: calling createUser({}) returns validation error, no user created
+```
+
+#### 2. Test Coverage Proof
+
+List passing test cases grouped by:
+
+- **Happy path** — expected inputs with expected outputs
+- **Error cases** — invalid inputs, failure conditions
+- **Edge cases** — null, undefined, empty, boundary values
+- **Suggestion/fix cases** — autofix or suggestion output (if applicable)
+
+_Example command (adapt to your project's test runner):_
+
+```bash
+# For example, with vitest:
+npx vitest run --reporter=verbose
+```
+
+#### 3. Integration Proof
+
+Confirm the change is wired into the project correctly. Output `[x]` for
+confirmed, `[ ]` for missing:
+
+- [ ] Exported/registered in the appropriate entry point
+- [ ] Included in the relevant configuration or module
+- [ ] Public API (types, function signatures) matches usage
+- [ ] Error messages are clear and actionable
+
+_Example (adapt to your project's structure):_
+
+```
+[x] Exported from the appropriate entry point
+[x] Registered in config module
+[x] Public types match call sites
+[x] Error messages follow project conventions
+```
+
+#### 4. Architecture Boundary Proof (if applicable)
+
+Required when the change touches imports, exports, package boundaries, shared
+code, service boundaries, or folder/layer structure. Show:
+
+- Modified zones/layers/packages
+- Changed dependency edges
+- Evidence that no upward, sideways, cyclic, or public-API-bypassing import was introduced
+- Tool evidence when available, e.g. `npx fallow dead-code --boundary-violations`
+
+_Example:_
+
+```md
+[x] `feature/auth` imports only `shared` and public `domain` APIs
+[x] No sibling feature internal imports
+[x] `npx fallow dead-code --boundary-violations` reports 0 violations
+```
+
+#### 5. Codebase Health Proof (if applicable)
+
+For TypeScript/JavaScript refactors, cleanup, shared utilities, or AI-generated
+changes where Fallow is available, include concise health evidence:
+
+```bash
+npx fallow --summary
+npx fallow dupes
+npx fallow health
+```
+
+Summarize only relevant findings: new dead code, duplication, complexity, cycles,
+or boundary regressions. Separate pre-existing debt from issues introduced by
+the change.
+
+#### 6. Documentation Proof (if applicable)
+
+- [ ] API documentation updated
+- [ ] README or usage docs updated (if public-facing change)
+
+_Example:_
+
+```
+[x] JSDoc updated on changed functions
+[x] README usage section updated
+```
+
+#### 7. Scope Control Proof
+
+Confirm the final diff stayed within the planned scope budget:
+
+- Planned scope budget: paste or quote the exact scope budget line used for
+  comparison.
+- Changed files match the stated scope, or scope expansion is explained with
+  evidence.
+- No unrelated cleanup, opportunistic refactor, or drive-by formatting was
+  included.
+- No new abstraction, helper layer, dependency, or configuration surface was
+  added unless required by current evidence.
+
+For small tasks, one sentence is enough:
+
+```md
+Planned scope budget: touch only `src/foo.ts` with a targeted guard-clause edit.
+Scope control: changed only `src/foo.ts`; no unrelated cleanup or new abstraction added.
+```
+
+---
+
+### For Bug Fixes
+
+After the fix, show:
+
+1. **The previously-failing test now passing** — paste the test name and result
+2. **The fix** — a one-paragraph summary of what changed in the logic
+3. **No regression** — all existing tests still pass
+
+Run the project's test suite with verbose output to confirm.
+
+---
+
+### For Docs / Chore Changes
+
+Show the relevant quality gate still passes:
+
+Run the project's full quality-gate command suite (test, lint, build/type-check).
+
+Paste the output. That IS the verification for non-code changes.
+
+---
+
+## Output Location: Pull Request Body
+
+The verification summary MUST be included in the PR description when the
+agent opens a pull request. This keeps the evidence next to the code it
+verifies, and the reviewer can scan it in 30 seconds without leaving the PR.
+
+When opening a PR, include a `## Verification` section in the PR body.
+The summary should follow this structure:
+
+```markdown
+## Verification
+
+### Functional
+
+✅ Hit: calling createUser({ name: "Alice" }) → returns user with id
+✅ Clean: calling createUser({}) → validation error, no side effects
+
+### Tests (12 passing)
+
+- Happy path (4): valid input, optional fields, default values, nested objects
+- Error cases (5): missing required field, invalid type, duplicate key, null input, empty string
+- Edge cases (2): max-length name, unicode characters
+- Suggestions (1): suggests trim on whitespace-padded name
+
+### Integration
+
+[x] Exported from src/users/create.ts
+[x] Registered in user module
+[x] Public types match call sites
+[x] Error messages follow project conventions
+
+### Architecture Boundaries
+
+[x] Modified files stay within allowed dependency direction
+[x] No new circular dependencies or public API bypasses
+
+### Documentation
+
+[x] JSDoc updated on createUser
+[x] README usage section updated
+
+### Scope Control
+
+Planned scope budget: touch `src/users/create.ts` and `tests/users/create.test.ts` for create-user validation only.
+Scope control: changed only the planned files; no unrelated cleanup, new abstraction, dependency, or configuration surface added.
+```
+
+If anything is `[ ]` or tests are missing, the implementation is not ready.
+Do not open the PR until verification is complete.
+
+For bug fixes and docs/chore changes, include a shorter verification
+block in the same PR section.
+
+---
+
+## Quality Gate Feedback
+
+Run the project-native gates selected by `directives/adaptive-routing.md`.
+Treat test, lint, type-check, build, static-analysis, and review-bot output as
+implementation feedback, not ceremony.
+
+When a linter or static-analysis rule explains an issue, fix the underlying
+pattern. Do not suppress the rule, weaken configuration, or make superficial
+rewrites unless the project explicitly allows that exception and the reason is
+documented.
+
+If a finding is pre-existing or outside the task scope, state that classification
+and show that the current change did not make it worse.
+
+---
+
+## Forbidden Patterns
+
+| Pattern                                      | Why Forbidden                                         |
+| -------------------------------------------- | ----------------------------------------------------- |
+| "Tests pass, ship it"                        | Passing tests ≠ production-ready                      |
+| Skipping functional proof                    | Must show both expected behavior AND no false positive |
+| Skipping integration proof                   | Misconfigured code passes tests but fails in production |
+| Skipping boundary proof for dependency changes | Passing tests do not prove architectural validity       |
+| Claiming verification without showing output | Evidence, not claims                                  |
+| Running GATES before verification            | Verification catches issues GATES misses              |
+
+---
+
+_This directive is mandatory for all implementations, bug fixes, and configuration changes._

package/directives/workspace-isolation.md

@@ -0,0 +1,219 @@
+---
+name: workspace-isolation
+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
+triggers:
+  - isolated-workspace
+  - worktree
+  - branch-isolation
+  - feature-work
+routing:
+  load: conditional
+  applies_to:
+    - implementation
+    - debugging
+---
+
+# Workspace Isolation Directive
+
+**When to load:** Load this directive before implementation or invasive debugging
+when the task will mutate a git-backed repository and the current workspace may be
+shared, protected, dirty, or otherwise not isolated.
+
+The goal is simple: protect the current workspace from task-specific edits unless
+there is a good reason to work in place. Detect existing isolation first. Prefer
+native workspace tools when the platform provides them. Use `git worktree` only
+as a fallback.
+
+---
+
+## Core Rules
+
+1. **Detect before creating.** Confirm whether the current checkout is already an
+   isolated workspace before creating anything.
+2. **Prefer native tools.** If the platform already manages isolated workspaces,
+   use that tool instead of manual `git worktree` commands.
+3. **Ask before creating a new workspace when preference is unknown.** If the
+   user has not already asked for isolation and project instructions do not
+   declare a preference, ask for consent before creating a new workspace.
+4. **Treat protected or shared checkouts as isolation candidates.** If the agent
+   is on `main`, `master`, `trunk`, another protected/default branch, or a
+   checkout with unrelated local changes, prefer isolation rather than editing in
+   place.
+5. **Baseline after isolation.** Setup and baseline verification belong in the
+   workspace where the task will actually run.
+
+---
+
+## Step 0: Detect Existing Isolation
+
+Before creating anything, determine whether the current checkout is already an
+isolated workspace:
+
+```bash
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || {
+  echo "Repository is not git-backed; workspace-isolation directive does not apply."
+  exit 0
+}
+
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+If `GIT_DIR != GIT_COMMON`, you may already be in a linked worktree. Guard
+against submodules before concluding that:
+
+```bash
+git rev-parse --show-superproject-working-tree 2>/dev/null
+```
+
+If the command returns empty output, the checkout is **not** a submodule. If it
+returns a path, the checkout **is** a submodule of that superproject and should
+be treated as a normal checkout for this directive rather than as an already
+isolated worktree.
+
+- If `GIT_DIR != GIT_COMMON` **and** the checkout is not a submodule, treat the
+  current location as already isolated. Do not create another worktree.
+- If `GIT_DIR == GIT_COMMON`, you are in the main checkout and should evaluate
+  whether a separate workspace is warranted.
+- If the repository is not git-backed, this directive does not apply; state that
+  clearly and continue with the routed workflow.
+
+Report the result before moving on:
+
+- On a branch: `Already in isolated workspace at <path> on branch <name>.`
+- Detached HEAD: `Already in isolated workspace at <path> (detached HEAD; branch creation may be needed later).`
+- Normal checkout: `Current checkout is not isolated; deciding whether to create one before editing.`
+
+---
+
+## Step 1: Choose the Isolation Mechanism
+
+### 1a. Native Workspace Tools (preferred)
+
+If the platform already provides a native worktree/workspace mechanism, use it.
+Native tools often manage placement, naming, cleanup, and integration better than
+manual git commands.
+
+Do **not** bypass a native isolation tool with `git worktree add` unless the
+platform explicitly requires the git fallback.
+
+### 1b. Git Worktree Fallback
+
+Use `git worktree` only when no native workspace tool is available.
+
+#### Directory selection
+
+Use this priority order:
+
+1. An explicit user or project-instruction preference
+2. An existing project-local `.worktrees/`
+3. An existing project-local `worktrees/`
+4. An outside-repo worktree location
+5. A new project-local `.worktrees/` only when it is already ignored or the user explicitly approves changing ignore rules
+
+#### Ignore verification
+
+For project-local worktree directories, verify the directory is ignored before
+creating the worktree. Check the directory you actually selected in the previous
+step:
+
+```bash
+git check-ignore -q "$CHOSEN_DIR" 2>/dev/null
+```
+
+If the chosen directory is not ignored, do **not** silently modify tracked repo
+files before isolation. Prefer an already-ignored directory, add an untracked
+rule in `.git/info/exclude`, or use an outside-repo location. Ask for explicit
+user consent before changing `.gitignore`.
+
+#### Create the worktree
+
+```bash
+git worktree add "<path>" -b "<branch-name>"
+cd "<path>"
+```
+
+If worktree creation fails because the environment blocks it (for example,
+permission or sandbox restrictions), say so explicitly and continue in place only
+with a documented fallback.
+
+---
+
+## Step 2: Project Setup in the Chosen Workspace
+
+Run the project's documented setup commands in the workspace where the task will
+execute. Prefer project instructions over generic ecosystem guesses.
+
+Minimum expectations:
+
+- Ensure the branch/workspace is the one you plan to edit
+- Run only the setup commands needed to make that workspace ready
+- Re-check `git status --short` so the baseline is understood in the actual work area
+
+---
+
+## Step 3: Baseline Proof Before Editing
+
+Before implementation starts, show that the chosen workspace is ready:
+
+- What workspace/path is active
+- What branch is active
+- Whether the workspace began clean or had pre-existing changes
+- Which baseline command(s) were run for this repository
+
+If baseline tests or checks fail, report that and ask whether to proceed. Do not
+silently treat a broken baseline as acceptable.
+
+---
+
+## Step 4: Proceed or Fall Back
+
+Once isolation and baseline are established:
+
+- Proceed with the routed workflow in the isolated workspace, or
+- State the fallback clearly if you must work in place
+
+Fallbacks are acceptable only when:
+
+- the user explicitly prefers in-place work,
+- the repository is not git-backed,
+- a native or git-based isolation mechanism is unavailable, or
+- the environment blocks workspace creation and the user still wants work to continue
+
+---
+
+## Forbidden Patterns
+
+| Pattern | Why Forbidden |
+| --- | --- |
+| Creating a new worktree without checking whether one already exists | Risks nested or duplicate workspaces |
+| Using `git worktree add` when a native workspace tool is available | Fights the platform/harness |
+| Editing a protected/default branch or dirty shared checkout without considering isolation | Needlessly risks unrelated work |
+| Creating a project-local worktree directory without ignore verification | Pollutes repo status and can leak files into commits |
+| Running setup or baseline in one checkout, then editing a different one | Evidence no longer matches reality |
+| Treating environment failures as silent permission to continue | Hides risk and makes later debugging harder |
+
+---
+
+## Quick Reference
+
+| Situation | Action |
+| --- | --- |
+| Already in a linked worktree | Reuse it; do not create another |
+| In a normal checkout on a shared/default branch | Prefer isolation before editing |
+| User already asked for isolation | Create or enter the isolated workspace without re-asking |
+| Preference unknown | Ask before creating a new workspace |
+| Native workspace tool exists | Use it before git fallback |
+| No native tool exists | Use `git worktree` with ignore verification |
+| Worktree creation is blocked | State the fallback and continue only with explicit justification |
+| Baseline is failing | Report it and get direction before proceeding |
+
+_This directive complements adaptive routing: the router decides **when** isolation
+matters, and this directive governs **how** to establish it safely._

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}