AST Skill

Version: 1.1.0
Framework: Jerry Framework v0.9.0
Layer: CLI adapter (single entry point to domain layer)

---

Document Sections

Section	Purpose
Overview	What this skill does and why
When to Use This Skill	Triggers and use cases
Operations Reference	All available CLI commands
Quick Reference	Copy-paste examples for common tasks
Routing Disambiguation	When this skill is the wrong choice
Constitutional Compliance	Principle mapping with consequences
Architecture Notes	Layer compliance and design

---

Overview

The AST skill provides structured markdown operations for Claude agents working
within the Jerry Framework. All operations are exposed via the jerry ast CLI
namespace, which is the single adapter between agents and the
src.domain.markdown_ast domain layer.

Core Capabilities

• Parse: Tokenize a markdown file and return AST structure as JSON.
• Frontmatter: Extract > **Key:** Value fields as a JSON object.
• Modify: Change a frontmatter field value and write back to disk.
• Validate: Check nav table compliance (H-23/H-24) and entity schema validation.
• Render: Normalize markdown via mdformat.
• Reinject: Extract all L2-REINJECT directives as a JSON list.
• Query: Query AST nodes by type.

---

When to Use This Skill

Invoke /ast when you need to:

• Read frontmatter fields from a Jerry entity file (story, task, enabler, bug).
• Modify a single frontmatter field without disturbing the rest of the file.
• Validate that a markdown file complies with H-23 (nav table required) and H-24 (anchor links).
• Extract L2-REINJECT directives to inspect or audit the re-injection payload.
• Normalize markdown formatting before writing or diffing files.

NEVER invoke this skill when:

• Reading raw file content without structural parsing -- Consequence: AST parsing overhead applied to simple file reads wastes CLI invocation cost; JSON output format adds unnecessary complexity for content retrieval; use Read tool directly
• Writing arbitrary content to files -- Consequence: AST modify is scoped to frontmatter field updates only; arbitrary content writes fail or produce incorrect results; use Write/Edit tools directly

See Routing Disambiguation for full exclusion conditions with consequences.

---

Operations Reference

All operations are invoked via jerry ast <command>. In agent context, use the
--directory prefix:

uv run --directory ${CLAUDE_PLUGIN_ROOT} jerry ast <command> [args]

jerry ast parse

jerry ast parse <file>

Parse a markdown file and output the full AST as JSON (tokens + tree).

Exit codes: 0 success, 2 file error.

---

jerry ast frontmatter

jerry ast frontmatter <file>

Extract all blockquote frontmatter fields as a JSON object.

Output: {"Type": "story", "Status": "pending", ...} or {} if no frontmatter.

Exit codes: 0 success, 2 file error.

---

jerry ast modify

jerry ast modify <file> --key <KEY> --value <VALUE>

Modify one frontmatter field and write the updated content back to disk.

Output: {"file": "...", "key": "...", "value": "...", "status": "modified"}

Exit codes: 0 success, 1 key not found, 2 file error.

---

jerry ast validate

jerry ast validate <file> [--schema <type>] [--nav]

Validate file structure against H-23/H-24 nav table rules and optionally
against an entity schema.

Without --schema: Returns JSON with nav table validation results.

With --schema <type>: Validates against entity schema (epic, feature,
story, enabler, task, bug). Returns JSON with both nav table and schema results.

With --nav: Includes detailed nav table entries in the output
(section_name, anchor, description, line_number).

Output JSON keys:

Key	Type	Description
is_valid	bool	True only when nav and schema are both valid
nav_table_valid	bool	True if nav table exists and covers all ## headings
missing_nav_entries	list	Heading texts absent from nav table
orphaned_nav_entries	list	Nav entries with no matching heading
schema_valid	bool	True when schema passes or no schema provided
schema_violations	list	Violation dicts (with --schema only)
nav_entries	list	Detailed entries (with --nav only)

Exit codes: 0 success, 1 validation failure, 2 file/schema error.

---

jerry ast render

jerry ast render <file>

Parse a file and output normalized (mdformat) markdown to stdout.

Exit codes: 0 success, 2 file error.

---

jerry ast reinject

jerry ast reinject <file>

Extract all L2-REINJECT directives from a markdown file as a JSON list.

Output: List of dicts with rank, tokens, content, line_number.

Exit codes: 0 success, 2 file error.

---

jerry ast query

jerry ast query <file> <selector>

Query AST nodes by type (e.g., heading, blockquote, paragraph).

Output: {"selector": "...", "count": N, "nodes": [...]}

Exit codes: 0 success, 2 file error.

---

Quick Reference

Read frontmatter from a story file

uv run jerry ast frontmatter projects/PROJ-005-markdown-ast/work/EPIC-001-markdown-ast/FEAT-001-ast-strategy/ST-005-ast-skill/ST-005-ast-skill.md

Update story status

uv run jerry ast modify projects/PROJ-005-markdown-ast/work/EPIC-001-markdown-ast/FEAT-001-ast-strategy/ST-005-ast-skill/ST-005-ast-skill.md --key Status --value in-progress

Validate a rule file for H-23/H-24 compliance

uv run jerry ast validate --nav .context/rules/quality-enforcement.md

Extract L2-REINJECT directives from a rule file

uv run jerry ast reinject .context/rules/quality-enforcement.md

Parse a file and inspect its structure

uv run jerry ast parse .context/rules/quality-enforcement.md

Validate an entity file against a schema

uv run jerry ast validate --schema story projects/PROJ-005-markdown-ast/work/EPIC-001-markdown-ast/FEAT-001-ast-strategy/ST-005-ast-skill/ST-005-ast-skill.md

---

Routing Disambiguation

When this skill is the wrong choice and what happens if misrouted.

Condition	Use Instead	Consequence of Misrouting
Reading raw file content without structural parsing	Read tool directly	AST parsing overhead applied to simple file reads wastes CLI invocation cost; JSON output format adds unnecessary complexity for content retrieval
Writing arbitrary content to files	Write/Edit tools directly	AST modify is scoped to frontmatter field updates only; arbitrary content writes require direct file tools
General text processing on non-entity markdown	Read/Write/Edit tools directly	AST validation schema applied to non-entity markdown produces false-positive structural errors; entity schema enforcement rejects valid non-worktracker files
Research, analysis, or investigation tasks	/problem-solving	AST provides structural parsing only; no analytical methodology, no research capability, no root cause investigation
Validating content quality or adversarial review	/adversary	AST validates structural compliance (H-23/H-24 nav tables, entity schemas), not content quality; no S-014 scoring rubric

---

Constitutional Compliance

All operations adhere to the Jerry Constitution v1.0:

Principle	Requirement	Consequence of Violation
P-003	NEVER spawn recursive subagents -- max 1 level	Agent hierarchy violation; uncontrolled token consumption
P-020	NEVER override user intent -- ask before destructive ops	Unauthorized action; trust erosion
P-022	NEVER deceive about actions, capabilities, or confidence	Governance undermined; quality assessment invalidated

---

Architecture Notes

Single CLI Adapter

The jerry ast CLI namespace (src/interface/cli/ast_commands.py) is the
single adapter between agents and the domain layer. There is no separate
skill script — the CLI is the adapter:

jerry ast <command>                 <- CLI (interface layer)
    -> src.domain.markdown_ast     <- domain layer

The domain layer (src/domain/markdown_ast/) does NOT import back into the
interface layer (H-07 enforced by architecture boundary tests).

References

Topic	Location
Domain layer exports	src/domain/markdown_ast/__init__.py
CLI commands	src/interface/cli/ast_commands.py
CLI parser	src/interface/cli/parser.py
Unit tests	tests/unit/interface/cli/test_ast_commands.py
Integration tests	tests/integration/cli/test_ast_subprocess.py
H-23/H-24 rules	.context/rules/markdown-navigation-standards.md
Quality enforcement	.context/rules/quality-enforcement.md