Practical Guide
How to Use the
Agentic Development Framework
A step-by-step walkthrough of the commands,
workflows, and daily patterns that make it work.
Before You Start
From Idea to Code: Five Phases
Most of the planning happens before you write a line of code. This is the suggested approach — research first, validate second, build last.
1. Seed — Research Your Idea
Use Claude Deep Research, Gemini, or manual reading to explore your domain. Save each session as a markdown file. Note key findings, competing approaches, and open questions.
Happens outside the framework. Pure ideation.
2. Anchor — Pressure-Test with Specialists
Paste your research findings into /deliberate. The agent panel evaluates from architecture, security, UX, and anti-groupthink perspectives. One deliberation per major theme.
Bridges external research into framework-captured reasoning.
3. Scout — Find Real-World Validation
Use /discover-projects to find reference implementations on GitHub, then /analyze-project to score their patterns. If 3+ projects implement a pattern well, that’s strong evidence.
Grounds research against actual working code.
4. Reconcile — Make Decisions
Run /deliberate again with all evidence — research, specialist findings, and project analysis scores. Produce ADRs documenting your architectural decisions with full alternatives considered.
Synthesizes everything into traceable decisions.
5. Specify — Create the Executable Plan
Run /plan to produce a structured spec. Specialists review it. Once approved, /build_module takes over and builds it with integrated quality gates.
coding begins.
Getting Started
Setup in 3 Minutes
Prerequisites
What You Get
The full framework infrastructure: 11 agents, 16 commands, 7 hooks, and the four-layer capture stack. Add your application code to src/ and start building.
For Existing Projects
Already have a codebase? Use /onboard instead of cloning. It runs the “takeover” protocol:
Daily Pattern
The Typical Development Flow
1. Write Your Code
Build features, fix bugs, refactor. The framework doesn't change how you write code — it changes what happens after.
2. Run /review
The facilitator assesses risk, assembles specialists, and produces a structured review with a verdict. Takes 30-90 seconds.
3. Address Findings
Blocking findings must be fixed. Advisory findings are recommendations. The review report tells you which is which.
4. Quality Gate
Run python scripts/quality_gate.py or just commit — the pre-commit hook runs it automatically.
5. Commit
If the quality gate passes and the review is clean, commit your code. The entire review is captured in the discussion archive.
6. Education Gate
For complex changes, run /walkthrough and /quiz to verify you understand the AI-generated code.
Core Command
/review — Multi-Agent Code Review
What Happens Behind the Scenes
The facilitator creates a discussion, assesses risk level, selects 2-5 specialists, dispatches them in parallel, collects findings, synthesizes a verdict, writes a report to docs/reviews/, and seals the discussion.
Risk-Based Specialist Assembly
Config, docs, simple fixes
2-3 agents. QA + 1 domain specialist. Ensemble mode.
New features, refactoring
3-4 agents. QA + Architecture + domain. Structured Dialogue mode.
Security, architecture changes
4-5 agents. Full panel including Security + Independent Perspective.
Verdicts
Approve · Approve with changes · Request changes · Reject
Building Features
/plan + /build_module — Spec-Driven Development
Step 1: Plan the feature
Step 2: Build from the spec
Why Spec-First?
The spec is reviewed by specialists before any code is written. Catching architecture mistakes at the spec stage is 10x cheaper than fixing them in code.
Mid-Build Checkpoints
When a build task creates a new module, touches security code, or changes database schema, 2 specialists automatically review the code mid-build. Max 2 rounds per checkpoint.
The Build Summary
After building, you get a summary with: tasks completed, checkpoint results, unresolved concerns (if any), and a recommendation for the final /review.
Decision Making
/deliberate — Structured Multi-Agent Discussion
When to Deliberate
Use /deliberate when you face a decision with multiple valid options and non-obvious trade-offs. The specialists bring different professional perspectives that surface considerations you might miss alone.
What You Get
Independent Analysis
Each specialist analyzes the question from their domain (security, performance, architecture, etc.) without seeing others' answers.
Cross-Pollination
Specialists see each other's findings and can refine their positions. Disagreements are surfaced, not hidden.
Synthesis & Recommendation
The facilitator synthesizes all perspectives into a recommendation with explicit trade-offs. You make the final call.
Every deliberation is captured in discussions/ with full event streams. Six months later, you can read exactly why a decision was made.
Quick Reference
What Do I Do When…
“I have an idea but don’t know where to start”
Research first (Phase 1), then /deliberate to pressure-test, then /plan to create a spec.
“I’m choosing between two approaches”
Run /deliberate with both options. The specialist panel will surface trade-offs you might miss.
“I want to see how others solved this”
/discover-projects to find reference repos, then /analyze-project to score their patterns for your project.
“I wrote code and need a second opinion”
/review src/ — the specialist panel reviews from security, architecture, performance, and quality perspectives.
“I found a bug and fixed it”
Write a regression test tagged @pytest.mark.regression, add it to the regression ledger, then /review the fix.
“AI wrote code I don’t fully understand”
/walkthrough for a guided explanation, then /quiz to verify you actually get it before shipping.
“I have an existing project I want to improve”
/onboard maps your codebase, reverse-engineers decisions, and creates a stabilization plan with a debt ledger.
“The sprint is over — what now?”
/retro analyzes all discussions, surfaces recurring patterns, and proposes process improvements. Run /batch-evaluate to audit pending adoptions.
Learning & Growth
Commands That Make You Better
/walkthrough education
Generates a guided reading path through code you (or AI) wrote. Explains decisions, trade-offs, and how components interact. Progressive disclosure from mental model to implementation details.
/quiz assessment
Bloom's taxonomy quiz on code you're about to ship. Tests understanding at 4 levels: recall, application, analysis, and evaluation. Includes debug scenarios and change-impact questions.
/analyze-project external
Points the specialist team at an external project to evaluate patterns worth adopting. Produces a scored recommendation report. Patterns scoring 20+/25 are recommended.
/discover-projects search
Searches GitHub for interesting projects to analyze. Filters by topic, language, or keywords. Checks for AI integration artifacts and ranks candidates for /analyze-project.
Continuous Improvement
The Framework Improves Itself
/retro sprint
Run at the end of each sprint. Queries all discussions from the period, identifies recurring patterns, evaluates adopted patterns (PENDING → CONFIRMED or REVERTED), and proposes process adjustments.
/meta-review quarterly
The big one. Quarterly assessment of framework effectiveness: agent scoring, architectural drift, rule updates, decision churn. Drives framework-level evolution.
/knowledge-health diagnostic
Quick health check on all 5 pipeline layers. Reports on discussion volume, SQLite index completeness, findings extraction, pattern clustering, and curated memory currency.
The Improvement Cadence
Daily
/review captures findings. Agent reflections after each discussion note what worked and what didn't.
Sprint
/retro aggregates findings, evaluates adoptions, surfaces stale advisories, and proposes adjustments.
Quarterly
/meta-review assesses the framework itself. Which agents are valuable? Which rules need updating? Is there architectural drift?
/promote — Layer 3
When a pattern proves valuable across multiple reviews, promote it to curated memory with /promote. Requires your explicit approval (Principle #7).
/batch-evaluate — Audit
Reviews all PENDING pattern adoptions from /analyze-project runs. Checks whether each pattern was actually implemented, verifies evidence, and presents verdicts for your approval.
Safety Net
The Quality Gate — Your Last Line of Defense
What It Checks
Formatting (ruff format) → Linting (ruff check) → Tests (pytest) → Coverage (≥ 80%) → ADR completeness → Review existence → Regression ledger
Hooks That Protect You
Secret Detection
Scans for 12 patterns (API keys, JWT, AWS, PATs) before any file write. Blocks the write if secrets are detected.
File Locking
Prevents concurrent agent edits to the same file. Locks auto-expire after 120 seconds.
Auto-Format
Every Python file is auto-formatted with ruff after every edit. You never commit unformatted code.
Branch Protection
Blocks direct pushes to main. Create a feature branch, open a PR, then merge. Keeps your history clean.
Session Continuity
BUILD_STATUS.md is auto-saved before context compaction and auto-loaded on resume. Work-in-progress survives sessions.
Release & Lineage
Shipping and Tracking Your Fork
/ship release
Full release workflow: quality gate verification, testing checklist, version bump, changelog generation, and rollback strategy. Everything you need to ship with confidence.
/lineage drift
Shows how your project relates to the upstream template. Detects drift, validates the manifest, and reports divergence distance. Intentional divergences can be pinned as traits.
Template → Project Relationship
When you fork this template for a real project, the framework-lineage.yaml manifest tracks:
The Steward Agent
The Steward is the framework's institutional memory for genealogy. It knows where your project came from, how far it has diverged, and which divergences are intentional vs. accidental drift.
Reference
Command Cheat Sheet
Every Day
Building Features
Quality
Process Improvement
External Learning
Release & Lineage
Start Building
The framework adds structure to AI-assisted development
without slowing you down.
AI-Native Agentic Development Framework v2.1 · Diviner Dojo
diviner-dojo@gmail.com