agent-directives 0.1.0

package/directives/error-memory.md

@@ -0,0 +1,169 @@
+---
+name: error-memory
+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
+triggers:
+  - repeated-mistakes
+  - error-memory
+  - post-task-learning
+routing:
+  load: conditional
+---
+
+# Error Memory Directive
+
+**When to load:** Load this directive when setting up a new project or when writing to the error memory file for the first time in a session.
+
+## MANDATORY: Document Repeated Mistakes in ERRORS.md
+
+---
+
+## When to Write an Error Entry
+
+Write an error entry when ALL of the following are true:
+
+1. The agent made a mistake that reached a commit, PR, or significant draft
+2. A human corrected it, or the agent caught it during VERIFY/GATES
+3. The mistake is likely to recur in future sessions (not a one-off typo)
+4. The prevention strategy is non-obvious — a future agent wouldn't
+   automatically avoid it
+
+**The test:** "Would a fresh agent in a new session make this same mistake?"
+
+If yes, write the entry. If no (obvious bug, one-off slip), skip it.
+
+---
+
+## When NOT to Write an Error Entry
+
+Do NOT write an error entry for:
+
+- Mistakes already caught by existing linter rules or CI checks
+- One-off typos or copy-paste errors
+- Mistakes mandated by unclear requirements (the requirements were the problem)
+- Anything a type checker would catch on its own
+- Mistakes the agent self-corrected before committing (no recurrence risk)
+
+---
+
+## File Location and Format
+
+```
+docs/ERRORS.md
+```
+
+Single file, not per-error files. Errors are cheap to scan in bulk and the file
+stays small (entries get retired as they're automated away).
+
+### Structure of an Entry
+
+Each entry in `docs/ERRORS.md` contains these fields:
+
+- **Error: [Short descriptive name]** — the pattern, not the agent
+- **Frequency**: N occurrences — triggers automation at 5+
+- **Severity**: High | Medium | Low — production impact
+- **Last Occurrence**: YYYY-MM-DD — recency signal
+- **Symptom**: What you see when the error manifests
+- **Bad Pattern**: The actual mistake (concrete code, not abstract description)
+- **Correct Pattern**: The right way (also concrete code)
+- **Prevention**: Actionable steps (e.g., "Enable X rule", "Check Y before Z")
+
+Example entry:
+
+    ## Error: Missing await on Promises
+
+    **Frequency**: 12 occurrences | **Severity**: High | **Last Occurrence**: 2026-01-20
+
+    **Symptom**: UnhandledPromiseRejectionWarning; function returns Promise instead of value
+
+    **Bad Pattern**: `const user = getUserById(id); console.log(user.email)`
+
+    **Correct Pattern**: `const user = await getUserById(id); console.log(user.email)`
+
+    **Prevention**: 1. Enable appropriate linter rules (e.g., @typescript-eslint/no-floating-promises for TypeScript projects) 2. Add pre-commit hook
+
+    ---
+
+---
+
+## When to Read ERRORS.md
+
+During the codebase survey/orientation phase, after loading types and test
+names, load relevant error entries for the domain you're working in.
+
+Do not load the entire file. Use progressive disclosure — grep for
+`## Error:` headings, then read the relevant entry by line range.
+
+**Before implementation starts** (after initial orientation, before
+implementation), the agent should have relevant error patterns in context.
+This is the "don't do these things" layer that complements the "do it this
+way" layer from types and tests.
+
+---
+
+## Monthly Review Process
+
+Each month, the first agent session after the 1st should check the review date
+in `docs/ERRORS.md`. If the last review is 30+ days old, run the review:
+
+1. **Sort by frequency** — highest-count errors first
+2. **Errors at 5+ occurrences**: Automate the prevention
+   - Can a linter rule catch it? → Create or enable one
+   - Can a type guard catch it? → Add one
+   - Can CI catch it? → Add a check
+3. **Errors at 1-2 occurrences with no recurrence in 30+ days**: Consider
+   retiring. The agent learned, or the codebase changed.
+4. **Update prevention strategies** — if a new rule or check was added,
+   note it in the entry
+
+**The goal isn't zero errors. It's zero repeated errors.**
+
+### Retirement
+
+When an error is fully automated (a linter rule exists, CI catches it, or a
+type guard prevents it), mark it:
+
+    ## Error: [name] (RETIRED)
+
+    **Retired**: YYYY-MM-DD
+    **Automated by**: `no-floating-promise` rule (v1.2.0)
+
+Retired entries stay in the file for reference but are skipped during codebase
+orientation.
+
+---
+
+## Connection to Other Directives
+
+```
+codebase-navigation guidance   ← loads error entries during survey phase
+session-decisions              ← captures why choices were made (not mistakes)
+verification                   ← catches errors before merge (not memory)
+error memory (this directive)  ← remembers mistakes to prevent recurrence
+```
+
+### Compacting Pipeline Integration
+
+During the compact step (every 5+ tasks, per codebase-navigation guidance),
+check:
+
+```
+Compacting checklist (extended):
+  □ Session digest (current context)
+  □ Pending work and active constraints
+  □ Decision logs for qualifying decisions
+  □ Error entries for qualifying mistakes ← NEW
+  □ Discard exploration context
+```
+
+If a task produced a corrected mistake that meets the error entry criteria,
+write it during compacting while the details are fresh.
+
+---
+
+_This directive ensures mistakes compound into guardrails instead of repeating._

package/directives/exploration-mode.md

@@ -0,0 +1,266 @@
+---
+name: exploration-mode
+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
+triggers:
+  - explore
+  - investigate
+  - compare-options
+  - uncertain-approach
+routing:
+  load: conditional
+---
+
+# Exploration Mode Directive
+
+**When to load:** Load this directive when the user wants to investigate, think through, or explore a problem before committing to an implementation approach. Also load when the user says "explore," "investigate," "think about," "what if," or "I'm not sure how to approach."
+
+This directive governs a distinct pre-implementation phase: structured
+investigation and thinking. It is not codebase navigation (how to search) or
+task framing (how to scope work). It governs the **stance** the agent takes
+when the right answer is not yet clear.
+
+**Do not implement during exploration.** The purpose is to develop
+understanding, surface options, and identify risks — not to write code.
+
+---
+
+## The Stance
+
+During exploration, the agent adopts a specific posture:
+
+- **Curious, not prescriptive** — Ask questions that emerge from what the user said. Don't follow a script or funnel toward a predetermined answer.
+- **Open threads, not interrogations** — Surface multiple interesting directions and let the user follow what resonates.
+- **Grounded in reality** — Explore the actual codebase when relevant. Don't just theorize. Read files, trace dependencies, map architecture.
+- **Visual when it helps** — Use ASCII diagrams, tables, and structured layouts to clarify thinking. A good diagram is worth many paragraphs.
+- **Patient** — Don't rush to conclusions. Let the shape of the problem emerge from investigation.
+- **Comfortable with uncertainty** — If something is unclear, say so. Unresolved questions are a valid output of exploration.
+
+---
+
+## What Exploration Produces
+
+Exploration may produce any combination of:
+
+### Problem Understanding
+
+- Clarified problem statement
+- Identified constraints (explicit and implicit)
+- Surfaced assumptions that need validation
+- Reframed problem from a different angle
+
+### Architecture Mapping
+
+```
+┌─────────────────────────────────────────────┐
+│            CURRENT SYSTEM                   │
+├─────────────────────────────────────────────┤
+│                                             │
+│  ┌──────────┐    ┌──────────┐              │
+│  │ Module A │───▶│ Module B │              │
+│  └──────────┘    └────┬─────┘              │
+│                       │                     │
+│                       ▼                     │
+│                 ┌──────────┐                │
+│                 │ Module C │                │
+│                 └──────────┘                │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+- How existing components relate to the area under investigation
+- Integration points and dependencies
+- Data flow and control flow
+- Where complexity lives
+
+### Option Comparison
+
+| Criterion    | Option A      | Option B      | Option C      |
+|------------- |-------------- |-------------- |-------------- |
+| Complexity   | Low           | Medium        | High          |
+| Performance  | Fast          | Adequate      | Fast          |
+| Maintenance  | Easy          | Moderate      | Hard          |
+| Risk         | Low           | Medium        | High          |
+
+- Multiple approaches with tradeoffs made visible
+- Constraints that favor or disfavor each option
+- Recommendation (if asked) with reasoning
+
+### Risk Surface
+
+- What could go wrong
+- Hidden complexity not obvious from the initial description
+- Dependencies that might block or complicate the work
+- Assumptions that, if wrong, would change the approach
+
+---
+
+## The Flow
+
+Exploration is not a fixed sequence. It is a conversation that follows
+interesting threads. The general pattern:
+
+### 1. Listen
+
+Receive what the user brings. It might be:
+- A vague idea ("I'm thinking about adding real-time collaboration")
+- A specific problem ("The auth system is a mess")
+- A question ("Should we use Postgres or SQLite?")
+- A blockage ("I'm stuck on the OAuth integration")
+
+### 2. Ground
+
+Before theorizing, check what actually exists:
+- Read relevant source files (using codebase-navigation discipline)
+- Trace the relevant architecture
+- Identify current patterns and conventions
+- Find existing constraints
+
+### 3. Investigate
+
+Follow the thread that seems most productive:
+- Ask clarifying questions that emerge from the codebase
+- Challenge assumptions — both the user's and your own
+- Reframe the problem if the current framing seems incomplete
+- Find analogies or prior art in the codebase
+
+### 4. Surface
+
+Present what you've found:
+- Diagrams for architecture and flow
+- Tables for comparisons and tradeoffs
+- Lists for risks, unknowns, and open questions
+- Plain language for insights and recommendations
+
+### 5. Summarize (optional)
+
+When the exploration feels like it's crystallizing, offer a summary:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Proceed to task framing and implementation
+- Keep exploring: follow a specific thread
+```
+
+This summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Handling Different Entry Points
+
+### Vague Idea
+
+```
+User: I'm thinking about adding real-time collaboration
+
+Agent: [maps the problem space, surfaces options at different
+       complexity levels, asks where the user's head is at]
+```
+
+Do not jump to "here's how we implement CRDTs." Explore the spectrum first.
+
+### Specific Problem
+
+```
+User: The auth system is a mess
+
+Agent: [reads the actual auth code, maps the tangle,
+       identifies specific pain points, asks which one burns most]
+```
+
+Do not prescribe a full rewrite. Find the specific tangle first.
+
+### Comparison Question
+
+```
+User: Should we use Postgres or SQLite?
+
+Agent: [asks about context and constraints, then evaluates
+       against the actual use case, not generic pros/cons]
+```
+
+Generic comparisons are boring. Ground them in the project's reality.
+
+### Mid-Implementation Blockage
+
+```
+User: I'm stuck — the OAuth integration is more complex than expected
+
+Agent: [reads the code where they're stuck, traces the actual
+       complexity, surfaces options for simplifying or working around it]
+```
+
+Do not just suggest reading the docs. Investigate the actual blocker.
+
+---
+
+## Exploration vs. Other Directives
+
+| Directive            | What it governs            | Phase            |
+| -------------------- | -------------------------- | ---------------- |
+| Codebase Navigation  | How to search efficiently  | Orientation      |
+| Task Framing         | How to scope work          | Planning         |
+| Exploration Mode     | How to think through       | Investigation    |
+| Test-Driven Dev      | How to implement           | Implementation   |
+| Verification         | How to confirm correctness | Review           |
+
+Exploration sits between navigation and framing. You orient (navigation),
+investigate (exploration), scope (framing), implement (TDD), verify
+(verification).
+
+---
+
+## Guardrails
+
+| Guardrail                   | Why                                                            |
+| --------------------------- | -------------------------------------------------------------- |
+| No implementation code      | Writing code commits to an approach before exploration is done  |
+| No auto-capture of insights | Offer to save findings; let the user decide                    |
+| No forced structure         | Exploration is conversational; let patterns emerge naturally   |
+| No rushing to conclusions   | Premature solutions miss better options                        |
+| No faking understanding     | If something is unclear, dig deeper rather than guessing       |
+
+---
+
+## Forbidden Patterns
+
+| Pattern                                     | Why Forbidden                                               |
+| ------------------------------------------- | ----------------------------------------------------------- |
+| Writing implementation code during exploration | Commits to approach before investigation is complete        |
+| Following a fixed question checklist         | Every exploration is different; scripts kill curiosity      |
+| Prescribing a solution in the first response | Premature solutions skip the most valuable thinking         |
+| Theorizing without reading the codebase      | Ungrounded advice is noise                                  |
+| Producing a required artifact                | Exploration may end with clarity, a decision, or more questions — all are valid |
+
+---
+
+## When Exploration Ends
+
+There is no required ending. Exploration might:
+
+- **Flow into task framing** — "I have a clear picture now. Want me to frame the task?"
+- **Result in a decision** — "We should go with Option B because..."
+- **Just provide clarity** — User has what they need, moves on
+- **Continue later** — "We can pick this up anytime"
+
+The signal that exploration is done: the user asks to implement something,
+or a clear path forward has emerged and been confirmed.
+
+---
+
+_This directive applies to any investigation, brainstorm, or "what if" conversation. It is optional for straightforward tasks with obvious implementations._

package/directives/session-decisions.md

@@ -0,0 +1,193 @@
+---
+name: session-decisions
+description: Captures durable decisions for repo policy, architecture, workflow, and cross-cutting conventions.
+version: 1.0.0
+required: false
+category: memory
+tools:
+  - claude
+  - codex
+triggers:
+  - policy-change
+  - architecture-decision
+  - workflow-change
+  - cross-cutting-convention
+routing:
+  load: conditional
+---
+
+# Session Decisions Directive
+
+**When to load:** Load this directive when making changes that affect repo policy, architecture, contributor workflow, or cross-cutting conventions.
+
+## MANDATORY: Capture Durable Decisions at Task Completion
+
+Before closing out any task where you set or changed a durable repo/process
+policy, architectural constraint, or cross-cutting code/documentation
+convention, you MUST write a decision log entry if the reasoning would not be
+obvious later. This is non-negotiable.
+
+---
+
+## When to Write a Decision Log
+
+Write a decision log when ALL of the following are true:
+
+1. You set, changed, or explicitly confirmed a durable decision that affects repo policy, contributor workflow, architecture, or a cross-cutting convention
+2. You made a choice between two or more real alternatives
+3. The rejected alternatives were plausible (a reasonable agent might have chosen them)
+4. The reason for your choice is not obvious from the code, config, or document diff alone, and a future agent would likely spend real time re-deciding or accidentally reversing it without a log
+
+**The test:** Ask yourself:
+
+- "Will this decision still matter outside the file I changed?"
+- "Would another reasonable agent revisit this tradeoff without extra context?"
+
+If both are yes, write the log. If any of the criteria above are false, no log
+is needed.
+
+---
+
+## When NOT to Write a Decision Log
+
+Do NOT write a decision log for:
+
+- Choices mandated by a directive (e.g., using TDD, defining types first, following naming conventions)
+- Naming choices where no alternatives were explicitly considered
+- Standard library usage over custom code (always prefer standard — not a decision)
+- Bug fixes (the decision is obvious: fix it correctly)
+- Routine implementation details where the code clearly explains itself
+- Single-file or one-off refactors that do not establish an ongoing convention
+- Local code-level choices that do not affect future work elsewhere in the repo
+
+Most code-level decisions do **not** need a log. Code decisions qualify only
+when they create a reusable rule for later work, such as an architectural
+boundary, an authoring convention, or a cross-cutting policy.
+
+---
+
+## When to Read Existing Decision Logs
+
+Before changing repo policy, contributor workflow, architecture, or any
+cross-cutting code or documentation convention:
+
+1. Scan the frontmatter in `docs/decisions/*.md`
+2. Filter for entries with `status: active`
+3. Match on `domain`, `triggers`, and `applies_to`
+4. Open only the matching logs unless you need a superseded record for history
+
+Decision logs are for progressive disclosure. Do not load every file in
+`docs/decisions/` by default.
+
+---
+
+## File Naming
+
+```
+docs/decisions/YYYY-MM-DD-<topic>.md
+```
+
+Use today's date with zero-padded month and day. Use a short kebab-case topic
+that names the **decision domain**, not the outcome.
+
+```
+docs/decisions/2026-04-05-error-reporting-format.md     ✅ names the domain
+docs/decisions/2026-04-05-chose-discriminated-unions.md ✗ names the outcome
+docs/decisions/2026-04-05-refactor.md                   ✗ too vague
+```
+
+---
+
+## Frontmatter
+
+Every decision log MUST begin with YAML frontmatter so agents can classify and
+retrieve the right records before reading the full body.
+
+```yaml
+---
+date: YYYY-MM-DD
+task: one-line task description
+domain: short-kebab-case-decision-domain
+kind: repo-policy | process | architecture | code-convention
+scope: repo | cross-cutting | subtree
+status: active | superseded | retired
+triggers:
+  - when this record should be read
+applies_to:
+  - path/or/glob
+supersedes: []
+---
+```
+
+### Required Fields
+
+| Field        | Purpose                                                                  |
+| ------------ | ------------------------------------------------------------------------ |
+| `date`       | The date the decision was recorded                                       |
+| `task`       | The task this decision arose from                                        |
+| `domain`     | Stable retrieval key for the decision area                               |
+| `kind`       | Broad class of decision                                                  |
+| `scope`      | Whether the decision applies repo-wide, cross-cuttingly, or to a subtree |
+| `status`     | Whether the decision is current                                          |
+| `triggers`   | Short phrases describing when agents should read this log                |
+| `applies_to` | Paths or globs affected by the decision                                  |
+| `supersedes` | Older decision records replaced by this one                              |
+
+Keep frontmatter short and operational. If a field does not help an agent decide
+whether to read the file, it does not belong here.
+
+This directive is the canonical source for the retrieval workflow and
+frontmatter schema. Other docs should link here instead of duplicating the full
+rules.
+
+---
+
+## Template
+
+Copy the decision log template from `templates/decision-log.md` (or
+`docs/decisions/TEMPLATE.md` in your project), fill in every section. Delete
+placeholder text. Do not leave `[brackets]` in the output.
+
+### Required Sections
+
+Every decision log MUST contain all five sections:
+
+| Section                   | What it contains                                                                          |
+| ------------------------- | ----------------------------------------------------------------------------------------- |
+| **Title**                 | One sentence starting with a verb. Names the domain, not the outcome.                     |
+| **Context**               | 2–4 sentences on the problem, constraints, and why this was a real choice.                |
+| **Decision**              | One paragraph. Specific reasoning — name the properties that made this option preferable. |
+| **Rejected Alternatives** | At least one entry. Name the alternative and the specific reason it was disqualified.     |
+| **Consequences**          | Easier / Harder / Watch for / **Unlearn** — what this decision makes true going forward.  |
+
+**The Unlearn entry in Consequences:** After writing Easier / Harder / Watch for,
+ask: *"What assumption worked for this task that should NOT be carried forward
+as a default?"* If the answer is "none," skip it. If an assumption was valid
+here but context-dependent (e.g., "we denormalized because reads dominate — but
+that won't hold if writes increase"), name it. Future sessions encountering
+this decision log should verify the Unlearn entry still holds before inheriting
+the approach.
+
+---
+
+## Forbidden Patterns
+
+| Pattern                                           | Why it's forbidden                            |
+| ------------------------------------------------- | --------------------------------------------- |
+| "We decided to use the best approach"             | Not a decision — no alternative named         |
+| Leaving `[placeholder]` text in the output        | Decision log is incomplete — do not commit it |
+| Logging choices already captured in code comments | Duplication — code comments are sufficient    |
+| Writing the log before finishing the task         | You don't know the consequences yet           |
+
+---
+
+## Quick Reference
+
+| Question                                                                                      | Answer                                                              |
+| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Does this set repo policy, workflow, architecture, or a cross-cutting convention?             | If no → skip the log                                                |
+| Did I choose between plausible alternatives?                                                  | If no → skip the log                                                |
+| Is the reasoning obvious from the diff, and would a future agent avoid re-deciding it anyway? | If yes → skip the log                                               |
+| Before making a cross-cutting change, what do I do first?                                     | Scan decision-log frontmatter and read only matching active entries |
+| Where does the file go?                                                                       | `docs/decisions/YYYY-MM-DD-<topic>.md`                              |
+| What template?                                                                                | Use the decision log template from `templates/decision-log.md`      |