agentic-workflow-framework

Agentic Workflow Framework

Lightweight multi-agent orchestration conventions for Claude Code.

---

What this installs

• 1 spec document (~/.claude/AGENTIC.md) -- the full framework spec imported into every session via CLAUDE.md
• 10 subagent definitions in ~/.claude/agents/: planner, auditor, reviewer, builder-smart, builder-fast, builder-trivial, finder, researcher, tester, watcher
• 6 slash commands in ~/.claude/commands/: /agentic, /init-agentic, /handoff, /blocker, /known-issue, /qq
• 1 reinforcement hook (~/.claude/hooks/orchestrator.sh) -- fires on UserPromptSubmit to prevent Orchestrator drift
• 2 settings.json hook entries -- SessionStart (blocker/handoff scanner) + UserPromptSubmit (orchestrator reinforcement)
• 1 CLAUDE.md import line -- @AGENTIC.md so the spec loads globally in every Claude Code session
• 2 skills in ~/.claude/skills/: agentic-workflow and personal-engineering-rules
• 6 permission globs in ~/.claude/settings.json: Write/Edit for .localdev/workflow/**, .localdev/workflow/handoffs/**, and docs/KNOWN_ISSUES.md

---

Operational Tools

This framework treats three external tools as first-class infrastructure:

• GitNexus — mandatory first stop for structural code questions (call chains, impact, architecture) when the repo is indexed. Query before grepping.
• context-mode — mandatory sandbox for large outputs (file reads, logs, test runs) so raw data never enters the context window.
• context7 — mandatory verification of library/API/CLI behavior before asserting it; never from training memory.
• RTK — token-filtered shell command proxy for routine ops.

These are not bundled. Install separately. Fail-loud rule: when one of their MCP calls errors, the orchestrator and every subagent report the exact tool + verbatim error to the user instead of silently degrading to raw grep / web / training-data recall — silent fallback is how hallucinations ship.

---

Install

Option 0: Claude Code plugin marketplace (no cloning)

/plugin add jeanfbrito/agentic-workflow-framework

Claude Code downloads, installs, and activates the framework automatically. Hooks, slash commands, agents, and skills are live immediately — no shell step required.

The plugin sandbox cannot edit ~/.claude/CLAUDE.md or settings.json, so the plugin closes those two gaps with its own hooks:

• Always-on conventions: a SessionStart hook injects AGENTIC.md into every session's context (it no-ops when the shell installer's @AGENTIC.md import is present, so nothing loads twice).
• Permissions: a PreToolUse hook auto-allows Write/Edit on .localdev/workflow/** and docs/KNOWN_ISSUES.md, mirroring the permission globs install.sh grants. All other paths follow the normal permission flow.

Both paths land on the same conventions but wire them up differently: the plugin path relies on its own hooks (context injection, orchestrator reinforcement, permission auto-allow) since it cannot touch ~/.claude/CLAUDE.md or settings.json; the shell path instead writes the @AGENTIC.md import into CLAUDE.md and the permission globs directly into settings.json. Same end behavior via different mechanisms.

Option 1: clone and run

git clone https://github.com/jeanfbrito/agentic-workflow-framework.git ~/agentic-workflow-framework
cd ~/agentic-workflow-framework
./install.sh

Pass --yes / -y to skip the confirmation prompt. Pass --link to symlink instead of copy (dev mode — edits to the repo are reflected immediately).

The agent-driven self-installer has been retired (its embedded file copies drifted from the source of truth). Use the plugin marketplace path or the shell installer above.

---

Uninstall

./uninstall.sh

Removes the framework files, installed skills, and permission globs. By default this is a surgical strip: it removes only the framework's hook entries, permission globs, and @AGENTIC.md import, preserving anything else you've added to CLAUDE.md or settings.json since installing. Pass --restore-backup to instead wholesale-restore CLAUDE.md and settings.json from the pre-install backup snapshot, discarding all edits made since install. Does not remove the ~/.claude/agents/, ~/.claude/commands/, ~/.claude/hooks/, or ~/.claude/skills/ directories themselves.

---

Model mapping

Doctrine: opus is the general, sonnet the soldiers, haiku the scouts.