fledgling

Category: Docs & Knowledge | Uploader: teaguesterling | Downloads: 0 | Version: v1.0（Latest）

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).

Changelog: Source: GitHub https://github.com/teaguesterling/fledgling

Directory Structure

Current level: Root

📁 .lq/
- 📄 commands.toml 933 B
- 📄 config.toml 559 B
📁 bin/
- 📄 fledgling 7.9 KB
📁 config/
- 📄 claude-code.example.json 226 B
📁 docs/
- 📁 blog/
  - 📄 actor-taxonomy.md 22.8 KB
  - 📄 blog-series-intro.md 6.1 KB
  - 📄 conversations-as-closures.md 20.3 KB
  - 📄 formal-framework.md 35.1 KB
  - 📄 ma-critique.md 8.2 KB
  - 📄 primer-kleisli-graded-pi.md 15.1 KB
  - 📄 scope-transitions.md 9.5 KB
  - 📄 turn-anatomy.md 15.5 KB
- 📁 macros/
  - 📄 code.md 1.9 KB
  - 📄 conversations.md 2.4 KB
  - 📄 docs.md 2.2 KB
  - 📄 repo.md 2.1 KB
  - 📄 source.md 2.5 KB
- 📁 planning/
  - 📄 NEXT_STEPS.md 6.5 KB
- 📁 tasks/
  - 📄 P2-001-files-tools.md 4.4 KB
  - 📄 P2-002-code-tools.md 2.4 KB
  - 📄 P2-003-docs-tools.md 1.8 KB
  - 📄 P2-004-git-tools.md 2.0 KB
  - 📄 P2-005-init-and-config.md 7.3 KB
  - 📄 P2-006-fledgling-mvp.md 6.8 KB
  - 📄 P2-007-profile-integration.md 3.2 KB
  - 📄 P2-009-mcp-path-resolution.md 6.9 KB
  - 📄 P3-001-git-diff.md 3.9 KB
  - 📄 P3-002-git-status.md 3.1 KB
  - 📄 P3-003-git-show.md 2.2 KB
  - 📄 P3-004-git-tags.md 1.6 KB
  - 📄 P3-005-project-overview.md 2.9 KB
  - 📄 P3-006-packaging.md 3.0 KB
  - 📄 P3-007-claude-conversations.md 3.2 KB
  - 📄 P3-008-validation.md 1.8 KB
  - 📄 P3-009-structural-diff.md 8.0 KB
- 📁 vision/
  - 📄 CONVERSATION_ANALYSIS.md 6.7 KB
  - 📄 CONVERSATION_SCHEMA_DESIGN.md 13.9 KB
  - 📄 PRODUCT_SPEC.md 16.8 KB
- 📄 getting-started.md 1.7 KB
- 📄 index.md 2.3 KB
- 📄 product-thinking.md 4.0 KB
- 📄 quartermaster-pattern.md 3.4 KB
📁 init/
- 📄 init-fledgling-analyst.sql 1.3 KB
- 📄 init-fledgling-base.sql 2.0 KB
- 📄 init-fledgling-core.sql 1.3 KB
- 📄 init-fledgling.sql 547 B
📁 scripts/
- 📄 call_tool.py 1.9 KB
📁 sql/
- 📁 profiles/
  - 📄 analyst.sql 472 B
  - 📄 core.sql 920 B
- 📁 tools/
  - 📄 code.sql 1.6 KB
  - 📄 conversations.sql 4.9 KB
  - 📄 docs.sql 940 B
  - 📄 files.sql 1.6 KB
  - 📄 git.sql 1.8 KB
  - 📄 help.sql 619 B
- 📄 code.sql 6.3 KB
- 📄 conversations.sql 17.3 KB
- 📄 docs.sql 3.1 KB
- 📄 dr_fledgling.sql 1.3 KB
- 📄 help.sql 1.5 KB
- 📄 install-fledgling.sql 11.2 KB
- 📄 repo.sql 5.4 KB
- 📄 sandbox.sql 2.7 KB
- 📄 source.sql 6.5 KB
- 📄 structural.sql 4.6 KB
📁 tests/
- 📁 data/
  - 📁 validation-prompts/
    
    📄 01-files.md 2.8 KB
    
    📄 02-code.md 2.5 KB
    
    📄 03-docs.md 1.7 KB
    
    📄 04-git.md 894 B
    
    📄 05-conversations.md 2.2 KB
    
    📄 06-help.md 1.0 KB
    
    📄 07-analyst.md 1.8 KB
    
    📄 08-integration.md 3.7 KB
    
    📄 README.md 1.2 KB
- 📄 conftest.py 19.0 KB
- 📄 test_code.py 7.1 KB
- 📄 test_conversations.py 14.3 KB
- 📄 test_docs.py 5.4 KB
- 📄 test_dr_fledgling.py 1.7 KB
- 📄 test_help.py 4.3 KB
- 📄 test_installer.py 10.1 KB
- 📄 test_mcp_server.py 12.7 KB
- 📄 test_profiles.py 5.2 KB
- 📄 test_repo.py 10.4 KB
- 📄 test_sandbox.py 6.2 KB
- 📄 test_source.py 6.4 KB
- 📄 test_structural.py 4.8 KB
📄 .gitignore 120 B
📄 .mcp.json 361 B
📄 .readthedocs.yaml 196 B
📄 CLAUDE.md 13.0 KB
📄 LICENSE 11.0 KB
📄 mkdocs.yml 1.4 KB
📄 NOTICE 566 B
📄 pyproject.toml 1.2 KB
📄 README.md 5.7 KB
📄 SKILL.md 11.6 KB

SKILL.md

# 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` |
| **CodeStructure** | Top-level overview: what's defined in each file | `file_pattern` |
| **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` |

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

```sql
-- 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

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

### Understand a Function

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

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

### 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)` |
| `code_structure` | `(file_pattern)` |
| `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 := '.')` |

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

### Token Efficiency

- Use `CodeStructure` first to understand what's in a file before reading it
- Use `FindDefinitions` with `name_pattern` to narrow results
- Use `ReadLines` with `lines` and `match` to read only what you need
- Use `doc_outline()` via query before `MDSection` to find the right section

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

fledgling

Directory Structure

SKILL.md

Report

Notice