robbond/rdb-discovery
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: reafirmed project goals and direction

Browse Source
This commit is contained in:
robbond
2026-06-02 17:07:03 +01:00
parent 6eef97582d
commit 13f5e10f6f
6 changed files with 127 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.rdb/session-log.jsonl
+8
View File
@@ -7,3 +7,11 @@
{"timestamp": "2026-06-02T15:21:45.848114+00:00", "event_type": "command", "target": "rdb status", "details": {}}
{"timestamp": "2026-06-02T15:40:37.716111+00:00", "event_type": "command", "target": "rdb guardrails", "details": {}}
{"timestamp": "2026-06-02T15:42:28.735379+00:00", "event_type": "command", "target": "rdb status", "details": {}}
{"timestamp": "2026-06-02T15:44:50.746110+00:00", "event_type": "command", "target": "rdb status", "details": {}}
{"timestamp": "2026-06-02T15:44:50.931122+00:00", "event_type": "command", "target": "rdb next", "details": {}}
{"timestamp": "2026-06-02T15:58:40.572784+00:00", "event_type": "command", "target": "rdb status", "details": {}}
{"timestamp": "2026-06-02T15:58:44.609967+00:00", "event_type": "command", "target": "rdb next", "details": {}}
{"timestamp": "2026-06-02T15:58:49.677959+00:00", "event_type": "command", "target": "rdb prompt", "details": {}}
{"timestamp": "2026-06-02T16:01:01.182387+00:00", "event_type": "command", "target": "rdb status", "details": {}}
{"timestamp": "2026-06-02T16:05:14.118862+00:00", "event_type": "command", "target": "rdb complete", "details": {"task_id": "TASK-015"}}
{"timestamp": "2026-06-02T16:05:53.807097+00:00", "event_type": "command", "target": "rdb status", "details": {}}
AGENT_HANDOFF.md
+1 -1
View File
@@ -6,7 +6,7 @@ TASKS_READY
## Current Task
TASK-014
TASK-015
## Instructions For Agent
PROJECT_STATE.md
+1 -1
View File
@@ -4,7 +4,7 @@ Current Stage: BUILDING
Previous Stage: BOOTSTRAP_READY
Next Stage: REVIEW_READY
Current Task: TASK-014
Current Task: TASK-015
Active Branch: main
Last Updated: 2026-06-02
README.md
+30 -13
View File
@@ -1,8 +1,10 @@
# rdb-discovery
A small CLI-first tool for repeatable software project discovery and delivery.
A small CLI-first tool that helps you generate and maintain useful project context files for AI-assisted development.
It creates markdown files that help humans and AI coding agents understand:
## Purpose
rdb-discovery exists to make it easier for humans and AI coding agents to understand:
- what is being built
- why it exists
@@ -10,6 +12,20 @@ It creates markdown files that help humans and AI coding agents understand:
- 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
@@ -21,23 +37,24 @@ pip install -e '.[dev]'
## Commands
```bash
rdb init
rdb discover
rdb status
rdb next
rdb start TASK-001
rdb complete TASK-001
rdb handoff
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. Run `rdb status`
4. Run `rdb next`
5. Give the next task to Claude Code or Cline
6. Commit after each completed task
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
RUN_LOG.md
+1
View File
@@ -12,3 +12,4 @@ TASK-002 marked Done — agent prompt generation complete.
| 2026-06-02T10:02:18 | Task completed | TASK-004 | rdb ask-more implemented and tested |
| 2026-06-02T12:51:20 | Task completed | TASK-007 | enhanced prompts |
| 2026-06-02T13:45:00 | Task completed | TASK-012 | telemetry foundation — writer, JSONL storage, event reader, 12 tests passed |
| 2026-06-02T17:05:41 | Task completed | TASK-015 | updated README.md |
TASKS.md
+86 -2
View File
@@ -230,7 +230,91 @@ Acceptance Criteria:
Result:
Two new guardrail checks added:
- `check_repeated_commands_telemetry` — uses session-log.jsonl to detect repeated CLI commands (>3x)
- `check_repeated_reads_telemetry` — uses session-log.jsonl to detect repeated file reads (>3x)
Both integrate into `run_all_guardrails` alongside existing heuristic checks.
When telemetry data is absent, both return `"ok"` with an informative fallback message instead of failing.
Both integrate into `run_all_guardrails` alongside existing heuristic checks.
When telemetry data is absent, both return `"ok"` with an informative fallback message instead of failing.
## TASK-015 — Re-centre project purpose
Status: Done
Goal:
Clarify that rdb-discovery exists to help generate and maintain useful project context files for AI-assisted development.
Implementation Gap:
The project now has task, prompt, guardrail, and telemetry features, but the core product purpose needs to be made explicit again.
Acceptance Criteria:
- Update README.md with a clear project purpose
- Explain the core workflow:
- ask discovery questions
- capture answers
- generate context files
- support agent implementation
- Clarify that telemetry and guardrails support the workflow but are not the main product
- Add/update tests only if required
## TASK-016 — Define standard context file templates
Status: Todo
Goal:
Define the standard context files that rdb-discovery should help generate.
Implementation Gap:
There is not yet a clear built-in definition of the context files the tool should produce.
Acceptance Criteria:
- Define templates for:
- company-context.md
- development-context.md
- infrastructure-context.md
- agent-guidelines.md
- project-brief.md
- architecture.md
- Templates include headings and placeholder guidance
- Keep templates simple markdown
- Add/update tests
## TASK-017 — Generate context files from discovery answers
Status: Todo
Goal:
Use captured discovery answers to generate initial context files.
Implementation Gap:
Discovery questions can collect information, but the answers are not yet transformed into structured project context documents.
Acceptance Criteria:
- Add command or function to generate context files from discovery data
- Create missing context files safely
- Do not overwrite existing files without explicit behaviour
- Add/update tests
## TASK-018 — Add context completeness report
Status: Todo
Goal:
Report which expected context files exist and which sections still need information.
Implementation Gap:
There is no way to see whether a project has enough context for an AI agent to work effectively.
Acceptance Criteria:
- Add a context status/check command
- Report present context files
- Report missing context files
- Report obvious placeholder sections still needing completion
- Add/update tests