teaguesterling/fledgling

Fledgling Skill Guide

Fledgling gives you structured, token-efficient access to the codebase you're working in. Instead of reading raw files and guessing at structure, you get targeted tools backed by SQL macros and real parsers (AST for code, markdown parser for docs, git for history).

Quick Reference

Tools

| Tool | Purpose | Key params | |------|---------|------------| | ReadLines | Read file content with line ranges, context, and match filtering | file_path, lines, match, commit | | FindDefinitions | AST-based search for functions, classes, variables | file_pattern, name_pattern | | FindCode | CSS selector search: .func, #name, :has(...), ::callers | file_pattern, selector | | ViewCode | View source matched by CSS selector with context lines | file_pattern, selector, context | | SelectCode | Render selector matches as markdown: file:range headings + full source blocks | source, selector | | CodeStructure | Top-level overview: what's defined in each file | file_pattern | | ExploreProject | First-contact briefing: languages, structure, docs, recent activity | root, code_pattern, doc_pattern | | InvestigateSymbol | Deep dive: definitions, callers, call sites for a symbol | name, file_pattern | | ReviewChanges | Change review: files and functions ranked by complexity | from_rev, to_rev, file_pattern | | SearchProject | Multi-source search across definitions, calls, and docs | pattern, file_pattern | | MDOverview | Browse all docs with keyword/regex search | file_pattern, search | | MDSection | Read a markdown section by ID | file_path, section_id | | GitDiffSummary | File-level change summary between revisions | from_rev, to_rev | | GitShow | File content at a specific git revision | file, rev | | Help | This guide (no args = outline, section_id = details) | section | | ChatSessions | Browse conversation sessions | project, days, limit | | ChatSearch | Search across conversation messages | query, role | | ChatToolUsage | Tool usage frequency | project, days | | ChatDetail | Deep view of a single session | session_id | | SearchContent | BM25 full-text search over docs + code (requires rebuild first) | query, kind, extractor, limit | | SearchDocs | BM25 search over markdown sections | query, limit | | SearchCode | BM25 search over code (definition/comment/string) | query, kind, limit | | FtsStats | Diagnostic: counts per extractor/kind in the FTS index | — |

Query-Only Macros

These macros are available via the query tool. They provide the full power of Fledgling's SQL composability — you can join, filter, and aggregate across them.

| Macro | Purpose | Example | |-------|---------|---------| | list_files(pattern) | Find files by glob | SELECT * FROM list_files('src/**/*.py') | | project_overview(root) | File counts by language | SELECT * FROM project_overview('.') | | read_as_table(path, limit) | Preview CSV/JSON/Parquet as table | SELECT * FROM read_as_table('data.csv') | | find_calls(pattern, name) | Find function call sites | SELECT * FROM find_calls('src/**/*.py', 'connect') | | find_imports(pattern) | Find import statements | SELECT * FROM find_imports('src/**/*.py') | | complexity_hotspots(pattern, n) | Functions ranked by cyclomatic complexity | SELECT * FROM complexity_hotspots('src/**/*.py', 10) | | function_callers(pattern, name) | Who calls a function? | SELECT * FROM function_callers('src/**/*.py', 'validate') | | module_dependencies(pattern, pkg) | Internal import graph with fan-in | SELECT * FROM module_dependencies('src/**/*.py', 'myapp') | | doc_outline(pattern, max_level) | Markdown table of contents | SELECT * FROM doc_outline('docs/**/*.md') | | recent_changes(n, repo) | Commit history | SELECT * FROM recent_changes(10) | | branch_list(repo) | List branches | SELECT * FROM branch_list() | | tag_list(repo) | List tags | SELECT * FROM tag_list() | | file_changes(from, to, repo) | Files changed between revisions | SELECT * FROM file_changes('HEAD~3', 'HEAD') | | file_diff(file, from, to, repo) | Line-level unified diff | SELECT * FROM file_diff('src/main.py', 'HEAD~1', 'HEAD') | | working_tree_status(repo) | Untracked/deleted files | SELECT * FROM working_tree_status() | | structural_diff(file, from, to) | Semantic diff: added/removed/modified definitions | SELECT * FROM structural_diff('src/main.py', 'HEAD~1', 'HEAD') | | changed_function_summary(from, to, pattern) | Functions in changed files, ranked by cyclomatic complexity | SELECT * FROM changed_function_summary('HEAD~5', 'HEAD', 'src/**/*.py') |

Tools

ReadLines

Read file content with precision. Replaces cat/head/tail with structured output.

Returns: line_number, content

ReadLines(file_path="src/main.py")                    # whole file
ReadLines(file_path="src/main.py", lines="10-25")     # line range
ReadLines(file_path="src/main.py", lines="42", ctx="5")  # line 42 +/- 5 lines
ReadLines(file_path="src/main.py", match="import")    # only matching lines
ReadLines(file_path="src/main.py", lines="1-50", match="def")  # combined
ReadLines(file_path="src/main.py", commit="HEAD~1")   # previous version

FindDefinitions

Find where things are defined: functions, classes, methods, variables. AST-based, not text matching.

Returns: file_path, name, kind, start_line, end_line, signature

FindDefinitions(file_pattern="src/**/*.py")                # all definitions
FindDefinitions(file_pattern="src/**/*.py", name_pattern="parse%")  # names starting with "parse"
FindDefinitions(file_pattern="lib/*.ts", name_pattern="%Handler")   # names ending with "Handler"

The name_pattern uses SQL LIKE wildcards: % matches any sequence, _ matches one character.

CodeStructure

High-level overview of what's defined in files, with line counts. Good first step to understand unfamiliar code.

Returns: file_path, name, kind, start_line, end_line, line_count

CodeStructure(file_pattern="src/**/*.py")
CodeStructure(file_pattern="lib/auth.ts")

MDSection

Read a specific markdown section by ID. Use doc_outline() via the query tool to discover section IDs first.

Returns: section_id, title, level, content, start_line, end_line

MDSection(file_path="docs/guide.md", section_id="installation")
MDSection(file_path="README.md", section_id="getting-started")

GitDiffSummary

File-level summary of changes between two git revisions. For function-level analysis, use structural_diff() or changed_function_summary() via the query tool.

Returns: file_path, status, old_size, new_size

GitDiffSummary(from_rev="HEAD~1", to_rev="HEAD")
GitDiffSummary(from_rev="main", to_rev="feature-branch")

GitShow

Show file content at a specific git revision. Replaces git show rev:path.

Returns: file_path, ref, size_bytes, content

GitShow(file="README.md", rev="HEAD~1")
GitShow(file="sql/repo.sql", rev="main")

Help

This guide. Call with no args to see the section outline, or pass a section ID for details.

Help()                              # outline
Help(section="workflows")           # specific section

Code Intelligence

All code tools use AST parsing (via sitting_duck), not text matching. They work across 30 languages including Python, JavaScript, TypeScript, Rust, Go, Java, C/C++, Ruby, and more.

Use ast_supported_languages() via the query tool for the live list.

Composing Macros

The real power of Fledgling is composing macros via the query tool. Examples:

-- Complex functions in recently changed files
SELECT h.file_path, h.name, h.cyclomatic, h.lines
FROM complexity_hotspots('src/**/*.py') h
WHERE h.file_path IN (
    SELECT file_path FROM changed_function_summary('main', 'HEAD', 'src/**/*.py')
);

-- Module dependency fan-in (what's the most-imported module?)
SELECT target_module, fan_in
FROM module_dependencies('src/**/*.py', 'myapp')
ORDER BY fan_in DESC;

-- Functions over 20 lines with high complexity
SELECT file_path, name, cyclomatic, lines
FROM complexity_hotspots('src/**/*.py', 100)
WHERE cyclomatic > 10 AND lines > 20;

Workflows

Explore an Unfamiliar Codebase

Quick (one call): ExploreProject() — returns languages, top-complexity definitions, doc outline, and recent git activity in one structured result.

Detailed (step-by-step):

1. CodeStructure(file_pattern="src/**/*.py") — see what's defined where
2. ReadLines(file_path="src/main.py") — read key files
3. MDOverview(file_pattern="*.md") — find docs
4. MDSection(file_path="README.md", section_id="...") — read relevant docs

Understand a Function

Quick (one call): InvestigateSymbol(name="my_func") — returns definitions, callers, and call sites in one result.

Detailed (step-by-step):

1. FindDefinitions(file_pattern="src/**/*.py", name_pattern="my_func%") — find it
2. ReadLines(file_path="src/module.py", lines="42-80") — read implementation
3. Use query tool: SELECT * FROM function_callers('src/**/*.py', 'my_func') — who calls it?

Review Recent Changes

Quick (one call): ReviewChanges(from_rev="HEAD~3", to_rev="HEAD") — returns changed files and functions ranked by complexity.

Detailed (step-by-step):

1. GitDiffSummary(from_rev="HEAD~3", to_rev="HEAD") — which files changed
2. Use query tool: SELECT * FROM changed_function_summary('HEAD~3', 'HEAD', 'src/**/*.py') — what functions are affected
3. Use query tool: SELECT * FROM complexity_hotspots('src/**/*.py', 10) — what's risky
4. ReadLines(file_path="src/changed.py", lines="42-80") — read the changes

Search Across Sources

Quick (one call): SearchProject(pattern="parse%") — searches definitions, call sites, and docs simultaneously.

View Code by Selector

Use CSS selectors to find and view code structurally:

FindCode(file_pattern="src/**/*.py", selector=".func#validate")
ViewCode(file_pattern="src/**/*.py", selector=".func:has(.call#execute)")
SelectCode(source="src/**/*.py", selector=".class > .func")

Selector syntax: .func, .class, .call, .import, #name, :has(child), :not(...), ::callers, ::callees, A > B (direct child), A ~ B (sibling).

Analyze Architecture

1. Use query tool: SELECT * FROM module_dependencies('src/**/*.py', 'myapp') — import graph
2. CodeStructure(file_pattern="src/core/*.py") — core module structure
3. Use query tool: SELECT * FROM complexity_hotspots('src/**/*.py', 20) — complexity hotspots

Macro Reference

All macros are available via the query tool.

Files

| Macro | Signature | |-------|-----------| | list_files | (pattern, commit := NULL) | | read_source | (file_path, lines := NULL, ctx := 0, match := NULL) | | read_source_batch | (file_pattern, lines := NULL, ctx := 0) | | read_context | (file_path, center_line, ctx := 5) | | file_line_count | (file_pattern) | | project_overview | (root := '.') | | read_as_table | (file_path, lim := 100) |

Code

| Macro | Signature | |-------|-----------| | find_definitions | (file_pattern, name_pattern := '%') | | find_calls | (file_pattern, name_pattern := '%') | | find_imports | (file_pattern) | | find_code | (file_pattern, selector, lang := NULL) | | find_code_grep | (file_pattern, selector, lang := NULL) | | view_code | (file_pattern, selector, lang := NULL, ctx := 0) | | view_code_text | (file_pattern, selector, lang := NULL, ctx := 0) | | code_structure | (file_pattern) | | find_class_members | (file_path, class_node_id) | | complexity_hotspots | (file_pattern, n := 20) | | function_callers | (file_pattern, func_name) | | module_dependencies | (file_pattern, package_prefix) |

Structural Analysis

| Macro | Signature | |-------|-----------| | structural_diff | (file, from_rev, to_rev, repo := '.') | | changed_function_summary | (from_rev, to_rev, file_pattern, repo := '.') |

Workflows

| Macro | Signature | |-------|-----------| | explore_query | (root := '.', code_pattern := '**/*.py', doc_pattern := 'docs/**/*.md', top_n := 20, recent_n := 10) | | investigate_query | (name, file_pattern := '**/*.py') | | review_query | (from_rev := 'HEAD~1', to_rev := 'HEAD', file_pattern := '**/*.py', repo := '.', top_n := 20) | | search_query | (pattern, file_pattern := '**/*.py', doc_pattern := 'docs/**/*.md', top_n := 50) | | pss_render | (source, selector) | | ast_select_render | (source, selector) |

Docs

| Macro | Signature | |-------|-----------| | doc_outline | (file_pattern, max_lvl := 3) | | read_doc_section | (file_path, target_id) | | find_code_examples | (file_pattern, lang := NULL) | | doc_stats | (file_pattern) |

Git

| Macro | Signature | |-------|-----------| | recent_changes | (n := 10, repo := '.') | | branch_list | (repo := '.') | | tag_list | (repo := '.') | | repo_files | (rev := 'HEAD', repo := '.') | | file_at_version | (file, rev, repo := '.') | | file_changes | (from_rev, to_rev, repo := '.') | | file_diff | (file, from_rev, to_rev, repo := '.') | | working_tree_status | (repo := '.') |

Conversations

| Macro | Signature | |-------|-----------| | sessions | () | | messages | () | | content_blocks | () | | tool_calls | () | | tool_results | () | | token_usage | () | | tool_frequency | () | | bash_commands | () | | session_summary | () | | model_usage | () | | search_messages | (search_term) | | search_tool_inputs | (search_term) |

Help

| Macro | Signature | |-------|-----------| | help | (target_id := NULL) |

Tips

Supported Languages

Use ast_supported_languages() via the query tool to check the live list of languages supported by the code intelligence tools.

Glob Patterns

• * matches within a directory: src/*.py
• ** matches across directories: src/**/*.py
• Combine extensions: src/**/*.{py,ts}

Path Handling

• Paths are resolved relative to the project root
• Use absolute paths when outside the project
• Git mode paths are always repo-relative
• The sandbox restricts filesystem access to the project directory; use dedicated tools instead of raw SQL for file operations

Discovering Macro Schemas

Use the describe tool to inspect what columns a macro returns:

describe(query="SELECT * FROM complexity_hotspots('test', 1)")

This reveals column names and types, making it easier to compose macros via joins.

Data File Formats

read_as_table(path) auto-detects format by extension:

| Extension | Reader | Built-in? | |-----------|--------|-----------| | .csv, .tsv | read_csv_auto | Yes | | .json, .jsonl | read_json_auto | Yes | | .parquet, .pq | read_parquet | Yes |

Unsupported extensions fall back to CSV. For other formats, use the query tool with DuckDB's native readers directly (e.g., SELECT * FROM 'data.xlsx' if the spatial extension is installed).

Token Efficiency

• Use CodeStructure first to understand what's in a file before reading it
• Use FindDefinitions with name_pattern to narrow results
• Use FindCode with CSS selectors for targeted structural searches (.call#execute, .import, :has(...))
• Use ReadLines with lines and match to read only what you need
• Use doc_outline() via query before MDSection to find the right section