agentsmd

Documentation

Overview

Package agentsmd splits an AGENTS.md file into one markdown file per section so the existing directives pipeline can index and inject them.

The split is deliberately shallow: AGENTS.md is cut at level-2 headings (`## `). Everything before the first `## ` — typically the `# Title` and an intro paragraph — becomes a "preamble" section. Deeper headings (`###` and below) stay inside their parent H2 section; the downstream RAG chunker (pkg/rag) is what breaks a large section into retrievable chunks, so there is no need to over-fragment here.

The package is pure: Split takes a string and returns sections, with no file I/O. The handler layer (internal/handlers) is responsible for writing the sections to disk. This keeps the section logic trivially unit-testable.

Index

• Constants
• func FileName(idx int, s Section) string
• type Section
  • func Split(content string) []Section

Constants

const FilePrefix = "agents-"

FilePrefix is the reserved filename prefix for every section file generated from AGENTS.md. Files under the directives directory whose names start with this prefix are owned by pk: they are (re)written and pruned on every sync. User-authored directives must not use this prefix.

Functions

func FileName

func FileName(idx int, s Section) string

FileName returns the deterministic directives filename for the section at position idx (0-based) in Split's output. The 1-based, zero-padded index keeps files ordered and unique even when two sections share a slug.

Types

type Section

type Section struct {
	// Title is the heading text (without the leading `## `). For the preamble
	// it is the H1 title if present, otherwise "overview".
	Title string
	// Body is the raw markdown of the section, including its heading line for
	// H2 sections. It always ends with exactly one trailing newline.
	Body string
	// Preamble is true for the synthetic section holding everything before the
	// first `## ` heading.
	Preamble bool
}

Section is one slice of AGENTS.md: a heading (or the synthetic preamble title) plus the raw markdown body that belongs under it.

func Split

func Split(content string) []Section

Split cuts content at level-2 headings and returns the resulting sections in document order. A preamble section (everything before the first `## `) is emitted first when it contains non-whitespace text. Sections whose body is blank are dropped. Returns nil when content has no usable text.