/frontmatter-parsing

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:

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

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

{
  "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 | | `str