Skip to content

composable-capability.md

Latest commit

 

History

History
177 lines (121 loc) · 5.25 KB

composable-capability.md

File metadata and controls

177 lines (121 loc) · 5.25 KB

Composable Capability

fclt treats AI behavior as small capability units that can be composed into larger agent instructions and evolved independently.

This prevents one giant agent file from becoming the only place to put every preference, workflow, and exception. A language preference can live in one instruction. A repeated rendered block can live in one snippet. A workflow can live in one skill. Each unit can receive targeted writeback and targeted evolution.

This is the core model:

  • write domain guidance once
  • compose it with refs and snippets
  • render it only where a tool should receive it
  • target writeback at the smallest unit that needs to change

Units

Use instructions/ for reusable markdown doctrine.

Examples:

~/.ai/instructions/LANGUAGE.md
~/.ai/instructions/REVIEW.md
<repo>/.ai/instructions/TESTING.md

Use snippets/ for partial blocks inserted into rendered docs.

Examples:

~/.ai/snippets/global/codex/baseline.md
~/.ai/snippets/global/policy/review.md
<repo>/.ai/snippets/global/project/testing.md

Use skills/ for executable workflows, agents/ for delegated roles, mcp/ for tool interfaces, and automations/ for scheduled loops.

Refs

Canonical refs let a markdown asset point at another asset without hard-coding machine paths:

@ai/instructions/LANGUAGE.md
@project/instructions/TESTING.md
@builtin/facult-operating-model/instructions/WORK_UNITS.md

Use global refs for reusable user-owned capability. Use project refs for repo-owned capability. Use built-in refs for packaged defaults.

Config-backed refs are useful when the concrete path should be named in config.toml:

version = 1

[refs]
language_defaults = "@ai/instructions/LANGUAGE.md"
project_testing = "@project/instructions/TESTING.md"

Rendered markdown can use those refs through the render context when a tool adapter supports that target.

Snippets

Snippets use paired HTML markers:

<!-- fclty:global/policy/review -->
<!-- /fclty:global/policy/review -->

The marker above resolves to:

snippets/global/policy/review.md

Create and inspect snippets with:

fclt templates init snippet global/policy/review
fclt snippets list
fclt snippets show global/policy/review
fclt snippets sync --dry-run AGENTS.global.md

Use snippets when the same block appears in more than one rendered doc, or when a stable block should be independently targetable by writeback and evolution.

Instruction Templates

Create a new instruction scaffold with:

fclt templates init instruction LANGUAGE
fclt templates init instruction REVIEW

That writes:

instructions/LANGUAGE.md
instructions/REVIEW.md

An instruction can include refs, snippet markers, examples, and writeback targeting guidance. Keep one instruction focused on one reusable domain. For example:

  • LANGUAGE.md: user-owned language or tooling preferences.
  • REVIEW.md: user-owned review standards.
  • VERIFICATION.md: proof standards.

Composition Pattern

A global AGENTS.global.md can stay short and compose units:

# Global Agent Instructions

For work-unit framing, read `@ai/instructions/WORK_UNITS.md`.
For language/tooling preferences, read `@ai/instructions/LANGUAGE.md`.
For review standards, read `@ai/instructions/REVIEW.md`.

<!-- fclty:global/codex/baseline -->
<!-- /fclty:global/codex/baseline -->

A project can add narrower guidance:

# Project Agent Instructions

For project test policy, read `@project/instructions/TESTING.md`.
For local deployment rules, read `@project/instructions/DEPLOYMENT.md`.

This keeps global defaults reusable and lets projects override or extend them without rewriting the whole global file.

Evolution

Target the smallest unit that actually needs to change:

  • bad or stale domain guidance: update the instruction
  • repeated block copied in several docs: extract a snippet
  • missing workflow: add or update a skill
  • unclear delegation behavior: update an agent
  • tool integration gap: update MCP/tool config or create a tooling task
  • project-local pattern that proved reusable: promote the asset

Examples:

fclt ai writeback add --kind missing_context --summary "Language guidance did not cover test runner selection." --asset instruction:LANGUAGE
fclt ai writeback add --kind reusable_pattern --summary "Project testing policy should become a shared verification snippet." --asset @project/instructions/TESTING.md
fclt ai evolve propose

Do not create a global proposal for one-off taste. Use writeback to preserve evidence, then evolve when the signal repeats or the missing capability is already clear.

Review

Use these surfaces:

fclt list instructions --global
fclt list snippets --global
fclt show instruction:LANGUAGE
fclt graph deps AGENTS.global.md
fclt graph dependents @ai/instructions/LANGUAGE.md
fclt ai writeback group --by asset
fclt ai evolve list

Open ~/.ai/writebacks/ and ~/.ai/evolution/ in a markdown editor to inspect review artifacts with frontmatter status, scope, targets, project metadata, evidence, and proposal state.

Next