Babysitter frontmatter-parsing

YAML frontmatter parsing and manipulation for .planning/ documents. Provides read, write, update, query, and validation operations on frontmatter blocks in GSD markdown artifacts.

install

source · Clone the upstream repo

git clone https://github.com/a5c-ai/babysitter

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/a5c-ai/babysitter "$T" && mkdir -p ~/.claude/skills && cp -r "$T/library/methodologies/gsd/skills/frontmatter-parsing" ~/.claude/skills/a5c-ai-babysitter-frontmatter-parsing && rm -rf "$T"

manifest: library/methodologies/gsd/skills/frontmatter-parsing/SKILL.md

frontmatter-parsing

You are frontmatter-parsing - the skill for all YAML frontmatter operations within GSD artifacts. Every GSD document uses frontmatter for metadata (status, phase, version, wave, depends_on, files_modified, etc.). This skill provides structured access to read, write, update, and query frontmatter blocks.

Overview

GSD documents use YAML frontmatter (delimited by

---

) to store machine-readable metadata alongside human-readable markdown content. This skill corresponds to the original

lib/frontmatter.cjs

module.

Frontmatter appears at the top of every GSD artifact:

---
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:

# 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:

{
  "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:

# 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

Use
```
Read
```
to load the target file
Extract content between first
```
---
```
and second
```
---
```
Parse YAML content into key-value pairs
Return structured object

Updating a Field

Use
```
Read
```
to load the file
Locate the target field line within frontmatter
Use
```
Edit
```
with the exact field line as
```
old_string
```
Replace with new field value line
If field is multi-line (arrays), handle properly

Querying Across Files

Use
```
Glob
```
to find candidate files in the target directory
Use
```
Grep
```
to search for the field pattern (e.g.,
```
^wave: 1$
```
)
For each match, verify it's within frontmatter (not body content)
Return list of matching file paths

Validating Frontmatter

Use
```
Read
```
to load the file
Parse frontmatter
Check required fields exist for the document type
Validate field types (string, integer, array, boolean, date)
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

{
  "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)