rdb-discovery/README.md

rdb-discovery

A small CLI-first tool that helps you generate and maintain useful project context files for AI-assisted development.

Purpose

rdb-discovery exists to make it easier for humans and AI coding agents to understand:

• what is being built
• why it exists
• what questions remain open
• what task should be done next
• what stage the project is currently in

The tool creates and manages a set of markdown files — your project's source-of-truth context.

Core workflow

1. Ask discovery questions — rdb discover captures answers about the product, architecture, risks, and open questions.
2. Capture answers — Structured responses are stored in context/discovery-log.md alongside confidence scores and follow-ups.
3. Generate context files — rdb init creates standardised project files (product-brief.md, architecture.md, decisions.md, etc.).
4. Support agent implementation — rdb prompt produces ready-to-paste implementation prompts for Claude Code or Cline, and rdb start / rdb complete manage task lifecycles.

Support features (not the product)

• Telemetry records structured agent activity events in .rdb/session-log.jsonl. It enables future analysis but is not the main offering.
• Guardrails detect agent stalls, repeated reads, and inconsistent state to keep projects on track. They support the workflow but are secondary.

Install for local development

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Commands

rdb init             # Create standard project structure and context files
rdb discover         # Ask 10 core discovery questions, record answers
rdb guardrails       # Check for agent stalls and state inconsistencies
rdb prompt           # Generate implementation prompt for the next task
rdb context-status   # Report health and completeness of project context
rdb start TASK-001   # Mark a task as in progress
rdb complete TASK-001# Mark a task as done
rdb status           # Show current stage and active task
rdb next             # Print the next task to work on
rdb handoff          # Generate agent handoff notes

Bootstrap workflow

1. Run rdb init
2. Run rdb discover
3. Review rdb status and rdb next
4. Give the next prompt to Claude Code or Cline via rdb prompt
5. Commit after each completed task

Project structure

rdb init creates the following files (skips existing ones):

• context/discovery-log.md
• context/product-brief.md
• context/architecture.md
• context/decisions.md
• context/risks.md
• context/assumptions.md
• context/open-questions.md
• context/repository-context.md
• TASKS.md
• TEST_PLAN.md
• RUN_LOG.md
• PROJECT_STATE.md
• AGENT_HANDOFF.md
• .rdb/project.json

Principle

Markdown files are the source of truth. No database is required.