82 lines
2.8 KiB
Markdown
82 lines
2.8 KiB
Markdown
# 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 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.
|