Setup

Config

Run

Report

Step-by-Step Guide

Zero to First Report

10 steps that walk you through the entire EDPA framework — from tool installation to a calibrated hour allocation report.

Start the guide

Prerequisites

EDPA is local-first — all you need is Python 3.10+ and Git. Claude Code users: Python deps are installed automatically by the SessionStart hook. Other environments: pip install manually. GitHub CLI is optional, only if you want the PR-signal CI workflow (--with-ci).

claude code (recommended)

# Python 3.10+ must be in PATH
python3 --version   # >= 3.10

# Git for versioning .edpa/ (auto-commits)
git --version

# Python dependencies install automatically
# on first Claude Code session in the project (SessionStart hook)

terminal

# Python dependencies (Cursor, Codex CLI, raw)
pip install pyyaml ruamel.yaml openpyxl requests

# Verify
python3 --version   # >= 3.10
git --version

# Optional — only for PR-signal CI (--with-ci):
gh auth login

Expected output

Python 3.12.1
git version 2.44.0

# Local-first: no org, no PAT, no GitHub Projects
# required for the core flow. Everything lives in .edpa/.

Next step →

Create Repository

EDPA lives inside a Git repository. Any repo works — personal or org, on GitHub or a purely local git init. No Issue Types or GitHub Projects required.

terminal

# Option A — new GitHub repo
gh repo create project-name \
  --private --clone
cd project-name

# Option B — purely local (no GitHub)
mkdir project-name && cd project-name
git init

Expected output

✓ Created repository project-name on GitHub
✓ Cloned to ./project-name

# or locally:
Initialized empty Git repository in ./project-name/.git/

Back Next step →

Install EDPA

In Claude Code: install via the marketplace. Other environments (Cursor, Codex CLI): curl|sh. Both options vendor the engine to .edpa/engine/ and scaffold the .edpa/ structure.

claude code (recommended)

/plugin install edpa@technomaton-edpa
# Claude Code downloads the plugin from the marketplace

terminal

# Outside Claude Code (Cursor, Codex CLI, raw):
curl -fsSL https://edpa.technomaton.com/install.sh | sh

Expected output

EDPA Installer
==============
Downloading EDPA plugin...
✓ Engine vendored to .edpa/engine/
✓ Created .edpa/ structure:
  .edpa/engine/    ← scripts, templates, schemas
  .edpa/config/    ← team and project config
  .edpa/backlog/   ← work items (per-item YAML)
  .edpa/reports/   ← generated reports
✓ Created .edpa/config/people.yaml (edit your team)
✓ Created .edpa/config/edpa.yaml (edit project name)

Next: /edpa setup "Project Name"

Back Next step →

/edpa:setup

One command vendors the engine into .edpa/engine/ and seeds configs — team, project, and id_counters.yaml. Local-first: no GitHub Project provisioning. Optionally --with-ci adds the PR-signal workflow (edpa-contribution-sync.yml: PR-thread signals → evidence[], plus git hooks).

claude code (recommended)

/edpa:setup "Project Name"
# Claude Code handles everything interactively

# Optional — add the PR-signal CI workflow:
/edpa:setup "Project Name" --with-ci

terminal

# Manual alternative (outside Claude Code):
# 1. Edit .edpa/config/people.yaml (team, roles, FTE, capacity)
# 2. Edit .edpa/config/edpa.yaml (project name, governance, naming)
# 3. Seed ID counters:
python3 .edpa/engine/scripts/setup.py

# Optional — PR-signal CI workflow:
python3 .edpa/engine/scripts/setup.py --with-ci

Expected output

✓ Engine vendored: .edpa/engine/{scripts,templates,schemas}
✓ Team: 3 members configured (2.8 FTE)
✓ Config: .edpa/config/edpa.yaml (project + governance)
✓ Config: .edpa/config/people.yaml (team)
✓ Seeded: .edpa/config/id_counters.yaml
✓ CW heuristics: .edpa/config/cw_heuristics.yaml

# With --with-ci, additionally:
✓ Workflow: .github/workflows/edpa-contribution-sync.yml
  → PR-thread signals → evidence[] on items
✓ Git hooks installed (commit-msg: feat(<ID>): …)
# Under lefthook (lefthook.yml present): EDPA does not write .git/hooks/,
#   it prints a snippet → paste into lefthook.yml and run: lefthook install
# Verify anytime: project_setup.py --check-hooks

# Local-first: no org, no PAT, no GitHub Projects.

Back Next step →

Populate Backlog

Add items via backlog.py add — the ID is allocated from id_counters.yaml, the parent hierarchy is validated, and a .md file is written under .edpa/backlog/ and auto-committed as feat(<ID>):. Hierarchy: Initiative > Epic > Feature > Story. WSJF is calculated automatically.

claude code (recommended)

# In Claude Code, just say:
/edpa:add Story "Implement login endpoint" \
  --parent F-1 --js 5 --bv 8 --tc 5 --rr-oe 3 \
  --assignee jnovak --iteration PI-2026-1.1

# Claude, via MCP edpa_item_create:
#  • allocates the ID from id_counters.yaml (S-1)
#  • validates the parent (F-1 must exist)
#  • writes .edpa/backlog/stories/S-1.md
#  • auto-commits: feat(S-1): add story
# Then: "Validate the backlog and show me the tree"

terminal

# CLI fallback (outside Claude Code) — add auto-commits feat(<ID>):
python3 .edpa/engine/scripts/backlog.py add Story \
  "Implement login endpoint" \
  --parent F-1 --js 5 --bv 8 --tc 5 --rr-oe 3 \
  --assignee jnovak --iteration PI-2026-1.1

# Writes .edpa/backlog/stories/S-1.md (front-matter + body):
#   id: S-1 / type: Story / js,bv,tc,rr_oe / status: Backlog
#   parent: F-1 / assignee / iteration
#   created_at filled locally, closed_at on transition to Done

python3 .edpa/engine/scripts/backlog.py validate
python3 .edpa/engine/scripts/backlog.py tree

Expected output

✓ feat(S-1): add story  (auto-commit)
✓ Backlog valid (12 items, 0 errors)

I-1: Medical Platform
└── E-1: Data Processing Pipeline
    ├── F-1: Authentication (JS=8, WSJF=2.0)
    │   ├── S-1: Login endpoint (JS=5) ← jnovak
    │   └── S-2: Token refresh (JS=3) ← emala
    └── F-2: Data Import (JS=13, WSJF=1.8)
        ├── S-3: CSV parser (JS=5) ← emala
        └── S-4: Validation (JS=3) ← pkral

Back Next step →

Team Starts Working

The team works using standard Git flow — branch naming conventions, commits referencing items (feat(<ID>):), PRs and code review. EDPA reads evidence locally from Git history; if the PR-signal CI runs (--with-ci), PR-thread signals are additionally appended to evidence[].

terminal

# Branch naming (CI enforces format)
git checkout -b feature/S-1-login-endpoint

# Commit referencing item
git commit -m "feat(S-1): implement JWT login"

# Pull Request
gh pr create \
  --title "S-1: Login endpoint" \
  --body "Implements JWT auth flow" \
  --assignee jnovak

Expected output

Branch: feature/S-1-login-endpoint
Commits: 4 (linked to S-1)
PR #42: "S-1: Login endpoint"
  → Review requested: pkral
  → Status: Approved ✓ → Merged

Evidence (signal weights → contribution_score):
  jnovak: commit_author 4.00                = 4.00
  pkral:  pr_reviewer 2.17                  = 2.17
  → cw[jnovak, S-1] = 4.00 / 6.17 = 0.65
  → cw[pkral,  S-1] = 2.17 / 6.17 = 0.35

Timestamps (locally from Git history):
  S-1: created_at=2026-05-10, updated_at=2026-05-15, closed_at=2026-05-15

Flow metrics (MCP tool edpa_flow_metrics):
  S-1 cycle time: 5d | Throughput: 4 items/iter

Back Next step →

End of Iteration

At iteration end, the EDPA engine reads evidence from backlog files in .edpa/backlog/ and proportionally allocates hours based on actual work.

claude code (recommended)

/edpa:close-iteration PI-2026-1.1
# Claude Code reads evidence and computes allocation

terminal

python3 .edpa/engine/scripts/engine.py \
  --edpa-root .edpa \
  --iteration PI-2026-1.1

# The engine automatically:
# 1. Reads evidence from .edpa/backlog/ files
# 2. Computes contribution weight (CW)
# 3. Allocates hours: Score / Total × Capacity
# 4. Generates reports

Expected output

EDPA Engine v2.11.1 — PI-2026-1.1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Team:     3 members, 2.8 FTE
Capacity: 448 hours (2 weeks)

Allocation:
  jnovak  │████████████████░░│ 178.2h (39.8%)
  emala   │█████████████░░░░░│ 142.6h (31.8%)
  pkral   │████████████░░░░░░│ 127.2h (28.4%)
                        Total: 448.0h ✓
Invariants: ALL PASSED

Back Next step →

Reports & Timesheets

EDPA generates per-person timesheets, per-item cost allocation, JSON exports, and frozen snapshots. All auditable and reproducible.

claude code (recommended)

/edpa:reports
# Claude Code generates all reports and timesheets

terminal

# Generated files
.edpa/reports/
├── iteration-PI-2026-1.1/
│   ├── vykaz-jnovak.md      # per-person timesheet
│   ├── vykaz-emala.md
│   ├── vykaz-pkral.md
│   ├── edpa_results.json    # machine-readable
│   └── summary.xlsx         # Excel export
.edpa/snapshots/
└── iteration-PI-2026-1.1.json  # frozen snapshot

Expected output

Per-person timesheet (vykaz-jnovak.md):
┌──────────┬────────┬────────┬────────┐
│ Person   │ Hours  │ Share  │ Items  │
├──────────┼────────┼────────┼────────┤
│ jnovak   │ 178.2  │ 39.8%  │ 7      │
│ emala    │ 142.6  │ 31.8%  │ 5      │
│ pkral    │ 127.2  │ 28.4%  │ 6      │
├──────────┼────────┼────────┼────────┤
│ TOTAL    │ 448.0  │ 100%   │ 18     │
└──────────┴────────┴────────┴────────┘

Back Next step →

Retrospective + Calibration

Calibrate signal weights against a synthetic Monte Carlo corpus. calibrate_signals.py runs MC random sampling + coordinate descent and reports MAD baseline vs. calibrated.

claude code (recommended)

/edpa:calibrate
# Claude Code runs MC calibration and shows MAD results

terminal

# Monte Carlo signal-weight calibration
python3 .edpa/engine/scripts/calibrate_signals.py \
  --scenarios 1000 --seed 42

# MAD < 0.06 → excellent calibration
# MAD 0.06-0.10 → good calibration
# MAD > 0.10 → weight adjustment needed

Expected output

Calibration: 1000 scenarios, seed=42
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase 1 (random sample):  MAD baseline   = 0.0861
Phase 2 (coord descent):  MAD calibrated = 0.0805
Improvement: +6.5%

Verdict: GOOD (defaults are already near optimum)

Back Next step →

Next PI

Repeat for each iteration. With every cycle, calibration improves. Target: predictability > 80%, MAD < 0.05 by the third PI.

claude code (recommended)

/edpa:close-iteration PI-2026-1.2
# Next iteration — same workflow

terminal

# New iteration
python3 .edpa/engine/scripts/engine.py \
  --edpa-root .edpa \
  --iteration PI-2026-1.2

# Compare iteration results in .edpa/reports/

Expected output

Trend: PI-2026-1.1 → PI-2026-1.4
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MAD:            0.032 → 0.018  ↓ improving
Predictability: 78%   → 91%   ↑ on target
Correlation:    0.94  → 0.98  ↑ strong

Status: Mature — framework calibrated.

Back Done — back to EDPA