Imported from flyingrobots/colorful-language (AGENTS.md). Install upstream with npx skills add flyingrobots/colorful-language. Copyright stays with the author.

Working Agreement for Agents

This file tells an automated contributor (any coding agent) how to work in colorful-language so that its changes satisfy CONTRIBUTING.md.

CONTRIBUTING.md is the authority. This file is the operational translation: the concrete things to do, in order, on every change. When the two disagree, CONTRIBUTING.md wins — and you should fix this file.

Prime Directive

Living references describe only what is true on main. Never write a README.md, docs/topics/<topic>/README.md, or docs/workflows/<workflow>/README.md to describe behavior that does not yet exist in committed, tested code. Plans live in test plans, the roadmap, issues, and pull requests — never in the current reference.

The four artifacts and their one job each:

Documentation Corpus Standard

docs/DOCUMENTATION_STANDARDS.md is the project-local standard for maintaining the documentation corpus. Follow it for new and substantially changed docs.

Operational rules:

• Give every page one primary reader job: learn, do, look up, understand, troubleshoot, or contribute.
• Keep durable product behavior in docs/topics/<topic>/README.md; keep planned verification and known gaps in docs/topics/<topic>/test-plan.md.
• Keep recurring repository operations in docs/workflows/<workflow>/, not docs/topics/.
• Add tutorials, how-to guides, reference pages, or troubleshooting pages only when the topic reference does not serve the reader's task.
• Link any new durable documentation page from docs/README.md.
• Use runnable examples when practical; separate copyable commands from expected output; do not use shell prompts in copyable command blocks.
• Put warnings before destructive, privileged, costly, or irreversible commands.
• Give informative visuals useful alt text or a nearby textual equivalent; never put essential instructions only in a screenshot.
• Treat prose metrics as editorial signals, not universal merge gates. Hard gates are facts: links, examples, generated reference, evidence, Markdown, whitespace, and contract coverage.

Goalpost And Topic Discipline

Before starting implementation for a goalpost slice:

1. Open or select the slice issue. GitHub milestones are goalposts. Release trains use one versioned tracking issue; slice issues keep their goalpost milestone.
2. Identify the owning docs/topics/<topic>/ or docs/workflows/<workflow>/ folder.
3. If the work creates a durable lane with no home, create a topic or workflow folder with at least README.md and test-plan.md, then link it from docs/README.md.
4. Update the topic or workflow test-plan.md with planned cases before code. Each case needs a requirement, oracle, evidence type, and status.
5. Keep topic and workflow README.md pages as current truth only. Do not describe planned behavior there until the implementation and evidence land.
6. Update ROADMAP.md when a slice opens, closes, or changes goalpost posture.

Do not begin a "next goalpost" implementation from chat context alone. First check the milestone, issue list, ROADMAP.md, docs/topics/, and docs/workflows/. If a durable product lane such as editor integrations, themes, distribution, generated contracts, or downstream consumers will keep recurring, give it a topic home or explicitly place it under an existing topic. If the lane is release automation, publishing, or repository maintenance, give it a workflow home.

Release Work

For any release, ship, version, tag, publish, or "is this ready?" request, read docs/RELEASING.md fresh before answering or acting. Do not rely on memory or chat history for the release process.

Also inspect .continuum/release.yml. It is the repo-local release profile: version sources, signposts, validation entrypoints, publish workflow, crates, and artifacts.

Before claiming release readiness:

1. Record the current branch, sync state against origin/main, latest v* tag, workspace version, and intended target version.
2. Confirm the working tree is clean.
3. Run git fetch origin main --tags, then confirm the target tag does not already exist locally or on the remote.
4. Audit docs/topics/, docs/workflows/, crate READMEs, editor READMEs, CHANGELOG.md, and ROADMAP.md against implemented behavior on main.
5. Report any stale current-reference claim as a blocker or fix it on a branch before continuing.
6. Run bash scripts/release-profile-check.sh.
7. Run the release gate from docs/RELEASING.md when preparing the release packet, not a remembered subset of commands.
8. Before creating a public tag from main, run bash scripts/release-preflight.sh vX.Y.Z.

The release runbook is the source of truth. This file only says when to consult it.

The Delivery Loop

For any meaningful behavior change, do these in order:

1. If the change needs design discussion, write or update a design note (docs/design/) or a topic/workflow rationale.md.
2. Update the owning topic or workflow test-plan.md with planned cases before writing code. Each case carries a stable ID, the requirement(s) it covers, an explicit oracle, an evidence type, and a status.
3. Write the smallest deterministic, executable evidence that fails for the missing behavior. Tests are the spec — write the failing test first.
4. Implement until the test passes. Do not alter, skip, or weaken a test to go green; fix the code. If a test seems wrong, stop and raise it.
5. Update the owning README.md so it describes the behavior that now exists.
6. Mark the planned cases implemented and record the real test names / fixture paths / doctests that are the evidence.
7. Update CHANGELOG.md and ROADMAP.md when the change is release-visible or shifts project posture.

Small fixes scale this down but keep the same shape: clear claim, evidence, implementation, honest current reference.

Architecture Rules (the hexagon)

• colorful-core stays pure: domain types and port traits, no I/O.
• Everything outside (parsing, lexicon lookup, terminal output, the LSP) is an adapter behind a port.
• Parser (structure), Lexicon (context-free word lookup), and Annotator (context-aware classification) are separate ports. Keep them separate — that seam is what makes future goalposts cheap.
• Need a new capability? Add a port + adapter. Do not thread a concrete outside dependency through the core.

Commits and Branches

• One logical change per commit. Use Conventional Commits (feat:, fix:, docs:, refactor:, test:, chore:).
• For a slice with a meaningful behavior change, land the delivery loop steps as three separate commits: a planned-case commit (adds the case to the test plan with status 'planned'), a failing-evidence commit (adds the failing test/fixture/dependency), and a passing-implementation commit (implements the code and flips the test plan status to 'implemented'). Tiny-fix exceptions apply as described in CONTRIBUTING.md.
• Issue closure happens on the slice PR, not on individual commits. Put Closes #NN in the pull request description (see .github/pull_request_template.md), never in a commit trailer. A commit may reference the issue for traceability (Refs #NN) (e.g. in the footer: Refs #NN), but must not use a closing keyword (Closes/Fixes/Resolves) — this repo merges via merge commits, so a closing keyword on a non-final commit would close the issue before the PR is done. A CI check enforces this on every pull request; see scripts/check-closure-contract.sh.
• The only body-level closure exception is a GitHub-authenticated app/dependabot pull request whose complete changed-file inventory fits one reviewed dependency-update family. It may carry zero or one unique closing reference. Do not infer this authority from a branch name, title, or body; human and other automation pull requests still require exactly one, and all commits still reject closing keywords.
• A breaking change carries a BREAKING CHANGE: footer and warrants a version bump.
• History is append-only: no force-push, rebase, squash, or amend on shared branches. Make a new commit instead.
• Do not delete or unstage files you did not create without explicit approval.
• Feature work happens on a branch and lands via pull request. Do not commit feature work directly to main.
• Stage with git add -A; a well-kept .gitignore is the safeguard, not selective staging.

Roadmap Mechanics

• GitHub milestones = goalposts. Release trains use one versioned tracking issue; slice issues keep their goalpost milestone. A slice's work closes its issue; keep ROADMAP.md anchors in sync.
• Do not describe an unbuilt goalpost as if it exists, in ROADMAP.md or anywhere else. The "Horizon" section is for directions, not commitments.

Before You Say "Done"

Run the local gate and confirm it is clean. Once crates exist:

cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --all --locked

For documentation changes:

markdownlint-cli2 "**/*.md"
git diff --check "$(git hash-object -t tree /dev/null)" HEAD
node scripts/check-internal-links.mjs
node scripts/check-doc-citations.mjs

See docs/DOCUMENTATION_STANDARDS.md §8 for what these enforce and what remains a known gap.

If you touch a GitHub Actions workflow, validate it before pushing — a bad workflow fails with zero useful logs:

actionlint .github/workflows/*.yml

GitHub Actions runs the same checks as the merge gate. Zero tolerance for errors and warnings: fix what you find, including pre-existing issues in code you touch.

Hard Don'ts

• Do not create a second current reference for a topic that already has a folder.
• Do not put durable behavior only in an issue, PR, or goalpost note.
• Do not leave planned or blocked test cases vague.
• Do not regenerate golden fixtures casually — golden changes are deliberate, reviewable, and tied to a contract change.
• Do not claim something is verified that you did not run. Report failures with their output.