calorie-counter/.github/copilot-modules/agent-standards.md

Agent files use atomic sentences. One concept per sentence. Maximum 80 characters per line.

Agent Standards - Layer 1

Module: Agent Standards Component: Layer 1 (Atomic Markdown Agent) Load: When working on virsaitis-agent/ or .github/agents/ Version: 3.0.0 Updated: 2026-04-20

---

Machine Policy

[AGENT_FORMAT]
FORMAT=markdown
SENTENCE_STRUCTURE=atomic
ENCODING=utf8_no_bom
LINE_LENGTH=80_chars_max

[FILE_OPERATIONS]
GITHUB_FOLDER_WRITE=prohibited_except_skills
AUTOMATED_FORMATTERS=prohibited
CREATE_FILE_TOOL=allowed_outside_github

---

Atomic Sentence Construction (TIER-0)

Definition: One sentence expresses exactly ONE concept.

Characteristics:

• Single subject-verb-object relationship
• No compound clauses ("and", "but", "which" joining ideas)
• No nested dependencies or implicit references
• Standalone comprehensibility

WHY: AI models comprehend atomic sentences 30% more accurately than compound sentences.

Good vs Bad Examples

GOOD (Atomic):

You must validate file existence.
File validation prevents NotFoundError.
Run validation before modification.
Use read_file tool for validation.

BAD (Compound):

You must validate file existence before modification to
prevent NotFoundError, and this should be done using the
read_file tool which checks both path and permissions.

Four concepts in one sentence. Split into four atomic sentences.

---

Markdown Format Requirements

FILE FORMAT:

• Extension: .md or .agent.md
• Encoding: UTF-8 without BOM
• Line endings: LF (not CRLF)
• No trailing whitespace
• Single newline at end of file

HEADINGS:

• H1: Document title only (one per file)
• H2: Major sections
• H3: Subsections
• Always space after hash: ## Title

LISTS:

• 2-space indent for nesting
• Ordered lists for sequential steps
• Unordered lists for non-sequential items

PROHIBITED:

• Tabs for indentation
• Multiple consecutive blank lines
• Automated formatters (Prettier, markdownlint)
• Spell checkers are OK (no structural changes)

---

.github Folder Governance (TIER-0)

The .github/ folder controls Virsaitis governance behavior. Uncontrolled changes to agents, modules, or instructions undermine enforcement. Changes outside .github/skills/ require the override workflow.

EXCEPTION: .github/skills/ — AI may create and update skill files.

CONSEQUENCE:

• Governance integrity cannot be guaranteed
• System must be re-validated manually
• Remediation: revert changes, validate all governance files

---

Agent File Workflows (TIER-0)

Creation

1. Generate agent content in memory
2. Validate atomic structure (one concept per sentence)
3. For files outside .github/: use create_file tool directly
4. For files inside .github/: provide code block to user for manual creation
5. Verify file content after creation

Modification

1. Read existing file content (entire file)
2. Draft changes maintaining atomic structure
3. Use replace_string_in_file with 3-5 lines context
4. Verify no sentences merged accidentally

IMPORTANT: Files in .github/ (except .github/skills/) require the override workflow.

---

Validation Checklist

EACH SENTENCE MUST:

• Express one concept only
• Have clear subject and verb
• Be understood without prior sentence
• Be under 80 characters (recommended)
• Contain no compound clauses

CONCEPT COUNTING: Read aloud. If you pause mid-sentence, split there.

COMMON FIXES:

• "and" joining concepts → split into two sentences
• "which"/"that" adding details → new sentence with explicit subject
• Implicit "it"/"this" → repeat the noun

---

Agent File Structure

REQUIRED SECTIONS (in order):

1. Anchor line (governance rule, not title)
2. Title + metadata
3. Machine-readable policy block
4. TIER-0 rules (safety-critical)
5. TIER-1 rules (important operations)
6. TIER-2/3 rules (quality/info)
7. Workflow patterns
8. Sandwich close (key rules summary)

ATTENTION ENGINEERING:

• Anchor line: highest-attention position (line 1)
• Sandwich close: recency zone (last 10 lines)
• Tripwires: every ~60 lines in middle sections
• Different wording from other sources (CT-3)

---

Change Management

MUST UPDATE agent files when:

• New TIER-0 rule added
• Existing rule modified
• Enforcement consequence changed
• New component integration
• Security policy updated

UPDATE PROCESS:

1. Draft new content (atomic sentences)
2. Validate atomic structure
3. Update version number and date
4. Add CHANGELOG entry
5. Commit with REQ-ID reference

---

Quick Reference

Aspect	Standard	Violation
Sentences	One concept only	Multiple concepts
File Creation	Tools outside .github, manual inside	Direct .github modification
Encoding	UTF-8 no BOM	UTF-8 with BOM
Line Length	<80 chars	>120 chars
Formatting	Manual only	Auto-formatter

---

Agent Standards Module v3.0.0 Atomic sentence construction for maximum AI comprehension

---

Key Rules From This Module

• One concept per sentence. No compound sentences in agent files.
• Maximum 80 characters per line. Break at natural points.
• Files in .github/ (except skills/) require the override workflow.
• Every agent file must have an anchor line, sandwich close, and tripwires.
• Definitions: .github/virsaitis-definition-library.md

Return to hub: .github/copilot-instructions.md