==================== START: .fortura-core/reference/formatting-conventions.md ====================
<!-- Powered by Fortura™ Core -->

# 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:**
```markdown
# 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:**
```markdown
- Item one
- Item two
  - Nested item
  - Nested item
- Item three
```

**Ordered Lists:**
```markdown
1. First item
2. Second item
   1. Nested item
   2. Nested item
3. Third item
```

**Checkbox Lists:**
```markdown
- [ ] 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:**
```markdown
Use `backticks` for inline code, filenames, or variables.
```

**Code Blocks:**
````markdown
```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:**
```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
| Data 4   | Data 5   | Data 6   |
```

**Alignment:**
```markdown
| 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:**
```markdown
**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:**
```markdown
[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:**
```markdown
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:**
```markdown
> 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:**
```markdown
---
```

**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)

```yaml
level1:
  level2:
    level3: value
```

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

---

### Strings

**Unquoted:**
```yaml
simple_string: This is fine without quotes
```

**Quoted:**
```yaml
special_chars: "String with: colons, #comments, or special chars"
multiline: "String with\nnewlines"
```

**Multi-line:**
```yaml
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:**
```yaml
items:
  - item1
  - item2
  - item3
```

**Bracket Notation:**
```yaml
items: [item1, item2, item3]
```

**Mixed (objects in array):**
```yaml
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:**
```yaml
true_value: true
false_value: false
null_value: null
```

**Rules:**
- Use lowercase: `true`, `false`, `null`
- Don't use: `True`, `FALSE`, `~`, `yes`, `no`

---

### Comments

**Standard:**
```yaml
# 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:**
```markdown
---
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:**
```markdown
[[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:**
```markdown
==================== 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:**
```markdown
{{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:**
```yaml
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:**
```markdown
<!-- 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:**
```markdown
<!-- 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:**
```markdown
# Document Title: Project Name

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

---

### Change Logs

**Standard:**
```markdown
## 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:**
```markdown
[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 ====================