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)**:
```markdown
You must validate file existence.
File validation prevents NotFoundError.
Run validation before modification.
Use read_file tool for validation.
```

**BAD (Compound)**:
```markdown
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`