From 13f5e10f6f104c8b29311eb2fa35b3d273a7751e Mon Sep 17 00:00:00 2001 From: robbond Date: Tue, 2 Jun 2026 17:07:03 +0100 Subject: [PATCH] doc: reafirmed project goals and direction --- .rdb/session-log.jsonl | 8 ++++ AGENT_HANDOFF.md | 2 +- PROJECT_STATE.md | 2 +- README.md | 43 ++++++++++++++------- RUN_LOG.md | 1 + TASKS.md | 88 +++++++++++++++++++++++++++++++++++++++++- 6 files changed, 127 insertions(+), 17 deletions(-) diff --git a/.rdb/session-log.jsonl b/.rdb/session-log.jsonl index 9c67051..91c796f 100644 --- a/.rdb/session-log.jsonl +++ b/.rdb/session-log.jsonl @@ -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": {}} diff --git a/AGENT_HANDOFF.md b/AGENT_HANDOFF.md index 174d4de..cd776a3 100644 --- a/AGENT_HANDOFF.md +++ b/AGENT_HANDOFF.md @@ -6,7 +6,7 @@ TASKS_READY ## Current Task -TASK-014 +TASK-015 ## Instructions For Agent diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md index bdb5e0f..0b9f065 100644 --- a/PROJECT_STATE.md +++ b/PROJECT_STATE.md @@ -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 diff --git a/README.md b/README.md index bf9ddba..e5c4a0e 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/RUN_LOG.md b/RUN_LOG.md index e8f7638..5232286 100644 --- a/RUN_LOG.md +++ b/RUN_LOG.md @@ -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 | diff --git a/TASKS.md b/TASKS.md index 45cc275..86beb1b 100644 --- a/TASKS.md +++ b/TASKS.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