ijfw-agents-md

name	ijfw-agents-md
description	Maintain canonical AGENTS.md (open spec). Trigger: 'agents.md', 'update AGENTS.md', or auto-fired by ijfw-team after agent generation.
context	fork
model	sonnet

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.

Block	Purpose
MEMORY	Pointer to project memory + last handoff summary
ROUTING	Peer-skill routing rules (workflow, design, etc.)
AGENTS	Auto-generated agent definitions from .ijfw/agents/
BLACKBOARD	Reserved for Pillar B (multi-CLI orchestration); empty
DISCIPLINE	Per-domain discipline rules (code | narrative | business | design | research)

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".

Auto-fire trigger

ijfw-workflow fires populateDisciplineBlock at:

• brainstorm-LOCK — when the brainstorm output is locked and project type is known (or inferable from the repo).
• plan-LOCK — when the plan is locked, to refresh discipline context after any type reclassification that may have occurred during planning.

These are the same LOCK hooks that fire populateBlackboardBlock and intent-aware seeding — the three fires are sequential within the same lock acquisition to preserve the §3 ordering invariant.

Conditional activation (project-type detection)

When projectType is not supplied explicitly, populateDisciplineBlock calls detectProjectTypeFromRepo(projectRoot) from discipline-selector.js to infer the type. Detection priority:

1. .ijfw/memory/brief.md frontmatter type key — highest fidelity, set by brainstorm-LOCK.
2. Well-known file/dir signals (existsSync only, no glob):
   • code: package.json, tsconfig.json, Cargo.toml, go.mod, pyproject.toml, setup.py, Gemfile, or any *.csproj in root.
   • narrative: chapters/ or manuscript/ directory present.
   • business: root entry starting with pitch-deck or business-plan, or any *.numbers file.
   • design: root entry starting with figma-, any *.sketch file, or design-system/ directory.
   • research: research/ or notebooks/ directory, or any *.ipynb file.
   • unknown: fallback when no signal matches.

---

Intent-aware seeding (v1.4.4 N7)

When AGENTS.md is being created fresh (file missing), the bootstrap is fed intent context from the active brainstorm/plan output (.ijfw/memory/brief.md if present). The bootstrap merges that intent into the initial AGENTS.md body under a ## Project intent (seeded from brainstorm) H2 so every subagent has project goals visible from the first session.

Rules

1. Fresh creation only. If AGENTS.md already exists, intent seeding does NOT run — idempotent by design. Existing files receive brainstorm context as a BLACKBOARD block update instead (see "BLACKBOARD Block Population").
2. brief.md is optional. If .ijfw/memory/brief.md is absent, bootstrap proceeds from the static template without the intent section.
3. Placement. The intent section is inserted after the YAML frontmatter and before any IJFW-managed marker blocks. User-authored content added later is never moved.
4. Auto-fire trigger. ijfw-workflow fires this skill at brainstorm-LOCK and plan-LOCK with the intent context. The skill self-detects whether AGENTS.md exists to decide seed vs. blackboard-update path.

---

Platform adapter creation (v1.4.4 N7)

IDE is detected via mcp-server/src/ide-detect.js (shipped in v1.4.3 B18). When the skill runs and the detected platform file is missing, it is created from the matching adapter template.

Detected IDE	Missing file	Template source
Claude	CLAUDE.md	templates/CLAUDE.md.adapter.tmpl
Gemini	GEMINI.md	templates/GEMINI.md.adapter.tmpl
Hermes	HERMES.md	templates/HERMES.md.adapter.tmpl
Wayland	WAYLAND.md	templates/WAYLAND.md.adapter.tmpl

Adapter body

# <IDE>

All project conventions live in [AGENTS.md](./AGENTS.md). Read it first.

Rules

1. Idempotent. If <IDE>.md already exists, it is never touched.
2. Detection required. Adapter is only created when ide-detect.js positively identifies the platform — never speculatively.
3. Template resolution. Templates live in the repository root templates/ directory. If the template is absent, the adapter is written inline from the body above rather than failing.
4. Auto-fire trigger. Same LOCK hook that fires intent seeding also runs the adapter-creation check, so a fresh Claude session always bootstraps both AGENTS.md content and a matching CLAUDE.md pointer.

---

Don'ts

• Do not write outside the five marker blocks.
• Do not replace the whole file; the merger is block-scoped by design.
• Do not write a .bak restore unless the user explicitly confirms.