Collaboration & Learning Mandate — Injection Mechanism

Implements: AGENTS.md § 1b — Collaborative Agentic Philosophy Source: tools/refactor_agents.py

Background

Cornerstone uses a distributed agent model: each domain has a specialist agent defined by a SKILL.md file under .agents/skills/. As the team grows, two failure modes emerge:

Knowledge hoarding — an agent solves a problem but does not document the solution in its SKILL.md, so the next session starts from scratch.
Scope creep — an agent attempts tasks outside its domain rather than delegating, producing lower-quality results than a specialist would.

The Collaboration & Learning Mandate section addresses both failure modes by encoding collaborative norms directly in each SKILL.md file, where the agent reads it at the start of every session.

Why a Script Instead of a Template?

A cookiecutter template only runs once at project creation. Skill files are living documents — domain experts update them continuously. The mandate text itself evolves as the team learns what collaborative norms matter most.

refactor_agents.py solves the day-2 problem: when the mandate text changes, re-running the script propagates the update to every skill file in a single command, without manual editing of 30+ files.

Idempotency Guarantee

The script's first action on every file is to check whether MANDATE_HEADING (## Collaboration & Learning Mandate) already appears in the content. If it does, the file is skipped without modification.

This means the script can run safely:

As a pre-commit hook on every git commit
In a CI job on every push to main
Manually, multiple times, without risk of duplicate sections

Insertion Strategy

File content
│
├── Existing content ...
│
│   [If ## When You Don't Know Something exists]
│   ↓
├── ## Collaboration & Learning Mandate   ← inserted here
│   (mandate block)
│
├── ---                                    ← visual delimiter
│
└── ## When You Don't Know Something      ← anchor heading
    (existing fallback guidance)

Why before ## When You Don't Know Something? The mandate is a proactive norm (share knowledge, stay in domain). The "don't know" section is a reactive fallback. Placing proactive guidance before reactive guidance reflects the intended reading order.

When the anchor is absent: The mandate is appended at the end of the file with exactly one blank line of separation. Blank-line padding is normalised so the output is consistent regardless of how much trailing whitespace the original file had.

Return Values

inject() returns a Literal["skipped", "appended", "inserted"] string. Using a Literal type (rather than an Enum or plain str) keeps the signature expressive without requiring a class definition, and mypy can verify exhaustive handling by callers.

Return value	Meaning
`"skipped"`	Mandate already present; file unchanged
`"inserted"`	Mandate injected before anchor heading
`"appended"`	Mandate appended at end of file

Output Format

  ✓  [inserted ]  .agents/skills/software/quality/technical-writer/SKILL.md
  –  [skipped  ]  .agents/skills/core/learning-protocol/SKILL.md
  +  [appended ]  .agents/skills/software/discovery/cobol-analyst/SKILL.md

Done — 1 inserted, 1 appended, 29 skipped (out of 31 files).

The one-character markers (✓, –, +) allow the output to be scanned visually in seconds, while the bracketed labels make grep-based filtering possible in CI log aggregation tools.

Updating the Mandate Text

Edit MANDATE_BLOCK in tools/refactor_agents.py.
Delete (or clear) MANDATE_HEADING from any SKILL.md files you want to refresh (or remove the heading to trigger "skipped" → "inserted" re-injection).
Run python tools/refactor_agents.py.
Commit the updated skill files with docs: refresh Collaboration Mandate.