doc: reafirmed project goals and direction
This commit is contained in:
@@ -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": {}}
|
||||
|
||||
+1
-1
@@ -6,7 +6,7 @@ TASKS_READY
|
||||
|
||||
## Current Task
|
||||
|
||||
TASK-014
|
||||
TASK-015
|
||||
|
||||
## Instructions For Agent
|
||||
|
||||
|
||||
+1
-1
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user