a5c-ai/babysitter / library/methodologies/gsd/skills/frontmatter-parsing
frontmatter-parsing
VerifiedYAML frontmatter parsing and manipulation for .planning/ documents. Provides read, write, update, query, and validation operations on frontmatter blocks in GSD markdown artifacts.
SKILL.md
View on GitHub---
name: frontmatter-parsing
description: YAML frontmatter parsing and manipulation for .planning/ documents. Provides read, write, update, query, and validation operations on frontmatter blocks in GSD markdown artifacts.
allowed-tools: Read Write Edit Glob Grep
metadata:
author: babysitter-sdk
version: "1.0.0"
category: gsd-core
backlog-id: SK-GSD-005
graph:
domains: [domain:software-engineering]
skillAreas: [skill-area:agentic-loops, skill-area:orchestration-loop]
workflows: [workflow:feature-development]
topics: [topic:developer-experience]
roles: [role:tech-lead, role:backend-engineer]
---
status: in-progress
phase: 72
wave: 1
depends_on: []
files_modified: ["src/auth/oauth.ts", "src/auth/tokens.ts"]
created: 2026-03-02
updated: 2026-03-02
---
# Plan content below...
```
## Capabilities
### 1. Parse Frontmatter
Extract frontmatter from a markdown file into structured data:
```yaml
# Input file: .planning/phase-72/PLAN-1.md
---
status: planned
phase: 72
plan_number: 1
wave: 1
depends_on: []
files_modified:
- src/auth/oauth.ts
- src/auth/tokens.ts
- src/middleware/auth.ts
task_count: 4
created: 2026-03-02
gap_closure: false
---
```
Parsed result:
```json
{
"status": "planned",
"phase": 72,
"plan_number": 1,
"wave": 1,
"depends_on": [],
"files_modified": ["src/auth/oauth.ts", "src/auth/tokens.ts", "src/middleware/auth.ts"],
"task_count": 4,
"created": "2026-03-02",
"gap_closure": false
}
```
### 2. Extract Specific Fields
Read individual fields without parsing the entire frontmatter:
```
get_field(.planning/phase-72/PLAN-1.md, "wave") -> 1
get_field(.planning/phase-72/PLAN-1.md, "status") -> "planned"
get_field(.planning/phase-72/PLAN-1.md, "files_modified") -> ["src/auth/oauth.ts", ...]
```
### 3. Update Fields
Update individual frontmatter fields without modifying body content:
```
update_field(.planning/phase-72/PLAN-1.md, "status", "executed")
update_field(.planning/phase-72/PLAN-1.md, "wave", 2)
update_field(.planning/phase-72/PLAN-1.md, "updated", "2026-03-02")
```
Uses `Edit` tool to surgically replace only the target field line.
### 4. Add New Fields
Add fields to existing frontmatter:
```
add_field(.planning/phase-72/PLAN-1.md, "executed_at", "2026-03-02T14:30:00Z")
add_field(.planning/phase-72/PLAN-1.md, "executor_agent", "gsd-executor")
```
Inserts new field before the closing `---` delimiter.
### 5. Remove Fields
Remove fields from frontmatter:
```
remove_field(.planning/phase-72/PLAN-1.md, "gap_closure")
```
### 6. Query Across Files
Find documents matching frontmatter criteria:
```
query(directory: ".planning/phase-72/", field: "wave", value: 1)
-> [".planning/phase-72/PLAN-1.md", ".planning/phase-72/PLAN-2.md"]
query(directory: ".planning/", field: "status", value: "planned", recursive: true)
-> [".planning/phase-72/PLAN-1.md", ".planning/phase-73/PLAN-1.md"]
```
Uses `Grep` to search for field patterns, then validates matches.
### 7. Validate Frontmatter
Validate frontmatter against document type schema:
```yaml
# PLAN.md required fields
required:
- status # planned|executing|executed|verified
- phase # integer or decimal
- plan_number # integer
- wave # integer (execution order group)
- task_count # integer
# PLAN.md optional fields
optional:
- depends_on # array of plan references
- files_modified # array of file paths
- gap_closure # boolean
- created # date
- updated # date
- executed_at # datetime
```
Document type schemas:
- **PLAN.md**: status, phase, plan_number, wave, task_count
- **SUMMARY.md**: phase, status, tasks_completed, commits
- **RESEARCH.md**: phase, status, approach_count, recommended
- **STATE.md**: last_updated, session_count, current_milestone
- **CONTEXT.md**: phase, decisions_count, preferences
### 8. Batch Operations
Update frontmatter across multiple files:
```
batch_update(
files: [".planning/phase-72/PLAN-1.md", ".planning/phase-72/PLAN-2.md"],
field: "status",
value: "executed"
)
```
## Tool Use Instructions
### Parsing Frontmatter
1. Use `Read` to load the target file
2. Extract content between first `---` and second `---`
3. Parse YAML content into key-value pairs
4. Return structured object
### Updating a Field
1. Use `Read` to load the file
2. Locate the target field line within frontmatter
3. Use `Edit` with the exact field line as `old_string`
4. Replace with new field value line
5. If field is multi-line (arrays), handle properly
### Querying Across Files
1. Use `Glob` to find candidate files in the target directory
2. Use `Grep` to search for the field pattern (e.g., `^wave: 1$`)
3. For each match, verify it's within frontmatter (not body content)
4. Return list of matching file paths
### Validating Frontmatter
1. Use `Read` to load the file
2. Parse frontmatter
3. Check required fields exist for the document type
4. Validate field types (string, integer, array, boolean, date)
5. Return validation result with any errors
## Process Integration
- `plan-phase.js` - Read/write plan frontmatter (wave, depends_on, files_modified)
- `execute-phase.js` - Update plan status as execution progresses, read wave assignments for parallel execution
- `audit-milestone.js` - Query all plans by status for completion checks
- `research-phase.js` - Write research frontmatter (approach_count, recommended)
- `discuss-phase.js` - Read phase metadata from roadmap sections
## Output Format
```json
{
"operation": "parse|get|update|add|remove|query|validate|batch",
"status": "success|error",
"file": ".planning/phase-72/PLAN-1.md",
"field": "status",
"previousValue": "planned",
"newValue": "executed",
"frontmatter": {},
"queryResults": [],
"validation": {
"valid": true,
"errors": [],
"warnings": []
}
}
```
## Configuration
| Setting | Default | Description |
|---------|---------|-------------|
| `frontmatterDelimiter` | `---` | YAML frontmatter delimiter |
| `strictValidation` | `false` | Fail on unknown fields |
| `autoUpdateTimestamp` | `true` | Auto-update `updated` field on writes |
## Error Handling
| Error | Cause | Resolution |
|-------|-------|------------|
| `No frontmatter found` | File missing `---` delimiters | Add frontmatter block or skip |
| `YAML parse error` | Malformed YAML in frontmatter | Fix YAML syntax (check indentation, colons, quotes) |
| `Field not found` | Requested field not in frontmatter | Return null, optionally add field |
| `Type mismatch` | Field value does not match expected type | Coerce if possible, error if not |
| `Edit collision` | Field line not unique in file | Include surrounding context for uniqueness |
## Constraints
- Frontmatter must be valid YAML between `---` delimiters at the top of the file
- Field updates must not modify body content below the frontmatter
- Array fields must use YAML list syntax (either inline `[a, b]` or block `- a\n- b`)
- Date fields must use ISO 8601 format
- Boolean fields must use `true`/`false` (not `yes`/`no`)
- Query operations are read-only; they never modify files
- Batch operations are atomic per file (each file update succeeds or fails independently)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |