# 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

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

## Commands

```bash
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 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.