Repository Instructions

These instructions apply to every file in this repository unless a more local AGENTS.md overrides them.

Purpose

Development Workflow is an open-source, agent-agnostic set of coding-agent skills that carry a change from problem to integration. It ships adapters for Claude Code and Codex. Optimize contributions for clarity, portability, and practical use, not for the feature set of a single agent.

Working rules

• Read the root README.md and the relevant directory documentation before changing a skill.
• Treat skills/<skill-name>/SKILL.md as the canonical definition of a skill.
• When you add, remove, or change a workflow skill under skills/, update the guide in docs/development-workflow/ in the same change so its plain-language pages never drift from the canonical SKILL.md files. Follow docs/development-workflow/maintaining.md to find which page to edit.
• Treat agents/<role>.md as the canonical role definition: what a role runs, what it produces, and its non-negotiables, in plain capability terms.
• Keep harness-specific configuration in adapters/<harness>/. An adapter wires the canonical files into a harness - tool limits, dispatch names, hooks - and points at them rather than restating any procedure. Do not pin models; workers inherit the session's model.
• Do not duplicate essential instructions across adapters. Link to or generate from the canonical material where practical. When an adapter and a canonical file disagree, the canonical file wins and the adapter is the bug.
• Keep changes scoped. Do not reformat or rewrite unrelated material.
• Prefer direct, testable instructions over broad advice or lengthy background.
• Use progressive disclosure: place detailed examples, specifications, and source notes in supporting files.
• Use lowercase kebab-case for skill directory names.
• Use relative links for files within the repository and verify that new links resolve.
• Use ASCII by default unless the content requires otherwise.

Reviewing external skills

Do not copy an external skill into the collection without review.

1. Document its repository, author or organization, license, and revision.
2. Explain what problem it solves and which parts are worth retaining.
3. Identify assumptions tied to a particular agent, operating system, or tool.
4. Remove redundant, overly broad, or untestable instructions.
5. Rewrite the selected behavior into the repository's canonical format.
6. Preserve required attribution and confirm that the source license permits adaptation and redistribution.

If licensing is absent or unclear, record notes in docs/ but do not copy the source material into skills/.

Validation

For documentation-only changes:

• Check headings, code blocks, and relative links.
• Confirm examples match the documented directory layout.
• Read instructions from the perspective of an agent with no prior context.

For any change under skills/ or agents/:

• Confirm the guide in docs/development-workflow/ was updated in the same change, or state explicitly why no doc change was needed (for example, a change with no effect on phases, loops, gates, artifacts, or roles).
• Confirm the catalog in skills/README.md still lists every skill, and that any affected adapter under adapters/ still resolves.
• For a skill containing a repeat-until loop, confirm it has all four brakes: a blocking threshold, a narrowing round scope, memory of settled decisions, and a round budget ending in escalation. An unbounded loop is a defect, not rigour.

Run scripts/check.sh before you finish. It syntax-checks every shell script, runs shellcheck when installed, and verifies every relative Markdown link.

For scripts or executable assets, run the narrowest relevant checks and record any environment requirements in the skill. Hook scripts under adapters/ must be syntax-checked and executed against both a triggering and a non-triggering input before the change is accepted.

Communication

When completing work, summarize what changed, what was validated, and any open licensing or portability questions. Do not claim compatibility with an agent that was not tested.