Core Concepts

FlyDocs is built around four core primitives (rules, skills, templates, and hooks) plus two system-level concepts that tie them together: progressive disclosure and the context graph. The primitives define what gets loaded and enforced. Progressive disclosure controls when and how much. The context graph adds cross-session memory.

For the high-level flow of how these concepts interact at runtime, see How It Works.

Rules

Rules are persistent instructions that govern how AI interacts with your codebase. Unlike chat messages that get lost, rules are always present and always enforced.

Rules can be:

• Always applied: Active in every session
• Contextual: Applied based on file patterns or project state
• Role-specific: Different rules for different agent roles

# Example rule: TypeScript strict mode
When writing TypeScript code:
- Use strict mode
- Never use 'any' type
- Prefer 'unknown' with proper narrowing
- All functions must have explicit return types

Skills

Skills are portable knowledge modules that encode methodology, patterns, and integrations. They come in two types. Passive skills are knowledge-only: coding standards, architectural guidance, testing patterns. Active skills add executable scripts: PM integration, issue tracking, status transitions. Both types are discovered through the same compressed manifest and loaded on demand.

Passive skills contain pattern documentation and coding guidance. Active skills add executable scripts that handle operations like issue creation, status transitions, and PM integration, all invoked deterministically.

Templates

Templates define the structure for issue specs. They ensure every feature, bug, or chore has the right information for AI to work effectively.

Templates include:

• Required sections (acceptance criteria, context, etc.)
• Default labels and assignments
• Estimation guidelines
• Validation rules

# Feature Template
## Context
[Why this feature is needed]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Technical Notes
[Implementation guidance]

Hooks

Hooks are platform-triggered scripts that fire automatically on specific events. Unlike instructions in a rules file (which are advisory), hooks run every time, guaranteed. They are the difference between a code style guide and a pre-commit hook.

FlyDocs uses four hooks:

• Context injection: Injects git state, active issue, and context graph output before every prompt
• Script approval: Approves FlyDocs skill scripts without manual confirmation
• Script preference: Redirects the AI toward deterministic skill scripts when MCP tools are also available
• Post-edit formatting: Auto-formats code and logs changes after every file edit

How They Work Together

Three layers serve three purposes:

1. Skills define how to do things right: passive skills provide methodology and patterns, active skills handle tool integration with deterministic scripts
2. Rules guide AI behavior with project-specific preferences and conventions
3. Hooks enforce guardrails the AI cannot skip: formatting, context injection, script approval
4. Templates ensure every issue spec has the structure AI needs to implement correctly

Progressive disclosure controls how much loads at any given time. A compressed manifest is always present, skill overviews load on demand, and section detail loads only when needed. The context graph connects skills, decisions, issues, and session history so the AI understands relationships, not just individual documents.

For a walkthrough of the runtime flow, see How It Works.

Questions about core concepts? Reach out at hello@flydocs.ai.