Skip to content

Commit 6eef016

Browse files
Copilotalexec
Copilot
and
alexec
authored
Add id, name, and description as standard frontmatter fields (#198)
* Initial plan * Add id, name, and description as standard frontmatter fields - Added ID, Name, and Description fields to TaskFrontMatter - Added ID, Name, and Description fields to RuleFrontMatter - Added ID, Name, and Description fields to CommandFrontMatter - All fields are optional and metadata-only - Updated existing tests to cover the new fields - Created comprehensive tests for CommandFrontMatter - All tests passing successfully Co-authored-by: alexec <1142830+alexec@users.noreply.github.com> * Update documentation for new id, name, and description frontmatter fields - Updated SPECIFICATION.md with new standard fields for tasks, rules, and commands - Updated docs/reference/file-formats.md with detailed documentation - Added examples for each new field - Updated Appendix C tables to include new fields - All changes maintain backward compatibility Co-authored-by: alexec <1142830+alexec@users.noreply.github.com> * Add example files demonstrating new standard frontmatter fields - Updated example task file to demonstrate id, name, and description fields - Created example rule file with standard fields - Created example command file with standard fields - All examples show proper usage and explain that fields are metadata-only Co-authored-by: alexec <1142830+alexec@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>
1 parent 3e1cbf1 commit 6eef016

9 files changed

Lines changed: 582 additions & 29 deletions

File tree

‎SPECIFICATION.md‎

Lines changed: 95 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -435,7 +435,40 @@ field3: "string value"
435435

436436
### 5.2 Standard Task Fields
437437

438-
#### 5.2.1 `task_name` (optional)
438+
#### 5.2.1 `id` (optional)
439+
- **Type:** String
440+
- **Purpose:** Unique identifier for the task
441+
- **Note:** Metadata only, does not affect task matching or filtering
442+
443+
```yaml
444+
---
445+
id: task-12345
446+
---
447+
```
448+
449+
#### 5.2.2 `name` (optional)
450+
- **Type:** String
451+
- **Purpose:** Human-readable name for the task
452+
- **Note:** Metadata only, does not affect task matching or filtering
453+
454+
```yaml
455+
---
456+
name: Fix Critical Bug
457+
---
458+
```
459+
460+
#### 5.2.3 `description` (optional)
461+
- **Type:** String
462+
- **Purpose:** Description of what the task does
463+
- **Note:** Metadata only, does not affect task matching or filtering
464+
465+
```yaml
466+
---
467+
description: Fix the critical bug affecting user authentication
468+
---
469+
```
470+
471+
#### 5.2.4 `task_name` (optional)
439472
- **Type:** String
440473
- **Purpose:** Metadata identifier for the task
441474
- **Note:** Tasks are matched by filename, not this field
@@ -446,7 +479,7 @@ task_name: fix-bug
446479
---
447480
```
448481

449-
#### 5.2.2 `resume` (optional)
482+
#### 5.2.5 `resume` (optional)
450483
- **Type:** Boolean
451484
- **Purpose:** Indicates if task is for resuming work
452485
- **Default:** `false`
@@ -458,7 +491,7 @@ resume: true
458491
---
459492
```
460493

461-
#### 5.2.3 `languages` (optional)
494+
#### 5.2.6 `languages` (optional)
462495
- **Type:** Array of strings (recommended) or string
463496
- **Purpose:** Metadata about programming languages
464497
- **Note:** Metadata only, does not auto-filter rules
@@ -472,7 +505,7 @@ languages:
472505
---
473506
```
474507

475-
#### 5.2.4 `agent` (optional)
508+
#### 5.2.7 `agent` (optional)
476509
- **Type:** String
477510
- **Purpose:** Target agent, acts as default selector
478511
- **Values:** `cursor`, `copilot`, `claude`, `gemini`, `opencode`, `augment`, `windsurf`, `codex`
@@ -483,7 +516,7 @@ agent: cursor
483516
---
484517
```
485518

486-
#### 5.2.5 `model` (optional)
519+
#### 5.2.8 `model` (optional)
487520
- **Type:** String
488521
- **Purpose:** AI model identifier (metadata only)
489522

@@ -493,7 +526,7 @@ model: anthropic.claude-sonnet-4-20250514-v1-0
493526
---
494527
```
495528

496-
#### 5.2.6 `single_shot` (optional)
529+
#### 5.2.9 `single_shot` (optional)
497530
- **Type:** Boolean
498531
- **Purpose:** Indicates single vs. multi-execution
499532
- **Note:** Metadata only
@@ -504,7 +537,7 @@ single_shot: true
504537
---
505538
```
506539

507-
#### 5.2.7 `timeout` (optional)
540+
#### 5.2.10 `timeout` (optional)
508541
- **Type:** String (Go time.Duration format)
509542
- **Purpose:** Task execution timeout
510543
- **Note:** Metadata only
@@ -515,7 +548,7 @@ timeout: 10m
515548
---
516549
```
517550

518-
#### 5.2.8 `selectors` (optional)
551+
#### 5.2.11 `selectors` (optional)
519552
- **Type:** Map of key-value pairs
520553
- **Purpose:** Auto-filter rules for this task
521554
- **Supports:** Scalar values and arrays (OR logic)
@@ -537,7 +570,7 @@ selectors:
537570
---
538571
```
539572

540-
#### 5.2.9 `expand` (optional)
573+
#### 5.2.12 `expand` (optional)
541574
- **Type:** Boolean
542575
- **Purpose:** Control parameter expansion
543576
- **Default:** `true`
@@ -550,7 +583,40 @@ expand: false
550583

551584
### 5.3 Standard Rule Fields
552585

553-
#### 5.3.1 `languages` (optional)
586+
#### 5.3.1 `id` (optional)
587+
- **Type:** String
588+
- **Purpose:** Unique identifier for the rule
589+
- **Note:** Metadata only, does not affect rule matching or filtering
590+
591+
```yaml
592+
---
593+
id: rule-12345
594+
---
595+
```
596+
597+
#### 5.3.2 `name` (optional)
598+
- **Type:** String
599+
- **Purpose:** Human-readable name for the rule
600+
- **Note:** Metadata only, does not affect rule matching or filtering
601+
602+
```yaml
603+
---
604+
name: Go Implementation Standards
605+
---
606+
```
607+
608+
#### 5.3.3 `description` (optional)
609+
- **Type:** String
610+
- **Purpose:** Description of what the rule provides
611+
- **Note:** Metadata only, does not affect rule matching or filtering
612+
613+
```yaml
614+
---
615+
description: Standards and best practices for Go implementation
616+
---
617+
```
618+
619+
#### 5.3.4 `languages` (optional)
554620
- **Type:** Array or string
555621
- **Purpose:** Filter rules by programming language
556622
- **Values:** Lowercase language names
@@ -562,7 +628,7 @@ languages:
562628
---
563629
```
564630

565-
#### 5.3.2 `stage` (optional)
631+
#### 5.3.5 `stage` (optional)
566632
- **Type:** String
567633
- **Purpose:** Filter by development stage
568634
- **Common values:** `planning`, `implementation`, `testing`, `review`
@@ -573,7 +639,7 @@ stage: implementation
573639
---
574640
```
575641

576-
#### 5.3.3 `agent` (optional)
642+
#### 5.3.6 `agent` (optional)
577643
- **Type:** String
578644
- **Purpose:** Target specific agent
579645

@@ -583,7 +649,7 @@ agent: cursor
583649
---
584650
```
585651

586-
#### 5.3.4 `mcp_server` (optional)
652+
#### 5.3.7 `mcp_server` (optional)
587653
- **Type:** Object
588654
- **Purpose:** Model Context Protocol server configuration
589655

@@ -1554,6 +1620,9 @@ Potential future additions while maintaining backward compatibility:
15541620

15551621
| Field | Type | Required | Purpose |
15561622
|-------|------|----------|---------|
1623+
| `id` | string | No | Unique identifier (metadata) |
1624+
| `name` | string | No | Human-readable name (metadata) |
1625+
| `description` | string | No | Task description (metadata) |
15571626
| `task_name` | string | No | Metadata identifier |
15581627
| `resume` | boolean | No | Resume mode indicator |
15591628
| `languages` | array/string | No | Programming languages (metadata) |
@@ -1568,11 +1637,24 @@ Potential future additions while maintaining backward compatibility:
15681637

15691638
| Field | Type | Required | Purpose |
15701639
|-------|------|----------|---------|
1640+
| `id` | string | No | Unique identifier (metadata) |
1641+
| `name` | string | No | Human-readable name (metadata) |
1642+
| `description` | string | No | Rule description (metadata) |
15711643
| `languages` | array/string | No | Language filter |
15721644
| `stage` | string | No | Development stage filter |
15731645
| `agent` | string | No | Agent filter |
15741646
| `mcp_server` | object | No | MCP server config |
15751647

1648+
### Command Fields
1649+
1650+
| Field | Type | Required | Purpose |
1651+
|-------|------|----------|---------|
1652+
| `id` | string | No | Unique identifier (metadata) |
1653+
| `name` | string | No | Human-readable name (metadata) |
1654+
| `description` | string | No | Command description (metadata) |
1655+
| `expand` | boolean | No | Parameter expansion control |
1656+
| `selectors` | object | No | Auto-filter rules |
1657+
15761658
### Skill Fields
15771659

15781660
| Field | Type | Required | Purpose |

‎docs/reference/file-formats.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,48 @@ Content can include ${parameter_placeholders}.
2929

3030
### Frontmatter Fields
3131

32+
#### `id` (optional, standard field)
33+
34+
**Type:** String
35+
**Purpose:** Unique identifier for the task. This field is metadata only and does not affect task matching or filtering.
36+
37+
**Example:**
38+
```yaml
39+
---
40+
id: task-12345
41+
---
42+
```
43+
44+
**Note:** The `id` field is purely informational and can be used to track tasks in external systems or for auditing purposes.
45+
46+
#### `name` (optional, standard field)
47+
48+
**Type:** String
49+
**Purpose:** Human-readable name for the task. This field is metadata only and does not affect task matching or filtering.
50+
51+
**Example:**
52+
```yaml
53+
---
54+
name: Fix Critical Authentication Bug
55+
---
56+
```
57+
58+
**Note:** The `name` field is useful for display purposes and documentation, but tasks are still matched by their filename.
59+
60+
#### `description` (optional, standard field)
61+
62+
**Type:** String
63+
**Purpose:** Description of what the task does. This field is metadata only and does not affect task matching or filtering.
64+
65+
**Example:**
66+
```yaml
67+
---
68+
description: Fix the critical bug affecting user authentication in the login flow
69+
---
70+
```
71+
72+
**Note:** The `description` field provides additional context about the task's purpose and goals.
73+
3274
#### `task_name` (optional)
3375

3476
**Type:** String
@@ -439,6 +481,48 @@ This content will be substituted when the command is referenced.
439481

440482
### Frontmatter Fields (optional)
441483

484+
#### `id` (optional, standard field)
485+
486+
**Type:** String
487+
**Purpose:** Unique identifier for the command. This field is metadata only and does not affect command matching or filtering.
488+
489+
**Example:**
490+
```yaml
491+
---
492+
id: cmd-12345
493+
---
494+
```
495+
496+
**Note:** The `id` field is useful for tracking commands in external systems.
497+
498+
#### `name` (optional, standard field)
499+
500+
**Type:** String
501+
**Purpose:** Human-readable name for the command. This field is metadata only and does not affect command matching or filtering.
502+
503+
**Example:**
504+
```yaml
505+
---
506+
name: Database Setup
507+
---
508+
```
509+
510+
**Note:** The `name` field helps identify the command's purpose in documentation.
511+
512+
#### `description` (optional, standard field)
513+
514+
**Type:** String
515+
**Purpose:** Description of what the command does. This field is metadata only and does not affect command matching or filtering.
516+
517+
**Example:**
518+
```yaml
519+
---
520+
description: Sets up PostgreSQL database with authentication
521+
---
522+
```
523+
524+
**Note:** The `description` field provides context about the command's functionality.
525+
442526
#### `expand` (optional)
443527

444528
**Type:** Boolean
@@ -563,6 +647,48 @@ All frontmatter fields are optional and used for filtering.
563647

564648
**Standard fields for rules:**
565649

650+
#### `id` (optional, standard field)
651+
652+
**Type:** String
653+
**Purpose:** Unique identifier for the rule. This field is metadata only and does not affect rule matching or filtering.
654+
655+
**Example:**
656+
```yaml
657+
---
658+
id: rule-12345
659+
---
660+
```
661+
662+
**Note:** The `id` field is useful for tracking rules in external systems or for documentation purposes.
663+
664+
#### `name` (optional, standard field)
665+
666+
**Type:** String
667+
**Purpose:** Human-readable name for the rule. This field is metadata only and does not affect rule matching or filtering.
668+
669+
**Example:**
670+
```yaml
671+
---
672+
name: Go Implementation Standards
673+
---
674+
```
675+
676+
**Note:** The `name` field helps identify the rule's purpose in documentation and tooling.
677+
678+
#### `description` (optional, standard field)
679+
680+
**Type:** String
681+
**Purpose:** Description of what the rule provides. This field is metadata only and does not affect rule matching or filtering.
682+
683+
**Example:**
684+
```yaml
685+
---
686+
description: Standards and best practices for implementing Go code
687+
---
688+
```
689+
690+
**Note:** The `description` field provides context about what guidance the rule offers.
691+
566692
#### `task_names` (rule selector)
567693

568694
Specifies which task(s) this rule applies to. Can be a string or array. The field name is `task_names` (plural).

‎examples/agents/commands/example-command-with-standard-fields.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
id: cmd-example-001
3+
name: Example Command with Standard Fields
4+
description: This command demonstrates the use of id, name, and description standard frontmatter fields
5+
expand: true
6+
---
7+
8+
# Example Command
9+
10+
This command demonstrates the new standard frontmatter fields:
11+
- `id`: A unique identifier for the command
12+
- `name`: A human-readable name
13+
- `description`: A description of what the command does
14+
15+
These fields are metadata only and do not affect command matching.
16+
Commands are still referenced using slash syntax like `/example-command-with-standard-fields`.

0 commit comments

Comments
 (0)