aide-agents-md

Files (1)

• SKILL.md

SKILL.md (first lines)

# AGENTS.md — Persistent Agent Instructions, Scoped Three Ways

Born 2026-08-31 from the wiring audit. AIDE has `harness/credo.md` (the global credo) and `aide-advanced-orchestration` Pattern 5 (AGENTS.md export) but the **load order, scoping rules, and edit UX** are not specified or wired. Every rival (Claude Code, Cursor, Cline, Copilot, Aider) has this. AIDE's version is "the credo is global, period" — too coarse. This skill IS the wire-in.

## The AIDE AGENTS.md contract (3 scopes, 1 precedence)

```
Priority (highest to lowest):
1. SESSION scope:    .aide/agents/session.md       (ephemeral, current session only)
2. WORKSPACE scope:  <workspace>/AGENTS.md         (committed, project-wide)
3. USER scope:       ~/.aide/agents/user.md        (cross-workspace, operator's preferences)
4. GLOBAL scope:     harness/credo.md              (the oath, non-overridable)
```

**Why 4 levels, not 3:** the global credo is **non-overridable** by the other three. It's the oath. The other three are preferences layered on top.

**The "non-overridable" rule:** the credo defines the oaths (protect user, evidence over confidence, etc.). Workspace AGENTS.md can ADD constraints ("always run tests before commit") but cannot REMOVE an oath. A diff that conflicts with the credo is rejected with `OATH_CONFLICT`.

## Files to touch (when wiring)

| File | Change |
|---|---|
| `node/src/services/agent-instructions.mjs` | NEW: `loadInstructions({workspace, userHome, sessionId})` returns the merged, deduplicated, oath-checked instruction set. |
| `node/src/services/scaffold.mjs` | EXTEND: `composeScaffold` calls `loadInstructions` and prepends the merged set to the system prompt. |
| `node/src/routes/agent.ts` (or new `node/src/routes/instructions.ts`) | ADD: `GET /api/instructions` (show merged), `PUT /api/instructions/scope/:scope` (edit one scope), `GET /api/instructions/scopes` (list all 4). |
| `common/contracts/agent.ts` or new `common/contracts/instructions.ts` | ADD: the 4 zod schemas. |
| `node/src/server.ts` | Wire the routes. |
| `tests/arch/agents-md.test.ts` | NEW: 5 tests (scope precedence, oath conflict, dedup, session expiry, edit UX). |
| `scripts/aide-bundle.cjs` | (optional) `bundle instructions` CLI. |
| `browser/src/...` | (optional) "Edit workspace instructions" UI in the settings panel. |

## The contract (zod-strict)

```ts
// in common/contracts/instructions.ts

export const InstructionScope = z.enum(['session', 'workspace', 'user', 'global']);

export const InstructionEntry = z.object({
  scope: InstructionScope,
  path: z.string(),       // file path for verification
  body: z.string(),
  lines: z.number().int().gte(0),
  modified_at: z.number().int(),
  oath_check: z.enum(['pass', 'fail', 'unknown']).default('unknown'),
  oath_conflict: z.string().nullable().optional()
}).strict();

## The load + merge algorithm

```js
// node/src/services/agent-instructions.mjs
import { promises as fs } from 'node:fs';
import path from 'node:path';
import os from 'node:os';

const OATHS = [
  'protect the user and their data',
  'evidence over confidence',
  'finish the procedure',
  'preserve the workspace',
  'carry knowledge forward'
];

const SCOPE_PATHS = {
  global:    'harness/credo.md',
  workspace: 'AGENTS.md',
  user:      path.join(os.homedir(), '.aide', 'agents', 'user.md'),
  session:   path.join('.aide', 'agents', 'session.md')
};

export async function loadInstructions({ workspace, sessionId }) {
  const entries = [];
  const conflicts = [];
  for (const [scope, relPath] of Object.entries(SCOPE_PATHS)) {
    const absPath = scope === 'user' || scope === 'global' ? relPath : path.join(workspace, relPath);
    let body;
    try { body = await fs.readFile(absPath, 'utf8'); }
    catch (e) {
      if (e.code === 'ENOENT') continue;
      throw e;
    }
    const oathCheck = checkOaths(scope, body);
    const entry = {
      scope, path: absPath, body,
      lines: body.split('\n').length,
      modified_at: (await fs.stat(absPath)).mtimeMs,
      oath_check: oathCheck.status,
      oath_conflict: oathCheck.conflict
    };
    entries.push(entry);
    if (oathCheck.status === 'fail') {
      conflicts.push({ scope, path: absPath, snippet: oathCheck.snippet, conflicting_oath: oathCheck.oath });
    }
  }
  const merged = entries
    .sort((a, b) => orderByScope(a.scope) - orderByScope(b.scope))
    .map(e => '# [' + e.scope + ']\n' + e.body)
    .join('\n\n');
  return { merged, entries, conflicts };
}

function orderByScope(scope) {
  return { global: 0, user: 1, workspace: 2, session: 3 }[scope];
}

function checkOaths(scope, body) {
  const violations = [

## The scaffold integration

```js
// in harness/scaffold.mjs:
import { loadInstructions } from '../node/src/services/agent-instructions.mjs';

export async function composeScaffoldWithInstructions({ workspace, effectiveContextTokens, taskFamily, sessionId }) {
  const baseScaffold = composeScaffold({ effectiveContextTokens, taskFamily });
  const instructions = await loadInstructions({ workspace, sessionId });
  const header = '[AIDE instructions | ' + instructions.entries.length + ' scope(s) loaded]';

From AnonymousNomad/covert-coder, Apache-2.0.

More from AnonymousNomad/covert-coder