ACF — AI Agent Directives

Canonical workflow for every agent using ACF to craft issues and PRs. Read this file top-to-bottom before using the skill.

Reading Order

1. AGENTS.md (this file) — Agent workflow and conventions
2. docs/ARCHITECTURE.md — Skill architecture and data flow
3. docs/FLOW.md — End-to-end pipeline diagram
4. docs/IDEAS.md — Source conversation and idea mapping
5. docs/PROCESS.md — Build process and decision log
6. docs/COMPACTION.md — Context compaction research (Kimi CLI) and caveman mode
7. docs/COMPATIBILITY.md — Multi-agent compatibility (agentskills.io spec)
8. docs/ROADMAP.md — Product roadmap and maturity assessment
9. skills/acf/SKILL.md — Orchestrator skill (source of truth, mirrored at .devin/skills/acf/)
10. skills/01-context-load/SKILL.md — Phase 1: context loading (mirrored at .devin/skills/01-context-load/)
11. skills/02-stack-audit/SKILL.md — Phase 2: stack auditing (mirrored at .devin/skills/02-stack-audit/)
12. skills/03-issue-craft/SKILL.md — Phase 3: issue crafting (mirrored at .devin/skills/03-issue-craft/)
13. skills/04-pr-context/SKILL.md — Phase 4: PR context building (mirrored at .devin/skills/04-pr-context/)
14. skills/05-frontend-preview/SKILL.md — Phase 5: frontend preview (optional) (mirrored at .devin/skills/05-frontend-preview/)
15. skills/06-label-metadata/SKILL.md — Label taxonomy (mirrored at .devin/skills/06-label-metadata/)
16. skills/07-compaction/SKILL.md — Phase 7: context compaction (mirrored at .devin/skills/07-compaction/)
17. skills/08-caveman/SKILL.md — Phase 8: extreme compression (mirrored at .devin/skills/08-caveman/)
18. skills/09-graph-scope/SKILL.md — Phase 0: dependency graph + blast radius (mirrored at .devin/skills/09-graph-scope/)
19. templates/issue-contextualized.md — Issue body template
20. templates/pr-contextualized.md — PR body template
21. SECURITY.md — Security policy
22. CONTRIBUTING.md — Contributing guidelines

Project Snapshot

Preferred Workflow

┌─────────────────────────────────────────────────────────────────┐
│  0. GRAPH-SCOPE   →  Decompose project into dependency graph,    │
│                      compute affected subgraph (large projects)  │
│  1. CONTEXT-LOAD  →  Read project MDs + scoped files, build      │
│                      snapshot                                    │
│  2. STACK-AUDIT   →  Detect orphan PRs, stale issues, libs       │
│  3. ISSUE-CRAFT   →  Craft issue with AC, labels, metadata       │
│  4. PR-CONTEXT    →  Build PR body with issue context            │
│  5. FRONTEND-PREVIEW (optional) → Visual diff, screenshot        │
│  6. LAUNCH        →  gh issue create / gh pr create              │
│  7. COMPACTION (auto/optional) → Kimi-inspired context compaction│
│  8. CAVEMAN (optional, extreme) → <500 tokens extreme compression│
└─────────────────────────────────────────────────────────────────┘

Phases 7 and 8 can trigger at any point after context-load when the accumulated context exceeds the token budget.

Phase Rules

• Never skip context-load — every issue and PR must be built from a snapshot
• Never skip stack-audit — always check for orphan PRs and escaped issues
• Max 2 AC for autonomous issues — more than 2 = decompose or batch-delivery
• Library suggestions are separate issues — never bundle into the main issue
• Labels are mandatory — type + priority + area, minimum 3 labels per issue
• Context is compressed — reference paths, never inline file contents
• Compaction triggers at ~2000 tokens — auto-compact using Kimi techniques
• Caveman triggers when compaction is not enough — target <500 tokens

Context Compression Rules

ACF has three compression tiers:

Compression principles (all tiers)

1. Paths, not contents — src/shared/Constants.luau not the file's code
2. Commands, not configs — lune run scripts/test_core.luau not the test file
3. Check names, not YAML — test (lune) not the full workflow
4. Counts, not lists — "26 services" not all 26 service names
5. Labels, not body text — priority:P1 not "Priority: High" in body
6. Max 5 bullets per section in the snapshot

Compaction-specific (phase 7)

• Head+tail preservation: keep the original request (head, max 500 tokens) and the most recent phase output (tail, max 1000 tokens) verbatim; compact the middle
• Priority-based: preserve task state, errors, test commands, CI checks
• XML-tagged output: <current_focus>, <stack>, <tests>, <ci>
• First-person handoff: progress file reads as agent's own working notes

Caveman-specific (phase 8)

• No prose — only paths, commands, labels, numbers
• Symbols over words — →, |, #N
• Bare caveman last resort — only NOW + NEXT + TESTS + CI (~100 tokens)

See docs/COMPACTION.md for the full research and design notes.

Label Taxonomy (summary)

See skills/06-label-metadata/SKILL.md for full taxonomy.

Every issue MUST have: 1 type + 1 priority + 1 area label (minimum).

Installation

Universal installer (recommended)

Use install.sh to install ACF into any project. It auto-detects which agent directories exist and installs to all of them:

./install.sh /target/project

Install to ALL supported agents (creating directories as needed):

./install.sh /target/project --all

Install to a specific agent only:

./install.sh /target/project --agent claude

Supported agents: devin, claude, cursor, codex, agents, opencode

See docs/COMPATIBILITY.md for the full compatibility matrix.

Manual installation

If you prefer to copy files manually:

Devin:

cp -r .devin/skills/* /target/project/.devin/skills/

Claude Code / Cursor / Codex / OpenCode / OpenClaw:

cp -r skills/* /target/project/.claude/skills/

(Replace .claude/skills/ with the appropriate path for your agent — see docs/COMPATIBILITY.md for the path table.)

Label setup

Run the label creation commands from skills/06-label-metadata/SKILL.md in the target repo to create all canonical labels.

Git Commits

feat:     New skill phase or feature
fix:      Bug fix in a skill
docs:     Documentation change
refactor: Skill reorganization
chore:    Build, config, tooling

Key File Reference