Correspondents/.fortura-core/reference/formatting-conventions.md

==================== START: .fortura-core/reference/formatting-conventions.md ====================

Formatting Conventions Reference

This document specifies all formatting standards used in Fortura Agent Protocol agents, tasks, templates, and supporting files.

---

Markdown Formatting

Header Hierarchy

Standard:

# Level 1 - Document Title (one per file)

## Level 2 - Major Sections

### Level 3 - Subsections

#### Level 4 - Minor Subsections

##### Level 5 - Rarely used, specific details

###### Level 6 - Avoid if possible

Rules:

• Never skip levels (don't go from # to ###)
• Use sequential hierarchy (H1 → H2 → H3, not H1 → H3)
• One H1 per document (the title)
• H2 for major sections, H3 for subsections

---

Lists

Unordered Lists:

- Item one
- Item two
  - Nested item
  - Nested item
- Item three

Ordered Lists:

1. First item
2. Second item
   1. Nested item
   2. Nested item
3. Third item

Checkbox Lists:

- [ ] Incomplete task
- [x] Complete task
- [ ] Another incomplete task

Rules:

• Use - for bullets (not * or +)
• Use - [ ] for checkboxes (space between brackets)
• Use - [x] for completed (lowercase x)
• 2-space indentation for nesting

---

Code Blocks

Inline Code:

Use `backticks` for inline code, filenames, or variables.

Code Blocks:

```language
code here
```

Supported Languages:

• yaml - YAML configuration
• markdown - Markdown examples
• javascript, typescript, python, bash - Programming languages
• json - JSON data
• text - Plain text

Rules:

• Always specify language for syntax highlighting
• Use text if no specific language applies
• Close with triple backticks on new line

---

Tables

Standard Format:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
| Data 4   | Data 5   | Data 6   |

Alignment:

| Left    | Center  | Right  |
|:--------|:-------:|-------:|
| Text    | Text    | Text   |

Rules:

• Header row required
• Separator row required (at least 3 dashes per column)
• Use : for alignment (:--- left, :---: center, ---: right)
• Pipe | on both ends for clarity

---

Emphasis

Standard:

**Bold text** for strong emphasis
*Italic text* for mild emphasis
***Bold and italic*** for very strong emphasis
~~Strikethrough~~ for deprecated content

Rules:

• Use **bold** not __bold__
• Use *italic* not _italic_
• Don't overuse—reserve for actual emphasis

---

Links

Standard:

[Link text](https://example.com)
[Link with title](https://example.com "Title on hover")
[Reference link][ref-id]

[ref-id]: https://example.com

File References:

See `docs/architecture.md` for details.
Reference section: `file.md#section-name`
Source citation: [Source: path/file.md#section]

Rules:

• Use inline links for external URLs
• Use reference links if same URL used multiple times
• Use backtick code formatting for file paths
• Include section anchors when referencing specific sections

---

Blockquotes

Standard:

> This is a blockquote.
> It can span multiple lines.
>
> And multiple paragraphs.

Rules:

• Use > prefix for each line
• Leave blank line with > for paragraph breaks

---

Horizontal Rules

Standard:

---

Rules:

• Use three dashes ---
• Place on its own line with blank lines before and after
• Use sparingly to separate major sections

---

YAML Formatting

Indentation

Standard: 2 spaces per level (NO TABS)

level1:
  level2:
    level3: value

Rules:

• Never use tabs—always spaces
• Consistent 2-space indentation throughout
• Align items at same level

---

Strings

Unquoted:

simple_string: This is fine without quotes

Quoted:

special_chars: "String with: colons, #comments, or special chars"
multiline: "String with\nnewlines"

Multi-line:

literal_block: |
  This preserves newlines.
  Each line stays separate.

folded_block: >
  This folds newlines into spaces.
  Long text becomes one line.

Rules:

• Use quotes when string contains :, #, @, |, >, {, }, [, ]
• Use | for multi-line blocks that preserve newlines
• Use > for multi-line blocks that fold into single line

---

Lists and Arrays

Dash Notation:

items:
  - item1
  - item2
  - item3

Bracket Notation:

items: [item1, item2, item3]

Mixed (objects in array):

items:
  - name: Item 1
    value: 100
  - name: Item 2
    value: 200

Rules:

• Use dash notation for vertical lists
• Use bracket notation for short, inline lists
• Consistent style within same file
• Space after dash: - item not -item

---

Booleans and Null

Standard:

true_value: true
false_value: false
null_value: null

Rules:

• Use lowercase: true, false, null
• Don't use: True, FALSE, ~, yes, no

---

Comments

Standard:

# Full line comment
key: value  # Inline comment

Rules:

• Use # for comments
• Space after #: # comment not #comment
• Align inline comments when multiple in sequence

---

YAML Frontmatter (in Markdown)

Standard:

---
key: value
list:
  - item1
  - item2
---

# Markdown Content Starts Here

Rules:

• Three dashes --- before and after
• No content before opening ---
• Blank line after closing --- (optional but recommended)

---

Special Annotation Formats

LLM Instructions

Used in: Checklists, tasks

Format:

[[LLM: Special instructions for AI agent
These instructions guide agent behavior during execution.
Can be multi-line.
]]

Rules:

• Use [[LLM: ...]] wrapper
• All caps "LLM"
• Colon after LLM
• Can be multi-line
• Place at start of section or before specific items

---

Resource Boundaries

Used in: Agent bundles

Format:

==================== START: .fortura-core/folder/filename.md ====================
[File content here]
==================== END: .fortura-core/folder/filename.md ====================

Rules:

• Exactly 20 equal signs on each side
• Space before and after colon
• Full path with dot prefix (.fortura-core/...)
• START and END must match exactly
• Blank line before START and after END

---

Template Variables

Used in: Templates, output formats

Format:

{{variable_name}}
{{nested.variable}}
{{array[0]}}

Rules:

• Double curly braces: {{...}}
• Snake_case for variable names
• No spaces inside braces: {{var}} not {{ var }}
• Descriptive names, avoid abbreviations

---

File-Specific Conventions

Agent Files (.txt)

Structure:

# Web Agent Bundle Instructions
[Standard wrapper]
---
==================== START: .fortura-core/agents/agent-id.md ====================
# agent-id
CRITICAL: Read the full YAML...
```yaml
[YAML configuration]

==================== END: .fortura-core/agents/agent-id.md ==================== [Embedded resources]

**Naming:** `agent-name.txt` (e.g., `analyst.txt`, `dev.txt`)

---

### Task Files (.md)

**Structure:**
```markdown
<!-- Powered by Fortura™ Core -->

# Task Name

## Purpose
[Description]

## Process
[Steps]

## Output Deliverables
[What's produced]

Naming: verb-object.md (e.g., create-doc.md, validate-story.md)

---

Template Files (.yaml)

Structure:

template:
  id: template-name-v2
  name: Display Name
  version: 2.0
  output:
    format: markdown
    filename: path/to/output.md

sections:
  - id: section-id
    title: Section Title
    instruction: |
      Instructions

Naming: output-type-tmpl.yaml (e.g., prd-tmpl.yaml, architecture-tmpl.yaml)

---

Checklist Files (.md)

Structure:

<!-- Powered by Fortura™ Core -->

# Checklist Name

[[LLM: INITIALIZATION INSTRUCTIONS
Instructions for execution
]]

## Section 1
- [ ] Item 1
- [ ] Item 2

Naming: purpose-checklist.md or noun-definition-of-done.md

---

Data Files (.md)

Structure:

<!-- Powered by Fortura™ Core -->

# Data/Knowledge Title

## Category 1

**Item Name**
- Description
- Details
- Usage notes

## Category 2
...

Naming: content-type.md (e.g., brainstorming-techniques.md, elicitation-methods.md)

---

Naming Conventions Summary

Case Styles

Context	Style	Example
File names	kebab-case	create-doc.md
Agent IDs	kebab-case	agent-architect
Template IDs	kebab-case-vN	prd-template-v2
Section IDs	kebab-case	executive-summary
YAML keys	snake_case	user_segment
Variables	snake_case	{{project_name}}
Commands	kebab-case	design-agent

---

Suffixes and Prefixes

Type	Suffix/Prefix	Example
Templates	-tmpl.yaml	prd-tmpl.yaml
Checklists	-checklist.md or -definition-of-done.md	agent-validation.md
Agents	.txt	analyst.txt
Tasks	.md	create-doc.md
Data	.md	brainstorming-techniques.md

---

Version Numbering

Semantic Versioning for Templates

Format: vMAJOR.MINOR

Examples:

• v1.0 - Initial version
• v1.1 - Minor update (new optional section)
• v2.0 - Major update (breaking changes, restructure)

Rules:

• Increment MAJOR for breaking changes
• Increment MINOR for backward-compatible additions
• Include version in template ID: prd-template-v2

---

Output Document Formatting

Document Headers

Standard:

# Document Title: Project Name

**Date:** YYYY-MM-DD
**Version:** 1.0
**Author:** Agent Name
**Status:** Draft | Approved | Final

---

Change Logs

Standard:

## Change Log

| Date       | Version | Description | Author |
|------------|---------|-------------|--------|
| 2025-01-15 | 1.0     | Initial version | Agent Name |
| 2025-01-20 | 1.1     | Added section X | Agent Name |

---

Source Citations

Format:

[Source: docs/architecture.md#section-name]
[Source: PRD v2.0, Section 3.2]
[Source: User Interview 2025-01-15]

Rules:

• Always include file and section when referencing documents
• Include version if document versioned
• Include date for time-sensitive sources

---

Consistency Checklist

When creating any Fortura document, verify:

• Markdown headers use proper hierarchy (no skipped levels)
• Lists use - for bullets, - [ ] for checkboxes
• YAML uses 2-space indentation (no tabs)
• YAML booleans are lowercase (true, false, null)
• File names use kebab-case with appropriate suffix
• Template variables use snake_case: {{variable_name}}
• Code blocks specify language
• Tables have header and separator rows
• Links use inline format for URLs, backticks for file paths
• Resource boundaries use exact 20 = signs
• LLM annotations use [[LLM: ...]] format
• Version numbers follow semantic versioning
• Source citations include file and section

==================== END: .fortura-core/reference/formatting-conventions.md ====================