Central repo for AI-assisted development workflows, specs, plans, and Claude Code configuration for the Dalgo platform.
dalgo-core/
├── .claude/
│ ├── agents/ # Specialized AI agents (auto-invoked by context)
│ ├── commands/
│ │ ├── product/ # PM commands
│ │ └── engineering/ # Engineering commands
│ └── skills/ # Evaluation lenses / thinking frameworks
├── prototypes/
│ └── {feature-name}/
│ └── brief.md # PM's prototype brief (spike)
├── features/
│ └── {feature-name}/
│ ├── spec.md # PM's original spec (full vision)
│ ├── v1/
│ │ ├── spec.md # Engineering's scoped iteration
│ │ ├── research.md # Codebase & external research
│ │ ├── plan.md # Implementation plan (HLD, LLD, security, milestones)
│ │ └── tasks.md # Execution progress checkpoint
│ └── v2/
│ └── ... # Next iteration
├── DDP_backend -> ../DDP_backend (symlink, gitignored)
└── webapp_v2 -> ../webapp_v2 (symlink, gitignored)
| Type | Location | Purpose | How to Use |
|---|---|---|---|
| Commands | .claude/commands/{product,engineering}/ |
Step-by-step workflows with inputs and outputs | /product/command or /engineering/command |
| Agents | .claude/agents/ |
Specialized personas invoked by context | Claude picks the right agent automatically |
| Skills | .claude/skills/ |
Evaluation lenses — shift how Claude looks at a problem | Invoke by name (e.g. /design-review) |
Quick validation with NGO partners before committing engineering time. PM owns this end-to-end.
| Run | /product/prototype "feature idea" or /product/prototype path/to/notes.md |
| Saves to | prototypes/{feature-name}/brief.md |
| Then | Optionally builds prototype code in a separate branch |
| Review | Show to the team before showing to users |
| After testing | Validated → /product/write-spec to promote. Didn't work → archive & move on. |
flowchart TD
A["Idea or NGO request"] --> B["Prototype
Run /product/prototype"]
B --> |"brief.md"| C["Build"]
C --> R{"Show to the team"}
R --> |"Approved"| F["Test with NGO"]
R --> C
R --> |"Rejected"|X["Archive"]
F --> G{Validated?}
G --> |Yes| H["Write spec
Run /product/write-spec"]
G --> |"Maybe / No"| I["Archive"]
style A fill:#f3f4f6,stroke:#6b7280,color:#000
style B fill:#fff,stroke:#6b7280,color:#000
style C fill:#fff,stroke:#6b7280,color:#000
style R fill:#fff,stroke:#6b7280,color:#000
style F fill:#fff,stroke:#6b7280,color:#000
style G fill:#fff,stroke:#6b7280,color:#000
style H fill:#fff,stroke:#6b7280,color:#000
style X fill:#fef3c7,stroke:#f59e0b,color:#000
style I fill:#fef3c7,stroke:#f59e0b,color:#000
Production-quality implementation for confirmed features. Engineering owns this. All artifacts in features/.
flowchart TD
A["Write spec
Run /product/write-spec"] --> |"spec.md"| B["Review Product Spec"]
B --> C["Scope version"]
B --> |"feedback review loop"| A
C --> |"v1/spec.md"| D["Plan & iterate
Run /engineering/plan-feature"]
C --> |"v1/spec.md"| E["Design/UX"]
D --> |"plan.md"| F["Execute plan
Run /engineering/execute-plan"]
F --> DR1["Design review"]
DR1 --> F
E --> DR1
DR1 --> |"Design incorporated"| G["Validate spec
Run /engineering/validate-spec"]
G --> H["Review PR
Run /engineering/review-pr"]
H --> I["Merge + Deploy"]
I --> J{Next?}
J --> |Bug| K["Debug issue
Run /engineering/debug-issue"]
J --> |v2| C
style A fill:#fff,stroke:#6b7280,color:#000
style C fill:#fff,stroke:#6b7280,color:#000
style D fill:#fff,stroke:#6b7280,color:#000
style F fill:#fff,stroke:#6b7280,color:#000
style G fill:#fff,stroke:#6b7280,color:#000
style H fill:#fff,stroke:#6b7280,color:#000
style I fill:#d1fae5,stroke:#10b981,color:#000
style J fill:#fff,stroke:#6b7280,color:#000
style K fill:#fff,stroke:#6b7280,color:#000
| Spike | Engineering | |
|---|---|---|
| Confidence | "I think this might work" | "We know we need this" |
| Goal | Validate with an NGO user | Ship to production |
| Time | Hours | Days |
| Workspace | prototypes/ |
features/ |
| Command | /product/prototype |
/product/write-spec → /engineering/* |
Quick spike — validate an idea with NGO partners before committing to a full spec.
/product/prototype "let users bookmark their favorite dashboard charts"
Output: prototypes/{feature-name}/brief.md (1-page brief with problem, scope, quick plan)
Optionally: builds the prototype code with # PROTOTYPE markers
Next step: Test with NGO → if validated, /product/write-spec "{feature name}"
Two modes in one command:
Mode A — New spec (from an idea):
/product/write-spec "scheduled report emails for dashboard owners"
Output: features/{feature-name}/spec.md (full vision)
Mode B — Scope a version (from an existing spec):
/product/write-spec features/scheduled-reports
Output: features/{feature-name}/v1/spec.md (or v2, v3, etc.)
Next step: /engineering/plan-feature features/{feature-name}/v1/spec.md
Generate an implementation plan with HLD, LLD, security review, and milestones.
/engineering/plan-feature features/scheduled-reports/v1/spec.md
Output: features/{feature-name}/v1/plan.md + research.md
The plan is a draft — engineers iterate on it through conversation. Claude updates plan.md in place.
Implement the feature following the plan, with checkpointing.
/engineering/execute-plan features/scheduled-reports/v1/plan.md
Creates: features/{feature-name}/v1/tasks.md for progress tracking
Next step: /engineering/validate-spec
Diagnose a bug from a Sentry URL, error message, or behavior description.
/engineering/debug-issue https://sentry.io/issues/DALGO-123/
/engineering/debug-issue "500 error on /api/v1/organizations/"
Structured code review — checks service-specific conventions, security, testing, breaking changes.
/engineering/review-pr 142
/engineering/review-pr https://github.com/DalgoT4D/DDP_backend/pull/142
Does NOT auto-post to GitHub — outputs the review for you to use.
Validates the implementation against the spec. Checks that all spec requirements are met, runs lint, tests, and migration checks. Read-only.
/engineering/validate-spec
Triggered by natural-language prompts like:
generate docs for orchestrate
update docs for #142
write a docs page for data quality
refresh docs for the abc123..def456 changes
Claude auto-loads the documentation skill in .claude/skills/documentation/. The skill walks you through research → placement (derived from webapp_v2/app/ + dalgo_docs/sidebars.js) → writing → sidebar update → domain-map update.
Output: Markdown page in dalgo_docs/docs/ at the correct location, screenshots in dalgo_docs/static/img/{feature}/, and updated dalgo_docs/sidebars.js if it's a new page.
The skill is broken into workflow.md, sidebar.md, repo-structure.md, and style-*.md files — each under 100 lines.
Single script (scripts/screenshot.py) that runs YAML recipes from scripts/recipes/. Each recipe describes the user flows for one feature as a list of flows × steps (navigate, click, wait, snap, press). One recipe per top-level feature.
Setup — first time:
cd dalgo-core
uv sync # creates .venv/, installs deps from uv.lock
uv run playwright install chromium # one-time browser downloadCreate dalgo-core/.env (gitignored, auto-loaded via python-dotenv):
E2E_ADMIN_EMAIL=your@email.com
E2E_ADMIN_PASSWORD=yourpassword
E2E_BASE_URL=https://staging-app.dalgo.org
Run:
cd dalgo-core
uv run python scripts/screenshot.py # run all recipes (bulk refresh)
uv run python scripts/screenshot.py kpis # one feature
uv run python scripts/screenshot.py kpis metrics # several
uv run python scripts/screenshot.py --list # show available recipes
# Inline base URL override (skips .env's E2E_BASE_URL):
E2E_BASE_URL=http://localhost:3001 uv run python scripts/screenshot.pyFailure semantics: required flows abort their recipe (exit code 2); optional flows print a warning and skip. The script logs ✓ / ⚠ / ✗ per step so you can spot drift.
Adding a new feature: drop a scripts/recipes/{feature}.yaml file. The engine auto-discovers it. See scripts/recipes/kpis.yaml or ingest.yaml for patterns.
Staging environment:
The staging environment is at
https://staging-app.dalgo.org. Ask the team for access credentials if you don't have them.
Agents are specialized personas that Claude invokes automatically when the context matches. Agents use skills as reference material for their decisions.
| Agent | What It Does | Skills Used |
|---|---|---|
| debugger | Diagnoses bugs across the full stack — Django backend, Next.js frontend, or cross-cutting. | backend-architecture, frontend-architecture |
| senior-product-manager | Product strategy and feature specs. Prioritization, roadmap, build-vs-buy, spec writing. | None — uses its own evaluation framework |
| ux-design-expert | UI/UX design using Dalgo's design system (Shadcn, teal brand, Tailwind). | design-review (patterns.md for design system reference) |
| ngo-data-platform-consultant | Evaluates features as "Priya" — a non-technical NGO program manager. | None — uses its own NGO persona framework |
| Skill | What It Does |
|---|---|
| design-review | Combined UX expert + NGO user evaluation of UI components or screenshots. |
| tal-lens | Tal Raviv's technology philosophy — demystify, build first, anti-hype, clarity over cleverness. |
| documentation | Workflow + IA + style guide for Dalgo's user-facing Docusaurus docs. Triggered by prompts like "generate/update docs for X" or "write a doc page for Y". |
/product/prototype "feature idea"
# test with NGO partner...
# if validated:
/product/write-spec "feature idea"
/product/write-spec "feature idea"
/product/write-spec features/{name}
/engineering/plan-feature features/{name}/v1/spec.md
# iterate on plan...
/engineering/execute-plan features/{name}/v1/plan.md
/engineering/validate-spec
/engineering/review-pr <pr-number>
/engineering/debug-issue "error description or Sentry URL"
# implement the fix
/engineering/validate-spec
/design-review
# Generate a doc page for a feature (triggers the `documentation` skill)
"generate docs for reports"
# After a PR lands, update affected docs
"update docs for #142"
# Capture all screenshots from staging in one run
uv run python scripts/screenshot.py
# Preview the docs site locally
cd ../dalgo_docs && npm start/product/write-spec features/{name}
# creates v2/spec.md from remaining items in original spec
/engineering/plan-feature features/{name}/v2/spec.md
| Idea | Why Not |
|---|---|
/write-tests |
Test writing is part of /engineering/execute-plan. |
/deploy |
Deployment depends on CI/CD that varies per environment. |
/estimate |
Effort estimation needs team velocity context Claude can't provide. |
| Repo-level agents | Workspace-level agents read all repos via symlinks. |
| Research agent | Research is a step within /engineering/plan-feature, saved as research.md. |