Agentic Workflow Architecture
How context files, rules, skills, agents, hooks, and memory work together across projects
01 Startup
agent.md auto
Click to view
rules/*.md conditional
Click to view
memory.md auto
Click to view
SessionStart hook auto
Click to view
02 Session Work
Skills on trigger
Click to view
Agents on delegate
Click to view
PostToolUse hook auto
Click to view
03 Context Pressure
PreCompact hook auto
Click to view
04 Session End
SessionEnd hook auto
Click to view
Knowledge synthesis
Click to view
Every element below can live at the ~/.global/ (global) level, the project/.project/ (project) level, or both. Global applies to all projects. Project-level config adds to or overrides global for that repo.
agent.md
The primary context file. Global: workflow preferences, git conventions, security rules. Project: architecture, commands, conventions. Both load at startup and combine.
~/.global/agent.md + project/agent.md
Click to view
rules/ paths: match
Conditional rules that apply based on file type. Global and project rules are additive: both load when paths match.
Example: code-quality.md → *.{ts,tsx,js,jsx,py} · testing.md → *.test.*, *.spec.* · documentation.md → *.md
~/.global/rules/ + .project/rules/
Click to view
skills/ on trigger
Reusable workflows triggered by slash commands (e.g. /retro, /review, /deploy). Define globally for cross-project use, or per-project for repo-specific workflows. A project skill with the same name overrides its global counterpart.
~/.global/skills/ + .project/skills/
Click to view
agents/ on delegate
Persistent subagents with their own instructions and optional memory. Global agents work across all projects. Project agents can override globals with domain-specific knowledge.
~/.global/agents/ + .project/agents/
Click to view
hooks/ auto
Custom actions that fire automatically at key moments: when a session starts, after each tool use, before context compression, and when a session ends. Use for file tracking, knowledge capture, linting, or other automation.
~/.global/scripts/hooks/
Click to view
memory.md
The index. Loads automatically every session (first 200 lines). Key facts, patterns, and pointers.
auto-loaded
Click to view
→
topics/*.md
Deep dives. One file per area (CRM sync, infrastructure, API gotchas). Read on demand when the agent needs detail.
on demand
Click to view
→
backlog.md
Deferred improvements. Skills check this each run and surface relevant items when the time is right.
on demand
Click to view
Each hierarchy exists at two scopes: user (cross-project, used by global agents) and project (repo-specific, used by project agents).
memory.md points to topics/ with > Details → see topics/crm-sync.md — the agent follows these links when it needs the full picture.
What writes to memory
SessionEnd Hook
Fires automatically. Spawns a subagent that asks: “Would knowing this change how a future session handles a similar task?”
Click to view
memory.md + topics/
/retro Skill
Run manually at end of productive sessions. Full extraction: scan conversation, route insights, compact oversized files.
Click to view
memory.md + topics/ + CLAUDE.md (suggest)
Skill Feedback
When a skill gets corrected mid-run, it writes the fix back to its own reference files. Next run starts smarter.
Click to view
skill reference files
Session N ends
Observations routed to memory.md, topics/, or skill references
→
Session N+1 starts
memory.md loads automatically. Agent reads topics/ when relevant. Skills start with updated references.
→
Each session is better
The agent accumulates project knowledge, avoids past mistakes, and follows established patterns without being told.