Instructions for Coding Agents

These instructions define how Coding Agents should assist with this project.

Fluent workflow

Use the fluent to build the fluent. For non-trivial code, documentation, skill, expertise, or behavior changes, follow the fluent skill and go through the Fluent lifecycle: brief, behaviors, approach, plan, execution, review, and land.

Do not implement substantial product/code changes directly on main. Use Fluent Work Items and Attempts for delegated build work that needs isolation, reviewers, and merging. The Work model path is: Work Item, Attempt, Task, Workspace, and Merge Candidate.

Conversation agents may edit Fluent planning and memory state directly when they are collaborating with the user in the discussion loop: observations, briefs, behavior drafts, approaches, plans, lightweight curation, and similar durable notes. These edits are part of shaping work, not delegated execution.

Do not meddle with live execution state directly: branches, worktrees, statuses, session artifacts, and merging state belong to the execution system. Modify them only during explicit recovery with the user.

Keep main available as a stable integration branch for Work to rebase from and merge into. If conversation-state edits could overlap with active Work or merging, make them on a lightweight discussion branch or worktree and land them separately instead of dirtying main. Use fluent observations add to record future work and lessons. Open observations live as one file per entry under .fluent/observations/; resolved ones move to .fluent/observations/resolved/. Inspect with fluent observations list and fluent observations show <id>.

Commit messages

Subject line

• Use imperative mood and active voice
• Start with a verb: "Add", "Fix", "Update", "Remove", "Refactor"
• Keep under 50 characters
• Capitalize the first letter
• Do not end with a period
• Describe the change, not the process that led to it
  • Good: "Fix sandbox worktree binding"
  • Bad: "Run review and fix issues found"
  • Bad: "Address reviewer findings"
• Use "Improve" over "Fix" when the change enhances something that was working but could be better. "Fix" implies it was broken.

Body

• Separate from the subject with a blank line
• Use bullet points (- prefix) for listing changes
• Wrap at 72 characters
• Explain what changed and why, not how
• Do not reference the process: no "from review run," "based on reviewer feedback," or "as part of run X"

Prohibited

• Do not add Co-Authored-By trailers
• Do not reference run IDs, review artifacts, or fluent internals
• Do not include counts or statistics: "fix 12 issues," "remove 3,000 lines," "update 47 files." The diff shows the numbers. The message describes the change.

Linear history

Maintain a linear commit history — never create merge commits.

• Rebase feature branches onto main before merging: git rebase main
• Fast-forward merge only: git merge --ff-only <branch>
• If the fast-forward fails, rebase the branch again and retry

Installing Fluent

When asked to install the local Fluent binary, build the release binary and install it to the PATH-preferred user location:

cargo build --release
install -m 0755 target/release/fluent /Users/mrinal/.local/bin/fluent
fluent version

Do not use cargo install --path . for this repository unless the user explicitly asks for it; that installs to Cargo's bin directory, while this environment resolves /Users/mrinal/.local/bin/fluent first.

Documentation

• Don't create too many summary documents and markdown files.

Use clear, self-contained language

Start with plain language. Use established programming terms when they make the explanation more precise, and define them when the reader may not know them.

Avoid inventing names or metaphors for concepts that already have a clear description. Use existing project terminology consistently. When a Fluent-specific term is necessary, explain it in one short sentence before using it. Prefer “the current blocker and next safe action” over undefined shorthand such as “frontier.”

Before asking the user for a decision or explaining a recommendation, make the message self-contained. State the goal, relevant earlier decisions, current state, important evidence, the blocker or tradeoff, and the exact question or next step. Do not assume the user remembers earlier messages.

Use active verb forms

When writing comments, docstrings, commit messages, or documentation, prefer active verb phrases over nominalized noun phrases.

Active verbs are clearer, more direct, and easier to scan. They specify who or what performs the action and reduce ambiguity.

Examples

Prefer "to + verb" over "for + gerund"

When describing what a module or function does, prefer infinitive phrases:

Where this applies

• Function and method docstrings
• TODO comments
• Commit messages
• PR descriptions
• README sections
• Inline comments explaining intent

Exceptions

Nominalized forms are acceptable for class names (ConnectionManager, RequestHandler), module names, category labels in structured docs, and domain terms where the noun form is canonical.

Quick test

If you can ask "Who does what?" and rewrite to answer that question with a subject and verb, use the active form.

Interactive commands

Some git commands open an interactive pager that blocks terminal execution. Always pipe output to prevent blocking:

# Use these patterns to avoid blocking
git log --oneline -10 | cat
git diff | cat
git diff --stat | cat
git show | cat
git branch -a | cat

# Or use --no-pager flag
git --no-pager log --oneline -10
git --no-pager diff