Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions engine/app/views/coplan/agent_instructions/show.text.erb
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,28 @@ The server diffs your content against the current revision, records granular ope

See [Editing Plans](#editing-plans-recommended-full-content-replacement) for the full request/response reference, and the lease + operations path only when you need a surgical single-operation edit.

## Writing Style

These rules apply to every plan you write or edit. One exception mechanism: **a plan type's description or template may override any of them — the type wins.** (A persuasive pitch type can welcome persuasive language; these defaults assume a working document.)

**The platform already records it.** Never write document metadata into the body:

- No date or "last updated" lines — every version is timestamped in the plan history.
- No author, attribution, or "prepared by" lines — every version and comment is attributed, including your agent name.
- No status lines, status fields, or status tables — visibility, archival, and tags carry state (see [Visibility & Archiving](#visibility--archiving)). There is no document status; do not invent one.
- No version numbers or changelogs — the plan history is the changelog.

The exception is dates that anchor **facts**, which belong in content: "confirmed against production 2026-08-19", "verified at commit abc123".

**Write plainly.** Follow Simplified-Technical-English-style rules:

- Short sentences. One idea per sentence. Active voice, present tense.
- Plain verbs: "use", not "leverage"; "check", not "perform validation of".
- No metaphors, no marketing adjectives, no drama. Words that signal padding — "robust", "seamless", "comprehensive", "cutting-edge", "elegant", "crucially", "delve", "honest", "actually" — are banned unless you are quoting someone.
- State facts without selling them. The reader is a colleague deciding what to do, not an audience to impress. Write like a runbook, not a keynote.
- Prefer a table or list over a paragraph when the content is enumerable.
- Length is a cost. Write the shortest document that serves its reader, then stop.

## API Reference

### List Plans
Expand Down
12 changes: 12 additions & 0 deletions spec/requests/agent_instructions_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,18 @@
expect(response.body).to include('"plan_type"')
end

it "sets writing-style ground rules with a type-level override" do
get agent_instructions_path

expect(response.body).to include("## Writing Style")
# Anti-metadata rules: the platform records dates/authors/status/versions.
expect(response.body).to include("The platform already records it.")
expect(response.body).to include("do not invent one")
# Plain-language rules with the override escape hatch.
expect(response.body).to include("the type wins")
expect(response.body).to include("Write like a runbook, not a keynote.")
end

it "walks agents through folder, type, and template before creating" do
get agent_instructions_path

Expand Down
Loading