# Aidf > Teaches AI agents how to work with AIDF (AI-Integrated Development Framework) projects — structure, task format, scope enforcement, completion signals, and conventions. Use when this capability is needed. - Skill: `tomevault-io/aidf` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/aidf` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/aidf/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/aidf --- # AIDF — AI-Integrated Development Framework This skill teaches you how to work within an AIDF-managed project. AIDF provides structured, layered context so AI assistants produce consistent, scoped, high-quality work. ## Project Structure AIDF projects contain a `.ai/` directory at the project root: ``` .ai/ ├── AGENTS.md # Layer 1: Project identity, architecture, conventions, boundaries ├── config.yml # Framework configuration (provider, validation, permissions) ├── ROLES.md # Quick reference for available roles ├── roles/ # Layer 2: Role definitions (developer, architect, tester, etc.) │ ├── developer.md │ ├── architect.md │ ├── tester.md │ ├── reviewer.md │ └── documenter.md ├── skills/ # Layer 3: Portable skill definitions (SKILL.md per agentskills.io) ├── tasks/ # Layer 4: Scoped task specifications │ ├── pending/ # Tasks waiting to be executed │ ├── completed/ # Successfully completed tasks │ └── blocked/ # Tasks that need human input ├── plans/ # Layer 5: Multi-task initiatives └── templates/ # Task and plan templates ``` ## Context Layers AIDF uses 5 layers of context that combine to form precise execution instructions: 1. **AGENTS.md** (Global) — Project overview, architecture, conventions, quality gates, boundaries 2. **Roles** (Expertise) — Specialized AI personas with defined responsibilities and constraints 3. **Skills** (Capabilities) — Portable, composable instructions following agentskills.io standard 4. **Tasks** (Scope) — Exact scope (allowed/forbidden files), requirements, definition of done 5. **Plans** (Coordination) — Multi-task initiatives with sequencing and dependencies **How they combine:** Project conventions (Layer 1) + role expertise (Layer 2) + skill context (Layer 3) + task scope (Layer 4) = precise execution instructions. ## Task File Format Task files are Markdown documents with specific sections. Here is the expected structure: ```markdown # Task: [Short descriptive title] ## Goal [Clear statement of what needs to be accomplished] ## Task Type [component | refactor | test | docs | architecture | bugfix] ## Suggested Roles - [role-name] ## Scope ### Allowed - `src/components/**` - `src/utils/helpers.ts` ### Forbidden - `src/config/**` - `.env*` ### Ask Before - `package.json` ## Requirements [Detailed requirements for the task] ## Definition of Done - [ ] [Criterion 1] - [ ] [Criterion 2] - [ ] [Criterion 3] ## Notes [Optional additional context] ``` ### Key Rules for Tasks - **Scope enforcement**: Only modify files listed under `### Allowed`. Never touch files under `### Forbidden`. Ask the user before modifying files under `### Ask Before`. - **Definition of Done**: Every checkbox must be satisfied before marking the task complete. - **Task Type**: Determines the approach — `component` (new feature), `refactor` (restructure), `test` (add tests), `docs` (documentation), `architecture` (design), `bugfix` (fix issue). ## Scope Enforcement AIDF enforces three scope modes: | Mode | Behavior | |------|----------| | `strict` | Block all changes outside allowed paths. Task fails on violation. | | `ask` | Prompt the user before any out-of-scope change. | | `permissive` | Allow with warnings. | **When working on a task, always check the scope before modifying any file.** ## Completion Signals When a task is complete, signal it with one of these markers in your output: - `` — Primary completion signal - `` — Alternative completion signal The executor detects these signals and marks the task as completed. If you cannot complete a task, signal it with: - `reason` — Indicates the task needs human input ## Configuration (config.yml) The `.ai/config.yml` file controls AIDF behavior: ```yaml version: 1 provider: type: claude-cli # claude-cli | cursor-cli | anthropic-api | openai-api model: claude-sonnet-4-5-20250929 # optional execution: max_iterations: 50 max_consecutive_failures: 3 timeout_per_iteration: 300 permissions: scope_enforcement: strict # strict | ask | permissive auto_commit: true auto_push: false validation: pre_commit: [npm run lint, npm run typecheck] pre_push: [npm run test] pre_pr: [npm run build] git: commit_prefix: "aidf:" branch_prefix: "aidf/" skills: enabled: true directories: [] # extra directories to scan for skills ``` ## Working with Roles Before starting a task, check the `## Suggested Roles` section. Load the corresponding role file from `.ai/roles/`. Each role defines: - **Identity**: Who you are and your expertise level - **Expertise**: Your areas of knowledge - **Responsibilities**: What you are accountable for - **Constraints**: What you must never do - **Quality Criteria**: Standards your work must meet ## Quality Gates Before marking any task complete: 1. Run all validation commands from `config.yml` (`pre_commit` hooks) 2. Ensure all `Definition of Done` checkboxes are satisfied 3. Verify no files outside scope were modified 4. Check that code follows conventions defined in `AGENTS.md` ## Behavior Rules ### ALWAYS - Read AGENTS.md before starting any work - Check task scope before modifying files - Follow conventions defined in AGENTS.md exactly - Run quality gates before marking complete - Signal completion with `` or `` ### NEVER - Modify files outside the task scope - Skip quality gates - Ignore role constraints - Add dependencies without approval - Commit sensitive values (API keys, passwords) --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/rubenmavarezb) — claim your Tome and manage your conversions.