Ijfw Agents Md

IJFW AGENTS.md Manager

Maintains a project's AGENTS.md per the open spec at https://agents.md/. AGENTS.md is the canonical agent-instructions surface across every IJFW host (Claude, Gemini, Codex, Wayland, Hermes, Cursor, Windsurf, Copilot). Each platform-specific file (CLAUDE.md, GEMINI.md, WAYLAND.md, etc.) is a thin adapter that points here.

When to Invoke

• User says: "agents.md", "update AGENTS.md", "regenerate agents file".
• Auto-fired by ijfw-team after generating agents to .ijfw/agents/.
• Auto-fired by session-start hooks to refresh memory + agents blocks.
• Auto-fired by ijfw-workflow at brainstorm-LOCK and plan-LOCK with intent context (v1.4.4 N7).

Marker Block Taxonomy (reserved -- do not break)

The file is segmented by four IJFW-managed regions. Content outside markers is user-authored and untouched.

Each block is delimited by <!-- IJFW-<NAME>-START --> / <!-- IJFW-<NAME>-END --> markers. Replace inside; never overwrite.

Frontmatter Contract (typed)

YAML frontmatter at top of file follows the JSON Schema at schema/agents-md-frontmatter.json. Keys that A1 may write or hoist:

• ijfw_version, ijfw_schema (required when present)
• type, primary_type, secondary_types, confidence (A3 writes)
• detected_at, signals (A3 writes)
• compute_trust (vm_only | subprocess), compute_net (deny | allow)

Wayland reads compute_trust + compute_net to set per-project sandbox defaults. Env vars override only when explicitly set.

Merge Mechanics

1. Use scripts/lock.sh -- PID lockfile + atomic rename guarantees concurrent invocations serialise without clobbering.
2. lock.sh invokes scripts/merge-block-aware.sh <path> <BLOCK> <content> which replaces marker-bounded regions atomically.
3. If AGENTS.md is absent, the merger seeds it from templates/AGENTS.md.tmpl.
4. If markers are absent in an existing file, they are appended at the end (user content stays intact).

Spec Subset IJFW Commits To

YAML frontmatter at top + GitHub-style heading slugs (lowercase, hyphenated). This is the load-bearing subset of the open AGENTS.md spec; section anchors remain stable for cross-tool references.

BLACKBOARD Block Population (v1.4.4 Pillar B activation)

The reserved BLACKBOARD marker block is now populated by mcp-server/src/orchestrator/wave-state.js::checkpointWave after every wave checkpoint. This activates Pillar B (multi-CLI orchestration) without requiring any manual skill invocation.

Block content shape

{
  "state_path": ".ijfw/wave-<waveId>/STATE.md",
  "last_completions": [
    "<waveId>: <summary line 1>",
    "<waveId>: <summary line 2>",
    "<waveId>: <summary line 3>"
  ]
}

• state_path — JSON pointer to the active wave's STATE.md.
• last_completions — last N=3 completion summaries (configurable; default 3). Drawn from the body field of each wave's STATE.md, newest first.

Write rules

1. The populator replaces content only between <!-- IJFW-BLACKBOARD-START --> and <!-- IJFW-BLACKBOARD-END --> markers.
2. Never write outside those markers. Use merge-block-aware.sh with BLACKBOARD as the block argument — same mechanism as MEMORY/ROUTING/AGENTS.
3. Idempotency: serialise the JSON with stable key order + \n terminator. Re-running on unchanged STATE.md produces byte-identical output; git sees no diff noise.
4. If no wave STATE.md exists yet, write an empty JSON object {} inside the block rather than omitting the block entirely (markers must remain present).

Discipline Block Population (v1.5.2 Wave 5B)

The DISCIPLINE marker block is populated by mcp-server/src/orchestrator/agents-md-blackboard.js::populateDisciplineBlock at brainstorm-LOCK and plan-LOCK in ijfw-workflow. It injects per-domain rules so every agent operating in the project gets domain-appropriate discipline guidance without manual configuration.

Block content shape

The block body is the raw text of the matching claude/skills/ijfw-agents-md/templates/discipline-<type>.md file, written verbatim between the markers. For unknown or mixed project types the body is intentionally empty (markers present, body empty — this is the correct state, not an error).

Example for a code project (abbreviated):

<!-- IJFW-DISCIPLINE-START -->
# Code Discipline

Working code only. Finish the job. Plausibility is not correctness.
…
<!-- IJFW-DISCIPLINE-END -->

Write rules

1. The populator replaces content only between <!-- IJFW-DISCIPLINE-START --> and <!-- IJFW-DISCIPLINE-END --> markers.
2. Never write outside those markers. Uses mergeFile() from merge-block-aware.js with DISCIPLINE as the block name — same mechanism as MEMORY/ROUTING/AGENTS/BLACKBOARD.
3. Same withFsLock tier-#8 AGENTS.md lock as populateBlackboardBlock — both writers serialise on the single §3 #8 lock so concurrent fires cannot interleave their writes.
4. Idempotency: re-running populateDisciplineBlock on unchanged project type produces byte-identical output; git sees no diff noise. The template files are static; the content written is purely a function of projectType.
5. Empty-body contract: if selectDisciplineTemplate returns an empty string (for unknown or mixed types), mergeFile still writes the block — the marker pair is present in AGENTS.md with an empty body. This is intentional: consumers can detect the block's presence without needing to distinguish "block absent" from "block empty".